pico8-claude-framework

A PICO-8 game development framework for Claude Code.
Scaffold a new game, set up your project context, and start building — all from one command.

Built by Brown Hammer Studios

What This Is

PICO-8 is a fantasy console with a small, fixed API and strict constraints. Claude Code is an AI coding agent that works best when it has persistent context about what it's building and what rules it's working within.

This framework gives Claude Code everything it needs to develop PICO-8 games effectively:

• A CLAUDE.md file that loads automatically in every Claude Code session — covering the full PICO-8 API, token limits, cart section rules, Lua quirks, and behavioral guardrails
• A pico8-cheatsheet.md that gets pulled into Claude's context via @include
• A setup script (npx create-pico8-game) that scaffolds a new game project with a starter pattern, a CLAUDE.local.md with your game's context, and organized wip/ and dist/ folders

Requirements

• Node.js v16 or higher
• Claude Code installed: npm install -g @anthropic-ai/claude-code
• PICO-8 installed (needed for the export command — not for setup)

Quick Start

Create a folder where you want to work, then run:

mkdir my-pico8-games
cd my-pico8-games
npx create-pico8-game

The setup script will:

1. Download CLAUDE.md and docs/pico8-cheatsheet.md into your current folder
2. Show a quick intro banner
3. Ask you 12 questions about your game
4. Scaffold a ready-to-open .p8 cartridge and a CLAUDE.local.md in wip/<your-title>/
5. Create an empty dist/<your-title>/ folder ready for export

Then open Claude Code:

claude

And tell it to get started:

open wip/<title>/<title>.p8 and let's start building

Setup Questions

The script asks 12 questions to tailor the scaffold to your game:

| # | Question | Why It Matters | |---|---|---| | 1 | Game title | Names the folder and .p8 file | | 2 | One-sentence description | Written into CLAUDE.local.md for context | | 3 | Game type | Selects the starter pattern | | 4 | Custom genre (if "other") | Noted in CLAUDE.local.md | | 5 | Number of players | Wires 1 or 2-player controls into the scaffold | | 6 | Target framerate | Uses _update (30fps) or _update60 (60fps) | | 7 | Does the world scroll? | Scaffolds camera() calls if yes | | 8 | Title screen? | Adds a "title" state to the state machine if yes | | 9 | Uses tilemap? | Includes map() and mget/fget collision if yes | | 10 | Save data? | Scaffolds cartdata(), dget/dset if yes | | 11 | Uses music? | Calls music(0) in _init if yes | | 12 | Project scope | Jam / Small / Release — affects how Claude manages token budget |

Game Types

| Type | What You Get | |---|---| | Platformer | Gravity, per-axis tile collision, jump, camera follow | | Top-Down | 8-directional movement, screen or world-space clamping | | Shooter / Shmup | Bullets, enemies, AABB collision, score, game-over state | | Puzzle / Menu-Driven | State machine with title, game, win, and lose states | | Other | Minimal blank scaffold with your genre noted for Claude |

Project Structure

After running the setup script, your folder will look like this:

my-pico8-games/
├── CLAUDE.md                  ← loaded by Claude Code every session
├── docs/
│   └── pico8-cheatsheet.md    ← full API reference, @included in CLAUDE.md
├── wip/
│   └── your-game/
│       ├── your-game.p8       ← scaffolded cartridge, ready to open
│       └── CLAUDE.local.md    ← game-specific context for Claude
└── dist/
    └── your-game/             ← export outputs land here

Exporting Your Game

When your game is ready, run this command (replace <title> with your game's folder name):

mkdir -p dist/<title> && \
pico8 -export dist/<title>/<title>.p8.png wip/<title>/<title>.p8 && \
cp wip/<title>/<title>.p8 dist/<title>/<title>.p8 && \
pico8 -export dist/<title>/<title>.p8.rom wip/<title>/<title>.p8

Or just tell Claude Code: "export the game" — it knows the command.

This produces three files in dist/<title>/:

| File | Format | Use | |---|---|---| | <title>.p8 | Raw source | Share on the PICO-8 BBS, back up, edit | | <title>.p8.png | PNG cartridge | Standard share format — itch.io, Twitter, etc. | | <title>.p8.rom | Binary ROM | Embed, archive, or run on compatible players |

How Claude Uses This Framework

When you open Claude Code in your project folder it automatically reads:

1. CLAUDE.md — the persistent ruleset: PICO-8 API, token budget rules, cart section permissions, Lua quirks, the game loop structure, and behavioral guardrails
2. docs/pico8-cheatsheet.md — the full API and keyboard shortcut reference, pulled in via @include
3. wip/<title>/CLAUDE.local.md — your specific game's context: title, genre, scope, players, framerate, and what's been scaffolded

Claude Code won't exceed 8192 tokens, won't touch __gfx__ or __map__ unless you ask, won't use standard Lua libraries that don't exist in PICO-8, and will warn you when your token budget gets tight — with the warning threshold adjusted for your project's scope.

Multiple Games

You can have as many games in wip/ as you want. Each one has its own subfolder and CLAUDE.local.md. Run npx create-pico8-game again from the same root folder to scaffold another. If a title already exists it auto-renames with a number suffix (myfungame-2).

Customizing Claude's Behavior

CLAUDE.md at the root sets the rules for all games. If you want to override or extend anything for a specific game, edit that game's CLAUDE.local.md — Claude reads it at the start of every session and it takes priority for project-specific context.

Contributing

Issues and PRs welcome. If you add a new game type pattern, follow the structure in lib/patterns.js — each pattern exports { lua, notes } and receives the full config object from the setup script.

License

MIT — see LICENSE

Brown Hammer Studios · patreon.com/brownhammerstudios
PICO-8 is a product of Lexaloffle Games. This framework is a community project and is not affiliated with or endorsed by Lexaloffle.