pico8-cart-dev

name: "pico8-cart-dev" description: "PICO-8 cart development and maintenance for .p8 and modular Lua projects under token, CPU, and cart-size limits. Use when Codex needs to add or adjust mechanics, debug state/input/collision logic, tune constants, preserve cart asset sections (gfx, gff, map, sfx, music), rebuild carts, and keep a runnable gameplay loop."

PICO-8 Cart Dev

Develop in thin, playable slices and keep the cart runnable after every change.

Workflow

1. Identify the source of truth for code edits.

• If the project is modular, edit module files and rebuild the cart.
• Treat generated cart files as outputs unless explicitly asked to patch them directly.

2. Implement one small, player-visible change at a time.
3. Add debug visibility for subtle or invisible behavior changes.
4. Rebuild after meaningful edits.

• Prefer python3 build_cart.py.
• Use project alternatives if provided (./build_cart.sh, make cart).

5. Run the fast validation checklist in references/pico8-checklists.md.
6. Leave the project in a runnable state.

Implementation Rules

• Keep per-frame allocations low; reuse tables where possible.
• Use local aggressively in hot paths.
• Prefer simple state machines over implicit mode flags.
• Keep naming clear first; shorten names only when token pressure requires it.
• Keep 2-space indentation and snake_case.

State and Update Order

• Represent screens as explicit states (st_title, st_game, st_pause, etc.).
• Implement state lifecycle functions used by the project:
  • enter(prev_state)
  • update()
  • draw()
  • exit(next_state) when needed
• Keep per-frame simulation order predictable:
  1. handle input
  2. update entities
  3. resolve collisions
  4. apply game rules
  5. spawn/despawn
  6. update camera/effects
  7. draw

Build Safety

• Preserve authored cart asset sections during rebuilds.
• Never wipe __gfx__, __gff__, __map__, __sfx__, or __music__ unless explicitly requested.
• If a build step risks data loss, stop and report the risk before proceeding.

Reporting

• Report player-visible changes first.
• Report exact build/test commands run.
• State clearly when live PICO-8 runtime testing could not be executed in-session.

References

• Use references/pico8-checklists.md for preflight, validation, and compression triggers.