What Is a Pet Spritesheet and pet.json?

Spritesheet basics

A spritesheet is a single image containing every frame of animation in a grid. Instead of loading 72 separate files, Codex opens one image and reads rectangular slices out of it in order. That is why a pet package is only two files: the sheet itself and a small JSON file describing it.

PetGen outputs a 1536x1872 transparent spritesheet with the exact grid Codex expects, and a pet.json that names the pet and points at the sheet. Put both in one folder, drop that folder into ~/.codex/pets (or %USERPROFILE%\.codex\pets on Windows), restart Codex, and the pet appears.

The exact grid: 1536x1872

The numbers are not arbitrary. The sheet is 1536 pixels wide and 1872 pixels tall, divided into 9 rows of 8 columns. That gives 72 frames total, and each individual frame works out to 192x208 pixels.

You can verify the arithmetic: 8 columns x 192px = 1536px wide, and 9 rows x 208px = 1872px tall. If a generator hands you a sheet with different dimensions, Codex will either crop it, stretch it, or skip the pet entirely — there is no auto-scaling fallback.

The nine animation states

Each of the 9 rows is one animation state, and each row holds 8 frames that play as a loop. The standard set covers idle, walk, run, sit, sleep, eat, play, happy, and a special or reaction state.

The idle row matters most in practice — it is what your pet does for the overwhelming majority of the time it is on screen. A pet with a charming idle animation and mediocre everything else still feels alive; the reverse feels broken.

How Codex maps frames to motion

Codex treats the row index as the state and the column index as the frame number within that state. To play the walk cycle it reads row 1, then walks columns 0 through 7, loops back to 0, and keeps going until the state changes.

This is why frame ordering is strict. Shuffling frames within a row produces a pet that twitches instead of moving, and no error is reported — the loader has no way to know the frames are out of order. If your pet looks like it is vibrating, suspect frame order first.

pet.json, field by field

pet.json is deliberately small. The fields that matter are name (the identifier Codex uses and the value that must match the folder name), description (free text, shown in some UI surfaces), and the spritesheet reference (usually just the filename spritesheet.webp, resolved relative to the folder).

The name field causes more failures than every other field combined. If the folder is my-cat-v2 but pet.json still declares name: "my-cat", the loader can refuse to mount the pet and will not tell you why. Copy the name value out of the JSON, rename the folder to match it exactly, and restart.

Why WebP rather than PNG

The sheet is WebP because it supports a full alpha channel at a fraction of the file size of an equivalent PNG. A 1536x1872 sheet with transparency is large enough that the format choice is noticeable: WebP versions typically land in the tens of kilobytes where PNG would run several times larger.

Smaller files load faster and redraw more cheaply, which matters for something sitting on your desktop all day. Codex supports WebP with alpha natively, so there is no compatibility tradeoff in using it.

Four format mistakes that break a pet silently

These four account for most "the pet installed but nothing happened" reports. None of them produces an error message, which is what makes them hard to diagnose.

• Wrong dimensions — the sheet is not exactly 1536x1872, so the 9x8 grid does not divide cleanly and frames land on the wrong boundaries.
• Missing or renamed file — the loader looks for spritesheet.webp by that exact name. A file called spritesheet (1).webp, or one still nested in a subfolder after unzipping, is invisible to it.
• Name mismatch — the folder name under ~/.codex/pets does not match the name field inside pet.json.
• No restart — Codex reads the pets directory at startup. Closing the window is not quitting on macOS, and on Windows the app keeps running in the tray.

How to verify a package before installing

Two checks take under a minute and catch nearly everything. Run them before you go looking for more exotic causes.

• Validate the JSON: node -e "JSON.parse(require('fs').readFileSync('pet.json','utf8'))" — if it throws, the file is malformed.
• Confirm the sheet dimensions are 1536x1872 and that spritesheet.webp sits directly beside pet.json, with no nested folder from the ZIP extraction.
• Check that the folder name and the name field inside pet.json are byte-identical, including hyphens and capitalisation.
• Fully quit Codex (Cmd+Q on macOS, exit from the tray icon on Windows), relaunch, and wait a few seconds before concluding it failed.

Building one by hand

It is possible to assemble a package manually, and doing it once is the fastest way to understand the format. Draw or export 72 frames at 192x208 each, compose them into a 9-row by 8-column grid with a transparent background, export as WebP with alpha, then write a pet.json whose name matches the folder you are about to create.

The honest caveat is that hand-pixeling 72 coherent frames takes hours, and matching the palette and silhouette across all nine states is harder than any single frame suggests. A generator collapses that into about a minute, which is the entire reason these tools exist — but knowing what the output should look like makes you much better at spotting when something went wrong.