# 战场场景生成流程

这套流程把“想法、分件、模型、Unity 场景”分成四个有门槛的阶段。当前先完成设计图选择，未选择方案时不会调用微信网页图生 3D，也不会拼装最终 Prefab。

## 1. 设计图阶段：三选一

三张方案图必须通过项目内 `Tools/gpt_image_generate.py` 调用 `gpt-image-2.5` 生成。它们是 1024×1024 的俯视概念图，供确认路线、地表和组件类型，不作为运行时贴图。旧版 PIL 绘制草图只能作为历史预览，不能作为设计门输入。

| 方案 | 图片 | 重点 | 风险 |
| --- | --- | --- | --- |
| A 绿野三岔口 | `Battlefield_Design_A_GreenFork.png` | 中央安全线、左右高差支路、教学读路清晰 | 地标辨识度较弱 |
| B 溪谷浮桥 | `Battlefield_Design_B_StreamBridges.png` | 水面横切、三座浮桥、元素主题明确 | 桥和水面碰撞验证更复杂 |
| C 旧城花园 | `Battlefield_Design_C_OldGarden.png` | 残墙拱门、中央花园、首领关地标 | 墙体遮挡和批次更复杂 |

生成命令：

```powershell
# 先在当前 PowerShell 配置 GRSAI_API_KEY 或 GPT_IMAGE_API_KEY
python Tools/generate_battlefield_designs.py --design all
```

提示词和模型记录在 `Doc/Design/Scene/Battlefield/battlefield_design_prompts.json`，每张图旁边会写入 `*_gpt_image_status.json`。当前已选择第 1 张方案，即 A；脚本在生成 A 后会把 `selectedDesign` 登记为 `A`，再进入下一阶段。

## 2. 分件设计图阶段

从选中的总览图归纳组件类别。A 方案先使用树、岩石、桥、路牌、灌木 5 类；地表单独设计、单独图生 3D、单独减面、单独 Prefab，不计入装饰组件上限。组件图继续调用 `gpt-image-2.5`，以提示词描述主界面 Candy 的造型、色彩和软阴影；默认不上传项目内部参考图。

组件拆分前先扫描 `AIClient/Assets/Bundles/`。若组件类型已有同名 Unity Prefab，则登记 `generationStatus: reused` 并跳过该组件新设计图；只有资源库没有的类型才生成新的组件设计图。默认执行 `python Tools/generate_battlefield_components.py --design <ID>`，需要重做已有组件时显式增加 `--force-new-components`。

推荐清单：树、岩石、桥、路牌、灌木、水面、芦苇、残墙、拱门、花坛、喷泉、路灯、长椅、栅门。选定方案可以删减，但不能增加未登记的新类别。每类分件图放在：

```text
Doc/Design/Scene/Battlefield/<方案ID>/parts/<type>.png
```

分件图要求：纯白背景、单件、3/4 视角、完整入画、无文字、无地面底座；地表图单独放在 `<方案ID>/ground.png`，画出俯视边界、坡度、可行走区域和三条路线。

生成 A 方案组件图：

```powershell
python Tools/generate_battlefield_components.py --design A
```

提示词记录在 `Doc/Design/Scene/Battlefield/A/battlefield_component_prompts.json`。生成完成后先在窗口审核 `A/ground.png` 与 `A/parts/*.png`，审核通过再进入混元 3D 图生模型阶段。

当前进度：树、岩石、桥、路牌、灌木 5 类与独立地表均已完成混元 50k GLB、纹理校验、Blender 减面与 XPbr 烘焙。Unity 2022.3.62f3 已通过 Pipeline 生成组件 Prefab、`GreenfieldGround.prefab` 和 `Battlefield_Greenfield.prefab`。烘焙地表原是朝向 Z 的薄板，场景实例绕 X 轴 -90 度放平，顶面贴在 y=0，并覆盖三条路线。`AttachGreenfield.Build` 已把该场景嵌进开战预制体 `PrototypeArena`，原来的方块地面已关闭。按现有战斗相机（正交 9.5，看向路线中段）核对：三条路线落在土路上。桥模型保留，场景中不再摆放。部署标记和青色防线仍在路面上。Greenfield 整棵子树必须在第 30 层，否则开战相机看不到地表。Play Mode 隔离服已验证开战加载无桥绿野，截图 `Assets/Screenshots/battlefield_play_battle.png`。

## 3. 微信网页图生 3D 与减面

分件图确认后，逐类执行项目现有的腾讯混元网页流程。每个模型都保留原始任务目录和日志，不能直接把高模放入 Unity：

```powershell
# 1) 微信扫码登录（首次或凭证过期时）
python Tools/hunyuan_3d_generate.py --login

# 2) 图生 GLB 高模（每类一份；不超过 15 类 + 地表）
python Tools/hunyuan_3d_generate.py `
  --image Doc/Design/Scene/Battlefield/<方案ID>/parts/tree.png `
  --faces 50k `
  --output Tools/output/battlefield/<方案ID>/tree

# 3) 减面、重展 UV、烘焙、XPbr 收尾
python Tools/model_tools/model_lowpoly_bake.py `
  Tools/output/battlefield/<方案ID>/tree/generated.glb `
  -o Tools/output/battlefield/<方案ID>/tree_game `
  --tris 700 --size 1024
```

`model_lowpoly_bake.py` 的具体目标面数按组件登记：地表 800～1500、地标 1200～2000、普通装饰 300～1000、重复小件 300～600；命令中的 `--tris` 每次填写一个确定整数。模型验收必须通过 GLB 文件头、内嵌贴图解码、低模三角面数、UV、包围盒和坐标检查。

最终 Unity 输入目录：

```text
AIClient/Assets/Bundles/Scenes/Prototype/Battlefield/<方案ID>/
  Ground/<ground>.fbx + XPbr 贴图 + 材质
  Components/<type>/<type>.fbx + XPbr 贴图 + 材质
```

FBX 统一为 Y-up、原点在底面中点、局部 -Z 为正面。摆放时用 -Z 朝向目标；地表使用非凸 MeshCollider，其他组件不添加运行时生成的临时网格。

## 4. Unity Prefab 拼装

模型导入和 Prefab 操作只能通过 Unity Pipeline。`AIClient/AgentScripts/BuildBattlefieldScene.cs` 会：

1. 读取 manifest，拒绝空 `selectedDesign`、重复类型、超过 15 类或缺少独立地表。
2. 检查 Ground 与 Components 的 Prefab、材质和碰撞体。
3. 按方案布局生成根节点、地表、路线标记、出生点、终点和可选装饰实例。
4. 保存 `Assets/Bundles/Scenes/Prototype/Battlefield/Battlefield_Greenfield.prefab`，并接入 Art/UI 资源收集。

场景根节点固定包含：`Ground`、`Routes/Lane0..2`、`Gameplay/SpawnPoints`、`Gameplay/GoalPoints`、`Decorations`、`Lighting`。战斗代码只读取路线与标记，不在运行时生成业务场景骨架。

## 验收与交付门槛

- 设计门：三图中选一，确认路线、视线、地标和组件清单。
- 分件门：所有组件图为纯白单件图；类别数 ≤15；地表独立。
- 模型门：GLB 检查、低模面数和坐标约束通过；每个模型有来源日志。
- Unity 门：Prefab 由 Pipeline 保存，地表碰撞可用，三路线出生/终点可定位，Art Bundle 收集成功。
- 性能门：首屏视锥内控制 Draw Call、贴图和实例数，真机再按 G3 预算验收。

选择结果、分件图、模型路径、低模面数和 Prefab 路径都写入 manifest；任何一步没有登记，流程不算完成。

### Unity Pipeline 入口（编辑器可用后）

组件与独立地表统一执行：unity command --project-path D:/UD/AI/AIGame/AIClient run_script --file AgentScripts/BuildBattlefieldAssets.cs --entry BuildBattlefieldAssets.BuildAll。其中 BuildGround 只在 Assets/Bundles/Scenes/Prototype/Battlefield/A/Ground/ground.fbx 存在时生成 GreenfieldGround.prefab，并启用可读网格与非凸 MeshCollider；随后执行 BuildBattlefieldScene.Build 拼装最终场景。