Creator guide

How to Create a Custom Codex Pet

A Codex pet is a small animated companion packaged as pet.json plus spritesheet.webp. Codex Pet Lab validates, previews, packages, and installs pets that follow the V2 animation contract.

1. Start with a pet concept

Choose one readable full-body character with a stable face, palette, silhouette, and props. Every frame must remain clear inside a 192×208 cell, so avoid tiny text, detached effects, soft shadows, and scenery.

  • Give the pet a lowercase slug such as cloud-bun.
  • Write a short display name and one-sentence description.
  • Decide whether the character is an animal, person, robot, or another compact mascot.

2. Produce the V2 animation atlas

A new V2 pet uses an 8-column by 11-row spritesheet. Rows 0–8 contain standard Codex states. Rows 9–10 contain 16 clockwise look directions.

  • Cell size: 192×208 pixels
  • Atlas size: 1536×2288 pixels
  • Format: transparent WebP or PNG
  • Version: spriteVersionNumber 2

3. Create pet.json

{
  "id": "cloud-bun",
  "displayName": "Cloud Bun",
  "description": "A soft deployment bunny for Codex.",
  "spritesheetPath": "spritesheet.webp",
  "spriteVersionNumber": 2,
  "kind": "animal"
}

4. Validate and preview locally

Open My Library in Codex Pet Lab and select pet.json and spritesheet.webp. Validation runs locally in the browser, confirms the manifest and atlas dimensions, and plays frames from the real spritesheet before anything is uploaded.

5. Package and install

Download a .codex-pet.zip package or install a published pet with the codexpetlab CLI.

npx codexpetlab add cloud-bun

Related resources