PixelForge

Text to pixels. A zero-dependency pixel art and sprite animation toolkit for AI agents and game developers.

Write a JSON recipe with palettes, text grids, reusable symbols and drawing operations. Get transparent PNGs, sprite sheets, animated PNGs, and the metadata and player needed to use them. Inspect and edit the recipe in a local browser studio.

Zero runtime dependencies. No build step, API key, image model, network service or native graphics library. Requires Node.js 20 or newer. Works from a checkout on Windows, macOS and Linux.

Quick start · Agent setup · MCP server · Recipe reference · Contributing

Art quality workflow

The original Listening Hollow study demonstrates silhouette/value/native-size review, animation-aware onion skins, masked regional corrections, authored parts and attachments, guarded rebuild overlays, a small scene, PNG interchange and aligned normal/emissive passes. See the format and workflow guide for the supported boundaries. This is a self-reviewed improvement study; it does not claim Animal Well parity.

npm run review:quality
node bin/pixelforge.js preview examples/quality/skink.json
node bin/pixelforge.js inspect examples/quality/skink.json --animation run --view onion --native --diagnostics

Related MCP server: ase-deliver

Start

git clone https://github.com/skulitom/PixelForge.git
cd PixelForge
node bin/pixelforge.js preview

Open http://127.0.0.1:4747. Pick the forest spirit, campfire or coin; edit the JSON; inspect the animation or sprite sheet; download the asset ZIP. The studio includes playback speed, frame selection, integer zoom, a pixel grid, onion skinning, palette inspection, source save/open and live error messages. All assets and fonts are local.

Or generate an asset without opening a browser:

node bin/pixelforge.js init hero.pixel.json
node bin/pixelforge.js validate hero.pixel.json
node bin/pixelforge.js inspect hero.pixel.json --out hero-frames.png
node bin/pixelforge.js render hero.pixel.json --out output/hero

inspect saves a contact sheet of every frame and lists each frame's timing. Add --grid to read frames back as palette-key text; --animation, --frames and --region narrow the view. patch hero.pixel.json --changes fix.json previews targeted edits and reports every pixel they change; add --out to save the new recipe. Commands return JSON; errors go to stderr and exit with code 1. Use - instead of a filename to read JSON from stdin. Existing output files are protected; add --force to replace them. You can optionally run npm link for the pixelforge command. No npm install is needed.

Play the local Emberfall demo

Emberfall is an original fantasy action platformer built to exercise PixelForge: 220 frames, 44 named animations, nine editable recipes, three elemental spells, reactive scenery, enemies and a boss. Its animation workshop exposes the recipes, contact sheets and complete export bundles.

npm run play

Open http://127.0.0.1:4173 and choose Begin adventure or Watch it play. The game runs entirely in the browser with no runtime dependencies. It is currently a local preview; hosting is intentionally deferred.

Demo details and controls · Stress-test findings and bug reports · PixelForge art-quality roadmap

For agents

Use PixelForge to create or revise pixel sprites, tiles, icons, effects and short animations from editable JSON. Choose the CLI when you have shell access or the Model Context Protocol (MCP) server when your client supports tools. Both use the same renderer and work locally.

Start with the authoring guide or MCP's pixel_help. Write a recipe, validate it, inspect every frame with pixel_inspect or pixelforge inspect, revise with targeted patches, then render to a fresh output directory. Validation checks the format; image inspection checks the art.

A tiny animation

{
  "version": 1,
  "name": "slime",
  "width": 8,
  "height": 8,
  "palette": { "g": "#72b58d", "e": "#20383f" },
  "frames": [
    {
      "name": "rest",
      "duration": 180,
      "ops": [{ "op": "grid", "x": 1, "y": 3,
        "rows": [".gggg.", "ggeegg", "gggggg", ".gggg."] }]
    },
    { "name": "up", "from": "rest", "translate": [0, -1], "duration": 180 }
  ],
  "animations": { "bounce": { "frames": ["rest", "up"] } }
}

Each text-grid character selects a palette color; . and space leave pixels untouched. Frame inheritance makes small changes cheap to describe. Rendering is deterministic and uses integer pixel coordinates.

Export bundle

APNG files use the .png extension intentionally. Lossless non-interlaced 8-bit RGB/RGBA PNG import is supported, optionally with unscaled atlas timing metadata; see interchange limits. GIF, native Aseprite files and automatic quantization remain outside the current scope. Sources stay editable JSON.

Connect an agent through MCP

Clone the repository first, then add the server to your agent's MCP configuration. Replace /absolute/path/to/PixelForge with your checkout's absolute path; on Windows use forward slashes, for example C:/DEV/PixelForge:

{
  "mcpServers": {
    "pixelforge": {
      "command": "node",
      "args": [
        "/absolute/path/to/PixelForge/bin/pixelforge.js",
        "mcp",
        "--out",
        "/absolute/path/to/PixelForge/output"
      ]
    }
  }
}

For clients that use TOML:

[mcp_servers.pixelforge]
command = "node"
args = ["/absolute/path/to/PixelForge/bin/pixelforge.js", "mcp", "--out", "/absolute/path/to/PixelForge/output"]

The five tools are:

• pixel_help: authoring guide, full schema and a complete sample.

• pixel_validate: validate { "project": ... } and save its recipe revision without exporting assets.

• pixel_inspect: contact sheets, exact regional grids, silhouette/grayscale/onion views, native size, named layer isolation, saved-reference comparisons and advisory diagnostics. Optional bounded samples expose omissions. Saves its recipe revision.

• pixel_patch: apply targeted set, insert, remove and paint edits. For example, { "paint": "frames[blink]", "value": [{ "x": 9, "y": 7, "color": "k" }] } corrects a pixel in final canvas coordinates after all layers; transparent erases it. Returns every frame whose pixels changed (exact pixels for small edits) and a before/after PNG. The source stays unchanged and successful edits get a new revision.

• pixel_render: render { "project": ... }, return a PNG contact sheet of every frame with cell names/timing plus output paths. Add "animation": "idle" to preview a sequence in playback order. The exported APNGs and HTML preview play the animation. Every call writes a fresh folder inside the configured output directory.

pixel_patch also supports compact grid, masked move and regional recolor, with explicit frame or inherited scope. Large pixel_render previews are sampled with total/shown/omitted metadata instead of blocking a valid export; exported animations remain complete. Pose compilation, scene export, guarded overlays and PNG import are available through the CLI/JavaScript API, then compiled sprite recipes use the same five MCP tools.

Send a recipe once. Each successful recipe-tool response includes a revision id that the other tools accept in place of project, so later calls, including patches, need not resend the recipe. Validate, inspect, patch and render save immutable snapshots in <MCP --out directory>/.revisions/; they survive restarts when you use the same directory, even before an asset export. Prefer an absolute --out path. Earlier revisions remain undo points. Older rendered revisions can be recovered from saved bundle recipes. Render also saves the recipe beside the assets.

The server implements newline-delimited stdio MCP with initialization, version negotiation, ping and tool discovery/calls. It supports protocol versions 2024-11-05, 2025-03-26, 2025-06-18 and 2025-11-25. It uses no HTTP transport or external services. See the MCP stdio specification.

An agent can also use the CLI directly. The reusable agent skill and authoring reference explain the complete format. schema.json supports editor completion and structural validation; the rasterizer additionally validates references, matching row widths and resource limits.

Use in a web app

Serve the exported folder with your application:

<canvas id="sprite"></canvas>
<script type="module">
  import { SpritePlayer } from './assets/player.js';
  const player = await SpritePlayer.load(
    document.querySelector('#sprite'),
    './assets/forest-spirit.atlas.json',
    { scale: 4 }
  );
  player.play('idle');
  // player.pause(); player.resume(); player.destroy();
</script>

Or use CSS alone:

<link rel="stylesheet" href="assets/forest-spirit.css">
<span class="pf-forest-spirit pf-forest-spirit-idle" role="img" aria-label="Forest spirit"></span>

CSS honors reduced-motion preferences. The Canvas API leaves autoplay decisions to the application. Atlas paths in SpritePlayer.load resolve relative to the atlas URL.

For a game engine, use the atlas rectangles or individual PNGs. For regular-grid importers, set sheet.padding to 0 and use the exported frame dimensions. Phaser accepts the JSON-hash frame layout via load.atlas; named animation sequences are in the extra animations field. See game integration notes.

JavaScript API

import { renderProject, inspectProject, patchRecipe, compareProjects, createBundle, writeBundle } from './src/index.js';

const project = renderProject(recipe); // RGBA buffers, durations, warnings
const view = inspectProject(project, { grid: true }); // contact sheet RGBA, palette-key grids
const { recipe: next, edits } = patchRecipe(recipe, [{ set: 'frames[idle].duration', value: 120 }]);
const report = compareProjects(project, renderProject(next)); // changed pixels, timing, before/after RGBA
const bundle = await createBundle(recipe);
await writeBundle(bundle, './output/my-sprite');

src/core.js and src/patch.js are browser-compatible and have no Node imports. The Node-only exporter uses the standard library for compression and file output. The studio shares the same renderer as the CLI and MCP server.

Develop and verify

npm test
npm run demo

Tests cover pixels, alpha blending, inheritance, transformations, flood fill, packing, timing, PNG/APNG structure, inspection sheets and grids, patching and comparison, revisions, overwrite protection, CLI stdin/errors, MCP calls, the Canvas runtime and the local server. Optional independent checks use Pillow and Python's ZIP reader: python scripts/verify-exports.py after npm run demo.

The studio binds to 127.0.0.1, serves an explicit asset allowlist, rejects foreign Host/Origin headers, and never writes through its HTTP API. Projects are limited to 256×256 pixels, 256 frames, 4,194,304 source pixels, 16,777,216 atlas pixels and bounded drawing/export work. This is designed for small sprites, effects and tiles.

Contributing

Bug reports, recipe examples, documentation improvements and focused pull requests are welcome. Read CONTRIBUTING.md and AGENTS.md before changing the toolkit. Report reproducible bugs through GitHub Issues.

License

MIT licensed. Included artwork is original and covered by the same license.