Troubleshooting guide
Codex Pet Troubleshooting
Most pet failures come from an incorrect install path, a manifest mismatch, wrong atlas dimensions, opaque backgrounds, or frames in the wrong row.
Pet does not appear
- Confirm the directory is inside $HOME/.codex/pets or CODEX_HOME/pets
- Confirm pet.json and spritesheet.webp are at the directory root
- Confirm the directory and manifest id match
- Restart or refresh Codex after installation
Spritesheet rejected
- V1 must be 1536×1872
- V2 must be 1536×2288
- spriteVersionNumber must match the atlas
- spritesheetPath must be spritesheet.webp
Animation is wrong
- Check row order
- Keep unused cells transparent
- Preserve frame order when mirroring running-left
- Inspect contact sheets and GIF previews for size or baseline popping
Look directions are wrong
- 000 is up, not neutral
- 090 is screen-right
- 180 is down
- 270 is screen-left
- The full sequence must advance clockwise without reversals
Run structural validation
npx codexpetlab validate ./my-pet.codex-pet.zip