All platforms · 8 min · Upstream checked July 17, 2026

Codex pet spritesheet and pet.json format

Reference the legacy 8×9 and current 8×11 Codex pet atlas contracts, cell dimensions, row order, look directions, and manifest fields.

Platform behavior can change. Compare this guide with the original repository at commit a1c48b3a84cc.
01Choose the correct atlas version
02Verify exact dimensions and transparency
03Check row order and direction semantics
04Validate pet.json paths and version

Two formats exist

Legacy v1 uses a 1536×1872 8×9 atlas for nine standard actions. Current v2 extends the same 192×208 cell grid to 1536×2288 and adds two rows containing sixteen look directions. New pets should target v2; legacy support should remain clearly labeled rather than described as equivalent.

The standard row order is fixed

Rows 0–8 are idle, run-right, run-left, wave, jump, failed, waiting, working, and review. Each row has eight frame cells. A creator can hold repeated poses when an animation uses fewer unique drawings, but cell position and row meaning still stay fixed.

v2 look direction order is semantic

Rows 9–10 rotate clockwise from 000 up through 337.5 up-left in 22.5-degree steps. Test the cardinal anchors—up, right, down, left—at normal size, then check continuity across every adjacent pair, including the wrap from 337.5 back to 000.

pet.json stays small and explicit

The manifest names the pet and points to spritesheet.webp or spritesheet.png. A v2 package must include spriteVersionNumber 2; without it the app interprets the asset under the legacy contract. Keep the manifest and referenced file at the package root and use a simple lowercase folder id.

A correctly sized atlas can still be visually invalid. Dimensions do not prove clean transparency, complete motion, consistent scale, or correct look direction meaning.

Completion checklist

Related guides