unreal-niagara

Unreal 5.8 Niagara

Build and optimize Unreal Niagara effects

---
name: unreal-niagara
description: Design, implement, connect, scale, profile, and debug visual effects in Unreal Engine 5.8. Use for Niagara Systems, emitters, modules, parameters, user parameters, CPU or GPU simulation, sprites, meshes, ribbons, collision, events, data interfaces, Data Channels, pooling, bounds, Effect Types, scalability, lightweight emitters, fluids, flipbooks, or gameplay-driven VFX.
---

# Unreal 5.8 Niagara

## Select the simulation before authoring

Read [`references/system-selector.md`](references/system-selector.md).

- Simple high-count noninteractive effect -> lightweight/stateless emitter candidate.
- Per-particle game-thread data, events, or CPU-only interfaces -> CPU simulation.
- Very high particle count with GPU-supported behavior -> GPU simulation.
- Many repeated gameplay bursts -> shared listener plus Niagara Data Channel candidate.
- Volumetric grid simulation -> Niagara Fluids only after platform/budget review; bake when possible.

Build the cheapest representation that preserves the required read, not the most elaborate simulation.

## Execute

1. Define the visual read, duration, scale, camera range, gameplay contract, and target platforms.
2. Split the effect into semantic emitters; choose renderer and simulation target per emitter.
3. Establish spawn, initialize, update, render, and completion behavior with built-in modules first.
4. Expose a small user-parameter contract; keep gameplay authority outside Niagara.
5. Add collision, events, data interfaces, or Data Channels only for a specific requirement.
6. Set bounds, warmup/pre-roll assumptions, pooling/reuse, and deactivation behavior.
7. Add Effect Type and platform scalability/culling rules before content multiplies.
8. Use Niagara Debugger and target-hardware captures at realistic instance counts and overdraw.

Load only what applies:

- [`references/architecture-and-stack.md`](references/architecture-and-stack.md)
- [`references/gameplay-integration.md`](references/gameplay-integration.md)
- [`references/cpu-gpu-collision-events.md`](references/cpu-gpu-collision-events.md)
- [`references/data-channels-and-interfaces.md`](references/data-channels-and-interfaces.md)
- [`references/scalability-and-pooling.md`](references/scalability-and-pooling.md)
- [`references/recipes.md`](references/recipes.md)
- [`references/debugging-and-profiling.md`](references/debugging-and-profiling.md)

## Required answer format

Return:

1. **Visual/gameplay contract** and chosen representation.
2. **System/emitter architecture**, simulation target, renderers, and module order.
3. **Spawn/lifetime/completion behavior**.
4. **User parameters and ownership/update frequency**.
5. **Collision/event/data-interface assumptions and fallbacks**.
6. **Bounds, pooling, Effect Type, culling, quality tiers, and platform consequences**.
7. **Debugger metrics and visual acceptance checks at realistic counts**.

## Hard rules

- Niagara presents effects; authoritative damage, hits, inventory, and progression remain gameplay-owned.
- Prefer existing modules/templates before custom Scratch Pad or HLSL modules.
- Choose CPU/GPU simulation from data-access, determinism, event, collision, and scale needs.
- Set and test bounds. GPU systems can disappear or waste work when bounds are wrong.
- Every looping system needs an explicit owner and stop/deactivate path.
- Pool only effects that reset cleanly; verify user parameters and persistent state on reuse.
- Use Effect Types for families of effects and platform-aware culling/scalability.
- Measure translucent overdraw as well as simulation time.
- Lightweight emitters trade flexibility for lower CPU/memory cost; verify feature compatibility.
- Niagara Fluids are Beta in UE 5.8 and can be graphically intensive; use 2D/game templates or
  baked flipbooks when they satisfy the effect.

See [`references/sources.md`](references/sources.md) for the UE 5.8 source trail.

## Select the simulation before authoring

Read [`references/system-selector.md`](/unreal/unreal-niagara/system-selector/).

- Simple high-count noninteractive effect -> lightweight/stateless emitter candidate.
- Per-particle game-thread data, events, or CPU-only interfaces -> CPU simulation.
- Very high particle count with GPU-supported behavior -> GPU simulation.
- Many repeated gameplay bursts -> shared listener plus Niagara Data Channel candidate.
- Volumetric grid simulation -> Niagara Fluids only after platform/budget review; bake when possible.

Build the cheapest representation that preserves the required read, not the most elaborate simulation.

## Execute

1. Define the visual read, duration, scale, camera range, gameplay contract, and target platforms.
2. Split the effect into semantic emitters; choose renderer and simulation target per emitter.
3. Establish spawn, initialize, update, render, and completion behavior with built-in modules first.
4. Expose a small user-parameter contract; keep gameplay authority outside Niagara.
5. Add collision, events, data interfaces, or Data Channels only for a specific requirement.
6. Set bounds, warmup/pre-roll assumptions, pooling/reuse, and deactivation behavior.
7. Add Effect Type and platform scalability/culling rules before content multiplies.
8. Use Niagara Debugger and target-hardware captures at realistic instance counts and overdraw.

Load only what applies:

- [`references/architecture-and-stack.md`](/unreal/unreal-niagara/architecture-and-stack/)
- [`references/gameplay-integration.md`](/unreal/unreal-niagara/gameplay-integration/)
- [`references/cpu-gpu-collision-events.md`](/unreal/unreal-niagara/cpu-gpu-collision-events/)
- [`references/data-channels-and-interfaces.md`](/unreal/unreal-niagara/data-channels-and-interfaces/)
- [`references/scalability-and-pooling.md`](/unreal/unreal-niagara/scalability-and-pooling/)
- [`references/recipes.md`](/unreal/unreal-niagara/recipes/)
- [`references/debugging-and-profiling.md`](/unreal/unreal-niagara/debugging-and-profiling/)

## Required answer format

Return:

1. **Visual/gameplay contract** and chosen representation.
2. **System/emitter architecture**, simulation target, renderers, and module order.
3. **Spawn/lifetime/completion behavior**.
4. **User parameters and ownership/update frequency**.
5. **Collision/event/data-interface assumptions and fallbacks**.
6. **Bounds, pooling, Effect Type, culling, quality tiers, and platform consequences**.
7. **Debugger metrics and visual acceptance checks at realistic counts**.

## Hard rules

- Niagara presents effects; authoritative damage, hits, inventory, and progression remain gameplay-owned.
- Prefer existing modules/templates before custom Scratch Pad or HLSL modules.
- Choose CPU/GPU simulation from data-access, determinism, event, collision, and scale needs.
- Set and test bounds. GPU systems can disappear or waste work when bounds are wrong.
- Every looping system needs an explicit owner and stop/deactivate path.
- Pool only effects that reset cleanly; verify user parameters and persistent state on reuse.
- Use Effect Types for families of effects and platform-aware culling/scalability.
- Measure translucent overdraw as well as simulation time.
- Lightweight emitters trade flexibility for lower CPU/memory cost; verify feature compatibility.
- Niagara Fluids are Beta in UE 5.8 and can be graphically intensive; use 2D/game templates or
  baked flipbooks when they satisfy the effect.

See [`references/sources.md`](/unreal/unreal-niagara/sources/) for the UE 5.8 source trail.

unreal 5.8 niagara design, implement, connect, scale, profile, and debug visual effects in unreal engine 5.8. use for niagara systems, emitters, modules, parameters, user parameters, cpu or gpu simulation, sprites, meshes, ribbons, collision, events, data interfaces, data channels, pooling, bounds, effect types, scalability, lightweight emitters, fluids, flipbooks, or gameplay-driven vfx. system architecture and stack order system architecture and stack order asset roles - system: complete effect, timelines, system-level parameters and scalability. - emitter: one particle population and behavior stream. - module: reusable operation in a stage/stack. - parameter: typed data in engine, user, system, emitter, or particle namespace. - renderer: converts particle/system data to sprites, meshes, ribbons, lights, or other output. build order 1. create a system from the closest template or an empty system. 2. add one emitter per semantic layer: core flash, debris, smoke, trail, decal handoff, and so on. 3. establish emitter/system lifecycle and loop behavior. 4. in spawn stages, initialize values that are constant over a particle's life. 5. in update stages, integrate motion and change values over time. 6. bind renderer attributes explicitly; remove unused attributes/modules. 7. add user parameters only at the system's public integration seam. 8. validate each emitter alone, then the composed effect. module order is behavior order. when a later module overwrites an attribute, earlier work can be invisible. debug by watching the attribute and disabling modules from the end of the relevant stack. use local/module inputs for internal implementation, particle attributes for per-particle state, system/emitter parameters for shared simulation state, and user parameters for caller-controlled values. name user parameters by meaning and units, not by the current graph node. cpu/gpu simulation, collision, and events cpu/gpu simulation, collision, and events cpu simulation choose cpu when required data interfaces, per-particle game-thread interaction, cpu events, or small counts outweigh the extra cpu cost. profile many simultaneous system instances, not only one. gpu simulation choose gpu for large counts and gpu-supported operations. define fixed bounds or a validated bounds strategy. confirm target-platform compute support, data-interface compatibility, collision method, sort cost, and any cpu readback requirement. collision selection - scene/depth-based gpu collision is view-dependent; off-screen or hidden geometry may not exist in the collision representation. - distance-field or hardware ray-tracing paths have their own platform/project requirements. - cpu collision can query world collision but costs grow with particles and queries. - cheap effects may use analytic planes, kill volumes, or authored timing instead of scene collision. events use niagara events when one simulation layer must react to another and the chosen simulation target supports the path. for gameplay events, let gameplay own the event and pass niagara the result. event-driven secondary particles can multiply work abruptly; cap spawn counts and test burst storms. when choosing a custom module, first confirm no built-in module already produces the behavior. document execution stage, required attributes, units, coordinate space, and supported simulation target. data channels and data interfaces data channels and data interfaces data interfaces use a data interface when the system needs structured access to an object or dataset such as a skeletal mesh, static mesh, curve, texture, render target, audio, or scene data. verify whether the interface supports cpu, gpu, both, and the required access mode on target platforms. prefer passing a stable owning component/object once over updating arrays of equivalent values every frame. guard invalid/destroyed references and define a fallback pose/value. niagara data channels ndcs carry a defined payload between gameplay code and niagara, or between niagara systems. they are useful for combining many repeated bursts into a shared listener simulation. 1. create a data channel asset and define the smallest typed payload. 2. associate the listener system(s). 3. configure a continuous listener with an intentional lifetime; epic's pattern uses infinite loop behavior plus complete if unused for cleanup. 4. read the channel and spawn particles from received entries. 5. have blueprint/c++ publish events with consistent coordinate space and units. 6. test maximum event rate, island bounds/extents, unused cleanup, and dropped/late events. use direct system user parameters for a few long-lived instances. use ndc when repeated system spawn overhead and many same-schema events justify a shared simulation. do not turn the channel into an unbounded general gameplay message bus. debugging and profiling debugging and profiling symptom ladder | symptom | inspect first | then | |---|---|---| | nothing renders | system/component active, emitter enabled, spawn count | bounds, renderer binding, compile errors | | disappears at angle/distance | fixed bounds | scalability/culling, lod/platform | | particles at origin | parameter binding and coordinate space | invalid data interface/source | | pooled effect keeps old color/target | reset contract | persistent age/emitter state | | gpu collision fails off-screen | collision representation | switch method or design fallback | | effect never ends | loop/lifetime/completion | owner cleanup, auto deactivate | | hitch on first use | compilation/pso/assets | prewarm/readiness strategy and packaged capture | | frame time spikes during bursts | system count and spawn multiplication | simulation, renderer, overdraw, collision | debug procedure 1. isolate one system and disable all but one emitter. 2. check compile messages and parameter bindings. 3. use attribute/parameter watch and niagara debugger (tools -> debug -> niagara debugger). 4. visualize bounds and collision/debug drawing where supported. 5. recreate the expected maximum system count and camera overlap. 6. use the debug overview performance view for system/game-thread comparison. 7. inspect shader complexity for translucent overdraw and use gpu/cpu profiling for actual timing. 8. compare one change under the same capture conditions. track system/emitter instance counts, active particles, tick/simulation time, render cost, material overdraw, collision/events, and memory. a cheap simulation can still be expensive to render; a cheap sprite can still become costly through overlap, sorting, lights, or full-screen coverage. gameplay integration gameplay integration ownership contract gameplay decides that an event occurred and supplies stable effect inputs. niagara renders the response. do not make particle collision the sole authority for damage or other persistent state. typical user parameters: - world position/normal or source transform; - color, intensity, size, duration, or normalized charge; - source/target actor or component for a data interface; - gameplay-owned seed/event identifier when repeatability matters. spawned burst 1. gameplay validates the event. 2. spawn/activate the niagara system at the authoritative visual location on the relevant clients. 3. set user parameters before activation when the first frame depends on them. 4. let finite emitters complete, then release/destroy/pool the component. attached/continuous effect 1. the owning actor/component creates or activates the effect. 2. attach using the intended transform rule and expose changing values at a bounded frequency. 3. stop spawning first when a graceful tail is needed; deactivate or destroy when complete. 4. clean up on owner end play, state exit, cancellation, and network relevancy changes. replicate compact gameplay state/events, then spawn cosmetic effects locally. do not replicate every particle. decide whether late joiners need current continuous state, whether unreliable one-shot events may be dropped, and whether prediction requires a reconciliation/cancellation path. effect recipes effect recipes impact burst finite system: flash sprite, directional debris, short smoke, optional decal handoff. inputs are position, surface normal, physical-surface style, scale, and seed. align directional particles to the normal, cap secondary spawns, auto-deactivate, and batch high-frequency impacts through a data channel when measurement supports it. character trail attach to a stable component/socket or sample a skeletal data interface. use ribbons when continuous history is required; reset ribbon identity on teleport/reuse. bound width, tessellation, lifetime, and translucency. stop spawning on state exit and allow a deliberate tail. area telegraph prefer a simple mesh/decal/material plus niagara accents. gameplay owns radius, timing, and damage; the effect consumes normalized progress and dimensions. preserve contrast and shape at low quality. environmental ambient use large controlled bounds, distance scalability, low update frequency where valid, and camera/local space only when it matches the illusion. avoid one independent system per tiny ambient element when one shared system or lightweight emitters suffice. smoke/fire start with sprites/flipbooks. use 2d niagara fluids templates when simulation materially improves a game effect and the budget supports it. reserve 3d fluids for high-end/cinematic cases unless proven. bake a fluid simulation to a flipbook when dynamic interaction is unnecessary. beam/target link pass source and target explicitly, define behavior when either is invalid, and update only as often as visual motion requires. ribbons/beams are presentation; gameplay traces determine hits. scalability, bounds, lifetime, and pooling scalability, bounds, lifetime, and pooling effect type policy create effect types by semantic/cost family, such as impacts, ambient, character, or critical telegraphs. they centralize system/emitter scalability, significance, cull reactions, update frequency, validation rules, and performance baselines. use system overrides only for justified exceptions. quality plan for each platform/tier decide: - maximum system/particle instances; - distance, visibility, and instance-count culling; - response when culled: deactivate, pause, or another supported reaction; - emitter spawn-rate/count scaling; - renderer/material simplification; - collision, lights, shadows, sorting, ribbons, and fluids availability. gameplay-critical telegraphs need a legible fallback; do not cull their information content merely because decorative effects are culled. bounds and lifetime - visualize and test bounds through the complete motion envelope. - overlarge bounds reduce culling efficiency; undersized bounds cause popping/disappearance. - enable auto deactivate when finite emitters should deactivate after spawning ends. - every loop needs a caller-owned stop path and cleanup on owner destruction. pooling pool only when repeated component creation is measured and the system resets reliably. before reuse, reset user parameters, attachments/transforms, age, loop state, data-interface bindings, and any persistent emitter state. test cancellation, rapid reuse, and owner destruction. lightweight emitters are another lever for many simple effects; compare them in niagara debugger rather than assuming. ue 5.8 primary sources ue 5.8 primary sources - niagara overview - creating visual effects in niagara - niagara debugger - system settings reference - niagara effect type api - niagara data channels - niagara data channels overview - lightweight emitters overview - lightweight emitters quick start - niagara fluids - fluid simulation overview pages were checked against the ue 5.8 documentation on 2026-07-19. reconfirm feature maturity, simulation-target support, and platform behavior after an engine upgrade. niagara system selector niagara system selector | requirement | prefer | verify | |---|---|---| | simple repeatable particles, many emitters | lightweight/stateless emitter | required modules/renderers are supported | | gameplay-readable particle data or cpu-only interface | cpu sim | particle count and game-thread cost | | large particle count, supported gpu behavior | gpu compute sim | bounds, gpu collision/data access, readback limits | | many same-type impacts/bursts | data channel + shared listener | batching semantics, island/extents, lifetime | | trail/beam | ribbon or beam-style module setup | source continuity, tessellation, uvs | | volumetric smoke/fire/liquid | niagara fluids or flipbook | beta maturity, gpu/memory budget, platform | | pure camera-facing illusion | sprite/flipbook | overdraw, sorting, lighting | | shape and parallax matter | mesh particles | triangles, draw calls, material cost | decision questions: 1. what must the player perceive, and for how long? 2. must particles affect gameplay, or only respond to gameplay? 3. does the simulation need scene/depth/distance-field collision? 4. how many systems and particles coexist in the worst representative view? 5. can a material animation, decal, mesh animation, or flipbook communicate the same effect cheaper? mixed systems may contain both stateful and lightweight emitters. choose per emitter, not by habit.

System architecture and stack order

# System architecture and stack order

## Asset roles

- **System**: complete effect, timelines, system-level parameters and scalability.
- **Emitter**: one particle population and behavior stream.
- **Module**: reusable operation in a stage/stack.
- **Parameter**: typed data in engine, user, system, emitter, or particle namespace.
- **Renderer**: converts particle/system data to sprites, meshes, ribbons, lights, or other output.

## Build order

1. Create a System from the closest template or an empty system.
2. Add one emitter per semantic layer: core flash, debris, smoke, trail, decal handoff, and so on.
3. Establish emitter/system lifecycle and loop behavior.
4. In spawn stages, initialize values that are constant over a particle's life.
5. In update stages, integrate motion and change values over time.
6. Bind renderer attributes explicitly; remove unused attributes/modules.
7. Add user parameters only at the system's public integration seam.
8. Validate each emitter alone, then the composed effect.

Module order is behavior order. When a later module overwrites an attribute, earlier work can be
invisible. Debug by watching the attribute and disabling modules from the end of the relevant stack.

Use local/module inputs for internal implementation, particle attributes for per-particle state,
system/emitter parameters for shared simulation state, and user parameters for caller-controlled
values. Name user parameters by meaning and units, not by the current graph node.

# CPU/GPU simulation, collision, and events

## CPU simulation

Choose CPU when required data interfaces, per-particle game-thread interaction, CPU events, or
small counts outweigh the extra CPU cost. Profile many simultaneous system instances, not only one.

## GPU simulation

Choose GPU for large counts and GPU-supported operations. Define fixed bounds or a validated bounds
strategy. Confirm target-platform compute support, data-interface compatibility, collision method,
sort cost, and any CPU readback requirement.

## Collision selection

- Scene/depth-based GPU collision is view-dependent; off-screen or hidden geometry may not exist
  in the collision representation.
- Distance-field or hardware ray-tracing paths have their own platform/project requirements.
- CPU collision can query world collision but costs grow with particles and queries.
- Cheap effects may use analytic planes, kill volumes, or authored timing instead of scene collision.

## Events

Use Niagara events when one simulation layer must react to another and the chosen simulation target
supports the path. For gameplay events, let gameplay own the event and pass Niagara the result.
Event-driven secondary particles can multiply work abruptly; cap spawn counts and test burst storms.

When choosing a custom module, first confirm no built-in module already produces the behavior.
Document execution stage, required attributes, units, coordinate space, and supported simulation target.

Data Channels and data interfaces

# Data Channels and data interfaces

## Data interfaces

Use a data interface when the system needs structured access to an object or dataset such as a
Skeletal Mesh, Static Mesh, curve, texture, render target, audio, or scene data. Verify whether the
interface supports CPU, GPU, both, and the required access mode on target platforms.

Prefer passing a stable owning component/object once over updating arrays of equivalent values every
frame. Guard invalid/destroyed references and define a fallback pose/value.

## Niagara Data Channels

NDCs carry a defined payload between gameplay code and Niagara, or between Niagara systems. They are
useful for combining many repeated bursts into a shared listener simulation.

1. Create a Data Channel asset and define the smallest typed payload.
2. Associate the listener system(s).
3. Configure a continuous listener with an intentional lifetime; Epic's pattern uses infinite loop
   behavior plus Complete If Unused for cleanup.
4. Read the channel and spawn particles from received entries.
5. Have Blueprint/C++ publish events with consistent coordinate space and units.
6. Test maximum event rate, island bounds/extents, unused cleanup, and dropped/late events.

Use direct system user parameters for a few long-lived instances. Use NDC when repeated system spawn
overhead and many same-schema events justify a shared simulation. Do not turn the channel into an
unbounded general gameplay message bus.

Debugging and profiling

# Debugging and profiling

## Symptom ladder

| Symptom | Inspect first | Then |
|---|---|---|
| Nothing renders | system/component active, emitter enabled, spawn count | bounds, renderer binding, compile errors |
| Disappears at angle/distance | fixed bounds | scalability/culling, LOD/platform |
| Particles at origin | parameter binding and coordinate space | invalid data interface/source |
| Pooled effect keeps old color/target | reset contract | persistent age/emitter state |
| GPU collision fails off-screen | collision representation | switch method or design fallback |
| Effect never ends | loop/lifetime/completion | owner cleanup, Auto Deactivate |
| Hitch on first use | compilation/PSO/assets | prewarm/readiness strategy and packaged capture |
| Frame time spikes during bursts | system count and spawn multiplication | simulation, renderer, overdraw, collision |

## Debug procedure

1. Isolate one system and disable all but one emitter.
2. Check compile messages and parameter bindings.
3. Use attribute/parameter watch and Niagara Debugger (Tools -> Debug -> Niagara Debugger).
4. Visualize bounds and collision/debug drawing where supported.
5. Recreate the expected maximum system count and camera overlap.
6. Use the Debug Overview Performance view for system/game-thread comparison.
7. Inspect Shader Complexity for translucent overdraw and use GPU/CPU profiling for actual timing.
8. Compare one change under the same capture conditions.

Track system/emitter instance counts, active particles, tick/simulation time, render cost, material
overdraw, collision/events, and memory. A cheap simulation can still be expensive to render; a cheap
sprite can still become costly through overlap, sorting, lights, or full-screen coverage.

Gameplay integration

# Gameplay integration

## Ownership contract

Gameplay decides that an event occurred and supplies stable effect inputs. Niagara renders the
response. Do not make particle collision the sole authority for damage or other persistent state.

Typical user parameters:

- world position/normal or source transform;
- color, intensity, size, duration, or normalized charge;
- source/target actor or component for a data interface;
- gameplay-owned seed/event identifier when repeatability matters.

## Spawned burst

1. Gameplay validates the event.
2. Spawn/activate the Niagara System at the authoritative visual location on the relevant clients.
3. Set user parameters before activation when the first frame depends on them.
4. Let finite emitters complete, then release/destroy/pool the component.

## Attached/continuous effect

1. The owning actor/component creates or activates the effect.
2. Attach using the intended transform rule and expose changing values at a bounded frequency.
3. Stop spawning first when a graceful tail is needed; deactivate or destroy when complete.
4. Clean up on owner end play, state exit, cancellation, and network relevancy changes.

Replicate compact gameplay state/events, then spawn cosmetic effects locally. Do not replicate every
particle. Decide whether late joiners need current continuous state, whether unreliable one-shot
events may be dropped, and whether prediction requires a reconciliation/cancellation path.

Effect recipes

# Effect recipes

## Impact burst

Finite system: flash sprite, directional debris, short smoke, optional decal handoff. Inputs are
position, surface normal, physical-surface style, scale, and seed. Align directional particles to
the normal, cap secondary spawns, auto-deactivate, and batch high-frequency impacts through a Data
Channel when measurement supports it.

## Character trail

Attach to a stable component/socket or sample a skeletal data interface. Use ribbons when continuous
history is required; reset ribbon identity on teleport/reuse. Bound width, tessellation, lifetime,
and translucency. Stop spawning on state exit and allow a deliberate tail.

## Area telegraph

Prefer a simple mesh/decal/material plus Niagara accents. Gameplay owns radius, timing, and damage;
the effect consumes normalized progress and dimensions. Preserve contrast and shape at low quality.

## Environmental ambient

Use large controlled bounds, distance scalability, low update frequency where valid, and camera/local
space only when it matches the illusion. Avoid one independent system per tiny ambient element when
one shared system or lightweight emitters suffice.

## Smoke/fire

Start with sprites/flipbooks. Use 2D Niagara Fluids templates when simulation materially improves a
game effect and the budget supports it. Reserve 3D fluids for high-end/cinematic cases unless proven.
Bake a fluid simulation to a flipbook when dynamic interaction is unnecessary.

## Beam/target link

Pass source and target explicitly, define behavior when either is invalid, and update only as often
as visual motion requires. Ribbons/beams are presentation; gameplay traces determine hits.

# Scalability, bounds, lifetime, and pooling

## Effect Type policy

Create Effect Types by semantic/cost family, such as impacts, ambient, character, or critical
telegraphs. They centralize system/emitter scalability, significance, cull reactions, update
frequency, validation rules, and performance baselines. Use system overrides only for justified
exceptions.

## Quality plan

For each platform/tier decide:

- maximum system/particle instances;
- distance, visibility, and instance-count culling;
- response when culled: deactivate, pause, or another supported reaction;
- emitter spawn-rate/count scaling;
- renderer/material simplification;
- collision, lights, shadows, sorting, ribbons, and fluids availability.

Gameplay-critical telegraphs need a legible fallback; do not cull their information content merely
because decorative effects are culled.

## Bounds and lifetime

- Visualize and test bounds through the complete motion envelope.
- Overlarge bounds reduce culling efficiency; undersized bounds cause popping/disappearance.
- Enable Auto Deactivate when finite emitters should deactivate after spawning ends.
- Every loop needs a caller-owned stop path and cleanup on owner destruction.

## Pooling

Pool only when repeated component creation is measured and the system resets reliably. Before reuse,
reset user parameters, attachments/transforms, age, loop state, data-interface bindings, and any
persistent emitter state. Test cancellation, rapid reuse, and owner destruction. Lightweight emitters
are another lever for many simple effects; compare them in Niagara Debugger rather than assuming.

UE 5.8 primary sources

# UE 5.8 primary sources

- [Niagara Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/overview-of-niagara-effects-for-unreal-engine)
- [Creating Visual Effects in Niagara](https://dev.epicgames.com/documentation/en-us/unreal-engine/creating-visual-effects-in-niagara-for-unreal-engine)
- [Niagara Debugger](https://dev.epicgames.com/documentation/en-us/unreal-engine/niagara-debugger-for-unreal-engine)
- [System Settings Reference](https://dev.epicgames.com/documentation/en-us/unreal-engine/system-settings-reference-for-niagara-effects-in-unreal-engine)
- [Niagara Effect Type API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/Niagara/UNiagaraEffectType)
- [Niagara Data Channels](https://dev.epicgames.com/documentation/en-us/unreal-engine/data-channels-in-niagara-for-unreal-engine)
- [Niagara Data Channels Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/niagara-data-channels-overview)
- [Lightweight Emitters Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/niagara-lightweight-emitters-overview)
- [Lightweight Emitters Quick Start](https://dev.epicgames.com/documentation/en-us/unreal-engine/lightweight-emitters-quick-start-for-niagara-in-unreal-engine)
- [Niagara Fluids](https://dev.epicgames.com/documentation/en-us/unreal-engine/niagara-fluids-in-unreal-engine)
- [Fluid Simulation Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/fluid-simulation-in-unreal-engine---overview)

Pages were checked against the UE 5.8 documentation on 2026-07-19. Reconfirm feature maturity,
simulation-target support, and platform behavior after an engine upgrade.

Niagara system selector

# Niagara system selector

| Requirement | Prefer | Verify |
|---|---|---|
| Simple repeatable particles, many emitters | Lightweight/stateless emitter | required modules/renderers are supported |
| Gameplay-readable particle data or CPU-only interface | CPU sim | particle count and game-thread cost |
| Large particle count, supported GPU behavior | GPU compute sim | bounds, GPU collision/data access, readback limits |
| Many same-type impacts/bursts | Data Channel + shared listener | batching semantics, island/extents, lifetime |
| Trail/beam | Ribbon or beam-style module setup | source continuity, tessellation, UVs |
| Volumetric smoke/fire/liquid | Niagara Fluids or flipbook | Beta maturity, GPU/memory budget, platform |
| Pure camera-facing illusion | Sprite/flipbook | overdraw, sorting, lighting |
| Shape and parallax matter | Mesh particles | triangles, draw calls, material cost |

Decision questions:

1. What must the player perceive, and for how long?
2. Must particles affect gameplay, or only respond to gameplay?
3. Does the simulation need scene/depth/distance-field collision?
4. How many systems and particles coexist in the worst representative view?
5. Can a material animation, decal, mesh animation, or flipbook communicate the same effect cheaper?

Mixed systems may contain both stateful and lightweight emitters. Choose per emitter, not by habit.


unreal-packaging-deployment

Unreal 5.8 Packaging and Deployment

Build, cook, package, deploy, and diagnose Unreal

---
name: unreal-packaging-deployment
description: Build, cook, stage, package, archive, deploy, release, and diagnose Unreal Engine 5.8 projects. Use for build configurations and targets, UnrealBuildTool, AutomationTool, BuildCookRun, Project Launcher profiles, command-line cooks, cook inclusion, maps, Pak or IoStore containers, chunks, patches, DLC, platform SDKs, plugins, runtime dependencies, configuration staging, signing and encryption, symbols, logs, crash reporting, CI artifacts, reproducible builds, missing cooked assets, packaging failures, or packaged-build differences.
---

# Unreal 5.8 Packaging and Deployment

## Establish the artifact contract

Read [`references/system-selector.md`](references/system-selector.md).

1. Record engine revision, project commit, target platform, architecture, target type, build
   configuration, device profile, distribution channel, and base release when patching.
2. Define the artifact: Development/Test/Shipping, client/server, container format, chunks, symbols,
   prerequisites, archive, deploy destination, and acceptance tests.
3. Separate Build, Cook, Stage, Package, Deploy, and Run. Identify the first failing phase.
4. Reproduce with a saved Project Launcher profile or recorded AutomationTool command.
5. Preserve the complete log, exit code, manifests, artifact hashes, size report, and symbol identity.
6. Run from a clean staging/archive location and test without editor binaries, loose source content,
   developer config, or a cook server.
7. Promote the exact tested artifact; do not rebuild after approval.

Route neighboring work deliberately:

- asset schemas, Primary Asset rules, and content-to-chunk ownership -> `unreal-data-assets-tables`;
- commandlets, Data Validation, and automation tests -> `unreal-editor-automation`;
- runtime loading, residency, PSOs, and load hitches -> `unreal-memory-streaming`;
- packaged performance captures -> `unreal-insights-profiling`;
- save-format compatibility across releases -> `unreal-save-load`.

Load only what applies:

- [`references/build-configurations-targets.md`](references/build-configurations-targets.md)
- [`references/build-cook-stage-package.md`](references/build-cook-stage-package.md)
- [`references/cooking-inclusion-validation.md`](references/cooking-inclusion-validation.md)
- [`references/uat-project-launcher-ci.md`](references/uat-project-launcher-ci.md)
- [`references/containers-chunks-patches-dlc.md`](references/containers-chunks-patches-dlc.md)
- [`references/config-staging-runtime-dependencies.md`](references/config-staging-runtime-dependencies.md)
- [`references/plugins-sdks-platforms.md`](references/plugins-sdks-platforms.md)
- [`references/symbols-logs-crash-reporting.md`](references/symbols-logs-crash-reporting.md)
- [`references/release-reproducibility-security.md`](references/release-reproducibility-security.md)
- [`references/diagnostics-recipes.md`](references/diagnostics-recipes.md)

## Required answer format

Return:

1. **Artifact contract** and target matrix.
2. **Exact pipeline surface**: editor, Project Launcher, commandlet, UAT, or CI.
3. **Ordered Build/Cook/Stage/Package/Deploy actions** and owned configuration.
4. **Cook roots, maps, chunks, staged files, plugins, SDKs, and platform prerequisites**.
5. **Symbols, logs, crash collection, version/build ID, archive, and security policy**.
6. **Clean-device verification**, failure injection, patch/base compatibility, and pass criteria.
7. **First causal error** with the smallest confirming experiment when diagnosing.

## Hard rules

- Use Cook By the Book and a packaged target build for QA/release evidence; Cook On the Fly is an
  iteration service, not a distributable artifact.
- Never use `-cookall`, broad always-cook directories, or loose copied assets as the first fix for a
  missing dependency. Identify the intended cook root and prove it in manifests/artifacts.
- Never infer success from AutomationTool exit alone. Launch, traverse, save/load, network, suspend,
  and platform-test the staged artifact required by the release contract.
- Keep source defaults, platform overrides, generated user config, and secrets separate. Inspect the
  staged effective configuration and strip denied keys/sections.
- Declare third-party runtime files through build/staging rules; do not repair a release by manually
  copying an untracked DLL beside one machine's executable.
- Preserve symbols outside the public artifact and map them to the exact executable/build identity.
- Build a patch against the exact retained base release. Never regenerate or silently replace the base.
- Treat signing/encryption keys as release secrets. Encryption can increase patch entropy and IO cost;
  measure the chosen policy.
- Test the distribution path on clean target hardware with the correct account, SDK/runtime,
  permissions, storage state, and no editor installation.
- Do not invent UAT flags or platform requirements. Inspect `BuildCookRun -Help`, the generated Project
  Launcher command, UE 5.8 source, and the target platform's current restricted documentation.

See [`references/sources.md`](references/sources.md) for the UE 5.8 primary-source trail.

## Establish the artifact contract

Read [`references/system-selector.md`](/unreal/unreal-packaging-deployment/system-selector/).

1. Record engine revision, project commit, target platform, architecture, target type, build
   configuration, device profile, distribution channel, and base release when patching.
2. Define the artifact: Development/Test/Shipping, client/server, container format, chunks, symbols,
   prerequisites, archive, deploy destination, and acceptance tests.
3. Separate Build, Cook, Stage, Package, Deploy, and Run. Identify the first failing phase.
4. Reproduce with a saved Project Launcher profile or recorded AutomationTool command.
5. Preserve the complete log, exit code, manifests, artifact hashes, size report, and symbol identity.
6. Run from a clean staging/archive location and test without editor binaries, loose source content,
   developer config, or a cook server.
7. Promote the exact tested artifact; do not rebuild after approval.

Route neighboring work deliberately:

- asset schemas, Primary Asset rules, and content-to-chunk ownership -> `unreal-data-assets-tables`;
- commandlets, Data Validation, and automation tests -> `unreal-editor-automation`;
- runtime loading, residency, PSOs, and load hitches -> `unreal-memory-streaming`;
- packaged performance captures -> `unreal-insights-profiling`;
- save-format compatibility across releases -> `unreal-save-load`.

Load only what applies:

- [`references/build-configurations-targets.md`](/unreal/unreal-packaging-deployment/build-configurations-targets/)
- [`references/build-cook-stage-package.md`](/unreal/unreal-packaging-deployment/build-cook-stage-package/)
- [`references/cooking-inclusion-validation.md`](/unreal/unreal-packaging-deployment/cooking-inclusion-validation/)
- [`references/uat-project-launcher-ci.md`](/unreal/unreal-packaging-deployment/uat-project-launcher-ci/)
- [`references/containers-chunks-patches-dlc.md`](/unreal/unreal-packaging-deployment/containers-chunks-patches-dlc/)
- [`references/config-staging-runtime-dependencies.md`](/unreal/unreal-packaging-deployment/config-staging-runtime-dependencies/)
- [`references/plugins-sdks-platforms.md`](/unreal/unreal-packaging-deployment/plugins-sdks-platforms/)
- [`references/symbols-logs-crash-reporting.md`](/unreal/unreal-packaging-deployment/symbols-logs-crash-reporting/)
- [`references/release-reproducibility-security.md`](/unreal/unreal-packaging-deployment/release-reproducibility-security/)
- [`references/diagnostics-recipes.md`](/unreal/unreal-packaging-deployment/diagnostics-recipes/)

## Required answer format

Return:

1. **Artifact contract** and target matrix.
2. **Exact pipeline surface**: editor, Project Launcher, commandlet, UAT, or CI.
3. **Ordered Build/Cook/Stage/Package/Deploy actions** and owned configuration.
4. **Cook roots, maps, chunks, staged files, plugins, SDKs, and platform prerequisites**.
5. **Symbols, logs, crash collection, version/build ID, archive, and security policy**.
6. **Clean-device verification**, failure injection, patch/base compatibility, and pass criteria.
7. **First causal error** with the smallest confirming experiment when diagnosing.

## Hard rules

- Use Cook By the Book and a packaged target build for QA/release evidence; Cook On the Fly is an
  iteration service, not a distributable artifact.
- Never use `-cookall`, broad always-cook directories, or loose copied assets as the first fix for a
  missing dependency. Identify the intended cook root and prove it in manifests/artifacts.
- Never infer success from AutomationTool exit alone. Launch, traverse, save/load, network, suspend,
  and platform-test the staged artifact required by the release contract.
- Keep source defaults, platform overrides, generated user config, and secrets separate. Inspect the
  staged effective configuration and strip denied keys/sections.
- Declare third-party runtime files through build/staging rules; do not repair a release by manually
  copying an untracked DLL beside one machine's executable.
- Preserve symbols outside the public artifact and map them to the exact executable/build identity.
- Build a patch against the exact retained base release. Never regenerate or silently replace the base.
- Treat signing/encryption keys as release secrets. Encryption can increase patch entropy and IO cost;
  measure the chosen policy.
- Test the distribution path on clean target hardware with the correct account, SDK/runtime,
  permissions, storage state, and no editor installation.
- Do not invent UAT flags or platform requirements. Inspect `BuildCookRun -Help`, the generated Project
  Launcher command, UE 5.8 source, and the target platform's current restricted documentation.

See [`references/sources.md`](/unreal/unreal-packaging-deployment/sources/) for the UE 5.8 primary-source trail.

unreal 5.8 packaging and deployment build, cook, stage, package, archive, deploy, release, and diagnose unreal engine 5.8 projects. use for build configurations and targets, unrealbuildtool, automationtool, buildcookrun, project launcher profiles, command-line cooks, cook inclusion, maps, pak or iostore containers, chunks, patches, dlc, platform sdks, plugins, runtime dependencies, configuration staging, signing and encryption, symbols, logs, crash reporting, ci artifacts, reproducible builds, missing cooked assets, packaging failures, or packaged-build differences. build configurations and targets build configurations and targets state configuration | configuration | use | important behavior | |---|---|---| | debug | engine and game debugging | no optimization; slow; source engine context | | debuggame | game-module debugging | game code unoptimized; engine remains optimized | | development | daily packaged testing and profiling | most optimization; console/tools available | | test | shipping-like qa with selected stats/profiling | shipping base with some diagnostic tools | | shipping | distribution candidate | full optimization; end-user console/stats stripped | shipping can still produce symbols. store them securely rather than assuming an optimized build is unsymbolicatable. target type - game: standalone executable requiring cooked target content. - editor: editor executable/module target; never a runtime distribution artifact. - client: multiplayer client target when <project>client.target.cs exists. - server: dedicated server target when <project>server.target.cs exists. record both dimensions, for example development game, test client, or shipping server. do not compare performance, config, modules, or cook output across unlike targets and call it an a/b test. use development first to retain logs/console/profile access, then repeat the release suite in test and shipping. verify exit ui and recovery paths that relied on a console during development. build, cook, stage, package, deploy build, cook, stage, package, deploy | phase | produces | diagnose here when | |---|---|---| | build | target binaries/modules | compile, link, module, architecture, or symbol failure | | cook | platform-ready assets/registry/shaders | serializer, asset, map, validation, ddc, or inclusion failure | | stage | runnable directory assembled from products | missing config, dll, movie, prerequisite, or wrong file class | | package | native distributable/container set | signing, compression, container, store-format failure | | deploy | copy/install to device | connection, account, capacity, permission, or install failure | | run | launched staged build | startup, default map, runtime dependency, config, or content failure | the standard packaging pipeline is executed by automationtool buildcookrun. use the editor for a quick smoke build, project launcher for a reviewable profile, and uat/buildgraph for ci. for an isolated cook, epic documents: text unrealeditor-cmd.exe <project.uproject> -run=cook -targetplatform=<platform> -map=<mapa>+<mapb> do not paste a generic release command blindly. create the intended project launcher profile, execute once, capture its generated buildcookrun command, then parameterize only project, platform, output, version, and credentials in ci. query the installed engine with runuat.bat buildcookrun -help before adding flags. archive outside the source tree. keep stage and archive paths unique per build identity so stale files cannot satisfy the next build accidentally. config, staging, and runtime dependencies config, staging, and runtime dependencies configuration ue config resolves through an ordered hierarchy: engine bases, platform bases, project defaults, platform project overrides, then user layers. diagnose the effective staged value, not one source file. - commit project defaults and deliberate platform overrides; - keep generated saved/config user/machine state out of release inputs; - use packaging ini key/section denylist for values that must not ship; - never put private signing, store, backend, or service secrets in staged client config; - verify maps, cultures, device profiles, scalability, online subsystem, and log settings in the artifact. game plugin config has a documented packaging caveat: plugin config files are not automatically packaged as an independent config layer. merge required runtime defaults into the project's config and validate the staged result. files outside assets use runtimedependencies in .build.cs for third-party libraries and staged files. choose: - ufs: accessed through unreal file apis and eligible for a container; - nonufs: loose file required by native/external io; - debugnonufs: loose debug file staged only when debug files are requested; - systemnonufs: loose system file outside normal remapping. dlls/shared libraries loaded by the os must remain loose. use the packaging settings for intentional non-asset directories only when build rules are not the right owner. verify license files, movies, certificates, prerequisites, and dynamic-library search paths on a clean machine. containers, chunks, patches, and dlc containers, chunks, patches, and dlc containers and chunks packaging settings can use pak files or iostore .utoc/.ucas containers. choose from platform and delivery requirements; verify mount, load, patch size, startup, io, and tooling on the target. asset manager rules/primary asset labels own content-to-chunk assignment. this skill owns generation, artifact inspection, delivery order, and release testing. audit shared dependencies and duplicate files; folder layout does not guarantee chunk ownership. design chunk 0 for content required before optional chunks are available. test missing, partial, delayed, wrong-version, and corrupted optional installs. never let core startup reference unavailable content. patch contract 1. retain the exact released binaries, containers, manifests, registry, config, keys, and version metadata. 2. build the patch against that base using the target platform's approved pipeline. 3. compare changed files/container blocks and investigate unexpected churn. 4. test base -> patch on a clean device; also test fresh full install at the patched version. 5. verify save migration, online compatibility, rollback policy, dlc entitlement, and disk-space behavior. compression, encryption, shader ordering, bulk-data changes, engine/toolchain changes, asset renames, and resaves can enlarge a patch. deterministic shader order may improve patch similarity while trading load behavior; measure both. platform stores own final patch/dlc constraints. do not infer console/mobile/store rules from a desktop pak example. cooking, inclusion, and validation cooking, inclusion, and validation define roots cook inclusion comes from maps, hard dependencies, asset manager rules, primary asset labels, explicitly configured directories/assets, plugins, or command-line/profile selections. a soft path alone does not prove inclusion. 1. set game default map and required maps explicitly. 2. identify every on-demand asset's owning primary asset/rule or other cook root. 3. run data validation and map check; use cook validation options when appropriate. 4. cook the exact target platform by the book. 5. inspect asset audit, cook/staging manifests, asset registry, container listing, and warnings. 6. run the cold path with no editor content or cook server. useful documented cook diagnostics include -verbosecookerwarnings, -runassetvalidation, -runmapvalidation, and -validationerrorsarefatal. confirm support against the installed 5.8 engine. avoid masking the cause - -cookall and cook everything increase size and can hide missing ownership. - broad additional asset directories to cook create implicit contracts that are hard to audit. - skipping soft/hard references is diagnostic and can create unloadable content. - iterative cooks accelerate iteration but can retain stale evidence; require a clean cook for release. - exclude editor content can expose an improper runtime dependency on editor content; fix the edge. treat warnings about unknown assets, redirectors, missing packages, shader formats, serialization, or never-cook conflicts as build defects until dispositioned. diagnostic recipes diagnostic recipes | symptom | first evidence | bounded next step | |---|---|---| | black screen at startup | game default map and runtime log | verify cooked map and staged effective config | | works in pie, asset missing packaged | cook root and manifest | trace owning map/primary asset/rule; clean target cook | | plugin module missing | target/module/plugin descriptor and binary | build exact target; remove editor-only/runtime mismatch | | dll/shared library missing | staged tree and os loader log | declare runtimedependencies; verify architecture/search path | | wrong config in package | staged effective ini/device profile | identify later hierarchy override; remove generated input | | cook succeeds, stage fails | uat phase boundary and staging manifest | inspect non-asset source path, permissions, disk, stale output | | shipping behaves unlike development | logs via test/diagnostic candidate | compare compiled flags, modules, config, timing, stripped tools | | package unexpectedly huge | container/chunk/file size report | rank largest additions and duplicate chunk ownership | | tiny change creates huge patch | retained base/delta manifests | inspect resaves, compression/encryption, shader order, tool changes | | crash has unreadable callstack | build id and symbol match | retrieve exact private symbols; never use rebuilt equivalents | | clean machine will not launch | os loader/prerequisite/platform log | verify prerequisites and loose runtime dependencies | | device platform unavailable | sdk/toolchain/platform component status | install supported version and re-run platform validation | after each fix, rerun the smallest failing phase, then the complete clean artifact and acceptance suite. plugins, sdks, and target platforms plugins, sdks, and target platforms plugins and modules for each enabled plugin, verify: - supported target platforms and architectures; - runtime versus editor/developer module type and loading phase; - source availability or matching prebuilt binaries; - cancontaincontent and cook inclusion when content is required; - dependencies declared in .uproject, .uplugin, and module rules; - third-party libraries staged through runtimedependencies; - shipping compile and startup with editor-only code excluded. disable unused plugins before the release branch stabilizes, then recook and run the full suite. a plugin that loads in editor can still lack a target binary, include an editor-only dependency, or omit content. platform readiness pin the engine-supported sdk, compiler/toolchain, platform extension, architecture, signing identity, entitlements/capabilities, device os, and store tooling. validate with the platform's setup checker and restricted documentation. some platforms require additional sdks/components; console packaging requires a source engine build according to epic's public ue 5.8 packaging guide. do not publish restricted platform paths, flags, certification rules, or keys into a general skill. route them to the authorized platform documentation and record only the verified outcome in private ci. release reproducibility and security release reproducibility and security candidate gate - clean source revision; recorded submodules/plugins and no undeclared local files; - pinned engine, sdk, compiler, build tools, platform extensions, and environment; - clean by-the-book cook/full rebuild according to release policy; - zero undispositioned validation/cook/package warnings; - expected maps, cultures, chunks, config, dependencies, prerequisites, and licenses; - artifact hash/size/build id, matching symbols, manifests, and retained base release; - automated smoke plus human target-device acceptance; - fresh install, upgrade/patch, uninstall/reinstall, low disk, offline, and permission tests; - save migration and online/backend compatibility verified; - exact candidate promoted without rebuild. security boundaries signing establishes artifact authenticity/integrity for its supported workflow; encryption limits casual content inspection. neither makes client code/data trusted. keep authoritative economy, entitlements, match results, and anti-cheat decisions server-side. store private keys outside source, artifacts, logs, profiles, and command history. rotate/revoke through the platform process. inspect staged config and loose files for credentials, internal urls, test accounts, debug endpoints, source paths, and unintended symbols. measure encrypted/compressed container startup, io, memory, build time, store size, and patch delta. ue 5.8 primary sources ue 5.8 primary sources - packaging your project - build operations: cook, package, deploy, and run - build configurations reference - content cooking - cooking and chunking - project launcher - project settings: packaging - configuration files - plugins - integrating third-party libraries - updating projects with patches - general patching information - crash reporting - versioning assets and packages pages were checked against ue 5.8 documentation on 2026-07-19. reconfirm platform sdk/toolchain requirements, uat arguments, container and patch workflows, packaging defaults, and store/certification rules after an engine or platform update. symbols, logs, and crash reporting symbols, logs, and crash reporting packaging failure preserve the full output log/uat log and exit code. search backward from the final automationtool summary for the first specific compiler, cooker, staging, signing, or platform error. later “unknown error” and cascade failures are usually not causal. record command, phase, asset/module/file, target, and the smallest rerun that reproduces it. delete only phase-appropriate generated output after preserving evidence; do not begin by deleting every cache. runtime failure use a development/test packaged build with logs, symbols, and the same content/config as shipping. capture: - project runtime log and platform/device log; - command line, map, account, locale, hardware, driver/os; - crash guid, callstacks, minidump/context, and build identity; - exact executable/modules and matching symbols. shipping symbols can be produced and retained without publicly staging them. symbolicate against the exact binary; symbols from a rebuild of the same source are not guaranteed to match. packaged games do not automatically send reports to epic. include/configure crash reporter only when a privacy-reviewed collection endpoint and consent policy exist. test offline, unattended, user-decline, upload failure, rate/size limits, pii redaction, and server symbolication. system selector system selector | need | primary surface | |---|---| | quick local packaged smoke test | platforms menu -> package project | | repeatable multi-step/device profile | project launcher custom launch profile | | unattended ci/release artifact | automationtool buildcookrun or buildgraph | | isolate content conversion | cook commandlet | | validate selected assets/maps during cook | cook validation flags plus validation reports | | content ownership/chunk assignment | asset manager/primary asset labels | | inspect staged non-assets/config | staging manifest and archive tree | | deploy/run on device | project launcher/automationtool plus platform tools | | symbolicate packaged crash | exact executable, symbols, build identity, crash context | | patch/dlc | retained base release plus platform delivery workflow | before acting, ask which phase produced the observed failure. “packaging” is not a phase-specific diagnosis. project launcher, uat, and ci project launcher, uat, and ci project launcher create named custom profiles for repeatable build, cook, package, deploy, and run choices. record: - project and target platform/device; - build configuration and target; - by-the-book versus on-the-fly cook; - maps/cultures/chunks/dlc/release version; - package/archive/deploy method; - command-line arguments and launch map. use its output log to capture the generated uat command. treat the profile as a reviewed specification, not the only record; engine/profile changes can alter generated flags. ci record persist for every candidate: text engine version + source changelist project commit and dirty-state policy uat command/profile export and environment sdk/toolchain/plugin versions full utf-8 log and exit code cook/stage/container manifests and warnings artifact hashes, sizes, build id, symbols test results and promotion decision fail on missing expected artifacts and selected warnings, not only a nonzero exit. make credentials ephemeral and redact logs. keep ddc/cache state observable: warm caches may change duration, never the intended output contract. promote an immutable artifact through qa/store lanes. rebuilding “the same commit” can change toolchain, sdk, generated data, timestamps, or dependencies.

Build configurations and targets

# Build configurations and targets

## State configuration

| Configuration | Use | Important behavior |
|---|---|---|
| Debug | engine and game debugging | no optimization; slow; source engine context |
| DebugGame | game-module debugging | game code unoptimized; engine remains optimized |
| Development | daily packaged testing and profiling | most optimization; console/tools available |
| Test | shipping-like QA with selected stats/profiling | Shipping base with some diagnostic tools |
| Shipping | distribution candidate | full optimization; end-user console/stats stripped |

Shipping can still produce symbols. Store them securely rather than assuming an optimized build is
unsymbolicatable.

## Target type

- **Game**: standalone executable requiring cooked target content.
- **Editor**: editor executable/module target; never a runtime distribution artifact.
- **Client**: multiplayer client target when `<Project>Client.Target.cs` exists.
- **Server**: dedicated server target when `<Project>Server.Target.cs` exists.

Record both dimensions, for example `Development Game`, `Test Client`, or `Shipping Server`. Do not
compare performance, config, modules, or cook output across unlike targets and call it an A/B test.

Use Development first to retain logs/console/profile access, then repeat the release suite in Test and
Shipping. Verify exit UI and recovery paths that relied on a console during development.

Build, cook, stage, package, deploy

# Build, cook, stage, package, deploy

| Phase | Produces | Diagnose here when |
|---|---|---|
| Build | target binaries/modules | compile, link, module, architecture, or symbol failure |
| Cook | platform-ready assets/registry/shaders | serializer, asset, map, validation, DDC, or inclusion failure |
| Stage | runnable directory assembled from products | missing config, DLL, movie, prerequisite, or wrong file class |
| Package | native distributable/container set | signing, compression, container, store-format failure |
| Deploy | copy/install to device | connection, account, capacity, permission, or install failure |
| Run | launched staged build | startup, default map, runtime dependency, config, or content failure |

The standard packaging pipeline is executed by AutomationTool `BuildCookRun`. Use the editor for a quick
smoke build, Project Launcher for a reviewable profile, and UAT/BuildGraph for CI.

For an isolated cook, Epic documents:

```text
UnrealEditor-Cmd.exe <Project.uproject> -run=cook -targetplatform=<Platform> -map=<MapA>+<MapB>
```

Do not paste a generic release command blindly. Create the intended Project Launcher profile, execute
once, capture its generated `BuildCookRun` command, then parameterize only project, platform, output,
version, and credentials in CI. Query the installed engine with `RunUAT.bat BuildCookRun -Help` before
adding flags.

Archive outside the source tree. Keep stage and archive paths unique per build identity so stale files
cannot satisfy the next build accidentally.

# Config, staging, and runtime dependencies

## Configuration

UE config resolves through an ordered hierarchy: engine bases, platform bases, project defaults,
platform project overrides, then user layers. Diagnose the effective staged value, not one source file.

- commit project defaults and deliberate platform overrides;
- keep generated `Saved/Config` user/machine state out of release inputs;
- use Packaging **Ini Key/Section Denylist** for values that must not ship;
- never put private signing, store, backend, or service secrets in staged client config;
- verify maps, cultures, device profiles, scalability, online subsystem, and log settings in the artifact.

Game plugin config has a documented packaging caveat: plugin config files are not automatically packaged
as an independent config layer. Merge required runtime defaults into the project's config and validate
the staged result.

## Files outside assets

Use `RuntimeDependencies` in `.Build.cs` for third-party libraries and staged files. Choose:

- `UFS`: accessed through Unreal file APIs and eligible for a container;
- `NonUFS`: loose file required by native/external IO;
- `DebugNonUFS`: loose debug file staged only when debug files are requested;
- `SystemNonUFS`: loose system file outside normal remapping.

DLLs/shared libraries loaded by the OS must remain loose. Use the packaging settings for intentional
non-asset directories only when build rules are not the right owner. Verify license files, movies,
certificates, prerequisites, and dynamic-library search paths on a clean machine.

Containers, chunks, patches, and DLC

# Containers, chunks, patches, and DLC

## Containers and chunks

Packaging settings can use Pak files or IoStore `.utoc`/`.ucas` containers. Choose from platform and
delivery requirements; verify mount, load, patch size, startup, IO, and tooling on the target.

Asset Manager rules/Primary Asset Labels own content-to-chunk assignment. This skill owns generation,
artifact inspection, delivery order, and release testing. Audit shared dependencies and duplicate files;
folder layout does not guarantee chunk ownership.

Design chunk 0 for content required before optional chunks are available. Test missing, partial, delayed,
wrong-version, and corrupted optional installs. Never let core startup reference unavailable content.

## Patch contract

1. Retain the exact released binaries, containers, manifests, registry, config, keys, and version metadata.
2. Build the patch against that base using the target platform's approved pipeline.
3. Compare changed files/container blocks and investigate unexpected churn.
4. Test base -> patch on a clean device; also test fresh full install at the patched version.
5. Verify save migration, online compatibility, rollback policy, DLC entitlement, and disk-space behavior.

Compression, encryption, shader ordering, bulk-data changes, engine/toolchain changes, asset renames, and
resaves can enlarge a patch. Deterministic shader order may improve patch similarity while trading load
behavior; measure both.

Platform stores own final patch/DLC constraints. Do not infer console/mobile/store rules from a desktop
Pak example.

Cooking, inclusion, and validation

# Cooking, inclusion, and validation

## Define roots

Cook inclusion comes from maps, hard dependencies, Asset Manager rules, Primary Asset Labels, explicitly
configured directories/assets, plugins, or command-line/profile selections. A soft path alone does not
prove inclusion.

1. Set Game Default Map and required maps explicitly.
2. Identify every on-demand asset's owning Primary Asset/rule or other cook root.
3. Run Data Validation and Map Check; use cook validation options when appropriate.
4. Cook the exact target platform By the Book.
5. Inspect Asset Audit, cook/staging manifests, Asset Registry, container listing, and warnings.
6. Run the cold path with no editor content or cook server.

Useful documented cook diagnostics include `-verbosecookerwarnings`, `-RunAssetValidation`,
`-RunMapValidation`, and `-ValidationErrorsAreFatal`. Confirm support against the installed 5.8 engine.

## Avoid masking the cause

- `-cookall` and **Cook Everything** increase size and can hide missing ownership.
- broad **Additional Asset Directories to Cook** create implicit contracts that are hard to audit.
- skipping soft/hard references is diagnostic and can create unloadable content.
- iterative cooks accelerate iteration but can retain stale evidence; require a clean cook for release.
- **Exclude Editor Content** can expose an improper runtime dependency on editor content; fix the edge.

Treat warnings about unknown assets, redirectors, missing packages, shader formats, serialization, or
never-cook conflicts as build defects until dispositioned.

Diagnostic recipes

# Diagnostic recipes

| Symptom | First evidence | Bounded next step |
|---|---|---|
| black screen at startup | Game Default Map and runtime log | verify cooked map and staged effective config |
| works in PIE, asset missing packaged | cook root and manifest | trace owning map/Primary Asset/rule; clean target cook |
| plugin module missing | target/module/plugin descriptor and binary | build exact target; remove editor-only/runtime mismatch |
| DLL/shared library missing | staged tree and OS loader log | declare `RuntimeDependencies`; verify architecture/search path |
| wrong config in package | staged effective ini/device profile | identify later hierarchy override; remove generated input |
| cook succeeds, stage fails | UAT phase boundary and staging manifest | inspect non-asset source path, permissions, disk, stale output |
| Shipping behaves unlike Development | logs via Test/diagnostic candidate | compare compiled flags, modules, config, timing, stripped tools |
| package unexpectedly huge | container/chunk/file size report | rank largest additions and duplicate chunk ownership |
| tiny change creates huge patch | retained base/delta manifests | inspect resaves, compression/encryption, shader order, tool changes |
| crash has unreadable callstack | build ID and symbol match | retrieve exact private symbols; never use rebuilt equivalents |
| clean machine will not launch | OS loader/prerequisite/platform log | verify prerequisites and loose runtime dependencies |
| device platform unavailable | SDK/toolchain/platform component status | install supported version and re-run platform validation |

After each fix, rerun the smallest failing phase, then the complete clean artifact and acceptance suite.

Plugins, SDKs, and target platforms

# Plugins, SDKs, and target platforms

## Plugins and modules

For each enabled plugin, verify:

- supported target platforms and architectures;
- runtime versus editor/developer module type and loading phase;
- source availability or matching prebuilt binaries;
- `CanContainContent` and cook inclusion when content is required;
- dependencies declared in `.uproject`, `.uplugin`, and module rules;
- third-party libraries staged through `RuntimeDependencies`;
- Shipping compile and startup with editor-only code excluded.

Disable unused plugins before the release branch stabilizes, then recook and run the full suite. A plugin
that loads in Editor can still lack a target binary, include an editor-only dependency, or omit content.

## Platform readiness

Pin the engine-supported SDK, compiler/toolchain, platform extension, architecture, signing identity,
entitlements/capabilities, device OS, and store tooling. Validate with the platform's setup checker and
restricted documentation. Some platforms require additional SDKs/components; console packaging requires
a source engine build according to Epic's public UE 5.8 packaging guide.

Do not publish restricted platform paths, flags, certification rules, or keys into a general skill.
Route them to the authorized platform documentation and record only the verified outcome in private CI.

Release reproducibility and security

# Release reproducibility and security

## Candidate gate

- clean source revision; recorded submodules/plugins and no undeclared local files;
- pinned engine, SDK, compiler, build tools, platform extensions, and environment;
- clean By-the-Book cook/full rebuild according to release policy;
- zero undispositioned validation/cook/package warnings;
- expected maps, cultures, chunks, config, dependencies, prerequisites, and licenses;
- artifact hash/size/build ID, matching symbols, manifests, and retained base release;
- automated smoke plus human target-device acceptance;
- fresh install, upgrade/patch, uninstall/reinstall, low disk, offline, and permission tests;
- save migration and online/backend compatibility verified;
- exact candidate promoted without rebuild.

## Security boundaries

Signing establishes artifact authenticity/integrity for its supported workflow; encryption limits casual
content inspection. Neither makes client code/data trusted. Keep authoritative economy, entitlements,
match results, and anti-cheat decisions server-side.

Store private keys outside source, artifacts, logs, profiles, and command history. Rotate/revoke through
the platform process. Inspect staged config and loose files for credentials, internal URLs, test accounts,
debug endpoints, source paths, and unintended symbols.

Measure encrypted/compressed container startup, IO, memory, build time, store size, and patch delta.

UE 5.8 primary sources

# UE 5.8 primary sources

- [Packaging Your Project](https://dev.epicgames.com/documentation/en-us/unreal-engine/packaging-your-project)
- [Build Operations: Cook, Package, Deploy, and Run](https://dev.epicgames.com/documentation/en-us/unreal-engine/build-operations-cooking-packaging-deploying-and-running-projects-in-unreal-engine)
- [Build Configurations Reference](https://dev.epicgames.com/documentation/en-us/unreal-engine/build-configurations-reference-for-unreal-engine)
- [Content Cooking](https://dev.epicgames.com/documentation/en-us/unreal-engine/cooking-content-in-unreal-engine)
- [Cooking and Chunking](https://dev.epicgames.com/documentation/en-us/unreal-engine/cooking-content-and-creating-chunks-in-unreal-engine)
- [Project Launcher](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-the-project-launcher-in-unreal-engine)
- [Project Settings: Packaging](https://dev.epicgames.com/documentation/en-us/unreal-engine/project-section-of-the-unreal-engine-project-settings)
- [Configuration Files](https://dev.epicgames.com/documentation/en-us/unreal-engine/configuration-files-in-unreal-engine)
- [Plugins](https://dev.epicgames.com/documentation/en-us/unreal-engine/plugins-in-unreal-engine)
- [Integrating Third-Party Libraries](https://dev.epicgames.com/documentation/en-us/unreal-engine/integrating-third-party-libraries-into-unreal-engine)
- [Updating Projects With Patches](https://dev.epicgames.com/documentation/en-us/unreal-engine/updating-unreal-engine-projects-with-patches-after-release)
- [General Patching Information](https://dev.epicgames.com/documentation/en-us/unreal-engine/general-patching-information-in-unreal-engine)
- [Crash Reporting](https://dev.epicgames.com/documentation/en-us/unreal-engine/crash-reporting-in-unreal-engine)
- [Versioning Assets and Packages](https://dev.epicgames.com/documentation/en-us/unreal-engine/versioning-of-assets-and-packages-in-unreal-engine)

Pages were checked against UE 5.8 documentation on 2026-07-19. Reconfirm platform SDK/toolchain
requirements, UAT arguments, container and patch workflows, packaging defaults, and store/certification
rules after an engine or platform update.

Symbols, logs, and crash reporting

# Symbols, logs, and crash reporting

## Packaging failure

Preserve the full Output Log/UAT log and exit code. Search backward from the final AutomationTool summary
for the first specific compiler, cooker, staging, signing, or platform error. Later “Unknown Error” and
cascade failures are usually not causal.

Record command, phase, asset/module/file, target, and the smallest rerun that reproduces it. Delete only
phase-appropriate generated output after preserving evidence; do not begin by deleting every cache.

## Runtime failure

Use a Development/Test packaged build with logs, symbols, and the same content/config as Shipping. Capture:

- project runtime log and platform/device log;
- command line, map, account, locale, hardware, driver/OS;
- crash GUID, callstacks, minidump/context, and build identity;
- exact executable/modules and matching symbols.

Shipping symbols can be produced and retained without publicly staging them. Symbolicate against the
exact binary; symbols from a rebuild of the same source are not guaranteed to match.

Packaged games do not automatically send reports to Epic. Include/configure Crash Reporter only when a
privacy-reviewed collection endpoint and consent policy exist. Test offline, unattended, user-decline,
upload failure, rate/size limits, PII redaction, and server symbolication.

System selector

# System selector

| Need | Primary surface |
|---|---|
| quick local packaged smoke test | Platforms menu -> Package Project |
| repeatable multi-step/device profile | Project Launcher custom launch profile |
| unattended CI/release artifact | AutomationTool `BuildCookRun` or BuildGraph |
| isolate content conversion | Cook commandlet |
| validate selected assets/maps during cook | cook validation flags plus validation reports |
| content ownership/chunk assignment | Asset Manager/Primary Asset Labels |
| inspect staged non-assets/config | staging manifest and archive tree |
| deploy/run on device | Project Launcher/AutomationTool plus platform tools |
| symbolicate packaged crash | exact executable, symbols, build identity, crash context |
| patch/DLC | retained base release plus platform delivery workflow |

Before acting, ask which phase produced the observed failure. “Packaging” is not a phase-specific
diagnosis.

Project Launcher, UAT, and CI

# Project Launcher, UAT, and CI

## Project Launcher

Create named custom profiles for repeatable build, cook, package, deploy, and run choices. Record:

- project and target platform/device;
- build configuration and target;
- By-the-Book versus On-the-Fly cook;
- maps/cultures/chunks/DLC/release version;
- package/archive/deploy method;
- command-line arguments and launch map.

Use its Output Log to capture the generated UAT command. Treat the profile as a reviewed specification,
not the only record; engine/profile changes can alter generated flags.

## CI record

Persist for every candidate:

```text
engine version + source changelist
project commit and dirty-state policy
UAT command/profile export and environment
SDK/toolchain/plugin versions
full UTF-8 log and exit code
cook/stage/container manifests and warnings
artifact hashes, sizes, build ID, symbols
test results and promotion decision
```

Fail on missing expected artifacts and selected warnings, not only a nonzero exit. Make credentials
ephemeral and redact logs. Keep DDC/cache state observable: warm caches may change duration, never the
intended output contract.

Promote an immutable artifact through QA/store lanes. Rebuilding “the same commit” can change toolchain,
SDK, generated data, timestamps, or dependencies.