Pixelbolt

# 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.

Example output: [a library scene drawn and animated with Pixelbolt](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/gallery/library.gif). Claude Code users can install the pixel art skill in one line, with no checkout and no MCP server: npx -y pixelbolt@latest skill install (Node.js 20 or newer; Pixelbolt 0.9.2 or later).

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). The skill install writes ~/.claude/skills/pixelbolt-pixel-art/ (--project: the current folder's .claude/skills/; --dir: any skills folder) with the guides, schemas and examples beside SKILL.md, runs every command through npx -y pixelbolt@<that version>, and never replaces a changed copy without --force. For the MCP tools too, install the Claude Code plugin instead, which brings the server with the same skill (claude plugin install pixelbolt --marketplace skulitom/Pixelbolt); Claude Desktop users can open pixelbolt.mcpb from the latest release (https://github.com/skulitom/Pixelbolt/releases/latest/download/pixelbolt.mcpb). Other installation instructions use the GitHub checkout. 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 or photographic images or large animations (an animation frame is at most 256 x 256 pixels, and a project at most 256 frames and 4,194,304 pixels in all; a single still, such as a 1920 x 1080 backdrop or mural, may be up to 4096 pixels a side within that total), for image-model generation, or to edit GIF or Aseprite files (it imports PNG only, at up to 8 bits per channel).

## Start here

- [README and setup](https://github.com/skulitom/Pixelbolt/blob/main/README.md): Quick start, CLI commands, MCP configuration, JavaScript API and exports.
- [Browser playground](https://skulitom.github.io/Pixelbolt/playground/): Render, export and share recipes in a browser with nothing installed; share links and exported PNGs carry the recipe and the engine version, so they reopen exactly.
- [Live fluid toy](https://skulitom.github.io/Pixelbolt/playground/fluids/): The fluid presets (campfire, honey, slime, waterfall, potion, magic swirl, steam) run live in a browser on the released engine's createLiveFluid; drag to stir, hold to pour, save a GIF, or copy a link that replays the pokes frame for frame.
- [Pixel art skill](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/skills/pixel-art/SKILL.md): A reusable workflow for authoring, inspecting and revising artwork.
- [Agent quick start](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/docs/agent-quick-start.md): The recipe format with a complete example, the operations, the tools and working habits in about 2,000 tokens; what MCP pixel_help returns.
- [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.
- [Pixel art and sprite MCP servers compared](https://skulitom.github.io/Pixelbolt/compare/pixel-art-mcp-servers-for-ai-agents/): Pixelbolt against aseprite-mcp, pixel-mcp, pixscii, pixelart-mcp, pixelforge-mcp and SpriteCook, checked 17 October 2026 and refreshed 29 October, with Pixelbolt's measured runs, how each makes the art, exports, single-pixel edits, cost, and when to choose each.
- [Pixel FX Designer alternatives compared](https://skulitom.github.io/Pixelbolt/compare/pixel-fx-designer-alternatives/): tools for pixel-art fire, smoke, explosion, water and spell effects (Pixel FX Designer, SpriteMancer, Fluid FX, Pixel Composer, PHOSPHOR, BlastFX, Pixel VFX Forge and Pixelbolt), checked 19 October 2026 with Pixel VFX Forge added 27 October, with Pixelbolt's fluid presets measured (repeatability, palette-only output, loop seams, timings), particles or fluid simulation, exports, palette control, which run without a GUI, and when to choose each.

## Workflow

Looping interference and portals: [wave controls and presets](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/docs/wave-effects.md), [wave schema](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/wave.schema.json). Compile a pixelforge-wave source with pixel_compile, or open it directly in the studio. Palette grids bake the motion; no runtime wave solver is needed.

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] [--time-limit seconds]. 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. Each tool call runs in a worker thread; one that takes longer than 50 seconds (the default time limit) or runs out of memory is stopped and answered with an error, and a sequence from one call may come to at most 512 MB. Tools: pixel_help (a short quick start; topic guide, workflow, schema or example for the full authoring guide, the art workflow, the recipe JSON Schema or a complete recipe, and poses, scenes, autotile, fx, fluid, wave or normals for source format 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 PNG import is supported (RGB, RGBA, greyscale and indexed, up to 8 bits per channel, not interlaced). 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), lights that follow a placement or its frame point, flicker (seeded, seamless per scene loop) and flash with keyed strength and radius on cue times, lit: false for light sources that keep their colours 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, box, ring, arc or line spawns with even spacing and outward launches, angle, speed, gravity, drag, floor, sway, trails, dissolve, loops, sprites facing their direction of travel, tint stages over the life, child emitters spawning where particles end, land or travel, behind layering, eased frame durations and cues exported as frame points, plus shape layers: shockwave rings, slashes, beams, lightning bolts, magic circles, impact stars, fireballs and tapered streams, each a field in a frame window cut into palette bands by a named look, with dither, lit and shade bands, cleanup and outline, and blob particles that merge into one body in a look) 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.

## Moving figures

Use pixelforge-poses with bone limbs, mass bodies, grid heads/props, ramps and world light. Relative angle composes with attachments; rotate stays absolute. reach on the second bone targets canvas pixels; views preserve grid detail at authored angles; relight mirrors redraw structural light. rig roles plus motions expand idle/walk/run/jump/attack/hurt into editable poses (side views keep near limbs in front; swapDepth: true exchanges them for front or back views); compile --expand saves the expansion. Authored poses override generated names. Inspect sources with inspect --motion run --speed 48 (or pixel_inspect source + view: motion); compiled recipes require explicit pose metadata. Reports include contacts, slide, ground error, pose spread and joint loop seams. The studio edits pose sources, plays them, and offers Motion and Show contacts. Read docs/art-workflow.md#structural-limbs-and-bodies for constraints and template parameters.

## 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).
- [Rigged hero](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/examples/hero.poses.json): A side-view figure of bones, a mass torso and a grid head, rigged for the idle, walk, run, jump, attack and hurt templates.
- [Particle effects](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/examples/effects.fx.json): Sparks, looping embers, dust, leaves and shards (compiled: examples/effects.json).
- [Spell effects](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/examples/healing-circle.fx.json): A magic circle with a pillar of light and rising sparkles; seven more in examples/*.fx.json, among them a swirling vortex, a falling meteor and a shield bubble (slash hit, fire explosion, a seamlessly looping fireball in eight directions, lightning strike), hero-magic.fx.json (the rigged hero taken apart pixel by pixel in a teleport, and a looping aura hugging his outline), swing-trail.fx.json (a crescent smear that follows a pose's sword tip round its hilt) and fluid-blast.fx.json (the fluid explosion playing under a flash star, a shockwave and embers), each shape layers cut into palette bands by named looks, with a few particle emitters.
- [Spell library](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/examples/fire-spells.fx.json): Game spells for seven elements (fire, ice, lightning, water, poison, holy, shadow) in examples/<element>-spells.fx.json, each a looping projectile in eight directions, an impact, an area effect and a looping buff on one 64 × 64 canvas anchored at the point a game places them.
- [Water effects](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/examples/water.fx.json): Cel-shaded water from shape layers: a geyser, a whip, a ring breaking into drops, a popping dome and a curling wave, with lit and shade bands, tapered streams and blob drops.
- [Fluid effects](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/examples/campfire.fluid.json): A simulated campfire; sixteen more presets in examples/*.fluid.json (smoke puff, explosion, steam vent, magic swirl, torch, splash, waterfall, drip, bubbling potion, honey, slime, snow off a roof, dam break, dust wave, bursting slime, honey let-go). Liquids may be viscous (honey, tar) or have a yield stress (mud, slime), and an obstacle with surface: "smooth" lets them slide down a drawn slope instead of catching on its pixel steps. Compile with pixelbolt compile or MCP pixel_compile, or run one live in a web page with createLiveFluid (docs/art-workflow.md#live-fluids); schema: fluid.schema.json; guide: docs/art-workflow.md#fluid-effects.
- [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.