local_florist

Spritesheet Reference

A Codogotchi pet is a folder consumed directly by the macOS app. This is the exact spec for the three-tier spritesheet system — file names, grid, timing, and the animation rows each tier carries.

auto_awesome

Don't want to draw all this? Let AI hatch it for you → /hatch

File Layout

${CODOGOTCHI_HOME:-~/.codogotchi}/pets/<pet_id>/
├── pet.json                          # manifest (id, display_name)
├── spritesheet.webp                  # Tier 1 — Codex  (required)
├── codogotchi-lite-spritesheet.webp  # Tier 2 — Lite   (optional)
└── codogotchi-soa-spritesheet.webp   # Tier 3 — SoA    (optional)

Grid & Timing

Columns
8 frames
Cell size
192 × 208 px
Frame timing
187.5 ms
Loop
continuous

Every tier uses an 8-column grid with a 192×208 cell. Other cell sizes are allowed if width % 8 == 0 and height % rowCount == 0, keeping the same aspect ratio across tiers.

Tier 1 · required

Codex — spritesheet.webp

Grid: 8 × 9
1536 × 1872 px

The required base sheet and fallback for every state. Carries idle, mouse interactions, errored, waiting, and fallback poses. If Lite and SoA are absent, the whole pet renders from here.

Tier 2 · optional

Lite — codogotchi-lite-spritesheet.webp

Grid: 8 × 11
1536 × 2288 px

Replaces Codex's generic "running" with per-activity art — all agent hook states plus idle mood escalation. When present, it wins over Codex for those rows.

Row Animation ActivityState Notes
0 idle idle No active session / quiet default
1 idle-impatient idle (escalated) No activity for a while
2 idle-frustrated idle (escalated) Idle even longer
3 standby standby Waiting for the developer
4 thinking thinking Exploring / searching the codebase
5 reading reading Reading source (light streak)
6 cramming cramming Deep-reading (3+ reads in a row)
7 implementing implementing Writing code
8 testing testing Running tests / verify / lint / build
9 errored errored Agent failed — distressed
10 waiting_for_input waiting_for_input Awaiting a permission prompt
Tier 3 · optional

SoA — codogotchi-soa-spritesheet.webp

Grid: 8 × 10
1536 × 2080 px

Son-of-Anton delivery-gate moments, shown only when ~/.codogotchi/gate.json is active and unexpired. Gate art takes precedence over the hook state for the duration of the gate.

Row Animation gate.json value Notes
0 ticket_started ticket_started Delivery ticket just started
1 green_tdd green_tdd Tests passing
2 red_tdd red_tdd Failing test committed
3 open_pr open_pr PR opened for review
4 adversarial_review adversarial_review Subagent review in progress
5 poll_review poll_review AI review window open
6 record_review record_review Review outcome recorded
7 advance advance Phase / ticket advanced
8 ticket_completed ticket_completed Ticket marked done
9 review_clean review_clean Review recorded as clean

Resolution order

The renderer resolves which row to animate using this priority — first match wins. Gate art shows only while active; otherwise the hook state shows through; Codex is the universal fallback.

SoA (gate.json) arrow_forward Lite arrow_forward Codex arrow_forward Codex idle

Compliance checklist

  • check_circle pet.json has at minimum an id (lowercase slug) and display_name.
  • check_circle spritesheet.webp present, 8 columns × 9 rows, cell aspect matches all tiers.
  • check_circle imageWidth % 8 == 0 and imageHeight % rowCount == 0 for every sheet.
  • check_circle Lite sheet (if present) is 8 × 11; SoA sheet (if present) is 8 × 10.
  • check_circle WebP lossless recommended (PNG also accepted); 8 frames per row.
  • check_circle Folder installed at ~/.codogotchi/pets/<pet_id>/, then restart the app.