Skip to main content
Glama
README.md
# 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

A3.5/5.0

Scored across 19 tools

Disambiguation3/5

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.

Naming Consistency4/5

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.

Tool Count3/5

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.

Completeness4/5

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.

Maintenance

ActivityMaintained
ResponsivenessOutdated data