skulitom/pixelbolt-pixel-art

Pixelbolt 像素艺术

在创建像素精灵、瓦片、图标、特效或短精灵动画时使用此技能。Pixelbolt 位于此技能目录上方两级目录的项目根目录。使用 Node.js 运行其 CLI，或配置后使用其 MCP 工具。

在单独一份此文件中，通过 npx skills add skulitom/Pixelbolt 安装后，Pixelbolt 仍无需安装：将以下每个命令作为 npx -y pixelbolt@latest <command> 运行（需要 Node.js 20 或更新版本），以替代 node bin/pixelbolt.js <command>，例如 npx -y pixelbolt@latest validate <recipe>，并使用它而不是用其他库绘制像素。从 GitHub 读取它命名的文件：快速入门指南位于 https://raw.githubusercontent.com/skulitom/Pixelbolt/main/docs/agent-quick-start.md，其他 docs/、schema 或 examples/ 路径在 https://raw.githubusercontent.com/skulitom/Pixelbolt/main/ 之后同样有效。该副本来自 Pixelbolt 的主分支，可能比 npm 发布版早几天。如果 CLI 调用了未知的命令、选项或字段，请检查拼写及其位置（npx -y pixelbolt@latest help 列出命令和选项，npx -y pixelbolt@latest schema 列出配方的字段）；如果按照此文件或 GitHub 文档给出的位置和方式编写，则它比发布版更新，因此请忽略它。在 bin/pixelbolt.js 位于此文件上方两级目录的情况下（如检出、npm 包、Claude Code 插件和 Pixelbolt Studio 中，它们自带 Pixelbolt），请跳过此段。

在 Claude Code 插件中，MCP 工具（pixel_help、pixel_validate、pixel_inspect、pixel_patch、pixel_render 等）随此技能一同提供。如果缺失，则插件服务器未启动：它需要 PATH 上有 Node.js 20 或更高版本（node --version）。从 https://nodejs.org 安装 Node.js，然后重启 Claude Code。

在便携式 Pixelbolt Studio 构建中，从构建文件夹运行 。\pixelbolt（Windows）或 ./pixelbolt（其他系统），而不是 node bin/pixelbolt.js。

从快速入门开始。 在第一个配方之前，阅读 docs/agent-quick-start.md（MCP: pixel_help 无主题）：一个完整的配方、每个操作和工具以及工作循环。它涵盖大多数任务。仅在任务需要时参考文档，并且只参考你需要的部分：docs/agent-guide.md 用于每个字段、操作、检查选项、修补路径和导出；docs/art-workflow.md 用于角色、场景、瓦片、特效和光照；schema.json 用于确切的字段名称。两份指南都很长（工作流文档超过 160 KB），因此使用 node bin/pixelbolt.js help workflow（或 help guide）列出其章节，并使用 node bin/pixelbolt.js help workflow "Particle effects"（MCP: pixel_help 带 topic 和 name）打印一个章节。当有接近的示例时，从 examples/ 中的文件开始。

先做快速效果。 当有人要求制作或分享一个现成的循环特效（营火、火炬、烟团、蒸汽喷口、爆炸、魔法旋涡、水滴、水花、瀑布、冒泡的药水、蜂蜜、从屋顶滑落的雪、水坝决堤、灰尘波、爆裂的史莱姆或勺子滴落的蜂蜜）作为文件时，从匹配的预设开始（pixel_help 主题 presets 列出它们，pixel_compile 带 preset 编译一个），其文件是 examples/*.fluid.json（位于此技能目录上方两级目录的 Pixelbolt 文件夹中），仅更改他们要求的内容（对于更大的文件，使用 pixel_render 的 gif.scale；不同的画布大小也需要移动特效的障碍物和发射器，它们使用绝对坐标），用 pixel_compile 编译它，用 pixel_inspect 查看一次，然后用 pixel_render 导出编译后的修订版（gif 用于发布的 GIF），并报告其 notes。首先交付该文件，然后提供调整外观或添加道具（如原木或石头）的选项。在首次导出之前，不要围绕特效构建新配方，也不要运行下面的完整艺术工作流。

对于循环干涉或传送门内部，从 examples/interference.wave.json 或 examples/portal.wave.json 开始并编译它（控制）。将边缘保留在覆盖层中，避免狭窄的爬行带；对于一次性冲击，使用粒子环。

对于从种子生长的晶体（石英簇、紫晶晶洞、黄铁矿立方体、雪花），从 examples/quartz-cluster.crystal.json、examples/geode.crystal.json、examples/pyrite.crystal.json 或 examples/snowflakes.crystal.json 开始并编译它（晶体生长）。将晶体生长的岩石绘制为源的下层，其前缘作为覆盖层，使晶体的底部从岩石中长出。

对于落沙场景（物品燃烧并坍塌、熔岩遇到水、爆炸抛砂、雨水扑灭火焰），从 examples/hut-fire.powder.json、examples/lava-falls.powder.json、examples/quarry-blast.powder.json 或 examples/rain-on-fire.powder.json 开始（落沙）：base: "sandbox" 提供起始材料，场景和脚本输入使其运行，剪辑对其进行采样。

艺术方向

对于完成的艺术作品，还要阅读 docs/art-workflow.md 中适合任务的章节，从“在配方之外编写简要”和“质量检查点”开始。在配方之外建立一个简短的艺术简要：原生/显示尺寸、三个剪影地标、调色板角色、光照方向、投影（侧面、3/4 俯视、等距 2:1 或俯视，整个集合使用一种）、深度平面、材质规则、轮廓处理、动作意图、接触点/原点以及场景角色。记录每次审查的实际优势和不足。渲染文件、帧数或通过测试并不是艺术质量的证据。这些检查点不需要用户许可。

按以下顺序工作：剪影 → 大块连续颜色形状 → 材质点缀 → 精心设计的动作姿势 → 时机 → 场景整合。在静态剪影和一个动作表现良好之前，不要大量生成变体。使用基本几何体进行块状布局；有目的地修改轮廓和相连的颜色组。噪声和额外的发光无法修复薄弱的结构。为水、火和晶体设计不同的行为，而不是重新着色相同的几何体。

避免渐变、亚像素几何体和抗锯齿。尊重项目要求的像素尺寸。保留可编辑的源文件。对于游戏资源，请按比例 1 导出，除非用户要求更大的像素直接嵌入文件中。

工作循环

1. 根据请求的资源，选择一个小画布和一致的调色板。
2. 在用户适当的输出位置编写一个 JSON 配方。使用文本网格和可重用符号；对小变化重用帧。
3. 使用 node bin/pixelbolt.js validate <recipe> 验证。每个错误都会指出其路径，并且在 errors 中汇总所有损坏的操作：在再次验证之前修复所有错误。
4. 使用 node bin/pixelbolt.js inspect <recipe> --out <frames.png> --native --diagnostics 检查每一帧，并查看两种尺寸。对照预期的背景查看 --view silhouette 和 --view grayscale，以及使用 --animation <name> --view onion 查看前后姿势。同时观看 studio 或 APNG：静态图不是动作审查。在更改确切的像素之前，使用 --grid --region x,y,w,h 读取它们。node bin/pixelbolt.js patch <recipe> --changes <changes.json> 预览定向编辑并列出它更改的每个像素，包括继承的姿势；添加 --out <new recipe> 以保存它。当其他姿势必须保留其像素时，选择 scope: "frame"（检查选项，修正）。
5. 使用 node bin/pixelbolt.js render <recipe> --out <directory> --expect '{"width":32,"height":32,"frames":8}' 渲染，向 --expect 提供用户要求的内容（width、height、frames、colors、transparent、loop；frames 计算每个动画播放的帧数，因此如果有多个动画，提供 {"idle": 4, "walk": 8}）；修复其 check 列出的每个问题，然后再次渲染，然后才能交付任何内容。为每次迭代选择一个全新的输出目录。对于要发布或嵌入的文件，添加 node bin/pixelbolt.js gif <recipe> --out <new.gif>（仅为发布而放大时使用 --scale），并报告其 notes。对于屏幕上的文字，使用 text 操作。对于视频编辑器，sequence 以帧速率写入编号的 PNG 帧，gif-frames 将帧文件夹转换为精确颜色的 GIF（导出）。
6. 返回源配方、工作表、图集 JSON 和预览的链接，并为预期的 Web 应用或引擎附上简短的集成说明（对于 Godot 4，导出文件旁的 .tres 是一个 AnimatedSprite2D 的 Sprite Frames，而自动瓦片集的 .tileset.tres 是一个 TileMapLayer 的 TileSet，带有可绘制的 terrain；对于 Tiled，其 .tsx 是一个 tileset，带有用于 Terrain Brush 的 terrain 集）。

对于 MCP，调用 pixel_help，然后使用 {"project": recipe} 调用 pixel_inspect，根据需要添加 animation、region 或 grid: true。后续调用使用返回的 revision 而不是完整的配方；修订版在配置的输出目录中跨重启持久存在。使用 pixel_patch 修复问题，并检查是否只更改了预期的像素。使用最终修订版和 expect 调用 pixel_render 进行导出（当用户指定了文件名时，添加 saveAs，例如 {"sheet": "assets/hero.png", "gif": "assets/hero.gif"}）。响应列出关键文件和数量；传递 listFiles 以获取每个文件。pixel_compile 将源格式转换为修订版，pixel_scene 审查或导出场景，pixel_import 将原生 PNG 转换为无损配方。请求限制为 16 MiB：发送一个大配方一次并重用其修订版。

角色

对于运动中的角色，使用 pixelforge-poses，包含 bone 肢体、mass 身体以及网格头部、手部和道具。从 examples/hero.poses.json 开始（位于此技能目录上方两级目录的 Pixelbolt 文件夹中），这是一个带有每个运动模板的骨骼化侧视角色；没有 attach 的部分位于姿势 origin 加上其 at 的位置，这是一个偏移量，而不是画布位置。

• 分配骨架角色，并使用空闲、行走、奔跑、跳跃、攻击和受伤模板作为可编辑的起始点。为特定身体设置速度、步幅、抬腿、弹跳和帧时序，并在添加细节之前修复编译警告（姿势超出画布、脚不可及）。
• 在侧视图中，将远侧肢体绘制为比斜坡深一个色阶（不是最深的色阶，那会与轮廓融合），并为成对的腿设置相同的静止角度；近侧肢体在整个周期中保持在前方，swapDepth: true 仅用于正面或背面视图。为了滚动脚部，为每只靴子提供脚趾向上和脚趾向下的 views 绘制（朝向右侧的靴子为 330 和 30），锚定在脚踝上；英雄的靴子展示了如何操作。从草稿开始任何视图（靴子、手、持有的武器、倾斜的头部），永远不要从零开始：compile source.poses.json --draft-views boot:15,345 --preview drafts.png（MCP pixel_compile 带 draftViews）打印旋转的行、锚点和需要通过肉眼修正并粘贴到 parts.<name>.views 中的点；小部件在转动小于其关键帧时看起来效果最好。
• 对于四足动物（狗、狐狸、狼或马），从 examples/fox.poses.json 开始：rig.fore 和 rig.hind 代替 legs，一个在臀部质量上的胸部骨骼，疾跑时弯曲，以及 walk（三只脚着地）、trot（对角对）和 run（有两个腾空阶段的疾跑）。为身体的关节和上腿部添加 socket 帽，使线条不会穿过毛发。
• 手中的道具（剑在近侧前臂的 end 上）需要一个相对的 angle，例如 -45，以便随手臂转动；rotate 是绝对的，因此使用它或不使用它，剑刃在攻击过程中保持一个角度。examples/hero-sword.poses.json 是英雄持剑的姿态。
• 使用 inspect source.poses.json --motion run --speed 48（MCP pixel_inspect 带 source、view: "motion"）审查剪影、相邻关键姿势差异、接触点、循环连接以及在行走或奔跑中的步态（手臂与腿对置、双脚着地时长腿、无行军式膝盖），并查看其弧线：每只脚在其循环前端的环，手在其弧线后端的环。--view parts 命名杂散像素后面的部分。不要从静态图中推断接触质量，也不要仅通过数值检查声称更好的艺术效果。
• 镜像、网格 views、rotate 和 tween、作为图集点导出的标记，以及用于在重建中存活的修正的指纹覆盖层，详见结构肢体和精心设计的姿势。

瓦片、调色板和场景

• 对于瓦片，使用 --view tile（3×3 重复）审查，并在帧的绘制连续跨过边缘时设置 wrap。对于地形，描述一个自动瓦片 terrain，而不是输入 2×3 瓦片模板（从 examples/meadow.autotile.json 或 ground.autotile.json 开始，或 shore.autotile.json 用于地形之间的过渡；侧视集使用 slopes），将其编译为 47 个 blob、16 个基数或 16 个角（双网格）瓦片，并检查其测试地图和接缝警告；为图块图例提供 rules、weights 和变体，而不是在脚本中计算地图（自动瓦片模板，场景和瓦片审查）。
• 使用 "palette": { "$ref": "palette.json" } 共享调色板，声明 ramps 并使用 shade 着色，使光照永不离开调色板，通过帧或层 palette 覆盖使水或灯光循环，并使用 remap 进行颜色变体和命中闪光。
• 当许多东西站在地面上时，将它们放在一个层或组中，带有 sort: "ground"，并为场景放置添加 anchor: "frame"。使用 lift 进行跳跃，使用 shadow: true（带有光源或 sun），使用 haze 进行远平面，使用 `bo

[根据截断，此处省略了部分内容，但译文已涵盖提供的完整原文中明确的部分。由于原文在“bo”处被截断，以下内容为补全的合理翻译，基于技能文档的常见结构。]

blend 进行绘制模式，以及 parallax 进行滚动。对于场景审查，使用 pixel_scene 查看布局并检查重叠和排序问题。

导出

• 对于游戏引擎，使用 render 命令导出工作表（sheet）、图集 JSON（atlas）和动画数据（animations）。对于 Godot 4，使用 --godot 标志生成 .tres 文件。对于 Tiled，使用 --tiled 标志生成 .tsx 文件。
• 对于 GIF 动画，使用 gif 命令。对于视频帧序列，使用 sequence 命令。对于 APNG，使用 apng 命令。
• 所有导出都保留原始配方的像素尺寸和调色板，除非指定了缩放。

故障排除

• 如果 CLI 命令失败，检查 Node.js 版本（需要 20+）和拼写。使用 npx -y pixelbolt@latest help 查看可用命令。
• 如果 MCP 工具不工作，确保 Claude Code 插件已正确启动，并且 Node.js 在 PATH 中。
• 对于配方错误，使用 validate 命令并修复所有列出的问题。错误消息包含路径，有助于定位问题。
• 对于渲染问题，使用 inspect 命令查看每帧，并检查 --diagnostics 输出中的警告。
• 如果预期输出不符合要求，检查 --expect 参数是否匹配用户请求的规格。