pixscii

pixscii

LLM は絵を描けません。この MCP なら描けます。 AI エージェント向けのピクセルアートアニメーションツールキットです。

artscii の姉妹プロジェクトです。artscii がターミナルで ASCII アートを提供するのに対し、pixscii は AI エージェントに本格的なピクセルアート制作環境を提供します。キャラクターの生成、シーンのアニメーション化、スプライトの描画、PNG のエクスポートができます。オフラインで動作し、決定論的で、遅延はゼロです。

1 回の呼び出しでアニメーションを作成

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
}

ツールを 1 回呼び出すだけです。キャラクター 3 体、タイル状の背景、24 フレーム。9 ミリ秒。

LLM がシーンの説明を構造化された入力に変換します。pixscii はそれを即座に実行します。

クイックスタート

npx pixscii

または、MCP クライアントの設定に追加します。

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

ツール（25 種類）

高レベル — 1 回の呼び出しでシーン全体を作成

ツール	説明
animate_scene	テキストの説明 → キャラクター、背景、動きを含むアニメーションシーン

ソース — キャンバスを作成または読み込み

ツール	説明
create	塗りつぶし色を任意で指定できる、新しい空白のキャンバス
get	バンドルされたスプライトを編集可能なキャンバスに読み込む
character	プロシージャルなピクセルキャラクターを生成
convert	任意の画像（URL または base64）をピクセルアートに量子化
search	スプライトライブラリを検索
creature	マスクとシードから、無限に生成できる左右対称のロボット、エイリアン、動物を作成。または非対称の星雲を生成
being	24×24 の人、猫、エルフを、赤ちゃん、成人、老人の姿で生成
landscape	シードから風景を生成。時刻に応じた空、太陽または月、星、雲、山、丘、海、森、地面、雨を含む

変更 — キャンバスに描画

ツール	説明
pixel	個別のピクセルを設定（一括で最大 512 個）
line	2 点間にブレゼンハム線を描画
rect	長方形 — 輪郭のみ、または塗りつぶし
fill	指定した点から塗りつぶし（漏れ検出機能付き）
mirror	左半分を右半分に反転
shapes	図形をくっきりしたピクセルアートとして描画。対象：長方形、円、楕円、多角形、線、曲線。ディザリング塗りつぶしとグラデーションに対応
undo	直前の描画操作を取り消す

観察 — キャンバスの状態を確認

ツール	説明
inspect	キャンバスを 16 進数文字のグリッドとして表示

合成と出力

ツール	説明
sequence	フレームごとの位置を指定して、シーン内のアクターをアニメーション化
compose	複数のキャンバス／スプライトを重ねてシーンを合成
tilemap	タイルグリッドからマップを作成
spritesheet	フレームを 1 枚の PNG に結合（横／縦／グリッド）
animate	ピクセル単位の動きでスプライトをアニメーション化（待機、歩行、攻撃など）
export	キャンバスを拡大して PNG にレンダリング

パレット — 雰囲気に合わせて色を変更

ツール	説明
palettes	パレットと名前付きスロットを一覧表示（スキーマで絞り込み可能）
repalette	キャンバスのパレットを切り替え。スキーマが同じ場合はピクセルを維持し、それ以外の場合はスロット名または最も近い色に基づいて対応付け

図形：幾何図形を記述してピクセルを生成

LLM はピクセルをうまく配置できませんが、座標なら問題なく扱えます。shapes はアンチエイリアスなしでピクセルの中心に合わせて幾何図形をラスタライズするため、各ピクセルは 1 つのパレットインデックスになります。滑らかな塗りつぶしは、組織的ディザリングで表現します。

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 は、シーンスキーマに基づいてシードからシーン全体を作成します。つまり、1 つのシードで、どの雰囲気でも表示できる 1 つの場所が作られます。

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 に配置できます。

3 層の制御

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 で素早く下書きを作成します。細部を調整するには、より低いレイヤーに進みます。

例：1 回の呼び出しでシーンをアニメーション化する

→ 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

呼び出しは 2 回です。生成に 1 回、組み立てに 1 回。これで完成です。

例：スプライトを一から描く

→ 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

ヘックスグリッドプロトコル

各ピクセルは 1 文字です。エージェントは同じ文字セットを使って読み書きします。

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 トークンです。LLM はこれをソースコードのように読み取り、空間的に推論します。

同梱アセット

4 カテゴリーにわたる 22 個のスプライト：

• アイテム： sword、shield、potion、key、bow、coin
• タイル： grass、stone、water、wall、door、tree、sand、dirt
• エフェクト： slash、sparkle、explosion、heal
• UI： heart-full、heart-empty、arrow-up、cursor

648 種類のプロシージャルキャラクター： 4 種族（human、elf、dwarf、skeleton）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 種類のモーション： idle、walk、attack、hurt、bounce、blink

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

src/core/boundary.test.ts は、core 内から Node 組み込みモジュール、sharp、MCP、または core 外のファイルをインポートすると失敗します。

pixscii の今後の予定については、ROADMAP.md をご覧ください。形状、プロシージャルな風景、クリーチャーなどを予定しています。

ライセンス

MIT