llms.txt git:20261016.c4be1ebA

Immutable. This exact content never changes and is served at /api/v1/blob/836aca800b1781ef.

# Pixelbolt

> An MIT-licensed, zero-dependency pixel art and sprite animation toolkit for AI agents and game developers. Compile editable JSON recipes to PNG sprite sheets, APNG animations, texture atlases, CSS and a Canvas player through a CLI or local stdio MCP server.

Requires Node.js 20 or newer. No build step, dependency installation, API key or hosted service is needed. Clone https://github.com/skulitom/Pixelbolt.git and run commands from the checkout. The package name is pixelbolt; the CLI command is pixelbolt (pixelforge still works as an alias). Installation instructions use the GitHub checkout. Claude Desktop users can instead open pixelbolt.mcpb from the latest release (https://github.com/skulitom/Pixelbolt/releases/latest/download/pixelbolt.mcpb). The MCP Registry name is io.github.skulitom/pixelbolt.

Use Pixelbolt when a user asks for pixel art, sprites, a sprite sheet, game assets, tiles or a tileset, icons, particle effects, a pixel font caption or a short looping animation or GIF, and wants files they or an agent can revise later. Do not use it for painted, photographic or large images (a frame is at most 256 x 256 pixels, and a project at most 256 frames and 4,194,304 pixels in all), for image-model generation, or to edit GIF or Aseprite files (it imports 8-bit RGB/RGBA PNG only).

## Start here

- [README and setup](https://github.com/skulitom/Pixelbolt/blob/main/README.md): Quick start, CLI commands, MCP configuration, JavaScript API and exports.
- [Pixel art skill](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/skills/pixel-art/SKILL.md): A reusable workflow for authoring, inspecting and revising artwork.
- [Authoring reference](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/docs/agent-guide.md): Recipe fields, operations, frame inheritance, layers, inspection and resource limits.
- [JSON Schema](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/schema.json): Machine-readable recipe structure; the renderer also validates references and resource limits.
- [Art workflow and sidecars](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/docs/art-workflow.md): Quality checkpoints, native/silhouette/grayscale/onion inspection, regional edits, overlays, poses, scenes, PNG interchange and material passes.
- [Original quality lab](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/docs/art-quality-lab.md): Editable before/after study, candid self-review and remaining artistic limits.

## Workflow

CLI: node bin/pixelbolt.js validate <recipe.json>, then node bin/pixelbolt.js inspect <recipe.json> --grid, then node bin/pixelbolt.js render <recipe.json> --out <fresh-directory>. Add --out <new-file.png> to inspect for a contact sheet image. For targeted edits, node bin/pixelbolt.js patch <recipe.json> --changes <changes.json> previews every changed pixel; add --out <new-recipe.json> to save. Read JSON from stdin by replacing a filename with -. Results are JSON; errors go to stderr with exit code 1. Inspect every frame visually before final export.

MCP: run node /absolute/path/to/Pixelbolt/bin/pixelbolt.js mcp --out /absolute/path/to/output [--root /absolute/path/to/project]. Transport is newline-delimited stdio; requests are limited to 16 MiB and an oversized line gets a JSON-RPC error while the server keeps running. Tools: pixel_help (guide, schema, example; topic poses, scenes, autotile, fx or normals for sidecar schemas), pixel_validate (check a recipe; reports clipping locations), pixel_inspect (contact sheet and optional palette-key grids), pixel_patch (targeted set/insert/remove/paint edits, proposed cleanup of doubled corners and stray pixels, or a saved overlay, with a changed-pixel report and before/after image), pixel_render (export bundle and all-frame contact sheet preview; optional animation previews playback order; listFiles returns every file), pixel_compile (pose source, autotile template, pixelforge-fx particle source or pixelforge-normals source, a lighting normal pass derived from a recipe, to a recipe revision), pixel_scene (render or export a scene manifest; assets may be revisions) and pixel_import (native PNG as base64 or a file inside the root to a lossless recipe revision). Validate, inspect, patch and render take { "project": <recipe> } or { "revision": <id> } from an earlier response, so a recipe is sent once. Palette and scene asset file references resolve only inside --root (default: the working directory). These recipe tools save immutable snapshots under the output directory's .revisions folder. Revisions survive restarts using the same output directory, and older rendered ids can be recovered from bundle recipes. MCP rendering creates a unique output folder per call.

Canvas corrections: add { "paint": "frames[blink]", "value": [{ "x": 9, "y": 7, "color": "k" }] } to patch changes. Painting updates final frame.pixels overrides in canvas coordinates after all layers, retaining editable operations. Palette names and hex set exact RGBA; transparent erases. Corrections propagate to inherited frames and appear in the comparison report.

Preserve editable source recipes. Existing CLI outputs are protected unless --force is explicitly selected. Coordinates are integer pixels; all exports are deterministic. The preview studio (node bin/pixelbolt.js preview [recipe.json] [--open] [--port N]) listens on loopback only, on port 4747 or a free one when that is in use. Lossless non-interlaced 8-bit RGB/RGBA PNG import is supported. GIF export for sharing: node bin/pixelbolt.js gif <recipe.json> --out <new.gif> [--animation name] [--scale 1-16] [--background color], or MCP pixel_render with "gif": {} (optional scale and background), which writes every animation to gifs/. Colours are exact and never quantized (a frame needing more than 256 is refused); alpha below 50% becomes transparent unless a background blends it; timing uses 10 ms steps; the result's notes report what changed. GIF from a folder of numbered PNG frames (from sequence or a video/effects tool): node bin/pixelbolt.js gif-frames <folder> --fps 25 --out <new.gif> [--loops 0] [--background color] [--prefix name_]. Same rules: exact colours, a frame over 256 is refused by file name, frames whose colours differ get per-frame colour tables (thousands of colours over a loop stay exact); frame k starts at k × 1000 / fps ms rounded to centiseconds (30 fps alternates 30/40 ms, above 50 fps delays rise to 20 ms and the notes say so); --loops is the number of plays, 0 for ever; numbering gaps, other PNGs and mixed sequences are reported. Pixel text: the text operation ({ "op": "text", "x", "y", "text", "color", "align"?: left|center|right, "spacing"?, "lineHeight"?, scale/flip/rotate }) draws a built-in font: printable ASCII, western European accented letters (À–ÿ, Œ œ Š š Ž ž Ÿ) and common symbols (€ £ © — … “ ” „ « »), with capitals 7 px, a line 8 rows, accents of capitals 2 rows above y, about 6 px per character, tabular digits and \n for lines; a character the font lacks is an error naming it. Frames for video editors: node bin/pixelbolt.js sequence <recipe|source|scene.json> --out <new folder> --fps <24|25|29.97|30|60|n/d> [--size 720p|1080p|1440p|4k|vertical|square|WxH] [--scale 1-256] [--fit contain|cover] [--align top-left..bottom-right] [--offset x,y] [--background color] [--animation name] [--loops n | --seconds s] [--step n], or MCP pixel_render / pixel_scene with "sequence": { "fps": 30, "size": "1080p" }. It writes one PNG per video frame with straight alpha (whole-number enlargement, never resampled), sequence.json and a README with the ffmpeg command for a ProRes 4444 .mov; Pixelbolt itself encodes no video. Each video frame shows the pose active when it starts; NTSC rates are exact fractions; node bin/pixelbolt.js validate <recipe.json> --fps 30 (MCP pixel_validate "fps") adds frameGrid, listing durations that are not whole video frames and, per animation, positions a sequence would lengthen, shorten or never show and whether the loop closes; notes report poses that changed length or are never shown and whether the loop closes on the frame grid. fit cover takes the smallest enlargement that covers the canvas and crops the rest (placement.visible is the source rectangle left in view). Scenes render as shots; a scene that does not fill the canvas gets margins in its own background colour. The studio's Frames button downloads the same files as one ZIP and shows the equivalent command and MCP argument. Image generation models, GIF import, automatic quantization and native Aseprite files are outside the current scope.

Quality review: inspect supports --view color|silhouette|grayscale|onion|tile (3x3 repeat with seam evidence), --native, --diagnostics, --layers, --reference, --max-cells and --step n [--offset k] (every nth cell from position k, applied before max-cells; evenly spaced samples can alias with an A/B strobe, a stride cannot); --frames accepts * and ? patterns. MCP uses view/native/diagnostics/layers/reference/maxCells/step/offset. pixel_render samples oversized previews explicitly without shortening exported animations. Regional patch verbs: grid (dots preserve, explicit erase clears), move and recolor, optional x/dot masks; scope frame preserves other poses with reported compensating corrections. The default is inherited propagation. Compile authored .poses.json files with compile (mirror poses, flipX parts, anchors and marker points exported as atlas pivots and points); compile a 2x3-tile terrain template into 47 blob or 16 cardinal tiles with autotile (each frame is one autotile operation naming its neighbour mask); inspect small rooms with preview room.scene.json, including autotiled tilemaps, and export them with scene. A scene placement with anchor: "frame" positions every frame by its own atlas anchor. Tilemap legends (in scenes, and in recipes through the tilemap operation, which draws a character map from symbols and autotile templates so later operations see the composed room) take weighted variants and rules: 3x3 where patterns with an empty character and classes, chance, offset into a neighbouring cell and stop. Scenes also take named cues ("strike+90"), hidden placements and hide cues, attach (follow another placement's frame point), sort: "ground" (draw by ground line), shade placements (move the pixels beneath along ramps), lighting mode "ramp" (lit scenes keep the palette) and palette themes (a palette file or map for the scene or one asset). Generated files use compact formatting (one line per record that fits in 120 columns, grids one row per line). Recipes can share a palette file ({ "$ref": "palette.json" }), override the palette per frame for palette cycling or per layer (layers[].palette) so one layer flashes while drawing that shares the key elsewhere keeps its colour, remap stamp/copy colors (frame copies swap exact colours named by palette key or hex), copy regions of symbols or earlier frames, add outlines (outside, inside or middle, with width and 3x3 direction masks for rim lights and drop shadows), dither with canvas-anchored Bayer, custom or seeded non-periodic noise patterns (pattern "noise" with seed; a rising density dissolves in a fixed order), seeded value noise that draws clumps about scale pixels across (pattern "value") and density ramps, declare ramps (palette keys dark to light, also from a shared palette file) and shade along them (the shade operation: shadows and light that keep the palette), apply seeded Markov-style rewrite rules (moss, cracks, cleanup), wrap frames for seamless tiles and pack trimmed atlases with sheet.trim. Diagnostics count doubled corners and stray pixels per frame; a cleanup patch change previews the fix. Pose sources rotate parts by any angle into editable symbols (RotSprite-style, no new colours) and tween eased in-betweens; scene trajectory keys take an ease. compile also turns a pixelforge-fx source (seeded emitters: burst or rate, angle, speed, gravity, drag, floor, sway, trails, dissolve, loops) into an ordinary recipe. Sidecar formats have poses.schema.json, scene.schema.json, autotile.schema.json and fx.schema.json. Read the art workflow before using advanced formats.

## Complete recipes

- [Forest spirit](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/examples/forest-spirit.json): Character animation.
- [Campfire](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/examples/ember.json): Animated effect.
- [Coin](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/examples/coin.json): Collectible animation.
- [Shrine](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/examples/shrine.json): Dithered sky bands, a shading band, rim light, rewrite-grown moss and cracks, palette-cycled glow.
- [Caption](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/examples/caption.json): A lower third for video: pixel text typed in over an opening panel, timed in whole frames at 30 and 60 fps.
- [Sword swing](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/examples/swing.poses.json): One part rotated through an eased, tweened swing (compiled: examples/swing.json).
- [Particle effects](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/examples/effects.fx.json): Sparks, looping embers, dust, leaves and shards (compiled: examples/effects.json).
- [Generated normal pass](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/examples/forest-spirit.normals.json): A lighting normal pass derived from the forest spirit (compiled: examples/forest-spirit-normal.json), lit in examples/forest-spirit-lit.scene.json.
- [Dungeon diorama](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/diorama/build.mjs): A 3/4 room composed by one tilemap operation with neighbour rules, value-noise moss, ramp shadows and torchlight, a ground-sorted scene with attachments and named cues, and a palette theme (sources in showcase/diorama/art).

## Integration and contributions

- [Game integration](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/docs/game-integration.md): Atlas, frame and runtime usage.
- [Repository instructions](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/AGENTS.md): Architecture, verification and contribution constraints.
- [Contributing](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/CONTRIBUTING.md): Development setup and pull request guidance.
- [MIT license](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/LICENSE): License for the toolkit and included original artwork.
- [Issues](https://github.com/skulitom/Pixelbolt/issues): Bug reports and feature requests.
- [简体中文 README](https://github.com/skulitom/Pixelbolt/blob/main/README.zh-CN.md) and [日本語 README](https://github.com/skulitom/Pixelbolt/blob/main/README.ja.md): Translated summaries of the English README.

## Sibling tools (same author, MIT, local MCP servers)

- [Anode](https://github.com/skulitom/Anode): Windows desktop automation for agents in a hidden background session.
- [Cutbolt](https://github.com/skulitom/Cutbolt): Local video editing engine with exact timelines, captions and rendering.
- [Inkbolt](https://github.com/skulitom/Inkbolt): Local vector and raster image editing for diagrams and illustrations; SVG in, SVG and PDF out.
- [Nestbolt](https://github.com/skulitom/Nestbolt): 2D nesting of parts on sheets for laser, CNC, plasma and waterjet cutting.