Skip to content
Back to search

pixelbolt

MarketplaceWorks with Claude CodeGitHub

Pixelbolt for Claude Code: the pixelbolt MCP server and the pixel art skill. It runs this repository's own bin/pixelbolt.js, so it needs Node.js 20 or later and nothing else.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026. Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/skulitom/Pixelbolt with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/skulitom/Pixelbolt'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/skulitom--pixelbolt/badge.svg)](/listings/skulitom--pixelbolt)

HTML

<a href="/listings/skulitom--pixelbolt"><img src="/api/listings/skulitom--pixelbolt/badge.svg" alt="findsafeskills safety rating" /></a>

Install

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 17 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "pixelbolt",
  3. "owner": {
  4. "name": "skulitom",
  5. "url": "https://github.com/skulitom"
  6. },
  7. "description": "Pixelbolt for Claude Code: the pixelbolt MCP server and the pixel art skill. It runs this repository's own bin/pixelbolt.js, so it needs Node.js 20 or later and nothing else.",
  8. "plugins": [
  9. {
  10. "name": "pixelbolt",
  11. "source": "./",
  12. "description": "Pixel art and sprite animation for agents: sprites, sprite sheets, tiles, icons, effects and short animations, exported as PNG, GIF, APNG or video frames.",
  13. "category": "design",
  14. "tags": ["pixel-art", "sprites", "sprite-sheet", "gamedev"]
  15. }
  16. ]
  17. }
README.md · README · 563 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Pixelbolt
  2. <img src="https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/gallery/library.gif" width="100%" alt="A library drawn with Pixelbolt: books circle the chandelier, a lectern book turns its page and a grey tabby sleeps on a shelf">
  3. [<img src="https://skulitom.github.io/Pixelbolt/gallery/montage.gif" alt="Eight looping effects made with Pixelbolt: a campfire, a torch, a steam vent, a bubbling potion, pouring honey, a drip, a plasma globe and a boiling pot">](https://skulitom.github.io/Pixelbolt/gallery/)
  4. **[The gallery](https://skulitom.github.io/Pixelbolt/gallery/): 66 pixel art effects, sprites and scenes from Pixelbolt 0.11.0, all playing, each one click from its recipe in the playground.**
  5. Give Claude Code the pixel art skill in one line (Node.js 20 or newer):
  6. ```sh
  7. npx -y pixelbolt@latest skill install
  8. ```
  9. For Codex, Cursor and the other agents the open [skills CLI](https://skills.sh) supports: `npx skills add skulitom/Pixelbolt`. It copies the skill file alone, which then runs Pixelbolt through npx. The CLI reports installs to the skills.sh leaderboard unless `DISABLE_TELEMETRY=1` is set. The skills CLI needs Node.js 22.20 or newer.
  10. **Pixel art and sprite animation that your AI agent can make, check and fix.** Pixelbolt turns an editable JSON recipe into sprites, tiles, icons, effects and short animations, and exports them as PNG sprite sheets, texture atlases, animated PNGs, GIFs and frames for a video editor. Agents drive it through a local MCP server or the command line; you can open, play and edit the same recipe in a local browser studio.
  11. [Try it in your browser](https://skulitom.github.io/Pixelbolt/playground/): render, export and share recipes with nothing installed.
  12. [Poke the pixels](https://skulitom.github.io/Pixelbolt/playground/fluids/): blow on a live pixel-art campfire, pour honey and slime, then save a GIF or share a link that replays exactly what you did.
  13. [Effect guides](https://skulitom.github.io/Pixelbolt/guides/): fire, explosions, smoke and steam, water, slime and honey, and magic, each with recipes that open in the playground. Using Unreal Engine? [Import the sheets into Paper2D, with flipbooks](https://skulitom.github.io/Pixelbolt/guides/unreal-paper2d-sprite-sheets/) (tested in 5.8.4). Need ground tiles? [Free autotile tile sets for Godot 4 and Tiled](https://skulitom.github.io/Pixelbolt/guides/tileset-generator-godot-tiled/), drawn from a terrain description (tested in Godot 4.7.2 and Tiled 1.12.2). Just want files? [Six free pixel art waterfall sprite sheets](https://skulitom.github.io/Pixelbolt/guides/pixel-art-waterfall-animation/): one simulated waterfall in stone, lava, slime and moonlit, with Godot 4 files.
  14. [Neon Voyage](https://skulitom.github.io/NeonRocketGame/): a free browser game made with Pixelbolt. Every sprite, effect and letter is a [recipe](https://github.com/skulitom/NeonRocketGame/tree/main/art), and the rocket's exhaust is a live fluid simulation that bends as you steer.
  15. English · [简体中文](https://github.com/skulitom/Pixelbolt/blob/main/README.zh-CN.md) · [日本語](https://github.com/skulitom/Pixelbolt/blob/main/README.ja.md) · [한국어](https://github.com/skulitom/Pixelbolt/blob/main/README.ko.md) · [Español](https://github.com/skulitom/Pixelbolt/blob/main/README.es.md) · [Português](https://github.com/skulitom/Pixelbolt/blob/main/README.pt-BR.md) · [Русский](https://github.com/skulitom/Pixelbolt/blob/main/README.ru.md)
  16. [![Tests](https://github.com/skulitom/Pixelbolt/actions/workflows/test.yml/badge.svg)](https://github.com/skulitom/Pixelbolt/actions/workflows/test.yml)
  17. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  18. [![Node.js: 20+](https://img.shields.io/badge/node.js-20%2B-43853d.svg)](package.json)
  19. ![A campfire simulated by Pixelbolt's fluid compiler: flames lick up from the logs, embers drift up and smoke curls away](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/campfire.gif) ![An explosion simulated by Pixelbolt: a white flash grows into an orange fireball that rises, cools and curls into smoke](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/explosion.gif)
  20. Fire, smoke, steam, explosions, magic, water, honey, slime and sand come from a real fluid simulation that runs on your own CPU in well under a second and bakes every frame into palette pixels you can edit, with seamless loops ([fluid effects](#fluid-effects)).
  21. - **Who it's for:** game developers, game-jam teams and web or video makers who want an agent such as Claude, Codex or Cursor to draw and revise their pixel art, and people building agents that need exact, repeatable images.
  22. - **Use it when** you want small 2D game assets that stay editable as text: the agent reads every pixel back, fixes one pixel or one frame without redrawing the rest, and the same recipe renders the same image every time.
  23. - **Don't use it for** painted or photographic images, large animations (an animation frame is at most 1024 pixels a side and 262,144 pixels, such as 320 × 180, 640 × 360 or 512 × 512, and a project at most 256 frames and 4,194,304 pixels in all, so 72 frames of 320 × 180; a single still, such as a 1920 × 1080 backdrop or mural, may be up to 4096 pixels a side within that total), generating art with an image model, or editing GIFs and Aseprite files (it imports PNG only, at up to 8 bits per channel).
  24. - **Compared with** aseprite-mcp, pixel-mcp, pixscii, pixelart-mcp, pixelforge-mcp and SpriteCook, with Pixelbolt's measured runs, the others read from their code and docs, and when to choose each one instead: [Pixel art and sprite tools for AI agents: 7 MCP servers compared](https://skulitom.github.io/Pixelbolt/compare/pixel-art-mcp-servers-for-ai-agents/) (checked 17 October 2026; refreshed 11 November with 0.15.0 measured). For fire, smoke, explosion, water and spell effects, with Pixel FX Designer, SpriteMancer, Fluid FX, Pixel Composer, PHOSPHOR, BlastFX, Pixel VFX Forge, Codixel and pixelfx: [Pixel FX Designer alternatives: 10 tools compared](https://skulitom.github.io/Pixelbolt/compare/pixel-fx-designer-alternatives/) (checked 19 October 2026; Codixel added and Pixelbolt re-measured on 0.17.0 on 15 November; pixelfx added and run on 17 November). Measured with and without Pixelbolt on Claude Haiku, Sonnet and Opus 5.5, in a benchmark we planned in advance: [Does a pixel-art MCP server help Claude?](https://skulitom.github.io/Pixelbolt/compare/claude-pixel-art-with-and-without-pixelbolt/) (run 23 October to 3 November 2026; on 0.11.0, 32 of 36 runs passed every check with Pixelbolt and 31 without, blind pairs 18 to 13 with one by default, p = 0.47, at 1.47 times the cost, short of our rule for saying it helps; animations and effects, which 0.11.0 was built for, 9 of 15 pairs, p = 0.61, and a same-day repeat would have failed that bar). For ring-escape, bouncing-ball and territory battle Shorts, with BallTok, Satisfying Labs, BounceMatch, ReelBall, BallSimulator, BallEngine, Korpi, WaveSpeed's free maker and physim: [Ring escape and territory battle Shorts with a free, open-source simulator](https://skulitom.github.io/Pixelbolt/compare/ring-escape-and-territory-battle-shorts/) (checked 9 November 2026; two clips with their recipes and one command each).
  25. **Try it.** You need Node.js 20 or newer; there is nothing else to install, no API key and no network service:
  26. ```sh
  27. git clone https://github.com/skulitom/Pixelbolt.git
  28. cd Pixelbolt
  29. node bin/pixelbolt.js preview --open
  30. ```
  31. No Node.js? [Download Pixelbolt Studio](https://github.com/skulitom/Pixelbolt/releases/latest): a portable build for Windows, macOS and Linux that brings its own Node.js runtime. Unpack it and start the studio; nothing is installed ([portable builds](#pixelbolt-studio-portable-builds)).
  32. **Give it to your agent.** For Claude Code, one line installs the pixel art skill, with nothing to clone and no MCP server (Pixelbolt 0.9.2 or later):
  33. ```sh
  34. npx -y pixelbolt@latest skill install
  35. ```
  36. It writes `~/.claude/skills/pixelbolt-pixel-art/` (`--project` writes the current folder's `.claude/skills/` instead, `--dir` any skills folder), runs every command it names through `npx -y pixelbolt@<that version>`, and never replaces a copy you have changed unless you add `--force`. For Pixelbolt's MCP tools too, install the [Claude Code plugin](#connect-an-agent-through-mcp) instead: it brings the server and the same skill together. In Claude Desktop, download [`pixelbolt.mcpb`](https://github.com/skulitom/Pixelbolt/releases/latest/download/pixelbolt.mcpb) from the latest release and open it (or install it from file under Settings → Extensions), choose a workspace folder for recipes and artwork, then ask the agent to call `pixel_help`. For Codex, Cursor and other MCP clients, see [Connect an agent through MCP](#connect-an-agent-through-mcp). Pixelbolt is in the official MCP Registry as `io.github.skulitom/pixelbolt`.
  37. Pixelbolt was called PixelForge until 0.8.0. The `pixelforge` command still works as an alias, and recipe files keep their `pixelforge-*` format tags, so existing files and agent setups keep working.
  38. [Gallery](#gallery) · [Fluid effects](#fluid-effects) · [Quick start](#start) · [Agent setup](#for-agents) · [MCP server](#connect-an-agent-through-mcp) · [Portable builds](#pixelbolt-studio-portable-builds) · [Recipe reference](docs/agent-guide.md) · [Contributing](CONTRIBUTING.md) · [Sibling tools](#sibling-tools)
  39. ## How it works
  40. Write a JSON recipe with palettes, text grids, reusable symbols and drawing operations. Get transparent PNGs, sprite sheets, animated PNGs, GIFs for sharing, numbered frames for video editors, and the metadata and player needed to use them. Inspect and edit the recipe in a local browser studio.
  41. 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.
  42. ## Figures in motion
  43. Author limbs as bones, bodies as masses, and faces or props as grids. Relative joints and two-bone reach keep attachments together; idle, walk, run, jump, attack and hurt templates expand into editable poses. Review planted feet, ground contact and loop joins in the CLI, MCP or studio. Small grid parts (boots, hands, blades) turn best as hand-drawn `views`; `--draft-views` drafts them by pixel-art rules for you to correct and paste. The output uses the existing sprite player.
  44. ```sh
  45. node bin/pixelbolt.js preview character.poses.json
  46. node bin/pixelbolt.js compile character.poses.json --expand --out character-edit.poses.json
  47. node bin/pixelbolt.js compile character.poses.json --draft-views boot:15,345,hand:45 --preview drafts.png
  48. node bin/pixelbolt.js inspect character.poses.json --motion run --speed 48
  49. ```
  50. [Pose and motion reference](docs/art-workflow.md#structural-limbs-and-bodies)
  51. ## Baked wave effects
  52. Looping interference and portal interiors combine waves before colouring them, leaving cancellation gaps between bright bands. Two editable presets bake to ordinary sprite frames and appear in the studio's sample list. The game only plays the exported animation.
  53. ![Paired cyan waves and a violet portal in a Tidewatch game scene](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/waves/scene.gif)
  54. ```sh
  55. node bin/pixelbolt.js preview examples/portal.wave.json --open
  56. node bin/pixelbolt.js compile examples/portal.wave.json --out output/portal.json
  57. node bin/pixelbolt.js render output/portal.json --out output/portal-assets
  58. ```
  59. [Wave controls and limits](docs/wave-effects.md) · [Scene comparison and review](https://github.com/skulitom/Pixelbolt/blob/main/showcase/waves/README.md). Loops only; masks shape the artwork without simulating reflection or collision.
  60. ## Gallery
  61. An AI agent drew these with Pixelbolt. Its scripts write the recipes, particle sources and scenes; Pixelbolt renders every sprite to a transparent sheet with an atlas, plays each 240×135 room as a scene and writes the GIFs. They are shown at 3×.
  62. ![An observatory: a porthole onto a ringed planet, a telescope, an armillary with a blooming crystal and a cat asleep on the window seat](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/gallery/observatory.gif)
  63. ![A workshop: a half-built brass automaton, a gear clock, glass coils that arc and a clockwork mouse](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/gallery/workshop.gif)
  64. ![Eight potions, each popping its cork: green, red, blue, purple, orange, frost, shadow and rainbow](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/gallery/potions.gif)
  65. ![Four bell jars: a sprouting bloom, glowcap mushrooms, a snapping flytrap and a succulent](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/gallery/bell-jars.gif)
  66. ![Three clockwork familiars: a brass owl, a koi in its bowl and a crystal moth over a lantern](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/gallery/familiars.gif)
  67. [Two more rooms and how these were made](https://github.com/skulitom/Pixelbolt/blob/main/showcase/gallery/README.md)
  68. ## Fluid effects
  69. A `pixelforge-fluid` source runs a small, deterministic fluid simulation and compiles it into an ordinary recipe of palette grids: gases with buoyancy, swirling vorticity, cooling and dissipation, and liquids as FLIP particles on the same grid, thin as water, thick as honey (a stream that never breaks, a mound that slowly sinks) or firm as slime (a blob that squashes, springs back and holds its shape). Look layers map density, temperature, speed and depth onto your palette ramps through ordered dither, so no colour outside the palette can appear, and looping effects close their seam. Each preset below compiles in well under a second on a laptop CPU, with no GPU and no model calls. Shown at 4×.
  70. ![A campfire: flames lick up from crossed logs, embers drift up and smoke curls away](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/campfire.gif) ![A torch: a small flame flickers on a wooden handle with a metal cup](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/torch.gif) ![Steam puffs rhythmically from a pipe, rises, curls and thins](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/steam-vent.gif) ![A magic swirl: two glowing sources orbit and leave purple mana that spirals](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/magic-swirl.gif)
  71. ![A wall torch: a flame tapers above an iron cup clamped to a wall plate, with embers, thin see-through smoke and a soft light on the wall](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/wall-torch.gif) ![Chimney smoke: see-through smoke curls up from a clay pot on a brick chimney and thins out](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/chimney-smoke.gif) ![A campfire in a ring of stones: a broad flame rises behind crossed logs, embers drift up and firelight flickers on the ground](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/campfire-stones.gif)
  72. ![A fireball explosion: a flash swells into a ball of flame that throws sparks and burns out from its edge inward](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/fireball-explosion.gif) ![Cannon smoke: a muzzle flash, then a thick cloud billows out of the barrel, lifts and thins away](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/cannon-smoke.gif)
  73. ![An explosion: a white flash grows into an orange fireball that rises, cools and curls into smoke while sparks fly](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/explosion.gif) ![A cartoon smoke puff, outlined and lit from the upper left, billows out in lobes and thins away](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/smoke-puff.gif)
  74. ![A waterfall: water pours off a mossy ledge in a foaming arc, splashes into a basin and spills over its lip](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/waterfall.gif) ![A drop falls from a stalactite and splashes into a small pool](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/drip.gif) ![A green potion bubbles in a round flask: the surface heaves and bubbles rise and pop](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/potion.gif) ![A drop falls into a pool, throws up a crown and spray, and the waves settle](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/splash.gif)
  75. ![Glossy honey runs off a dipper into a jar as one unbroken rope that folds into a mound on the calm surface](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/honey.gif) ![A blob of green slime drops, squashes flat, springs up tall, wobbles and settles into a dome that holds its shape](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/slime.gif)
  76. Obstacles can be smooth, so thick liquids slide down drawn slopes, or move and vanish on cue; dust can be thrown; a liquid can burst in mid-air or change on a frame you choose; bubbles behave like air, and air pockets keep theirs:
  77. ![Wet snow slides off a house's roof as one slab, pours over the eave and settles in a drift against the wall](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/roof-snow.gif) ![A plank dam lifts and the water behind it bursts out as a wave, rolls over a rock, splashes off the far wall and settles level](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/dam-break.gif) ![A stone drops onto the ground and throws a wave of dust out both ways that billows, slows and thins away](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/dust-wave.gif) ![A ball of green slime bursts in mid-air into chunks that fly out, land and wobble into mounds](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/slime-burst.gif) ![Stiff honey clings under a wooden spoon, then thins, stretches, lets go and drops into a bowl of honey](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/honey-drop.gif) ![An aquarium: bubbles rise from an air stone and run up under a rock ledge, and a filter's stream plunges in and drives bubbles into the water](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/aquarium.gif) ![A honey dipper is lifted out of a jar; the honey clings to it, draws up into a peak and joins it by a thin string that snaps](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/honey-dipper.gif) ![A bottle upside down over a glass glugs as it pours: it holds its water back, a big bubble pushes up its neck, and it pours again](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/glug.gif)
  78. Gases can carry electricity: electrodes break the gas down into branching plasma that conducts, glows, heats the air and fades:
  79. ![A Jacob's ladder: an arc strikes where two rods are closest, climbs on its own hot air, stretches wide at the top and goes out](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/jacobs-ladder.gif) ![Lightning: a branching leader steps down from a cloud, the return stroke flashes white and fades, and a second stroke runs down the same channel](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/lightning.gif) ![A plasma globe: violet filaments run from the central ball to the glass, flicker and wander](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/plasma-globe.gif)
  80. Liquids can carry heat and change phase: ice melts and freezes, water boils into steam that beads back as dew, frost grows on cold glass and dry ice turns straight into fog:
  81. ![An ice cube on a hot griddle melts and settles into a puddle that steams](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/ice-melt.gif) ![A pond freezes in from its snowy shore until the ice closes over the middle](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/pond-freeze.gif) ![A lidded pot boils: bubbles rise, steam beads under the cold lid and drips back](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/boiling-pot.gif) ![Frost creeps across a cold window from its frame](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/frost-window.gif) ![Dry ice on a table turns into heavy fog that pours off the edge onto the floor](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/dry-ice.gif)
  82. ```sh
  83. node bin/pixelbolt.js compile examples/campfire.fluid.json --out output/campfire.json
  84. node bin/pixelbolt.js gif output/campfire.json --scale 4 --out output/campfire.gif
  85. ```
  86. Liquids can be grains: sand holds its slope at any height, lands dead, avalanches down a face steeper than its repose and comes to rest:
  87. ![An hourglass: sand drains through the neck, the top caving into a crater while a heap builds in the bottom bulb](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/hourglass.gif) ![A board lifts and a bin of sand slumps into a ramp and stops](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/sand-gate.gif) ![A blade pushes a layer of sand along the ground into a heap that spills over it](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/sand-plough.gif)
  88. Bodies share a fluid: a crate dropped into a pool splashes and floats by its density while a stone sinks, a crate on sand rides it down when it slumps, a turning paddle stirs a pool, a red-hot stone boils one away and sand poured on a plank tips it:
  89. ![A crate, a ball and a stone drop into a pool: each throws a splash, the crate floats high and flat, the ball half out, the stone sinks](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/crate-splash.gif) ![A board lifts, a bin of sand slumps into a ramp and carries the crate standing on it down the slope](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/sand-slide.gif) ![A paddle cross turns in a pool for ever and stirs it while a duck and a crate ride the current](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/water-wheel.gif) ![A red-hot stone drops into a shallow pool and boils away the water round it in a burst of steam, then sits dry in the hollow](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/hot-stone.gif) ![Sand pours onto one end of a plank balanced on a peg, tips it down and slides off into a heap](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/fluid/plank-tip.gif)
  90. The forty-two presets are in [examples/](examples/) (`*.fluid.json`); agents compile them with MCP `pixel_compile` and read the format with `pixel_help` topic `fluid`. In the studio, **Fluid lab** (`/fluid.html`) runs the same compiler in your browser: pick a preset, move a few sliders and download the GIF, sprite sheet, recipe or edited source. **Effects lab** (`/effects.html`) does the same for the `pixelforge-fx` spell and particle presets: pick one of a source's effects (turned copies included), change its strength, speed and seed, and download. The [fluid effects guide](docs/art-workflow.md#fluid-effects) covers emitters, sparks, obstacles, looks, loops, thick fluids (viscosity, yield stress, adhesion), sticky liquids that move with an obstacle and stretch into strings, and electricity. In a web page, `createLiveFluid` runs the same simulation live, a frame at a time, and takes pushes, puffs and emitter boosts from the pointer ([live fluids](docs/art-workflow.md#live-fluids)).
  91. ## Rigid bodies
  92. A `pixelforge-bodies` source drops balls, boxes, polygons and spinning hoops into a canvas with gravity, walls and drawn pixel obstacles: they bounce, slide, roll, stack, knock each other about and come to rest, baked into palette grids like every other compiler. A body can start asleep until it is hit, change colour at each hit, trail behind it or be drawn as a sprite. Joints connect bodies into ragdolls, ropes sag and break, and cloth pins to bodies, ripples in the wind, drapes and tears. On a territory of team-owned cells, each team's balls claim the other side's cells they hit, with pickups that split, grow, speed up, warp or pull, a live score drawn over the board, and long matches written straight to video frames. A strike gives a power to whatever a named body touches, so a sword turning about its hilt can split every ball it hits until the crowd fills its ring. Shown at 4×.
  93. ![A ball bounces inside a ring of blocks, changing colour at every hit and knocking blocks loose until it shoves a gap open and escapes](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/bodies/ring-escape.gif) ![One pixel thrown into a small room bounces off the walls, a ledge and a staircase and rolls to rest](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/bodies/bouncing-pixel.gif) ![Three balls in a spinning hoop with a gap find the gap one by one and fall onto the floor](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/bodies/spinning-hoop.gif) ![A heavy ball thrown into a pyramid of crates knocks it apart; the crates tumble and settle](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/bodies/crate-topple.gif) ![Tide against ember: navy and amber halves of a board, each side's balls bouncing off the other's cells and claiming them, a pocket carved by a warped ball, a score bar and counts underneath](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/bodies/territory.gif) ![A sword turns about its hilt inside a ring with a white swish behind it, cutting through every ball it touches and leaving the pieces in its wake, until hundreds fill the ring and each turn washes a new colour round behind the blade; then the ring vanishes and they burst out](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/bodies/blade-bloom.gif) ![A heavy iron ball is thrown through a pane of glass into a pyramid of crates: the glass shatters, crates burst into planks that carry their boards and grain, and the debris settles in a heap](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/bodies/crate-smash.gif)
  94. Joints, ropes and cloth: a rope bridge sags under a crate, a wrecking ball swings on a rope, a lantern swings on its chain and settles, a ragdoll falls apart at its hinges, a flag waves on its pole and a tattered banner sways on its rod, both in a loop, and a cape trails behind a walking figure. They are `rope-bridge`, `wrecking-ball`, `lantern`, `ragdoll`, `flag`, `banner` and `cape` in [examples/](examples/).
  95. ![A rope bridge sags under a falling crate](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/bodies/rope-bridge.gif) ![A red flag waves in the wind](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/bodies/flag.gif) ![A caped figure walks as the cape trails behind](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/bodies/cape.gif)
  96. The fourteen presets are in [examples/](examples/) (`*.bodies.json`); agents compile them with MCP `pixel_compile` and read the format with `pixel_help` topic `bodies`. The [rigid bodies guide](docs/art-workflow.md#rigid-bodies) covers shapes, materials, sleeping, pivots, obstacles, joints, ropes, cloth, territories, power-ups and strikes, breaking, the score display, long matches, looks and the metadata. In a fluid source, a liquid takes the same `bodies`: they splash into water and float by their density, and land on sand and ride it when it slides ([above](#fluid-effects)).
  97. ## Crystal growth
  98. A `pixelforge-crystal` source grows crystals from seeds and lets them come to rest: quartz and amethyst points, pyrite cubes and octahedra drawn as small solids lit by one light, each face one band of its colour ramp, alone, fanned into clusters or lining a geode; and six-armed snowflakes grown as dendrites, whose side branches meet in chevrons a pixel apart. Each crystal starts as a bright seed, grows, and glints along its lit edge once grown. Shown at 4×.
  99. ![Amethyst points grow inward from the agate lining of a geode broken open, each catching the light as it finishes](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/crystals/geode.gif) ![Clear quartz points fan up out of a rock, the tall one first, then its neighbours, then the small ones in front](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/crystals/quartz-cluster.gif) ![Brassy isometric pyrite cubes and two octahedra grow out of a dark rock](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/crystals/pyrite.gif) ![Three snowflakes grow from hexagonal seeds: a broad stellar dendrite with twigs, a small sectored plate and a fern-like flake on its side](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/crystals/snowflakes.gif)
  100. The four presets are in [examples/](examples/) (`*.crystal.json`); agents compile them with MCP `pixel_compile` and read the format with `pixel_help` topic `crystal`. The [crystal growth guide](docs/art-workflow.md#crystal-growth) covers looks, habits, lighting, clusters, snowflakes and timing.
  101. ## Falling sand
  102. A `pixelforge-powder` source is a falling-sand sandbox: every pixel holds sand, water, stone, wood, fire, smoke, steam, oil, lava, ice, ash, moss or a material of your own, and the grid steps 60 times a second. Falls speed up and splash, pools level and rest, heat boils, melts and lights things, burnt-through structures collapse or, with `pieces: "tumble"`, topple and tumble as rigid bodies, and moving air carries smoke in plumes. The same source runs live in a game with `createLivePowder` (`pixelbolt/powder`, pointer strokes that replay exactly) and compiles to an ordinary recipe of one-shot clips.
  103. ![A hut on a pier burns, drops into its pool and floats there burning while lava pours off the far cliff into the water](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/powder/hut-fire.gif) ![Lava burns through a moss plug and pours into a pool, crusting to stone in clouds of steam](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/showcase/powder/lava-falls.gif)
  104. The five presets are in [examples/](examples/) (`*.powder.json`); agents compile them with MCP `pixel_compile` and read the format with `pixel_help` topic `powder`. In the studio, **Powder lab** (`/powder.html`) runs the sandbox live in your browser: paint any material, heat, cool, blow and blast with the pointer, and copy a link that replays every stroke to the same pixels. The [falling sand guide](docs/art-workflow.md#falling-sand) covers the starter table, materials, heat, reactions, air, inputs, clips and the live runner.
  105. ## Start
  106. ```sh
  107. git clone https://github.com/skulitom/Pixelbolt.git
  108. cd Pixelbolt
  109. node bin/pixelbolt.js preview
  110. ```
  111. Open **http://127.0.0.1:4747**, or add `--open` to have your default browser opened for you. If that port is in use, a free one is taken and printed instead; `--port N` insists on one port and fails when it is busy. `preview hero.pixel.json` starts with your own recipe. 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, whole-number zoom (the scroll wheel zooms at the pointer, dragging pans, and + − 0 and F zoom, fit and go full screen), a pixel grid, onion skinning, palette inspection, source save/open, a GIF download of the current animation, numbered frames for a video editor, recovery of unsaved edits and live error messages. All assets and fonts are local.
  112. ![Pixelbolt's local studio showing the forest spirit sprite, animation frames, editable JSON recipe and palette](docs/images/studio.png)
  113. Or generate an asset without opening a browser:
  114. ```sh
  115. node bin/pixelbolt.js init hero.pixel.json
  116. node bin/pixelbolt.js validate hero.pixel.json
  117. node bin/pixelbolt.js inspect hero.pixel.json --out hero-frames.png
  118. node bin/pixelbolt.js render hero.pixel.json --out output/hero
  119. ```
  120. `inspect` saves a contact sheet of every frame and lists each frame's timing (`--animation walk --every 100` draws a cell per 100 ms of playback, so pacing shows). Add `--grid` to read frames back as palette-key text; `--animation`, `--frames` (names or patterns such as `'flash-*'`) and `--region` narrow the view, and `--step 2 --offset 1` keeps every second cell from the second, so a strobe's A and B frames can be read apart. `validate hero.pixel.json --fps 30` also lists the durations that are not whole video frames at that rate and what a video sequence would do to each animation. `patch hero.pixel.json --changes fix.json` previews targeted edits and reports every pixel they change; add `--out` to save the new recipe. `gif hero.pixel.json --out hero.gif` saves one animation as a GIF for sharing. Command results except help and the preview server are 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. A forced export over an earlier export of the same recipe or sequence also removes the frames it no longer has and lists them as `removed`; a sprite export removes only frame and animation PNGs its own earlier atlas lists and no other atlas in the folder does, so another sprite's frames and PNGs you add there aren't deleted. No command writes over a file it reads, even with `--force` and through a link or another spelling of its path; `patch` may save over the recipe it edits. No export writes over its own recipe or the files it references. You can optionally run `npm link` for the `pixelbolt` command. No `npm install` is needed.
  121. `pixelbolt share <recipe.json|->` prints a playground link to the source, including wave, crystal, falling-sand and rigid-body sources, which the playground compiles and keeps editable; `render` and `scene` accept `--embed-recipe` (recipes up to 1 MiB, so every PNG still opens in Pillow), recovered with `import image.png --embedded --out recipe.json`.
  122. Both carry the resolved recipe text and engine version: the link in its URL fragment, which browsers do not send to a server, and the PNG in a compressed recipe chunk.
  123. ## Diorama: a 3/4 dungeon room
  124. An original 3/4 top-down dungeon room in the style of procedurally generated "floating diorama" games: 8-pixel tiles, wall caps with front faces, a sunken pool fed by a waterfall, moss, props, torches and a hero whose strike breaks a pot. The room is one recipe whose `tilemap` operation places walls, faces, cliffs, water and worn bricks by neighbour rules; moss is seeded value noise on the floor colour; shadows and torchlight move colours along palette ramps, so the scene keeps its 31 colours lit or re-themed.
  125. ```sh
  126. node bin/pixelbolt.js preview showcase/diorama/art/room.scene.json
  127. ```
  128. ![The diorama by torchlight: torches and candles flicker, and the room flashes where the hero's strike breaks a pot](https://raw.githubusercontent.com/skulitom/Pixelbolt/main/docs/images/diorama/room-night.gif)
  129. By night, each torch and candle light follows its placement and flickers on its own seed, and a light at the pot flashes on the strike cue: [moving scene lights](docs/art-workflow.md#aligned-material-passes), still in exactly the palette's colours.
  130. [Study details and images](https://github.com/skulitom/Pixelbolt/blob/main/showcase/diorama/README.md) · [Feasibility report: what the style asked of Pixelbolt](https://github.com/skulitom/Pixelbolt/blob/main/docs/reports/diorama-feasibility-2026-10-07.md)
  131. ## Art quality workflow
  132. The [art workflow](docs/art-workflow.md) covers silhouette, value and native-size review, animation-aware onion skins, masked regional corrections, authored parts and attachments, guarded rebuild overlays, scenes, PNG interchange and aligned normal/emissive passes. Passing checks are not a verdict on the art: look at every frame, at native size and in playback.
  133. ```sh
  134. node bin/pixelbolt.js inspect examples/forest-spirit.json --animation idle --view onion --native --diagnostics
  135. node bin/pixelbolt.js preview examples/forest-spirit-lit.scene.json
  136. ```
  137. ## For agents
  138. Use Pixelbolt 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.
  139. | Entry point | Purpose |
  140. | --- | --- |
  141. | [llms.txt](https://github.com/skulitom/Pixelbolt/blob/main/llms.txt) | Compact documentation index with direct links for agents |
  142. | [Pixel art skill](skills/pixel-art/SKILL.md) | Reusable authoring and visual inspection workflow; `npx -y pixelbolt@latest skill install` installs it on its own |
  143. | [Authoring guide](docs/agent-guide.md) | Recipe fields, drawing operations and limits |
  144. | [JSON Schema](schema.json) | Machine-readable recipe structure |
  145. | [Examples](examples/) | Complete forest spirit, campfire, coin and shrine recipes, an isometric tile set and the scene that lays it out, a caption with pixel text, a rotated sword swing, a rigged hero with walk, run, jump and attack templates, the same hero swinging a sword that turns with the arm, a red fox that walks, trots and gallops on four legs, a hermit crab in a treasure chest posed from drawn parts with no rig, a particle effects source, fifteen spell effects (slash hit, fire explosion, a looping fireball in eight directions, lightning strike, healing circle, a swirling vortex, a falling meteor, a shield bubble, a portal that lights its stone arch, a frost nova, a teleport-in, a coin sparkle, an electric arc that lights its prongs, an ice crystal with a pulse of cold light, a forest waterfall), a teleport and a spirit aura on the rigged hero, a sword smear that follows the swing's blade tip, a simulated explosion under spell-shape flashes, a spell library (fire, ice, lightning, water, poison, holy and shadow, each a projectile in eight directions, an impact, an area effect and a buff), five cel-shaded water effects, 42 fluid presets, fourteen rigid-body scenes (crates that topple or smash, a blade, a territory match, ropes, a ragdoll and cloth) and four crystal growths (a geode, a quartz cluster, pyrite and snowflakes) |
  146. | [AGENTS.md](https://github.com/skulitom/Pixelbolt/blob/main/AGENTS.md) | Instructions for agents contributing to the toolkit |
  147. Start with the authoring guide or MCP's `pixel_help`. Write a recipe, validate it, inspect every frame with `pixel_inspect` or `pixelbolt inspect`, revise with targeted patches, then render to a fresh output directory. Validation checks the format; image inspection checks the art.
  148. ## A tiny animation
  149. ```json
  150. {
  151. "version": 1,
  152. "name": "slime",
  153. "width": 8,
  154. "height": 8,
  155. "palette": { "g": "#72b58d", "e": "#20383f" },
  156. "frames": [
  157. {
  158. "name": "rest",
  159. "duration": 180,
  160. "ops": [{ "op": "grid", "x": 1, "y": 3,
  161. "rows": [".gggg.", "ggeegg", "gggggg", ".gggg."] }]
  162. },
  163. { "name": "up", "from": "rest", "translate": [0, -1], "duration": 180 }
  164. ],
  165. "animations": { "bounce": { "frames": ["rest", "up"] } }
  166. }
  167. ```
  168. 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.
  169. ## Export bundle
  170. | File | Use |
  171. | --- | --- |
  172. | `name.png` | RGBA PNG sprite sheet, with configurable columns, padding and integer scale, or packed by visible bounds with `sheet.trim` |
  173. | `name.atlas.json` | TexturePacker-style JSON hash: rectangles, trim offsets, source sizes, pivots/anchors, named points, frame durations, named animations and Aseprite-style frame tags. Stills and a still tile set (below) list their frames only, with no `animations` and no `meta.frameTags` |
  174. | `name.tres` | Godot 4 `SpriteFrames` for `AnimatedSprite2D`: one atlas texture per frame (trimmed frames keep their place on the canvas) and every animation with its loop and exact frame times; keep it next to `name.png`. Not for stills or a still tile set |
  175. | `name.tileset.tres` | Only for a tile set (an autotile set, or frames with `tile`): a Godot 4 `TileSet` for `TileMapLayer` with a terrain per set (blob, cardinal or corner, or a corner set of layered terrains whose transitions Godot paints), so Godot's terrain painter picks the tile Pixelbolt's tilemap would, plus each tile's probability and collision; keep it next to `name.png`. A tile set without animations of its own skips the SpriteFrames, APNGs, CSS and player |
  176. | `name.tsx` | Only for a tile set: a [Tiled](https://www.mapeditor.org) tileset over `name.png` with a Wang set per terrain for the Terrain Brush (mixed for blob, edge for cardinal, corner for corner and layered sets), each tile's probability, collision objects and animation; keep it next to `name.png` |
  177. | `frames/*.png` | Each frame as a transparent PNG |
  178. | `animations/*.png` | APNG for each animation, retaining transparency, frame timing and loop behavior. Not for stills or a still tile set |
  179. | `name.css` | CSS animation classes; supports multi-row sheets and unequal frame durations. Not for stills or a still tile set |
  180. | `player.js` | Small, dependency-free Canvas player with play, pause, resume and named animations, plus `loadSpriteSheet`, `frameAt` and `drawFrame` for games. Not for stills or a still tile set |
  181. | `name.pixel.json` | Editable source recipe |
  182. | `preview.html` | Standalone preview you can open directly in a browser (the sheet, for stills and a still tile set) |
  183. Stills are a recipe whose `"animations"` is `{}`: icons, UI states, a 9-slice panel. A still tile set is a tile set whose recipe leaves `animations` out. Neither plays anything, so the export writes only `name.png`, `name.atlas.json` (frames only), `frames/`, `name.pixel.json`, `preview.html` and `README.txt` (plus `name.tileset.tres` and `name.tsx` for a tile set), and no GIFs.
  184. APNG files use the `.png` extension intentionally. Recipes can share a palette file (`"palette": { "$ref": "palette.json" }`), recolor keys per frame for palette cycling or per layer for a flash that leaves the rest of the frame alone, copy rectangles from template symbols or earlier frames (with exact colour swaps), outline layers (outside, inside or both, with direction masks for rim lights and drop shadows), dither between colours with canvas-anchored Bayer, custom, seeded non-periodic noise or clumping value-noise patterns, shade along palette ramps (`ramps` and the `shade` operation) without leaving the palette, draw whole character maps with the `tilemap` operation (variants, weights and neighbour rules), and grow detail such as moss or cracks with seeded rewrite rules. They compile 47-tile blob or 16-tile cardinal autotile sets with `pixelbolt autotile`, drawn from template rows or from a terrain description (a seamless fill and each side's edge, outline, rim light, shadow and tufts), optionally with shape variants, and review every tile over a test map with seam warnings; see the [authoring guide](docs/agent-guide.md) and [art workflow](docs/art-workflow.md#autotile-templates).
  185. Several of these ideas come from [Pixel Composer](https://github.com/Ttanasart-pt/Pixel-Composer)'s node set, adapted to text recipes. Patches can propose De-Corner/De-Stray cleanup, and inspection diagnostics count per frame what it would change. Pose sources rotate parts by any angle into editable symbols, using RotSprite-style resampling that adds no colours, and tween eased in-betweens. Scene trajectories ease. A `pixelforge-fx` source compiles seeded particle emitters and spell shapes (slashes, shockwave rings, beams, lightning, magic circles, impact stars, fireballs, cel-shaded water streams and drops) into an ordinary recipe with `pixelbolt compile`, a `pixelforge-fluid` source does the same with a fluid simulation, and a `pixelforge-normals` source derives a lighting normal pass from any recipe: an editable recipe aligned frame for frame, for scene lighting and engine normal maps ([the spirit's](examples/forest-spirit.normals.json), lit in [a small night scene](examples/forest-spirit-lit.scene.json); [details](docs/art-workflow.md#generated-normal-passes)). See [the shrine](examples/shrine.json), [the swing](examples/swing.poses.json), [the effects](examples/effects.fx.json) and [a healing circle](examples/healing-circle.fx.json). Lossless PNG import is supported (RGB, RGBA, greyscale and indexed, up to 8 bits per channel, not interlaced), optionally with unscaled atlas timing metadata; see [interchange limits](docs/art-workflow.md#lossless-raster-return-path). GIF import, native Aseprite files and automatic quantization remain outside the current scope. Sources stay editable JSON.
  186. ### GIF for sharing
  187. APNG keeps full alpha and exact timing, but many chat, forum and store pages only animate GIFs and cannot scale pixels crisply. `pixelbolt gif` writes one animation as a GIF at the frames' own size; `--scale` (1-16) enlarges it by a whole number for pages that would show a small sprite tiny:
  188. ```sh
  189. node bin/pixelbolt.js gif hero.pixel.json --out hero.gif
  190. node bin/pixelbolt.js gif --preset campfire --size 32x32 --scale 8 --out campfire.gif --sheet campfire-frames.png
  191. node bin/pixelbolt.js gif hero.pixel.json --animation blink --scale 8 --background "#17191d" --out hero-blink.gif
  192. ```
  193. Colours are exact: nothing is quantized or dithered, and a frame that needs more than 256 colours is refused with an error instead of being approximated. GIF has no partial transparency, so pixels below 50% alpha become transparent and the rest opaque; `--background` (a palette name or opaque hex colour) blends every pixel onto one colour instead, which keeps soft shadows. Frame times are rounded to GIF's 10 ms steps with the remainder carried to the next frame, and raised to 20 ms where shorter. Transparent pixels stay clear in every viewer, including ffmpeg and Pillow, which fill a cleared frame with the background colour unless it names a transparent index (the notes report the rare frame with 256 colours of its own that has none to name). The JSON result's `notes` say which of these happened. The studio's **GIF** button downloads the current animation at the current zoom, and MCP `pixel_render` takes `"gif": {}` (the frames' own size) or `"gif": { "scale": 8 }`. Every render also reports a `check` of what it wrote; give `pixel_render` an `expect` (or `render` an `--expect`) with the size, frames, colours, background or loop the user asked for, and the check names each file that misses it and how to fix it. The export bundle itself is unchanged.
  194. `pixelbolt gif-frames` makes a GIF from a folder of numbered PNG frames, such as a `sequence` folder or frames a video or effects tool wrote, by the same rules:
  195. ```sh
  196. node bin/pixelbolt.js gif-frames shots/prism --fps 25 --out prism.gif
  197. node bin/pixelbolt.js gif-frames shots/prism --fps 30 --loops 3 --background "#101828" --prefix prism_ --out prism-3x.gif
  198. ```
  199. Files are read in number order (`prism_0001.png`, `prism_0002.png` …); gaps in the numbering, other PNGs in the folder and a folder holding two sequences (choose one with `--prefix`) are reported, never guessed around. Each frame keeps its exact colours: one with more than 256 is refused by name, and when the frames use different colours, each frame carries a colour table of its own, so a loop of 48 frames at 1080 × 1080 with about 120 colours per frame and 4,345 in all decodes back pixel for pixel, where a palette generator would shift some colours. Frame k starts at k × 1000 / fps ms rounded to GIF's centiseconds: 25 fps is 40 ms per frame, 30 fps alternates 30 and 40 ms and keeps the loop's length, and above 50 fps delays are raised to 20 ms, which the notes report with the new length. `--loops` is the number of plays, 0 (the default) for ever. Without transparency, each frame after the first stores only the rectangle that changed. The PNGs may be RGB, RGBA, greyscale or indexed with up to 8 bits per channel, all the same size; the loop may hold 134,217,728 pixels (115 frames at 1080 × 1080).
  200. ### Pixel text
  201. The `text` operation draws titles, captions, labels and counters in a built-in pixel font: printable ASCII, the accented letters of western European languages (À–ÿ, Œ œ Š š Ž ž Ÿ) and common symbols such as € £ © — … “ ” „ « », with capitals 7 pixels tall, proportional letters and tabular digits. The accent of a capital sits in the two rows above `y`.
  202. ```json
  203. { "op": "text", "x": 120, "y": 8, "text": "GAME OVER\nscore 12480", "color": "ink", "align": "center" }
  204. ```
  205. `align` says whether `x` is the left edge, the centre or the right edge; `spacing`, `lineHeight`, `scale` and rotation adjust it, and `outline` after it gives a readable edge. Text that runs off the canvas is reported like any other clipped drawing, and a character the font lacks is an error that names it. [examples/caption.json](examples/caption.json) is a lower third that opens and types its title; `node bin/pixelbolt.js sequence examples/caption.json --fps 30 --size 1080p --align bottom --offset 0,-64 --out shots/caption` turns it into 81 frames that sit across the bottom of a 1080p picture.
  206. ### Frames for a video editor
  207. Video editors do not animate APNG, and GIF loses alpha and exact timing. `pixelbolt sequence` writes what editors do read: one numbered PNG per video frame, at a constant frame rate, on a canvas of the video's size, with the alpha kept.
  208. ```sh
  209. node bin/pixelbolt.js sequence hero.pixel.json --fps 30 --size 1080p --out shots/hero
  210. node bin/pixelbolt.js sequence examples/effects.fx.json --animation sparks --fps 29.97 --size 4k --scale 16 --align bottom --offset 0,-200 --out shots/sparks
  211. node bin/pixelbolt.js sequence room.scene.json --fps 24 --size 1080p --fit cover --out shots/room
  212. ```
  213. - **Timing.** Each video frame shows the pose that is active when the frame starts. `--fps` takes 24, 25, 30, 50, 60, the NTSC rates 23.976, 29.97 and 59.94 (kept exact as 24000/1001, 30000/1001 and 60000/1001, so long clips do not drift), or a fraction. `--loops n` or `--seconds s` sets the length; `--step 2` animates on twos. A looping animation keeps cycling; one that plays once holds its last pose.
  214. - **Size.** `--size` is `720p`, `1080p`, `1440p`, `4k`, `vertical` (1080×1920), `square` or `WIDTHxHEIGHT`. The sprite is enlarged by a whole number, never resampled: the largest that fits, or `--scale` up to 256. `--align` (`top-left` … `center` … `bottom-right`) and `--offset x,y` place it. `--fit cover` takes the smallest whole number that covers the canvas instead and crops what hangs over; `--align` then chooses the part that stays, and the result's `placement.visible` says which columns and rows of the source that is. Without `--size` the canvas is the sprite at `--scale`. `--background` blends onto an opaque colour instead of keeping alpha.
  215. - **Sources.** A recipe (`--animation` picks one), a pose, autotile or effects source, which is compiled on the way in, or a scene, which is rendered moment by moment as a shot; moments that look the same share one PNG. A scene of 192×108 or 240×135 pixels fills 1080p exactly at scale 10 or 8. Any other scene is centred with margins in its own background colour, so the shot is still opaque from edge to edge, or fills the canvas with `--fit cover`.
  216. - **What you get.** A new folder with `name_0001.png` onwards, `sequence.json` (frame rate as a fraction, frame count, size, placement, loop facts and the timing of every pose) and a `README.txt` that says how to import them. The result's `notes` say what the frame grid did: which poses changed length, which are shorter than a video frame and never shown, and whether the clip ends exactly where the loop does, with the number of loops that would.
  217. - **One video file.** Pixelbolt does not encode video. The folder's README and the JSON result give the exact `ffmpeg` command for a ProRes 4444 `.mov` with alpha, and, when there is a background, for an H.264 `.mp4` in lossless 4:4:4. H.264 usually stores colour once for each 2 × 2 pixels (4:2:0), which smears every pixel edge whatever the scale once a player interpolates it; 4:4:4 keeps every colour, in a file no larger for pixel art, but QuickTime, Safari and Windows' own players may not play it, so on an even canvas `h264Compatible` gives a 4:2:0 file as well. With ffmpeg 7 the ProRes command keeps the alpha exactly and the colours within 2 of 255, and the H.264 command the colours within 1; `scripts/verify-exports.py` repeats those checks when ffmpeg is installed.
  218. In the editor, import the files as an image sequence and set the clip's frame rate (the files carry none), then leave the clip at 100% scale: scaling there would blur the pixels. A sequence holds at most 18,000 frames and a canvas at most 4096 pixels on a side. MCP `pixel_render` and `pixel_scene` take `"sequence": { "fps": 30, "size": "1080p" }` with the same options.
  219. The studio's **Frames** button downloads the same files for the animation on screen as one ZIP. Its dialog also shows the `pixelbolt sequence` command and the MCP `sequence` argument for the chosen frame rate and size, so an agent can repeat the export without the browser.
  220. ### Large frames and stills
  221. An animation frame may be up to 1024 pixels a side and 262,144 pixels: a full-screen 320 × 180, 480 × 270 or 640 × 360 overlay (rain, snow, fog) is one recipe, as is a 512 × 512 or 1024 × 256 frame. All of a recipe's frames hold at most 4,194,304 pixels, so 72 frames of 320 × 180, 18 of 640 × 360 or 16 of 512 × 512. A recipe with a single frame may be larger still: up to 4096 pixels a side and 4,194,304 pixels in all. A 1920 × 1080 or 2560 × 1440 backdrop, wallpaper or mural is then one canvas, drawn at one screen pixel per art pixel, and every drawing operation sees all of it. On a canvas wider or taller than 256, rectangles, ellipses and dither or shade regions may be up to twice its side instead of 512.
  222. A scene's view and each of its assets, an effect source and an imported frame have the animation frame's limit, so a tiled level is one picture. Everything else keeps its limits: pose, bodies, crystal, normals and compiled powder sources stay at 256 pixels a side, fluid and wave sources at 128, and the 67-million-pixel drawing budget is unchanged: `fill`, `replace` and `outline` each pass over the whole canvas, about 2 million of that budget at 1920 × 1080. To show bigger pixels instead, enlarge a small canvas with `sheet.scale` or `sequence --size`, as before. The studio opens a large still or an animation frame over 256 px a side fitted to its window (zoom 1 shows it at 1×), scaled down smoothly so dither reads as the tone it makes; zoom in with the scroll wheel and drag to look around at 1× and up.
  223. ## Connect an agent through MCP
  224. **Claude Code plugin.** One command installs the MCP server and the pixel art skill, with nothing to clone (Claude Code 2.1.292 or later):
  225. ```
  226. claude plugin install pixelbolt --marketplace skulitom/Pixelbolt
  227. ```
  228. Inside a session, `/plugin install pixelbolt --marketplace skulitom/Pixelbolt` does the same from Claude Code 2.1.275. On older versions, add the marketplace first with `claude plugin marketplace add skulitom/Pixelbolt`, then run `claude plugin install pixelbolt@pixelbolt`. The plugin runs its own copy of `bin/pixelbolt.js` with your Node.js (20 or later), in the project folder you open in Claude Code: file references resolve inside that folder and exports go to its `output/` folder. Restart Claude Code after installing.
  229. **Other MCP clients.** The npm package runs the server, with nothing to clone (Node.js 20 or newer). Add it to your agent's MCP configuration and replace `/absolute/path/to/pixelbolt-output` with the folder where exports should go. Use an absolute path, because clients start servers in different folders; on Windows use forward slashes, for example `C:/Art/pixelbolt-output`:
  230. ```json
  231. {
  232. "mcpServers": {
  233. "pixelbolt": {
  234. "command": "npx",
  235. "args": ["-y", "pixelbolt@latest", "mcp", "--out", "/absolute/path/to/pixelbolt-output"]
  236. }
  237. }
  238. }
  239. ```
  240. For clients that use TOML:
  241. ```toml
  242. [mcp_servers.pixelbolt]
  243. command = "npx"
  244. args = ["-y", "pixelbolt@latest", "mcp", "--out", "/absolute/path/to/pixelbolt-output"]
  245. ```
  246. On Windows, a client that starts the server without a shell can't run `npx` (Kimi Code reports `spawn npx ENOENT`). Use `"command": "cmd"` with `"args": ["/c", "npx", "-y", "pixelbolt@latest", "mcp", "--out", "C:/Art/pixelbolt-output"]` there instead.
  247. To run a checkout instead (for example `main`, which can be ahead of npm), clone the repository and use `"command": "node"` with `"args": ["/absolute/path/to/Pixelbolt/bin/pixelbolt.js", "mcp", "--out", "/absolute/path/to/Pixelbolt/output"]`.
  248. **Kimi Code, DeepSeek Harness and OpenCode.** Each takes the same `npx` server in its own format:
  249. - **Kimi Code CLI:** put the `mcpServers` block above in `~/.kimi-code/mcp.json` (or `.kimi-code/mcp.json` in a trusted project), in the `cmd /c` form on Windows; `/mcp` shows it.
  250. - **OpenCode:** add it under `mcp` in `opencode.json` (the project's, or `~/.config/opencode/opencode.json`), with the whole command as one array; `opencode mcp list` shows it connected:
  251. ```json
  252. {
  253. "$schema": "https://opencode.ai/config.json",
  254. "mcp": {
  255. "pixelbolt": {
  256. "type": "local",
  257. "command": ["npx", "-y", "pixelbolt@latest", "mcp", "--out", "/absolute/path/to/pixelbolt-output"]
  258. }
  259. }
  260. }
  261. ```
  262. - **DeepSeek Harness:** add this to `~/.dsh/cordis.patch.yml`; the tools appear as `mcp__pixelbolt__pixel_render` and so on:
  263. ```yaml
  264. - insert:
  265. - id: mcp-pixelbolt
  266. name: '@deepseek-ai/dsh-mcp-client'
  267. config:
  268. serverName: pixelbolt
  269. transport: stdio
  270. command: npx
  271. args: ['-y', 'pixelbolt@latest', 'mcp', '--out', '/absolute/path/to/pixelbolt-output']
  272. env: {}
  273. ```
  274. All three also read skills from `~/.agents/skills/`, so `npx -y pixelbolt@latest skill install --dir "$HOME/.agents/skills"` gives them the pixel art skill as well (in cmd.exe, `--dir "%USERPROFILE%\.agents\skills"`). Checked on 3 November 2026 with Pixelbolt 0.11.0 on Windows: OpenCode 1.19.5 lists the server as connected; Kimi Code 2.4.1 finds all eight tools through `cmd /c` (a bare `npx` fails there); DeepSeek Harness 0.2.1-rc.5 accepts the patch, though the server wasn't started from it, because it needs a DeepSeek key to start.
  275. The eight tools are:
  276. - **`pixel_help`**: a short quick start (the recipe format, operations, tools and workflow, about 2,000 tokens); `topic` returns the full authoring guide (`guide`), the art workflow (`workflow`), the recipe schema (`schema`), a complete sample (`example`), or the poses, scenes, autotile, fx, fluid, wave, crystal, powder, bodies or normals schemas (the guide and workflow list their sections, and `name` returns one, a part of a long one, or the paragraphs that mention a word); topic `presets` lists the shipped presets (fire, smoke, explosions, spells, liquids, plasma, rigid bodies, crystals, falling sand, characters) to compile instead of drawing, and `preset` with `name` returns one's source.
  277. - **`pixel_validate`**: validate `{ "project": ... }` and save its recipe revision without exporting assets. Reports every clipped location; `"fps": 30` adds `frameGrid`, the durations off that video frame grid and what a sequence would do to each animation.
  278. - **`pixel_inspect`**: contact sheets, exact regional grids, silhouette/grayscale/onion views, a parts view naming the layer or pose part behind each pixel, 3×3 tile repeats with seam evidence, native size, named layer isolation, saved-reference comparisons, advisory diagnostics, motion review with contacts, limb arcs and explicit pose metadata, and perspective `guides` (a horizon, vanishing points, an isometric grid). `frames` takes `*`/`?` patterns, `step`/`offset` keep every nth cell, and optional bounded samples expose omissions. Saves its recipe revision.
  279. - **`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.
  280. - **`pixel_render`**: render `{ "project": ... }`, return a PNG contact sheet of every frame with cell names/timing plus the output folder, its key files and frame/animation counts (`listFiles: true` lists everything). Add `"animation": "idle"` to preview a sequence in playback order. The exported APNGs and HTML preview play the animation. Add `"gif": {}` (or `{ "scale": 8, "background": "#17191d" }`) to also write every animation as a GIF in `gifs/`, with notes on any alpha or timing change, and `"sequence": { "fps": 30, "size": "1080p" }` to write one animation as numbered PNG frames for a video editor in `sequence/`. Every call writes a fresh folder inside the configured output directory.
  281. - **`pixel_compile`**: compile a `pixelforge-poses` source (including bones, masses, relative joints, reach targets and editable motion templates), a `pixelforge-autotile` template or terrain (returned with a second image of every tile over a test map), a `pixelforge-fx` source (particles and spell shapes), a `pixelforge-fluid` source (simulated smoke, fire, explosions, magic, water, thick and sticky liquids, sand, air pockets and bubbles, ice and steam, electric arcs, and bodies that float, sink and stir), a `pixelforge-wave` source (looping interference and portals), a `pixelforge-crystal` source (crystals, clusters, geodes and snowflakes that grow and rest), a `pixelforge-powder` source (a falling-sand sandbox of sand, water, fire, smoke, lava and more, sampled into one-shot clips), a `pixelforge-bodies` source (balls, boxes and hoops that bounce, stack and rest, and territory matches; `sequence` writes a match of any length as numbered video frames) or a `pixelforge-normals` source (a normal pass derived from a recipe or revision, with flat `faces` by colour for boxes and walls) into a recipe revision, with a contact sheet and optional metadata; `preset` compiles a shipped preset by name instead of a `source`.
  282. - **`pixel_scene`**: render a `pixelforge-scene` manifest (tilemaps with autotile legends and neighbour rules, named cues, sequences, trajectories, attachments, ground sorting, shade placements, ramp or multiplied lighting from point lights and a sun, with cast shadows, palette themes, haze for far planes, a panning camera with parallax planes) at any time, with a `depth` view of what is drawn in front of what, export it (with a Tiled map of it whose layers carry each plane's parallax, `scene.tmx`, hazed copies of far assets, and each plane as an image that a Godot `scene.tscn` scrolls with `Parallax2D`), or write it as a shot of numbered PNG frames with `sequence`; assets may be revisions.
  283. - **`pixel_import`**: import a native-resolution PNG, given as base64 or a file inside the server root, as a lossless recipe revision.
  284. `pixel_render` optionally accepts `"share": true` for a playground link (or a link-limit error without failing the render) and `"embedRecipe": true` for recipes inside exported PNGs.
  285. `pixel_render` also writes files at the names the user asked for: `"saveAs": { "sheet": "assets/hero.png", "gif": "assets/hero.gif" }` (keys `sheet`, `atlas`, `godot` for the Godot `.tres`, `tileset` for an autotile set's Godot TileSet, `tiled` for its Tiled tileset, `recipe`, `gif`, `apng` or any exported PNG, GIF or JSON file; paths inside the server root, keeping the file type, never under a hidden name or in the home folder's `AppData` or `Library`). A saved atlas, `.tres` or `.tsx` names the saved sheet (or the export folder's), and a `.tres` inside a Godot project needs its sheet inside it too. It never replaces an existing file unless `"overwrite": true`, and then a JSON file only if it is a recipe, atlas or sequence, a `.tres` only if it is the same kind of Godot resource (SpriteFrames, TileSet or CanvasTexture), and a `.tsx` only if it is a Tiled tileset; it never writes over the palette and asset files the recipe references, and checks every path before writing anything.
  286. `pixel_patch` also supports compact `grid`, masked `move`, regional `recolor` and proposed `cleanup` of doubled corners and stray pixels, with explicit `frame` or `inherited` scope, and applies saved correction overlays (`overlay`). Large `pixel_render` previews are sampled with total/shown/omitted metadata instead of blocking a valid export; exported animations remain complete. Palette and scene file references resolve inside the server's `--root` (default: its working directory); requests may be up to 16 MiB, and an oversized request is answered with an error without stopping the server. Each tool call runs in a worker thread and is stopped if it takes longer than 50 seconds (`--time-limit <seconds>` changes this) or runs out of memory; the call is answered with an error that says so, and the server keeps serving. A `sequence` from one call may come to at most 512 MB; `pixelbolt sequence` writes longer shots.
  287. 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. Once that directory exists, the presets listing keeps what it measured in `.presets/` beside them, so later listings are quick. 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.
  288. 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 through initialization, plus 2026-07-28 through `server/discover` and stateless requests carrying protocol version and client capabilities in `_meta`. It uses no HTTP transport or external services. See the [MCP stdio specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports).
  289. An agent can also use the CLI directly. The reusable [agent skill](skills/pixel-art/SKILL.md) and [authoring reference](docs/agent-guide.md) explain the complete format; `npx -y pixelbolt@latest skill install` gives Claude Code the skill with its guides, schemas and examples and no server. [schema.json](schema.json) supports editor completion and structural validation; the rasterizer additionally validates references, matching row widths and resource limits.
  290. ## Inline previews (MCP Apps)
  291. Hosts that support MCP Apps (the `io.modelcontextprotocol/ui` extension) show an inline pixel art player for inspect, patch, compile, render, scene and import results. It has crisp integer zoom, playback, frame stepping, speed, animation and background controls; render results also show written paths, the delivery check and an optional playground button. The viewer needs no network. Clients without MCP Apps receive exactly the same tool listings and results as before.
  292. ## Use in a web app
  293. Serve the exported folder with your application:
  294. ```html
  295. <canvas id="sprite"></canvas>
  296. <script type="module">
  297. import { SpritePlayer } from './assets/player.js';
  298. const player = await SpritePlayer.load(
  299. document.querySelector('#sprite'),
  300. './assets/forest-spirit.atlas.json',
  301. { scale: 4 }
  302. );
  303. player.play('idle');
  304. // player.pause(); player.resume(); player.destroy();
  305. </script>
  306. ```
  307. Or use CSS alone:
  308. ```html
  309. <link rel="stylesheet" href="assets/forest-spirit.css">
  310. <span class="pf-forest-spirit pf-forest-spirit-idle" role="img" aria-label="Forest spirit"></span>
  311. ```
  312. 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.
  313. A game drawing many sprites into one canvas can use the same module's helpers. `drawFrame` places a frame by its anchor (when the recipe declares one), restores trimmed frames to their original offset and snaps fractional positions to whole pixels, so a sprite moving at sub-pixel speeds keeps hard edges. `rotate` (radians, about the anchor) turns it. A turned sprite keeps clean square pixels only where each of its pixels covers several of the canvas's, so draw what turns, and what should glide from place to place and not step, on a second canvas at the screen's own resolution with `scale` 3 or more, laid over the canvas the grid-aligned world is drawn on:
  314. ```html
  315. <script type="module">
  316. import { loadSpriteSheet, frameAt, drawFrame } from './assets/player.js';
  317. const hero = await loadSpriteSheet('./assets/hero.atlas.json'), context = canvas.getContext('2d');
  318. requestAnimationFrame(function draw(time) {
  319. context.clearRect(0, 0, canvas.width, canvas.height);
  320. drawFrame(context, hero, frameAt(hero.atlas, 'walk', time), 64, 96, { scale: 3 }); // (64, 96) is where the anchor lands
  321. requestAnimationFrame(draw);
  322. });
  323. </script>
  324. ```
  325. For Godot 4, put `name.png` and `name.tres` in one folder of the project and use the `.tres` as an `AnimatedSprite2D`'s Sprite Frames. For another 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](docs/game-integration.md).
  326. ## JavaScript API
  327. ```js
  328. import { renderProject, inspectProject, patchRecipe, compareProjects, createBundle, writeBundle, readExpect, checkDelivery, compileEffects, compileFluid, createLiveFluid, animationGIF, folderGIF, frameGrid } from './src/index.js';
  329. const project = renderProject(recipe); // RGBA buffers, durations, warnings
  330. const view = inspectProject(project, { grid: true }); // contact sheet RGBA, palette-key grids
  331. const { recipe: next, edits } = patchRecipe(recipe, [{ set: 'frames[idle].duration', value: 120 }]);
  332. const report = compareProjects(project, renderProject(next)); // changed pixels, timing, before/after RGBA
  333. const bundle = await createBundle(recipe);
  334. await writeBundle(bundle, './output/my-sprite');
  335. const check = checkDelivery(bundle.project, { recipe, expect: readExpect({ width: 32, height: 32, frames: 8 }) }); // the CLI's and MCP's check: { ok, delivered, problems }, each problem with its fix
  336. const { recipe: effects } = compileEffects(fxSource); // seeded particles and spell shapes baked into an ordinary recipe
  337. const { recipe: fire, metadata } = compileFluid(fluidSource); // a fluid simulation baked into palette grids
  338. const { rgba, keys } = createLiveFluid(fluidSource).push({ x: 8, y: 20, vx: 2 }).step().render(); // the same simulation, live
  339. const gif = animationGIF(project, 'idle', { scale: 8 }); // { data, width, height, notes, ... }
  340. const loop = folderGIF('shots/prism', { fps: 25 }); // GIF from numbered PNG frames; framesGIF takes RGBA frames
  341. const grid = frameGrid(project, 30); // durations off a 30 fps video frame grid
  342. ```
  343. `src/core.js`, `src/craft.js`, `src/font.js`, `src/patch.js`, `src/fx.js`, `src/fluid.js` and `src/gif.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.
  344. ## Develop and verify
  345. ```sh
  346. npm test
  347. npm run demo
  348. ```
  349. Tests cover pixels, alpha blending, inheritance, transformations, flood fill, text and the font, dither (including value noise), palette ramps and shading, outlines, rewrite rules, cleanup, rotation, tweens, particle effects, fluid simulation (golden recipes per preset, palette-only output, loop seams), tilemaps and rule tiles, scene cues, attachments and sorting, schema alignment, packing, timing, PNG/APNG structure, GIF structure and decoding, video frame timing and placement, inspection sheets and grids, patching and comparison, revisions, overwrite protection, CLI stdin/errors, MCP calls, the Canvas runtime, the local server and the portable Windows build. `node scripts/qa-studio.mjs` walks the studio in a real browser (an installed Edge or Chrome, headless, with a throwaway profile; Node.js 22+): every sample, live editing, a broken recipe, the preview controls, Save, Open, Export and GIF downloads landing on disk, a recipe that links a shared palette file, draft recovery, keyboard access, narrow and wide windows, and that no request leaves the computer. `node scripts/verify-godot.mjs` loads exported SpriteFrames in a headless Godot 4, when one is installed, and checks every frame's region, trim margin, pixels and timing and each animation's playback. Optional independent checks use Pillow and Python's ZIP reader: `python scripts/verify-exports.py` after `npm run demo`; it also decodes GIFs (including ones made from PNG folders) and an image sequence and compares every pixel, delay and loop flag, and runs the sequence's ffmpeg command when ffmpeg is installed.
  350. 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. Unsaved edits are kept as a draft in the browser's own storage for the studio's address, one per tab, and offered back after a reload or, once that tab is closed, on the next visit; nothing about them is sent to the server, and **Save JSON** remains the way to keep a recipe. Browser storage is per address, so a draft made on one port is not seen on another. Projects are limited to animation frames of 1024 pixels a side and 262,144 pixels (stills up to 4096 a side), 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.
  351. ## Pixelbolt Studio: portable builds
  352. `scripts/build-studio.mjs` packs the toolkit, the official Node.js 24 LTS runtime and a few small launcher scripts into one archive per system, for people who have no Node.js, git or administrator rights: a ZIP for 64-bit Windows, and a `.tar.gz` that keeps execute permissions for Linux (x64 and ARM64) and macOS (Apple silicon and Intel). Nothing is installed, and deleting the folder removes everything.
  353. **Download:** each release's page carries the five archives and a `PixelboltStudio-<version>-SHA256SUMS.txt` list, from 0.17.0 on: [the latest release](https://github.com/skulitom/Pixelbolt/releases/latest). `.github/workflows/studio-assets.yml` builds, checks and attaches them once the Release workflow has finished. To check a download, run `sha256sum -c --ignore-missing PixelboltStudio-<version>-SHA256SUMS.txt` in its folder, or compare `Get-FileHash` on Windows.
  354. | | Studio | Command line | Connect an agent |
  355. | --- | --- | --- | --- |
  356. | Windows | double-click `Pixelbolt Studio.cmd`, or drag a recipe onto it | `pixelbolt.cmd` | `Connect your agent.cmd` |
  357. | macOS | double-click `Pixelbolt Studio.command`, or `./pixelbolt-studio [recipe]` | `./pixelbolt` | `Connect your agent.command` or `./connect-your-agent` |
  358. | Linux | `./pixelbolt-studio [recipe]` | `./pixelbolt` | `./connect-your-agent` |
  359. The studio launcher is `pixelbolt preview --open`: it opens the default browser on loopback port 4747, or on any free port when that one is taken (the usual port is what lets the studio's draft recovery find its draft again). The connect helper prints MCP settings for Claude Code, Claude Desktop, Codex and Cursor with that folder's paths, plus a one-line `claude mcp add` and `codex mcp add` command written for that system's shells; the helper itself never edits a configuration file.
  360. ```sh
  361. node scripts/build-studio.mjs # this machine's own target, into dist/
  362. node scripts/build-studio.mjs --target all # win-x64, linux-x64, linux-arm64, darwin-arm64, darwin-x64
  363. node scripts/build-studio.mjs --target all --check # rebuild and compare with the archives in dist/
  364. node scripts/verify-studio.mjs dist/PixelboltStudio-<version>-<target>.zip # or .tar.gz
  365. ```
  366. Any machine can build any target; each archive comes with its `.sha256` and a per-file manifest. An archive holds exactly the files `npm pack` ships (under `app/`), the runtime, and the files for its system from [packaging](https://github.com/skulitom/Pixelbolt/blob/main/packaging): no demos, tests or development scripts. The runtimes are pinned in the build script by version and SHA-256, downloaded from nodejs.org on the first build (36 to 58 MB each, cached in `dist/.cache`; `--node-archive <file>` uses a copy you already have) and included unmodified; a mismatch stops the build. `BUILD-INFO.txt` inside names the Pixelbolt version, the source commit, the target and the runtime's hashes. A build refuses uncommitted changes to shipped files unless `--allow-dirty` marks it as a development build, and a release build takes every shipped file from the commit itself rather than the working copy. One commit gives the same file list and per-file hashes anywhere. Where a runtime is pinned for the building machine the packing runs under that runtime, and the archives then come out byte-identical whichever system builds them: every CI runner (Windows, Linux on x64 and ARM64, and macOS) builds all five and prints their hashes.
  367. `verify-studio.mjs` extracts an archive with the system's own tool into a folder whose path has a space and a non-ASCII character, and runs it with no Node.js or git on `PATH`: the launcher (several copies, loopback only, every studio route, foreign Host and Origin refused, export, a recipe handed to it), the commands exactly as `START HERE.txt` gives them in two shells, the MCP server over stdio, the helper's output and its one-line commands, execute permissions and line endings, and that no process is left behind. It needs the system the archive is for; elsewhere it checks the contents only and says so. The Tests workflow builds, rebuilds and verifies each archive on a runner of its own system (the Intel Mac build through Rosetta on an Apple silicon runner), then runs the test suite on the bundled runtime and walks the extracted build's studio in the runner's browser. On the macOS runner the command line also runs with the download quarantine mark set. No runner has a person at the screen: the prompts Windows and macOS show for downloaded files, a double-click and a real browser are not exercised there.
  368. ## Contributing
  369. Bug reports, recipe examples, documentation improvements and focused pull requests are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](https://github.com/skulitom/Pixelbolt/blob/main/AGENTS.md) before changing the toolkit. Report reproducible bugs through [GitHub Issues](https://github.com/skulitom/Pixelbolt/issues).
  370. ## Sibling tools
  371. Pixelbolt is one of five free, MIT-licensed tools for agents by the same author. Each runs locally and works as an MCP server:
  372. - [Anode](https://github.com/skulitom/Anode): Windows desktop automation in a hidden background session, so an agent can click, type and take screenshots without taking over your screen.
  373. - [Cutbolt](https://github.com/skulitom/Cutbolt): a video editing engine with exact timelines, captions and rendering.
  374. - [Inkbolt](https://github.com/skulitom/Inkbolt): vector and raster image editing for diagrams and illustrations, with SVG import and SVG or PDF export.
  375. - [Nestbolt](https://github.com/skulitom/Nestbolt): 2D nesting of parts on sheets for laser, CNC, plasma and waterjet cutting, also [in your browser](https://skulitom.github.io/Nestbolt/).
  376. ## License
  377. [MIT licensed](LICENSE). Included artwork is original and covered by the same license.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.