寵物 / 使用指南

一張精靈圖，
九種狀態，零設定。

每隻寵物都只附一張精靈圖：直接裝進 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

精靈圖結構

動畫狀態

引擎串接

小提醒

一張精靈圖，
九種狀態，零設定。