Codex pet spritesheet format: v1, v2 and animation rows

Choose v1 or v2 before assembling the image

Existing v1 packages use eight columns and nine rows. V2 keeps the first nine rows and adds two rows of look-direction poses. Both use 192 × 208 pixel cells.

The desktop-bundled hatch-pet contract inspected on November 5 requires v2 for newly hatched pets; its 8 × 9 image is an intermediate assembly, not the final new package. The public OpenAI skills repository still describes the older v1 format. Follow the contract shipped with your installed workflow and preserve an existing package’s original version.

This website can inspect both formats. That does not prove your running app loads v2 or activates its look directions. Verify the package in the client you actually use before calling it installed.

Reference: OpenAI: public Hatch Pet v1 contract · Codex Pets: versioned format verification · Codex Pets: manifest contract

The first nine rows: state, frames and timing

Rows and columns are zero-based. Place each active frame from left to right. Running-right and running-left are locomotion; the separate running row means active task work. Waiting, failed and review should have distinguishable poses.

Eight columns describe the canvas width, not eight active frames in every state. Keep unused cells fully transparent. Hold the character’s scale and anchor steady so changing states does not make it jump around.

Reference: OpenAI: public Hatch Pet v1 contract · Codex Pets: versioned format verification · codex-pets-react: atlas implementation

V2 rows 9–10: one clockwise look sequence

Each look cell is a pose. Row 9 contains 0°, 22.5°, 45°, 67.5°, 90°, 112.5°, 135° and 157.5°. Row 10 continues with 180°, 202.5°, 225°, 247.5°, 270°, 292.5°, 315° and 337.5°. All sixteen cells are used.

0° means looking up, at twelve o’clock, not neutral/front. The bundled contract uses idle for the pointer deadzone. Do not obtain v2 by stretching a v1 image or changing only the JSON field: author the extra poses and check their continuity.

The current Sprite Preview plays the nine standard states. It does not demonstrate the pointer-driven look sequence; inspect those cells separately and verify the behavior in your client.

Reference: Codex Pets: versioned format verification · Codex Pets: manifest contract

Export exact cells without gutters or labels

Export PNG or WebP with a transparent background. Keep grid lines, labels, borders and contact-sheet gutters out of the image. Fit every pose, prop and shadow inside its cell so it is not cropped.

For zero-based column c and row r, the source rectangle begins at x = c × 192, y = r × 208, with width 192 and height 208. The first waiting frame begins at (0, 1248); the first v2 look pose begins at (0, 1872).

Check the actual exported pixel dimensions. Resizing the entire image cannot repair the wrong row count. Re-export the correct grid, then inspect the character at its intended display size on light and dark backgrounds.

Reference: OpenAI: public Hatch Pet v1 contract · Codex Pets: versioned format verification · codex-pets-react: atlas implementation

Keep pet.json beside the matching image

This is a v2 example. Replace the identity and description with your own. The manifest and image belong at the package root; avoid an extra enclosing folder inside a ZIP. Match spritesheetPath to the real filename.

For an existing v1 package, preserve its 1536 × 1872 image and v1 or omitted version. Renaming an extension does not convert an image. Valid JSON alone cannot prove the image exists or contains the right frames.

{
  "id": "sample-pet",
  "displayName": "Sample Pet",
  "description": "A small companion with distinct working and waiting poses.",
  "spriteVersionNumber": 2,
  "spritesheetPath": "spritesheet.webp"
}

Reference: OpenAI: public Hatch Pet v1 contract · Codex Pets: versioned format verification · Codex Pets: manifest contract

Check the files, then inspect the motion

Open Sprite Preview and select the local ZIP checker for a package you hold. Check its reported version, dimensions and required files. Repair a mismatch in the source package before installing.

Compare the existing v1 Boxcat and v2 Beanie packages below. Switch through the nine standard states, especially left versus right movement and waiting versus working. These are reference examples, not permission to reuse their artwork.

Boxcat is a legacy geometry example: its package structure passes this site’s checks, but the newer bundled authoring validator flags invisible RGB residue in transparent pixels. Do not treat it as a clean new-artwork template. Beanie’s v2 atlas passed that stricter validator in this check.

File validation, animation readability, artwork permission and installation are separate checks. When the package is ready, follow the installation steps and confirm it in your running app.

• Open Sprite & Package Preview
• Compare the existing v1 Boxcat package
• Compare the existing v2 Beanie package
• Install and verify your pet package

Try it in Codex

Review an atlas against its declared contract

Review only the pet package I explicitly select. Identify the image dimensions, manifest version and intended client/workflow. Do not change files or install anything. Map the grid, active frame counts and state rows, check transparency and report mismatches between pet.json and the real image. For v2, inspect all sixteen look poses separately from the nine standard states. Distinguish file validation, visual quality, artwork permission and actual client installation. Propose the smallest correction and its verification. Do not resize, overwrite or convert the package without my approval.

Check your result

• The image dimensions, grid and manifest version agree.
• Each state uses its declared row and frame count; unused cells are transparent.
• V2 contains sixteen correctly ordered look poses, rather than stretched v1 rows.
• The real package passes file checks and its states are distinguishable at display size.
• Untested client behavior and artwork permissions remain explicit.

Sources and scope

The references below distinguish documented behavior from our dated practical checks. Task prompts and completion checks are community guidance; each source states what it supports.

• OpenAI: public Hatch Pet v1 contractThe public repository’s older 8 × 9 contract and original manifest; it does not establish the current bundled v2 contract.
• Codex Pets: versioned format verificationDated inspection of the bundled v2 contract, real package/browser checks and explicit client-compatibility limits.
• Codex Pets: manifest contractThis website’s version/dimension mapping and required manifest fields; browser checks are separate from installation.
• codex-pets-react: atlas implementationThe state rows and timing used by this website, checked against installed version 0.2.0.

Something changed in your version? Send a correction with the guide URL, platform, and version. Leave out credentials and private project content.