Add the Lite-Basic (Tier 2) sprite atlas to an EXISTING Codogotchi pet that already has a Codex `spritesheet.webp`. Produces the 9-row minimal alive/ghost sheet (revive, standby, thinking, reading, implementing, testing, errored, waiting, ghost). Row 0 is the revive fist-pump animation (renderer-selected, 5 s TTL on health gain). Idle falls through to the Codex sheet. Use when a user has a Codex pet and wants the baseline Codogotchi lite animations added.
Add the Lite-Basic (Tier 2) sprite atlas to an EXISTING Codogotchi pet that already has a Codex `spritesheet.webp`. Produces the 9-row minimal alive/ghost sheet (revive, standby, thinking, reading, implementing, testing, errored, waiting, ghost). Row 0 is the revive fist-pump animation (renderer-selected, 5 s TTL on health gain). Idle falls through to the Codex sheet. Use when a user has a Codex pet and wants the baseline Codogotchi lite animations added.
Paths in this skill — scripts/…, references/…, and README.md below are relative to this plugin's root (hatch-codogotchi/, two directories up from this file). cd to the plugin root before running the commands, or prefix each path with it.
I/O policy — scripts own all paths; the skill names none.image_gen cannot reliably store or re-find what it generates, so never tell it to save a row to a named directory and never hunt for an image-generation save folder. Pass whatever local/temp paths the caller picks into the script arguments and chain each script's output forward; the only artifact that must persist is the final magenta atlas the user keys and installs.
No model-side visual inspection. Do not use Computer Use, screenshots, or UI automation to eyeball generated output — the model cannot reliably see its own framing and it burns tokens. Frame geometry is enforced deterministically by slice_grid.py; visual review is the human's, on the script-produced contact sheet and previews.
hatch-codogotchi-lite-basic
Add the Lite-Basic sheet (Tier 2) to a pet that already has a Codex spritesheet.webp — the 9-row minimal "alive/ghost" tier every codogotchi ships.
Prerequisite: a valid Codex spritesheet.webp for the pet (the character reference is extracted from it).
Execution model (slot-first): Codex uses its built-in image_gen tool to generate one full Lite-Basic row per call as 8 invisible equal-size slots, 4 across and 2 down (read left-to-right, top row then bottom), all 8 filled, on the single flat chroma key chosen for this pet (see below). The slots are an invisible placement grid — the prompt says "slots," never "grid/cells," so the model paints one continuous flat field, not 8 separate cards. prepare_pet_run.py also emits a layout-guide.png (4×2 placeholder with slot boundaries, blue safe-margins, centering crosshairs); attach it (and the seed) to every image_gen call as reference-only — it keeps frames from clipping. image_gen need not hit an exact canvas size. Then run slice_grid.py (dimension-tolerant): it slices by fraction, shares one scale across all 8 frames, and emits the exact canonical 1536×208 row strip. Generate one row at a time; never ask for the whole atlas in a single image.
Non-negotiable row gate: finish one row completely (generate grid → slice_grid.py) before generating the next. If a grid comes back clipped, cramped, or off-model, regenerate the whole grid instead of patching forward. Do not compose until every row strip exists. The model does not screenshot or eyeball its own output — slice_grid.py enforces geometry, and prop clarity / face / scale / motion are reviewed by the human on the script-produced contact sheet after composing.
Chroma key — one auto-selected key for the whole pet, keyed by the user later. The chroma is fixed for the pet by prepare_pet_run.py (auto-selected from the seed — magenta #FF00FF, blue #0047BB, or green #00B140 — magenta fallback) and must match the pet's existing sheets; pass --chroma to match if needed. The ghost recolors automatically to avoid the key (default ethereal blue; flips to warm rose under a blue key) so it is never keyed out. This plugin does not key the sheet. After QA, hand the flat-key atlas to the user to key in Codogotchi Studio (https://codogotchi.app/studio).
Recommended production pattern: generate the minimum number of distinct keyframes needed for a readable, non-static row, then reuse or mirror earlier stable frames to close the loop when that produces a clean result. Many rows can be completed faster with ~4 strong keyframes plus a mirrored/reused closure instead of 8 fully independent generations. This is a recommended speedup, not a hard requirement.
Which skill?
No Codex sheet yet → SKILL-codex-and-lite-basic.md (generates both).
Want Basic and Enhanced added to an existing pet → run this, then SKILL-lite-enhanced.md.
Add only the SoA gate sheet → SKILL-soa.md (needs only the Codex sheet).
Read first — the doctrines (full text in README.md + references/animation-rows-lite.md)
0. Motion restraint — stability over expressiveness (paramount). A calm pet with small, smooth motion always beats an expressive one that jitters; when they conflict, choose stability. Big or whole-body described motion comes back incoherent across the row — legs swing, props teleport, the pet hops. Anchor the torso, head, hips, and both feet in nearly the same place across all 8 frames (legs don't walk or swing in standing rows); confine motion to one element — the named prop, one arm, or the expression — at low amplitude with short, smooth arcs. "No static rows" is a floor (subtle smooth life so frames differ), not a push toward big motion: a barely-moving stable row passes; a busy jittery row is a reject.
Prop doctrine — NOT charades. Emotion-mappable states (revive, errored→sad) lead with expression; every other state is carried by one clearly-visible prop — never subtle hand gestures, never a mimed/"invisible" prop ("invisible keyboard", "unseen screen"), never an A/B choice (the old reading "page/tablet" drew both). Same prop, all 8 frames. Per-row props are in references/animation-rows-lite.md.
Scale consistency. Same character size across all 8 cells of a row. Ask image_gen for a shared head height / body scale across the grid; slice_grid.py shares one scale across the row, and any residual drift is caught by the human on the contact sheet. If one cell is off, regenerate the whole grid.
Visual identity checklist. Every frame must preserve the same age/proportions, hair silhouette, dress/outfit, sandals/accessories, palette, and linework as the seed artifact. This is an eyeball pass on the contact sheet — there is no automated identity gate.
Alignment stability. Keep the character on a stable horizontal axis in every 192×208 frame; the pet must not hop left/right. Vertically align ordinary standing rows to a shared bottom baseline near cell_h - 8, not the vertical center. Confirm on the contact sheet / previews.
Plus the standing failure modes: don't fake frames by transforming the seed; grid-first, one row at a time; never whole-atlas generation; keep the magenta background flat; don't drift from the Codex sheet's style.
Quality caveats for the recommended pattern:
Some rows need more unique motion than others; generate extra distinct frames whenever the action or emotion reads weakly.
Reused/mirrored closures are acceptable only if the prop stays obvious, the row does not feel static, and the loop does not visibly pop.
Script validation is necessary but not sufficient; human visual review can still reject a row that passes mechanically if the motion looks cheap.
Workflow
# 1. Extract the character reference from the existing Codex sheet (idle row, frame 1)
python scripts/extract_seed_from_codex.py \
--spritesheet "${CODOGOTCHI_HOME:-$HOME/.codogotchi}/pets/<pet-id>/spritesheet.webp" \
--out <seed>
# (confirm the seed artifact is a clean neutral pose; --print-cell-size if cell ≠ 192×208)# 2. Prepare the Lite-Basic run (each strip prompt embeds the prop doctrine, scale rule, flat #FF00FF bg)
python scripts/prepare_pet_run.py --seed <seed> \
--pet-name "<display name>" --pet-id "<pet-id>" --tier lite-basic --style auto
# 3. For each of the 9 rows, in order, use built-in image_gen grid-first:# generate ONE 4x2 grid (4 cols x 2 rows of 192x208 cells, 8 populated, no empty# cell) on flat #FF00FF. image_gen need not hit an exact size. Prop must stay clearly# drawn + identical across all 8 cells; seed artifact attached. Then slice the grid# into the canonical 1536x208 row strip (paths are caller-chosen/ephemeral):
python scripts/slice_grid.py --input <grid> --out <row-strip>
# slice_grid.py enforces geometry; if the grid is clipped/off-model, regenerate it.# 4. Compose + encode (after all 9 rows) → magenta-background atlas
python scripts/compose_atlas.py --rows-dir <row-strips-dir> --tier lite-basic --out <atlas-png>
cwebp -lossless -exact <atlas-png> -o <atlas-webp>
# 5. Slim QA gate
python scripts/validate_atlas.py --atlas <atlas-webp> --tier lite-basic --out-json <validation-json>
python scripts/make_contact_sheet.py --atlas <atlas-webp> --tier lite-basic
python scripts/render_animation_previews.py --atlas <atlas-webp> --tier lite-basic
python scripts/pre_install_qa_gate.py --atlas <atlas-webp> --tier lite-basic
Final step — keying is the user's. The composed *.webp still has its flat magenta background. Do not install it. Direct the user to https://codogotchi.app/studio to key it (load → tune knobs → export transparent sheet), then install the keyed codogotchi-lite-basic-spritesheet.webp (do NOT overwrite spritesheet.webp or pet.json) and quit-reopen Codogotchi.
Row order (see references/animation-rows-lite.md):
revive, standby, thinking, reading, implementing, testing, errored, waiting-for-input, ghost
Fix a bad frame
If any frame in a grid is wrong, regenerate the whole grid for that row, re-run slice_grid.py, and re-run the QA scripts. Fix by regenerating the grid, never by editing individual frames.
Flat #FF00FF background, perfectly uniform across the atlas (no falloff/shadow/texture)
Character/content horizontal center is stable across the row; ordinary standing rows share a bottom foot baseline near cell_h - 8 (eyeballed)
Stable motion (paramount): body/feet anchored, one element moves at low amplitude, no jitter/hopping/limb-swing
No static rows (gated by validate_atlas.py); each row has subtle distinct motion; loop closes
Each prop-led row shows its single named prop clearly in all 8 frames
Character size consistent across all 8 frames of every row (eyeballed)
Per-frame visual QA passed: same age/proportions, hair silhouette, dress/outfit, sandals/accessories, palette, and linework as the seed artifact
Style/palette/proportions match the existing spritesheet.webp
validate-lite-basic.json, contact-lite-basic.png, and previews-lite-basic/ exist and are newer than the final atlas
pre_install_qa_gate.py passed; user directed to https://codogotchi.app/studio to key the magenta atlas before install
spritesheet.webp and pet.json unchanged
Final response checklist
Before saying done, report: rows generated or regenerated; validation command/result; contact sheet and preview directory paths; known compromises. State clearly that the delivered atlas is magenta-background (pre-key) and the user must key it at https://codogotchi.app/studio before installing. If the tier was completed unusually quickly, state what was compressed, reused, or skipped. Validation alone is not QA.
