# AI Game Asset Pipeline

> 【AI 素材管线】当需要用 AIGC 生成游戏素材、验证素材格式兼容性、批量导入引擎资源目录时使用。适用场景：AI 生图后导入引擎、批量素材格式转换、素材兼容性检查、纹理图集生成、音效批量处理。触发词：生成素材、AI出图、素材导入、格式转换、生成贴图、生成音效、asset pipeline、generate texture、import assets、convert format、批量导入、素材检查。⚠️所有 AIGC 产出必须经过格式校验才能写入项目，严禁将引擎不支持的格式直接放入资源目录

- Skill: `gitcustomer/ai-game-asset-pipeline` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gitcustomer/ai-game-asset-pipeline`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gitcustomer/ai-game-asset-pipeline/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: gitcustomer (https://skillmd.com/u/gitcustomer)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/gitcustomer/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`
- 用户仅想查看资源列表 → 使用资源索引工具

## 输入参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `asset_type` | string | ✓ | - | 素材类型：`image` / `audio` / `model` |
| `prompt` | string | 条件必填 | - | AIGC 生成提示词（生成模式必填） |
| `source_dir` | string | 条件必填 | - | 已有素材的源目录（导入/转换模式必填） |
| `target_engine` | string | | `auto` | 目标引擎（自动检测或手动指定）：`auto` / `generic` / 其他引擎名 |
| `output_dir` | string | | `assets/` | 输出到项目资源目录 |
| `mode` | string | | `generate` | 模式：`generate`（AI 生成）/ `import`（导入校验）/ `convert`（格式转换） |

## 格式兼容性参考

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

### 图片格式

| 格式 | 通用兼容性 | AIGC 常见输出 | 建议 |
|------|:---------:|:------------:|------|
| PNG | ✅ 几乎所有引擎 | ✅ | **推荐格式**，无损 + 透明通道 |
| JPG | ✅ 几乎所有引擎 | ✅ | 适合背景，不支持透明 |
| WebP | ⚠️ 部分引擎需插件 | ✅ | AIGC 常输出此格式，需校验兼容性 |
| SVG | ⚠️ 少数引擎原生支持 | ❌ | 矢量图，通常需光栅化后使用 |
| AVIF | ❌ 大多数引擎不支持 | ✅ | AIGC 新兴格式，**必须转换为 PNG** |
| HEIC | ❌ 游戏引擎普遍不支持 | ✅ | Apple 专属格式，**必须转换为 PNG** |
| TGA | ✅ 多数引擎支持 | ❌ | Web 平台不支持 |
| EXR | ⚠️ 主要用于 HDR/光照贴图 | ❌ | 专业用途，非通用 |
| BMP | ✅ 广泛支持 | ❌ | 文件过大，建议转 PNG |

### 音频格式

| 格式 | 通用兼容性 | 建议 |
|------|:---------:|------|
| WAV | ✅ 所有引擎 | **推荐音效格式**，无压缩 |
| OGG | ✅ 大多数引擎 | **推荐 BGM 格式**，体积小 |
| MP3 | ✅ 大多数引擎 | 有专利历史，部分引擎推荐 OGG 替代 |
| FLAC | ❌ 多数引擎不支持 | 无损但不通用，需转 WAV 或 OGG |
| AAC | ⚠️ 部分引擎支持 | 移动端常见，桌面引擎兼容性不稳定 |
| OPUS | ⚠️ 新兴格式 | Web 平台部分支持，引擎支持有限 |

### 3D 模型格式

| 格式 | 通用兼容性 | 建议 |
|------|:---------:|------|
| GLTF/GLB | ✅ 行业新标准 | **推荐格式**，开放标准，含材质/动画 |
| FBX | ✅ 行业传统标准 | 功能全面，但为 Autodesk 私有格式 |
| OBJ | ✅ 广泛支持 | 仅几何体 + UV，无动画/材质 |
| BLEND | ❌ Blender 专属 | 必须导出为 GLTF/FBX 后使用 |
| USD | ⚠️ 部分引擎支持 | Apple/Pixar 推动的开放格式，生态扩展中 |

## 执行流程

### 步骤 0：前置检查

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

### 步骤 1：素材获取

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

**生成模式 (generate)**：

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

| 素材类型 | 提示词增强规则 | 推荐参数 |
|----------|-------------|---------|
| 角色立绘 | 追加 "game character sprite, transparent background, front-facing" | 1024x1024, PNG |
| 场景背景 | 追加 "game background, seamless tileable, 16:9 aspect ratio" | 1920x1080, PNG |
| UI 图标 | 追加 "game UI icon, flat design, centered, 64x64 pixel art" | 256x256, PNG |
| 音效 | 追加 "game sound effect, short, clean, no background noise" | WAV 44100Hz |
| BGM | 追加 "game background music, loopable, 8-bit/orchestral" | OGG 44100Hz |

**导入模式 (import)**：

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

**转换模式 (convert)**：

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

### 步骤 2：格式校验

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

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

**Magic Bytes 参考**：

| 格式 | Magic Bytes（Hex） |
|------|-------------------|
| PNG | `89 50 4E 47 0D 0A 1A 0A` |
| JPG | `FF D8 FF` |
| WebP | `52 49 46 46 xx xx xx xx 57 45 42 50` |
| GIF | `47 49 46 38` |
| BMP | `42 4D` |
| WAV | `52 49 46 46 xx xx xx xx 57 41 56 45` |
| OGG | `4F 67 67 53` |
| MP3 | `FF FB` 或 `49 44 33` |
| GLTF | `67 6C 54 46`（GLB二进制）或 JSON `{` 开头 |

**校验报告格式**：

```
📋 素材校验报告
━━━━━━━━━━━━━━━━━━
目标引擎: 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]
```

用户确认后执行转换：

**图片转换规则**：

| 源格式 | 目标格式 | 转换方式 | 备注 |
|--------|---------|---------|------|
| AVIF → PNG | 无损解码 | 保持透明通道 | |
| HEIC → PNG | 无损解码 | 保持透明通道 | |
| WebP → PNG | 无损解码 | 仅在引擎不支持 WebP 时转换 | |
| BMP → PNG | 无损压缩 | 减小文件体积 | |
| TGA → PNG | 无损解码 | 仅对 HTML5 目标引擎 | |

**音频转换规则**：

| 源格式 | 目标格式 | 转换参数 | 备注 |
|--------|---------|---------|------|
| FLAC → OGG | 有损, quality 8 | 44100Hz, stereo | 体积减小 60-70% |
| AAC → OGG | 有损, quality 8 | 44100Hz, stereo | |
| OPUS → OGG | 重封装 | 保持原参数 | Opus 本身是 OGG 子集 |
| WAV (非标准采样率) → WAV | 重采样 | 44100Hz, 16bit | 统一采样率 |

### 步骤 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>
```

## 错误处理

| 场景 | 处理方式 |
|------|----------|
| AIGC 服务不可用 | 提示用户检查 API Key 和网络，停止执行 |
| 文件损坏无法识别 | 标记为 `❌ 不可用`，跳过并在报告中说明 |
| 转换后文件体积异常（>10x 或 <0.01x） | 视为转换失败，保留原文件，报告异常 |
| 输出目录写入权限不足 | 提示用户检查目录权限 |
| 采样率重采样引入杂音 | 保留原文件，建议用户人工确认音质 |
| 单文件超过 100MB | 警告用户可能影响加载性能，建议压缩或降分辨率 |

## 与其他 Skill 的协作

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