pet-platformer

name

pet-platformer

description

Turn a packaged Codex pet (the output of hatch-pet - pet.json + spritesheet.webp) into a playable, customizable side-scrolling platformer that ships as a self-contained static site. Use when the user wants to build a game from a pet sprite, theme or customize a pet game, generate themed game art around a Codex pet, or deploy a shareable pet game. The pet's fixed 8x9 atlas drives the player character; the output is a static bundle (index.html + game.js + styles.css + assets) with no backend, deployable to Netlify or any static host.

Pet Platformer

Build a side-scrolling platformer ("Crystal Run") around a Codex pet and ship it as a self-contained static site — no build step, no backend.

The pet's fixed 8x9 / 192x208 sprite atlas drives the player character; rows map to states (idle, run-left/right, wave, jump, fail, wait). The generated output is just index.html, game.js, styles.css, and an assets/ folder, with all paths relative — so it runs from any static file server and deploys cleanly.

This skill consumes the output of hatch-pet. Atlas geometry and the pet package layout are defined in references/codex-pet-contract.md; the row-to-state map the engine encodes is in references/animation-rows.md. Don't re-derive them - they are the source of truth.

Inputs

A pet, located one of three ways:

• --pet <id> -> ${CODEX_HOME:-$HOME/.codex}/pets/<id>/
• --pet-dir <folder> -> any folder with pet.json + a spritesheet
• --petdex <slug> -> pulled live from the PetDex gallery by slug (downloads pet.json + spritesheet via the PetDex manifest API and caches them under ${CODEX_HOME:-$HOME/.codex}/petdex-cache/<slug>/)

List local pets, or browse the PetDex gallery for a slug:

ls "${CODEX_HOME:-$HOME/.codex}/pets/"        # local pets
# or browse https://petdex.crafter.run/ and pass the slug to --petdex

Environment

• Build needs only Python 3.
• Art generation needs an OpenAI API key (OPENAI_API_KEY, or a Codex API-key login) and curl.
• Deploying to Netlify needs netlify-cli and netlify login.

SKILL_DIR="<this skill's dir>"   # e.g. ./skills/pet-platformer

Workflow

1. Pick the pet and lock the theme

Read pet.json and inspect the spritesheet so the world matches the character. Confirm the important levers with the user instead of silently picking defaults:

• theme / world
• palette
• labels
• difficulty / lives / goal threshold
• whether to use procedural art only or generate selected themed assets

Write the choices to game-config.json (schema: references/game-config.md; starter: templates/game-config.example.json). All fields are optional.

2. Optionally generate themed art

Only if the user wants custom art. Each generated file is optional; anything not generated falls back to procedural pixel art. This step is skippable entirely.

python3 "$SKILL_DIR/scripts/generate_assets.py" \
  --pet <id> \
  --config /path/to/game-config.json \
  --out /path/to/generated-assets \
  --keys background,collectible,walker

Preview prompts first without spending tokens:

python3 "$SKILL_DIR/scripts/generate_assets.py" \
  --pet <id> --config /path/to/game-config.json \
  --out /tmp/generated-assets --dry-run

Asset keys: background, collectible, super, walker, flyer, spiker, tile, goal. Inspect the PNGs before building and regenerate anything that misses.

3. Build the static site

python3 "$SKILL_DIR/scripts/build_game.py" \
  --pet <id> \
  --config /path/to/game-config.json \
  --output-dir /path/to/<pet-id>-site

The output is a flat static bundle:

<pet-id>-site/
  index.html
  game.js
  styles.css
  assets/<pet-id>/spritesheet.webp   (+ any generated art)

Swap --pet <id> for --petdex <slug> to build straight from the PetDex gallery. Pass --assets-dir <dir> to wire in generated art (or drop the <key>.png files under <output>/assets/ before building). Use --force to overwrite a non-empty output directory.

4. Run locally

cd /path/to/<pet-id>-site
python3 -m http.server 8000
# open http://localhost:8000/

Verify the pet animates and controls correctly, the theme/labels are right, and any generated assets appear.

5. Deploy to Netlify

The bundle is self-contained, so deploy it directly:

"$SKILL_DIR/scripts/deploy_netlify.sh" \
  --dir /path/to/<pet-id>-site \
  --name <pet-id>

First run creates https://<pet-id>.netlify.app and pushes a production deploy; re-run with --site <site-id> (or NETLIFY_SITE_ID) to redeploy the same site. The bundle also deploys to any other static host (GitHub Pages, etc.) unchanged.

Controls / mechanics

Left/right or A/D move. Up, W, or Space jumps. Hold jump for height. R restarts the current life.

Stomp walkers and flyers from above. Spikers cannot be stomped unless boosted. Collect enough collectibles to open the portal. Touch controls appear on coarse-pointer devices.

Files

• templates/game.js - the platformer runtime
• templates/styles.css - the game chrome
• templates/index.html.tmpl - the static game page template
• scripts/build_game.py - assembles the static site
• scripts/generate_assets.py - generates themed art
• scripts/deploy_netlify.sh - one-command Netlify deploy
• references/animation-rows.md, references/codex-pet-contract.md - pet atlas contract
• references/game-config.md - config schema

Acceptance criteria

• Generated output is a self-contained static bundle (relative paths, no backend).
• The game loads from a plain static server, is playable, and remains winnable.
• Any missing generated art falls back cleanly to procedural assets.
• The bundle deploys to Netlify (or any static host) without modification.