Pixelbolt pixel art toolkit

Pixelbolt

AI エージェントが作成、確認、修正できるピクセルアートとスプライトアニメーションです。 Pixelbolt は編集可能な JSON レシピを、スプライト、タイル、アイコン、エフェクト、短いアニメーションに変換し、PNG スプライトシート、テクスチャアトラス、アニメーション PNG、GIF、動画エディター用のフレームとしてエクスポートします。エージェントはローカル MCP サーバーまたはコマンドラインから操作でき、同じレシピをローカルブラウザースタジオで開いて、再生や編集もできます。

英語 · 簡体字中国語 · 日本語

炎、煙、蒸気、爆発、魔法、水、蜂蜜、スライムは、実際の流体シミュレーションから生成されます。シミュレーションはお使いの CPU 上で 1 秒もかからずに実行され、各フレームを編集可能なパレットピクセルに変換します。シームレスなループにも対応しています（流体エフェクト）。

• 対象ユーザー： Claude、Codex、Cursor などのエージェントにピクセルアートを描画・修正させたいゲーム開発者、ゲームジャムチーム、ウェブや動画の制作者、また正確で再現性のある画像を必要とするエージェントを構築する人。
• こんな場合にお使いください： テキストとして編集可能な小さな 2D ゲームアセットが必要な場合です。エージェントはすべてのピクセルを読み戻し、残りを描き直すことなく 1 ピクセルまたは 1 フレームだけを修正できます。同じレシピを使えば、毎回同じ画像がレンダリングされます。
• こんな用途には向いていません： 絵画調、写真風、大きな画像の作成（1 フレームは最大 256 × 256 ピクセル、プロジェクト全体では最大 256 フレーム、合計 4,194,304 ピクセルです）、画像モデルによるアートの生成、GIF や Aseprite ファイルの編集（読み込めるのは 8 ビット RGB/RGBA PNG のみです）。
• 比較対象： aseprite-mcp、pixel-mcp、pixscii、pixelart-mcp、pixelforge-mcp、SpriteCook について、Pixelbolt での計測結果、各ツールのコードやドキュメントから確認した内容、各ツールを選ぶべき場面を紹介します：AI エージェント向けピクセルアート・スプライト MCP サーバー：7 種類を比較（2026 年 10 月 17 日確認）。炎、煙、爆発、水のエフェクトについては、Pixel FX Designer、SpriteMancer、Fluid FX、Pixel Composer、PHOSPHOR、BlastFX を比較しています：Pixel FX Designer の代替ツール：7 種類を比較（2026 年 10 月 19 日確認）。

試してみましょう。 Node.js 20 以降が必要です。それ以外にインストールするものはなく、API キーもネットワークサービスも不要です：

git clone https://github.com/skulitom/Pixelbolt.git
cd Pixelbolt
node bin/pixelbolt.js preview --open

エージェントに使わせましょう。 Claude Desktop では、最新リリースから pixelbolt.mcpb をダウンロードして開き（または「設定」→「拡張機能」からファイルをインストールし）、レシピとアートワーク用のワークスペースフォルダーを選んでから、エージェントに pixel_help を呼び出すよう依頼してください。Claude Code、Codex、Cursor、その他の MCP クライアントについては、MCP 経由でエージェントを接続するをご覧ください。Pixelbolt は公式 MCP レジストリに io.github.skulitom/pixelbolt として登録されています。 Pixelbolt は 0.8.0 まで PixelForge という名前でした。pixelforge コマンドは引き続きエイリアスとして機能し、レシピファイルの pixelforge-* 形式タグもそのままなので、既存のファイルやエージェントの設定は引き続き動作します。

ギャラリー · 流体エフェクト · クイックスタート · エージェントのセットアップ · MCP サーバー · ポータブルビルド · レシピリファレンス · コントリビューション · 関連ツール

仕組み

パレット、テキストグリッド、再利用可能なシンボル、描画操作を含む JSON レシピを作成します。透過 PNG、スプライトシート、アニメーション PNG、共有用 GIF、動画編集ソフト用の番号付きフレーム、さらにそれらを使用するためのメタデータとプレーヤーを生成します。ローカルのブラウザスタジオでレシピを確認、編集できます。

実行時の依存関係はゼロです。ビルド手順、API キー、画像モデル、ネットワークサービス、ネイティブグラフィックスライブラリは不要です。Node.js 20 以降が必要です。Windows、macOS、Linux で、チェックアウトしたソースから動作します。

動きのあるキャラクター

手足はボーン、胴体はマス、顔や小道具はグリッドとして作成します。相対ジョイントと二本ボーンのリーチによりアタッチメントをまとめて保持できます。待機、歩行、走行、ジャンプ、攻撃、被ダメージのテンプレートは、編集可能なポーズに展開されます。CLI、MCP、スタジオで、足の接地、地面との接触、ループのつなぎ目を確認できます。出力には既存のスプライトプレーヤーを使用します。

node bin/pixelbolt.js preview character.poses.json
node bin/pixelbolt.js compile character.poses.json --expand --out character-edit.poses.json
node bin/pixelbolt.js inspect character.poses.json --motion run --speed 48

ポーズと動きのリファレンス

ギャラリー

AI エージェントが Pixelbolt で描いた作品です。エージェントのスクリプトがレシピ、パーティクルソース、シーンを書き込み、Pixelbolt がすべてのスプライトをアトラス付きの透過シートにレンダリングします。各 240×135 の部屋をシーンとして再生し、GIF を書き出します。3 倍のサイズで表示しています。

さらに2つの部屋と制作方法

流体エフェクト

pixelforge-fluid ソースは、小規模で決定論的な流体シミュレーションを実行し、通常のパレットグリッドレシピにコンパイルします。浮力、渦度による旋回、冷却と散逸を伴う気体と、同じグリッド上の FLIP 粒子として表現される液体を扱います。液体は水のようにさらさらしたものから、蜂蜜のように粘り気のあるもの（途切れることのない流れや、ゆっくり沈む盛り上がり）、スライムのように弾力のあるもの（つぶれても元に戻り、形を保つ塊）まで表現できます。表示レイヤーは、順序付きディザリングを通じて密度、温度、速度、深度をパレットのグラデーションに割り当てるため、パレットにない色は現れず、ループするエフェクトは継ぎ目なくつながります。以下の各プリセットは、GPU もモデル呼び出しも使わず、ノート PC の CPU で 1 秒もかからずにコンパイルできます。表示倍率は 4 倍です。

node bin/pixelbolt.js compile examples/campfire.fluid.json --out output/campfire.json
node bin/pixelbolt.js gif output/campfire.json --scale 4 --out output/campfire.gif

12 種類のプリセットは examples/（*.fluid.json）にあります。エージェントは MCP の pixel_compile でコンパイルし、pixel_help のトピック fluid で形式を確認できます。Studio の Fluid lab（/fluid.html）では、同じコンパイラーをブラウザー上で実行できます。プリセットを選び、いくつかのスライダーを動かして、GIF、スプライトシート、レシピ、または編集したソースをダウンロードできます。流体エフェクトガイドでは、エミッター、火花、障害物、表示方法、ループ、粘性の高い流体（粘度、降伏応力、付着性）について説明しています。Web ページでは、createLiveFluid を使って同じシミュレーションをフレームごとにリアルタイムで実行でき、ポインターからの押し出し、噴出、エミッターのブーストを受け取ります（リアルタイム流体）。

はじめに

git clone https://github.com/skulitom/Pixelbolt.git
cd Pixelbolt
node bin/pixelbolt.js preview

http://127.0.0.1:4747 を開くか、--open を追加すると、既定のブラウザーが自動的に開きます。このポートが使用中の場合は、空いているポートが選ばれ、その番号が表示されます。--port N を指定するとポートが固定され、使用中の場合は失敗します。独自のレシピで始めるには、preview hero.pixel.json を実行します。森の精霊、キャンプファイヤー、コインを選び、JSON を編集して、アニメーションやスプライトシートを確認し、アセット ZIP をダウンロードできます。このスタジオには、再生速度の調整、フレーム選択、整数倍ズーム、ピクセルグリッド、オニオンスキン、パレットの確認、ソースの保存と読み込み、現在のアニメーションの GIF ダウンロード、ビデオエディター向けの連番フレーム、未保存の編集内容の復元、エラーメッセージのリアルタイム表示が備わっています。アセットとフォントはすべてローカルにあります。

または、ブラウザーを開かずにアセットを生成できます。

node bin/pixelbolt.js init hero.pixel.json
node bin/pixelbolt.js validate hero.pixel.json
node bin/pixelbolt.js inspect hero.pixel.json --out hero-frames.png
node bin/pixelbolt.js render hero.pixel.json --out output/hero

inspect はすべてのフレームのコンタクトシートを保存し、各フレームの表示時間を一覧表示します。--grid を追加すると、フレームをパレットキーのテキストとして読み取れます。--animation、--frames（名前または 'flash-*' のようなパターン）、--region を指定すると表示対象を絞り込めます。また、--step 2 --offset 1 を指定すると、2番目のセルから2つおきにセルを取り出します。これにより、ストロボの A フレームと B フレームを分けて読み取れます。validate hero.pixel.json --fps 30 を実行すると、そのフレームレートで動画のフレーム数に一致しない表示時間と、動画シーケンスが各アニメーションに与える影響も一覧表示されます。patch hero.pixel.json --changes fix.json は、指定した編集内容をプレビューし、変更されるピクセルをすべて報告します。--out を追加すると、新しいレシピを保存できます。gif hero.pixel.json --out hero.gif は、共有用に1つのアニメーションを GIF として保存します。ヘルプとプレビューサーバーを除き、コマンドの結果は JSON 形式です。エラーは stderr に出力され、終了コード 1 で終了します。ファイル名の代わりに - を指定すると、stdin から JSON を読み込みます。既存の出力ファイルは保護されます。置き換えるには --force を追加してください。必要に応じて npm link を実行し、pixelbolt コマンドを使うこともできます。npm install は不要です。

ジオラマ：3/4 視点のダンジョン部屋

手続き型で生成される「浮遊ジオラマ」ゲームのスタイルを取り入れた、オリジナルの3/4視点のトップダウン型ダンジョン部屋です。8ピクセルのタイル、正面を備えた壁の頂部、滝から水が注ぐくぼんだ池、苔、オブジェクト、たいまつ、そして攻撃で壺を壊す主人公が登場します。この部屋は1つのレシピで構成されており、tilemap オペレーションが隣接ルールに従って壁、壁面、崖、水、風化したレンガを配置します。苔は床の色に適用されたシード付きのバリューノイズです。影とたいまつの光はパレットの色調に沿って色を変化させるため、シーンの照明やテーマを変えても31色を維持できます。

node bin/pixelbolt.js preview showcase/diorama/art/room.scene.json

夜になると、各たいまつとろうそくは配置場所に応じた光を放ち、それぞれのシードに基づいて揺らめきます。壺の近くの光は攻撃の合図に合わせて点滅します。これは、パレットの色だけを正確に使った動くシーンライトです。

詳細と画像を見る · 実現可能性レポート：このスタイルが Pixelbolt に求めたもの

アート品質のワークフロー

アートのワークフローでは、シルエット、明度、ネイティブサイズでの確認、アニメーションに対応したオニオンスキン、マスクを使った部分修正、作成したパーツとアタッチメント、保護された再構築オーバーレイ、シーン、PNG 形式での受け渡し、位置合わせされたノーマルパスとエミッシブパスについて説明します。チェックに合格しても、アートの品質が保証されるわけではありません。すべてのフレームをネイティブサイズで確認し、再生してチェックしてください。

node bin/pixelbolt.js inspect examples/forest-spirit.json --animation idle --view onion --native --diagnostics
node bin/pixelbolt.js preview examples/forest-spirit-lit.scene.json

エージェント向け

Pixelbolt を使うと、編集可能な JSON からピクセルスプライト、タイル、アイコン、エフェクト、短いアニメーションを作成・修正できます。シェルにアクセスできる場合は CLI を、クライアントがツールに対応している場合は Model Context Protocol（MCP）サーバーを選択してください。どちらも同じレンダラーを使用し、ローカルで動作します。

エントリーポイント	目的
llms.txt	エージェント向けの直接リンクを含む簡潔なドキュメント索引
ピクセルアートスキル	再利用可能な作成および目視検査のワークフロー
作成ガイド	レシピのフィールド、描画操作、制限
JSON Schema	機械可読なレシピ構造
サンプル	森の精霊、キャンプファイヤー、コイン、祠の完全なレシピ、ピクセル文字を使ったキャプション、回転する剣の振り、パーティクルエフェクトのソース、12 種類の流体プリセット
AGENTS.md	ツールキットに貢献するエージェント向けの手順

作成ガイドまたは MCP の pixel_help から始めてください。レシピを作成して検証し、pixel_inspect または pixelbolt inspect ですべてのフレームを確認します。次に、対象を絞ったパッチで修正してから、新しい出力ディレクトリにレンダリングします。検証では形式を、画像検査ではアートを確認します。

短いアニメーション

{
  "version": 1,
  "name": "slime",
  "width": 8,
  "height": 8,
  "palette": { "g": "#72b58d", "e": "#20383f" },
  "frames": [
    {
      "name": "rest",
      "duration": 180,
      "ops": [{ "op": "grid", "x": 1, "y": 3,
        "rows": [".gggg.", "ggeegg", "gggggg", ".gggg."] }]
    },
    { "name": "up", "from": "rest", "translate": [0, -1], "duration": 180 }
  ],
  "animations": { "bounce": { "frames": ["rest", "up"] } }
}

テキストグリッドの各文字はパレットの色を指定します。. と空白はピクセルを変更しません。フレームの継承により、小さな変更を簡潔に記述できます。レンダリングは決定的で、整数のピクセル座標を使用します。

エクスポートバンドル

ファイル	用途
name.png	列数、パディング、整数スケールを設定できる RGBA PNG スプライトシート。sheet.trim を指定すると、可視範囲に合わせてパッキングされます
name.atlas.json	TexturePacker 形式の JSON ハッシュ。矩形、トリミングオフセット、ソースサイズ、ピボット／アンカー、名前付きポイント、フレーム時間、名前付きアニメーションを含みます
frames/*.png	各フレームを透過 PNG として保存します
animations/*.png	各アニメーションを APNG として保存し、透過、フレーム時間、ループ動作を保持します
name.css	CSS アニメーションクラス。複数行のシートと、フレームごとに異なる時間に対応します
player.js	再生、一時停止、再開、名前付きアニメーションに対応する、依存関係のない小型の Canvas プレーヤーです。ゲーム向けに loadSpriteSheet、frameAt、drawFrame も備えています
name.pixel.json	編集可能なソースレシピです
preview.html	ブラウザーで直接開ける単体のプレビューです

APNG ファイルでは、意図的に .png 拡張子を使用します。レシピではパレットファイルを共有でき（"palette": { "$ref": "palette.json" }）、パレットサイクリング用にフレームごと、またはほかの部分に影響を与えずにフラッシュさせるためにレイヤーごとに色置換キーを設定できます。テンプレートシンボルや先行フレームから矩形をコピーする（色を正確に置換するオプションもあります）、レイヤーに輪郭を付ける（外側、内側、または両方。リムライトやドロップシャドウ用の方向マスクにも対応します）、キャンバスに固定した Bayer、カスタム、シード付きの非周期ノイズ、または塊状の値ノイズパターンで色間をディザリングする、パレットから外れずにパレットランプに沿って陰影を付ける（ramps と shade 操作）、tilemap 操作でキャラクターマップ全体を描画する（バリアント、重み、近傍ルールに対応します）、シード付きの書き換えルールでコケやひび割れなどのディテールを増やす、といったことができます。pixelbolt autotile を使って、47 タイルのブロブまたは 16 タイルのカーディナルオートタイルセットを、オプションで形状バリアント付きでコンパイルできます。作成ガイドとアートワークフローを参照してください。

これらのアイデアのいくつかは、テキストレシピ向けに調整した Pixel Composer のノードセットに由来します。パッチでは De-Corner／De-Stray によるクリーンアップを提案でき、検査診断ではフレームごとに変更対象をカウントします。ポーズソースでは、RotSprite 形式の再サンプリングを使ってパーツを任意の角度に回転させ、色を増やさずに編集可能なシンボルを作成し、イージングされた中間フレームをトゥイーンします。シーンの軌跡にもイージングが適用されます。pixelforge-fx ソースは、シード付きパーティクルエミッターを pixelbolt compile で通常のレシピにコンパイルします。pixelforge-fluid ソースも流体シミュレーションを同様にコンパイルし、pixelforge-normals ソースは任意のレシピからライティング用の法線パスを生成します。これはフレーム単位で位置を合わせた編集可能なレシピで、シーンライティングやエンジンの法線マップに使用できます（精霊の例、小さな夜のシーンでのライティング、詳細）。祠、ブランコ、エフェクトを参照してください。ロスレスの非インターレース 8 ビット RGB／RGBA PNG のインポートに対応しており、拡大縮小されていないアトラスのタイミングメタデータも任意で利用できます。相互運用の制限を参照してください。GIF のインポート、Aseprite のネイティブファイル、自動量子化は、現時点では対象外です。ソースは編集可能な JSON のまま保持されます。

共有用 GIF

APNG はアルファ値を完全に保持し、タイミングも正確ですが、多くのチャット、フォーラム、ストアのページでは GIF しかアニメーション表示できず、ピクセルをくっきり拡大できません。pixelbolt gif は、1つのアニメーションを整数倍に拡大して GIF として書き出します（デフォルトでは、長辺が 256 ピクセル以内に収まる最大倍率です）。

node bin/pixelbolt.js gif hero.pixel.json --out hero.gif
node bin/pixelbolt.js gif hero.pixel.json --animation blink --scale 8 --background "#17191d" --out hero-blink.gif

色は正確です。量子化やディザリングは一切行わず、256 色を超えるフレームは近似せずにエラーとして拒否されます。GIF は半透明を扱えないため、アルファ値が 50％未満のピクセルは透明になり、それ以外は不透明になります。代わりに --background（パレット名または不透明な16進数の色）を指定すると、すべてのピクセルを1色に合成でき、柔らかい影を保てます。フレーム時間は、余りを次のフレームに繰り越しながら GIF の10ミリ秒単位に丸められ、20ミリ秒未満の場合は20ミリ秒に引き上げられます。透明ピクセルは、ffmpeg や Pillow を含むすべてのビューアで透明なままです。これらのツールは、透明なインデックスが指定されていない場合、消去されたフレームを背景色で塗りつぶします（各フレーム単独で256色を使い、指定できる透明色がないまれなフレームは、注記に表示されます）。JSON の結果にある notes には、これらの処理が行われた内容が記載されます。スタジオの GIF ボタンは、現在のズーム倍率でアニメーションをダウンロードします。MCP の pixel_render では "gif": {} を指定します。エクスポートバンドル自体に変更はありません。

pixelbolt gif-frames は、sequence フォルダーや動画・エフェクトツールが書き出したフレームのように、連番の PNG フレームが入ったフォルダーから、同じルールで GIF を作成します。

node bin/pixelbolt.js gif-frames shots/prism --fps 25 --out prism.gif
node bin/pixelbolt.js gif-frames shots/prism --fps 30 --loops 3 --background "#101828" --prefix prism_ --out prism-3x.gif

ファイルは番号順に読み込まれます（prism_0001.png、prism_0002.png …）。番号の欠落、フォルダー内の他の PNG、2つのシーケンスが混在するフォルダー（--prefix でどちらかを選択）は報告され、推測による処理は行われません。各フレームの色は正確に保たれます。256色を超えるフレームはファイル名を示して拒否されます。フレームごとに色が異なる場合は、各フレームが独自のカラーテーブルを持つため、1フレームあたり約120色、合計4,345色を使う 1080 × 1080 の48フレームのループも、パレット生成ツールなら一部の色がずれてしまうところ、ピクセル単位で完全に復元できます。フレーム k は、GIF のセンチ秒単位に丸めた k × 1000 / fps ミリ秒から始まります。25 fps では1フレーム40ミリ秒、30 fps では30ミリ秒と40ミリ秒が交互になり、ループ全体の長さが保たれます。50 fps を超える場合は遅延が20ミリ秒に引き上げられ、新しい長さが注記に表示されます。--loops は再生回数です。0（デフォルト）は無限ループです。透明部分がない場合、最初のフレーム以降は変更された部分だけが保存されます。PNG は8ビットの RGB または RGBA で、すべて同じサイズである必要があります。ループには最大134,217,728ピクセルを含められます（115フレーム、各1080 × 1080）。

ピクセルテキスト

text オペレーションは、組み込みのピクセルフォントでタイトル、キャプション、ラベル、カウンターを描画します。印字可能な ASCII、西ヨーロッパ言語のアクセント付き文字（À–ÿ、Œ œ Š š Ž ž Ÿ）、€ £ © — … “ ” „ « » などの一般的な記号に対応し、大文字は高さ7ピクセルで、文字幅は可変、数字の幅は等幅です。大文字のアクセント記号は y の上2行に表示されます。

{ "op": "text", "x": 120, "y": 8, "text": "GAME OVER\nscore 12480", "color": "ink", "align": "center" }

align は、x を左端、中央、右端のどこにするかを指定します。spacing、lineHeight、scale、回転で調整でき、さらに outline を指定すると読みやすい輪郭が付きます。キャンバスからはみ出したテキストは、ほかの描画と同様にクリッピングとして報告されます。フォントにない文字は、その文字を示すエラーになります。examples/caption.json は、下三分の一にタイトルを表示してタイプ入力する例です。node bin/pixelbolt.js sequence examples/caption.json --fps 30 --size 1080p --align bottom --offset 0,-64 --out shots/caption を実行すると、1080p の画像の下部に配置される81フレームが生成されます。

動画編集用フレーム

動画編集ソフトではAPNGがアニメーション再生されず、GIFではアルファが失われ、タイミングも正確に保てません。pixelbolt sequence は、動画編集ソフトで読み込める形式で出力します。動画のサイズに合わせたキャンバス上に、一定のフレームレートで連番のPNGを1フレームにつき1枚書き出し、アルファも保持します。

node bin/pixelbolt.js sequence hero.pixel.json --fps 30 --size 1080p --out shots/hero
node bin/pixelbolt.js sequence examples/effects.fx.json --animation sparks --fps 29.97 --size 4k --scale 16 --align bottom --offset 0,-200 --out shots/sparks
node bin/pixelbolt.js sequence room.scene.json --fps 24 --size 1080p --fit cover --out shots/room

• タイミング。 各動画フレームには、そのフレームの開始時点で有効なポーズが表示されます。--fps には24、25、30、50、60、NTSCのレートである23.976、29.97、59.94（長いクリップでもずれないよう、24000/1001、30000/1001、60000/1001として正確に保持）、または分数を指定できます。--loops n または --seconds s で長さを指定し、--step 2 で2コマ打ちにします。ループするアニメーションは繰り返し再生され、1回だけ再生するアニメーションは最後のポーズで停止します。
• サイズ。 --size には 720p、1080p、1440p、4k、vertical（1080×1920）、square、または WIDTHxHEIGHT を指定します。スプライトは再サンプリングせず、整数倍に拡大します。キャンバスに収まる最大の倍率が使われますが、--scale で最大256まで指定することもできます。--align（top-left … center … bottom-right）と --offset x,y で配置します。--fit cover を指定すると、キャンバスを覆う最小の整数倍を使い、はみ出した部分を切り抜きます。この場合、--align で残す部分を選択し、結果の placement.visible に元画像のどの列と行が見えているかが示されます。--size を指定しない場合、キャンバスは --scale 倍したスプライトのサイズになります。--background を指定すると、アルファを保持する代わりに不透明色を合成します。
• ソース。 レシピ（--animation で選択）、ポーズ、自動タイル、またはエフェクトのソースは、読み込み時にコンパイルされます。シーンはショットとして瞬間ごとにレンダリングされ、見た目が同じ瞬間には同じPNGが使われます。192×108または240×135ピクセルのシーンは、倍率をそれぞれ10倍または8倍にすると1080pにぴったり収まります。それ以外のサイズのシーンは、余白を含めてシーン固有の背景色の上に中央配置されるため、ショットは端から端まで不透明になります。または、--fit cover でキャンバス全体を埋めることもできます。
• 出力内容。 新しいフォルダーに、name_0001.png から始まる連番ファイル、フレームレート（分数）、フレーム数、サイズ、配置、ループ情報、各ポーズのタイミングを記録した sequence.json、および読み込み方法を説明する README.txt が作成されます。結果の notes には、フレームグリッドによって生じた変化が記録されます。長さが変わったポーズ、動画フレームより短く一度も表示されないポーズ、クリップがループと同じ位置で正確に終わるかどうか、また終わる場合はそのために必要なループ回数が示されます。
• 動画ファイル1本で出力する場合。 Pixelboltは動画をエンコードしません。フォルダー内のREADMEとJSONの結果には、アルファ付きProRes 4444 .mov 用の正確な ffmpeg コマンドと、背景がある場合はロスレス4:4:4のH.264 .mp4 用のコマンドが記載されます。H.264は通常、2 × 2ピクセルごとに色を1つだけ保存する（4:2:0）ため、プレーヤーが補間すると、倍率にかかわらずピクセルの輪郭がにじみます。4:4:4ではすべての色が保持され、ピクセルアートの場合はファイルサイズも大きくなりません。ただし、QuickTime、Safari、Windows標準のプレーヤーでは再生できない場合があります。そのため、キャンバスの縦横が偶数の場合は、h264Compatible によって4:2:0のファイルも用意されます。ffmpeg 7では、ProResコマンドはアルファを正確に保持し、色の誤差を255段階中2以内に抑えます。H.264コマンドでは色の誤差が1以内になります。ffmpegがインストールされている場合、scripts/verify-exports.py で同じ検証を再実行できます。

編集ソフトではファイルをイメージシーケンスとして読み込み、クリップのフレームレートを設定してください（ファイルにはフレームレートが記録されていません）。クリップの拡大率は100%のままにしてください。編集ソフト側で拡大するとピクセルがぼやけます。シーケンスは最大18,000フレーム、キャンバスは一辺最大4096ピクセルです。MCPの pixel_render と pixel_scene では、同じオプションを指定した "sequence": { "fps": 30, "size": "1080p" } を指定できます。

スタジオの Frames ボタンを押すと、画面に表示中のアニメーションと同じファイルがZIPでダウンロードされます。ダイアログには、選択したフレームレートとサイズに対応する pixelbolt sequence コマンドとMCPの sequence 引数も表示されるため、エージェントはブラウザーを使わずに同じ書き出しを再現できます。

MCP経由でエージェントを接続する

Claude Codeプラグイン。 コマンドを1つ実行するだけで、クローンせずにMCPサーバーとピクセルアートスキルをインストールできます（Claude Code 2.1.292以降）。

claude plugin install pixelbolt --marketplace skulitom/Pixelbolt

セッション内では、/plugin install pixelbolt --marketplace skulitom/Pixelbolt を実行すると、Claude Code 2.1.275 から同じ操作を行えます。古いバージョンでは、まず claude plugin marketplace add skulitom/Pixelbolt でマーケットプレイスを追加してから、claude plugin install pixelbolt@pixelbolt を実行してください。このプラグインは、Claude Code で開いたプロジェクトフォルダー内で、Node.js（20 以降）を使って独自の bin/pixelbolt.js のコピーを実行します。ファイル参照はそのフォルダー内で解決され、エクスポート先はそのフォルダーの output/ になります。インストール後、Claude Code を再起動してください。

その他の MCP クライアント。 まずリポジトリをクローンしてから、エージェントの MCP 設定にサーバーを追加します。/absolute/path/to/Pixelbolt をチェックアウト先の絶対パスに置き換えてください。Windows では、たとえば C:/DEV/Pixelbolt のようにスラッシュを使用してください。

{
  "mcpServers": {
    "pixelbolt": {
      "command": "node",
      "args": [
        "/absolute/path/to/Pixelbolt/bin/pixelbolt.js",
        "mcp",
        "--out",
        "/absolute/path/to/Pixelbolt/output"
      ]
    }
  }
}

TOML を使用するクライアントの場合：

[mcp_servers.pixelbolt]
command = "node"
args = ["/absolute/path/to/Pixelbolt/bin/pixelbolt.js", "mcp", "--out", "/absolute/path/to/Pixelbolt/output"]

8 つのツールは次のとおりです。

• pixel_help：簡単なクイックスタート（レシピ形式、操作、ツール、ワークフロー、約 2,000 トークン）を表示します。topic を指定すると、完全版の作成ガイド（guide）、アートのワークフロー（workflow）、レシピスキーマ（schema）、完全なサンプル（example）、または poses、scenes、autotile、fx、fluid、normals の各スキーマを表示します。
• pixel_validate：{ "project": ... } を検証し、アセットをエクスポートせずにレシピのリビジョンを保存します。クリップされた位置をすべて報告します。"fps": 30 を指定すると、frameGrid、その動画フレームグリッドから外れる時間、およびシーケンスが各アニメーションに与える影響を追加します。
• pixel_inspect：コンタクトシート、正確な領域グリッド、シルエット／グレースケール／オニオンスキン表示、継ぎ目の証拠を含む 3×3 タイルの反復、ネイティブサイズ、名前付きレイヤーの分離、保存済み参照との比較、参考情報としての診断、コンタクトシートと明示的なポーズメタデータを含むモーションレビューを提供します。frames では *／? パターンを使用でき、step／offset では n 個ごとにセルを表示できます。また、省略箇所を確認できる、任意の上限付きサンプルにも対応します。レシピのリビジョンを保存します。
• pixel_patch：対象を絞った set、insert、remove、paint 編集を適用します。たとえば、{ "paint": "frames[blink]", "value": [{ "x": 9, "y": 7, "color": "k" }] } は、すべてのレイヤーを合成した後の最終キャンバス座標でピクセルを修正します。transparent を指定すると消去します。ピクセルが変更されたフレームをすべて返し（小さな編集では正確なピクセルも返します）、編集前後の PNG を返します。ソースは変更されず、編集が成功すると新しいリビジョンが作成されます。
• pixel_render：{ "project": ... } をレンダリングし、各フレームのセル名とタイミングが記載された PNG コンタクトシートに加えて、出力フォルダー、その主要ファイル、フレーム数／アニメーション数を返します（listFiles: true を指定するとすべてのファイルを一覧表示します）。再生順でシーケンスをプレビューするには、"animation": "idle" を追加します。エクスポートされた APNG と HTML プレビューではアニメーションを再生できます。"gif": {}（または { "scale": 8, "background": "#17191d" }）を追加すると、アルファ値やタイミングの変更に関する注記とともに、各アニメーションを gifs/ に GIF として書き出します。また、"sequence": { "fps": 30, "size": "1080p" } を追加すると、動画編集ソフト用に 1 つのアニメーションを連番 PNG フレームとして sequence/ に書き出します。呼び出すたびに、設定済みの出力ディレクトリ内に新しいフォルダーを作成します。
• pixel_compile：pixelforge-poses ソース（ボーン、質量、相対ジョイント、リーチターゲット、編集可能なモーションテンプレートを含む）、pixelforge-autotile テンプレート、pixelforge-fx パーティクルソース、pixelforge-fluid ソース（シミュレーションによる煙、炎、爆発、魔法、水）、または pixelforge-normals ソース（レシピまたはリビジョンから生成した法線パス）をレシピのリビジョンにコンパイルし、コンタクトシートと任意のメタデータを返します。
• pixel_scene：pixelforge-scene マニフェスト（オートタイルの凡例と隣接ルールを含むタイルマップ、名前付きキュー、シーケンス、軌道、アタッチメント、地面のソート、シェードの配置、ランプ式または乗算式のライティング、パレットテーマ）を任意の時点でレンダリングしてエクスポートするか、sequence を使ってショットを連番 PNG フレームとして書き出します。アセットにはリビジョンを指定できます。
• pixel_import：base64 またはサーバーのルート内にあるファイルで指定したネイティブ解像度の PNG を、ロスレスのレシピリビジョンとしてインポートします。 pixel_patchは、コンパクトなgrid、マスク付きのmove、領域単位のrecolor、二重になった角や余分なピクセルの修正案を作成するcleanupもサポートしています。対象範囲にはframeまたはinheritedを明示でき、保存済みの修正オーバーレイ（overlay）を適用できます。大きなpixel_renderのプレビューは、有効なエクスポートを妨げないよう、合計・表示・省略のメタデータとともにサンプリングされます。エクスポートされるアニメーションは完全なままです。パレットとシーンファイルの参照先はサーバーの--root（デフォルト：作業ディレクトリ）内に解決されます。リクエストの上限は16 MiBで、サイズ超過のリクエストにはエラーが返されますが、サーバーは停止しません。

レシピは一度だけ送信します。レシピツールが正常に応答すると、他のツールがprojectの代わりに使えるrevision IDが含まれます。そのため、パッチを含む後続の呼び出しでレシピを再送信する必要はありません。検証、確認、パッチ適用、レンダリングでは、<MCP --out directory>/.revisions/に不変のスナップショットが保存されます。同じディレクトリを使えば、アセットをエクスポートする前でも、再起動後にスナップショットを利用できます。絶対パスの--outを推奨します。以前のリビジョンは取り消し用のポイントとして残ります。以前にレンダリングしたリビジョンは、保存済みのバンドルレシピから復元できます。レンダリング時には、アセットと同じ場所にもレシピが保存されます。

サーバーは、初期化、バージョンネゴシエーション、ping、ツールの検出と呼び出しに対応する、改行区切りのstdio MCPを実装しています。プロトコルバージョン2024-11-05、2025-03-26、2025-06-18、2025-11-25をサポートしています。HTTPトランスポートや外部サービスは使用しません。MCP stdio仕様を参照してください。

エージェントはCLIを直接使用することもできます。再利用可能なエージェントスキルとオーサリングリファレンスでは、フォーマット全体を説明しています。schema.jsonはエディターの補完と構造検証に利用できます。ラスターライザーはさらに、参照、行幅の一致、リソース制限も検証します。

Web アプリでの使用

エクスポートしたフォルダーをアプリケーションで配信します。

<canvas id="sprite"></canvas>
<script type="module">
  import { SpritePlayer } from './assets/player.js';
  const player = await SpritePlayer.load(
    document.querySelector('#sprite'),
    './assets/forest-spirit.atlas.json',
    { scale: 4 }
  );
  player.play('idle');
  // player.pause(); player.resume(); player.destroy();
</script>

または、CSSだけを使用します。

<link rel="stylesheet" href="assets/forest-spirit.css">
<span class="pf-forest-spirit pf-forest-spirit-idle" role="img" aria-label="Forest spirit"></span>

CSSは、視差効果を抑える設定に対応しています。Canvas APIで自動再生するかどうかは、アプリケーション側で決定します。SpritePlayer.loadのアトラスパスは、アトラスURLを基準に解決されます。

1つのキャンバスに多数のスプライトを描画するゲームでは、同じモジュールのヘルパーを使用できます。drawFrameは、レシピでアンカーが宣言されている場合はそれを基準にフレームを配置し、トリミングされたフレームを元のオフセットに復元して、小数の位置を整数ピクセルにスナップします。そのため、サブピクセル速度で移動するスプライトでも、エッジがくっきり保たれます。

<script type="module">
  import { loadSpriteSheet, frameAt, drawFrame } from './assets/player.js';
  const hero = await loadSpriteSheet('./assets/hero.atlas.json'), context = canvas.getContext('2d');
  requestAnimationFrame(function draw(time) {
    context.clearRect(0, 0, canvas.width, canvas.height);
    drawFrame(context, hero, frameAt(hero.atlas, 'walk', time), 64, 96, { scale: 3 }); // (64, 96) is where the anchor lands
    requestAnimationFrame(draw);
  });
</script>

ゲームエンジンでは、アトラスの矩形または個別のPNGを使用してください。規則的なグリッドを使うインポーターでは、sheet.paddingを0に設定し、エクスポートされたフレーム寸法を使用してください。Phaserはload.atlasを介してJSONハッシュ形式のフレームレイアウトを読み込めます。名前付きアニメーションシーケンスは、追加のanimationsフィールドにあります。ゲーム統合に関する注意事項を参照してください。

JavaScript API

import { renderProject, inspectProject, patchRecipe, compareProjects, createBundle, writeBundle, compileEffects, compileFluid, createLiveFluid, animationGIF, folderGIF, frameGrid } from './src/index.js';

const project = renderProject(recipe); // RGBA buffers, durations, warnings
const view = inspectProject(project, { grid: true }); // contact sheet RGBA, palette-key grids
const { recipe: next, edits } = patchRecipe(recipe, [{ set: 'frames[idle].duration', value: 120 }]);
const report = compareProjects(project, renderProject(next)); // changed pixels, timing, before/after RGBA
const bundle = await createBundle(recipe);
await writeBundle(bundle, './output/my-sprite');
const { recipe: effects } = compileEffects(fxSource); // seeded particles baked into an ordinary recipe
const { recipe: fire, metadata } = compileFluid(fluidSource); // a fluid simulation baked into palette grids
const { rgba, keys } = createLiveFluid(fluidSource).push({ x: 8, y: 20, vx: 2 }).step().render(); // the same simulation, live
const gif = animationGIF(project, 'idle', { scale: 8 }); // { data, width, height, notes, ... }
const loop = folderGIF('shots/prism', { fps: 25 }); // GIF from numbered PNG frames; framesGIF takes RGBA frames
const grid = frameGrid(project, 30); // durations off a 30 fps video frame grid

src/core.js、src/craft.js、src/font.js、src/patch.js、src/fx.js、src/fluid.js、src/gif.jsはブラウザーと互換性があり、Nodeのインポートはありません。Node専用のエクスポーターは、圧縮とファイル出力に標準ライブラリを使用します。スタジオはCLIおよびMCPサーバーと同じレンダラーを共有しています。

開発と検証

npm test
npm run demo

テストでは、ピクセル、アルファブレンディング、継承、変換、塗りつぶし、テキストとフォント、ディザリング（バリューノイズを含む）、パレットのグラデーションとシェーディング、輪郭、書き換えルール、クリーンアップ、回転、トゥイーン、パーティクルエフェクト、流体シミュレーション（プリセットごとのゴールデンレシピ、パレットのみの出力、ループの継ぎ目）、タイルマップとルールタイル、シーンキュー、アタッチメントとソート、スキーマの整合性、パッキング、タイミング、PNG/APNG の構造、GIF の構造とデコード、動画のフレームタイミングと配置、検査シートとグリッド、パッチ適用と比較、リビジョン、上書き保護、CLI の標準入力／エラー、MCP 呼び出し、Canvas ランタイム、ローカルサーバー、ポータブル版 Windows ビルドを網羅しています。node scripts/qa-studio.mjs は実際のブラウザー（インストール済みの Edge または Chrome、ヘッドレスモード、一時プロファイル、Node.js 22 以降）でスタジオを操作し、すべてのサンプル、ライブ編集、壊れたレシピ、プレビューコントロール、Save、Open、Export、ディスクに保存される GIF のダウンロード、下書きの復元、キーボード操作、幅の狭いウィンドウと広いウィンドウ、そしてリクエストがコンピューター外へ送信されないことを確認します。任意の独立検証には Pillow と Python の ZIP リーダーを使用します。npm run demo の後に python scripts/verify-exports.py を実行してください。このスクリプトは GIF（PNG フォルダーから作成したものを含む）と画像シーケンスもデコードし、すべてのピクセル、遅延時間、ループフラグを比較します。また、ffmpeg がインストールされている場合は、シーケンスの ffmpeg コマンドを実行します。

スタジオは 127.0.0.1 にバインドし、明示的に許可されたアセットのみを配信し、外部の Host/Origin ヘッダーを拒否し、HTTP API 経由で書き込みを行うことはありません。保存されていない編集内容は、ブラウザー独自のストレージにスタジオのアドレスごとに単一の下書きとして保持され、次回のアクセス時に復元するかどうかが提示されます。下書きの内容がサーバーに送信されることはなく、レシピを保存するには引き続き Save JSON を使用します。ブラウザーのストレージはアドレスごとに分かれているため、あるポートで作成した下書きは別のポートでは表示されません。プロジェクトのサイズは、256×256 ピクセル、256 フレーム、ソースピクセル数 4,194,304、アトラスピクセル数 16,777,216 に制限されており、描画およびエクスポートの処理量にも上限があります。小さなスプライト、エフェクト、タイル向けに設計されています。

Pixelbolt Studio：ポータブルビルド

scripts/build-studio.mjs は、Node.js、git、または管理者権限を持たないユーザー向けに、ツールキット、公式の Node.js 24 LTS ランタイム、少数の小さなランチャースクリプトをシステムごとに 1 つのアーカイブにまとめます。64 ビット Windows 用の ZIP と、Linux（x64 および ARM64）および macOS（Apple シリコンおよび Intel）用の実行権限を保持した .tar.gz です。何もインストールされず、フォルダーを削除すればすべて削除されます。

	Studio	コマンドライン	エージェントを接続
Windows	Pixelbolt Studio.cmd をダブルクリックするか、レシピをその上にドラッグします	pixelbolt.cmd	Connect your agent.cmd
macOS	Pixelbolt Studio.command をダブルクリックするか、./pixelbolt-studio [recipe] を実行します	./pixelbolt	Connect your agent.command または ./connect-your-agent
Linux	./pixelbolt-studio [recipe]	./pixelbolt	./connect-your-agent

Studio ランチャーは pixelbolt preview --open です。ループバックのポート 4747 でデフォルトのブラウザーを開きます。ポート 4747 が使用中の場合は、空いているポートを使います（通常のポートを使うことで、Studio のドラフト復元機能がドラフトを再び見つけられます）。接続ヘルパーは、Claude Code、Claude Desktop、Codex、Cursor 用の MCP 設定を、そのフォルダーのパスを使って出力します。また、システムのシェル向けに記述された 1 行の claude mcp add および codex mcp add コマンドも出力します。ヘルパー自体が設定ファイルを編集することはありません。

node scripts/build-studio.mjs                       # this machine's own target, into dist/
node scripts/build-studio.mjs --target all          # win-x64, linux-x64, linux-arm64, darwin-arm64, darwin-x64
node scripts/build-studio.mjs --target all --check  # rebuild and compare with the archives in dist/
node scripts/verify-studio.mjs dist/PixelboltStudio-<version>-<target>.zip   # or .tar.gz

どのマシンでもすべてのターゲットをビルドでき、各アーカイブには .sha256 ファイルとファイルごとのマニフェストが付属します。アーカイブには、npm pack が出荷するファイル（app/ 内）、ランタイム、および packaging にあるそのシステム用のファイルだけが含まれます。デモ、テスト、開発用スクリプトは含まれません。ランタイムはビルドスクリプト内でバージョンと SHA-256 により固定され、初回のビルド時に nodejs.org からダウンロードされます（各 36～58 MB、dist/.cache にキャッシュされます。すでに手元にあるコピーを使うには --node-archive <file> を指定します）。変更を加えずに同梱され、不一致があるとビルドは停止します。アーカイブ内の BUILD-INFO.txt には、Pixelbolt のバージョン、ソースのコミット、ターゲット、ランタイムのハッシュが記載されます。--allow-dirty で開発ビルドと指定しない限り、出荷対象ファイルに未コミットの変更があるとビルドは拒否されます。また、リリースビルドでは作業コピーではなく、コミット自体から出荷対象の全ファイルを取得します。どこでビルドしても、同じコミットからは同じファイル一覧とファイルごとのハッシュが生成されます。ビルドするマシン用のランタイムが固定されている場合、パッケージ作成はそのランタイムで実行されるため、どのシステムでビルドしてもアーカイブはバイト単位で同一になります。すべての CI ランナー（Windows、x64 および ARM64 の Linux、macOS）が 5 つすべてをビルドし、それぞれのハッシュを出力します。

verify-studio.mjs は、システム標準のツールを使って、パスに空白と非 ASCII 文字が含まれるフォルダーにアーカイブを展開し、PATH に Node.js も git もない状態で実行します。ランチャー（複数のコピー、ループバックのみ、Studio のすべてのルート、拒否される外部の Host と Origin、エクスポート、ランチャーに渡すレシピ）、2 種類のシェルで START HERE.txt の記載どおりに実行するコマンド、stdio 経由の MCP サーバー、ヘルパーの出力と 1 行コマンド、実行権限と改行コード、プロセスが残らないことを検証します。検証にはアーカイブの対象システムが必要です。それ以外の環境では内容のみを確認し、その旨を表示します。Tests ワークフローは、各アーカイブをそのシステム専用のランナー上でビルド、再ビルド、検証します（Intel Mac のビルドは Apple シリコンのランナー上で Rosetta を介して実行します）。その後、同梱ランタイムでテストスイートを実行し、ランナーのブラウザーで展開済みビルドの Studio を操作します。macOS ランナーでは、ダウンロード時の隔離属性を付けた状態でもコマンドラインを実行します。どのランナーにも画面の前に人はいません。ダウンロードしたファイルに対して Windows と macOS が表示するプロンプト、ダブルクリック、実際のブラウザーでの動作は、そこで検証されません。

コントリビューション

バグ報告、レシピの例、ドキュメントの改善、範囲を絞ったプルリクエストを歓迎します。ツールキットを変更する前に、CONTRIBUTING.md と AGENTS.md をお読みください。再現可能なバグは GitHub Issues から報告してください。

関連ツール

Pixelbolt は、同じ作者による、無料で MIT ライセンスのエージェント向けツール 5 つのうちの 1 つです。すべてローカルで動作し、MCP サーバーとして利用できます。

• Anode：非表示のバックグラウンドセッションで Windows デスクトップを自動化するため、エージェントは画面を操作せずにクリック、入力、スクリーンショットの撮影ができます。
• Cutbolt：正確なタイムライン、キャプション、レンダリングに対応した動画編集エンジンです。
• Inkbolt：図表やイラスト向けのベクター画像とラスター画像の編集ツールで、SVG のインポートと SVG または PDF へのエクスポートに対応しています。
• Nestbolt：レーザー、CNC、プラズマ、ウォータージェットによる切断向けに、シート上へパーツを 2D ネスティングするツールです。ブラウザー上でも利用できます。

ライセンス

MIT ライセンスです。同梱のアートワークはオリジナルであり、同じライセンスが適用されます。