pixscii
# pixscii
**LLMs can't draw. This MCP can.** A pixel art animation toolkit for AI agents.
Sister project of [artscii](https://github.com/rxolve/artscii). While artscii provides terminal ASCII art, pixscii gives AI agents a full pixel art workbench — generate characters, animate scenes, draw sprites, and export PNGs. Offline, deterministic, zero latency.
## One Call Animation
```json
animate_scene {
"width": 128, "height": 48,
"background": { "tiles": [["tree","grass","grass","sand","stone","wall","wall","door"]] },
"actors": [
{ "seed": "hero", "species": "human", "armor": "plate", "weapon": "sword",
"motion": "walk", "from": {"x":0,"y":28}, "to": {"x":96,"y":28} },
{ "seed": "mage", "species": "elf", "armor": "cloth", "weapon": "staff",
"motion": "walk", "from": {"x":-16,"y":30}, "to": {"x":72,"y":30} },
{ "seed": "guard", "species": "skeleton", "motion": "idle",
"from": {"x":108,"y":28}, "to": {"x":108,"y":28} }
],
"frames": 24, "delay": 150
}
```
One tool call. 3 characters, tiled background, 24 frames. 9ms.
The LLM translates a scene description into structured input. pixscii executes it instantly.
## Quick Start
```bash
npx pixscii
```
Or add to your MCP client config:
```json
{
"mcpServers": {
"pixscii": {
"command": "npx",
"args": ["-y", "pixscii"]
}
}
}
```
## Tools (25)
### High-Level — Full scenes in one call
| Tool | Description |
|------|-------------|
| `animate_scene` | Text description → animated scene with characters, background, and motion |
### Source — Create or load a canvas
| Tool | Description |
|------|-------------|
| `create` | New blank canvas with optional fill color |
| `get` | Load a bundled sprite into an editable canvas |
| `character` | Generate a procedural pixel character |
| `convert` | Quantize any image (URL or base64) to pixel art |
| `search` | Browse the sprite library |
| `creature` | Endless symmetric robots, aliens and critters from a mask and a seed, or an asymmetric nebula |
| `being` | A 24×24 person, cat or elf as a baby, an adult or old |
| `landscape` | Generate a landscape from a seed: sky by time of day, sun or moon, stars, clouds, mountains, hills, sea, forest, ground, rain |
### Mutate — Draw on a canvas
| Tool | Description |
|------|-------------|
| `pixel` | Set individual pixels (batch up to 512) |
| `line` | Bresenham line between two points |
| `rect` | Rectangle — outline or filled |
| `fill` | Flood fill from a point (with leak detection) |
| `mirror` | Mirror left half to right half |
| `shapes` | Draw geometry as crisp pixel art: rect, circle, ellipse, polygon, line, curve, with dithered fills and gradients |
| `undo` | Revert the last drawing operation |
### Observe — Read the canvas state
| Tool | Description |
|------|-------------|
| `inspect` | View the canvas as a hex character grid |
### Compose & Output
| Tool | Description |
|------|-------------|
| `sequence` | Animate actors across a scene with per-frame positions |
| `compose` | Layer multiple canvases/sprites into a scene |
| `tilemap` | Build a map from a tile grid |
| `spritesheet` | Stitch frames into a single PNG (horizontal/vertical/grid) |
| `animate` | Animate a sprite with pixel motion (idle, walk, attack...) |
| `export` | Render a canvas to scaled PNG |
### Palette — Recolor by mood
| Tool | Description |
|------|-------------|
| `palettes` | List palettes and their named slots (filter by schema) |
| `repalette` | Switch a canvas to another palette: same schema keeps pixels, others map by slot name or nearest color |
## Shapes: Write Geometry, Get Pixels
LLMs can't place pixels well, but they write coordinates fine. `shapes` rasterizes geometry at pixel centers with no anti-aliasing, so every pixel is one palette index. Soft fills come from ordered dithering:
```json
shapes {
"width": 128, "height": 72, "palette": "scene-dusk",
"shapes": [
{ "type": "rect", "x": 0, "y": 0, "w": 128, "h": 46, "fill": { "gradient": ["sky-top", "sky-mid", "sky-low"] } },
{ "type": "circle", "cx": 92, "cy": 40, "r": 9, "fill": "sun" },
{ "type": "polygon", "points": [[0,46],[22,26],[40,38],[62,20],[90,42],[128,40],[128,48],[0,48]], "fill": "far" },
{ "type": "rect", "x": 0, "y": 46, "w": 128, "h": 26, "fill": { "gradient": ["water", "near"] } },
{ "type": "curve", "points": [[34,56],[44,44],[56,56]], "color": "accent" }
]
}
```
Then `repalette` to `scene-sea` or `scene-night` for the same picture in another mood. In code: `drawShapes(sprite, shapes, palette)`.
## Landscapes from a Seed
`landscape` builds a whole scene from a seed in the scene schema, so one seed is one place you can show in any mood:
```json
landscape { "seed": "harbor-town", "preset": "dusk" }
landscape { "seed": "harbor-town", "preset": "dusk", "palette": "scene-night" }
landscape { "seed": "pine-ridge", "time": "dawn", "layers": ["sky", "sun", "mountains", "forest", "ground"] }
```
Presets match the scene palettes: `dawn`, `home`, `school`, `night`, `sea`, `storm`, `window`, `forest`, `dusk`, `stars`. Layers: sky (dithered gradient), stars, sun or moon (with a halo, and glitter on water), clouds, mountains (midpoint-displacement ridge), hills (value noise), sea (waves), forest (pines and round trees), ground, rain. Default size 128×72. In code: `landscape({ seed, preset })`.
## Creatures and Beings
`creature` mirrors a mask filled by the seed (body, maybe-body, empty), drops stray pixels, outlines it, lights it from the top and gives it eyes. Kinds: `robot`, `alien`, `critter`, plus `nebula` (asymmetric noise cloud with caught stars). `being` draws a person, cat or elf at a life stage from shapes: babies have big heads and no legs, old people white hair and a cane, old elves a staff, old cats a rounder body and a lowered tail.
```json
creature { "seed": "voyager-7", "kind": "robot" }
being { "species": "elf", "stage": "old", "palette": "scene-forest" }
```
Both use the scene schema, so they sit on a `landscape` in the same palette.
## Three Layers of Control
```
Layer 1: animate_scene → full scene in one call (fast path)
Layer 2: sequence/compose → manual frame composition (precise control)
Layer 3: pixel/line/rect → individual pixel editing (full control)
```
Start with `animate_scene` for a fast draft. Drop to lower layers to refine.
## Example: One-Call Scene Animation
```
→ animate_scene {
width: 80, height: 40,
background: { tiles: [["grass","grass","stone","wall","door","wall"]] },
actors: [{
seed: "hero-girl", species: "human", armor: "cloth",
motion: "walk", from: {x:0, y:24}, to: {x:60, y:24}
}],
frames: 16, delay: 120
}
← 16 frame PNGs + frame_ids
→ spritesheet { frames: [frame_ids], direction: "horizontal" }
← single strip PNG with all 16 frames
```
Two calls: one to generate, one to assemble. Done.
## Example: Drawing a Sprite from Scratch
```
→ create { width: 16, height: 16, fill: "." }
← canvas_id + hex grid
→ rect { canvas_id, x: 3, y: 5, w: 10, h: 9, color: "1" }
→ fill { canvas_id, x: 7, y: 7, color: "8" }
← filled: 56 pixels, leaked: false (grid returned — agent verifies)
→ inspect { canvas_id }
← agent reads grid, spots issue, fixes with pixel tool
→ export { canvas_id, scale: 4 }
← 64x64 PNG
```
## The Hex Grid Protocol
Every pixel is one character. The agent reads and writes in the same alphabet:
```
0-F = PICO-8 palette colors (0=black, 7=white, 8=red, ...)
. = transparent
```
```
0123456789ABCDEF
0: ................
1: .....111111.....
2: .....177771.....
3: .....177771.....
4: ...1111111111...
5: ...1888888881...
6: ...1788888881...
```
~80 tokens for a full 16x16 sprite. The LLM reads this like source code and reasons about it spatially.
## Bundled Assets
**22 sprites** across 4 categories:
- **Items:** sword, shield, potion, key, bow, coin
- **Tiles:** grass, stone, water, wall, door, tree, sand, dirt
- **Effects:** slash, sparkle, explosion, heal
- **UI:** heart-full, heart-empty, arrow-up, cursor
**648 procedural characters:**
4 species (human, elf, dwarf, skeleton) x 3 armors x 3 weapons x 3 helms x 6 skin tones.
**13 palettes:** pico8 (default), grayscale, gameboy, and 10 scene moods (`scene-dawn`, `home`, `school`, `night`, `sea`, `storm`, `window`, `forest`, `dusk`, `stars`)
The scene palettes share one **schema**: the same 16 named slots (`ink`, `sky-top`, `sky-mid`, `sky-low`, `sun`, `cloud`, `far`, `mid`, `near`, `ground`, `water`, `foam`, `accent`, `skin`, `cloth`, `light`). Draw once with those slots, then render with any scene palette to get the same picture in another mood. In code: `SCENE.ground`, `slotIndex(palette, 'water')`, `remapPalette(sprite, from, to)`.
**6 motion types:** idle, walk, attack, hurt, bounce, blink
## CLI
```bash
npx pixscii import sprite.png --id my-sword --category items
npx pixscii export sword --scale 4 --out sword.png
```
## Use in the Browser: `pixscii/core`
Everything that draws, composes and renders also runs without Node. `pixscii/core` has no Node built-ins, no sharp and no MCP:
```ts
import { createEmpty, drawRect, registerPalette, getPalette, renderToRGBA } from 'pixscii/core';
registerPalette({
id: 'dusk',
name: 'Dusk',
colors: [
{ index: 0, hex: '#1A1016', name: 'sky' },
{ index: 1, hex: '#E88FB0', name: 'sun' },
{ index: 2, hex: '#3A2433', name: 'ground' },
],
});
let scene = createEmpty(32, 18, 0);
scene = drawRect(scene, 13, 4, 6, 6, 1, true);
scene = drawRect(scene, 0, 12, 32, 6, 2, true);
const { width, height, data } = renderToRGBA(scene, getPalette('dusk'), 8);
canvas.getContext('2d')!.putImageData(new ImageData(new Uint8ClampedArray(data), width, height), 0, 0);
```
Bundled sprites, palettes and characters load through an asset source. In Node the MCP server and CLI use the files in `sprites/`. Elsewhere, pass anything that can read those files:
```ts
import { setAssetSource, loadPalettes } from 'pixscii/core';
setAssetSource({
readJSON: (file) => fetch(`/pixscii/sprites/${file}`).then((r) => r.json()),
list: async (dir) => (dir === 'palettes' ? ['pico8.json', 'gameboy.json', 'grayscale.json'] : []),
});
await loadPalettes();
```
## Development
```bash
npm install
npm run dev # Start MCP server (stdio)
npm run build # Compile TypeScript
npm test # Run tests
```
```
src/core/ pure TypeScript, runs anywhere (exported as pixscii/core)
src/node/ sprites/ on disk, PNG encode and image import (sharp), CLI
src/mcp/ MCP server and tools
```
`src/core/boundary.test.ts` fails if anything in core imports a Node built-in, sharp, MCP or a file outside core.
See [ROADMAP.md](ROADMAP.md) for where pixscii is going: shapes, procedural landscapes and creatures.
## License
MIT
TDQS
Scored across 19 tools
Most tools are distinct, but the three animation tools (animate, sequence, animate_scene) have overlapping purposes, making it unclear which to choose for scene-level animation. Other tool boundaries are clear.
All tool names are single lowercase words, providing a consistent style. However, some names like 'get' and 'create' are generic and less self-explanatory, but the overall pattern is uniform.
With 19 tools, the surface is somewhat heavy, but each tool addresses a specific aspect of pixel art creation, composition, and animation. The count is near the upper bound of acceptable for the range of features.
The server covers drawing, editing, library access, composition, export, and animation, providing a comprehensive workflow. Missing features like canvas deletion or rotation are minor and do not block core usage.