unreal-world-partition

Unreal 5.8 World Partition

---
name: unreal-world-partition
description: Operational Unreal Engine 5.8 guidance for World Partition, streaming sources, runtime grids, Data Layers, HLODs, One File Per Actor, Level Instances, conversion, commandlets, PCG integration, and large-world diagnosis. Use when designing, implementing, profiling, or debugging a partitioned or streamed world.
---

# Unreal 5.8 World Partition

## Ownership boundary

This skill owns cells, streaming sources, runtime grids, Data Layers, HLODs, and OFPA/Level Instance
world organization. Route procedural generation/output rules to
[`unreal-pcg`](../unreal-pcg/SKILL.md), Landscape topology and deformation to
[`unreal-landscape`](../unreal-landscape/SKILL.md), and cooked-asset residency/readiness to
[`unreal-memory-streaming`](../unreal-memory-streaming/SKILL.md).

Route a world-streaming task to the smallest relevant reference. Give concrete editor actions, runtime ownership, failure checks, and a verification pass.

## Select the world system first

- Use **World Partition with Enable Streaming on** for a continuous world whose content should load by distance or explicit streaming sources.
- Use **World Partition with Enable Streaming off** when its authoring model, OFPA, Data Layers, or future scale helps but the whole map can remain resident.
- Use **Level Instances** for reusable points of interest or gameplay assemblies. Prefer OFPA-backed Embedded Mode in a World Partition main world.
- Use **Packed Level Blueprints** for repeated, dense, static-mesh arrangements. Do not assume arbitrary components survive packing.
- Keep traditional sublevel streaming for a legacy architecture or a discrete-level requirement that World Partition does not satisfy. Do not introduce World Composition in a new UE5 project.

Read [system-selector-conversion.md](references/system-selector-conversion.md) before converting an existing world.

## Route by task

| Need | Load |
|---|---|
| Choose a world model or convert a map | [system-selector-conversion.md](references/system-selector-conversion.md) |
| Decide spatial loading, references, ownership, persistence | [actor-placement-references.md](references/actor-placement-references.md) |
| Configure sources, cells, grids, loading ranges, teleport gates | [streaming-sources-grids.md](references/streaming-sources-grids.md) |
| Author editor/runtime variants and state changes | [data-layers.md](references/data-layers.md) |
| Build and tune distant proxy content | [hlod.md](references/hlod.md) |
| Reuse assemblies; understand OFPA and runtime modes | [level-instances-ofpa.md](references/level-instances-ofpa.md) |
| Combine PCG with partitioning, Data Layers, and HLOD | [pcg-integration.md](references/pcg-integration.md) |
| Diagnose loading or run unattended builds | [debugging-builders.md](references/debugging-builders.md) |
| Apply common production patterns and test gates | [patterns-testing.md](references/patterns-testing.md) |
| Verify claims or feature maturity | [sources.md](references/sources.md) |

## Execute in this order

1. State map scale, movement speed, multiplayer model, target hardware, memory budget, and whether transitions may block.
2. Classify each important actor by spatial lifetime, Data Layer state, runtime grid, HLOD policy, and hard-reference dependencies.
3. Begin with the default 2D Runtime Spatial Hash and one runtime grid. Add grids only after a measured requirement.
4. Place or configure streaming sources. Derive initial loading range from maximum travel speed, worst observed load latency, and safety margin.
5. Gate teleports and scripted arrivals on streaming completion; provide timeout and failure behavior.
6. Add Runtime Data Layers for stateful world variants, not as a substitute for every gameplay visibility flag.
7. Assign and build HLODs for distant, non-interactive representation. Compare proxies against sources at expected viewing distance.
8. Validate editor, PIE, standalone, multiplayer, cooked build, target device, and worst-case traversal.
9. Profile cell timing, memory, I/O, hitches, draw calls, and HLOD transitions before increasing ranges or making content always loaded.

## Hard rules

- Do not solve streaming bugs by marking broad content **not spatially loaded**; that converts uncertainty into permanent memory and initialization cost.
- Treat hard actor references as streaming dependencies. Referenced actors can be bundled and loaded together even when spatially separated.
- The server owns Runtime Data Layer state in networked play. Replicate gameplay state; do not let clients independently decide authoritative world state.
- A distant HLOD is representation, not authoritative collision, interaction, AI, or gameplay state.
- Do not teleport into an unloaded destination. Enable a destination streaming source, wait for completion, then move the player and retire the temporary source.
- Do not tune only in the editor. Cooked packaging, I/O, memory pressure, and target hardware decide whether streaming works.
- OFPA reduces file contention; it does not remove logical merge conflicts or make cross-actor ownership safe.
- Keep Experimental features explicitly labeled. UE 5.8 World Partition Insights and Fast Geometry-related workflows require deliberate opt-in and validation.

## Answer contract

Return:

1. **Selected system and assumptions** — including why it fits.
2. **Actor/content classification** — spatial loading, Data Layer, grid, HLOD, references.
3. **Exact actions** — editor paths, properties, components, APIs, commands, or commandlets.
4. **Parameter effects** — what changing cell size, loading range, priority, or state actually does.
5. **Network and packaging consequences**.
6. **Failure checks and recovery**.
7. **Verification** — observable pass criteria on a cooked target build.

Do not invent universal cell sizes, loading radii, or memory budgets. Supply a starting hypothesis only when its assumptions are stated, then require measurement.

## Ownership boundary

This skill owns cells, streaming sources, runtime grids, Data Layers, HLODs, and OFPA/Level Instance
world organization. Route procedural generation/output rules to
[`unreal-pcg`](/unreal/unreal-pcg/), Landscape topology and deformation to
[`unreal-landscape`](/unreal/unreal-landscape/), and cooked-asset residency/readiness to
[`unreal-memory-streaming`](/unreal/unreal-memory-streaming/).

Route a world-streaming task to the smallest relevant reference. Give concrete editor actions, runtime ownership, failure checks, and a verification pass.

## Select the world system first

- Use **World Partition with Enable Streaming on** for a continuous world whose content should load by distance or explicit streaming sources.
- Use **World Partition with Enable Streaming off** when its authoring model, OFPA, Data Layers, or future scale helps but the whole map can remain resident.
- Use **Level Instances** for reusable points of interest or gameplay assemblies. Prefer OFPA-backed Embedded Mode in a World Partition main world.
- Use **Packed Level Blueprints** for repeated, dense, static-mesh arrangements. Do not assume arbitrary components survive packing.
- Keep traditional sublevel streaming for a legacy architecture or a discrete-level requirement that World Partition does not satisfy. Do not introduce World Composition in a new UE5 project.

Read [system-selector-conversion.md](/unreal/unreal-world-partition/system-selector-conversion/) before converting an existing world.

## Route by task

| Need | Load |
|---|---|
| Choose a world model or convert a map | [system-selector-conversion.md](/unreal/unreal-world-partition/system-selector-conversion/) |
| Decide spatial loading, references, ownership, persistence | [actor-placement-references.md](/unreal/unreal-world-partition/actor-placement-references/) |
| Configure sources, cells, grids, loading ranges, teleport gates | [streaming-sources-grids.md](/unreal/unreal-world-partition/streaming-sources-grids/) |
| Author editor/runtime variants and state changes | [data-layers.md](/unreal/unreal-world-partition/data-layers/) |
| Build and tune distant proxy content | [hlod.md](/unreal/unreal-world-partition/hlod/) |
| Reuse assemblies; understand OFPA and runtime modes | [level-instances-ofpa.md](/unreal/unreal-world-partition/level-instances-ofpa/) |
| Combine PCG with partitioning, Data Layers, and HLOD | [pcg-integration.md](/unreal/unreal-world-partition/pcg-integration/) |
| Diagnose loading or run unattended builds | [debugging-builders.md](/unreal/unreal-world-partition/debugging-builders/) |
| Apply common production patterns and test gates | [patterns-testing.md](/unreal/unreal-world-partition/patterns-testing/) |
| Verify claims or feature maturity | [sources.md](/unreal/unreal-world-partition/sources/) |

## Execute in this order

1. State map scale, movement speed, multiplayer model, target hardware, memory budget, and whether transitions may block.
2. Classify each important actor by spatial lifetime, Data Layer state, runtime grid, HLOD policy, and hard-reference dependencies.
3. Begin with the default 2D Runtime Spatial Hash and one runtime grid. Add grids only after a measured requirement.
4. Place or configure streaming sources. Derive initial loading range from maximum travel speed, worst observed load latency, and safety margin.
5. Gate teleports and scripted arrivals on streaming completion; provide timeout and failure behavior.
6. Add Runtime Data Layers for stateful world variants, not as a substitute for every gameplay visibility flag.
7. Assign and build HLODs for distant, non-interactive representation. Compare proxies against sources at expected viewing distance.
8. Validate editor, PIE, standalone, multiplayer, cooked build, target device, and worst-case traversal.
9. Profile cell timing, memory, I/O, hitches, draw calls, and HLOD transitions before increasing ranges or making content always loaded.

## Hard rules

- Do not solve streaming bugs by marking broad content **not spatially loaded**; that converts uncertainty into permanent memory and initialization cost.
- Treat hard actor references as streaming dependencies. Referenced actors can be bundled and loaded together even when spatially separated.
- The server owns Runtime Data Layer state in networked play. Replicate gameplay state; do not let clients independently decide authoritative world state.
- A distant HLOD is representation, not authoritative collision, interaction, AI, or gameplay state.
- Do not teleport into an unloaded destination. Enable a destination streaming source, wait for completion, then move the player and retire the temporary source.
- Do not tune only in the editor. Cooked packaging, I/O, memory pressure, and target hardware decide whether streaming works.
- OFPA reduces file contention; it does not remove logical merge conflicts or make cross-actor ownership safe.
- Keep Experimental features explicitly labeled. UE 5.8 World Partition Insights and Fast Geometry-related workflows require deliberate opt-in and validation.

## Answer contract

Return:

1. **Selected system and assumptions** — including why it fits.
2. **Actor/content classification** — spatial loading, Data Layer, grid, HLOD, references.
3. **Exact actions** — editor paths, properties, components, APIs, commands, or commandlets.
4. **Parameter effects** — what changing cell size, loading range, priority, or state actually does.
5. **Network and packaging consequences**.
6. **Failure checks and recovery**.
7. **Verification** — observable pass criteria on a cooked target build.

Do not invent universal cell sizes, loading radii, or memory budgets. Supply a starting hypothesis only when its assumptions are stated, then require measurement.

unreal 5.8 world partition operational unreal engine 5.8 guidance for world partition, streaming sources, runtime grids, data layers, hlods, one file per actor, level instances, conversion, commandlets, pcg integration, and large-world diagnosis. use when designing, implementing, profiling, or debugging a partitioned or streamed world. actor placement, references, and lifetime actor placement, references, and lifetime classify every load-bearing actor record five decisions: 1. spatial lifetime — source-distance loaded or always resident. 2. world state — no data layer, editor data layer, or runtime data layer and initial state. 3. runtime grid — normally none so the partition system selects the default. 4. distant representation — hlod layer or intentionally none. 5. dependencies — hard actor references, soft asset references, subsystem lookup, or stable identifier. is spatially loaded - enabled: the actor loads when it is in range of a streaming source and is not excluded by a disabled runtime data layer. - disabled: the actor is not distance-streamed; data layer state can still control it. use non-spatial loading for truly global world actors whose lifetime is intentional and cheap. do not use it for distant content, ordinary interactables, or as a blanket cure for missing references. reference rule a hard reference between spatial actors can make them part of the same streaming dependency bundle. a reference spanning distant cells may therefore pull content into memory earlier or keep it resident longer than expected. prefer, according to the requirement: - a subsystem or manager that resolves a nearby actor at use time; - an interface plus overlap/spatial query; - a soft asset reference for asynchronously loaded assets; - a stable gameplay identifier resolved through a registry; - an event/message carrying data rather than a stored pointer. do not replace a required same-lifetime relationship with a soft reference merely to silence a warning. if two actors must exist together, co-location and bundling may be correct; document it. ownership patterns global rule or service put state in gamemode/gamestate, gameinstance, an appropriate subsystem, or a replicated service—not in a random placed actor that happens to remain loaded. spatial interactable keep durable state outside the streamed actor or reconstruct it from a stable id when the cell loads. treat actor unload as normal lifecycle, not destruction of game truth. cross-cell mission dependency store mission state centrally. resolve each endpoint when its cell is present and tolerate absence. avoid direct endpoint-to-endpoint hard references across the world. attached actors keep parent and child streaming policies compatible. test attachment and absolute-transform behavior through unload/reload; editor visibility alone is insufficient. validation - use the reference viewer and size map for suspicious asset chains. - inspect streaming-generation warnings and unexpected actor bundles. - traverse with debug cell visualization enabled and watch whether distant dependencies load. - unload/reload the cell repeatedly; confirm durable gameplay state survives. - test server and client separately because authoritative and client-visible actor sets can differ. data layers data layers data model - a data layer asset is a project asset that declares an editor or runtime layer. - a data layer instance is the world-specific instance and assignment surface. - editor data layers organize authoring views and alternate editing sets; they do not define a runtime state machine. - runtime data layers can be changed at runtime and participate in streaming. runtime states: - unloaded: content is not resident. - loaded: content is resident but not visible/activated. - activated: content is resident and visible/active. treat loaded as a preload state and activated as presentation/gameplay availability. verify component-specific behavior instead of assuming visibility is the only activation consequence. network authority in client/server play, the server changes authoritative runtime data layer state. clients should observe the replicated result. do not let each client independently activate a layer that changes collision, interaction, or world truth. cosmetic client-only variants should use an explicitly client-owned presentation mechanism unless their data layer behavior and replication have been proven for the target design. good uses - preloading a boss arena before revealing it; - switching repaired/destroyed or seasonal world variants; - phasing a location by authoritative quest state; - separating alternate set dressing while preserving shared terrain; - grouping editor-only disciplines or review passes. poor uses - replacing a local component visibility flag for one tiny object; - encoding every quest boolean as a separate layer; - assigning widely scattered actors to many runtime data layers without measuring streaming cost; - hiding authoritative actors only on a client; - storing durable quest truth in the layer state itself. state-transition pattern 1. author a runtime data layer asset and world instance. 2. assign only the content that shares the transition and lifetime. 3. set and document the initial runtime state. 4. on the server, request loaded early enough to cover worst load latency. 5. wait for readiness when the transition requires collision or interaction. 6. request activated at the reveal/phase boundary. 7. persist the underlying gameplay state separately so load/save can reconstruct the layer state. 8. test late join, reconnect, respawn, and server travel. performance caution actors spread over large areas or repeated across many runtime data layers can degrade streaming performance by creating broad or fragmented dependencies. use cohesive spatial/state groups and inspect the resulting cells. debug commands text wp.dumpdatalayers wp.runtime.setdatalayerruntimestate wp.runtime.toggledatalayeractivation wp.runtime.toggledrawdatalayers epic's current documentation also lists wp.runtime.debugfilerbydatalayer with that spelling. confirm the available console command in the running 5.8 build before automating it. debugging and builder commandlets debugging and builder commandlets diagnose in layers 1. source — is an enabled source requesting the expected location, grid, shape, target state, and priority? 2. cell — is the expected runtime cell generated, requested, loaded, and activated? 3. policy — do is spatially loaded, data layer state, grid assignment, and references agree? 4. content — did the actor initialize, register collision/rendering/navigation, and survive replication rules? 5. representation — is hlod replacing the source as intended? 6. budget — did i/o, decompression, memory, game-thread work, or rendering miss the deadline? useful runtime commands text wp.runtime.toggledrawruntimehash2d wp.runtime.toggledrawruntimehash3d wp.runtime.toggledrawdatalayers wp.dumpdatalayers wp.runtime.hlod 0 use stat unit, stat streaming, memory tools, insights, and platform i/o telemetry alongside cell visualization. a colored cell does not prove the content was ready without a hitch. world partition insights in 5.8 ue 5.8 introduces per-cell streaming analysis and session playback in unreal insights. epic documents enabling worldstreaminginsights in unreal insights configuration and tracing with: text -trace=worldstreaming optional trace channels include: text +worldstreamingpriority +worldstreamingdependencies treat the toolchain as version-specific. confirm configuration in the installed 5.8 build and record trace overhead before using production timing as a baseline. repro capture record: - engine revision and build configuration; - map, start transform, route, speed, and source configuration; - cell size/loading range and data layer states; - cold versus warm cache; - platform/storage/memory state; - trace, log, hitch timestamp, and visible symptom. builder commandlet form text unrealeditor.exe <project.uproject> <map> -run=worldpartitionbuildercommandlet -builder=<builderclass> -unattended current documented builders include: - worldpartitionhlodsbuilder - worldpartitionminimapbuilder - worldpartitionrenameduplicatebuilder - worldpartitionresaveactorsbuilder - worldpartitionfoliagebuilder - worldpartitionnavigationdatabuilder - worldpartitionsmartobjectcollectionbuilder - pcgworldpartitionbuilder - worldpartitionruntimevirtualtexturebuilder some builders require rendering; add -allowcommandletrendering only when required. choose source-control behavior explicitly (-sccprovider=... or the documented no-source-control path) and never automate submission without a reviewed change set. builder acceptance - command exits successfully with no ignored errors; - expected assets changed and unrelated assets did not; - a second identical run is stable or differences are explained; - source-control status is reviewable; - the map cooks and loads; - target traversal, data layer transitions, hlod, navigation, and pcg behave as expected. world partition hlod world partition hlod purpose and boundary hlod replaces distant content from unloaded cells with proxy representation and can reduce draw calls. it is for visual continuity and rendering cost—not authoritative interaction, collision, navigation, destruction state, or ai. layer type selector | hlod layer type | use when | primary tradeoff | |---|---|---| | instancing | source actors share a mesh/material pattern | low build complexity; less consolidation than merging | | merged mesh | a combined proxy can preserve adequate silhouette/material appearance | fewer components/draw calls; asset and texture cost can grow | | simplified mesh | distant geometry can tolerate reduction | best geometric reduction; longer builds and more visual risk | authoring workflow 1. identify distant content that must remain visually present after its source cell unloads. 2. ensure source actors are static and eligible to generate hlod. 3. create focused hlod layer assets by content behavior, not one universal layer. 4. choose layer type and mesh/material settings from expected viewing distance and silhouette importance. 5. set hlod layer cell size, loading range, optional parent layer, and always loaded only when justified. 6. assign actors or defaults deliberately. 7. build hlod setup, then proxies. 8. compare source and proxy at the intended transition distance and in motion. 9. profile draw calls, gpu time, memory, disk size, and transition hitches. parameter effects - larger hlod cells merge more source content into fewer, heavier proxies. - smaller hlod cells improve granularity but increase actor/cell counts and transitions. - larger hlod loading range preserves distant representation longer and raises residency. - parent hlod layers create additional distance tiers; each tier adds build, storage, and validation cost. - always loaded removes transition risk for that hlod layer but creates permanent residency. ue 5.8 workflow additions ue 5.8 adds region- and selection-scoped hlod builds, comparison against source content, a perceptual-difference option for deciding whether an update is needed, and standalone hlod improvements. use scoped builds to shorten iteration, then run the complete reproducible build before release. features explicitly marked experimental in the release notes—such as externalizing hlod assets—must remain opt-in and receive cook/source-control/rollback validation. commandlet general form: text unrealeditor.exe <project.uproject> <map> -run=worldpartitionbuildercommandlet -builder=worldpartitionhlodsbuilder -allowcommandletrendering -unattended useful builder switches include: - -setuphlods - -buildhlods - -deletehlods add project source-control flags deliberately; do not let an unattended build unexpectedly check out or submit files. validation failures - proxy pops or changes silhouette: adjust transition distance, simplification, materials, or layer grouping. - proxy shows stale state: rebuild after source changes and verify data layer/hlod assignment. - gameplay disappears with source cells: gameplay was incorrectly assumed to live in the hlod. - memory rises after hlod: inspect proxy textures/materials, overlapping tiers, always-loaded settings, and source residency. - build churn is excessive: use 5.8 scoped iteration, stable grouping, and the perceptual-difference heuristic; still require a clean final build. for rapid visual diagnosis, toggle hlods with: text wp.runtime.hlod 0 restore the default after the comparison. level instances, packed level blueprints, and ofpa level instances, packed level blueprints, and ofpa choose the reusable unit level instance use for a repeated point of interest, building with gameplay actors, or standalone setup that benefits from in-context sublevel editing. saving edits to the source propagates to every instance. packed level blueprint use for a repeated, dense, static-mesh visual assembly. packing replaces supported source meshes with an optimized actor representation. arbitrary components are unsupported and can produce an incomplete packed actor; use a regular level instance when behavior or component support is uncertain. runtime behavior in a world partition main world embedded mode - default and recommended for ofpa level instances. - at runtime, the level instance wrapper is discarded and its external actors are added to the parent world partition grid. - the level instance is primarily an editor authoring construct. - non-ofpa actors such as the instance's aworldsettings do not survive embedding. do not place runtime logic there. level streaming mode - used when the instance cannot be embedded, including non-ofpa content. - loading the owning world partition cell streams the associated level. - each streamed level adds runtime overhead. avoid high densities of level instances that require this mode. outside a world partition main world, level instances do not gain automatic world partition streaming management. data layers actors inside an instance inherit the data layer assigned to the level instance actor by default and may also have additional internal data layers. use this for cohesive variants, but verify runtime state and hlod behavior in every placed copy. ofpa boundary one file per actor stores actor edits in external files so team members can change different actors without checking out the entire level. world partition enables ofpa by default. ofpa is an editor/source-control workflow. during cooking, actor content is embedded into the appropriate cooked level packages. never write runtime code that depends on external actor file layout. ofpa does not prevent: - two people changing the same actor; - logical conflicts between related actors; - rename/move/delete coordination failures; - broad churn from derived hlod or generated content. creation checklist 1. select the cohesive actors. 2. choose create level instance for general assemblies or create packed level actor for supported static visual assemblies. 3. enable external actors when the instance should use ofpa. 4. choose a stable pivot meaningful for placement and snapping. 5. save under the project's naming and ownership conventions. 6. test propagation to several instances. 7. verify embedded versus level streaming behavior in a cooked build. 8. verify internal gameplay actors, data layers, hlods, collision, navigation, and references. breaking a level instance replaces it with its original actors and cannot be undone through the level instance operation. commit/save before destructive restructuring. production patterns and test gates production patterns and test gates pattern: open-world traversal - one default runtime grid until evidence requires another. - player source plus a velocity/look-ahead strategy for fast travel. - spatial environment actors; true global systems outside placed-world lifetime. - hlod for distant static silhouette. - runtime data layers only for cohesive world phases. - cooked traversal benchmark covering slow walk, sprint, fastest vehicle, abrupt turn, and return path. pattern: seamless teleport or fast travel - destination streaming source enabled before travel. - loading/transition presentation begins. - wait for streaming completion and project-specific gameplay readiness. - server performs authoritative move. - client camera/input resumes after possession and local presentation are ready. - temporary source retires after the normal source owns the area. - timeout returns to a known safe location or explicit failure ui. pattern: stateful location - durable quest/state data lives in save/gameplay state. - server maps that truth to runtime data layer state. - loaded prewarms the destination; activated reveals the chosen phase. - streamed interactables reconstruct local presentation from durable ids/state. - late join and load-game tests confirm the same phase. pattern: repeated point of interest - level instance for mixed gameplay/content assembly. - packed level blueprint only when the assembly is supported static visual content. - ofpa for collaborative editing. - instance-level data layer supplies the broad phase; internal layers only for truly reusable variants. - validate every instance transform, hlod, navigation, and references. pattern: persistent manager use a framework class or subsystem appropriate to its lifetime. a placed always-loaded actor is acceptable only when world placement is semantically required and its lifetime/cost are explicit. required test matrix | axis | minimum cases | |---|---| | build | pie, standalone, cooked development, shipping-equivalent target | | cache | cold start and warm repeat | | motion | slow, fastest sustained, burst/teleport, sudden reversal | | network | listen/dedicated as applicable, late join, reconnect, packet impairment | | state | each runtime data layer transition and save/load reconstruction | | memory | baseline, worst vista, repeated round trip, long soak | | hlod | source/proxy comparison, transition in motion, rebuild after source edit | | failure | missing/late cell, timeout, cancelled travel, invalid reference | acceptance gates - no player reaches absent collision or interactive state. - no unbounded memory rise after repeated traversal. - cell/hlod transitions meet the project's visible-pop and hitch budgets. - server and clients agree on authoritative data layer/gameplay state. - a clean builder run is reproducible from source control. - packaged behavior matches editor intent. - debug overrides are removed and experimental dependencies are documented. pcg and world partition integration pcg and world partition integration use this with ../../unreal-pcg/skill.md. world partition owns spatial residency; pcg owns procedural generation. keep their responsibilities explicit. partitioned generation a partitioned pcg component can generate through pcg partition actors aligned to generation grids. hierarchical generation can use multiple grid sizes in one graph. runtime generation schedules work around configured generation sources. do not assume the pcg grid and world partition runtime grid are the same thing. name which grid a setting belongs to. integration workflow 1. decide whether output is authored/baked, generated on demand in editor, or generated at runtime. 2. decide whether the pcg component is partitioned and whether hierarchical generation is needed. 3. keep deterministic seeds and stable source data where reproducibility matters. 4. assign intended data layers and hlod layers at the source/pcg settings level. 5. confirm generated actors inherit the intended data layer and hlod assignments. 6. align generation/loading lead distance with player speed and worst generation latency. 7. define cleanup when a source cell unloads or runtime generation is cancelled. 8. re-run generation after relevant source or partition changes and validate in a cooked build. ownership rules - durable gameplay state must not exist only in a generated actor that can be unloaded or regenerated. - generated collision and navigation must be ready before gameplay relies on them. - server-authoritative gameplay generation needs a replication/state plan; do not assume independently seeded clients produce authoritative equivalence. - data layer state should express world phase; pcg parameters should express generation inputs. do not create two competing state machines. - hlod represents distant generated visuals only after the output is eligible, assigned, and built appropriately. commandlet for offline or automated generation, use the pcgworldpartitionbuilder through the world partition builder commandlet. record the map, generation filters, source-control mode, engine version, and output in build logs. do not treat successful commandlet exit as sufficient. check generated actor counts/bounds, warnings, determinism, data layers, hlod inputs, and cooked runtime behavior. failure patterns - duplicate output: generation ownership or cleanup overlaps across components/cells. - seams at cell boundaries: sampling lacks neighbor context or grid sizes/seed domains disagree. - generated content never unloads: output ownership, runtime mode, or cleanup is wrong. - content visible in the wrong phase: generated actor data layer assignment was not inherited as assumed. - hlod excludes generated content: output is not eligible/assigned or hlod was not rebuilt after generation. - arrival hitch: generation and cell streaming compete at the point of entry; preload earlier, reduce work, cache where valid, or bake stable content. primary sources and maturity notes primary sources and maturity notes checked against unreal engine 5.8 documentation on 2026-07-19. core documentation - world partition — system overview, enabling/conversion, actor settings, streaming sources, runtime grids, debug commands. - world partition data layers — assets/instances, editor vs runtime layers, runtime states, network authority, diagnostics. - world partition hlod — hlod layer types, assignment, settings, building, commandlet. - one file per actor — editor/source-control workflow and cooked-package boundary. - level instancing — level instances, packed level blueprints, embedded and level streaming runtime modes, data layers. - apackedlevelactor — packing boundary and fallback to a regular level instance when components are unsupported. - world partition builder commandlet reference — builder classes, forms, and source-control/rendering options. - using pcg with world partition — partitioned/hierarchical pcg interaction, data layer and hlod assignment. - uworldpartitionsubsystem::isstreamingcompleted — readiness api used in source-gated travel. - ue 5.8 release notes — world partition insights, hlod workflow changes, fixes, and experimental features. maturity and interpretation - world partition, data layers, hlod, ofpa, level instances, and builder commandlets are established ue5 workflows. - world partition insights is new in 5.8; verify its configuration and capture overhead in the installed engine. - release-note items marked experimental, including fast geometry-related work and optional external hlod asset workflows, are not production defaults. - uworldpartitionruntimehashset exists in the 5.8 api, but this skill does not prescribe it without current project-specific documentation and profiling. the documented default 2d runtime spatial hash remains the baseline. - current epic pages occasionally preserve command spelling quirks. check console autocomplete/help in the exact engine build before scripting a command. source-use rule prefer the 5.8 page or engine source over remembered ue 5.0–5.7 behavior. if a property, command, or ui path is absent in the installed build, report the discrepancy and inspect the engine version/plugin/configuration instead of inventing a replacement. streaming sources, runtime grids, and teleports streaming sources, runtime grids, and teleports source model playercontrollers can act as streaming sources. use a worldpartitionstreamingsourcecomponent for vehicles, cameras, scripted destinations, or temporary preloading. important source properties include: - target state: request loaded or activated; when sources overlap, the highest requested state wins. - priority: resolves competition between sources; higher priority wins. - shapes: constrain the affected region instead of always using an unconstrained radius. - target grid and target hlod layer: narrow a source only when a specific design requires it. avoid leaving speculative sources active. each one expands residency and i/o demand. loading-range model use a measured lower bound: text minimum lead distance = maximum approach speed × worst observed ready latency + camera/interaction look-ahead + safety margin ready latency includes storage i/o, decompression, object creation, registration, render-resource readiness, and gameplay initialization on the target build. - increasing loading range raises lead time but increases resident memory and concurrent work. - decreasing it reduces residency but increases pop-in and arrival hitch risk. - smaller cells increase cell count and management overhead while improving spatial granularity. - larger cells reduce cell count but make each transition heavier and coarser. do not tune cell size and range simultaneously. change one variable, record a repeatable traversal, and compare. runtime grid policy start with the default 2d runtime spatial hash and one grid. more than one runtime grid can hurt performance and makes source behavior harder to reason about. add a grid only when profiling shows a distinct content class needs a materially different cell size or loading range. relevant grid settings: - cell size - loading range - block on slow streaming - priority blocking can protect world correctness but visibly stalls play. decide explicitly which transitions may block and provide ui or transition design when needed. safe teleport pattern 1. place or move a temporary streaming-source component at the destination. 2. enable the source with an appropriate target state and shape. 3. poll uworldpartitionsubsystem::isstreamingcompleted for that source/provider. 4. on success, teleport the pawn and camera. 5. retain the source until the normal player source owns the destination cells. 6. disable or remove the temporary source. 7. on timeout, cancel, present a loading transition, or move to a safe fallback. never silently teleport into missing collision. high-speed traversal pattern - lead the source in the velocity/look direction rather than merely inflating a symmetric range. - test sudden turns, braking, respawn, spectating, network correction, and possession changes. - keep gameplay-critical collision and navigation readiness in the acceptance check, not just visual presence. debug commands text wp.runtime.toggledrawruntimehash2d wp.runtime.toggledrawruntimehash3d wp.runtime.showruntimespatialhashgridlevel wp.runtime.showruntimespatialhashgridlevelcount wp.runtime.showruntimespatialhashgridindex wp.runtime.overrideruntimespatialhashloadingrange wp.runtime.maxloadinglevelstreamingcells use overrides only for diagnosis. return to authored settings before recording final performance. system selector and conversion system selector and conversion choose the smallest system that meets the need | situation | default choice | reason | |---|---|---| | continuous traversable world with bounded residency | world partition, streaming enabled | automatic source-distance streaming and one persistent authoring world | | small map that fits budget | world partition, streaming disabled, or a normal level | avoid runtime streaming complexity while retaining the desired authoring workflow | | repeated point of interest or gameplay assembly | level instance | reusable sublevel edited in context | | repeated static architectural/mesh assembly | packed level blueprint | packs supported static content into an optimized actor | | existing ue5 world partition project | extend current model | avoid a second overlapping streaming authority | | legacy/discrete sublevel architecture | existing level streaming until migration is justified | conversion risk may exceed its value | world partition is epic's recommended ue5 large-world approach. it is not proof that every map needs cell streaming. conversion safety workflow 1. work on a source-controlled branch or verified backup. 2. inventory level blueprints, streaming volumes, scripted sublevel transitions, world settings, always-loaded managers, actor references, foliage, navigation, and hlods. 3. resave the source level and correct unstable actor guid warnings before conversion. 4. run the conversion commandlet with -reportonly first. 5. review actors that cannot be externalized, reference clusters, sublevel handling, and generated configuration. 6. convert a copy or use -conversionsuffix until the result passes validation. 7. rebuild derived data: hlod, navigation, foliage, pcg, minimap, or rvt as applicable. 8. compare gameplay and memory in a cooked build; keep the old map until parity is demonstrated. general form: text unrealeditor.exe <project.uproject> <mapname> -run=worldpartitionconvertcommandlet -reportonly useful flags include: - -conversionsuffix: preserve the source and write a converted map with a suffix. - -reportonly: analyze without converting. - -generateini: emit conversion settings that can be reviewed and reused. - -onlymergesublevels: merge sublevels without otherwise converting the result to world partition. avoid -skipstableguidvalidation as a routine fix. stable guids are required for repeatable conversion; resave and repair the map instead. reject the conversion when - success depends on level blueprint state or streaming callbacks not yet replaced; - non-ofpa actors inside level instances must exist at runtime but the design assumes embedded mode; - reference bundles make most of the world resident; - target-device memory or traversal hitching regresses with no credible mitigation; - the team cannot rebuild and validate derived content reproducibly. version-sensitive note ue 5.8 adds world partition streaming analysis in unreal insights and improves scoped hlod building. treat these as new workflow capabilities, not permission to skip before/after performance captures.

# Actor placement, references, and lifetime

## Classify every load-bearing actor

Record five decisions:

1. **Spatial lifetime** — source-distance loaded or always resident.
2. **World state** — no Data Layer, Editor Data Layer, or Runtime Data Layer and initial state.
3. **Runtime grid** — normally `None` so the partition system selects the default.
4. **Distant representation** — HLOD layer or intentionally none.
5. **Dependencies** — hard actor references, soft asset references, subsystem lookup, or stable identifier.

## `Is Spatially Loaded`

- Enabled: the actor loads when it is in range of a streaming source and is not excluded by a disabled Runtime Data Layer.
- Disabled: the actor is not distance-streamed; Data Layer state can still control it.

Use non-spatial loading for truly global world actors whose lifetime is intentional and cheap. Do not use it for distant content, ordinary interactables, or as a blanket cure for missing references.

## Reference rule

A hard reference between spatial actors can make them part of the same streaming dependency bundle. A reference spanning distant cells may therefore pull content into memory earlier or keep it resident longer than expected.

Prefer, according to the requirement:

- a subsystem or manager that resolves a nearby actor at use time;
- an interface plus overlap/spatial query;
- a soft asset reference for asynchronously loaded assets;
- a stable gameplay identifier resolved through a registry;
- an event/message carrying data rather than a stored pointer.

Do not replace a required same-lifetime relationship with a soft reference merely to silence a warning. If two actors must exist together, co-location and bundling may be correct; document it.

## Ownership patterns

### Global rule or service

Put state in GameMode/GameState, GameInstance, an appropriate subsystem, or a replicated service—not in a random placed actor that happens to remain loaded.

### Spatial interactable

Keep durable state outside the streamed actor or reconstruct it from a stable ID when the cell loads. Treat actor unload as normal lifecycle, not destruction of game truth.

### Cross-cell mission dependency

Store mission state centrally. Resolve each endpoint when its cell is present and tolerate absence. Avoid direct endpoint-to-endpoint hard references across the world.

### Attached actors

Keep parent and child streaming policies compatible. Test attachment and absolute-transform behavior through unload/reload; editor visibility alone is insufficient.

## Validation

- Use the reference viewer and Size Map for suspicious asset chains.
- Inspect streaming-generation warnings and unexpected actor bundles.
- Traverse with debug cell visualization enabled and watch whether distant dependencies load.
- Unload/reload the cell repeatedly; confirm durable gameplay state survives.
- Test server and client separately because authoritative and client-visible actor sets can differ.

Data Layers

# Data Layers

## Data model

- A **Data Layer Asset** is a project asset that declares an Editor or Runtime layer.
- A **Data Layer Instance** is the world-specific instance and assignment surface.
- **Editor Data Layers** organize authoring views and alternate editing sets; they do not define a runtime state machine.
- **Runtime Data Layers** can be changed at runtime and participate in streaming.

Runtime states:

- **Unloaded**: content is not resident.
- **Loaded**: content is resident but not visible/activated.
- **Activated**: content is resident and visible/active.

Treat `Loaded` as a preload state and `Activated` as presentation/gameplay availability. Verify component-specific behavior instead of assuming visibility is the only activation consequence.

## Network authority

In client/server play, the server changes authoritative Runtime Data Layer state. Clients should observe the replicated result. Do not let each client independently activate a layer that changes collision, interaction, or world truth.

Cosmetic client-only variants should use an explicitly client-owned presentation mechanism unless their Data Layer behavior and replication have been proven for the target design.

## Good uses

- preloading a boss arena before revealing it;
- switching repaired/destroyed or seasonal world variants;
- phasing a location by authoritative quest state;
- separating alternate set dressing while preserving shared terrain;
- grouping editor-only disciplines or review passes.

## Poor uses

- replacing a local component visibility flag for one tiny object;
- encoding every quest boolean as a separate layer;
- assigning widely scattered actors to many Runtime Data Layers without measuring streaming cost;
- hiding authoritative actors only on a client;
- storing durable quest truth in the layer state itself.

## State-transition pattern

1. Author a Runtime Data Layer Asset and world instance.
2. Assign only the content that shares the transition and lifetime.
3. Set and document the initial runtime state.
4. On the server, request `Loaded` early enough to cover worst load latency.
5. Wait for readiness when the transition requires collision or interaction.
6. Request `Activated` at the reveal/phase boundary.
7. Persist the underlying gameplay state separately so load/save can reconstruct the layer state.
8. Test late join, reconnect, respawn, and server travel.

## Performance caution

Actors spread over large areas or repeated across many Runtime Data Layers can degrade streaming performance by creating broad or fragmented dependencies. Use cohesive spatial/state groups and inspect the resulting cells.

## Debug commands

```text
wp.DumpDatalayers
wp.Runtime.SetDataLayerRuntimeState
wp.Runtime.ToggleDataLayerActivation
wp.Runtime.ToggleDrawDataLayers
```

Epic's current documentation also lists `wp.Runtime.DebugFilerByDatalayer` with that spelling. Confirm the available console command in the running 5.8 build before automating it.

Debugging and builder commandlets

# Debugging and builder commandlets

## Diagnose in layers

1. **Source** — is an enabled source requesting the expected location, grid, shape, target state, and priority?
2. **Cell** — is the expected runtime cell generated, requested, loaded, and activated?
3. **Policy** — do `Is Spatially Loaded`, Data Layer state, grid assignment, and references agree?
4. **Content** — did the actor initialize, register collision/rendering/navigation, and survive replication rules?
5. **Representation** — is HLOD replacing the source as intended?
6. **Budget** — did I/O, decompression, memory, game-thread work, or rendering miss the deadline?

## Useful runtime commands

```text
wp.Runtime.ToggleDrawRuntimeHash2D
wp.Runtime.ToggleDrawRuntimeHash3D
wp.Runtime.ToggleDrawDataLayers
wp.DumpDatalayers
wp.Runtime.HLOD 0
```

Use `stat unit`, `stat streaming`, memory tools, Insights, and platform I/O telemetry alongside cell visualization. A colored cell does not prove the content was ready without a hitch.

## World Partition Insights in 5.8

UE 5.8 introduces per-cell streaming analysis and session playback in Unreal Insights. Epic documents enabling `WorldStreamingInsights` in Unreal Insights configuration and tracing with:

```text
-trace=WorldStreaming
```

Optional trace channels include:

```text
+WorldStreamingPriority
+WorldStreamingDependencies
```

Treat the toolchain as version-specific. Confirm configuration in the installed 5.8 build and record trace overhead before using production timing as a baseline.

## Repro capture

Record:

- engine revision and build configuration;
- map, start transform, route, speed, and source configuration;
- cell size/loading range and Data Layer states;
- cold versus warm cache;
- platform/storage/memory state;
- trace, log, hitch timestamp, and visible symptom.

## Builder commandlet form

```text
UnrealEditor.exe <Project.uproject> <Map> -run=WorldPartitionBuilderCommandlet -Builder=<BuilderClass> -Unattended
```

Current documented builders include:

- `WorldPartitionHLODsBuilder`
- `WorldPartitionMiniMapBuilder`
- `WorldPartitionRenameDuplicateBuilder`
- `WorldPartitionResaveActorsBuilder`
- `WorldPartitionFoliageBuilder`
- `WorldPartitionNavigationDataBuilder`
- `WorldPartitionSmartObjectCollectionBuilder`
- `PCGWorldPartitionBuilder`
- `WorldPartitionRuntimeVirtualTextureBuilder`

Some builders require rendering; add `-AllowCommandletRendering` only when required. Choose source-control behavior explicitly (`-SCCProvider=...` or the documented no-source-control path) and never automate submission without a reviewed change set.

## Builder acceptance

- command exits successfully with no ignored errors;
- expected assets changed and unrelated assets did not;
- a second identical run is stable or differences are explained;
- source-control status is reviewable;
- the map cooks and loads;
- target traversal, Data Layer transitions, HLOD, navigation, and PCG behave as expected.

World Partition HLOD

# World Partition HLOD

## Purpose and boundary

HLOD replaces distant content from unloaded cells with proxy representation and can reduce draw calls. It is for visual continuity and rendering cost—not authoritative interaction, collision, navigation, destruction state, or AI.

## Layer type selector

| HLOD layer type | Use when | Primary tradeoff |
|---|---|---|
| Instancing | Source actors share a mesh/material pattern | Low build complexity; less consolidation than merging |
| Merged Mesh | A combined proxy can preserve adequate silhouette/material appearance | Fewer components/draw calls; asset and texture cost can grow |
| Simplified Mesh | Distant geometry can tolerate reduction | Best geometric reduction; longer builds and more visual risk |

## Authoring workflow

1. Identify distant content that must remain visually present after its source cell unloads.
2. Ensure source actors are Static and eligible to generate HLOD.
3. Create focused HLOD Layer assets by content behavior, not one universal layer.
4. Choose layer type and mesh/material settings from expected viewing distance and silhouette importance.
5. Set HLOD layer `Cell Size`, `Loading Range`, optional parent layer, and `Always Loaded` only when justified.
6. Assign actors or defaults deliberately.
7. Build HLOD setup, then proxies.
8. Compare source and proxy at the intended transition distance and in motion.
9. Profile draw calls, GPU time, memory, disk size, and transition hitches.

## Parameter effects

- Larger HLOD cells merge more source content into fewer, heavier proxies.
- Smaller HLOD cells improve granularity but increase actor/cell counts and transitions.
- Larger HLOD loading range preserves distant representation longer and raises residency.
- Parent HLOD layers create additional distance tiers; each tier adds build, storage, and validation cost.
- `Always Loaded` removes transition risk for that HLOD layer but creates permanent residency.

## UE 5.8 workflow additions

UE 5.8 adds region- and selection-scoped HLOD builds, comparison against source content, a perceptual-difference option for deciding whether an update is needed, and standalone HLOD improvements. Use scoped builds to shorten iteration, then run the complete reproducible build before release.

Features explicitly marked Experimental in the release notes—such as externalizing HLOD assets—must remain opt-in and receive cook/source-control/rollback validation.

## Commandlet

General form:

```text
UnrealEditor.exe <Project.uproject> <Map> -run=WorldPartitionBuilderCommandlet -Builder=WorldPartitionHLODsBuilder -AllowCommandletRendering -Unattended
```

Useful builder switches include:

- `-SetupHLODs`
- `-BuildHLODs`
- `-DeleteHLODs`

Add project source-control flags deliberately; do not let an unattended build unexpectedly check out or submit files.

## Validation failures

- **Proxy pops or changes silhouette**: adjust transition distance, simplification, materials, or layer grouping.
- **Proxy shows stale state**: rebuild after source changes and verify Data Layer/HLOD assignment.
- **Gameplay disappears with source cells**: gameplay was incorrectly assumed to live in the HLOD.
- **Memory rises after HLOD**: inspect proxy textures/materials, overlapping tiers, always-loaded settings, and source residency.
- **Build churn is excessive**: use 5.8 scoped iteration, stable grouping, and the perceptual-difference heuristic; still require a clean final build.

For rapid visual diagnosis, toggle HLODs with:

```text
wp.Runtime.HLOD 0
```

Restore the default after the comparison.

# Level Instances, Packed Level Blueprints, and OFPA

## Choose the reusable unit

### Level Instance

Use for a repeated point of interest, building with gameplay actors, or standalone setup that benefits from in-context sublevel editing. Saving edits to the source propagates to every instance.

### Packed Level Blueprint

Use for a repeated, dense, static-mesh visual assembly. Packing replaces supported source meshes with an optimized actor representation. Arbitrary components are unsupported and can produce an incomplete packed actor; use a regular Level Instance when behavior or component support is uncertain.

## Runtime behavior in a World Partition main world

### Embedded Mode

- Default and recommended for OFPA Level Instances.
- At runtime, the Level Instance wrapper is discarded and its external actors are added to the parent World Partition grid.
- The Level Instance is primarily an editor authoring construct.
- Non-OFPA actors such as the instance's `AWorldSettings` do not survive embedding. Do not place runtime logic there.

### Level Streaming Mode

- Used when the instance cannot be embedded, including non-OFPA content.
- Loading the owning World Partition cell streams the associated Level.
- Each streamed Level adds runtime overhead. Avoid high densities of Level Instances that require this mode.

Outside a World Partition main world, Level Instances do not gain automatic World Partition streaming management.

## Data Layers

Actors inside an instance inherit the Data Layer assigned to the Level Instance Actor by default and may also have additional internal Data Layers. Use this for cohesive variants, but verify runtime state and HLOD behavior in every placed copy.

## OFPA boundary

One File Per Actor stores actor edits in external files so team members can change different actors without checking out the entire level. World Partition enables OFPA by default.

OFPA is an editor/source-control workflow. During cooking, actor content is embedded into the appropriate cooked level packages. Never write runtime code that depends on external actor file layout.

OFPA does not prevent:

- two people changing the same actor;
- logical conflicts between related actors;
- rename/move/delete coordination failures;
- broad churn from derived HLOD or generated content.

## Creation checklist

1. Select the cohesive actors.
2. Choose **Create Level Instance** for general assemblies or **Create Packed Level Actor** for supported static visual assemblies.
3. Enable External Actors when the instance should use OFPA.
4. Choose a stable pivot meaningful for placement and snapping.
5. Save under the project's naming and ownership conventions.
6. Test propagation to several instances.
7. Verify Embedded versus Level Streaming behavior in a cooked build.
8. Verify internal gameplay actors, Data Layers, HLODs, collision, navigation, and references.

Breaking a Level Instance replaces it with its original actors and cannot be undone through the Level Instance operation. Commit/save before destructive restructuring.

Production patterns and test gates

# Production patterns and test gates

## Pattern: open-world traversal

- One default runtime grid until evidence requires another.
- Player source plus a velocity/look-ahead strategy for fast travel.
- Spatial environment actors; true global systems outside placed-world lifetime.
- HLOD for distant static silhouette.
- Runtime Data Layers only for cohesive world phases.
- Cooked traversal benchmark covering slow walk, sprint, fastest vehicle, abrupt turn, and return path.

## Pattern: seamless teleport or fast travel

- Destination streaming source enabled before travel.
- Loading/transition presentation begins.
- Wait for streaming completion and project-specific gameplay readiness.
- Server performs authoritative move.
- Client camera/input resumes after possession and local presentation are ready.
- Temporary source retires after the normal source owns the area.
- Timeout returns to a known safe location or explicit failure UI.

## Pattern: stateful location

- Durable quest/state data lives in save/gameplay state.
- Server maps that truth to Runtime Data Layer state.
- `Loaded` prewarms the destination; `Activated` reveals the chosen phase.
- Streamed interactables reconstruct local presentation from durable IDs/state.
- Late join and load-game tests confirm the same phase.

## Pattern: repeated point of interest

- Level Instance for mixed gameplay/content assembly.
- Packed Level Blueprint only when the assembly is supported static visual content.
- OFPA for collaborative editing.
- Instance-level Data Layer supplies the broad phase; internal layers only for truly reusable variants.
- Validate every instance transform, HLOD, navigation, and references.

## Pattern: persistent manager

Use a framework class or subsystem appropriate to its lifetime. A placed always-loaded actor is acceptable only when world placement is semantically required and its lifetime/cost are explicit.

## Required test matrix

| Axis | Minimum cases |
|---|---|
| Build | PIE, standalone, cooked Development, shipping-equivalent target |
| Cache | cold start and warm repeat |
| Motion | slow, fastest sustained, burst/teleport, sudden reversal |
| Network | listen/dedicated as applicable, late join, reconnect, packet impairment |
| State | each Runtime Data Layer transition and save/load reconstruction |
| Memory | baseline, worst vista, repeated round trip, long soak |
| HLOD | source/proxy comparison, transition in motion, rebuild after source edit |
| Failure | missing/late cell, timeout, cancelled travel, invalid reference |

## Acceptance gates

- No player reaches absent collision or interactive state.
- No unbounded memory rise after repeated traversal.
- Cell/HLOD transitions meet the project's visible-pop and hitch budgets.
- Server and clients agree on authoritative Data Layer/gameplay state.
- A clean builder run is reproducible from source control.
- Packaged behavior matches editor intent.
- Debug overrides are removed and experimental dependencies are documented.

PCG and World Partition integration

# PCG and World Partition integration

Use this with [`../../unreal-pcg/SKILL.md`](../../unreal-pcg/SKILL.md). World Partition owns spatial residency; PCG owns procedural generation. Keep their responsibilities explicit.

## Partitioned generation

A partitioned PCG component can generate through PCG Partition Actors aligned to generation grids. Hierarchical generation can use multiple grid sizes in one graph. Runtime generation schedules work around configured generation sources.

Do not assume the PCG grid and World Partition runtime grid are the same thing. Name which grid a setting belongs to.

## Integration workflow

1. Decide whether output is authored/baked, generated on demand in editor, or generated at runtime.
2. Decide whether the PCG component is partitioned and whether hierarchical generation is needed.
3. Keep deterministic seeds and stable source data where reproducibility matters.
4. Assign intended Data Layers and HLOD layers at the source/PCG settings level.
5. Confirm generated actors inherit the intended Data Layer and HLOD assignments.
6. Align generation/loading lead distance with player speed and worst generation latency.
7. Define cleanup when a source cell unloads or runtime generation is cancelled.
8. Re-run generation after relevant source or partition changes and validate in a cooked build.

## Ownership rules

- Durable gameplay state must not exist only in a generated actor that can be unloaded or regenerated.
- Generated collision and navigation must be ready before gameplay relies on them.
- Server-authoritative gameplay generation needs a replication/state plan; do not assume independently seeded clients produce authoritative equivalence.
- Data Layer state should express world phase; PCG parameters should express generation inputs. Do not create two competing state machines.
- HLOD represents distant generated visuals only after the output is eligible, assigned, and built appropriately.

## Commandlet

For offline or automated generation, use the `PCGWorldPartitionBuilder` through the World Partition Builder Commandlet. Record the map, generation filters, source-control mode, engine version, and output in build logs.

Do not treat successful commandlet exit as sufficient. Check generated actor counts/bounds, warnings, determinism, Data Layers, HLOD inputs, and cooked runtime behavior.

## Failure patterns

- **Duplicate output**: generation ownership or cleanup overlaps across components/cells.
- **Seams at cell boundaries**: sampling lacks neighbor context or grid sizes/seed domains disagree.
- **Generated content never unloads**: output ownership, runtime mode, or cleanup is wrong.
- **Content visible in the wrong phase**: generated actor Data Layer assignment was not inherited as assumed.
- **HLOD excludes generated content**: output is not eligible/assigned or HLOD was not rebuilt after generation.
- **Arrival hitch**: generation and cell streaming compete at the point of entry; preload earlier, reduce work, cache where valid, or bake stable content.

Use this with [`../../unreal-pcg/SKILL.md`](/unreal/unreal-pcg/). World Partition owns spatial residency; PCG owns procedural generation. Keep their responsibilities explicit.

## Partitioned generation

A partitioned PCG component can generate through PCG Partition Actors aligned to generation grids. Hierarchical generation can use multiple grid sizes in one graph. Runtime generation schedules work around configured generation sources.

Do not assume the PCG grid and World Partition runtime grid are the same thing. Name which grid a setting belongs to.

## Integration workflow

1. Decide whether output is authored/baked, generated on demand in editor, or generated at runtime.
2. Decide whether the PCG component is partitioned and whether hierarchical generation is needed.
3. Keep deterministic seeds and stable source data where reproducibility matters.
4. Assign intended Data Layers and HLOD layers at the source/PCG settings level.
5. Confirm generated actors inherit the intended Data Layer and HLOD assignments.
6. Align generation/loading lead distance with player speed and worst generation latency.
7. Define cleanup when a source cell unloads or runtime generation is cancelled.
8. Re-run generation after relevant source or partition changes and validate in a cooked build.

## Ownership rules

- Durable gameplay state must not exist only in a generated actor that can be unloaded or regenerated.
- Generated collision and navigation must be ready before gameplay relies on them.
- Server-authoritative gameplay generation needs a replication/state plan; do not assume independently seeded clients produce authoritative equivalence.
- Data Layer state should express world phase; PCG parameters should express generation inputs. Do not create two competing state machines.
- HLOD represents distant generated visuals only after the output is eligible, assigned, and built appropriately.

## Commandlet

For offline or automated generation, use the `PCGWorldPartitionBuilder` through the World Partition Builder Commandlet. Record the map, generation filters, source-control mode, engine version, and output in build logs.

Do not treat successful commandlet exit as sufficient. Check generated actor counts/bounds, warnings, determinism, Data Layers, HLOD inputs, and cooked runtime behavior.

## Failure patterns

- **Duplicate output**: generation ownership or cleanup overlaps across components/cells.
- **Seams at cell boundaries**: sampling lacks neighbor context or grid sizes/seed domains disagree.
- **Generated content never unloads**: output ownership, runtime mode, or cleanup is wrong.
- **Content visible in the wrong phase**: generated actor Data Layer assignment was not inherited as assumed.
- **HLOD excludes generated content**: output is not eligible/assigned or HLOD was not rebuilt after generation.
- **Arrival hitch**: generation and cell streaming compete at the point of entry; preload earlier, reduce work, cache where valid, or bake stable content.

Primary sources and maturity notes

# Primary sources and maturity notes

Checked against Unreal Engine 5.8 documentation on 2026-07-19.

## Core documentation

- [World Partition](https://dev.epicgames.com/documentation/en-us/unreal-engine/world-partition-in-unreal-engine) — system overview, enabling/conversion, actor settings, streaming sources, runtime grids, debug commands.
- [World Partition Data Layers](https://dev.epicgames.com/documentation/en-us/unreal-engine/world-partition---data-layers-in-unreal-engine) — assets/instances, Editor vs Runtime layers, runtime states, network authority, diagnostics.
- [World Partition HLOD](https://dev.epicgames.com/documentation/en-us/unreal-engine/world-partition---hierarchical-level-of-detail-in-unreal-engine) — HLOD layer types, assignment, settings, building, commandlet.
- [One File Per Actor](https://dev.epicgames.com/documentation/en-us/unreal-engine/one-file-per-actor-in-unreal-engine) — editor/source-control workflow and cooked-package boundary.
- [Level Instancing](https://dev.epicgames.com/documentation/en-us/unreal-engine/level-instancing-in-unreal-engine) — Level Instances, Packed Level Blueprints, Embedded and Level Streaming runtime modes, Data Layers.
- [`APackedLevelActor`](https://dev.epicgames.com/documentation/unreal-engine/API/Runtime/Engine/APackedLevelActor?lang=en-US) — packing boundary and fallback to a regular Level Instance when components are unsupported.
- [World Partition Builder Commandlet Reference](https://dev.epicgames.com/documentation/en-us/unreal-engine/world-partition-builder-commandlet-reference) — builder classes, forms, and source-control/rendering options.
- [Using PCG with World Partition](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-pcg-with-world-partition-in-unreal-engine) — partitioned/hierarchical PCG interaction, Data Layer and HLOD assignment.
- [`UWorldPartitionSubsystem::IsStreamingCompleted`](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/UWorldPartitionSubsystem/IsStreamingCompleted) — readiness API used in source-gated travel.
- [UE 5.8 Release Notes](https://dev.epicgames.com/documentation/unreal-engine/unreal-engine-5-8-release-notes?lang=en-US) — World Partition Insights, HLOD workflow changes, fixes, and experimental features.

## Maturity and interpretation

- World Partition, Data Layers, HLOD, OFPA, Level Instances, and builder commandlets are established UE5 workflows.
- World Partition Insights is new in 5.8; verify its configuration and capture overhead in the installed engine.
- Release-note items marked Experimental, including Fast Geometry-related work and optional external HLOD asset workflows, are not production defaults.
- `UWorldPartitionRuntimeHashSet` exists in the 5.8 API, but this skill does not prescribe it without current project-specific documentation and profiling. The documented default 2D Runtime Spatial Hash remains the baseline.
- Current Epic pages occasionally preserve command spelling quirks. Check console autocomplete/help in the exact engine build before scripting a command.

## Source-use rule

Prefer the 5.8 page or engine source over remembered UE 5.0–5.7 behavior. If a property, command, or UI path is absent in the installed build, report the discrepancy and inspect the engine version/plugin/configuration instead of inventing a replacement.

# Streaming sources, runtime grids, and teleports

## Source model

PlayerControllers can act as streaming sources. Use a `WorldPartitionStreamingSourceComponent` for vehicles, cameras, scripted destinations, or temporary preloading.

Important source properties include:

- **Target State**: request `Loaded` or `Activated`; when sources overlap, the highest requested state wins.
- **Priority**: resolves competition between sources; higher priority wins.
- **Shapes**: constrain the affected region instead of always using an unconstrained radius.
- **Target Grid** and **Target HLOD Layer**: narrow a source only when a specific design requires it.

Avoid leaving speculative sources active. Each one expands residency and I/O demand.

## Loading-range model

Use a measured lower bound:

```text
minimum lead distance = maximum approach speed × worst observed ready latency
                       + camera/interaction look-ahead
                       + safety margin
```

`ready latency` includes storage I/O, decompression, object creation, registration, render-resource readiness, and gameplay initialization on the target build.

- Increasing loading range raises lead time but increases resident memory and concurrent work.
- Decreasing it reduces residency but increases pop-in and arrival hitch risk.
- Smaller cells increase cell count and management overhead while improving spatial granularity.
- Larger cells reduce cell count but make each transition heavier and coarser.

Do not tune cell size and range simultaneously. Change one variable, record a repeatable traversal, and compare.

## Runtime grid policy

Start with the default 2D Runtime Spatial Hash and one grid. More than one runtime grid can hurt performance and makes source behavior harder to reason about. Add a grid only when profiling shows a distinct content class needs a materially different cell size or loading range.

Relevant grid settings:

- `Cell Size`
- `Loading Range`
- `Block on Slow Streaming`
- `Priority`

Blocking can protect world correctness but visibly stalls play. Decide explicitly which transitions may block and provide UI or transition design when needed.

## Safe teleport pattern

1. Place or move a temporary streaming-source component at the destination.
2. Enable the source with an appropriate target state and shape.
3. Poll `UWorldPartitionSubsystem::IsStreamingCompleted` for that source/provider.
4. On success, teleport the pawn and camera.
5. Retain the source until the normal player source owns the destination cells.
6. Disable or remove the temporary source.
7. On timeout, cancel, present a loading transition, or move to a safe fallback. Never silently teleport into missing collision.

## High-speed traversal pattern

- Lead the source in the velocity/look direction rather than merely inflating a symmetric range.
- Test sudden turns, braking, respawn, spectating, network correction, and possession changes.
- Keep gameplay-critical collision and navigation readiness in the acceptance check, not just visual presence.

## Debug commands

```text
wp.Runtime.ToggleDrawRuntimeHash2D
wp.Runtime.ToggleDrawRuntimeHash3D
wp.Runtime.ShowRuntimeSpatialHashGridLevel
wp.Runtime.ShowRuntimeSpatialHashGridLevelCount
wp.Runtime.ShowRuntimeSpatialHashGridIndex
wp.Runtime.OverrideRuntimeSpatialHashLoadingRange
wp.Runtime.MaxLoadingLevelStreamingCells
```

Use overrides only for diagnosis. Return to authored settings before recording final performance.

System selector and conversion

# System selector and conversion

## Choose the smallest system that meets the need

| Situation | Default choice | Reason |
|---|---|---|
| Continuous traversable world with bounded residency | World Partition, streaming enabled | Automatic source-distance streaming and one persistent authoring world |
| Small map that fits budget | World Partition, streaming disabled, or a normal level | Avoid runtime streaming complexity while retaining the desired authoring workflow |
| Repeated point of interest or gameplay assembly | Level Instance | Reusable sublevel edited in context |
| Repeated static architectural/mesh assembly | Packed Level Blueprint | Packs supported static content into an optimized actor |
| Existing UE5 World Partition project | Extend current model | Avoid a second overlapping streaming authority |
| Legacy/discrete sublevel architecture | Existing level streaming until migration is justified | Conversion risk may exceed its value |

World Partition is Epic's recommended UE5 large-world approach. It is not proof that every map needs cell streaming.

## Conversion safety workflow

1. Work on a source-controlled branch or verified backup.
2. Inventory Level Blueprints, streaming volumes, scripted sublevel transitions, world settings, always-loaded managers, actor references, foliage, navigation, and HLODs.
3. Resave the source level and correct unstable actor GUID warnings before conversion.
4. Run the conversion commandlet with `-ReportOnly` first.
5. Review actors that cannot be externalized, reference clusters, sublevel handling, and generated configuration.
6. Convert a copy or use `-ConversionSuffix` until the result passes validation.
7. Rebuild derived data: HLOD, navigation, foliage, PCG, minimap, or RVT as applicable.
8. Compare gameplay and memory in a cooked build; keep the old map until parity is demonstrated.

General form:

```text
UnrealEditor.exe <Project.uproject> <MapName> -run=WorldPartitionConvertCommandlet -ReportOnly
```

Useful flags include:

- `-ConversionSuffix`: preserve the source and write a converted map with a suffix.
- `-ReportOnly`: analyze without converting.
- `-GenerateIni`: emit conversion settings that can be reviewed and reused.
- `-OnlyMergeSubLevels`: merge sublevels without otherwise converting the result to World Partition.

Avoid `-SkipStableGUIDValidation` as a routine fix. Stable GUIDs are required for repeatable conversion; resave and repair the map instead.

## Reject the conversion when

- success depends on Level Blueprint state or streaming callbacks not yet replaced;
- non-OFPA actors inside Level Instances must exist at runtime but the design assumes Embedded Mode;
- reference bundles make most of the world resident;
- target-device memory or traversal hitching regresses with no credible mitigation;
- the team cannot rebuild and validate derived content reproducibly.

## Version-sensitive note

UE 5.8 adds World Partition streaming analysis in Unreal Insights and improves scoped HLOD building. Treat these as new workflow capabilities, not permission to skip before/after performance captures.