精灵图生成器是做什么的？

输出

生成并验证后的精灵图、预览图以及 Godot 集成文件。

非目标

使用本地绘图脚本替代实际的图像生成。

目的

根据概念、一张或多张参考图像或详细的艺术指导说明，创建面向生产的二维游戏精灵图。该技能故意保持风格无关：用户可以提供参考图像、风格卡、截图或生动描述，工作流会将其转化为可复用的精灵图生成运行，包含提示词、基础图像、生成的基础参考、动画/状态任务、确定性提取、质量控制和 Godot 启动文件。

目标不仅仅是生成漂亮的图片。目标是生成能够放入 Godot 项目的资产，具有可预测的文件名、透明背景、整洁的图集、帧元数据、质量保证联系表以及 SpriteFrames 启动资源。

使用此技能处理如下请求：

"为房子创建家具，包含干净和脏的版本。"
"以这种艺术风格制作一个角色，包含待机、行走、指向和清洁动画。"
"以与参考图相同的风格创建玩偶屋房间地图。"
"生成替代服装/颜色变体，并保持相同的身体比例。"
"将此物体草图转换为可直接用于游戏的透明道具精灵图。"

输入

接受以下任意组合的输入：

参考图像： 风格表、现有角色、道具、截图、情绪板、调色板、之前生成的精灵图或游戏内截图。
生动描述： 资产名称、角色、形状、材质、颜色、比例、摄像机角度、预期用途和风格形容词。
资产类型： character、npc、player、furniture、prop、object、map、room、dollhouse 或通用 sprite。
动画： 命名动作、帧数、方向、循环/一次性行为、持续时间或 FPS，以及特殊姿势备注。
状态和变体： 干净/脏、打开/关闭、健康/枯萎、空/满、服装 A/B、颜色集、损坏程度等。
集成目标： Godot 版本、单元格大小、图集列数、缩放比例、俯视/等距/侧视摄像机以及首选导入路径。

如果用户遗漏了细节，则推断合理的默认值，并使输出易于迭代。不要在每个缺失的细节上都卡住。仅在遗漏会导致代价高昂的错误工作时才提出澄清问题，例如未知风格、未知角色身份或必需的动画列表。

视觉生成委派

实际艺术必须使用环境的图像生成能力生成，而不是本地脚本。在 Codex 风格的技能环境中，如果可用，则委托给已安装的 $imagegen 技能。在 ChatGPT 中，当用户要求实际创建视觉资产时，使用原生图像生成工具。捆绑的 Python 脚本仅用于确定性的生产步骤。

允许的确定性步骤：

创建运行文件夹和提示文件
将稳定的参考图像复制到运行文件夹中
创建布局指南图像
记录选定的生成输出
去除平坦的色键背景
将序列拆分为帧
裁剪、缩放、填充和居中帧到一致的单元格中
合成 PNG/WebP 图集
生成联系表和 GIF 预览
编写 JSON 清单和 Godot 启动资源

硬性边界：不要使用 Pillow、SVG、CSS、HTML Canvas 或编程形状来绘制、上色、合成、平铺、扭曲或发明精灵图艺术，以替代图像生成。脚本可以处理生成的图像；它们不能用作隐藏的艺术生成器。

风格捕获和风格锁定

当提供风格参考时，将其视为事实来源。将以下品质提取到提示计划中：

摄像机角度和视角：正面、侧面、俯视、等距、3/4、玩偶屋、正交
比例：Q版、写实、矮胖、高瘦、玩具般、像素、绘画感、扁平矢量、低多边形渲染
线条和边缘处理：无轮廓、粗轮廓、柔和渲染边缘、像素边缘、卡通着色边框
材质和光照：黏土、毛绒、塑料玩具、彩绘 3D、扁平卡通、光泽、哑光、水彩等
调色板和饱和度
阴影策略：透明精灵无阴影，除非明确保留为物体的一部分
背景策略：透明或用于提取的平坦色键
在目标单元格大小下的比例和可读性

如果某一行或状态看起来是不同风格的相关资产，而不是目标风格下的同一资产，则视为失败。

资产类型默认值

角色/NPC/玩家

如果用户未指定动画，默认输出：

动画	帧数	用途
`idle`	4	呼吸/眨眼循环；第一帧可作为静态姿势使用
`walk_down`	6	正面/向下移动
`walk_up`	6	背面/向上移动
`walk_left`	6	面向左侧的侧视移动
`walk_right`	6	面向右侧的侧视移动

可选常用动作：point、talk、pickup、carry、clean、use_item、sit、sleep、cry、celebrate、fail、interact、attack、cast、jump、push、pull。

家具/道具/物体

如果用户未指定状态，默认输出：

状态	帧数	用途
`clean`	1	正常/整洁状态
`dirty`	1	同一物体的脏乱/杂乱状态

可选常用状态：empty、half_full、full、overflowing、open、closed、on、off、healthy、wilted、broken、repaired、selected、highlighted、locked、unlocked。

地图/房间/玩偶屋

默认输出是一张大尺寸 map_base 精灵图或背景。对于房间，指定是需要单个扁平的艺术图层，还是单独的图层，例如 floor、walls、furniture、interactables、path_overlay 和 collision_reference。除非请求作为单独的覆盖层，否则不要在成品地图艺术中包含 UI 标签、箭头、路径线或教程覆盖层。

背景和透明度规则

当图像工具不能可靠地生成真正的 Alpha 通道时，首选平坦的色键背景。默认键为 #00ff00。最终图集应为提取后的透明 PNG/WebP。

对于生成的源图像：

在整个序列或物体渲染中使用一种平坦的背景色
保持资产与色键视觉上分离
当使用绿色键时，避免资产具有绿色高光/材质；如果资产需要绿色，则选择品红色或蓝色键
无白色背景、棋盘格背景、UI 面板、标签、帧编号、可见网格、边框或场景
无投射阴影、地板阴影、辉光、柔和的透明光晕、灰尘云、速度线、运动轨迹或松散的分离特效，除非小型附加的不透明特效明确是精灵图的一部分
每个帧必须完整、分离、未裁剪且位于其插槽内

动画提示规则

对于每个动画行/序列：

请求恰好声明的帧数
指定布局：通常为从左到右的水平序列
使用规范的基准图像和参考图像作为基础输入
保持身份、比例、调色板、材质、轮廓/边缘样式和摄像机角度一致
通过姿势变化传达运动，而不是通过模糊、速度线、灰尘或阴影
当 loop=true 时，第一帧和最后一帧应能干净地循环
对于方向性动画，明确请求方向，并避免角色有侧边特定配饰时意外镜像细节

如果某一行改变了角色的面部、身体形状、服装、道具设计、材质风格或相对于基准的比例，则不要接受。

可见进度计划

对于正常的资产运行，为用户保留一个可见的清单：

准备资产请求。
创建规范外观。
创建状态和动画行。
为 Godot 打包。

每个步骤的含义：

准备资产请求： 确定资产名称、资产类型、风格来源、输出、单元格大小、色键和运行目录。
创建规范外观： 生成或选择成为身份/风格锁定的基准参考。
创建状态和动画行： 使用基准和参考生成每个输出任务；仅修复失败的行/状态。
为 Godot 打包： 提取帧、合成图集、创建质量保证联系表、编写清单、编写 SpriteFrames 启动资源，并报告文件路径。

只有当实际文件或决策存在时，才标记步骤完成。

工作流

1. 准备运行文件夹

python3 ./scripts/prepare_sprite_run.py \
  --asset-name "Market Crate" \
  --asset-type prop \
  --description "readable wooden market crate with colorful contents" \
  --style-notes "match the supplied game art reference" \
  --reference /absolute/path/to/style_reference.png \
  --state full:1:"crate full of items":single:once \
  --state empty:1:"same crate empty":single:once \
  --cell-size 256x256 \
  --columns 2 \
  --output-dir /absolute/path/to/run

对于角色：

python3 ./scripts/prepare_sprite_run.py \
  --asset-name "Player" \
  --asset-type character \
  --description "friendly player character with a clear silhouette" \
  --reference /absolute/path/to/style_reference.png \
  --animation idle:4:"gentle breathing and blink" \
  --animation walk_down:6:"walking toward camera" \
  --animation walk_up:6:"walking away from camera" \
  --animation walk_left:6:"walking left side view" \
  --animation walk_right:6:"walking right side view" \
  --cell-size 256x320 \
  --columns 6 \
  --output-dir /absolute/path/to/run

高级运行可以使用 JSON 配置文件描述，并通过 --config 传递。

2. 检查就绪任务

python3 ./scripts/sprite_job_status.py --run-dir /absolute/path/to/run

应首先生成 base 任务。在生成依赖任务之前，记录选定的生成基准图像。记录器写入 references/canonical-base.png，后续任务应将其用作输入图像。

3. 生成每个视觉任务

对于每个就绪任务，使用 imagegen-jobs.json 中列出的提示文件以及所有列出的输入图像。选择最佳的原始生成图像，然后记录它：

python3 ./scripts/record_imagegen_result.py \
  --run-dir /absolute/path/to/run \
  --job-id job-id-from-status \
  --source /absolute/path/to/generated-output.png

不要记录手动编辑的固定图、缩略图或来自运行最终帧文件夹的文件作为源艺术。记录选定的原始生成输出。

4. 最终确定

python3 ./scripts/finalize_sprite_run.py --run-dir /absolute/path/to/run

预期输出：

run/
  asset_request.json
  imagegen-jobs.json
  prompts/
  references/
  decoded/
  frames/frames-manifest.json
  final/spritesheet.png
  final/spritesheet.webp
  final/validation.json
  qa/contact-sheet.png
  qa/previews/*.gif
  qa/run-summary.json
  godot/<asset>_spriteframes.tres
  godot/<asset>_animated_sprite_2d.tscn
  godot/godot_import_manifest.json
  godot/README_GODOT.md

5. 复制到 Godot

python3 ./scripts/package_godot_assets.py \
  --run-dir /absolute/path/to/run \
  --project-dir /absolute/path/to/godot-project \
  --dest assets/sprites

打包后查看 godot/README_GODOT.md。如果将文件复制到不同的 res:// 位置，请更新生成的 .tres 文件内的纹理路径。

修复工作流

如果质量保证失败，首先修复最小范围：

单个错误状态或动画行。
单个错误帧，但前提是图像工具能够可靠地支持帧级编辑。
仅当身份/风格在所有地方都错误时，才修复规范基准。
仅作为最后手段，修复整个图集。

常见修复提示：

"仅重新生成 walk_left；保留精确的规范角色、服装、比例和玩具渲染风格。"
"仅重新生成 dirty；它必须是与 clean 相同的沙发，但毯子/枕头杂乱。"
"重新生成恰好 6 帧且无帧编号或标签的序列。"
"使用品红色色键，因为物体需要绿色材质。"

记录修复图像后，重新运行最终确定。

质量保证评价标准

在以下检查通过之前，不要接受资产：

生成的基准与请求的风格或提供的风格参考匹配。
每个状态/动画是相同的资产身份，而不是重新设计。
存在精确的帧数。
透明提取不会去除精灵图的重要部分。
帧完整、居中、填充且未裁剪。
没有标签、帧编号、网格线、水印、UI 面板或场景泄露到成品艺术中。
提取后没有多余的阴影、辉光、灰尘、速度线、模糊或分离特效。
联系表在目标尺寸下视觉上正确可读。
final/validation.json 没有错误；警告已进行视觉审查。
Godot 清单名称与您在代码中调用的动画名称匹配。

验收标准

完成的运行应包括：

references/canonical-base.png 中的规范基准参考
imagegen-jobs.json 中记录的选定生成源
提取的透明帧 PNG
final/spritesheet.png 以及（如果支持）final/spritesheet.webp
qa/contact-sheet.png
多帧动画的 GIF 预览
final/validation.json 无错误
godot/ 下的 Godot 启动文件
一份简短的面向用户的报告，说明哪些行/状态已修复或尽管有警告但已手动接受

规则

视觉方面使用视觉生成；脚本仅用于确定性处理。
对于多输出资产，始终使用规范基准。
当图像工具支持参考时，为每个依赖的视觉任务附加参考。
优先选择透明或与色键兼容的输出，而不是场景插图。
除非请求将其作为单独的覆盖资产，否则不要将 UI 标签、指示箭头、路径线或碰撞指南放入生产精灵图中。
对于 Godot，保持动画名称稳定且小写，使用

精灵图生成器