AI Game Asset Pipeline

AI Game Asset Pipeline

端到端的 AIGC 游戏素材管线：提示词构造 → AI 生成 → 格式校验 → 后处理 → 引擎导入。 覆盖图片（角色/场景/UI）、音频（BGM/音效）、3D 模型三大类资源。

⚠️ Hard Rules

1. AIGC 产出必须格式校验 — AI 生成的文件格式不可控（可能是 AVIF、WebP、HEIC 等），必须经过步骤 3 的格式校验后才能写入项目资源目录。直接放入会导致引擎导入失败或运行时崩溃
2. 魔数优先，不信任扩展名 — 文件格式判定必须读取文件头（magic bytes），不能只看 .png / .jpg 等扩展名。AIGC 工具经常输出扩展名错误的文件
3. 转换前备份原文件 — 执行格式转换时，必须将原文件备份到 {output_dir}/.originals/，防止转换失败导致素材丢失
4. 禁止静默覆盖 — 目标路径已有同名文件时，必须询问用户选择：覆盖 / 重命名 / 跳过
5. 单批次上限 50 个文件 — 批量处理时单次不超过 50 个文件，超过时自动分批并在每批间输出进度
6. 音频必须检查采样率 — 游戏音频统一采样率为 44100 Hz / 16 bit，不符合的必须重采样，否则引擎播放会出现杂音或变速

触发条件

当用户说以下内容时触发本 Skill：

• "用 AI 生成角色立绘" / "帮我画一个怪物"
• "生成游戏背景音乐" / "做一个攻击音效"
• "把这些图片导入引擎" / "批量转换素材格式"
• "检查素材兼容性" / "哪些文件格式不支持"
• "generate game textures" / "import assets to engine"

不触发条件

以下情况应使用其他 Skill：

• 用户想生成关卡配置（不是素材） → 使用 ai-game-level-generator
• 用户想手动编辑已有素材（调色、裁剪） → 使用图片编辑工具
• 用户想测试素材在游戏中的表现 → 使用 ai-game-playtester
• 用户仅想查看资源列表 → 使用资源索引工具

输入参数

格式兼容性参考

以下矩阵列出常见格式在大多数游戏引擎中的兼容情况。 实际使用时应以你的目标引擎文档为准。本表仅作为校验和转换决策的参考依据。

图片格式

音频格式

3D 模型格式

执行流程

步骤 0：前置检查

1. 确认运行模式：根据用户输入判断 mode（generate / import / convert）
2. 确定目标引擎：
   • 若用户指定了 target_engine → 使用指定值
   • 若为 auto → 扫描项目根目录的引擎配置文件自动判断
   • 若无法自动判断 → 询问用户，或使用 generic（仅保留通用安全格式：PNG + WAV + GLTF）
3. 检查输出目录：output_dir 不存在时自动创建

步骤 1：素材获取

根据 mode 执行不同的获取逻辑：

生成模式 (generate)：

构造 AIGC 提示词并调用生成服务：

导入模式 (import)：

扫描 source_dir 中的所有资源文件，按扩展名分类统计。

转换模式 (convert)：

扫描 source_dir，筛选出目标引擎不兼容的文件。

步骤 2：格式校验

对每个文件执行以下校验链：

文件输入
  → 1. 读取文件头 magic bytes（前 16 字节）
  → 2. 判定真实格式（不看扩展名）
  → 3. 查询兼容矩阵，确认目标引擎是否支持
  → 4. 检查分辨率/采样率/面数等品质参数
  → 5. 输出校验报告

Magic Bytes 参考：

校验报告格式：

📋 素材校验报告
━━━━━━━━━━━━━━━━━━
目标引擎: generic (通用安全格式)
扫描文件: 12 个
━━━━━━━━━━━━━━━━━━
✅ 兼容 (8):
  - player_idle.png (PNG, 512x512)
  - attack_sfx.wav (WAV, 44100Hz, 16bit)
  ...

⚠️ 需转换 (3):
  - bg_forest.avif → 建议转 PNG
  - ambient.flac → 建议转 OGG
  - hero.heic → 建议转 PNG

❌ 不可用 (1):
  - corrupt_file.dat → 文件损坏，无法识别格式

步骤 3：后处理与转换

对需要转换的文件，先展示转换计划并等待用户确认：

🔄 转换计划：
  1. bg_forest.avif → bg_forest.png (无损)
  2. ambient.flac → ambient.ogg (有损, 品质 8)
  3. hero.heic → hero.png (无损)

原文件将备份到 assets/.originals/
确认执行？ [Y/n]

用户确认后执行转换：

图片转换规则：

音频转换规则：

步骤 4：导入项目资源目录

将处理后的文件按项目的目录结构放置。

通用推荐目录结构（适用于大多数引擎和框架）：

{project_root}/
├── assets/
│   ├── sprites/         ← 角色/物体精灵图
│   ├── backgrounds/     ← 场景背景
│   ├── ui/              ← UI 图标和界面元素
│   ├── audio/
│   │   ├── bgm/         ← 背景音乐
│   │   └── sfx/         ← 音效
│   └── models/          ← 3D 模型

注意：如果项目已有资源目录结构，应遵循已有结构而非强制使用上述结构。 步骤 0 的 Runtime-First 原则同样适用——先读取项目已有目录布局，保持一致。

写入后列出结果清单：

✅ 素材导入完成 (11 个文件)
━━━━━━━━━━━━━━━━━━
  assets/sprites/player_idle.png (45 KB)
  assets/sprites/player_run.png (62 KB)
  assets/audio/sfx/attack.wav (128 KB)
  assets/audio/bgm/forest_theme.ogg (1.2 MB)
  ...

📁 备份目录: assets/.originals/ (3 个原始文件)

完成标志

所有文件校验通过并已写入引擎资源目录后，输出：

<promise>DONE</promise>

错误处理

与其他 Skill 的协作

用户描述需求 / ai-game-level-generator 生成关卡主题
    ↓
ai-game-asset-pipeline (本 Skill)
    ├─ 步骤 1: AIGC 生成 / 用户提供素材
    ├─ 步骤 2: 格式校验
    ├─ 步骤 3: 后处理与转换
    └─ 步骤 4: 写入引擎资源目录
    ↓
ai-game-playtester (可选)
    ├─ 验证素材是否正确加载
    └─ 检查渲染/播放效果