scenario-unreal-world-building

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Unreal world building (levels, open worlds, landscape, PCG)

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

Expert level here means a world sized by rule, placed by tier of importance, streamed and budgeted from the first map, and changed by script region by region, never by hand-selecting thousands of actors. The environment artist decides what stays manual, what is baked and what is generated at runtime, then proves every choice with a count, a trace or a screenshot. If a sibling skill named here is missing from your available skills, ask the user to install it (

npx skills add scenario-labs/skills --skill <name>

); unattended, proceed from tool schemas and flag the gap.

REQUIRED BACKGROUND: scenario-unreal-expert (channels, review loop, 5.8 traps). Toolkit:

scripts/ue_world.py

(

sys.path[:0] = ["<skills>/scenario-unreal-world-building/scripts", "<skills>/scenario-unreal-expert/scripts"]; import ue_world as W

) with

ue_run

ue_review

ue_audit

ue_stat

. Not yet run in Unreal: the offline layer passed

tests/code/unreal-world-building/test_world_offline.py

; [verify] names are resolved by

W.probe()

. A written plan names the engine call behind each

W.*

step (procedures P0 table).

这里的专家级意味着：世界依据规则确定规模，按重要性层级布置，从第一张地图开始就进行流式加载与预算控制，并通过脚本逐区域修改，绝不手动勾选数千个 actor。环境美术负责决定哪些内容保留手工制作、哪些进行烘焙、哪些在运行时生成，然后用数量、trace 或 screenshot 证明每项选择。如果此处提到的某个同级 skill 未包含在可用 skills 中，请要求用户安装（

npx skills add scenario-labs/skills --skill <name>

）；无人值守时，则依据 tool schemas 继续，并标明缺失项。

必需背景： 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.*

步骤指定对应的 engine call（procedures P0 表）。

Stance (the expert delta)

立场（专家能力增量）

Start from the integrated setup, then measure. File > New Level > Open World gives World Partition, OFPA, Data Layers, HLOD and outdoor lighting: "just use the template" (Sam Deiter, EEf07ggFWRw [00:20:40]). One runtime grid: more grids "can negatively impact performance" (World Partition doc). WP and OFPA from day one held 100,000 actors (Sam Dark, Subnautica 2, AalP65lrtpo [00:19:20]).
Place by tier of importance. Hero assets and key areas by hand; shrubs to trees and rocks pre-baked; only grass-class detail generated at runtime on the GPU (CD Projekt RED and Epic, icIFFlOyob4 [00:04:23]-[00:07:05]). Collision and far visibility force persistent placement (Unreal Sensei, 5ju7wyvZGBI [00:54:16]). Bake what players do not perceive as varied; preview procedural output in the editor (Dark [00:07:56]). Decide what stays manual first (Matt Oztalay, TbNZ4GKaTow [00:32:26]).
PCG is authored like materials. Template graphs with parameters, Graph Instances per use (Oztalay [00:12:18]); Is Partitioned is "pretty mandatory" [00:22:34]. Output inherits the PCG actor's Data Layer and HLOD Layer: assign them before generating (PCG doc). Grids: unbounded for parameters, 128 m for landscape reads, 32 m for scatter; every CPU to GPU transfer costs; layer weights do not exist on the GPU (icIFFlOyob4 [00:08:04] [00:23:16] [00:24:12]). Pop-in is generation latency, judged in Test builds [00:27:10] [00:27:44]. Bad data must be loud: Warn on Data Missing Attribute (Oztalay frame 00:10:47).
A landscape is sized, not picked. Valid sizes (2017, 4033, never 2048), at most 1024 components, 2x2 sections, edit layers (Landscape doc). Z scale and actor Z come from the exported heights (Z = span / 512, actor at the midpoint), never a declared relief: 250 m on paper reached 314 m and clipped 123,356 pixels in our GREEN test [added]. The material contract, built by scenario-unreal-materials, is checked here: Opaque with Opacity Mask wired, one LB Alpha Blend base, a Layer Info per name (Landscape doc); triplanar only on the steep layer, anti-tiling on large layers, low specular (Sensei [00:11:12]-[00:15:36]).
Nanite by default, construction still matters. "Enabled wherever possible" (Nanite doc), but porous kitbashes, hard-edge splits, seams and noisy vertex colors stop simplification: 250 MB vs 12 MB, same look (Epic, 6igUsOp8FdA [00:02:46]-[00:08:04]). Distance culling does not apply to Nanite (Nanite doc). Tessellation has no collision: per layer, center 0.5 on ground, 1 on vertical rock; dicing rate 2 [00:22:58] [00:29:53]. Foliage opaque and modeled (Quixel, aZr-mWAzoTg [00:01:46]).
Streaming structure follows content. One HLOD layer per family: Instancing for foliage, Merged Mesh for buildings, Simplified when merged is still heavy (doc; Deiter [00:41:13]). Level Instance when content changes with gameplay, Packed Level Actor for static sets [00:30:59]. Runtime Data Layers only for gameplay state (doc). Teleport targets need a Streaming Source and, for runtime PCG, a generation source (doc; icIFFlOyob4 [00:36:44]).
World-scale work is scripted, regional and validated. Scripts, never Outliner select-and-drag; whole-map jobs as builder commandlets region by region (Dark [00:20:23] [00:20:55]). Builders generate, then HLODs; generated actors stay out of changelists (Oztalay [00:26:23] [00:29:07]). Rules that documents only request become validators (Dark [00:23:04]).
Kits are commitments. Footprint is the maximum extent, pivots frozen, standard door widths, core pieces first, hero last (Burgess and Purkeypile, QBAM27YbKZg [00:06:14] [00:07:51] [00:22:34]). Village paths join the nearest built path (Oztalay [00:20:01]); fences follow a spline grammar [00:18:51].

从集成配置开始，然后测量。 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]）。
按重要性层级布置。 Hero assets 与关键区域由手工放置；灌木到树木和岩石进行预烘焙；仅 grass-class 细节在运行时由 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 应像材质一样进行创作。 使用带参数的模板 graph，并为每种用途创建 Graph Instance（Oztalay [00:12:18]）；Is Partitioned“几乎是必需的”[00:22:34]。输出继承 PCG actor 的 Data Layer 和 HLOD Layer：生成前先分配它们（PCG 文档）。网格划分：参数使用无边界网格，landscape 读取使用 128 m 网格，scatter 使用 32 m 网格；每次 CPU 到 GPU 的传输都有成本；GPU 上不存在 layer weights（icIFFlOyob4 [00:08:04] [00:23:16] [00:24:12]）。Pop-in 属于生成延迟，应在 Test build 中判断 [00:27:10] [00:27:44]。错误数据必须显式暴露：对 Data Missing Attribute 发出 Warn（Oztalay frame 00:10:47）。
Landscape 的尺寸需要计算，而非随意选择。 有效尺寸为 2017、4033，绝不能使用 2048；最多 1024 个 components、2x2 sections，并使用 Edit Layers（Landscape 文档）。Z scale 和 actor Z 必须来自导出的高度（Z = span / 512，actor 位于中点），绝不能依据声明的起伏范围设置：纸面标注 250 m 的地形实际达到 314 m，并在我们的 GREEN test 中裁切了 123,356 个像素 [added]。此处检查由 scenario-unreal-materials 构建的材质契约：Opaque 已连接 Opacity Mask、一个采用 LB Alpha Blend 的 base layer、每个名称对应一个 Layer Info（Landscape 文档）；仅在陡峭 layer 上使用 triplanar，大型 layer 使用 anti-tiling，采用低 specular（Sensei [00:11:12]-[00:15:36]）。
默认使用 Nanite，但 construction 仍然重要。 Nanite 文档建议“尽可能启用”，但多孔的 kitbash 资产、硬边拆分、接缝和嘈杂的 vertex colors 会阻止简化：250 MB 与 12 MB 的资产可以保持相同外观（Epic，6igUsOp8FdA [00:02:46]-[00:08:04]）。距离剔除不适用于 Nanite（Nanite 文档）。Tessellation 没有碰撞：按 layer 设置，地面中心为 0.5，垂直岩石为 1；dicing rate 为 2 [00:22:58] [00:29:53]。Foliage 应为不透明且经过建模（Quixel，aZr-mWAzoTg [00:01:46]）。
Streaming 结构应跟随内容组织。 每个内容 family 使用一个 HLOD layer：foliage 使用 Instancing，建筑物使用 Merged Mesh，合并后仍然过重时使用 Simplified（文档；Deiter [00:41:13]）。内容会随 gameplay 变化时使用 Level Instance，静态场景集合使用 Packed Level Actor [00:30:59]。Runtime Data Layers 仅用于 gameplay state（文档）。Teleport 目标需要 Streaming Source；使用 runtime PCG 时还需要 generation source（文档；icIFFlOyob4 [00:36:44]）。
世界级工作必须脚本化、区域化并经过验证。 使用脚本，绝不通过 Outliner 拖选；整图任务按 region 通过 builder commandlets 执行（Dark [00:20:23] [00:20:55]）。Builders 先生成内容，再生成 HLOD；生成的 actor 不进入 changelists（Oztalay [00:26:23] [00:29:07]）。文档中仅以文字提出的规则应转化为 validators（Dark [00:23:04]）。
Kits 意味着长期承诺。 Footprint 指最大范围，pivots 必须冻结，使用标准门宽，核心部件优先，Hero 部件最后制作（Burgess 和 Purkeypile，QBAM27YbKZg [00:06:14] [00:07:51] [00:22:34]）。村庄路径连接到最近的已建路径（Oztalay [00:20:01]）；围栏遵循 spline grammar [00:18:51]。

Establish first

首先确定

Input	Changes	Default when silent
Platform, frame budget	Nanite, foliage path, layers; PCG time, grass density	PC and consoles, Nanite on, 60 fps (scenario-unreal-performance)
Size, quad size, height source	layout, Z scale, actor Z	`W.plan_landscape` , 1 m quads; Z fitted to the heights
Fastest traversal, teleports	loading range, streaming and generation sources	ask gameplay; recorded as unknown
Terrain features, Experimental tolerance	Landscape vs Mesh Terrain; Nanite Foliage, PVE, FastGeo	Landscape; no Experimental feature for shipping
Manual vs procedural, source control	graph scope, who commits generated PCG	hand: village layout, river, roads, hero areas; builders own generation

输入	变更内容	未说明时的默认值
平台、帧预算	Nanite、foliage 路径、layers；PCG 时间、grass 密度	PC 和主机，启用 Nanite，60 fps（scenario-unreal-performance）
尺寸、quad 尺寸、高度来源	布局、Z scale、actor Z	`W.plan_landscape` ，1 m quads；Z 根据高度拟合
最快通行方式、teleports	加载范围、streaming 和 generation sources	询问 gameplay；记录为 unknown
地形特性、Experimental 容错度	Landscape 还是 Mesh Terrain；Nanite Foliage、PVE、FastGeo	Landscape；发布版本不使用 Experimental feature
手工还是程序化、source control	graph 范围、谁提交生成的 PCG	手工：村庄布局、河流、道路、Hero 区域；生成内容由 builders 负责

Workflow

工作流

Each stage is an

ue_run

job or a live call; code in procedures (P-numbers).

Brief as a world spec (P1), like
```
W.U1_EXAMPLE_SPEC
```
;
```
W.probe()
```
once per install. GATE:
```
W.check_world_spec(spec)["ok"]
```
, info findings answered.

Map (P2).

W.new_open_world_map(path)

from the template; old levels through

W.convert_args(..., report_only=True)

first. GATE:

W.wp_facts_check(W.world_facts())

clean; PIE screenshot with

wp.Runtime.ToggleDrawRuntimeHash2D

Terrain (P3, P4). DCC heightmap or the blockout
```
W.valley_heightmap
```
;
```
W.export_heightmap
```
fits Z and actor Z to the real range. Creation is one Landscape mode step (Location Z =
```
actor_z_cm
```
, Scale Z =
```
z_scale
```
) unless an MCP tool does it [verify]. Edit layers Base, Sculpt Details, Paint, Splines, Patches. River (Water Body River or a Splines-layer spline) before heavy painting. Then the landscape builder. GATE:
```
W.heightmap_clip_gate
```
empty (0 clipped pixels) before import;
```
W.landscape_facts()
```
matches plan, scale and location;
```
W.landscape_material_check
```
clean; Layer Debug, cliff close-up, grass in sun, mannequin at 2, 10 and 100 m.
Organization (P5, P6). Editor Data Layers per family; HLOD layers from
```
W.hlod_plan
```
; Streaming Source components at teleport targets. GATE:
```
W.data_layer_check
```
,
```
W.hlod_actor_check
```
clean.
Village and kits (P7).
```
W.kit_piece_check
```
,
```
W.door_width_check
```
; houses as Level Instances or Packed Level Actors; clutter as tagged assemblies (
```
W.tag_actors
```
); paths by
```
W.village_paths
```
into landscape splines; fences by grammar strings. Version the map before breaking an instance. GATE: no kit errors; no z-fighting or obvious repetition from the paths.
Nanite (P8).
```
W.nanite_construction_check(W.obj_construction_stats(obj))
```
on DCC exports;
```
W.batch_nanite(paths, dry_run=True)
```
, read, run;
```
W.tessellation_check
```
with per-layer centers. GATE: no translucent Nanite mesh; Overdraw over the canopy; feet on displaced ground.
Baked PCG: forest and rocks (P9). Template graph (layer filter warning on missing data, slope density, Extents Modifier into Difference for paths, Distance thinning at banks, understory differenced against trees, Self Pruning, species table, collision on trunks only), checked by
```
W.pcg_graph_lint
```
;
```
W.spawn_pcg_volume(..., hlod_layer=, data_layer=)
```
. Debug one volume (D) first. GATE:
```
W.pcg_component_check
```
clean; counts against
```
W.expected_points
```
; top-down and gameplay-height shots, nothing on paths or curated areas.
Runtime grass (P10).
```
W.grass_rings()
```
(dense to 128 m on 32 m cells, sparse to 256 m on 128 m cells, far edge recolored); mask from grass types without meshes through Generate Grass Maps; a placeholder in every asset array; editor viewport as generation source; landscape cache;
```
pcg.FrameTime
```
set. GATE:
```
W.runtime_grass_check
```
and
```
W.find_gpu_transfers
```
clean;
```
W.generation_lead_check
```
with latency measured on a Test build.
Builds (P11).
```
for name, args in W.build_pipeline(map, graphs): ue_run.run_commandlet(uproject, name, args)
```
: landscape, PCG, HLOD. GATE: exit 0 each; HLOD actors per layer counted;
```
W.changelist_check
```
, then submit from the editor.
Review and handoff (P12 to P14).
```
W.tour(...)
```
with
```
W.REVIEW_CONSOLE
```
passes,
```
ue_review.image_checks
```
on every shot, then look;
```
W.world_rules_check(W.world_census(), vocab)
```
;
```
W.budget_sheet
```
,
```
W.lighting_handoff
```
. GATE: critique rubric passes; nothing reported done without a capture.

每个阶段都是一项

ue_run

job 或一次 live call；代码见 procedures（P 编号）。

将简报编写为 world spec（P1），例如
```
W.U1_EXAMPLE_SPEC
```
；每次安装调用一次
```
W.probe()
```
。GATE：
```
W.check_world_spec(spec)["ok"]
```
，并答复所有 info 类发现。

地图（P2）。通过模板执行

W.new_open_world_map(path)

；旧关卡先通过

W.convert_args(..., report_only=True)

转换。GATE：

W.wp_facts_check(W.world_facts())

无问题；使用

wp.Runtime.ToggleDrawRuntimeHash2D

获取 PIE screenshot。

地形（P3、P4）。使用 DCC heightmap 或 blockout
```
W.valley_heightmap
```
；
```
W.export_heightmap
```
根据真实范围拟合 Z 和 actor Z。创建过程通过一步 Landscape mode 操作完成（Location Z =
```
actor_z_cm
```
，Scale Z =
```
z_scale
```
），除非由 MCP tool 完成 [verify]。Edit Layers：Base、Sculpt Details、Paint、Splines、Patches。在进行大量绘制前先创建河流（Water Body River 或 Splines-layer spline），然后运行 landscape builder。GATE：导入前
```
W.heightmap_clip_gate
```
为空（裁切像素为 0）；
```
W.landscape_facts()
```
与计划中的 scale 和 location 一致；
```
W.landscape_material_check
```
无问题；检查 Layer Debug、悬崖特写、阳光下 grass，以及人形模型在 2、10 和 100 m 处的效果。
组织（P5、P6）。每个 family 使用一个 Editor Data Layer；通过
```
W.hlod_plan
```
创建 HLOD layers；在 teleport 目标放置 Streaming Source components。GATE：
```
W.data_layer_check
```
、
```
W.hlod_actor_check
```
无问题。
村庄与 Kits（P7）。使用
```
W.kit_piece_check
```
、
```
W.door_width_check
```
；房屋使用 Level Instances 或 Packed Level Actors；clutter 使用带标签的组件集合（
```
W.tag_actors
```
）；通过
```
W.village_paths
```
将路径写入 landscape splines；围栏使用 grammar strings。修改 instance 前先为地图创建版本。GATE：不存在 kit 错误；路径不产生 z-fighting 或明显重复。
Nanite（P8）。对 DCC exports 执行
```
W.nanite_construction_check(W.obj_construction_stats(obj))
```
；执行
```
W.batch_nanite(paths, dry_run=True)
```
，读取结果后运行；使用
```
W.tessellation_check
```
检查各 layer 的中心值。GATE：不存在透明 Nanite mesh；树冠区域的 overdraw 符合预期；角色双脚贴合位移后的地面。
烘焙 PCG：森林与岩石（P9）。模板 graph（layer filter 缺少数据时发出 warning、slope density、将 Extents Modifier 设为 Difference 以避让路径、河岸使用 Distance thinning、understory 相对于 trees 使用 Difference、Self Pruning、species table、collision 仅用于树干），通过
```
W.pcg_graph_lint
```
检查；执行
```
W.spawn_pcg_volume(..., hlod_layer=, data_layer=)
```
。先调试一个 volume（D）。GATE：
```
W.pcg_component_check
```
无问题；数量与
```
W.expected_points
```
一致；获取俯视图和 gameplay 高度截图；路径和经过精心策划的区域中不应出现任何对象。
Runtime Grass（P10）。
```
W.grass_rings()
```
（32 m cells 上密集覆盖至 128 m，128 m cells 上稀疏覆盖至 256 m，远端边缘重新着色）；对不含 mesh 的 grass types 通过 Generate Grass Maps 生成 mask；每个 asset array 中放置一个 placeholder；将 Editor Viewport 作为 generation source；启用 landscape cache；设置
```
pcg.FrameTime
```
。GATE：
```
W.runtime_grass_check
```
和
```
W.find_gpu_transfers
```
无问题；使用
```
W.generation_lead_check
```
，并在 Test build 中测量延迟。
构建（P11）。
```
for name, args in W.build_pipeline(map, graphs): ue_run.run_commandlet(uproject, name, args)
```
：landscape、PCG、HLOD。GATE：每项退出码均为 0；统计每个 layer 的 HLOD actor 数量；执行
```
W.changelist_check
```
，然后从 Editor 提交。
审查与交付（P12 至 P14）。使用
```
W.tour(...)
```
，确保
```
W.REVIEW_CONSOLE
```
检查通过；对每张截图执行
```
ue_review.image_checks
```
，然后进行人工查看；执行
```
W.world_rules_check(W.world_census(), vocab)
```
；生成
```
W.budget_sheet
```
、
```
W.lighting_handoff
```
。GATE：critique rubric 通过；未提供截图不得报告完成。

Numbers

数值

Value	Setting	Relative to / source
Landscape 2 km	2017 x 2017, 63 quads, 2x2, 256 of max 1024 components	1 m quads (Landscape doc)
Z scale	span cm / 512 x 1.02; actor Z at the span midpoint	16-bit heights (doc); headroom [added]
Template grid	cell 25,600 cm, range 76,800 cm	profile first (Deiter [00:15:32])
PCG partition grid	25,600 cm	PCG World Actor (Oztalay frame 00:23:16)
Hierarchical grids	unbounded, 128 m, 32 m	runtime grass (icIFFlOyob4 [00:08:39])
Grass rings	dense to 128 m, sparse to 256 m	icIFFlOyob4 [00:15:30]
Instances per 32 m cell	10k to 20k fine	base PS5, 5.6 demo [00:30:26]
`pcg.FrameTime`	5 ms default; 2 ms in the demo	5.6 notes; base PS5 [00:26:24]
Height upload	about 0.5 ms game thread per 32 m cell	base PS5 [00:24:12]
Streamed instances	16 million hard limit	Nanite doc
Nanite construction	250 MB vs 12 MB, same look	6igUsOp8FdA [00:02:46]
Nanite Assemblies	5 to 10% of asset size; 200 to 1,000 wind bones	aZr-mWAzoTg [00:07:13] [00:09:51]
Dicing rate	2; slower below 2 and above about 5 or 6	6igUsOp8FdA [00:29:53]
Displacement center	0.5 ground, 1 vertical rock, per layer	collision surface [00:22:58]
Terrain specular	0.02 (Sensei); 0.5 as a cavity-driven ceiling (Cloward)	5ju7wyvZGBI [00:11:12]; 0L5Azq6ugyo [00:01:19]
Tick aggregation	above 10 to 15 placed instances	Dark [00:23:04]
Mobile landscape	3 layers, 16 samplers	ES3.1 (doc)

数值	设置	相对基准或来源
2 km Landscape	2017 x 2017，63 quads，2x2，最大 1024 个 components 中使用 256 个	1 m quads（Landscape 文档）
Z scale	span cm / 512 x 1.02；actor Z 位于 span 中点	16-bit heights（文档）；预留余量 [added]
模板网格	cell 为 25,600 cm，range 为 76,800 cm	首先确定 profile（Deiter [00:15:32]）
PCG partition 网格	25,600 cm	PCG World Actor（Oztalay frame 00:23:16]）
层级网格	无边界、128 m、32 m	runtime grass（icIFFlOyob4 [00:08:39]）
Grass rings	密集至 128 m，稀疏至 256 m	icIFFlOyob4 [00:15:30]
每个 32 m cell 的实例数	10k 至 20k 较合适	基准 PS5，5.6 demo [00:30:26]
`pcg.FrameTime`	默认 5 ms；demo 中为 2 ms	5.6 notes；基准 PS5 [00:26:24]
Height upload	每个 32 m cell 的 game thread 约 0.5 ms	基准 PS5 [00:24:12]
Streamed instances	16 million 硬限制	Nanite 文档
Nanite construction	250 MB 与 12 MB，外观相同	6igUsOp8FdA [00:02:46]
Nanite Assemblies	资产大小的 5% 至 10%；200 至 1,000 个 wind bones	aZr-mWAzoTg [00:07:13] [00:09:51]
Dicing rate	2；低于 2 或高于约 5 至 6 时性能会下降	6igUsOp8FdA [00:29:53]
Displacement center	地面为 0.5，垂直岩石为 1，按 layer 设置	collision surface [00:22:58]
Terrain specular	0.02（Sensei）；0.5 作为 cavity-driven ceiling（Cloward）	5ju7wyvZGBI [00:11:12]；0L5Azq6ugyo [00:01:19]
Tick aggregation	已放置实例超过 10 至 15 个时	Dark [00:23:04]
Mobile Landscape	3 layers，16 samplers	ES3.1（文档）

Quality gates

质量门禁

Measurable: the workflow checks (all
```
W.*_check
```
,
```
heightmap_clip_gate
```
,
```
pcg_graph_lint
```
,
```
find_gpu_transfers
```
);
```
ue_audit
```
on imports; builders exit 0;
```
stat unit
```
,
```
stat gpu
```
per viewpoint; PCG time in Insights on a Test build;
```
-trace=WorldStreaming
```
;
```
wp.Runtime.HLOD 0/1
```
A/B.
Visual: runtime hash overlay without failed cells; Layer Debug without black spots; tiling against a mannequin; cliffs without stretching; no plastic sheen on grass in sun; feet on displaced ground; canopy overdraw; Hierarchical LOD Coloration and HLOD silhouettes; ring handover and pop-in on frame-by-frame video; nothing on paths, banks thinned; rocks grounded. Rubric:
```
references/critique.md
```
.

可测量： 工作流检查（所有
```
W.*_check
```
、
```
heightmap_clip_gate
```
、
```
pcg_graph_lint
```
、
```
find_gpu_transfers
```
）；对 imports 执行
```
ue_audit
```
；builders 退出码为 0；针对每个视点执行
```
stat unit
```
、
```
stat gpu
```
；在 Test build 中通过 Insights 检查 PCG 时间；使用
```
-trace=WorldStreaming
```
；执行
```
wp.Runtime.HLOD 0/1
```
A/B 测试。
视觉： runtime hash overlay 中没有失败单元格；Layer Debug 中没有黑斑；使用人形模型检查平铺；悬崖没有拉伸；阳光下的 grass 没有塑料质感；角色双脚贴合位移后的地面；检查树冠区域的 overdraw；检查 Hierarchical LOD Coloration 和 HLOD silhouettes；通过逐帧视频检查 ring 切换与 pop-in；路径上没有任何对象，河岸已做稀疏处理；岩石正确落地。评分标准：
```
references/critique.md
```
。

Common mistakes

常见错误

Mistake	What it looks like	Fix
Z scale from a declared relief	plateaus and pits after import	fitted export, `W.heightmap_clip_gate`
2048 heightmap	import refuses or resamples	2017 or 4033
All layers height-blended; layer without Layer Info	black patches; layer never paints	base layer Alpha Blend; Layer Info, same name
Second runtime grid	streaming cost, no gain	one grid, HLOD for distance
Runtime Data Layers for tidiness; Level Blueprint references	hitches; actors always loaded	Editor Data Layers; Blueprint classes
PCG volume without HLOD or Data Layer	baked forest missing at distance	assign both before generating
Runtime graph invisible in editor	artists see nothing	Treat Editor Viewport as Generation Source
Layer weights in a GPU graph	empty grass mask	grass types without meshes, Generate Grass Maps
Empty artist asset array	grass streams collapse	one placeholder per array
Cull or draw distance on Nanite	no thinning, rings do not hand over	HLOD, generation radius per ring
GPU-only trees	trees missing from Lumen	GPU-only for small things
One ever-larger grass radius	instance explosion, visible edge	two rings, recolored edge
Porous kitbashed rocks	huge assets, holes at distance	connected base, tiling texture
Construction-script scatter	170,000 bodies, 7-minute map open (Oztalay [00:30:49])	PCG output, clutter collision off
Generated PCG actors checked in	contention, stale data	builders own generation
Select-all edits on a big map	editor stalls	`W.region_batch` or a builder

错误	表现	修复方法
根据声明的起伏范围设置 Z scale	导入后出现台地和坑洼	使用拟合后的 export，运行 `W.heightmap_clip_gate`
2048 heightmap	导入被拒绝或重新采样	使用 2017 或 4033
所有 layers 都使用 height blend；某个 layer 没有 Layer Info	出现黑色斑块；layer 始终无法绘制	base layer 使用 Alpha Blend；Layer Info 使用相同名称
第二个 runtime 网格	增加 streaming 成本，却没有收益	使用单一网格，并通过 HLOD 处理远距离内容
为整洁而使用 Runtime Data Layers；Level Blueprint 引用	出现卡顿；actor 始终保持加载	使用 Editor Data Layers 和 Blueprint classes
PCG volume 没有 HLOD 或 Data Layer	远处的烘焙森林缺失	生成前同时分配两者
Runtime graph 在编辑器中不可见	美术人员看不到任何内容	将 Editor Viewport 视为 Generation Source
GPU graph 中使用 layer weights	grass mask 为空	使用不含 meshes 的 grass types，并执行 Generate Grass Maps
美术资产数组为空	grass streams 崩溃	每个数组至少放置一个 placeholder
对 Nanite 设置 cull 或 draw distance	无法进行稀疏处理，rings 无法切换	使用 HLOD，并按 ring 设置 generation radius
仅使用 GPU 的树木	树木未出现在 Lumen 中	GPU-only 仅用于小型对象
不断扩大的单一 grass radius	实例爆炸，出现明显边缘	使用两个 rings，并重新着色边缘
多孔的 kitbashed rocks	资产过大，远距离出现孔洞	使用连通的 base 和 tiling texture
使用 construction script 散布	170,000 个 bodies，地图打开耗时 7 分钟（Oztalay [00:30:49]）	使用 PCG output，并关闭 clutter collision
将生成的 PCG actors 提交到版本控制	产生冲突和数据陈旧	由 builders 负责生成内容
在大型地图上使用全选编辑	Editor 停顿	使用 `W.region_batch` 或 builder

Handoffs

交接

Receives from scenario-unreal-pipeline-automation: meshes passed by
```
ue_audit
```
, standard kit pieces, DCC heightmaps with their height range; construction failures go back (and to scenario-maya-expert, scenario-blender-expert).
Receives from scenario-unreal-materials: the landscape instance and layer list (blend types, steep layer, anti-tiling), RVTs with bounds, grass type names, the rock RVT blend, opaque foliage. Specular is theirs; the world artist reports sheen from the sun capture.
Delivers to scenario-unreal-lighting-rendering: the map, World Bookmarks or
```
tour_viewpoints
```
,
```
W.lighting_handoff
```
(template lights, GPU-only roles outside the Lumen scene, HLOD far-field and distance-field flags, Data Layer states).
Delivers to scenario-unreal-performance:
```
W.budget_sheet
```
and the tour path.
Also: scenario-unreal-gameplay (streaming and generation sources, Asset User Data, tick aggregation); scenario-unreal-pipeline-automation (world rules for its validators); scenario-unreal-cinematics (
```
pcg.FrameTime
```
pauses, icIFFlOyob4 [00:28:51]); scenario-unreal-vfx (water shading).

接收自 scenario-unreal-pipeline-automation： 通过
```
ue_audit
```
的 meshes、标准 kit pieces、包含高度范围的 DCC heightmaps；construction failures 会退回，也可转交 scenario-maya-expert、scenario-blender-expert。
接收自 scenario-unreal-materials： landscape instance 和 layer 列表（blend types、steep layer、anti-tiling）、包含 bounds 的 RVTs、grass type 名称、rock RVT blend、opaque foliage。Specular 由该环节负责；world artist 报告阳光捕获中的 sheen。
交付给 scenario-unreal-lighting-rendering： 地图、World Bookmarks 或
```
tour_viewpoints
```
、
```
W.lighting_handoff
```
（模板灯光、Lumen scene 之外的 GPU-only 角色、HLOD far-field 和 distance-field flags、Data Layer states）。
交付给 scenario-unreal-performance：
```
W.budget_sheet
```
和 tour path。
其他： scenario-unreal-gameplay（streaming 和 generation sources、Asset User Data、tick aggregation）；scenario-unreal-pipeline-automation（供其 validators 使用的 world rules）；scenario-unreal-cinematics（
```
pcg.FrameTime
```
暂停，icIFFlOyob4 [00:28:51]）；scenario-unreal-vfx（water shading）。

UE 5.8 notes

UE 5.8 注意事项

New WP maps use the runtime hash with partitions (5.4): read
```
world_facts()
```
before writing grid properties [verify].
PCG on by default; PCG Python Data Processor, PCG Builder Volume; landscape cache opt-in since 5.6 (runtime CPU reads fail without it).
Edit layers mandatory (5.7);
```
landscape.ForceLayersFullUpdate
```
replaces
```
ForceLayersUpdate
```
;
```
WorldPartitionLandscapeBuilder
```
(5.7); water brushes force a global merge.
HLOD: Build HLOD for Selection or Region,
```
bForceRayTracingFarField
```
, Custom HLOD actors (5.7); Approximate Mesh absent from the saved doc [verify].
Experimental: Mesh Terrain, Nanite Foliage, PVE, FastGeo, World Streaming Insights. Mac: Nanite and VSM Beta on M2 or newer; cook platform
```
Mac
```
.

新 WP 地图使用带 partitions 的 runtime hash（5.4）：写入 grid properties 前先读取
```
world_facts()
```
[verify]。
PCG 默认启用；提供 PCG Python Data Processor、PCG Builder Volume；自 5.6 起 landscape cache 需要主动启用（否则 runtime CPU reads 会失败）。
Edit Layers 在 5.7 中成为必需；
```
landscape.ForceLayersFullUpdate
```
替代
```
ForceLayersUpdate
```
；
```
WorldPartitionLandscapeBuilder
```
（5.7）；water brushes 会强制执行全局合并。
HLOD：Build HLOD for Selection 或 Region、
```
bForceRayTracingFarField
```
、Custom HLOD actors（5.7）；保存的文档中没有 Approximate Mesh [verify]。
Experimental：Mesh Terrain、Nanite Foliage、PVE、FastGeo、World Streaming Insights。Mac：M2 或更新版本支持 Nanite 和 VSM Beta；cook 平台为
```
Mac
```
。

References

参考资料

```
references/expert-notes.md
```
: judgment by expert, with timestamps.
```
references/procedures.md
```
: P0 to P14, full code, engine calls behind the toolkit, tests, status.
```
references/critique.md
```
: the rubric for each gate.
```
references/gui-paths.md
```
: editor menus for every procedure.
```
references/sources.md
```
: sources, credentials, URLs, timestamps, revision history.

```
references/expert-notes.md
```
：专家判断及时间戳。
```
references/procedures.md
```
：P0 至 P14、完整代码、工具包对应的 engine calls、测试和状态。
```
references/critique.md
```
：每个 gate 的评分标准。
```
references/gui-paths.md
```
：每项操作的 Editor 菜单路径。
```
references/sources.md
```
：来源、凭据、URL、时间戳和修订历史。