AIGame/GameResProductProc.md

# 游戏资源生产流程

> 本文说明游戏内各类资源从设计到入库的生产步骤。  
> 工具用法见 [`ResourceCreate.md`](ResourceCreate.md)。生成完成后必须登记 [`Doc/ResDesc.md`](Doc/ResDesc.md) 对应分册，未登记视为流程未完成。

当前状态：**框架已立**。各条的细化与实跑验证按文末清单逐条进行；标「待细化」的条目只保留步骤骨架，不写未经验证的命令。

---

## 0. 总则

1. **画图**一律走项目画图方案（见附录 A）。设计图、UI 原图、序列帧、粒子贴图的生成底为**纯白**。
2. **3D**一律走 3D 模型生成流程（见附录 B）。面数是减面后的游戏用三角面，不是混元高模面数。游戏 FBX：**Y-up**、原点在**底面中点**、局部 **-Z 为正面**（设计图朝向相机的那面）。摆放时正面朝向目标，不要按 Unity 默认 +Z forward。
3. **中间件**放 `Tools/output/`，不进正式包。**游戏用资源**放 `AIClient/Assets/Bundles/` 对应目录。
4. **设计原稿**放 `Doc/Design/{类型}/{名称}/`，**不要拷进** `AIClient/`。`{类型}` 与下文各大类对应（如 `Scene`、`Character`、`UI`、`Weapon`、`Prop`、`Effect`）。
5. **英文名称**用于 Bundle 目录与文件名：帕斯卡或既有角色名风格均可，目录内保持一致，不含空格与中文。
6. **确认点**写在步骤里的，必须等人确认后再进入下一步。
7. **Unity 操作**一律走 Unity Pipeline（`unity command …`），见 [`UNITY-GUIDE.md`](UNITY-GUIDE.md) 与 `unity-pipeline` 技能。不要用 Unity MCP；场景、Prefab、材质、导入设置、以及 `Assets/` 下文件的移动/重命名/删除，都通过 Pipeline 完成。

| 登记 | 文件 |
| --- | --- |
| 图、设计原稿、UI 切图 | `Doc/ResDesc_Picture.md` |
| 模型、贴图、Prefab | `Doc/ResDesc_Model.md` |
| 动画 | `Doc/ResDesc_Animation.md` |
| 特效 | `Doc/ResDesc_Effect.md` |
| 音乐、音效 | `Doc/ResDesc_Sound.md` |

---

## 一、2D 资源

### 1. 设计图

状态：已跑通。样例为轻松休闲 UI、小镇广场、轻科幻曹操（2026-09-28）。

1. 用 `Tools/gpt_image_generate.py` 出图。默认模型 `gpt-image-2.5`，`--quality high`。背景写进提示词：纯白 `#FFFFFF`，不要场景底、渐变和纸纹。
2. 比例用字符串，不要自己传大于 1K 的像素。本次实测映射为：

| 用途 | `--aspect-ratio` | 实测尺寸 |
| --- | --- | --- |
| 竖屏 UI | `9:16` | 940×1672 |
| 场景总览 | `1:1` | 1254×1254 |
| 全身角色 | `2:3` | 1024×1536 |

3. 需要锁已有风格时加 `-i` 参考图。UI 样例参考 `Doc/Design/ui_design.jpg`。
4. 原稿放到 `Doc/Design/{类型}/{名称}/`，文件名用英文。本次：

| 类型 | 路径 |
| --- | --- |
| UI | `Doc/Design/UI/Casual/casual_ui.png` |
| Scene | `Doc/Design/Scene/TownSquare/town_square.png` |
| Character | `Doc/Design/Character/CaoCao/caocao.png` |

5. 检查四角 RGB。接近 255（本次均 ≥253）即视为纯白通过。
6. 在 `Doc/ResDesc_Picture.md` 登记路径、用途、模型与尺寸。

角色若接着走 3D，设计图按人物条目画成正面 T Pose、双手空、全身入画。本次曹操已按此出图。

本条产出不进 `Bundles`。场景总览画出后先归纳物件类型（10 种以内）等人确认，再进入分件。

```bash
python Tools/gpt_image_generate.py --result-only --quality high --aspect-ratio 9:16 -i Doc/Design/ui_design.jpg -o Doc/Design/UI/Casual/casual_ui.png -p "..."
python Tools/gpt_image_generate.py --result-only --quality high --aspect-ratio 1:1 -o Doc/Design/Scene/TownSquare/town_square.png -p "..."
python Tools/gpt_image_generate.py --result-only --quality high --aspect-ratio 2:3 -o Doc/Design/Character/CaoCao/caocao.png -p "..."
```

### 2. UI 图

状态：待细化。切图与 Sprite 导入已有样例（`Doc/UI_Normal_Set.md`、`Tools/slice_ui_normal_atlas.py`、`Assets/Bundles/UI/Texture/Common/`），新风格组件仍按本条重走一遍并核对。

1. 参考既有 UI 范例图，用项目画图方案绘制新的风格组件图，背景纯白。
   - 视觉基准：`Doc/Design/ui_design.jpg`、`Doc/Design/UI_Design_Principles.md`。
   - 范例图集：`Doc/UI_Simple_Set.md`、`Doc/UI_Normal_Set.md`。
   - 原稿放到 `Doc/Design/UI/{名称}/`。
2. 把组件图拆成单张图。
3. 导入 Unity，贴图类型改为 **Sprite (2D and UI)**。
   - 落点：`AIClient/Assets/Bundles/UI/Texture/Common/`（或该套组件的子目录）。
   - 现有 Common 图：`spriteMode: 1`（Single），`textureType: 8`（Sprite），`spritePixelsToUnits: 100`，关闭 Mip Map。
4. 业务界面仍走 JSON→Prefab，见 `Doc/UI_AutoGen_Overview.md`。不要用运行时代码拼业务 UI。
5. 登记 `Doc/ResDesc_Picture.md`。

---

## 二、3D 资源

### 1. 场景

状态：a / b / c / d 已用 `TownSquare` 跑通。

**a. 整体设计图（需确认）**

1. 用项目画图方案绘制整场景设计图（样例：`Doc/Design/Scene/TownSquare/town_square.png`）。
2. 从设计图归纳场景物件类型，**控制在 10 种以内**（含地表计 1 种）。
3. **停在这里等人确认**类型清单与整体设计图。未确认不画组件、不生成模型。
4. 原稿放到 `Doc/Design/Scene/{场景号}/`。

`TownSquare` 已确认 8 类：地表、店铺、树、路灯、告示牌、喷泉、长椅、灌木花箱。

**b. 分件设计图**

确认后，总览图作 `-i` 参考，一类一张、单件、纯白底、3/4 视角。文件放在 `Doc/Design/Scene/{场景号}/`，英文短名：

| 类型 | 文件 |
| --- | --- |
| 地表 | `ground.png` |
| 店铺 | `shop.png` |
| 树 | `tree.png` |
| 路灯 | `lamp.png` |
| 告示牌 | `board.png` |
| 喷泉 | `fountain.png` |
| 长椅 | `bench.png` |
| 灌木花箱 | `bush.png` |

提示词约束：只画该类型一件，不要把总览里的其它物件带进来。分件必须对齐总览（本次喷泉第一次出成三层，已按总览改回两层）。比例默认 `1:1`；瘦高件（路灯）用 `2:3`。四角纯白检查同「一.1」。登记 `Doc/ResDesc_Picture.md`。

```bash
python Tools/gpt_image_generate.py --result-only --quality high --aspect-ratio 1:1 -i Doc/Design/Scene/TownSquare/town_square.png -o Doc/Design/Scene/TownSquare/{name}.png -p "..."
```

**c. 生成模型并入库**

1. 分件设计图逐一走附录 B：混元 `--faces 50k` → `model_lowpoly_bake.py --tris <目标> --size 1024`。
2. 减面后面数 **300～2000**。`TownSquare` 取值：地表 800、店铺 1800、树 1500、路灯 500、告示牌 800、喷泉 1800、长椅 700、灌木 500。
3. 碎叶类（灌木）普通 collapse 会卡在约 2 万面；减面脚本在超差且仍高于目标 2 倍时改用**体素重网格**回退。本次灌木最终 **436** 面。
4. 校验 GLB 文件头须为 `glTF`，且**内嵌贴图能解码**（`hunyuan_3d.glb_check`）。中断拷贝可能得到全 0 文件；贴图 CRC 损坏时 Blender 当缺贴图处理，颜色烘焙会出品红（路灯曾中招）。
5. 最终资源放到 `AIClient/Assets/Bundles/Scenes/{类型}/{场景号}/{英文短名}/`，含 `{名}.fbx`、`{名}_base.png`、`{名}_mix.png`、`{名}.mat`。设计图留在 `Doc/Design/Scene/{场景号}/`，不进 Unity。
   - 样例：`AIClient/Assets/Bundles/Scenes/Town/TownSquare/{ground,shop,tree,lamp,board,fountain,bench,bush}/`
6. 高模与烘焙中间件留在 `Tools/output/townsquare_3d/`、`Tools/output/townsquare_game/`。编排脚本：`Tools/output/run_townsquare_pipeline.py`。
7. 登记 `Doc/ResDesc_Model.md`。

**d. 摆场景（可进游戏）**

状态：已用 `TownSquare` 跑通（Unity Pipeline）。

1. 所有 Unity 操作走 Pipeline：`unity command run_script --file AgentScripts/BuildTownSquare.cs --entry BuildTownSquare.Run`。
2. 每个分件做成 Prefab（缩放、XPbr），再拼 `TownSquare.prefab`。游戏 FBX 与混元 GLB 同为 Y-up，原点在底面中点，**正面为局部 -Z**。地表 Prefab 加非凸 **MeshCollider**（FBX Read/Write 打开以便烹饪）。其它物件水平位置按总览图 L 形，**Y 用地表碰撞高度**（从上往下打到 MeshCollider）。店铺/告示牌/长椅的 **-Z 朝向广场中心**。只有红顶店网格，两座店共用。运行时角色同样用 `GroundSit` 贴地。
3. 可编辑场景：`AIClient/Assets/Bundles/Scenes/Town/TownSquare/TownSquare.unity`（主相机 + 方向光 + 广场实例）。
4. 运行时由 `TownSquareSpawner` 按地址 `TownSquare` 加载 Prefab（YooAsset Art；编辑器走 AssetDatabase）。`GameplayBootstrap` 先摆广场再刷角色。
5. Art 收集增加 `Assets/Bundles/Scenes`（`PackDirectory` / `AddressByFileName`）。

`TownSquare` 实测三角面：ground 800、shop 1797、tree 1498、lamp 500、board 800、fountain 1798、bench 699、bush 436。

### 2. 角色

#### A. 人物角色

状态：待细化。工具链已在 MaleExplorer 上跑通过（`Doc/ResDesc_Model.md`）；本条按新目录与约 3000 面重核。

1. 参照风格图绘制设计图：**T Pose**，背景纯白。
2. 原稿放到 `Doc/Design/Character/{英文名称}/`。
3. 设计图走附录 B，减面后约 **3000** 面。
4. 最终资源放到 `AIClient/Assets/Bundles/Characters/{类型}/{英文名称}/`。
5. 登记 `Doc/ResDesc_Model.md` 与 `Doc/ResDesc_Picture.md`。

既有 `Characters/MaleExplorer/` 是早期平铺目录，新角色按 `{类型}/{英文名称}` 存放。

#### B. 非人角色

状态：待细化。

步骤骨架与人物相同（风格图 → 纯白设计图 → 附录 B → 入库 → 登记）。差异留到细化时写明：姿势、面数、`{类型}` 取值、是否需要与人形共用骨骼。

### 3. 动画

状态：待细化。仓库尚无入库的动画生产脚本，本节不预设工具。

#### A. 人形角色动画

骨架：动作列表确认 → 生成或导入剪辑 → 绑定到对应角色 → 放到该角色目录或统一动画目录 → 登记 `Doc/ResDesc_Animation.md`。

#### B. 非人角色动画

骨架同上。与人形是否共用动作、是否单独绑定，细化时确定。

### 4. 独立物件

状态：待细化。生产走附录 B；**入库目录细化时确定**（本框架不先占一个未使用的 Bundle 路径）。

#### A. 武器

骨架：纯白设计图 `Doc/Design/Weapon/{英文名称}/` → 附录 B → 入库 → 登记 Model / Picture。

#### B. 道具

骨架：纯白设计图 `Doc/Design/Prop/{英文名称}/` → 附录 B → 入库 → 登记 Model / Picture。

面数在细化时按物件尺度定，默认参照场景组件的 300～2000，不默认使用角色的 3000。

### 5. 特效

用户提纲里本条与「独立物件」同为第 4 点，流程文档中改为第 5 点。

#### A. 序列帧动画

状态：待细化。

1. 用项目画图方案生成 **4×4** 序列帧，画布 **1024×1024**，背景纯白。
2. 整图缩小为 **256×256**。
3. 在 Unity 中做成 Particle 特效供游戏使用。
4. 图片、Prefab 及相关资源全部放到 `AIClient/Assets/Bundles/Effects/{英文名称}/`。
5. 登记 `Doc/ResDesc_Effect.md`（序列帧图可同时在 Picture 记一笔）。

#### B. 粒子动画

状态：待细化。

1. 用项目画图方案生成粒子图，画布 **1024×1024**，背景纯白。
2. 缩小为 **128×128**。
3. 在 Unity 中做成 Particle 特效供游戏使用。
4. 图片、Prefab 及相关资源全部放到 `AIClient/Assets/Bundles/Effects/{英文名称}/`。
5. 登记 `Doc/ResDesc_Effect.md`。

---

## 三、声音资源

状态：待细化。仓库尚无入库的音频生成脚本，本节不预设工具。

### 1. 音乐

骨架：确定用途与时长 → 生成或导入 → 放到声音 Bundle 目录 → 登记 `Doc/ResDesc_Sound.md`。目录在细化时确定。

### 2. 音效

骨架同上，与音乐分开登记。

---

## 附录 A. 项目画图方案

节点说明与命令见 [`ResourceCreate.md`](ResourceCreate.md)「文/图生图」。

- 脚本：`Tools/gpt_image_generate.py`
- 边长 ≤1024（含 `1024×1024`）：默认模型 `gpt-image-2.5`
- 任一边 >1024：必须用 `gpt-image-2-vip`，并传像素尺寸（如 `2048x2048`），不要用 `"16:9"` 这类比例字符串
- 需要锁风格时用图生图（`--image` / JSON `image`），参考图为对应风格图或 UI 范例图
- 本流程额外约束：**背景纯白**。写进提示词，出图后目视确认，不把灰底、场景底直接交给切图或图生 3D

### 出图尺寸（与上文条目对应）

| 用途 | 尺寸 | 模型 |
| --- | --- | --- |
| 设计图 | 见「一.1」：UI `9:16`、场景 `1:1`、角色 `2:3`（比例字符串，默认模型） | 默认模型 |
| UI 组件图集（沿用现有图集） | `2048×2048` | VIP |
| 序列帧 | 先 `1024×1024`（4×4），再缩到 `256×256` | 默认模型 |
| 粒子图 | 先 `1024×1024`，再缩到 `128×128` | 默认模型 |

缩小在细化时写成固定步骤（脚本或图像工具二选一，选定后写回本节）。

---

## 附录 B. 3D 模型生成流程

节点说明见 [`ResourceCreate.md`](ResourceCreate.md)「腾讯混元 3D」与「高模减面与贴图烘焙」。调用方只改面数、输出目录和登记类型。

```text
纯白设计图
  → 混元图生 3D（Tools/hunyuan_3d_generate.py）→ GLB 高模
  → 减面 + 烘焙 + XPbr（Tools/model_tools/model_lowpoly_bake.py）
  → 安装到对应 Bundles 目录
  → 登记 Doc/ResDesc_*.md
```

- 混元面数档：`--faces 50k|500k|1m`（默认 `50k`）。这是高模档，不是游戏面数。
- 游戏面数用 `--tris` 控制。场景组件 / 地表：**300～2000**。人物：约 **3000**。
- 高模与烘焙中间件留在 `Tools/output/`。
- 角色安装可参考：`Tools/install_character_bundles.py`。场景分件：拷到 `Bundles/Scenes/{类型}/{场景号}/{英文短名}/`（`Tools/output/run_townsquare_pipeline.py`）。设计原稿不进 Bundles。
- 碎叶等非流形：`bl_decimate.py` 在 collapse 卡住后会体素重网格再减面。
- 轴向：混元 GLB = glTF Y-up。烘焙在 Blender 里用 Z-up；**导出 FBX 时** `prepare_game_export` 转回 Y-up，原点放在**底面中点**。**局部 -Z 是正面**（设计图朝相机的那面，与 glTF 相机看向 -Z 一致）。Unity 摆放用「-Z 指向目标」，不要用 `LookRotation` 默认的 +Z forward，也不要再绕 X 扶正或抬高度。
- 最终 `_base.png` / `_mix.png`（以及烘焙五通道 PNG）写出时做 **PNG 无损压缩**（zlib 最高档；有 Pillow 则 `optimize=True`）。像素不变，只缩小文件。
- 角色 Prefab：Unity 菜单 `AIGame/M3/Setup Character Prefab`。其他类型的 Prefab 步骤在细化时写明。

---

## 细化验证清单

按表从上到下逐条做。一条通过（步骤可重复执行、路径与登记写回本文）后再做下一条。

| 顺序 | 条目 | 验证时要写回本文的内容 |
| --- | --- | --- |
| 1 | 一.1 设计图 | 已写回：比例与实测尺寸、三张样例路径、四角纯白检查 |
| 2 | 一.2 UI 图 | 参考图、拆单图步骤、Sprite 导入参数、与 JSON→Prefab 的衔接 |
| 3 | 二.1 场景 | a/b/c/d 已写回：TownSquare 分件入库、拼装 Prefab/场景、运行时加载 |
| 4 | 二.2.A 人物 | 按约 3000 面与 `{类型}/{英文名称}` 重跑或核对 MaleExplorer 差异 |
| 5 | 二.2.B 非人角色 | 姿势、面数、骨骼、目录 |
| 6 | 二.3 动画 | 人形 / 非人各自的生成与绑定方式 |
| 7 | 二.4 独立物件 | 武器与道具的面数和 Bundle 目录 |
| 8 | 二.5 特效 | 缩小步骤、序列帧切格、Particle Prefab 做法 |
| 9 | 三 声音 | 音乐与音效的生成方式和目录 |