local_florist

Spritesheet Reference

A Codogotchi pet is a folder consumed directly by the macOS app. This is the exact spec for the four-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, displayName)
├── spritesheet.webp                           # Tier 1 — Codex         (required)
├── codogotchi-lite-basic-spritesheet.webp     # Tier 2 — Lite-Basic    (optional)
├── codogotchi-lite-enhanced-spritesheet.webp  # Tier 3 — Lite-Enhanced (optional, requires Basic)
└── codogotchi-soa-spritesheet.webp            # Tier 4 — SoA           (optional)

The old codogotchi-lite-spritesheet.webp (single 8×11 sheet) is deprecated — the app still loads it during a migration window but new pets should target the two split files above.

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 universal fallback. This is the upstream Codex pet format — a Codogotchi pet's Tier 1 sheet is a standard Codex sheet, so any Codex-compatible pet works as a base. It carries idle, mouse interactions, errored, waiting, and the fallback poses used when no Lite sheet is present. If Lite and SoA are absent, the whole pet renders from here.

open_in_new

Tier 1 follows the canonical Codex pet spec at codexpet.xyz/spec. Frame counts are recommendations — a row may animate fewer than 8 of the 8 columns.

Row State (Codex) Rec. frames Drives in Codogotchi
0 idle 6 idle
1 running-right 8 Drag-right (floating pet)
2 running-left 8 Drag-left (floating pet)
3 waving 4 standby
4 jumping 5 Click-hold (floating pet)
5 failed 8 errored
6 waiting 6 waiting_for_input
7 running 6 implementing / testing (fallback)
8 review 6 thinking / reading (fallback)
Tier 2 · optional

Lite-Basic — codogotchi-lite-basic-spritesheet.webp

Grid: 8 × 9
1536 × 1872 px

The minimal "alive/ghost" tier — every published pet ships this. Replaces Codex's generic fallback rows with per-activity art for the core agent hook states, plus a ghost pose at 0 HP and a revive celebration at row 0 (5 s TTL, renderer-selected on any health gain). The resting idle state falls through to the Codex sheet. States not listed here fall back to Codex.

Row Animation ActivityState Notes
0 revive (renderer — revive_until > now) Health gained — fist-pump celebration, 5 s TTL
1 standby standby Done, handing control back — rings a handbell
2 thinking thinking Pondering — thought-bubble + lightbulb
3 reading reading Light reading — one open book
4 implementing implementing Active coding — laptop
5 testing testing Lab-experiment — flask + test tube
6 errored errored Distressed — red ✗ badge
7 waiting-for-input waiting_for_input Blocked, awaiting your input — "?" sign
8 ghost (renderer — 0 HP) 0 HP ghost form — spectral idle silhouette
Tier 3 · optional

Lite-Enhanced — codogotchi-lite-enhanced-spritesheet.webp

Grid: 8 × 8
1536 × 1664 px

Polish extension adding heuristic-state art and idle mood escalation. Requires Lite-Basic — cannot be installed without it. The app looks here first; misses fall through to Basic, then Codex. States not listed here are covered by Basic or Codex.

Row Animation ActivityState / trigger Notes
0 idle-impatient (renderer — ~5 min idle) Restless — taps wristwatch
1 idle-frustrated (renderer — ~10 min idle) Agitated — steam puffs
2 cramming cramming Heavy study — tall stack of books
3 editing editing Targeted edit — pencil + paper
4 git-ops git_ops Shipping — Octocat icon launched
5 verifying verifying Post-change check — clipboard + green stamp
6 searching searching Local grep/find — magnifier + file folder
7 web-search web_search Web query — deerstalker hat + globe
Tier 4 · optional

SoA — codogotchi-soa-spritesheet.webp

Grid: 8 × 10
1536 × 2080 px

Delivery-gate moments from Son-of-Anton (SoA), a structured delivery orchestrator — 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; Enhanced falls through to Basic on a miss; Codex is the universal fallback.

SoA (gate.json) arrow_forward Lite-Enhanced arrow_forward Lite-Basic arrow_forward Codex arrow_forward Codex idle

Compliance checklist

  • check_circle pet.json has at minimum an id (lowercase slug) and displayName.
  • check_circle spritesheet.webp present, 8 × 9 (Codex); cell aspect matches all tiers.
  • check_circle imageWidth % 8 == 0 and imageHeight % rowCount == 0 for every sheet.
  • check_circle Lite-Basic (if present): 8 × 9. Lite-Enhanced (if present): 8 × 8 and requires Basic. SoA (if present): 8 × 10.
  • check_circle WebP lossless recommended (PNG also accepted); 8 frames per row; all cells RGBA.
  • check_circle Folder installed at ~/.codogotchi/pets/<pet_id>/, then quit and reopen the app.