generate2dsprite

生成 2D 精灵图

制作游戏所需的最小资源包，尺寸、摄像机和风格均按游戏中的实际显示效果确定。 游戏逻辑（碰撞、伤害、计时）与美术资源保持独立。

适用场景

• 需要将角色、生物、道具、物品、图标或特效制作成主静帧、精灵图集或动画片段。
• 帧已存在（生成、绘制或代码绘制），需要制作动画片段、调色板或导出到引擎。

不适用场景

• 地图、图块、地形、视差或场景底板：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）、BytePlus Seedream（ARK_API_KEY）或 fal.ai（FAL_KEY），密钥可以在环境变量或用户配置文件中（route-media.md）。配置的密钥即表示所有者已同意，因此无需针对每次调用单独询问。
2. 本地：优先使用你自己的图像工具（Codex image_gen、Grok 原生工具）；如果没有，则使用用户已登录的 Codex CLI，然后使用 Grok CLI。
3. 仅当用户明确要求使用代码绘制美术资源，或 route_media.py 输出 no-route（退出码 3）时，才使用 codeart2d。此时应说明“代码绘制，无图像模型”。

每张图像都通过一个命令生成：python "<skill-dir>/../generate2dmedia/scripts/route_media.py" image --prompt-file <txt> --reference <png> --size 1024x1024 --out-dir <new>。该命令会按上述顺序选择路线，并输出一行包含 route、artifact、sha256 和 estimateUsd 的 JSON；resolve --kind image 会说明将使用哪条路线。始终欢迎用户提供现有美术资源。绝不可声称完成了实际上未执行的生成；应保留提示词和约定，并报告缺失的能力。

• **收尾：**HD 是默认选项：全彩、干净的 Alpha、统一锚点，并按比例缩小至游戏中的高度。用户要求像素美术时，可选择像素风格收尾（统一调色板、二值 Alpha、不抖动）。绝不要提示图像模型生成逻辑像素网格；像素风格通过收尾处理实现。
• **角色：**每个角色先确认一张主静帧，再使用 video2dsprite 为其制作动画：每个动作从这张主图生成一个图生视频片段（sprite_set.py）。每个动作的角色高度都要与主图的静止姿势保持一致。
• 精灵图集适用于特效、图标、道具（以及用户提供的帧），不用于角色动画。

主静帧（每个角色动画都从这里开始）

每个角色先准备一张获批的主静帧，然后从它为每个动作生成一个图生视频片段（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（默认 HD；只有在提出要求时才用 pixel）、--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 "<one change>" --output-dir <new>（或 --master <dir>）。
5. 批准：master_still.py approve --run <dir> --take N --output-dir <new>（其他来源的静帧：--still <png> --route <what made it>）。此命令会为静帧添加色键，按 6 px 边距裁剪，并使用 LANCZOS 缩放至 1024x1024 画布上的对应类别构图（hero 高 788 px，顶部边距 138 px），然后写入 master.png（不透明，纯色键）、master_rgba.png 和 master.json（generate2dsprite.master.v1）。
6. 动作步骤会读取 master.json（identity_recap、facing、finish、class、framing、key、files、transform、route），绝不重新测量静帧；每个视频片段的提示词都以“The same <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：**其原生图像和视频工具是你自己的工具；请使用其真实 schema。

命令

从用户项目根目录运行每个工具，且每条命令单独一行：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 保留真实透明度（绘制出来的棋盘格不是真正的 alpha）；仅当主体没有透明度时，chroma_key 才使用纯洋红色；opaque 保留完整图像（assemble_frames.py）。
• 采样：生成的美术作品使用 lanczos 或预乘透明度的面积缩放；只有经验证的像素网格才使用 nearest。高分辨率的像素风绘画并不等于干净的 32 px 美术作品。
• 共享根位置不是逐帧 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）
身份、NEAR/FAR 交替、漂移、基线	运行 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；应注明它们是代码绘制的

验收

• 按游戏中的尺寸进行检查：轮廓与辨识度、接触与飞行、循环接缝或单次播放后的恢复、在浅色和深色背景上的透明通道效果、肢体末端、各动作间的缩放一致性、根节点与碰撞体。
• 质量声明须附上具体数值：pipeline-meta.json 中的 matte.qa（出现 key_ring_spill 警告时：添加 --despill-radius 1 或 --key-quality soft）、sheet-qc.json、剪辑构建器的 lint 检查。数值 QC 能发现症状，但无法判断解剖结构或动作是否合格。
• 逐字报告每个已发布 QA 结果包中的所有 WARN 或 FAIL 检查项（id、值、阈值、文件）；只要有任何已发布结果包包含警告，就绝不能说“所有检查均已通过”。
• 交付已验收的源美术素材、运行时帧或剪辑、预览、提示词和溯源信息（路由、模型、estimateUsd）、QA 结果和剩余限制。修订时保留最后一个已验收的交付包。

参考资料

processing.md（处理标志、旧版开关）、modes.md、prompt-rules.md、action-recipes.md、character-animation.md（动画索引）、frames-and-clips.md、palette-and-pixels.md、engine-export.md、runtime-integration.md、video-handoff.md；数据契约见 references/schemas/sprite.schema.json。