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 贴图。

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 的组件才调用图像生成。

python Tools/generate_battlefield_components.py --design A

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

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。所有新组件（含独立地表）默认遵循 统一模型流程：

分件图 → 混元 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。

$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 是否存在，但编排器本身不校验完整模型生产回执：

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 规则。