scenario-unreal-world-building

Unreal 世界构建（关卡、开放世界、地形、PCG）

这里所说的专家级别，意味着按规则确定世界的规模，按重要程度分层放置，从第一张地图开始就进行流式加载和预算管理，并按区域通过脚本修改，而不是手动逐一选择数千个 Actor。环境美术师决定哪些内容保留为手动制作、哪些内容进行烘焙、哪些内容在运行时生成，然后用计数、跟踪记录或截图证明每项选择。如果此处提到的同类技能不在你可用的技能中，请让用户安装 (npx skills add scenario-labs/skills --skill <name>）；若需在无人值守的情况下继续，则根据工具架构处理，并标明此缺口。

必备背景： scenario-unreal-expert（通道、审查循环、5.8 陷阱）。工具包： scripts/ue_world.py （sys.path[:0] = ["<skills>/scenario-unreal-world-building/scripts", "<skills>/scenario-unreal-expert/scripts"]; import ue_world as W） 包含 ue_run、ue_review、ue_audit、ue_stat。尚未在 Unreal 中运行： 离线层已通过 tests/code/unreal-world-building/test_world_offline.py；[verify] 名称由 W.probe() 解析。书面计划会为每个 W.* 步骤注明对应的引擎调用（流程 P0 表）。

立场（专家的不同见解）

• 从集成设置开始，再进行测量。 File > New Level > Open World 会提供 World Partition、OFPA、Data Layers、HLOD 和户外照明：“直接使用模板即可”（Sam Deiter， EEf07ggFWRw [00:20:40]）。使用一个运行时网格：更多网格“可能会对性能产生负面影响”（World Partition 文档）。从第一天起就使用 WP 和 OFPA，承载了 100,000 个 Actor（Sam Dark，Subnautica 2，AalP65lrtpo [00:19:20]）。
• 按重要性分层放置。 英雄资产和关键区域手动放置；灌木到树木、岩石预先烘焙；只有草类细节在运行时由 GPU 生成（CD Projekt RED 和 Epic，icIFFlOyob4 [00:04:23]-[00:07:05]）。碰撞和远距离可见性要求使用持久化放置（Unreal Sensei，5ju7wyvZGBI [00:54:16]）。将玩家不会感知到变化的内容烘焙；在编辑器中预览程序化输出（Dark [00:07:56]）。首先确定哪些内容保持手动放置（Matt Oztalay， TbNZ4GKaTow [00:32:26]）。
• PCG 的创作方式应像材质一样。 使用带参数的模板图表，每次使用时创建图表实例 （Oztalay [00:12:18]）；Is Partitioned“基本上是必需的”[00:22:34]。输出会继承 PCG Actor 的 Data Layer 和 HLOD Layer：生成前先为其分配图层（PCG 文档）。网格：参数使用无界网格，读取 Landscape 使用 128 m 网格，散布使用 32 m 网格；每次 CPU 到 GPU 的传输都会产生开销；GPU 上不存在图层权重（icIFFlOyob4 [00:08:04] [00:23:16] [00:24:12]）。物体突然出现是生成延迟导致的，应在 Test 构建中评估 [00:27:10] [00:27:44]。错误数据必须明确警告：对 Data Missing Attribute 发出警告（Oztalay 时间点 00:10:47）。
• Landscape 的尺寸需要计算，而不是随意选择。 有效尺寸为 2017、4033，绝不能用 2048；最多 1024 个组件，使用 2x2 区段和编辑图层（Landscape 文档）。Z 缩放和 Actor Z 坐标由导出的高度决定（Z = 高度跨度 / 512，Actor 位于中点），而不是由声明的起伏高度决定：文档中写的是 250 m，但实际达到了 314 m，导致我们的 GREEN 测试中有 123,356 个像素被裁剪 [added]。由 scenario-unreal-materials 构建的材质约定在此处进行检查：使用 Opaque，连接 Opacity Mask，使用一个 LB Alpha Blend 基础材质，每个名称对应一个 Layer Info（Landscape 文档）；仅在陡坡图层上使用三平面映射，大面积图层使用抗平铺，降低镜面反射度（Sensei [00:11:12]-[00:15:36]）。
• 默认使用 Nanite，但构造方式仍然重要。“尽可能启用”（Nanite 文档），但多孔的套件拼接、硬边分割、接缝和嘈杂的顶点颜色都会阻碍简化：250 MB 对比 12 MB，外观相同（Epic，6igUsOp8FdA [00:02:46]-[00:08:04]）。距离剔除不适用于 Nanite（Nanite 文档）。细分没有碰撞：按图层设置，地面中心值为 0.5，垂直岩石为 1；细分率为 2 [00:22:58] [00:29:53]。植被应使用不透明材质并建模制作（Quixel，aZr-mWAzoTg [00:01:46]）。
• 流送结构应与内容相匹配。 每个类别使用一个 HLOD 图层：植被使用 Instancing，建筑使用 Merged Mesh，合并后仍然过重时使用 Simplified（文档；Deiter [00:41:13]）。内容会随游戏玩法改变时使用 Level Instance，静态组合使用 Packed Level Actor [00:30:59]。Runtime Data Layers 仅用于游戏状态（文档）。传送目标需要 Streaming Source；对于运行时 PCG，还需要生成源（文档；icIFFlOyob4 [00:36:44]）。
• 世界规模的工作应通过脚本完成，按区域处理并进行验证。 使用脚本，绝不在 Outliner 中选择并拖动；整张地图的任务应通过 builder commandlet 按区域逐一处理（Dark [00:20:23] [00:20:55]）。Builder 先生成内容，再生成 HLOD；生成的 Actor 不应加入变更列表（Oztalay [00:26:23] [00:29:07]）。将文档仅要求做到的规则转化为验证器（Dark [00:23:04]）。
• 套件代表承诺。 占地范围取最大延伸尺寸，固定枢轴，统一门宽，先制作核心组件，最后制作英雄组件（Burgess 和 Purkeypile，QBAM27YbKZg [00:06:14] [00:07:51] [00:22:34]）。村庄路径应连接到最近的已建路径（Oztalay [00:20:01]）；围栏应遵循样条线语法 [00:18:51]。

首先确定

输入	影响	未说明时的默认值
平台、帧率预算	Nanite、植被路径、层；PCG 时间、草地密度	PC 和主机，启用 Nanite，60 fps（scenario-unreal-performance）
尺寸、四边形尺寸、高度来源	布局、Z 轴缩放、Actor 的 Z 坐标	W.plan_landscape，1 m 四边形；Z 轴根据高度拟合
最快移动方式、传送	加载范围、流式加载和生成来源	咨询游戏玩法团队；记录为未知
地形特征、对 Experimental 的容忍度	Landscape 与 Mesh Terrain；Nanite Foliage、PVE、FastGeo	Landscape；发布版本不使用 Experimental 功能
手动还是程序化、源代码管理	图表范围、谁提交生成的 PCG	手动处理：村庄布局、河流、道路、核心区域；生成工作由构建人员负责

工作流

每个阶段都是一个 ue_run 作业或实时调用；过程中的代码（P 编号）。

1. 将简报作为世界规格（P1），例如 W.U1_EXAMPLE_SPEC；每次安装调用一次 W.probe()。门槛： W.check_world_spec(spec)["ok"]，并回答信息性发现。
2. 绘制地图（P2）。使用模板中的 W.new_open_world_map(path)；旧关卡先通过 W.convert_args(..., report_only=True) 处理。门槛：W.wp_facts_check(W.world_facts()) 无问题； PIE 截图中使用 wp.Runtime.ToggleDrawRuntimeHash2D。
3. 地形（P3、P4）。使用 DCC 高度图或占位用的 W.valley_heightmap；W.export_heightmap 会将 Z 和 Actor Z 调整到实际范围。创建是在 Landscape 模式中的一个步骤（Location Z = actor_z_cm，Scale Z = z_scale），除非 MCP 工具可以完成此操作［需验证］。 编辑图层：Base、Sculpt Details、Paint、Splines、Patches。大量绘制前先创建河流（Water Body River 或 Splines 图层中的样条线）。然后使用 Landscape 构建器。门槛：导入前 W.heightmap_clip_gate 为空（裁剪像素为 0）；W.landscape_facts() 与计划、缩放和位置相符； W.landscape_material_check 无问题；检查 Layer Debug、悬崖特写、阳光下的草，以及 2、10 和 100 m 处的人偶。
4. 组织（P5、P6）。按类别创建 Editor Data Layers；根据 W.hlod_plan 创建 HLOD 图层； 在传送目标处放置 Streaming Source 组件。门槛：W.data_layer_check、W.hlod_actor_check 无问题。
5. 村庄和套件（P7）。使用 W.kit_piece_check、W.door_width_check；房屋使用 Level Instances 或 Packed Level Actors；杂物使用带标签的组合件（W.tag_actors）；通过 W.village_paths 将路径生成到 landscape 样条线中；用语法字符串生成围栏。在拆分实例前为地图创建版本。 门槛：套件无错误；路径没有 Z-fighting 或明显重复。
6. Nanite（P8）。对 DCC 导出执行 W.nanite_construction_check(W.obj_construction_stats(obj))； 执行 W.batch_nanite(paths, dry_run=True)，阅读后再运行；使用每层中心执行 W.tessellation_check。 门槛：没有半透明 Nanite 网格；检查树冠上方的 Overdraw；脚部位于置换后的地面上。
7. 烘焙 PCG：森林和岩石（P9）。模板图表（缺少数据时图层筛选器发出警告、坡度密度、将 Extents Modifier 接入 Difference 以避开路径、在河岸使用 Distance thinning、林下植被与树木做差集、Self Pruning、物种表、仅树干启用碰撞），通过 W.pcg_graph_lint 检查；使用 W.spawn_pcg_volume(..., hlod_layer=, data_layer=)。先调试一个体积（D）。门槛：W.pcg_component_check 无问题；数量与 W.expected_points 相符；检查俯视图和游戏高度的镜头，路径或精心布置的区域上没有任何生成物。
8. 运行时草地（P10）。使用 W.grass_rings()（在 32 m 网格单元上，密集范围延伸至 128 m；在 128 m 网格单元上，稀疏范围延伸至 256 m；重新着色远端边缘）；从不带网格的草类型创建遮罩，通过 Generate Grass Maps 生成；每个资源数组中都放置一个占位项；将编辑器视口设为生成源；使用 landscape cache； 设置 pcg.FrameTime。门槛：W.runtime_grass_check 和 W.find_gpu_transfers 无问题； W.generation_lead_check 使用 Test 构建测量延迟。
9. 构建（P11）。 for name, args in W.build_pipeline(map, graphs): ue_run.run_commandlet(uproject, name, args)： landscape、PCG、HLOD。门槛：每项的退出代码均为 0；统计每层的 HLOD Actor 数量；执行 W.changelist_check， 然后从编辑器提交。
10. 审查和交接（P12 至 P14）。使用 W.REVIEW_CONSOLE 运行 W.tour(...) 并通过检查， 对每张截图执行 ue_review.image_checks，然后查看截图； 执行 W.world_rules_check(W.world_census(), vocab)；W.budget_sheet、W.lighting_handoff。门槛： 通过评审标准；没有截图佐证的已完成事项不得报告为完成。

数值

数值	设置	相对值 / 来源
2 km 景观	2017 x 2017，63 个四边形，2x2，组件数为最大 1024 的 256	1 m 四边形（Landscape 文档）
Z 轴缩放	跨度（cm）/ 512 x 1.02；Actor 的 Z 位于跨度中点	16 位高度（文档）；预留空间 [已添加]
模板网格	单元格 25,600 cm，范围 76,800 cm	优先配置轮廓（Deiter [00:15:32]）
PCG 分区网格	25,600 cm	PCG World Actor（Oztalay 画面 00:23:16）
分层网格	无界、128 m、32 m	运行时草地（icIFFlOyob4 [00:08:39]）
草地环	128 m 内密集，256 m 内稀疏	icIFFlOyob4 [00:15:30]
每个 32 m 单元格的实例数	1 万至 2 万个较精细	基础款 PS5，5.6 演示 [00:30:26]
pcg.FrameTime	默认 5 ms；演示中为 2 ms	5.6 说明；基础款 PS5 [00:26:24]
高度上传	每个 32 m 单元格约占用游戏线程 0.5 ms	基础款 PS5 [00:24:12]
流送实例	硬性上限为 1600 万	Nanite 文档
Nanite 构建	250 MB 对比 12 MB，外观相同	6igUsOp8FdA [00:02:46]
Nanite Assemblies	占资产大小的 5% 到 10%；200 到 1,000 个风动骨骼	aZr-mWAzoTg [00:07:13] [00:09:51]
切分率	2；低于 2 以及高于约 5 或 6 时速度较慢	6igUsOp8FdA [00:29:53]
位移中心	地面为 0.5，垂直岩石为 1，按层计算	碰撞表面 [00:22:58]
地形镜面反射	0.02（Sensei）；作为由凹陷驱动的上限时为 0.5（Cloward）	5ju7wyvZGBI [00:11:12]；0L5Azq6ugyo [00:01:19]
Tick 聚合	超过 10 到 15 个放置的实例	Dark [00:23:04]
移动端景观	3 个图层，16 个采样器	ES3.1（文档）

质量门槛

• **可测量：**工作流检查（所有 W.*_check、heightmap_clip_gate、pcg_graph_lint、 find_gpu_transfers）；对导入内容运行 ue_audit；构建器以 0 退出；按视点运行 stat unit、stat gpu；在 Test 构建中通过 Insights 查看 PCG 耗时；-trace=WorldStreaming； 对 wp.Runtime.HLOD 0/1 进行 A/B 测试。
• **视觉：**运行时哈希叠加层中没有失败单元格；Layer Debug 没有黑斑；与人台对比检查铺贴； 悬崖没有拉伸；阳光下的草没有塑料般的光泽；脚部落在位移后的地面上；检查树冠过度绘制； Hierarchical LOD 着色和 HLOD 轮廓；逐帧视频中检查环带交接和弹入；路径上没有物体，河岸处 植被稀疏；岩石牢固地贴合地面。评审标准： references/critique.md。

常见错误

错误	表现	修复
根据声明的浮雕设置 Z 轴缩放	导入后出现平台和凹坑	使用拟合导出，W.heightmap_clip_gate
使用 2048 高度图	导入失败或被重新采样	使用 2017 或 4033
所有图层都启用高度混合；图层没有 Layer Info	出现黑块；图层始终无法绘制	基础图层使用 Alpha Blend；添加同名 Layer Info
使用第二个运行时网格	增加流送开销，没有收益	使用一个网格，并通过 HLOD 处理远距离
为了整洁而使用运行时数据层；关卡蓝图中有引用	卡顿；Actor 始终处于加载状态	使用编辑器数据层；改用蓝图类
PCG 体积没有 HLOD 或数据层	远距离看不到烘焙后的森林	生成前同时分配两者
运行时图在编辑器中不可见	美术人员看不到任何内容	将编辑器视口设为生成源
在 GPU 图中使用图层权重	草地蒙版为空	使用没有网格的草地类型，生成草地贴图
美术资源数组为空	草地流送崩溃	每个数组中放置一个占位项
对 Nanite 使用剔除或绘制距离	不会变稀疏，环带之间无法交接	使用 HLOD，为每个环带设置生成半径
仅使用 GPU 树木	Lumen 中看不到树木	仅对小型物体使用 GPU
不断增大草地半径	实例数量激增，边缘可见	使用两个环带，并重新着色边缘
组合岩石存在孔隙	资产过大，远距离可见孔洞	使用连通的基座和可平铺纹理
使用构造脚本散布	170,000 个刚体，打开地图耗时 7 分钟（Oztalay [00:30:49]）	使用 PCG 输出，关闭杂物碰撞
将生成的 PCG Actor 提交到版本库	产生冲突，数据过时	由构建器负责生成
在大型地图上使用全选进行编辑	编辑器卡顿	使用 W.region_batch 或构建器

交接

• **接收自 scenario-unreal-pipeline-automation：**由 ue_audit 传入的网格、标准套件部件、带有高度范围的 DCC 高度图；构建失败时退回（并反馈给 scenario-maya-expert、scenario-blender-expert）。
• **接收自 scenario-unreal-materials：**地形实例和图层列表（混合类型、陡坡图层、防重复纹理）、带边界的 RVT、草地类型名称、岩石 RVT 混合、非透明植被。镜面反射由他们负责；世界美术师根据太阳捕捉结果报告光泽度。
• **交付给 scenario-unreal-lighting-rendering：**地图、World Bookmarks 或 tour_viewpoints、W.lighting_handoff（模板灯光、Lumen 场景之外仅供 GPU 使用的角色、HLOD 远场和距离场标志、Data Layer 状态）。
• 交付给 scenario-unreal-performance：W.budget_sheet 和巡览路径。
• **还包括：**scenario-unreal-gameplay（流送和生成源、Asset User Data、Tick 聚合）；scenario-unreal-pipeline-automation（供其验证器使用的世界规则）；scenario-unreal-cinematics（pcg.FrameTime 暂停，icIFFlOyob4 [00:28:51]）；scenario-unreal-vfx（水面着色）。

UE 5.8 说明

• 新的 WP 地图使用带分区的运行时哈希（5.4）：写入网格属性前读取 world_facts() [verify]。
• 默认启用 PCG；PCG Python Data Processor、PCG Builder Volume；地形缓存自 5.6 起为可选项（不启用时运行时 CPU 读取会失败）。
• 必须使用编辑图层（5.7）；landscape.ForceLayersFullUpdate 取代 ForceLayersUpdate；WorldPartitionLandscapeBuilder（5.7）；水体笔刷会强制进行全局合并。
• HLOD：Build HLOD for Selection 或 Region、bForceRayTracingFarField、Custom HLOD actors（5.7）；保存的文档中没有 Approximate Mesh [verify]。
• 实验性功能：Mesh Terrain、Nanite Foliage、PVE、FastGeo、World Streaming Insights。Mac：M2 或更新版本上启用 Nanite 和 VSM Beta；烘焙平台 Mac。

参考资料

• references/expert-notes.md：专家判断，附时间戳。
• references/procedures.md：P0 至 P14、完整代码、工具包背后的引擎调用、测试、状态。
• references/critique.md：各道关卡的评估标准。
• references/gui-paths.md：每个流程对应的编辑器菜单。
• references/sources.md：来源、凭据、URL、时间戳、修订历史。