AIGame/Doc/Design/Scene/SceneReviewGeneration.md

# Unity 关卡场景五阶段生成流程

每个新关卡都按“设计选择 → 组件拆分 → 3D 资产 → Unity 场景 → 美术收尾与对图验收”推进。每一阶段都有输入、输出和状态登记；没有完成上一阶段时，不进入下一阶段。

技术检查（面数、哈希、碰撞、Console）通过只代表“可用”，不代表“可上线”。场景交付以第 5 阶段对图验收为准。

## 商业化品质基线

以下问题来自 HomeCamp 首版复盘（`Tools/output/homecamp_review/homecamp_portrait.png` 对比 `home_camp.png`），新场景必须在对应阶段提前规避：

| 首版问题 | 根因 | 对应要求 |
| --- | --- | --- |
| 广场空旷，远不及参考图丰富 | 只拆了 4 个组件，花盆、摊位、围栏、岩石、台阶、拱门都没做 | 第 2 阶段按 A/B/C 分层拆件，并给出密度目标 |
| 石板尺寸失真，地面像一张大贴图 | 36×42m 地表只用一张 1254² 贴图，纹素密度过低 | 地表表面用 `XTerrain` 平铺分层材质，并做路沿/台阶等边缘件 |
| 物件不贴地，画面发平 | 地表和树卡用的是 Unlit 材质，不接收阴影；场景里没有后处理 Volume | 第 5 阶段统一 Lit 材质、阴影、烘焙 AO、调色 |
| 侧屋、地表、树、灌木出现碎面和黑斑 | 2000～3000 面的预算压到复杂造型上，Studio 低模产生碎片和反面 | 按屏占比定面数，失败时先走规定的重试顺序 |
| 主屋复制三次，一眼能看出重复 | 没有变体手段 | 复用件必须有材质色调、缩放、附件的变体 |

### 美术基准包（第 1 阶段产出，人工确认）

写入场景 manifest 的 `artDirection` 字段，后续所有阶段都以它为准：

- `referenceImage`：唯一视觉目标图，同时也是第 5 阶段的对比基准。
- `palette`：主色、辅色、点缀色各 2～3 个，外加阴影色倾向（冷或暖）。
- `scaleChart`：角色身高 1.6m 为基准，标出门高、窗台、长椅、路灯、石板边长、台阶高度。所有分件都按这张表确定尺寸。
- `lighting`：主光方向和色温、环境光、阴影软硬、雾的起止距离。
- `camera`：正式机位与 FOV，并标出安全区。HUD 会遮挡的区域不摆主体。
- `density`：目标画面内 A/B/C 三类件各自的数量下限，以及相机内地面暴露率上限（参考值：近景不超过 35%）。

## 1. 生成设计图并选择方案

根据当前关卡要求维护 `battlefield_design_prompts.json`，用项目图像生成工具生成多张总览方案。总览图只表达路线、地表和组件类别，不直接作为 Unity 贴图。

```powershell
python Tools/generate_battlefield_designs.py --design all
python Tools/battlefield_scene_pipeline.py status
python Tools/battlefield_scene_pipeline.py select A
```

生成回执和选择结果写入 `battlefield_scene_manifest.json`。人工在 `Doc/Design/Scene/Battlefield/` 查看方案后，才执行 `select`。

## 2. 按方案拆分组件设计图

选中的总览图拆成独立地表图和组件图，输出到 `Doc/Design/Scene/Battlefield/<design>/`。组件类型先与资源库匹配：如果 `AIClient/Assets/Bundles/` 已存在同名 Unity Prefab，则登记为 `generationStatus: reused`，跳过该组件的新设计图；没有现成 Prefab 的组件才调用图像生成。

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

默认复用已有组件。需要刻意重做某个组件时使用：

```powershell
python Tools/generate_battlefield_components.py --design A --force-new-components
```

组件拆分完成后先审核地表图和组件图，再进入 3D 阶段。组件复用路径、生成状态和设计图路径都写回 manifest。

### 分层拆件与密度

每个组件在 manifest 里标 `tier`，拆件时按参考图逐区域清点，不能只拆大件：

| 层级 | 内容 | 典型数量 | 说明 |
| --- | --- | --- | --- |
| A 主体 | 主建筑、地标（喷泉、城门） | 1～4 种 | 决定画面辨识度，预算最高，必须有独立设计图 |
| B 中景 | 侧屋、摊位、围栏段、台阶、拱门、大树 | 4～8 种 | 构成场景结构，复用件必须有变体 |
| C 点缀 | 花盆、木箱、岩石、灌木、花丛、路牌 | 6～15 种 | 决定“丰富感”，按组散布 |

- 地表另拆为“可平铺表面 + 边缘件”（路沿、草地石板过渡、台阶、水岸），边缘件按 B 层制作。
- 复用件的变体手段写进 manifest `variants`：材质色调（屋顶、墙面、遮阳棚颜色）、0.85～1.15 的缩放、附件组合（花箱、灯笼、招牌）。同一 Prefab 在同一画面里出现超过 2 次时，必须换变体。
- C 层优先做成 `Cluster` 组合 Prefab（例如花盆 ×3 + 木箱），拼装时成组摆放，避免散点感。
- 战场装饰类别上限 15 类仍然有效。A/B/C 合计超过上限时，先合并成组合件。

## 3. 根据新设计图生成 3D 模型

只有新组件才执行图生 3D；复用组件使用已验收 Prefab。所有新组件（含独立地表）默认遵循 [统一模型流程](SceneModelProduction.md)：

```text
分件图 → 混元 50k GLB 高模 → Studio 低模 → Studio UV
  → Blender 同源对齐、保留 Studio UV 烘焙
  → 实际面数 > 目标×1.30 时保留 UV 减面，否则登记跳过
  → FBX + XPbr 贴图 → Unity Pipeline 导入和制作 Prefab
```

统一工具为 `Tools/scene_component_pipeline.py --manifest <场景manifest> --part <id>`；`--dry-run` 只打印计划。高模先由混元网页工具完成。Studio 低模/UV 任务、来源哈希、烘焙、条件减面与最终路径必须登记。不得用 Blender 自动 UV 替代 Studio UV。

FBX 遵循 Y-up、底面中心原点、局部 +Z 正面；导入和 Prefab 制作只能走 Unity Pipeline。既有战场 A 按真实旧回执保留，不自动重做。

## 4. 生成 Unity 场景并交给人工审核

场景装配脚本读取 manifest，把独立地表、路线、出生点/终点和组件 Prefab 保存为总 Prefab。审核场景再从总 Prefab 生成持久化 `.unity`，加入固定 `ReviewCamera`、`ReviewKeyLight` 和 `ReviewLabel`。

```powershell
$project = 'D:/UD/AI/AIGame/AIClient'
unity command --project-path $project run_script --file AgentScripts/BuildBattlefieldScene.cs --entry BuildBattlefieldScene.Build
unity command --project-path $project run_script --file AgentScripts/BuildBattlefieldScene.cs --entry BuildBattlefieldScene.VerifyBuilt
unity command --project-path $project run_script --file AgentScripts/BuildSceneReview.cs --entry BuildSceneReview.BuildAndOpenReview
```

审核输入由 `scene_review_manifest.json` 指定：

- `sourcePrefab`：第 4 阶段装配出的总 Prefab。
- `outputScene`：审核场景的 `.unity` 路径。
- `cameraPosition`、`cameraTarget`：固定审核机位，便于不同版本比较。
- `reportPath`：生成结果和审核步骤记录。

人工审核 Hierarchy、Scene View 和 Game View，重点检查组件穿插、悬空、朝向、地表碰撞和路线可读性。审核场景只用于编辑器审阅，不加入正式 Build Settings，也不由运行时代码创建。

审核场景固定摆一个 1.6m 灰模角色作为比例参照，放在正式机位里的主要活动区。

## 5. 美术收尾与对图验收

拼装通过后，由同一个场景构建脚本完成以下收尾，全部通过 Pipeline 持久化，不在运行时补：

**材质与地表**

- 场景内只要在正式机位里可见、而且位于地面层的物件，都使用 Lit 材质（XPbr、`XTerrain` 或 URP Simple Lit），并开启接收阴影。Unlit 只允许用于天空和远景面片。
- 植被卡片用 Alpha Clip 的 Lit 材质，开启接收阴影；树冠法线朝外球面化，避免卡片发平。卡片底部放接触阴影贴片。
- 地表使用 `XTerrain`：4 层平铺纹理（石板、草地、泥土、碎石）加一张控制图。控制图按布局图绘制，平铺密度按 `scaleChart` 里的石板边长换算，禁止整块地表只用一张拉伸贴图。
- 物件和地面接缝处必须有过渡：草边、路沿、碎石、贴花，不能是硬切边。

**灯光与后处理**

- 静态固定机位的场景优先烘焙：静态物件勾选 Contribute GI，烘焙 lightmap 和 AO。实时主光只给角色和动态物件投影。
- 场景放一个全局 Volume：Tonemapping（Neutral 或 ACES 二选一，按 `artDirection.lighting` 定）、Color Adjustments、Shadows Midtones Highlights，再加轻量 Bloom 和 Vignette。低档画质只保留调色，Bloom 关闭。
- 开启线性雾或高度雾，让远景面片和近景之间有空气层次；雾色取远景图的地平线颜色。
- 灯具、窗户使用自发光贴图，配合 Bloom 做出点缀亮点。

**对图验收（交付门）**

1. 用正式机位，在 1080×1920 和长屏两种尺寸下各渲染一张图，与 `referenceImage` 并排拼成对比图，存到 `Tools/output/<sceneId>_review/compare_*.png`。
2. 人工按下表评分，每项 1～5 分。任意一项低于 4 分则打回对应阶段，不进入接入环节：

| 维度 | 4 分标准 |
| --- | --- |
| 轮廓与辨识度 | 主建筑和地标一眼能认出来，前中后景层次分明 |
| 密度与丰富度 | 画面内没有大片空白地面，A/B/C 数量达到 `density` 下限 |
| 比例 | 门、长椅、路灯和 1.6m 参照角色比例协调 |
| 光影 | 每个物件都有落地阴影或 AO，体积感清楚 |
| 色彩 | 与 `palette` 一致，饱和度和明暗不出现脏色或过曝 |
| 品质瑕疵 | 没有碎面、黑斑、反面、接缝漏光和明显重复 |

3. 评分和打回原因写进 manifest `qa.artReview`。`verification.txt` 必须分两行写：`TECH PASS/FAIL` 和 `ART PASS/FAIL/PENDING`。只有技术项通过时，只能写成 `ART PENDING`。
4. 接入正式玩法前，补做真机性能验收：画面内三角面、Draw Call、贴图内存，以及微信小游戏低端机帧率。超出预算时优先合并材质图集、开启 GPU Instancing、做 LOD，不要靠删减 C 层点缀来过关。

## 一键编排与状态门

前四阶段由编排器按顺序提示和调用，第 5 阶段的评分由人工完成；模型阶段仍需独立执行统一模型工具，编排器不自动调用模型服务。它默认复用已有组件，只打印第 3 阶段的模型任务；未准备好模型和 Prefab 时，不要增加 `--run-unity`。Unity 拼装端会检查引用的 Prefab 是否存在，但编排器本身不校验完整模型生产回执：

```powershell
python Tools/run_battlefield_scene_pipeline.py --design A --dry-run
```

确认设计和组件图后，去掉 `--dry-run`；需要重做设计或组件时分别使用 `--force-design`、`--force-new-components`。Unity Editor 和 Pipeline 运行后，再加 `--run-unity` 执行第 4 阶段。


朝向新约定自 2026-10-24 生效；旧场景的 -Z 组件保持其已登记的朝向与布局，不直接套用新资源的 LookRotation 规则。