宠物 / 使用指南

一张精灵图，
九种状态，零配置。

每只宠物都只附一张精灵图：直接装进 Codex 桌面端，也能在任何引擎里干净地切分——每个动画状态占一行，每行 8 格。

安装到 Codex

Codex（OpenAI 的编程智能体应用）会用一个宠物悬浮窗反映智能体的工作状态。这些宠物无需任何额外配置即可接入：

1.在任意宠物页下载 “安装到 Codex” 压缩包并解压。
2.把 pet.json 与 spritesheet.webp 拷进 ~/.codex/pets/<名字>/（文件夹不存在就先建）。
3.重启 Codex，在设置 → 外观 → 宠物里选中它。
4.在任意会话里运行 /pet 唤醒它——切到别的应用时，它也会以悬浮窗继续陪伴。

~/.codex/pets/shibe/
├── pet.json            { id, displayName, description,
│                         spritesheetPath: "spritesheet.webp" }
└── spritesheet.webp    1536 × 1872 · 8 × 9 · 192 × 208 per cell

九种状态与 Codex 应用契约一一对应（idle、running、running-left、running-right、jumping、waving、failed、waiting、review），表现与内置宠物完全一致。

精灵图结构

每张精灵图为 1536×1872 px：8 列 × 9 行，每格是一帧 192×208 px 的透明背景动画。第 0 行永远对应宠物页状态列表里的第一个状态；帧从左到右读取。如果某状态不足 8 帧，该行多余的格子是空的——只循环宠物页上标注的帧数即可。

sheet.webp  1536 × 1872
┌──────── 8 columns ────────┐
│ f0  f1  f2  f3  f4  …  f7 │ ← row 0 · idle
│ f0  f1  f2  f3  ·   ·   · │ ← row 1 · next state
│ …                         │
└──────── 9 rows ───────────┘  192 × 208 per cell

打包文件里还附带 README.txt，列出每个状态的确切行号与帧数——不用猜。

动画状态

全部 433 只宠物共享同样的九种状态，换宠物也不用改状态机。

idle

默认待机循环。宠物站在玩家身旁不动时使用。

running

向前移动。侧面奔跑循环，用于跟随玩家。

running-left

明确的向左奔跑，适合不做帧镜像的引擎。

running-right

明确的向右奔跑，适合不做帧镜像的引擎。

jumping

空中姿态循环。宠物跳跃或下落时播放。

waving

打招呼表情。可在出现、升级或交互时触发。

failed

负面反应——落空、碰撞或动作失败。

waiting

长待机变体。一段时间无输入后切换到此状态。

review

QA 审核用的展示循环，也可当备用待机使用。

引擎接入

Godot 4

导入精灵图，用区域 (col×192, row×208, 192, 208) 构建 AtlasTexture 帧，再按状态分别推入 AnimatedSprite2D。

var frames := SpriteFrames.new()
for col in range(FRAME_COUNT[idle]):
    var tex := AtlasTexture.new()
    tex.atlas = sheet
    tex.region = Rect2(col * 192, ROW[idle] * 208, 192, 208)
    frames.add_frame("idle", tex)

Unity

在 Project 窗口选中贴图，把 Sprite Mode 设为 Multiple，打开 Sprite Editor 选择 Grid By Cell Size，填 192 × 208。每一行就是一个动画片段。

Phaser 3

// rows differ per state — see the pet page for row indices
this.anims.create({
  key: "idle",
  frames: this.anims.generateFrameNumbers("pet-sheet", {
    start: ROW.idle * 8, end: ROW.idle * 8 + FRAMES.idle - 1,
  }),
  frameRate: 10, repeat: -1,
});

纯 CSS

只需要循环预览时，每个状态用一张 GIF：

<img src="https://r2.favori.dev/codexpet/pets/black-kitty/gif/idle.gif"
     alt="Black Kitty idling" width="192" height="208" />

小贴士

帧尺寸为 192×208——按整数倍缩小（96×104、48×52）并使用最近邻过滤，像素边缘才清晰。
running-left / running-right 是真实循环，不是镜像——选与移动方向匹配的那个，或者翻转其中一个以省内存。
网页项目优先用 WEBP 精灵图（体积更小）；流水线解不了 WEBP 就用 PNG。
每个打包里的 README.txt 都列出各状态的行号与帧数——和宠物页上显示的数字一致。

浏览宠物阅读授权

一张精灵图，九种状态，零配置。

安装到 Codex

精灵图结构

动画状态

引擎接入

小贴士

一张精灵图，
九种状态，零配置。