Pixelbolt pixel art toolkit

Pixelbolt

AI Agent 可以用来创作、检查和修复像素艺术与精灵动画。 Pixelbolt 可将可编辑的 JSON 配方转换为精灵、图块、图标、特效和短动画，并导出为 PNG 精灵表、纹理图集、动画 PNG、GIF，以及供视频编辑器使用的帧。Agent 可通过本地 MCP 服务或命令行驱动它；你也可以在本地浏览器工作室中打开、播放和编辑同一份配方。

English · 简体中文 · 日本語

火焰、烟雾、蒸汽、爆炸、魔法、水、蜂蜜和史莱姆效果都来自真正的流体模拟，可在你自己的 CPU 上不到一秒运行完成，并将每一帧烘焙为可编辑的调色板像素，还支持无缝循环（流体特效）。

• 适用对象： 想让 Claude、Codex 或 Cursor 等 Agent 绘制并修改像素艺术的游戏开发者、游戏创作马拉松团队、网页或视频创作者，以及需要精确、可重复图像的 Agent 构建者。
• 适用场景： 你想要可通过文本编辑的小型 2D 游戏素材：Agent 可以读取每个像素，只修复一个像素或一帧而不重绘其余部分，而且同一份配方每次渲染的图像都相同。
• 不适用场景： 绘画、照片或大尺寸图像（每帧最多 256 × 256 像素，每个项目最多 256 帧，总计 4,194,304 像素）；使用图像模型生成艺术；或编辑 GIF 和 Aseprite 文件（仅支持导入 8-bit RGB/RGBA PNG）。
• 与其他工具相比： 关于 aseprite-mcp、pixel-mcp、pixscii、pixelart-mcp、pixelforge-mcp 和 SpriteCook，Pixelbolt 的实测结果、其他工具的代码与文档分析，以及各工具的适用场景，请参阅：面向 AI Agent 的像素艺术与精灵 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

交给你的 Agent。 在 Claude Desktop 中，从最新版本下载 pixelbolt.mcpb 并打开（或在 Settings → Extensions 中从文件安装），选择一个用于存放配方和美术素材的工作区文件夹，然后让 Agent 调用 pixel_help。对于 Claude Code、Codex、Cursor 和其他 MCP 客户端，请参阅通过 MCP 连接 Agent。Pixelbolt 已收录在官方 MCP Registry 中，名称为 io.github.skulitom/pixelbolt。 在 0.8.0 之前，Pixelbolt 曾名为 PixelForge。pixelforge 命令仍可用作别名，配方文件也保留了 pixelforge-* 格式标签，因此现有文件和 Agent 配置仍可正常使用。

画廊 · 流体效果 · 快速开始 · Agent 设置 · 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 Agent 使用 Pixelbolt 绘制了这些作品。它的脚本负责编写配方、粒子源和场景；Pixelbolt 会将每个精灵渲染到带图集的透明图集上，将每个 240×135 房间作为场景播放，并生成 GIF。下方作品均以 3× 尺寸展示。

另外两个房间及其制作过程

流体效果

pixelforge-fluid 源会运行一个小型确定性流体模拟，并将其编译为普通的调色板网格配方：具有浮力、涡旋、冷却和消散效果的气体，以及在同一网格上作为 FLIP 粒子模拟的液体，可以稀薄如水、浓稠如蜂蜜（一股不断流的细流、缓慢沉降的液堆），也可以坚韧如黏液（团块会被压扁、弹回并保持形状）。外观图层通过有序抖动，将密度、温度、速度和深度映射到调色板渐变，因此不会出现调色板之外的颜色，循环效果也能无缝衔接。以下每个预设都能在笔记本电脑 CPU 上不到一秒完成编译，无需 GPU，也不会调用模型。图示放大至 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

这十二个预设位于 examples/（*.fluid.json）中；Agent 使用 MCP pixel_compile 编译，并通过 pixel_help 的 fluid 主题读取格式说明。在工作室中，Fluid lab（/fluid.html）会在浏览器中运行同一编译器：选择预设、调整几个滑块，然后下载 GIF、精灵图、配方或编辑后的源文件。流体效果指南介绍了发射器、火花、障碍物、外观、循环和浓稠流体（黏度、屈服应力、附着力）。在网页中，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 会从第二格开始每隔一格保留一格，这样就能分别读取频闪动画的 A 帧和 B 帧。validate hero.pixel.json --fps 30 还会列出在该帧率下时长不是整帧数的动画，以及视频序列会如何处理每个动画。patch hero.pixel.json --changes fix.json 会预览针对性修改，并报告每处修改影响的像素；添加 --out 可保存新配方。gif hero.pixel.json --out hero.gif 会将一个动画保存为 GIF，方便分享。除帮助信息和预览服务外，命令结果均为 JSON。错误会输出到 stderr，并以代码 1 退出。用 - 替代文件名可从 stdin 读取 JSON。已有输出文件会受到保护；添加 --force 可覆盖它们。也可以选择运行 npm link 来使用 pixelbolt 命令。无需运行 npm install。

立体场景：3/4 视角地牢房间

原创的 3/4 俯视地牢房间，采用程序生成的“浮空微缩场景”游戏风格：8 像素瓦片、带正面的墙顶、瀑布汇入的下沉水池、苔藓、道具、火把，以及一位攻击时会打破陶罐的英雄。整个房间由一个配方构成，其中 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

面向 Agent

使用 Pixelbolt 通过可编辑的 JSON 创建或修改像素精灵、图块、图标、特效和短动画。如果可以访问 shell，请选择 CLI；如果客户端支持工具，请选择 Model Context Protocol（MCP）服务。两者使用相同的渲染器，且都在本地运行。

入口	用途
llms.txt	紧凑的文档索引，包含供 Agent 使用的直接链接
Pixel art skill	可复用的创作与视觉检查工作流
创作指南	配方字段、绘制操作和限制
JSON Schema	机器可读的配方结构
示例	完整的森林精灵、营火、硬币和神龛配方、带像素文字的说明文字、旋转的挥剑动作、粒子特效源，以及 12 种流体预设
AGENTS.md	为参与工具包开发的 Agent 提供的说明

从创作指南或 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 图块 blob 或 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 保留完整的 Alpha 通道和精确的时间，但许多聊天、论坛和商店页面只支持 GIF 动画，而且无法清晰地缩放像素。pixelbolt gif 会将一个动画写入 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 不支持部分透明，因此 Alpha 值低于 50% 的像素会变为透明，其余像素则变为不透明；--background（调色板名称或不透明的十六进制颜色）则会将每个像素混合到同一种颜色上，从而保留柔和阴影。帧时间会四舍五入到 GIF 的 10 ms 时间步长，并将余数计入下一帧；低于 20 ms 的时间则会提高到 20 ms。所有查看器（包括 ffmpeg 和 Pillow）中，透明像素都会保持透明；除非指定透明索引，否则它们会用背景色填充已清除的帧（说明中会指出极少数帧自身有 256 种颜色、因此没有可指定的透明索引）。JSON 结果的 notes 会说明发生了哪些情况。工作室中的 GIF 按钮会按当前缩放比例下载当前动画；MCP pixel_render 则使用 "gif": {}。导出包本身不会改变。

pixelbolt gif-frames 会按照相同规则，从一组带编号 PNG 帧的文件夹创建 GIF，例如 sequence 文件夹，或视频、特效工具生成的帧：

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，或文件夹里有两组序列（可用 --prefix 选择其中一组），都会报告，不会自行猜测处理。每帧的颜色都保持精确：超过 256 种颜色的帧会按文件名报错拒绝处理；帧使用的颜色不同时，每帧都会携带自己的颜色表，因此，包含 48 帧、尺寸为 1080 × 1080、每帧约有 120 种颜色且总计 4,345 种颜色的循环动画，解码后仍能逐像素还原，而调色板生成器会改变部分颜色。第 k 帧的起始时间为 k × 1000 / fps 毫秒，并四舍五入到 GIF 的百分之一秒：25 fps 时每帧为 40 ms；30 fps 时帧间隔会交替为 30 和 40 ms，同时保持循环总时长不变；高于 50 fps 时，帧间隔会提高到 20 ms，说明中会报告调整后的总时长。--loops 指定播放次数，默认值 0 表示无限循环。不使用透明度时，第一帧之后的每帧只保存发生变化的矩形区域。PNG 必须为 8 位 RGB 或 RGBA，且尺寸相同；循环动画最多可包含 134,217,728 个像素（115 帧，尺寸为 1080 × 1080）。

像素文本

text 操作使用内置像素字体绘制标题、说明文字、标签和计数器：支持可打印 ASCII、西欧语言中的重音字母（À–ÿ、Œ œ Š š Ž ž Ÿ）以及 € £ © — … “ ” „ « » 等常见符号；大写字母高 7 像素，字母为比例宽度，数字为等宽。大写字母的重音符号位于 y 上方两行。

{ "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 会将其转换为 81 帧，并置于 1080p 画面的底部。

面向视频编辑器的帧序列

视频编辑器不会为 APNG 制作动画，而 GIF 会丢失 Alpha 通道和精确的时序。pixelbolt sequence 会生成编辑器可读取的内容：每个视频帧对应一张带编号的 PNG，帧率恒定，画布尺寸与视频相同，并保留 Alpha 通道。

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 表示隔两帧更新一次动画。循环动画会持续循环播放；只播放一次的动画会停留在最后一个姿势。
• 尺寸。 --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 会将图像与不透明颜色混合，而不是保留 Alpha 通道。
• 来源。 可以是配方（用 --animation 选择）、姿势、自动拼接图块或特效来源（导入时会编译），也可以是场景（逐时刻渲染成一个镜头；画面相同的时刻会共用一张 PNG）。192×108 或 240×135 像素的场景分别以 10 倍或 8 倍缩放后恰好填满 1080p。其他尺寸的场景会在自身背景色上居中并留边，确保镜头从一边到另一边均为不透明；也可以用 --fit cover 填满画布。
• 输出内容。 会新建一个文件夹，其中包含从 name_0001.png 开始编号的 PNG、sequence.json（包含以分数表示的帧率、帧数、尺寸、位置、循环信息和每个姿势的时序），以及说明如何导入的 README.txt。结果中的 notes 会说明帧网格的处理情况：哪些姿势的时长发生了变化，哪些姿势短于一个视频帧而未显示，以及片段结束位置是否与循环结束位置完全重合，并注明需要循环播放的次数。
• 生成单个视频文件。 Pixelbolt 不会编码视频。文件夹中的 README 和 JSON 结果会提供精确的 ffmpeg 命令，用于生成带 Alpha 通道的 ProRes 4444 .mov；如果设置了背景，也会提供生成无损 4:4:4 H.264 .mp4 的命令。H.264 通常每 2 × 2 像素只存储一次颜色（4:2:0），播放器进行插值后，无论缩放倍数如何，都会使每个像素边缘变模糊；4:4:4 会保留每种颜色，对于像素艺术，文件不会更大。但 QuickTime、Safari 和 Windows 自带的播放器可能无法播放，因此在画布尺寸为偶数时，h264Compatible 也会提供 4:2:0 文件。使用 ffmpeg 7 时，ProRes 命令会精确保留 Alpha 通道，颜色误差不超过 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 参数，方便 Agent 无需浏览器即可重复导出。

通过 MCP 接入 Agent

Claude Code 插件。 只需一条命令即可安装 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 客户端。 先克隆仓库，然后将服务添加到 Agent 的 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 个 token）；topic 可返回完整的创作指南（guide）、美术工作流（workflow）、配方架构（schema）、完整示例（example），或姿势、场景、自动拼接、特效、流体或法线架构。
• 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，并说明任何 alpha 或时序变化；添加 "sequence": { "fps": 30, "size": "1080p" }，则会将一个动画写为供视频编辑器使用的编号 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，超出上限的请求会收到错误响应，但不会导致服务端停止。

只需发送一次配方。每次成功的配方工具响应都会包含一个 revision ID，其他工具可用它代替 project，因此后续调用（包括补丁）无需重新发送配方。验证、检查、补丁和渲染都会将不可变快照保存到 <MCP --out directory>/.revisions/；只要使用同一目录，即使服务重启，这些快照也会保留，即使尚未导出资源亦然。建议使用绝对 --out 路径。较早的修订版本仍可作为撤销点。较早的渲染修订版本可从已保存的捆绑包配方中恢复。渲染还会将配方保存到资源所在目录。

该服务实现了以换行符分隔的 stdio MCP，支持初始化、版本协商、ping 以及工具发现和调用。它支持协议版本 2024-11-05、2025-03-26、2025-06-18 和 2025-11-25。它不使用 HTTP 传输或外部服务。请参阅 MCP stdio 规范。

Agent 也可以直接使用 CLI。可复用的 Agent 技能和创作参考指南介绍了完整格式。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 解析。

在一个画布上绘制多个精灵的游戏可以使用同一模块中的辅助函数。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-hash 帧布局；命名动画序列位于额外的 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 的导出器使用标准库进行压缩和文件输出。Studio 与 CLI 和 MCP 服务使用同一渲染器。

开发与验证

npm test
npm run demo

测试涵盖像素、Alpha 混合、继承、变换、泛洪填充、文本和字体、抖动（包括值噪声）、调色板渐变和着色、轮廓、重写规则、清理、旋转、补间、粒子效果、流体模拟（每个预设的黄金配方、仅调色板输出、循环接缝）、图块地图和规则图块、场景提示、附加内容和排序、架构对齐、打包、计时、PNG/APNG 结构、GIF 结构和解码、视频帧计时与放置、检查表和网格、修补与比较、修订、覆盖保护、CLI 标准输入/错误、MCP 调用、Canvas 运行时、本地服务和便携式 Windows 构建。node scripts/qa-studio.mjs 会在真实浏览器中遍历工作室（已安装的 Edge 或 Chrome、无头模式，并使用临时配置文件；Node.js 22+）：每个示例、实时编辑、损坏的配方、预览控件、保存、打开、导出和下载到磁盘的 GIF、草稿恢复、键盘访问、窄窗口和宽窗口，以及确保没有请求离开计算机。可选的独立检查使用 Pillow 和 Python 的 ZIP 读取器：运行 npm run demo 后执行 python scripts/verify-exports.py；它还会解码 GIF（包括由 PNG 文件夹生成的 GIF）和图像序列，并比较每个像素、延迟和循环标记；如果已安装 ffmpeg，还会运行图像序列的 ffmpeg 命令。

工作室绑定到 127.0.0.1，只提供明确允许的资源，拒绝来自外部的 Host/Origin 标头，并且绝不会通过其 HTTP API 写入文件。未保存的编辑内容会作为一个草稿保存在浏览器自身的存储中，且仅对应工作室的地址，并会在下次访问时提供恢复；这些内容不会发送到服务器，而保存 JSON仍是保留配方的方式。浏览器存储按地址隔离，因此在一个端口创建的草稿不会出现在另一个端口。项目限制为 256×256 像素、256 帧、4,194,304 个源像素、16,777,216 个图集像素，并限制绘制和导出工作量。本工具专为小型精灵图、效果和图块而设计。

Pixelbolt Studio：便携版构建

scripts/build-studio.mjs 会将工具包、官方 Node.js 24 LTS 运行时和几个小型启动脚本打包成每个系统一个归档文件，供没有 Node.js、git 或管理员权限的用户使用：64 位 Windows 使用 ZIP；Linux（x64 和 ARM64）以及 macOS（Apple silicon 和 Intel）使用保留可执行权限的 .tar.gz。无需安装，删除文件夹即可移除所有内容。

	Studio	命令行	连接 Agent
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 端口打开默认浏览器；如果该端口已被占用，则会使用任意空闲端口（常用端口可让 Studio 的草稿恢复功能再次找到草稿）。连接助手会输出适用于 Claude Code、Claude Desktop、Codex 和 Cursor 的 MCP 设置，其中包含该文件夹的路径；还会输出一行适用于该系统 Shell 的 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）都会构建全部五个归档并输出其哈希值。

verify-studio.mjs 会使用系统自带的工具将归档解压到路径中含有空格和非 ASCII 字符的文件夹，然后在 PATH 中没有 Node.js 或 git 的情况下运行它，检查启动器（多个副本、仅限本地回环地址、所有 Studio 路由、拒绝外部 Host 和 Origin、导出、向其传入配方）、按照 START HERE.txt 中的说明在两个 Shell 中原样运行命令、通过 stdio 运行 MCP 服务、助手的输出及其单行命令、可执行权限和换行符，以及是否有进程残留。它需要目标归档所对应的系统；在其他系统上则只检查内容并说明这一点。Tests 工作流会在各自系统的运行器上构建、重新构建并验证每个归档（Intel Mac 构建通过 Rosetta 在 Apple silicon 运行器上完成），然后使用捆绑的运行时运行测试套件，并在运行器的浏览器中操作解压后构建版本的 Studio。在 macOS 运行器上，命令行还会在设置了下载隔离标记的情况下运行。没有运行器会安排人员在屏幕前操作：因此不会在那里测试 Windows 和 macOS 对下载文件的提示、双击操作以及真实浏览器。

贡献

欢迎提交错误报告、配方示例、文档改进和范围明确的拉取请求。更改工具包前，请阅读 CONTRIBUTING.md 和 AGENTS.md。请通过 GitHub Issues 报告可复现的错误。

相关工具

Pixelbolt 是同一作者开发的五款免费、采用 MIT 许可的 Agent 工具之一。每款工具都在本地运行，并可作为 MCP 服务：

• Anode：在隐藏的后台会话中自动化操作 Windows 桌面，让 Agent 无需接管你的屏幕即可点击、输入和截屏。
• Cutbolt：视频编辑引擎，支持精确的时间线、字幕和渲染。
• Inkbolt：用于编辑图表和插图的矢量与栅格图像，支持导入 SVG，并导出 SVG 或 PDF。
• Nestbolt：为激光、CNC、等离子和水刀切割，将零件二维排样到板材上，也可在浏览器中使用。

许可证

采用 MIT 许可。所含美术作品均为原创，并受相同许可证保护。