pixscii

pixscii

大模型不会画图，但这个 MCP 可以。 面向 AI Agent 的像素艺术动画工具包。

artscii 的姊妹项目。artscii 提供终端 ASCII 艺术，而 pixscii 为 AI Agent 提供完整的像素艺术工作台——生成角色、制作场景动画、绘制精灵图并导出 PNG。离线运行、结果确定、零延迟。

一次调用制作动画

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
}

一次工具调用。3 个角色、平铺背景、24 帧。耗时 9ms。

大模型将场景描述转换为结构化输入。pixscii 会立即执行。

快速开始

npx pixscii

或者添加到 MCP 客户端配置中：

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

工具（25 个）

高层工具 — 一次调用生成完整场景

工具	描述
animate_scene	文本描述 → 包含角色、背景和动作的动画场景

源 — 创建或加载画布

工具	描述
create	创建可选填充颜色的空白画布
get	将内置精灵图加载到可编辑画布中
character	生成程序化像素角色
convert	将任意图像（URL 或 base64）量化为像素艺术
search	浏览精灵图库
creature	使用遮罩和种子生成无穷无尽的对称机器人、外星人和小生物，或生成不对称星云
being	生成 24×24 的人物、猫或精灵，可选择婴儿、成人或老人形态
landscape	根据种子生成景观：按时段生成天空、太阳或月亮、星星、云、山脉、丘陵、海洋、森林、地面和雨

修改 — 在画布上绘制

工具	描述
pixel	设置单个像素（批量最多 512 个）
line	在两点之间绘制 Bresenham 直线
rect	绘制矩形 — 轮廓或填充
fill	从某一点开始进行泛洪填充（带有泄漏检测）
mirror	将左半边镜像到右半边
shapes	将几何图形绘制为清晰的像素艺术：矩形、圆形、椭圆、多边形、直线、曲线，并支持有序抖动填充和渐变
undo	撤销上一次绘制操作

查看 — 读取画布状态

工具	描述
inspect	以十六进制字符网格查看画布

合成与输出

工具	描述
sequence	使用逐帧位置在场景中为多个角色制作动画
compose	将多个画布/精灵图分层合成为场景
tilemap	根据图块网格构建地图
spritesheet	将多帧拼接为单张 PNG（水平/垂直/网格布局）
animate	为精灵图添加像素动画（待机、行走、攻击……）
export	将画布渲染为缩放后的 PNG

调色板 — 按氛围重新着色

工具	描述
palettes	列出调色板及其命名槽位（可按架构筛选）
repalette	将画布切换到另一调色板：相同架构会保留像素，其他架构则按槽位名称或最接近的颜色映射

形状：编写几何图形，生成像素

大模型不擅长放置像素，但能很好地编写坐标。shapes 会在像素中心栅格化几何图形，不进行抗锯齿，因此每个像素都是一个调色板索引。柔和填充通过有序抖动实现：

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" }
  ]
}

然后使用 repalette 切换到 scene-sea 或 scene-night，即可用另一种氛围呈现同一幅画面。在代码中：drawShapes(sprite, shapes, palette)。

根据种子生成景观

landscape 会根据场景架构中的种子构建完整场景，因此同一个种子对应同一处地点，可呈现为任意氛围：

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"] }

预设与场景调色板匹配：dawn、home、school、night、sea、storm、window、forest、dusk、stars。图层：天空（抖动渐变）、星星、太阳或月亮（带光晕，水面上还有闪光）、云、山脉（中点位移山脊）、丘陵（值噪声）、海洋（波浪）、森林（松树和圆形树木）、地面、雨。默认尺寸为 128×72。在代码中：landscape({ seed, preset })。

生物与角色

creature 会根据种子填充蒙版（身体、可能是身体、空白），清除多余像素，为其描边、从顶部打光并加上眼睛。类型包括：robot、alien、critter，以及 nebula（带有捕获星星的非对称噪声云）。being 会根据形状绘制不同生命阶段的人、猫或精灵：婴儿头大且没有腿，老人头发花白并拄着手杖，老年精灵拿着法杖，老猫的身体更圆、尾巴下垂。

creature { "seed": "voyager-7", "kind": "robot" }
being { "species": "elf", "stage": "old", "palette": "scene-forest" }

两者都使用场景架构，因此可以在同一调色板中放置在 landscape 上。

三层控制

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)

先用 animate_scene 快速生成草稿，再深入底层进行完善。

示例：一次调用完成场景动画

→ 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

只需两次调用：一次生成，一次组装。完成。

示例：从头绘制精灵图

→ 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

十六进制网格协议

每个像素对应一个字符。Agent 使用同一套字符集读取和写入：

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...

完整的 16x16 精灵图约需 80 个 token。大模型像阅读源代码一样读取它，并在空间层面进行推理。

内置资源

22 个精灵图，分为 4 类：

• **物品：**剑、盾牌、药水、钥匙、弓、硬币
• **图块：**草地、石头、水、墙、门、树、沙子、泥土
• **特效：**斩击、闪光、爆炸、治疗
• **UI：**heart-full、heart-empty、arrow-up、cursor

648 个程序生成的角色： 4 个种族（人类、精灵、矮人、骷髅）x 3 种盔甲 x 3 种武器 x 3 种头盔 x 6 种肤色。

**13 种调色板：**pico8（默认）、grayscale、gameboy，以及 10 种场景氛围（scene-dawn、home、school、night、sea、storm、window、forest、dusk、stars）

场景调色板共用一个架构：包含相同的 16 个命名槽位（ink、sky-top、sky-mid、sky-low、sun、cloud、far、mid、near、ground、water、foam、accent、skin、cloth、light）。使用这些槽位绘制一次，再使用任意场景调色板进行渲染，即可在另一种氛围中获得相同的图像。代码示例：SCENE.ground、slotIndex(palette, 'water')、remapPalette(sprite, from, to)。

**6 种动作类型：**待机、行走、攻击、受伤、弹跳、眨眼

CLI

npx pixscii import sprite.png --id my-sword --category items
npx pixscii export sword --scale 4 --out sword.png

在浏览器中使用：pixscii/core

所有绘制、组合和渲染功能都能在没有 Node 的环境中运行。pixscii/core 不包含 Node 内置模块、sharp 或 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);

内置精灵图、调色板和角色通过资源源加载。在 Node 中，MCP 服务和 CLI 使用 sprites/ 中的文件。在其他环境中，可传入任何能够读取这些文件的对象：

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();

开发

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

如果 core 中的任何内容导入了 Node 内置模块、sharp、MCP 或 core 以外的文件，src/core/boundary.test.ts 就会失败。

请参阅 ROADMAP.md，了解 pixscii 的发展方向：形状、程序生成的景观和生物。

许可证

MIT