Skip to main content

SpriteForge

Describe a game in a sentence. A team of AI agents builds a playable 2D pixel-art browser game, and you approve every step.

Stormlight Keeper, a platformer SpriteForge built

SpriteForge runs on your own machine. Muse Spark plans, designs, writes and repairs the game; Muse Image draws and revises its art. Eleven role-based agents carry the game from brief to finished build and pause at five human gates. Each finished game teaches the harness: its lessons go to a local, auditable knowledge base that later builds read once you promote them.

Built for the Meta Global AI Developer Hackathon (Oct 26 - Nov 4, 2026).

Highlights

  • A studio, not a prompt box. A chat-first local UI shows the agents in the order they work. Chat with any of them, give them reference images, or stop a run and send it back to an earlier step.
  • You decide, the agents work. Five gates: brief, design, menus, playtest, final. Feedback in plain words goes only to the agent it is about, and after a playtest the Director shows its plan for your feedback before anything is rebuilt.
  • Real games. Full-HD (1920x1080) Phaser 3 games with menus, saved progress, synthesised sound and a sound editor, exported as a static site with their own pytest + Playwright tests. Side-view games get levels written as data and proven clearable by code.
  • Code checks what models write. Palettes, sprite grids, tile seams, level reachability, menu flow and jump physics are checked deterministically, and a bot plays every level before you do.
  • Costs you can see. Every Muse call is metered in a durable ledger, and each agent has its own $10 allowance.
  • Runs offline. Mock providers stand in for Muse, so the whole pipeline and its 525 tests run without a key.

The studio: agents on the left, the run in the middle, costs on the right

Games made with SpriteForge

Each started as one sentence, went through all five gates, and was played and approved by a human. Every sprite, tile and title picture is Muse Image art or CC0/free-to-use library art.

Game Genre Builds Muse cost
Stormlight Keeper: climb a storm-battered lighthouse and relight its lamps before the ship hits the rocks Side-scrolling platformer 3 $1.77
Pale Shores: Three-Isle Hold: command small squads against Viking landings across three islands Real-time island defence 10 $4.89
Tiny Kingdom Defense: build basic, splash and slow towers along a winding path for six waves Tower defense 3 $1.66

Gameplay clips: Stormlight Keeper · Pale Shores · Tiny Kingdom Defense

The builds count feedback rounds: Pale Shores took ten because a human playtest found the squads too weak to win, twice, and each round went back through the Director's plan. Two harness checks came out of these games: a HUD check (texts drawn over each other or off the screen fail the playtest) and a tile check (a ground tile drawn as an object on a background is redrawn).

How a game gets made

flowchart LR
    idea(["Your idea"]) --> G1["G1 Brief"] --> G2["G2 Design"] --> G3["G3 Menus"] --> G4["G4 Playtest"]
    G4 -->|feedback| plan["The Director's plan"]
    plan -->|you approve it| redo["Only the affected agents redo their part"]
    redo --> G4
    G4 -->|approve| G5["G5 Final"] --> kb[("Knowledge base")]
Gate You see What happens before it
G1 Brief A short questionnaire for your genre The Director picks one of 11 genre kits and the questions that matter for it
G2 Design Research, the game plan, the design (and a story, if you asked), every agent's task list The Game Designer studies similar games with Muse Spark web search, writes a numbered plan that code checks, then the design
G3 Menus Every screen of the game and its title art The Menu Designer writes the menus as data; Muse Image draws the title art
G4 Playtest A play link, the art sheet, animations, the build report, each agent's report Art comes from the local library or Muse Image; for a side-view game the Level/Tile Designer writes levels that code proves clearable; the Programmer writes Phaser code against a small SDK; a bot plays every level; the QA Playtester's tests run with real key presses; failures go back for repairs; the Art Reviewer (Spark vision) checks the art in the running game
G5 Final The whole game, its cost, and the Librarian's lessons Approval exports the game and its full record

At any gate, write feedback in plain words ("the slime should jump higher", "the splash is too loud"). The Director splits it into design, art, code, level, menu, sound, story and QA changes and routes each to its agent; only that part is redone. At G4 and G5 its reading is shown first, as a plan: submit it empty to approve, or type what the Director got wrong and it plans again. Nothing is built until you approve.

In the studio you can also:

  • chat with any agent: a question is answered from that agent's own work; a change is filed into its part of the next revision;
  • go back: changing work that is already done stops the agent working now and rewinds the run to the step the change is about (calls already paid for are kept and cached);
  • give references: images for one agent or for all of them (Spark sees them; the art agents' references steer Muse Image's style);
  • apply an Art Reviewer suggestion with one click, or send feedback for one level only.

How SpriteForge uses Muse

Agent Muse Its job
Director Spark Picks a genre and the brief's questions; turns your feedback into a plan of changes per agent
Game Designer Spark, web search Studies similar games online; writes the game plan, the design and, on request, a story
Level/Tile Designer Spark, web search Studies the level design of similar games; writes each level as data
Art Director Spark Picks library art; writes every entity's animation rows, forms and effects
Pixel Artist Muse Image Draws sprite sheets (a row of frames per animation), the title background and an emblem
Menu Designer Spark Writes every menu screen as data
Sound Director Spark Picks a synthesised sound for every moment of the game
Programmer Spark Writes the Phaser 3 game against a small SDK, then repairs it from what failed
QA Playtester Spark Writes tests played with real key presses, and code checks for each game
Art Reviewer Spark vision, Muse Image edits Reviews the art in screenshots of the running game and fixes blocking issues
Librarian Spark Writes the lessons each finished game teaches; describes library art (vision)

The Muse features the harness relies on, each verified with live calls (the notes are in src/spriteforge/config.yaml):

  • strict json_schema output for every design, plan, level, menu and code file set;
  • reasoning_effort per task: low for routing, high for design and code, max for the art review;
  • prompt caching: prompts lead with their stable part and send a prompt_cache_key per task;
  • web search through the Responses API, with every URL the research cites checked against the pages the search returned;
  • vision: screenshots of the running game, library art and your reference images;
  • Muse Image generations and edits at the high setting, with reference images and a content-addressed cache, so an identical request is never paid for twice;
  • tool use: in a live build, agents call their granted MCP tools and load skills before they answer.

Principles

  • Models propose; code enforces. Palettes, sprite sizes, tile seams, jump physics, menu reachability and QA tests are checked by code, not trusted.
  • Accepted art is locked. Muse Image has no seed, so approved assets are never regenerated unless you ask for a change to them.
  • Caps stop loops, not you. Each agent may spend $10 (budget.max_agent_cost) since your last action; its loops (repairs, redraws, review rounds) go on while they improve, until that is used up. Work you ask for always starts. spriteforge report RUN_ID shows calls, tokens and cost.
  • Local-first. All data stays in a workspace folder. The API key is read from the environment and scrubbed from logs, memory and exports.
  • Auditable learning. Knowledge is plain Markdown in a git repo (OKF format). Lessons the agents write stay "generated" until a human promotes them.
  • Extensible. Agent roles are Markdown files; skills (SKILL.md folders) and MCP servers are granted per agent.

Quick start

Requires Python 3.11+. Node.js is optional (used to syntax-check generated code).

pip install spriteforge
python -m playwright install chromium

To work on SpriteForge itself, install from a clone instead (this also gets you the tests and the CC0 art packs in assets/library/):

git clone https://github.com/reviver134/spriteforge.git && cd spriteforge
python -m venv .venv && . .venv/bin/activate     # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
python -m playwright install chromium

Installed with pip, the art library lives in ~/spriteforge-workspace/library (or the folder SPRITEFORGE_LIBRARY names) and starts empty: add packs with spriteforge library add, or let Muse Image draw everything.

Offline (no key):

python -m spriteforge start --agents --mock --workspace workspace

Live with Muse: put your key in the environment or in a .env file in the folder you start from (in a clone, .env is gitignored), then start without --mock:

echo META_API_KEY=your-key > .env
python -m spriteforge start --agents --workspace workspace --goal "a slime that squishes through a cave"

The studio opens at http://127.0.0.1:8765 (the previous UI stays at /classic), and python -m spriteforge on its own opens it for every project in the workspace: describe a new game there (without a key it offers the offline mock), and several projects can run at once. It serves localhost only and refuses cross-site requests. Stop the process at any gate and pick up later:

python -m spriteforge runs --workspace workspace
python -m spriteforge resume RUN_ID --workspace workspace

Without the UI: design, art, code, playtest and repair in one command:

python -m spriteforge game make "a 10 minute top-down survival game" --out out/survival
python -m spriteforge game make "a slime arena" --out out/slime --mock

What you get

Each run lives in workspace/runs/RUN_ID/. A finished game (game/vN/) is a static Phaser 3 site with no build step: open index.html over any static server, or host it anywhere.

  • export.zip: the build, its QA tests (pytest build/tests) and its full record.
  • sounds.html: a sound editor. All sound is synthesised in the browser (no audio files).
  • game/db/: the game's record as an OKF bundle (design, entities, art, code, QA, builds, your decisions), readable by agents through read-only MCP tools (spriteforge game db mcp workspace/runs/RUN_ID).

In the game: arrows/WASD and Enter, Escape pauses, M toggles sound. ?play=1 skips the title, ?reset=1 clears saved progress.

Knowledge, skills and tools

python -m spriteforge memory --help                         # search, validate, promote lessons
python -m spriteforge memory promote lessons/<id> --by you  # let later games use a lesson
python -m spriteforge skills --help                         # add SKILL.md folders, grant per agent
python -m spriteforge mcp --help                            # add MCP servers, grant per agent
python -m spriteforge library --help                        # local art packs with license tracking

Agent roles are Markdown files in src/spriteforge/agents/roles/; built-in skills are in src/spriteforge/skills/builtin/, including seven open-source game-development skills (level design, platformer, puzzle, game feel, physics tuning, audio design, game UI/UX; Apache-2.0) granted to the agents they suit.

In a live build each agent may look things up before it answers (up to game.tool_rounds rounds): the built-in MCP tools its role grants (library.* for the art library, game_db.* for the game's record), its skills (load_skill), and your MCP tools granted to it that you set to run without confirmation. Each lookup shows in the agent's chat. game.agent_tools: false turns this off (one call per answer).

MCP server templates are in src/spriteforge/mcp/templates/. The official fetch server lets agents read public web pages (needs uv; it refuses private and local addresses):

python -m spriteforge mcp add fetch src/spriteforge/mcp/templates/fetch.json
python -m spriteforge mcp inspect fetch
python -m spriteforge mcp enable fetch --role "Level/Tile Designer"
python -m spriteforge mcp policy fetch fetch --no-confirm   # builds use only tools that do not ask

The Context7 server gives the Programmer the Phaser 3.90 documentation (needs Node.js; the questions go to context7.com; an optional free CONTEXT7_API_KEY raises its limits):

python -m spriteforge mcp add context7 src/spriteforge/mcp/templates/context7.json
python -m spriteforge mcp inspect context7
python -m spriteforge mcp enable context7 --role Programmer
python -m spriteforge mcp policy context7 resolve-library-id --no-confirm
python -m spriteforge mcp policy context7 query-docs --no-confirm

python -m spriteforge mcp disable NAME takes a server away again.

Configuration

src/spriteforge/config.yaml (or your own file with --config) holds the endpoints, the model ids (muse-spark-1.3, muse-image-1.0), the reasoning effort per task and these switches:

Key Default What it does
budget.max_agent_cost 10 USD each agent may spend since your last action
game.patience 2 An agent's loop stops after this many tries in a row without improvement
game.screen_scale 6 320x180 design pixels times this: 6 is 1920x1080, 4 is 1280x720
game.image_reasoning high Muse Image's setting for every first draw
game.review true The Art Reviewer checks the art before G4
game.agent_tools true Agents may call MCP tools and load skills in a live build
game.hud_check true The bot playtest fails a build whose HUD texts cover each other or run off the screen

Project layout

src/spriteforge/
  agents/     role prompts (Markdown), router, agent runtime
  app/        FastAPI server, the built studio (static/) and the classic page
  core/       state (SQLite), gates, cost ledger, secret scrubbing
  providers/  Muse Spark, Muse Image, web search, and mock providers
  stages/     the gated workflow: brief, design, menus, playtest, final, rewind
  game/       design, levels, art, code generation, the game SDK, menus, sounds, QA, export
  pixel/      deterministic pixel tools: grid detection, palettes, seams, atlases
  memory/     OKF knowledge base
  library/    local art packs with license tracking
  skills/     SKILL.md folders granted per agent
  mcp/        MCP servers and templates granted per agent
ui/           the React studio (Vite, TypeScript); its build is committed to app/static/
tests/        pytest + Playwright, offline
docs/         engineering notes: levels, QA code checks, the Sound Director, the studio
tools/        live-run, font and art-library helpers

Tests

python -m pytest -q

The tests use mock providers and make no network calls; the browser tests need the Chromium installed above.

Developing the studio UI

The React studio lives in ui/ (Vite, React 18, TypeScript). Its build is committed to src/spriteforge/app/static/, so running SpriteForge never needs Node.

cd ui && npm ci
npm run dev     # http://localhost:5173, proxies /api to a running `python -m spriteforge`
npm run build   # type-checks, then rewrites src/spriteforge/app/static/

License

SpriteForge is released under the MIT License. Bundled third-party parts keep their own licenses:

  • Phaser 3.90.0 (MIT) in src/spriteforge/templates/phaser/vendor/;
  • the Press Start 2P font (SIL OFL 1.1, license next to it) in the studio build;
  • seven skills from awesome-gamedev-agent-skills (Apache-2.0, see src/spriteforge/skills/builtin/THIRD_PARTY.md);
  • art packs in assets/library/, tracked by license: only packs verified as redistributable (CC0 here) are committed; the rest stay on your machine and are listed in assets/library/.gitignore.

Metadata

Release files for spriteforge 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for spriteforge 0.1.1
File Size Uploaded Provenance Actions
spriteforge-0.1.1.tar.gz 1.2 MB Without provenance Details for spriteforge-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for spriteforge 0.1.1
File Interpreter ABI Platform Actions
spriteforge-0.1.1-py3-none-any.whl Python 3 none any Details for spriteforge-0.1.1-py3-none-any.whl

Total release size: 2.3 MB

Release files / spriteforge-0.1.1.tar.gz

Download URL spriteforge-0.1.1.tar.gz
Size 1.2 MB
Tags Source
SHA-256 checksum
How to use checksums
f2c605a498c10ccced57a62dfbbd29de34949a70d0820c096ffeba8e1c7b46fe
BLAKE2b-256 checksum
How to use checksums
791555ac0798959f5e58db53e351cac39abb2a2324243827adb4355c1066ffcf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.3

Release files / spriteforge-0.1.1-py3-none-any.whl

Download URL spriteforge-0.1.1-py3-none-any.whl
Size 1.1 MB
Tags Python 3
SHA-256 checksum
How to use checksums
59e0346a9032ac90e15c28d898951def2e8aa13884bf6d48fb6dda6464be8345
BLAKE2b-256 checksum
How to use checksums
6a4e251a06ef35c9f737baf17c4a8f41f18d12c405af0d697aed52f8019a2f56
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.3

Security for spriteforge 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page