生成2D精灵图 (Generate 2D Sprite)

生成2D精灵图 (Generate 2D Sprite) 是做什么的？

制作游戏所需的最小资产包，按实际显示尺寸、相机角度和风格输出。 游戏逻辑（碰撞、伤害、计时）独立于艺术资产。

适用场景

• 需要为角色、生物、道具、物品、图标或特效创建静态主图、精灵表或动画片段。
• 已有帧（通过生成、绘制、代码绘制等方式获得），需要将其转化为片段、调色板或导出为游戏引擎格式。

不适用场景

• 地图、瓦片、地形、视差或场景底板：请使用 generate2dmap。
• 角色动画：先在此技能中批准一张主图，然后 video2dsprite 为每个动作生成一个片段（参见 video-handoff.md）。
• 用户要求的代码绘制艺术：请使用 codeart2d。
• 仅进行API或CLI调用：请使用 generate2dmedia。

能力检查（每个会话一次）

运行 python "<skill-dir>/../generate2dmedia/scripts/forge_doctor.py" --host-tools <tools> --save <output>/doctor.json，其中 <tools> 列出了您自己的媒体工具列表中的媒体工具（image_gen、image_edit、image_to_video）或 none。它的 ROUTES 块会显示哪些API密钥已配置（是或否）、本地就绪状态以及解析后的顺序。如果 encoding.stdout 失败，请设置 PYTHONUTF8=1。

艺术来源

图像生成是角色、生物、道具、图标和特效的默认艺术来源。将其记录为 art_source（api、host_image、existing 或仅在请求时使用 code），并在您的回复中命名路由。用户明确指定的路由优先。

1. API，当配置了密钥时：OpenAI (OPENAI_API_KEY)、Google Gemini (GEMINI_API_KEY)、xAI (XAI_API_KEY)、字节跳动豆包 Seedream (ARK_API_KEY) 或 fal.ai (FAL_KEY)，这些密钥在环境变量或用户配置文件中（参见 route-media.md）。配置的密钥即代表所有者同意，因此无需每次调用都询问。
2. 本地：您自己的图像工具（Codex image_gen、Grok 原生工具），当您拥有时；否则回退到用户已登录的 Codex CLI，然后是 Grok CLI。
3. codeart2d 仅在用户明确要求代码绘制艺术时使用，或者当 route_media.py 输出 no-route（退出码3）时。此时请说“代码绘制，无图像模型”。

Hi-Bit 特效是唯一的例外：fx_pixelfx.py check 会在用户已安装 pixelfx 时将其发送给 pixelfx（路由A，第三方代码绘制特效，需注明来源并披露），否则发送给图像路由（路由B）。参见 hibit.md。

每张图像都通过一个命令生成：python "<skill-dir>/../generate2dmedia/scripts/route_media.py" image --prompt-file <txt> --reference <png> --size 1024x1024 --out-dir <new>。它会按上述顺序选择路由，并打印一行JSON，包含 route、artifact、sha256 和 estimateUsd；resolve --kind image 会显示将要运行的路由。始终欢迎用户提供的现有艺术资产。绝不声称未发生的生成操作；保留提示词和契约，并报告缺失的能力。

• 完成度 (Finish): 高清 (HD) 是默认设置：全彩色、干净的透明度、一个注册点以及按游戏高度进行预乘区域下采样。像素完成度（一个共享调色板、二值透明度、无抖动）在用户要求像素艺术时作为选项提供；Hi-Bit 完成度（模型的扁平无线条艺术，然后是一个角色调色板、多数投票下采样以及从图像中提取的轮廓颜色）在用户想要 Hi-Bit 外观时提供（参见 hibit.md）。切勿要求图像模型生成逻辑像素网格；像素外观来自完成度处理。
• 角色： 每个角色批准一张静态主图，然后使用 video2dsprite 进行动画：每个动作一个图像到视频的片段，所有片段都来自该主图（sprite_set.py）。保持每个动作的身体高度与主图静止姿势一致。
• 精灵表 (Sheets) 用于特效、图标和道具（以及用户提供的帧），不用于角色动画。

静态主图（每个角色动画的起点）

每个角色批准一张静态主图，然后从此主图为每个动作生成一个图像到视频的片段（参见 video2dsprite）；精灵表用于特效、图标和道具。措辞指南：请参见 prompt-rules.md；命令、构图和 master.json：请参见 master-still.md。

1. 规格 (--spec <json> 和/或标志)：--name、--subject、--identity（长且精确）、--facing left|right|front|back、--class hero|mob|boss|prop、--finish hd|pixel|hibit（HD 默认；仅在要求时使用 pixel 或 hibit；hibit 会使静态图变得扁平且无线条）、--identity-ref（第一张图片，精确复制）、--style-ref（第二张：已批准的同类精灵，仅提取风格和构图）、--key（默认 #FF00FF；对于紫色和粉色设计使用绿色或蓝色）。
2. 生成：python "<skill-dir>/scripts/master_still.py" generate --spec <json> --takes 3 --output-dir <new>。每次尝试都通过 generate2dmedia route_media.py（首先是API密钥，然后是本地守护进程）；takes.png 会并排显示它们。退出码3表示无路由：请说明；codeart2d 是后备方案（“代码绘制，无图像模型”）。如果使用主机自己的图像工具：运行 master_still.py prompt 并按顺序附上列出的参考图。
3. 通过以下方式选择：检查身份、朝向、没有任何元素接触边缘、无文字。
4. 通过编辑来修正接近正确的图片，切勿重新生成：master_still.py edit --run <dir> --take N --change "<一次修改>" --output-dir <new>（或 --master <dir>）。
5. 批准：master_still.py approve --run <dir> --take N --output-dir <new>（来自其他来源的静态图：--still <png> --route <产生它的方法>）。它会对静态图进行键控，以6像素边距裁剪，使用 LANCZOS 算法缩放到1024x1024的类构图（英雄身高788像素，上边距138像素），并写入 master.png（不透明，纯键色）、master_rgba.png 和 master.json（generate2dsprite.master.v1）。
6. 运动步骤读取 master.json（identity_recap、facing、finish、class、framing、key、files、transform、route），且绝不重新测量静态图；每个片段提示词都以“同样的 <identity_recap>”开头。

报告来自 master.json 中 route 的路由。FORGE_ROUTE_MEDIA_FAKE 警告表示该图像并非真实生成。

主机说明

• Codex： image_gen 是您自己的图像工具；如果未配置密钥，请使用它并通过 view_image 查看结果。本会话中生成但不在项目中的图像：python "<skill-dir>/../generate2dmedia/scripts/cli_media.py" adopt --codex-thread <thread-id> --output-dir <new>，然后处理 generated.png。codeart2d 和 generate2dmedia 是显式访问的：当此技能路由到它们时，请打开它们的 SKILL.md。
• Claude Code： 无内置图像生成器：route_media.py 使用API或本地CLI。使用 Read查看您创建的每个PNG；使用 Bash 运行工具；<skill-dir> 是 ${CLAUDE_SKILL_DIR}。
• Grok： 其原生图像和视频工具是您自己的工具；请使用它们的真实模式。

命令

从用户的项目根目录将每个工具作为一行运行：python "<skill-dir>/scripts/<tool>.py" ...。<skill-dir> 是本技能的文件夹；同级技能位于其旁边（<skill-dir>/../video2dsprite）。保持输入和输出在项目内部。每个工具都会写入一个新的 --output-dir：如果目录已存在则拒绝，在旁边暂存，并仅在其检查通过后发布（--strict-qc / --strict 在失败时不发布任何内容）。成功时打印一行JSON；错误时打印 error: ... 并退出码1；用法错误退出码2。需要 Python 3.10+、numpy 和 Pillow（推荐 scipy）。--help 列出所有标志。

规划资产

记录身份和参考、相机角度和朝向、风格、游戏显示尺寸、完成度（默认HD，按需像素）、动作列表和阶段、循环或一次性、运动包络线、共享根部以及输出格式。每个角色保留一个已接受的主图和一种源到显示的缩放比例；除非计划中另有说明，否则小兵的高度不得超过英雄。网格并不等于平滑度：姿势间距、时间、循环接缝和地面接触更为重要。姿势、近/远腿和时间的规划：请参见 animation-planning.md。

• Alpha：native_alpha 保持真正的透明度（绘制棋盘格不是透明度）；chroma_key 仅在主题没有任何透明度时使用纯品红色；opaque 保留完整图像（assemble_frames.py）。
• 采样：lanczos 或为生成的图像使用预乘区域缩放；仅对已验证的像素网格使用 nearest。高分辨率的像素风绘画不是干净的32像素艺术。
• 共享根部并非每帧alpha边界框底部：保留有意的飞行、跳跃、弹跳和后坐力。

生成（图像路由）

自己编写提示词（参见 prompt-rules.md；网格、阶段和预设请参见 action-recipes.md）。通过 --reference（或您工具的真实图像输入）附加参考图；路径本身不是参考。在每次生成中保留已接受的主图，并描述绝对阶段，而不是链式编辑；修复是对已批准的静态图进行编辑，并仅命名唯一的更改。一次生成一个动作系列，并将宽挥砍、拖尾和投射物保留在身体精灵表之外。验证实际的路由、模型和返回大小；切勿从提示词中声称这些信息。

管道

精灵表（特效、图标、道具）：在原始精灵表上运行 sheet_qc.py spill，然后运行 generate2dsprite.py process，再运行 sheet_qc.py frames，然后 scale_frames.py，再 build_animation_clips.py，最后 export_engine.py。角色动作从 video2dsprite 作为打包好的片段返回。

需求	路由
为图像工具规划精灵表（宽高比、网格、参考图、提示词）	plan_guide.py --frames N --cycle run --output-dir <new>；附加 guide.png，粘贴 prompt.txt。固定缩放和脚线：使用 make_anchor_layout.py；空的蒙版帧：使用 make_layout_guide.py
在切片前检查原始精灵表	sheet_qc.py spill --input <sheet> --rows R --cols C --output-dir <new>；交叉部分意味着需要重新生成，增加边距或按归属切片，切勿使用最大组件过滤器
对精灵表进行键控、切片和注册	generate2dsprite.py process --input <sheet> --target asset --mode <mode> --rows R --cols C --output-dir <new> --strict-qc（几何 v2；参见 processing.md）
以M源像素/艺术像素绘制的像素艺术	process --resampler nearest --logical-pixel M --pixel-scale N（仅整数缩放）
在一个注册点上有跳跃、弹跳或后坐力	process --scale-strategy registered（或 --anchor-px X,Y）
同一角色跨动作的缩放	首先在接地参考上使用 process --write-scale-profile <p.json>，然后使用 --scale-profile <p.json> --max-profile-scale-drift 0.08
画布无法整除网格；其他行顺序	process --grid-rounding nearest 或 --pad-to-grid；--direction-order down,up,left,right（参见 modes.md）
身份、近/远腿交替、漂移、基线	sheet_qc.py frames --sheet <sheet> --rows R --cols C --cycle run --output-dir <new>；重复的半循环意味着重新生成后半部分。对于代码绘制的帧（art_source=code），identity_residual 和 torso_drift 仅供参考
游戏尺寸在一个画布和一个根上，绝不超出边界	scale_frames.py --frames <pngs> --root-lock torso-x --row-baseline --emit-clips --ticks N --output-dir <new>；后续动作添加 --profile <first>/scale-frames.json --action-padding L,T,R,B
带时间、事件、过渡的片段	build_animation_clips.py --manifest clips.json --output-dir <new>；读取 lint 输出和 review/ 文件夹（参见 frames-and-clips.md）
整帧或场景循环（无需键控）	assemble_frames.py（--key chroma，--slice ownership；仅环境循环使用 --loop-overlap K --ambient）
共享调色板、锁定、变体、闪烁（像素完成度）	palette_tool.py build，apply，lock，quantize-seq，variants，luts；严格逻辑网格：pixel_reduce.py（参见 palette-and-pixels.md）
引擎导出	export_engine.py --clips <animation-clips.json> --target all --output-dir <new>；Sprite3D：--target godot-sprite3d --world-height <units>（参见 engine-export.md）
在游戏中播放片段（步态、受击暂停、过渡）	参见 runtime-integration.md
代码绘制的精灵、骨架或特效，仅按需	使用 codeart2d 的 render_pixelspec.py，rig_animate.py 或 fx_build.py 并加上 --build-clips（绝不使用 process），然后 export_engine.py；将其披露为代码绘制
Hi-Bit 游戏的特效	fx_pixelfx.py check 选择路由（用户命名的路由优先）。路由A，已安装 pixelfx（推荐）：fx_pixelfx.py render --pixelfx <checkout> --id <effect> --ramp ... --snap <palette.json>，pixelfx 来自 https://github.com/patch-gg/pixelfx，由 Patch 开发（MIT 协议，一个用户克隆的独立项目），附带 CREDITS.txt 并披露为 pixelfx 代码绘制。路由B，否则：从图像路由生成 2x2 特效精灵表，使用 process --scale-strategy registered --cell-size 512，然后使用 hibit_fx.py pixelize --palette <palette.json>（参见 hibit.md）

验收

• 在游戏实际尺寸下审查：剪影和身份、接触和飞行、循环接缝或一次性恢复、在亮色和暗色背景上的透明度、四肢、跨动作的缩放、根部和碰撞体。
• 引用数字进行质量声明：pipeline-meta.json 中的 matte.qa（key_ring_spill 警告：添加 --despill-radius 1 或 --key-quality soft）、sheet-qc.json、片段构建器的 lint 输出。数字QC能发现症状；但它从不批准解剖或运动。
• 逐字报告每个 WARN 或 FAIL 检查（id、值、阈值、文件），来自每个已发布的 QA 信封；当任何已发布的信封有警告时，切勿说“所有检查通过”。
• 交付已接受的原艺术资产、运行时帧或片段、预览、提示词和来源信息（路由、模型、estimateUsd）、质量检查结果以及剩余限制。在修订时保留最后一个已接受的资产包。

参考文档

processing.md（处理标志，旧版开关），modes.md，prompt-rules.md