完整使用手册
Studio 和桌宠的职责
PetPack Studio 是导入、校验、预览和发布工具；生成的桌宠是独立运行时。桌宠只读取相邻的 petpack.bundle，不要求 Codex 正在运行，也不读取 Codex 的宠物目录。
导入来源
本地文件夹
选择宠物根目录，或选择只包含一个宠物子目录的父目录。Studio 会查找 pet.json，再读取清单引用的 PNG/WebP 图集。
ZIP 或单个文件
ZIP 可以把宠物文件放在根目录或一个顶层文件夹内。ZIP 中存在多个宠物、路径穿越或绝对路径时会被拒绝。
选择 pet.json 或 spritesheet 文件时，Studio 使用它所在的目录作为宠物根目录。
Petdex
输入 Petdex slug 或 petdex.dev/pets/<slug> 页面地址。Studio 只从 Petdex 官方资产域读取清单和图集，不执行页面脚本。
校验结果
校验区域分为三类信息：
| 项目 | 作用 |
|---|---|
| 图集尺寸 | 判断 Codex v2、Codex/Petdex v1 或兼容 9 行格式。 |
| 帧占用 | 确认要求使用的单元格有可见像素，保留单元格完全透明。 |
| 清单文件 | 检查 ID、显示名称、版本声明和图集路径。 |
错误会阻断发布；警告表示格式可以运行，但可能不是标准尺寸或缺少建议字段。
动画预览
状态按钮对应 9 个标准动作：
- 待机；
- 向右移动；
- 向左移动；
- 挥手；
- 跳跃；
- 失落；
- 等待；
- 工作；
- 检查。
Codex v2 还包含 16 个顺时针注视方向。独立桌宠会根据指针相对位置选择注视帧，指针离开或进入中心死区后恢复待机。
桌面试玩
“桌面试玩”使用当前导入包创建临时透明窗口，适合发布前确认：
- 角色没有裁切；
- 缩放后仍完整可见；
- 底部把手能够拖动；
- 工具栏仅在光标进入宠物时出现；
- 动画帧没有跳动、方向反转或背景残留。
试玩窗口关闭后不会生成发布文件。
应用信息
发布前可以修改：
- 应用 ID：用于输出文件夹、程序名和包标识；建议使用小写字母、数字和连字符。
- 显示名称：显示在桌宠窗口、托盘和说明文件中。
- 描述：写入导出清单，便于记录角色来源和用途。
修改这些字段不会覆盖原始宠物目录。
当前平台成品
当前平台成品包含本机原生运行时。Windows 生成 EXE，macOS 生成 App，Linux 生成可执行文件。Studio 同时输出便携目录和 ZIP。
适用场景：
- 自己在当前设备使用；
- 分发给相同操作系统和 CPU 架构的用户；
- 发布前快速验证最终运行时。
跨平台构建包
跨平台构建包用于在目标设备生成原生运行时。它不包含完整 Studio 界面，只包含：
petpack-cross-platform/
├── petpack.bundle/
├── build-request.json
├── builders/
├── START-HERE.html
├── BUILD-WINDOWS.cmd
├── BUILD-MAC.command
├── BUILD-LINUX.sh
├── build-here.ps1
├── build-here.sh
└── README.md目标设备先打开 START-HERE.html，再双击对应系统的一键入口；成功后会自动打开 output/，其中包含原生桌宠目录和 ZIP。构建器缺失时会在首次运行自动下载；失败时指引页会提供手动下载入口。详见跨平台构建与分发。
独立桌宠交互
拖动
按住宠物底部三点把手移动。多显示器和高 DPI 环境使用逻辑坐标定位，调整大小后会把窗口限制在当前显示器可见范围内。
缩放
悬停工具栏的 − 和 ＋ 以 15% 为步长缩放，范围为 70%–140%。托盘菜单提供小、标准和大三档。缩放值保存在当前桌宠的本地 WebView 存储中。
动作
工具栏提供挥手和跳跃；托盘菜单还可以切换待机、工作等状态。动作完成后会返回正常循环。
置顶
桌宠默认置顶。点击圆点按钮或使用托盘菜单切换置顶状态。
退出
点击悬停工具栏的关闭按钮或托盘“退出”。任务栏中没有桌宠按钮是正常行为。
Studio 窗口行为
Studio 是普通桌面程序：
- 最小化后保留在任务栏；
- 点击任务栏图标恢复；
- 点击关闭按钮直接结束 Studio 进程；
- Studio 本身不常驻托盘。
输出目录说明
不要只发送桌宠可执行文件。运行程序必须和 petpack.bundle 保持相对位置。推荐始终发送 Studio 生成的完整 ZIP。
重新打包同一个宠物时，选择空输出目录或先移走旧产物，避免接收者混用不同版本的运行时和资源。