Pixscii

pixscii

LLMs can't draw. This MCP can. A pixel art animation toolkit for AI agents.

Sister project of 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

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

npx pixscii

Or add to your MCP client config:

{  "mcpServers": {    "pixscii": {      "command": "npx",      "args": ["-y", "pixscii"]    }  }}

Tools (25)

High-Level — Full scenes in one call

Source — Create or load a canvas

Mutate — Draw on a canvas

Observe — Read the canvas state

Compose & Output

Palette — Recolor by mood

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:

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:

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.

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

npx pixscii import sprite.png --id my-sword --category itemsnpx 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:

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:

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

npm installnpm run dev      # Start MCP server (stdio)npm run build    # Compile TypeScriptnpm test         # Run tests

src/core/   pure TypeScript, runs anywhere (exported as pixscii/core)src/node/   sprites/ on disk, PNG encode and image import (sharp), CLIsrc/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 for where pixscii is going: shapes, procedural landscapes and creatures.

License

MIT