pixelbolt-pixel-art git:20261031.d04dad0A

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

---
name: pixelbolt-pixel-art
description: Make or fix pixel art - sprites, sprite sheets, tiles and tilesets, icons, game effects such as fire, smoke, water or sparks, and short frame animations - and save them as PNG, GIF, APNG or frames for a video. Use when someone asks to draw, animate, fix or export pixel art or game sprites. Pixelbolt JSON recipes, local, no account, no API key.
---

# Pixelbolt pixel art

Use this when creating pixel sprites, tiles, icons, effects or short sprite animations. Pixelbolt lives at the project root two directories above this skill's directory. Run its CLI with Node.js, or use its MCP tools if configured.

In the Claude Code plugin, the MCP tools (`pixel_help`, `pixel_validate`, `pixel_inspect`, `pixel_patch`, `pixel_render` and the rest) come with this skill. If they are missing, the plugin's server did not start: it needs Node.js 20 or later on PATH (`node --version`). Install Node.js from https://nodejs.org, then restart Claude Code.

In the portable Pixelbolt Studio build, run `.\pixelbolt` on Windows or `./pixelbolt` elsewhere from the build folder instead of `node bin/pixelbolt.js`.

**Start with the quick start.** Read `docs/agent-quick-start.md` (MCP: `pixel_help` with no topic) before the first recipe: a complete recipe, every operation and tool, and the working loop. It covers most tasks. Open a reference only when the task needs it: `docs/agent-guide.md` for every field, operation, inspection option, patch path and export; `docs/art-workflow.md` for characters, scenes, tiles, effects and lighting; `schema.json` for exact field names. Begin from a file in `examples/` when one is close.

**Quick effects first.** When someone asks for a ready-made looping effect (a campfire, torch, smoke puff, steam vent, explosion, magic swirl, drip, splash, waterfall, bubbling potion, honey, snow sliding off a roof, a dam break, a dust wave, bursting slime or honey dripping off a spoon) as a file to use or share, start from the matching preset (`pixel_help` topic `presets` lists them and `pixel_compile` with `preset` compiles one), whose files are `examples/*.fluid.json` (in the Pixelbolt folder two directories above this skill's directory), change only what they asked for (for a bigger file, use `pixel_render`'s `gif.scale`; a different canvas size also means moving the effect's obstacles and emitters, which use absolute coordinates), compile it with `pixel_compile`, look at it once with `pixel_inspect`, and export the compiled revision with `pixel_render` (`gif` for a GIF to post). Deliver that file first, then offer to tune the look or add props such as logs or stones. Don't build a new recipe around the effect, or run the full art workflow below, before the first export.

For looping interference or portal interiors, start from `examples/interference.wave.json` or `examples/portal.wave.json` and compile it ([controls](../../docs/wave-effects.md)). Keep rims in an overlay and avoid narrow crawling bands; use particle rings for one-shot impacts.

## Art direction

For finished artwork, also read `docs/art-workflow.md`. Establish a small art brief outside the recipe: native/display size, three silhouette landmarks, palette roles, light direction, projection (side, 3/4 top-down, isometric 2:1 or top-down, one for the whole set) and depth planes, material rules, outline treatment, action intent, contact/origin and scene role. Record the actual strengths and failures of each review. A rendered file, frame count or passing test is not evidence of artistic quality. These checkpoints do not require user permission.

Work in this order: **silhouette → large connected color shapes → material accents → authored action poses → timing → scene integration**. Do not mass-generate variants before the resting silhouette and one action read well. Use primitive geometry as a blockout; revise contours and connected color groups deliberately. Noise and extra glow cannot fix weak structure. Design different behaviors for water, fire and crystal rather than recoloring identical geometry.

Avoid gradients, subpixel geometry and antialiasing. Respect the project's requested pixel dimensions. Preserve editable source. Export at scale 1 for game assets unless the user asks for larger pixels baked into the files.

## The loop

1. Choose a small canvas and cohesive palette appropriate to the requested asset.
2. Write a JSON recipe in a user-appropriate output location. Use text grids and reusable symbols; reuse frames for small changes.
3. Validate with `node bin/pixelbolt.js validate <recipe>`. Every error names its path, and broken operations come back together in `errors`: fix them all before validating again.
4. Inspect every frame with `node bin/pixelbolt.js inspect <recipe> --out <frames.png> --native --diagnostics` and look at both sizes. Review `--view silhouette` and `--view grayscale` against the intended background, and `--animation <name> --view onion` for previous and next poses. Watch the studio or APNG too: a static sheet is not motion review. Before changing exact pixels, read them with `--grid --region x,y,w,h`. `node bin/pixelbolt.js patch <recipe> --changes <changes.json>` previews a targeted edit and lists every pixel it changes, including inherited poses; add `--out <new recipe>` to save it. Choose `scope: "frame"` when other poses must keep their pixels ([inspection options](../../docs/art-workflow.md#inspection-options), [corrections](../../docs/art-workflow.md#regional-corrections-and-scope)).
5. Render with `node bin/pixelbolt.js render <recipe> --out <directory> --expect '{"width":32,"height":32,"frames":8}'`, giving `--expect` what the user asked for (`width`, `height`, `frames`, `colors`, `transparent`, `loop`); fix every problem its `check` lists, then render again, before you hand anything on. Choose a fresh output directory for each iteration. For a file to post or embed, add `node bin/pixelbolt.js gif <recipe> --out <new.gif>` (`--scale` only to enlarge it for posting) and report its `notes`. For words on screen use the `text` operation. For a video editor, `sequence` writes numbered PNG frames at a frame rate, and `gif-frames` turns a folder of frames into an exact-colour GIF ([exports](../../docs/agent-guide.md#calling-the-tool)).
6. Return links to the source recipe, sheet, atlas JSON and preview, with a short integration note for the intended web app or engine (for Godot 4, the export's `.tres` beside its sheet is an `AnimatedSprite2D`'s Sprite Frames, and an autotile set's `.tileset.tres` is a `TileMapLayer`'s TileSet with a terrain to paint; for Tiled, its `.tsx` is a tileset with a terrain set for the Terrain Brush).

For MCP, call `pixel_help`, then `pixel_inspect` with `{ "project": recipe }`, adding `animation`, `region` or `grid: true` as needed. Later calls take the returned `revision` instead of the full recipe; revisions persist in the configured output directory across restarts. Fix problems with `pixel_patch` and check that only the intended pixels changed. Call `pixel_render` with the final revision and `expect` to export (when the user named files, add `saveAs`, such as `{ "sheet": "assets/hero.png", "gif": "assets/hero.gif" }`). The response lists key files and counts; pass `listFiles` for every file. `pixel_compile` turns a source format into a revision, `pixel_scene` reviews or exports a scene, and `pixel_import` converts a native PNG into a lossless recipe. Requests are capped at 16 MiB: send a large recipe once and reuse its revision.

## Characters

For figures in motion, use `pixelforge-poses` with `bone` limbs, `mass` bodies and grid heads, hands and props. Start from `examples/hero.poses.json` (in the Pixelbolt folder two directories above this skill's directory), a rigged side-view figure with every motion template; a part without `attach` stands at the pose `origin` plus its `at`, an offset rather than a canvas position.

- Assign rig roles and use the idle, walk, run, jump, attack and hurt templates as editable starting points. Set speed, stride, lift, bob and frame timing for the particular body, and fix compile warnings (a pose off the canvas, a foot out of reach) before adding detail.
- In a side view, draw far limbs a ramp step darker and give paired legs the same rest angles; near limbs stay in front for the whole cycle, and `swapDepth: true` is only for front or back views.
- Review silhouette, adjacent key-pose differences, planted contacts and the loop join with `inspect source.poses.json --motion run --speed 48` (MCP `pixel_inspect` with `source`, `view: "motion"`). Do not infer contact quality from a still sheet or claim better art from passing numerical checks alone.
- Mirrors, grid `views`, `rotate` and `tween`, markers exported as atlas points, and fingerprinted overlays for corrections that survive a rebuild are in [structural limbs](../../docs/art-workflow.md#structural-limbs-and-bodies) and [authored poses](../../docs/art-workflow.md#authored-poses-attachments-and-cues).

## Tiles, palettes and scenes

- For tiles, review `--view tile` (a 3×3 repeat) and set `wrap` on frames whose drawing continues across the edges. For terrain, describe an autotile `terrain` instead of typing the 2×3-tile template (start from `examples/meadow.autotile.json` or `ground.autotile.json`, or `shore.autotile.json` for transitions between terrains), compile it into 47 blob, 16 cardinal or 16 corner (dual-grid) tiles, and check its test map and seam warnings; give tilemap legends `rules`, `weights` and variants instead of computing maps in a script ([autotile templates](../../docs/art-workflow.md#autotile-templates), [scene and tile review](../../docs/art-workflow.md#scene-and-tile-review)).
- Share a palette with `"palette": { "$ref": "palette.json" }`, declare `ramps` and shade with `shade` so light never leaves the palette, cycle water or lights with frame or layer `palette` overrides, and use `remap` for colour variants and hit flashes.
- When many things stand on the ground, put them in one layer or group with `sort: "ground"`, and give scene placements `anchor: "frame"`. Use `lift` for jumps, `shadow: true` with a light or a `sun`, `haze` for far planes, the `box` operation and `layout: "iso"` for isometric art, and a `camera` with `parallax` to pan. Scene assets are at most 256 pixels a side, so tile a panning backdrop with `repeat` or a `tilemap`. A backdrop or mural rendered on its own, outside a scene, may be a single-frame still up to 4096 pixels a side; draw it at one pixel per screen pixel, with no enlarged stamps or text.
- Before showing a scene, inspect a 2–4× `region` wherever different kinds of thing meet, and check who covers whom with `pixel_scene` `view: "depth"` and `guides` ([depth and perspective](../../docs/art-workflow.md#depth-and-perspective)).

## Craft, effects and lighting

- Craft operations help once the forms are right: `dither` for transitions and bands (not whole surfaces), `pattern: "value"` for clumps of moss or rubble, `pattern: "noise"` with a fixed `seed` for fades without flicker, `outline` with `position: "inside"` and `directions` for rim lights, and seeded `rewrite` rules for moss or cracks. Preview `cleanup` proposals with `patch` and keep deliberate corners, eyes and sparks ([operations](../../docs/agent-guide.md#operations)).
- For a game spell (a projectile in eight directions, an impact, an area effect or a buff), start from the matching effect in `examples/<element>-spells.fx.json` (fire, ice, lightning, water, poison, holy, shadow) and change only what was asked.
- For particle effects, write a `pixelforge-fx` source: give each material its own motion and shapes, keep counts low enough to read, give an impact one strong shape before the scatter, and add spell `layers` (slash, ring, beam, bolt, glyph, star, burst, stream, aura, trail) instead of drawing them ([particle effects](../../docs/art-workflow.md#particle-effects)). Fix every edge warning the compile gives (something is cut off at the canvas edge) unless the effect lists that side in `edges`. Make gas and mist see-through, not outlined. For an effect round a character, give what belongs behind it a `depth`, so the game draws `<effect>-back`, its character, then `<effect>-front`.
- For fire, smoke, steam, explosions, magic, water, honey or slime that should move like a fluid, start from an `examples/*.fluid.json` preset and tune it (`viscosity`, `yield`); its `look` decides the colours. Check one-shots at 1× and end empty, and keep the loop boundary quiet ([fluid effects](../../docs/art-workflow.md#fluid-effects)).
- For lit scenes, derive normal passes with a `pixelforge-normals` source rather than painting them, light the result from both sides before trusting it, and tell the user Godot and Unity read +Y up ([generated normal passes](../../docs/art-workflow.md#generated-normal-passes), [game integration](../../docs/game-integration.md#normal-and-emissive-passes)).

Advisory findings are prompts to inspect, not commands to delete pixels. Exempt intentional holds, eyes, sparks, literal colors and alpha blends in the brief. Keep original assets and failed comparisons. If asked for a named game's quality level, make original art and report what the visible evidence supports; do not equate new features or automated tests with matching that game's art direction.