game-character-sprites

游戏角色精灵

概述

使用此技能制作可直接用于游戏的固定单元格像素艺术角色动画。如果用户指定了单元格尺寸，则这些尺寸就是必须交付的范围。如果未指定尺寸，默认使用 64x64。

绝不擅自扩大或缩小范围。如果用户只要求“攻击和行走”，就只制作这些动作。如果用户要求 GIF，就交付 GIF/WebP 预览，而不只是图集 PNG。如果用户未指定方向，且要求制作完整的游戏角色移动素材包，则默认采用完整的 8 向方向；如果是快速示例、测试或单方向请求，则只使用一个方向并标注清楚。

工作区最低交付内容：

run/
  run-manifest.json
  source/<original-imagegen-output>.png
  <cell>/
    generated/<action>-<direction>.png
    frames/<action>-<direction>/<index>.png
    final/<action>-sheet-clean.png
    final/<action>-metadata.json
    qa/<action>-validation.json
    qa/<action>-contact-sheet.png
    qa/visual-review.json
    qa/previews/*-transparent-x4.webp
    qa/previews/*-transparent-x4.gif
    qa/previews/*-checker-x4.gif

范围

支持的单元格尺寸：32、64、128。

尺寸约定

用户要求的尺寸必须交付。如果用户要求 32x32 64x64 128x128，则为每种尺寸创建原生输出集：

run/32/...
run/64/...
run/128/...

除非用户明确表示可以接受缩放变体，否则不要将多尺寸请求缩减为单张 64x64 主图加缩放变体。如果必须以缩放变体作为备用方案，请将其标注为 scaled-32 或 upscaled-128，说明它们不是原生素材，也不要将其描述为创作的原生图集。

通常不要让 imagegen 生成组合的 32/64/128 联系表。组合的多尺寸联系表会让模型将尺寸视为一张图片中的布局元素，而不是独立的像素艺术预算。对于原生素材，请按每种请求的尺寸预算，分别生成各自的 imagegen 行条带。

多尺寸精灵图必须遵循严格的分辨率层级：

• 主级固定为 32x32：剪影、比例、姿势节奏和主要色块。
• 次级从 64x64 开始：内部线条、较大的面部／服装细节，以及锁定的主级形状内清晰可辨的次要形态。
• 第三级从 128x128 开始：微小高光、小褶皱、表面像素，以及锁定的主级和次级结构内的细小点缀。
• 概念上，较大尺寸应类似于 32px 设计的最近邻扩展，并在相同形状内增加信息。
• 较大尺寸不得更改主要剪影、肢体长度、身体比例、姿势序列或主要调色板色块。

对于原生多尺寸任务，应按层级执行工作流程，而不是把三种尺寸作为三张互不相关的图来绘制：

generate the 32px strip directly as a 32px-budget pixel-art row
visually accept the 32px primary silhouette, pose timing, and main color blocks
generate the 64px strip directly as a 64px-budget row, using the accepted 32px strip as the primary-structure reference
generate the 128px strip directly as a 128px-budget row, using the accepted 32px and 64px strips as structure references
assemble each size with --cell <cell>
clean each size with --cell <cell>
validate each size with --cell <cell>
run hierarchy QA by making thumbnail comparisons only; do not create assets by downsampling
export previews for each size

单元格尺寸指南：

• 32x32：简化细节、夸张剪影、减少颜色，避免添加模糊不清的微小面部／配件细节。
• 64x64：适合游戏原型和清晰易辨的 Q 版角色的均衡默认尺寸。
• 128x128：原生重绘，增加更多像素细节并让次级动作更流畅，而不是将 64 放大到最近邻尺寸。

不予验收的情况：如果用户要求多种尺寸，而最终回复只包含创作的 64px 图集以及缩放的 32/128 变体，则任务不完整，除非用户同意这种折中方案。

如果 32/64/128 是三张不一致的图，也不予验收。原生的大尺寸版本可以增加细节，但缩小后必须与相同的 32px 主剪影和主要色彩布局一致。

默认方向：

south, south-east, east, north-east, north, north-west, west, south-west

只创建用户要求的方向。对于完整的 8 向导出，按上述顺序排列。

单方向任务

包含“一个方向”“单方向”“只要一个方向”“1 个方向”或“测试一个方向”的请求，表示：

rows: 1
directions: <requested direction, or south/front if the reference is front-facing>

不要将单方向任务扩展为 4 向或 8 向图集。如果用户提供了正面朝向的参考图但未指定方向，则使用 south，并说明测试使用的是参考图所示的朝前方向。

单方向多尺寸测试的预期输出如下：

run/32/final/walk-sheet-clean.png   # 192x32 for 6 frames
run/64/final/walk-sheet-clean.png   # 384x64 for 6 frames
run/128/final/walk-sheet-clean.png  # 768x128 for 6 frames

默认帧数：

idle:   4 frames, optionally padded to 6 cells
walk:   6 frames
attack: 6 frames

Agent 工作流

1. 明确请求范围：单元格尺寸、动作、方向、帧数、武器／职业，以及必须保留的参考细节。明确指定的尺寸必须作为必需输出。
2. 根据用户提供的参考图确定角色。如果图像工具无法读取文件路径，请使用聊天上下文中附加的图片；如果没有可用于视觉参考的内容，请停止并说明无法使用该参考图，而不要凭空编造一个仅基于文字、与参考图不符的角色。
3. 在生成之前创建 run/run-manifest.json。记录参考来源、身份细节、请求范围和计划采用的生成方法。
4. 先为请求的最小尺寸制作一个高质量的标准基础精灵图，通常为 32x32，以便先确定主要设计，再添加细节。
5. 每次只生成一个动作、方向和尺寸的条带，例如先生成 32/walk-south，再生成 64/walk-south，然后生成 128/walk-south。
6. 对于多尺寸任务，每个请求的尺寸都必须有单独的 imagegen 输出文件。不要使用一张 imagegen 联系表作为多个原生尺寸的来源。
7. 在 run/run-manifest.json 中记录每个生成的条带，包含 method: "imagegen"、单元格尺寸、动作、方向、imagegen 输出路径、源路径和提示词路径。
8. 使用 scripts/assemble_action_sheet.py 组装条带。
9. 使用 scripts/pixel_snap.py 进行清理，并使用色度键清理方式。
10. 使用 scripts/validate_sheet.py 和 scripts/audit_sprite_motion.py 验证几何形状、残留和动作。
11. 对于多尺寸任务，使用 scripts/validate_resolution_hierarchy.py 验证分辨率层级。
12. 使用 scripts/export_animation_previews.py 导出预览。
13. 目视检查每张联系表，以及每个方向组至少一张 GIF/WebP，然后编写 qa/visual-review.json。不要只依赖验证 JSON 来评估美术质量。
14. 使用 scripts/validate_run_manifest.py 验证来源信息和视觉验收结果。
15. 只重新生成质量较弱的方向或帧，不要重做质量较高的行。

不要在一条图像提示词中生成完整的八方向图集。一次性生成的图集经常会出现步行动作帧近乎重复、方向偏移、方向缺失和角色不一致等问题。

对于 Web/ChatGPT Agent，请使用基于 CLI 和文件的工作流。将产物写入工作区，在平台提供文件导出／分享工具时调用该工具，然后返回最终图集、元数据、联系表、验证 JSON 和预览 GIF/WebP 文件的可下载链接。如果 UI 需要导出的文件，仅提供 /workspace/... 文本路径是不够的。

不要将未经处理的色度键条带作为最终结果展示。原始条带仅用于中间 QA。最终视觉预览必须是经过清理的透明 WebP/GIF 或棋盘格背景的 GIF／联系表。

使用聊天附件作为参考时，请在运行文件夹中记录一条身份说明，列出从图片中准确保留的细节。除非图片确实不可用，否则不要写“退而使用提示词”。即使聊天中可见的图片无法作为常规文件系统路径访问，它仍可作为身份说明的有效视觉依据。

图像生成文件交接

图像生成结果必须先成为本地文件，技能才能完成。在 Codex Desktop 中，生成的图像会保存到：

D:\CodexHome\generated_images\<thread-id>\<image-id>.png

将选定的图像生成结果复制到 run/source/，并保留原文件。如果平台无法将生成的图像作为文件提供，请停止并说明图像已生成，但无法处理成精灵图文件。不要声称精灵图包已完成。

标准原生工作流：

imagegen -> run/source/32-walk-south.png -> run/32/generated/walk-south.png
imagegen -> run/source/64-walk-south.png -> run/64/generated/walk-south.png
imagegen -> run/source/128-walk-south.png -> run/128/generated/walk-south.png

每张源图都必须专门针对相应的单元格尺寸预算生成。例如，32 图像生成提示词应要求仅生成一行六帧 32x32 图像。64 提示词应要求仅生成一行六帧 64x64 图像。128 提示词应要求仅生成一行六帧 128x128 图像。

仅限紧急备用方案：如果图像生成已经返回一张多尺寸联系表，可使用 scripts/import_imagegen_contact_sheet.py 进行抢救，以便诊断。此输出必须在清单中标记为 imported_contact_sheet: true，除非用户明确接受此备用方案，否则不得称其为原生多尺寸处理流程。

python "<skill>/scripts/import_imagegen_contact_sheet.py" \
  --input path/to/imagegen-output.png \
  --run-dir path/to/run \
  --action walk \
  --direction south \
  --sizes 32,64,128 \
  --columns 6 \
  --key-color "#00ff00" \
  --copy-source

这会创建：

run/32/generated/walk-south.png
run/64/generated/walk-south.png
run/128/generated/walk-south.png
run/source/<imagegen-output>.png
run/imagegen-import-report.json

然后继续进行组装、清理、验证、预览、清单验证和视觉检查。

参考资料与来源验证关卡

除非视觉源条由 $imagegen 根据用户提供的参考生成，否则该次运行不算有效的美术测试。仅有文字形式的身份说明并不足够。

必需的清单：

{
  "reference": {
    "source_type": "chat_attachment",
    "source": "attached image #1 or path/to/reference.png",
    "used_for_generation": true,
    "identity_notes": [
      "green bird/penguin body",
      "red and white cap",
      "white unicorn float",
      "rainbow tail",
      "sandals"
    ]
  },
  "scope": {
    "sizes": [32, 64, 128],
    "actions": ["walk"],
    "directions": ["south"],
    "frames": 6
  },
  "generation": {
    "method": "imagegen",
    "imagegen_output_path": "run/source/32-walk-south.png",
    "procedural": false,
    "text_only": false,
    "imported_contact_sheet": false
  },
  "strips": [
    {
      "cell": 32,
      "action": "walk",
      "direction": "south",
      "method": "imagegen",
      "imagegen_output_path": "run/source/32-walk-south.png",
      "source_path": "run/32/generated/walk-south.png",
      "prompt_path": "run/32/prompts/walk-south.txt"
    }
  ],
  "visual_review": {
    "path": "run/32/qa/visual-review.json"
  }
}

验收受阻的情形：

• generation.method 为 procedural、python_draw、script、text_only，或任何非 imagegen 值
• 缺少 generation.imagegen_output_path，或该路径不是实际的本地文件
• 未经明确批准使用备用方案，就将一个图像生成结果重复用作多个所需原生尺寸的源文件
• generation.imported_contact_sheet 为 true，但最终回复却将输出称为原生生成
• reference.used_for_generation 不为 true
• 生成的条带由本地绘图代码制作
• 最终回复将程序化冒烟测试称为真实的图像／参考测试
• 视觉检查认为精灵图与参考、方向或所要求的动作不符

本地代码只能为脚本单元测试创建微型测试样例。这些输出必须标记为 pipeline-only，不得作为美术资源交付，也不得用来声称技能能够生成所需角色。

子 Agent

如果用户明确要求使用子 Agent 或并行 Agent，请按动作或方向拆分工作：

• Worker A：基础精灵图和身份说明
• Workers B/C/D：各自独立制作不同方向的条带，并使用互不重叠的输出路径
• QA worker：验证／联系表检查和薄弱行列表

各 Worker 只能编辑分配给自己的文件，不得覆盖其他 Worker 的输出。主 Agent 负责整合各行、运行验证，并且只重新生成薄弱方向。

方向锁定

根据以下规则提示并排除方向：

• south：面朝前，脸部／身体朝向镜头
• north：背朝前，能看到后脑／身体背面
• east：侧面朝向屏幕右侧
• west：侧面朝向屏幕左侧
• 对角方向必须与相邻方向明显区分
• 如果每一帧都逐渐偏向屏幕右侧，则排除该行
• 如果只有脚在移动，但躯干／头部方向始终不变，则排除该行

方向错误时，只重新生成薄弱方向，并使用明确措辞，例如“背朝前的北向，不要露出正脸”或“侧面朝左，向西行走”。

生成规则

使用 $imagegen 生成视觉内容。不要用本地代码手绘缺失的动画帧。脚本可以裁剪、组装、量化、对齐、验证和预览已生成的美术资源。

基础精灵图提示词：

<cell>x<cell> pixel-art game sprite, single character, transparent or flat chroma-key background.
Readable silhouette, hard pixel edges, limited palette, no UI, no text, no frame border.
Preserve: <identity details>.

行条带提示词：

<cell>x<cell> pixel-art game sprite animation strip.
One horizontal row of exactly <N> separated frames.
Action: <action>. Direction: <direction>.
Flat pure solid chroma-key background <key color>, no gradient, no rounded panel, no shadows, no floor, no UI, no text, no frame numbers.
Preserve the canonical character identity exactly.
Hard pixel-art edges, saturated readable colors, clear green/magenta space between frames.

优先使用 #00ff00 色度键。如果角色或 VFX 使用绿色，则改用 #ff00ff。遇到渐变背景、圆角彩色卡片、帧分隔缺失、身体／武器被裁切或包含任何文字／标签的条带时，应予以拒绝并重新生成。不要尝试通过等分切片来挽救结构糟糕的条带。

行走质量

不要一次性生成整张行走表。每个方向分别生成 6 帧条带。

使用以下姿势结构：

contact, down, passing, up, contact, passing

生成前锁定以下动画规则：

• 头部上下摆动：1-2 px
• 臀部移动：1 px
• 手臂和腿做相反方向的摆动
• 披风/头发比躯干慢一帧
• 持武器的手保持稳定
• Q 版/小尺寸精灵需要夸张动作才能清晰呈现

如果行走看起来像几乎重复的站立姿势，请使用更强的提示词重新生成该方向：“步幅轮廓清晰易读，双脚交替，接触/下沉/经过/抬起姿势明确。”

跳跃质量

跳跃使用 6 帧：

crouch, launch, rise, apex, fall, land/recover

角色身体应在单元格内垂直移动，同时保持在边距范围内。下蹲/落地时，腿部必须明显压缩。头发、披风、耳朵、尾巴或衣物应略有滞后。如果角色只是改变手臂姿势而双脚保持不动，请舍弃该跳跃帧行。

攻击质量

近战攻击应展现蓄势、挥击/接触和恢复阶段。武器轨迹必须与武器相连，并保持在单元格内。

弓箭手攻击应包含拉弓、保持/瞄准、释放、后坐和恢复阶段。除非用户要求将其放在帧内，否则投射物应作为单独的 VFX。持弓的手应保持稳定，方向准确。

如果攻击看起来被截断，请检查边缘像素和 bbox。仅重新生成该帧行，并使用提示词：“每帧的完整身体和武器都在画面内，不裁切，居中并留出 2-4 px 边距。”

色度键与清理

分两步移除色度键：

1. 边缘连通泛洪移除：仅删除与图像边缘连通的键色像素。
2. 最终残留清理：适配帧后，仅移除几乎完全一致的键色像素。

切勿全局删除所有偏绿色的像素。许多精灵会用绿色表现魔法、毒素、赛博光效、眼睛或衣物。

建议的清理方式：

python "<skill>/scripts/pixel_snap.py" \
  --input path/to/source.png \
  --output path/to/clean.png \
  --cell <cell> \
  --palette 96 \
  --alpha-threshold 12 \
  --chroma-key "#00ff00" \
  --edge-flood-threshold 105 \
  --residue-threshold 72

攻击/VFX 使用调色板 96-128，简单的待机/行走使用 32-64。仅当生成的美术效果过于平滑时才使用 --pixelate-scale 2。

可选的 TachiSnap 阶段：如果有 TachiSnap，当生成的像素网格不均匀时，在移除色度键之后、最终预览之前使用它。TachiSnap 是一款客户端 Rust/WASM 像素吸附工具，支持 k-means++ CIELAB 调色板量化、泛洪/全局背景移除、GIF/图集动画支持、批量文件夹处理、JSON 报告和最近邻放大。不要让它改变图集几何结构；逐条带或逐帧运行，然后使用技能脚本重新组装。

TachiSnap 的 Agent 安全用法示例：

tachi-snap bulk ./input-ai-pixel-art ./output-clean \
  --recursive \
  --k 16 \
  --pixel-size 0 \
  --upscale 4 \
  --remove-bg \
  --bg-mode flood \
  --json

组装

将独立条带组装成一个动作图集：

python "<skill>/scripts/assemble_action_sheet.py" \
  --input-dir path/to/generated \
  --output path/to/final/walk-sheet.png \
  --action walk \
  --cell <cell> \
  --columns 6 \
  --frames-dir path/to/frames \
  --key-color "#00ff00"

然后对组装好的图集或帧运行清理。

使用随附的组装器，避免编写临时切片代码。只有当生成的条带帧槽宽度完全一致，且通过残留、边缘和动作质量检查时，才可接受等宽切片。如需使用自定义备用脚本，请将其保存在运行文件夹中，并确保输出与随附脚本相同。

验证

最终回复前进行验证：

python "<skill>/scripts/validate_sheet.py" \
  --input path/to/final/walk-sheet-clean.png \
  --rows <rows> \
  --columns 6 \
  --cell <cell> \
  --row-names <comma-separated-requested-directions> \
  --chroma-key "#00ff00" \
  --fail-on-warnings \
  --json-out path/to/qa/walk-validation.json \
  --contact-sheet path/to/qa/walk-contact-sheet.png

对每个行走、奔跑和跳跃图集运行 scripts/audit_sprite_motion.py。用户抱怨行走效果差、缺少方向、动作幅度弱、残留色度键颜色或帧混杂时，也要运行该脚本。将警告视为需要重新生成的清单，而不是重做全部内容的理由。

验证运行图集的来源，并进行人工视觉检查：

python "<skill>/scripts/validate_run_manifest.py" \
  --manifest path/to/run/run-manifest.json \
  --required-sizes 32,64,128 \
  --required-actions walk \
  --required-directions south \
  --require-visual-review

仅将多尺寸层级验证用作 QA。此命令会比较缩略图以检查结构是否发生偏移。绝不能用它来创建 32px、64px 或 128px 资源：

python "<skill>/scripts/validate_resolution_hierarchy.py" \
  --base32 path/to/run/32/final/walk-sheet-clean.png \
  --sheet64 path/to/run/64/final/walk-sheet-clean.png \
  --sheet128 path/to/run/128/final/walk-sheet-clean.png \
  --rows <rows> \
  --columns 6 \
  --json-out path/to/run/qa/resolution-hierarchy.json \
  --fail-on-warnings

视觉审查文件：

{
  "accepted": false,
  "reviewer_notes": "Reject until this is manually inspected.",
  "checks": {
    "reference_identity": "fail",
    "direction": "fail",
    "animation_readable": "fail",
    "frame_separation": "fail",
    "not_procedural": "fail"
  }
}

只有当接触表和预览动画确实与用户参考相似，并且符合要求的动作和方向时，才将 accepted: true。

出现以下情况时，不得通过验收：

• 图集尺寸错误
• 必需帧为空
• 精灵意外触及单元格边缘
• 仍有色度键残留
• 透明 GIF 帧累积或出现拖影
• 行走帧几乎完全重复
• 行的方向偏移错误
• 攻击特效脱离主体、尺寸过大或被裁切
• 运行清单无法证明图像生成/参考来源
• 缺少视觉审查，或审查未获通过
• 多尺寸输出未通过分辨率层级 QA 检查

验证通过只能证明几何与像素处理规范，并不能证明动画效果良好。声称素材包“扎实”“干净”或“已就绪”之前，Agent 必须检查接触表和预览。

导出预览

透明预览优先使用动画 WebP。GIF 用于兼容性输出。

python "<skill>/scripts/export_animation_previews.py" \
  --atlas path/to/final/walk-sheet-clean.png \
  --rows <rows> \
  --columns 6 \
  --cell <cell> \
  --row-names <comma-separated-requested-directions> \
  --prefix walk \
  --out-dir path/to/qa/previews \
  --scale 4

GIF 规则：

• 使用全局调色板
• 调色板索引 0 保留为透明色
• disposal=2
• 不使用抖动
• 不使用会将 disposal 改为 1 的优化器

用户索要 GIF 时，务必发送预览链接。

对于 128x128，要区分原生重绘和放大。如果用户要求原生 128，应生成原生 128 条带。将 64px 图像用最近邻算法放大 2 倍，属于放大素材包，而非原生 128 资源。

对于 32x32，要区分原生简化和缩小。如果用户要求原生 32，应生成或重绘简化的 32px 条带。将 64px 图像用最近邻算法缩小一半，属于缩小版本，而非原生 32 资源。

定向重新生成

用户说“效果好多了，但有些方向缺失”或“重新生成效果弱的方向”时，请执行以下操作：

1. 检查接触表和预览动画。
2. 按动作和方向列出效果较弱的行。
3. 以规范基础素材和未通过的行作为上下文，仅重新生成这些条带。
4. 重新组装、清理、验证并预览。

除非用户明确要求全部重做，否则不要覆盖效果良好的已生成条带。