{"slug":"unreal-animation-blending","name":"unreal-animation-blending","title":"Unreal 5.8 Animation Blending","description":"Select, implement, tune, and debug character animation blending in Unreal Engine 5.8. Use for Animation Blueprints, Blend Spaces, state transitions, inertialization, sync groups and markers, layered blends per bone, additive animation, Aim Offsets, Montages and Slots, locomotion, upper-body actions, hit reactions, foot-phase problems, or animation popping.","shortDescription":"Build and debug animation blends in UE 5.8","category":"Animation","referenceCount":6,"rawMarkdown":"---\nname: unreal-animation-blending\ndescription: Select, implement, tune, and debug character animation blending in Unreal Engine 5.8. Use for Animation Blueprints, Blend Spaces, state transitions, inertialization, sync groups and markers, layered blends per bone, additive animation, Aim Offsets, Montages and Slots, locomotion, upper-body actions, hit reactions, foot-phase problems, or animation popping.\n---\n\n# Unreal 5.8 Animation Blending\n\n## Ownership boundary\n\nThis skill owns final AnimGraph composition, base locomotion, transitions, phase synchronization,\nadditives, and regional layering. Route bounded action sections/cancel windows to\n[`unreal-animation-montages`](../unreal-animation-montages/SKILL.md), pose-search selection to\n[`unreal-motion-matching`](../unreal-motion-matching/SKILL.md), and any defect already visible in an\nIK Retargeter preview/export to [`unreal-control-rig-ik`](../unreal-control-rig-ik/SKILL.md).\n\n## Select the mechanism before building the graph\n\nRead [`references/method-selector.md`](references/method-selector.md).\n\n- Continuous values → Blend Space.\n- Discrete persistent modes → State Machine.\n- Simple Boolean/enum/int choice → Blend Poses node.\n- Simultaneous body regions → Layered Blend per Bone or Blend Mask.\n- Relative motion layered over a base → additive animation / Aim Offset.\n- Gameplay-triggered authored action → Montage + Slot.\n- Cycles that must preserve phase → Sync Group + matching Sync Markers.\n- Short natural transition with source evaluation no longer needed → Inertialization.\n\nDo not solve every animation problem with more states or longer crossfades.\n\n## Execute\n\n1. Define gameplay state and animation variables outside the final pose graph.\n2. Choose the smallest mechanism that matches the behavior.\n3. Establish phase, root-motion, additive-space, and Slot assumptions.\n4. Implement base locomotion before overlays.\n5. Add transition logic and explicit blend behavior.\n6. Validate notifies, root motion, sync markers, interruptions, and network behavior.\n7. Profile graph evaluation and confirm thread-safe data access.\n\nRead:\n\n- [`references/locomotion.md`](references/locomotion.md) for Blend Space and phase setup.\n- [`references/layering-and-actions.md`](references/layering-and-actions.md) for upper-body,\n  additive, montage, and hit-reaction patterns.\n- [`references/transitions-and-sync.md`](references/transitions-and-sync.md) for state\n  transitions, inertialization, and markers.\n- [`references/troubleshooting.md`](references/troubleshooting.md) for visible failures.\n\n## Required answer format\n\nReturn:\n\n1. **Chosen blend mechanism** and rejected alternatives.\n2. **Required assets and assumptions**: Skeleton, additive type, root motion, markers.\n3. **AnimGraph/state-machine node order**.\n4. **Variables and how to calculate them**.\n5. **Blend durations/curves as a tuning procedure**, not invented universal numbers.\n6. **Notify, interruption, root-motion, and network consequences**.\n7. **Debug and acceptance checks**.\n\n## Hard rules\n\n- Use Sync Markers for foot-phase alignment when length syncing is insufficient.\n- Only markers common to every animation in a Sync Group participate.\n- Keep inertialization blends short; UE guidance recommends under 0.4 seconds.\n- Do not use inertialization for extremely different poses.\n- Source animation evaluation and its future Notifies stop when inertialization begins.\n- Treat Dead Blending as experimental in UE 5.8; do not make it a shipping dependency.\n- Place inertialization after the nodes requesting it and generally before final IK.\n- Use Layered Blend per Bone for regional overrides; use additive poses for deltas.\n- Use Montages for event-driven actions, not the permanent locomotion state graph.\n- Verify montage/root-motion authority and RPC behavior in networked games.\n\nSee [`references/sources.md`](references/sources.md) for the UE 5.8 source trail.\n","webMarkdown":"## Ownership boundary\n\nThis skill owns final AnimGraph composition, base locomotion, transitions, phase synchronization,\nadditives, and regional layering. Route bounded action sections/cancel windows to\n[`unreal-animation-montages`](/unreal/unreal-animation-montages/), pose-search selection to\n[`unreal-motion-matching`](/unreal/unreal-motion-matching/), and any defect already visible in an\nIK Retargeter preview/export to [`unreal-control-rig-ik`](/unreal/unreal-control-rig-ik/).\n\n## Select the mechanism before building the graph\n\nRead [`references/method-selector.md`](/unreal/unreal-animation-blending/method-selector/).\n\n- Continuous values → Blend Space.\n- Discrete persistent modes → State Machine.\n- Simple Boolean/enum/int choice → Blend Poses node.\n- Simultaneous body regions → Layered Blend per Bone or Blend Mask.\n- Relative motion layered over a base → additive animation / Aim Offset.\n- Gameplay-triggered authored action → Montage + Slot.\n- Cycles that must preserve phase → Sync Group + matching Sync Markers.\n- Short natural transition with source evaluation no longer needed → Inertialization.\n\nDo not solve every animation problem with more states or longer crossfades.\n\n## Execute\n\n1. Define gameplay state and animation variables outside the final pose graph.\n2. Choose the smallest mechanism that matches the behavior.\n3. Establish phase, root-motion, additive-space, and Slot assumptions.\n4. Implement base locomotion before overlays.\n5. Add transition logic and explicit blend behavior.\n6. Validate notifies, root motion, sync markers, interruptions, and network behavior.\n7. Profile graph evaluation and confirm thread-safe data access.\n\nRead:\n\n- [`references/locomotion.md`](/unreal/unreal-animation-blending/locomotion/) for Blend Space and phase setup.\n- [`references/layering-and-actions.md`](/unreal/unreal-animation-blending/layering-and-actions/) for upper-body,\n  additive, montage, and hit-reaction patterns.\n- [`references/transitions-and-sync.md`](/unreal/unreal-animation-blending/transitions-and-sync/) for state\n  transitions, inertialization, and markers.\n- [`references/troubleshooting.md`](/unreal/unreal-animation-blending/troubleshooting/) for visible failures.\n\n## Required answer format\n\nReturn:\n\n1. **Chosen blend mechanism** and rejected alternatives.\n2. **Required assets and assumptions**: Skeleton, additive type, root motion, markers.\n3. **AnimGraph/state-machine node order**.\n4. **Variables and how to calculate them**.\n5. **Blend durations/curves as a tuning procedure**, not invented universal numbers.\n6. **Notify, interruption, root-motion, and network consequences**.\n7. **Debug and acceptance checks**.\n\n## Hard rules\n\n- Use Sync Markers for foot-phase alignment when length syncing is insufficient.\n- Only markers common to every animation in a Sync Group participate.\n- Keep inertialization blends short; UE guidance recommends under 0.4 seconds.\n- Do not use inertialization for extremely different poses.\n- Source animation evaluation and its future Notifies stop when inertialization begins.\n- Treat Dead Blending as experimental in UE 5.8; do not make it a shipping dependency.\n- Place inertialization after the nodes requesting it and generally before final IK.\n- Use Layered Blend per Bone for regional overrides; use additive poses for deltas.\n- Use Montages for event-driven actions, not the permanent locomotion state graph.\n- Verify montage/root-motion authority and RPC behavior in networked games.\n\nSee [`references/sources.md`](/unreal/unreal-animation-blending/sources/) for the UE 5.8 source trail.\n","searchText":"unreal 5.8 animation blending select, implement, tune, and debug character animation blending in unreal engine 5.8. use for animation blueprints, blend spaces, state transitions, inertialization, sync groups and markers, layered blends per bone, additive animation, aim offsets, montages and slots, locomotion, upper-body actions, hit reactions, foot-phase problems, or animation popping. layering and action patterns layering and action patterns run while firing asset setup: 1. create firing animation montage. 2. create/use an upperbody slot. 3. put the montage sequence on that slot. animgraph order: 1. evaluate locomotion state machine / blend space. 2. save cached pose locomotion. 3. feed cached pose to the slot as the base. 4. feed original cached pose to layered blend per bone base pose. 5. feed slot result to a blend pose. 6. start branch filter at the intended spine bone or use an authored blend mask. 7. output the layered result. 8. apply final ik after blending unless the design requires regional ik first. verify pelvis ownership, shoulder seam, weapon alignment, aim offset order, and montage blend out while moving. reload while moving - use a montage section for each authored phase only when gameplay may branch/interupt. - use notifies/notify states for magazine detach/attach, hand ik windows, and gameplay state changes. - use branching point only for frame-critical gameplay decisions; queued notifies are cheaper. - set trigger weight threshold so barely weighted outgoing animation does not fire unwanted events. - define interruption behavior: retain old magazine, commit reload, or roll back. full-body attack - use full-body slot/montage when attack owns the whole pose. - decide in-place versus root motion before graph work. - gate locomotion visually and mechanically from the same gameplay state. - use sections for combo windows and branching. - put authoritative damage windows in gameplay logic driven by well-defined notify or ability events; test interruption and network authority. additive recoil 1. confirm recoil clip is authored as additive against the intended reference pose. 2. evaluate base locomotion/aim pose. 3. apply additive recoil with an alpha driven by gameplay/curve. 4. apply before or after upper-body regional masking based on which bones should receive recoil. 5. filter lower-body bones if required. 6. verify repeated firing does not accumulate pose error. hit reaction choose: - additive directional reaction for small impulses that preserve current action; - layered blend per bone for regional override; - montage for authored full/partial-body reaction with timing and interruption; - physics/ragdoll only when pose animation is no longer the correct model. drive direction from hit vector transformed into character local space. ensure a high- priority reaction does not silently cancel required gameplay montages in the same slot group. multiple slots - same slot and slot group: later/active montage overrides competing playback. - different body regions: use separate slots and combine explicitly in animgraph. - keep sequence lengths aligned when multiple slots in one montage must stay synchronized. - document slot ownership so abilities do not fight over unnamed defaults. child montages use child montages for weapon/character animation variants that retain parent sections, notifies, and logic. replace compatible animation segments; verify automatic play-rate adjustment does not create implausible motion. locomotion patterns locomotion patterns 1d idle/walk/run blend space assets: - compatible idle, walk, and run/sprint sequences; - same skeleton and consistent forward axis; - compatible gait start phase where possible. setup: 1. create blend space 1d for the skeleton. 2. name axis speed; use cm/s to match character movement velocity. 3. set axis min/max to the actual locomotion range. 4. place idle at zero and gait samples at their authored travel speeds. 5. drive from horizontal velocity magnitude, not full 3d velocity if falling should not increase locomotion speed. 6. add axis smoothing only to remove noisy input; do not use it to hide incorrect acceleration or bad sample speeds. 7. put compatible gait clips in the same sync group. 8. add matching left/right foot sync markers when phase drift is visible. 2d strafe blend space common axes: - speed and local-space direction, or - local forward velocity and local right velocity. procedure: 1. transform world velocity into character/mesh local space. 2. match axis ranges to actual movement limits. 3. place forward/back/left/right/diagonal samples according to authored direction. 4. preview corners and diagonals, not only axis centers. 5. validate foot phase across neighboring samples. 6. if diagonal speed differs mechanically, drive the blend space with actual local velocity rather than normalized input. starts, stops, and pivots - keep simple locomotion in a looping blend space. - add start/stop/pivot states when acceleration direction, planted foot, or authored anticipation materially changes the pose. - use marker-based sync for run-to-stop or walk-to-run transitions when phases differ. - set start/stop animations to an appropriate leader role when they must define phase. - use transition rules from movement state, acceleration, direction delta, and time remaining—not arbitrary delays alone. aim offset over locomotion 1. author/convert directional aim samples as mesh-space additive. 2. create aim offset with yaw/pitch axes. 3. feed locomotion cached pose into the aim offset base pose. 4. compute aim delta relative to character/mesh facing. 5. clamp/wrap yaw and pitch to authored limits. 6. layer weapon recoil after or within the aim layer according to desired space. 7. verify spine/shoulder deformation at extreme corners. root motion choice - in-place locomotion: character/mover movement is authoritative; animation visualizes it. - root-motion action: animation drives movement for the action; use montages for the common networked path. - enabling root motion from everything moves animgraph evaluation to the game thread; profile before choosing it broadly. - verify capsule/mesh agreement, movement mode, slopes, falling behavior, replication, and correction. evaluation checks - no foot sliding at authored sample speeds. - no phase double-step during walk/run blends. - direction changes do not collapse knees or twist pelvis. - acceleration/deceleration visual timing matches movement. - falling does not feed incorrect speed/direction into grounded locomotion. - network correction does not repeatedly restart or desynchronize gait. method selector method selector | problem | primary mechanism | why | common misuse | |---|---|---|---| | idle/walk/run over speed | blend space 1d | one continuous axis | separate state per speed | | strafing over speed and direction | blend space 2d | two continuous axes | unsynced directional clips | | aim/look over yaw and pitch | aim offset | mesh-space additive directional pose | ordinary non-additive blend space | | grounded/falling/swimming/climbing modes | state machine | persistent discrete states and transitions | boolean blend web in main animgraph | | weapon equipped/unequipped | blend poses by bool/enum or linked layer | small discrete variant | duplicating the entire locomotion machine | | run while firing/reloading | montage slot + layered blend per bone | event action over lower-body base | full-body montage when legs must continue | | recoil/breathing/lean | additive pose | relative delta over base pose | treating additive clip as full pose | | walk/run cycles drift out of foot phase | sync group + sync markers | aligns named gait events | longer blend duration | | abrupt short transition between similar moving poses | inertialization | carries outgoing motion without continued source evaluation | using it between radically different poses | | one-off attack/combo with sections | montage | controlled sequence, sections, notifies, slots | large state-machine branch | | different bones need different transition rates | blend profile | per-bone transition weighting | multiple arbitrary transition nodes | | complex reusable body-mode graph | linked anim layer / linked anim graph | modular graph ownership | copy-pasted graphs | decision tests blend space use when the desired pose is a smooth function of one or two measured values. inputs must have meaningful units and ranges. samples should represent comparable motion and compatible phase. state machine use when the animation mode persists and entry/exit rules matter. keep gameplay truth outside the state machine; let transitions consume stable variables. montage use when gameplay explicitly starts/stops/branches an authored action. use sections for combos or loops and slots for body-region application. same-slot sequences override one another. layered blend per bone use for regional full-pose overrides. select branch filter or blend mask deliberately. define the first affected bone and verify all descendants. use mesh-space rotation blend when local-space composition produces shoulder/spine artifacts, then recheck cost and visual result. additive use when the clip represents a delta from a known reference pose. confirm local-space or mesh-space additive setup and reference pose before blaming the graph. inertialization use for short transitions where preserving outgoing velocity matters more than continuing to evaluate the source clip. keep standard crossfade when source notifies or exact source phase must remain active through the transition. ue 5.8 primary sources ue 5.8 primary sources - epic games, blending animations - epic games, animation blueprint blend nodes - epic games, blend spaces - epic games, blend spaces in animation blueprints - epic games, state machines - epic games, transition rules - epic games, animation sync groups - epic games, animation notifies - epic games, using layered animations - epic games, animation montages - epic games, root motion version target: unreal engine 5.8. recheck node stability, experimental status, and threading behavior before using this skill with a later engine version. transitions, sync, and inertialization transitions, sync, and inertialization standard state transition 1. build one directional transition for each allowed direction. 2. base the rule on stable gameplay/movement variables. 3. set priority order when multiple transitions can be true; smaller number wins. 4. choose duration and curve from the visible motion, then test interruptions. 5. use blend profile when body regions should settle at different rates. 6. use shared transition/crossfade settings only when editing one should intentionally change all users. 7. do not enable bidirectional; ue 5.8 documentation marks it unsupported. for non-looping exit: - use relevant animation time remaining or automatic rule based on sequence player. - mark unrelated players ignore for relevancy test when they would corrupt the query. - test with altered play rate. sync groups use for animations representing the same cyclical action at different rates. 1. give compatible nodes the same group name. 2. set method to sync group, or graph when sync is propagated by graph structure. 3. choose group role deliberately; highest-weight animation is leader by default. 4. ensure clips begin with compatible body phase. 5. avoid drastic clip-length differences that create play-rate pops. marker-based sync 1. add shared markers such as leftfootdown and rightfootdown to every gait clip. 2. put animations in the same sync group. 3. ensure marker spelling and order match. 4. remember: only markers common to all animations in the group are used. 5. if no matching markers exist, ue falls back to length-based syncing. 6. set start/stop clips as leader where they must control the transition phase. inertialization setup: 1. set compatible transition/blend node transition type to inertialization. 2. add one inertialization node after all request sources it should serve. 3. place it near output pose to consolidate requests where appropriate. 4. apply before final ik in the common whole-body path. 5. keep requested blend under 0.4 seconds and test shorter first. use when: - outgoing pose is still moving; - poses are reasonably compatible; - rapid natural settling is desired; - source clip no longer needs evaluation. avoid when: - poses are extremely different; - source notifies must still fire after transition begins; - continuous interruptions degrade quality; - exact crossfade sampling is required. when multiple requests occur, ue uses the minimum requested duration. dead blending dead blending predicts outgoing motion and may handle large differences better, but ue 5.8 labels the node experimental and does not recommend shipping projects that depend on it. use only for evaluation with an explicit inertialization/standard-blend fallback. troubleshooting troubleshooting | symptom | likely cause | action | |---|---|---| | feet double-step during blend | gait clips out of phase | add matching sync group and foot markers | | feet slide at steady speed | sample authored speed differs from movement speed | place sample at measured speed; use stride/play-rate solution deliberately | | pop entering state | pose discontinuity, zero/short blend, bad reference pose | inspect source/target poses; tune crossfade/profile or use compatible inertialization | | inertialization logs runtime error | request exists without downstream node | add inertialization after request source | | important source notify never fires | inertialization stops source evaluation | use standard blend or move gameplay event ownership | | inertial blend looks stiff/broken | poses too different or repeated interruptions | use standard/custom blend; reduce interruptions | | upper body action moves legs | branch root too high/low or wrong blend mask | inspect affected hierarchy and blend depth/mask | | shoulder/spine twists | local-space regional rotation composition | test mesh-space rotation blend; fix additive/reference setup | | aim offset explodes at extremes | samples not mesh-space additive or bad axis/wrap | correct additive setup; clamp/wrap inputs; inspect corner samples | | montage does not appear | slot node absent/wrong slot or slot group conflict | add matching slot to animgraph; inspect competing montages | | montage cancels another action | same slot group owns both | separate ownership/slots or define priority/cancel policy | | transition chooses wrong path | competing true rules / priority | set explicit priority order and simplify state truth | | time remaining is wrong | multiple relevant players | enable ignore for relevancy test on unrelated players | | notifies fire from tiny blend weight | trigger weight threshold too low | raise threshold and test blend edges | | network root motion diverges | montage/rpc/authority mismatch | make gameplay authoritative; replicate montage trigger and verify correction | | returning state resumes midway | always reset on entry disabled | enable when restart is intended; leave disabled only for resume behavior | debug sequence 1. inspect live animation blueprint and active state weights. 2. display relevant variables: speed, local direction, movement mode, action state. 3. preview blend space at actual runtime coordinates. 4. inspect sync group leader/follower and marker names. 5. temporarily bypass overlays to isolate base locomotion. 6. re-enable slot, additive, regional blend, and ik one stage at a time. 7. inspect montage instance, slot group, sections, and blend weights. 8. test interruption at start, midpoint, and blend out. 9. test low frame rate and network latency where applicable. acceptance checks - phase remains stable across gait blends. - no visible pop at normal or interrupted transitions. - regional actions affect only intended bones. - gameplay events fire exactly once at the intended authority. - root motion and capsule remain aligned. - graph remains understandable and does not duplicate persistent gameplay truth.","references":[{"slug":"layering-and-actions","file":"layering-and-actions.md","title":"Layering and action patterns","rawMarkdown":"# Layering and action patterns\n\n## Run while firing\n\nAsset setup:\n\n1. Create firing Animation Montage.\n2. Create/use an `UpperBody` Slot.\n3. Put the Montage sequence on that Slot.\n\nAnimGraph order:\n\n1. Evaluate locomotion State Machine / Blend Space.\n2. Save Cached Pose `Locomotion`.\n3. Feed cached pose to the Slot as the base.\n4. Feed original cached pose to Layered Blend per Bone Base Pose.\n5. Feed Slot result to a Blend Pose.\n6. Start branch filter at the intended spine bone or use an authored Blend Mask.\n7. Output the layered result.\n8. Apply final IK after blending unless the design requires regional IK first.\n\nVerify pelvis ownership, shoulder seam, weapon alignment, aim offset order, and Montage\nblend out while moving.\n\n## Reload while moving\n\n- Use a Montage Section for each authored phase only when gameplay may branch/interupt.\n- Use Notifies/Notify States for magazine detach/attach, hand IK windows, and gameplay\n  state changes.\n- Use Branching Point only for frame-critical gameplay decisions; queued notifies are\n  cheaper.\n- Set Trigger Weight Threshold so barely weighted outgoing animation does not fire\n  unwanted events.\n- Define interruption behavior: retain old magazine, commit reload, or roll back.\n\n## Full-body attack\n\n- Use full-body Slot/Montage when attack owns the whole pose.\n- Decide in-place versus root motion before graph work.\n- Gate locomotion visually and mechanically from the same gameplay state.\n- Use Sections for combo windows and branching.\n- Put authoritative damage windows in gameplay logic driven by well-defined notify or\n  ability events; test interruption and network authority.\n\n## Additive recoil\n\n1. Confirm recoil clip is authored as additive against the intended reference pose.\n2. Evaluate base locomotion/aim pose.\n3. Apply additive recoil with an alpha driven by gameplay/curve.\n4. Apply before or after upper-body regional masking based on which bones should receive\n   recoil.\n5. Filter lower-body bones if required.\n6. Verify repeated firing does not accumulate pose error.\n\n## Hit reaction\n\nChoose:\n\n- additive directional reaction for small impulses that preserve current action;\n- Layered Blend per Bone for regional override;\n- Montage for authored full/partial-body reaction with timing and interruption;\n- physics/ragdoll only when pose animation is no longer the correct model.\n\nDrive direction from hit vector transformed into character local space. Ensure a high-\npriority reaction does not silently cancel required gameplay Montages in the same Slot\nGroup.\n\n## Multiple Slots\n\n- Same Slot and Slot Group: later/active Montage overrides competing playback.\n- Different body regions: use separate Slots and combine explicitly in AnimGraph.\n- Keep sequence lengths aligned when multiple Slots in one Montage must stay synchronized.\n- Document Slot ownership so abilities do not fight over unnamed defaults.\n\n## Child Montages\n\nUse Child Montages for weapon/character animation variants that retain parent Sections,\nNotifies, and logic. Replace compatible animation segments; verify automatic play-rate\nadjustment does not create implausible motion.\n","webMarkdown":"## Run while firing\n\nAsset setup:\n\n1. Create firing Animation Montage.\n2. Create/use an `UpperBody` Slot.\n3. Put the Montage sequence on that Slot.\n\nAnimGraph order:\n\n1. Evaluate locomotion State Machine / Blend Space.\n2. Save Cached Pose `Locomotion`.\n3. Feed cached pose to the Slot as the base.\n4. Feed original cached pose to Layered Blend per Bone Base Pose.\n5. Feed Slot result to a Blend Pose.\n6. Start branch filter at the intended spine bone or use an authored Blend Mask.\n7. Output the layered result.\n8. Apply final IK after blending unless the design requires regional IK first.\n\nVerify pelvis ownership, shoulder seam, weapon alignment, aim offset order, and Montage\nblend out while moving.\n\n## Reload while moving\n\n- Use a Montage Section for each authored phase only when gameplay may branch/interupt.\n- Use Notifies/Notify States for magazine detach/attach, hand IK windows, and gameplay\n  state changes.\n- Use Branching Point only for frame-critical gameplay decisions; queued notifies are\n  cheaper.\n- Set Trigger Weight Threshold so barely weighted outgoing animation does not fire\n  unwanted events.\n- Define interruption behavior: retain old magazine, commit reload, or roll back.\n\n## Full-body attack\n\n- Use full-body Slot/Montage when attack owns the whole pose.\n- Decide in-place versus root motion before graph work.\n- Gate locomotion visually and mechanically from the same gameplay state.\n- Use Sections for combo windows and branching.\n- Put authoritative damage windows in gameplay logic driven by well-defined notify or\n  ability events; test interruption and network authority.\n\n## Additive recoil\n\n1. Confirm recoil clip is authored as additive against the intended reference pose.\n2. Evaluate base locomotion/aim pose.\n3. Apply additive recoil with an alpha driven by gameplay/curve.\n4. Apply before or after upper-body regional masking based on which bones should receive\n   recoil.\n5. Filter lower-body bones if required.\n6. Verify repeated firing does not accumulate pose error.\n\n## Hit reaction\n\nChoose:\n\n- additive directional reaction for small impulses that preserve current action;\n- Layered Blend per Bone for regional override;\n- Montage for authored full/partial-body reaction with timing and interruption;\n- physics/ragdoll only when pose animation is no longer the correct model.\n\nDrive direction from hit vector transformed into character local space. Ensure a high-\npriority reaction does not silently cancel required gameplay Montages in the same Slot\nGroup.\n\n## Multiple Slots\n\n- Same Slot and Slot Group: later/active Montage overrides competing playback.\n- Different body regions: use separate Slots and combine explicitly in AnimGraph.\n- Keep sequence lengths aligned when multiple Slots in one Montage must stay synchronized.\n- Document Slot ownership so abilities do not fight over unnamed defaults.\n\n## Child Montages\n\nUse Child Montages for weapon/character animation variants that retain parent Sections,\nNotifies, and logic. Replace compatible animation segments; verify automatic play-rate\nadjustment does not create implausible motion.\n","searchText":"layering and action patterns run while firing asset setup: 1. create firing animation montage. 2. create/use an upperbody slot. 3. put the montage sequence on that slot. animgraph order: 1. evaluate locomotion state machine / blend space. 2. save cached pose locomotion. 3. feed cached pose to the slot as the base. 4. feed original cached pose to layered blend per bone base pose. 5. feed slot result to a blend pose. 6. start branch filter at the intended spine bone or use an authored blend mask. 7. output the layered result. 8. apply final ik after blending unless the design requires regional ik first. verify pelvis ownership, shoulder seam, weapon alignment, aim offset order, and montage blend out while moving. reload while moving - use a montage section for each authored phase only when gameplay may branch/interupt. - use notifies/notify states for magazine detach/attach, hand ik windows, and gameplay state changes. - use branching point only for frame-critical gameplay decisions; queued notifies are cheaper. - set trigger weight threshold so barely weighted outgoing animation does not fire unwanted events. - define interruption behavior: retain old magazine, commit reload, or roll back. full-body attack - use full-body slot/montage when attack owns the whole pose. - decide in-place versus root motion before graph work. - gate locomotion visually and mechanically from the same gameplay state. - use sections for combo windows and branching. - put authoritative damage windows in gameplay logic driven by well-defined notify or ability events; test interruption and network authority. additive recoil 1. confirm recoil clip is authored as additive against the intended reference pose. 2. evaluate base locomotion/aim pose. 3. apply additive recoil with an alpha driven by gameplay/curve. 4. apply before or after upper-body regional masking based on which bones should receive recoil. 5. filter lower-body bones if required. 6. verify repeated firing does not accumulate pose error. hit reaction choose: - additive directional reaction for small impulses that preserve current action; - layered blend per bone for regional override; - montage for authored full/partial-body reaction with timing and interruption; - physics/ragdoll only when pose animation is no longer the correct model. drive direction from hit vector transformed into character local space. ensure a high- priority reaction does not silently cancel required gameplay montages in the same slot group. multiple slots - same slot and slot group: later/active montage overrides competing playback. - different body regions: use separate slots and combine explicitly in animgraph. - keep sequence lengths aligned when multiple slots in one montage must stay synchronized. - document slot ownership so abilities do not fight over unnamed defaults. child montages use child montages for weapon/character animation variants that retain parent sections, notifies, and logic. replace compatible animation segments; verify automatic play-rate adjustment does not create implausible motion."},{"slug":"locomotion","file":"locomotion.md","title":"Locomotion patterns","rawMarkdown":"# Locomotion patterns\n\n## 1D idle/walk/run Blend Space\n\nAssets:\n\n- compatible idle, walk, and run/sprint sequences;\n- same Skeleton and consistent forward axis;\n- compatible gait start phase where possible.\n\nSetup:\n\n1. Create Blend Space 1D for the Skeleton.\n2. Name axis `Speed`; use cm/s to match Character Movement velocity.\n3. Set axis min/max to the actual locomotion range.\n4. Place idle at zero and gait samples at their authored travel speeds.\n5. Drive from horizontal velocity magnitude, not full 3D velocity if falling should not\n   increase locomotion speed.\n6. Add axis smoothing only to remove noisy input; do not use it to hide incorrect\n   acceleration or bad sample speeds.\n7. Put compatible gait clips in the same Sync Group.\n8. Add matching left/right foot Sync Markers when phase drift is visible.\n\n## 2D strafe Blend Space\n\nCommon axes:\n\n- `Speed` and local-space `Direction`, or\n- local forward velocity and local right velocity.\n\nProcedure:\n\n1. Transform world velocity into character/mesh local space.\n2. Match axis ranges to actual movement limits.\n3. Place forward/back/left/right/diagonal samples according to authored direction.\n4. Preview corners and diagonals, not only axis centers.\n5. Validate foot phase across neighboring samples.\n6. If diagonal speed differs mechanically, drive the Blend Space with actual local\n   velocity rather than normalized input.\n\n## Starts, stops, and pivots\n\n- Keep simple locomotion in a looping Blend Space.\n- Add start/stop/pivot states when acceleration direction, planted foot, or authored\n  anticipation materially changes the pose.\n- Use marker-based sync for run-to-stop or walk-to-run transitions when phases differ.\n- Set start/stop animations to an appropriate leader role when they must define phase.\n- Use transition rules from movement state, acceleration, direction delta, and time\n  remaining—not arbitrary delays alone.\n\n## Aim Offset over locomotion\n\n1. Author/convert directional aim samples as mesh-space additive.\n2. Create Aim Offset with yaw/pitch axes.\n3. Feed locomotion cached pose into the Aim Offset base pose.\n4. Compute aim delta relative to character/mesh facing.\n5. Clamp/wrap yaw and pitch to authored limits.\n6. Layer weapon recoil after or within the aim layer according to desired space.\n7. Verify spine/shoulder deformation at extreme corners.\n\n## Root motion choice\n\n- In-place locomotion: Character/Mover movement is authoritative; animation visualizes it.\n- Root-motion action: animation drives movement for the action; use Montages for the\n  common networked path.\n- Enabling Root Motion from Everything moves AnimGraph evaluation to the Game Thread;\n  profile before choosing it broadly.\n- Verify capsule/mesh agreement, movement mode, slopes, falling behavior, replication,\n  and correction.\n\n## Evaluation checks\n\n- No foot sliding at authored sample speeds.\n- No phase double-step during walk/run blends.\n- Direction changes do not collapse knees or twist pelvis.\n- Acceleration/deceleration visual timing matches movement.\n- Falling does not feed incorrect speed/direction into grounded locomotion.\n- Network correction does not repeatedly restart or desynchronize gait.\n","webMarkdown":"## 1D idle/walk/run Blend Space\n\nAssets:\n\n- compatible idle, walk, and run/sprint sequences;\n- same Skeleton and consistent forward axis;\n- compatible gait start phase where possible.\n\nSetup:\n\n1. Create Blend Space 1D for the Skeleton.\n2. Name axis `Speed`; use cm/s to match Character Movement velocity.\n3. Set axis min/max to the actual locomotion range.\n4. Place idle at zero and gait samples at their authored travel speeds.\n5. Drive from horizontal velocity magnitude, not full 3D velocity if falling should not\n   increase locomotion speed.\n6. Add axis smoothing only to remove noisy input; do not use it to hide incorrect\n   acceleration or bad sample speeds.\n7. Put compatible gait clips in the same Sync Group.\n8. Add matching left/right foot Sync Markers when phase drift is visible.\n\n## 2D strafe Blend Space\n\nCommon axes:\n\n- `Speed` and local-space `Direction`, or\n- local forward velocity and local right velocity.\n\nProcedure:\n\n1. Transform world velocity into character/mesh local space.\n2. Match axis ranges to actual movement limits.\n3. Place forward/back/left/right/diagonal samples according to authored direction.\n4. Preview corners and diagonals, not only axis centers.\n5. Validate foot phase across neighboring samples.\n6. If diagonal speed differs mechanically, drive the Blend Space with actual local\n   velocity rather than normalized input.\n\n## Starts, stops, and pivots\n\n- Keep simple locomotion in a looping Blend Space.\n- Add start/stop/pivot states when acceleration direction, planted foot, or authored\n  anticipation materially changes the pose.\n- Use marker-based sync for run-to-stop or walk-to-run transitions when phases differ.\n- Set start/stop animations to an appropriate leader role when they must define phase.\n- Use transition rules from movement state, acceleration, direction delta, and time\n  remaining—not arbitrary delays alone.\n\n## Aim Offset over locomotion\n\n1. Author/convert directional aim samples as mesh-space additive.\n2. Create Aim Offset with yaw/pitch axes.\n3. Feed locomotion cached pose into the Aim Offset base pose.\n4. Compute aim delta relative to character/mesh facing.\n5. Clamp/wrap yaw and pitch to authored limits.\n6. Layer weapon recoil after or within the aim layer according to desired space.\n7. Verify spine/shoulder deformation at extreme corners.\n\n## Root motion choice\n\n- In-place locomotion: Character/Mover movement is authoritative; animation visualizes it.\n- Root-motion action: animation drives movement for the action; use Montages for the\n  common networked path.\n- Enabling Root Motion from Everything moves AnimGraph evaluation to the Game Thread;\n  profile before choosing it broadly.\n- Verify capsule/mesh agreement, movement mode, slopes, falling behavior, replication,\n  and correction.\n\n## Evaluation checks\n\n- No foot sliding at authored sample speeds.\n- No phase double-step during walk/run blends.\n- Direction changes do not collapse knees or twist pelvis.\n- Acceleration/deceleration visual timing matches movement.\n- Falling does not feed incorrect speed/direction into grounded locomotion.\n- Network correction does not repeatedly restart or desynchronize gait.\n","searchText":"locomotion patterns 1d idle/walk/run blend space assets: - compatible idle, walk, and run/sprint sequences; - same skeleton and consistent forward axis; - compatible gait start phase where possible. setup: 1. create blend space 1d for the skeleton. 2. name axis speed; use cm/s to match character movement velocity. 3. set axis min/max to the actual locomotion range. 4. place idle at zero and gait samples at their authored travel speeds. 5. drive from horizontal velocity magnitude, not full 3d velocity if falling should not increase locomotion speed. 6. add axis smoothing only to remove noisy input; do not use it to hide incorrect acceleration or bad sample speeds. 7. put compatible gait clips in the same sync group. 8. add matching left/right foot sync markers when phase drift is visible. 2d strafe blend space common axes: - speed and local-space direction, or - local forward velocity and local right velocity. procedure: 1. transform world velocity into character/mesh local space. 2. match axis ranges to actual movement limits. 3. place forward/back/left/right/diagonal samples according to authored direction. 4. preview corners and diagonals, not only axis centers. 5. validate foot phase across neighboring samples. 6. if diagonal speed differs mechanically, drive the blend space with actual local velocity rather than normalized input. starts, stops, and pivots - keep simple locomotion in a looping blend space. - add start/stop/pivot states when acceleration direction, planted foot, or authored anticipation materially changes the pose. - use marker-based sync for run-to-stop or walk-to-run transitions when phases differ. - set start/stop animations to an appropriate leader role when they must define phase. - use transition rules from movement state, acceleration, direction delta, and time remaining—not arbitrary delays alone. aim offset over locomotion 1. author/convert directional aim samples as mesh-space additive. 2. create aim offset with yaw/pitch axes. 3. feed locomotion cached pose into the aim offset base pose. 4. compute aim delta relative to character/mesh facing. 5. clamp/wrap yaw and pitch to authored limits. 6. layer weapon recoil after or within the aim layer according to desired space. 7. verify spine/shoulder deformation at extreme corners. root motion choice - in-place locomotion: character/mover movement is authoritative; animation visualizes it. - root-motion action: animation drives movement for the action; use montages for the common networked path. - enabling root motion from everything moves animgraph evaluation to the game thread; profile before choosing it broadly. - verify capsule/mesh agreement, movement mode, slopes, falling behavior, replication, and correction. evaluation checks - no foot sliding at authored sample speeds. - no phase double-step during walk/run blends. - direction changes do not collapse knees or twist pelvis. - acceleration/deceleration visual timing matches movement. - falling does not feed incorrect speed/direction into grounded locomotion. - network correction does not repeatedly restart or desynchronize gait."},{"slug":"method-selector","file":"method-selector.md","title":"Method selector","rawMarkdown":"# Method selector\n\n| Problem | Primary mechanism | Why | Common misuse |\n|---|---|---|---|\n| Idle/walk/run over speed | Blend Space 1D | One continuous axis | Separate state per speed |\n| Strafing over speed and direction | Blend Space 2D | Two continuous axes | Unsynced directional clips |\n| Aim/look over yaw and pitch | Aim Offset | Mesh-space additive directional pose | Ordinary non-additive Blend Space |\n| Grounded/falling/swimming/climbing modes | State Machine | Persistent discrete states and transitions | Boolean blend web in main AnimGraph |\n| Weapon equipped/unequipped | Blend Poses by Bool/Enum or linked layer | Small discrete variant | Duplicating the entire locomotion machine |\n| Run while firing/reloading | Montage Slot + Layered Blend per Bone | Event action over lower-body base | Full-body montage when legs must continue |\n| Recoil/breathing/lean | Additive pose | Relative delta over base pose | Treating additive clip as full pose |\n| Walk/run cycles drift out of foot phase | Sync Group + Sync Markers | Aligns named gait events | Longer blend duration |\n| Abrupt short transition between similar moving poses | Inertialization | Carries outgoing motion without continued source evaluation | Using it between radically different poses |\n| One-off attack/combo with sections | Montage | Controlled sequence, sections, notifies, slots | Large state-machine branch |\n| Different bones need different transition rates | Blend Profile | Per-bone transition weighting | Multiple arbitrary transition nodes |\n| Complex reusable body-mode graph | Linked Anim Layer / Linked Anim Graph | Modular graph ownership | Copy-pasted graphs |\n\n## Decision tests\n\n### Blend Space\n\nUse when the desired pose is a smooth function of one or two measured values. Inputs\nmust have meaningful units and ranges. Samples should represent comparable motion and\ncompatible phase.\n\n### State Machine\n\nUse when the animation mode persists and entry/exit rules matter. Keep gameplay truth\noutside the state machine; let transitions consume stable variables.\n\n### Montage\n\nUse when gameplay explicitly starts/stops/branches an authored action. Use Sections for\ncombos or loops and Slots for body-region application. Same-Slot sequences override one\nanother.\n\n### Layered Blend per Bone\n\nUse for regional full-pose overrides. Select Branch Filter or Blend Mask deliberately.\nDefine the first affected bone and verify all descendants. Use mesh-space rotation blend\nwhen local-space composition produces shoulder/spine artifacts, then recheck cost and\nvisual result.\n\n### Additive\n\nUse when the clip represents a delta from a known reference pose. Confirm local-space or\nmesh-space additive setup and reference pose before blaming the graph.\n\n### Inertialization\n\nUse for short transitions where preserving outgoing velocity matters more than continuing\nto evaluate the source clip. Keep standard crossfade when source Notifies or exact source\nphase must remain active through the transition.\n","webMarkdown":"| Problem | Primary mechanism | Why | Common misuse |\n|---|---|---|---|\n| Idle/walk/run over speed | Blend Space 1D | One continuous axis | Separate state per speed |\n| Strafing over speed and direction | Blend Space 2D | Two continuous axes | Unsynced directional clips |\n| Aim/look over yaw and pitch | Aim Offset | Mesh-space additive directional pose | Ordinary non-additive Blend Space |\n| Grounded/falling/swimming/climbing modes | State Machine | Persistent discrete states and transitions | Boolean blend web in main AnimGraph |\n| Weapon equipped/unequipped | Blend Poses by Bool/Enum or linked layer | Small discrete variant | Duplicating the entire locomotion machine |\n| Run while firing/reloading | Montage Slot + Layered Blend per Bone | Event action over lower-body base | Full-body montage when legs must continue |\n| Recoil/breathing/lean | Additive pose | Relative delta over base pose | Treating additive clip as full pose |\n| Walk/run cycles drift out of foot phase | Sync Group + Sync Markers | Aligns named gait events | Longer blend duration |\n| Abrupt short transition between similar moving poses | Inertialization | Carries outgoing motion without continued source evaluation | Using it between radically different poses |\n| One-off attack/combo with sections | Montage | Controlled sequence, sections, notifies, slots | Large state-machine branch |\n| Different bones need different transition rates | Blend Profile | Per-bone transition weighting | Multiple arbitrary transition nodes |\n| Complex reusable body-mode graph | Linked Anim Layer / Linked Anim Graph | Modular graph ownership | Copy-pasted graphs |\n\n## Decision tests\n\n### Blend Space\n\nUse when the desired pose is a smooth function of one or two measured values. Inputs\nmust have meaningful units and ranges. Samples should represent comparable motion and\ncompatible phase.\n\n### State Machine\n\nUse when the animation mode persists and entry/exit rules matter. Keep gameplay truth\noutside the state machine; let transitions consume stable variables.\n\n### Montage\n\nUse when gameplay explicitly starts/stops/branches an authored action. Use Sections for\ncombos or loops and Slots for body-region application. Same-Slot sequences override one\nanother.\n\n### Layered Blend per Bone\n\nUse for regional full-pose overrides. Select Branch Filter or Blend Mask deliberately.\nDefine the first affected bone and verify all descendants. Use mesh-space rotation blend\nwhen local-space composition produces shoulder/spine artifacts, then recheck cost and\nvisual result.\n\n### Additive\n\nUse when the clip represents a delta from a known reference pose. Confirm local-space or\nmesh-space additive setup and reference pose before blaming the graph.\n\n### Inertialization\n\nUse for short transitions where preserving outgoing velocity matters more than continuing\nto evaluate the source clip. Keep standard crossfade when source Notifies or exact source\nphase must remain active through the transition.\n","searchText":"method selector | problem | primary mechanism | why | common misuse | |---|---|---|---| | idle/walk/run over speed | blend space 1d | one continuous axis | separate state per speed | | strafing over speed and direction | blend space 2d | two continuous axes | unsynced directional clips | | aim/look over yaw and pitch | aim offset | mesh-space additive directional pose | ordinary non-additive blend space | | grounded/falling/swimming/climbing modes | state machine | persistent discrete states and transitions | boolean blend web in main animgraph | | weapon equipped/unequipped | blend poses by bool/enum or linked layer | small discrete variant | duplicating the entire locomotion machine | | run while firing/reloading | montage slot + layered blend per bone | event action over lower-body base | full-body montage when legs must continue | | recoil/breathing/lean | additive pose | relative delta over base pose | treating additive clip as full pose | | walk/run cycles drift out of foot phase | sync group + sync markers | aligns named gait events | longer blend duration | | abrupt short transition between similar moving poses | inertialization | carries outgoing motion without continued source evaluation | using it between radically different poses | | one-off attack/combo with sections | montage | controlled sequence, sections, notifies, slots | large state-machine branch | | different bones need different transition rates | blend profile | per-bone transition weighting | multiple arbitrary transition nodes | | complex reusable body-mode graph | linked anim layer / linked anim graph | modular graph ownership | copy-pasted graphs | decision tests blend space use when the desired pose is a smooth function of one or two measured values. inputs must have meaningful units and ranges. samples should represent comparable motion and compatible phase. state machine use when the animation mode persists and entry/exit rules matter. keep gameplay truth outside the state machine; let transitions consume stable variables. montage use when gameplay explicitly starts/stops/branches an authored action. use sections for combos or loops and slots for body-region application. same-slot sequences override one another. layered blend per bone use for regional full-pose overrides. select branch filter or blend mask deliberately. define the first affected bone and verify all descendants. use mesh-space rotation blend when local-space composition produces shoulder/spine artifacts, then recheck cost and visual result. additive use when the clip represents a delta from a known reference pose. confirm local-space or mesh-space additive setup and reference pose before blaming the graph. inertialization use for short transitions where preserving outgoing velocity matters more than continuing to evaluate the source clip. keep standard crossfade when source notifies or exact source phase must remain active through the transition."},{"slug":"sources","file":"sources.md","title":"UE 5.8 primary sources","rawMarkdown":"# UE 5.8 primary sources\n\n- Epic Games, [Blending Animations](https://dev.epicgames.com/documentation/en-us/unreal-engine/blending-animations-in-unreal-engine)\n- Epic Games, [Animation Blueprint Blend Nodes](https://dev.epicgames.com/documentation/unreal-engine/animation-blueprint-blend-nodes-in-unreal-engine?lang=en-US)\n- Epic Games, [Blend Spaces](https://dev.epicgames.com/documentation/en-us/unreal-engine/blend-spaces-in-unreal-engine)\n- Epic Games, [Blend Spaces in Animation Blueprints](https://dev.epicgames.com/documentation/en-us/unreal-engine/blend-spaces-in-animation-blueprints-in-unreal-engine)\n- Epic Games, [State Machines](https://dev.epicgames.com/documentation/en-us/unreal-engine/state-machines-in-unreal-engine)\n- Epic Games, [Transition Rules](https://dev.epicgames.com/documentation/en-us/unreal-engine/transition-rules-in-unreal-engine)\n- Epic Games, [Animation Sync Groups](https://dev.epicgames.com/documentation/unreal-engine/animation-sync-groups-in-unreal-engine?lang=en-US)\n- Epic Games, [Animation Notifies](https://dev.epicgames.com/documentation/en-us/unreal-engine/animation-notifies-in-unreal-engine)\n- Epic Games, [Using Layered Animations](https://dev.epicgames.com/documentation/unreal-engine/using-layered-animations-in-unreal-engine?lang=en-US)\n- Epic Games, [Animation Montages](https://dev.epicgames.com/documentation/en-us/unreal-engine/animation-montage-in-unreal-engine)\n- Epic Games, [Root Motion](https://dev.epicgames.com/documentation/unreal-engine/root-motion-in-unreal-engine)\n\nVersion target: Unreal Engine 5.8. Recheck node stability, experimental status, and\nthreading behavior before using this skill with a later engine version.\n","webMarkdown":"- Epic Games, [Blending Animations](https://dev.epicgames.com/documentation/en-us/unreal-engine/blending-animations-in-unreal-engine)\n- Epic Games, [Animation Blueprint Blend Nodes](https://dev.epicgames.com/documentation/unreal-engine/animation-blueprint-blend-nodes-in-unreal-engine?lang=en-US)\n- Epic Games, [Blend Spaces](https://dev.epicgames.com/documentation/en-us/unreal-engine/blend-spaces-in-unreal-engine)\n- Epic Games, [Blend Spaces in Animation Blueprints](https://dev.epicgames.com/documentation/en-us/unreal-engine/blend-spaces-in-animation-blueprints-in-unreal-engine)\n- Epic Games, [State Machines](https://dev.epicgames.com/documentation/en-us/unreal-engine/state-machines-in-unreal-engine)\n- Epic Games, [Transition Rules](https://dev.epicgames.com/documentation/en-us/unreal-engine/transition-rules-in-unreal-engine)\n- Epic Games, [Animation Sync Groups](https://dev.epicgames.com/documentation/unreal-engine/animation-sync-groups-in-unreal-engine?lang=en-US)\n- Epic Games, [Animation Notifies](https://dev.epicgames.com/documentation/en-us/unreal-engine/animation-notifies-in-unreal-engine)\n- Epic Games, [Using Layered Animations](https://dev.epicgames.com/documentation/unreal-engine/using-layered-animations-in-unreal-engine?lang=en-US)\n- Epic Games, [Animation Montages](https://dev.epicgames.com/documentation/en-us/unreal-engine/animation-montage-in-unreal-engine)\n- Epic Games, [Root Motion](https://dev.epicgames.com/documentation/unreal-engine/root-motion-in-unreal-engine)\n\nVersion target: Unreal Engine 5.8. Recheck node stability, experimental status, and\nthreading behavior before using this skill with a later engine version.\n","searchText":"ue 5.8 primary sources - epic games, blending animations - epic games, animation blueprint blend nodes - epic games, blend spaces - epic games, blend spaces in animation blueprints - epic games, state machines - epic games, transition rules - epic games, animation sync groups - epic games, animation notifies - epic games, using layered animations - epic games, animation montages - epic games, root motion version target: unreal engine 5.8. recheck node stability, experimental status, and threading behavior before using this skill with a later engine version."},{"slug":"transitions-and-sync","file":"transitions-and-sync.md","title":"Transitions, sync, and inertialization","rawMarkdown":"# Transitions, sync, and inertialization\n\n## Standard state transition\n\n1. Build one directional transition for each allowed direction.\n2. Base the rule on stable gameplay/movement variables.\n3. Set Priority Order when multiple transitions can be true; smaller number wins.\n4. Choose Duration and curve from the visible motion, then test interruptions.\n5. Use Blend Profile when body regions should settle at different rates.\n6. Use shared transition/crossfade settings only when editing one should intentionally\n   change all users.\n7. Do not enable Bidirectional; UE 5.8 documentation marks it unsupported.\n\nFor non-looping exit:\n\n- Use relevant animation time remaining or Automatic Rule Based on Sequence Player.\n- Mark unrelated players `Ignore for Relevancy Test` when they would corrupt the query.\n- Test with altered play rate.\n\n## Sync Groups\n\nUse for animations representing the same cyclical action at different rates.\n\n1. Give compatible nodes the same Group Name.\n2. Set Method to Sync Group, or Graph when sync is propagated by graph structure.\n3. Choose Group Role deliberately; highest-weight animation is leader by default.\n4. Ensure clips begin with compatible body phase.\n5. Avoid drastic clip-length differences that create play-rate pops.\n\n## Marker-based sync\n\n1. Add shared markers such as `LeftFootDown` and `RightFootDown` to every gait clip.\n2. Put animations in the same Sync Group.\n3. Ensure marker spelling and order match.\n4. Remember: only markers common to all animations in the group are used.\n5. If no matching markers exist, UE falls back to length-based syncing.\n6. Set start/stop clips as leader where they must control the transition phase.\n\n## Inertialization\n\nSetup:\n\n1. Set compatible transition/blend node Transition Type to Inertialization.\n2. Add one Inertialization node after all request sources it should serve.\n3. Place it near Output Pose to consolidate requests where appropriate.\n4. Apply before final IK in the common whole-body path.\n5. Keep requested blend under 0.4 seconds and test shorter first.\n\nUse when:\n\n- outgoing pose is still moving;\n- poses are reasonably compatible;\n- rapid natural settling is desired;\n- source clip no longer needs evaluation.\n\nAvoid when:\n\n- poses are extremely different;\n- source Notifies must still fire after transition begins;\n- continuous interruptions degrade quality;\n- exact crossfade sampling is required.\n\nWhen multiple requests occur, UE uses the minimum requested duration.\n\n## Dead Blending\n\nDead Blending predicts outgoing motion and may handle large differences better, but UE\n5.8 labels the node experimental and does not recommend shipping projects that depend\non it. Use only for evaluation with an explicit Inertialization/standard-blend fallback.\n","webMarkdown":"## Standard state transition\n\n1. Build one directional transition for each allowed direction.\n2. Base the rule on stable gameplay/movement variables.\n3. Set Priority Order when multiple transitions can be true; smaller number wins.\n4. Choose Duration and curve from the visible motion, then test interruptions.\n5. Use Blend Profile when body regions should settle at different rates.\n6. Use shared transition/crossfade settings only when editing one should intentionally\n   change all users.\n7. Do not enable Bidirectional; UE 5.8 documentation marks it unsupported.\n\nFor non-looping exit:\n\n- Use relevant animation time remaining or Automatic Rule Based on Sequence Player.\n- Mark unrelated players `Ignore for Relevancy Test` when they would corrupt the query.\n- Test with altered play rate.\n\n## Sync Groups\n\nUse for animations representing the same cyclical action at different rates.\n\n1. Give compatible nodes the same Group Name.\n2. Set Method to Sync Group, or Graph when sync is propagated by graph structure.\n3. Choose Group Role deliberately; highest-weight animation is leader by default.\n4. Ensure clips begin with compatible body phase.\n5. Avoid drastic clip-length differences that create play-rate pops.\n\n## Marker-based sync\n\n1. Add shared markers such as `LeftFootDown` and `RightFootDown` to every gait clip.\n2. Put animations in the same Sync Group.\n3. Ensure marker spelling and order match.\n4. Remember: only markers common to all animations in the group are used.\n5. If no matching markers exist, UE falls back to length-based syncing.\n6. Set start/stop clips as leader where they must control the transition phase.\n\n## Inertialization\n\nSetup:\n\n1. Set compatible transition/blend node Transition Type to Inertialization.\n2. Add one Inertialization node after all request sources it should serve.\n3. Place it near Output Pose to consolidate requests where appropriate.\n4. Apply before final IK in the common whole-body path.\n5. Keep requested blend under 0.4 seconds and test shorter first.\n\nUse when:\n\n- outgoing pose is still moving;\n- poses are reasonably compatible;\n- rapid natural settling is desired;\n- source clip no longer needs evaluation.\n\nAvoid when:\n\n- poses are extremely different;\n- source Notifies must still fire after transition begins;\n- continuous interruptions degrade quality;\n- exact crossfade sampling is required.\n\nWhen multiple requests occur, UE uses the minimum requested duration.\n\n## Dead Blending\n\nDead Blending predicts outgoing motion and may handle large differences better, but UE\n5.8 labels the node experimental and does not recommend shipping projects that depend\non it. Use only for evaluation with an explicit Inertialization/standard-blend fallback.\n","searchText":"transitions, sync, and inertialization standard state transition 1. build one directional transition for each allowed direction. 2. base the rule on stable gameplay/movement variables. 3. set priority order when multiple transitions can be true; smaller number wins. 4. choose duration and curve from the visible motion, then test interruptions. 5. use blend profile when body regions should settle at different rates. 6. use shared transition/crossfade settings only when editing one should intentionally change all users. 7. do not enable bidirectional; ue 5.8 documentation marks it unsupported. for non-looping exit: - use relevant animation time remaining or automatic rule based on sequence player. - mark unrelated players ignore for relevancy test when they would corrupt the query. - test with altered play rate. sync groups use for animations representing the same cyclical action at different rates. 1. give compatible nodes the same group name. 2. set method to sync group, or graph when sync is propagated by graph structure. 3. choose group role deliberately; highest-weight animation is leader by default. 4. ensure clips begin with compatible body phase. 5. avoid drastic clip-length differences that create play-rate pops. marker-based sync 1. add shared markers such as leftfootdown and rightfootdown to every gait clip. 2. put animations in the same sync group. 3. ensure marker spelling and order match. 4. remember: only markers common to all animations in the group are used. 5. if no matching markers exist, ue falls back to length-based syncing. 6. set start/stop clips as leader where they must control the transition phase. inertialization setup: 1. set compatible transition/blend node transition type to inertialization. 2. add one inertialization node after all request sources it should serve. 3. place it near output pose to consolidate requests where appropriate. 4. apply before final ik in the common whole-body path. 5. keep requested blend under 0.4 seconds and test shorter first. use when: - outgoing pose is still moving; - poses are reasonably compatible; - rapid natural settling is desired; - source clip no longer needs evaluation. avoid when: - poses are extremely different; - source notifies must still fire after transition begins; - continuous interruptions degrade quality; - exact crossfade sampling is required. when multiple requests occur, ue uses the minimum requested duration. dead blending dead blending predicts outgoing motion and may handle large differences better, but ue 5.8 labels the node experimental and does not recommend shipping projects that depend on it. use only for evaluation with an explicit inertialization/standard-blend fallback."},{"slug":"troubleshooting","file":"troubleshooting.md","title":"Troubleshooting","rawMarkdown":"# Troubleshooting\n\n| Symptom | Likely cause | Action |\n|---|---|---|\n| Feet double-step during blend | Gait clips out of phase | Add matching Sync Group and foot markers |\n| Feet slide at steady speed | Sample authored speed differs from movement speed | Place sample at measured speed; use stride/play-rate solution deliberately |\n| Pop entering state | Pose discontinuity, zero/short blend, bad reference pose | Inspect source/target poses; tune crossfade/profile or use compatible inertialization |\n| Inertialization logs runtime error | Request exists without downstream node | Add Inertialization after request source |\n| Important source Notify never fires | Inertialization stops source evaluation | Use standard blend or move gameplay event ownership |\n| Inertial blend looks stiff/broken | Poses too different or repeated interruptions | Use standard/custom blend; reduce interruptions |\n| Upper body action moves legs | Branch root too high/low or wrong Blend Mask | Inspect affected hierarchy and blend depth/mask |\n| Shoulder/spine twists | Local-space regional rotation composition | Test mesh-space rotation blend; fix additive/reference setup |\n| Aim Offset explodes at extremes | Samples not mesh-space additive or bad axis/wrap | Correct additive setup; clamp/wrap inputs; inspect corner samples |\n| Montage does not appear | Slot node absent/wrong Slot or Slot Group conflict | Add matching Slot to AnimGraph; inspect competing Montages |\n| Montage cancels another action | Same Slot Group owns both | Separate ownership/Slots or define priority/cancel policy |\n| Transition chooses wrong path | Competing true rules / priority | Set explicit Priority Order and simplify state truth |\n| Time Remaining is wrong | Multiple relevant players | Enable Ignore for Relevancy Test on unrelated players |\n| Notifies fire from tiny blend weight | Trigger Weight Threshold too low | Raise threshold and test blend edges |\n| Network root motion diverges | Montage/RPC/authority mismatch | Make gameplay authoritative; replicate montage trigger and verify correction |\n| Returning state resumes midway | `Always Reset on Entry` disabled | Enable when restart is intended; leave disabled only for resume behavior |\n\n## Debug sequence\n\n1. Inspect live Animation Blueprint and active state weights.\n2. Display relevant variables: speed, local direction, movement mode, action state.\n3. Preview Blend Space at actual runtime coordinates.\n4. Inspect Sync Group leader/follower and marker names.\n5. Temporarily bypass overlays to isolate base locomotion.\n6. Re-enable Slot, additive, regional blend, and IK one stage at a time.\n7. Inspect Montage instance, Slot Group, Sections, and blend weights.\n8. Test interruption at start, midpoint, and blend out.\n9. Test low frame rate and network latency where applicable.\n\n## Acceptance checks\n\n- Phase remains stable across gait blends.\n- No visible pop at normal or interrupted transitions.\n- Regional actions affect only intended bones.\n- Gameplay events fire exactly once at the intended authority.\n- Root motion and capsule remain aligned.\n- Graph remains understandable and does not duplicate persistent gameplay truth.\n","webMarkdown":"| Symptom | Likely cause | Action |\n|---|---|---|\n| Feet double-step during blend | Gait clips out of phase | Add matching Sync Group and foot markers |\n| Feet slide at steady speed | Sample authored speed differs from movement speed | Place sample at measured speed; use stride/play-rate solution deliberately |\n| Pop entering state | Pose discontinuity, zero/short blend, bad reference pose | Inspect source/target poses; tune crossfade/profile or use compatible inertialization |\n| Inertialization logs runtime error | Request exists without downstream node | Add Inertialization after request source |\n| Important source Notify never fires | Inertialization stops source evaluation | Use standard blend or move gameplay event ownership |\n| Inertial blend looks stiff/broken | Poses too different or repeated interruptions | Use standard/custom blend; reduce interruptions |\n| Upper body action moves legs | Branch root too high/low or wrong Blend Mask | Inspect affected hierarchy and blend depth/mask |\n| Shoulder/spine twists | Local-space regional rotation composition | Test mesh-space rotation blend; fix additive/reference setup |\n| Aim Offset explodes at extremes | Samples not mesh-space additive or bad axis/wrap | Correct additive setup; clamp/wrap inputs; inspect corner samples |\n| Montage does not appear | Slot node absent/wrong Slot or Slot Group conflict | Add matching Slot to AnimGraph; inspect competing Montages |\n| Montage cancels another action | Same Slot Group owns both | Separate ownership/Slots or define priority/cancel policy |\n| Transition chooses wrong path | Competing true rules / priority | Set explicit Priority Order and simplify state truth |\n| Time Remaining is wrong | Multiple relevant players | Enable Ignore for Relevancy Test on unrelated players |\n| Notifies fire from tiny blend weight | Trigger Weight Threshold too low | Raise threshold and test blend edges |\n| Network root motion diverges | Montage/RPC/authority mismatch | Make gameplay authoritative; replicate montage trigger and verify correction |\n| Returning state resumes midway | `Always Reset on Entry` disabled | Enable when restart is intended; leave disabled only for resume behavior |\n\n## Debug sequence\n\n1. Inspect live Animation Blueprint and active state weights.\n2. Display relevant variables: speed, local direction, movement mode, action state.\n3. Preview Blend Space at actual runtime coordinates.\n4. Inspect Sync Group leader/follower and marker names.\n5. Temporarily bypass overlays to isolate base locomotion.\n6. Re-enable Slot, additive, regional blend, and IK one stage at a time.\n7. Inspect Montage instance, Slot Group, Sections, and blend weights.\n8. Test interruption at start, midpoint, and blend out.\n9. Test low frame rate and network latency where applicable.\n\n## Acceptance checks\n\n- Phase remains stable across gait blends.\n- No visible pop at normal or interrupted transitions.\n- Regional actions affect only intended bones.\n- Gameplay events fire exactly once at the intended authority.\n- Root motion and capsule remain aligned.\n- Graph remains understandable and does not duplicate persistent gameplay truth.\n","searchText":"troubleshooting | symptom | likely cause | action | |---|---|---| | feet double-step during blend | gait clips out of phase | add matching sync group and foot markers | | feet slide at steady speed | sample authored speed differs from movement speed | place sample at measured speed; use stride/play-rate solution deliberately | | pop entering state | pose discontinuity, zero/short blend, bad reference pose | inspect source/target poses; tune crossfade/profile or use compatible inertialization | | inertialization logs runtime error | request exists without downstream node | add inertialization after request source | | important source notify never fires | inertialization stops source evaluation | use standard blend or move gameplay event ownership | | inertial blend looks stiff/broken | poses too different or repeated interruptions | use standard/custom blend; reduce interruptions | | upper body action moves legs | branch root too high/low or wrong blend mask | inspect affected hierarchy and blend depth/mask | | shoulder/spine twists | local-space regional rotation composition | test mesh-space rotation blend; fix additive/reference setup | | aim offset explodes at extremes | samples not mesh-space additive or bad axis/wrap | correct additive setup; clamp/wrap inputs; inspect corner samples | | montage does not appear | slot node absent/wrong slot or slot group conflict | add matching slot to animgraph; inspect competing montages | | montage cancels another action | same slot group owns both | separate ownership/slots or define priority/cancel policy | | transition chooses wrong path | competing true rules / priority | set explicit priority order and simplify state truth | | time remaining is wrong | multiple relevant players | enable ignore for relevancy test on unrelated players | | notifies fire from tiny blend weight | trigger weight threshold too low | raise threshold and test blend edges | | network root motion diverges | montage/rpc/authority mismatch | make gameplay authoritative; replicate montage trigger and verify correction | | returning state resumes midway | always reset on entry disabled | enable when restart is intended; leave disabled only for resume behavior | debug sequence 1. inspect live animation blueprint and active state weights. 2. display relevant variables: speed, local direction, movement mode, action state. 3. preview blend space at actual runtime coordinates. 4. inspect sync group leader/follower and marker names. 5. temporarily bypass overlays to isolate base locomotion. 6. re-enable slot, additive, regional blend, and ik one stage at a time. 7. inspect montage instance, slot group, sections, and blend weights. 8. test interruption at start, midpoint, and blend out. 9. test low frame rate and network latency where applicable. acceptance checks - phase remains stable across gait blends. - no visible pop at normal or interrupted transitions. - regional actions affect only intended bones. - gameplay events fire exactly once at the intended authority. - root motion and capsule remain aligned. - graph remains understandable and does not duplicate persistent gameplay truth."}]}
{"slug":"unreal-animation-montages","name":"unreal-animation-montages","title":"Unreal 5.8 Animation Montages","description":"Design, play, branch, layer, cancel, replicate, and debug Animation Montages in Unreal Engine 5.8. Use for attacks, dodges, reloads, interactions, abilities, Slots and Slot Groups, Montage Sections, combos, loops, Anim Notifies and Notify States, branching points, cancel windows, root motion, GAS Play Montage and Wait, interruptions, network playback, child montages, or gameplay animation timing.","shortDescription":"Build and debug gameplay animation actions","category":"Animation","referenceCount":9,"rawMarkdown":"---\nname: unreal-animation-montages\ndescription: Design, play, branch, layer, cancel, replicate, and debug Animation Montages in Unreal Engine 5.8. Use for attacks, dodges, reloads, interactions, abilities, Slots and Slot Groups, Montage Sections, combos, loops, Anim Notifies and Notify States, branching points, cancel windows, root motion, GAS Play Montage and Wait, interruptions, network playback, child montages, or gameplay animation timing.\n---\n\n# Unreal 5.8 Animation Montages\n\n## Ownership boundary\n\nThis skill owns authored action playback, Slots, Sections, notify-timed windows, branching, and\ninterruption. Route final pose composition to\n[`unreal-animation-blending`](../unreal-animation-blending/SKILL.md), authoritative Character\ndisplacement and prediction to [`unreal-character-movement`](../unreal-character-movement/SKILL.md),\nand ability activation/cost/cooldown ownership to\n[`unreal-gas-abilities`](../unreal-gas-abilities/SKILL.md).\n\n## Use Montages for bounded actions\n\nRead [`references/action-selector.md`](references/action-selector.md).\n\nUse a Montage when gameplay starts a discrete authored action and needs explicit playback,\nsections, events, interruption, or root-motion control. Keep persistent locomotion in a State\nMachine, Blend Space, or Motion Matching system. A Montage inserts an action through an AnimGraph\nSlot; it does not replace the underlying gameplay state machine.\n\n## Execute\n\n1. Define action authority, eligibility, commitment, cancel, completion, and interruption states.\n2. Choose full-body or regional layering and create the matching Slot/Slot Group path.\n3. Build named Sections around semantic phases; define default and runtime transitions.\n4. Add Notifies/Notify States only for events that must follow animation time.\n5. Choose playback API: gameplay/AnimInstance, Character proxy node, or GAS Ability Task.\n6. Define root-motion ownership and movement/collision behavior for every section.\n7. Implement all completion, blend-out, interruption, cancellation, and owner-destruction exits.\n8. Test network roles, variable frame rates, late interruption, and section boundaries.\n\nLoad only what applies:\n\n- [`references/asset-sections-and-slots.md`](references/asset-sections-and-slots.md)\n- [`references/playback-and-lifecycle.md`](references/playback-and-lifecycle.md)\n- [`references/notifies-and-gameplay-windows.md`](references/notifies-and-gameplay-windows.md)\n- [`references/combos-loops-and-variants.md`](references/combos-loops-and-variants.md)\n- [`references/root-motion-and-movement.md`](references/root-motion-and-movement.md)\n- [`references/gas-and-networking.md`](references/gas-and-networking.md)\n- [`references/debugging-patterns.md`](references/debugging-patterns.md)\n\n## Required answer format\n\nReturn:\n\n1. **Action owner and authority** with eligibility/commitment/cancel rules.\n2. **Montage, Slot/Group, body-region, and root-motion assumptions**.\n3. **Named Sections and transition graph**.\n4. **Playback API and exact callbacks handled**.\n5. **Notifies/windows with cosmetic versus authoritative responsibility**.\n6. **Interruption, GAS, replication, movement, and cleanup consequences**.\n7. **Acceptance cases across frame rate and network roles**.\n\n## Hard rules\n\n- A matching Slot node must exist in the evaluated AnimGraph path or the Montage is invisible.\n- Sequences in the same Slot/Slot Group can override or interfere; design concurrency explicitly.\n- Sections describe playback topology; gameplay state decides whether a transition is legal.\n- Treat Notify delivery as animation-timed signaling, not sole authority for irreversible gameplay.\n- Use Branching Point timing only when its synchronous precision justifies higher cost.\n- `Play Montage` exposes Montage Notify callbacks; `Play Anim Montage` does not expose the same proxy callbacks.\n- Handle Completed, Blend Out, Interrupted, and Cancelled as distinct outcomes.\n- Playing a Montage locally is not a complete network contract. Replicate/predict the gameplay action\n  and trigger appropriate playback per role; root-motion correction does not replicate gameplay logic.\n- Use `Root Motion from Montages Only` when the networked design relies on montage root motion.\n- Keep Motion Matching/State Machines as the locomotion base; place final IK after action blending.\n\nSee [`references/sources.md`](references/sources.md) for the UE 5.8 source trail.\n","webMarkdown":"## Ownership boundary\n\nThis skill owns authored action playback, Slots, Sections, notify-timed windows, branching, and\ninterruption. Route final pose composition to\n[`unreal-animation-blending`](/unreal/unreal-animation-blending/), authoritative Character\ndisplacement and prediction to [`unreal-character-movement`](/unreal/unreal-character-movement/),\nand ability activation/cost/cooldown ownership to\n[`unreal-gas-abilities`](/unreal/unreal-gas-abilities/).\n\n## Use Montages for bounded actions\n\nRead [`references/action-selector.md`](/unreal/unreal-animation-montages/action-selector/).\n\nUse a Montage when gameplay starts a discrete authored action and needs explicit playback,\nsections, events, interruption, or root-motion control. Keep persistent locomotion in a State\nMachine, Blend Space, or Motion Matching system. A Montage inserts an action through an AnimGraph\nSlot; it does not replace the underlying gameplay state machine.\n\n## Execute\n\n1. Define action authority, eligibility, commitment, cancel, completion, and interruption states.\n2. Choose full-body or regional layering and create the matching Slot/Slot Group path.\n3. Build named Sections around semantic phases; define default and runtime transitions.\n4. Add Notifies/Notify States only for events that must follow animation time.\n5. Choose playback API: gameplay/AnimInstance, Character proxy node, or GAS Ability Task.\n6. Define root-motion ownership and movement/collision behavior for every section.\n7. Implement all completion, blend-out, interruption, cancellation, and owner-destruction exits.\n8. Test network roles, variable frame rates, late interruption, and section boundaries.\n\nLoad only what applies:\n\n- [`references/asset-sections-and-slots.md`](/unreal/unreal-animation-montages/asset-sections-and-slots/)\n- [`references/playback-and-lifecycle.md`](/unreal/unreal-animation-montages/playback-and-lifecycle/)\n- [`references/notifies-and-gameplay-windows.md`](/unreal/unreal-animation-montages/notifies-and-gameplay-windows/)\n- [`references/combos-loops-and-variants.md`](/unreal/unreal-animation-montages/combos-loops-and-variants/)\n- [`references/root-motion-and-movement.md`](/unreal/unreal-animation-montages/root-motion-and-movement/)\n- [`references/gas-and-networking.md`](/unreal/unreal-animation-montages/gas-and-networking/)\n- [`references/debugging-patterns.md`](/unreal/unreal-animation-montages/debugging-patterns/)\n\n## Required answer format\n\nReturn:\n\n1. **Action owner and authority** with eligibility/commitment/cancel rules.\n2. **Montage, Slot/Group, body-region, and root-motion assumptions**.\n3. **Named Sections and transition graph**.\n4. **Playback API and exact callbacks handled**.\n5. **Notifies/windows with cosmetic versus authoritative responsibility**.\n6. **Interruption, GAS, replication, movement, and cleanup consequences**.\n7. **Acceptance cases across frame rate and network roles**.\n\n## Hard rules\n\n- A matching Slot node must exist in the evaluated AnimGraph path or the Montage is invisible.\n- Sequences in the same Slot/Slot Group can override or interfere; design concurrency explicitly.\n- Sections describe playback topology; gameplay state decides whether a transition is legal.\n- Treat Notify delivery as animation-timed signaling, not sole authority for irreversible gameplay.\n- Use Branching Point timing only when its synchronous precision justifies higher cost.\n- `Play Montage` exposes Montage Notify callbacks; `Play Anim Montage` does not expose the same proxy callbacks.\n- Handle Completed, Blend Out, Interrupted, and Cancelled as distinct outcomes.\n- Playing a Montage locally is not a complete network contract. Replicate/predict the gameplay action\n  and trigger appropriate playback per role; root-motion correction does not replicate gameplay logic.\n- Use `Root Motion from Montages Only` when the networked design relies on montage root motion.\n- Keep Motion Matching/State Machines as the locomotion base; place final IK after action blending.\n\nSee [`references/sources.md`](/unreal/unreal-animation-montages/sources/) for the UE 5.8 source trail.\n","searchText":"unreal 5.8 animation montages design, play, branch, layer, cancel, replicate, and debug animation montages in unreal engine 5.8. use for attacks, dodges, reloads, interactions, abilities, slots and slot groups, montage sections, combos, loops, anim notifies and notify states, branching points, cancel windows, root motion, gas play montage and wait, interruptions, network playback, child montages, or gameplay animation timing. action selector action selector | need | prefer | avoid | |---|---|---| | persistent locomotion/mode | state machine, blend space, motion matching | long looping montage as primary locomotion | | one-shot full-body action | montage through full-body slot | state explosion for every action | | upper-body action over locomotion | montage slot + layered blend per bone | replacing the locomotion base | | start-loop-end action | montage sections with runtime next-section change | restarting separate assets every loop | | contextual animation variant, same timing contract | child montage or data-selected montage | branching gameplay logic inside animation assets | | gas-owned ability action | play montage and wait ability task | unmanaged montage lifecycle | | pure cosmetic one-frame response | short montage or additive blend by complexity | authoritative gameplay in a cosmetic notify | before authoring, write: - who may start the action; - when commitment begins; - which inputs buffer or cancel it; - whether locomotion continues underneath; - who owns displacement/collision; - which outcomes are completed, interrupted, or cancelled. if those are undefined, additional montage sections will conceal rather than solve the design gap. asset, sections, and slots asset, sections, and slots create create via content browser -> animation -> animation montage and choose the skeleton, or right-click an animation sequence -> create -> create animmontage. add sequences to the slot track. sections create named sections at semantic boundaries, for example start, loop, release, recovery, or combo stages. a section must begin at montage time zero. in the sections panel, define the default next section and preview each path. keep names stable because blueprint/c++ and gas may reference them. use montage set next section to relink what follows the current section, such as changing start -> loop -> loop into loop -> end. use an immediate jump only when skipping the remaining current-section motion is intended. slots and slot groups add slot nodes to the animgraph at the point where actions should enter. a montage exclusively plays through its slot; a missing or bypassed node yields no visible pose. use separate slot groups/body regions only when simultaneous actions are intended, then layer them explicitly. avoid overlapping sequence segments on one slot. when multiple slot tracks represent variants, align their end-to-end timing and section boundaries so runtime section calls mean the same thing. typical regional order: locomotion base -> upper-body slot -> layered blend per bone/mask -> inertialization if used -> final ik. full-body actions may use a slot after locomotion and replace it. combos, loops, and variants combos, loops, and variants combo sections create one section per committed stage and explicit recovery/exit. during an input window, gameplay buffers the next action. after validation, call montage set next section for the current stage to link to the next. if no valid input arrives, retain or relink to recovery. do not jump based solely on the input press; use the action's legal cancel/chain window. protect against stale input by tagging the buffered request with the current action/stage instance. clear it on consumption, interruption, cancellation, owner change, and timeout. start-loop-end default graph: start -> loop, loop -> loop, end -> complete. when gameplay ends the held action, relink loop -> end. define behavior when release happens during start, after the loop boundary, or while blending out. child montages use a child montage to replace animation segments while inheriting the parent's section/notify/slot contract. unreal adjusts replacement playback to the parent's time range, so visually inspect speed, contacts, root motion, and notify alignment. child montages cannot parent another child. use separate parent montages when variants have different gameplay timing or topology. do not force substantially different attacks into one inherited timing contract merely to reuse code. concurrent actions slots in the same group can interrupt each other. separate groups allow concurrency but can create conflicting bone ownership, root motion, or gameplay lifecycles. define precedence explicitly and test reload+hit reaction, aim+fire, and action+death cases. debugging patterns debugging patterns isolation ladder 1. confirm the skeletal mesh uses the expected animbp and skeleton. 2. play the montage in its editor and preview the intended section path/slot. 3. confirm the matching slot node lies on the evaluated animgraph path. 4. play without layering; then restore layered blend per bone/masks. 5. log play return, active montage/instance, current section, position, weight, and callbacks. 6. disable root motion and notifies separately to isolate pose versus gameplay/movement faults. 7. test standalone, listen server, owning client, simulated client, and dedicated server. | symptom | first check | |---|---| | montage reports playing but invisible | missing/bypassed slot node, wrong slot/group | | upper body affects legs | layer branch bone/mask and mesh skeleton | | stops unexpectedly | competing montage in same slot group, ability cancel | | combo never advances | section names, current section, next-section relink timing | | loop never exits | wrong from section, relink after boundary, stale input | | notify callback absent | playback node type, montage notify type, slot/link/filter settings | | end event missing | interruption/cancel path not handled | | mesh snaps to capsule | root motion disabled/mode mismatch/root lock | | server/client differ | playback trigger and gameplay state not replicated/predicted coherently | | works at normal rate only | notify window/section boundary tied to frames rather than semantics | acceptance suite: early/late cancel, overlapping action request, same-group interruption, death/stun, owner destruction, extreme play rate, low fps, root-motion obstacle, network latency/loss, and every terminal callback. gas and networking gas and networking gas use play montage and wait when the gameplay ability owns the action. supply montage, rate, optional start section/time, root-motion translation scale, and stop when ability ends deliberately. handle every output: - on completed: normal montage completion. - on blend out: visual blend-out began; not identical to completion. - on interrupted: another montage/action displaced it. - on cancelled: task/ability cancellation. - on blended in: optional point when full action pose is established. the task always stops on explicit ability cancellation. if stop when ability ends is true, normal ability end also aborts it. end/cancel the ability and clean gameplay windows on all terminal paths. custom projects often combine montage waiting with gameplay events; keep event tags and action instance validation explicit. network contract starting a montage on one machine does not by itself start equivalent gameplay on every peer. the server validates the action; the owning client may predict if the system supports it; simulated peers receive replicated gameplay state/cues or an appropriate multicast/ability path and play presentation. epic's montage documentation notes that an rpc must carry the play montage trigger; only root-motion replication/correction is carried by the root-motion movement path. notifies, sections, hit results, and arbitrary gameplay state are not automatically replicated by root-motion correction. test authority, autonomous proxy, simulated proxy, dedicated server, latency/loss, correction during root motion, cancellation, relevancy loss, and replay/late state. deduplicate predicted cosmetic cues when confirmed events arrive. notifies and gameplay windows notifies and gameplay windows choose the signal - anim notify: one instant, such as a footstep or cosmetic cue. - notify state: begin/tick/end window, such as trace-active, invulnerability, or input acceptance. - montage notify / montage notify window: emits play montage proxy notify callbacks. - branching point timing: precise synchronous ordering for a gameplay branch; more expensive. - queued timing: asynchronous and cheaper when minor frame imprecision is acceptable. trigger weight threshold, lod filtering, dedicated-server firing, follower behavior, trigger chance, and link method can all change delivery. choose relative/proportional linking when a notify should follow a moved/scaled montage segment; use absolute only when timeline position must remain fixed. authority boundary use notifies to align presentation and request bounded gameplay transitions. the gameplay owner still checks current action instance, authority, targets, and idempotence before applying damage or durable state. network peers can cross an animation frame at different times; a cosmetic notify is not proof that the server accepted the action. for melee, a robust window is: 1. server/predicted ability owns the attack; 2. notify state begins and enables a trace for that action instance; 3. each target is deduplicated; 4. authoritative hit validation applies effects; 5. notify state ends or interruption cleanup disables the trace. test skipped sections, high play rate, low frame rate, blend-out during a window, and interruption before both begin and end. playback and lifecycle playback and lifecycle choose playback api - animinstance montage functions: direct control for systems already owning the animinstance. - play montage proxy node: exposes completed, blend out, interrupted, notify begin, and notify end. - play anim montage: simpler character convenience function, without the same proxy notify outputs. - gas play montage and wait: action lifecycle owned by a gameplay ability. ordered lifecycle 1. gameplay verifies eligibility and commits the action at the intended point. 2. set required state/parameters before playback. 3. play the montage at rate/start section or time. 4. treat a failed/zero-length play result as failure and unwind state. 5. react to notify windows and section changes without assuming completion. 6. on blend out, stop spawning new action work if visual recovery has begun. 7. on completed, perform normal cleanup/completion. 8. on interrupted or cancelled, perform interruption cleanup and rollback only what is reversible. 9. clean up when owner/ability ends even if no expected callback arrives. do not bind a second action to stale callbacks from the first. when using delegates in c++, bind them to the specific montage instance/lifecycle and unbind on cleanup. stopping with blend time does not mean the action remains gameplay-active for that blend. define whether commitment ends at cancel request, blend-out start, notify end, or montage completion. root motion and movement root motion and movement contract 1. verify the source asset has an animated root bone and enable root motion is set. 2. choose root motion root lock: reference pose, animation first frame, or zero, based on the asset. 3. in animbp class defaults choose the intended root motion mode. for network-oriented montage root motion, use root motion from montages only. 4. decide how character movement mode handles vertical displacement. walking/falling apply movement physics differently from flying. 5. test capsule/mesh alignment, collision, slopes, stairs, interruption, correction, and blend-out. root motion moves the collision-owning character through the movement system; do not separately add the same displacement in gameplay code. conversely, in-place actions need code-driven movement when displacement matters. section/cancel hazards - jumping into a section can skip root displacement that the following frames assume occurred. - interrupting a lunge must leave capsule and mesh aligned and define remaining momentum. - scaling montage play rate changes displacement timing and gameplay windows. - child montage replacements may preserve timeline length while changing actual root trajectory. - root motion modes move animgraph work to the game thread; profile target characters. for directional or target-aligned actions, use motion/rotation warping only after the source root, target transform, sync points, and maximum allowed warp are explicit. gameplay collision and target validity remain authoritative. ue 5.8 primary sources ue 5.8 primary sources - animation montage - editing and using animation montage - animation slots - animation notifies - montage set next section - root motion - gameplay ability tasks - play montage and wait - uabilitytask playmontageandwait api - character movement networking pages were checked against the ue 5.8 documentation on 2026-07-19. reconfirm callback behavior, network assumptions, root-motion policy, and node/api names after an engine upgrade.","references":[{"slug":"action-selector","file":"action-selector.md","title":"Action selector","rawMarkdown":"# Action selector\n\n| Need | Prefer | Avoid |\n|---|---|---|\n| Persistent locomotion/mode | State Machine, Blend Space, Motion Matching | long looping Montage as primary locomotion |\n| One-shot full-body action | Montage through full-body Slot | state explosion for every action |\n| Upper-body action over locomotion | Montage Slot + Layered Blend per Bone | replacing the locomotion base |\n| Start-loop-end action | Montage Sections with runtime next-section change | restarting separate assets every loop |\n| Contextual animation variant, same timing contract | Child Montage or data-selected Montage | branching gameplay logic inside animation assets |\n| GAS-owned ability action | Play Montage and Wait Ability Task | unmanaged montage lifecycle |\n| Pure cosmetic one-frame response | short Montage or additive blend by complexity | authoritative gameplay in a cosmetic notify |\n\nBefore authoring, write:\n\n- who may start the action;\n- when commitment begins;\n- which inputs buffer or cancel it;\n- whether locomotion continues underneath;\n- who owns displacement/collision;\n- which outcomes are completed, interrupted, or cancelled.\n\nIf those are undefined, additional Montage Sections will conceal rather than solve the design gap.\n","webMarkdown":"| Need | Prefer | Avoid |\n|---|---|---|\n| Persistent locomotion/mode | State Machine, Blend Space, Motion Matching | long looping Montage as primary locomotion |\n| One-shot full-body action | Montage through full-body Slot | state explosion for every action |\n| Upper-body action over locomotion | Montage Slot + Layered Blend per Bone | replacing the locomotion base |\n| Start-loop-end action | Montage Sections with runtime next-section change | restarting separate assets every loop |\n| Contextual animation variant, same timing contract | Child Montage or data-selected Montage | branching gameplay logic inside animation assets |\n| GAS-owned ability action | Play Montage and Wait Ability Task | unmanaged montage lifecycle |\n| Pure cosmetic one-frame response | short Montage or additive blend by complexity | authoritative gameplay in a cosmetic notify |\n\nBefore authoring, write:\n\n- who may start the action;\n- when commitment begins;\n- which inputs buffer or cancel it;\n- whether locomotion continues underneath;\n- who owns displacement/collision;\n- which outcomes are completed, interrupted, or cancelled.\n\nIf those are undefined, additional Montage Sections will conceal rather than solve the design gap.\n","searchText":"action selector | need | prefer | avoid | |---|---|---| | persistent locomotion/mode | state machine, blend space, motion matching | long looping montage as primary locomotion | | one-shot full-body action | montage through full-body slot | state explosion for every action | | upper-body action over locomotion | montage slot + layered blend per bone | replacing the locomotion base | | start-loop-end action | montage sections with runtime next-section change | restarting separate assets every loop | | contextual animation variant, same timing contract | child montage or data-selected montage | branching gameplay logic inside animation assets | | gas-owned ability action | play montage and wait ability task | unmanaged montage lifecycle | | pure cosmetic one-frame response | short montage or additive blend by complexity | authoritative gameplay in a cosmetic notify | before authoring, write: - who may start the action; - when commitment begins; - which inputs buffer or cancel it; - whether locomotion continues underneath; - who owns displacement/collision; - which outcomes are completed, interrupted, or cancelled. if those are undefined, additional montage sections will conceal rather than solve the design gap."},{"slug":"asset-sections-and-slots","file":"asset-sections-and-slots.md","title":"Asset, Sections, and Slots","rawMarkdown":"# Asset, Sections, and Slots\n\n## Create\n\nCreate via Content Browser -> Animation -> Animation Montage and choose the Skeleton, or right-click\nan Animation Sequence -> Create -> Create AnimMontage. Add sequences to the Slot track.\n\n## Sections\n\nCreate named Sections at semantic boundaries, for example `Start`, `Loop`, `Release`, `Recovery`,\nor combo stages. A Section must begin at montage time zero. In the Sections panel, define the default\nnext section and preview each path. Keep names stable because Blueprint/C++ and GAS may reference them.\n\nUse `Montage Set Next Section` to relink what follows the current section, such as changing\n`Start -> Loop -> Loop` into `Loop -> End`. Use an immediate jump only when skipping the remaining\ncurrent-section motion is intended.\n\n## Slots and Slot Groups\n\nAdd Slot nodes to the AnimGraph at the point where actions should enter. A Montage exclusively plays\nthrough its Slot; a missing or bypassed node yields no visible pose. Use separate Slot Groups/body\nregions only when simultaneous actions are intended, then layer them explicitly.\n\nAvoid overlapping sequence segments on one Slot. When multiple Slot tracks represent variants, align\ntheir end-to-end timing and Section boundaries so runtime section calls mean the same thing.\n\nTypical regional order: locomotion base -> upper-body Slot -> Layered Blend per Bone/mask ->\ninertialization if used -> final IK. Full-body actions may use a Slot after locomotion and replace it.\n","webMarkdown":"## Create\n\nCreate via Content Browser -> Animation -> Animation Montage and choose the Skeleton, or right-click\nan Animation Sequence -> Create -> Create AnimMontage. Add sequences to the Slot track.\n\n## Sections\n\nCreate named Sections at semantic boundaries, for example `Start`, `Loop`, `Release`, `Recovery`,\nor combo stages. A Section must begin at montage time zero. In the Sections panel, define the default\nnext section and preview each path. Keep names stable because Blueprint/C++ and GAS may reference them.\n\nUse `Montage Set Next Section` to relink what follows the current section, such as changing\n`Start -> Loop -> Loop` into `Loop -> End`. Use an immediate jump only when skipping the remaining\ncurrent-section motion is intended.\n\n## Slots and Slot Groups\n\nAdd Slot nodes to the AnimGraph at the point where actions should enter. A Montage exclusively plays\nthrough its Slot; a missing or bypassed node yields no visible pose. Use separate Slot Groups/body\nregions only when simultaneous actions are intended, then layer them explicitly.\n\nAvoid overlapping sequence segments on one Slot. When multiple Slot tracks represent variants, align\ntheir end-to-end timing and Section boundaries so runtime section calls mean the same thing.\n\nTypical regional order: locomotion base -> upper-body Slot -> Layered Blend per Bone/mask ->\ninertialization if used -> final IK. Full-body actions may use a Slot after locomotion and replace it.\n","searchText":"asset, sections, and slots create create via content browser -> animation -> animation montage and choose the skeleton, or right-click an animation sequence -> create -> create animmontage. add sequences to the slot track. sections create named sections at semantic boundaries, for example start, loop, release, recovery, or combo stages. a section must begin at montage time zero. in the sections panel, define the default next section and preview each path. keep names stable because blueprint/c++ and gas may reference them. use montage set next section to relink what follows the current section, such as changing start -> loop -> loop into loop -> end. use an immediate jump only when skipping the remaining current-section motion is intended. slots and slot groups add slot nodes to the animgraph at the point where actions should enter. a montage exclusively plays through its slot; a missing or bypassed node yields no visible pose. use separate slot groups/body regions only when simultaneous actions are intended, then layer them explicitly. avoid overlapping sequence segments on one slot. when multiple slot tracks represent variants, align their end-to-end timing and section boundaries so runtime section calls mean the same thing. typical regional order: locomotion base -> upper-body slot -> layered blend per bone/mask -> inertialization if used -> final ik. full-body actions may use a slot after locomotion and replace it."},{"slug":"combos-loops-and-variants","file":"combos-loops-and-variants.md","title":"Combos, loops, and variants","rawMarkdown":"# Combos, loops, and variants\n\n## Combo sections\n\nCreate one Section per committed stage and explicit recovery/exit. During an input window, gameplay\nbuffers the next action. After validation, call `Montage Set Next Section` for the current stage to\nlink to the next. If no valid input arrives, retain or relink to recovery. Do not jump based solely on\nthe input press; use the action's legal cancel/chain window.\n\nProtect against stale input by tagging the buffered request with the current action/stage instance.\nClear it on consumption, interruption, cancellation, owner change, and timeout.\n\n## Start-loop-end\n\nDefault graph: `Start -> Loop`, `Loop -> Loop`, `End -> complete`. When gameplay ends the held action,\nrelink `Loop -> End`. Define behavior when release happens during Start, after the loop boundary, or\nwhile blending out.\n\n## Child Montages\n\nUse a Child Montage to replace animation segments while inheriting the parent's section/notify/slot\ncontract. Unreal adjusts replacement playback to the parent's time range, so visually inspect speed,\ncontacts, root motion, and notify alignment. Child Montages cannot parent another child.\n\nUse separate parent Montages when variants have different gameplay timing or topology. Do not force\nsubstantially different attacks into one inherited timing contract merely to reuse code.\n\n## Concurrent actions\n\nSlots in the same group can interrupt each other. Separate groups allow concurrency but can create\nconflicting bone ownership, root motion, or gameplay lifecycles. Define precedence explicitly and\ntest reload+hit reaction, aim+fire, and action+death cases.\n","webMarkdown":"## Combo sections\n\nCreate one Section per committed stage and explicit recovery/exit. During an input window, gameplay\nbuffers the next action. After validation, call `Montage Set Next Section` for the current stage to\nlink to the next. If no valid input arrives, retain or relink to recovery. Do not jump based solely on\nthe input press; use the action's legal cancel/chain window.\n\nProtect against stale input by tagging the buffered request with the current action/stage instance.\nClear it on consumption, interruption, cancellation, owner change, and timeout.\n\n## Start-loop-end\n\nDefault graph: `Start -> Loop`, `Loop -> Loop`, `End -> complete`. When gameplay ends the held action,\nrelink `Loop -> End`. Define behavior when release happens during Start, after the loop boundary, or\nwhile blending out.\n\n## Child Montages\n\nUse a Child Montage to replace animation segments while inheriting the parent's section/notify/slot\ncontract. Unreal adjusts replacement playback to the parent's time range, so visually inspect speed,\ncontacts, root motion, and notify alignment. Child Montages cannot parent another child.\n\nUse separate parent Montages when variants have different gameplay timing or topology. Do not force\nsubstantially different attacks into one inherited timing contract merely to reuse code.\n\n## Concurrent actions\n\nSlots in the same group can interrupt each other. Separate groups allow concurrency but can create\nconflicting bone ownership, root motion, or gameplay lifecycles. Define precedence explicitly and\ntest reload+hit reaction, aim+fire, and action+death cases.\n","searchText":"combos, loops, and variants combo sections create one section per committed stage and explicit recovery/exit. during an input window, gameplay buffers the next action. after validation, call montage set next section for the current stage to link to the next. if no valid input arrives, retain or relink to recovery. do not jump based solely on the input press; use the action's legal cancel/chain window. protect against stale input by tagging the buffered request with the current action/stage instance. clear it on consumption, interruption, cancellation, owner change, and timeout. start-loop-end default graph: start -> loop, loop -> loop, end -> complete. when gameplay ends the held action, relink loop -> end. define behavior when release happens during start, after the loop boundary, or while blending out. child montages use a child montage to replace animation segments while inheriting the parent's section/notify/slot contract. unreal adjusts replacement playback to the parent's time range, so visually inspect speed, contacts, root motion, and notify alignment. child montages cannot parent another child. use separate parent montages when variants have different gameplay timing or topology. do not force substantially different attacks into one inherited timing contract merely to reuse code. concurrent actions slots in the same group can interrupt each other. separate groups allow concurrency but can create conflicting bone ownership, root motion, or gameplay lifecycles. define precedence explicitly and test reload+hit reaction, aim+fire, and action+death cases."},{"slug":"debugging-patterns","file":"debugging-patterns.md","title":"Debugging patterns","rawMarkdown":"# Debugging patterns\n\n## Isolation ladder\n\n1. Confirm the Skeletal Mesh uses the expected AnimBP and Skeleton.\n2. Play the Montage in its editor and preview the intended Section path/Slot.\n3. Confirm the matching Slot node lies on the evaluated AnimGraph path.\n4. Play without layering; then restore Layered Blend per Bone/masks.\n5. Log play return, active montage/instance, current Section, position, weight, and callbacks.\n6. Disable root motion and notifies separately to isolate pose versus gameplay/movement faults.\n7. Test standalone, listen server, owning client, simulated client, and dedicated server.\n\n| Symptom | First check |\n|---|---|\n| Montage reports playing but invisible | missing/bypassed Slot node, wrong Slot/Group |\n| Upper body affects legs | layer branch bone/mask and mesh skeleton |\n| Stops unexpectedly | competing montage in same Slot Group, ability cancel |\n| Combo never advances | Section names, current Section, next-section relink timing |\n| Loop never exits | wrong `From Section`, relink after boundary, stale input |\n| Notify callback absent | playback node type, Montage Notify type, Slot/link/filter settings |\n| End event missing | interruption/cancel path not handled |\n| Mesh snaps to capsule | root motion disabled/mode mismatch/root lock |\n| Server/client differ | playback trigger and gameplay state not replicated/predicted coherently |\n| Works at normal rate only | notify window/section boundary tied to frames rather than semantics |\n\nAcceptance suite: early/late cancel, overlapping action request, same-group interruption, death/stun,\nowner destruction, extreme play rate, low FPS, root-motion obstacle, network latency/loss, and every\nterminal callback.\n","webMarkdown":"## Isolation ladder\n\n1. Confirm the Skeletal Mesh uses the expected AnimBP and Skeleton.\n2. Play the Montage in its editor and preview the intended Section path/Slot.\n3. Confirm the matching Slot node lies on the evaluated AnimGraph path.\n4. Play without layering; then restore Layered Blend per Bone/masks.\n5. Log play return, active montage/instance, current Section, position, weight, and callbacks.\n6. Disable root motion and notifies separately to isolate pose versus gameplay/movement faults.\n7. Test standalone, listen server, owning client, simulated client, and dedicated server.\n\n| Symptom | First check |\n|---|---|\n| Montage reports playing but invisible | missing/bypassed Slot node, wrong Slot/Group |\n| Upper body affects legs | layer branch bone/mask and mesh skeleton |\n| Stops unexpectedly | competing montage in same Slot Group, ability cancel |\n| Combo never advances | Section names, current Section, next-section relink timing |\n| Loop never exits | wrong `From Section`, relink after boundary, stale input |\n| Notify callback absent | playback node type, Montage Notify type, Slot/link/filter settings |\n| End event missing | interruption/cancel path not handled |\n| Mesh snaps to capsule | root motion disabled/mode mismatch/root lock |\n| Server/client differ | playback trigger and gameplay state not replicated/predicted coherently |\n| Works at normal rate only | notify window/section boundary tied to frames rather than semantics |\n\nAcceptance suite: early/late cancel, overlapping action request, same-group interruption, death/stun,\nowner destruction, extreme play rate, low FPS, root-motion obstacle, network latency/loss, and every\nterminal callback.\n","searchText":"debugging patterns isolation ladder 1. confirm the skeletal mesh uses the expected animbp and skeleton. 2. play the montage in its editor and preview the intended section path/slot. 3. confirm the matching slot node lies on the evaluated animgraph path. 4. play without layering; then restore layered blend per bone/masks. 5. log play return, active montage/instance, current section, position, weight, and callbacks. 6. disable root motion and notifies separately to isolate pose versus gameplay/movement faults. 7. test standalone, listen server, owning client, simulated client, and dedicated server. | symptom | first check | |---|---| | montage reports playing but invisible | missing/bypassed slot node, wrong slot/group | | upper body affects legs | layer branch bone/mask and mesh skeleton | | stops unexpectedly | competing montage in same slot group, ability cancel | | combo never advances | section names, current section, next-section relink timing | | loop never exits | wrong from section, relink after boundary, stale input | | notify callback absent | playback node type, montage notify type, slot/link/filter settings | | end event missing | interruption/cancel path not handled | | mesh snaps to capsule | root motion disabled/mode mismatch/root lock | | server/client differ | playback trigger and gameplay state not replicated/predicted coherently | | works at normal rate only | notify window/section boundary tied to frames rather than semantics | acceptance suite: early/late cancel, overlapping action request, same-group interruption, death/stun, owner destruction, extreme play rate, low fps, root-motion obstacle, network latency/loss, and every terminal callback."},{"slug":"gas-and-networking","file":"gas-and-networking.md","title":"GAS and networking","rawMarkdown":"# GAS and networking\n\n## GAS\n\nUse `Play Montage and Wait` when the Gameplay Ability owns the action. Supply Montage, rate, optional\nstart Section/time, root-motion translation scale, and `Stop when Ability Ends` deliberately.\n\nHandle every output:\n\n- **On Completed**: normal montage completion.\n- **On Blend Out**: visual blend-out began; not identical to completion.\n- **On Interrupted**: another montage/action displaced it.\n- **On Cancelled**: task/ability cancellation.\n- **On Blended In**: optional point when full action pose is established.\n\nThe task always stops on explicit ability cancellation. If Stop When Ability Ends is true, normal\nability end also aborts it. End/cancel the ability and clean gameplay windows on all terminal paths.\nCustom projects often combine montage waiting with Gameplay Events; keep event tags and action\ninstance validation explicit.\n\n## Network contract\n\nStarting a Montage on one machine does not by itself start equivalent gameplay on every peer. The\nserver validates the action; the owning client may predict if the system supports it; simulated peers\nreceive replicated gameplay state/cues or an appropriate multicast/ability path and play presentation.\n\nEpic's Montage documentation notes that an RPC must carry the Play Montage trigger; only root-motion\nreplication/correction is carried by the root-motion movement path. Notifies, Sections, hit results,\nand arbitrary gameplay state are not automatically replicated by root-motion correction.\n\nTest authority, autonomous proxy, simulated proxy, dedicated server, latency/loss, correction during\nroot motion, cancellation, relevancy loss, and replay/late state. Deduplicate predicted cosmetic cues\nwhen confirmed events arrive.\n","webMarkdown":"## GAS\n\nUse `Play Montage and Wait` when the Gameplay Ability owns the action. Supply Montage, rate, optional\nstart Section/time, root-motion translation scale, and `Stop when Ability Ends` deliberately.\n\nHandle every output:\n\n- **On Completed**: normal montage completion.\n- **On Blend Out**: visual blend-out began; not identical to completion.\n- **On Interrupted**: another montage/action displaced it.\n- **On Cancelled**: task/ability cancellation.\n- **On Blended In**: optional point when full action pose is established.\n\nThe task always stops on explicit ability cancellation. If Stop When Ability Ends is true, normal\nability end also aborts it. End/cancel the ability and clean gameplay windows on all terminal paths.\nCustom projects often combine montage waiting with Gameplay Events; keep event tags and action\ninstance validation explicit.\n\n## Network contract\n\nStarting a Montage on one machine does not by itself start equivalent gameplay on every peer. The\nserver validates the action; the owning client may predict if the system supports it; simulated peers\nreceive replicated gameplay state/cues or an appropriate multicast/ability path and play presentation.\n\nEpic's Montage documentation notes that an RPC must carry the Play Montage trigger; only root-motion\nreplication/correction is carried by the root-motion movement path. Notifies, Sections, hit results,\nand arbitrary gameplay state are not automatically replicated by root-motion correction.\n\nTest authority, autonomous proxy, simulated proxy, dedicated server, latency/loss, correction during\nroot motion, cancellation, relevancy loss, and replay/late state. Deduplicate predicted cosmetic cues\nwhen confirmed events arrive.\n","searchText":"gas and networking gas use play montage and wait when the gameplay ability owns the action. supply montage, rate, optional start section/time, root-motion translation scale, and stop when ability ends deliberately. handle every output: - on completed: normal montage completion. - on blend out: visual blend-out began; not identical to completion. - on interrupted: another montage/action displaced it. - on cancelled: task/ability cancellation. - on blended in: optional point when full action pose is established. the task always stops on explicit ability cancellation. if stop when ability ends is true, normal ability end also aborts it. end/cancel the ability and clean gameplay windows on all terminal paths. custom projects often combine montage waiting with gameplay events; keep event tags and action instance validation explicit. network contract starting a montage on one machine does not by itself start equivalent gameplay on every peer. the server validates the action; the owning client may predict if the system supports it; simulated peers receive replicated gameplay state/cues or an appropriate multicast/ability path and play presentation. epic's montage documentation notes that an rpc must carry the play montage trigger; only root-motion replication/correction is carried by the root-motion movement path. notifies, sections, hit results, and arbitrary gameplay state are not automatically replicated by root-motion correction. test authority, autonomous proxy, simulated proxy, dedicated server, latency/loss, correction during root motion, cancellation, relevancy loss, and replay/late state. deduplicate predicted cosmetic cues when confirmed events arrive."},{"slug":"notifies-and-gameplay-windows","file":"notifies-and-gameplay-windows.md","title":"Notifies and gameplay windows","rawMarkdown":"# Notifies and gameplay windows\n\n## Choose the signal\n\n- **Anim Notify**: one instant, such as a footstep or cosmetic cue.\n- **Notify State**: begin/tick/end window, such as trace-active, invulnerability, or input acceptance.\n- **Montage Notify / Montage Notify Window**: emits Play Montage proxy notify callbacks.\n- **Branching Point timing**: precise synchronous ordering for a gameplay branch; more expensive.\n- **Queued timing**: asynchronous and cheaper when minor frame imprecision is acceptable.\n\n`Trigger Weight Threshold`, LOD filtering, dedicated-server firing, follower behavior, trigger chance,\nand link method can all change delivery. Choose Relative/Proportional linking when a notify should\nfollow a moved/scaled montage segment; use Absolute only when timeline position must remain fixed.\n\n## Authority boundary\n\nUse notifies to align presentation and request bounded gameplay transitions. The gameplay owner still\nchecks current action instance, authority, targets, and idempotence before applying damage or durable\nstate. Network peers can cross an animation frame at different times; a cosmetic notify is not proof\nthat the server accepted the action.\n\nFor melee, a robust window is:\n\n1. server/predicted ability owns the attack;\n2. Notify State begins and enables a trace for that action instance;\n3. each target is deduplicated;\n4. authoritative hit validation applies effects;\n5. Notify State ends or interruption cleanup disables the trace.\n\nTest skipped sections, high play rate, low frame rate, blend-out during a window, and interruption\nbefore both Begin and End.\n","webMarkdown":"## Choose the signal\n\n- **Anim Notify**: one instant, such as a footstep or cosmetic cue.\n- **Notify State**: begin/tick/end window, such as trace-active, invulnerability, or input acceptance.\n- **Montage Notify / Montage Notify Window**: emits Play Montage proxy notify callbacks.\n- **Branching Point timing**: precise synchronous ordering for a gameplay branch; more expensive.\n- **Queued timing**: asynchronous and cheaper when minor frame imprecision is acceptable.\n\n`Trigger Weight Threshold`, LOD filtering, dedicated-server firing, follower behavior, trigger chance,\nand link method can all change delivery. Choose Relative/Proportional linking when a notify should\nfollow a moved/scaled montage segment; use Absolute only when timeline position must remain fixed.\n\n## Authority boundary\n\nUse notifies to align presentation and request bounded gameplay transitions. The gameplay owner still\nchecks current action instance, authority, targets, and idempotence before applying damage or durable\nstate. Network peers can cross an animation frame at different times; a cosmetic notify is not proof\nthat the server accepted the action.\n\nFor melee, a robust window is:\n\n1. server/predicted ability owns the attack;\n2. Notify State begins and enables a trace for that action instance;\n3. each target is deduplicated;\n4. authoritative hit validation applies effects;\n5. Notify State ends or interruption cleanup disables the trace.\n\nTest skipped sections, high play rate, low frame rate, blend-out during a window, and interruption\nbefore both Begin and End.\n","searchText":"notifies and gameplay windows choose the signal - anim notify: one instant, such as a footstep or cosmetic cue. - notify state: begin/tick/end window, such as trace-active, invulnerability, or input acceptance. - montage notify / montage notify window: emits play montage proxy notify callbacks. - branching point timing: precise synchronous ordering for a gameplay branch; more expensive. - queued timing: asynchronous and cheaper when minor frame imprecision is acceptable. trigger weight threshold, lod filtering, dedicated-server firing, follower behavior, trigger chance, and link method can all change delivery. choose relative/proportional linking when a notify should follow a moved/scaled montage segment; use absolute only when timeline position must remain fixed. authority boundary use notifies to align presentation and request bounded gameplay transitions. the gameplay owner still checks current action instance, authority, targets, and idempotence before applying damage or durable state. network peers can cross an animation frame at different times; a cosmetic notify is not proof that the server accepted the action. for melee, a robust window is: 1. server/predicted ability owns the attack; 2. notify state begins and enables a trace for that action instance; 3. each target is deduplicated; 4. authoritative hit validation applies effects; 5. notify state ends or interruption cleanup disables the trace. test skipped sections, high play rate, low frame rate, blend-out during a window, and interruption before both begin and end."},{"slug":"playback-and-lifecycle","file":"playback-and-lifecycle.md","title":"Playback and lifecycle","rawMarkdown":"# Playback and lifecycle\n\n## Choose playback API\n\n- **AnimInstance Montage functions**: direct control for systems already owning the AnimInstance.\n- **Play Montage proxy node**: exposes Completed, Blend Out, Interrupted, Notify Begin, and Notify End.\n- **Play Anim Montage**: simpler Character convenience function, without the same proxy notify outputs.\n- **GAS Play Montage and Wait**: action lifecycle owned by a Gameplay Ability.\n\n## Ordered lifecycle\n\n1. Gameplay verifies eligibility and commits the action at the intended point.\n2. Set required state/parameters before playback.\n3. Play the Montage at rate/start section or time.\n4. Treat a failed/zero-length play result as failure and unwind state.\n5. React to notify windows and section changes without assuming completion.\n6. On Blend Out, stop spawning new action work if visual recovery has begun.\n7. On Completed, perform normal cleanup/completion.\n8. On Interrupted or Cancelled, perform interruption cleanup and rollback only what is reversible.\n9. Clean up when owner/ability ends even if no expected callback arrives.\n\nDo not bind a second action to stale callbacks from the first. When using delegates in C++, bind them\nto the specific montage instance/lifecycle and unbind on cleanup.\n\nStopping with blend time does not mean the action remains gameplay-active for that blend. Define\nwhether commitment ends at cancel request, blend-out start, notify end, or montage completion.\n","webMarkdown":"## Choose playback API\n\n- **AnimInstance Montage functions**: direct control for systems already owning the AnimInstance.\n- **Play Montage proxy node**: exposes Completed, Blend Out, Interrupted, Notify Begin, and Notify End.\n- **Play Anim Montage**: simpler Character convenience function, without the same proxy notify outputs.\n- **GAS Play Montage and Wait**: action lifecycle owned by a Gameplay Ability.\n\n## Ordered lifecycle\n\n1. Gameplay verifies eligibility and commits the action at the intended point.\n2. Set required state/parameters before playback.\n3. Play the Montage at rate/start section or time.\n4. Treat a failed/zero-length play result as failure and unwind state.\n5. React to notify windows and section changes without assuming completion.\n6. On Blend Out, stop spawning new action work if visual recovery has begun.\n7. On Completed, perform normal cleanup/completion.\n8. On Interrupted or Cancelled, perform interruption cleanup and rollback only what is reversible.\n9. Clean up when owner/ability ends even if no expected callback arrives.\n\nDo not bind a second action to stale callbacks from the first. When using delegates in C++, bind them\nto the specific montage instance/lifecycle and unbind on cleanup.\n\nStopping with blend time does not mean the action remains gameplay-active for that blend. Define\nwhether commitment ends at cancel request, blend-out start, notify end, or montage completion.\n","searchText":"playback and lifecycle choose playback api - animinstance montage functions: direct control for systems already owning the animinstance. - play montage proxy node: exposes completed, blend out, interrupted, notify begin, and notify end. - play anim montage: simpler character convenience function, without the same proxy notify outputs. - gas play montage and wait: action lifecycle owned by a gameplay ability. ordered lifecycle 1. gameplay verifies eligibility and commits the action at the intended point. 2. set required state/parameters before playback. 3. play the montage at rate/start section or time. 4. treat a failed/zero-length play result as failure and unwind state. 5. react to notify windows and section changes without assuming completion. 6. on blend out, stop spawning new action work if visual recovery has begun. 7. on completed, perform normal cleanup/completion. 8. on interrupted or cancelled, perform interruption cleanup and rollback only what is reversible. 9. clean up when owner/ability ends even if no expected callback arrives. do not bind a second action to stale callbacks from the first. when using delegates in c++, bind them to the specific montage instance/lifecycle and unbind on cleanup. stopping with blend time does not mean the action remains gameplay-active for that blend. define whether commitment ends at cancel request, blend-out start, notify end, or montage completion."},{"slug":"root-motion-and-movement","file":"root-motion-and-movement.md","title":"Root motion and movement","rawMarkdown":"# Root motion and movement\n\n## Contract\n\n1. Verify the source asset has an animated root bone and Enable Root Motion is set.\n2. Choose Root Motion Root Lock: reference pose, animation first frame, or zero, based on the asset.\n3. In AnimBP Class Defaults choose the intended Root Motion Mode. For network-oriented montage root\n   motion, use **Root Motion from Montages Only**.\n4. Decide how Character Movement mode handles vertical displacement. Walking/Falling apply movement\n   physics differently from Flying.\n5. Test capsule/mesh alignment, collision, slopes, stairs, interruption, correction, and blend-out.\n\nRoot motion moves the collision-owning character through the movement system; do not separately add\nthe same displacement in gameplay code. Conversely, in-place actions need code-driven movement when\ndisplacement matters.\n\n## Section/cancel hazards\n\n- Jumping into a Section can skip root displacement that the following frames assume occurred.\n- Interrupting a lunge must leave capsule and mesh aligned and define remaining momentum.\n- Scaling montage play rate changes displacement timing and gameplay windows.\n- Child Montage replacements may preserve timeline length while changing actual root trajectory.\n- Root Motion modes move AnimGraph work to the Game Thread; profile target characters.\n\nFor directional or target-aligned actions, use motion/rotation warping only after the source root,\ntarget transform, sync points, and maximum allowed warp are explicit. Gameplay collision and target\nvalidity remain authoritative.\n","webMarkdown":"## Contract\n\n1. Verify the source asset has an animated root bone and Enable Root Motion is set.\n2. Choose Root Motion Root Lock: reference pose, animation first frame, or zero, based on the asset.\n3. In AnimBP Class Defaults choose the intended Root Motion Mode. For network-oriented montage root\n   motion, use **Root Motion from Montages Only**.\n4. Decide how Character Movement mode handles vertical displacement. Walking/Falling apply movement\n   physics differently from Flying.\n5. Test capsule/mesh alignment, collision, slopes, stairs, interruption, correction, and blend-out.\n\nRoot motion moves the collision-owning character through the movement system; do not separately add\nthe same displacement in gameplay code. Conversely, in-place actions need code-driven movement when\ndisplacement matters.\n\n## Section/cancel hazards\n\n- Jumping into a Section can skip root displacement that the following frames assume occurred.\n- Interrupting a lunge must leave capsule and mesh aligned and define remaining momentum.\n- Scaling montage play rate changes displacement timing and gameplay windows.\n- Child Montage replacements may preserve timeline length while changing actual root trajectory.\n- Root Motion modes move AnimGraph work to the Game Thread; profile target characters.\n\nFor directional or target-aligned actions, use motion/rotation warping only after the source root,\ntarget transform, sync points, and maximum allowed warp are explicit. Gameplay collision and target\nvalidity remain authoritative.\n","searchText":"root motion and movement contract 1. verify the source asset has an animated root bone and enable root motion is set. 2. choose root motion root lock: reference pose, animation first frame, or zero, based on the asset. 3. in animbp class defaults choose the intended root motion mode. for network-oriented montage root motion, use root motion from montages only. 4. decide how character movement mode handles vertical displacement. walking/falling apply movement physics differently from flying. 5. test capsule/mesh alignment, collision, slopes, stairs, interruption, correction, and blend-out. root motion moves the collision-owning character through the movement system; do not separately add the same displacement in gameplay code. conversely, in-place actions need code-driven movement when displacement matters. section/cancel hazards - jumping into a section can skip root displacement that the following frames assume occurred. - interrupting a lunge must leave capsule and mesh aligned and define remaining momentum. - scaling montage play rate changes displacement timing and gameplay windows. - child montage replacements may preserve timeline length while changing actual root trajectory. - root motion modes move animgraph work to the game thread; profile target characters. for directional or target-aligned actions, use motion/rotation warping only after the source root, target transform, sync points, and maximum allowed warp are explicit. gameplay collision and target validity remain authoritative."},{"slug":"sources","file":"sources.md","title":"UE 5.8 primary sources","rawMarkdown":"# UE 5.8 primary sources\n\n- [Animation Montage](https://dev.epicgames.com/documentation/en-us/unreal-engine/animation-montage-in-unreal-engine)\n- [Editing and Using Animation Montage](https://dev.epicgames.com/documentation/en-us/unreal-engine/animation-montage-editor-in-unreal-engine)\n- [Animation Slots](https://dev.epicgames.com/documentation/en-us/unreal-engine/animation-slots-in-unreal-engine)\n- [Animation Notifies](https://dev.epicgames.com/documentation/en-us/unreal-engine/animation-notifies-in-unreal-engine)\n- [Montage Set Next Section](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/Animation/Montage/MontageSetNextSection)\n- [Root Motion](https://dev.epicgames.com/documentation/en-us/unreal-engine/root-motion-in-unreal-engine)\n- [Gameplay Ability Tasks](https://dev.epicgames.com/documentation/en-us/unreal-engine/gameplay-ability-tasks-in-unreal-engine)\n- [Play Montage and Wait](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/Ability/Tasks/PlayMontageAndWait)\n- [UAbilityTask PlayMontageAndWait API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/GameplayAbilities/UAbilityTask_PlayMontageAndWait)\n- [Character Movement Networking](https://dev.epicgames.com/documentation/en-us/unreal-engine/understanding-networked-movement-in-the-character-movement-component-for-unreal-engine)\n\nPages were checked against the UE 5.8 documentation on 2026-07-19. Reconfirm callback behavior,\nnetwork assumptions, root-motion policy, and node/API names after an engine upgrade.\n","webMarkdown":"- [Animation Montage](https://dev.epicgames.com/documentation/en-us/unreal-engine/animation-montage-in-unreal-engine)\n- [Editing and Using Animation Montage](https://dev.epicgames.com/documentation/en-us/unreal-engine/animation-montage-editor-in-unreal-engine)\n- [Animation Slots](https://dev.epicgames.com/documentation/en-us/unreal-engine/animation-slots-in-unreal-engine)\n- [Animation Notifies](https://dev.epicgames.com/documentation/en-us/unreal-engine/animation-notifies-in-unreal-engine)\n- [Montage Set Next Section](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/Animation/Montage/MontageSetNextSection)\n- [Root Motion](https://dev.epicgames.com/documentation/en-us/unreal-engine/root-motion-in-unreal-engine)\n- [Gameplay Ability Tasks](https://dev.epicgames.com/documentation/en-us/unreal-engine/gameplay-ability-tasks-in-unreal-engine)\n- [Play Montage and Wait](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/Ability/Tasks/PlayMontageAndWait)\n- [UAbilityTask PlayMontageAndWait API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/GameplayAbilities/UAbilityTask_PlayMontageAndWait)\n- [Character Movement Networking](https://dev.epicgames.com/documentation/en-us/unreal-engine/understanding-networked-movement-in-the-character-movement-component-for-unreal-engine)\n\nPages were checked against the UE 5.8 documentation on 2026-07-19. Reconfirm callback behavior,\nnetwork assumptions, root-motion policy, and node/API names after an engine upgrade.\n","searchText":"ue 5.8 primary sources - animation montage - editing and using animation montage - animation slots - animation notifies - montage set next section - root motion - gameplay ability tasks - play montage and wait - uabilitytask playmontageandwait api - character movement networking pages were checked against the ue 5.8 documentation on 2026-07-19. reconfirm callback behavior, network assumptions, root-motion policy, and node/api names after an engine upgrade."}]}
{"slug":"unreal-blueprint-architecture","name":"unreal-blueprint-architecture","title":"Unreal 5.8 Blueprint Architecture","description":"Design, refactor, and debug maintainable Blueprint gameplay architecture in Unreal Engine 5.8. Use for choosing Actors, Actor Components, Blueprint Interfaces, Event Dispatchers, direct references, Subsystems, Data Assets, function libraries, C++ boundaries, Construction Script behavior, dependency direction, lifecycle, or Blueprint performance patterns.","shortDescription":"Structure scalable Blueprint gameplay systems","category":"Data, Tools & Shipping","referenceCount":6,"rawMarkdown":"---\nname: unreal-blueprint-architecture\ndescription: Design, refactor, and debug maintainable Blueprint gameplay architecture in Unreal Engine 5.8. Use for choosing Actors, Actor Components, Blueprint Interfaces, Event Dispatchers, direct references, Subsystems, Data Assets, function libraries, C++ boundaries, Construction Script behavior, dependency direction, lifecycle, or Blueprint performance patterns.\n---\n\n# Unreal 5.8 Blueprint Architecture\n\n## Select the owner and lifetime\n\nRead [`references/system-selector.md`](references/system-selector.md) before choosing a\nclass. Put behavior on the object with the shortest correct lifetime and clear ownership.\n\n- Use an **Actor** for an independently placed, spawned, replicated, or transformed entity.\n- Use an **Actor Component** for a reusable capability owned by an Actor.\n- Use a **GameInstance Subsystem** for one service spanning maps in one game instance.\n- Use a **LocalPlayer Subsystem** for per-local-player services and split-screen isolation.\n- Use a **World Subsystem** for one service per World.\n- Use a **Data Asset** for authored definitions; keep mutable runtime state elsewhere.\n- Use a **Blueprint Function Library** only for stateless operations.\n\n## Select communication\n\nRead [`references/communication-patterns.md`](references/communication-patterns.md).\n\n1. Use a direct reference for a stable one-to-one relationship.\n2. Use a Blueprint Interface when the caller has a target but should not depend on its\n   concrete class.\n3. Use an Event Dispatcher when one known publisher notifies zero or more listeners.\n4. Use a subsystem/message router for many-to-many, cross-system events with deliberate\n   scope and debugging.\n5. Do not replace clear one-to-one calls with global messaging.\n\n## Execute\n\n1. State ownership, lifetime, authority, and save/replication requirements.\n2. Draw dependency direction before adding references.\n3. Keep reusable capability logic in components; access owners through interfaces where\n   concrete casts would defeat reuse.\n4. Keep Blueprint graphs event-driven. Replace repeated Tick work with events, timers,\n   or invalidation unless continuous per-frame evaluation is required.\n5. Keep Construction Script idempotent and editor-safe. Put runtime mutation in explicit\n   runtime functions.\n6. Move stable contracts, high-frequency work, networking foundations, and merge-heavy\n   shared systems to C++; expose deliberate Blueprint-facing APIs.\n7. Test lifecycle, duplicate binding, teardown, map travel, respawn, multiplayer authority,\n   and packaged behavior.\n\nRead [`references/use-cases.md`](references/use-cases.md) for concrete layouts and\n[`references/lifecycle-performance.md`](references/lifecycle-performance.md) for execution\nboundaries. Use [`references/troubleshooting.md`](references/troubleshooting.md) when a\nsystem becomes coupled, fires twice, retains stale references, or behaves differently in\nthe editor and runtime.\n\n## Required answer format\n\nReturn:\n\n1. **Class/component layout** and ownership.\n2. **Communication choice** and why alternatives were rejected.\n3. **Ordered implementation actions** with named nodes/APIs where verified.\n4. **State, lifetime, authority, and replication boundaries**.\n5. **Dependencies and asset-reference consequences**.\n6. **Failure checks** and a packaged-build verification procedure.\n\nDo not invent Blueprint nodes, editor paths, defaults, or replication behavior.\n\n## Hard rules\n\n- Avoid gameplay logic in Level Blueprints unless it truly belongs to that level.\n- Never use `Get All Actors of Class` as routine dependency injection.\n- Never bind a delegate repeatedly without a matching unbind or one-time guard.\n- Never store mutable session state in a Data Asset or class default object.\n- Treat Interfaces as contracts, not object discovery; a target reference is still needed.\n- Treat Event Dispatchers as publisher-owned signals, not global message buses.\n- Profile before moving Blueprint code to C++, but keep per-frame loops and complex math\n  under suspicion.\n\nSee [`references/sources.md`](references/sources.md) for the UE 5.8 source trail.\n","webMarkdown":"## Select the owner and lifetime\n\nRead [`references/system-selector.md`](/unreal/unreal-blueprint-architecture/system-selector/) before choosing a\nclass. Put behavior on the object with the shortest correct lifetime and clear ownership.\n\n- Use an **Actor** for an independently placed, spawned, replicated, or transformed entity.\n- Use an **Actor Component** for a reusable capability owned by an Actor.\n- Use a **GameInstance Subsystem** for one service spanning maps in one game instance.\n- Use a **LocalPlayer Subsystem** for per-local-player services and split-screen isolation.\n- Use a **World Subsystem** for one service per World.\n- Use a **Data Asset** for authored definitions; keep mutable runtime state elsewhere.\n- Use a **Blueprint Function Library** only for stateless operations.\n\n## Select communication\n\nRead [`references/communication-patterns.md`](/unreal/unreal-blueprint-architecture/communication-patterns/).\n\n1. Use a direct reference for a stable one-to-one relationship.\n2. Use a Blueprint Interface when the caller has a target but should not depend on its\n   concrete class.\n3. Use an Event Dispatcher when one known publisher notifies zero or more listeners.\n4. Use a subsystem/message router for many-to-many, cross-system events with deliberate\n   scope and debugging.\n5. Do not replace clear one-to-one calls with global messaging.\n\n## Execute\n\n1. State ownership, lifetime, authority, and save/replication requirements.\n2. Draw dependency direction before adding references.\n3. Keep reusable capability logic in components; access owners through interfaces where\n   concrete casts would defeat reuse.\n4. Keep Blueprint graphs event-driven. Replace repeated Tick work with events, timers,\n   or invalidation unless continuous per-frame evaluation is required.\n5. Keep Construction Script idempotent and editor-safe. Put runtime mutation in explicit\n   runtime functions.\n6. Move stable contracts, high-frequency work, networking foundations, and merge-heavy\n   shared systems to C++; expose deliberate Blueprint-facing APIs.\n7. Test lifecycle, duplicate binding, teardown, map travel, respawn, multiplayer authority,\n   and packaged behavior.\n\nRead [`references/use-cases.md`](/unreal/unreal-blueprint-architecture/use-cases/) for concrete layouts and\n[`references/lifecycle-performance.md`](/unreal/unreal-blueprint-architecture/lifecycle-performance/) for execution\nboundaries. Use [`references/troubleshooting.md`](/unreal/unreal-blueprint-architecture/troubleshooting/) when a\nsystem becomes coupled, fires twice, retains stale references, or behaves differently in\nthe editor and runtime.\n\n## Required answer format\n\nReturn:\n\n1. **Class/component layout** and ownership.\n2. **Communication choice** and why alternatives were rejected.\n3. **Ordered implementation actions** with named nodes/APIs where verified.\n4. **State, lifetime, authority, and replication boundaries**.\n5. **Dependencies and asset-reference consequences**.\n6. **Failure checks** and a packaged-build verification procedure.\n\nDo not invent Blueprint nodes, editor paths, defaults, or replication behavior.\n\n## Hard rules\n\n- Avoid gameplay logic in Level Blueprints unless it truly belongs to that level.\n- Never use `Get All Actors of Class` as routine dependency injection.\n- Never bind a delegate repeatedly without a matching unbind or one-time guard.\n- Never store mutable session state in a Data Asset or class default object.\n- Treat Interfaces as contracts, not object discovery; a target reference is still needed.\n- Treat Event Dispatchers as publisher-owned signals, not global message buses.\n- Profile before moving Blueprint code to C++, but keep per-frame loops and complex math\n  under suspicion.\n\nSee [`references/sources.md`](/unreal/unreal-blueprint-architecture/sources/) for the UE 5.8 source trail.\n","searchText":"unreal 5.8 blueprint architecture design, refactor, and debug maintainable blueprint gameplay architecture in unreal engine 5.8. use for choosing actors, actor components, blueprint interfaces, event dispatchers, direct references, subsystems, data assets, function libraries, c++ boundaries, construction script behavior, dependency direction, lifecycle, or blueprint performance patterns. communication patterns communication patterns direct reference use when one caller owns or is explicitly configured with one target. 1. expose an object reference, assign it at spawn/configuration, or obtain it from a known framework relationship. 2. validate the reference at the use boundary. 3. call the typed function directly. this is the clearest option. a cast does not find an object; it only tests/converts an existing reference. avoid repeated discovery calls. blueprint interface use when the caller has a target but multiple unrelated classes implement the operation. 1. create a blueprint interface containing the smallest stable function contract. 2. implement it on each responder. 3. obtain a target reference through overlap, trace, ownership, configuration, or spawn. 4. call the interface message on that reference. 5. define what a non-implementing target means; do not silently depend on a response. example: an interaction trace calls interact on doors, pickups, and terminals without casting to each concrete class. event dispatcher use when one known publisher emits a signal to zero or more listeners. 1. declare the dispatcher on the publisher. 2. give the payload the minimum data listeners need. 3. listeners obtain the publisher and bind once during a defined lifecycle event. 4. publisher calls the dispatcher after its authoritative state change. 5. listeners unbind on teardown or when switching publishers. the publisher owns the event; listeners own their reactions. guard against duplicate binds. subsystem or message router use for deliberately scoped many-to-many communication, not as a default. 1. choose lifetime: gameinstance, world, or localplayer. 2. define message channel identifiers and payload structs. 3. register listeners and retain handles where the api requires them. 4. broadcast only after authoritative state is valid. 5. log channel, source, target scope, and payload in development builds. 6. unregister on teardown. global messaging hides dependency and ordering. document who may publish, whether messages cross the network, and whether late subscribers need current state separately. choice table | relationship | pattern | |---|---| | one caller → one concrete target | direct reference | | one caller → one target behind a shared contract | interface | | one publisher → many listeners | event dispatcher | | many publishers → many listeners | scoped message router | | listener needs current value, not merely an occurrence | query owned state, then subscribe to changes | lifecycle and performance lifecycle and performance construction versus runtime construction script can rerun in the editor when an instance changes. make it idempotent: 1. clear or reuse previously generated objects/components. 2. derive output entirely from current exposed inputs. 3. avoid irreversible external side effects. 4. do not assume beginplay has run. 5. verify placed, duplicated, moved, recompiled, spawned, and packaged instances. use beginplay or an explicit runtime initialization function for runtime bindings and mutable session state. pair every binding, timer, spawned helper, and registration with cleanup. tick decision keep tick only when the value genuinely depends on every rendered/simulation frame. otherwise: - state changed → call an event; - fixed cadence → timer; - animation presentation → animation blueprint/native animation systems; - delayed one-shot → timer or latent action with lifecycle guard; - ui change → dispatcher/delegate/field notification; - expensive repeated query → cache and invalidate. if tick remains, disable it by default where possible, enable only while active, scale motion by delta seconds, avoid world scans and allocation, and profile on target hardware. references and loading a hard class/object reference can pull referenced assets into the dependency/load graph. use soft references when the asset is optional or should load asynchronously. use primary assets when identity, discovery, bundles, cooking rules, or controlled loading justify asset manager integration. verify with reference viewer and packaged/cooked tests. multiplayer boundary blueprint communication does not itself replicate. decide separately: - who owns authority; - which properties replicate and with what notification; - which rpc direction is legal; - whether a dispatcher is local reaction to replicated state; - whether a message router is local-only. never assume a client-side dispatcher call reaches the server or other clients. ue 5.8 primary sources ue 5.8 primary sources verified 2026-07-19. prefer these pages over remembered node names or third-party tutorials. - blueprint best practices - blueprint communication usage - actor communication - programming subsystems - data assets - asset management version note: the epic pages above currently resolve to unreal engine 5.8 documentation. subsystem lifetime and asset-loading claims are taken from epic's 5.8 pages. blueprint communication patterns are architectural choices; they do not add network replication. system selector system selector choose by ownership and lifetime before convenience. | need | use | avoid when | |---|---|---| | placed/spawned world entity with transform, collision, replication, or independent lifetime | actor | it is only a reusable capability of another actor | | reusable capability attached to actors | actor component | it needs its own transform; use scene component or actor as appropriate | | reusable transform-bearing subobject | scene component | it must exist independently or replicate as an actor | | service lasting for one engine process | engine subsystem | state should reset per game instance/world/player | | service lasting across map travel in one game instance | gameinstance subsystem | data is world-specific or per local player | | service scoped to one world | world subsystem | it must survive world replacement | | service scoped to one local human | localplayer subsystem | state is shared by all local players | | immutable authored definition | data asset | the value mutates during play | | rich definition needing asset manager identity/load control | primary data asset | normal direct loading is sufficient | | stateless reusable operation | blueprint function library | the function needs state, lifecycle, authority, or polymorphism | | shared behavior contract across unrelated object types | blueprint interface | the caller has no target reference | placement procedure 1. name the state owner. 2. name the destruction/reset event: component removal, actor destroy, pawn respawn, world teardown, map travel, local player removal, or process exit. 3. choose the class whose lifetime matches that reset event. 4. decide whether the state is authoritative, predicted, cosmetic, saveable, or authored. 5. keep authored definitions in assets and mutable instances in runtime objects. blueprint versus c++ prefer c++ for stable shared contracts, custom replication, high-frequency loops, complex math, low-level engine integration, and code that many binary blueprints would otherwise duplicate. prefer blueprint for content assembly, presentation, designer-facing variation, and event-driven orchestration. profile before converting solely for speed. troubleshooting troubleshooting cast fails - confirm the input reference is the expected object; casting does not locate it. - replace repeated concrete casts with an interface only when multiple types share a contract. - fix ownership/spawn/configuration rather than adding more casts. event fires twice - search for multiple bind/assign nodes and repeated initialization. - log publisher, listener, lifecycle event, and object instance name. - bind once or unbind before rebinding. - check respawn, widget reconstruction, possession, and map travel. event never fires - confirm binding occurs before broadcast. - confirm listener and publisher are the same instances. - confirm neither was destroyed or replaced. - for multiplayer, confirm the state/rpc actually reaches that machine; dispatchers are local. stale or invalid reference - identify which object's lifetime is shorter. - rebind on possession/target/world changes. - clear references and unregister during teardown. - avoid caching level actors in objects that survive map travel. editor duplicates generated objects - make construction script regeneration idempotent. - destroy/reuse generated components from the previous run. - do not append to persistent arrays without clearing/reconciling. blueprint becomes unmaintainable - split reusable capabilities into components. - replace cross-type casts with a narrow interface. - replace global searches with explicit references or scoped registries. - move stable shared contracts and hot paths to c++. - keep graphs as orchestration; move repeated logic into functions. packaged build differs - check asset cooking and soft-reference loading. - remove assumptions about editor-only objects or construction script timing. - verify initialization order and null checks. - test a development packaged build with logs before shipping. architecture use cases architecture use cases reusable interaction - bpiinteractable: contract such as caninteract and interact. - player interaction component: traces, holds the current target, invokes the interface. - door/pickup/terminal actors: implement their own response. - ui: subscribes to target-change events; it does not discover interactables independently. reusable health capability - actor component owns health behavior or bridges to an asc. - owner implements only interfaces the component requires. - component emits onhealthchanged and ondeath after state changes. - hud binds through the possessed pawn/player view model and rebinds on possession change. - server owns damage; replicated state/delegates drive client presentation. global save service - gameinstance subsystem coordinates save/load across maps. - savegame object contains serialized mutable state. - world actors expose stable identifiers and a save contract. - data assets remain definitions and are referenced by stable ids; they do not store progress. per-player settings or ui routing - localplayer subsystem owns data that differs between split-screen players. - widgets receive the correct owning local player. - avoid gameinstance globals for per-player focus, input mode, or local settings state. encounter director - world subsystem owns world-scoped registry/director state. - encounter actors register/unregister explicitly. - designers configure encounter definitions in data assets. - the subsystem emits local events; replicated gameplay still follows server authority. data-driven item - primary data asset stores immutable item identity, display data, and soft references. - runtime item instance stores quantity, durability, roll, owner, and save identity. - inventory component owns runtime instances. - ui reads a projection/view model, not the mutable data asset.","references":[{"slug":"communication-patterns","file":"communication-patterns.md","title":"Communication patterns","rawMarkdown":"# Communication patterns\n\n## Direct reference\n\nUse when one caller owns or is explicitly configured with one target.\n\n1. Expose an object reference, assign it at spawn/configuration, or obtain it from a known\n   framework relationship.\n2. Validate the reference at the use boundary.\n3. Call the typed function directly.\n\nThis is the clearest option. A cast does not find an object; it only tests/converts an\nexisting reference. Avoid repeated discovery calls.\n\n## Blueprint Interface\n\nUse when the caller has a target but multiple unrelated classes implement the operation.\n\n1. Create a Blueprint Interface containing the smallest stable function contract.\n2. Implement it on each responder.\n3. Obtain a target reference through overlap, trace, ownership, configuration, or spawn.\n4. Call the interface message on that reference.\n5. Define what a non-implementing target means; do not silently depend on a response.\n\nExample: an interaction trace calls `Interact` on doors, pickups, and terminals without\ncasting to each concrete class.\n\n## Event Dispatcher\n\nUse when one known publisher emits a signal to zero or more listeners.\n\n1. Declare the dispatcher on the publisher.\n2. Give the payload the minimum data listeners need.\n3. Listeners obtain the publisher and bind once during a defined lifecycle event.\n4. Publisher calls the dispatcher after its authoritative state change.\n5. Listeners unbind on teardown or when switching publishers.\n\nThe publisher owns the event; listeners own their reactions. Guard against duplicate binds.\n\n## Subsystem or message router\n\nUse for deliberately scoped many-to-many communication, not as a default.\n\n1. Choose lifetime: GameInstance, World, or LocalPlayer.\n2. Define message channel identifiers and payload structs.\n3. Register listeners and retain handles where the API requires them.\n4. Broadcast only after authoritative state is valid.\n5. Log channel, source, target scope, and payload in development builds.\n6. Unregister on teardown.\n\nGlobal messaging hides dependency and ordering. Document who may publish, whether messages\ncross the network, and whether late subscribers need current state separately.\n\n## Choice table\n\n| Relationship | Pattern |\n|---|---|\n| One caller → one concrete target | Direct reference |\n| One caller → one target behind a shared contract | Interface |\n| One publisher → many listeners | Event Dispatcher |\n| Many publishers → many listeners | Scoped message router |\n| Listener needs current value, not merely an occurrence | Query owned state, then subscribe to changes |\n","webMarkdown":"## Direct reference\n\nUse when one caller owns or is explicitly configured with one target.\n\n1. Expose an object reference, assign it at spawn/configuration, or obtain it from a known\n   framework relationship.\n2. Validate the reference at the use boundary.\n3. Call the typed function directly.\n\nThis is the clearest option. A cast does not find an object; it only tests/converts an\nexisting reference. Avoid repeated discovery calls.\n\n## Blueprint Interface\n\nUse when the caller has a target but multiple unrelated classes implement the operation.\n\n1. Create a Blueprint Interface containing the smallest stable function contract.\n2. Implement it on each responder.\n3. Obtain a target reference through overlap, trace, ownership, configuration, or spawn.\n4. Call the interface message on that reference.\n5. Define what a non-implementing target means; do not silently depend on a response.\n\nExample: an interaction trace calls `Interact` on doors, pickups, and terminals without\ncasting to each concrete class.\n\n## Event Dispatcher\n\nUse when one known publisher emits a signal to zero or more listeners.\n\n1. Declare the dispatcher on the publisher.\n2. Give the payload the minimum data listeners need.\n3. Listeners obtain the publisher and bind once during a defined lifecycle event.\n4. Publisher calls the dispatcher after its authoritative state change.\n5. Listeners unbind on teardown or when switching publishers.\n\nThe publisher owns the event; listeners own their reactions. Guard against duplicate binds.\n\n## Subsystem or message router\n\nUse for deliberately scoped many-to-many communication, not as a default.\n\n1. Choose lifetime: GameInstance, World, or LocalPlayer.\n2. Define message channel identifiers and payload structs.\n3. Register listeners and retain handles where the API requires them.\n4. Broadcast only after authoritative state is valid.\n5. Log channel, source, target scope, and payload in development builds.\n6. Unregister on teardown.\n\nGlobal messaging hides dependency and ordering. Document who may publish, whether messages\ncross the network, and whether late subscribers need current state separately.\n\n## Choice table\n\n| Relationship | Pattern |\n|---|---|\n| One caller → one concrete target | Direct reference |\n| One caller → one target behind a shared contract | Interface |\n| One publisher → many listeners | Event Dispatcher |\n| Many publishers → many listeners | Scoped message router |\n| Listener needs current value, not merely an occurrence | Query owned state, then subscribe to changes |\n","searchText":"communication patterns direct reference use when one caller owns or is explicitly configured with one target. 1. expose an object reference, assign it at spawn/configuration, or obtain it from a known framework relationship. 2. validate the reference at the use boundary. 3. call the typed function directly. this is the clearest option. a cast does not find an object; it only tests/converts an existing reference. avoid repeated discovery calls. blueprint interface use when the caller has a target but multiple unrelated classes implement the operation. 1. create a blueprint interface containing the smallest stable function contract. 2. implement it on each responder. 3. obtain a target reference through overlap, trace, ownership, configuration, or spawn. 4. call the interface message on that reference. 5. define what a non-implementing target means; do not silently depend on a response. example: an interaction trace calls interact on doors, pickups, and terminals without casting to each concrete class. event dispatcher use when one known publisher emits a signal to zero or more listeners. 1. declare the dispatcher on the publisher. 2. give the payload the minimum data listeners need. 3. listeners obtain the publisher and bind once during a defined lifecycle event. 4. publisher calls the dispatcher after its authoritative state change. 5. listeners unbind on teardown or when switching publishers. the publisher owns the event; listeners own their reactions. guard against duplicate binds. subsystem or message router use for deliberately scoped many-to-many communication, not as a default. 1. choose lifetime: gameinstance, world, or localplayer. 2. define message channel identifiers and payload structs. 3. register listeners and retain handles where the api requires them. 4. broadcast only after authoritative state is valid. 5. log channel, source, target scope, and payload in development builds. 6. unregister on teardown. global messaging hides dependency and ordering. document who may publish, whether messages cross the network, and whether late subscribers need current state separately. choice table | relationship | pattern | |---|---| | one caller → one concrete target | direct reference | | one caller → one target behind a shared contract | interface | | one publisher → many listeners | event dispatcher | | many publishers → many listeners | scoped message router | | listener needs current value, not merely an occurrence | query owned state, then subscribe to changes |"},{"slug":"lifecycle-performance","file":"lifecycle-performance.md","title":"Lifecycle and performance","rawMarkdown":"# Lifecycle and performance\n\n## Construction versus runtime\n\nConstruction Script can rerun in the editor when an instance changes. Make it idempotent:\n\n1. Clear or reuse previously generated objects/components.\n2. Derive output entirely from current exposed inputs.\n3. Avoid irreversible external side effects.\n4. Do not assume BeginPlay has run.\n5. Verify placed, duplicated, moved, recompiled, spawned, and packaged instances.\n\nUse BeginPlay or an explicit runtime initialization function for runtime bindings and mutable\nsession state. Pair every binding, timer, spawned helper, and registration with cleanup.\n\n## Tick decision\n\nKeep Tick only when the value genuinely depends on every rendered/simulation frame. Otherwise:\n\n- state changed → call an event;\n- fixed cadence → timer;\n- animation presentation → Animation Blueprint/native animation systems;\n- delayed one-shot → timer or latent action with lifecycle guard;\n- UI change → dispatcher/delegate/field notification;\n- expensive repeated query → cache and invalidate.\n\nIf Tick remains, disable it by default where possible, enable only while active, scale motion\nby delta seconds, avoid world scans and allocation, and profile on target hardware.\n\n## References and loading\n\nA hard class/object reference can pull referenced assets into the dependency/load graph. Use\nsoft references when the asset is optional or should load asynchronously. Use Primary Assets\nwhen identity, discovery, bundles, cooking rules, or controlled loading justify Asset Manager\nintegration. Verify with Reference Viewer and packaged/cooked tests.\n\n## Multiplayer boundary\n\nBlueprint communication does not itself replicate. Decide separately:\n\n- who owns authority;\n- which properties replicate and with what notification;\n- which RPC direction is legal;\n- whether a dispatcher is local reaction to replicated state;\n- whether a message router is local-only.\n\nNever assume a client-side dispatcher call reaches the server or other clients.\n","webMarkdown":"## Construction versus runtime\n\nConstruction Script can rerun in the editor when an instance changes. Make it idempotent:\n\n1. Clear or reuse previously generated objects/components.\n2. Derive output entirely from current exposed inputs.\n3. Avoid irreversible external side effects.\n4. Do not assume BeginPlay has run.\n5. Verify placed, duplicated, moved, recompiled, spawned, and packaged instances.\n\nUse BeginPlay or an explicit runtime initialization function for runtime bindings and mutable\nsession state. Pair every binding, timer, spawned helper, and registration with cleanup.\n\n## Tick decision\n\nKeep Tick only when the value genuinely depends on every rendered/simulation frame. Otherwise:\n\n- state changed → call an event;\n- fixed cadence → timer;\n- animation presentation → Animation Blueprint/native animation systems;\n- delayed one-shot → timer or latent action with lifecycle guard;\n- UI change → dispatcher/delegate/field notification;\n- expensive repeated query → cache and invalidate.\n\nIf Tick remains, disable it by default where possible, enable only while active, scale motion\nby delta seconds, avoid world scans and allocation, and profile on target hardware.\n\n## References and loading\n\nA hard class/object reference can pull referenced assets into the dependency/load graph. Use\nsoft references when the asset is optional or should load asynchronously. Use Primary Assets\nwhen identity, discovery, bundles, cooking rules, or controlled loading justify Asset Manager\nintegration. Verify with Reference Viewer and packaged/cooked tests.\n\n## Multiplayer boundary\n\nBlueprint communication does not itself replicate. Decide separately:\n\n- who owns authority;\n- which properties replicate and with what notification;\n- which RPC direction is legal;\n- whether a dispatcher is local reaction to replicated state;\n- whether a message router is local-only.\n\nNever assume a client-side dispatcher call reaches the server or other clients.\n","searchText":"lifecycle and performance construction versus runtime construction script can rerun in the editor when an instance changes. make it idempotent: 1. clear or reuse previously generated objects/components. 2. derive output entirely from current exposed inputs. 3. avoid irreversible external side effects. 4. do not assume beginplay has run. 5. verify placed, duplicated, moved, recompiled, spawned, and packaged instances. use beginplay or an explicit runtime initialization function for runtime bindings and mutable session state. pair every binding, timer, spawned helper, and registration with cleanup. tick decision keep tick only when the value genuinely depends on every rendered/simulation frame. otherwise: - state changed → call an event; - fixed cadence → timer; - animation presentation → animation blueprint/native animation systems; - delayed one-shot → timer or latent action with lifecycle guard; - ui change → dispatcher/delegate/field notification; - expensive repeated query → cache and invalidate. if tick remains, disable it by default where possible, enable only while active, scale motion by delta seconds, avoid world scans and allocation, and profile on target hardware. references and loading a hard class/object reference can pull referenced assets into the dependency/load graph. use soft references when the asset is optional or should load asynchronously. use primary assets when identity, discovery, bundles, cooking rules, or controlled loading justify asset manager integration. verify with reference viewer and packaged/cooked tests. multiplayer boundary blueprint communication does not itself replicate. decide separately: - who owns authority; - which properties replicate and with what notification; - which rpc direction is legal; - whether a dispatcher is local reaction to replicated state; - whether a message router is local-only. never assume a client-side dispatcher call reaches the server or other clients."},{"slug":"sources","file":"sources.md","title":"UE 5.8 primary sources","rawMarkdown":"# UE 5.8 primary sources\n\nVerified 2026-07-19. Prefer these pages over remembered node names or third-party tutorials.\n\n- [Blueprint Best Practices](https://dev.epicgames.com/documentation/en-us/unreal-engine/blueprint-best-practices-in-unreal-engine)\n- [Blueprint Communication Usage](https://dev.epicgames.com/documentation/en-us/unreal-engine/blueprint-communication-usage-in-unreal-engine)\n- [Actor Communication](https://dev.epicgames.com/documentation/en-us/unreal-engine/actor-communication-in-unreal-engine)\n- [Programming Subsystems](https://dev.epicgames.com/documentation/en-us/unreal-engine/programming-subsystems-in-unreal-engine)\n- [Data Assets](https://dev.epicgames.com/documentation/en-us/unreal-engine/data-assets-in-unreal-engine)\n- [Asset Management](https://dev.epicgames.com/documentation/en-us/unreal-engine/asset-management-in-unreal-engine)\n\nVersion note: the Epic pages above currently resolve to Unreal Engine 5.8 documentation.\nSubsystem lifetime and asset-loading claims are taken from Epic's 5.8 pages. Blueprint\ncommunication patterns are architectural choices; they do not add network replication.\n","webMarkdown":"Verified 2026-07-19. Prefer these pages over remembered node names or third-party tutorials.\n\n- [Blueprint Best Practices](https://dev.epicgames.com/documentation/en-us/unreal-engine/blueprint-best-practices-in-unreal-engine)\n- [Blueprint Communication Usage](https://dev.epicgames.com/documentation/en-us/unreal-engine/blueprint-communication-usage-in-unreal-engine)\n- [Actor Communication](https://dev.epicgames.com/documentation/en-us/unreal-engine/actor-communication-in-unreal-engine)\n- [Programming Subsystems](https://dev.epicgames.com/documentation/en-us/unreal-engine/programming-subsystems-in-unreal-engine)\n- [Data Assets](https://dev.epicgames.com/documentation/en-us/unreal-engine/data-assets-in-unreal-engine)\n- [Asset Management](https://dev.epicgames.com/documentation/en-us/unreal-engine/asset-management-in-unreal-engine)\n\nVersion note: the Epic pages above currently resolve to Unreal Engine 5.8 documentation.\nSubsystem lifetime and asset-loading claims are taken from Epic's 5.8 pages. Blueprint\ncommunication patterns are architectural choices; they do not add network replication.\n","searchText":"ue 5.8 primary sources verified 2026-07-19. prefer these pages over remembered node names or third-party tutorials. - blueprint best practices - blueprint communication usage - actor communication - programming subsystems - data assets - asset management version note: the epic pages above currently resolve to unreal engine 5.8 documentation. subsystem lifetime and asset-loading claims are taken from epic's 5.8 pages. blueprint communication patterns are architectural choices; they do not add network replication."},{"slug":"system-selector","file":"system-selector.md","title":"System selector","rawMarkdown":"# System selector\n\nChoose by ownership and lifetime before convenience.\n\n| Need | Use | Avoid when |\n|---|---|---|\n| Placed/spawned world entity with transform, collision, replication, or independent lifetime | Actor | It is only a reusable capability of another Actor |\n| Reusable capability attached to actors | Actor Component | It needs its own transform; use Scene Component or Actor as appropriate |\n| Reusable transform-bearing subobject | Scene Component | It must exist independently or replicate as an Actor |\n| Service lasting for one engine process | Engine Subsystem | State should reset per game instance/world/player |\n| Service lasting across map travel in one game instance | GameInstance Subsystem | Data is world-specific or per local player |\n| Service scoped to one World | World Subsystem | It must survive world replacement |\n| Service scoped to one local human | LocalPlayer Subsystem | State is shared by all local players |\n| Immutable authored definition | Data Asset | The value mutates during play |\n| Rich definition needing Asset Manager identity/load control | Primary Data Asset | Normal direct loading is sufficient |\n| Stateless reusable operation | Blueprint Function Library | The function needs state, lifecycle, authority, or polymorphism |\n| Shared behavior contract across unrelated object types | Blueprint Interface | The caller has no target reference |\n\n## Placement procedure\n\n1. Name the state owner.\n2. Name the destruction/reset event: component removal, actor destroy, pawn respawn, world\n   teardown, map travel, local player removal, or process exit.\n3. Choose the class whose lifetime matches that reset event.\n4. Decide whether the state is authoritative, predicted, cosmetic, saveable, or authored.\n5. Keep authored definitions in assets and mutable instances in runtime objects.\n\n## Blueprint versus C++\n\nPrefer C++ for stable shared contracts, custom replication, high-frequency loops, complex\nmath, low-level engine integration, and code that many binary Blueprints would otherwise\nduplicate. Prefer Blueprint for content assembly, presentation, designer-facing variation,\nand event-driven orchestration. Profile before converting solely for speed.\n","webMarkdown":"Choose by ownership and lifetime before convenience.\n\n| Need | Use | Avoid when |\n|---|---|---|\n| Placed/spawned world entity with transform, collision, replication, or independent lifetime | Actor | It is only a reusable capability of another Actor |\n| Reusable capability attached to actors | Actor Component | It needs its own transform; use Scene Component or Actor as appropriate |\n| Reusable transform-bearing subobject | Scene Component | It must exist independently or replicate as an Actor |\n| Service lasting for one engine process | Engine Subsystem | State should reset per game instance/world/player |\n| Service lasting across map travel in one game instance | GameInstance Subsystem | Data is world-specific or per local player |\n| Service scoped to one World | World Subsystem | It must survive world replacement |\n| Service scoped to one local human | LocalPlayer Subsystem | State is shared by all local players |\n| Immutable authored definition | Data Asset | The value mutates during play |\n| Rich definition needing Asset Manager identity/load control | Primary Data Asset | Normal direct loading is sufficient |\n| Stateless reusable operation | Blueprint Function Library | The function needs state, lifecycle, authority, or polymorphism |\n| Shared behavior contract across unrelated object types | Blueprint Interface | The caller has no target reference |\n\n## Placement procedure\n\n1. Name the state owner.\n2. Name the destruction/reset event: component removal, actor destroy, pawn respawn, world\n   teardown, map travel, local player removal, or process exit.\n3. Choose the class whose lifetime matches that reset event.\n4. Decide whether the state is authoritative, predicted, cosmetic, saveable, or authored.\n5. Keep authored definitions in assets and mutable instances in runtime objects.\n\n## Blueprint versus C++\n\nPrefer C++ for stable shared contracts, custom replication, high-frequency loops, complex\nmath, low-level engine integration, and code that many binary Blueprints would otherwise\nduplicate. Prefer Blueprint for content assembly, presentation, designer-facing variation,\nand event-driven orchestration. Profile before converting solely for speed.\n","searchText":"system selector choose by ownership and lifetime before convenience. | need | use | avoid when | |---|---|---| | placed/spawned world entity with transform, collision, replication, or independent lifetime | actor | it is only a reusable capability of another actor | | reusable capability attached to actors | actor component | it needs its own transform; use scene component or actor as appropriate | | reusable transform-bearing subobject | scene component | it must exist independently or replicate as an actor | | service lasting for one engine process | engine subsystem | state should reset per game instance/world/player | | service lasting across map travel in one game instance | gameinstance subsystem | data is world-specific or per local player | | service scoped to one world | world subsystem | it must survive world replacement | | service scoped to one local human | localplayer subsystem | state is shared by all local players | | immutable authored definition | data asset | the value mutates during play | | rich definition needing asset manager identity/load control | primary data asset | normal direct loading is sufficient | | stateless reusable operation | blueprint function library | the function needs state, lifecycle, authority, or polymorphism | | shared behavior contract across unrelated object types | blueprint interface | the caller has no target reference | placement procedure 1. name the state owner. 2. name the destruction/reset event: component removal, actor destroy, pawn respawn, world teardown, map travel, local player removal, or process exit. 3. choose the class whose lifetime matches that reset event. 4. decide whether the state is authoritative, predicted, cosmetic, saveable, or authored. 5. keep authored definitions in assets and mutable instances in runtime objects. blueprint versus c++ prefer c++ for stable shared contracts, custom replication, high-frequency loops, complex math, low-level engine integration, and code that many binary blueprints would otherwise duplicate. prefer blueprint for content assembly, presentation, designer-facing variation, and event-driven orchestration. profile before converting solely for speed."},{"slug":"troubleshooting","file":"troubleshooting.md","title":"Troubleshooting","rawMarkdown":"# Troubleshooting\n\n## Cast fails\n\n- Confirm the input reference is the expected object; casting does not locate it.\n- Replace repeated concrete casts with an interface only when multiple types share a contract.\n- Fix ownership/spawn/configuration rather than adding more casts.\n\n## Event fires twice\n\n- Search for multiple Bind/Assign nodes and repeated initialization.\n- Log publisher, listener, lifecycle event, and object instance name.\n- Bind once or unbind before rebinding.\n- Check respawn, widget reconstruction, possession, and map travel.\n\n## Event never fires\n\n- Confirm binding occurs before broadcast.\n- Confirm listener and publisher are the same instances.\n- Confirm neither was destroyed or replaced.\n- For multiplayer, confirm the state/RPC actually reaches that machine; dispatchers are local.\n\n## Stale or invalid reference\n\n- Identify which object's lifetime is shorter.\n- Rebind on possession/target/world changes.\n- Clear references and unregister during teardown.\n- Avoid caching level actors in objects that survive map travel.\n\n## Editor duplicates generated objects\n\n- Make Construction Script regeneration idempotent.\n- Destroy/reuse generated components from the previous run.\n- Do not append to persistent arrays without clearing/reconciling.\n\n## Blueprint becomes unmaintainable\n\n- Split reusable capabilities into components.\n- Replace cross-type casts with a narrow interface.\n- Replace global searches with explicit references or scoped registries.\n- Move stable shared contracts and hot paths to C++.\n- Keep graphs as orchestration; move repeated logic into functions.\n\n## Packaged build differs\n\n- Check asset cooking and soft-reference loading.\n- Remove assumptions about editor-only objects or Construction Script timing.\n- Verify initialization order and null checks.\n- Test a Development packaged build with logs before Shipping.\n","webMarkdown":"## Cast fails\n\n- Confirm the input reference is the expected object; casting does not locate it.\n- Replace repeated concrete casts with an interface only when multiple types share a contract.\n- Fix ownership/spawn/configuration rather than adding more casts.\n\n## Event fires twice\n\n- Search for multiple Bind/Assign nodes and repeated initialization.\n- Log publisher, listener, lifecycle event, and object instance name.\n- Bind once or unbind before rebinding.\n- Check respawn, widget reconstruction, possession, and map travel.\n\n## Event never fires\n\n- Confirm binding occurs before broadcast.\n- Confirm listener and publisher are the same instances.\n- Confirm neither was destroyed or replaced.\n- For multiplayer, confirm the state/RPC actually reaches that machine; dispatchers are local.\n\n## Stale or invalid reference\n\n- Identify which object's lifetime is shorter.\n- Rebind on possession/target/world changes.\n- Clear references and unregister during teardown.\n- Avoid caching level actors in objects that survive map travel.\n\n## Editor duplicates generated objects\n\n- Make Construction Script regeneration idempotent.\n- Destroy/reuse generated components from the previous run.\n- Do not append to persistent arrays without clearing/reconciling.\n\n## Blueprint becomes unmaintainable\n\n- Split reusable capabilities into components.\n- Replace cross-type casts with a narrow interface.\n- Replace global searches with explicit references or scoped registries.\n- Move stable shared contracts and hot paths to C++.\n- Keep graphs as orchestration; move repeated logic into functions.\n\n## Packaged build differs\n\n- Check asset cooking and soft-reference loading.\n- Remove assumptions about editor-only objects or Construction Script timing.\n- Verify initialization order and null checks.\n- Test a Development packaged build with logs before Shipping.\n","searchText":"troubleshooting cast fails - confirm the input reference is the expected object; casting does not locate it. - replace repeated concrete casts with an interface only when multiple types share a contract. - fix ownership/spawn/configuration rather than adding more casts. event fires twice - search for multiple bind/assign nodes and repeated initialization. - log publisher, listener, lifecycle event, and object instance name. - bind once or unbind before rebinding. - check respawn, widget reconstruction, possession, and map travel. event never fires - confirm binding occurs before broadcast. - confirm listener and publisher are the same instances. - confirm neither was destroyed or replaced. - for multiplayer, confirm the state/rpc actually reaches that machine; dispatchers are local. stale or invalid reference - identify which object's lifetime is shorter. - rebind on possession/target/world changes. - clear references and unregister during teardown. - avoid caching level actors in objects that survive map travel. editor duplicates generated objects - make construction script regeneration idempotent. - destroy/reuse generated components from the previous run. - do not append to persistent arrays without clearing/reconciling. blueprint becomes unmaintainable - split reusable capabilities into components. - replace cross-type casts with a narrow interface. - replace global searches with explicit references or scoped registries. - move stable shared contracts and hot paths to c++. - keep graphs as orchestration; move repeated logic into functions. packaged build differs - check asset cooking and soft-reference loading. - remove assumptions about editor-only objects or construction script timing. - verify initialization order and null checks. - test a development packaged build with logs before shipping."},{"slug":"use-cases","file":"use-cases.md","title":"Architecture use cases","rawMarkdown":"# Architecture use cases\n\n## Reusable interaction\n\n- `BPI_Interactable`: contract such as `CanInteract` and `Interact`.\n- Player interaction component: traces, holds the current target, invokes the interface.\n- Door/pickup/terminal actors: implement their own response.\n- UI: subscribes to target-change events; it does not discover interactables independently.\n\n## Reusable health capability\n\n- Actor Component owns health behavior or bridges to an ASC.\n- Owner implements only interfaces the component requires.\n- Component emits `OnHealthChanged` and `OnDeath` after state changes.\n- HUD binds through the possessed pawn/player view model and rebinds on possession change.\n- Server owns damage; replicated state/delegates drive client presentation.\n\n## Global save service\n\n- GameInstance Subsystem coordinates save/load across maps.\n- SaveGame object contains serialized mutable state.\n- World actors expose stable identifiers and a save contract.\n- Data Assets remain definitions and are referenced by stable IDs; they do not store progress.\n\n## Per-player settings or UI routing\n\n- LocalPlayer Subsystem owns data that differs between split-screen players.\n- Widgets receive the correct owning Local Player.\n- Avoid GameInstance globals for per-player focus, input mode, or local settings state.\n\n## Encounter director\n\n- World Subsystem owns world-scoped registry/director state.\n- Encounter actors register/unregister explicitly.\n- Designers configure encounter definitions in Data Assets.\n- The subsystem emits local events; replicated gameplay still follows server authority.\n\n## Data-driven item\n\n- Primary Data Asset stores immutable item identity, display data, and soft references.\n- Runtime item instance stores quantity, durability, roll, owner, and save identity.\n- Inventory component owns runtime instances.\n- UI reads a projection/view model, not the mutable Data Asset.\n","webMarkdown":"## Reusable interaction\n\n- `BPI_Interactable`: contract such as `CanInteract` and `Interact`.\n- Player interaction component: traces, holds the current target, invokes the interface.\n- Door/pickup/terminal actors: implement their own response.\n- UI: subscribes to target-change events; it does not discover interactables independently.\n\n## Reusable health capability\n\n- Actor Component owns health behavior or bridges to an ASC.\n- Owner implements only interfaces the component requires.\n- Component emits `OnHealthChanged` and `OnDeath` after state changes.\n- HUD binds through the possessed pawn/player view model and rebinds on possession change.\n- Server owns damage; replicated state/delegates drive client presentation.\n\n## Global save service\n\n- GameInstance Subsystem coordinates save/load across maps.\n- SaveGame object contains serialized mutable state.\n- World actors expose stable identifiers and a save contract.\n- Data Assets remain definitions and are referenced by stable IDs; they do not store progress.\n\n## Per-player settings or UI routing\n\n- LocalPlayer Subsystem owns data that differs between split-screen players.\n- Widgets receive the correct owning Local Player.\n- Avoid GameInstance globals for per-player focus, input mode, or local settings state.\n\n## Encounter director\n\n- World Subsystem owns world-scoped registry/director state.\n- Encounter actors register/unregister explicitly.\n- Designers configure encounter definitions in Data Assets.\n- The subsystem emits local events; replicated gameplay still follows server authority.\n\n## Data-driven item\n\n- Primary Data Asset stores immutable item identity, display data, and soft references.\n- Runtime item instance stores quantity, durability, roll, owner, and save identity.\n- Inventory component owns runtime instances.\n- UI reads a projection/view model, not the mutable Data Asset.\n","searchText":"architecture use cases reusable interaction - bpiinteractable: contract such as caninteract and interact. - player interaction component: traces, holds the current target, invokes the interface. - door/pickup/terminal actors: implement their own response. - ui: subscribes to target-change events; it does not discover interactables independently. reusable health capability - actor component owns health behavior or bridges to an asc. - owner implements only interfaces the component requires. - component emits onhealthchanged and ondeath after state changes. - hud binds through the possessed pawn/player view model and rebinds on possession change. - server owns damage; replicated state/delegates drive client presentation. global save service - gameinstance subsystem coordinates save/load across maps. - savegame object contains serialized mutable state. - world actors expose stable identifiers and a save contract. - data assets remain definitions and are referenced by stable ids; they do not store progress. per-player settings or ui routing - localplayer subsystem owns data that differs between split-screen players. - widgets receive the correct owning local player. - avoid gameinstance globals for per-player focus, input mode, or local settings state. encounter director - world subsystem owns world-scoped registry/director state. - encounter actors register/unregister explicitly. - designers configure encounter definitions in data assets. - the subsystem emits local events; replicated gameplay still follows server authority. data-driven item - primary data asset stores immutable item identity, display data, and soft references. - runtime item instance stores quantity, durability, roll, owner, and save identity. - inventory component owns runtime instances. - ui reads a projection/view model, not the mutable data asset."}]}
{"slug":"unreal-camera-cinematics","name":"unreal-camera-cinematics","title":"Unreal 5.8 Cameras and Cinematics","description":"Design, implement, blend, animate, and debug gameplay cameras and cinematics in Unreal Engine 5.8. Use for Camera Components, Spring Arms, PlayerCameraManager, view targets, follow/orbit/aim/lock-on cameras, collision and lag, FOV, Camera Modifiers and shakes, accessibility, Experimental Gameplay Camera System, Cine Camera Actors, Sequencer, Camera Cut Tracks, gameplay-to-cinematic handoff, Camera Rig Rail or Crane, lens/focus/exposure, split screen, multiplayer, or camera jitter/clipping.","shortDescription":"Build gameplay cameras and cinematic shots","category":"Presentation","referenceCount":11,"rawMarkdown":"---\nname: unreal-camera-cinematics\ndescription: Design, implement, blend, animate, and debug gameplay cameras and cinematics in Unreal Engine 5.8. Use for Camera Components, Spring Arms, PlayerCameraManager, view targets, follow/orbit/aim/lock-on cameras, collision and lag, FOV, Camera Modifiers and shakes, accessibility, Experimental Gameplay Camera System, Cine Camera Actors, Sequencer, Camera Cut Tracks, gameplay-to-cinematic handoff, Camera Rig Rail or Crane, lens/focus/exposure, split screen, multiplayer, or camera jitter/clipping.\n---\n\n# Unreal 5.8 Cameras and Cinematics\n\n## Choose the ownership model\n\nRead [`references/system-selector.md`](references/system-selector.md).\n\n- Pawn-relative gameplay follow/orbit -> Camera Component + Spring Arm.\n- Central local-player rules/overlays/view-target control -> PlayerCameraManager.\n- Reusable complex data-driven rigs -> Gameplay Camera System, but Experimental in UE 5.8.\n- Authored shot/cut -> Cine Camera Actor + Level Sequence/Sequencer.\n- Dolly/jib motion -> Camera Rig Rail or Crane in Sequencer.\n\nThe camera is local presentation. Replicate gameplay targets/state that influence it, not the final\nper-frame camera transform, unless a special shared-camera design explicitly requires otherwise.\n\n## Execute\n\n1. Define the camera's gameplay job, local owner, subject/target, input authority, and comfort limits.\n2. Choose gameplay or cinematic ownership and a single component responsible for final POV.\n3. Establish pivot, distance/FOV, rotation, framing, and collision before adding lag or shake.\n4. Add state transitions with explicit blend/interrupt/return policy.\n5. Layer recoil, shake, post process, and offsets in a stable ordered stack with intensity controls.\n6. For Sequencer, define cameras, cuts/blends, bindings, spawnable/possessable ownership, and handoff.\n7. Test obstruction, teleport, low/high frame rate, split screen, network corrections, and accessibility.\n8. Profile camera queries, post process, depth of field, and cinematic rendering on target hardware.\n\nLoad only what applies:\n\n- [`references/gameplay-camera-architecture.md`](references/gameplay-camera-architecture.md)\n- [`references/spring-arm-follow-and-collision.md`](references/spring-arm-follow-and-collision.md)\n- [`references/transitions-modifiers-and-shakes.md`](references/transitions-modifiers-and-shakes.md)\n- [`references/gameplay-camera-system.md`](references/gameplay-camera-system.md)\n- [`references/cine-camera-and-lens.md`](references/cine-camera-and-lens.md)\n- [`references/sequencer-cuts-and-handoff.md`](references/sequencer-cuts-and-handoff.md)\n- [`references/rails-cranes-and-shot-recipes.md`](references/rails-cranes-and-shot-recipes.md)\n- [`references/network-accessibility-and-performance.md`](references/network-accessibility-and-performance.md)\n- [`references/debugging-patterns.md`](references/debugging-patterns.md)\n\n## Required answer format\n\nReturn:\n\n1. **Camera job, local owner, subject, and selected architecture**.\n2. **Responsibility/order from input and target to final POV**.\n3. **Transform/FOV/lens/collision/lag parameters and directional effects**.\n4. **State transition, interruption, and gameplay-return rules**.\n5. **Shake/modifier/post-process stack and accessibility scaling**.\n6. **Sequencer binding/cut/rig or multiplayer/split-screen consequences**.\n7. **Debug views, reproducible scenarios, and acceptance checks**.\n\n## Hard rules\n\n- Establish a stable unlagged, unshaken base camera before layering secondary effects.\n- Use Spring Arm `SocketOffset`, not an arbitrary relative Camera offset, when collision tracing must\n  account for the final framing position.\n- Higher Spring Arm lag speed follows the target faster; lower speed creates more lag.\n- Apply camera behavior once. Do not let Pawn, Controller, CameraManager, and Sequencer fight over POV.\n- `Set View Target with Blend` changes the local PlayerController's view; define interruption/return.\n- World camera shakes affect nearby local players and do not replicate automatically.\n- Cap stacked shake and expose an intensity slider including zero.\n- Treat the Gameplay Camera System and VCam as Experimental in UE 5.8; provide a shipping fallback.\n- Camera Cut Track owns active cinematic camera; define blend-to/from-gameplay and sequence completion.\n- Separate camera collision/readability from visual occlusion fixes; never move the player collision\n  capsule merely to solve a camera obstruction.\n\nSee [`references/sources.md`](references/sources.md) for the UE 5.8 source trail.\n","webMarkdown":"## Choose the ownership model\n\nRead [`references/system-selector.md`](/unreal/unreal-camera-cinematics/system-selector/).\n\n- Pawn-relative gameplay follow/orbit -> Camera Component + Spring Arm.\n- Central local-player rules/overlays/view-target control -> PlayerCameraManager.\n- Reusable complex data-driven rigs -> Gameplay Camera System, but Experimental in UE 5.8.\n- Authored shot/cut -> Cine Camera Actor + Level Sequence/Sequencer.\n- Dolly/jib motion -> Camera Rig Rail or Crane in Sequencer.\n\nThe camera is local presentation. Replicate gameplay targets/state that influence it, not the final\nper-frame camera transform, unless a special shared-camera design explicitly requires otherwise.\n\n## Execute\n\n1. Define the camera's gameplay job, local owner, subject/target, input authority, and comfort limits.\n2. Choose gameplay or cinematic ownership and a single component responsible for final POV.\n3. Establish pivot, distance/FOV, rotation, framing, and collision before adding lag or shake.\n4. Add state transitions with explicit blend/interrupt/return policy.\n5. Layer recoil, shake, post process, and offsets in a stable ordered stack with intensity controls.\n6. For Sequencer, define cameras, cuts/blends, bindings, spawnable/possessable ownership, and handoff.\n7. Test obstruction, teleport, low/high frame rate, split screen, network corrections, and accessibility.\n8. Profile camera queries, post process, depth of field, and cinematic rendering on target hardware.\n\nLoad only what applies:\n\n- [`references/gameplay-camera-architecture.md`](/unreal/unreal-camera-cinematics/gameplay-camera-architecture/)\n- [`references/spring-arm-follow-and-collision.md`](/unreal/unreal-camera-cinematics/spring-arm-follow-and-collision/)\n- [`references/transitions-modifiers-and-shakes.md`](/unreal/unreal-camera-cinematics/transitions-modifiers-and-shakes/)\n- [`references/gameplay-camera-system.md`](/unreal/unreal-camera-cinematics/gameplay-camera-system/)\n- [`references/cine-camera-and-lens.md`](/unreal/unreal-camera-cinematics/cine-camera-and-lens/)\n- [`references/sequencer-cuts-and-handoff.md`](/unreal/unreal-camera-cinematics/sequencer-cuts-and-handoff/)\n- [`references/rails-cranes-and-shot-recipes.md`](/unreal/unreal-camera-cinematics/rails-cranes-and-shot-recipes/)\n- [`references/network-accessibility-and-performance.md`](/unreal/unreal-camera-cinematics/network-accessibility-and-performance/)\n- [`references/debugging-patterns.md`](/unreal/unreal-camera-cinematics/debugging-patterns/)\n\n## Required answer format\n\nReturn:\n\n1. **Camera job, local owner, subject, and selected architecture**.\n2. **Responsibility/order from input and target to final POV**.\n3. **Transform/FOV/lens/collision/lag parameters and directional effects**.\n4. **State transition, interruption, and gameplay-return rules**.\n5. **Shake/modifier/post-process stack and accessibility scaling**.\n6. **Sequencer binding/cut/rig or multiplayer/split-screen consequences**.\n7. **Debug views, reproducible scenarios, and acceptance checks**.\n\n## Hard rules\n\n- Establish a stable unlagged, unshaken base camera before layering secondary effects.\n- Use Spring Arm `SocketOffset`, not an arbitrary relative Camera offset, when collision tracing must\n  account for the final framing position.\n- Higher Spring Arm lag speed follows the target faster; lower speed creates more lag.\n- Apply camera behavior once. Do not let Pawn, Controller, CameraManager, and Sequencer fight over POV.\n- `Set View Target with Blend` changes the local PlayerController's view; define interruption/return.\n- World camera shakes affect nearby local players and do not replicate automatically.\n- Cap stacked shake and expose an intensity slider including zero.\n- Treat the Gameplay Camera System and VCam as Experimental in UE 5.8; provide a shipping fallback.\n- Camera Cut Track owns active cinematic camera; define blend-to/from-gameplay and sequence completion.\n- Separate camera collision/readability from visual occlusion fixes; never move the player collision\n  capsule merely to solve a camera obstruction.\n\nSee [`references/sources.md`](/unreal/unreal-camera-cinematics/sources/) for the UE 5.8 source trail.\n","searchText":"unreal 5.8 cameras and cinematics design, implement, blend, animate, and debug gameplay cameras and cinematics in unreal engine 5.8. use for camera components, spring arms, playercameramanager, view targets, follow/orbit/aim/lock-on cameras, collision and lag, fov, camera modifiers and shakes, accessibility, experimental gameplay camera system, cine camera actors, sequencer, camera cut tracks, gameplay-to-cinematic handoff, camera rig rail or crane, lens/focus/exposure, split screen, multiplayer, or camera jitter/clipping. cine camera actor and lens cine camera actor and lens cine camera actor adds filmback, lens, aperture, focus, and look-at tools suited to cinematics. physical controls - filmback/sensor affects field of view for a given focal length and establishes aspect framing. - current focal length: longer narrows fov/compresses framing; shorter widens fov and exaggerates spatial perspective when camera position changes to preserve subject size. - aperture (f-stop): lower f-number increases aperture and shallow depth-of-field potential; higher f-number deepens focus. exposure interaction depends on project/camera settings. - focus method / manual focus distance / tracking: defines focal plane behavior. - post process blend weight: blends the camera's post-process overrides. setup 1. choose delivery aspect/resolution and filmback before composing. 2. place the camera for perspective; then choose focal length for framing. 3. set focus method and visualize focus plane/debug focus. 4. tune aperture/dof only after subject blocking and focus distance are stable. 5. lock exposure behavior with the lighting/cinematic plan; avoid compensating lens mistakes with arbitrary post process. 6. test camera motion for focus pumping, clipping, motion blur, and temporal artifacts. depth of field can obscure gameplay-critical information and increases rendering cost. for in-game cinematics, preserve subtitles, skip prompts, ui safe area, and accessibility requirements. debugging patterns debugging patterns ownership isolation 1. print/log current local playercontroller, view target, cameramanager, active sequence, and final pov. 2. disable sequencer camera cuts, then modifiers/shakes, lag, and collision in that order. 3. verify the unmodified desired pivot/rotation/distance/fov. 4. re-enable collision, lag, state blend, modifiers, shake, and post process one at a time. 5. test the same path at fixed low/high frame rates and in a packaged build. | symptom | inspect first | |---|---| | camera inside wall | spring arm collision enabled/channel/probe, camera attachment | | snaps near corners | collision geometry/probe/release, pivot path, competing writers | | character occluded but no collision | foreground occlusion policy; spring arm solves camera collision only | | persistent jitter | target movement vs camera tick/order, multiple writers, network correction | | sluggish input | rotation lag or smoothed input/desired rotation twice | | offset ignored | relative camera offset instead of spring arm socketoffset | | wrong player camera | local controller/view target assumption, split screen index | | shake absent remotely | event not replicated/local playback not triggered | | shake never ends | indefinite duration/owner cleanup | | sequence plays but camera stays gameplay | missing/disabled camera cut track or binding | | camera remains cinematic | finish/skip/interruption handoff omitted | | focus hunts/pumps | tracking target/focus distance and key interpolation | | rail speed uneven | spline/time-key parameterization and interpolation | acceptance routes: tight corridors, ceilings, corners, fast rotation, sprint/aim transition, teleport, death/possession, lock target lost, split screen, latency correction, cinematic finish/skip/interruption, resolution/aspect changes, zero-shake setting, and target performance capture. gameplay camera architecture gameplay camera architecture traditional shipping baseline - camera component: projection, fov/aspect, post process, and pov on a pawn/actor. - spring arm: desired boom distance, rotation inheritance, collision retract, optional lag. - playercontroller: local input/view target and set view target with blend. - playercameramanager: calculates/caches final pov and applies modifiers/shakes/post process. keep gameplay-facing camera state small: exploration, aim, lock-on, sprint, dialogue, photo, cinematic. each state supplies desired pivot, arm length, fov, offsets, rotation constraints, and blend policy. interpolate a state result rather than running several independent timelines against the same property. follow/orbit 1. derive pivot from a stable target component/socket plus state offset. 2. use controller rotation for player orbit when appropriate; separate character facing from camera yaw. 3. clamp pitch before solving obstruction. 4. compute desired arm/framing, solve collision, then apply bounded smoothing. 5. preserve player input responsiveness; smooth camera motion, not input recognition. aim/lock-on blend shoulder/fov/rotation policy as a state. keep reticle, weapon trace, camera trace, and character aim solutions distinct. for lock-on, validate target, visibility/range, target switching, camera pitch, and unlock fallback. avoid snapping the player/camera because a target was briefly occluded. on teleport, possession, respawn, or large correction, reset accumulated camera lag and stale targets. experimental gameplay camera system experimental gameplay camera system the ue 5.8 gameplay camera system is experimental. use it only after an explicit production-maturity decision and retain a traditional camera component/playercameramanager fallback. architecture - camera asset: camera rigs, transitions, director, and variables. - camera rig: node network describing camera behavior. - camera transitions / shared transitions: enter/exit behavior. - camera director: selects active rig—single, blueprint, or statetree director. - gameplay camera component/actor: consumes the camera asset. - camera variable collection: exposes values used by the asset. procedure 1. define bounded rig states and variables before building nodes. 2. create one camera asset and the smallest required camera rigs. 3. choose a director matching selection complexity. 4. author explicit enter/exit transitions and interruption behavior. 5. feed stable gameplay-facing variables into the consuming component. 6. use camera debugger to inspect selected rig, variables, and transitions. 7. test cook/package, multiplayer local ownership, split screen, performance, and migration fallback. do not combine a data-driven camera rig with a second blueprint system writing the same final pov. use traditional camera systems when the requirement is simple or shipping-risk tolerance is low. network, accessibility, and performance network, accessibility, and performance network/local ownership player cameras normally exist as local presentation for human-controlled local players. replicate the subject, lock-on target, gameplay state, or cinematic event; each relevant local playercontroller constructs its own view. world camera shake does not replicate. in split screen, address the intended local controller(s), not an assumed player zero. network corrections can feed large target discontinuities into camera lag. reset or bound camera history after teleports/corrections. spectating/possession requires a new valid target and explicit transition/cleanup. accessibility/comfort - expose shake intensity including off; - expose or limit head bob, motion blur, fov changes, and aggressive camera lag where appropriate; - avoid forced roll and rapid oscillation; - keep reticle/horizon/reference stable during precision tasks; - preserve subtitle/ui safe areas and non-camera alternatives for feedback; - provide cinematic skip and restore control predictably. performance profile per-local-player camera traces, target/occlusion tests, blueprint modifier work, post process, depth of field, motion blur, and cinematic resolution. avoid many redundant traces from pawn, controller, and cameramanager. cache stable references, restrict expensive target searches, and test split screen as multiplied local work. camera motion can expose rendering/streaming problems not visible from static views. test fast rails, wide reveals, cuts across the world, lumen/lighting transitions, world partition streaming, and target hardware. coordinate with unreal-lighting and unreal-world-partition for those boundaries. rails, cranes, and shot recipes rails, cranes, and shot recipes camera rig rail place from cinematic actors, shape its blueprint spline, attach the cine camera to the dolly, and animate current position on rail from 0 to 1 in sequencer. lock orientation to rail makes camera rotation relative to dolly orientation; otherwise animate orientation independently. spatially even spline travel is not guaranteed by evenly spaced time keys—inspect speed and use key interpolation. camera rig crane attach the camera to the mount, then animate arm length, yaw, and pitch. lock mount pitch/yaw only when camera orientation should follow the crane. combine rail and crane only when the extra degrees of freedom materially serve the shot; nested transforms complicate framing and debugging. recipes - reveal: begin with occlusion/tight frame, move rail/crane to expose subject, preserve focal plane. - tracking shot: rail/dolly carries translation; camera independently maintains composition/look. - dialogue cut: consistent eyeline/screen direction, controlled lens/focus, intentional cut timing. - gameplay establishing shot: show objective/path, minimize duration, retain/restore player context, and provide skip/replay policy. - impact camera: directional short modifier/shake layered over stable gameplay camera; never replace precise aiming information with uncontrolled jitter. use unreal-splines for general spline construction decisions. camera rig rail owns the cinematic tracking-shot implementation and sequencer keying. sequencer cuts, blends, and gameplay handoff sequencer cuts, blends, and gameplay handoff sequencer uses a level sequence asset for tracks/keys/bindings and a level sequence actor in the world for playback/context. camera workflow 1. create/open a level sequence. 2. add cine camera actors as spawnables or possessables according to lifetime/ownership. 3. add one camera cut track and bind shot sections to cameras. 4. place cut boundaries deliberately; overlap/shape supported sections when a camera blend is intended. 5. animate camera transform/lens/focus and preview through the cinematic viewport. 6. add event/audio/subsequence tracks only with explicit runtime ownership. 7. configure playback, binding overrides, sequence completion state, skip, and gameplay return. camera cut track controls the active cinematic camera. disabling camera cuts prevents the sequence from taking camera control. can blend/cut blending and gameplay blending must be tested with any gameplay camera switching that could occur during the blend. handoff contract before playback, capture/derive the local playercontroller's gameplay view state, input mode, ui, time/dilation, and player-control policy. during playback, decide whether gameplay continues, pauses, or is restricted. on finish, skip, interruption, death, level transition, or sequence destruction: 1. stop/finish the sequence using the intended completion policy; 2. restore or blend to the current valid gameplay view target, not a stale actor; 3. restore input/ui/time state; 4. clear cinematic-only modifiers and camera shakes; 5. handle repeated/overlapping sequence requests idempotently. test packaged builds and all terminal paths; editor scrubbing is not runtime handoff proof. ue 5.8 primary sources ue 5.8 primary sources - cameras - camera actors - spring arm component api - player camera manager api - camera modifier api - set view target with blend - camera shakes - play world camera shake - gameplay camera system overview - cine camera actor - sequencer overview - camera cut track - camera rigs - virtual cameras pages were checked against the ue 5.8 documentation on 2026-07-19. reconfirm experimental feature maturity, camera-stack behavior, sequencer handoff, and api/property names after an engine upgrade. spring arm follow, lag, and collision spring arm follow, lag, and collision uspringarmcomponent tries to maintain targetarmlength, retracts for collision, and returns when clear. important controls - targetarmlength: unobstructed boom distance. - targetoffset: world-space offset at the arm origin/pivot. - socketoffset: offset at the arm end; use it for shoulder framing so collision tracing includes it. - use pawn control rotation / inherit axes: defines rotation source. - do collision test: enables probe retraction. - probechannel / probesize: collision response and sphere size. - cameralagspeed: higher catches target faster; lower increases positional lag. - camerarotationlagspeed: higher catches desired rotation faster. - cameralagmaxdistance: caps positional separation from the target. - use camera lag substepping / max time step: improves damping consistency under fluctuating frame rate at added cost. tuning order 1. disable lag and shake; tune pivot, offsets, pitch, and arm length. 2. configure camera collision channel so intended blockers block and characters/effects do not. 3. test walls, corners, ceilings, doors, thin props, slopes, and tight corridors. 4. add location lag, cap it, then rotation lag. 5. test at multiple frame rates and after teleport/network correction. if retraction pops, inspect trace geometry/channel, probe size, pivot path, and obstruction release before slowing the entire camera. spring arm prevents its camera child from entering blockers; it does not solve subject occlusion by foreground objects between the camera and character. system selector system selector | need | prefer | key risk | |---|---|---| | third-person follow/orbit | pawn camera + spring arm | collision pop, lag, tight spaces | | first-person viewpoint | pawn camera / playercameramanager | body clipping, recoil/comfort | | local overlays and central pov policy | playercameramanager/cameramodifier | competing ownership/order | | switch to fixed/security camera | view target blend | return/interruption, local player | | reusable complex data-driven rigs | gameplay camera system | experimental ue 5.8 maturity | | authored cinematic | sequencer + cine camera | binding/time/skip/handoff | | tracking/dolly/crane shot | camera rig rail/crane | spline speed/orientation/framing | | virtual production operation | vcam | experimental/runtime/device workflow | write the ownership chain before implementation: input/game state -> desired subject/pivot -> base camera rig -> obstruction/collision -> lag -> state blend -> modifiers/shake -> post process -> final local pov. sequencer temporarily replaces or blends with that chain when camera cuts are enabled. one system must be authoritative for final pov at each instant. transitions, modifiers, and shakes transitions, modifiers, and shakes view targets use playercontroller set view target with blend with new view target, blend time, blend function, blend exponent, and optional lock outgoing. lock outgoing freezes the outgoing camera at its last position during the blend. store/derive the return target and define what happens if the target is destroyed, the player skips, or another transition interrupts. camera modifiers ucameramodifier adjusts final camera/post process through the owning playercameramanager. priority defines order; a modifier can be exclusive at its priority. use modifiers for bounded cross-camera effects such as recoil, damage response, sprint fov, or post-process feedback. enable/disable and blend them rather than permanently accumulating offsets. camera shakes - perlin: irregular high-energy rumble/explosion. - wave oscillator: smooth periodic rocking/drift. - sequence: authored camera animation. - composite: layered pattern types. amplitude controls displacement/rotation/fov magnitude; frequency controls speed. duration <= 0 can be indefinite, so owner cleanup is mandatory. blend in/out prevents discontinuities. single instance restarts instead of stacking another copy. use world shake for radial local-player response with inner/outer radius and falloff. it does not replicate; replicate/dispatch the gameplay event and play locally where appropriate. cap combined amplitude/frequency, scale by event/distance, and apply the player's shake-intensity setting including zero. avoid shake in precision aiming/platforming unless explicitly designed and controllable.","references":[{"slug":"cine-camera-and-lens","file":"cine-camera-and-lens.md","title":"Cine Camera Actor and lens","rawMarkdown":"# Cine Camera Actor and lens\n\nCine Camera Actor adds filmback, lens, aperture, focus, and look-at tools suited to cinematics.\n\n## Physical controls\n\n- **Filmback/sensor** affects field of view for a given focal length and establishes aspect framing.\n- **Current Focal Length**: longer narrows FOV/compresses framing; shorter widens FOV and exaggerates\n  spatial perspective when camera position changes to preserve subject size.\n- **Aperture (f-stop)**: lower f-number increases aperture and shallow depth-of-field potential;\n  higher f-number deepens focus. Exposure interaction depends on project/camera settings.\n- **Focus Method / Manual Focus Distance / Tracking**: defines focal plane behavior.\n- **Post Process Blend Weight**: blends the camera's post-process overrides.\n\n## Setup\n\n1. Choose delivery aspect/resolution and filmback before composing.\n2. Place the camera for perspective; then choose focal length for framing.\n3. Set focus method and visualize focus plane/debug focus.\n4. Tune aperture/DOF only after subject blocking and focus distance are stable.\n5. Lock exposure behavior with the lighting/cinematic plan; avoid compensating lens mistakes with\n   arbitrary post process.\n6. Test camera motion for focus pumping, clipping, motion blur, and temporal artifacts.\n\nDepth of field can obscure gameplay-critical information and increases rendering cost. For in-game\ncinematics, preserve subtitles, skip prompts, UI safe area, and accessibility requirements.\n","webMarkdown":"Cine Camera Actor adds filmback, lens, aperture, focus, and look-at tools suited to cinematics.\n\n## Physical controls\n\n- **Filmback/sensor** affects field of view for a given focal length and establishes aspect framing.\n- **Current Focal Length**: longer narrows FOV/compresses framing; shorter widens FOV and exaggerates\n  spatial perspective when camera position changes to preserve subject size.\n- **Aperture (f-stop)**: lower f-number increases aperture and shallow depth-of-field potential;\n  higher f-number deepens focus. Exposure interaction depends on project/camera settings.\n- **Focus Method / Manual Focus Distance / Tracking**: defines focal plane behavior.\n- **Post Process Blend Weight**: blends the camera's post-process overrides.\n\n## Setup\n\n1. Choose delivery aspect/resolution and filmback before composing.\n2. Place the camera for perspective; then choose focal length for framing.\n3. Set focus method and visualize focus plane/debug focus.\n4. Tune aperture/DOF only after subject blocking and focus distance are stable.\n5. Lock exposure behavior with the lighting/cinematic plan; avoid compensating lens mistakes with\n   arbitrary post process.\n6. Test camera motion for focus pumping, clipping, motion blur, and temporal artifacts.\n\nDepth of field can obscure gameplay-critical information and increases rendering cost. For in-game\ncinematics, preserve subtitles, skip prompts, UI safe area, and accessibility requirements.\n","searchText":"cine camera actor and lens cine camera actor adds filmback, lens, aperture, focus, and look-at tools suited to cinematics. physical controls - filmback/sensor affects field of view for a given focal length and establishes aspect framing. - current focal length: longer narrows fov/compresses framing; shorter widens fov and exaggerates spatial perspective when camera position changes to preserve subject size. - aperture (f-stop): lower f-number increases aperture and shallow depth-of-field potential; higher f-number deepens focus. exposure interaction depends on project/camera settings. - focus method / manual focus distance / tracking: defines focal plane behavior. - post process blend weight: blends the camera's post-process overrides. setup 1. choose delivery aspect/resolution and filmback before composing. 2. place the camera for perspective; then choose focal length for framing. 3. set focus method and visualize focus plane/debug focus. 4. tune aperture/dof only after subject blocking and focus distance are stable. 5. lock exposure behavior with the lighting/cinematic plan; avoid compensating lens mistakes with arbitrary post process. 6. test camera motion for focus pumping, clipping, motion blur, and temporal artifacts. depth of field can obscure gameplay-critical information and increases rendering cost. for in-game cinematics, preserve subtitles, skip prompts, ui safe area, and accessibility requirements."},{"slug":"debugging-patterns","file":"debugging-patterns.md","title":"Debugging patterns","rawMarkdown":"# Debugging patterns\n\n## Ownership isolation\n\n1. Print/log current local PlayerController, View Target, CameraManager, active sequence, and final POV.\n2. Disable Sequencer Camera Cuts, then modifiers/shakes, lag, and collision in that order.\n3. Verify the unmodified desired pivot/rotation/distance/FOV.\n4. Re-enable collision, lag, state blend, modifiers, shake, and post process one at a time.\n5. Test the same path at fixed low/high frame rates and in a packaged build.\n\n| Symptom | Inspect first |\n|---|---|\n| Camera inside wall | Spring Arm collision enabled/channel/probe, Camera attachment |\n| Snaps near corners | collision geometry/probe/release, pivot path, competing writers |\n| Character occluded but no collision | foreground occlusion policy; Spring Arm solves camera collision only |\n| Persistent jitter | target movement vs camera tick/order, multiple writers, network correction |\n| Sluggish input | rotation lag or smoothed input/desired rotation twice |\n| Offset ignored | relative Camera offset instead of Spring Arm SocketOffset |\n| Wrong player camera | local controller/view target assumption, split screen index |\n| Shake absent remotely | event not replicated/local playback not triggered |\n| Shake never ends | indefinite duration/owner cleanup |\n| Sequence plays but camera stays gameplay | missing/disabled Camera Cut Track or binding |\n| Camera remains cinematic | finish/skip/interruption handoff omitted |\n| Focus hunts/pumps | tracking target/focus distance and key interpolation |\n| Rail speed uneven | spline/time-key parameterization and interpolation |\n\nAcceptance routes: tight corridors, ceilings, corners, fast rotation, sprint/aim transition, teleport,\ndeath/possession, lock target lost, split screen, latency correction, cinematic finish/skip/interruption,\nresolution/aspect changes, zero-shake setting, and target performance capture.\n","webMarkdown":"## Ownership isolation\n\n1. Print/log current local PlayerController, View Target, CameraManager, active sequence, and final POV.\n2. Disable Sequencer Camera Cuts, then modifiers/shakes, lag, and collision in that order.\n3. Verify the unmodified desired pivot/rotation/distance/FOV.\n4. Re-enable collision, lag, state blend, modifiers, shake, and post process one at a time.\n5. Test the same path at fixed low/high frame rates and in a packaged build.\n\n| Symptom | Inspect first |\n|---|---|\n| Camera inside wall | Spring Arm collision enabled/channel/probe, Camera attachment |\n| Snaps near corners | collision geometry/probe/release, pivot path, competing writers |\n| Character occluded but no collision | foreground occlusion policy; Spring Arm solves camera collision only |\n| Persistent jitter | target movement vs camera tick/order, multiple writers, network correction |\n| Sluggish input | rotation lag or smoothed input/desired rotation twice |\n| Offset ignored | relative Camera offset instead of Spring Arm SocketOffset |\n| Wrong player camera | local controller/view target assumption, split screen index |\n| Shake absent remotely | event not replicated/local playback not triggered |\n| Shake never ends | indefinite duration/owner cleanup |\n| Sequence plays but camera stays gameplay | missing/disabled Camera Cut Track or binding |\n| Camera remains cinematic | finish/skip/interruption handoff omitted |\n| Focus hunts/pumps | tracking target/focus distance and key interpolation |\n| Rail speed uneven | spline/time-key parameterization and interpolation |\n\nAcceptance routes: tight corridors, ceilings, corners, fast rotation, sprint/aim transition, teleport,\ndeath/possession, lock target lost, split screen, latency correction, cinematic finish/skip/interruption,\nresolution/aspect changes, zero-shake setting, and target performance capture.\n","searchText":"debugging patterns ownership isolation 1. print/log current local playercontroller, view target, cameramanager, active sequence, and final pov. 2. disable sequencer camera cuts, then modifiers/shakes, lag, and collision in that order. 3. verify the unmodified desired pivot/rotation/distance/fov. 4. re-enable collision, lag, state blend, modifiers, shake, and post process one at a time. 5. test the same path at fixed low/high frame rates and in a packaged build. | symptom | inspect first | |---|---| | camera inside wall | spring arm collision enabled/channel/probe, camera attachment | | snaps near corners | collision geometry/probe/release, pivot path, competing writers | | character occluded but no collision | foreground occlusion policy; spring arm solves camera collision only | | persistent jitter | target movement vs camera tick/order, multiple writers, network correction | | sluggish input | rotation lag or smoothed input/desired rotation twice | | offset ignored | relative camera offset instead of spring arm socketoffset | | wrong player camera | local controller/view target assumption, split screen index | | shake absent remotely | event not replicated/local playback not triggered | | shake never ends | indefinite duration/owner cleanup | | sequence plays but camera stays gameplay | missing/disabled camera cut track or binding | | camera remains cinematic | finish/skip/interruption handoff omitted | | focus hunts/pumps | tracking target/focus distance and key interpolation | | rail speed uneven | spline/time-key parameterization and interpolation | acceptance routes: tight corridors, ceilings, corners, fast rotation, sprint/aim transition, teleport, death/possession, lock target lost, split screen, latency correction, cinematic finish/skip/interruption, resolution/aspect changes, zero-shake setting, and target performance capture."},{"slug":"gameplay-camera-architecture","file":"gameplay-camera-architecture.md","title":"Gameplay camera architecture","rawMarkdown":"# Gameplay camera architecture\n\n## Traditional shipping baseline\n\n- **Camera Component**: projection, FOV/aspect, post process, and POV on a Pawn/Actor.\n- **Spring Arm**: desired boom distance, rotation inheritance, collision retract, optional lag.\n- **PlayerController**: local input/view target and `Set View Target with Blend`.\n- **PlayerCameraManager**: calculates/caches final POV and applies modifiers/shakes/post process.\n\nKeep gameplay-facing camera state small: exploration, aim, lock-on, sprint, dialogue, photo, cinematic.\nEach state supplies desired pivot, arm length, FOV, offsets, rotation constraints, and blend policy.\nInterpolate a state result rather than running several independent timelines against the same property.\n\n## Follow/orbit\n\n1. Derive pivot from a stable target component/socket plus state offset.\n2. Use controller rotation for player orbit when appropriate; separate character facing from camera yaw.\n3. Clamp pitch before solving obstruction.\n4. Compute desired arm/framing, solve collision, then apply bounded smoothing.\n5. Preserve player input responsiveness; smooth camera motion, not input recognition.\n\n## Aim/lock-on\n\nBlend shoulder/FOV/rotation policy as a state. Keep reticle, weapon trace, camera trace, and character\naim solutions distinct. For lock-on, validate target, visibility/range, target switching, camera pitch,\nand unlock fallback. Avoid snapping the player/camera because a target was briefly occluded.\n\nOn teleport, possession, respawn, or large correction, reset accumulated camera lag and stale targets.\n","webMarkdown":"## Traditional shipping baseline\n\n- **Camera Component**: projection, FOV/aspect, post process, and POV on a Pawn/Actor.\n- **Spring Arm**: desired boom distance, rotation inheritance, collision retract, optional lag.\n- **PlayerController**: local input/view target and `Set View Target with Blend`.\n- **PlayerCameraManager**: calculates/caches final POV and applies modifiers/shakes/post process.\n\nKeep gameplay-facing camera state small: exploration, aim, lock-on, sprint, dialogue, photo, cinematic.\nEach state supplies desired pivot, arm length, FOV, offsets, rotation constraints, and blend policy.\nInterpolate a state result rather than running several independent timelines against the same property.\n\n## Follow/orbit\n\n1. Derive pivot from a stable target component/socket plus state offset.\n2. Use controller rotation for player orbit when appropriate; separate character facing from camera yaw.\n3. Clamp pitch before solving obstruction.\n4. Compute desired arm/framing, solve collision, then apply bounded smoothing.\n5. Preserve player input responsiveness; smooth camera motion, not input recognition.\n\n## Aim/lock-on\n\nBlend shoulder/FOV/rotation policy as a state. Keep reticle, weapon trace, camera trace, and character\naim solutions distinct. For lock-on, validate target, visibility/range, target switching, camera pitch,\nand unlock fallback. Avoid snapping the player/camera because a target was briefly occluded.\n\nOn teleport, possession, respawn, or large correction, reset accumulated camera lag and stale targets.\n","searchText":"gameplay camera architecture traditional shipping baseline - camera component: projection, fov/aspect, post process, and pov on a pawn/actor. - spring arm: desired boom distance, rotation inheritance, collision retract, optional lag. - playercontroller: local input/view target and set view target with blend. - playercameramanager: calculates/caches final pov and applies modifiers/shakes/post process. keep gameplay-facing camera state small: exploration, aim, lock-on, sprint, dialogue, photo, cinematic. each state supplies desired pivot, arm length, fov, offsets, rotation constraints, and blend policy. interpolate a state result rather than running several independent timelines against the same property. follow/orbit 1. derive pivot from a stable target component/socket plus state offset. 2. use controller rotation for player orbit when appropriate; separate character facing from camera yaw. 3. clamp pitch before solving obstruction. 4. compute desired arm/framing, solve collision, then apply bounded smoothing. 5. preserve player input responsiveness; smooth camera motion, not input recognition. aim/lock-on blend shoulder/fov/rotation policy as a state. keep reticle, weapon trace, camera trace, and character aim solutions distinct. for lock-on, validate target, visibility/range, target switching, camera pitch, and unlock fallback. avoid snapping the player/camera because a target was briefly occluded. on teleport, possession, respawn, or large correction, reset accumulated camera lag and stale targets."},{"slug":"gameplay-camera-system","file":"gameplay-camera-system.md","title":"Experimental Gameplay Camera System","rawMarkdown":"# Experimental Gameplay Camera System\n\nThe UE 5.8 Gameplay Camera System is Experimental. Use it only after an explicit production-maturity\ndecision and retain a traditional Camera Component/PlayerCameraManager fallback.\n\n## Architecture\n\n- **Camera Asset**: Camera Rigs, transitions, Director, and variables.\n- **Camera Rig**: node network describing camera behavior.\n- **Camera Transitions / Shared Transitions**: enter/exit behavior.\n- **Camera Director**: selects active rig—Single, Blueprint, or StateTree Director.\n- **Gameplay Camera Component/Actor**: consumes the Camera Asset.\n- **Camera Variable Collection**: exposes values used by the asset.\n\n## Procedure\n\n1. Define bounded rig states and variables before building nodes.\n2. Create one Camera Asset and the smallest required Camera Rigs.\n3. Choose a Director matching selection complexity.\n4. Author explicit enter/exit transitions and interruption behavior.\n5. Feed stable gameplay-facing variables into the consuming component.\n6. Use Camera Debugger to inspect selected rig, variables, and transitions.\n7. Test cook/package, multiplayer local ownership, split screen, performance, and migration fallback.\n\nDo not combine a data-driven Camera Rig with a second Blueprint system writing the same final POV.\nUse traditional camera systems when the requirement is simple or shipping-risk tolerance is low.\n","webMarkdown":"The UE 5.8 Gameplay Camera System is Experimental. Use it only after an explicit production-maturity\ndecision and retain a traditional Camera Component/PlayerCameraManager fallback.\n\n## Architecture\n\n- **Camera Asset**: Camera Rigs, transitions, Director, and variables.\n- **Camera Rig**: node network describing camera behavior.\n- **Camera Transitions / Shared Transitions**: enter/exit behavior.\n- **Camera Director**: selects active rig—Single, Blueprint, or StateTree Director.\n- **Gameplay Camera Component/Actor**: consumes the Camera Asset.\n- **Camera Variable Collection**: exposes values used by the asset.\n\n## Procedure\n\n1. Define bounded rig states and variables before building nodes.\n2. Create one Camera Asset and the smallest required Camera Rigs.\n3. Choose a Director matching selection complexity.\n4. Author explicit enter/exit transitions and interruption behavior.\n5. Feed stable gameplay-facing variables into the consuming component.\n6. Use Camera Debugger to inspect selected rig, variables, and transitions.\n7. Test cook/package, multiplayer local ownership, split screen, performance, and migration fallback.\n\nDo not combine a data-driven Camera Rig with a second Blueprint system writing the same final POV.\nUse traditional camera systems when the requirement is simple or shipping-risk tolerance is low.\n","searchText":"experimental gameplay camera system the ue 5.8 gameplay camera system is experimental. use it only after an explicit production-maturity decision and retain a traditional camera component/playercameramanager fallback. architecture - camera asset: camera rigs, transitions, director, and variables. - camera rig: node network describing camera behavior. - camera transitions / shared transitions: enter/exit behavior. - camera director: selects active rig—single, blueprint, or statetree director. - gameplay camera component/actor: consumes the camera asset. - camera variable collection: exposes values used by the asset. procedure 1. define bounded rig states and variables before building nodes. 2. create one camera asset and the smallest required camera rigs. 3. choose a director matching selection complexity. 4. author explicit enter/exit transitions and interruption behavior. 5. feed stable gameplay-facing variables into the consuming component. 6. use camera debugger to inspect selected rig, variables, and transitions. 7. test cook/package, multiplayer local ownership, split screen, performance, and migration fallback. do not combine a data-driven camera rig with a second blueprint system writing the same final pov. use traditional camera systems when the requirement is simple or shipping-risk tolerance is low."},{"slug":"network-accessibility-and-performance","file":"network-accessibility-and-performance.md","title":"Network, accessibility, and performance","rawMarkdown":"# Network, accessibility, and performance\n\n## Network/local ownership\n\nPlayer cameras normally exist as local presentation for human-controlled local players. Replicate the\nsubject, lock-on target, gameplay state, or cinematic event; each relevant local PlayerController\nconstructs its own view. World camera shake does not replicate. In split screen, address the intended\nlocal controller(s), not an assumed player zero.\n\nNetwork corrections can feed large target discontinuities into camera lag. Reset or bound camera\nhistory after teleports/corrections. Spectating/possession requires a new valid target and explicit\ntransition/cleanup.\n\n## Accessibility/comfort\n\n- expose shake intensity including off;\n- expose or limit head bob, motion blur, FOV changes, and aggressive camera lag where appropriate;\n- avoid forced roll and rapid oscillation;\n- keep reticle/horizon/reference stable during precision tasks;\n- preserve subtitle/UI safe areas and non-camera alternatives for feedback;\n- provide cinematic skip and restore control predictably.\n\n## Performance\n\nProfile per-local-player camera traces, target/occlusion tests, Blueprint modifier work, post process,\ndepth of field, motion blur, and cinematic resolution. Avoid many redundant traces from Pawn,\nController, and CameraManager. Cache stable references, restrict expensive target searches, and test\nsplit screen as multiplied local work.\n\nCamera motion can expose rendering/streaming problems not visible from static views. Test fast rails,\nwide reveals, cuts across the world, Lumen/lighting transitions, World Partition streaming, and target\nhardware. Coordinate with `unreal-lighting` and `unreal-world-partition` for those boundaries.\n","webMarkdown":"## Network/local ownership\n\nPlayer cameras normally exist as local presentation for human-controlled local players. Replicate the\nsubject, lock-on target, gameplay state, or cinematic event; each relevant local PlayerController\nconstructs its own view. World camera shake does not replicate. In split screen, address the intended\nlocal controller(s), not an assumed player zero.\n\nNetwork corrections can feed large target discontinuities into camera lag. Reset or bound camera\nhistory after teleports/corrections. Spectating/possession requires a new valid target and explicit\ntransition/cleanup.\n\n## Accessibility/comfort\n\n- expose shake intensity including off;\n- expose or limit head bob, motion blur, FOV changes, and aggressive camera lag where appropriate;\n- avoid forced roll and rapid oscillation;\n- keep reticle/horizon/reference stable during precision tasks;\n- preserve subtitle/UI safe areas and non-camera alternatives for feedback;\n- provide cinematic skip and restore control predictably.\n\n## Performance\n\nProfile per-local-player camera traces, target/occlusion tests, Blueprint modifier work, post process,\ndepth of field, motion blur, and cinematic resolution. Avoid many redundant traces from Pawn,\nController, and CameraManager. Cache stable references, restrict expensive target searches, and test\nsplit screen as multiplied local work.\n\nCamera motion can expose rendering/streaming problems not visible from static views. Test fast rails,\nwide reveals, cuts across the world, Lumen/lighting transitions, World Partition streaming, and target\nhardware. Coordinate with `unreal-lighting` and `unreal-world-partition` for those boundaries.\n","searchText":"network, accessibility, and performance network/local ownership player cameras normally exist as local presentation for human-controlled local players. replicate the subject, lock-on target, gameplay state, or cinematic event; each relevant local playercontroller constructs its own view. world camera shake does not replicate. in split screen, address the intended local controller(s), not an assumed player zero. network corrections can feed large target discontinuities into camera lag. reset or bound camera history after teleports/corrections. spectating/possession requires a new valid target and explicit transition/cleanup. accessibility/comfort - expose shake intensity including off; - expose or limit head bob, motion blur, fov changes, and aggressive camera lag where appropriate; - avoid forced roll and rapid oscillation; - keep reticle/horizon/reference stable during precision tasks; - preserve subtitle/ui safe areas and non-camera alternatives for feedback; - provide cinematic skip and restore control predictably. performance profile per-local-player camera traces, target/occlusion tests, blueprint modifier work, post process, depth of field, motion blur, and cinematic resolution. avoid many redundant traces from pawn, controller, and cameramanager. cache stable references, restrict expensive target searches, and test split screen as multiplied local work. camera motion can expose rendering/streaming problems not visible from static views. test fast rails, wide reveals, cuts across the world, lumen/lighting transitions, world partition streaming, and target hardware. coordinate with unreal-lighting and unreal-world-partition for those boundaries."},{"slug":"rails-cranes-and-shot-recipes","file":"rails-cranes-and-shot-recipes.md","title":"Rails, cranes, and shot recipes","rawMarkdown":"# Rails, cranes, and shot recipes\n\n## Camera Rig Rail\n\nPlace from Cinematic actors, shape its Blueprint Spline, attach the Cine Camera to the dolly, and\nanimate `Current Position on Rail` from 0 to 1 in Sequencer. `Lock Orientation to Rail` makes camera\nrotation relative to dolly orientation; otherwise animate orientation independently. Spatially even\nspline travel is not guaranteed by evenly spaced time keys—inspect speed and use key interpolation.\n\n## Camera Rig Crane\n\nAttach the camera to the mount, then animate arm length, yaw, and pitch. Lock mount pitch/yaw only\nwhen camera orientation should follow the crane. Combine Rail and Crane only when the extra degrees of\nfreedom materially serve the shot; nested transforms complicate framing and debugging.\n\n## Recipes\n\n- **Reveal**: begin with occlusion/tight frame, move Rail/Crane to expose subject, preserve focal plane.\n- **Tracking shot**: rail/dolly carries translation; camera independently maintains composition/look.\n- **Dialogue cut**: consistent eyeline/screen direction, controlled lens/focus, intentional cut timing.\n- **Gameplay establishing shot**: show objective/path, minimize duration, retain/restore player context,\n  and provide skip/replay policy.\n- **Impact camera**: directional short modifier/shake layered over stable gameplay camera; never replace\n  precise aiming information with uncontrolled jitter.\n\nUse `unreal-splines` for general spline construction decisions. Camera Rig Rail owns the cinematic\ntracking-shot implementation and Sequencer keying.\n","webMarkdown":"## Camera Rig Rail\n\nPlace from Cinematic actors, shape its Blueprint Spline, attach the Cine Camera to the dolly, and\nanimate `Current Position on Rail` from 0 to 1 in Sequencer. `Lock Orientation to Rail` makes camera\nrotation relative to dolly orientation; otherwise animate orientation independently. Spatially even\nspline travel is not guaranteed by evenly spaced time keys—inspect speed and use key interpolation.\n\n## Camera Rig Crane\n\nAttach the camera to the mount, then animate arm length, yaw, and pitch. Lock mount pitch/yaw only\nwhen camera orientation should follow the crane. Combine Rail and Crane only when the extra degrees of\nfreedom materially serve the shot; nested transforms complicate framing and debugging.\n\n## Recipes\n\n- **Reveal**: begin with occlusion/tight frame, move Rail/Crane to expose subject, preserve focal plane.\n- **Tracking shot**: rail/dolly carries translation; camera independently maintains composition/look.\n- **Dialogue cut**: consistent eyeline/screen direction, controlled lens/focus, intentional cut timing.\n- **Gameplay establishing shot**: show objective/path, minimize duration, retain/restore player context,\n  and provide skip/replay policy.\n- **Impact camera**: directional short modifier/shake layered over stable gameplay camera; never replace\n  precise aiming information with uncontrolled jitter.\n\nUse `unreal-splines` for general spline construction decisions. Camera Rig Rail owns the cinematic\ntracking-shot implementation and Sequencer keying.\n","searchText":"rails, cranes, and shot recipes camera rig rail place from cinematic actors, shape its blueprint spline, attach the cine camera to the dolly, and animate current position on rail from 0 to 1 in sequencer. lock orientation to rail makes camera rotation relative to dolly orientation; otherwise animate orientation independently. spatially even spline travel is not guaranteed by evenly spaced time keys—inspect speed and use key interpolation. camera rig crane attach the camera to the mount, then animate arm length, yaw, and pitch. lock mount pitch/yaw only when camera orientation should follow the crane. combine rail and crane only when the extra degrees of freedom materially serve the shot; nested transforms complicate framing and debugging. recipes - reveal: begin with occlusion/tight frame, move rail/crane to expose subject, preserve focal plane. - tracking shot: rail/dolly carries translation; camera independently maintains composition/look. - dialogue cut: consistent eyeline/screen direction, controlled lens/focus, intentional cut timing. - gameplay establishing shot: show objective/path, minimize duration, retain/restore player context, and provide skip/replay policy. - impact camera: directional short modifier/shake layered over stable gameplay camera; never replace precise aiming information with uncontrolled jitter. use unreal-splines for general spline construction decisions. camera rig rail owns the cinematic tracking-shot implementation and sequencer keying."},{"slug":"sequencer-cuts-and-handoff","file":"sequencer-cuts-and-handoff.md","title":"Sequencer cuts, blends, and gameplay handoff","rawMarkdown":"# Sequencer cuts, blends, and gameplay handoff\n\nSequencer uses a Level Sequence Asset for tracks/keys/bindings and a Level Sequence Actor in the\nworld for playback/context.\n\n## Camera workflow\n\n1. Create/open a Level Sequence.\n2. Add Cine Camera Actors as spawnables or possessables according to lifetime/ownership.\n3. Add one Camera Cut Track and bind shot sections to cameras.\n4. Place cut boundaries deliberately; overlap/shape supported sections when a camera blend is intended.\n5. Animate camera transform/lens/focus and preview through the cinematic viewport.\n6. Add event/audio/subsequence tracks only with explicit runtime ownership.\n7. Configure playback, binding overrides, sequence completion state, skip, and gameplay return.\n\nCamera Cut Track controls the active cinematic camera. Disabling Camera Cuts prevents the sequence\nfrom taking camera control. `Can Blend`/cut blending and gameplay blending must be tested with any\ngameplay camera switching that could occur during the blend.\n\n## Handoff contract\n\nBefore playback, capture/derive the local PlayerController's gameplay view state, input mode, UI,\ntime/dilation, and player-control policy. During playback, decide whether gameplay continues, pauses,\nor is restricted. On finish, skip, interruption, death, level transition, or sequence destruction:\n\n1. stop/finish the sequence using the intended completion policy;\n2. restore or blend to the current valid gameplay view target, not a stale actor;\n3. restore input/UI/time state;\n4. clear cinematic-only modifiers and camera shakes;\n5. handle repeated/overlapping sequence requests idempotently.\n\nTest packaged builds and all terminal paths; editor scrubbing is not runtime handoff proof.\n","webMarkdown":"Sequencer uses a Level Sequence Asset for tracks/keys/bindings and a Level Sequence Actor in the\nworld for playback/context.\n\n## Camera workflow\n\n1. Create/open a Level Sequence.\n2. Add Cine Camera Actors as spawnables or possessables according to lifetime/ownership.\n3. Add one Camera Cut Track and bind shot sections to cameras.\n4. Place cut boundaries deliberately; overlap/shape supported sections when a camera blend is intended.\n5. Animate camera transform/lens/focus and preview through the cinematic viewport.\n6. Add event/audio/subsequence tracks only with explicit runtime ownership.\n7. Configure playback, binding overrides, sequence completion state, skip, and gameplay return.\n\nCamera Cut Track controls the active cinematic camera. Disabling Camera Cuts prevents the sequence\nfrom taking camera control. `Can Blend`/cut blending and gameplay blending must be tested with any\ngameplay camera switching that could occur during the blend.\n\n## Handoff contract\n\nBefore playback, capture/derive the local PlayerController's gameplay view state, input mode, UI,\ntime/dilation, and player-control policy. During playback, decide whether gameplay continues, pauses,\nor is restricted. On finish, skip, interruption, death, level transition, or sequence destruction:\n\n1. stop/finish the sequence using the intended completion policy;\n2. restore or blend to the current valid gameplay view target, not a stale actor;\n3. restore input/UI/time state;\n4. clear cinematic-only modifiers and camera shakes;\n5. handle repeated/overlapping sequence requests idempotently.\n\nTest packaged builds and all terminal paths; editor scrubbing is not runtime handoff proof.\n","searchText":"sequencer cuts, blends, and gameplay handoff sequencer uses a level sequence asset for tracks/keys/bindings and a level sequence actor in the world for playback/context. camera workflow 1. create/open a level sequence. 2. add cine camera actors as spawnables or possessables according to lifetime/ownership. 3. add one camera cut track and bind shot sections to cameras. 4. place cut boundaries deliberately; overlap/shape supported sections when a camera blend is intended. 5. animate camera transform/lens/focus and preview through the cinematic viewport. 6. add event/audio/subsequence tracks only with explicit runtime ownership. 7. configure playback, binding overrides, sequence completion state, skip, and gameplay return. camera cut track controls the active cinematic camera. disabling camera cuts prevents the sequence from taking camera control. can blend/cut blending and gameplay blending must be tested with any gameplay camera switching that could occur during the blend. handoff contract before playback, capture/derive the local playercontroller's gameplay view state, input mode, ui, time/dilation, and player-control policy. during playback, decide whether gameplay continues, pauses, or is restricted. on finish, skip, interruption, death, level transition, or sequence destruction: 1. stop/finish the sequence using the intended completion policy; 2. restore or blend to the current valid gameplay view target, not a stale actor; 3. restore input/ui/time state; 4. clear cinematic-only modifiers and camera shakes; 5. handle repeated/overlapping sequence requests idempotently. test packaged builds and all terminal paths; editor scrubbing is not runtime handoff proof."},{"slug":"sources","file":"sources.md","title":"UE 5.8 primary sources","rawMarkdown":"# UE 5.8 primary sources\n\n- [Cameras](https://dev.epicgames.com/documentation/en-us/unreal-engine/cameras-in-unreal-engine)\n- [Camera Actors](https://dev.epicgames.com/documentation/en-us/unreal-engine/camera-actors-in-unreal-engine)\n- [Spring Arm Component API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/USpringArmComponent)\n- [Player Camera Manager API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/APlayerCameraManager)\n- [Camera Modifier API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/UCameraModifier)\n- [Set View Target with Blend](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/Game/Player/SetViewTargetwithBlend)\n- [Camera Shakes](https://dev.epicgames.com/documentation/en-us/unreal-engine/camera-shakes-in-unreal-engine)\n- [Play World Camera Shake](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/Camera/PlayWorldCameraShake)\n- [Gameplay Camera System Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/gameplay-camera-system-overview)\n- [Cine Camera Actor](https://dev.epicgames.com/documentation/en-us/unreal-engine/cinematic-cameras-in-unreal-engine)\n- [Sequencer Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-sequencer-movie-tool-overview)\n- [Camera Cut Track](https://dev.epicgames.com/documentation/en-us/unreal-engine/cinematic-camera-cut-track-in-unreal-engine)\n- [Camera Rigs](https://dev.epicgames.com/documentation/en-us/unreal-engine/camera-jibs-and-dollies-in-unreal-engine)\n- [Virtual Cameras](https://dev.epicgames.com/documentation/en-us/unreal-engine/virtual-cameras-in-unreal-engine)\n\nPages were checked against the UE 5.8 documentation on 2026-07-19. Reconfirm Experimental feature\nmaturity, camera-stack behavior, Sequencer handoff, and API/property names after an engine upgrade.\n","webMarkdown":"- [Cameras](https://dev.epicgames.com/documentation/en-us/unreal-engine/cameras-in-unreal-engine)\n- [Camera Actors](https://dev.epicgames.com/documentation/en-us/unreal-engine/camera-actors-in-unreal-engine)\n- [Spring Arm Component API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/USpringArmComponent)\n- [Player Camera Manager API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/APlayerCameraManager)\n- [Camera Modifier API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/UCameraModifier)\n- [Set View Target with Blend](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/Game/Player/SetViewTargetwithBlend)\n- [Camera Shakes](https://dev.epicgames.com/documentation/en-us/unreal-engine/camera-shakes-in-unreal-engine)\n- [Play World Camera Shake](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/Camera/PlayWorldCameraShake)\n- [Gameplay Camera System Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/gameplay-camera-system-overview)\n- [Cine Camera Actor](https://dev.epicgames.com/documentation/en-us/unreal-engine/cinematic-cameras-in-unreal-engine)\n- [Sequencer Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-sequencer-movie-tool-overview)\n- [Camera Cut Track](https://dev.epicgames.com/documentation/en-us/unreal-engine/cinematic-camera-cut-track-in-unreal-engine)\n- [Camera Rigs](https://dev.epicgames.com/documentation/en-us/unreal-engine/camera-jibs-and-dollies-in-unreal-engine)\n- [Virtual Cameras](https://dev.epicgames.com/documentation/en-us/unreal-engine/virtual-cameras-in-unreal-engine)\n\nPages were checked against the UE 5.8 documentation on 2026-07-19. Reconfirm Experimental feature\nmaturity, camera-stack behavior, Sequencer handoff, and API/property names after an engine upgrade.\n","searchText":"ue 5.8 primary sources - cameras - camera actors - spring arm component api - player camera manager api - camera modifier api - set view target with blend - camera shakes - play world camera shake - gameplay camera system overview - cine camera actor - sequencer overview - camera cut track - camera rigs - virtual cameras pages were checked against the ue 5.8 documentation on 2026-07-19. reconfirm experimental feature maturity, camera-stack behavior, sequencer handoff, and api/property names after an engine upgrade."},{"slug":"spring-arm-follow-and-collision","file":"spring-arm-follow-and-collision.md","title":"Spring Arm follow, lag, and collision","rawMarkdown":"# Spring Arm follow, lag, and collision\n\n`USpringArmComponent` tries to maintain `TargetArmLength`, retracts for collision, and returns when\nclear.\n\n## Important controls\n\n- **TargetArmLength**: unobstructed boom distance.\n- **TargetOffset**: world-space offset at the arm origin/pivot.\n- **SocketOffset**: offset at the arm end; use it for shoulder framing so collision tracing includes it.\n- **Use Pawn Control Rotation / inherit axes**: defines rotation source.\n- **Do Collision Test**: enables probe retraction.\n- **ProbeChannel / ProbeSize**: collision response and sphere size.\n- **CameraLagSpeed**: higher catches target faster; lower increases positional lag.\n- **CameraRotationLagSpeed**: higher catches desired rotation faster.\n- **CameraLagMaxDistance**: caps positional separation from the target.\n- **Use Camera Lag Substepping / Max Time Step**: improves damping consistency under fluctuating frame\n  rate at added cost.\n\n## Tuning order\n\n1. Disable lag and shake; tune pivot, offsets, pitch, and arm length.\n2. Configure Camera collision channel so intended blockers block and characters/effects do not.\n3. Test walls, corners, ceilings, doors, thin props, slopes, and tight corridors.\n4. Add location lag, cap it, then rotation lag.\n5. Test at multiple frame rates and after teleport/network correction.\n\nIf retraction pops, inspect trace geometry/channel, probe size, pivot path, and obstruction release\nbefore slowing the entire camera. Spring Arm prevents its camera child from entering blockers; it does\nnot solve subject occlusion by foreground objects between the camera and character.\n","webMarkdown":"`USpringArmComponent` tries to maintain `TargetArmLength`, retracts for collision, and returns when\nclear.\n\n## Important controls\n\n- **TargetArmLength**: unobstructed boom distance.\n- **TargetOffset**: world-space offset at the arm origin/pivot.\n- **SocketOffset**: offset at the arm end; use it for shoulder framing so collision tracing includes it.\n- **Use Pawn Control Rotation / inherit axes**: defines rotation source.\n- **Do Collision Test**: enables probe retraction.\n- **ProbeChannel / ProbeSize**: collision response and sphere size.\n- **CameraLagSpeed**: higher catches target faster; lower increases positional lag.\n- **CameraRotationLagSpeed**: higher catches desired rotation faster.\n- **CameraLagMaxDistance**: caps positional separation from the target.\n- **Use Camera Lag Substepping / Max Time Step**: improves damping consistency under fluctuating frame\n  rate at added cost.\n\n## Tuning order\n\n1. Disable lag and shake; tune pivot, offsets, pitch, and arm length.\n2. Configure Camera collision channel so intended blockers block and characters/effects do not.\n3. Test walls, corners, ceilings, doors, thin props, slopes, and tight corridors.\n4. Add location lag, cap it, then rotation lag.\n5. Test at multiple frame rates and after teleport/network correction.\n\nIf retraction pops, inspect trace geometry/channel, probe size, pivot path, and obstruction release\nbefore slowing the entire camera. Spring Arm prevents its camera child from entering blockers; it does\nnot solve subject occlusion by foreground objects between the camera and character.\n","searchText":"spring arm follow, lag, and collision uspringarmcomponent tries to maintain targetarmlength, retracts for collision, and returns when clear. important controls - targetarmlength: unobstructed boom distance. - targetoffset: world-space offset at the arm origin/pivot. - socketoffset: offset at the arm end; use it for shoulder framing so collision tracing includes it. - use pawn control rotation / inherit axes: defines rotation source. - do collision test: enables probe retraction. - probechannel / probesize: collision response and sphere size. - cameralagspeed: higher catches target faster; lower increases positional lag. - camerarotationlagspeed: higher catches desired rotation faster. - cameralagmaxdistance: caps positional separation from the target. - use camera lag substepping / max time step: improves damping consistency under fluctuating frame rate at added cost. tuning order 1. disable lag and shake; tune pivot, offsets, pitch, and arm length. 2. configure camera collision channel so intended blockers block and characters/effects do not. 3. test walls, corners, ceilings, doors, thin props, slopes, and tight corridors. 4. add location lag, cap it, then rotation lag. 5. test at multiple frame rates and after teleport/network correction. if retraction pops, inspect trace geometry/channel, probe size, pivot path, and obstruction release before slowing the entire camera. spring arm prevents its camera child from entering blockers; it does not solve subject occlusion by foreground objects between the camera and character."},{"slug":"system-selector","file":"system-selector.md","title":"System selector","rawMarkdown":"# System selector\n\n| Need | Prefer | Key risk |\n|---|---|---|\n| Third-person follow/orbit | Pawn Camera + Spring Arm | collision pop, lag, tight spaces |\n| First-person viewpoint | Pawn Camera / PlayerCameraManager | body clipping, recoil/comfort |\n| Local overlays and central POV policy | PlayerCameraManager/CameraModifier | competing ownership/order |\n| Switch to fixed/security camera | View target blend | return/interruption, local player |\n| Reusable complex data-driven rigs | Gameplay Camera System | Experimental UE 5.8 maturity |\n| Authored cinematic | Sequencer + Cine Camera | binding/time/skip/handoff |\n| Tracking/dolly/crane shot | Camera Rig Rail/Crane | spline speed/orientation/framing |\n| Virtual production operation | VCam | Experimental/runtime/device workflow |\n\nWrite the ownership chain before implementation:\n\n`input/game state -> desired subject/pivot -> base camera rig -> obstruction/collision -> lag ->\nstate blend -> modifiers/shake -> post process -> final local POV`.\n\nSequencer temporarily replaces or blends with that chain when Camera Cuts are enabled. One system\nmust be authoritative for final POV at each instant.\n","webMarkdown":"| Need | Prefer | Key risk |\n|---|---|---|\n| Third-person follow/orbit | Pawn Camera + Spring Arm | collision pop, lag, tight spaces |\n| First-person viewpoint | Pawn Camera / PlayerCameraManager | body clipping, recoil/comfort |\n| Local overlays and central POV policy | PlayerCameraManager/CameraModifier | competing ownership/order |\n| Switch to fixed/security camera | View target blend | return/interruption, local player |\n| Reusable complex data-driven rigs | Gameplay Camera System | Experimental UE 5.8 maturity |\n| Authored cinematic | Sequencer + Cine Camera | binding/time/skip/handoff |\n| Tracking/dolly/crane shot | Camera Rig Rail/Crane | spline speed/orientation/framing |\n| Virtual production operation | VCam | Experimental/runtime/device workflow |\n\nWrite the ownership chain before implementation:\n\n`input/game state -> desired subject/pivot -> base camera rig -> obstruction/collision -> lag ->\nstate blend -> modifiers/shake -> post process -> final local POV`.\n\nSequencer temporarily replaces or blends with that chain when Camera Cuts are enabled. One system\nmust be authoritative for final POV at each instant.\n","searchText":"system selector | need | prefer | key risk | |---|---|---| | third-person follow/orbit | pawn camera + spring arm | collision pop, lag, tight spaces | | first-person viewpoint | pawn camera / playercameramanager | body clipping, recoil/comfort | | local overlays and central pov policy | playercameramanager/cameramodifier | competing ownership/order | | switch to fixed/security camera | view target blend | return/interruption, local player | | reusable complex data-driven rigs | gameplay camera system | experimental ue 5.8 maturity | | authored cinematic | sequencer + cine camera | binding/time/skip/handoff | | tracking/dolly/crane shot | camera rig rail/crane | spline speed/orientation/framing | | virtual production operation | vcam | experimental/runtime/device workflow | write the ownership chain before implementation: input/game state -> desired subject/pivot -> base camera rig -> obstruction/collision -> lag -> state blend -> modifiers/shake -> post process -> final local pov. sequencer temporarily replaces or blends with that chain when camera cuts are enabled. one system must be authoritative for final pov at each instant."},{"slug":"transitions-modifiers-and-shakes","file":"transitions-modifiers-and-shakes.md","title":"Transitions, modifiers, and shakes","rawMarkdown":"# Transitions, modifiers, and shakes\n\n## View targets\n\nUse PlayerController `Set View Target with Blend` with New View Target, Blend Time, Blend Function,\nBlend Exponent, and optional Lock Outgoing. Lock Outgoing freezes the outgoing camera at its last\nposition during the blend. Store/derive the return target and define what happens if the target is\ndestroyed, the player skips, or another transition interrupts.\n\n## Camera modifiers\n\n`UCameraModifier` adjusts final camera/Post Process through the owning PlayerCameraManager. Priority\ndefines order; a modifier can be exclusive at its priority. Use modifiers for bounded cross-camera\neffects such as recoil, damage response, sprint FOV, or post-process feedback. Enable/disable and\nblend them rather than permanently accumulating offsets.\n\n## Camera shakes\n\n- **Perlin**: irregular high-energy rumble/explosion.\n- **Wave oscillator**: smooth periodic rocking/drift.\n- **Sequence**: authored camera animation.\n- **Composite**: layered pattern types.\n\nAmplitude controls displacement/rotation/FOV magnitude; frequency controls speed. Duration <= 0 can\nbe indefinite, so owner cleanup is mandatory. Blend in/out prevents discontinuities. Single Instance\nrestarts instead of stacking another copy.\n\nUse world shake for radial local-player response with inner/outer radius and falloff. It does not\nreplicate; replicate/dispatch the gameplay event and play locally where appropriate. Cap combined\namplitude/frequency, scale by event/distance, and apply the player's shake-intensity setting including\nzero. Avoid shake in precision aiming/platforming unless explicitly designed and controllable.\n","webMarkdown":"## View targets\n\nUse PlayerController `Set View Target with Blend` with New View Target, Blend Time, Blend Function,\nBlend Exponent, and optional Lock Outgoing. Lock Outgoing freezes the outgoing camera at its last\nposition during the blend. Store/derive the return target and define what happens if the target is\ndestroyed, the player skips, or another transition interrupts.\n\n## Camera modifiers\n\n`UCameraModifier` adjusts final camera/Post Process through the owning PlayerCameraManager. Priority\ndefines order; a modifier can be exclusive at its priority. Use modifiers for bounded cross-camera\neffects such as recoil, damage response, sprint FOV, or post-process feedback. Enable/disable and\nblend them rather than permanently accumulating offsets.\n\n## Camera shakes\n\n- **Perlin**: irregular high-energy rumble/explosion.\n- **Wave oscillator**: smooth periodic rocking/drift.\n- **Sequence**: authored camera animation.\n- **Composite**: layered pattern types.\n\nAmplitude controls displacement/rotation/FOV magnitude; frequency controls speed. Duration <= 0 can\nbe indefinite, so owner cleanup is mandatory. Blend in/out prevents discontinuities. Single Instance\nrestarts instead of stacking another copy.\n\nUse world shake for radial local-player response with inner/outer radius and falloff. It does not\nreplicate; replicate/dispatch the gameplay event and play locally where appropriate. Cap combined\namplitude/frequency, scale by event/distance, and apply the player's shake-intensity setting including\nzero. Avoid shake in precision aiming/platforming unless explicitly designed and controllable.\n","searchText":"transitions, modifiers, and shakes view targets use playercontroller set view target with blend with new view target, blend time, blend function, blend exponent, and optional lock outgoing. lock outgoing freezes the outgoing camera at its last position during the blend. store/derive the return target and define what happens if the target is destroyed, the player skips, or another transition interrupts. camera modifiers ucameramodifier adjusts final camera/post process through the owning playercameramanager. priority defines order; a modifier can be exclusive at its priority. use modifiers for bounded cross-camera effects such as recoil, damage response, sprint fov, or post-process feedback. enable/disable and blend them rather than permanently accumulating offsets. camera shakes - perlin: irregular high-energy rumble/explosion. - wave oscillator: smooth periodic rocking/drift. - sequence: authored camera animation. - composite: layered pattern types. amplitude controls displacement/rotation/fov magnitude; frequency controls speed. duration <= 0 can be indefinite, so owner cleanup is mandatory. blend in/out prevents discontinuities. single instance restarts instead of stacking another copy. use world shake for radial local-player response with inner/outer radius and falloff. it does not replicate; replicate/dispatch the gameplay event and play locally where appropriate. cap combined amplitude/frequency, scale by event/distance, and apply the player's shake-intensity setting including zero. avoid shake in precision aiming/platforming unless explicitly designed and controllable."}]}
{"slug":"unreal-chaos-physics","name":"unreal-chaos-physics","title":"Unreal 5.8 Chaos Physics","description":"Design, implement, tune, replicate, optimize, and debug Chaos Physics systems in Unreal Engine 5.8. Use for collision channels and shapes, scene queries, rigid bodies, mass, damping, friction, restitution, CCD, forces and impulses, Physics Constraints and drives, substepping, async/fixed physics, networked physics replication modes and resimulation, Physics Assets, ragdolls, physical animation, Geometry Collections, fracture and clustering, Chaos Fields, destruction caches, Chaos Cloth, Chaos Visual Debugger, unstable simulation, tunneling, jitter, explosions, or physics performance.","shortDescription":"Build and debug Chaos physics systems","category":"Gameplay","referenceCount":12,"rawMarkdown":"---\nname: unreal-chaos-physics\ndescription: Design, implement, tune, replicate, optimize, and debug Chaos Physics systems in Unreal Engine 5.8. Use for collision channels and shapes, scene queries, rigid bodies, mass, damping, friction, restitution, CCD, forces and impulses, Physics Constraints and drives, substepping, async/fixed physics, networked physics replication modes and resimulation, Physics Assets, ragdolls, physical animation, Geometry Collections, fracture and clustering, Chaos Fields, destruction caches, Chaos Cloth, Chaos Visual Debugger, unstable simulation, tunneling, jitter, explosions, or physics performance.\n---\n\n# Unreal 5.8 Chaos Physics\n\n## Choose the physical contract first\n\nRead [`references/system-selector.md`](references/system-selector.md).\n\n1. Define which interactions are authoritative gameplay and which are cosmetic simulation.\n2. Choose query-only, simple rigid body, skeletal Physics Asset, constraint assembly, Geometry\n   Collection, cloth, or cached playback.\n3. Define collision object/trace channels, shape representation, mass/inertia, timestep, sleep, and\n   network authority before tuning forces.\n4. Build the smallest stable case at target scale and frame-rate range.\n5. Add constraints, drives, fields, fracture, cloth, and replication incrementally.\n6. Reproduce worst contact counts, piece counts, player latency, and frame spikes on target hardware.\n7. Capture Chaos Visual Debugger plus Timing/Network Insights when the failure is not visible in one\n   component's settings.\n\nUse `unreal-replication` for general Actor/property/RPC ownership. This skill owns physics-specific\nreplication modes, inputs/state history, correction, and resimulation.\n\nLoad only what applies:\n\n- [`references/collision-and-queries.md`](references/collision-and-queries.md)\n- [`references/rigid-bodies-forces-and-sleep.md`](references/rigid-bodies-forces-and-sleep.md)\n- [`references/constraints-and-drives.md`](references/constraints-and-drives.md)\n- [`references/timestep-substepping-and-async.md`](references/timestep-substepping-and-async.md)\n- [`references/networked-physics.md`](references/networked-physics.md)\n- [`references/physics-assets-and-ragdolls.md`](references/physics-assets-and-ragdolls.md)\n- [`references/destruction-collections-and-fields.md`](references/destruction-collections-and-fields.md)\n- [`references/cloth.md`](references/cloth.md)\n- [`references/debugging-and-performance.md`](references/debugging-and-performance.md)\n- [`references/use-case-recipes.md`](references/use-case-recipes.md)\n\n## Required answer format\n\nReturn:\n\n1. **Gameplay authority and chosen physics representation**.\n2. **Collision/query matrix**, shapes, scale, mass/inertia, and physical material.\n3. **Timestep/threading/substep assumptions** and failure frame-rate.\n4. **Forces, impulses, constraints, drives, fields, or fracture/cloth settings** with units/effects.\n5. **Network replication mode**, input/state ownership, correction, and latency test if multiplayer.\n6. **Performance budget** for bodies, contacts, constraints, pieces, cloth vertices, events, and traces.\n7. **Chaos Visual Debugger/Insights evidence** and acceptance checks.\n\n## Hard rules\n\n- Prefer simple primitives/convex collision for simulation; `Use Complex Collision As Simple` cannot\n  simulate the object itself.\n- Separate Query Only, Physics Only, and Query and Physics behavior deliberately.\n- Enable overlap/hit events only for consumers that need them; event generation has work and both sides'\n  response settings matter.\n- Use force for sustained acceleration and impulse for an instantaneous change. Apply at location only\n  when induced torque is intended.\n- Do not repair scale, mass, collision, or timestep errors by arbitrary extreme damping/solver values.\n- Treat UE 5.8 substepping, async substepping, and async physics settings as Experimental and test every\n  platform/gameplay dependency.\n- Physics callbacks under substepping may produce multiple ordered contact transitions in one game frame.\n- Default, Predictive Interpolation, and Resimulation solve different network problems; Resimulation is\n  more costly and the Network Physics Component requires manual C++ integration.\n- Chaos Cloth is Production Ready in UE 5.8; Chaos Caching remains Experimental.\n- Bound destruction piece/contact/event lifetime with clustering, sleep/disable/removal, and pooling.\n- Do not make authoritative damage depend on nondeterministic cosmetic debris or cloth contacts.\n- Profile the complete scene; a stable isolated asset can fail under real contact and solver load.\n\nSee [`references/sources.md`](references/sources.md) for the UE 5.8 primary-source trail.\n","webMarkdown":"## Choose the physical contract first\n\nRead [`references/system-selector.md`](/unreal/unreal-chaos-physics/system-selector/).\n\n1. Define which interactions are authoritative gameplay and which are cosmetic simulation.\n2. Choose query-only, simple rigid body, skeletal Physics Asset, constraint assembly, Geometry\n   Collection, cloth, or cached playback.\n3. Define collision object/trace channels, shape representation, mass/inertia, timestep, sleep, and\n   network authority before tuning forces.\n4. Build the smallest stable case at target scale and frame-rate range.\n5. Add constraints, drives, fields, fracture, cloth, and replication incrementally.\n6. Reproduce worst contact counts, piece counts, player latency, and frame spikes on target hardware.\n7. Capture Chaos Visual Debugger plus Timing/Network Insights when the failure is not visible in one\n   component's settings.\n\nUse `unreal-replication` for general Actor/property/RPC ownership. This skill owns physics-specific\nreplication modes, inputs/state history, correction, and resimulation.\n\nLoad only what applies:\n\n- [`references/collision-and-queries.md`](/unreal/unreal-chaos-physics/collision-and-queries/)\n- [`references/rigid-bodies-forces-and-sleep.md`](/unreal/unreal-chaos-physics/rigid-bodies-forces-and-sleep/)\n- [`references/constraints-and-drives.md`](/unreal/unreal-chaos-physics/constraints-and-drives/)\n- [`references/timestep-substepping-and-async.md`](/unreal/unreal-chaos-physics/timestep-substepping-and-async/)\n- [`references/networked-physics.md`](/unreal/unreal-chaos-physics/networked-physics/)\n- [`references/physics-assets-and-ragdolls.md`](/unreal/unreal-chaos-physics/physics-assets-and-ragdolls/)\n- [`references/destruction-collections-and-fields.md`](/unreal/unreal-chaos-physics/destruction-collections-and-fields/)\n- [`references/cloth.md`](/unreal/unreal-chaos-physics/cloth/)\n- [`references/debugging-and-performance.md`](/unreal/unreal-chaos-physics/debugging-and-performance/)\n- [`references/use-case-recipes.md`](/unreal/unreal-chaos-physics/use-case-recipes/)\n\n## Required answer format\n\nReturn:\n\n1. **Gameplay authority and chosen physics representation**.\n2. **Collision/query matrix**, shapes, scale, mass/inertia, and physical material.\n3. **Timestep/threading/substep assumptions** and failure frame-rate.\n4. **Forces, impulses, constraints, drives, fields, or fracture/cloth settings** with units/effects.\n5. **Network replication mode**, input/state ownership, correction, and latency test if multiplayer.\n6. **Performance budget** for bodies, contacts, constraints, pieces, cloth vertices, events, and traces.\n7. **Chaos Visual Debugger/Insights evidence** and acceptance checks.\n\n## Hard rules\n\n- Prefer simple primitives/convex collision for simulation; `Use Complex Collision As Simple` cannot\n  simulate the object itself.\n- Separate Query Only, Physics Only, and Query and Physics behavior deliberately.\n- Enable overlap/hit events only for consumers that need them; event generation has work and both sides'\n  response settings matter.\n- Use force for sustained acceleration and impulse for an instantaneous change. Apply at location only\n  when induced torque is intended.\n- Do not repair scale, mass, collision, or timestep errors by arbitrary extreme damping/solver values.\n- Treat UE 5.8 substepping, async substepping, and async physics settings as Experimental and test every\n  platform/gameplay dependency.\n- Physics callbacks under substepping may produce multiple ordered contact transitions in one game frame.\n- Default, Predictive Interpolation, and Resimulation solve different network problems; Resimulation is\n  more costly and the Network Physics Component requires manual C++ integration.\n- Chaos Cloth is Production Ready in UE 5.8; Chaos Caching remains Experimental.\n- Bound destruction piece/contact/event lifetime with clustering, sleep/disable/removal, and pooling.\n- Do not make authoritative damage depend on nondeterministic cosmetic debris or cloth contacts.\n- Profile the complete scene; a stable isolated asset can fail under real contact and solver load.\n\nSee [`references/sources.md`](/unreal/unreal-chaos-physics/sources/) for the UE 5.8 primary-source trail.\n","searchText":"unreal 5.8 chaos physics design, implement, tune, replicate, optimize, and debug chaos physics systems in unreal engine 5.8. use for collision channels and shapes, scene queries, rigid bodies, mass, damping, friction, restitution, ccd, forces and impulses, physics constraints and drives, substepping, async/fixed physics, networked physics replication modes and resimulation, physics assets, ragdolls, physical animation, geometry collections, fracture and clustering, chaos fields, destruction caches, chaos cloth, chaos visual debugger, unstable simulation, tunneling, jitter, explosions, or physics performance. chaos cloth chaos cloth chaos cloth is production ready in ue 5.8. prefer the chaos cloth asset/dataflow workflow for new authoring and convert legacy skeletal-mesh cloth when continued editing/round-trip needs justify it. authoring sequence 1. import/build the render and simulation meshes; keep simulation topology only as dense as deformation requires. 2. define skin weights, fixed/kinematic regions, seam/panel construction, and cloth-to-character mapping. 3. paint/author constraint masks for max distance, stiffness, damping, bending, and related properties. 4. add collision primitives/physics asset with simple, stable shapes. 5. configure gravity, wind, animation drive, self/intersection behavior, and solver iterations deliberately. 6. build cloth simulation lods and validate transition behavior. parameter directions: - more simulation vertices/iterations/collision shapes improve potential fidelity and raise cpu cost; - higher stiffness resists stretch/bend but can require finer timesteps/iterations; - damping reduces oscillation but can deaden motion; - stronger animation drive holds cloth closer to animated pose and reduces free secondary motion; - self-collision can be expensive; enable only where visible intersections justify it. test worst animation speed, teleports, spawn, lod changes, wind, frame spikes, character scaling, multiple characters, and collision extremes. reset/teleport cloth state explicitly when discontinuous movement would stretch history across the world. authoritative gameplay must not depend on cloth particle contacts. use separate collision/gameplay shapes. collision and queries collision and queries configure the matrix 1. define stable object channels for categories and trace channels for questions. 2. give each component a preset: collision enabled mode, object type, and per-channel block/overlap/ignore. 3. use query only when no solver contact is required; physics only when only simulation contacts matter; use query and physics only when both are consumed. 4. enable generate overlap events or simulation generates hit events only where the callback is needed. 5. test both participants' response rows; the interaction resolves from both settings. shape selection - sphere/capsule/box: cheapest stable approximation for many props/characters; - multiple simple primitives: preserve concavity with bounded shape count; - convex hulls: irregular simulated bodies, avoiding excessive hull detail; - complex trimesh: detailed scene queries/static collision when justified. collision complexity: | mode | behavior | |---|---| | simple and complex | simple shapes for simple queries/simulation, trimesh for complex queries | | use simple as complex | complex queries use simple shapes; saves trimesh memory/expense | | use complex as simple | simple queries/other bodies collide with trimesh; this object cannot simulate | use ccd on fast small bodies only after proving tunneling. it increases collision work and cannot repair bad collision geometry, teleportation, or an excessively large timestep. validate at gameplay scale, maximum speed, rotating thin obstacles, low frame rate, and cooked collision. constraints and drives constraints and drives build order 1. place body shapes, centers of mass, and constraint frames correctly. 2. disable collision between constrained bodies when their shapes should not fight the joint. 3. lock/free/limit x/y/z and swing1/swing2/twist to form the intended hinge, slider, ball, or fixed joint. 4. test hard limits before enabling soft limits or motors. 5. add position/orientation and velocity drives with bounded max force. 6. add break/plasticity rules only after stable normal operation. parameter effects: - higher stiffness/drive strength reaches the target harder but can oscillate or demand more solver work; - higher damping opposes target-relative velocity and reduces oscillation but can feel sluggish; - restitution adds bounce at a violated limit; - lower max force allows lag/compliance; unlimited/excess force can overpower the assembly; - slerp angular drive handles full orientation but does not work when an angular axis is locked; - twist and swing drive works with decomposed axes/locked configurations. projection is a post-solve correction. it can stiffen a chain at lower iterations but works poorly while the chain interacts with other objects and may inject nonphysical correction. shock propagation stiffens chains by increasing parent mass on the last solve iteration but can inject energy. use both as measured, bounded tools—not default fixes. validate constraint-frame alignment, extreme pose, dropped frame, contact load, break threshold, scale, and network correction. debugging and performance debugging and performance chaos visual debugger open tools -> debug -> chaos visual debugger. record local/remote pie, client/server, or packaged development/test sessions. capture only needed data channels; cvd data volume and recording overhead can be substantial. test builds may omit object debug names. inspect particles, position/velocity/mass/state, collision geometry/channels, contact constraints, joint constraints, character ground constraints, sync/async frames, and resimulated frames. save recordings for cross-team reproduction without requiring project assets. symptom matrix | symptom | inspect first | |---|---| | falls through thin wall | collision shape, speed/timestep, ccd, teleport versus sweep | | jitters at rest | penetration, shape seams, mass ratio, contact/constraint, per-frame writes | | constraint stretches/explodes | frames, limits, collision, mass ratio, timestep, drive/projection | | overlap/hit fires twice | both-side settings, substep callback queue, duplicate components | | ragdoll explodes | overlapping bodies, bad constraints, scale, pose penetration | | debris never settles | sleep thresholds, ongoing field/contact, removal policy | | network object rubber-bands | replication mode, authority, send/latency, predicted forces | | cloth stretches/explodes | teleport reset, collision penetration, timestep, stiffness/iterations | profile timing insights/stat physics plus active/dynamic/sleeping bodies, shapes, broadphase pairs, contacts, constraints/iterations, substeps, cloth vertices/iterations, destruction pieces/events, and cvd/trace overhead. disable visualization/recording for final timing. destruction, geometry collections, and fields destruction, geometry collections, and fields author a bounded collection 1. create a geometry collection from suitable source meshes in fracture mode. 2. fracture only to the piece scale visible/interactive in play. 3. cluster pieces into hierarchy levels; higher clusters simulate as fewer bodies until broken. 4. configure collision/size-specific data, damage thresholds, material interiors, and initial state. 5. anchor structural regions with construction fields or authored support. 6. trigger external strain/velocity with a bounded transient field. 7. sleep, disable, remove, or swap settled small debris according to gameplay authority. field types: - transient: execute temporary strain/force/velocity and disappear. - construction: establish initial persistent structure such as anchors. - persistent: evaluate every physics tick until removed; scope narrowly because cost persists. external strain must exceed the relevant cluster damage threshold. num strain hits can advance multiple cluster levels. sleep pieces can wake from collision; disabled pieces cannot unless explicitly activated. use field metadata/culling to restrict particle state, object type, position, and volume. unbounded persistent fields can affect unintended particles and add per-tick work. budget unbroken collections, active bodies, contacts, constraints, break events, renderer pieces, niagara/ audio callbacks, replication, and removal. cache deterministic cinematic destruction when live interaction is unnecessary; chaos caching and achaoscachemanager are experimental in ue 5.8. networked physics networked physics the server remains authoritative. select replication per actor interaction pattern: | mode | use | tradeoff | |---|---|---| | default | simple replicated simulated props with limited local interaction | legacy correction overwrites local alterations; interactions degrade | | predictive interpolation | server-authoritative props that clients predictably push/interact with | better local interaction, cheaper/less network intensive than resimulation | | resimulation | physics pawns/actors needing full local prediction and authoritative replay | input/state history, rewinds/replays, higher cpu/memory/network complexity | default mode applies velocity/correction toward the forward-predicted server state. predictive interpolation includes local velocity and correction timing so predicted interactions can survive. resimulation runs the client ahead and rewinds/replays when authoritative state diverges. for resimulation, implement the low-level network physics component in c++: 1. define serializable input and state structures. 2. capture player input at physics-step cadence. 3. apply identical deterministic-enough forces/actions during prediction and replay. 4. cache bounded history for latency/jitter budget. 5. compare authoritative state and trigger resimulation/correction through the framework. 6. separate cosmetic events from replayable authoritative effects to avoid duplicates. ue 5.8 supports predictive interpolation and resimulation simultaneously on different actors and adds networked actions. inspect np2.predictiveinterpolation, np2.resim, and p.resim console families for current tuning options rather than copying stale cvar recipes. test packet loss, jitter, latency, low send rate, high velocity, collisions between modes, ownership transfer, sleep/wake, spawn/despawn, and correction visibility. physics assets, ragdolls, and physical animation physics assets, ragdolls, and physical animation author 1. open the physics asset editor and fit minimal capsules/boxes/spheres/convex bodies to meaningful bones. 2. remove or simplify tiny bodies that do not affect collision/readability. 3. disable collision for adjacent bodies that should not contact. 4. align constraint frames at anatomical/mechanical joints. 5. set swing/twist limits from the intended range, then test animation extremes. 6. assign mass, damping, physical materials, and body/constraint profiles by gameplay state. 7. simulate in-editor with representative collision and impulses; then test in the actual character. choose the behavior - full ragdoll: transition the required bodies to simulation and define capsule/movement/camera ownership. - partial ragdoll: simulate below a bone while animation controls the rest. - physical animation component: drive simulated bodies toward animation using a named profile. - rigid body animation node: secondary physics inside the animation graph when its world/collision mode fits. blend in/out with an explicit state machine. on recovery, stop gameplay authority from reading unstable limb contacts, choose a valid get-up pose/orientation, reconcile the character capsule, and return body control in a known order. profile body/contact/constraint counts across all characters. skeletal visual lod does not automatically guarantee a cheap physics representation; use physics asset/body/constraint profiles and distance/state policy appropriate to the game. rigid bodies, forces, and sleep rigid bodies, forces, and sleep body setup - fit collision around the mass-bearing shape; remove tiny snagging features. - set density/physical material or mass in kg deliberately; inspect center of mass and inertia behavior. - use linear/angular damping for real resistive behavior, not to mask unstable contacts. - set friction/restitution through physical materials and test combined material behavior. - enable gravity, ccd, hit/wake events, and simulation only when required. apply motion | intent | use | notes | |---|---|---| | sustained thruster/wind | add force each physics/game update for duration | mass matters unless accel change | | instantaneous kick/explosion | add impulse once | mass matters unless vel change | | sustained force causing rotation | add force at location | off-center application creates torque | | instant off-center strike | add impulse at location | changes linear and angular motion | | direct kinematic placement | move/teleport/sweep policy | do not mix arbitrary transform writes with free simulation | sleep settled bodies to remove solver work. if an object wakes repeatedly, inspect contact jitter, moving supports, thresholds, tiny penetrations, constraints, and per-frame property/transform writes before forcing sleep. disabled destruction pieces cannot be collision-woken; use only when the lifecycle allows it. test mass ratios. very light bodies constrained/contacting extremely heavy bodies can destabilize stacks and joints; correct representation and scale before raising iterations or projection. ue 5.8 primary sources ue 5.8 primary sources - physics in unreal engine - collision overview - simple versus complex collision - physics bodies reference - physics constraint reference - physics sub-stepping - physics project settings - networked physics overview - physics asset editor - destruction overview - cluster geometry collections - chaos fields user guide - physics fields overview - chaos visual debugger - capturing with chaos visual debugger - clothing tool - ue 5.8 release notes - chaos caching api - add force at location - add impulse pages were checked against ue 5.8 documentation on 2026-07-19. reconfirm maturity labels, replication apis/modes, threading/timestep behavior, defaults, field nodes, and chaos caching after an engine upgrade. system selector system selector | need | prefer | |---|---| | detect without physical response | query/overlap or trace with explicit channel | | block/move kinematically | collision component + swept movement | | free simulated prop | simple/convex rigid body | | hinge, slider, tether, suspension | physics constraint component/constraint profile | | skeletal collision/ragdoll | physics asset | | animation with localized physical response | physical animation component/profile | | breakable authored object | geometry collection + clustering/fields | | region-based force/strain/state | transient/construction/persistent chaos field | | deforming garment | chaos cloth asset/solver | | repeatable cinematic heavy simulation | authored/cache playback, noting chaos caching is experimental | | server-authoritative interactive physics | predictive interpolation or resimulation by interaction needs | decision questions: 1. must the result affect authoritative movement, damage, cover, or navigation? 2. is continuous collision response required, or only a query/event? 3. what is the smallest collision representation preserving the gameplay silhouette? 4. what frame-rate/latency/piece/contact worst case must remain stable? 5. can distant/settled results sleep, disable, remove, swap representation, or play a cache? timestep, substepping, and async physics timestep, substepping, and async physics physics stability depends on maximum step size. ue's frame delta varies; large steps reduce contact and constraint accuracy. project settings -> physics exposes: | setting | effect | |---|---| | max physics delta time | caps simulated step; a lower cap may slow simulation during long frames | | substepping | divides a frame step into smaller solves; improves stability at cpu/bookkeeping cost | | max substep delta time | smaller permits finer/more steps and higher cost | | max substeps | caps catch-up work; beyond it, simulation cannot maintain the requested resolution | | tick physics async | moves simulation to async thread; experimental in ue 5.8 | | async fixed time step size | fixed async step; experimental and requires thread-safe integration | substepping, substepping async, and async physics are marked experimental in ue 5.8 project settings. do not enable them merely because an asset jitters. first correct scale, penetration, collision shape, constraint frames, mass ratios, and force application. collision callbacks are queued until the final substep and may include begin and end contact for the same pair in one game frame. make event consumers idempotent and state-based; do not award damage twice from callback multiplicity. async/fixed simulation creates a game-thread/physics-thread boundary. read/write physics state through supported apis and schedule authoritative forces/inputs at the intended physics step. test 30/60/120 fps, frame spikes, pause/time dilation, slow motion, and network resimulation. use-case recipes use-case recipes hinged door use one simulated door body plus world/frame constraint. lock linear axes; free or limit one angular axis; lock the others. add angular drive only for self-closing. limit max force so players can resist it. disable frame-door collision if shapes fight. test both push directions, edge impacts, low fps, and replication. explosive prop use a radial impulse or transient field once, not a per-frame force. keep gameplay damage authoritative and separate from debris. bound affected object types/radius, enable ccd only for fast critical fragments, and cap/sleep/disable/remove cosmetic pieces. partial hit reaction use a physics asset plus physical animation profile below the hit bone. apply a bounded impulse at the hit location, blend physics weight, then restore animation/body state. keep character movement/capsule authoritative unless the design intentionally enters ragdoll. breakable wall use clustered geometry collection, anchored supports, size-specific collision, and thresholded transient strain. break large clusters first; disable/remove settled small fragments. test worst simultaneous walls, event-driven vfx/audio, navigation/cover authority, and network representation. physics pawn use resimulation only when full predicted interaction is required; otherwise evaluate predictive interpolation. implement step-indexed inputs/state/actions in c++, keep cosmetic events replay-safe, and test latency/loss/jitter/corrections against non-player physics objects.","references":[{"slug":"cloth","file":"cloth.md","title":"Chaos Cloth","rawMarkdown":"# Chaos Cloth\n\nChaos Cloth is **Production Ready in UE 5.8**. Prefer the Chaos Cloth Asset/Dataflow workflow for new\nauthoring and convert legacy skeletal-mesh cloth when continued editing/round-trip needs justify it.\n\n## Authoring sequence\n\n1. Import/build the render and simulation meshes; keep simulation topology only as dense as deformation\n   requires.\n2. Define skin weights, fixed/kinematic regions, seam/panel construction, and cloth-to-character mapping.\n3. Paint/author constraint masks for max distance, stiffness, damping, bending, and related properties.\n4. Add collision primitives/physics asset with simple, stable shapes.\n5. Configure gravity, wind, animation drive, self/intersection behavior, and solver iterations deliberately.\n6. Build cloth simulation LODs and validate transition behavior.\n\nParameter directions:\n\n- more simulation vertices/iterations/collision shapes improve potential fidelity and raise CPU cost;\n- higher stiffness resists stretch/bend but can require finer timesteps/iterations;\n- damping reduces oscillation but can deaden motion;\n- stronger animation drive holds cloth closer to animated pose and reduces free secondary motion;\n- self-collision can be expensive; enable only where visible intersections justify it.\n\nTest worst animation speed, teleports, spawn, LOD changes, wind, frame spikes, character scaling, multiple\ncharacters, and collision extremes. Reset/teleport cloth state explicitly when discontinuous movement\nwould stretch history across the world.\n\nAuthoritative gameplay must not depend on cloth particle contacts. Use separate collision/gameplay shapes.\n","webMarkdown":"Chaos Cloth is **Production Ready in UE 5.8**. Prefer the Chaos Cloth Asset/Dataflow workflow for new\nauthoring and convert legacy skeletal-mesh cloth when continued editing/round-trip needs justify it.\n\n## Authoring sequence\n\n1. Import/build the render and simulation meshes; keep simulation topology only as dense as deformation\n   requires.\n2. Define skin weights, fixed/kinematic regions, seam/panel construction, and cloth-to-character mapping.\n3. Paint/author constraint masks for max distance, stiffness, damping, bending, and related properties.\n4. Add collision primitives/physics asset with simple, stable shapes.\n5. Configure gravity, wind, animation drive, self/intersection behavior, and solver iterations deliberately.\n6. Build cloth simulation LODs and validate transition behavior.\n\nParameter directions:\n\n- more simulation vertices/iterations/collision shapes improve potential fidelity and raise CPU cost;\n- higher stiffness resists stretch/bend but can require finer timesteps/iterations;\n- damping reduces oscillation but can deaden motion;\n- stronger animation drive holds cloth closer to animated pose and reduces free secondary motion;\n- self-collision can be expensive; enable only where visible intersections justify it.\n\nTest worst animation speed, teleports, spawn, LOD changes, wind, frame spikes, character scaling, multiple\ncharacters, and collision extremes. Reset/teleport cloth state explicitly when discontinuous movement\nwould stretch history across the world.\n\nAuthoritative gameplay must not depend on cloth particle contacts. Use separate collision/gameplay shapes.\n","searchText":"chaos cloth chaos cloth is production ready in ue 5.8. prefer the chaos cloth asset/dataflow workflow for new authoring and convert legacy skeletal-mesh cloth when continued editing/round-trip needs justify it. authoring sequence 1. import/build the render and simulation meshes; keep simulation topology only as dense as deformation requires. 2. define skin weights, fixed/kinematic regions, seam/panel construction, and cloth-to-character mapping. 3. paint/author constraint masks for max distance, stiffness, damping, bending, and related properties. 4. add collision primitives/physics asset with simple, stable shapes. 5. configure gravity, wind, animation drive, self/intersection behavior, and solver iterations deliberately. 6. build cloth simulation lods and validate transition behavior. parameter directions: - more simulation vertices/iterations/collision shapes improve potential fidelity and raise cpu cost; - higher stiffness resists stretch/bend but can require finer timesteps/iterations; - damping reduces oscillation but can deaden motion; - stronger animation drive holds cloth closer to animated pose and reduces free secondary motion; - self-collision can be expensive; enable only where visible intersections justify it. test worst animation speed, teleports, spawn, lod changes, wind, frame spikes, character scaling, multiple characters, and collision extremes. reset/teleport cloth state explicitly when discontinuous movement would stretch history across the world. authoritative gameplay must not depend on cloth particle contacts. use separate collision/gameplay shapes."},{"slug":"collision-and-queries","file":"collision-and-queries.md","title":"Collision and queries","rawMarkdown":"# Collision and queries\n\n## Configure the matrix\n\n1. Define stable Object Channels for categories and Trace Channels for questions.\n2. Give each component a preset: Collision Enabled mode, Object Type, and per-channel Block/Overlap/Ignore.\n3. Use Query Only when no solver contact is required; Physics Only when only simulation contacts matter;\n   use Query and Physics only when both are consumed.\n4. Enable Generate Overlap Events or Simulation Generates Hit Events only where the callback is needed.\n5. Test both participants' response rows; the interaction resolves from both settings.\n\n## Shape selection\n\n- sphere/capsule/box: cheapest stable approximation for many props/characters;\n- multiple simple primitives: preserve concavity with bounded shape count;\n- convex hulls: irregular simulated bodies, avoiding excessive hull detail;\n- complex trimesh: detailed scene queries/static collision when justified.\n\nCollision Complexity:\n\n| Mode | Behavior |\n|---|---|\n| Simple And Complex | simple shapes for simple queries/simulation, trimesh for complex queries |\n| Use Simple As Complex | complex queries use simple shapes; saves trimesh memory/expense |\n| Use Complex As Simple | simple queries/other bodies collide with trimesh; this object cannot simulate |\n\nUse CCD on fast small bodies only after proving tunneling. It increases collision work and cannot repair\nbad collision geometry, teleportation, or an excessively large timestep.\n\nValidate at gameplay scale, maximum speed, rotating thin obstacles, low frame rate, and cooked collision.\n","webMarkdown":"## Configure the matrix\n\n1. Define stable Object Channels for categories and Trace Channels for questions.\n2. Give each component a preset: Collision Enabled mode, Object Type, and per-channel Block/Overlap/Ignore.\n3. Use Query Only when no solver contact is required; Physics Only when only simulation contacts matter;\n   use Query and Physics only when both are consumed.\n4. Enable Generate Overlap Events or Simulation Generates Hit Events only where the callback is needed.\n5. Test both participants' response rows; the interaction resolves from both settings.\n\n## Shape selection\n\n- sphere/capsule/box: cheapest stable approximation for many props/characters;\n- multiple simple primitives: preserve concavity with bounded shape count;\n- convex hulls: irregular simulated bodies, avoiding excessive hull detail;\n- complex trimesh: detailed scene queries/static collision when justified.\n\nCollision Complexity:\n\n| Mode | Behavior |\n|---|---|\n| Simple And Complex | simple shapes for simple queries/simulation, trimesh for complex queries |\n| Use Simple As Complex | complex queries use simple shapes; saves trimesh memory/expense |\n| Use Complex As Simple | simple queries/other bodies collide with trimesh; this object cannot simulate |\n\nUse CCD on fast small bodies only after proving tunneling. It increases collision work and cannot repair\nbad collision geometry, teleportation, or an excessively large timestep.\n\nValidate at gameplay scale, maximum speed, rotating thin obstacles, low frame rate, and cooked collision.\n","searchText":"collision and queries configure the matrix 1. define stable object channels for categories and trace channels for questions. 2. give each component a preset: collision enabled mode, object type, and per-channel block/overlap/ignore. 3. use query only when no solver contact is required; physics only when only simulation contacts matter; use query and physics only when both are consumed. 4. enable generate overlap events or simulation generates hit events only where the callback is needed. 5. test both participants' response rows; the interaction resolves from both settings. shape selection - sphere/capsule/box: cheapest stable approximation for many props/characters; - multiple simple primitives: preserve concavity with bounded shape count; - convex hulls: irregular simulated bodies, avoiding excessive hull detail; - complex trimesh: detailed scene queries/static collision when justified. collision complexity: | mode | behavior | |---|---| | simple and complex | simple shapes for simple queries/simulation, trimesh for complex queries | | use simple as complex | complex queries use simple shapes; saves trimesh memory/expense | | use complex as simple | simple queries/other bodies collide with trimesh; this object cannot simulate | use ccd on fast small bodies only after proving tunneling. it increases collision work and cannot repair bad collision geometry, teleportation, or an excessively large timestep. validate at gameplay scale, maximum speed, rotating thin obstacles, low frame rate, and cooked collision."},{"slug":"constraints-and-drives","file":"constraints-and-drives.md","title":"Constraints and drives","rawMarkdown":"# Constraints and drives\n\n## Build order\n\n1. Place body shapes, centers of mass, and constraint frames correctly.\n2. Disable collision between constrained bodies when their shapes should not fight the joint.\n3. Lock/free/limit X/Y/Z and Swing1/Swing2/Twist to form the intended hinge, slider, ball, or fixed joint.\n4. Test hard limits before enabling soft limits or motors.\n5. Add position/orientation and velocity drives with bounded Max Force.\n6. Add break/plasticity rules only after stable normal operation.\n\nParameter effects:\n\n- higher stiffness/drive strength reaches the target harder but can oscillate or demand more solver work;\n- higher damping opposes target-relative velocity and reduces oscillation but can feel sluggish;\n- restitution adds bounce at a violated limit;\n- lower Max Force allows lag/compliance; unlimited/excess force can overpower the assembly;\n- SLERP angular drive handles full orientation but does not work when an angular axis is locked;\n- Twist and Swing drive works with decomposed axes/locked configurations.\n\nProjection is a post-solve correction. It can stiffen a chain at lower iterations but works poorly while\nthe chain interacts with other objects and may inject nonphysical correction. Shock Propagation stiffens\nchains by increasing parent mass on the last solve iteration but can inject energy. Use both as measured,\nbounded tools—not default fixes.\n\nValidate constraint-frame alignment, extreme pose, dropped frame, contact load, break threshold, scale,\nand network correction.\n","webMarkdown":"## Build order\n\n1. Place body shapes, centers of mass, and constraint frames correctly.\n2. Disable collision between constrained bodies when their shapes should not fight the joint.\n3. Lock/free/limit X/Y/Z and Swing1/Swing2/Twist to form the intended hinge, slider, ball, or fixed joint.\n4. Test hard limits before enabling soft limits or motors.\n5. Add position/orientation and velocity drives with bounded Max Force.\n6. Add break/plasticity rules only after stable normal operation.\n\nParameter effects:\n\n- higher stiffness/drive strength reaches the target harder but can oscillate or demand more solver work;\n- higher damping opposes target-relative velocity and reduces oscillation but can feel sluggish;\n- restitution adds bounce at a violated limit;\n- lower Max Force allows lag/compliance; unlimited/excess force can overpower the assembly;\n- SLERP angular drive handles full orientation but does not work when an angular axis is locked;\n- Twist and Swing drive works with decomposed axes/locked configurations.\n\nProjection is a post-solve correction. It can stiffen a chain at lower iterations but works poorly while\nthe chain interacts with other objects and may inject nonphysical correction. Shock Propagation stiffens\nchains by increasing parent mass on the last solve iteration but can inject energy. Use both as measured,\nbounded tools—not default fixes.\n\nValidate constraint-frame alignment, extreme pose, dropped frame, contact load, break threshold, scale,\nand network correction.\n","searchText":"constraints and drives build order 1. place body shapes, centers of mass, and constraint frames correctly. 2. disable collision between constrained bodies when their shapes should not fight the joint. 3. lock/free/limit x/y/z and swing1/swing2/twist to form the intended hinge, slider, ball, or fixed joint. 4. test hard limits before enabling soft limits or motors. 5. add position/orientation and velocity drives with bounded max force. 6. add break/plasticity rules only after stable normal operation. parameter effects: - higher stiffness/drive strength reaches the target harder but can oscillate or demand more solver work; - higher damping opposes target-relative velocity and reduces oscillation but can feel sluggish; - restitution adds bounce at a violated limit; - lower max force allows lag/compliance; unlimited/excess force can overpower the assembly; - slerp angular drive handles full orientation but does not work when an angular axis is locked; - twist and swing drive works with decomposed axes/locked configurations. projection is a post-solve correction. it can stiffen a chain at lower iterations but works poorly while the chain interacts with other objects and may inject nonphysical correction. shock propagation stiffens chains by increasing parent mass on the last solve iteration but can inject energy. use both as measured, bounded tools—not default fixes. validate constraint-frame alignment, extreme pose, dropped frame, contact load, break threshold, scale, and network correction."},{"slug":"debugging-and-performance","file":"debugging-and-performance.md","title":"Debugging and performance","rawMarkdown":"# Debugging and performance\n\n## Chaos Visual Debugger\n\nOpen Tools -> Debug -> Chaos Visual Debugger. Record local/remote PIE, client/server, or packaged\nDevelopment/Test sessions. Capture only needed data channels; CVD data volume and recording overhead can\nbe substantial. Test builds may omit object debug names.\n\nInspect particles, position/velocity/mass/state, collision geometry/channels, contact constraints, joint\nconstraints, character ground constraints, sync/async frames, and resimulated frames. Save recordings for\ncross-team reproduction without requiring project assets.\n\n## Symptom matrix\n\n| Symptom | Inspect first |\n|---|---|\n| falls through thin wall | collision shape, speed/timestep, CCD, teleport versus sweep |\n| jitters at rest | penetration, shape seams, mass ratio, contact/constraint, per-frame writes |\n| constraint stretches/explodes | frames, limits, collision, mass ratio, timestep, drive/projection |\n| overlap/hit fires twice | both-side settings, substep callback queue, duplicate components |\n| ragdoll explodes | overlapping bodies, bad constraints, scale, pose penetration |\n| debris never settles | sleep thresholds, ongoing field/contact, removal policy |\n| network object rubber-bands | replication mode, authority, send/latency, predicted forces |\n| cloth stretches/explodes | teleport reset, collision penetration, timestep, stiffness/iterations |\n\nProfile Timing Insights/`stat physics` plus active/dynamic/sleeping bodies, shapes, broadphase pairs,\ncontacts, constraints/iterations, substeps, cloth vertices/iterations, destruction pieces/events, and\nCVD/trace overhead. Disable visualization/recording for final timing.\n","webMarkdown":"## Chaos Visual Debugger\n\nOpen Tools -> Debug -> Chaos Visual Debugger. Record local/remote PIE, client/server, or packaged\nDevelopment/Test sessions. Capture only needed data channels; CVD data volume and recording overhead can\nbe substantial. Test builds may omit object debug names.\n\nInspect particles, position/velocity/mass/state, collision geometry/channels, contact constraints, joint\nconstraints, character ground constraints, sync/async frames, and resimulated frames. Save recordings for\ncross-team reproduction without requiring project assets.\n\n## Symptom matrix\n\n| Symptom | Inspect first |\n|---|---|\n| falls through thin wall | collision shape, speed/timestep, CCD, teleport versus sweep |\n| jitters at rest | penetration, shape seams, mass ratio, contact/constraint, per-frame writes |\n| constraint stretches/explodes | frames, limits, collision, mass ratio, timestep, drive/projection |\n| overlap/hit fires twice | both-side settings, substep callback queue, duplicate components |\n| ragdoll explodes | overlapping bodies, bad constraints, scale, pose penetration |\n| debris never settles | sleep thresholds, ongoing field/contact, removal policy |\n| network object rubber-bands | replication mode, authority, send/latency, predicted forces |\n| cloth stretches/explodes | teleport reset, collision penetration, timestep, stiffness/iterations |\n\nProfile Timing Insights/`stat physics` plus active/dynamic/sleeping bodies, shapes, broadphase pairs,\ncontacts, constraints/iterations, substeps, cloth vertices/iterations, destruction pieces/events, and\nCVD/trace overhead. Disable visualization/recording for final timing.\n","searchText":"debugging and performance chaos visual debugger open tools -> debug -> chaos visual debugger. record local/remote pie, client/server, or packaged development/test sessions. capture only needed data channels; cvd data volume and recording overhead can be substantial. test builds may omit object debug names. inspect particles, position/velocity/mass/state, collision geometry/channels, contact constraints, joint constraints, character ground constraints, sync/async frames, and resimulated frames. save recordings for cross-team reproduction without requiring project assets. symptom matrix | symptom | inspect first | |---|---| | falls through thin wall | collision shape, speed/timestep, ccd, teleport versus sweep | | jitters at rest | penetration, shape seams, mass ratio, contact/constraint, per-frame writes | | constraint stretches/explodes | frames, limits, collision, mass ratio, timestep, drive/projection | | overlap/hit fires twice | both-side settings, substep callback queue, duplicate components | | ragdoll explodes | overlapping bodies, bad constraints, scale, pose penetration | | debris never settles | sleep thresholds, ongoing field/contact, removal policy | | network object rubber-bands | replication mode, authority, send/latency, predicted forces | | cloth stretches/explodes | teleport reset, collision penetration, timestep, stiffness/iterations | profile timing insights/stat physics plus active/dynamic/sleeping bodies, shapes, broadphase pairs, contacts, constraints/iterations, substeps, cloth vertices/iterations, destruction pieces/events, and cvd/trace overhead. disable visualization/recording for final timing."},{"slug":"destruction-collections-and-fields","file":"destruction-collections-and-fields.md","title":"Destruction, Geometry Collections, and Fields","rawMarkdown":"# Destruction, Geometry Collections, and Fields\n\n## Author a bounded collection\n\n1. Create a Geometry Collection from suitable source meshes in Fracture Mode.\n2. Fracture only to the piece scale visible/interactive in play.\n3. Cluster pieces into hierarchy levels; higher clusters simulate as fewer bodies until broken.\n4. Configure collision/size-specific data, damage thresholds, material interiors, and initial state.\n5. Anchor structural regions with construction fields or authored support.\n6. Trigger external strain/velocity with a bounded transient field.\n7. Sleep, disable, remove, or swap settled small debris according to gameplay authority.\n\nField types:\n\n- **Transient**: execute temporary strain/force/velocity and disappear.\n- **Construction**: establish initial persistent structure such as anchors.\n- **Persistent**: evaluate every physics tick until removed; scope narrowly because cost persists.\n\nExternal Strain must exceed the relevant cluster Damage Threshold. `Num Strain Hits` can advance multiple\ncluster levels. Sleep pieces can wake from collision; Disabled pieces cannot unless explicitly activated.\n\nUse field metadata/culling to restrict particle state, object type, position, and volume. Unbounded\npersistent fields can affect unintended particles and add per-tick work.\n\nBudget unbroken collections, active bodies, contacts, constraints, break events, renderer pieces, Niagara/\naudio callbacks, replication, and removal. Cache deterministic cinematic destruction when live interaction\nis unnecessary; Chaos Caching and `AChaosCacheManager` are Experimental in UE 5.8.\n","webMarkdown":"## Author a bounded collection\n\n1. Create a Geometry Collection from suitable source meshes in Fracture Mode.\n2. Fracture only to the piece scale visible/interactive in play.\n3. Cluster pieces into hierarchy levels; higher clusters simulate as fewer bodies until broken.\n4. Configure collision/size-specific data, damage thresholds, material interiors, and initial state.\n5. Anchor structural regions with construction fields or authored support.\n6. Trigger external strain/velocity with a bounded transient field.\n7. Sleep, disable, remove, or swap settled small debris according to gameplay authority.\n\nField types:\n\n- **Transient**: execute temporary strain/force/velocity and disappear.\n- **Construction**: establish initial persistent structure such as anchors.\n- **Persistent**: evaluate every physics tick until removed; scope narrowly because cost persists.\n\nExternal Strain must exceed the relevant cluster Damage Threshold. `Num Strain Hits` can advance multiple\ncluster levels. Sleep pieces can wake from collision; Disabled pieces cannot unless explicitly activated.\n\nUse field metadata/culling to restrict particle state, object type, position, and volume. Unbounded\npersistent fields can affect unintended particles and add per-tick work.\n\nBudget unbroken collections, active bodies, contacts, constraints, break events, renderer pieces, Niagara/\naudio callbacks, replication, and removal. Cache deterministic cinematic destruction when live interaction\nis unnecessary; Chaos Caching and `AChaosCacheManager` are Experimental in UE 5.8.\n","searchText":"destruction, geometry collections, and fields author a bounded collection 1. create a geometry collection from suitable source meshes in fracture mode. 2. fracture only to the piece scale visible/interactive in play. 3. cluster pieces into hierarchy levels; higher clusters simulate as fewer bodies until broken. 4. configure collision/size-specific data, damage thresholds, material interiors, and initial state. 5. anchor structural regions with construction fields or authored support. 6. trigger external strain/velocity with a bounded transient field. 7. sleep, disable, remove, or swap settled small debris according to gameplay authority. field types: - transient: execute temporary strain/force/velocity and disappear. - construction: establish initial persistent structure such as anchors. - persistent: evaluate every physics tick until removed; scope narrowly because cost persists. external strain must exceed the relevant cluster damage threshold. num strain hits can advance multiple cluster levels. sleep pieces can wake from collision; disabled pieces cannot unless explicitly activated. use field metadata/culling to restrict particle state, object type, position, and volume. unbounded persistent fields can affect unintended particles and add per-tick work. budget unbroken collections, active bodies, contacts, constraints, break events, renderer pieces, niagara/ audio callbacks, replication, and removal. cache deterministic cinematic destruction when live interaction is unnecessary; chaos caching and achaoscachemanager are experimental in ue 5.8."},{"slug":"networked-physics","file":"networked-physics.md","title":"Networked physics","rawMarkdown":"# Networked physics\n\nThe server remains authoritative. Select replication per Actor interaction pattern:\n\n| Mode | Use | Tradeoff |\n|---|---|---|\n| Default | simple replicated simulated props with limited local interaction | legacy correction overwrites local alterations; interactions degrade |\n| Predictive Interpolation | server-authoritative props that clients predictably push/interact with | better local interaction, cheaper/less network intensive than Resimulation |\n| Resimulation | physics Pawns/Actors needing full local prediction and authoritative replay | input/state history, rewinds/replays, higher CPU/memory/network complexity |\n\nDefault mode applies velocity/correction toward the forward-predicted server state. Predictive\nInterpolation includes local velocity and correction timing so predicted interactions can survive.\nResimulation runs the client ahead and rewinds/replays when authoritative state diverges.\n\nFor Resimulation, implement the low-level Network Physics Component in C++:\n\n1. Define serializable input and state structures.\n2. Capture player input at physics-step cadence.\n3. Apply identical deterministic-enough forces/actions during prediction and replay.\n4. Cache bounded history for latency/jitter budget.\n5. Compare authoritative state and trigger resimulation/correction through the framework.\n6. Separate cosmetic events from replayable authoritative effects to avoid duplicates.\n\nUE 5.8 supports Predictive Interpolation and Resimulation simultaneously on different Actors and adds\nnetworked Actions. Inspect `np2.PredictiveInterpolation`, `np2.Resim`, and `p.Resim` console families for\ncurrent tuning options rather than copying stale CVar recipes.\n\nTest packet loss, jitter, latency, low send rate, high velocity, collisions between modes, ownership\ntransfer, sleep/wake, spawn/despawn, and correction visibility.\n","webMarkdown":"The server remains authoritative. Select replication per Actor interaction pattern:\n\n| Mode | Use | Tradeoff |\n|---|---|---|\n| Default | simple replicated simulated props with limited local interaction | legacy correction overwrites local alterations; interactions degrade |\n| Predictive Interpolation | server-authoritative props that clients predictably push/interact with | better local interaction, cheaper/less network intensive than Resimulation |\n| Resimulation | physics Pawns/Actors needing full local prediction and authoritative replay | input/state history, rewinds/replays, higher CPU/memory/network complexity |\n\nDefault mode applies velocity/correction toward the forward-predicted server state. Predictive\nInterpolation includes local velocity and correction timing so predicted interactions can survive.\nResimulation runs the client ahead and rewinds/replays when authoritative state diverges.\n\nFor Resimulation, implement the low-level Network Physics Component in C++:\n\n1. Define serializable input and state structures.\n2. Capture player input at physics-step cadence.\n3. Apply identical deterministic-enough forces/actions during prediction and replay.\n4. Cache bounded history for latency/jitter budget.\n5. Compare authoritative state and trigger resimulation/correction through the framework.\n6. Separate cosmetic events from replayable authoritative effects to avoid duplicates.\n\nUE 5.8 supports Predictive Interpolation and Resimulation simultaneously on different Actors and adds\nnetworked Actions. Inspect `np2.PredictiveInterpolation`, `np2.Resim`, and `p.Resim` console families for\ncurrent tuning options rather than copying stale CVar recipes.\n\nTest packet loss, jitter, latency, low send rate, high velocity, collisions between modes, ownership\ntransfer, sleep/wake, spawn/despawn, and correction visibility.\n","searchText":"networked physics the server remains authoritative. select replication per actor interaction pattern: | mode | use | tradeoff | |---|---|---| | default | simple replicated simulated props with limited local interaction | legacy correction overwrites local alterations; interactions degrade | | predictive interpolation | server-authoritative props that clients predictably push/interact with | better local interaction, cheaper/less network intensive than resimulation | | resimulation | physics pawns/actors needing full local prediction and authoritative replay | input/state history, rewinds/replays, higher cpu/memory/network complexity | default mode applies velocity/correction toward the forward-predicted server state. predictive interpolation includes local velocity and correction timing so predicted interactions can survive. resimulation runs the client ahead and rewinds/replays when authoritative state diverges. for resimulation, implement the low-level network physics component in c++: 1. define serializable input and state structures. 2. capture player input at physics-step cadence. 3. apply identical deterministic-enough forces/actions during prediction and replay. 4. cache bounded history for latency/jitter budget. 5. compare authoritative state and trigger resimulation/correction through the framework. 6. separate cosmetic events from replayable authoritative effects to avoid duplicates. ue 5.8 supports predictive interpolation and resimulation simultaneously on different actors and adds networked actions. inspect np2.predictiveinterpolation, np2.resim, and p.resim console families for current tuning options rather than copying stale cvar recipes. test packet loss, jitter, latency, low send rate, high velocity, collisions between modes, ownership transfer, sleep/wake, spawn/despawn, and correction visibility."},{"slug":"physics-assets-and-ragdolls","file":"physics-assets-and-ragdolls.md","title":"Physics Assets, ragdolls, and physical animation","rawMarkdown":"# Physics Assets, ragdolls, and physical animation\n\n## Author\n\n1. Open the Physics Asset Editor and fit minimal capsules/boxes/spheres/convex bodies to meaningful bones.\n2. Remove or simplify tiny bodies that do not affect collision/readability.\n3. Disable collision for adjacent bodies that should not contact.\n4. Align constraint frames at anatomical/mechanical joints.\n5. Set Swing/Twist limits from the intended range, then test animation extremes.\n6. Assign mass, damping, physical materials, and body/constraint profiles by gameplay state.\n7. Simulate in-editor with representative collision and impulses; then test in the actual character.\n\n## Choose the behavior\n\n- Full ragdoll: transition the required bodies to simulation and define capsule/movement/camera ownership.\n- Partial ragdoll: simulate below a bone while animation controls the rest.\n- Physical Animation Component: drive simulated bodies toward animation using a named profile.\n- Rigid Body animation node: secondary physics inside the animation graph when its world/collision mode fits.\n\nBlend in/out with an explicit state machine. On recovery, stop gameplay authority from reading unstable\nlimb contacts, choose a valid get-up pose/orientation, reconcile the character capsule, and return body\ncontrol in a known order.\n\nProfile body/contact/constraint counts across all characters. Skeletal visual LOD does not automatically\nguarantee a cheap physics representation; use Physics Asset/body/constraint profiles and distance/state\npolicy appropriate to the game.\n","webMarkdown":"## Author\n\n1. Open the Physics Asset Editor and fit minimal capsules/boxes/spheres/convex bodies to meaningful bones.\n2. Remove or simplify tiny bodies that do not affect collision/readability.\n3. Disable collision for adjacent bodies that should not contact.\n4. Align constraint frames at anatomical/mechanical joints.\n5. Set Swing/Twist limits from the intended range, then test animation extremes.\n6. Assign mass, damping, physical materials, and body/constraint profiles by gameplay state.\n7. Simulate in-editor with representative collision and impulses; then test in the actual character.\n\n## Choose the behavior\n\n- Full ragdoll: transition the required bodies to simulation and define capsule/movement/camera ownership.\n- Partial ragdoll: simulate below a bone while animation controls the rest.\n- Physical Animation Component: drive simulated bodies toward animation using a named profile.\n- Rigid Body animation node: secondary physics inside the animation graph when its world/collision mode fits.\n\nBlend in/out with an explicit state machine. On recovery, stop gameplay authority from reading unstable\nlimb contacts, choose a valid get-up pose/orientation, reconcile the character capsule, and return body\ncontrol in a known order.\n\nProfile body/contact/constraint counts across all characters. Skeletal visual LOD does not automatically\nguarantee a cheap physics representation; use Physics Asset/body/constraint profiles and distance/state\npolicy appropriate to the game.\n","searchText":"physics assets, ragdolls, and physical animation author 1. open the physics asset editor and fit minimal capsules/boxes/spheres/convex bodies to meaningful bones. 2. remove or simplify tiny bodies that do not affect collision/readability. 3. disable collision for adjacent bodies that should not contact. 4. align constraint frames at anatomical/mechanical joints. 5. set swing/twist limits from the intended range, then test animation extremes. 6. assign mass, damping, physical materials, and body/constraint profiles by gameplay state. 7. simulate in-editor with representative collision and impulses; then test in the actual character. choose the behavior - full ragdoll: transition the required bodies to simulation and define capsule/movement/camera ownership. - partial ragdoll: simulate below a bone while animation controls the rest. - physical animation component: drive simulated bodies toward animation using a named profile. - rigid body animation node: secondary physics inside the animation graph when its world/collision mode fits. blend in/out with an explicit state machine. on recovery, stop gameplay authority from reading unstable limb contacts, choose a valid get-up pose/orientation, reconcile the character capsule, and return body control in a known order. profile body/contact/constraint counts across all characters. skeletal visual lod does not automatically guarantee a cheap physics representation; use physics asset/body/constraint profiles and distance/state policy appropriate to the game."},{"slug":"rigid-bodies-forces-and-sleep","file":"rigid-bodies-forces-and-sleep.md","title":"Rigid bodies, forces, and sleep","rawMarkdown":"# Rigid bodies, forces, and sleep\n\n## Body setup\n\n- Fit collision around the mass-bearing shape; remove tiny snagging features.\n- Set density/physical material or Mass in KG deliberately; inspect center of mass and inertia behavior.\n- Use Linear/Angular Damping for real resistive behavior, not to mask unstable contacts.\n- Set friction/restitution through Physical Materials and test combined material behavior.\n- Enable gravity, CCD, hit/wake events, and simulation only when required.\n\n## Apply motion\n\n| Intent | Use | Notes |\n|---|---|---|\n| sustained thruster/wind | Add Force each physics/game update for duration | mass matters unless Accel Change |\n| instantaneous kick/explosion | Add Impulse once | mass matters unless Vel Change |\n| sustained force causing rotation | Add Force at Location | off-center application creates torque |\n| instant off-center strike | Add Impulse at Location | changes linear and angular motion |\n| direct kinematic placement | move/teleport/sweep policy | do not mix arbitrary transform writes with free simulation |\n\nSleep settled bodies to remove solver work. If an object wakes repeatedly, inspect contact jitter, moving\nsupports, thresholds, tiny penetrations, constraints, and per-frame property/transform writes before\nforcing sleep. Disabled destruction pieces cannot be collision-woken; use only when the lifecycle allows it.\n\nTest mass ratios. Very light bodies constrained/contacting extremely heavy bodies can destabilize stacks\nand joints; correct representation and scale before raising iterations or projection.\n","webMarkdown":"## Body setup\n\n- Fit collision around the mass-bearing shape; remove tiny snagging features.\n- Set density/physical material or Mass in KG deliberately; inspect center of mass and inertia behavior.\n- Use Linear/Angular Damping for real resistive behavior, not to mask unstable contacts.\n- Set friction/restitution through Physical Materials and test combined material behavior.\n- Enable gravity, CCD, hit/wake events, and simulation only when required.\n\n## Apply motion\n\n| Intent | Use | Notes |\n|---|---|---|\n| sustained thruster/wind | Add Force each physics/game update for duration | mass matters unless Accel Change |\n| instantaneous kick/explosion | Add Impulse once | mass matters unless Vel Change |\n| sustained force causing rotation | Add Force at Location | off-center application creates torque |\n| instant off-center strike | Add Impulse at Location | changes linear and angular motion |\n| direct kinematic placement | move/teleport/sweep policy | do not mix arbitrary transform writes with free simulation |\n\nSleep settled bodies to remove solver work. If an object wakes repeatedly, inspect contact jitter, moving\nsupports, thresholds, tiny penetrations, constraints, and per-frame property/transform writes before\nforcing sleep. Disabled destruction pieces cannot be collision-woken; use only when the lifecycle allows it.\n\nTest mass ratios. Very light bodies constrained/contacting extremely heavy bodies can destabilize stacks\nand joints; correct representation and scale before raising iterations or projection.\n","searchText":"rigid bodies, forces, and sleep body setup - fit collision around the mass-bearing shape; remove tiny snagging features. - set density/physical material or mass in kg deliberately; inspect center of mass and inertia behavior. - use linear/angular damping for real resistive behavior, not to mask unstable contacts. - set friction/restitution through physical materials and test combined material behavior. - enable gravity, ccd, hit/wake events, and simulation only when required. apply motion | intent | use | notes | |---|---|---| | sustained thruster/wind | add force each physics/game update for duration | mass matters unless accel change | | instantaneous kick/explosion | add impulse once | mass matters unless vel change | | sustained force causing rotation | add force at location | off-center application creates torque | | instant off-center strike | add impulse at location | changes linear and angular motion | | direct kinematic placement | move/teleport/sweep policy | do not mix arbitrary transform writes with free simulation | sleep settled bodies to remove solver work. if an object wakes repeatedly, inspect contact jitter, moving supports, thresholds, tiny penetrations, constraints, and per-frame property/transform writes before forcing sleep. disabled destruction pieces cannot be collision-woken; use only when the lifecycle allows it. test mass ratios. very light bodies constrained/contacting extremely heavy bodies can destabilize stacks and joints; correct representation and scale before raising iterations or projection."},{"slug":"sources","file":"sources.md","title":"UE 5.8 primary sources","rawMarkdown":"# UE 5.8 primary sources\n\n- [Physics in Unreal Engine](https://dev.epicgames.com/documentation/en-us/unreal-engine/physics-in-unreal-engine)\n- [Collision Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/collision-in-unreal-engine---overview)\n- [Simple versus Complex Collision](https://dev.epicgames.com/documentation/en-us/unreal-engine/simple-versus-complex-collision-in-unreal-engine)\n- [Physics Bodies Reference](https://dev.epicgames.com/documentation/en-us/unreal-engine/physics-bodies-reference-for-unreal-engine)\n- [Physics Constraint Reference](https://dev.epicgames.com/documentation/en-us/unreal-engine/physics-constraint-reference-in-unreal-engine)\n- [Physics Sub-Stepping](https://dev.epicgames.com/documentation/en-us/unreal-engine/physics-sub-stepping-in-unreal-engine)\n- [Physics Project Settings](https://dev.epicgames.com/documentation/en-us/unreal-engine/physics-settings-in-the-unreal-engine-project-settings)\n- [Networked Physics Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/networked-physics-overview)\n- [Physics Asset Editor](https://dev.epicgames.com/documentation/en-us/unreal-engine/physics-asset-editor-in-unreal-engine)\n- [Destruction Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/destruction-overview)\n- [Cluster Geometry Collections](https://dev.epicgames.com/documentation/en-us/unreal-engine/cluster-geometry-collections-user-guide-in-unreal-engine)\n- [Chaos Fields User Guide](https://dev.epicgames.com/documentation/en-us/unreal-engine/chaos-fields-user-guide-in-unreal-engine)\n- [Physics Fields Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/overview-of-physics-fields-in-unreal-engine)\n- [Chaos Visual Debugger](https://dev.epicgames.com/documentation/en-us/unreal-engine/getting-started-with-chaos-visual-debugger)\n- [Capturing with Chaos Visual Debugger](https://dev.epicgames.com/documentation/en-us/unreal-engine/capturing-data-with-chaos-visual-debugger)\n- [Clothing Tool](https://dev.epicgames.com/documentation/en-us/unreal-engine/clothing-tool-in-unreal-engine)\n- [UE 5.8 Release Notes](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-8-release-notes)\n- [Chaos Caching API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/ChaosCaching)\n- [Add Force at Location](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/Physics/AddForceatLocation)\n- [Add Impulse](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/Physics/AddImpulse)\n\nPages were checked against UE 5.8 documentation on 2026-07-19. Reconfirm maturity labels, replication\nAPIs/modes, threading/timestep behavior, defaults, field nodes, and Chaos caching after an engine upgrade.\n","webMarkdown":"- [Physics in Unreal Engine](https://dev.epicgames.com/documentation/en-us/unreal-engine/physics-in-unreal-engine)\n- [Collision Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/collision-in-unreal-engine---overview)\n- [Simple versus Complex Collision](https://dev.epicgames.com/documentation/en-us/unreal-engine/simple-versus-complex-collision-in-unreal-engine)\n- [Physics Bodies Reference](https://dev.epicgames.com/documentation/en-us/unreal-engine/physics-bodies-reference-for-unreal-engine)\n- [Physics Constraint Reference](https://dev.epicgames.com/documentation/en-us/unreal-engine/physics-constraint-reference-in-unreal-engine)\n- [Physics Sub-Stepping](https://dev.epicgames.com/documentation/en-us/unreal-engine/physics-sub-stepping-in-unreal-engine)\n- [Physics Project Settings](https://dev.epicgames.com/documentation/en-us/unreal-engine/physics-settings-in-the-unreal-engine-project-settings)\n- [Networked Physics Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/networked-physics-overview)\n- [Physics Asset Editor](https://dev.epicgames.com/documentation/en-us/unreal-engine/physics-asset-editor-in-unreal-engine)\n- [Destruction Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/destruction-overview)\n- [Cluster Geometry Collections](https://dev.epicgames.com/documentation/en-us/unreal-engine/cluster-geometry-collections-user-guide-in-unreal-engine)\n- [Chaos Fields User Guide](https://dev.epicgames.com/documentation/en-us/unreal-engine/chaos-fields-user-guide-in-unreal-engine)\n- [Physics Fields Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/overview-of-physics-fields-in-unreal-engine)\n- [Chaos Visual Debugger](https://dev.epicgames.com/documentation/en-us/unreal-engine/getting-started-with-chaos-visual-debugger)\n- [Capturing with Chaos Visual Debugger](https://dev.epicgames.com/documentation/en-us/unreal-engine/capturing-data-with-chaos-visual-debugger)\n- [Clothing Tool](https://dev.epicgames.com/documentation/en-us/unreal-engine/clothing-tool-in-unreal-engine)\n- [UE 5.8 Release Notes](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-8-release-notes)\n- [Chaos Caching API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/ChaosCaching)\n- [Add Force at Location](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/Physics/AddForceatLocation)\n- [Add Impulse](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/Physics/AddImpulse)\n\nPages were checked against UE 5.8 documentation on 2026-07-19. Reconfirm maturity labels, replication\nAPIs/modes, threading/timestep behavior, defaults, field nodes, and Chaos caching after an engine upgrade.\n","searchText":"ue 5.8 primary sources - physics in unreal engine - collision overview - simple versus complex collision - physics bodies reference - physics constraint reference - physics sub-stepping - physics project settings - networked physics overview - physics asset editor - destruction overview - cluster geometry collections - chaos fields user guide - physics fields overview - chaos visual debugger - capturing with chaos visual debugger - clothing tool - ue 5.8 release notes - chaos caching api - add force at location - add impulse pages were checked against ue 5.8 documentation on 2026-07-19. reconfirm maturity labels, replication apis/modes, threading/timestep behavior, defaults, field nodes, and chaos caching after an engine upgrade."},{"slug":"system-selector","file":"system-selector.md","title":"System selector","rawMarkdown":"# System selector\n\n| Need | Prefer |\n|---|---|\n| detect without physical response | query/overlap or trace with explicit channel |\n| block/move kinematically | collision component + swept movement |\n| free simulated prop | simple/convex rigid body |\n| hinge, slider, tether, suspension | Physics Constraint Component/constraint profile |\n| skeletal collision/ragdoll | Physics Asset |\n| animation with localized physical response | Physical Animation Component/profile |\n| breakable authored object | Geometry Collection + clustering/fields |\n| region-based force/strain/state | transient/construction/persistent Chaos Field |\n| deforming garment | Chaos Cloth Asset/solver |\n| repeatable cinematic heavy simulation | authored/cache playback, noting Chaos Caching is Experimental |\n| server-authoritative interactive physics | Predictive Interpolation or Resimulation by interaction needs |\n\nDecision questions:\n\n1. Must the result affect authoritative movement, damage, cover, or navigation?\n2. Is continuous collision response required, or only a query/event?\n3. What is the smallest collision representation preserving the gameplay silhouette?\n4. What frame-rate/latency/piece/contact worst case must remain stable?\n5. Can distant/settled results sleep, disable, remove, swap representation, or play a cache?\n","webMarkdown":"| Need | Prefer |\n|---|---|\n| detect without physical response | query/overlap or trace with explicit channel |\n| block/move kinematically | collision component + swept movement |\n| free simulated prop | simple/convex rigid body |\n| hinge, slider, tether, suspension | Physics Constraint Component/constraint profile |\n| skeletal collision/ragdoll | Physics Asset |\n| animation with localized physical response | Physical Animation Component/profile |\n| breakable authored object | Geometry Collection + clustering/fields |\n| region-based force/strain/state | transient/construction/persistent Chaos Field |\n| deforming garment | Chaos Cloth Asset/solver |\n| repeatable cinematic heavy simulation | authored/cache playback, noting Chaos Caching is Experimental |\n| server-authoritative interactive physics | Predictive Interpolation or Resimulation by interaction needs |\n\nDecision questions:\n\n1. Must the result affect authoritative movement, damage, cover, or navigation?\n2. Is continuous collision response required, or only a query/event?\n3. What is the smallest collision representation preserving the gameplay silhouette?\n4. What frame-rate/latency/piece/contact worst case must remain stable?\n5. Can distant/settled results sleep, disable, remove, swap representation, or play a cache?\n","searchText":"system selector | need | prefer | |---|---| | detect without physical response | query/overlap or trace with explicit channel | | block/move kinematically | collision component + swept movement | | free simulated prop | simple/convex rigid body | | hinge, slider, tether, suspension | physics constraint component/constraint profile | | skeletal collision/ragdoll | physics asset | | animation with localized physical response | physical animation component/profile | | breakable authored object | geometry collection + clustering/fields | | region-based force/strain/state | transient/construction/persistent chaos field | | deforming garment | chaos cloth asset/solver | | repeatable cinematic heavy simulation | authored/cache playback, noting chaos caching is experimental | | server-authoritative interactive physics | predictive interpolation or resimulation by interaction needs | decision questions: 1. must the result affect authoritative movement, damage, cover, or navigation? 2. is continuous collision response required, or only a query/event? 3. what is the smallest collision representation preserving the gameplay silhouette? 4. what frame-rate/latency/piece/contact worst case must remain stable? 5. can distant/settled results sleep, disable, remove, swap representation, or play a cache?"},{"slug":"timestep-substepping-and-async","file":"timestep-substepping-and-async.md","title":"Timestep, substepping, and async physics","rawMarkdown":"# Timestep, substepping, and async physics\n\nPhysics stability depends on maximum step size. UE's frame delta varies; large steps reduce contact and\nconstraint accuracy.\n\nProject Settings -> Physics exposes:\n\n| Setting | Effect |\n|---|---|\n| Max Physics Delta Time | caps simulated step; a lower cap may slow simulation during long frames |\n| Substepping | divides a frame step into smaller solves; improves stability at CPU/bookkeeping cost |\n| Max Substep Delta Time | smaller permits finer/more steps and higher cost |\n| Max Substeps | caps catch-up work; beyond it, simulation cannot maintain the requested resolution |\n| Tick Physics Async | moves simulation to async thread; Experimental in UE 5.8 |\n| Async Fixed Time Step Size | fixed async step; Experimental and requires thread-safe integration |\n\nSubstepping, Substepping Async, and async physics are marked Experimental in UE 5.8 Project Settings.\nDo not enable them merely because an asset jitters. First correct scale, penetration, collision shape,\nconstraint frames, mass ratios, and force application.\n\nCollision callbacks are queued until the final substep and may include begin and end contact for the same\npair in one game frame. Make event consumers idempotent and state-based; do not award damage twice from\ncallback multiplicity.\n\nAsync/fixed simulation creates a game-thread/physics-thread boundary. Read/write physics state through\nsupported APIs and schedule authoritative forces/inputs at the intended physics step. Test 30/60/120 fps,\nframe spikes, pause/time dilation, slow motion, and network resimulation.\n","webMarkdown":"Physics stability depends on maximum step size. UE's frame delta varies; large steps reduce contact and\nconstraint accuracy.\n\nProject Settings -> Physics exposes:\n\n| Setting | Effect |\n|---|---|\n| Max Physics Delta Time | caps simulated step; a lower cap may slow simulation during long frames |\n| Substepping | divides a frame step into smaller solves; improves stability at CPU/bookkeeping cost |\n| Max Substep Delta Time | smaller permits finer/more steps and higher cost |\n| Max Substeps | caps catch-up work; beyond it, simulation cannot maintain the requested resolution |\n| Tick Physics Async | moves simulation to async thread; Experimental in UE 5.8 |\n| Async Fixed Time Step Size | fixed async step; Experimental and requires thread-safe integration |\n\nSubstepping, Substepping Async, and async physics are marked Experimental in UE 5.8 Project Settings.\nDo not enable them merely because an asset jitters. First correct scale, penetration, collision shape,\nconstraint frames, mass ratios, and force application.\n\nCollision callbacks are queued until the final substep and may include begin and end contact for the same\npair in one game frame. Make event consumers idempotent and state-based; do not award damage twice from\ncallback multiplicity.\n\nAsync/fixed simulation creates a game-thread/physics-thread boundary. Read/write physics state through\nsupported APIs and schedule authoritative forces/inputs at the intended physics step. Test 30/60/120 fps,\nframe spikes, pause/time dilation, slow motion, and network resimulation.\n","searchText":"timestep, substepping, and async physics physics stability depends on maximum step size. ue's frame delta varies; large steps reduce contact and constraint accuracy. project settings -> physics exposes: | setting | effect | |---|---| | max physics delta time | caps simulated step; a lower cap may slow simulation during long frames | | substepping | divides a frame step into smaller solves; improves stability at cpu/bookkeeping cost | | max substep delta time | smaller permits finer/more steps and higher cost | | max substeps | caps catch-up work; beyond it, simulation cannot maintain the requested resolution | | tick physics async | moves simulation to async thread; experimental in ue 5.8 | | async fixed time step size | fixed async step; experimental and requires thread-safe integration | substepping, substepping async, and async physics are marked experimental in ue 5.8 project settings. do not enable them merely because an asset jitters. first correct scale, penetration, collision shape, constraint frames, mass ratios, and force application. collision callbacks are queued until the final substep and may include begin and end contact for the same pair in one game frame. make event consumers idempotent and state-based; do not award damage twice from callback multiplicity. async/fixed simulation creates a game-thread/physics-thread boundary. read/write physics state through supported apis and schedule authoritative forces/inputs at the intended physics step. test 30/60/120 fps, frame spikes, pause/time dilation, slow motion, and network resimulation."},{"slug":"use-case-recipes","file":"use-case-recipes.md","title":"Use-case recipes","rawMarkdown":"# Use-case recipes\n\n## Hinged door\n\nUse one simulated door body plus world/frame constraint. Lock linear axes; free or limit one angular axis;\nlock the others. Add angular drive only for self-closing. Limit Max Force so players can resist it. Disable\nframe-door collision if shapes fight. Test both push directions, edge impacts, low FPS, and replication.\n\n## Explosive prop\n\nUse a radial impulse or transient field once, not a per-frame force. Keep gameplay damage authoritative and\nseparate from debris. Bound affected object types/radius, enable CCD only for fast critical fragments, and\ncap/sleep/disable/remove cosmetic pieces.\n\n## Partial hit reaction\n\nUse a Physics Asset plus Physical Animation profile below the hit bone. Apply a bounded impulse at the hit\nlocation, blend physics weight, then restore animation/body state. Keep character movement/capsule\nauthoritative unless the design intentionally enters ragdoll.\n\n## Breakable wall\n\nUse clustered Geometry Collection, anchored supports, size-specific collision, and thresholded transient\nstrain. Break large clusters first; disable/remove settled small fragments. Test worst simultaneous walls,\nevent-driven VFX/audio, navigation/cover authority, and network representation.\n\n## Physics Pawn\n\nUse Resimulation only when full predicted interaction is required; otherwise evaluate Predictive\nInterpolation. Implement step-indexed inputs/state/actions in C++, keep cosmetic events replay-safe, and\ntest latency/loss/jitter/corrections against non-player physics objects.\n","webMarkdown":"## Hinged door\n\nUse one simulated door body plus world/frame constraint. Lock linear axes; free or limit one angular axis;\nlock the others. Add angular drive only for self-closing. Limit Max Force so players can resist it. Disable\nframe-door collision if shapes fight. Test both push directions, edge impacts, low FPS, and replication.\n\n## Explosive prop\n\nUse a radial impulse or transient field once, not a per-frame force. Keep gameplay damage authoritative and\nseparate from debris. Bound affected object types/radius, enable CCD only for fast critical fragments, and\ncap/sleep/disable/remove cosmetic pieces.\n\n## Partial hit reaction\n\nUse a Physics Asset plus Physical Animation profile below the hit bone. Apply a bounded impulse at the hit\nlocation, blend physics weight, then restore animation/body state. Keep character movement/capsule\nauthoritative unless the design intentionally enters ragdoll.\n\n## Breakable wall\n\nUse clustered Geometry Collection, anchored supports, size-specific collision, and thresholded transient\nstrain. Break large clusters first; disable/remove settled small fragments. Test worst simultaneous walls,\nevent-driven VFX/audio, navigation/cover authority, and network representation.\n\n## Physics Pawn\n\nUse Resimulation only when full predicted interaction is required; otherwise evaluate Predictive\nInterpolation. Implement step-indexed inputs/state/actions in C++, keep cosmetic events replay-safe, and\ntest latency/loss/jitter/corrections against non-player physics objects.\n","searchText":"use-case recipes hinged door use one simulated door body plus world/frame constraint. lock linear axes; free or limit one angular axis; lock the others. add angular drive only for self-closing. limit max force so players can resist it. disable frame-door collision if shapes fight. test both push directions, edge impacts, low fps, and replication. explosive prop use a radial impulse or transient field once, not a per-frame force. keep gameplay damage authoritative and separate from debris. bound affected object types/radius, enable ccd only for fast critical fragments, and cap/sleep/disable/remove cosmetic pieces. partial hit reaction use a physics asset plus physical animation profile below the hit bone. apply a bounded impulse at the hit location, blend physics weight, then restore animation/body state. keep character movement/capsule authoritative unless the design intentionally enters ragdoll. breakable wall use clustered geometry collection, anchored supports, size-specific collision, and thresholded transient strain. break large clusters first; disable/remove settled small fragments. test worst simultaneous walls, event-driven vfx/audio, navigation/cover authority, and network representation. physics pawn use resimulation only when full predicted interaction is required; otherwise evaluate predictive interpolation. implement step-indexed inputs/state/actions in c++, keep cosmetic events replay-safe, and test latency/loss/jitter/corrections against non-player physics objects."}]}
{"slug":"unreal-character-movement","name":"unreal-character-movement","title":"Unreal 5.8 Character Movement","description":"Design, tune, extend, network, and debug Character movement in Unreal Engine 5.8. Use for Character Movement Component selection, movement feel, walking, acceleration, braking, friction, rotation, jumping, gravity, air control, slopes, steps, crouching, moving platforms, custom movement modes, dashes, launches, teleports, root motion sources, client prediction, saved moves, corrections, smoothing, or evaluating experimental Mover.","shortDescription":"Tune and network Character Movement systems","category":"Gameplay","referenceCount":8,"rawMarkdown":"---\nname: unreal-character-movement\ndescription: Design, tune, extend, network, and debug Character movement in Unreal Engine 5.8. Use for Character Movement Component selection, movement feel, walking, acceleration, braking, friction, rotation, jumping, gravity, air control, slopes, steps, crouching, moving platforms, custom movement modes, dashes, launches, teleports, root motion sources, client prediction, saved moves, corrections, smoothing, or evaluating experimental Mover.\n---\n\n# Unreal 5.8 Character Movement\n\n## Select the movement framework\n\n- Use `ACharacter` with `UCharacterMovementComponent` for standard capsule-based walking,\n  falling, swimming, flying, crouching, root motion, and mature network prediction.\n- Extend CMC with `MOVE_Custom` when one or more special modes must coexist with standard\n  Character movement and its networking model.\n- Use Root Motion Sources or GAS root-motion Ability Tasks for short, programmatic special\n  moves that must participate in Character network prediction.\n- Evaluate **Mover** only when its mode/layered-move architecture materially benefits the\n  project. In UE 5.8 Epic still labels Mover Experimental; record that shipping risk.\n- Use a bespoke Pawn movement component only when Character's capsule/mode model is a poor fit.\n\nRead [`references/system-selector.md`](references/system-selector.md) before choosing.\n\n## Tune in dependency order\n\n1. Declare desired feel in measurable terms: target speed, time to speed, stopping distance,\n   turn time, jump height/time, air steering, walkable slope, and step height.\n2. Establish collision capsule and floor behavior.\n3. Tune `MaxWalkSpeed`, `MaxAcceleration`, braking, and friction together.\n4. Select rotation ownership: movement direction, controller desired rotation, or explicit\n   gameplay rotation. Avoid competing rotation systems.\n5. Tune `JumpZVelocity`, gravity, hold behavior, and `AirControl` as one jump model.\n6. Add crouch, sprint, slopes, platforms, and special movement one at a time.\n7. Integrate animation after the physical trajectory is stable.\n8. Verify at varied frame rate, target hardware, slopes/steps/edges, and network conditions.\n\nRead [`references/parameter-effects.md`](references/parameter-effects.md) for variable effects\nand [`references/grounding-jumping.md`](references/grounding-jumping.md) for ground and jump\nprocedures.\n\n## Network before polishing\n\nRead [`references/networking.md`](references/networking.md) before adding replicated special\nmovement. Standard CMC prediction does not automatically serialize arbitrary custom state.\nExtend saved moves/network move data when the server must reproduce new input or state.\n\nRead [`references/special-movement.md`](references/special-movement.md) for dashes, launches,\nteleports, custom modes, and root motion. Route action timing/input buffers to\n`$unreal-enhanced-input`, action animation blending to `$unreal-animation-blending`, and\nability-owned movement to `$unreal-gas-abilities`.\n\n## Required answer format\n\nReturn:\n\n1. **Movement framework choice** and maturity risk.\n2. **Desired feel metrics** and assumptions.\n3. **Ordered parameter changes**, units, expected effects, and interactions.\n4. **Movement/rotation/animation ownership**.\n5. **Authority, prediction, saved-move, and smoothing design**.\n6. **Test course and network verification matrix**.\n\nDo not invent defaults, property names, prediction behavior, or safe values.\n\n## Hard rules\n\n- Tune coupled parameters together; speed alone does not define feel.\n- Do not drive one movement simultaneously through CMC velocity, manual transforms, and root\n  motion.\n- Do not use client `SetActorLocation` as predicted multiplayer movement.\n- Teleport on the server and mark the move as a teleport through the supported API path.\n- Do not disable server corrections to hide a faulty movement implementation.\n- Keep the collision capsule authoritative; mesh offset is presentation.\n- Test custom movement with latency, packet loss, low frame rate, slopes, edges, and moving bases.\n\nUse [`references/troubleshooting.md`](references/troubleshooting.md) for sliding, jitter,\ncorrections, slope/step failures, root-motion conflicts, and frame-rate dependence. See\n[`references/sources.md`](references/sources.md) for the UE 5.8 source trail.\n","webMarkdown":"## Select the movement framework\n\n- Use `ACharacter` with `UCharacterMovementComponent` for standard capsule-based walking,\n  falling, swimming, flying, crouching, root motion, and mature network prediction.\n- Extend CMC with `MOVE_Custom` when one or more special modes must coexist with standard\n  Character movement and its networking model.\n- Use Root Motion Sources or GAS root-motion Ability Tasks for short, programmatic special\n  moves that must participate in Character network prediction.\n- Evaluate **Mover** only when its mode/layered-move architecture materially benefits the\n  project. In UE 5.8 Epic still labels Mover Experimental; record that shipping risk.\n- Use a bespoke Pawn movement component only when Character's capsule/mode model is a poor fit.\n\nRead [`references/system-selector.md`](/unreal/unreal-character-movement/system-selector/) before choosing.\n\n## Tune in dependency order\n\n1. Declare desired feel in measurable terms: target speed, time to speed, stopping distance,\n   turn time, jump height/time, air steering, walkable slope, and step height.\n2. Establish collision capsule and floor behavior.\n3. Tune `MaxWalkSpeed`, `MaxAcceleration`, braking, and friction together.\n4. Select rotation ownership: movement direction, controller desired rotation, or explicit\n   gameplay rotation. Avoid competing rotation systems.\n5. Tune `JumpZVelocity`, gravity, hold behavior, and `AirControl` as one jump model.\n6. Add crouch, sprint, slopes, platforms, and special movement one at a time.\n7. Integrate animation after the physical trajectory is stable.\n8. Verify at varied frame rate, target hardware, slopes/steps/edges, and network conditions.\n\nRead [`references/parameter-effects.md`](/unreal/unreal-character-movement/parameter-effects/) for variable effects\nand [`references/grounding-jumping.md`](/unreal/unreal-character-movement/grounding-jumping/) for ground and jump\nprocedures.\n\n## Network before polishing\n\nRead [`references/networking.md`](/unreal/unreal-character-movement/networking/) before adding replicated special\nmovement. Standard CMC prediction does not automatically serialize arbitrary custom state.\nExtend saved moves/network move data when the server must reproduce new input or state.\n\nRead [`references/special-movement.md`](/unreal/unreal-character-movement/special-movement/) for dashes, launches,\nteleports, custom modes, and root motion. Route action timing/input buffers to\n`$unreal-enhanced-input`, action animation blending to `$unreal-animation-blending`, and\nability-owned movement to `$unreal-gas-abilities`.\n\n## Required answer format\n\nReturn:\n\n1. **Movement framework choice** and maturity risk.\n2. **Desired feel metrics** and assumptions.\n3. **Ordered parameter changes**, units, expected effects, and interactions.\n4. **Movement/rotation/animation ownership**.\n5. **Authority, prediction, saved-move, and smoothing design**.\n6. **Test course and network verification matrix**.\n\nDo not invent defaults, property names, prediction behavior, or safe values.\n\n## Hard rules\n\n- Tune coupled parameters together; speed alone does not define feel.\n- Do not drive one movement simultaneously through CMC velocity, manual transforms, and root\n  motion.\n- Do not use client `SetActorLocation` as predicted multiplayer movement.\n- Teleport on the server and mark the move as a teleport through the supported API path.\n- Do not disable server corrections to hide a faulty movement implementation.\n- Keep the collision capsule authoritative; mesh offset is presentation.\n- Test custom movement with latency, packet loss, low frame rate, slopes, edges, and moving bases.\n\nUse [`references/troubleshooting.md`](/unreal/unreal-character-movement/troubleshooting/) for sliding, jitter,\ncorrections, slope/step failures, root-motion conflicts, and frame-rate dependence. See\n[`references/sources.md`](/unreal/unreal-character-movement/sources/) for the UE 5.8 source trail.\n","searchText":"unreal 5.8 character movement design, tune, extend, network, and debug character movement in unreal engine 5.8. use for character movement component selection, movement feel, walking, acceleration, braking, friction, rotation, jumping, gravity, air control, slopes, steps, crouching, moving platforms, custom movement modes, dashes, launches, teleports, root motion sources, client prediction, saved moves, corrections, smoothing, or evaluating experimental mover. movement and animation seam movement and animation seam ownership - cmc/capsule owns authoritative collision, position, velocity, acceleration, movement mode, and floor state for code-driven locomotion. - animation blueprint reads those values and presents them. - montage root motion may temporarily drive movement when deliberately enabled. - mesh offsets, leaning, stride warping, and smoothing are presentation; do not move the authoritative capsule through arbitrary anim blueprint logic. in-place locomotion 1. derive speed from cmc velocity, using horizontal or local-space components as the graph requires. 2. derive direction from velocity relative to character/control rotation. 3. read falling, acceleration, crouch, and movement mode from the character/cmc. 4. match animation play rate/stride warping to approved physical speed. 5. keep gait thresholds derived from movement states/data, not duplicated magic values. root motion - animation asset must contain root-bone motion and have root motion enabled. - animation blueprint root-motion mode controls extraction/application. - epic warns that extracting root motion from everything moves animation graph work to the game thread; prefer the narrowest mode that satisfies the project, especially in networked gameplay. - while walking/falling, character physics still constrains vertical root motion; flying applies full root motion. - root motion takes precedence over standard movement physics. troubleshooting seam if feet slide but capsule trajectory is correct, fix animation stride/play rate/warping. if capsule trajectory is wrong, fix movement. if both systems rotate or translate the actor, select one owner before tuning either. grounding, slopes, steps, and jumping grounding, slopes, steps, and jumping ground test course build reusable geometry containing: - flat acceleration/braking lane with distance marks; - gradual slopes below, at, and above walkablefloorangle; - steps below, at, and above maxstepheight; - narrow ledges and corners for perching; - low ceilings for crouch/uncrouch; - moving and rotating bases; - seams between collision pieces. test capsule behavior first. the skeletal mesh is not the authoritative collision body. rotation ownership choose one primary path: - borientrotationtomovement: face acceleration using rotationrate; - busecontrollerdesiredrotation: rotate toward controller desired rotation using rotationrate; - explicit gameplay rotation: disable competing automatic rotation and own it in one system. also reconcile acharacter::busecontrollerrotationyaw. conflicting owners cause snapping, oscillation, or a facing direction that disagrees with movement/aim. jump model 1. define target apex height, time to apex, total airtime, horizontal control, and variable jump behavior. 2. tune jumpzvelocity and gravityscale together. 3. configure character jump-hold behavior (jumpmaxholdtime) only if variable-height jumps are desired; bind press to jump and release to stop jumping. 4. tune aircontrol, boost settings, falling friction, and lateral cap. 5. add coyote time and buffered jump as explicit gameplay forgiveness; route the timestamped input design to $unreal-enhanced-input. 6. test stepping off edges, ceilings, slopes, moving bases, repeated press, held input, and landing during a buffered request. use cmc's getmaxjumpheight/getmaxjumpheightwithjumptime as diagnostics, then verify in the actual level because collision, slopes, bases, and frame/network behavior matter. sprint and crouch - treat sprint as a state that changes desired max speed and perhaps acceleration, not as a second movement implementation. - decide hold versus toggle in the input layer. - keep the server authoritative over sprint/crouch eligibility. - use character crouch support so capsule changes and movement integration remain coherent. - test uncrouch obstruction; never force the capsule into a ceiling. character movement networking character movement networking standard flow - autonomous proxy performs local movement, records fsavedmovecharacter, and sends packed move data. - server reproduces and validates movement, then acknowledges or corrects. - owning client replays unacknowledged saved moves after a correction. - simulated proxies receive replicated movement and use network smoothing. standard cmc modes implement this. new custom state does not become predicted merely because it lives on an acharacter. custom predicted state when a custom movement flag/value changes physics: 1. add it to a custom fsavedmovecharacter and clear/store/combine it correctly. 2. extend fcharacternetworkmovedata with values the server must receive. 3. serialize them. 4. provide a custom fcharacternetworkmovedatacontainer. 5. install it through setnetworkmovedatacontainer in the custom cmc. 6. apply the data before the server reproduces movement. 7. test move combining; moves with incompatible state must not combine. use compressed flags only when their limited space and boolean semantics fit. follow current 5.8 engine headers/source for signatures. corrections and smoothing - fix deterministic divergence before tuning smoothing. - networksmoothingmode affects simulated-proxy presentation, not server authority. - location/rotation smoothing times and no-smooth distances are advanced levers; do not use them to conceal constant corrections. - keep visual mesh smoothing separate from authoritative capsule state. verification matrix run standalone, listen server, and dedicated server where relevant: - owning autonomous proxy; - server-controlled ai; - remote simulated proxy; - 0/medium/high artificial latency; - packet loss and jitter; - low and high frame rates; - sprint/crouch/custom-mode transitions while moves combine; - moving platforms and jump-off velocity; - root motion start/cancel/finish; - teleport; - server rejection/correction. log role, movement/custom mode, acceleration, velocity, location error, correction count, saved custom flags/data, and root-motion sources. never ship with client-authoritative position or correction bypasses enabled as a workaround. character movement parameter effects character movement parameter effects units follow unreal's centimeter-based world unless the project changes conventions. | parameter | primary effect | increasing it does | important coupling | |---|---|---|---| | maxwalkspeed (cm/s) | maximum ground speed; also maximum lateral falling speed | raises travel/top air-lateral cap | acceleration, braking, animation stride | | maxacceleration (cm/s²) | rate velocity can change from input | reaches desired velocity/direction faster | ground friction, analog magnitude | | brakingdecelerationwalking (cm/s²) | constant deceleration with no acceleration | shortens coast/stopping time | braking friction/factor | | groundfriction | ground movement control/friction | increases directional grip and braking when shared braking friction is used | buseseparatebrakingfriction | | buseseparatebrakingfriction | selects dedicated braking friction | separates turning grip from no-input stopping drag | brakingfriction, factor | | brakingfriction | drag coefficient while braking | shortens coast when separate braking friction is active | brakingfrictionfactor | | rotationrate (deg/s) | rotation change rate | turns facing faster | only used by controller-desired or orient-to-movement modes | | aircontrol | lateral control during falling | permits stronger steering in air | boost multiplier/threshold, falling friction | | fallinglateralfriction | drag on lateral falling motion | removes lateral velocity faster in air | braking deceleration falling | | jumpzvelocity (cm/s) | initial upward jump velocity | raises jump and airtime for fixed gravity | gravity scale, jump hold | | gravityscale | multiplier on character gravity | increases downward acceleration and shortens airtime | jump z velocity | | maxstepheight (cm) | maximum step-up height | traverses taller ledges without jumping | capsule, floor angle, geometry | | walkablefloorangle (0–90°) | maximum walkable slope | accepts steeper surfaces as floor | floor normals, slide design | | perchradiusthreshold (cm) | rejects edge contacts near capsule rim | requires more capsule support to perch | ledge behavior, capsule radius | | maxwalkspeedcrouched (cm/s) | crouched top speed | speeds crouched travel | crouched capsule and animation | | minanalogwalkspeed (cm/s) | speed at minimum analog tilt | raises low-stick movement floor | dead zone and response curve | tuning method 1. tune a clean flat test lane without animation-driven motion. 2. measure time to 90% speed and stopping distance, not just max speed. 3. tune direction reversal separately from release-to-stop. 4. add rotation ownership and rate. 5. test stick magnitudes, keyboard digital input, low and high frame rates. 6. add animation and correct stride/lean presentation after trajectory is approved. do not publish universal numeric presets. desired scale, camera, genre, capsule, animation, and network conditions change what feels correct. ue 5.8 primary sources ue 5.8 primary sources verified 2026-07-19. - movement components - ucharactermovementcomponent api - networked movement in the character movement component - set movement mode blueprint api - add movement input blueprint api - launch character blueprint api - acharacter::jump api - root motion - locomotion - mover features and concepts - unreal engine 5.8 release notes version note: these pages currently resolve to unreal engine 5.8. epic labels mover experimental. the 5.8 release notes describe expanded mover prediction/rollback work but do not remove that maturity warning. character movement remains the mature default for standard networked character locomotion. special movement patterns special movement patterns launch use launchcharacter for an impulse-like velocity change that should enter the character movement pipeline. decide independently whether xy/z override existing velocity. test authority, prediction/correction, landing, air control, and repeated launches. a launch is not a duration- controlled dash. teleport for network play: 1. validate the destination on the server. 2. use a supported setlocation path with teleport behavior or the teleport blueprint node. 3. ensure collision/encroachment policy matches the design. 4. expect clients to snap rather than smooth the teleport. do not move the owning client first with ordinary transform changes and expect cmc prediction to accept it. root motion source use for short programmatic motion needing character root-motion networking, such as move-to or jump-force behavior. 1. select/create the appropriate frootmotionsource variant. 2. set duration, priority/accumulation, start/target, and finish behavior. 3. apply through ucharactermovementcomponent::applyrootmotionsource on the appropriate prediction/authority path. 4. retain the returned handle/id. 5. remove with removerootmotionsource when canceled or finished if required by the pattern. 6. test server rejection, collision, moving targets, and montage/root-motion competition. gas provides ability tasks that use root motion sources; prefer those when the ability owns activation, cancellation, and prediction. custom movement mode 1. allocate a stable custom sub-mode byte/enum. 2. enter through setmovementmode(movecustom, submode). 3. implement updatecustommovement in character blueprint for prototypes, or override physcustom in a custom cmc for production control. 4. perform swept movement and define collision, floor, velocity, gravity, and exit rules. 5. serialize any custom input/state the server needs through saved-move/network move data. 6. return to walking/falling/etc. through an explicit exit condition. movecustom suspends normal movement physics. failing to implement gravity, collision, or velocity semantics is not an engine bug. montage root motion use for animation-authored committed actions. root motion takes priority over standard movement physics. in network games, ensure gameplay triggers the montage consistently; gas can synchronize ability-owned montages/root motion. route blend/slot details to $unreal-animation-blending. movement system selector movement system selector | need | use | reason / warning | |---|---|---| | standard humanoid capsule movement and mature multiplayer support | acharacter + ucharactermovementcomponent | walking/falling/swimming/flying/custom modes, prediction, correction, smoothing | | a special mode integrated with normal character movement | cmc movecustom + custom sub-mode | standard physics are suspended while custom physics run; custom state may need saved-move serialization | | short deterministic/programmatic ability movement | root motion source or gas root-motion ability task | participates in character root-motion networking when used correctly | | animation-authored committed movement | montage root motion | root motion takes priority over normal movement physics; gameplay must synchronize montage execution | | modular mode/layered-move architecture and willingness to carry experimental risk | mover | epic labels mover experimental in ue 5.8 | | vehicle, rolling body, non-capsule creature, or unconventional physics | purpose-built pawn/movement system | character and cmc are designed together around character movement assumptions | selection procedure 1. define collision shape and whether the entity must use acharacter. 2. list movement modes and which may overlap as temporary layered moves. 3. state single-player/multiplayer, authority, prediction, and rollback requirements. 4. state whether motion is code-driven, animation-driven, or selected per action. 5. choose the most mature framework that satisfies the requirements. 6. if choosing mover, record experimental status, engine-version lock, fallback cost, and a packaged multiplayer prototype milestone before committing production content. do not migrate from cmc merely because custom movement requires c++. the deciding question is whether cmc's character/capsule/mode/network model still fits the game. troubleshooting troubleshooting character slides after input release - raise braking deceleration and/or effective braking friction deliberately. - check buseseparatebrakingfriction, brakingfriction, and factor interaction. - distinguish no-input stopping from direction-change grip. direction changes feel slow despite high acceleration - check groundfriction and effective input magnitude. - check rotation ownership/rate if facing, not velocity, is the slow part. - measure velocity change separately from mesh turn animation. cannot climb a small step - compare collision height with maxstepheight. - confirm the upper surface is walkable and the capsule has clearance. - inspect collision seams and blocking channels. - test without decorative mesh collision overriding intended simple collision. stands on implausibly tiny edges - review perchradiusthreshold, capsule radius, and ledge geometry. - visualize collision/floor results; do not judge by skeletal mesh feet. jump varies with frame rate - remove manual per-frame velocity/position increments lacking delta-time/physics integration. - verify variable jump release is bound correctly. - check custom movement simulation time steps/iterations under low frame rate. constant server corrections - confirm client and server use identical parameters and custom state. - serialize state that changes movement physics. - prevent incompatible saved moves from combining. - remove client-only transform changes. - fix divergence before changing smoothing or correction thresholds. remote character jitters - first determine whether authoritative capsule is correcting or only mesh smoothing looks bad. - inspect update rate, packet conditions, moving base, and custom-mode replication. - tune smoothing only after deterministic movement is correct. root motion fights movement - confirm root-motion extraction mode and asset settings. - remember root motion takes precedence over normal movement physics. - do not also drive the same action with launch/setlocation/velocity. - ensure montage start/cancel is synchronized across network roles. custom mode floats or tunnels - movecustom suspends standard physics; implement gravity, velocity, swept collision, floor, sub-stepping, and exit behavior explicitly. - prefer c++ physcustom for complex production modes.","references":[{"slug":"animation-seam","file":"animation-seam.md","title":"Movement and animation seam","rawMarkdown":"# Movement and animation seam\n\n## Ownership\n\n- CMC/capsule owns authoritative collision, position, velocity, acceleration, movement mode,\n  and floor state for code-driven locomotion.\n- Animation Blueprint reads those values and presents them.\n- Montage root motion may temporarily drive movement when deliberately enabled.\n- Mesh offsets, leaning, stride warping, and smoothing are presentation; do not move the\n  authoritative capsule through arbitrary Anim Blueprint logic.\n\n## In-place locomotion\n\n1. Derive speed from CMC velocity, using horizontal or local-space components as the graph\n   requires.\n2. Derive direction from velocity relative to character/control rotation.\n3. Read falling, acceleration, crouch, and movement mode from the Character/CMC.\n4. Match animation play rate/stride warping to approved physical speed.\n5. Keep gait thresholds derived from movement states/data, not duplicated magic values.\n\n## Root motion\n\n- Animation asset must contain root-bone motion and have root motion enabled.\n- Animation Blueprint root-motion mode controls extraction/application.\n- Epic warns that extracting root motion from everything moves Animation Graph work to the\n  Game Thread; prefer the narrowest mode that satisfies the project, especially in networked\n  gameplay.\n- While Walking/Falling, Character physics still constrains vertical root motion; Flying\n  applies full root motion.\n- Root motion takes precedence over standard movement physics.\n\n## Troubleshooting seam\n\nIf feet slide but capsule trajectory is correct, fix animation stride/play rate/warping. If\ncapsule trajectory is wrong, fix movement. If both systems rotate or translate the actor,\nselect one owner before tuning either.\n","webMarkdown":"## Ownership\n\n- CMC/capsule owns authoritative collision, position, velocity, acceleration, movement mode,\n  and floor state for code-driven locomotion.\n- Animation Blueprint reads those values and presents them.\n- Montage root motion may temporarily drive movement when deliberately enabled.\n- Mesh offsets, leaning, stride warping, and smoothing are presentation; do not move the\n  authoritative capsule through arbitrary Anim Blueprint logic.\n\n## In-place locomotion\n\n1. Derive speed from CMC velocity, using horizontal or local-space components as the graph\n   requires.\n2. Derive direction from velocity relative to character/control rotation.\n3. Read falling, acceleration, crouch, and movement mode from the Character/CMC.\n4. Match animation play rate/stride warping to approved physical speed.\n5. Keep gait thresholds derived from movement states/data, not duplicated magic values.\n\n## Root motion\n\n- Animation asset must contain root-bone motion and have root motion enabled.\n- Animation Blueprint root-motion mode controls extraction/application.\n- Epic warns that extracting root motion from everything moves Animation Graph work to the\n  Game Thread; prefer the narrowest mode that satisfies the project, especially in networked\n  gameplay.\n- While Walking/Falling, Character physics still constrains vertical root motion; Flying\n  applies full root motion.\n- Root motion takes precedence over standard movement physics.\n\n## Troubleshooting seam\n\nIf feet slide but capsule trajectory is correct, fix animation stride/play rate/warping. If\ncapsule trajectory is wrong, fix movement. If both systems rotate or translate the actor,\nselect one owner before tuning either.\n","searchText":"movement and animation seam ownership - cmc/capsule owns authoritative collision, position, velocity, acceleration, movement mode, and floor state for code-driven locomotion. - animation blueprint reads those values and presents them. - montage root motion may temporarily drive movement when deliberately enabled. - mesh offsets, leaning, stride warping, and smoothing are presentation; do not move the authoritative capsule through arbitrary anim blueprint logic. in-place locomotion 1. derive speed from cmc velocity, using horizontal or local-space components as the graph requires. 2. derive direction from velocity relative to character/control rotation. 3. read falling, acceleration, crouch, and movement mode from the character/cmc. 4. match animation play rate/stride warping to approved physical speed. 5. keep gait thresholds derived from movement states/data, not duplicated magic values. root motion - animation asset must contain root-bone motion and have root motion enabled. - animation blueprint root-motion mode controls extraction/application. - epic warns that extracting root motion from everything moves animation graph work to the game thread; prefer the narrowest mode that satisfies the project, especially in networked gameplay. - while walking/falling, character physics still constrains vertical root motion; flying applies full root motion. - root motion takes precedence over standard movement physics. troubleshooting seam if feet slide but capsule trajectory is correct, fix animation stride/play rate/warping. if capsule trajectory is wrong, fix movement. if both systems rotate or translate the actor, select one owner before tuning either."},{"slug":"grounding-jumping","file":"grounding-jumping.md","title":"Grounding, slopes, steps, and jumping","rawMarkdown":"# Grounding, slopes, steps, and jumping\n\n## Ground test course\n\nBuild reusable geometry containing:\n\n- flat acceleration/braking lane with distance marks;\n- gradual slopes below, at, and above `WalkableFloorAngle`;\n- steps below, at, and above `MaxStepHeight`;\n- narrow ledges and corners for perching;\n- low ceilings for crouch/uncrouch;\n- moving and rotating bases;\n- seams between collision pieces.\n\nTest capsule behavior first. The skeletal mesh is not the authoritative collision body.\n\n## Rotation ownership\n\nChoose one primary path:\n\n- `bOrientRotationToMovement`: face acceleration using `RotationRate`;\n- `bUseControllerDesiredRotation`: rotate toward controller desired rotation using\n  `RotationRate`;\n- explicit gameplay rotation: disable competing automatic rotation and own it in one system.\n\nAlso reconcile `ACharacter::bUseControllerRotationYaw`. Conflicting owners cause snapping,\noscillation, or a facing direction that disagrees with movement/aim.\n\n## Jump model\n\n1. Define target apex height, time to apex, total airtime, horizontal control, and variable\n   jump behavior.\n2. Tune `JumpZVelocity` and `GravityScale` together.\n3. Configure Character jump-hold behavior (`JumpMaxHoldTime`) only if variable-height jumps\n   are desired; bind press to Jump and release to Stop Jumping.\n4. Tune `AirControl`, boost settings, falling friction, and lateral cap.\n5. Add coyote time and buffered jump as explicit gameplay forgiveness; route the timestamped\n   input design to `$unreal-enhanced-input`.\n6. Test stepping off edges, ceilings, slopes, moving bases, repeated press, held input, and\n   landing during a buffered request.\n\nUse CMC's `GetMaxJumpHeight`/`GetMaxJumpHeightWithJumpTime` as diagnostics, then verify in the\nactual level because collision, slopes, bases, and frame/network behavior matter.\n\n## Sprint and crouch\n\n- Treat sprint as a state that changes desired max speed and perhaps acceleration, not as a\n  second movement implementation.\n- Decide hold versus toggle in the input layer.\n- Keep the server authoritative over sprint/crouch eligibility.\n- Use Character crouch support so capsule changes and movement integration remain coherent.\n- Test uncrouch obstruction; never force the capsule into a ceiling.\n","webMarkdown":"## Ground test course\n\nBuild reusable geometry containing:\n\n- flat acceleration/braking lane with distance marks;\n- gradual slopes below, at, and above `WalkableFloorAngle`;\n- steps below, at, and above `MaxStepHeight`;\n- narrow ledges and corners for perching;\n- low ceilings for crouch/uncrouch;\n- moving and rotating bases;\n- seams between collision pieces.\n\nTest capsule behavior first. The skeletal mesh is not the authoritative collision body.\n\n## Rotation ownership\n\nChoose one primary path:\n\n- `bOrientRotationToMovement`: face acceleration using `RotationRate`;\n- `bUseControllerDesiredRotation`: rotate toward controller desired rotation using\n  `RotationRate`;\n- explicit gameplay rotation: disable competing automatic rotation and own it in one system.\n\nAlso reconcile `ACharacter::bUseControllerRotationYaw`. Conflicting owners cause snapping,\noscillation, or a facing direction that disagrees with movement/aim.\n\n## Jump model\n\n1. Define target apex height, time to apex, total airtime, horizontal control, and variable\n   jump behavior.\n2. Tune `JumpZVelocity` and `GravityScale` together.\n3. Configure Character jump-hold behavior (`JumpMaxHoldTime`) only if variable-height jumps\n   are desired; bind press to Jump and release to Stop Jumping.\n4. Tune `AirControl`, boost settings, falling friction, and lateral cap.\n5. Add coyote time and buffered jump as explicit gameplay forgiveness; route the timestamped\n   input design to `$unreal-enhanced-input`.\n6. Test stepping off edges, ceilings, slopes, moving bases, repeated press, held input, and\n   landing during a buffered request.\n\nUse CMC's `GetMaxJumpHeight`/`GetMaxJumpHeightWithJumpTime` as diagnostics, then verify in the\nactual level because collision, slopes, bases, and frame/network behavior matter.\n\n## Sprint and crouch\n\n- Treat sprint as a state that changes desired max speed and perhaps acceleration, not as a\n  second movement implementation.\n- Decide hold versus toggle in the input layer.\n- Keep the server authoritative over sprint/crouch eligibility.\n- Use Character crouch support so capsule changes and movement integration remain coherent.\n- Test uncrouch obstruction; never force the capsule into a ceiling.\n","searchText":"grounding, slopes, steps, and jumping ground test course build reusable geometry containing: - flat acceleration/braking lane with distance marks; - gradual slopes below, at, and above walkablefloorangle; - steps below, at, and above maxstepheight; - narrow ledges and corners for perching; - low ceilings for crouch/uncrouch; - moving and rotating bases; - seams between collision pieces. test capsule behavior first. the skeletal mesh is not the authoritative collision body. rotation ownership choose one primary path: - borientrotationtomovement: face acceleration using rotationrate; - busecontrollerdesiredrotation: rotate toward controller desired rotation using rotationrate; - explicit gameplay rotation: disable competing automatic rotation and own it in one system. also reconcile acharacter::busecontrollerrotationyaw. conflicting owners cause snapping, oscillation, or a facing direction that disagrees with movement/aim. jump model 1. define target apex height, time to apex, total airtime, horizontal control, and variable jump behavior. 2. tune jumpzvelocity and gravityscale together. 3. configure character jump-hold behavior (jumpmaxholdtime) only if variable-height jumps are desired; bind press to jump and release to stop jumping. 4. tune aircontrol, boost settings, falling friction, and lateral cap. 5. add coyote time and buffered jump as explicit gameplay forgiveness; route the timestamped input design to $unreal-enhanced-input. 6. test stepping off edges, ceilings, slopes, moving bases, repeated press, held input, and landing during a buffered request. use cmc's getmaxjumpheight/getmaxjumpheightwithjumptime as diagnostics, then verify in the actual level because collision, slopes, bases, and frame/network behavior matter. sprint and crouch - treat sprint as a state that changes desired max speed and perhaps acceleration, not as a second movement implementation. - decide hold versus toggle in the input layer. - keep the server authoritative over sprint/crouch eligibility. - use character crouch support so capsule changes and movement integration remain coherent. - test uncrouch obstruction; never force the capsule into a ceiling."},{"slug":"networking","file":"networking.md","title":"Character movement networking","rawMarkdown":"# Character movement networking\n\n## Standard flow\n\n- Autonomous proxy performs local movement, records `FSavedMove_Character`, and sends packed\n  move data.\n- Server reproduces and validates movement, then acknowledges or corrects.\n- Owning client replays unacknowledged saved moves after a correction.\n- Simulated proxies receive replicated movement and use network smoothing.\n\nStandard CMC modes implement this. New custom state does not become predicted merely because it\nlives on an `ACharacter`.\n\n## Custom predicted state\n\nWhen a custom movement flag/value changes physics:\n\n1. Add it to a custom `FSavedMove_Character` and clear/store/combine it correctly.\n2. Extend `FCharacterNetworkMoveData` with values the server must receive.\n3. Serialize them.\n4. Provide a custom `FCharacterNetworkMoveDataContainer`.\n5. Install it through `SetNetworkMoveDataContainer` in the custom CMC.\n6. Apply the data before the server reproduces movement.\n7. Test move combining; moves with incompatible state must not combine.\n\nUse compressed flags only when their limited space and boolean semantics fit. Follow current\n5.8 engine headers/source for signatures.\n\n## Corrections and smoothing\n\n- Fix deterministic divergence before tuning smoothing.\n- `NetworkSmoothingMode` affects simulated-proxy presentation, not server authority.\n- Location/rotation smoothing times and no-smooth distances are advanced levers; do not use\n  them to conceal constant corrections.\n- Keep visual mesh smoothing separate from authoritative capsule state.\n\n## Verification matrix\n\nRun standalone, listen server, and dedicated server where relevant:\n\n- owning autonomous proxy;\n- server-controlled AI;\n- remote simulated proxy;\n- 0/medium/high artificial latency;\n- packet loss and jitter;\n- low and high frame rates;\n- sprint/crouch/custom-mode transitions while moves combine;\n- moving platforms and jump-off velocity;\n- root motion start/cancel/finish;\n- teleport;\n- server rejection/correction.\n\nLog role, movement/custom mode, acceleration, velocity, location error, correction count,\nsaved custom flags/data, and root-motion sources. Never ship with client-authoritative\nposition or correction bypasses enabled as a workaround.\n","webMarkdown":"## Standard flow\n\n- Autonomous proxy performs local movement, records `FSavedMove_Character`, and sends packed\n  move data.\n- Server reproduces and validates movement, then acknowledges or corrects.\n- Owning client replays unacknowledged saved moves after a correction.\n- Simulated proxies receive replicated movement and use network smoothing.\n\nStandard CMC modes implement this. New custom state does not become predicted merely because it\nlives on an `ACharacter`.\n\n## Custom predicted state\n\nWhen a custom movement flag/value changes physics:\n\n1. Add it to a custom `FSavedMove_Character` and clear/store/combine it correctly.\n2. Extend `FCharacterNetworkMoveData` with values the server must receive.\n3. Serialize them.\n4. Provide a custom `FCharacterNetworkMoveDataContainer`.\n5. Install it through `SetNetworkMoveDataContainer` in the custom CMC.\n6. Apply the data before the server reproduces movement.\n7. Test move combining; moves with incompatible state must not combine.\n\nUse compressed flags only when their limited space and boolean semantics fit. Follow current\n5.8 engine headers/source for signatures.\n\n## Corrections and smoothing\n\n- Fix deterministic divergence before tuning smoothing.\n- `NetworkSmoothingMode` affects simulated-proxy presentation, not server authority.\n- Location/rotation smoothing times and no-smooth distances are advanced levers; do not use\n  them to conceal constant corrections.\n- Keep visual mesh smoothing separate from authoritative capsule state.\n\n## Verification matrix\n\nRun standalone, listen server, and dedicated server where relevant:\n\n- owning autonomous proxy;\n- server-controlled AI;\n- remote simulated proxy;\n- 0/medium/high artificial latency;\n- packet loss and jitter;\n- low and high frame rates;\n- sprint/crouch/custom-mode transitions while moves combine;\n- moving platforms and jump-off velocity;\n- root motion start/cancel/finish;\n- teleport;\n- server rejection/correction.\n\nLog role, movement/custom mode, acceleration, velocity, location error, correction count,\nsaved custom flags/data, and root-motion sources. Never ship with client-authoritative\nposition or correction bypasses enabled as a workaround.\n","searchText":"character movement networking standard flow - autonomous proxy performs local movement, records fsavedmovecharacter, and sends packed move data. - server reproduces and validates movement, then acknowledges or corrects. - owning client replays unacknowledged saved moves after a correction. - simulated proxies receive replicated movement and use network smoothing. standard cmc modes implement this. new custom state does not become predicted merely because it lives on an acharacter. custom predicted state when a custom movement flag/value changes physics: 1. add it to a custom fsavedmovecharacter and clear/store/combine it correctly. 2. extend fcharacternetworkmovedata with values the server must receive. 3. serialize them. 4. provide a custom fcharacternetworkmovedatacontainer. 5. install it through setnetworkmovedatacontainer in the custom cmc. 6. apply the data before the server reproduces movement. 7. test move combining; moves with incompatible state must not combine. use compressed flags only when their limited space and boolean semantics fit. follow current 5.8 engine headers/source for signatures. corrections and smoothing - fix deterministic divergence before tuning smoothing. - networksmoothingmode affects simulated-proxy presentation, not server authority. - location/rotation smoothing times and no-smooth distances are advanced levers; do not use them to conceal constant corrections. - keep visual mesh smoothing separate from authoritative capsule state. verification matrix run standalone, listen server, and dedicated server where relevant: - owning autonomous proxy; - server-controlled ai; - remote simulated proxy; - 0/medium/high artificial latency; - packet loss and jitter; - low and high frame rates; - sprint/crouch/custom-mode transitions while moves combine; - moving platforms and jump-off velocity; - root motion start/cancel/finish; - teleport; - server rejection/correction. log role, movement/custom mode, acceleration, velocity, location error, correction count, saved custom flags/data, and root-motion sources. never ship with client-authoritative position or correction bypasses enabled as a workaround."},{"slug":"parameter-effects","file":"parameter-effects.md","title":"Character Movement parameter effects","rawMarkdown":"# Character Movement parameter effects\n\nUnits follow Unreal's centimeter-based world unless the project changes conventions.\n\n| Parameter | Primary effect | Increasing it does | Important coupling |\n|---|---|---|---|\n| `MaxWalkSpeed` (cm/s) | Maximum ground speed; also maximum lateral falling speed | Raises travel/top air-lateral cap | Acceleration, braking, animation stride |\n| `MaxAcceleration` (cm/s²) | Rate velocity can change from input | Reaches desired velocity/direction faster | Ground friction, analog magnitude |\n| `BrakingDecelerationWalking` (cm/s²) | Constant deceleration with no acceleration | Shortens coast/stopping time | Braking friction/factor |\n| `GroundFriction` | Ground movement control/friction | Increases directional grip and braking when shared braking friction is used | `bUseSeparateBrakingFriction` |\n| `bUseSeparateBrakingFriction` | Selects dedicated braking friction | Separates turning grip from no-input stopping drag | `BrakingFriction`, factor |\n| `BrakingFriction` | Drag coefficient while braking | Shortens coast when separate braking friction is active | `BrakingFrictionFactor` |\n| `RotationRate` (deg/s) | Rotation change rate | Turns facing faster | Only used by controller-desired or orient-to-movement modes |\n| `AirControl` | Lateral control during falling | Permits stronger steering in air | Boost multiplier/threshold, falling friction |\n| `FallingLateralFriction` | Drag on lateral falling motion | Removes lateral velocity faster in air | Braking deceleration falling |\n| `JumpZVelocity` (cm/s) | Initial upward jump velocity | Raises jump and airtime for fixed gravity | Gravity scale, jump hold |\n| `GravityScale` | Multiplier on character gravity | Increases downward acceleration and shortens airtime | Jump Z velocity |\n| `MaxStepHeight` (cm) | Maximum step-up height | Traverses taller ledges without jumping | Capsule, floor angle, geometry |\n| `WalkableFloorAngle` (0–90°) | Maximum walkable slope | Accepts steeper surfaces as floor | Floor normals, slide design |\n| `PerchRadiusThreshold` (cm) | Rejects edge contacts near capsule rim | Requires more capsule support to perch | Ledge behavior, capsule radius |\n| `MaxWalkSpeedCrouched` (cm/s) | Crouched top speed | Speeds crouched travel | Crouched capsule and animation |\n| `MinAnalogWalkSpeed` (cm/s) | Speed at minimum analog tilt | Raises low-stick movement floor | Dead zone and response curve |\n\n## Tuning method\n\n1. Tune a clean flat test lane without animation-driven motion.\n2. Measure time to 90% speed and stopping distance, not just max speed.\n3. Tune direction reversal separately from release-to-stop.\n4. Add rotation ownership and rate.\n5. Test stick magnitudes, keyboard digital input, low and high frame rates.\n6. Add animation and correct stride/lean presentation after trajectory is approved.\n\nDo not publish universal numeric presets. Desired scale, camera, genre, capsule, animation,\nand network conditions change what feels correct.\n","webMarkdown":"Units follow Unreal's centimeter-based world unless the project changes conventions.\n\n| Parameter | Primary effect | Increasing it does | Important coupling |\n|---|---|---|---|\n| `MaxWalkSpeed` (cm/s) | Maximum ground speed; also maximum lateral falling speed | Raises travel/top air-lateral cap | Acceleration, braking, animation stride |\n| `MaxAcceleration` (cm/s²) | Rate velocity can change from input | Reaches desired velocity/direction faster | Ground friction, analog magnitude |\n| `BrakingDecelerationWalking` (cm/s²) | Constant deceleration with no acceleration | Shortens coast/stopping time | Braking friction/factor |\n| `GroundFriction` | Ground movement control/friction | Increases directional grip and braking when shared braking friction is used | `bUseSeparateBrakingFriction` |\n| `bUseSeparateBrakingFriction` | Selects dedicated braking friction | Separates turning grip from no-input stopping drag | `BrakingFriction`, factor |\n| `BrakingFriction` | Drag coefficient while braking | Shortens coast when separate braking friction is active | `BrakingFrictionFactor` |\n| `RotationRate` (deg/s) | Rotation change rate | Turns facing faster | Only used by controller-desired or orient-to-movement modes |\n| `AirControl` | Lateral control during falling | Permits stronger steering in air | Boost multiplier/threshold, falling friction |\n| `FallingLateralFriction` | Drag on lateral falling motion | Removes lateral velocity faster in air | Braking deceleration falling |\n| `JumpZVelocity` (cm/s) | Initial upward jump velocity | Raises jump and airtime for fixed gravity | Gravity scale, jump hold |\n| `GravityScale` | Multiplier on character gravity | Increases downward acceleration and shortens airtime | Jump Z velocity |\n| `MaxStepHeight` (cm) | Maximum step-up height | Traverses taller ledges without jumping | Capsule, floor angle, geometry |\n| `WalkableFloorAngle` (0–90°) | Maximum walkable slope | Accepts steeper surfaces as floor | Floor normals, slide design |\n| `PerchRadiusThreshold` (cm) | Rejects edge contacts near capsule rim | Requires more capsule support to perch | Ledge behavior, capsule radius |\n| `MaxWalkSpeedCrouched` (cm/s) | Crouched top speed | Speeds crouched travel | Crouched capsule and animation |\n| `MinAnalogWalkSpeed` (cm/s) | Speed at minimum analog tilt | Raises low-stick movement floor | Dead zone and response curve |\n\n## Tuning method\n\n1. Tune a clean flat test lane without animation-driven motion.\n2. Measure time to 90% speed and stopping distance, not just max speed.\n3. Tune direction reversal separately from release-to-stop.\n4. Add rotation ownership and rate.\n5. Test stick magnitudes, keyboard digital input, low and high frame rates.\n6. Add animation and correct stride/lean presentation after trajectory is approved.\n\nDo not publish universal numeric presets. Desired scale, camera, genre, capsule, animation,\nand network conditions change what feels correct.\n","searchText":"character movement parameter effects units follow unreal's centimeter-based world unless the project changes conventions. | parameter | primary effect | increasing it does | important coupling | |---|---|---|---| | maxwalkspeed (cm/s) | maximum ground speed; also maximum lateral falling speed | raises travel/top air-lateral cap | acceleration, braking, animation stride | | maxacceleration (cm/s²) | rate velocity can change from input | reaches desired velocity/direction faster | ground friction, analog magnitude | | brakingdecelerationwalking (cm/s²) | constant deceleration with no acceleration | shortens coast/stopping time | braking friction/factor | | groundfriction | ground movement control/friction | increases directional grip and braking when shared braking friction is used | buseseparatebrakingfriction | | buseseparatebrakingfriction | selects dedicated braking friction | separates turning grip from no-input stopping drag | brakingfriction, factor | | brakingfriction | drag coefficient while braking | shortens coast when separate braking friction is active | brakingfrictionfactor | | rotationrate (deg/s) | rotation change rate | turns facing faster | only used by controller-desired or orient-to-movement modes | | aircontrol | lateral control during falling | permits stronger steering in air | boost multiplier/threshold, falling friction | | fallinglateralfriction | drag on lateral falling motion | removes lateral velocity faster in air | braking deceleration falling | | jumpzvelocity (cm/s) | initial upward jump velocity | raises jump and airtime for fixed gravity | gravity scale, jump hold | | gravityscale | multiplier on character gravity | increases downward acceleration and shortens airtime | jump z velocity | | maxstepheight (cm) | maximum step-up height | traverses taller ledges without jumping | capsule, floor angle, geometry | | walkablefloorangle (0–90°) | maximum walkable slope | accepts steeper surfaces as floor | floor normals, slide design | | perchradiusthreshold (cm) | rejects edge contacts near capsule rim | requires more capsule support to perch | ledge behavior, capsule radius | | maxwalkspeedcrouched (cm/s) | crouched top speed | speeds crouched travel | crouched capsule and animation | | minanalogwalkspeed (cm/s) | speed at minimum analog tilt | raises low-stick movement floor | dead zone and response curve | tuning method 1. tune a clean flat test lane without animation-driven motion. 2. measure time to 90% speed and stopping distance, not just max speed. 3. tune direction reversal separately from release-to-stop. 4. add rotation ownership and rate. 5. test stick magnitudes, keyboard digital input, low and high frame rates. 6. add animation and correct stride/lean presentation after trajectory is approved. do not publish universal numeric presets. desired scale, camera, genre, capsule, animation, and network conditions change what feels correct."},{"slug":"sources","file":"sources.md","title":"UE 5.8 primary sources","rawMarkdown":"# UE 5.8 primary sources\n\nVerified 2026-07-19.\n\n- [Movement Components](https://dev.epicgames.com/documentation/en-us/unreal-engine/movement-components-in-unreal-engine)\n- [`UCharacterMovementComponent` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/UCharacterMovementComponent)\n- [Networked Movement in the Character Movement Component](https://dev.epicgames.com/documentation/en-us/unreal-engine/understanding-networked-movement-in-the-character-movement-component-for-unreal-engine)\n- [Set Movement Mode Blueprint API](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/Pawn/Components/CharacterMovement/SetMovementMode)\n- [Add Movement Input Blueprint API](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/Pawn/Input/AddMovementInput)\n- [Launch Character Blueprint API](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/Character/LaunchCharacter)\n- [`ACharacter::Jump` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/ACharacter/Jump)\n- [Root Motion](https://dev.epicgames.com/documentation/en-us/unreal-engine/root-motion-in-unreal-engine)\n- [Locomotion](https://dev.epicgames.com/documentation/en-us/unreal-engine/locomotion-in-unreal-engine)\n- [Mover Features and Concepts](https://dev.epicgames.com/documentation/en-us/unreal-engine/mover-features-and-concepts-in-unreal-engine)\n- [Unreal Engine 5.8 Release Notes](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-8-release-notes)\n\nVersion note: these pages currently resolve to Unreal Engine 5.8. Epic labels Mover\nExperimental. The 5.8 release notes describe expanded Mover prediction/rollback work but do\nnot remove that maturity warning. Character Movement remains the mature default for standard\nnetworked Character locomotion.\n","webMarkdown":"Verified 2026-07-19.\n\n- [Movement Components](https://dev.epicgames.com/documentation/en-us/unreal-engine/movement-components-in-unreal-engine)\n- [`UCharacterMovementComponent` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/UCharacterMovementComponent)\n- [Networked Movement in the Character Movement Component](https://dev.epicgames.com/documentation/en-us/unreal-engine/understanding-networked-movement-in-the-character-movement-component-for-unreal-engine)\n- [Set Movement Mode Blueprint API](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/Pawn/Components/CharacterMovement/SetMovementMode)\n- [Add Movement Input Blueprint API](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/Pawn/Input/AddMovementInput)\n- [Launch Character Blueprint API](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/Character/LaunchCharacter)\n- [`ACharacter::Jump` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/ACharacter/Jump)\n- [Root Motion](https://dev.epicgames.com/documentation/en-us/unreal-engine/root-motion-in-unreal-engine)\n- [Locomotion](https://dev.epicgames.com/documentation/en-us/unreal-engine/locomotion-in-unreal-engine)\n- [Mover Features and Concepts](https://dev.epicgames.com/documentation/en-us/unreal-engine/mover-features-and-concepts-in-unreal-engine)\n- [Unreal Engine 5.8 Release Notes](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-8-release-notes)\n\nVersion note: these pages currently resolve to Unreal Engine 5.8. Epic labels Mover\nExperimental. The 5.8 release notes describe expanded Mover prediction/rollback work but do\nnot remove that maturity warning. Character Movement remains the mature default for standard\nnetworked Character locomotion.\n","searchText":"ue 5.8 primary sources verified 2026-07-19. - movement components - ucharactermovementcomponent api - networked movement in the character movement component - set movement mode blueprint api - add movement input blueprint api - launch character blueprint api - acharacter::jump api - root motion - locomotion - mover features and concepts - unreal engine 5.8 release notes version note: these pages currently resolve to unreal engine 5.8. epic labels mover experimental. the 5.8 release notes describe expanded mover prediction/rollback work but do not remove that maturity warning. character movement remains the mature default for standard networked character locomotion."},{"slug":"special-movement","file":"special-movement.md","title":"Special movement patterns","rawMarkdown":"# Special movement patterns\n\n## Launch\n\nUse `LaunchCharacter` for an impulse-like velocity change that should enter the Character\nmovement pipeline. Decide independently whether XY/Z override existing velocity. Test authority,\nprediction/correction, landing, air control, and repeated launches. A launch is not a duration-\ncontrolled dash.\n\n## Teleport\n\nFor network play:\n\n1. Validate the destination on the server.\n2. Use a supported SetLocation path with teleport behavior or the Teleport Blueprint node.\n3. Ensure collision/encroachment policy matches the design.\n4. Expect clients to snap rather than smooth the teleport.\n\nDo not move the owning client first with ordinary transform changes and expect CMC prediction\nto accept it.\n\n## Root Motion Source\n\nUse for short programmatic motion needing Character root-motion networking, such as move-to or\njump-force behavior.\n\n1. Select/create the appropriate `FRootMotionSource` variant.\n2. Set duration, priority/accumulation, start/target, and finish behavior.\n3. Apply through `UCharacterMovementComponent::ApplyRootMotionSource` on the appropriate\n   prediction/authority path.\n4. Retain the returned handle/ID.\n5. Remove with `RemoveRootMotionSource` when canceled or finished if required by the pattern.\n6. Test server rejection, collision, moving targets, and montage/root-motion competition.\n\nGAS provides Ability Tasks that use Root Motion Sources; prefer those when the ability owns\nactivation, cancellation, and prediction.\n\n## Custom movement mode\n\n1. Allocate a stable custom sub-mode byte/enum.\n2. Enter through `SetMovementMode(MOVE_Custom, SubMode)`.\n3. Implement `UpdateCustomMovement` in Character Blueprint for prototypes, or override\n   `PhysCustom` in a custom CMC for production control.\n4. Perform swept movement and define collision, floor, velocity, gravity, and exit rules.\n5. Serialize any custom input/state the server needs through saved-move/network move data.\n6. Return to Walking/Falling/etc. through an explicit exit condition.\n\n`MOVE_Custom` suspends normal movement physics. Failing to implement gravity, collision, or\nvelocity semantics is not an engine bug.\n\n## Montage root motion\n\nUse for animation-authored committed actions. Root motion takes priority over standard\nmovement physics. In network games, ensure gameplay triggers the montage consistently; GAS can\nsynchronize ability-owned montages/root motion. Route blend/slot details to\n`$unreal-animation-blending`.\n","webMarkdown":"## Launch\n\nUse `LaunchCharacter` for an impulse-like velocity change that should enter the Character\nmovement pipeline. Decide independently whether XY/Z override existing velocity. Test authority,\nprediction/correction, landing, air control, and repeated launches. A launch is not a duration-\ncontrolled dash.\n\n## Teleport\n\nFor network play:\n\n1. Validate the destination on the server.\n2. Use a supported SetLocation path with teleport behavior or the Teleport Blueprint node.\n3. Ensure collision/encroachment policy matches the design.\n4. Expect clients to snap rather than smooth the teleport.\n\nDo not move the owning client first with ordinary transform changes and expect CMC prediction\nto accept it.\n\n## Root Motion Source\n\nUse for short programmatic motion needing Character root-motion networking, such as move-to or\njump-force behavior.\n\n1. Select/create the appropriate `FRootMotionSource` variant.\n2. Set duration, priority/accumulation, start/target, and finish behavior.\n3. Apply through `UCharacterMovementComponent::ApplyRootMotionSource` on the appropriate\n   prediction/authority path.\n4. Retain the returned handle/ID.\n5. Remove with `RemoveRootMotionSource` when canceled or finished if required by the pattern.\n6. Test server rejection, collision, moving targets, and montage/root-motion competition.\n\nGAS provides Ability Tasks that use Root Motion Sources; prefer those when the ability owns\nactivation, cancellation, and prediction.\n\n## Custom movement mode\n\n1. Allocate a stable custom sub-mode byte/enum.\n2. Enter through `SetMovementMode(MOVE_Custom, SubMode)`.\n3. Implement `UpdateCustomMovement` in Character Blueprint for prototypes, or override\n   `PhysCustom` in a custom CMC for production control.\n4. Perform swept movement and define collision, floor, velocity, gravity, and exit rules.\n5. Serialize any custom input/state the server needs through saved-move/network move data.\n6. Return to Walking/Falling/etc. through an explicit exit condition.\n\n`MOVE_Custom` suspends normal movement physics. Failing to implement gravity, collision, or\nvelocity semantics is not an engine bug.\n\n## Montage root motion\n\nUse for animation-authored committed actions. Root motion takes priority over standard\nmovement physics. In network games, ensure gameplay triggers the montage consistently; GAS can\nsynchronize ability-owned montages/root motion. Route blend/slot details to\n`$unreal-animation-blending`.\n","searchText":"special movement patterns launch use launchcharacter for an impulse-like velocity change that should enter the character movement pipeline. decide independently whether xy/z override existing velocity. test authority, prediction/correction, landing, air control, and repeated launches. a launch is not a duration- controlled dash. teleport for network play: 1. validate the destination on the server. 2. use a supported setlocation path with teleport behavior or the teleport blueprint node. 3. ensure collision/encroachment policy matches the design. 4. expect clients to snap rather than smooth the teleport. do not move the owning client first with ordinary transform changes and expect cmc prediction to accept it. root motion source use for short programmatic motion needing character root-motion networking, such as move-to or jump-force behavior. 1. select/create the appropriate frootmotionsource variant. 2. set duration, priority/accumulation, start/target, and finish behavior. 3. apply through ucharactermovementcomponent::applyrootmotionsource on the appropriate prediction/authority path. 4. retain the returned handle/id. 5. remove with removerootmotionsource when canceled or finished if required by the pattern. 6. test server rejection, collision, moving targets, and montage/root-motion competition. gas provides ability tasks that use root motion sources; prefer those when the ability owns activation, cancellation, and prediction. custom movement mode 1. allocate a stable custom sub-mode byte/enum. 2. enter through setmovementmode(movecustom, submode). 3. implement updatecustommovement in character blueprint for prototypes, or override physcustom in a custom cmc for production control. 4. perform swept movement and define collision, floor, velocity, gravity, and exit rules. 5. serialize any custom input/state the server needs through saved-move/network move data. 6. return to walking/falling/etc. through an explicit exit condition. movecustom suspends normal movement physics. failing to implement gravity, collision, or velocity semantics is not an engine bug. montage root motion use for animation-authored committed actions. root motion takes priority over standard movement physics. in network games, ensure gameplay triggers the montage consistently; gas can synchronize ability-owned montages/root motion. route blend/slot details to $unreal-animation-blending."},{"slug":"system-selector","file":"system-selector.md","title":"Movement system selector","rawMarkdown":"# Movement system selector\n\n| Need | Use | Reason / warning |\n|---|---|---|\n| Standard humanoid capsule movement and mature multiplayer support | `ACharacter` + `UCharacterMovementComponent` | Walking/falling/swimming/flying/custom modes, prediction, correction, smoothing |\n| A special mode integrated with normal Character movement | CMC `MOVE_Custom` + custom sub-mode | Standard physics are suspended while custom physics run; custom state may need saved-move serialization |\n| Short deterministic/programmatic ability movement | Root Motion Source or GAS root-motion Ability Task | Participates in Character root-motion networking when used correctly |\n| Animation-authored committed movement | Montage root motion | Root motion takes priority over normal movement physics; gameplay must synchronize montage execution |\n| Modular mode/layered-move architecture and willingness to carry experimental risk | Mover | Epic labels Mover Experimental in UE 5.8 |\n| Vehicle, rolling body, non-capsule creature, or unconventional physics | Purpose-built Pawn/movement system | Character and CMC are designed together around Character movement assumptions |\n\n## Selection procedure\n\n1. Define collision shape and whether the entity must use `ACharacter`.\n2. List movement modes and which may overlap as temporary layered moves.\n3. State single-player/multiplayer, authority, prediction, and rollback requirements.\n4. State whether motion is code-driven, animation-driven, or selected per action.\n5. Choose the most mature framework that satisfies the requirements.\n6. If choosing Mover, record experimental status, engine-version lock, fallback cost, and a\n   packaged multiplayer prototype milestone before committing production content.\n\nDo not migrate from CMC merely because custom movement requires C++. The deciding question is\nwhether CMC's Character/capsule/mode/network model still fits the game.\n","webMarkdown":"| Need | Use | Reason / warning |\n|---|---|---|\n| Standard humanoid capsule movement and mature multiplayer support | `ACharacter` + `UCharacterMovementComponent` | Walking/falling/swimming/flying/custom modes, prediction, correction, smoothing |\n| A special mode integrated with normal Character movement | CMC `MOVE_Custom` + custom sub-mode | Standard physics are suspended while custom physics run; custom state may need saved-move serialization |\n| Short deterministic/programmatic ability movement | Root Motion Source or GAS root-motion Ability Task | Participates in Character root-motion networking when used correctly |\n| Animation-authored committed movement | Montage root motion | Root motion takes priority over normal movement physics; gameplay must synchronize montage execution |\n| Modular mode/layered-move architecture and willingness to carry experimental risk | Mover | Epic labels Mover Experimental in UE 5.8 |\n| Vehicle, rolling body, non-capsule creature, or unconventional physics | Purpose-built Pawn/movement system | Character and CMC are designed together around Character movement assumptions |\n\n## Selection procedure\n\n1. Define collision shape and whether the entity must use `ACharacter`.\n2. List movement modes and which may overlap as temporary layered moves.\n3. State single-player/multiplayer, authority, prediction, and rollback requirements.\n4. State whether motion is code-driven, animation-driven, or selected per action.\n5. Choose the most mature framework that satisfies the requirements.\n6. If choosing Mover, record experimental status, engine-version lock, fallback cost, and a\n   packaged multiplayer prototype milestone before committing production content.\n\nDo not migrate from CMC merely because custom movement requires C++. The deciding question is\nwhether CMC's Character/capsule/mode/network model still fits the game.\n","searchText":"movement system selector | need | use | reason / warning | |---|---|---| | standard humanoid capsule movement and mature multiplayer support | acharacter + ucharactermovementcomponent | walking/falling/swimming/flying/custom modes, prediction, correction, smoothing | | a special mode integrated with normal character movement | cmc movecustom + custom sub-mode | standard physics are suspended while custom physics run; custom state may need saved-move serialization | | short deterministic/programmatic ability movement | root motion source or gas root-motion ability task | participates in character root-motion networking when used correctly | | animation-authored committed movement | montage root motion | root motion takes priority over normal movement physics; gameplay must synchronize montage execution | | modular mode/layered-move architecture and willingness to carry experimental risk | mover | epic labels mover experimental in ue 5.8 | | vehicle, rolling body, non-capsule creature, or unconventional physics | purpose-built pawn/movement system | character and cmc are designed together around character movement assumptions | selection procedure 1. define collision shape and whether the entity must use acharacter. 2. list movement modes and which may overlap as temporary layered moves. 3. state single-player/multiplayer, authority, prediction, and rollback requirements. 4. state whether motion is code-driven, animation-driven, or selected per action. 5. choose the most mature framework that satisfies the requirements. 6. if choosing mover, record experimental status, engine-version lock, fallback cost, and a packaged multiplayer prototype milestone before committing production content. do not migrate from cmc merely because custom movement requires c++. the deciding question is whether cmc's character/capsule/mode/network model still fits the game."},{"slug":"troubleshooting","file":"troubleshooting.md","title":"Troubleshooting","rawMarkdown":"# Troubleshooting\n\n## Character slides after input release\n\n- Raise braking deceleration and/or effective braking friction deliberately.\n- Check `bUseSeparateBrakingFriction`, `BrakingFriction`, and factor interaction.\n- Distinguish no-input stopping from direction-change grip.\n\n## Direction changes feel slow despite high acceleration\n\n- Check GroundFriction and effective input magnitude.\n- Check rotation ownership/rate if facing, not velocity, is the slow part.\n- Measure velocity change separately from mesh turn animation.\n\n## Cannot climb a small step\n\n- Compare collision height with `MaxStepHeight`.\n- Confirm the upper surface is walkable and the capsule has clearance.\n- Inspect collision seams and blocking channels.\n- Test without decorative mesh collision overriding intended simple collision.\n\n## Stands on implausibly tiny edges\n\n- Review `PerchRadiusThreshold`, capsule radius, and ledge geometry.\n- Visualize collision/floor results; do not judge by skeletal mesh feet.\n\n## Jump varies with frame rate\n\n- Remove manual per-frame velocity/position increments lacking delta-time/physics integration.\n- Verify variable jump release is bound correctly.\n- Check custom movement simulation time steps/iterations under low frame rate.\n\n## Constant server corrections\n\n- Confirm client and server use identical parameters and custom state.\n- Serialize state that changes movement physics.\n- Prevent incompatible saved moves from combining.\n- Remove client-only transform changes.\n- Fix divergence before changing smoothing or correction thresholds.\n\n## Remote character jitters\n\n- First determine whether authoritative capsule is correcting or only mesh smoothing looks bad.\n- Inspect update rate, packet conditions, moving base, and custom-mode replication.\n- Tune smoothing only after deterministic movement is correct.\n\n## Root motion fights movement\n\n- Confirm root-motion extraction mode and asset settings.\n- Remember root motion takes precedence over normal movement physics.\n- Do not also drive the same action with Launch/SetLocation/velocity.\n- Ensure montage start/cancel is synchronized across network roles.\n\n## Custom mode floats or tunnels\n\n- `MOVE_Custom` suspends standard physics; implement gravity, velocity, swept collision, floor,\n  sub-stepping, and exit behavior explicitly.\n- Prefer C++ `PhysCustom` for complex production modes.\n","webMarkdown":"## Character slides after input release\n\n- Raise braking deceleration and/or effective braking friction deliberately.\n- Check `bUseSeparateBrakingFriction`, `BrakingFriction`, and factor interaction.\n- Distinguish no-input stopping from direction-change grip.\n\n## Direction changes feel slow despite high acceleration\n\n- Check GroundFriction and effective input magnitude.\n- Check rotation ownership/rate if facing, not velocity, is the slow part.\n- Measure velocity change separately from mesh turn animation.\n\n## Cannot climb a small step\n\n- Compare collision height with `MaxStepHeight`.\n- Confirm the upper surface is walkable and the capsule has clearance.\n- Inspect collision seams and blocking channels.\n- Test without decorative mesh collision overriding intended simple collision.\n\n## Stands on implausibly tiny edges\n\n- Review `PerchRadiusThreshold`, capsule radius, and ledge geometry.\n- Visualize collision/floor results; do not judge by skeletal mesh feet.\n\n## Jump varies with frame rate\n\n- Remove manual per-frame velocity/position increments lacking delta-time/physics integration.\n- Verify variable jump release is bound correctly.\n- Check custom movement simulation time steps/iterations under low frame rate.\n\n## Constant server corrections\n\n- Confirm client and server use identical parameters and custom state.\n- Serialize state that changes movement physics.\n- Prevent incompatible saved moves from combining.\n- Remove client-only transform changes.\n- Fix divergence before changing smoothing or correction thresholds.\n\n## Remote character jitters\n\n- First determine whether authoritative capsule is correcting or only mesh smoothing looks bad.\n- Inspect update rate, packet conditions, moving base, and custom-mode replication.\n- Tune smoothing only after deterministic movement is correct.\n\n## Root motion fights movement\n\n- Confirm root-motion extraction mode and asset settings.\n- Remember root motion takes precedence over normal movement physics.\n- Do not also drive the same action with Launch/SetLocation/velocity.\n- Ensure montage start/cancel is synchronized across network roles.\n\n## Custom mode floats or tunnels\n\n- `MOVE_Custom` suspends standard physics; implement gravity, velocity, swept collision, floor,\n  sub-stepping, and exit behavior explicitly.\n- Prefer C++ `PhysCustom` for complex production modes.\n","searchText":"troubleshooting character slides after input release - raise braking deceleration and/or effective braking friction deliberately. - check buseseparatebrakingfriction, brakingfriction, and factor interaction. - distinguish no-input stopping from direction-change grip. direction changes feel slow despite high acceleration - check groundfriction and effective input magnitude. - check rotation ownership/rate if facing, not velocity, is the slow part. - measure velocity change separately from mesh turn animation. cannot climb a small step - compare collision height with maxstepheight. - confirm the upper surface is walkable and the capsule has clearance. - inspect collision seams and blocking channels. - test without decorative mesh collision overriding intended simple collision. stands on implausibly tiny edges - review perchradiusthreshold, capsule radius, and ledge geometry. - visualize collision/floor results; do not judge by skeletal mesh feet. jump varies with frame rate - remove manual per-frame velocity/position increments lacking delta-time/physics integration. - verify variable jump release is bound correctly. - check custom movement simulation time steps/iterations under low frame rate. constant server corrections - confirm client and server use identical parameters and custom state. - serialize state that changes movement physics. - prevent incompatible saved moves from combining. - remove client-only transform changes. - fix divergence before changing smoothing or correction thresholds. remote character jitters - first determine whether authoritative capsule is correcting or only mesh smoothing looks bad. - inspect update rate, packet conditions, moving base, and custom-mode replication. - tune smoothing only after deterministic movement is correct. root motion fights movement - confirm root-motion extraction mode and asset settings. - remember root motion takes precedence over normal movement physics. - do not also drive the same action with launch/setlocation/velocity. - ensure montage start/cancel is synchronized across network roles. custom mode floats or tunnels - movecustom suspends standard physics; implement gravity, velocity, swept collision, floor, sub-stepping, and exit behavior explicitly. - prefer c++ physcustom for complex production modes."}]}
{"slug":"unreal-control-rig-ik","name":"unreal-control-rig-ik","title":"Unreal 5.8 Control Rig and IK","description":"Build, retarget, procedurally adjust, bake, and debug skeletal animation in Unreal Engine 5.8. Use for IK Rig, IK Retargeter, retarget chains and poses, the retarget operation stack, runtime Retarget Pose From Mesh, root or pelvis drift, foot sliding, hand or weapon offsets, Control Rig, Full Body IK, foot placement, backward knees or elbows, Sequencer rigging, or baking animation.","shortDescription":"Build and debug Unreal IK and retargeting","category":"Animation","referenceCount":10,"rawMarkdown":"---\nname: unreal-control-rig-ik\ndescription: Build, retarget, procedurally adjust, bake, and debug skeletal animation in Unreal Engine 5.8. Use for IK Rig, IK Retargeter, retarget chains and poses, the retarget operation stack, runtime Retarget Pose From Mesh, root or pelvis drift, foot sliding, hand or weapon offsets, Control Rig, Full Body IK, foot placement, backward knees or elbows, Sequencer rigging, or baking animation.\n---\n\n# Unreal 5.8 Control Rig and IK\n\n## Ownership boundary\n\nThis skill owns skeleton transfer, IK Retargeter setup, retarget poses/operations, procedural solves,\ncontact correction, and animation baking. If a retargeted preview/export is correct but the final pose\nis wrong, route to [`unreal-animation-blending`](../unreal-animation-blending/SKILL.md). Route capsule\nmovement, root-motion authority, and network prediction to\n[`unreal-character-movement`](../unreal-character-movement/SKILL.md).\n\n## Route before editing\n\nRead [`references/system-selector.md`](references/system-selector.md).\n\n- Transfer animation between skeletons -> IK Rig + IK Retargeter.\n- Retarget live from another component -> Retarget Pose From Mesh.\n- Procedurally solve a connected body -> Full Body IK.\n- Adjust a few limbs at runtime -> IK Rig node or focused IK nodes.\n- Author or repair poses/animation -> Control Rig or FK Control Rig in Sequencer.\n- Pin contacts after the base transfer is correct -> goals, Speed Planting, or foot placement.\n\nDo not add IK until the source animation, skeleton assignment, chain map, retarget pose,\npelvis, and root behavior have been checked.\n\n## Diagnose first when the request is a bug\n\nRead [`references/symptom-diagnostics.md`](references/symptom-diagnostics.md), then reproduce\nwith one source sequence and one target mesh. Record whether the defect appears in the IK\nRetargeter preview, an exported sequence, runtime retargeting, or only the final AnimGraph.\n\n## Execute\n\n1. Classify the job and isolate the first stage where the pose becomes wrong.\n2. Verify source animation, source/target meshes, skeletons, reference poses, and root bones.\n3. Define matching retarget roots and chains; inspect every chain mapping.\n4. Create and align a dedicated retarget pose.\n5. Validate the operation stack from top to bottom, enabling one correction at a time.\n6. Add goals/solvers only for contacts or procedural controls that need them.\n7. Verify root motion, curves, notifies, runtime component order, LOD, and hidden-mesh ticking.\n8. Test representative clips at speed; profile and bake only after the live result is correct.\n\nLoad only what applies:\n\n- [`references/ik-retargeter-setup.md`](references/ik-retargeter-setup.md)\n- [`references/poses-chains-and-operations.md`](references/poses-chains-and-operations.md)\n- [`references/root-pelvis-and-contact.md`](references/root-pelvis-and-contact.md)\n- [`references/runtime-retargeting.md`](references/runtime-retargeting.md)\n- [`references/control-rig-and-fbik.md`](references/control-rig-and-fbik.md)\n- [`references/runtime-foot-placement.md`](references/runtime-foot-placement.md)\n- [`references/sequencer-and-baking.md`](references/sequencer-and-baking.md)\n\n## Required answer format\n\nReturn:\n\n1. **First broken stage** and evidence.\n2. **Chosen system** and rejected alternatives.\n3. **Required assets, roots, chains, goals, solvers, and pose assumptions**.\n4. **Exact editor/runtime node order and settings to inspect or change**.\n5. **One-change-at-a-time diagnostic procedure**.\n6. **Root-motion, curve, notify, networking, LOD, and performance consequences**.\n7. **Acceptance clips and debug checks**.\n\n## Hard rules\n\n- Set a retarget root on both IK Rigs, normally the pelvis/hips for bipeds.\n- Chain names may differ, but source and target chain intent and boundaries must match.\n- Create a new retarget pose for alignment; preserve the default pose as a baseline.\n- A Retarget Pose operation belongs first in the operation stack.\n- Prefer no FK translation for most chains; change translation mode only for a diagnosed need.\n- An IK operation cannot move a chain unless the target chain has an IK goal.\n- Fix chains, pose, pelvis, root, and speed before masking foot slide with Speed Planting.\n- `Ignore Root Lock in Preview` is preview-only; export behavior uses export root-lock settings.\n- A hidden runtime source mesh must still tick pose and refresh bones.\n- Inertialization normally belongs before final IK; runtime IK belongs after the base pose exists.\n- Treat Modular Control Rig according to its Experimental UE 5.8 maturity; do not silently make\n  it a shipping dependency.\n- Test multiple clips, not only the editor reference pose or one idle.\n\nSee [`references/sources.md`](references/sources.md) for the UE 5.8 source trail.\n","webMarkdown":"## Ownership boundary\n\nThis skill owns skeleton transfer, IK Retargeter setup, retarget poses/operations, procedural solves,\ncontact correction, and animation baking. If a retargeted preview/export is correct but the final pose\nis wrong, route to [`unreal-animation-blending`](/unreal/unreal-animation-blending/). Route capsule\nmovement, root-motion authority, and network prediction to\n[`unreal-character-movement`](/unreal/unreal-character-movement/).\n\n## Route before editing\n\nRead [`references/system-selector.md`](/unreal/unreal-control-rig-ik/system-selector/).\n\n- Transfer animation between skeletons -> IK Rig + IK Retargeter.\n- Retarget live from another component -> Retarget Pose From Mesh.\n- Procedurally solve a connected body -> Full Body IK.\n- Adjust a few limbs at runtime -> IK Rig node or focused IK nodes.\n- Author or repair poses/animation -> Control Rig or FK Control Rig in Sequencer.\n- Pin contacts after the base transfer is correct -> goals, Speed Planting, or foot placement.\n\nDo not add IK until the source animation, skeleton assignment, chain map, retarget pose,\npelvis, and root behavior have been checked.\n\n## Diagnose first when the request is a bug\n\nRead [`references/symptom-diagnostics.md`](/unreal/unreal-control-rig-ik/symptom-diagnostics/), then reproduce\nwith one source sequence and one target mesh. Record whether the defect appears in the IK\nRetargeter preview, an exported sequence, runtime retargeting, or only the final AnimGraph.\n\n## Execute\n\n1. Classify the job and isolate the first stage where the pose becomes wrong.\n2. Verify source animation, source/target meshes, skeletons, reference poses, and root bones.\n3. Define matching retarget roots and chains; inspect every chain mapping.\n4. Create and align a dedicated retarget pose.\n5. Validate the operation stack from top to bottom, enabling one correction at a time.\n6. Add goals/solvers only for contacts or procedural controls that need them.\n7. Verify root motion, curves, notifies, runtime component order, LOD, and hidden-mesh ticking.\n8. Test representative clips at speed; profile and bake only after the live result is correct.\n\nLoad only what applies:\n\n- [`references/ik-retargeter-setup.md`](/unreal/unreal-control-rig-ik/ik-retargeter-setup/)\n- [`references/poses-chains-and-operations.md`](/unreal/unreal-control-rig-ik/poses-chains-and-operations/)\n- [`references/root-pelvis-and-contact.md`](/unreal/unreal-control-rig-ik/root-pelvis-and-contact/)\n- [`references/runtime-retargeting.md`](/unreal/unreal-control-rig-ik/runtime-retargeting/)\n- [`references/control-rig-and-fbik.md`](/unreal/unreal-control-rig-ik/control-rig-and-fbik/)\n- [`references/runtime-foot-placement.md`](/unreal/unreal-control-rig-ik/runtime-foot-placement/)\n- [`references/sequencer-and-baking.md`](/unreal/unreal-control-rig-ik/sequencer-and-baking/)\n\n## Required answer format\n\nReturn:\n\n1. **First broken stage** and evidence.\n2. **Chosen system** and rejected alternatives.\n3. **Required assets, roots, chains, goals, solvers, and pose assumptions**.\n4. **Exact editor/runtime node order and settings to inspect or change**.\n5. **One-change-at-a-time diagnostic procedure**.\n6. **Root-motion, curve, notify, networking, LOD, and performance consequences**.\n7. **Acceptance clips and debug checks**.\n\n## Hard rules\n\n- Set a retarget root on both IK Rigs, normally the pelvis/hips for bipeds.\n- Chain names may differ, but source and target chain intent and boundaries must match.\n- Create a new retarget pose for alignment; preserve the default pose as a baseline.\n- A Retarget Pose operation belongs first in the operation stack.\n- Prefer no FK translation for most chains; change translation mode only for a diagnosed need.\n- An IK operation cannot move a chain unless the target chain has an IK goal.\n- Fix chains, pose, pelvis, root, and speed before masking foot slide with Speed Planting.\n- `Ignore Root Lock in Preview` is preview-only; export behavior uses export root-lock settings.\n- A hidden runtime source mesh must still tick pose and refresh bones.\n- Inertialization normally belongs before final IK; runtime IK belongs after the base pose exists.\n- Treat Modular Control Rig according to its Experimental UE 5.8 maturity; do not silently make\n  it a shipping dependency.\n- Test multiple clips, not only the editor reference pose or one idle.\n\nSee [`references/sources.md`](/unreal/unreal-control-rig-ik/sources/) for the UE 5.8 source trail.\n","searchText":"unreal 5.8 control rig and ik build, retarget, procedurally adjust, bake, and debug skeletal animation in unreal engine 5.8. use for ik rig, ik retargeter, retarget chains and poses, the retarget operation stack, runtime retarget pose from mesh, root or pelvis drift, foot sliding, hand or weapon offsets, control rig, full body ik, foot placement, backward knees or elbows, sequencer rigging, or baking animation. control rig and full body ik control rig and full body ik control rig setup 1. right-click a skeletal mesh -> create -> control rig. 2. keep controls in a clear control hierarchy adjacent to the imported skeleton. 3. use forward solve for controls-to-bones runtime evaluation. 4. use backwards solve when bones must drive controls for baking or round-tripping. 5. use construction event for setup that depends on the rig hierarchy. 6. compile after hierarchy, variable, or structural graph changes; auto-compile does not cover every change. full body ik 1. enable the fullbodyik plugin and restart if required. 2. add the fbik node to forward solve. 3. choose a solver root, commonly pelvis/hips for a biped. 4. add effectors only for endpoints that need targets. 5. drive targets from controls or validated gameplay-space transforms. 6. tune position/rotation stiffness: 0 allows movement, 1 resists/locks it. 7. enable and set preferred angles for stable knee/elbow bending. 8. configure limits only where anatomy or design requires them. 9. exclude irrelevant bones rather than making every bone fully stiff. diagnostic order - confirm control/goal transform space. - confirm solver root and affected hierarchy. - move one effector with all others disabled. - check preferred bend direction before adding more stiffness. - add constraints one at a time. - test unreachable targets and singular straight-limb poses. modular control rig is experimental in ue 5.8. use it only with an explicit maturity decision. ik rig and retargeter setup ik rig and retargeter setup build the minimum transfer 1. create one ik rig for the source skeletal mesh and one for the target. 2. in each ik rig, set the retarget root. for a biped this is normally pelvis/hips, not the scene root, because it carries proportional body translation. 3. create chains for matching semantic regions: root/pelvis as appropriate, spine, neck, head, each arm, each leg, and optional fingers or accessory chains. 4. give every chain an exact start and end bone. a single-bone chain is valid. 5. add ik goals only to chains that need goal-based retarget operations or runtime solving. 6. create an ik retargeter: content browser -> add -> animation -> ik rig -> ik retargeter. 7. assign source/target ik rigs and preview meshes. 8. verify chain mapping manually, even if auto map or auto create retarget chains succeeds. 9. preview idle, locomotion, turns, crouch, jumps, extremes, and any root-motion clips. 10. export only after the preview and output log are clean. chain rules - map by function, not by coincidental name. - do not let a leg chain begin at the pelvis or end at an ik marker unless that is intentional. - separate fingers when independent finger motion matters; omit them when it does not. - include twist/helper bones only when their transfer is understood; otherwise let the target skeleton's deformation setup handle them. - use the retarget output log for missing or incompatible chain warnings. automation is a draft, not proof auto retarget chains uses name matching and common templates. auto align can substantially accelerate setup. both must be verified on the target skeleton, especially with unusual names, extra roots, asymmetric rigs, nonhuman proportions, or different reference stances. retarget poses, chains, and operation stack retarget poses, chains, and operation stack pose alignment 1. create a named target retarget pose; do not overwrite the baseline without a reason. 2. compare source and target in reference-pose view. 3. align large axes first: pelvis facing, spine, clavicles, upper/lower arms, hands, thighs, calves, feet, and toes. 4. use auto align as a starting point. direction, local/global rotation axes, and mesh methods solve different mismatches; inspect every limb afterward. 5. snap the character to ground when vertical reference offsets differ. 6. scrub retarget pose blend between 0 and 1 to distinguish reference-pose error from the stored correction. operation stack discipline operations evaluate top to bottom. disable all nonessential corrections, establish a clean fk transfer, then enable one operation at a time. - retarget pose: first in the stack; selects stored source/target pose overrides. - pelvis motion: transfers and constrains pelvis movement; tune floor/crotch offsets only after the retarget roots and poses are correct. - fk chains: maps rotations/translations by chain. - root motion: copies source root or generates it from target pelvis. - run ik rig: applies goal-based target solving. - pin bones / goal offsets / floor constraints: late corrections for explicit contacts. - remap curves: needed when semantic curves have different names. fk modes - interpolated rotation: default choice when chain lengths, proportions, or bone counts differ. - one to one: corresponding bones transfer directly; use when counts and intent match. - one to one reversed: maps from chain ends; useful only when the end is the stable anchor. - none: exclude the chain from fk rotation transfer. - translation none: preferred for most chains. - globally scaled / absolute / stretch modes: use only for a specific diagnosed translation requirement; verify deformation and root behavior across clips. use profile ops to find an unexpectedly expensive retarget operation. root, pelvis, feet, and hand contact root, pelvis, feet, and hand contact root/pelvis order 1. confirm the source sequence contains the motion you expect. 2. confirm both retarget roots and actual skeleton root/pelvis hierarchy. 3. establish pelvis transfer before adding root generation. 4. in root motion, choose either copy from source root or generate from target pelvis according to the source data. do not combine two owners of translation. 5. choose root height intentionally: copy source height or snap to ground. 6. inspect maintain pelvis offset, child updates, global offsets, and pelvis-yaw contribution. 7. test export separately; preview root-lock overrides do not define exported behavior. symptom mapping - whole character floats/sinks -> retarget pose ground, pelvis operation, root height, mesh scale. - pelvis stays while feet move -> retarget root, pelvis source/target, fk translation mode. - double translation -> root motion applied in both retarget/export and gameplay movement. - character rotates unexpectedly -> pelvis yaw/root rotation settings or incorrect root basis. - feet penetrate only on slopes -> runtime ground solution, not a retarget-pose correction. contact correction use speed planting only after the base motion matches. it needs: - target leg chains with ik goals and a functioning ik solver; - source curves that identify foot-bone speed/contact, often generated with animation data modifiers; - thresholds tested across walk, run, start, stop, turn, and uneven ground. for hands or weapon markers, first correct arm/hand chains and retarget pose. use pin bones for special bones such as a weapon ik marker that must follow a target hand, then apply small goal offsets. never compensate for a wrong chain map with a large per-animation hand offset. runtime foot placement and focused ik runtime foot placement and focused ik use runtime foot placement when contacts depend on current world geometry. retarget poses and speed planting solve different problems: the former aligns skeletons, the latter preserves source contact, while runtime foot placement adapts to live terrain. procedure 1. begin with a correct locomotion pose. 2. trace from a stable foot reference toward the walkable surface using the same collision assumptions as character movement. 3. reject invalid, distant, vertical, or non-walkable hits. 4. convert hit position/normal into the exact component/bone space expected by the solver. 5. solve feet, then derive pelvis compensation from the reachable leg with the limiting offset. 6. clamp leg extension and pelvis displacement; define behavior when no ground is found. 7. smooth target positions and normals over time without adding visible lag. 8. apply after locomotion blending/inertialization and before any later presentation-only pass that intentionally depends on the solved pose. failure patterns - feet snap -> unsmoothed target or discontinuous trace result. - knees invert -> missing preferred bend/pole direction or target crosses singularity. - legs stretch -> no reach clamp or pelvis compensation. - feet hover on stairs -> trace origin/distance or capsule-to-mesh offset mismatch. - correct on flat ground, wrong on moving platforms -> target stored in world space without platform-relative handling. - network jitter -> cosmetic client solve is consuming discontinuous replicated movement; smooth movement first and avoid replicating trace results unless gameplay requires them. validate flat ground, ramps, individual steps, stair runs, ledges, moving bases, sudden falls, crouch, turns, and low animation lods. runtime retargeting runtime retargeting retarget pose from mesh 1. on the target animation blueprint, place retarget pose from mesh as the base pose source. 2. assign the ik retargeter asset. 3. either enable use attached parent and parent the target skeletal mesh component to the source skeletal mesh component, or explicitly provide the source mesh component. 4. if the source mesh is hidden, set its visibility based anim tick option to always tick pose and refresh bones. 5. apply target-only overlays or ik after the retargeted base pose. 6. use retarget profiles when gameplay must override supported operation settings at runtime. runtime failure gates - frozen/default target -> wrong source component, wrong parent, missing retargeter, or source not ticking. - one-frame lag -> component tick prerequisite/order; ensure source updates before target. - preview works, runtime breaks -> component hierarchy, lod, visibility tick, graph order, runtime profile. - correct close-up, wrong at distance -> lod strips required bones or disables the solver/node. - different clients disagree -> replicate gameplay state/targets, not final cosmetic bone transforms, unless the design explicitly requires pose replication. runtime retargeting saves exported assets and supports dynamic source characters, but it adds per-frame work. profile the target platform and prefer exported sequences when runtime flexibility does not justify the cost. sequencer, authoring, and baking sequencer, authoring, and baking choose the authoring path - use control rig in sequencer for reusable controls and procedural relationships. - use fk control rig for fast additive per-bone repair. - use backwards solve when an existing animation must populate controls. - bake when runtime evaluation is unnecessary, compatibility matters, or the result must become a normal animation sequence. bake gates 1. duplicate or version the source asset. 2. confirm display rate, sample rate, sequence range, root behavior, and additive intent. 3. evaluate the complete source graph, including any warmup needed for procedural state. 4. bake transforms and required curves; choose local/world evaluation intentionally. 5. reduce keys only after visually comparing the unreduced bake; tune tolerance against the smallest important contact or facial motion. 6. recheck notifies and metadata because transform baking does not automatically preserve every semantic event contract. 7. test the resulting animation sequence outside sequencer and in a cooked build. keep a reversible path: source sequence/rig, settings, and generated output should be distinct. ue 5.8 primary sources ue 5.8 primary sources - ik rig animation retargeting - retargeting bipeds with ik rig - retargeting operation stack in ue 5.8 - auto retargeting - runtime ik retargeting - animating ik retarget settings / retarget profiles - fix foot sliding with ik retargeter - ik rig - ik rig in animation blueprints - control rig - create control rigs - full-body ik - fk control rig - control rig editor - root motion pages were checked against the ue 5.8 documentation on 2026-07-19. reconfirm feature maturity and property names after an engine upgrade. symptom-first diagnostics symptom-first diagnostics isolation ladder 1. play the source animation sequence on its intended source mesh. 2. preview the ik retargeter with all optional operations disabled. 3. validate chain map and dedicated retarget pose. 4. enable pelvis, fk, root, ik, pin/contact, and curve operations one at a time. 5. export one sequence and play it directly on the target. 6. test runtime retarget pose from mesh without target overlays. 7. re-enable the final animgraph from base pose outward. the first failing rung owns the investigation. | symptom | inspect first | then | |---|---|---| | target frozen or stale | source mesh tick, source component, attached parent | graph order, lod | | limbs explode/contort | chain start/end/map | retarget pose axes, fk rotation mode | | knees/elbows bend backward | pose bend direction | preferred angles, goal space | | floating or sinking | ground alignment, pelvis op | root height, floor constraint | | foot sliding | source speed vs target motion | speed planting curves/goals | | hand/weapon offset | arm/hand chains and pose | pin bones, goal offsets | | root motion absent | source root data and root op | export/root-motion settings, movement owner | | root motion doubled | duplicate translation owner | animbp/movement integration | | preview correct, export wrong | export root-lock mode | curves/bake settings | | preview correct, runtime wrong | component parent/source/tick | profile, lod, node order | | works near camera only | animation/solver lod | required bone stripping | capture: source/target asset names, skeleton roots, retarget roots, chain map, retarget pose name, operation stack order, runtime component hierarchy, node order, and the shortest failing clip. do not tune several offsets at once. system selector system selector | need | primary system | avoid when | |---|---|---| | reuse animation on another skeleton | ik rig + ik retargeter | skeletons are already compatible enough for compatible skeletons | | drive a target from a live source mesh | retarget pose from mesh | offline export is simpler and runtime flexibility is unnecessary | | correct whole-body reach/stance | full body ik | a single two-bone limb solve is sufficient | | runtime goal-driven limbs | ik rig node / focused ik | the change is authored and should be baked | | animate controls in sequencer | control rig | only a small additive bone correction is needed | | quick per-bone additive repair | fk control rig | a reusable procedural rig is required | | preserve planted contacts during retarget | speed planting after base retarget | the real fault is chain, pose, pelvis, root, or speed mismatch | decision gates: 1. is this transfer, procedural correction, or authoring? 2. must it remain live at runtime? 3. does it require one limb or a connected full-body response? 4. does gameplay need to drive the goal, or can the result be baked? 5. is the problem already visible before ik? if yes, fix that stage first. keep ownership explicit: gameplay produces targets; the animation graph consumes targets; ik solves the pose. do not move authoritative gameplay state into a rig graph.","references":[{"slug":"control-rig-and-fbik","file":"control-rig-and-fbik.md","title":"Control Rig and Full Body IK","rawMarkdown":"# Control Rig and Full Body IK\n\n## Control Rig setup\n\n1. Right-click a Skeletal Mesh -> Create -> Control Rig.\n2. Keep controls in a clear control hierarchy adjacent to the imported skeleton.\n3. Use **Forward Solve** for controls-to-bones runtime evaluation.\n4. Use **Backwards Solve** when bones must drive controls for baking or round-tripping.\n5. Use **Construction Event** for setup that depends on the rig hierarchy.\n6. Compile after hierarchy, variable, or structural graph changes; auto-compile does not cover\n   every change.\n\n## Full Body IK\n\n1. Enable the FullBodyIK plugin and restart if required.\n2. Add the FBIK node to Forward Solve.\n3. Choose a solver root, commonly pelvis/hips for a biped.\n4. Add effectors only for endpoints that need targets.\n5. Drive targets from controls or validated gameplay-space transforms.\n6. Tune Position/Rotation Stiffness: 0 allows movement, 1 resists/locks it.\n7. Enable and set Preferred Angles for stable knee/elbow bending.\n8. Configure limits only where anatomy or design requires them.\n9. Exclude irrelevant bones rather than making every bone fully stiff.\n\n## Diagnostic order\n\n- Confirm control/goal transform space.\n- Confirm solver root and affected hierarchy.\n- Move one effector with all others disabled.\n- Check preferred bend direction before adding more stiffness.\n- Add constraints one at a time.\n- Test unreachable targets and singular straight-limb poses.\n\nModular Control Rig is Experimental in UE 5.8. Use it only with an explicit maturity decision.\n","webMarkdown":"## Control Rig setup\n\n1. Right-click a Skeletal Mesh -> Create -> Control Rig.\n2. Keep controls in a clear control hierarchy adjacent to the imported skeleton.\n3. Use **Forward Solve** for controls-to-bones runtime evaluation.\n4. Use **Backwards Solve** when bones must drive controls for baking or round-tripping.\n5. Use **Construction Event** for setup that depends on the rig hierarchy.\n6. Compile after hierarchy, variable, or structural graph changes; auto-compile does not cover\n   every change.\n\n## Full Body IK\n\n1. Enable the FullBodyIK plugin and restart if required.\n2. Add the FBIK node to Forward Solve.\n3. Choose a solver root, commonly pelvis/hips for a biped.\n4. Add effectors only for endpoints that need targets.\n5. Drive targets from controls or validated gameplay-space transforms.\n6. Tune Position/Rotation Stiffness: 0 allows movement, 1 resists/locks it.\n7. Enable and set Preferred Angles for stable knee/elbow bending.\n8. Configure limits only where anatomy or design requires them.\n9. Exclude irrelevant bones rather than making every bone fully stiff.\n\n## Diagnostic order\n\n- Confirm control/goal transform space.\n- Confirm solver root and affected hierarchy.\n- Move one effector with all others disabled.\n- Check preferred bend direction before adding more stiffness.\n- Add constraints one at a time.\n- Test unreachable targets and singular straight-limb poses.\n\nModular Control Rig is Experimental in UE 5.8. Use it only with an explicit maturity decision.\n","searchText":"control rig and full body ik control rig setup 1. right-click a skeletal mesh -> create -> control rig. 2. keep controls in a clear control hierarchy adjacent to the imported skeleton. 3. use forward solve for controls-to-bones runtime evaluation. 4. use backwards solve when bones must drive controls for baking or round-tripping. 5. use construction event for setup that depends on the rig hierarchy. 6. compile after hierarchy, variable, or structural graph changes; auto-compile does not cover every change. full body ik 1. enable the fullbodyik plugin and restart if required. 2. add the fbik node to forward solve. 3. choose a solver root, commonly pelvis/hips for a biped. 4. add effectors only for endpoints that need targets. 5. drive targets from controls or validated gameplay-space transforms. 6. tune position/rotation stiffness: 0 allows movement, 1 resists/locks it. 7. enable and set preferred angles for stable knee/elbow bending. 8. configure limits only where anatomy or design requires them. 9. exclude irrelevant bones rather than making every bone fully stiff. diagnostic order - confirm control/goal transform space. - confirm solver root and affected hierarchy. - move one effector with all others disabled. - check preferred bend direction before adding more stiffness. - add constraints one at a time. - test unreachable targets and singular straight-limb poses. modular control rig is experimental in ue 5.8. use it only with an explicit maturity decision."},{"slug":"ik-retargeter-setup","file":"ik-retargeter-setup.md","title":"IK Rig and Retargeter setup","rawMarkdown":"# IK Rig and Retargeter setup\n\n## Build the minimum transfer\n\n1. Create one IK Rig for the source Skeletal Mesh and one for the target.\n2. In each IK Rig, set the Retarget Root. For a biped this is normally pelvis/hips, not the\n   scene root, because it carries proportional body translation.\n3. Create chains for matching semantic regions: root/pelvis as appropriate, spine, neck,\n   head, each arm, each leg, and optional fingers or accessory chains.\n4. Give every chain an exact start and end bone. A single-bone chain is valid.\n5. Add IK Goals only to chains that need goal-based retarget operations or runtime solving.\n6. Create an IK Retargeter: Content Browser -> Add -> Animation -> IK Rig -> IK Retargeter.\n7. Assign source/target IK Rigs and preview meshes.\n8. Verify chain mapping manually, even if Auto Map or Auto Create Retarget Chains succeeds.\n9. Preview idle, locomotion, turns, crouch, jumps, extremes, and any root-motion clips.\n10. Export only after the preview and output log are clean.\n\n## Chain rules\n\n- Map by function, not by coincidental name.\n- Do not let a leg chain begin at the pelvis or end at an IK marker unless that is intentional.\n- Separate fingers when independent finger motion matters; omit them when it does not.\n- Include twist/helper bones only when their transfer is understood; otherwise let the target\n  skeleton's deformation setup handle them.\n- Use the Retarget Output Log for missing or incompatible chain warnings.\n\n## Automation is a draft, not proof\n\nAuto Retarget Chains uses name matching and common templates. Auto Align can substantially\naccelerate setup. Both must be verified on the target skeleton, especially with unusual names,\nextra roots, asymmetric rigs, nonhuman proportions, or different reference stances.\n","webMarkdown":"## Build the minimum transfer\n\n1. Create one IK Rig for the source Skeletal Mesh and one for the target.\n2. In each IK Rig, set the Retarget Root. For a biped this is normally pelvis/hips, not the\n   scene root, because it carries proportional body translation.\n3. Create chains for matching semantic regions: root/pelvis as appropriate, spine, neck,\n   head, each arm, each leg, and optional fingers or accessory chains.\n4. Give every chain an exact start and end bone. A single-bone chain is valid.\n5. Add IK Goals only to chains that need goal-based retarget operations or runtime solving.\n6. Create an IK Retargeter: Content Browser -> Add -> Animation -> IK Rig -> IK Retargeter.\n7. Assign source/target IK Rigs and preview meshes.\n8. Verify chain mapping manually, even if Auto Map or Auto Create Retarget Chains succeeds.\n9. Preview idle, locomotion, turns, crouch, jumps, extremes, and any root-motion clips.\n10. Export only after the preview and output log are clean.\n\n## Chain rules\n\n- Map by function, not by coincidental name.\n- Do not let a leg chain begin at the pelvis or end at an IK marker unless that is intentional.\n- Separate fingers when independent finger motion matters; omit them when it does not.\n- Include twist/helper bones only when their transfer is understood; otherwise let the target\n  skeleton's deformation setup handle them.\n- Use the Retarget Output Log for missing or incompatible chain warnings.\n\n## Automation is a draft, not proof\n\nAuto Retarget Chains uses name matching and common templates. Auto Align can substantially\naccelerate setup. Both must be verified on the target skeleton, especially with unusual names,\nextra roots, asymmetric rigs, nonhuman proportions, or different reference stances.\n","searchText":"ik rig and retargeter setup build the minimum transfer 1. create one ik rig for the source skeletal mesh and one for the target. 2. in each ik rig, set the retarget root. for a biped this is normally pelvis/hips, not the scene root, because it carries proportional body translation. 3. create chains for matching semantic regions: root/pelvis as appropriate, spine, neck, head, each arm, each leg, and optional fingers or accessory chains. 4. give every chain an exact start and end bone. a single-bone chain is valid. 5. add ik goals only to chains that need goal-based retarget operations or runtime solving. 6. create an ik retargeter: content browser -> add -> animation -> ik rig -> ik retargeter. 7. assign source/target ik rigs and preview meshes. 8. verify chain mapping manually, even if auto map or auto create retarget chains succeeds. 9. preview idle, locomotion, turns, crouch, jumps, extremes, and any root-motion clips. 10. export only after the preview and output log are clean. chain rules - map by function, not by coincidental name. - do not let a leg chain begin at the pelvis or end at an ik marker unless that is intentional. - separate fingers when independent finger motion matters; omit them when it does not. - include twist/helper bones only when their transfer is understood; otherwise let the target skeleton's deformation setup handle them. - use the retarget output log for missing or incompatible chain warnings. automation is a draft, not proof auto retarget chains uses name matching and common templates. auto align can substantially accelerate setup. both must be verified on the target skeleton, especially with unusual names, extra roots, asymmetric rigs, nonhuman proportions, or different reference stances."},{"slug":"poses-chains-and-operations","file":"poses-chains-and-operations.md","title":"Retarget poses, chains, and operation stack","rawMarkdown":"# Retarget poses, chains, and operation stack\n\n## Pose alignment\n\n1. Create a named target retarget pose; do not overwrite the baseline without a reason.\n2. Compare source and target in reference-pose view.\n3. Align large axes first: pelvis facing, spine, clavicles, upper/lower arms, hands, thighs,\n   calves, feet, and toes.\n4. Use Auto Align as a starting point. Direction, local/global rotation axes, and mesh methods\n   solve different mismatches; inspect every limb afterward.\n5. Snap the character to ground when vertical reference offsets differ.\n6. Scrub Retarget Pose Blend between 0 and 1 to distinguish reference-pose error from the\n   stored correction.\n\n## Operation stack discipline\n\nOperations evaluate top to bottom. Disable all nonessential corrections, establish a clean\nFK transfer, then enable one operation at a time.\n\n- **Retarget Pose**: first in the stack; selects stored source/target pose overrides.\n- **Pelvis Motion**: transfers and constrains pelvis movement; tune floor/crotch offsets only\n  after the retarget roots and poses are correct.\n- **FK Chains**: maps rotations/translations by chain.\n- **Root Motion**: copies source root or generates it from target pelvis.\n- **Run IK Rig**: applies goal-based target solving.\n- **Pin Bones / goal offsets / floor constraints**: late corrections for explicit contacts.\n- **Remap Curves**: needed when semantic curves have different names.\n\n## FK modes\n\n- **Interpolated rotation**: default choice when chain lengths, proportions, or bone counts differ.\n- **One to One**: corresponding bones transfer directly; use when counts and intent match.\n- **One to One Reversed**: maps from chain ends; useful only when the end is the stable anchor.\n- **None**: exclude the chain from FK rotation transfer.\n- **Translation None**: preferred for most chains.\n- **Globally Scaled / Absolute / Stretch modes**: use only for a specific diagnosed translation\n  requirement; verify deformation and root behavior across clips.\n\nUse Profile Ops to find an unexpectedly expensive retarget operation.\n","webMarkdown":"## Pose alignment\n\n1. Create a named target retarget pose; do not overwrite the baseline without a reason.\n2. Compare source and target in reference-pose view.\n3. Align large axes first: pelvis facing, spine, clavicles, upper/lower arms, hands, thighs,\n   calves, feet, and toes.\n4. Use Auto Align as a starting point. Direction, local/global rotation axes, and mesh methods\n   solve different mismatches; inspect every limb afterward.\n5. Snap the character to ground when vertical reference offsets differ.\n6. Scrub Retarget Pose Blend between 0 and 1 to distinguish reference-pose error from the\n   stored correction.\n\n## Operation stack discipline\n\nOperations evaluate top to bottom. Disable all nonessential corrections, establish a clean\nFK transfer, then enable one operation at a time.\n\n- **Retarget Pose**: first in the stack; selects stored source/target pose overrides.\n- **Pelvis Motion**: transfers and constrains pelvis movement; tune floor/crotch offsets only\n  after the retarget roots and poses are correct.\n- **FK Chains**: maps rotations/translations by chain.\n- **Root Motion**: copies source root or generates it from target pelvis.\n- **Run IK Rig**: applies goal-based target solving.\n- **Pin Bones / goal offsets / floor constraints**: late corrections for explicit contacts.\n- **Remap Curves**: needed when semantic curves have different names.\n\n## FK modes\n\n- **Interpolated rotation**: default choice when chain lengths, proportions, or bone counts differ.\n- **One to One**: corresponding bones transfer directly; use when counts and intent match.\n- **One to One Reversed**: maps from chain ends; useful only when the end is the stable anchor.\n- **None**: exclude the chain from FK rotation transfer.\n- **Translation None**: preferred for most chains.\n- **Globally Scaled / Absolute / Stretch modes**: use only for a specific diagnosed translation\n  requirement; verify deformation and root behavior across clips.\n\nUse Profile Ops to find an unexpectedly expensive retarget operation.\n","searchText":"retarget poses, chains, and operation stack pose alignment 1. create a named target retarget pose; do not overwrite the baseline without a reason. 2. compare source and target in reference-pose view. 3. align large axes first: pelvis facing, spine, clavicles, upper/lower arms, hands, thighs, calves, feet, and toes. 4. use auto align as a starting point. direction, local/global rotation axes, and mesh methods solve different mismatches; inspect every limb afterward. 5. snap the character to ground when vertical reference offsets differ. 6. scrub retarget pose blend between 0 and 1 to distinguish reference-pose error from the stored correction. operation stack discipline operations evaluate top to bottom. disable all nonessential corrections, establish a clean fk transfer, then enable one operation at a time. - retarget pose: first in the stack; selects stored source/target pose overrides. - pelvis motion: transfers and constrains pelvis movement; tune floor/crotch offsets only after the retarget roots and poses are correct. - fk chains: maps rotations/translations by chain. - root motion: copies source root or generates it from target pelvis. - run ik rig: applies goal-based target solving. - pin bones / goal offsets / floor constraints: late corrections for explicit contacts. - remap curves: needed when semantic curves have different names. fk modes - interpolated rotation: default choice when chain lengths, proportions, or bone counts differ. - one to one: corresponding bones transfer directly; use when counts and intent match. - one to one reversed: maps from chain ends; useful only when the end is the stable anchor. - none: exclude the chain from fk rotation transfer. - translation none: preferred for most chains. - globally scaled / absolute / stretch modes: use only for a specific diagnosed translation requirement; verify deformation and root behavior across clips. use profile ops to find an unexpectedly expensive retarget operation."},{"slug":"root-pelvis-and-contact","file":"root-pelvis-and-contact.md","title":"Root, pelvis, feet, and hand contact","rawMarkdown":"# Root, pelvis, feet, and hand contact\n\n## Root/pelvis order\n\n1. Confirm the source sequence contains the motion you expect.\n2. Confirm both retarget roots and actual skeleton root/pelvis hierarchy.\n3. Establish pelvis transfer before adding root generation.\n4. In Root Motion, choose either Copy From Source Root or Generate From Target Pelvis according\n   to the source data. Do not combine two owners of translation.\n5. Choose root height intentionally: copy source height or snap to ground.\n6. Inspect Maintain Pelvis Offset, child updates, global offsets, and pelvis-yaw contribution.\n7. Test export separately; preview root-lock overrides do not define exported behavior.\n\n## Symptom mapping\n\n- Whole character floats/sinks -> retarget pose ground, pelvis operation, root height, mesh scale.\n- Pelvis stays while feet move -> retarget root, pelvis source/target, FK translation mode.\n- Double translation -> root motion applied in both retarget/export and gameplay movement.\n- Character rotates unexpectedly -> pelvis yaw/root rotation settings or incorrect root basis.\n- Feet penetrate only on slopes -> runtime ground solution, not a retarget-pose correction.\n\n## Contact correction\n\nUse Speed Planting only after the base motion matches. It needs:\n\n- target leg chains with IK goals and a functioning IK solver;\n- source curves that identify foot-bone speed/contact, often generated with Animation Data\n  Modifiers;\n- thresholds tested across walk, run, start, stop, turn, and uneven ground.\n\nFor hands or weapon markers, first correct arm/hand chains and retarget pose. Use Pin Bones for\nspecial bones such as a weapon IK marker that must follow a target hand, then apply small goal\noffsets. Never compensate for a wrong chain map with a large per-animation hand offset.\n","webMarkdown":"## Root/pelvis order\n\n1. Confirm the source sequence contains the motion you expect.\n2. Confirm both retarget roots and actual skeleton root/pelvis hierarchy.\n3. Establish pelvis transfer before adding root generation.\n4. In Root Motion, choose either Copy From Source Root or Generate From Target Pelvis according\n   to the source data. Do not combine two owners of translation.\n5. Choose root height intentionally: copy source height or snap to ground.\n6. Inspect Maintain Pelvis Offset, child updates, global offsets, and pelvis-yaw contribution.\n7. Test export separately; preview root-lock overrides do not define exported behavior.\n\n## Symptom mapping\n\n- Whole character floats/sinks -> retarget pose ground, pelvis operation, root height, mesh scale.\n- Pelvis stays while feet move -> retarget root, pelvis source/target, FK translation mode.\n- Double translation -> root motion applied in both retarget/export and gameplay movement.\n- Character rotates unexpectedly -> pelvis yaw/root rotation settings or incorrect root basis.\n- Feet penetrate only on slopes -> runtime ground solution, not a retarget-pose correction.\n\n## Contact correction\n\nUse Speed Planting only after the base motion matches. It needs:\n\n- target leg chains with IK goals and a functioning IK solver;\n- source curves that identify foot-bone speed/contact, often generated with Animation Data\n  Modifiers;\n- thresholds tested across walk, run, start, stop, turn, and uneven ground.\n\nFor hands or weapon markers, first correct arm/hand chains and retarget pose. Use Pin Bones for\nspecial bones such as a weapon IK marker that must follow a target hand, then apply small goal\noffsets. Never compensate for a wrong chain map with a large per-animation hand offset.\n","searchText":"root, pelvis, feet, and hand contact root/pelvis order 1. confirm the source sequence contains the motion you expect. 2. confirm both retarget roots and actual skeleton root/pelvis hierarchy. 3. establish pelvis transfer before adding root generation. 4. in root motion, choose either copy from source root or generate from target pelvis according to the source data. do not combine two owners of translation. 5. choose root height intentionally: copy source height or snap to ground. 6. inspect maintain pelvis offset, child updates, global offsets, and pelvis-yaw contribution. 7. test export separately; preview root-lock overrides do not define exported behavior. symptom mapping - whole character floats/sinks -> retarget pose ground, pelvis operation, root height, mesh scale. - pelvis stays while feet move -> retarget root, pelvis source/target, fk translation mode. - double translation -> root motion applied in both retarget/export and gameplay movement. - character rotates unexpectedly -> pelvis yaw/root rotation settings or incorrect root basis. - feet penetrate only on slopes -> runtime ground solution, not a retarget-pose correction. contact correction use speed planting only after the base motion matches. it needs: - target leg chains with ik goals and a functioning ik solver; - source curves that identify foot-bone speed/contact, often generated with animation data modifiers; - thresholds tested across walk, run, start, stop, turn, and uneven ground. for hands or weapon markers, first correct arm/hand chains and retarget pose. use pin bones for special bones such as a weapon ik marker that must follow a target hand, then apply small goal offsets. never compensate for a wrong chain map with a large per-animation hand offset."},{"slug":"runtime-foot-placement","file":"runtime-foot-placement.md","title":"Runtime foot placement and focused IK","rawMarkdown":"# Runtime foot placement and focused IK\n\nUse runtime foot placement when contacts depend on current world geometry. Retarget poses and\nSpeed Planting solve different problems: the former aligns skeletons, the latter preserves\nsource contact, while runtime foot placement adapts to live terrain.\n\n## Procedure\n\n1. Begin with a correct locomotion pose.\n2. Trace from a stable foot reference toward the walkable surface using the same collision\n   assumptions as character movement.\n3. Reject invalid, distant, vertical, or non-walkable hits.\n4. Convert hit position/normal into the exact component/bone space expected by the solver.\n5. Solve feet, then derive pelvis compensation from the reachable leg with the limiting offset.\n6. Clamp leg extension and pelvis displacement; define behavior when no ground is found.\n7. Smooth target positions and normals over time without adding visible lag.\n8. Apply after locomotion blending/inertialization and before any later presentation-only pass\n   that intentionally depends on the solved pose.\n\n## Failure patterns\n\n- Feet snap -> unsmoothed target or discontinuous trace result.\n- Knees invert -> missing preferred bend/pole direction or target crosses singularity.\n- Legs stretch -> no reach clamp or pelvis compensation.\n- Feet hover on stairs -> trace origin/distance or capsule-to-mesh offset mismatch.\n- Correct on flat ground, wrong on moving platforms -> target stored in world space without\n  platform-relative handling.\n- Network jitter -> cosmetic client solve is consuming discontinuous replicated movement;\n  smooth movement first and avoid replicating trace results unless gameplay requires them.\n\nValidate flat ground, ramps, individual steps, stair runs, ledges, moving bases, sudden falls,\ncrouch, turns, and low animation LODs.\n","webMarkdown":"Use runtime foot placement when contacts depend on current world geometry. Retarget poses and\nSpeed Planting solve different problems: the former aligns skeletons, the latter preserves\nsource contact, while runtime foot placement adapts to live terrain.\n\n## Procedure\n\n1. Begin with a correct locomotion pose.\n2. Trace from a stable foot reference toward the walkable surface using the same collision\n   assumptions as character movement.\n3. Reject invalid, distant, vertical, or non-walkable hits.\n4. Convert hit position/normal into the exact component/bone space expected by the solver.\n5. Solve feet, then derive pelvis compensation from the reachable leg with the limiting offset.\n6. Clamp leg extension and pelvis displacement; define behavior when no ground is found.\n7. Smooth target positions and normals over time without adding visible lag.\n8. Apply after locomotion blending/inertialization and before any later presentation-only pass\n   that intentionally depends on the solved pose.\n\n## Failure patterns\n\n- Feet snap -> unsmoothed target or discontinuous trace result.\n- Knees invert -> missing preferred bend/pole direction or target crosses singularity.\n- Legs stretch -> no reach clamp or pelvis compensation.\n- Feet hover on stairs -> trace origin/distance or capsule-to-mesh offset mismatch.\n- Correct on flat ground, wrong on moving platforms -> target stored in world space without\n  platform-relative handling.\n- Network jitter -> cosmetic client solve is consuming discontinuous replicated movement;\n  smooth movement first and avoid replicating trace results unless gameplay requires them.\n\nValidate flat ground, ramps, individual steps, stair runs, ledges, moving bases, sudden falls,\ncrouch, turns, and low animation LODs.\n","searchText":"runtime foot placement and focused ik use runtime foot placement when contacts depend on current world geometry. retarget poses and speed planting solve different problems: the former aligns skeletons, the latter preserves source contact, while runtime foot placement adapts to live terrain. procedure 1. begin with a correct locomotion pose. 2. trace from a stable foot reference toward the walkable surface using the same collision assumptions as character movement. 3. reject invalid, distant, vertical, or non-walkable hits. 4. convert hit position/normal into the exact component/bone space expected by the solver. 5. solve feet, then derive pelvis compensation from the reachable leg with the limiting offset. 6. clamp leg extension and pelvis displacement; define behavior when no ground is found. 7. smooth target positions and normals over time without adding visible lag. 8. apply after locomotion blending/inertialization and before any later presentation-only pass that intentionally depends on the solved pose. failure patterns - feet snap -> unsmoothed target or discontinuous trace result. - knees invert -> missing preferred bend/pole direction or target crosses singularity. - legs stretch -> no reach clamp or pelvis compensation. - feet hover on stairs -> trace origin/distance or capsule-to-mesh offset mismatch. - correct on flat ground, wrong on moving platforms -> target stored in world space without platform-relative handling. - network jitter -> cosmetic client solve is consuming discontinuous replicated movement; smooth movement first and avoid replicating trace results unless gameplay requires them. validate flat ground, ramps, individual steps, stair runs, ledges, moving bases, sudden falls, crouch, turns, and low animation lods."},{"slug":"runtime-retargeting","file":"runtime-retargeting.md","title":"Runtime retargeting","rawMarkdown":"# Runtime retargeting\n\n## Retarget Pose From Mesh\n\n1. On the target Animation Blueprint, place `Retarget Pose From Mesh` as the base pose source.\n2. Assign the IK Retargeter asset.\n3. Either enable **Use Attached Parent** and parent the target Skeletal Mesh Component to the\n   source Skeletal Mesh Component, or explicitly provide the source mesh component.\n4. If the source mesh is hidden, set its Visibility Based Anim Tick Option to\n   **Always Tick Pose and Refresh Bones**.\n5. Apply target-only overlays or IK after the retargeted base pose.\n6. Use Retarget Profiles when gameplay must override supported operation settings at runtime.\n\n## Runtime failure gates\n\n- Frozen/default target -> wrong source component, wrong parent, missing retargeter, or source not ticking.\n- One-frame lag -> component tick prerequisite/order; ensure source updates before target.\n- Preview works, runtime breaks -> component hierarchy, LOD, visibility tick, graph order, runtime profile.\n- Correct close-up, wrong at distance -> LOD strips required bones or disables the solver/node.\n- Different clients disagree -> replicate gameplay state/targets, not final cosmetic bone transforms,\n  unless the design explicitly requires pose replication.\n\nRuntime retargeting saves exported assets and supports dynamic source characters, but it adds\nper-frame work. Profile the target platform and prefer exported sequences when runtime flexibility\ndoes not justify the cost.\n","webMarkdown":"## Retarget Pose From Mesh\n\n1. On the target Animation Blueprint, place `Retarget Pose From Mesh` as the base pose source.\n2. Assign the IK Retargeter asset.\n3. Either enable **Use Attached Parent** and parent the target Skeletal Mesh Component to the\n   source Skeletal Mesh Component, or explicitly provide the source mesh component.\n4. If the source mesh is hidden, set its Visibility Based Anim Tick Option to\n   **Always Tick Pose and Refresh Bones**.\n5. Apply target-only overlays or IK after the retargeted base pose.\n6. Use Retarget Profiles when gameplay must override supported operation settings at runtime.\n\n## Runtime failure gates\n\n- Frozen/default target -> wrong source component, wrong parent, missing retargeter, or source not ticking.\n- One-frame lag -> component tick prerequisite/order; ensure source updates before target.\n- Preview works, runtime breaks -> component hierarchy, LOD, visibility tick, graph order, runtime profile.\n- Correct close-up, wrong at distance -> LOD strips required bones or disables the solver/node.\n- Different clients disagree -> replicate gameplay state/targets, not final cosmetic bone transforms,\n  unless the design explicitly requires pose replication.\n\nRuntime retargeting saves exported assets and supports dynamic source characters, but it adds\nper-frame work. Profile the target platform and prefer exported sequences when runtime flexibility\ndoes not justify the cost.\n","searchText":"runtime retargeting retarget pose from mesh 1. on the target animation blueprint, place retarget pose from mesh as the base pose source. 2. assign the ik retargeter asset. 3. either enable use attached parent and parent the target skeletal mesh component to the source skeletal mesh component, or explicitly provide the source mesh component. 4. if the source mesh is hidden, set its visibility based anim tick option to always tick pose and refresh bones. 5. apply target-only overlays or ik after the retargeted base pose. 6. use retarget profiles when gameplay must override supported operation settings at runtime. runtime failure gates - frozen/default target -> wrong source component, wrong parent, missing retargeter, or source not ticking. - one-frame lag -> component tick prerequisite/order; ensure source updates before target. - preview works, runtime breaks -> component hierarchy, lod, visibility tick, graph order, runtime profile. - correct close-up, wrong at distance -> lod strips required bones or disables the solver/node. - different clients disagree -> replicate gameplay state/targets, not final cosmetic bone transforms, unless the design explicitly requires pose replication. runtime retargeting saves exported assets and supports dynamic source characters, but it adds per-frame work. profile the target platform and prefer exported sequences when runtime flexibility does not justify the cost."},{"slug":"sequencer-and-baking","file":"sequencer-and-baking.md","title":"Sequencer, authoring, and baking","rawMarkdown":"# Sequencer, authoring, and baking\n\n## Choose the authoring path\n\n- Use Control Rig in Sequencer for reusable controls and procedural relationships.\n- Use FK Control Rig for fast additive per-bone repair.\n- Use Backwards Solve when an existing animation must populate controls.\n- Bake when runtime evaluation is unnecessary, compatibility matters, or the result must become\n  a normal Animation Sequence.\n\n## Bake gates\n\n1. Duplicate or version the source asset.\n2. Confirm display rate, sample rate, sequence range, root behavior, and additive intent.\n3. Evaluate the complete source graph, including any warmup needed for procedural state.\n4. Bake transforms and required curves; choose local/world evaluation intentionally.\n5. Reduce keys only after visually comparing the unreduced bake; tune tolerance against the\n   smallest important contact or facial motion.\n6. Recheck notifies and metadata because transform baking does not automatically preserve every\n   semantic event contract.\n7. Test the resulting Animation Sequence outside Sequencer and in a cooked build.\n\nKeep a reversible path: source sequence/rig, settings, and generated output should be distinct.\n","webMarkdown":"## Choose the authoring path\n\n- Use Control Rig in Sequencer for reusable controls and procedural relationships.\n- Use FK Control Rig for fast additive per-bone repair.\n- Use Backwards Solve when an existing animation must populate controls.\n- Bake when runtime evaluation is unnecessary, compatibility matters, or the result must become\n  a normal Animation Sequence.\n\n## Bake gates\n\n1. Duplicate or version the source asset.\n2. Confirm display rate, sample rate, sequence range, root behavior, and additive intent.\n3. Evaluate the complete source graph, including any warmup needed for procedural state.\n4. Bake transforms and required curves; choose local/world evaluation intentionally.\n5. Reduce keys only after visually comparing the unreduced bake; tune tolerance against the\n   smallest important contact or facial motion.\n6. Recheck notifies and metadata because transform baking does not automatically preserve every\n   semantic event contract.\n7. Test the resulting Animation Sequence outside Sequencer and in a cooked build.\n\nKeep a reversible path: source sequence/rig, settings, and generated output should be distinct.\n","searchText":"sequencer, authoring, and baking choose the authoring path - use control rig in sequencer for reusable controls and procedural relationships. - use fk control rig for fast additive per-bone repair. - use backwards solve when an existing animation must populate controls. - bake when runtime evaluation is unnecessary, compatibility matters, or the result must become a normal animation sequence. bake gates 1. duplicate or version the source asset. 2. confirm display rate, sample rate, sequence range, root behavior, and additive intent. 3. evaluate the complete source graph, including any warmup needed for procedural state. 4. bake transforms and required curves; choose local/world evaluation intentionally. 5. reduce keys only after visually comparing the unreduced bake; tune tolerance against the smallest important contact or facial motion. 6. recheck notifies and metadata because transform baking does not automatically preserve every semantic event contract. 7. test the resulting animation sequence outside sequencer and in a cooked build. keep a reversible path: source sequence/rig, settings, and generated output should be distinct."},{"slug":"sources","file":"sources.md","title":"UE 5.8 primary sources","rawMarkdown":"# UE 5.8 primary sources\n\n- [IK Rig Animation Retargeting](https://dev.epicgames.com/documentation/en-us/unreal-engine/ik-rig-animation-retargeting-in-unreal-engine)\n- [Retargeting Bipeds with IK Rig](https://dev.epicgames.com/documentation/en-us/unreal-engine/retargeting-bipeds-with-ik-rig-in-unreal-engine)\n- [Retargeting Operation Stack in UE 5.8](https://dev.epicgames.com/documentation/en-us/unreal-engine/retargeting-operation-stack-in-unreal-engine-5-8)\n- [Auto Retargeting](https://dev.epicgames.com/documentation/en-us/unreal-engine/auto-retargeting-in-unreal-engine)\n- [Runtime IK Retargeting](https://dev.epicgames.com/documentation/en-us/unreal-engine/runtime-ik-retargeting-in-unreal-engine)\n- [Animating IK Retarget Settings / Retarget Profiles](https://dev.epicgames.com/documentation/en-us/unreal-engine/animating-ik-retarget-settings-in-unreal-engine)\n- [Fix Foot Sliding with IK Retargeter](https://dev.epicgames.com/documentation/en-us/unreal-engine/fix-foot-sliding-with-ik-retargeter-in-unreal-engine)\n- [IK Rig](https://dev.epicgames.com/documentation/en-us/unreal-engine/ik-rig-in-unreal-engine)\n- [IK Rig in Animation Blueprints](https://dev.epicgames.com/documentation/en-us/unreal-engine/ik-rig-in-animation-blueprints-in-unreal-engine)\n- [Control Rig](https://dev.epicgames.com/documentation/en-us/unreal-engine/control-rig-in-unreal-engine)\n- [Create Control Rigs](https://dev.epicgames.com/documentation/en-us/unreal-engine/how-to-create-control-rigs-in-unreal-engine)\n- [Full-Body IK](https://dev.epicgames.com/documentation/en-us/unreal-engine/control-rig-full-body-ik-in-unreal-engine)\n- [FK Control Rig](https://dev.epicgames.com/documentation/en-us/unreal-engine/fk-control-rig-in-unreal-engine)\n- [Control Rig Editor](https://dev.epicgames.com/documentation/en-us/unreal-engine/control-rig-editor-in-unreal-engine)\n- [Root Motion](https://dev.epicgames.com/documentation/en-us/unreal-engine/root-motion-in-unreal-engine)\n\nPages were checked against the UE 5.8 documentation on 2026-07-19. Reconfirm feature maturity\nand property names after an engine upgrade.\n","webMarkdown":"- [IK Rig Animation Retargeting](https://dev.epicgames.com/documentation/en-us/unreal-engine/ik-rig-animation-retargeting-in-unreal-engine)\n- [Retargeting Bipeds with IK Rig](https://dev.epicgames.com/documentation/en-us/unreal-engine/retargeting-bipeds-with-ik-rig-in-unreal-engine)\n- [Retargeting Operation Stack in UE 5.8](https://dev.epicgames.com/documentation/en-us/unreal-engine/retargeting-operation-stack-in-unreal-engine-5-8)\n- [Auto Retargeting](https://dev.epicgames.com/documentation/en-us/unreal-engine/auto-retargeting-in-unreal-engine)\n- [Runtime IK Retargeting](https://dev.epicgames.com/documentation/en-us/unreal-engine/runtime-ik-retargeting-in-unreal-engine)\n- [Animating IK Retarget Settings / Retarget Profiles](https://dev.epicgames.com/documentation/en-us/unreal-engine/animating-ik-retarget-settings-in-unreal-engine)\n- [Fix Foot Sliding with IK Retargeter](https://dev.epicgames.com/documentation/en-us/unreal-engine/fix-foot-sliding-with-ik-retargeter-in-unreal-engine)\n- [IK Rig](https://dev.epicgames.com/documentation/en-us/unreal-engine/ik-rig-in-unreal-engine)\n- [IK Rig in Animation Blueprints](https://dev.epicgames.com/documentation/en-us/unreal-engine/ik-rig-in-animation-blueprints-in-unreal-engine)\n- [Control Rig](https://dev.epicgames.com/documentation/en-us/unreal-engine/control-rig-in-unreal-engine)\n- [Create Control Rigs](https://dev.epicgames.com/documentation/en-us/unreal-engine/how-to-create-control-rigs-in-unreal-engine)\n- [Full-Body IK](https://dev.epicgames.com/documentation/en-us/unreal-engine/control-rig-full-body-ik-in-unreal-engine)\n- [FK Control Rig](https://dev.epicgames.com/documentation/en-us/unreal-engine/fk-control-rig-in-unreal-engine)\n- [Control Rig Editor](https://dev.epicgames.com/documentation/en-us/unreal-engine/control-rig-editor-in-unreal-engine)\n- [Root Motion](https://dev.epicgames.com/documentation/en-us/unreal-engine/root-motion-in-unreal-engine)\n\nPages were checked against the UE 5.8 documentation on 2026-07-19. Reconfirm feature maturity\nand property names after an engine upgrade.\n","searchText":"ue 5.8 primary sources - ik rig animation retargeting - retargeting bipeds with ik rig - retargeting operation stack in ue 5.8 - auto retargeting - runtime ik retargeting - animating ik retarget settings / retarget profiles - fix foot sliding with ik retargeter - ik rig - ik rig in animation blueprints - control rig - create control rigs - full-body ik - fk control rig - control rig editor - root motion pages were checked against the ue 5.8 documentation on 2026-07-19. reconfirm feature maturity and property names after an engine upgrade."},{"slug":"symptom-diagnostics","file":"symptom-diagnostics.md","title":"Symptom-first diagnostics","rawMarkdown":"# Symptom-first diagnostics\n\n## Isolation ladder\n\n1. Play the source Animation Sequence on its intended source mesh.\n2. Preview the IK Retargeter with all optional operations disabled.\n3. Validate chain map and dedicated retarget pose.\n4. Enable Pelvis, FK, Root, IK, pin/contact, and curve operations one at a time.\n5. Export one sequence and play it directly on the target.\n6. Test runtime `Retarget Pose From Mesh` without target overlays.\n7. Re-enable the final AnimGraph from base pose outward.\n\nThe first failing rung owns the investigation.\n\n| Symptom | Inspect first | Then |\n|---|---|---|\n| Target frozen or stale | source mesh tick, source component, attached parent | graph order, LOD |\n| Limbs explode/contort | chain start/end/map | retarget pose axes, FK rotation mode |\n| Knees/elbows bend backward | pose bend direction | preferred angles, goal space |\n| Floating or sinking | ground alignment, pelvis op | root height, floor constraint |\n| Foot sliding | source speed vs target motion | Speed Planting curves/goals |\n| Hand/weapon offset | arm/hand chains and pose | Pin Bones, goal offsets |\n| Root motion absent | source root data and root op | export/root-motion settings, movement owner |\n| Root motion doubled | duplicate translation owner | AnimBP/movement integration |\n| Preview correct, export wrong | export root-lock mode | curves/bake settings |\n| Preview correct, runtime wrong | component parent/source/tick | profile, LOD, node order |\n| Works near camera only | animation/solver LOD | required bone stripping |\n\nCapture: source/target asset names, skeleton roots, retarget roots, chain map, retarget pose name,\noperation stack order, runtime component hierarchy, node order, and the shortest failing clip.\nDo not tune several offsets at once.\n","webMarkdown":"## Isolation ladder\n\n1. Play the source Animation Sequence on its intended source mesh.\n2. Preview the IK Retargeter with all optional operations disabled.\n3. Validate chain map and dedicated retarget pose.\n4. Enable Pelvis, FK, Root, IK, pin/contact, and curve operations one at a time.\n5. Export one sequence and play it directly on the target.\n6. Test runtime `Retarget Pose From Mesh` without target overlays.\n7. Re-enable the final AnimGraph from base pose outward.\n\nThe first failing rung owns the investigation.\n\n| Symptom | Inspect first | Then |\n|---|---|---|\n| Target frozen or stale | source mesh tick, source component, attached parent | graph order, LOD |\n| Limbs explode/contort | chain start/end/map | retarget pose axes, FK rotation mode |\n| Knees/elbows bend backward | pose bend direction | preferred angles, goal space |\n| Floating or sinking | ground alignment, pelvis op | root height, floor constraint |\n| Foot sliding | source speed vs target motion | Speed Planting curves/goals |\n| Hand/weapon offset | arm/hand chains and pose | Pin Bones, goal offsets |\n| Root motion absent | source root data and root op | export/root-motion settings, movement owner |\n| Root motion doubled | duplicate translation owner | AnimBP/movement integration |\n| Preview correct, export wrong | export root-lock mode | curves/bake settings |\n| Preview correct, runtime wrong | component parent/source/tick | profile, LOD, node order |\n| Works near camera only | animation/solver LOD | required bone stripping |\n\nCapture: source/target asset names, skeleton roots, retarget roots, chain map, retarget pose name,\noperation stack order, runtime component hierarchy, node order, and the shortest failing clip.\nDo not tune several offsets at once.\n","searchText":"symptom-first diagnostics isolation ladder 1. play the source animation sequence on its intended source mesh. 2. preview the ik retargeter with all optional operations disabled. 3. validate chain map and dedicated retarget pose. 4. enable pelvis, fk, root, ik, pin/contact, and curve operations one at a time. 5. export one sequence and play it directly on the target. 6. test runtime retarget pose from mesh without target overlays. 7. re-enable the final animgraph from base pose outward. the first failing rung owns the investigation. | symptom | inspect first | then | |---|---|---| | target frozen or stale | source mesh tick, source component, attached parent | graph order, lod | | limbs explode/contort | chain start/end/map | retarget pose axes, fk rotation mode | | knees/elbows bend backward | pose bend direction | preferred angles, goal space | | floating or sinking | ground alignment, pelvis op | root height, floor constraint | | foot sliding | source speed vs target motion | speed planting curves/goals | | hand/weapon offset | arm/hand chains and pose | pin bones, goal offsets | | root motion absent | source root data and root op | export/root-motion settings, movement owner | | root motion doubled | duplicate translation owner | animbp/movement integration | | preview correct, export wrong | export root-lock mode | curves/bake settings | | preview correct, runtime wrong | component parent/source/tick | profile, lod, node order | | works near camera only | animation/solver lod | required bone stripping | capture: source/target asset names, skeleton roots, retarget roots, chain map, retarget pose name, operation stack order, runtime component hierarchy, node order, and the shortest failing clip. do not tune several offsets at once."},{"slug":"system-selector","file":"system-selector.md","title":"System selector","rawMarkdown":"# System selector\n\n| Need | Primary system | Avoid when |\n|---|---|---|\n| Reuse animation on another skeleton | IK Rig + IK Retargeter | Skeletons are already compatible enough for Compatible Skeletons |\n| Drive a target from a live source mesh | Retarget Pose From Mesh | Offline export is simpler and runtime flexibility is unnecessary |\n| Correct whole-body reach/stance | Full Body IK | A single two-bone limb solve is sufficient |\n| Runtime goal-driven limbs | IK Rig node / focused IK | The change is authored and should be baked |\n| Animate controls in Sequencer | Control Rig | Only a small additive bone correction is needed |\n| Quick per-bone additive repair | FK Control Rig | A reusable procedural rig is required |\n| Preserve planted contacts during retarget | Speed Planting after base retarget | The real fault is chain, pose, pelvis, root, or speed mismatch |\n\nDecision gates:\n\n1. Is this transfer, procedural correction, or authoring?\n2. Must it remain live at runtime?\n3. Does it require one limb or a connected full-body response?\n4. Does gameplay need to drive the goal, or can the result be baked?\n5. Is the problem already visible before IK? If yes, fix that stage first.\n\nKeep ownership explicit: gameplay produces targets; the animation graph consumes targets;\nIK solves the pose. Do not move authoritative gameplay state into a rig graph.\n","webMarkdown":"| Need | Primary system | Avoid when |\n|---|---|---|\n| Reuse animation on another skeleton | IK Rig + IK Retargeter | Skeletons are already compatible enough for Compatible Skeletons |\n| Drive a target from a live source mesh | Retarget Pose From Mesh | Offline export is simpler and runtime flexibility is unnecessary |\n| Correct whole-body reach/stance | Full Body IK | A single two-bone limb solve is sufficient |\n| Runtime goal-driven limbs | IK Rig node / focused IK | The change is authored and should be baked |\n| Animate controls in Sequencer | Control Rig | Only a small additive bone correction is needed |\n| Quick per-bone additive repair | FK Control Rig | A reusable procedural rig is required |\n| Preserve planted contacts during retarget | Speed Planting after base retarget | The real fault is chain, pose, pelvis, root, or speed mismatch |\n\nDecision gates:\n\n1. Is this transfer, procedural correction, or authoring?\n2. Must it remain live at runtime?\n3. Does it require one limb or a connected full-body response?\n4. Does gameplay need to drive the goal, or can the result be baked?\n5. Is the problem already visible before IK? If yes, fix that stage first.\n\nKeep ownership explicit: gameplay produces targets; the animation graph consumes targets;\nIK solves the pose. Do not move authoritative gameplay state into a rig graph.\n","searchText":"system selector | need | primary system | avoid when | |---|---|---| | reuse animation on another skeleton | ik rig + ik retargeter | skeletons are already compatible enough for compatible skeletons | | drive a target from a live source mesh | retarget pose from mesh | offline export is simpler and runtime flexibility is unnecessary | | correct whole-body reach/stance | full body ik | a single two-bone limb solve is sufficient | | runtime goal-driven limbs | ik rig node / focused ik | the change is authored and should be baked | | animate controls in sequencer | control rig | only a small additive bone correction is needed | | quick per-bone additive repair | fk control rig | a reusable procedural rig is required | | preserve planted contacts during retarget | speed planting after base retarget | the real fault is chain, pose, pelvis, root, or speed mismatch | decision gates: 1. is this transfer, procedural correction, or authoring? 2. must it remain live at runtime? 3. does it require one limb or a connected full-body response? 4. does gameplay need to drive the goal, or can the result be baked? 5. is the problem already visible before ik? if yes, fix that stage first. keep ownership explicit: gameplay produces targets; the animation graph consumes targets; ik solves the pose. do not move authoritative gameplay state into a rig graph."}]}
{"slug":"unreal-data-assets-tables","name":"unreal-data-assets-tables","title":"Unreal 5.8 Data Assets and Tables","description":"Design, implement, load, cook, validate, and debug data-driven content in Unreal Engine 5.8. Use for UDataAsset, UPrimaryDataAsset, Data-Only Blueprints, Data Tables, Curve Tables, Composite Data Tables, Data Registries, FPrimaryAssetId, Asset Manager scan rules, asset bundles, hard versus soft references, asynchronous loading, Asset Registry queries, Primary Asset Labels, cooking, chunking, or data validation.","shortDescription":"Design and load data-driven Unreal content","category":"Data, Tools & Shipping","referenceCount":11,"rawMarkdown":"---\nname: unreal-data-assets-tables\ndescription: Design, implement, load, cook, validate, and debug data-driven content in Unreal Engine 5.8. Use for UDataAsset, UPrimaryDataAsset, Data-Only Blueprints, Data Tables, Curve Tables, Composite Data Tables, Data Registries, FPrimaryAssetId, Asset Manager scan rules, asset bundles, hard versus soft references, asynchronous loading, Asset Registry queries, Primary Asset Labels, cooking, chunking, or data validation.\n---\n\n# Unreal 5.8 Data Assets and Tables\n\n## Ownership boundary\n\nThis skill owns definition schemas, stable asset IDs, discovery, Asset Manager rules, bundles, and\ncontent-to-cook/chunk ownership. Route runtime residency, reference-chain hitches, and unload policy to\n[`unreal-memory-streaming`](../unreal-memory-streaming/SKILL.md), artifact construction and packaged-only\nfailure isolation to [`unreal-packaging-deployment`](../unreal-packaging-deployment/SKILL.md), and mutable\nplayer/world persistence to [`unreal-save-load`](../unreal-save-load/SKILL.md).\n\n## Select the representation\n\nRead [`references/selector-model.md`](references/selector-model.md) before creating a schema.\n\n- Use a **Data Asset** for one inspectable authored definition with heterogeneous fields.\n- Use a **Primary Data Asset** when the definition needs a stable `FPrimaryAssetId`,\n  Asset Manager discovery, bundles, explicit loading, or cook rules.\n- Use a **Data-Only Blueprint** when authored definitions require inheritance.\n- Use a **Data Table** for many homogeneous rows sharing one `FTableRowBase` schema.\n- Use a **Curve Table** for keyed numeric progression and interpolation.\n- Use a **Data Registry** when multiple read-only sources, override/fallback ordering,\n  asynchronous acquisition, or managed caching justify its plugin and indirection.\n- Use **SaveGame/runtime objects**, not authored assets, for mutable player or session state.\n\n## Execute\n\n1. State the definition/state boundary, stable identifier, ownership, load lifetime, and\n   cook requirements.\n2. Choose the smallest representation that satisfies those requirements.\n3. Define the schema in C++ when type stability, validation, or broad reuse matters.\n4. Choose hard references only for assets that must load with the owner. Use soft\n   references when the dependency should load on demand.\n5. If using the Asset Manager, configure the Primary Asset Type and scan path before\n   relying on discovery. Keep each type in deliberate folders.\n6. Load asynchronously before the asset is needed; retain the returned asset or handle\n   for the required lifetime and define failure behavior.\n7. Validate identifiers, ranges, references, duplicate rows, cross-row relationships,\n   and cook inclusion before runtime.\n8. Test in a cooked build. Editor discovery and successful PIE loading do not prove that\n   an indirectly referenced asset was cooked.\n\nRead the reference matching the task:\n\n- authored definitions: [`references/data-assets-primary.md`](references/data-assets-primary.md)\n- tabular schemas/import: [`references/data-tables-curves.md`](references/data-tables-curves.md)\n- stable identity and state: [`references/identifiers-state-versioning.md`](references/identifiers-state-versioning.md)\n- reference and loading choice: [`references/references-loading.md`](references/references-loading.md)\n- Asset Manager/bundles: [`references/asset-manager-bundles.md`](references/asset-manager-bundles.md)\n- unloaded discovery: [`references/asset-registry-discovery.md`](references/asset-registry-discovery.md)\n- cooking/chunking: [`references/cooking-chunking-audit.md`](references/cooking-chunking-audit.md)\n- validation and failures: [`references/validation-debugging.md`](references/validation-debugging.md)\n- concrete layouts: [`references/patterns.md`](references/patterns.md)\n\n## Required answer format\n\nReturn:\n\n1. **Representation and schema**, including why nearby alternatives were rejected.\n2. **Stable identifier and mutable-state boundary**.\n3. **Reference graph**, naming hard and soft edges.\n4. **Discovery, loading, ownership, and unload sequence**.\n5. **Cook/chunk rules** and a packaged-build proof.\n6. **Validation rules**, failure behavior, and migration consequences.\n\nDo not invent editor paths, Blueprint nodes, APIs, metadata, or cook behavior.\n\n## Hard rules\n\n- Treat Data Assets, Data Tables, and Data Registries as read-only definitions at runtime.\n- Never use an asset object or table-row pointer as persistent mutable game state.\n- Never cache a Data Table row pointer beyond local use when the table may reimport.\n- Never assume a soft reference loads or cooks its target merely because the path exists.\n- Never replace every hard reference with a soft reference; loading boundaries must be\n  explicit and worth their complexity.\n- Never rename shipped Primary Asset IDs or row identifiers without redirects or migration.\n- Query unloaded assets through metadata before calling an API that materializes `UObject`s.\n- Validate the cooked artifact, not only the editor database.\n\nSee [`references/sources.md`](references/sources.md) for the UE 5.8 source trail.\n","webMarkdown":"## Ownership boundary\n\nThis skill owns definition schemas, stable asset IDs, discovery, Asset Manager rules, bundles, and\ncontent-to-cook/chunk ownership. Route runtime residency, reference-chain hitches, and unload policy to\n[`unreal-memory-streaming`](/unreal/unreal-memory-streaming/), artifact construction and packaged-only\nfailure isolation to [`unreal-packaging-deployment`](/unreal/unreal-packaging-deployment/), and mutable\nplayer/world persistence to [`unreal-save-load`](/unreal/unreal-save-load/).\n\n## Select the representation\n\nRead [`references/selector-model.md`](/unreal/unreal-data-assets-tables/selector-model/) before creating a schema.\n\n- Use a **Data Asset** for one inspectable authored definition with heterogeneous fields.\n- Use a **Primary Data Asset** when the definition needs a stable `FPrimaryAssetId`,\n  Asset Manager discovery, bundles, explicit loading, or cook rules.\n- Use a **Data-Only Blueprint** when authored definitions require inheritance.\n- Use a **Data Table** for many homogeneous rows sharing one `FTableRowBase` schema.\n- Use a **Curve Table** for keyed numeric progression and interpolation.\n- Use a **Data Registry** when multiple read-only sources, override/fallback ordering,\n  asynchronous acquisition, or managed caching justify its plugin and indirection.\n- Use **SaveGame/runtime objects**, not authored assets, for mutable player or session state.\n\n## Execute\n\n1. State the definition/state boundary, stable identifier, ownership, load lifetime, and\n   cook requirements.\n2. Choose the smallest representation that satisfies those requirements.\n3. Define the schema in C++ when type stability, validation, or broad reuse matters.\n4. Choose hard references only for assets that must load with the owner. Use soft\n   references when the dependency should load on demand.\n5. If using the Asset Manager, configure the Primary Asset Type and scan path before\n   relying on discovery. Keep each type in deliberate folders.\n6. Load asynchronously before the asset is needed; retain the returned asset or handle\n   for the required lifetime and define failure behavior.\n7. Validate identifiers, ranges, references, duplicate rows, cross-row relationships,\n   and cook inclusion before runtime.\n8. Test in a cooked build. Editor discovery and successful PIE loading do not prove that\n   an indirectly referenced asset was cooked.\n\nRead the reference matching the task:\n\n- authored definitions: [`references/data-assets-primary.md`](/unreal/unreal-data-assets-tables/data-assets-primary/)\n- tabular schemas/import: [`references/data-tables-curves.md`](/unreal/unreal-data-assets-tables/data-tables-curves/)\n- stable identity and state: [`references/identifiers-state-versioning.md`](/unreal/unreal-data-assets-tables/identifiers-state-versioning/)\n- reference and loading choice: [`references/references-loading.md`](/unreal/unreal-data-assets-tables/references-loading/)\n- Asset Manager/bundles: [`references/asset-manager-bundles.md`](/unreal/unreal-data-assets-tables/asset-manager-bundles/)\n- unloaded discovery: [`references/asset-registry-discovery.md`](/unreal/unreal-data-assets-tables/asset-registry-discovery/)\n- cooking/chunking: [`references/cooking-chunking-audit.md`](/unreal/unreal-data-assets-tables/cooking-chunking-audit/)\n- validation and failures: [`references/validation-debugging.md`](/unreal/unreal-data-assets-tables/validation-debugging/)\n- concrete layouts: [`references/patterns.md`](/unreal/unreal-data-assets-tables/patterns/)\n\n## Required answer format\n\nReturn:\n\n1. **Representation and schema**, including why nearby alternatives were rejected.\n2. **Stable identifier and mutable-state boundary**.\n3. **Reference graph**, naming hard and soft edges.\n4. **Discovery, loading, ownership, and unload sequence**.\n5. **Cook/chunk rules** and a packaged-build proof.\n6. **Validation rules**, failure behavior, and migration consequences.\n\nDo not invent editor paths, Blueprint nodes, APIs, metadata, or cook behavior.\n\n## Hard rules\n\n- Treat Data Assets, Data Tables, and Data Registries as read-only definitions at runtime.\n- Never use an asset object or table-row pointer as persistent mutable game state.\n- Never cache a Data Table row pointer beyond local use when the table may reimport.\n- Never assume a soft reference loads or cooks its target merely because the path exists.\n- Never replace every hard reference with a soft reference; loading boundaries must be\n  explicit and worth their complexity.\n- Never rename shipped Primary Asset IDs or row identifiers without redirects or migration.\n- Query unloaded assets through metadata before calling an API that materializes `UObject`s.\n- Validate the cooked artifact, not only the editor database.\n\nSee [`references/sources.md`](/unreal/unreal-data-assets-tables/sources/) for the UE 5.8 source trail.\n","searchText":"unreal 5.8 data assets and tables design, implement, load, cook, validate, and debug data-driven content in unreal engine 5.8. use for udataasset, uprimarydataasset, data-only blueprints, data tables, curve tables, composite data tables, data registries, fprimaryassetid, asset manager scan rules, asset bundles, hard versus soft references, asynchronous loading, asset registry queries, primary asset labels, cooking, chunking, or data validation. asset manager, primary assets, and bundles asset manager, primary assets, and bundles configure discovery open project settings > game > asset manager and define each primary asset type: 1. match the actual primary asset type returned by getprimaryassetid. 2. set the correct base class and whether the entries are blueprint classes. 3. add narrow scan directories; exclude tests where appropriate. 4. define type-level cook/chunk rules only when the delivery plan requires them. 5. restart/rescan as required, then confirm ids through asset manager audit tools or code. do not create a custom uassetmanager subclass unless startup registration, dynamic assets, or project-specific policy requires it. the base manager can load configured primary assets. load and unload use loadprimaryasset, loadprimaryassets, or loadprimaryassetswithtype with the bundles needed for the current phase. use the corresponding unload functions at the owner-defined boundary. loading the primary asset can also load secondary assets listed in requested bundles. state who owns residency. avoid independent systems issuing unmatched loads/unloads against the same content without a shared lifetime contract. asset bundles create a bundle by placing meta=(assetbundles=\"bundlename\") on soft asset/class properties of a primary asset. saving the primary data asset updates its bundle data. good bundle names describe use phases: - ui: icon, portrait, preview material; - gameplay: class, mesh, animation set, effects; - server: authoritative data needed without presentation assets. bundle names have no inherent semantics. the caller chooses which bundles to load. validate that each required dependency is included and each excluded dependency is genuinely optional. identity and configuration traps - data asset instances and blueprint class assets use different asset manager accessors; blueprint class helpers include class in their names. - a type/base-class mismatch or wrong scan path produces an empty discovery set. - renaming an asset changes the default name portion of its primary asset id; shipped ids require redirects or a custom stable identity. - asset manager success in editor does not prove that cook rules include all secondaries. asset registry discovery without loading asset registry discovery without loading use the asset registry when a tool or system must enumerate assets by path, class, or stored metadata without materializing every uobject. query pattern 1. build a narrow farfilter using package paths, class paths, and tag/value pairs. 2. query fassetdata. 3. read package/name/class and registry tags first. 4. call getasset() only for entries that truly require loading; it loads the asset when necessary. avoid getallassets() in routine interactive tools; epic documents it as potentially slow. searchable metadata mark appropriate properties assetregistrysearchable, or implement asset-registry tag generation for derived metadata. keep tags compact, stable, and useful for filtering. after adding or changing searchable metadata, resave assets. registry tags are gathered into the saved asset header; unsaved legacy assets will not retroactively expose the new value. completeness and state the registry gathers asynchronously. if an operation requires the complete project catalog, wait for initial discovery or use completion delegates rather than assuming the first query is complete. be explicit about whether a query should use disk data or in-memory data. unsaved loaded assets may differ from their on-disk registry state. asset manager boundary - asset registry answers: “what assets and metadata exist?” - asset manager answers: “which assets have primary identity, how are they grouped, loaded, and cooked?” use both when a catalog is discovered by metadata but loaded under managed primary identities. cooking, chunking, and audit cooking, chunking, and audit prove cook inclusion a reference working in pie is insufficient. for every asynchronously loaded asset: 1. identify the primary asset, label, directory, map, or explicit cook rule that includes it. 2. cook the target platform. 3. inspect asset audit, cooked output, or staging manifests. 4. launch a packaged build without editor-only loose content. 5. exercise the cold-load path and its failure handling. use project settings > game > asset manager for type rules. use tools > audit > asset audit and reference viewer to inspect management and dependency chains. primary asset labels use uprimaryassetlabel to assign rules to explicit assets, collections, or a directory tree. labels can define priority, chunk id, and cook rule. important 5.8 constraint: blueprint subclasses of primaryassetlabel do not work for chunking. use the provided class or a native c++ subclass when adding metadata. chunking - chunk 0 is the default base content. - positive chunk ids create separately assignable content groups when chunk generation is enabled. - a primary asset's management rules can assign referenced secondary assets. - higher-priority management can win when more than one primary asset claims content. design chunks around install/patch/dlc boundaries, not folder aesthetics. duplicated shared dependencies, circular ownership, and accidental hard references can defeat the intended layout. release checks - enable only cook production assets when development-only primary assets must fail a production cook. - compare asset audit across representative builds. - verify chunk availability order on the real delivery platform. - treat rule and label changes as packaging changes requiring a full staged test. data assets and primary data assets data assets and primary data assets plain data asset use a native subclass of udataasset when designers need one asset per definition. 1. create the native class and expose deliberate fields with uproperty. 2. create instances through content browser > miscellaneous > data asset. 3. store authored definition data only. 4. add isdatavalid for invariants owned by the class. prefer a non-blueprint data asset instance when inheritance is unnecessary. it is simpler and more memory-efficient than representing pure data as a blueprint class. inherited definitions when values must inherit: 1. derive a blueprint class from the native data asset/primary data asset base. 2. create data-only blueprint children from that blueprint class. 3. read definition values from the class defaults. do not expect one data asset instance to inherit values from another instance. epic's 5.8 guidance recommends data-only blueprint classes for inheritance and parent updates. primary data asset use uprimarydataasset when the asset needs: - an fprimaryassetid; - asset manager discovery and direct manipulation; - named bundles of soft-referenced secondary assets; - explicit load/unload or cook/chunk policy. its default primary asset type depends on the first native class or highest blueprint class in the hierarchy. confirm the actual type:name emitted by getprimaryassetid; override getprimaryassetid when the default identity is not the stable contract you need. definition pattern keep lightweight identity and tuning directly on the definition. store optional heavy content as tsoftobjectptr/tsoftclassptr, grouped into semantic bundles such as ui, gameplay, or match only when callers truly load different subsets. do not mutate the asset to track ownership, quantity, durability, cooldown, or progress. create a runtime instance/state struct keyed by the stable definition id. data tables, curve tables, and overlays data tables, curve tables, and overlays define a data table schema 1. declare a ustruct(blueprinttype) deriving from ftablerowbase. 2. expose typed columns with uproperty. 3. use fname, gameplay tags, enums, and typed handles where they communicate domain meaning better than free-form strings. 4. use tsoftobjectptr for optional or heavy assets. a hard uobject field can cause all referenced assets to load with the table. 5. add defaults and validation for every field whose absence has meaning. for csv/json import, map headings to struct property names. csv convention uses name as the row key unless import key field selects another field. keep ignore extra fields and ignore missing fields off when schema drift should fail loudly. reimport uses the stored source path. treat the source spreadsheet/csv/json and the unreal asset as one controlled pipeline; decide which side is authoritative. read rows safely - expose fdatatablerowhandle when designers should choose both table and row. - in c++, use findrow<t>() with a useful context string and handle null explicitly. - do not retain returned row or curve pointers beyond local scope. reimport can refresh the table and invalidate pointers. - copy a row only when a snapshot is intentional; otherwise resolve by handle when needed. curve tables use a curve table when each named row is a float curve. select interpolation deliberately: - constant: step changes; holds the previous value. - linear: straight interpolation between keys. - cubic: smooth interpolation that can overshoot; inspect gameplay-critical ranges. use fcurvetablerowhandle for authored references. do not use a curve table to disguise a wide, heterogeneous record schema. composite data tables and data registries use a composite data table for a controlled stack of same-schema parent tables. validate duplicate rows and make override precedence visible. runtime changes to parent tables can rebuild the composite and hitch. use a data registry instead when data comes from several sources, needs ordered fallback, asynchronous acquisition, or configurable caching. acquireitem scheduling success does not prove that the item exists. do not retain registry-owned row pointers if a source can unload; consume immediately or copy the value. identifiers, state, and schema evolution identifiers, state, and schema evolution stable identity choose an identifier before content volume grows: - primary assets: fprimaryassetid (type:name). - data table rows: stable fname row key or a domain id stored and validated in the row. - data registry items: fdataregistryid. - cross-system categories/state: governed gameplay tags where hierarchy is useful. display names are localized presentation, never durable identity. array index and editor position are not identity. rename policy treat shipped ids as append-only contracts. when a rename is unavoidable: 1. record old-to-new mapping. 2. configure primary asset id/type/name redirects where asset manager identity changed. 3. migrate save data and external references explicitly. 4. validate that old ids resolve or fail with a controlled migration message. 5. test an upgrade from a real previous save and cooked build. asset redirectors repair package references; they do not automatically migrate every string, row name, gameplay tag, save payload, or external service key. definition versus state use this split: text definition asset/table row stable id, display data, tuning, soft content references runtime state definition id, quantity, durability, ownership, cooldown, progress save payload stable definition id, version, minimal authoritative state resolve the definition after loading a save. handle missing definitions with a documented fallback, quarantine, refund, or migration; never crash on an unchecked lookup. schema changes - add fields with safe defaults. - validate old imports against renamed/removed columns. - keep serialization versioning separate from the current asset schema. - for computed/derived values, prefer recomputation over persisting redundant state. - run reimport, validation, cook, and previous-save migration after structural changes. concrete data patterns concrete data patterns item catalog with runtime inventory text uitemdefinition : uprimarydataasset itemid or stable primaryassetid displayname, tags, tuning ui bundle: icon gameplay bundle: actor class, mesh/effects finventoryentry (runtime/save) definitionid quantity durability instance modifiers load ui for menus; load gameplay before spawning/equipping. the definition never stores quantity or ownership. balance table use one ftablerowbase schema for homogeneous weapon or progression values. put heavy visual assets behind soft references. expose fdatatablerowhandle to authored consumers. validate unique domain ids, monotonic thresholds where required, and all referenced rows. layered tuning use a composite data table only for a small, visible base-to-override stack sharing one schema. validate duplicate-row precedence. if sources are discovered dynamically, asynchronously acquired, or cached under different lifetimes, use a data registry instead. catalog browser tool query the asset registry by narrow path/class/tag filters, display fassetdata, then load only the selected record. never load the entire catalog merely to populate a list. menu-to-match preload 1. resolve selected primary asset ids. 2. request the next phase's bundles asynchronously. 3. display progress and allow controlled cancellation. 4. verify every required object in completion. 5. transfer ownership to the match/session object. 6. enter the match only after required content is resident. 7. release at match teardown after dependent actors are gone. validation ci gate run c++ data validation in a headless editor job, capture exit status and logs, then cook a representative target. treat invalid definition assets and missing cook dependencies as build failures. keep expensive full-project relationship checks separate from fast on-save checks. hard references, soft references, and load ownership hard references, soft references, and load ownership choose the edge use a hard tobjectptr<t>/class reference when the target must be resident whenever its owner is resident and the dependency is acceptably small. use tsoftobjectptr<t>, tsoftclassptr<t>, or fsoftobjectpath when the target should not load with the owner, content is optional, or a large catalog must remain unloaded. soft does not mean free: - callers must load before dereference; - failure, cancellation, and race behavior must be defined; - a path does not keep the object resident after loading; - cook inclusion still needs a discoverable rule. async load pattern 1. gather soft paths or primary asset ids before the transition that needs them. 2. request asynchronous loading through asset manager or a suitable streamable manager. 3. retain the fstreamablehandle when cancellation, progress, combined requests, or explicit residency management matters. 4. in completion, verify the handle/request and every required asset. 5. transfer loaded objects into a hard owner for their use lifetime, or keep the handle alive according to the chosen api. 6. release the owner/handle at the explicit unload boundary. never call a synchronous load in a latency-sensitive path merely because the soft pointer api offers it. small editor utilities and controlled loading screens may accept blocking; gameplay and streaming paths normally should not. reference audit use reference viewer and size map/asset audit to find accidental hard dependency chains. a lightweight definition that hard-references one blueprint can pull in that blueprint's complete dependency graph. for a suspect asset, report: - why it is loaded; - which edge is hard; - what the correct load boundary is; - whether converting the edge to soft changes cook rules; - how residency will be proven on target hardware. representation selector representation selector decision table | need | choose | reject when | |---|---|---| | one authored definition with named fields | udataasset instance | it needs asset manager identity/loading or inheritance | | individually discoverable/loadable definition | uprimarydataasset | it is only a small row in one always-loaded table | | definition inheritance | data-only blueprint derived from a suitable base | inheritance would hide important per-item differences | | many records with one flat schema | udatatable | records need different shapes, behavior, or independent load policy | | numeric values over an input axis | ucurvetable | the row contains nonnumeric definition data | | ordered table overlays | ucompositedatatable | sources need asynchronous acquisition, caching, or flexible resolution | | multiple read-only sources with fallback/overrides | data registry | one table or asset set is sufficient | | search unloaded asset metadata | asset registry | the actual object must be executed or inspected beyond stored metadata | | mutable session/player state | runtime owner plus savegame where persistent | never store it in a shared definition asset | selection questions answer in order: 1. is this authored definition or mutable runtime state? 2. does every record share the same schema? 3. does each record need independent identity, inheritance, loading, or cook rules? 4. must heavy dependencies load with the definition? 5. must content be discovered without loading it? 6. will shipped identifiers survive renames and schema changes? prefer one simple data table or data asset until a demonstrated loading, override, or production requirement justifies asset manager or data registry machinery. boundaries - a data table row is a value in a table, not a polymorphic object. - a data asset is a uobject asset instance. a data-only blueprint is a class and gains inheritance through class defaults. - a primary data asset is not automatically discovered merely because it derives from uprimarydataasset; configure its type and scan path or register it in code. - data registries are for general read-only data. use savegame for story progress, inventories, unlocks, or other mutable persistence. ue 5.8 primary sources ue 5.8 primary sources verified against epic games documentation for unreal engine 5.8 on 2026-07-19. - data assets - asset management - data driven gameplay elements - object pointers - asynchronous asset loading - asset registry - data registries - data validation - cooking and chunking - preparing assets for chunking - uprimarydataasset api - uprimaryassetlabel api - udatatable api - fprimaryassetrules api version-sensitive notes retained in this package: - primary asset label blueprint subclasses do not work for chunking. - data table/curve table pointers should not be cached beyond local scope across reimport. - data registry-owned item pointers can become invalid when dynamically sourced data unloads. - data validation commandlets run c++ rules by default; python validators require registration. validation and debugging validation and debugging validation placement use both layers when appropriate: - override isdatavalid on the definition class for invariants that belong to that object. - derive ueditorvalidatorbase to validate assets across engine/custom classes or enforce project-wide policy. implement canvalidateasset and ensure every validateloadedasset path calls assetpasses or assetfails. validate through content browser actions, tools > validate data, and ci: text unrealeditor-cmd.exe project.uproject -run=datavalidation the commandlet runs c++ rules by default. blueprint/python validation support requires explicit extension; python validators must register with ueditorvalidatorsubsystem. definition checks at minimum validate: - id is present, unique, governed, and consistent with the asset/row when required; - numeric values are finite and within domain ranges; - required hard/soft references resolve and have allowed classes; - mutually exclusive options are not both selected; - dependent fields are present together; - rows/reference targets exist; - no forbidden dependency cycle or editor-only content crosses into runtime; - asset manager id and bundle/cook expectations are satisfied. use errors for content that cannot ship and warnings for suspicious but valid states. include asset path, field, received value, expected rule, and a repair action in every message. failure routing | symptom | check first | |---|---| | primary asset id not found | actual id, type config, base-class mode, scan path, excluded path | | soft pointer is null | was it loaded, did load finish, did the path redirect, is target cooked? | | table lookup fails | correct table, exact row key, schema/import warnings, reimport result | | values do not update | cached row pointer/copy, stale reimport, wrong source authority | | unexpected memory spike | hard reference chain, broad bundle, synchronous load, retained handle | | works in pie, fails packaged | cook rule, primary asset label, editor-only class/path, chunk availability | | registry query misses assets | initial scan incomplete, wrong class path/filter, asset not resaved for tags | log stable ids and package paths at load boundaries. do not “fix” missing data by silently substituting unrelated content unless the product explicitly defines that fallback.","references":[{"slug":"asset-manager-bundles","file":"asset-manager-bundles.md","title":"Asset Manager, Primary Assets, and bundles","rawMarkdown":"# Asset Manager, Primary Assets, and bundles\n\n## Configure discovery\n\nOpen **Project Settings > Game > Asset Manager** and define each Primary Asset Type:\n\n1. Match the actual Primary Asset Type returned by `GetPrimaryAssetId`.\n2. Set the correct base class and whether the entries are Blueprint classes.\n3. Add narrow scan directories; exclude tests where appropriate.\n4. Define type-level cook/chunk rules only when the delivery plan requires them.\n5. Restart/rescan as required, then confirm IDs through Asset Manager audit tools or code.\n\nDo not create a custom `UAssetManager` subclass unless startup registration, dynamic assets,\nor project-specific policy requires it. The base manager can load configured primary assets.\n\n## Load and unload\n\nUse `LoadPrimaryAsset`, `LoadPrimaryAssets`, or `LoadPrimaryAssetsWithType` with the bundles\nneeded for the current phase. Use the corresponding unload functions at the owner-defined\nboundary. Loading the primary asset can also load secondary assets listed in requested bundles.\n\nState who owns residency. Avoid independent systems issuing unmatched loads/unloads against\nthe same content without a shared lifetime contract.\n\n## Asset bundles\n\nCreate a bundle by placing `meta=(AssetBundles=\"BundleName\")` on soft asset/class properties\nof a Primary Asset. Saving the Primary Data Asset updates its bundle data.\n\nGood bundle names describe use phases:\n\n- `UI`: icon, portrait, preview material;\n- `Gameplay`: class, mesh, animation set, effects;\n- `Server`: authoritative data needed without presentation assets.\n\nBundle names have no inherent semantics. The caller chooses which bundles to load. Validate\nthat each required dependency is included and each excluded dependency is genuinely optional.\n\n## Identity and configuration traps\n\n- Data Asset instances and Blueprint class assets use different Asset Manager accessors;\n  Blueprint class helpers include `Class` in their names.\n- A type/base-class mismatch or wrong scan path produces an empty discovery set.\n- Renaming an asset changes the default name portion of its Primary Asset ID; shipped IDs\n  require redirects or a custom stable identity.\n- Asset Manager success in editor does not prove that cook rules include all secondaries.\n","webMarkdown":"## Configure discovery\n\nOpen **Project Settings > Game > Asset Manager** and define each Primary Asset Type:\n\n1. Match the actual Primary Asset Type returned by `GetPrimaryAssetId`.\n2. Set the correct base class and whether the entries are Blueprint classes.\n3. Add narrow scan directories; exclude tests where appropriate.\n4. Define type-level cook/chunk rules only when the delivery plan requires them.\n5. Restart/rescan as required, then confirm IDs through Asset Manager audit tools or code.\n\nDo not create a custom `UAssetManager` subclass unless startup registration, dynamic assets,\nor project-specific policy requires it. The base manager can load configured primary assets.\n\n## Load and unload\n\nUse `LoadPrimaryAsset`, `LoadPrimaryAssets`, or `LoadPrimaryAssetsWithType` with the bundles\nneeded for the current phase. Use the corresponding unload functions at the owner-defined\nboundary. Loading the primary asset can also load secondary assets listed in requested bundles.\n\nState who owns residency. Avoid independent systems issuing unmatched loads/unloads against\nthe same content without a shared lifetime contract.\n\n## Asset bundles\n\nCreate a bundle by placing `meta=(AssetBundles=\"BundleName\")` on soft asset/class properties\nof a Primary Asset. Saving the Primary Data Asset updates its bundle data.\n\nGood bundle names describe use phases:\n\n- `UI`: icon, portrait, preview material;\n- `Gameplay`: class, mesh, animation set, effects;\n- `Server`: authoritative data needed without presentation assets.\n\nBundle names have no inherent semantics. The caller chooses which bundles to load. Validate\nthat each required dependency is included and each excluded dependency is genuinely optional.\n\n## Identity and configuration traps\n\n- Data Asset instances and Blueprint class assets use different Asset Manager accessors;\n  Blueprint class helpers include `Class` in their names.\n- A type/base-class mismatch or wrong scan path produces an empty discovery set.\n- Renaming an asset changes the default name portion of its Primary Asset ID; shipped IDs\n  require redirects or a custom stable identity.\n- Asset Manager success in editor does not prove that cook rules include all secondaries.\n","searchText":"asset manager, primary assets, and bundles configure discovery open project settings > game > asset manager and define each primary asset type: 1. match the actual primary asset type returned by getprimaryassetid. 2. set the correct base class and whether the entries are blueprint classes. 3. add narrow scan directories; exclude tests where appropriate. 4. define type-level cook/chunk rules only when the delivery plan requires them. 5. restart/rescan as required, then confirm ids through asset manager audit tools or code. do not create a custom uassetmanager subclass unless startup registration, dynamic assets, or project-specific policy requires it. the base manager can load configured primary assets. load and unload use loadprimaryasset, loadprimaryassets, or loadprimaryassetswithtype with the bundles needed for the current phase. use the corresponding unload functions at the owner-defined boundary. loading the primary asset can also load secondary assets listed in requested bundles. state who owns residency. avoid independent systems issuing unmatched loads/unloads against the same content without a shared lifetime contract. asset bundles create a bundle by placing meta=(assetbundles=\"bundlename\") on soft asset/class properties of a primary asset. saving the primary data asset updates its bundle data. good bundle names describe use phases: - ui: icon, portrait, preview material; - gameplay: class, mesh, animation set, effects; - server: authoritative data needed without presentation assets. bundle names have no inherent semantics. the caller chooses which bundles to load. validate that each required dependency is included and each excluded dependency is genuinely optional. identity and configuration traps - data asset instances and blueprint class assets use different asset manager accessors; blueprint class helpers include class in their names. - a type/base-class mismatch or wrong scan path produces an empty discovery set. - renaming an asset changes the default name portion of its primary asset id; shipped ids require redirects or a custom stable identity. - asset manager success in editor does not prove that cook rules include all secondaries."},{"slug":"asset-registry-discovery","file":"asset-registry-discovery.md","title":"Asset Registry discovery without loading","rawMarkdown":"# Asset Registry discovery without loading\n\nUse the Asset Registry when a tool or system must enumerate assets by path, class, or stored\nmetadata without materializing every `UObject`.\n\n## Query pattern\n\n1. Build a narrow `FARFilter` using package paths, class paths, and tag/value pairs.\n2. Query `FAssetData`.\n3. Read package/name/class and registry tags first.\n4. Call `GetAsset()` only for entries that truly require loading; it loads the asset when\n   necessary.\n\nAvoid `GetAllAssets()` in routine interactive tools; Epic documents it as potentially slow.\n\n## Searchable metadata\n\nMark appropriate properties `AssetRegistrySearchable`, or implement asset-registry tag\ngeneration for derived metadata. Keep tags compact, stable, and useful for filtering.\n\nAfter adding or changing searchable metadata, resave assets. Registry tags are gathered into\nthe saved asset header; unsaved legacy assets will not retroactively expose the new value.\n\n## Completeness and state\n\nThe registry gathers asynchronously. If an operation requires the complete project catalog,\nwait for initial discovery or use completion delegates rather than assuming the first query is\ncomplete.\n\nBe explicit about whether a query should use disk data or in-memory data. Unsaved loaded assets\nmay differ from their on-disk registry state.\n\n## Asset Manager boundary\n\n- Asset Registry answers: “what assets and metadata exist?”\n- Asset Manager answers: “which assets have primary identity, how are they grouped, loaded,\n  and cooked?”\n\nUse both when a catalog is discovered by metadata but loaded under managed primary identities.\n","webMarkdown":"Use the Asset Registry when a tool or system must enumerate assets by path, class, or stored\nmetadata without materializing every `UObject`.\n\n## Query pattern\n\n1. Build a narrow `FARFilter` using package paths, class paths, and tag/value pairs.\n2. Query `FAssetData`.\n3. Read package/name/class and registry tags first.\n4. Call `GetAsset()` only for entries that truly require loading; it loads the asset when\n   necessary.\n\nAvoid `GetAllAssets()` in routine interactive tools; Epic documents it as potentially slow.\n\n## Searchable metadata\n\nMark appropriate properties `AssetRegistrySearchable`, or implement asset-registry tag\ngeneration for derived metadata. Keep tags compact, stable, and useful for filtering.\n\nAfter adding or changing searchable metadata, resave assets. Registry tags are gathered into\nthe saved asset header; unsaved legacy assets will not retroactively expose the new value.\n\n## Completeness and state\n\nThe registry gathers asynchronously. If an operation requires the complete project catalog,\nwait for initial discovery or use completion delegates rather than assuming the first query is\ncomplete.\n\nBe explicit about whether a query should use disk data or in-memory data. Unsaved loaded assets\nmay differ from their on-disk registry state.\n\n## Asset Manager boundary\n\n- Asset Registry answers: “what assets and metadata exist?”\n- Asset Manager answers: “which assets have primary identity, how are they grouped, loaded,\n  and cooked?”\n\nUse both when a catalog is discovered by metadata but loaded under managed primary identities.\n","searchText":"asset registry discovery without loading use the asset registry when a tool or system must enumerate assets by path, class, or stored metadata without materializing every uobject. query pattern 1. build a narrow farfilter using package paths, class paths, and tag/value pairs. 2. query fassetdata. 3. read package/name/class and registry tags first. 4. call getasset() only for entries that truly require loading; it loads the asset when necessary. avoid getallassets() in routine interactive tools; epic documents it as potentially slow. searchable metadata mark appropriate properties assetregistrysearchable, or implement asset-registry tag generation for derived metadata. keep tags compact, stable, and useful for filtering. after adding or changing searchable metadata, resave assets. registry tags are gathered into the saved asset header; unsaved legacy assets will not retroactively expose the new value. completeness and state the registry gathers asynchronously. if an operation requires the complete project catalog, wait for initial discovery or use completion delegates rather than assuming the first query is complete. be explicit about whether a query should use disk data or in-memory data. unsaved loaded assets may differ from their on-disk registry state. asset manager boundary - asset registry answers: “what assets and metadata exist?” - asset manager answers: “which assets have primary identity, how are they grouped, loaded, and cooked?” use both when a catalog is discovered by metadata but loaded under managed primary identities."},{"slug":"cooking-chunking-audit","file":"cooking-chunking-audit.md","title":"Cooking, chunking, and audit","rawMarkdown":"# Cooking, chunking, and audit\n\n## Prove cook inclusion\n\nA reference working in PIE is insufficient. For every asynchronously loaded asset:\n\n1. Identify the Primary Asset, label, directory, map, or explicit cook rule that includes it.\n2. Cook the target platform.\n3. Inspect Asset Audit, cooked output, or staging manifests.\n4. Launch a packaged build without editor-only loose content.\n5. exercise the cold-load path and its failure handling.\n\nUse **Project Settings > Game > Asset Manager** for type rules. Use **Tools > Audit > Asset\nAudit** and Reference Viewer to inspect management and dependency chains.\n\n## Primary Asset Labels\n\nUse `UPrimaryAssetLabel` to assign rules to explicit assets, collections, or a directory tree.\nLabels can define priority, chunk ID, and cook rule.\n\nImportant 5.8 constraint: Blueprint subclasses of `PrimaryAssetLabel` do not work for chunking.\nUse the provided class or a native C++ subclass when adding metadata.\n\n## Chunking\n\n- Chunk `0` is the default base content.\n- Positive chunk IDs create separately assignable content groups when chunk generation is\n  enabled.\n- A Primary Asset's management rules can assign referenced secondary assets.\n- Higher-priority management can win when more than one Primary Asset claims content.\n\nDesign chunks around install/patch/DLC boundaries, not folder aesthetics. Duplicated shared\ndependencies, circular ownership, and accidental hard references can defeat the intended layout.\n\n## Release checks\n\n- Enable **Only Cook Production Assets** when development-only primary assets must fail a\n  production cook.\n- Compare Asset Audit across representative builds.\n- Verify chunk availability order on the real delivery platform.\n- Treat rule and label changes as packaging changes requiring a full staged test.\n","webMarkdown":"## Prove cook inclusion\n\nA reference working in PIE is insufficient. For every asynchronously loaded asset:\n\n1. Identify the Primary Asset, label, directory, map, or explicit cook rule that includes it.\n2. Cook the target platform.\n3. Inspect Asset Audit, cooked output, or staging manifests.\n4. Launch a packaged build without editor-only loose content.\n5. exercise the cold-load path and its failure handling.\n\nUse **Project Settings > Game > Asset Manager** for type rules. Use **Tools > Audit > Asset\nAudit** and Reference Viewer to inspect management and dependency chains.\n\n## Primary Asset Labels\n\nUse `UPrimaryAssetLabel` to assign rules to explicit assets, collections, or a directory tree.\nLabels can define priority, chunk ID, and cook rule.\n\nImportant 5.8 constraint: Blueprint subclasses of `PrimaryAssetLabel` do not work for chunking.\nUse the provided class or a native C++ subclass when adding metadata.\n\n## Chunking\n\n- Chunk `0` is the default base content.\n- Positive chunk IDs create separately assignable content groups when chunk generation is\n  enabled.\n- A Primary Asset's management rules can assign referenced secondary assets.\n- Higher-priority management can win when more than one Primary Asset claims content.\n\nDesign chunks around install/patch/DLC boundaries, not folder aesthetics. Duplicated shared\ndependencies, circular ownership, and accidental hard references can defeat the intended layout.\n\n## Release checks\n\n- Enable **Only Cook Production Assets** when development-only primary assets must fail a\n  production cook.\n- Compare Asset Audit across representative builds.\n- Verify chunk availability order on the real delivery platform.\n- Treat rule and label changes as packaging changes requiring a full staged test.\n","searchText":"cooking, chunking, and audit prove cook inclusion a reference working in pie is insufficient. for every asynchronously loaded asset: 1. identify the primary asset, label, directory, map, or explicit cook rule that includes it. 2. cook the target platform. 3. inspect asset audit, cooked output, or staging manifests. 4. launch a packaged build without editor-only loose content. 5. exercise the cold-load path and its failure handling. use project settings > game > asset manager for type rules. use tools > audit > asset audit and reference viewer to inspect management and dependency chains. primary asset labels use uprimaryassetlabel to assign rules to explicit assets, collections, or a directory tree. labels can define priority, chunk id, and cook rule. important 5.8 constraint: blueprint subclasses of primaryassetlabel do not work for chunking. use the provided class or a native c++ subclass when adding metadata. chunking - chunk 0 is the default base content. - positive chunk ids create separately assignable content groups when chunk generation is enabled. - a primary asset's management rules can assign referenced secondary assets. - higher-priority management can win when more than one primary asset claims content. design chunks around install/patch/dlc boundaries, not folder aesthetics. duplicated shared dependencies, circular ownership, and accidental hard references can defeat the intended layout. release checks - enable only cook production assets when development-only primary assets must fail a production cook. - compare asset audit across representative builds. - verify chunk availability order on the real delivery platform. - treat rule and label changes as packaging changes requiring a full staged test."},{"slug":"data-assets-primary","file":"data-assets-primary.md","title":"Data Assets and Primary Data Assets","rawMarkdown":"# Data Assets and Primary Data Assets\n\n## Plain Data Asset\n\nUse a native subclass of `UDataAsset` when designers need one asset per definition.\n\n1. Create the native class and expose deliberate fields with `UPROPERTY`.\n2. Create instances through **Content Browser > Miscellaneous > Data Asset**.\n3. Store authored definition data only.\n4. Add `IsDataValid` for invariants owned by the class.\n\nPrefer a non-Blueprint Data Asset instance when inheritance is unnecessary. It is simpler\nand more memory-efficient than representing pure data as a Blueprint class.\n\n## Inherited definitions\n\nWhen values must inherit:\n\n1. Derive a Blueprint class from the native Data Asset/Primary Data Asset base.\n2. Create Data-Only Blueprint children from that Blueprint class.\n3. Read definition values from the class defaults.\n\nDo not expect one Data Asset instance to inherit values from another instance. Epic's 5.8\nguidance recommends Data-Only Blueprint classes for inheritance and parent updates.\n\n## Primary Data Asset\n\nUse `UPrimaryDataAsset` when the asset needs:\n\n- an `FPrimaryAssetId`;\n- Asset Manager discovery and direct manipulation;\n- named bundles of soft-referenced secondary assets;\n- explicit load/unload or cook/chunk policy.\n\nIts default Primary Asset Type depends on the first native class or highest Blueprint class\nin the hierarchy. Confirm the actual `Type:Name` emitted by `GetPrimaryAssetId`; override\n`GetPrimaryAssetId` when the default identity is not the stable contract you need.\n\n## Definition pattern\n\nKeep lightweight identity and tuning directly on the definition. Store optional heavy\ncontent as `TSoftObjectPtr`/`TSoftClassPtr`, grouped into semantic bundles such as `UI`,\n`Gameplay`, or `Match` only when callers truly load different subsets.\n\nDo not mutate the asset to track ownership, quantity, durability, cooldown, or progress.\nCreate a runtime instance/state struct keyed by the stable definition ID.\n","webMarkdown":"## Plain Data Asset\n\nUse a native subclass of `UDataAsset` when designers need one asset per definition.\n\n1. Create the native class and expose deliberate fields with `UPROPERTY`.\n2. Create instances through **Content Browser > Miscellaneous > Data Asset**.\n3. Store authored definition data only.\n4. Add `IsDataValid` for invariants owned by the class.\n\nPrefer a non-Blueprint Data Asset instance when inheritance is unnecessary. It is simpler\nand more memory-efficient than representing pure data as a Blueprint class.\n\n## Inherited definitions\n\nWhen values must inherit:\n\n1. Derive a Blueprint class from the native Data Asset/Primary Data Asset base.\n2. Create Data-Only Blueprint children from that Blueprint class.\n3. Read definition values from the class defaults.\n\nDo not expect one Data Asset instance to inherit values from another instance. Epic's 5.8\nguidance recommends Data-Only Blueprint classes for inheritance and parent updates.\n\n## Primary Data Asset\n\nUse `UPrimaryDataAsset` when the asset needs:\n\n- an `FPrimaryAssetId`;\n- Asset Manager discovery and direct manipulation;\n- named bundles of soft-referenced secondary assets;\n- explicit load/unload or cook/chunk policy.\n\nIts default Primary Asset Type depends on the first native class or highest Blueprint class\nin the hierarchy. Confirm the actual `Type:Name` emitted by `GetPrimaryAssetId`; override\n`GetPrimaryAssetId` when the default identity is not the stable contract you need.\n\n## Definition pattern\n\nKeep lightweight identity and tuning directly on the definition. Store optional heavy\ncontent as `TSoftObjectPtr`/`TSoftClassPtr`, grouped into semantic bundles such as `UI`,\n`Gameplay`, or `Match` only when callers truly load different subsets.\n\nDo not mutate the asset to track ownership, quantity, durability, cooldown, or progress.\nCreate a runtime instance/state struct keyed by the stable definition ID.\n","searchText":"data assets and primary data assets plain data asset use a native subclass of udataasset when designers need one asset per definition. 1. create the native class and expose deliberate fields with uproperty. 2. create instances through content browser > miscellaneous > data asset. 3. store authored definition data only. 4. add isdatavalid for invariants owned by the class. prefer a non-blueprint data asset instance when inheritance is unnecessary. it is simpler and more memory-efficient than representing pure data as a blueprint class. inherited definitions when values must inherit: 1. derive a blueprint class from the native data asset/primary data asset base. 2. create data-only blueprint children from that blueprint class. 3. read definition values from the class defaults. do not expect one data asset instance to inherit values from another instance. epic's 5.8 guidance recommends data-only blueprint classes for inheritance and parent updates. primary data asset use uprimarydataasset when the asset needs: - an fprimaryassetid; - asset manager discovery and direct manipulation; - named bundles of soft-referenced secondary assets; - explicit load/unload or cook/chunk policy. its default primary asset type depends on the first native class or highest blueprint class in the hierarchy. confirm the actual type:name emitted by getprimaryassetid; override getprimaryassetid when the default identity is not the stable contract you need. definition pattern keep lightweight identity and tuning directly on the definition. store optional heavy content as tsoftobjectptr/tsoftclassptr, grouped into semantic bundles such as ui, gameplay, or match only when callers truly load different subsets. do not mutate the asset to track ownership, quantity, durability, cooldown, or progress. create a runtime instance/state struct keyed by the stable definition id."},{"slug":"data-tables-curves","file":"data-tables-curves.md","title":"Data Tables, Curve Tables, and overlays","rawMarkdown":"# Data Tables, Curve Tables, and overlays\n\n## Define a Data Table schema\n\n1. Declare a `USTRUCT(BlueprintType)` deriving from `FTableRowBase`.\n2. Expose typed columns with `UPROPERTY`.\n3. Use `FName`, Gameplay Tags, enums, and typed handles where they communicate domain\n   meaning better than free-form strings.\n4. Use `TSoftObjectPtr` for optional or heavy assets. A hard `UObject` field can cause all\n   referenced assets to load with the table.\n5. Add defaults and validation for every field whose absence has meaning.\n\nFor CSV/JSON import, map headings to struct property names. CSV convention uses `Name` as\nthe row key unless **Import Key Field** selects another field. Keep **Ignore Extra Fields**\nand **Ignore Missing Fields** off when schema drift should fail loudly.\n\nReimport uses the stored source path. Treat the source spreadsheet/CSV/JSON and the Unreal\nasset as one controlled pipeline; decide which side is authoritative.\n\n## Read rows safely\n\n- Expose `FDataTableRowHandle` when designers should choose both table and row.\n- In C++, use `FindRow<T>()` with a useful context string and handle null explicitly.\n- Do not retain returned row or curve pointers beyond local scope. Reimport can refresh the\n  table and invalidate pointers.\n- Copy a row only when a snapshot is intentional; otherwise resolve by handle when needed.\n\n## Curve Tables\n\nUse a Curve Table when each named row is a float curve. Select interpolation deliberately:\n\n- **Constant**: step changes; holds the previous value.\n- **Linear**: straight interpolation between keys.\n- **Cubic**: smooth interpolation that can overshoot; inspect gameplay-critical ranges.\n\nUse `FCurveTableRowHandle` for authored references. Do not use a Curve Table to disguise a\nwide, heterogeneous record schema.\n\n## Composite Data Tables and Data Registries\n\nUse a Composite Data Table for a controlled stack of same-schema parent tables. Validate\nduplicate rows and make override precedence visible. Runtime changes to parent tables can\nrebuild the composite and hitch.\n\nUse a Data Registry instead when data comes from several sources, needs ordered fallback,\nasynchronous acquisition, or configurable caching. `AcquireItem` scheduling success does\nnot prove that the item exists. Do not retain registry-owned row pointers if a source can\nunload; consume immediately or copy the value.\n","webMarkdown":"## Define a Data Table schema\n\n1. Declare a `USTRUCT(BlueprintType)` deriving from `FTableRowBase`.\n2. Expose typed columns with `UPROPERTY`.\n3. Use `FName`, Gameplay Tags, enums, and typed handles where they communicate domain\n   meaning better than free-form strings.\n4. Use `TSoftObjectPtr` for optional or heavy assets. A hard `UObject` field can cause all\n   referenced assets to load with the table.\n5. Add defaults and validation for every field whose absence has meaning.\n\nFor CSV/JSON import, map headings to struct property names. CSV convention uses `Name` as\nthe row key unless **Import Key Field** selects another field. Keep **Ignore Extra Fields**\nand **Ignore Missing Fields** off when schema drift should fail loudly.\n\nReimport uses the stored source path. Treat the source spreadsheet/CSV/JSON and the Unreal\nasset as one controlled pipeline; decide which side is authoritative.\n\n## Read rows safely\n\n- Expose `FDataTableRowHandle` when designers should choose both table and row.\n- In C++, use `FindRow<T>()` with a useful context string and handle null explicitly.\n- Do not retain returned row or curve pointers beyond local scope. Reimport can refresh the\n  table and invalidate pointers.\n- Copy a row only when a snapshot is intentional; otherwise resolve by handle when needed.\n\n## Curve Tables\n\nUse a Curve Table when each named row is a float curve. Select interpolation deliberately:\n\n- **Constant**: step changes; holds the previous value.\n- **Linear**: straight interpolation between keys.\n- **Cubic**: smooth interpolation that can overshoot; inspect gameplay-critical ranges.\n\nUse `FCurveTableRowHandle` for authored references. Do not use a Curve Table to disguise a\nwide, heterogeneous record schema.\n\n## Composite Data Tables and Data Registries\n\nUse a Composite Data Table for a controlled stack of same-schema parent tables. Validate\nduplicate rows and make override precedence visible. Runtime changes to parent tables can\nrebuild the composite and hitch.\n\nUse a Data Registry instead when data comes from several sources, needs ordered fallback,\nasynchronous acquisition, or configurable caching. `AcquireItem` scheduling success does\nnot prove that the item exists. Do not retain registry-owned row pointers if a source can\nunload; consume immediately or copy the value.\n","searchText":"data tables, curve tables, and overlays define a data table schema 1. declare a ustruct(blueprinttype) deriving from ftablerowbase. 2. expose typed columns with uproperty. 3. use fname, gameplay tags, enums, and typed handles where they communicate domain meaning better than free-form strings. 4. use tsoftobjectptr for optional or heavy assets. a hard uobject field can cause all referenced assets to load with the table. 5. add defaults and validation for every field whose absence has meaning. for csv/json import, map headings to struct property names. csv convention uses name as the row key unless import key field selects another field. keep ignore extra fields and ignore missing fields off when schema drift should fail loudly. reimport uses the stored source path. treat the source spreadsheet/csv/json and the unreal asset as one controlled pipeline; decide which side is authoritative. read rows safely - expose fdatatablerowhandle when designers should choose both table and row. - in c++, use findrow<t>() with a useful context string and handle null explicitly. - do not retain returned row or curve pointers beyond local scope. reimport can refresh the table and invalidate pointers. - copy a row only when a snapshot is intentional; otherwise resolve by handle when needed. curve tables use a curve table when each named row is a float curve. select interpolation deliberately: - constant: step changes; holds the previous value. - linear: straight interpolation between keys. - cubic: smooth interpolation that can overshoot; inspect gameplay-critical ranges. use fcurvetablerowhandle for authored references. do not use a curve table to disguise a wide, heterogeneous record schema. composite data tables and data registries use a composite data table for a controlled stack of same-schema parent tables. validate duplicate rows and make override precedence visible. runtime changes to parent tables can rebuild the composite and hitch. use a data registry instead when data comes from several sources, needs ordered fallback, asynchronous acquisition, or configurable caching. acquireitem scheduling success does not prove that the item exists. do not retain registry-owned row pointers if a source can unload; consume immediately or copy the value."},{"slug":"identifiers-state-versioning","file":"identifiers-state-versioning.md","title":"Identifiers, state, and schema evolution","rawMarkdown":"# Identifiers, state, and schema evolution\n\n## Stable identity\n\nChoose an identifier before content volume grows:\n\n- Primary Assets: `FPrimaryAssetId` (`Type:Name`).\n- Data Table rows: stable `FName` row key or a domain ID stored and validated in the row.\n- Data Registry items: `FDataRegistryId`.\n- Cross-system categories/state: governed Gameplay Tags where hierarchy is useful.\n\nDisplay names are localized presentation, never durable identity. Array index and editor\nposition are not identity.\n\n## Rename policy\n\nTreat shipped IDs as append-only contracts. When a rename is unavoidable:\n\n1. Record old-to-new mapping.\n2. Configure Primary Asset ID/type/name redirects where Asset Manager identity changed.\n3. Migrate save data and external references explicitly.\n4. Validate that old IDs resolve or fail with a controlled migration message.\n5. Test an upgrade from a real previous save and cooked build.\n\nAsset redirectors repair package references; they do not automatically migrate every string,\nrow name, gameplay tag, save payload, or external service key.\n\n## Definition versus state\n\nUse this split:\n\n```text\nDefinition asset/table row\n  stable ID, display data, tuning, soft content references\n\nRuntime state\n  definition ID, quantity, durability, ownership, cooldown, progress\n\nSave payload\n  stable definition ID, version, minimal authoritative state\n```\n\nResolve the definition after loading a save. Handle missing definitions with a documented\nfallback, quarantine, refund, or migration; never crash on an unchecked lookup.\n\n## Schema changes\n\n- Add fields with safe defaults.\n- Validate old imports against renamed/removed columns.\n- Keep serialization versioning separate from the current asset schema.\n- For computed/derived values, prefer recomputation over persisting redundant state.\n- Run reimport, validation, cook, and previous-save migration after structural changes.\n","webMarkdown":"## Stable identity\n\nChoose an identifier before content volume grows:\n\n- Primary Assets: `FPrimaryAssetId` (`Type:Name`).\n- Data Table rows: stable `FName` row key or a domain ID stored and validated in the row.\n- Data Registry items: `FDataRegistryId`.\n- Cross-system categories/state: governed Gameplay Tags where hierarchy is useful.\n\nDisplay names are localized presentation, never durable identity. Array index and editor\nposition are not identity.\n\n## Rename policy\n\nTreat shipped IDs as append-only contracts. When a rename is unavoidable:\n\n1. Record old-to-new mapping.\n2. Configure Primary Asset ID/type/name redirects where Asset Manager identity changed.\n3. Migrate save data and external references explicitly.\n4. Validate that old IDs resolve or fail with a controlled migration message.\n5. Test an upgrade from a real previous save and cooked build.\n\nAsset redirectors repair package references; they do not automatically migrate every string,\nrow name, gameplay tag, save payload, or external service key.\n\n## Definition versus state\n\nUse this split:\n\n```text\nDefinition asset/table row\n  stable ID, display data, tuning, soft content references\n\nRuntime state\n  definition ID, quantity, durability, ownership, cooldown, progress\n\nSave payload\n  stable definition ID, version, minimal authoritative state\n```\n\nResolve the definition after loading a save. Handle missing definitions with a documented\nfallback, quarantine, refund, or migration; never crash on an unchecked lookup.\n\n## Schema changes\n\n- Add fields with safe defaults.\n- Validate old imports against renamed/removed columns.\n- Keep serialization versioning separate from the current asset schema.\n- For computed/derived values, prefer recomputation over persisting redundant state.\n- Run reimport, validation, cook, and previous-save migration after structural changes.\n","searchText":"identifiers, state, and schema evolution stable identity choose an identifier before content volume grows: - primary assets: fprimaryassetid (type:name). - data table rows: stable fname row key or a domain id stored and validated in the row. - data registry items: fdataregistryid. - cross-system categories/state: governed gameplay tags where hierarchy is useful. display names are localized presentation, never durable identity. array index and editor position are not identity. rename policy treat shipped ids as append-only contracts. when a rename is unavoidable: 1. record old-to-new mapping. 2. configure primary asset id/type/name redirects where asset manager identity changed. 3. migrate save data and external references explicitly. 4. validate that old ids resolve or fail with a controlled migration message. 5. test an upgrade from a real previous save and cooked build. asset redirectors repair package references; they do not automatically migrate every string, row name, gameplay tag, save payload, or external service key. definition versus state use this split: text definition asset/table row stable id, display data, tuning, soft content references runtime state definition id, quantity, durability, ownership, cooldown, progress save payload stable definition id, version, minimal authoritative state resolve the definition after loading a save. handle missing definitions with a documented fallback, quarantine, refund, or migration; never crash on an unchecked lookup. schema changes - add fields with safe defaults. - validate old imports against renamed/removed columns. - keep serialization versioning separate from the current asset schema. - for computed/derived values, prefer recomputation over persisting redundant state. - run reimport, validation, cook, and previous-save migration after structural changes."},{"slug":"patterns","file":"patterns.md","title":"Concrete data patterns","rawMarkdown":"# Concrete data patterns\n\n## Item catalog with runtime inventory\n\n```text\nUItemDefinition : UPrimaryDataAsset\n  ItemId or stable PrimaryAssetId\n  DisplayName, Tags, tuning\n  UI bundle: icon\n  Gameplay bundle: actor class, mesh/effects\n\nFInventoryEntry (runtime/save)\n  DefinitionId\n  Quantity\n  Durability\n  Instance modifiers\n```\n\nLoad `UI` for menus; load `Gameplay` before spawning/equipping. The definition never stores\nquantity or ownership.\n\n## Balance table\n\nUse one `FTableRowBase` schema for homogeneous weapon or progression values. Put heavy visual\nassets behind soft references. Expose `FDataTableRowHandle` to authored consumers. Validate\nunique domain IDs, monotonic thresholds where required, and all referenced rows.\n\n## Layered tuning\n\nUse a Composite Data Table only for a small, visible base-to-override stack sharing one schema.\nValidate duplicate-row precedence. If sources are discovered dynamically, asynchronously\nacquired, or cached under different lifetimes, use a Data Registry instead.\n\n## Catalog browser tool\n\nQuery the Asset Registry by narrow path/class/tag filters, display `FAssetData`, then load only\nthe selected record. Never load the entire catalog merely to populate a list.\n\n## Menu-to-match preload\n\n1. Resolve selected Primary Asset IDs.\n2. Request the next phase's bundles asynchronously.\n3. Display progress and allow controlled cancellation.\n4. Verify every required object in completion.\n5. Transfer ownership to the match/session object.\n6. Enter the match only after required content is resident.\n7. Release at match teardown after dependent actors are gone.\n\n## Validation CI gate\n\nRun C++ data validation in a headless editor job, capture exit status and logs, then cook a\nrepresentative target. Treat invalid definition assets and missing cook dependencies as build\nfailures. Keep expensive full-project relationship checks separate from fast on-save checks.\n","webMarkdown":"## Item catalog with runtime inventory\n\n```text\nUItemDefinition : UPrimaryDataAsset\n  ItemId or stable PrimaryAssetId\n  DisplayName, Tags, tuning\n  UI bundle: icon\n  Gameplay bundle: actor class, mesh/effects\n\nFInventoryEntry (runtime/save)\n  DefinitionId\n  Quantity\n  Durability\n  Instance modifiers\n```\n\nLoad `UI` for menus; load `Gameplay` before spawning/equipping. The definition never stores\nquantity or ownership.\n\n## Balance table\n\nUse one `FTableRowBase` schema for homogeneous weapon or progression values. Put heavy visual\nassets behind soft references. Expose `FDataTableRowHandle` to authored consumers. Validate\nunique domain IDs, monotonic thresholds where required, and all referenced rows.\n\n## Layered tuning\n\nUse a Composite Data Table only for a small, visible base-to-override stack sharing one schema.\nValidate duplicate-row precedence. If sources are discovered dynamically, asynchronously\nacquired, or cached under different lifetimes, use a Data Registry instead.\n\n## Catalog browser tool\n\nQuery the Asset Registry by narrow path/class/tag filters, display `FAssetData`, then load only\nthe selected record. Never load the entire catalog merely to populate a list.\n\n## Menu-to-match preload\n\n1. Resolve selected Primary Asset IDs.\n2. Request the next phase's bundles asynchronously.\n3. Display progress and allow controlled cancellation.\n4. Verify every required object in completion.\n5. Transfer ownership to the match/session object.\n6. Enter the match only after required content is resident.\n7. Release at match teardown after dependent actors are gone.\n\n## Validation CI gate\n\nRun C++ data validation in a headless editor job, capture exit status and logs, then cook a\nrepresentative target. Treat invalid definition assets and missing cook dependencies as build\nfailures. Keep expensive full-project relationship checks separate from fast on-save checks.\n","searchText":"concrete data patterns item catalog with runtime inventory text uitemdefinition : uprimarydataasset itemid or stable primaryassetid displayname, tags, tuning ui bundle: icon gameplay bundle: actor class, mesh/effects finventoryentry (runtime/save) definitionid quantity durability instance modifiers load ui for menus; load gameplay before spawning/equipping. the definition never stores quantity or ownership. balance table use one ftablerowbase schema for homogeneous weapon or progression values. put heavy visual assets behind soft references. expose fdatatablerowhandle to authored consumers. validate unique domain ids, monotonic thresholds where required, and all referenced rows. layered tuning use a composite data table only for a small, visible base-to-override stack sharing one schema. validate duplicate-row precedence. if sources are discovered dynamically, asynchronously acquired, or cached under different lifetimes, use a data registry instead. catalog browser tool query the asset registry by narrow path/class/tag filters, display fassetdata, then load only the selected record. never load the entire catalog merely to populate a list. menu-to-match preload 1. resolve selected primary asset ids. 2. request the next phase's bundles asynchronously. 3. display progress and allow controlled cancellation. 4. verify every required object in completion. 5. transfer ownership to the match/session object. 6. enter the match only after required content is resident. 7. release at match teardown after dependent actors are gone. validation ci gate run c++ data validation in a headless editor job, capture exit status and logs, then cook a representative target. treat invalid definition assets and missing cook dependencies as build failures. keep expensive full-project relationship checks separate from fast on-save checks."},{"slug":"references-loading","file":"references-loading.md","title":"Hard references, soft references, and load ownership","rawMarkdown":"# Hard references, soft references, and load ownership\n\n## Choose the edge\n\nUse a hard `TObjectPtr<T>`/class reference when the target must be resident whenever its\nowner is resident and the dependency is acceptably small.\n\nUse `TSoftObjectPtr<T>`, `TSoftClassPtr<T>`, or `FSoftObjectPath` when the target should not\nload with the owner, content is optional, or a large catalog must remain unloaded.\n\nSoft does not mean free:\n\n- callers must load before dereference;\n- failure, cancellation, and race behavior must be defined;\n- a path does not keep the object resident after loading;\n- cook inclusion still needs a discoverable rule.\n\n## Async load pattern\n\n1. Gather soft paths or Primary Asset IDs before the transition that needs them.\n2. Request asynchronous loading through Asset Manager or a suitable Streamable Manager.\n3. Retain the `FStreamableHandle` when cancellation, progress, combined requests, or\n   explicit residency management matters.\n4. In completion, verify the handle/request and every required asset.\n5. Transfer loaded objects into a hard owner for their use lifetime, or keep the handle\n   alive according to the chosen API.\n6. Release the owner/handle at the explicit unload boundary.\n\nNever call a synchronous load in a latency-sensitive path merely because the soft pointer\nAPI offers it. Small editor utilities and controlled loading screens may accept blocking;\ngameplay and streaming paths normally should not.\n\n## Reference audit\n\nUse **Reference Viewer** and **Size Map/Asset Audit** to find accidental hard dependency\nchains. A lightweight definition that hard-references one Blueprint can pull in that\nBlueprint's complete dependency graph.\n\nFor a suspect asset, report:\n\n- why it is loaded;\n- which edge is hard;\n- what the correct load boundary is;\n- whether converting the edge to soft changes cook rules;\n- how residency will be proven on target hardware.\n","webMarkdown":"## Choose the edge\n\nUse a hard `TObjectPtr<T>`/class reference when the target must be resident whenever its\nowner is resident and the dependency is acceptably small.\n\nUse `TSoftObjectPtr<T>`, `TSoftClassPtr<T>`, or `FSoftObjectPath` when the target should not\nload with the owner, content is optional, or a large catalog must remain unloaded.\n\nSoft does not mean free:\n\n- callers must load before dereference;\n- failure, cancellation, and race behavior must be defined;\n- a path does not keep the object resident after loading;\n- cook inclusion still needs a discoverable rule.\n\n## Async load pattern\n\n1. Gather soft paths or Primary Asset IDs before the transition that needs them.\n2. Request asynchronous loading through Asset Manager or a suitable Streamable Manager.\n3. Retain the `FStreamableHandle` when cancellation, progress, combined requests, or\n   explicit residency management matters.\n4. In completion, verify the handle/request and every required asset.\n5. Transfer loaded objects into a hard owner for their use lifetime, or keep the handle\n   alive according to the chosen API.\n6. Release the owner/handle at the explicit unload boundary.\n\nNever call a synchronous load in a latency-sensitive path merely because the soft pointer\nAPI offers it. Small editor utilities and controlled loading screens may accept blocking;\ngameplay and streaming paths normally should not.\n\n## Reference audit\n\nUse **Reference Viewer** and **Size Map/Asset Audit** to find accidental hard dependency\nchains. A lightweight definition that hard-references one Blueprint can pull in that\nBlueprint's complete dependency graph.\n\nFor a suspect asset, report:\n\n- why it is loaded;\n- which edge is hard;\n- what the correct load boundary is;\n- whether converting the edge to soft changes cook rules;\n- how residency will be proven on target hardware.\n","searchText":"hard references, soft references, and load ownership choose the edge use a hard tobjectptr<t>/class reference when the target must be resident whenever its owner is resident and the dependency is acceptably small. use tsoftobjectptr<t>, tsoftclassptr<t>, or fsoftobjectpath when the target should not load with the owner, content is optional, or a large catalog must remain unloaded. soft does not mean free: - callers must load before dereference; - failure, cancellation, and race behavior must be defined; - a path does not keep the object resident after loading; - cook inclusion still needs a discoverable rule. async load pattern 1. gather soft paths or primary asset ids before the transition that needs them. 2. request asynchronous loading through asset manager or a suitable streamable manager. 3. retain the fstreamablehandle when cancellation, progress, combined requests, or explicit residency management matters. 4. in completion, verify the handle/request and every required asset. 5. transfer loaded objects into a hard owner for their use lifetime, or keep the handle alive according to the chosen api. 6. release the owner/handle at the explicit unload boundary. never call a synchronous load in a latency-sensitive path merely because the soft pointer api offers it. small editor utilities and controlled loading screens may accept blocking; gameplay and streaming paths normally should not. reference audit use reference viewer and size map/asset audit to find accidental hard dependency chains. a lightweight definition that hard-references one blueprint can pull in that blueprint's complete dependency graph. for a suspect asset, report: - why it is loaded; - which edge is hard; - what the correct load boundary is; - whether converting the edge to soft changes cook rules; - how residency will be proven on target hardware."},{"slug":"selector-model","file":"selector-model.md","title":"Representation selector","rawMarkdown":"# Representation selector\n\n## Decision table\n\n| Need | Choose | Reject when |\n|---|---|---|\n| One authored definition with named fields | `UDataAsset` instance | It needs Asset Manager identity/loading or inheritance |\n| Individually discoverable/loadable definition | `UPrimaryDataAsset` | It is only a small row in one always-loaded table |\n| Definition inheritance | Data-Only Blueprint derived from a suitable base | Inheritance would hide important per-item differences |\n| Many records with one flat schema | `UDataTable` | Records need different shapes, behavior, or independent load policy |\n| Numeric values over an input axis | `UCurveTable` | The row contains nonnumeric definition data |\n| Ordered table overlays | `UCompositeDataTable` | Sources need asynchronous acquisition, caching, or flexible resolution |\n| Multiple read-only sources with fallback/overrides | Data Registry | One table or asset set is sufficient |\n| Search unloaded asset metadata | Asset Registry | The actual object must be executed or inspected beyond stored metadata |\n| Mutable session/player state | Runtime owner plus SaveGame where persistent | Never store it in a shared definition asset |\n\n## Selection questions\n\nAnswer in order:\n\n1. Is this authored definition or mutable runtime state?\n2. Does every record share the same schema?\n3. Does each record need independent identity, inheritance, loading, or cook rules?\n4. Must heavy dependencies load with the definition?\n5. Must content be discovered without loading it?\n6. Will shipped identifiers survive renames and schema changes?\n\nPrefer one simple Data Table or Data Asset until a demonstrated loading, override, or\nproduction requirement justifies Asset Manager or Data Registry machinery.\n\n## Boundaries\n\n- A Data Table row is a value in a table, not a polymorphic object.\n- A Data Asset is a `UObject` asset instance. A Data-Only Blueprint is a class and gains\n  inheritance through class defaults.\n- A Primary Data Asset is not automatically discovered merely because it derives from\n  `UPrimaryDataAsset`; configure its type and scan path or register it in code.\n- Data Registries are for general read-only data. Use SaveGame for story progress,\n  inventories, unlocks, or other mutable persistence.\n","webMarkdown":"## Decision table\n\n| Need | Choose | Reject when |\n|---|---|---|\n| One authored definition with named fields | `UDataAsset` instance | It needs Asset Manager identity/loading or inheritance |\n| Individually discoverable/loadable definition | `UPrimaryDataAsset` | It is only a small row in one always-loaded table |\n| Definition inheritance | Data-Only Blueprint derived from a suitable base | Inheritance would hide important per-item differences |\n| Many records with one flat schema | `UDataTable` | Records need different shapes, behavior, or independent load policy |\n| Numeric values over an input axis | `UCurveTable` | The row contains nonnumeric definition data |\n| Ordered table overlays | `UCompositeDataTable` | Sources need asynchronous acquisition, caching, or flexible resolution |\n| Multiple read-only sources with fallback/overrides | Data Registry | One table or asset set is sufficient |\n| Search unloaded asset metadata | Asset Registry | The actual object must be executed or inspected beyond stored metadata |\n| Mutable session/player state | Runtime owner plus SaveGame where persistent | Never store it in a shared definition asset |\n\n## Selection questions\n\nAnswer in order:\n\n1. Is this authored definition or mutable runtime state?\n2. Does every record share the same schema?\n3. Does each record need independent identity, inheritance, loading, or cook rules?\n4. Must heavy dependencies load with the definition?\n5. Must content be discovered without loading it?\n6. Will shipped identifiers survive renames and schema changes?\n\nPrefer one simple Data Table or Data Asset until a demonstrated loading, override, or\nproduction requirement justifies Asset Manager or Data Registry machinery.\n\n## Boundaries\n\n- A Data Table row is a value in a table, not a polymorphic object.\n- A Data Asset is a `UObject` asset instance. A Data-Only Blueprint is a class and gains\n  inheritance through class defaults.\n- A Primary Data Asset is not automatically discovered merely because it derives from\n  `UPrimaryDataAsset`; configure its type and scan path or register it in code.\n- Data Registries are for general read-only data. Use SaveGame for story progress,\n  inventories, unlocks, or other mutable persistence.\n","searchText":"representation selector decision table | need | choose | reject when | |---|---|---| | one authored definition with named fields | udataasset instance | it needs asset manager identity/loading or inheritance | | individually discoverable/loadable definition | uprimarydataasset | it is only a small row in one always-loaded table | | definition inheritance | data-only blueprint derived from a suitable base | inheritance would hide important per-item differences | | many records with one flat schema | udatatable | records need different shapes, behavior, or independent load policy | | numeric values over an input axis | ucurvetable | the row contains nonnumeric definition data | | ordered table overlays | ucompositedatatable | sources need asynchronous acquisition, caching, or flexible resolution | | multiple read-only sources with fallback/overrides | data registry | one table or asset set is sufficient | | search unloaded asset metadata | asset registry | the actual object must be executed or inspected beyond stored metadata | | mutable session/player state | runtime owner plus savegame where persistent | never store it in a shared definition asset | selection questions answer in order: 1. is this authored definition or mutable runtime state? 2. does every record share the same schema? 3. does each record need independent identity, inheritance, loading, or cook rules? 4. must heavy dependencies load with the definition? 5. must content be discovered without loading it? 6. will shipped identifiers survive renames and schema changes? prefer one simple data table or data asset until a demonstrated loading, override, or production requirement justifies asset manager or data registry machinery. boundaries - a data table row is a value in a table, not a polymorphic object. - a data asset is a uobject asset instance. a data-only blueprint is a class and gains inheritance through class defaults. - a primary data asset is not automatically discovered merely because it derives from uprimarydataasset; configure its type and scan path or register it in code. - data registries are for general read-only data. use savegame for story progress, inventories, unlocks, or other mutable persistence."},{"slug":"sources","file":"sources.md","title":"UE 5.8 primary sources","rawMarkdown":"# UE 5.8 primary sources\n\nVerified against Epic Games documentation for Unreal Engine 5.8 on 2026-07-19.\n\n- [Data Assets](https://dev.epicgames.com/documentation/en-us/unreal-engine/data-assets-in-unreal-engine)\n- [Asset Management](https://dev.epicgames.com/documentation/en-us/unreal-engine/asset-management-in-unreal-engine)\n- [Data Driven Gameplay Elements](https://dev.epicgames.com/documentation/en-us/unreal-engine/data-driven-gameplay-elements-in-unreal-engine)\n- [Object Pointers](https://dev.epicgames.com/documentation/en-us/unreal-engine/object-pointers-in-unreal-engine)\n- [Asynchronous Asset Loading](https://dev.epicgames.com/documentation/en-us/unreal-engine/asynchronous-asset-loading-in-unreal-engine)\n- [Asset Registry](https://dev.epicgames.com/documentation/en-us/unreal-engine/asset-registry-in-unreal-engine)\n- [Data Registries](https://dev.epicgames.com/documentation/en-us/unreal-engine/data-registries-in-unreal-engine)\n- [Data Validation](https://dev.epicgames.com/documentation/en-us/unreal-engine/data-validation-in-unreal-engine)\n- [Cooking and Chunking](https://dev.epicgames.com/documentation/en-us/unreal-engine/cooking-content-and-creating-chunks-in-unreal-engine)\n- [Preparing Assets for Chunking](https://dev.epicgames.com/documentation/en-us/unreal-engine/preparing-assets-for-chunking-in-unreal-engine)\n- [`UPrimaryDataAsset` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/UPrimaryDataAsset)\n- [`UPrimaryAssetLabel` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/UPrimaryAssetLabel)\n- [`UDataTable` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/UDataTable)\n- [`FPrimaryAssetRules` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/FPrimaryAssetRules)\n\nVersion-sensitive notes retained in this package:\n\n- Primary Asset Label Blueprint subclasses do not work for chunking.\n- Data Table/Curve Table pointers should not be cached beyond local scope across reimport.\n- Data Registry-owned item pointers can become invalid when dynamically sourced data unloads.\n- Data Validation commandlets run C++ rules by default; Python validators require registration.\n","webMarkdown":"Verified against Epic Games documentation for Unreal Engine 5.8 on 2026-07-19.\n\n- [Data Assets](https://dev.epicgames.com/documentation/en-us/unreal-engine/data-assets-in-unreal-engine)\n- [Asset Management](https://dev.epicgames.com/documentation/en-us/unreal-engine/asset-management-in-unreal-engine)\n- [Data Driven Gameplay Elements](https://dev.epicgames.com/documentation/en-us/unreal-engine/data-driven-gameplay-elements-in-unreal-engine)\n- [Object Pointers](https://dev.epicgames.com/documentation/en-us/unreal-engine/object-pointers-in-unreal-engine)\n- [Asynchronous Asset Loading](https://dev.epicgames.com/documentation/en-us/unreal-engine/asynchronous-asset-loading-in-unreal-engine)\n- [Asset Registry](https://dev.epicgames.com/documentation/en-us/unreal-engine/asset-registry-in-unreal-engine)\n- [Data Registries](https://dev.epicgames.com/documentation/en-us/unreal-engine/data-registries-in-unreal-engine)\n- [Data Validation](https://dev.epicgames.com/documentation/en-us/unreal-engine/data-validation-in-unreal-engine)\n- [Cooking and Chunking](https://dev.epicgames.com/documentation/en-us/unreal-engine/cooking-content-and-creating-chunks-in-unreal-engine)\n- [Preparing Assets for Chunking](https://dev.epicgames.com/documentation/en-us/unreal-engine/preparing-assets-for-chunking-in-unreal-engine)\n- [`UPrimaryDataAsset` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/UPrimaryDataAsset)\n- [`UPrimaryAssetLabel` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/UPrimaryAssetLabel)\n- [`UDataTable` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/UDataTable)\n- [`FPrimaryAssetRules` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/FPrimaryAssetRules)\n\nVersion-sensitive notes retained in this package:\n\n- Primary Asset Label Blueprint subclasses do not work for chunking.\n- Data Table/Curve Table pointers should not be cached beyond local scope across reimport.\n- Data Registry-owned item pointers can become invalid when dynamically sourced data unloads.\n- Data Validation commandlets run C++ rules by default; Python validators require registration.\n","searchText":"ue 5.8 primary sources verified against epic games documentation for unreal engine 5.8 on 2026-07-19. - data assets - asset management - data driven gameplay elements - object pointers - asynchronous asset loading - asset registry - data registries - data validation - cooking and chunking - preparing assets for chunking - uprimarydataasset api - uprimaryassetlabel api - udatatable api - fprimaryassetrules api version-sensitive notes retained in this package: - primary asset label blueprint subclasses do not work for chunking. - data table/curve table pointers should not be cached beyond local scope across reimport. - data registry-owned item pointers can become invalid when dynamically sourced data unloads. - data validation commandlets run c++ rules by default; python validators require registration."},{"slug":"validation-debugging","file":"validation-debugging.md","title":"Validation and debugging","rawMarkdown":"# Validation and debugging\n\n## Validation placement\n\nUse both layers when appropriate:\n\n- Override `IsDataValid` on the definition class for invariants that belong to that object.\n- Derive `UEditorValidatorBase` to validate assets across engine/custom classes or enforce\n  project-wide policy. Implement `CanValidateAsset` and ensure every `ValidateLoadedAsset`\n  path calls `AssetPasses` or `AssetFails`.\n\nValidate through Content Browser actions, **Tools > Validate Data**, and CI:\n\n```text\nUnrealEditor-Cmd.exe Project.uproject -run=DataValidation\n```\n\nThe commandlet runs C++ rules by default. Blueprint/Python validation support requires\nexplicit extension; Python validators must register with `UEditorValidatorSubsystem`.\n\n## Definition checks\n\nAt minimum validate:\n\n- ID is present, unique, governed, and consistent with the asset/row when required;\n- numeric values are finite and within domain ranges;\n- required hard/soft references resolve and have allowed classes;\n- mutually exclusive options are not both selected;\n- dependent fields are present together;\n- rows/reference targets exist;\n- no forbidden dependency cycle or editor-only content crosses into runtime;\n- Asset Manager ID and bundle/cook expectations are satisfied.\n\nUse errors for content that cannot ship and warnings for suspicious but valid states. Include\nasset path, field, received value, expected rule, and a repair action in every message.\n\n## Failure routing\n\n| Symptom | Check first |\n|---|---|\n| Primary Asset ID not found | Actual ID, type config, base-class mode, scan path, excluded path |\n| Soft pointer is null | Was it loaded, did load finish, did the path redirect, is target cooked? |\n| Table lookup fails | Correct table, exact row key, schema/import warnings, reimport result |\n| Values do not update | Cached row pointer/copy, stale reimport, wrong source authority |\n| Unexpected memory spike | Hard reference chain, broad bundle, synchronous load, retained handle |\n| Works in PIE, fails packaged | Cook rule, Primary Asset Label, editor-only class/path, chunk availability |\n| Registry query misses assets | Initial scan incomplete, wrong class path/filter, asset not resaved for tags |\n\nLog stable IDs and package paths at load boundaries. Do not “fix” missing data by silently\nsubstituting unrelated content unless the product explicitly defines that fallback.\n","webMarkdown":"## Validation placement\n\nUse both layers when appropriate:\n\n- Override `IsDataValid` on the definition class for invariants that belong to that object.\n- Derive `UEditorValidatorBase` to validate assets across engine/custom classes or enforce\n  project-wide policy. Implement `CanValidateAsset` and ensure every `ValidateLoadedAsset`\n  path calls `AssetPasses` or `AssetFails`.\n\nValidate through Content Browser actions, **Tools > Validate Data**, and CI:\n\n```text\nUnrealEditor-Cmd.exe Project.uproject -run=DataValidation\n```\n\nThe commandlet runs C++ rules by default. Blueprint/Python validation support requires\nexplicit extension; Python validators must register with `UEditorValidatorSubsystem`.\n\n## Definition checks\n\nAt minimum validate:\n\n- ID is present, unique, governed, and consistent with the asset/row when required;\n- numeric values are finite and within domain ranges;\n- required hard/soft references resolve and have allowed classes;\n- mutually exclusive options are not both selected;\n- dependent fields are present together;\n- rows/reference targets exist;\n- no forbidden dependency cycle or editor-only content crosses into runtime;\n- Asset Manager ID and bundle/cook expectations are satisfied.\n\nUse errors for content that cannot ship and warnings for suspicious but valid states. Include\nasset path, field, received value, expected rule, and a repair action in every message.\n\n## Failure routing\n\n| Symptom | Check first |\n|---|---|\n| Primary Asset ID not found | Actual ID, type config, base-class mode, scan path, excluded path |\n| Soft pointer is null | Was it loaded, did load finish, did the path redirect, is target cooked? |\n| Table lookup fails | Correct table, exact row key, schema/import warnings, reimport result |\n| Values do not update | Cached row pointer/copy, stale reimport, wrong source authority |\n| Unexpected memory spike | Hard reference chain, broad bundle, synchronous load, retained handle |\n| Works in PIE, fails packaged | Cook rule, Primary Asset Label, editor-only class/path, chunk availability |\n| Registry query misses assets | Initial scan incomplete, wrong class path/filter, asset not resaved for tags |\n\nLog stable IDs and package paths at load boundaries. Do not “fix” missing data by silently\nsubstituting unrelated content unless the product explicitly defines that fallback.\n","searchText":"validation and debugging validation placement use both layers when appropriate: - override isdatavalid on the definition class for invariants that belong to that object. - derive ueditorvalidatorbase to validate assets across engine/custom classes or enforce project-wide policy. implement canvalidateasset and ensure every validateloadedasset path calls assetpasses or assetfails. validate through content browser actions, tools > validate data, and ci: text unrealeditor-cmd.exe project.uproject -run=datavalidation the commandlet runs c++ rules by default. blueprint/python validation support requires explicit extension; python validators must register with ueditorvalidatorsubsystem. definition checks at minimum validate: - id is present, unique, governed, and consistent with the asset/row when required; - numeric values are finite and within domain ranges; - required hard/soft references resolve and have allowed classes; - mutually exclusive options are not both selected; - dependent fields are present together; - rows/reference targets exist; - no forbidden dependency cycle or editor-only content crosses into runtime; - asset manager id and bundle/cook expectations are satisfied. use errors for content that cannot ship and warnings for suspicious but valid states. include asset path, field, received value, expected rule, and a repair action in every message. failure routing | symptom | check first | |---|---| | primary asset id not found | actual id, type config, base-class mode, scan path, excluded path | | soft pointer is null | was it loaded, did load finish, did the path redirect, is target cooked? | | table lookup fails | correct table, exact row key, schema/import warnings, reimport result | | values do not update | cached row pointer/copy, stale reimport, wrong source authority | | unexpected memory spike | hard reference chain, broad bundle, synchronous load, retained handle | | works in pie, fails packaged | cook rule, primary asset label, editor-only class/path, chunk availability | | registry query misses assets | initial scan incomplete, wrong class path/filter, asset not resaved for tags | log stable ids and package paths at load boundaries. do not “fix” missing data by silently substituting unrelated content unless the product explicitly defines that fallback."}]}
{"slug":"unreal-editor-automation","name":"unreal-editor-automation","title":"Unreal 5.8 Editor Automation","description":"Design, implement, run, and debug safe Unreal Editor automation for Unreal Engine 5.8. Use for Editor Utility Widgets, Editor Utility Blueprints, Scripted Actions, Call in Editor, Scriptable Tools, Python Editor scripting, editor subsystems, asset import or batch mutation, commandlets, CI, Data Validation, Automation Tests, Functional Tests, transactions, source control, or the experimental Unreal MCP server and AI-driven editor tools.","shortDescription":"Automate Unreal Editor workflows safely","category":"Data, Tools & Shipping","referenceCount":11,"rawMarkdown":"---\nname: unreal-editor-automation\ndescription: Design, implement, run, and debug safe Unreal Editor automation for Unreal Engine 5.8. Use for Editor Utility Widgets, Editor Utility Blueprints, Scripted Actions, Call in Editor, Scriptable Tools, Python Editor scripting, editor subsystems, asset import or batch mutation, commandlets, CI, Data Validation, Automation Tests, Functional Tests, transactions, source control, or the experimental Unreal MCP server and AI-driven editor tools.\n---\n\n# Unreal 5.8 Editor Automation\n\n## Select the automation surface\n\nRead [`references/selector-architecture.md`](references/selector-architecture.md).\n\n- Use a **Scripted Action** for a contextual operation on selected assets or actors.\n- Use an **Editor Utility Widget** for a persistent dockable UI and human-reviewed batch work.\n- Use **Call in Editor** for an action attached to a placed Actor that also has runtime use.\n- Use a **Scriptable Tool** for modal viewport interaction with accept/cancel semantics.\n- Use **Python** for text-based pipelines, cross-DCC integration, and repeatable batches.\n- Use a **commandlet** for unattended/headless work and CI.\n- Use **Data Validation** for asset invariants, not as a general behavior-test framework.\n- Use **Automation/Functional Tests** for code, system, map, gameplay, and regression checks.\n- Use **Unreal MCP** only for bounded AI tool calls in 5.8; it is Experimental.\n\n## Execute safely\n\n1. Define selection/input scope, mutation set, source-control behavior, undo boundary,\n   save policy, cancellation, logs, and validation before writing the tool.\n2. Separate discovery and planning from mutation. Produce a dry-run report for destructive,\n   bulk, or difficult-to-reverse work.\n3. Use editor APIs for assets and packages. Never move, rename, or delete `.uasset` files\n   with generic filesystem operations.\n4. Use `get_editor_property`/`set_editor_property` when scripting reflected editor data so\n   editor change notifications run.\n5. Wrap only genuinely undoable changes in a transaction. Import, save, source-control,\n   and many package operations are not made reversible by a transaction.\n6. Mark changed objects/packages dirty, save deliberately, and report every failure.\n7. Make reruns idempotent or detect prior output. Test on a disposable subset before the\n   full content tree.\n8. Run validation/tests and inspect the actual diff before submission.\n\nLoad the task reference:\n\n- UI/Blueprint tools: [`references/editor-utilities-blueprint.md`](references/editor-utilities-blueprint.md)\n- Python execution/APIs: [`references/python-workflows.md`](references/python-workflows.md)\n- mutation guardrails: [`references/safe-asset-mutation.md`](references/safe-asset-mutation.md)\n- command line/CI: [`references/commandlets-headless-ci.md`](references/commandlets-headless-ci.md)\n- Data Validation: [`references/data-validation.md`](references/data-validation.md)\n- test frameworks: [`references/automation-tests.md`](references/automation-tests.md)\n- Unreal MCP: [`references/unreal-mcp.md`](references/unreal-mcp.md)\n- concrete tools: [`references/patterns.md`](references/patterns.md)\n- recovery: [`references/debugging-recovery.md`](references/debugging-recovery.md)\n\n## Required answer format\n\nReturn:\n\n1. **Automation surface** and maturity status.\n2. **Inputs, selection filters, preconditions, and dry-run output**.\n3. **Ordered API/node/command sequence** with editor/runtime boundaries.\n4. **Transaction, source-control, save, cancellation, and idempotency policy**.\n5. **Validation/test procedure**, logs, exit criteria, and expected diff.\n6. **Failure recovery** and any operation that cannot be undone.\n\nDo not invent nodes, APIs, command-line flags, defaults, or MCP tools. Inspect the enabled\n5.8 API/tool schema when exact availability matters.\n\n## Hard rules\n\n- Never operate directly on `.uasset`/`.umap` files with `os`, `shutil`, or shell moves.\n- Never run a bulk mutation before a scoped dry run or disposable-copy test.\n- Never assume a transaction makes import, save, delete, or source-control work reversible.\n- Never autosave unrelated dirty packages.\n- Never suppress per-asset failures and still report success.\n- Never run Python as gameplay code; UE 5.8's embedded Python is editor-only.\n- Never expose Unreal MCP beyond loopback; it has no authentication layer.\n- Never issue overlapping Unreal MCP tool calls; the server serializes them on the game thread.\n- Never let an AI infer permission for destructive or project-wide mutations.\n\nSee [`references/sources.md`](references/sources.md) for the UE 5.8 source trail.\n","webMarkdown":"## Select the automation surface\n\nRead [`references/selector-architecture.md`](/unreal/unreal-editor-automation/selector-architecture/).\n\n- Use a **Scripted Action** for a contextual operation on selected assets or actors.\n- Use an **Editor Utility Widget** for a persistent dockable UI and human-reviewed batch work.\n- Use **Call in Editor** for an action attached to a placed Actor that also has runtime use.\n- Use a **Scriptable Tool** for modal viewport interaction with accept/cancel semantics.\n- Use **Python** for text-based pipelines, cross-DCC integration, and repeatable batches.\n- Use a **commandlet** for unattended/headless work and CI.\n- Use **Data Validation** for asset invariants, not as a general behavior-test framework.\n- Use **Automation/Functional Tests** for code, system, map, gameplay, and regression checks.\n- Use **Unreal MCP** only for bounded AI tool calls in 5.8; it is Experimental.\n\n## Execute safely\n\n1. Define selection/input scope, mutation set, source-control behavior, undo boundary,\n   save policy, cancellation, logs, and validation before writing the tool.\n2. Separate discovery and planning from mutation. Produce a dry-run report for destructive,\n   bulk, or difficult-to-reverse work.\n3. Use editor APIs for assets and packages. Never move, rename, or delete `.uasset` files\n   with generic filesystem operations.\n4. Use `get_editor_property`/`set_editor_property` when scripting reflected editor data so\n   editor change notifications run.\n5. Wrap only genuinely undoable changes in a transaction. Import, save, source-control,\n   and many package operations are not made reversible by a transaction.\n6. Mark changed objects/packages dirty, save deliberately, and report every failure.\n7. Make reruns idempotent or detect prior output. Test on a disposable subset before the\n   full content tree.\n8. Run validation/tests and inspect the actual diff before submission.\n\nLoad the task reference:\n\n- UI/Blueprint tools: [`references/editor-utilities-blueprint.md`](/unreal/unreal-editor-automation/editor-utilities-blueprint/)\n- Python execution/APIs: [`references/python-workflows.md`](/unreal/unreal-editor-automation/python-workflows/)\n- mutation guardrails: [`references/safe-asset-mutation.md`](/unreal/unreal-editor-automation/safe-asset-mutation/)\n- command line/CI: [`references/commandlets-headless-ci.md`](/unreal/unreal-editor-automation/commandlets-headless-ci/)\n- Data Validation: [`references/data-validation.md`](/unreal/unreal-editor-automation/data-validation/)\n- test frameworks: [`references/automation-tests.md`](/unreal/unreal-editor-automation/automation-tests/)\n- Unreal MCP: [`references/unreal-mcp.md`](/unreal/unreal-editor-automation/unreal-mcp/)\n- concrete tools: [`references/patterns.md`](/unreal/unreal-editor-automation/patterns/)\n- recovery: [`references/debugging-recovery.md`](/unreal/unreal-editor-automation/debugging-recovery/)\n\n## Required answer format\n\nReturn:\n\n1. **Automation surface** and maturity status.\n2. **Inputs, selection filters, preconditions, and dry-run output**.\n3. **Ordered API/node/command sequence** with editor/runtime boundaries.\n4. **Transaction, source-control, save, cancellation, and idempotency policy**.\n5. **Validation/test procedure**, logs, exit criteria, and expected diff.\n6. **Failure recovery** and any operation that cannot be undone.\n\nDo not invent nodes, APIs, command-line flags, defaults, or MCP tools. Inspect the enabled\n5.8 API/tool schema when exact availability matters.\n\n## Hard rules\n\n- Never operate directly on `.uasset`/`.umap` files with `os`, `shutil`, or shell moves.\n- Never run a bulk mutation before a scoped dry run or disposable-copy test.\n- Never assume a transaction makes import, save, delete, or source-control work reversible.\n- Never autosave unrelated dirty packages.\n- Never suppress per-asset failures and still report success.\n- Never run Python as gameplay code; UE 5.8's embedded Python is editor-only.\n- Never expose Unreal MCP beyond loopback; it has no authentication layer.\n- Never issue overlapping Unreal MCP tool calls; the server serializes them on the game thread.\n- Never let an AI infer permission for destructive or project-wide mutations.\n\nSee [`references/sources.md`](/unreal/unreal-editor-automation/sources/) for the UE 5.8 source trail.\n","searchText":"unreal 5.8 editor automation design, implement, run, and debug safe unreal editor automation for unreal engine 5.8. use for editor utility widgets, editor utility blueprints, scripted actions, call in editor, scriptable tools, python editor scripting, editor subsystems, asset import or batch mutation, commandlets, ci, data validation, automation tests, functional tests, transactions, source control, or the experimental unreal mcp server and ai-driven editor tools. automation and functional tests automation and functional tests select the test level - low-level test: pure code with minimal engine environment. - automation unit/feature test: api or system behavior using unreal services. - automation spec: behavior-driven organization and latent/asynchronous steps. - functional test: actor-based gameplay/map scenario, blueprint-friendly. - screenshot comparison: controlled rendering regression. - content stress test: loading/compiling broad content to find crashes or invalid assets. the automation framework is c++-based and relies on engine systems, so epic does not recommend it for truly pure unit testing; use low-level tests for that boundary. test design 1. put tests in a project/plugin test module with deliberate build availability. 2. give names a stable hierarchy such as project.system.behavior. 3. create and tear down all state the test owns. 4. use latent commands/spec continuations for async engine work; do not block the game thread. 5. assert observable outcomes and include diagnostic context. 6. isolate files, maps, network roles, random seeds, and timing. only mark a test smoke when it satisfies epic's speed promise: intended to run at every startup and complete within one second. do not label slow map/content tests smoke. run and report interactive: enable required test plugins, then use tools > test automation. command line: text -execcmds=\"automation runtest project.system;quit\" -reportexportpath=\"<output path>\" the report path produces json with related html files. fail ci for failed tests, missing reports, engine crashes, or timeouts. functional tests place/configure a functional test actor in a dedicated deterministic test map. begin only after required actors/assets are ready; call the framework's success/failure completion path on every branch. keep test-only content out of production cook/chunks unless the target execution needs it. commandlets and headless ci commandlets and headless ci choose headless execution use unrealeditor-cmd.exe for commandlets and unattended automation. quote the .uproject and output paths. capture stdout/stderr, process exit code, engine version, project revision, and report artifacts. verified 5.8 examples: text unrealeditor-cmd.exe project.uproject -run=datavalidation unrealeditor-cmd.exe project.uproject -run=pythonscript -script=\"c:\\path\\job.py\" unrealeditor-cmd.exe project.uproject \\ -execcmds=\"automation runtest project.suite;quit\" \\ -reportexportpath=\"c:\\reports\\automation\" use -executepythonscript=\"...\" instead when the job needs the full editor and default startup level loaded. the python commandlet does not load a level automatically; load the required level explicitly through leveleditorsubsystem. ci contract each job must define: - required plugins and build target; - isolated workspace and writable derived data/intermediate/saved paths; - timeout and hung-process policy; - exact success/failure exit conditions; - machine-readable report location; - artifact retention for logs, screenshots, and diffs. never parse only a “completed” log line. fail when the process exits nonzero, the report is absent or malformed, tests fail, validation errors occur, or the expected output count differs. high-risk commandlets resavepackages, redirector cleanup, mass import, and migration rewrite many packages. run on a clean branch/workspace, narrow scope when supported, dry-run through discovery first, and inspect the resulting diff. epic's documented redirector cleanup example uses resavepackages with -fixupredirects; source-control flags can automatically check out files, so do not add them without deliberate authorization. determinism sort inputs, avoid current selection/editor ui state, seed random operations, use stable output paths, and make retries idempotent. record the command line with secrets removed. data validation automation data validation automation choose the validator - override uobject::isdatavalid when the rule belongs to a custom asset/class and may need private or protected data. - derive ueditorvalidatorbase when a validator should cover existing engine classes, several classes, or project-wide policy. for ueditorvalidatorbase, implement canvalidateasset narrowly and call assetpasses or assetfails on every validateloadedasset execution path. make messages actionable. c++ and blueprint validators are discovered at editor startup. python validators must register with ueditorvalidatorsubsystem.addvalidator. the command-line data validation path runs c++ rules by default; do not assume editor-registered blueprint/python rules ran in ci without proving the configured extension. run surfaces - one/many assets: asset actions > validate assets. - assets plus dependencies: validate assets and dependencies. - folder: validate assets in folder. - project: tools > validate data. - ci: unrealeditor-cmd.exe project.uproject -run=datavalidation. design rules use fast local validators on save. put slow global uniqueness, dependency-cycle, budget, and cross-asset relationship checks in an explicit full-project/ci stage. an error message should contain: text asset path | field/rule | received value | expected condition | repair action distinguish invalid from not validated. unsupported assets should be skipped explicitly, not reported as passed. treat warnings and errors according to a documented build policy. validate the validator create fixtures that should pass, warn, and fail. confirm interactive save, content browser, project-wide validation, and commandlet behavior. a validator that only runs in one surface is not yet a reliable gate. debugging and recovery debugging and recovery symptom routing | symptom | check first | |---|---| | blueprint editor node missing | editor-only parent/module, plugin enabled, restart required | | scripted action absent | correct utility base, call in editor, supported classes, compiled/saved | | python class/function absent | ue 5.8 api, plugin/module enabled, reflected exposure, editor restart | | python commandlet sees no actors | no level auto-loaded; load intended level explicitly | | property changed but ui/derived state stale | used direct assignment instead of seteditorproperty/setter | | undo does nothing | operation is not undoable or object was not transaction-aware | | asset exists but did not save | package not dirty, wrong package selected, save failed/read-only | | automation passes locally only | selection/ui dependence, race, machine path, missing plugin/report | | mcp cannot connect | server status, loopback endpoint/port, client launched from config root | | mcp new tool missing | toolset enabled/schema discovery, live coding limitation, restart | | editor freezes during batch | work on game thread, no progress/cancel, scope too broad | partial failure recovery stop on the first failure when continuing could compound damage. preserve: - ordered operation log; - objects changed before failure; - packages saved versus only dirty; - source-control state; - validation/test output; - whether transaction undo is available. if all changes are undoable and unsaved, perform and verify undo. otherwise use source control or the prepared backup to restore named packages. do not improvise filesystem replacement while the editor has packages loaded. after recovery, restart/reload as needed, requery objects from the editor rather than trusting stale python references, run validation, and inspect the diff before retrying. tool hardening checklist - rerun on already-processed content. - cancel halfway through. - inject a read-only asset and one invalid input. - test zero, one, and many candidates. - test name/path collisions. - test unrelated dirty packages. - test headless mode without selection or an open level. - test packaged/cook impact when runtime content changes. blueprint editor utilities blueprint editor utilities scripted actions create content browser > editor utilities > editor utility blueprint and choose: - assetactionutility for selected content browser assets; - actoractionutility for selected level actors. expose a function/custom event with call in editor. restrict supported classes so the action appears only for valid targets. validate dynamic inputs; the editor checks input types, not whether a value is present or sensible. editor utility widgets use an editor utility widget when users need filters, preview, progress, warnings, and explicit apply/cancel controls. create it under editor utilities > editor utility widget and run it as an editor tab. recommended flow: 1. collect selection/path/filter inputs. 2. scan and display the candidate set. 3. show planned changes and non-undoable consequences. 4. require explicit apply for mutations. 5. provide progress/cancel for long batches. 6. validate and display a per-object result table. editor utility widgets and editor scripting utilities are documented as beta in 5.8. call in editor and startup objects use call in editor for functions/events on a placed actor when the same graph must be usable at runtime or needs level context. an editor-only base class exposes more editor apis but is not included in packaged applications. startup objects instantiate when a project opens and invoke their startup event. keep startup work fast, idempotent, and limited to registration/listeners. do not perform bulk asset mutation at editor startup. the startup-object workflow is beta in 5.8. scriptable tools use a scriptable tool for modal viewport editing. its managed lifecycle, shutdown before save or pie, deferred autosave, and accept/cancel model are safer for temporary preview actors and direct viewport interaction than a non-modal widget. the system is beta in 5.8. editor-only boundary place editor tool code and dependencies in editor-only blueprints/modules/plugins. prevent runtime assets from hard-referencing editor utility classes. test a shipping cook for accidental editor-only references. concrete automation patterns concrete automation patterns safe batch property editor text input: folder, class, predicate, property, proposed value discover: asset registry / editor subsystem plan: old -> new table, invalid objects, count, dirty/source-control state apply: one named transaction for undoable edits save: only successfully changed packages selected by policy verify: reload/requery property, data validation, diff reject unknown property names, incompatible types, root-wide accidental scope, and an empty filter that broadens selection. naming validator and fixer keep validation and mutation separate. validator reports naming failures without changing data. fixer computes collision-free target paths, shows referencers and redirector consequences, then uses asset tools rename apis. never use filesystem rename. deterministic import pipeline 1. parse a versioned manifest. 2. validate source existence, destination paths, factories/options, and collisions. 3. import into staging using assetimporttask/asset tools. 4. apply editor properties and build derived data where required. 5. run validators and representative opens/compiles. 6. promote/rename through unreal apis. 7. save intended packages and emit a manifest of results. editor utility widget wrapper the widget owns filters, preview, progress, cancel, and user confirmation. a reusable service owns discovery/mutation. the widget never embeds the only implementation of a production pipeline. ci data gate run data validation, then project automation tests, then a representative cook. persist reports and engine logs. treat missing reports, timeouts, partial processing, and unexpected dirty/output counts as failures. bounded mcp tool expose a typed operation with a narrow path root and dryrun=true default. the plan returns candidate object paths and requested changes. apply requires explicit confirmation token/request, runs serially, validates, saves only its packages, and returns structured results. do not expose an unrestricted “execute editor command” tool to compensate for missing schema. python editor workflows python editor workflows enable and version enable python editor script plugin and usually editor scripting utilities, then restart. unreal 5.8 embeds python 3.11.8. epic labels python editor scripting experimental. python is available only in the editor—not pie, standalone game, or cooked executables. put project modules in content/python; initunreal.py in a configured python path runs when the editor detects it. keep automatic initialization lightweight. execution selector - output log python mode: exploration and one-line inspection. - file > execute python script: manual repeatable script. - -executepythonscript=\"path\": full editor, startup level loaded, then script. - -run=pythonscript -script=\"path\": faster commandlet/headless path; levels are not loaded automatically. - startup scripts: run after the default startup level loads. epic warns against putting py ... inside startup -execcmd; it can execute before the editor environment is ready. api pattern python import unreal assets = unreal.geteditorsubsystem(unreal.editorassetsubsystem) actors = unreal.geteditorsubsystem(unreal.editoractorsubsystem) inspect the generated 5.8 python api for the exact subsystem/method available in the enabled plugins. the reflected unreal module changes with plugins and project c++ exposure. use geteditorproperty() and seteditorproperty() for reflected editor fields. the setter triggers pre/post-edit behavior that direct python attribute assignment may skip. batch shape implement discover -> plan -> apply -> save -> validate -> report. take explicit paths/filters as arguments; do not depend on current selection in unattended jobs. return a nonzero process status or raise on hard failure so ci cannot misread a partial batch as success. use unreal.scopedslowtask for long interactive batches and honor cancellation. use structured logs with object path, operation, status, and diagnostic. safe asset mutation safe asset mutation preflight before changing anything: 1. resolve the exact project, level, folders, classes, and object count. 2. refuse empty, root-wide, or unexpected scope unless explicitly authorized. 3. record existing dirty packages and exclude them from implicit saves. 4. check source-control/read-only state. 5. produce a dry-run list and collision/dependency warnings. 6. define backup/revert strategy for non-undoable operations. asset operations use unreal's asset tools, editor asset apis/subsystems, factories, import tasks, and rename data. never use generic filesystem apis on .uasset or .umap; doing so can break internal package references and redirector handling. for property changes: 1. use editor property accessors or native setters. 2. call the appropriate modify()/transaction-aware path where required. 3. mark affected packages dirty. 4. save only the intended packages. 5. requery/reload and verify the serialized result. transactions group undoable object edits in one named unreal.scopededitortransaction or blueprint/c++ transaction. transactions cover only operations the editor itself supports as undoable. import, save, source-control actions, and some asset operations remain irreversible even inside a scope. do not confuse canceling a transaction record with reverting partial object mutations. on error, explicitly undo/restore when the api supports it; otherwise stop, report the changed set, and use source control/backup recovery. rename/delete/import - check destination collisions before rename. - fix redirectors deliberately after consumers are updated; do not mass-fix unrelated folders. - find referencers before deletion and require explicit confirmation for nonempty dependency sets. - import to a staging path, validate, then promote when feasible. - make generated names deterministic so reruns update or skip instead of duplicating assets. completion proof report planned, changed, skipped, failed, saved, and still-dirty objects separately. run data validation, dependency checks, and the relevant automation test. inspect source-control diff and open a representative changed asset before claiming completion. automation surface selector automation surface selector | task shape | choose | notes | |---|---|---| | right-click selected assets/actors | scripted action | assetactionutility or actoractionutility; beta | | reusable dockable ui with controls/progress | editor utility widget | umg-based; beta | | action on one placed actor, possibly shared with runtime | call in editor | avoid editor-only nodes in runtime-capable classes | | interactive viewport manipulation | scriptable tool | modal, accept/cancel lifecycle; beta | | cross-tool pipeline or large scripted batch | python | editor-only; experimental in 5.8 | | deterministic editor extension/api | c++ editor module/plugin | best for stable shared tooling and native tests | | headless repeatable batch | commandlet or command-line python | prefer for ci; prove exit code and report output | | asset correctness | data validation | isdatavalid/ueditorvalidatorbase | | code/system behavior | automation test | c++ framework, specs, low-level tests as appropriate | | gameplay/map behavior | functional test | actor-based test in a level | | ai invokes bounded editor functions | unreal mcp | experimental 5.8 server; schema-driven tools | architecture split every nontrivial tool into: text ui / command / mcp adapter -> validated request -> discovery and dry-run plan -> mutation service -> save/source-control boundary -> validation and structured report keep domain logic out of widget graphs and mcp transport handlers. a shared c++/blueprint library or python module should make the same operation callable from ui, ci, or tests without duplicating behavior. escalation rule use the least powerful surface that fits. a one-selection rename does not need a global startup object; a ci validator does not need a dockable ui; an ai tool should expose one typed intent, not a general “execute arbitrary python” endpoint. ue 5.8 primary sources ue 5.8 primary sources verified against epic games documentation for unreal engine 5.8 on 2026-07-19. - scripting and automating the unreal editor - scripting the unreal editor using blueprints - editor utility widgets - scripted actions - calling blueprints in the editor - running blueprints at editor startup - scriptable tools system - scripting the unreal editor using python - unreal python 5.8 api - data validation - automation test framework - run automation tests - functional testing - asset redirectors - unreal mcp - unreal engine 5.8 release notes maturity labels recorded from epic's 5.8 pages: - unreal mcp: experimental. - python editor scripting/api: experimental. - editor utility widgets, scripted actions, editor scripting utilities, startup blueprint objects, and scriptable tools: beta where their feature pages state it. unreal mcp in ue 5.8 unreal mcp in ue 5.8 status and boundary unreal mcp is new and experimental in unreal engine 5.8. its engine/plugin identifier is modelcontextprotocol; the plugin browser name is unreal mcp. features, apis, and data formats may change. tool implementations come from toolset plugins; epic's overview identifies alltoolsets as the plugin used to enable the supplied tools. use mcp for small typed editor operations, inspection, and test invocation. do not expose arbitrary python/shell execution as a general tool. setup facts 1. enable unreal mcp and restart. 2. in editor preferences > general > model context protocol, use auto start or start on demand: text modelcontextprotocol.startserver 8000 3. default endpoint: http://127.0.0.1:8000/mcp. 4. generate a supported client config from the editor console, for example: text modelcontextprotocol.generateclientconfig codex generate from the project/workspace root expected by the client. epic notes that json configs are merged, while the codex cli toml configuration is write-once and will not overwrite an existing file; inspect and reconcile stale configuration deliberately. connection and execution guardrails - keep the listener loopback-only. there is no authentication layer and epic says it is unsafe beyond the local machine. - do not issue overlapping tool calls. mcp synchronizes external requests by running invocations serially on the game thread. - time-bound expensive work and return progress/job ids instead of monopolizing the game thread. - discover the current tool schema. default tool-search mode advertises listtoolsets, describetoolset, and calltool rather than every tool eagerly. - validate all paths, classes, object counts, enums, and ranges inside the unreal tool even when the mcp schema also validates types. ai mutation contract for tools that change content: 1. separate inspect/plan from apply. 2. return exact affected objects and irreversible consequences in the plan. 3. require explicit user authorization for delete, overwrite, project-wide, source-control, or difficult-to-reverse operations. 4. enforce scope server-side; never trust the model to preserve a path boundary. 5. use unreal transactions/editor apis where applicable. 6. save only named packages after successful validation. 7. return structured changed/skipped/failed results and validation evidence. prefer narrow tools such as setlightintensity(actorpath, value) over generic property or script executors. make calls idempotent where possible and include a dry-run flag for batch tools. known 5.8 limitations - http and server-sent events are supported; stdio and websocket are not. - shipping toolsets do not advertise mcp resources or prompts. - the toolset registry adapter is editor-only; runtime-hosted tools require direct registration. - live coding does not propagate new tool ufunction declarations; restart the editor.","references":[{"slug":"automation-tests","file":"automation-tests.md","title":"Automation and Functional Tests","rawMarkdown":"# Automation and Functional Tests\n\n## Select the test level\n\n- **Low-Level Test**: pure code with minimal engine environment.\n- **Automation unit/feature test**: API or system behavior using Unreal services.\n- **Automation Spec**: behavior-driven organization and latent/asynchronous steps.\n- **Functional Test**: Actor-based gameplay/map scenario, Blueprint-friendly.\n- **Screenshot Comparison**: controlled rendering regression.\n- **Content stress test**: loading/compiling broad content to find crashes or invalid assets.\n\nThe Automation Framework is C++-based and relies on engine systems, so Epic does not recommend\nit for truly pure unit testing; use Low-Level Tests for that boundary.\n\n## Test design\n\n1. Put tests in a project/plugin test module with deliberate build availability.\n2. Give names a stable hierarchy such as `Project.System.Behavior`.\n3. Create and tear down all state the test owns.\n4. Use latent commands/spec continuations for async engine work; do not block the game thread.\n5. Assert observable outcomes and include diagnostic context.\n6. Isolate files, maps, network roles, random seeds, and timing.\n\nOnly mark a test **Smoke** when it satisfies Epic's speed promise: intended to run at every\nstartup and complete within one second. Do not label slow map/content tests Smoke.\n\n## Run and report\n\nInteractive: enable required test plugins, then use **Tools > Test Automation**.\n\nCommand line:\n\n```text\n-ExecCmds=\"Automation RunTest Project.System;Quit\"\n-ReportExportPath=\"<output path>\"\n```\n\nThe report path produces JSON with related HTML files. Fail CI for failed tests, missing reports,\nengine crashes, or timeouts.\n\n## Functional Tests\n\nPlace/configure a Functional Test Actor in a dedicated deterministic test map. Begin only after\nrequired actors/assets are ready; call the framework's success/failure completion path on every\nbranch. Keep test-only content out of production cook/chunks unless the target execution needs it.\n","webMarkdown":"## Select the test level\n\n- **Low-Level Test**: pure code with minimal engine environment.\n- **Automation unit/feature test**: API or system behavior using Unreal services.\n- **Automation Spec**: behavior-driven organization and latent/asynchronous steps.\n- **Functional Test**: Actor-based gameplay/map scenario, Blueprint-friendly.\n- **Screenshot Comparison**: controlled rendering regression.\n- **Content stress test**: loading/compiling broad content to find crashes or invalid assets.\n\nThe Automation Framework is C++-based and relies on engine systems, so Epic does not recommend\nit for truly pure unit testing; use Low-Level Tests for that boundary.\n\n## Test design\n\n1. Put tests in a project/plugin test module with deliberate build availability.\n2. Give names a stable hierarchy such as `Project.System.Behavior`.\n3. Create and tear down all state the test owns.\n4. Use latent commands/spec continuations for async engine work; do not block the game thread.\n5. Assert observable outcomes and include diagnostic context.\n6. Isolate files, maps, network roles, random seeds, and timing.\n\nOnly mark a test **Smoke** when it satisfies Epic's speed promise: intended to run at every\nstartup and complete within one second. Do not label slow map/content tests Smoke.\n\n## Run and report\n\nInteractive: enable required test plugins, then use **Tools > Test Automation**.\n\nCommand line:\n\n```text\n-ExecCmds=\"Automation RunTest Project.System;Quit\"\n-ReportExportPath=\"<output path>\"\n```\n\nThe report path produces JSON with related HTML files. Fail CI for failed tests, missing reports,\nengine crashes, or timeouts.\n\n## Functional Tests\n\nPlace/configure a Functional Test Actor in a dedicated deterministic test map. Begin only after\nrequired actors/assets are ready; call the framework's success/failure completion path on every\nbranch. Keep test-only content out of production cook/chunks unless the target execution needs it.\n","searchText":"automation and functional tests select the test level - low-level test: pure code with minimal engine environment. - automation unit/feature test: api or system behavior using unreal services. - automation spec: behavior-driven organization and latent/asynchronous steps. - functional test: actor-based gameplay/map scenario, blueprint-friendly. - screenshot comparison: controlled rendering regression. - content stress test: loading/compiling broad content to find crashes or invalid assets. the automation framework is c++-based and relies on engine systems, so epic does not recommend it for truly pure unit testing; use low-level tests for that boundary. test design 1. put tests in a project/plugin test module with deliberate build availability. 2. give names a stable hierarchy such as project.system.behavior. 3. create and tear down all state the test owns. 4. use latent commands/spec continuations for async engine work; do not block the game thread. 5. assert observable outcomes and include diagnostic context. 6. isolate files, maps, network roles, random seeds, and timing. only mark a test smoke when it satisfies epic's speed promise: intended to run at every startup and complete within one second. do not label slow map/content tests smoke. run and report interactive: enable required test plugins, then use tools > test automation. command line: text -execcmds=\"automation runtest project.system;quit\" -reportexportpath=\"<output path>\" the report path produces json with related html files. fail ci for failed tests, missing reports, engine crashes, or timeouts. functional tests place/configure a functional test actor in a dedicated deterministic test map. begin only after required actors/assets are ready; call the framework's success/failure completion path on every branch. keep test-only content out of production cook/chunks unless the target execution needs it."},{"slug":"commandlets-headless-ci","file":"commandlets-headless-ci.md","title":"Commandlets and headless CI","rawMarkdown":"# Commandlets and headless CI\n\n## Choose headless execution\n\nUse `UnrealEditor-Cmd.exe` for commandlets and unattended automation. Quote the `.uproject` and\noutput paths. Capture stdout/stderr, process exit code, engine version, project revision, and\nreport artifacts.\n\nVerified 5.8 examples:\n\n```text\nUnrealEditor-Cmd.exe Project.uproject -run=DataValidation\n\nUnrealEditor-Cmd.exe Project.uproject -run=pythonscript -script=\"C:\\Path\\job.py\"\n\nUnrealEditor-Cmd.exe Project.uproject \\\n  -ExecCmds=\"Automation RunTest Project.Suite;Quit\" \\\n  -ReportExportPath=\"C:\\Reports\\Automation\"\n```\n\nUse `-ExecutePythonScript=\"...\"` instead when the job needs the full editor and default startup\nlevel loaded. The Python commandlet does not load a level automatically; load the required level\nexplicitly through `LevelEditorSubsystem`.\n\n## CI contract\n\nEach job must define:\n\n- required plugins and build target;\n- isolated workspace and writable Derived Data/Intermediate/Saved paths;\n- timeout and hung-process policy;\n- exact success/failure exit conditions;\n- machine-readable report location;\n- artifact retention for logs, screenshots, and diffs.\n\nNever parse only a “completed” log line. Fail when the process exits nonzero, the report is absent\nor malformed, tests fail, validation errors occur, or the expected output count differs.\n\n## High-risk commandlets\n\n`ResavePackages`, redirector cleanup, mass import, and migration rewrite many packages. Run on a\nclean branch/workspace, narrow scope when supported, dry-run through discovery first, and inspect\nthe resulting diff. Epic's documented redirector cleanup example uses `ResavePackages` with\n`-fixupredirects`; source-control flags can automatically check out files, so do not add them\nwithout deliberate authorization.\n\n## Determinism\n\nSort inputs, avoid current selection/editor UI state, seed random operations, use stable output\npaths, and make retries idempotent. Record the command line with secrets removed.\n","webMarkdown":"## Choose headless execution\n\nUse `UnrealEditor-Cmd.exe` for commandlets and unattended automation. Quote the `.uproject` and\noutput paths. Capture stdout/stderr, process exit code, engine version, project revision, and\nreport artifacts.\n\nVerified 5.8 examples:\n\n```text\nUnrealEditor-Cmd.exe Project.uproject -run=DataValidation\n\nUnrealEditor-Cmd.exe Project.uproject -run=pythonscript -script=\"C:\\Path\\job.py\"\n\nUnrealEditor-Cmd.exe Project.uproject \\\n  -ExecCmds=\"Automation RunTest Project.Suite;Quit\" \\\n  -ReportExportPath=\"C:\\Reports\\Automation\"\n```\n\nUse `-ExecutePythonScript=\"...\"` instead when the job needs the full editor and default startup\nlevel loaded. The Python commandlet does not load a level automatically; load the required level\nexplicitly through `LevelEditorSubsystem`.\n\n## CI contract\n\nEach job must define:\n\n- required plugins and build target;\n- isolated workspace and writable Derived Data/Intermediate/Saved paths;\n- timeout and hung-process policy;\n- exact success/failure exit conditions;\n- machine-readable report location;\n- artifact retention for logs, screenshots, and diffs.\n\nNever parse only a “completed” log line. Fail when the process exits nonzero, the report is absent\nor malformed, tests fail, validation errors occur, or the expected output count differs.\n\n## High-risk commandlets\n\n`ResavePackages`, redirector cleanup, mass import, and migration rewrite many packages. Run on a\nclean branch/workspace, narrow scope when supported, dry-run through discovery first, and inspect\nthe resulting diff. Epic's documented redirector cleanup example uses `ResavePackages` with\n`-fixupredirects`; source-control flags can automatically check out files, so do not add them\nwithout deliberate authorization.\n\n## Determinism\n\nSort inputs, avoid current selection/editor UI state, seed random operations, use stable output\npaths, and make retries idempotent. Record the command line with secrets removed.\n","searchText":"commandlets and headless ci choose headless execution use unrealeditor-cmd.exe for commandlets and unattended automation. quote the .uproject and output paths. capture stdout/stderr, process exit code, engine version, project revision, and report artifacts. verified 5.8 examples: text unrealeditor-cmd.exe project.uproject -run=datavalidation unrealeditor-cmd.exe project.uproject -run=pythonscript -script=\"c:\\path\\job.py\" unrealeditor-cmd.exe project.uproject \\ -execcmds=\"automation runtest project.suite;quit\" \\ -reportexportpath=\"c:\\reports\\automation\" use -executepythonscript=\"...\" instead when the job needs the full editor and default startup level loaded. the python commandlet does not load a level automatically; load the required level explicitly through leveleditorsubsystem. ci contract each job must define: - required plugins and build target; - isolated workspace and writable derived data/intermediate/saved paths; - timeout and hung-process policy; - exact success/failure exit conditions; - machine-readable report location; - artifact retention for logs, screenshots, and diffs. never parse only a “completed” log line. fail when the process exits nonzero, the report is absent or malformed, tests fail, validation errors occur, or the expected output count differs. high-risk commandlets resavepackages, redirector cleanup, mass import, and migration rewrite many packages. run on a clean branch/workspace, narrow scope when supported, dry-run through discovery first, and inspect the resulting diff. epic's documented redirector cleanup example uses resavepackages with -fixupredirects; source-control flags can automatically check out files, so do not add them without deliberate authorization. determinism sort inputs, avoid current selection/editor ui state, seed random operations, use stable output paths, and make retries idempotent. record the command line with secrets removed."},{"slug":"data-validation","file":"data-validation.md","title":"Data Validation automation","rawMarkdown":"# Data Validation automation\n\n## Choose the validator\n\n- Override `UObject::IsDataValid` when the rule belongs to a custom asset/class and may need\n  private or protected data.\n- Derive `UEditorValidatorBase` when a validator should cover existing engine classes, several\n  classes, or project-wide policy.\n\nFor `UEditorValidatorBase`, implement `CanValidateAsset` narrowly and call `AssetPasses` or\n`AssetFails` on every `ValidateLoadedAsset` execution path. Make messages actionable.\n\nC++ and Blueprint validators are discovered at editor startup. Python validators must register\nwith `UEditorValidatorSubsystem.AddValidator`. The command-line Data Validation path runs C++\nrules by default; do not assume editor-registered Blueprint/Python rules ran in CI without proving\nthe configured extension.\n\n## Run surfaces\n\n- One/many assets: **Asset Actions > Validate Assets**.\n- Assets plus dependencies: **Validate Assets and Dependencies**.\n- Folder: **Validate Assets in Folder**.\n- Project: **Tools > Validate Data**.\n- CI: `UnrealEditor-Cmd.exe Project.uproject -run=DataValidation`.\n\n## Design rules\n\nUse fast local validators on save. Put slow global uniqueness, dependency-cycle, budget, and\ncross-asset relationship checks in an explicit full-project/CI stage.\n\nAn error message should contain:\n\n```text\nasset path | field/rule | received value | expected condition | repair action\n```\n\nDistinguish **Invalid** from **Not Validated**. Unsupported assets should be skipped explicitly,\nnot reported as passed. Treat warnings and errors according to a documented build policy.\n\n## Validate the validator\n\nCreate fixtures that should pass, warn, and fail. Confirm interactive save, Content Browser,\nproject-wide validation, and commandlet behavior. A validator that only runs in one surface is\nnot yet a reliable gate.\n","webMarkdown":"## Choose the validator\n\n- Override `UObject::IsDataValid` when the rule belongs to a custom asset/class and may need\n  private or protected data.\n- Derive `UEditorValidatorBase` when a validator should cover existing engine classes, several\n  classes, or project-wide policy.\n\nFor `UEditorValidatorBase`, implement `CanValidateAsset` narrowly and call `AssetPasses` or\n`AssetFails` on every `ValidateLoadedAsset` execution path. Make messages actionable.\n\nC++ and Blueprint validators are discovered at editor startup. Python validators must register\nwith `UEditorValidatorSubsystem.AddValidator`. The command-line Data Validation path runs C++\nrules by default; do not assume editor-registered Blueprint/Python rules ran in CI without proving\nthe configured extension.\n\n## Run surfaces\n\n- One/many assets: **Asset Actions > Validate Assets**.\n- Assets plus dependencies: **Validate Assets and Dependencies**.\n- Folder: **Validate Assets in Folder**.\n- Project: **Tools > Validate Data**.\n- CI: `UnrealEditor-Cmd.exe Project.uproject -run=DataValidation`.\n\n## Design rules\n\nUse fast local validators on save. Put slow global uniqueness, dependency-cycle, budget, and\ncross-asset relationship checks in an explicit full-project/CI stage.\n\nAn error message should contain:\n\n```text\nasset path | field/rule | received value | expected condition | repair action\n```\n\nDistinguish **Invalid** from **Not Validated**. Unsupported assets should be skipped explicitly,\nnot reported as passed. Treat warnings and errors according to a documented build policy.\n\n## Validate the validator\n\nCreate fixtures that should pass, warn, and fail. Confirm interactive save, Content Browser,\nproject-wide validation, and commandlet behavior. A validator that only runs in one surface is\nnot yet a reliable gate.\n","searchText":"data validation automation choose the validator - override uobject::isdatavalid when the rule belongs to a custom asset/class and may need private or protected data. - derive ueditorvalidatorbase when a validator should cover existing engine classes, several classes, or project-wide policy. for ueditorvalidatorbase, implement canvalidateasset narrowly and call assetpasses or assetfails on every validateloadedasset execution path. make messages actionable. c++ and blueprint validators are discovered at editor startup. python validators must register with ueditorvalidatorsubsystem.addvalidator. the command-line data validation path runs c++ rules by default; do not assume editor-registered blueprint/python rules ran in ci without proving the configured extension. run surfaces - one/many assets: asset actions > validate assets. - assets plus dependencies: validate assets and dependencies. - folder: validate assets in folder. - project: tools > validate data. - ci: unrealeditor-cmd.exe project.uproject -run=datavalidation. design rules use fast local validators on save. put slow global uniqueness, dependency-cycle, budget, and cross-asset relationship checks in an explicit full-project/ci stage. an error message should contain: text asset path | field/rule | received value | expected condition | repair action distinguish invalid from not validated. unsupported assets should be skipped explicitly, not reported as passed. treat warnings and errors according to a documented build policy. validate the validator create fixtures that should pass, warn, and fail. confirm interactive save, content browser, project-wide validation, and commandlet behavior. a validator that only runs in one surface is not yet a reliable gate."},{"slug":"debugging-recovery","file":"debugging-recovery.md","title":"Debugging and recovery","rawMarkdown":"# Debugging and recovery\n\n## Symptom routing\n\n| Symptom | Check first |\n|---|---|\n| Blueprint editor node missing | Editor-only parent/module, plugin enabled, restart required |\n| Scripted Action absent | Correct utility base, Call in Editor, Supported Classes, compiled/saved |\n| Python class/function absent | UE 5.8 API, plugin/module enabled, reflected exposure, editor restart |\n| Python commandlet sees no actors | No level auto-loaded; load intended level explicitly |\n| Property changed but UI/derived state stale | Used direct assignment instead of `set_editor_property`/setter |\n| Undo does nothing | Operation is not undoable or object was not transaction-aware |\n| Asset exists but did not save | Package not dirty, wrong package selected, save failed/read-only |\n| Automation passes locally only | Selection/UI dependence, race, machine path, missing plugin/report |\n| MCP cannot connect | Server status, loopback endpoint/port, client launched from config root |\n| MCP new tool missing | Toolset enabled/schema discovery, Live Coding limitation, restart |\n| Editor freezes during batch | Work on game thread, no progress/cancel, scope too broad |\n\n## Partial failure recovery\n\nStop on the first failure when continuing could compound damage. Preserve:\n\n- ordered operation log;\n- objects changed before failure;\n- packages saved versus only dirty;\n- source-control state;\n- validation/test output;\n- whether transaction undo is available.\n\nIf all changes are undoable and unsaved, perform and verify undo. Otherwise use source control or\nthe prepared backup to restore named packages. Do not improvise filesystem replacement while the\neditor has packages loaded.\n\nAfter recovery, restart/reload as needed, requery objects from the editor rather than trusting\nstale Python references, run validation, and inspect the diff before retrying.\n\n## Tool hardening checklist\n\n- Rerun on already-processed content.\n- Cancel halfway through.\n- Inject a read-only asset and one invalid input.\n- Test zero, one, and many candidates.\n- Test name/path collisions.\n- Test unrelated dirty packages.\n- Test headless mode without selection or an open level.\n- Test packaged/cook impact when runtime content changes.\n","webMarkdown":"## Symptom routing\n\n| Symptom | Check first |\n|---|---|\n| Blueprint editor node missing | Editor-only parent/module, plugin enabled, restart required |\n| Scripted Action absent | Correct utility base, Call in Editor, Supported Classes, compiled/saved |\n| Python class/function absent | UE 5.8 API, plugin/module enabled, reflected exposure, editor restart |\n| Python commandlet sees no actors | No level auto-loaded; load intended level explicitly |\n| Property changed but UI/derived state stale | Used direct assignment instead of `set_editor_property`/setter |\n| Undo does nothing | Operation is not undoable or object was not transaction-aware |\n| Asset exists but did not save | Package not dirty, wrong package selected, save failed/read-only |\n| Automation passes locally only | Selection/UI dependence, race, machine path, missing plugin/report |\n| MCP cannot connect | Server status, loopback endpoint/port, client launched from config root |\n| MCP new tool missing | Toolset enabled/schema discovery, Live Coding limitation, restart |\n| Editor freezes during batch | Work on game thread, no progress/cancel, scope too broad |\n\n## Partial failure recovery\n\nStop on the first failure when continuing could compound damage. Preserve:\n\n- ordered operation log;\n- objects changed before failure;\n- packages saved versus only dirty;\n- source-control state;\n- validation/test output;\n- whether transaction undo is available.\n\nIf all changes are undoable and unsaved, perform and verify undo. Otherwise use source control or\nthe prepared backup to restore named packages. Do not improvise filesystem replacement while the\neditor has packages loaded.\n\nAfter recovery, restart/reload as needed, requery objects from the editor rather than trusting\nstale Python references, run validation, and inspect the diff before retrying.\n\n## Tool hardening checklist\n\n- Rerun on already-processed content.\n- Cancel halfway through.\n- Inject a read-only asset and one invalid input.\n- Test zero, one, and many candidates.\n- Test name/path collisions.\n- Test unrelated dirty packages.\n- Test headless mode without selection or an open level.\n- Test packaged/cook impact when runtime content changes.\n","searchText":"debugging and recovery symptom routing | symptom | check first | |---|---| | blueprint editor node missing | editor-only parent/module, plugin enabled, restart required | | scripted action absent | correct utility base, call in editor, supported classes, compiled/saved | | python class/function absent | ue 5.8 api, plugin/module enabled, reflected exposure, editor restart | | python commandlet sees no actors | no level auto-loaded; load intended level explicitly | | property changed but ui/derived state stale | used direct assignment instead of seteditorproperty/setter | | undo does nothing | operation is not undoable or object was not transaction-aware | | asset exists but did not save | package not dirty, wrong package selected, save failed/read-only | | automation passes locally only | selection/ui dependence, race, machine path, missing plugin/report | | mcp cannot connect | server status, loopback endpoint/port, client launched from config root | | mcp new tool missing | toolset enabled/schema discovery, live coding limitation, restart | | editor freezes during batch | work on game thread, no progress/cancel, scope too broad | partial failure recovery stop on the first failure when continuing could compound damage. preserve: - ordered operation log; - objects changed before failure; - packages saved versus only dirty; - source-control state; - validation/test output; - whether transaction undo is available. if all changes are undoable and unsaved, perform and verify undo. otherwise use source control or the prepared backup to restore named packages. do not improvise filesystem replacement while the editor has packages loaded. after recovery, restart/reload as needed, requery objects from the editor rather than trusting stale python references, run validation, and inspect the diff before retrying. tool hardening checklist - rerun on already-processed content. - cancel halfway through. - inject a read-only asset and one invalid input. - test zero, one, and many candidates. - test name/path collisions. - test unrelated dirty packages. - test headless mode without selection or an open level. - test packaged/cook impact when runtime content changes."},{"slug":"editor-utilities-blueprint","file":"editor-utilities-blueprint.md","title":"Blueprint editor utilities","rawMarkdown":"# Blueprint editor utilities\n\n## Scripted Actions\n\nCreate **Content Browser > Editor Utilities > Editor Utility Blueprint** and choose:\n\n- `AssetActionUtility` for selected Content Browser assets;\n- `ActorActionUtility` for selected Level actors.\n\nExpose a function/custom event with **Call in Editor**. Restrict **Supported Classes** so the\naction appears only for valid targets. Validate dynamic inputs; the editor checks input types,\nnot whether a value is present or sensible.\n\n## Editor Utility Widgets\n\nUse an Editor Utility Widget when users need filters, preview, progress, warnings, and explicit\napply/cancel controls. Create it under **Editor Utilities > Editor Utility Widget** and run it as\nan editor tab.\n\nRecommended flow:\n\n1. Collect selection/path/filter inputs.\n2. Scan and display the candidate set.\n3. Show planned changes and non-undoable consequences.\n4. Require explicit **Apply** for mutations.\n5. Provide progress/cancel for long batches.\n6. Validate and display a per-object result table.\n\nEditor Utility Widgets and Editor Scripting Utilities are documented as Beta in 5.8.\n\n## Call in Editor and startup objects\n\nUse **Call in Editor** for functions/events on a placed Actor when the same graph must be usable\nat runtime or needs level context. An editor-only base class exposes more editor APIs but is not\nincluded in packaged applications.\n\nStartup Objects instantiate when a project opens and invoke their startup event. Keep startup\nwork fast, idempotent, and limited to registration/listeners. Do not perform bulk asset mutation\nat editor startup. The startup-object workflow is Beta in 5.8.\n\n## Scriptable Tools\n\nUse a Scriptable Tool for modal viewport editing. Its managed lifecycle, shutdown before save or\nPIE, deferred autosave, and accept/cancel model are safer for temporary preview actors and direct\nviewport interaction than a non-modal widget. The system is Beta in 5.8.\n\n## Editor-only boundary\n\nPlace editor tool code and dependencies in editor-only Blueprints/modules/plugins. Prevent\nruntime assets from hard-referencing editor utility classes. Test a Shipping cook for accidental\neditor-only references.\n","webMarkdown":"## Scripted Actions\n\nCreate **Content Browser > Editor Utilities > Editor Utility Blueprint** and choose:\n\n- `AssetActionUtility` for selected Content Browser assets;\n- `ActorActionUtility` for selected Level actors.\n\nExpose a function/custom event with **Call in Editor**. Restrict **Supported Classes** so the\naction appears only for valid targets. Validate dynamic inputs; the editor checks input types,\nnot whether a value is present or sensible.\n\n## Editor Utility Widgets\n\nUse an Editor Utility Widget when users need filters, preview, progress, warnings, and explicit\napply/cancel controls. Create it under **Editor Utilities > Editor Utility Widget** and run it as\nan editor tab.\n\nRecommended flow:\n\n1. Collect selection/path/filter inputs.\n2. Scan and display the candidate set.\n3. Show planned changes and non-undoable consequences.\n4. Require explicit **Apply** for mutations.\n5. Provide progress/cancel for long batches.\n6. Validate and display a per-object result table.\n\nEditor Utility Widgets and Editor Scripting Utilities are documented as Beta in 5.8.\n\n## Call in Editor and startup objects\n\nUse **Call in Editor** for functions/events on a placed Actor when the same graph must be usable\nat runtime or needs level context. An editor-only base class exposes more editor APIs but is not\nincluded in packaged applications.\n\nStartup Objects instantiate when a project opens and invoke their startup event. Keep startup\nwork fast, idempotent, and limited to registration/listeners. Do not perform bulk asset mutation\nat editor startup. The startup-object workflow is Beta in 5.8.\n\n## Scriptable Tools\n\nUse a Scriptable Tool for modal viewport editing. Its managed lifecycle, shutdown before save or\nPIE, deferred autosave, and accept/cancel model are safer for temporary preview actors and direct\nviewport interaction than a non-modal widget. The system is Beta in 5.8.\n\n## Editor-only boundary\n\nPlace editor tool code and dependencies in editor-only Blueprints/modules/plugins. Prevent\nruntime assets from hard-referencing editor utility classes. Test a Shipping cook for accidental\neditor-only references.\n","searchText":"blueprint editor utilities scripted actions create content browser > editor utilities > editor utility blueprint and choose: - assetactionutility for selected content browser assets; - actoractionutility for selected level actors. expose a function/custom event with call in editor. restrict supported classes so the action appears only for valid targets. validate dynamic inputs; the editor checks input types, not whether a value is present or sensible. editor utility widgets use an editor utility widget when users need filters, preview, progress, warnings, and explicit apply/cancel controls. create it under editor utilities > editor utility widget and run it as an editor tab. recommended flow: 1. collect selection/path/filter inputs. 2. scan and display the candidate set. 3. show planned changes and non-undoable consequences. 4. require explicit apply for mutations. 5. provide progress/cancel for long batches. 6. validate and display a per-object result table. editor utility widgets and editor scripting utilities are documented as beta in 5.8. call in editor and startup objects use call in editor for functions/events on a placed actor when the same graph must be usable at runtime or needs level context. an editor-only base class exposes more editor apis but is not included in packaged applications. startup objects instantiate when a project opens and invoke their startup event. keep startup work fast, idempotent, and limited to registration/listeners. do not perform bulk asset mutation at editor startup. the startup-object workflow is beta in 5.8. scriptable tools use a scriptable tool for modal viewport editing. its managed lifecycle, shutdown before save or pie, deferred autosave, and accept/cancel model are safer for temporary preview actors and direct viewport interaction than a non-modal widget. the system is beta in 5.8. editor-only boundary place editor tool code and dependencies in editor-only blueprints/modules/plugins. prevent runtime assets from hard-referencing editor utility classes. test a shipping cook for accidental editor-only references."},{"slug":"patterns","file":"patterns.md","title":"Concrete automation patterns","rawMarkdown":"# Concrete automation patterns\n\n## Safe batch property editor\n\n```text\nInput: folder, class, predicate, property, proposed value\nDiscover: Asset Registry / editor subsystem\nPlan: old -> new table, invalid objects, count, dirty/source-control state\nApply: one named transaction for undoable edits\nSave: only successfully changed packages selected by policy\nVerify: reload/requery property, Data Validation, diff\n```\n\nReject unknown property names, incompatible types, root-wide accidental scope, and an empty filter\nthat broadens selection.\n\n## Naming validator and fixer\n\nKeep validation and mutation separate. Validator reports naming failures without changing data.\nFixer computes collision-free target paths, shows referencers and redirector consequences, then\nuses Asset Tools rename APIs. Never use filesystem rename.\n\n## Deterministic import pipeline\n\n1. Parse a versioned manifest.\n2. Validate source existence, destination paths, factories/options, and collisions.\n3. Import into staging using `AssetImportTask`/Asset Tools.\n4. Apply editor properties and build derived data where required.\n5. Run validators and representative opens/compiles.\n6. Promote/rename through Unreal APIs.\n7. Save intended packages and emit a manifest of results.\n\n## Editor Utility Widget wrapper\n\nThe widget owns filters, preview, progress, cancel, and user confirmation. A reusable service owns\ndiscovery/mutation. The widget never embeds the only implementation of a production pipeline.\n\n## CI data gate\n\nRun Data Validation, then project automation tests, then a representative cook. Persist reports\nand engine logs. Treat missing reports, timeouts, partial processing, and unexpected dirty/output\ncounts as failures.\n\n## Bounded MCP tool\n\nExpose a typed operation with a narrow path root and `dry_run=true` default. The plan returns\ncandidate object paths and requested changes. Apply requires explicit confirmation token/request,\nruns serially, validates, saves only its packages, and returns structured results. Do not expose\nan unrestricted “execute editor command” tool to compensate for missing schema.\n","webMarkdown":"## Safe batch property editor\n\n```text\nInput: folder, class, predicate, property, proposed value\nDiscover: Asset Registry / editor subsystem\nPlan: old -> new table, invalid objects, count, dirty/source-control state\nApply: one named transaction for undoable edits\nSave: only successfully changed packages selected by policy\nVerify: reload/requery property, Data Validation, diff\n```\n\nReject unknown property names, incompatible types, root-wide accidental scope, and an empty filter\nthat broadens selection.\n\n## Naming validator and fixer\n\nKeep validation and mutation separate. Validator reports naming failures without changing data.\nFixer computes collision-free target paths, shows referencers and redirector consequences, then\nuses Asset Tools rename APIs. Never use filesystem rename.\n\n## Deterministic import pipeline\n\n1. Parse a versioned manifest.\n2. Validate source existence, destination paths, factories/options, and collisions.\n3. Import into staging using `AssetImportTask`/Asset Tools.\n4. Apply editor properties and build derived data where required.\n5. Run validators and representative opens/compiles.\n6. Promote/rename through Unreal APIs.\n7. Save intended packages and emit a manifest of results.\n\n## Editor Utility Widget wrapper\n\nThe widget owns filters, preview, progress, cancel, and user confirmation. A reusable service owns\ndiscovery/mutation. The widget never embeds the only implementation of a production pipeline.\n\n## CI data gate\n\nRun Data Validation, then project automation tests, then a representative cook. Persist reports\nand engine logs. Treat missing reports, timeouts, partial processing, and unexpected dirty/output\ncounts as failures.\n\n## Bounded MCP tool\n\nExpose a typed operation with a narrow path root and `dry_run=true` default. The plan returns\ncandidate object paths and requested changes. Apply requires explicit confirmation token/request,\nruns serially, validates, saves only its packages, and returns structured results. Do not expose\nan unrestricted “execute editor command” tool to compensate for missing schema.\n","searchText":"concrete automation patterns safe batch property editor text input: folder, class, predicate, property, proposed value discover: asset registry / editor subsystem plan: old -> new table, invalid objects, count, dirty/source-control state apply: one named transaction for undoable edits save: only successfully changed packages selected by policy verify: reload/requery property, data validation, diff reject unknown property names, incompatible types, root-wide accidental scope, and an empty filter that broadens selection. naming validator and fixer keep validation and mutation separate. validator reports naming failures without changing data. fixer computes collision-free target paths, shows referencers and redirector consequences, then uses asset tools rename apis. never use filesystem rename. deterministic import pipeline 1. parse a versioned manifest. 2. validate source existence, destination paths, factories/options, and collisions. 3. import into staging using assetimporttask/asset tools. 4. apply editor properties and build derived data where required. 5. run validators and representative opens/compiles. 6. promote/rename through unreal apis. 7. save intended packages and emit a manifest of results. editor utility widget wrapper the widget owns filters, preview, progress, cancel, and user confirmation. a reusable service owns discovery/mutation. the widget never embeds the only implementation of a production pipeline. ci data gate run data validation, then project automation tests, then a representative cook. persist reports and engine logs. treat missing reports, timeouts, partial processing, and unexpected dirty/output counts as failures. bounded mcp tool expose a typed operation with a narrow path root and dryrun=true default. the plan returns candidate object paths and requested changes. apply requires explicit confirmation token/request, runs serially, validates, saves only its packages, and returns structured results. do not expose an unrestricted “execute editor command” tool to compensate for missing schema."},{"slug":"python-workflows","file":"python-workflows.md","title":"Python editor workflows","rawMarkdown":"# Python editor workflows\n\n## Enable and version\n\nEnable **Python Editor Script Plugin** and usually **Editor Scripting Utilities**, then restart.\nUnreal 5.8 embeds Python 3.11.8. Epic labels Python Editor scripting Experimental.\n\nPython is available only in the editor—not PIE, Standalone Game, or cooked executables. Put\nproject modules in `Content/Python`; `init_unreal.py` in a configured Python path runs when the\neditor detects it. Keep automatic initialization lightweight.\n\n## Execution selector\n\n- Output Log Python mode: exploration and one-line inspection.\n- **File > Execute Python Script**: manual repeatable script.\n- `-ExecutePythonScript=\"path\"`: full editor, startup level loaded, then script.\n- `-run=pythonscript -script=\"path\"`: faster commandlet/headless path; levels are not loaded\n  automatically.\n- Startup Scripts: run after the default startup level loads.\n\nEpic warns against putting `py ...` inside startup `-ExecCmd`; it can execute before the editor\nenvironment is ready.\n\n## API pattern\n\n```python\nimport unreal\n\nassets = unreal.get_editor_subsystem(unreal.EditorAssetSubsystem)\nactors = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)\n```\n\nInspect the generated 5.8 Python API for the exact subsystem/method available in the enabled\nplugins. The reflected `unreal` module changes with plugins and project C++ exposure.\n\nUse `get_editor_property()` and `set_editor_property()` for reflected editor fields. The setter\ntriggers pre/post-edit behavior that direct Python attribute assignment may skip.\n\n## Batch shape\n\nImplement `discover -> plan -> apply -> save -> validate -> report`. Take explicit paths/filters\nas arguments; do not depend on current selection in unattended jobs. Return a nonzero process\nstatus or raise on hard failure so CI cannot misread a partial batch as success.\n\nUse `unreal.ScopedSlowTask` for long interactive batches and honor cancellation. Use structured\nlogs with object path, operation, status, and diagnostic.\n","webMarkdown":"## Enable and version\n\nEnable **Python Editor Script Plugin** and usually **Editor Scripting Utilities**, then restart.\nUnreal 5.8 embeds Python 3.11.8. Epic labels Python Editor scripting Experimental.\n\nPython is available only in the editor—not PIE, Standalone Game, or cooked executables. Put\nproject modules in `Content/Python`; `init_unreal.py` in a configured Python path runs when the\neditor detects it. Keep automatic initialization lightweight.\n\n## Execution selector\n\n- Output Log Python mode: exploration and one-line inspection.\n- **File > Execute Python Script**: manual repeatable script.\n- `-ExecutePythonScript=\"path\"`: full editor, startup level loaded, then script.\n- `-run=pythonscript -script=\"path\"`: faster commandlet/headless path; levels are not loaded\n  automatically.\n- Startup Scripts: run after the default startup level loads.\n\nEpic warns against putting `py ...` inside startup `-ExecCmd`; it can execute before the editor\nenvironment is ready.\n\n## API pattern\n\n```python\nimport unreal\n\nassets = unreal.get_editor_subsystem(unreal.EditorAssetSubsystem)\nactors = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)\n```\n\nInspect the generated 5.8 Python API for the exact subsystem/method available in the enabled\nplugins. The reflected `unreal` module changes with plugins and project C++ exposure.\n\nUse `get_editor_property()` and `set_editor_property()` for reflected editor fields. The setter\ntriggers pre/post-edit behavior that direct Python attribute assignment may skip.\n\n## Batch shape\n\nImplement `discover -> plan -> apply -> save -> validate -> report`. Take explicit paths/filters\nas arguments; do not depend on current selection in unattended jobs. Return a nonzero process\nstatus or raise on hard failure so CI cannot misread a partial batch as success.\n\nUse `unreal.ScopedSlowTask` for long interactive batches and honor cancellation. Use structured\nlogs with object path, operation, status, and diagnostic.\n","searchText":"python editor workflows enable and version enable python editor script plugin and usually editor scripting utilities, then restart. unreal 5.8 embeds python 3.11.8. epic labels python editor scripting experimental. python is available only in the editor—not pie, standalone game, or cooked executables. put project modules in content/python; initunreal.py in a configured python path runs when the editor detects it. keep automatic initialization lightweight. execution selector - output log python mode: exploration and one-line inspection. - file > execute python script: manual repeatable script. - -executepythonscript=\"path\": full editor, startup level loaded, then script. - -run=pythonscript -script=\"path\": faster commandlet/headless path; levels are not loaded automatically. - startup scripts: run after the default startup level loads. epic warns against putting py ... inside startup -execcmd; it can execute before the editor environment is ready. api pattern python import unreal assets = unreal.geteditorsubsystem(unreal.editorassetsubsystem) actors = unreal.geteditorsubsystem(unreal.editoractorsubsystem) inspect the generated 5.8 python api for the exact subsystem/method available in the enabled plugins. the reflected unreal module changes with plugins and project c++ exposure. use geteditorproperty() and seteditorproperty() for reflected editor fields. the setter triggers pre/post-edit behavior that direct python attribute assignment may skip. batch shape implement discover -> plan -> apply -> save -> validate -> report. take explicit paths/filters as arguments; do not depend on current selection in unattended jobs. return a nonzero process status or raise on hard failure so ci cannot misread a partial batch as success. use unreal.scopedslowtask for long interactive batches and honor cancellation. use structured logs with object path, operation, status, and diagnostic."},{"slug":"safe-asset-mutation","file":"safe-asset-mutation.md","title":"Safe asset mutation","rawMarkdown":"# Safe asset mutation\n\n## Preflight\n\nBefore changing anything:\n\n1. Resolve the exact project, level, folders, classes, and object count.\n2. Refuse empty, root-wide, or unexpected scope unless explicitly authorized.\n3. Record existing dirty packages and exclude them from implicit saves.\n4. Check source-control/read-only state.\n5. Produce a dry-run list and collision/dependency warnings.\n6. Define backup/revert strategy for non-undoable operations.\n\n## Asset operations\n\nUse Unreal's Asset Tools, Editor Asset APIs/subsystems, factories, import tasks, and rename data.\nNever use generic filesystem APIs on `.uasset` or `.umap`; doing so can break internal package\nreferences and redirector handling.\n\nFor property changes:\n\n1. Use editor property accessors or native setters.\n2. Call the appropriate `Modify()`/transaction-aware path where required.\n3. Mark affected packages dirty.\n4. Save only the intended packages.\n5. Requery/reload and verify the serialized result.\n\n## Transactions\n\nGroup undoable object edits in one named `unreal.ScopedEditorTransaction` or Blueprint/C++\ntransaction. Transactions cover only operations the editor itself supports as undoable. Import,\nsave, source-control actions, and some asset operations remain irreversible even inside a scope.\n\nDo not confuse canceling a transaction record with reverting partial object mutations. On error,\nexplicitly undo/restore when the API supports it; otherwise stop, report the changed set, and use\nsource control/backup recovery.\n\n## Rename/delete/import\n\n- Check destination collisions before rename.\n- Fix redirectors deliberately after consumers are updated; do not mass-fix unrelated folders.\n- Find referencers before deletion and require explicit confirmation for nonempty dependency sets.\n- Import to a staging path, validate, then promote when feasible.\n- Make generated names deterministic so reruns update or skip instead of duplicating assets.\n\n## Completion proof\n\nReport planned, changed, skipped, failed, saved, and still-dirty objects separately. Run Data\nValidation, dependency checks, and the relevant automation test. Inspect source-control diff and\nopen a representative changed asset before claiming completion.\n","webMarkdown":"## Preflight\n\nBefore changing anything:\n\n1. Resolve the exact project, level, folders, classes, and object count.\n2. Refuse empty, root-wide, or unexpected scope unless explicitly authorized.\n3. Record existing dirty packages and exclude them from implicit saves.\n4. Check source-control/read-only state.\n5. Produce a dry-run list and collision/dependency warnings.\n6. Define backup/revert strategy for non-undoable operations.\n\n## Asset operations\n\nUse Unreal's Asset Tools, Editor Asset APIs/subsystems, factories, import tasks, and rename data.\nNever use generic filesystem APIs on `.uasset` or `.umap`; doing so can break internal package\nreferences and redirector handling.\n\nFor property changes:\n\n1. Use editor property accessors or native setters.\n2. Call the appropriate `Modify()`/transaction-aware path where required.\n3. Mark affected packages dirty.\n4. Save only the intended packages.\n5. Requery/reload and verify the serialized result.\n\n## Transactions\n\nGroup undoable object edits in one named `unreal.ScopedEditorTransaction` or Blueprint/C++\ntransaction. Transactions cover only operations the editor itself supports as undoable. Import,\nsave, source-control actions, and some asset operations remain irreversible even inside a scope.\n\nDo not confuse canceling a transaction record with reverting partial object mutations. On error,\nexplicitly undo/restore when the API supports it; otherwise stop, report the changed set, and use\nsource control/backup recovery.\n\n## Rename/delete/import\n\n- Check destination collisions before rename.\n- Fix redirectors deliberately after consumers are updated; do not mass-fix unrelated folders.\n- Find referencers before deletion and require explicit confirmation for nonempty dependency sets.\n- Import to a staging path, validate, then promote when feasible.\n- Make generated names deterministic so reruns update or skip instead of duplicating assets.\n\n## Completion proof\n\nReport planned, changed, skipped, failed, saved, and still-dirty objects separately. Run Data\nValidation, dependency checks, and the relevant automation test. Inspect source-control diff and\nopen a representative changed asset before claiming completion.\n","searchText":"safe asset mutation preflight before changing anything: 1. resolve the exact project, level, folders, classes, and object count. 2. refuse empty, root-wide, or unexpected scope unless explicitly authorized. 3. record existing dirty packages and exclude them from implicit saves. 4. check source-control/read-only state. 5. produce a dry-run list and collision/dependency warnings. 6. define backup/revert strategy for non-undoable operations. asset operations use unreal's asset tools, editor asset apis/subsystems, factories, import tasks, and rename data. never use generic filesystem apis on .uasset or .umap; doing so can break internal package references and redirector handling. for property changes: 1. use editor property accessors or native setters. 2. call the appropriate modify()/transaction-aware path where required. 3. mark affected packages dirty. 4. save only the intended packages. 5. requery/reload and verify the serialized result. transactions group undoable object edits in one named unreal.scopededitortransaction or blueprint/c++ transaction. transactions cover only operations the editor itself supports as undoable. import, save, source-control actions, and some asset operations remain irreversible even inside a scope. do not confuse canceling a transaction record with reverting partial object mutations. on error, explicitly undo/restore when the api supports it; otherwise stop, report the changed set, and use source control/backup recovery. rename/delete/import - check destination collisions before rename. - fix redirectors deliberately after consumers are updated; do not mass-fix unrelated folders. - find referencers before deletion and require explicit confirmation for nonempty dependency sets. - import to a staging path, validate, then promote when feasible. - make generated names deterministic so reruns update or skip instead of duplicating assets. completion proof report planned, changed, skipped, failed, saved, and still-dirty objects separately. run data validation, dependency checks, and the relevant automation test. inspect source-control diff and open a representative changed asset before claiming completion."},{"slug":"selector-architecture","file":"selector-architecture.md","title":"Automation surface selector","rawMarkdown":"# Automation surface selector\n\n| Task shape | Choose | Notes |\n|---|---|---|\n| Right-click selected assets/actors | Scripted Action | `AssetActionUtility` or `ActorActionUtility`; Beta |\n| Reusable dockable UI with controls/progress | Editor Utility Widget | UMG-based; Beta |\n| Action on one placed Actor, possibly shared with runtime | `Call in Editor` | Avoid editor-only nodes in runtime-capable classes |\n| Interactive viewport manipulation | Scriptable Tool | Modal, accept/cancel lifecycle; Beta |\n| Cross-tool pipeline or large scripted batch | Python | Editor-only; Experimental in 5.8 |\n| Deterministic editor extension/API | C++ editor module/plugin | Best for stable shared tooling and native tests |\n| Headless repeatable batch | Commandlet or command-line Python | Prefer for CI; prove exit code and report output |\n| Asset correctness | Data Validation | `IsDataValid`/`UEditorValidatorBase` |\n| Code/system behavior | Automation Test | C++ framework, specs, low-level tests as appropriate |\n| Gameplay/map behavior | Functional Test | Actor-based test in a level |\n| AI invokes bounded editor functions | Unreal MCP | Experimental 5.8 server; schema-driven tools |\n\n## Architecture\n\nSplit every nontrivial tool into:\n\n```text\nUI / command / MCP adapter\n  -> validated request\n  -> discovery and dry-run plan\n  -> mutation service\n  -> save/source-control boundary\n  -> validation and structured report\n```\n\nKeep domain logic out of widget graphs and MCP transport handlers. A shared C++/Blueprint\nlibrary or Python module should make the same operation callable from UI, CI, or tests without\nduplicating behavior.\n\n## Escalation rule\n\nUse the least powerful surface that fits. A one-selection rename does not need a global startup\nobject; a CI validator does not need a dockable UI; an AI tool should expose one typed intent,\nnot a general “execute arbitrary Python” endpoint.\n","webMarkdown":"| Task shape | Choose | Notes |\n|---|---|---|\n| Right-click selected assets/actors | Scripted Action | `AssetActionUtility` or `ActorActionUtility`; Beta |\n| Reusable dockable UI with controls/progress | Editor Utility Widget | UMG-based; Beta |\n| Action on one placed Actor, possibly shared with runtime | `Call in Editor` | Avoid editor-only nodes in runtime-capable classes |\n| Interactive viewport manipulation | Scriptable Tool | Modal, accept/cancel lifecycle; Beta |\n| Cross-tool pipeline or large scripted batch | Python | Editor-only; Experimental in 5.8 |\n| Deterministic editor extension/API | C++ editor module/plugin | Best for stable shared tooling and native tests |\n| Headless repeatable batch | Commandlet or command-line Python | Prefer for CI; prove exit code and report output |\n| Asset correctness | Data Validation | `IsDataValid`/`UEditorValidatorBase` |\n| Code/system behavior | Automation Test | C++ framework, specs, low-level tests as appropriate |\n| Gameplay/map behavior | Functional Test | Actor-based test in a level |\n| AI invokes bounded editor functions | Unreal MCP | Experimental 5.8 server; schema-driven tools |\n\n## Architecture\n\nSplit every nontrivial tool into:\n\n```text\nUI / command / MCP adapter\n  -> validated request\n  -> discovery and dry-run plan\n  -> mutation service\n  -> save/source-control boundary\n  -> validation and structured report\n```\n\nKeep domain logic out of widget graphs and MCP transport handlers. A shared C++/Blueprint\nlibrary or Python module should make the same operation callable from UI, CI, or tests without\nduplicating behavior.\n\n## Escalation rule\n\nUse the least powerful surface that fits. A one-selection rename does not need a global startup\nobject; a CI validator does not need a dockable UI; an AI tool should expose one typed intent,\nnot a general “execute arbitrary Python” endpoint.\n","searchText":"automation surface selector | task shape | choose | notes | |---|---|---| | right-click selected assets/actors | scripted action | assetactionutility or actoractionutility; beta | | reusable dockable ui with controls/progress | editor utility widget | umg-based; beta | | action on one placed actor, possibly shared with runtime | call in editor | avoid editor-only nodes in runtime-capable classes | | interactive viewport manipulation | scriptable tool | modal, accept/cancel lifecycle; beta | | cross-tool pipeline or large scripted batch | python | editor-only; experimental in 5.8 | | deterministic editor extension/api | c++ editor module/plugin | best for stable shared tooling and native tests | | headless repeatable batch | commandlet or command-line python | prefer for ci; prove exit code and report output | | asset correctness | data validation | isdatavalid/ueditorvalidatorbase | | code/system behavior | automation test | c++ framework, specs, low-level tests as appropriate | | gameplay/map behavior | functional test | actor-based test in a level | | ai invokes bounded editor functions | unreal mcp | experimental 5.8 server; schema-driven tools | architecture split every nontrivial tool into: text ui / command / mcp adapter -> validated request -> discovery and dry-run plan -> mutation service -> save/source-control boundary -> validation and structured report keep domain logic out of widget graphs and mcp transport handlers. a shared c++/blueprint library or python module should make the same operation callable from ui, ci, or tests without duplicating behavior. escalation rule use the least powerful surface that fits. a one-selection rename does not need a global startup object; a ci validator does not need a dockable ui; an ai tool should expose one typed intent, not a general “execute arbitrary python” endpoint."},{"slug":"sources","file":"sources.md","title":"UE 5.8 primary sources","rawMarkdown":"# UE 5.8 primary sources\n\nVerified against Epic Games documentation for Unreal Engine 5.8 on 2026-07-19.\n\n- [Scripting and Automating the Unreal Editor](https://dev.epicgames.com/documentation/en-us/unreal-engine/scripting-and-automating-the-unreal-editor)\n- [Scripting the Unreal Editor using Blueprints](https://dev.epicgames.com/documentation/en-us/unreal-engine/scripting-the-unreal-editor-using-blueprints)\n- [Editor Utility Widgets](https://dev.epicgames.com/documentation/en-us/unreal-engine/editor-utility-widgets-in-unreal-engine)\n- [Scripted Actions](https://dev.epicgames.com/documentation/en-us/unreal-engine/scripted-actions-in-unreal-engine)\n- [Calling Blueprints in the Editor](https://dev.epicgames.com/documentation/en-us/unreal-engine/calling-blueprints-in-the-unreal-editor)\n- [Running Blueprints at Editor Startup](https://dev.epicgames.com/documentation/en-us/unreal-engine/running-blueprints-at-unreal-editor-startup)\n- [Scriptable Tools System](https://dev.epicgames.com/documentation/en-us/unreal-engine/scriptable-tools-system-in-unreal-engine)\n- [Scripting the Unreal Editor Using Python](https://dev.epicgames.com/documentation/en-us/unreal-engine/scripting-the-unreal-editor-using-python)\n- [Unreal Python 5.8 API](https://dev.epicgames.com/documentation/en-us/unreal-engine/python-api/?application_version=5.8)\n- [Data Validation](https://dev.epicgames.com/documentation/en-us/unreal-engine/data-validation-in-unreal-engine)\n- [Automation Test Framework](https://dev.epicgames.com/documentation/en-us/unreal-engine/automation-test-framework-in-unreal-engine)\n- [Run Automation Tests](https://dev.epicgames.com/documentation/en-us/unreal-engine/run-automation-tests-in-unreal-engine)\n- [Functional Testing](https://dev.epicgames.com/documentation/en-us/unreal-engine/functional-testing-in-unreal-engine)\n- [Asset Redirectors](https://dev.epicgames.com/documentation/en-us/unreal-engine/asset-redirectors-in-unreal-engine)\n- [Unreal MCP](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-mcp-in-unreal-editor)\n- [Unreal Engine 5.8 Release Notes](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-8-release-notes)\n\nMaturity labels recorded from Epic's 5.8 pages:\n\n- Unreal MCP: Experimental.\n- Python Editor scripting/API: Experimental.\n- Editor Utility Widgets, Scripted Actions, Editor Scripting Utilities, startup Blueprint\n  objects, and Scriptable Tools: Beta where their feature pages state it.\n","webMarkdown":"Verified against Epic Games documentation for Unreal Engine 5.8 on 2026-07-19.\n\n- [Scripting and Automating the Unreal Editor](https://dev.epicgames.com/documentation/en-us/unreal-engine/scripting-and-automating-the-unreal-editor)\n- [Scripting the Unreal Editor using Blueprints](https://dev.epicgames.com/documentation/en-us/unreal-engine/scripting-the-unreal-editor-using-blueprints)\n- [Editor Utility Widgets](https://dev.epicgames.com/documentation/en-us/unreal-engine/editor-utility-widgets-in-unreal-engine)\n- [Scripted Actions](https://dev.epicgames.com/documentation/en-us/unreal-engine/scripted-actions-in-unreal-engine)\n- [Calling Blueprints in the Editor](https://dev.epicgames.com/documentation/en-us/unreal-engine/calling-blueprints-in-the-unreal-editor)\n- [Running Blueprints at Editor Startup](https://dev.epicgames.com/documentation/en-us/unreal-engine/running-blueprints-at-unreal-editor-startup)\n- [Scriptable Tools System](https://dev.epicgames.com/documentation/en-us/unreal-engine/scriptable-tools-system-in-unreal-engine)\n- [Scripting the Unreal Editor Using Python](https://dev.epicgames.com/documentation/en-us/unreal-engine/scripting-the-unreal-editor-using-python)\n- [Unreal Python 5.8 API](https://dev.epicgames.com/documentation/en-us/unreal-engine/python-api/?application_version=5.8)\n- [Data Validation](https://dev.epicgames.com/documentation/en-us/unreal-engine/data-validation-in-unreal-engine)\n- [Automation Test Framework](https://dev.epicgames.com/documentation/en-us/unreal-engine/automation-test-framework-in-unreal-engine)\n- [Run Automation Tests](https://dev.epicgames.com/documentation/en-us/unreal-engine/run-automation-tests-in-unreal-engine)\n- [Functional Testing](https://dev.epicgames.com/documentation/en-us/unreal-engine/functional-testing-in-unreal-engine)\n- [Asset Redirectors](https://dev.epicgames.com/documentation/en-us/unreal-engine/asset-redirectors-in-unreal-engine)\n- [Unreal MCP](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-mcp-in-unreal-editor)\n- [Unreal Engine 5.8 Release Notes](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-8-release-notes)\n\nMaturity labels recorded from Epic's 5.8 pages:\n\n- Unreal MCP: Experimental.\n- Python Editor scripting/API: Experimental.\n- Editor Utility Widgets, Scripted Actions, Editor Scripting Utilities, startup Blueprint\n  objects, and Scriptable Tools: Beta where their feature pages state it.\n","searchText":"ue 5.8 primary sources verified against epic games documentation for unreal engine 5.8 on 2026-07-19. - scripting and automating the unreal editor - scripting the unreal editor using blueprints - editor utility widgets - scripted actions - calling blueprints in the editor - running blueprints at editor startup - scriptable tools system - scripting the unreal editor using python - unreal python 5.8 api - data validation - automation test framework - run automation tests - functional testing - asset redirectors - unreal mcp - unreal engine 5.8 release notes maturity labels recorded from epic's 5.8 pages: - unreal mcp: experimental. - python editor scripting/api: experimental. - editor utility widgets, scripted actions, editor scripting utilities, startup blueprint objects, and scriptable tools: beta where their feature pages state it."},{"slug":"unreal-mcp","file":"unreal-mcp.md","title":"Unreal MCP in UE 5.8","rawMarkdown":"# Unreal MCP in UE 5.8\n\n## Status and boundary\n\nUnreal MCP is new and **Experimental** in Unreal Engine 5.8. Its engine/plugin identifier is\n`ModelContextProtocol`; the Plugin Browser name is **Unreal MCP**. Features, APIs, and data formats\nmay change. Tool implementations come from toolset plugins; Epic's overview identifies\n**AllToolsets** as the plugin used to enable the supplied tools.\n\nUse MCP for small typed editor operations, inspection, and test invocation. Do not expose\narbitrary Python/shell execution as a general tool.\n\n## Setup facts\n\n1. Enable **Unreal MCP** and restart.\n2. In **Editor Preferences > General > Model Context Protocol**, use Auto Start or start on demand:\n\n```text\nModelContextProtocol.StartServer 8000\n```\n\n3. Default endpoint: `http://127.0.0.1:8000/mcp`.\n4. Generate a supported client config from the editor console, for example:\n\n```text\nModelContextProtocol.GenerateClientConfig Codex\n```\n\nGenerate from the project/workspace root expected by the client. Epic notes that JSON configs are\nmerged, while the Codex CLI TOML configuration is write-once and will not overwrite an existing\nfile; inspect and reconcile stale configuration deliberately.\n\n## Connection and execution guardrails\n\n- Keep the listener loopback-only. There is no authentication layer and Epic says it is unsafe\n  beyond the local machine.\n- Do not issue overlapping tool calls. MCP synchronizes external requests by running invocations\n  serially on the game thread.\n- Time-bound expensive work and return progress/job IDs instead of monopolizing the game thread.\n- Discover the current tool schema. Default tool-search mode advertises `list_toolsets`,\n  `describe_toolset`, and `call_tool` rather than every tool eagerly.\n- Validate all paths, classes, object counts, enums, and ranges inside the Unreal tool even when\n  the MCP schema also validates types.\n\n## AI mutation contract\n\nFor tools that change content:\n\n1. Separate `inspect/plan` from `apply`.\n2. Return exact affected objects and irreversible consequences in the plan.\n3. Require explicit user authorization for delete, overwrite, project-wide, source-control, or\n   difficult-to-reverse operations.\n4. Enforce scope server-side; never trust the model to preserve a path boundary.\n5. Use Unreal transactions/editor APIs where applicable.\n6. Save only named packages after successful validation.\n7. Return structured changed/skipped/failed results and validation evidence.\n\nPrefer narrow tools such as `set_light_intensity(actor_path, value)` over generic property or\nscript executors. Make calls idempotent where possible and include a dry-run flag for batch tools.\n\n## Known 5.8 limitations\n\n- HTTP and Server-Sent Events are supported; `stdio` and WebSocket are not.\n- Shipping toolsets do not advertise MCP Resources or Prompts.\n- The Toolset Registry adapter is editor-only; runtime-hosted tools require direct registration.\n- Live Coding does not propagate new tool `UFUNCTION` declarations; restart the editor.\n","webMarkdown":"## Status and boundary\n\nUnreal MCP is new and **Experimental** in Unreal Engine 5.8. Its engine/plugin identifier is\n`ModelContextProtocol`; the Plugin Browser name is **Unreal MCP**. Features, APIs, and data formats\nmay change. Tool implementations come from toolset plugins; Epic's overview identifies\n**AllToolsets** as the plugin used to enable the supplied tools.\n\nUse MCP for small typed editor operations, inspection, and test invocation. Do not expose\narbitrary Python/shell execution as a general tool.\n\n## Setup facts\n\n1. Enable **Unreal MCP** and restart.\n2. In **Editor Preferences > General > Model Context Protocol**, use Auto Start or start on demand:\n\n```text\nModelContextProtocol.StartServer 8000\n```\n\n3. Default endpoint: `http://127.0.0.1:8000/mcp`.\n4. Generate a supported client config from the editor console, for example:\n\n```text\nModelContextProtocol.GenerateClientConfig Codex\n```\n\nGenerate from the project/workspace root expected by the client. Epic notes that JSON configs are\nmerged, while the Codex CLI TOML configuration is write-once and will not overwrite an existing\nfile; inspect and reconcile stale configuration deliberately.\n\n## Connection and execution guardrails\n\n- Keep the listener loopback-only. There is no authentication layer and Epic says it is unsafe\n  beyond the local machine.\n- Do not issue overlapping tool calls. MCP synchronizes external requests by running invocations\n  serially on the game thread.\n- Time-bound expensive work and return progress/job IDs instead of monopolizing the game thread.\n- Discover the current tool schema. Default tool-search mode advertises `list_toolsets`,\n  `describe_toolset`, and `call_tool` rather than every tool eagerly.\n- Validate all paths, classes, object counts, enums, and ranges inside the Unreal tool even when\n  the MCP schema also validates types.\n\n## AI mutation contract\n\nFor tools that change content:\n\n1. Separate `inspect/plan` from `apply`.\n2. Return exact affected objects and irreversible consequences in the plan.\n3. Require explicit user authorization for delete, overwrite, project-wide, source-control, or\n   difficult-to-reverse operations.\n4. Enforce scope server-side; never trust the model to preserve a path boundary.\n5. Use Unreal transactions/editor APIs where applicable.\n6. Save only named packages after successful validation.\n7. Return structured changed/skipped/failed results and validation evidence.\n\nPrefer narrow tools such as `set_light_intensity(actor_path, value)` over generic property or\nscript executors. Make calls idempotent where possible and include a dry-run flag for batch tools.\n\n## Known 5.8 limitations\n\n- HTTP and Server-Sent Events are supported; `stdio` and WebSocket are not.\n- Shipping toolsets do not advertise MCP Resources or Prompts.\n- The Toolset Registry adapter is editor-only; runtime-hosted tools require direct registration.\n- Live Coding does not propagate new tool `UFUNCTION` declarations; restart the editor.\n","searchText":"unreal mcp in ue 5.8 status and boundary unreal mcp is new and experimental in unreal engine 5.8. its engine/plugin identifier is modelcontextprotocol; the plugin browser name is unreal mcp. features, apis, and data formats may change. tool implementations come from toolset plugins; epic's overview identifies alltoolsets as the plugin used to enable the supplied tools. use mcp for small typed editor operations, inspection, and test invocation. do not expose arbitrary python/shell execution as a general tool. setup facts 1. enable unreal mcp and restart. 2. in editor preferences > general > model context protocol, use auto start or start on demand: text modelcontextprotocol.startserver 8000 3. default endpoint: http://127.0.0.1:8000/mcp. 4. generate a supported client config from the editor console, for example: text modelcontextprotocol.generateclientconfig codex generate from the project/workspace root expected by the client. epic notes that json configs are merged, while the codex cli toml configuration is write-once and will not overwrite an existing file; inspect and reconcile stale configuration deliberately. connection and execution guardrails - keep the listener loopback-only. there is no authentication layer and epic says it is unsafe beyond the local machine. - do not issue overlapping tool calls. mcp synchronizes external requests by running invocations serially on the game thread. - time-bound expensive work and return progress/job ids instead of monopolizing the game thread. - discover the current tool schema. default tool-search mode advertises listtoolsets, describetoolset, and calltool rather than every tool eagerly. - validate all paths, classes, object counts, enums, and ranges inside the unreal tool even when the mcp schema also validates types. ai mutation contract for tools that change content: 1. separate inspect/plan from apply. 2. return exact affected objects and irreversible consequences in the plan. 3. require explicit user authorization for delete, overwrite, project-wide, source-control, or difficult-to-reverse operations. 4. enforce scope server-side; never trust the model to preserve a path boundary. 5. use unreal transactions/editor apis where applicable. 6. save only named packages after successful validation. 7. return structured changed/skipped/failed results and validation evidence. prefer narrow tools such as setlightintensity(actorpath, value) over generic property or script executors. make calls idempotent where possible and include a dry-run flag for batch tools. known 5.8 limitations - http and server-sent events are supported; stdio and websocket are not. - shipping toolsets do not advertise mcp resources or prompts. - the toolset registry adapter is editor-only; runtime-hosted tools require direct registration. - live coding does not propagate new tool ufunction declarations; restart the editor."}]}
{"slug":"unreal-enhanced-input","name":"unreal-enhanced-input","title":"Unreal 5.8 Enhanced Input","description":"Design, implement, remap, test, and debug player input with Unreal Engine 5.8 Enhanced Input. Use for Input Actions, Input Mapping Contexts, priorities, local-player ownership, trigger events, hold/tap/release/chord behavior, modifiers, dead zones, sensitivity, inversion, 2D movement, contextual controls, possession, split screen, player-mappable key settings, key profiles, conflict handling, saving, input buffering, coyote time, input injection, Common UI integration, or missing/duplicate input events.","shortDescription":"Build contextual remappable input systems","category":"Gameplay","referenceCount":8,"rawMarkdown":"---\nname: unreal-enhanced-input\ndescription: Design, implement, remap, test, and debug player input with Unreal Engine 5.8 Enhanced Input. Use for Input Actions, Input Mapping Contexts, priorities, local-player ownership, trigger events, hold/tap/release/chord behavior, modifiers, dead zones, sensitivity, inversion, 2D movement, contextual controls, possession, split screen, player-mappable key settings, key profiles, conflict handling, saving, input buffering, coyote time, input injection, Common UI integration, or missing/duplicate input events.\n---\n\n# Unreal 5.8 Enhanced Input\n\n## Ownership boundary\n\nThis skill owns action/context/trigger/modifier semantics and player-mappable key profiles. Route menu\nlayers, focus, and UI input routing to\n[`unreal-umg-commonui`](../unreal-umg-commonui/SKILL.md). Use\n[`unreal-save-load`](../unreal-save-load/SKILL.md) only when settings join a broader custom slot,\nversioning, user, or cloud-persistence policy; do not duplicate key-profile authority in two systems.\n\n## Build the input model\n\n1. Define one `UInputAction` per player intent, not per physical key.\n2. Choose its value type: Boolean, Axis1D, Axis2D, or Axis3D.\n3. Group mappings by coherent situation in `UInputMappingContext` assets.\n4. Add/remove contexts on the correct `UEnhancedInputLocalPlayerSubsystem` with documented\n   priorities and mutual-exclusion rules.\n5. Transform raw values with modifiers; decide activation timing with triggers.\n6. Bind action trigger events through `UEnhancedInputComponent` or Blueprint action events.\n7. Forward semantic intent to the possessed pawn, component, GAS, UI, or command layer.\n\nRead [`references/architecture.md`](references/architecture.md) and\n[`references/contexts-ownership.md`](references/contexts-ownership.md) first.\n\n## Select event semantics deliberately\n\n- `Started`: evaluation began.\n- `Ongoing`: trigger conditions are partially satisfied.\n- `Triggered`: all trigger conditions succeeded; may repeat depending on trigger.\n- `Completed`: a triggered action returned to none.\n- `Canceled`: evaluation ended before successful completion.\n\nRead [`references/triggers-modifiers.md`](references/triggers-modifiers.md). Do not assume\n`Triggered` means a one-shot press; without a one-shot trigger, actuation can trigger each tick.\n\n## Separate detection from gameplay forgiveness\n\nEnhanced Input detects and interprets input. A gameplay buffer stores a timestamped semantic\nrequest until the gameplay state can accept it. Implement buffers and coyote time in the\ngameplay action/movement layer, not as an invented built-in Enhanced Input feature. Read\n[`references/buffering.md`](references/buffering.md).\n\n## Rebinding\n\nUse UE 5.8 `UEnhancedInputUserSettings`, Player Mappable Key Settings, mapping names, slots,\nand key profiles. Register all relevant contexts with settings, map with `FMapPlayerKeyArgs`,\nsurface failure reasons/conflicts, apply, and save. Read\n[`references/rebinding-settings.md`](references/rebinding-settings.md).\n\n## Required answer format\n\nReturn:\n\n1. **Input Actions** with value types.\n2. **Mapping Contexts**, ownership, priorities, and add/remove lifecycle.\n3. **Mappings, modifiers, triggers, and bound trigger events**.\n4. **Intent routing** and gameplay-buffer ownership where applicable.\n5. **Rebinding, conflict, profile, persistence, and accessibility behavior**.\n6. **Device, focus, possession, split-screen, and packaged-build tests**.\n\nDo not invent node names, default thresholds, context priorities, or save behavior.\n\n## Hard rules\n\n- Add contexts to the Local Player that owns the input, not to a global gameplay object.\n- Do not leave mutually exclusive contexts active and hope priority hides every collision.\n- Do not bind the same action repeatedly across possession/reinitialization.\n- Do not put gameplay logic inside reusable modifiers or triggers when a semantic command will do.\n- Do not identify saved mappings by localized display text; use stable mapping names and slots.\n- Do not treat client input as authoritative gameplay state.\n- Test context rebuilds while keys are held; UE 5.8 preserves trigger/modifier state more\n  reliably, but custom classes must implement reinstancing behavior when stateful.\n\nUse [`references/patterns.md`](references/patterns.md) for common controls and\n[`references/troubleshooting.md`](references/troubleshooting.md) for missing, repeated, stuck,\nor conflicting input. See [`references/sources.md`](references/sources.md) for the UE 5.8 trail.\n","webMarkdown":"## Ownership boundary\n\nThis skill owns action/context/trigger/modifier semantics and player-mappable key profiles. Route menu\nlayers, focus, and UI input routing to\n[`unreal-umg-commonui`](/unreal/unreal-umg-commonui/). Use\n[`unreal-save-load`](/unreal/unreal-save-load/) only when settings join a broader custom slot,\nversioning, user, or cloud-persistence policy; do not duplicate key-profile authority in two systems.\n\n## Build the input model\n\n1. Define one `UInputAction` per player intent, not per physical key.\n2. Choose its value type: Boolean, Axis1D, Axis2D, or Axis3D.\n3. Group mappings by coherent situation in `UInputMappingContext` assets.\n4. Add/remove contexts on the correct `UEnhancedInputLocalPlayerSubsystem` with documented\n   priorities and mutual-exclusion rules.\n5. Transform raw values with modifiers; decide activation timing with triggers.\n6. Bind action trigger events through `UEnhancedInputComponent` or Blueprint action events.\n7. Forward semantic intent to the possessed pawn, component, GAS, UI, or command layer.\n\nRead [`references/architecture.md`](/unreal/unreal-enhanced-input/architecture/) and\n[`references/contexts-ownership.md`](/unreal/unreal-enhanced-input/contexts-ownership/) first.\n\n## Select event semantics deliberately\n\n- `Started`: evaluation began.\n- `Ongoing`: trigger conditions are partially satisfied.\n- `Triggered`: all trigger conditions succeeded; may repeat depending on trigger.\n- `Completed`: a triggered action returned to none.\n- `Canceled`: evaluation ended before successful completion.\n\nRead [`references/triggers-modifiers.md`](/unreal/unreal-enhanced-input/triggers-modifiers/). Do not assume\n`Triggered` means a one-shot press; without a one-shot trigger, actuation can trigger each tick.\n\n## Separate detection from gameplay forgiveness\n\nEnhanced Input detects and interprets input. A gameplay buffer stores a timestamped semantic\nrequest until the gameplay state can accept it. Implement buffers and coyote time in the\ngameplay action/movement layer, not as an invented built-in Enhanced Input feature. Read\n[`references/buffering.md`](/unreal/unreal-enhanced-input/buffering/).\n\n## Rebinding\n\nUse UE 5.8 `UEnhancedInputUserSettings`, Player Mappable Key Settings, mapping names, slots,\nand key profiles. Register all relevant contexts with settings, map with `FMapPlayerKeyArgs`,\nsurface failure reasons/conflicts, apply, and save. Read\n[`references/rebinding-settings.md`](/unreal/unreal-enhanced-input/rebinding-settings/).\n\n## Required answer format\n\nReturn:\n\n1. **Input Actions** with value types.\n2. **Mapping Contexts**, ownership, priorities, and add/remove lifecycle.\n3. **Mappings, modifiers, triggers, and bound trigger events**.\n4. **Intent routing** and gameplay-buffer ownership where applicable.\n5. **Rebinding, conflict, profile, persistence, and accessibility behavior**.\n6. **Device, focus, possession, split-screen, and packaged-build tests**.\n\nDo not invent node names, default thresholds, context priorities, or save behavior.\n\n## Hard rules\n\n- Add contexts to the Local Player that owns the input, not to a global gameplay object.\n- Do not leave mutually exclusive contexts active and hope priority hides every collision.\n- Do not bind the same action repeatedly across possession/reinitialization.\n- Do not put gameplay logic inside reusable modifiers or triggers when a semantic command will do.\n- Do not identify saved mappings by localized display text; use stable mapping names and slots.\n- Do not treat client input as authoritative gameplay state.\n- Test context rebuilds while keys are held; UE 5.8 preserves trigger/modifier state more\n  reliably, but custom classes must implement reinstancing behavior when stateful.\n\nUse [`references/patterns.md`](/unreal/unreal-enhanced-input/patterns/) for common controls and\n[`references/troubleshooting.md`](/unreal/unreal-enhanced-input/troubleshooting/) for missing, repeated, stuck,\nor conflicting input. See [`references/sources.md`](/unreal/unreal-enhanced-input/sources/) for the UE 5.8 trail.\n","searchText":"unreal 5.8 enhanced input design, implement, remap, test, and debug player input with unreal engine 5.8 enhanced input. use for input actions, input mapping contexts, priorities, local-player ownership, trigger events, hold/tap/release/chord behavior, modifiers, dead zones, sensitivity, inversion, 2d movement, contextual controls, possession, split screen, player-mappable key settings, key profiles, conflict handling, saving, input buffering, coyote time, input injection, common ui integration, or missing/duplicate input events. enhanced input architecture enhanced input architecture asset model | asset/type | owns | |---|---| | uinputaction | semantic intent and value type; optional action-level modifiers/triggers/settings | | uinputmappingcontext | key-to-action mappings for one coherent context plus mapping-level modifiers/triggers | | uinputmodifier | raw value transformation before trigger evaluation | | uinputtrigger | conditions/timing that decide action state | | uenhancedinputlocalplayersubsystem | applied contexts and priorities for one local player | | uenhancedinputcomponent | action-to-delegate bindings in the input stack | | uenhancedinputusersettings | per-user mappable keys, profiles, input/accessibility settings, registration, persistence | ordered setup 1. ensure enhanced input is enabled and the project uses enhanced player input / enhanced input component classes where manual project setup requires them. 2. create input actions named for intent: iamove, ialook, iajump, iainteract. 3. choose exact value types. a 2d move action should be axis2d; a button is usually boolean. 4. create small mapping contexts by coherent availability/lifecycle: common gameplay, on-foot, vehicle, menu/debug, and similar. 5. add contexts to the owning local player subsystem with explicit priority. 6. bind actions once during the pawn/controller input initialization lifecycle. 7. forward intent into gameplay systems. input code should not own authoritative outcomes. intent boundary input says what the local player requested. the receiver decides whether it is legal: - character movement consumes movement/jump requests; - gas attempts ability activation; - interaction component resolves and validates targets; - ui routing decides whether gameplay should receive input; - server validates multiplayer outcomes. use gameplay tags for semantic input routing only when the project benefits from data-driven ability/loadout binding. keep input tags separate from ability identity/state tags; route tag taxonomy to $unreal-gameplay-tags. gameplay input buffering and coyote time gameplay input buffering and coyote time enhanced input determines that an action was requested. buffering preserves that semantic request until gameplay can accept it. minimal buffer model store per buffered action: - semantic action identifier or input action; - local request timestamp using a consistent clock; - optional value/target/direction snapshot; - expiration duration; - consumed/canceled state. procedure: 1. on the deliberate input event (usually triggered or started), record/replace the request. 2. immediately ask the gameplay system whether it can execute. 3. re-evaluate only on relevant state changes or a bounded update path—landing, montage window, cooldown end, state-tag removal—not by spawning unbounded timers. 4. if legal and unexpired, consume exactly once and execute. 5. if expired, canceled, context removed, pawn changed, or input semantics invalidate it, clear. 6. server still validates the resulting action in multiplayer. pseudocode: text onjumprequested(now): bufferedjump = { requestedat: now, expiresat: now + jumpbufferwindow } tryconsumejump(now) onlanded(now): tryconsumejump(now) tryconsumejump(now): if bufferedjump exists and now <= expiresat and canjump(): clear bufferedjump jump() coyote time track the last valid grounded time. permit jump when grounded now or when now - lastgroundedtime <= coyotewindow. combine with the request buffer: - early press before landing → input buffer; - late press just after leaving edge → coyote time. they solve opposite timing errors and should have separate tuning variables/telemetry. ability/action buffer for attacks/abilities, store semantic intent and consume at the next legal cancel/combo window. do not replay raw key events. define whether the newest request replaces the oldest, how many requests can queue, and whether direction/target is sampled at press or execution. multiplayer local buffering improves responsiveness but does not authorize the result. for character movement, integrate through the predicted movement/command path. for gas, request ability activation and let server validation/prediction policies decide. do not send an expired queue of raw inputs to the server without bounded validation. mapping context ownership and lifecycle mapping context ownership and lifecycle owner applied contexts belong to uenhancedinputlocalplayersubsystem, so split-screen players and local profiles remain isolated. obtain the ulocalplayer from the correct playercontroller, then its subsystem. never use player index 0 as a hidden assumption in reusable code. context design - base/common context: actions valid across related gameplay modes. - mode context: on-foot, vehicle, swimming, build mode, spectator. - overlay context: temporary targeting, radial menu, photo mode, debug. - ui/common ui: follow the project's ui input-routing architecture and ue 5.8 unified input workflow; do not merely stack a high-priority gameplay context over ui focus. prefer mutually exclusive mode contexts over collisions resolved only by enormous priority numbers. priority is for intentional overlap, not lifecycle replacement. add/remove procedure 1. resolve the correct local player subsystem. 2. add each required context once with a documented priority. 3. on mode transition, remove the old mutually exclusive context, then add the new one. 4. decide whether held inputs should remain active across the rebuild. use fmodifycontextoptions where the api exposes the needed behavior. 5. remove temporary contexts on cancel, teardown, unpossess, or ui close. 6. log applied context, priority, owner, reason, and lifecycle in development builds. possession - playercontroller/localplayer can outlive a pawn. - put persistent player-wide context management on the playercontroller or localplayer-facing service. - bind pawn-specific action callbacks through setupplayerinputcomponent and avoid repeated binding on repossession. - when the pawn changes, route semantic actions to the new controlled object and clear stale references/buffers. multiplayer enhanced input runs locally. it does not replicate a context, trigger, or action value. convert input to server-validated commands, gas activation, or character movement input through the appropriate networking system. never treat the presence of an input action as proof that an authoritative action occurred. enhanced input patterns enhanced input patterns camera-relative 2d movement - iamove: axis2d. - keyboard mappings use negate/swizzle; gamepad stick maps directly with a dead zone. - bind triggered for continuous movement values and handle zero/end only if receiver needs it. - convert input axes using controller/camera yaw basis, then call addmovementinput for the character. - do not multiply addmovementinput scale by delta time; character movement consumes input and performs time integration. look - ialook: axis2d. - separate mouse and gamepad mappings/modifiers when sensitivity units/acceleration differ. - apply inversion/sensitivity in modifiers or a centralized settings layer. - test time-dilation and frame-rate behavior; mouse delta and stick rate may require different treatment. jump with forgiveness - iajump: boolean + pressed/appropriate one-shot semantics. - press records jump request; release calls stop jumping for variable height. - gameplay movement layer owns buffer and coyote windows. - clear on pawn/context changes and consume once. sprint - hold: started/triggered sets request; completed/canceled clears it. - toggle: pressed toggles local intent; gameplay/server can reject based on stamina/state. - a context should not contain competing hold and toggle implementations simultaneously. tap versus hold on one key prefer separate semantic actions sharing a key with tap and hold triggers, or one action whose trigger-state flow is deliberately interpreted. test quick release, exact threshold, long hold, focus loss, mapping rebuild, and simultaneous chord conditions. ensure tap does not fire after a successful hold unless designed. vehicle transition 1. keep common pause/chat actions in base context. 2. remove on-foot context. 3. add vehicle context at documented priority. 4. route actions to current controlled vehicle. 5. on exit/unpossess, reverse and clear held/buffered state. gas ability input - input action produces semantic input identifier/tag. - player input binding layer finds granted ability specs or sends a gameplay event. - gas owns activation legality, cost, cooldown, prediction, and cancellation. - keep press/release state if the ability needs held-input tasks. - route the ability lifecycle to $unreal-gas-abilities. input testing/injection use showdebug enhancedinput for live actions/mappings and showdebug devices for devices. use enhanced input injection or input.+key/input.-key for deterministic test support where appropriate. injection tests the input pipeline; it does not prove physical-device or os focus behavior. rebinding and user settings rebinding and user settings use ue 5.8 uenhancedinputusersettings and player-mappable key profiles for shipping remapping. authoring 1. enable enhanced input user settings in enhanced input developer/project settings. 2. mark each remappable action mapping with player mappable key settings at the mapping or referenced input action according to its setting behavior. 3. assign a stable unique mapping name, localized displayname, display category, supported profiles, and optional metadata. 4. use mapping slots for multiple bindings to the same semantic row, such as primary and secondary. 5. register every relevant input mapping context with user settings, including unloaded plugin contexts through the intended registration point. do not use localized labels or asset display names as persistent identity. runtime remap 1. obtain user settings from the correct enhanced input subsystem/local player. 2. query the current key profile and mapping row/slot. 3. capture the new fkey. 4. query/report collisions according to project policy before mapping. 5. build fmapplayerkeyargs with stable mapping name, slot, new key, and hardware/profile data required by the current api. 6. call mapplayerkey and inspect the returned failure-reason tag container. 7. apply settings/rebuild ui as required. 8. save settings asynchronously for ordinary ux unless the project has a reason to block. provide reset-row, reset-profile, clear-slot, cancel, and restore-default operations. surface failure reasons instead of silently failing. conflict policy choose and communicate one: - reject duplicate; - ask to swap; - replace old binding; - allow duplicates only across mutually exclusive contexts; - allow duplicates for accessibility. check device family, context overlap, action consumption/priority, and profile slot—not only whether the raw key appears anywhere. persistence tests - relaunch and load; - different local users/profiles; - primary/secondary slots; - keyboard, mouse, gamepad, and accessibility devices; - changed/removed mapping assets after an update; - plugin context registered while not loaded; - reset to defaults; - corrupted/missing save fallback; - localized ui does not alter stable mapping identity. ue 5.8 primary sources ue 5.8 primary sources verified 2026-07-19. - enhanced input - enhanced input api - etriggerevent api - uenhancedinputcomponent api - add mapping context blueprint api - uenhancedinputusersettings api - uenhancedinputdevelopersettings api - uplayermappablekeysettings api - register input mapping context - save settings - unreal engine 5.8 release notes version note: ue 5.8 unifies enhanced input and common input/ui workflows and fixes state loss and re-firing around mapping rebuilds. epic's current apis expose uenhancedinputusersettings, player-mappable profiles, mapping rows/slots, failure reasons, apply, and save operations. the gameplay-buffer procedure in this skill is an explicit project-layer pattern, not a claim that enhanced input provides a built-in precondition buffer. triggers and modifiers triggers and modifiers processing order raw device value → mapping/action modifiers → triggers → etriggerevent callbacks. use modifiers for values and triggers for activation conditions. modifier patterns - dead zone: suppress small analog noise; choose axial or radial behavior deliberately. - scalar: sensitivity or axis gain. - negate: invert selected axes or turn positive digital keys into negative input. - swizzle input axis values: move a 1d key value to another axis. - response/dead-zone custom modifier: only when built-ins cannot express the device curve. - world-space modifier: only when the receiver truly needs world-space input. for wasd feeding axis2d, epic's documented pattern is: | key | desired value | mapping modifiers | |---|---|---| | w | +y | swizzle axis | | a | −x | negate | | s | −y | negate + swizzle axis | | d | +x | none | normalize/clamp only when the design requires it. diagonal keyboard accumulation and analog magnitude must be tested rather than assumed. trigger patterns - pressed: one trigger as actuation crosses the threshold. - released: trigger on release after actuation. - hold: trigger after held duration; can be one-shot or repeated by configuration. - hold and release: trigger on release after minimum hold. - tap: press/release within threshold. - pulse: repeated interval while actuated. - chord: requires another input action. - blocker: prevents success when its condition succeeds. event binding semantics | event | use | |---|---| | started | begin evaluation/presentation, such as charging feedback | | ongoing | show incomplete hold/tap evaluation; may fire each tick | | triggered | execute successful semantic intent; repetition depends on trigger | | completed | handle normal end after a triggered action | | canceled | handle release/interruption before success | bind only the events the design needs. a raw action with no one-shot trigger can produce triggered repeatedly while actuated; do not use it for a one-shot action without deliberate trigger/event design. trigger composition explicit triggers require at least one explicit success, implicit triggers all must succeed, and blocker success forces failure. when mixing types, write a truth table and inspect showdebug enhancedinput. do not infer and/or behavior from asset ordering. stateful custom classes ue 5.8 preserves trigger/modifier state more reliably across mapping rebuilds. stateful custom blueprint/c++ triggers and modifiers should implement the current reinstancing callbacks so state transfers when mappings are rebuilt without semantic change. troubleshooting troubleshooting action never fires - confirm the correct mapping context is applied to the correct local player. - inspect context priority/collisions with showdebug enhancedinput. - confirm value type matches mapping and callback extraction. - inspect modifier output and trigger state/threshold. - confirm action is bound after possession/input component setup. action fires every frame instead of once - raw actuation with no one-shot trigger can trigger each tick. - use pressed or another deliberate one-shot trigger, or bind the correct event. - do not patch with a gameplay bool before understanding trigger semantics. hold never completes or tap fires unexpectedly - inspect hold/tap threshold, actuation threshold, explicit/implicit/blocker composition. - handle completed and canceled separately. - test focus loss and mapping rebuild while held. - ensure two actions sharing the key have intentional chord/blocker/priority behavior. input becomes stuck after opening ui - confirm ui input routing/focus and gameplay context lifecycle. - handle flushed input and canceled/completed cleanup. - clear gameplay held state when context/pawn changes. - in ue 5.8, check custom stateful modifier/trigger reinstancing implementation. context added but wrong action wins - inspect all active contexts and their priorities. - remove mutually exclusive context instead of relying only on priority. - check whether the same key maps to the same versus different actions. - revisit consume/chord behavior and ue 5.8 common ui integration. duplicate callback after respawn - bind actions once in the correct input-component lifecycle. - check repeated bindaction calls and stale pawn/component references. - keep context management separate from pawn callback binding. rebinding appears in ui but does not work - confirm mapping context is registered with user settings. - confirm stable mapping name, slot, profile, and device data. - inspect mapplayerkey failure-reason tags. - apply/rebuild as required and save the correct local player's settings. - query the active profile, not only the default asset mapping. keyboard diagonal is too fast - inspect accumulated axis2d magnitude after negate/swizzle. - clamp/normalize in the appropriate input/gameplay layer only if the design requires equal cardinal and diagonal magnitude. - preserve analog magnitude when normalizing digital input; one rule may not fit both devices. buffered action fires in the wrong state - clear on context removal, pawn replacement, death, cancel, or expiry. - revalidate legality at consumption time. - consume exactly once and log request/consume timestamps. - decide whether direction/target is captured at press or at execution.","references":[{"slug":"architecture","file":"architecture.md","title":"Enhanced Input architecture","rawMarkdown":"# Enhanced Input architecture\n\n## Asset model\n\n| Asset/type | Owns |\n|---|---|\n| `UInputAction` | Semantic intent and value type; optional action-level modifiers/triggers/settings |\n| `UInputMappingContext` | Key-to-action mappings for one coherent context plus mapping-level modifiers/triggers |\n| `UInputModifier` | Raw value transformation before trigger evaluation |\n| `UInputTrigger` | Conditions/timing that decide action state |\n| `UEnhancedInputLocalPlayerSubsystem` | Applied contexts and priorities for one local player |\n| `UEnhancedInputComponent` | Action-to-delegate bindings in the input stack |\n| `UEnhancedInputUserSettings` | Per-user mappable keys, profiles, input/accessibility settings, registration, persistence |\n\n## Ordered setup\n\n1. Ensure Enhanced Input is enabled and the project uses Enhanced Player Input / Enhanced\n   Input Component classes where manual project setup requires them.\n2. Create Input Actions named for intent: `IA_Move`, `IA_Look`, `IA_Jump`, `IA_Interact`.\n3. Choose exact value types. A 2D move action should be Axis2D; a button is usually Boolean.\n4. Create small Mapping Contexts by coherent availability/lifecycle: common gameplay, on-foot,\n   vehicle, menu/debug, and similar.\n5. Add contexts to the owning Local Player subsystem with explicit priority.\n6. Bind actions once during the Pawn/Controller input initialization lifecycle.\n7. Forward intent into gameplay systems. Input code should not own authoritative outcomes.\n\n## Intent boundary\n\nInput says what the local player requested. The receiver decides whether it is legal:\n\n- Character Movement consumes movement/jump requests;\n- GAS attempts ability activation;\n- interaction component resolves and validates targets;\n- UI routing decides whether gameplay should receive input;\n- server validates multiplayer outcomes.\n\nUse Gameplay Tags for semantic input routing only when the project benefits from data-driven\nability/loadout binding. Keep input tags separate from ability identity/state tags; route tag\ntaxonomy to `$unreal-gameplay-tags`.\n","webMarkdown":"## Asset model\n\n| Asset/type | Owns |\n|---|---|\n| `UInputAction` | Semantic intent and value type; optional action-level modifiers/triggers/settings |\n| `UInputMappingContext` | Key-to-action mappings for one coherent context plus mapping-level modifiers/triggers |\n| `UInputModifier` | Raw value transformation before trigger evaluation |\n| `UInputTrigger` | Conditions/timing that decide action state |\n| `UEnhancedInputLocalPlayerSubsystem` | Applied contexts and priorities for one local player |\n| `UEnhancedInputComponent` | Action-to-delegate bindings in the input stack |\n| `UEnhancedInputUserSettings` | Per-user mappable keys, profiles, input/accessibility settings, registration, persistence |\n\n## Ordered setup\n\n1. Ensure Enhanced Input is enabled and the project uses Enhanced Player Input / Enhanced\n   Input Component classes where manual project setup requires them.\n2. Create Input Actions named for intent: `IA_Move`, `IA_Look`, `IA_Jump`, `IA_Interact`.\n3. Choose exact value types. A 2D move action should be Axis2D; a button is usually Boolean.\n4. Create small Mapping Contexts by coherent availability/lifecycle: common gameplay, on-foot,\n   vehicle, menu/debug, and similar.\n5. Add contexts to the owning Local Player subsystem with explicit priority.\n6. Bind actions once during the Pawn/Controller input initialization lifecycle.\n7. Forward intent into gameplay systems. Input code should not own authoritative outcomes.\n\n## Intent boundary\n\nInput says what the local player requested. The receiver decides whether it is legal:\n\n- Character Movement consumes movement/jump requests;\n- GAS attempts ability activation;\n- interaction component resolves and validates targets;\n- UI routing decides whether gameplay should receive input;\n- server validates multiplayer outcomes.\n\nUse Gameplay Tags for semantic input routing only when the project benefits from data-driven\nability/loadout binding. Keep input tags separate from ability identity/state tags; route tag\ntaxonomy to `$unreal-gameplay-tags`.\n","searchText":"enhanced input architecture asset model | asset/type | owns | |---|---| | uinputaction | semantic intent and value type; optional action-level modifiers/triggers/settings | | uinputmappingcontext | key-to-action mappings for one coherent context plus mapping-level modifiers/triggers | | uinputmodifier | raw value transformation before trigger evaluation | | uinputtrigger | conditions/timing that decide action state | | uenhancedinputlocalplayersubsystem | applied contexts and priorities for one local player | | uenhancedinputcomponent | action-to-delegate bindings in the input stack | | uenhancedinputusersettings | per-user mappable keys, profiles, input/accessibility settings, registration, persistence | ordered setup 1. ensure enhanced input is enabled and the project uses enhanced player input / enhanced input component classes where manual project setup requires them. 2. create input actions named for intent: iamove, ialook, iajump, iainteract. 3. choose exact value types. a 2d move action should be axis2d; a button is usually boolean. 4. create small mapping contexts by coherent availability/lifecycle: common gameplay, on-foot, vehicle, menu/debug, and similar. 5. add contexts to the owning local player subsystem with explicit priority. 6. bind actions once during the pawn/controller input initialization lifecycle. 7. forward intent into gameplay systems. input code should not own authoritative outcomes. intent boundary input says what the local player requested. the receiver decides whether it is legal: - character movement consumes movement/jump requests; - gas attempts ability activation; - interaction component resolves and validates targets; - ui routing decides whether gameplay should receive input; - server validates multiplayer outcomes. use gameplay tags for semantic input routing only when the project benefits from data-driven ability/loadout binding. keep input tags separate from ability identity/state tags; route tag taxonomy to $unreal-gameplay-tags."},{"slug":"buffering","file":"buffering.md","title":"Gameplay input buffering and coyote time","rawMarkdown":"# Gameplay input buffering and coyote time\n\nEnhanced Input determines that an action was requested. Buffering preserves that semantic\nrequest until gameplay can accept it.\n\n## Minimal buffer model\n\nStore per buffered action:\n\n- semantic action identifier or Input Action;\n- local request timestamp using a consistent clock;\n- optional value/target/direction snapshot;\n- expiration duration;\n- consumed/canceled state.\n\nProcedure:\n\n1. On the deliberate input event (usually `Triggered` or `Started`), record/replace the request.\n2. Immediately ask the gameplay system whether it can execute.\n3. Re-evaluate only on relevant state changes or a bounded update path—landing, montage window,\n   cooldown end, state-tag removal—not by spawning unbounded timers.\n4. If legal and unexpired, consume exactly once and execute.\n5. If expired, canceled, context removed, pawn changed, or input semantics invalidate it, clear.\n6. Server still validates the resulting action in multiplayer.\n\nPseudocode:\n\n```text\nOnJumpRequested(now):\n    bufferedJump = { requestedAt: now, expiresAt: now + JumpBufferWindow }\n    TryConsumeJump(now)\n\nOnLanded(now):\n    TryConsumeJump(now)\n\nTryConsumeJump(now):\n    if bufferedJump exists and now <= expiresAt and CanJump():\n        clear bufferedJump\n        Jump()\n```\n\n## Coyote time\n\nTrack the last valid grounded time. Permit Jump when grounded now or when\n`Now - LastGroundedTime <= CoyoteWindow`. Combine with the request buffer:\n\n- early press before landing → input buffer;\n- late press just after leaving edge → coyote time.\n\nThey solve opposite timing errors and should have separate tuning variables/telemetry.\n\n## Ability/action buffer\n\nFor attacks/abilities, store semantic intent and consume at the next legal cancel/combo window.\nDo not replay raw key events. Define whether the newest request replaces the oldest, how many\nrequests can queue, and whether direction/target is sampled at press or execution.\n\n## Multiplayer\n\nLocal buffering improves responsiveness but does not authorize the result. For Character\nmovement, integrate through the predicted movement/command path. For GAS, request ability\nactivation and let server validation/prediction policies decide. Do not send an expired queue\nof raw inputs to the server without bounded validation.\n","webMarkdown":"Enhanced Input determines that an action was requested. Buffering preserves that semantic\nrequest until gameplay can accept it.\n\n## Minimal buffer model\n\nStore per buffered action:\n\n- semantic action identifier or Input Action;\n- local request timestamp using a consistent clock;\n- optional value/target/direction snapshot;\n- expiration duration;\n- consumed/canceled state.\n\nProcedure:\n\n1. On the deliberate input event (usually `Triggered` or `Started`), record/replace the request.\n2. Immediately ask the gameplay system whether it can execute.\n3. Re-evaluate only on relevant state changes or a bounded update path—landing, montage window,\n   cooldown end, state-tag removal—not by spawning unbounded timers.\n4. If legal and unexpired, consume exactly once and execute.\n5. If expired, canceled, context removed, pawn changed, or input semantics invalidate it, clear.\n6. Server still validates the resulting action in multiplayer.\n\nPseudocode:\n\n```text\nOnJumpRequested(now):\n    bufferedJump = { requestedAt: now, expiresAt: now + JumpBufferWindow }\n    TryConsumeJump(now)\n\nOnLanded(now):\n    TryConsumeJump(now)\n\nTryConsumeJump(now):\n    if bufferedJump exists and now <= expiresAt and CanJump():\n        clear bufferedJump\n        Jump()\n```\n\n## Coyote time\n\nTrack the last valid grounded time. Permit Jump when grounded now or when\n`Now - LastGroundedTime <= CoyoteWindow`. Combine with the request buffer:\n\n- early press before landing → input buffer;\n- late press just after leaving edge → coyote time.\n\nThey solve opposite timing errors and should have separate tuning variables/telemetry.\n\n## Ability/action buffer\n\nFor attacks/abilities, store semantic intent and consume at the next legal cancel/combo window.\nDo not replay raw key events. Define whether the newest request replaces the oldest, how many\nrequests can queue, and whether direction/target is sampled at press or execution.\n\n## Multiplayer\n\nLocal buffering improves responsiveness but does not authorize the result. For Character\nmovement, integrate through the predicted movement/command path. For GAS, request ability\nactivation and let server validation/prediction policies decide. Do not send an expired queue\nof raw inputs to the server without bounded validation.\n","searchText":"gameplay input buffering and coyote time enhanced input determines that an action was requested. buffering preserves that semantic request until gameplay can accept it. minimal buffer model store per buffered action: - semantic action identifier or input action; - local request timestamp using a consistent clock; - optional value/target/direction snapshot; - expiration duration; - consumed/canceled state. procedure: 1. on the deliberate input event (usually triggered or started), record/replace the request. 2. immediately ask the gameplay system whether it can execute. 3. re-evaluate only on relevant state changes or a bounded update path—landing, montage window, cooldown end, state-tag removal—not by spawning unbounded timers. 4. if legal and unexpired, consume exactly once and execute. 5. if expired, canceled, context removed, pawn changed, or input semantics invalidate it, clear. 6. server still validates the resulting action in multiplayer. pseudocode: text onjumprequested(now): bufferedjump = { requestedat: now, expiresat: now + jumpbufferwindow } tryconsumejump(now) onlanded(now): tryconsumejump(now) tryconsumejump(now): if bufferedjump exists and now <= expiresat and canjump(): clear bufferedjump jump() coyote time track the last valid grounded time. permit jump when grounded now or when now - lastgroundedtime <= coyotewindow. combine with the request buffer: - early press before landing → input buffer; - late press just after leaving edge → coyote time. they solve opposite timing errors and should have separate tuning variables/telemetry. ability/action buffer for attacks/abilities, store semantic intent and consume at the next legal cancel/combo window. do not replay raw key events. define whether the newest request replaces the oldest, how many requests can queue, and whether direction/target is sampled at press or execution. multiplayer local buffering improves responsiveness but does not authorize the result. for character movement, integrate through the predicted movement/command path. for gas, request ability activation and let server validation/prediction policies decide. do not send an expired queue of raw inputs to the server without bounded validation."},{"slug":"contexts-ownership","file":"contexts-ownership.md","title":"Mapping Context ownership and lifecycle","rawMarkdown":"# Mapping Context ownership and lifecycle\n\n## Owner\n\nApplied contexts belong to `UEnhancedInputLocalPlayerSubsystem`, so split-screen players and\nlocal profiles remain isolated. Obtain the `ULocalPlayer` from the correct PlayerController,\nthen its subsystem. Never use player index 0 as a hidden assumption in reusable code.\n\n## Context design\n\n- Base/common context: actions valid across related gameplay modes.\n- Mode context: on-foot, vehicle, swimming, build mode, spectator.\n- Overlay context: temporary targeting, radial menu, photo mode, debug.\n- UI/Common UI: follow the project's UI input-routing architecture and UE 5.8 unified input\n  workflow; do not merely stack a high-priority gameplay context over UI focus.\n\nPrefer mutually exclusive mode contexts over collisions resolved only by enormous priority\nnumbers. Priority is for intentional overlap, not lifecycle replacement.\n\n## Add/remove procedure\n\n1. Resolve the correct Local Player subsystem.\n2. Add each required context once with a documented priority.\n3. On mode transition, remove the old mutually exclusive context, then add the new one.\n4. Decide whether held inputs should remain active across the rebuild. Use\n   `FModifyContextOptions` where the API exposes the needed behavior.\n5. Remove temporary contexts on cancel, teardown, unpossess, or UI close.\n6. Log applied context, priority, owner, reason, and lifecycle in development builds.\n\n## Possession\n\n- PlayerController/LocalPlayer can outlive a Pawn.\n- Put persistent player-wide context management on the PlayerController or LocalPlayer-facing\n  service.\n- Bind Pawn-specific action callbacks through `SetupPlayerInputComponent` and avoid repeated\n  binding on repossession.\n- When the Pawn changes, route semantic actions to the new controlled object and clear stale\n  references/buffers.\n\n## Multiplayer\n\nEnhanced Input runs locally. It does not replicate a context, trigger, or action value. Convert\ninput to server-validated commands, GAS activation, or Character movement input through the\nappropriate networking system. Never treat the presence of an input action as proof that an\nauthoritative action occurred.\n","webMarkdown":"## Owner\n\nApplied contexts belong to `UEnhancedInputLocalPlayerSubsystem`, so split-screen players and\nlocal profiles remain isolated. Obtain the `ULocalPlayer` from the correct PlayerController,\nthen its subsystem. Never use player index 0 as a hidden assumption in reusable code.\n\n## Context design\n\n- Base/common context: actions valid across related gameplay modes.\n- Mode context: on-foot, vehicle, swimming, build mode, spectator.\n- Overlay context: temporary targeting, radial menu, photo mode, debug.\n- UI/Common UI: follow the project's UI input-routing architecture and UE 5.8 unified input\n  workflow; do not merely stack a high-priority gameplay context over UI focus.\n\nPrefer mutually exclusive mode contexts over collisions resolved only by enormous priority\nnumbers. Priority is for intentional overlap, not lifecycle replacement.\n\n## Add/remove procedure\n\n1. Resolve the correct Local Player subsystem.\n2. Add each required context once with a documented priority.\n3. On mode transition, remove the old mutually exclusive context, then add the new one.\n4. Decide whether held inputs should remain active across the rebuild. Use\n   `FModifyContextOptions` where the API exposes the needed behavior.\n5. Remove temporary contexts on cancel, teardown, unpossess, or UI close.\n6. Log applied context, priority, owner, reason, and lifecycle in development builds.\n\n## Possession\n\n- PlayerController/LocalPlayer can outlive a Pawn.\n- Put persistent player-wide context management on the PlayerController or LocalPlayer-facing\n  service.\n- Bind Pawn-specific action callbacks through `SetupPlayerInputComponent` and avoid repeated\n  binding on repossession.\n- When the Pawn changes, route semantic actions to the new controlled object and clear stale\n  references/buffers.\n\n## Multiplayer\n\nEnhanced Input runs locally. It does not replicate a context, trigger, or action value. Convert\ninput to server-validated commands, GAS activation, or Character movement input through the\nappropriate networking system. Never treat the presence of an input action as proof that an\nauthoritative action occurred.\n","searchText":"mapping context ownership and lifecycle owner applied contexts belong to uenhancedinputlocalplayersubsystem, so split-screen players and local profiles remain isolated. obtain the ulocalplayer from the correct playercontroller, then its subsystem. never use player index 0 as a hidden assumption in reusable code. context design - base/common context: actions valid across related gameplay modes. - mode context: on-foot, vehicle, swimming, build mode, spectator. - overlay context: temporary targeting, radial menu, photo mode, debug. - ui/common ui: follow the project's ui input-routing architecture and ue 5.8 unified input workflow; do not merely stack a high-priority gameplay context over ui focus. prefer mutually exclusive mode contexts over collisions resolved only by enormous priority numbers. priority is for intentional overlap, not lifecycle replacement. add/remove procedure 1. resolve the correct local player subsystem. 2. add each required context once with a documented priority. 3. on mode transition, remove the old mutually exclusive context, then add the new one. 4. decide whether held inputs should remain active across the rebuild. use fmodifycontextoptions where the api exposes the needed behavior. 5. remove temporary contexts on cancel, teardown, unpossess, or ui close. 6. log applied context, priority, owner, reason, and lifecycle in development builds. possession - playercontroller/localplayer can outlive a pawn. - put persistent player-wide context management on the playercontroller or localplayer-facing service. - bind pawn-specific action callbacks through setupplayerinputcomponent and avoid repeated binding on repossession. - when the pawn changes, route semantic actions to the new controlled object and clear stale references/buffers. multiplayer enhanced input runs locally. it does not replicate a context, trigger, or action value. convert input to server-validated commands, gas activation, or character movement input through the appropriate networking system. never treat the presence of an input action as proof that an authoritative action occurred."},{"slug":"patterns","file":"patterns.md","title":"Enhanced Input patterns","rawMarkdown":"# Enhanced Input patterns\n\n## Camera-relative 2D movement\n\n- `IA_Move`: Axis2D.\n- Keyboard mappings use Negate/Swizzle; gamepad stick maps directly with a dead zone.\n- Bind `Triggered` for continuous movement values and handle zero/end only if receiver needs it.\n- Convert input axes using controller/camera yaw basis, then call `AddMovementInput` for the\n  Character.\n- Do not multiply `AddMovementInput` scale by delta time; Character Movement consumes input and\n  performs time integration.\n\n## Look\n\n- `IA_Look`: Axis2D.\n- Separate mouse and gamepad mappings/modifiers when sensitivity units/acceleration differ.\n- Apply inversion/sensitivity in modifiers or a centralized settings layer.\n- Test time-dilation and frame-rate behavior; mouse delta and stick rate may require different\n  treatment.\n\n## Jump with forgiveness\n\n- `IA_Jump`: Boolean + Pressed/appropriate one-shot semantics.\n- Press records jump request; release calls Stop Jumping for variable height.\n- Gameplay movement layer owns buffer and coyote windows.\n- Clear on pawn/context changes and consume once.\n\n## Sprint\n\n- Hold: Started/Triggered sets request; Completed/Canceled clears it.\n- Toggle: Pressed toggles local intent; gameplay/server can reject based on stamina/state.\n- A context should not contain competing hold and toggle implementations simultaneously.\n\n## Tap versus hold on one key\n\nPrefer separate semantic actions sharing a key with Tap and Hold triggers, or one action whose\ntrigger-state flow is deliberately interpreted. Test quick release, exact threshold, long hold,\nfocus loss, mapping rebuild, and simultaneous chord conditions. Ensure tap does not fire after a\nsuccessful hold unless designed.\n\n## Vehicle transition\n\n1. Keep common pause/chat actions in base context.\n2. Remove on-foot context.\n3. Add vehicle context at documented priority.\n4. Route actions to current controlled vehicle.\n5. On exit/unpossess, reverse and clear held/buffered state.\n\n## GAS ability input\n\n- Input Action produces semantic input identifier/tag.\n- Player input binding layer finds granted ability specs or sends a Gameplay Event.\n- GAS owns activation legality, cost, cooldown, prediction, and cancellation.\n- Keep press/release state if the ability needs held-input tasks.\n- Route the ability lifecycle to `$unreal-gas-abilities`.\n\n## Input testing/injection\n\nUse `showdebug enhancedinput` for live actions/mappings and `showdebug devices` for devices.\nUse Enhanced Input injection or `Input.+key`/`Input.-key` for deterministic test support where\nappropriate. Injection tests the input pipeline; it does not prove physical-device or OS focus\nbehavior.\n","webMarkdown":"## Camera-relative 2D movement\n\n- `IA_Move`: Axis2D.\n- Keyboard mappings use Negate/Swizzle; gamepad stick maps directly with a dead zone.\n- Bind `Triggered` for continuous movement values and handle zero/end only if receiver needs it.\n- Convert input axes using controller/camera yaw basis, then call `AddMovementInput` for the\n  Character.\n- Do not multiply `AddMovementInput` scale by delta time; Character Movement consumes input and\n  performs time integration.\n\n## Look\n\n- `IA_Look`: Axis2D.\n- Separate mouse and gamepad mappings/modifiers when sensitivity units/acceleration differ.\n- Apply inversion/sensitivity in modifiers or a centralized settings layer.\n- Test time-dilation and frame-rate behavior; mouse delta and stick rate may require different\n  treatment.\n\n## Jump with forgiveness\n\n- `IA_Jump`: Boolean + Pressed/appropriate one-shot semantics.\n- Press records jump request; release calls Stop Jumping for variable height.\n- Gameplay movement layer owns buffer and coyote windows.\n- Clear on pawn/context changes and consume once.\n\n## Sprint\n\n- Hold: Started/Triggered sets request; Completed/Canceled clears it.\n- Toggle: Pressed toggles local intent; gameplay/server can reject based on stamina/state.\n- A context should not contain competing hold and toggle implementations simultaneously.\n\n## Tap versus hold on one key\n\nPrefer separate semantic actions sharing a key with Tap and Hold triggers, or one action whose\ntrigger-state flow is deliberately interpreted. Test quick release, exact threshold, long hold,\nfocus loss, mapping rebuild, and simultaneous chord conditions. Ensure tap does not fire after a\nsuccessful hold unless designed.\n\n## Vehicle transition\n\n1. Keep common pause/chat actions in base context.\n2. Remove on-foot context.\n3. Add vehicle context at documented priority.\n4. Route actions to current controlled vehicle.\n5. On exit/unpossess, reverse and clear held/buffered state.\n\n## GAS ability input\n\n- Input Action produces semantic input identifier/tag.\n- Player input binding layer finds granted ability specs or sends a Gameplay Event.\n- GAS owns activation legality, cost, cooldown, prediction, and cancellation.\n- Keep press/release state if the ability needs held-input tasks.\n- Route the ability lifecycle to `$unreal-gas-abilities`.\n\n## Input testing/injection\n\nUse `showdebug enhancedinput` for live actions/mappings and `showdebug devices` for devices.\nUse Enhanced Input injection or `Input.+key`/`Input.-key` for deterministic test support where\nappropriate. Injection tests the input pipeline; it does not prove physical-device or OS focus\nbehavior.\n","searchText":"enhanced input patterns camera-relative 2d movement - iamove: axis2d. - keyboard mappings use negate/swizzle; gamepad stick maps directly with a dead zone. - bind triggered for continuous movement values and handle zero/end only if receiver needs it. - convert input axes using controller/camera yaw basis, then call addmovementinput for the character. - do not multiply addmovementinput scale by delta time; character movement consumes input and performs time integration. look - ialook: axis2d. - separate mouse and gamepad mappings/modifiers when sensitivity units/acceleration differ. - apply inversion/sensitivity in modifiers or a centralized settings layer. - test time-dilation and frame-rate behavior; mouse delta and stick rate may require different treatment. jump with forgiveness - iajump: boolean + pressed/appropriate one-shot semantics. - press records jump request; release calls stop jumping for variable height. - gameplay movement layer owns buffer and coyote windows. - clear on pawn/context changes and consume once. sprint - hold: started/triggered sets request; completed/canceled clears it. - toggle: pressed toggles local intent; gameplay/server can reject based on stamina/state. - a context should not contain competing hold and toggle implementations simultaneously. tap versus hold on one key prefer separate semantic actions sharing a key with tap and hold triggers, or one action whose trigger-state flow is deliberately interpreted. test quick release, exact threshold, long hold, focus loss, mapping rebuild, and simultaneous chord conditions. ensure tap does not fire after a successful hold unless designed. vehicle transition 1. keep common pause/chat actions in base context. 2. remove on-foot context. 3. add vehicle context at documented priority. 4. route actions to current controlled vehicle. 5. on exit/unpossess, reverse and clear held/buffered state. gas ability input - input action produces semantic input identifier/tag. - player input binding layer finds granted ability specs or sends a gameplay event. - gas owns activation legality, cost, cooldown, prediction, and cancellation. - keep press/release state if the ability needs held-input tasks. - route the ability lifecycle to $unreal-gas-abilities. input testing/injection use showdebug enhancedinput for live actions/mappings and showdebug devices for devices. use enhanced input injection or input.+key/input.-key for deterministic test support where appropriate. injection tests the input pipeline; it does not prove physical-device or os focus behavior."},{"slug":"rebinding-settings","file":"rebinding-settings.md","title":"Rebinding and user settings","rawMarkdown":"# Rebinding and user settings\n\nUse UE 5.8 `UEnhancedInputUserSettings` and player-mappable key profiles for shipping remapping.\n\n## Authoring\n\n1. Enable Enhanced Input user settings in Enhanced Input developer/project settings.\n2. Mark each remappable action mapping with Player Mappable Key Settings at the mapping or\n   referenced Input Action according to its Setting Behavior.\n3. Assign a stable unique mapping `Name`, localized `DisplayName`, display category, supported\n   profiles, and optional metadata.\n4. Use mapping slots for multiple bindings to the same semantic row, such as primary and\n   secondary.\n5. Register every relevant Input Mapping Context with user settings, including unloaded plugin\n   contexts through the intended registration point.\n\nDo not use localized labels or asset display names as persistent identity.\n\n## Runtime remap\n\n1. Obtain user settings from the correct Enhanced Input subsystem/local player.\n2. Query the current key profile and mapping row/slot.\n3. Capture the new `FKey`.\n4. Query/report collisions according to project policy before mapping.\n5. Build `FMapPlayerKeyArgs` with stable mapping name, slot, new key, and hardware/profile data\n   required by the current API.\n6. Call `MapPlayerKey` and inspect the returned failure-reason tag container.\n7. Apply settings/rebuild UI as required.\n8. Save settings asynchronously for ordinary UX unless the project has a reason to block.\n\nProvide reset-row, reset-profile, clear-slot, cancel, and restore-default operations. Surface\nfailure reasons instead of silently failing.\n\n## Conflict policy\n\nChoose and communicate one:\n\n- reject duplicate;\n- ask to swap;\n- replace old binding;\n- allow duplicates only across mutually exclusive contexts;\n- allow duplicates for accessibility.\n\nCheck device family, context overlap, action consumption/priority, and profile slot—not only\nwhether the raw key appears anywhere.\n\n## Persistence tests\n\n- relaunch and load;\n- different local users/profiles;\n- primary/secondary slots;\n- keyboard, mouse, gamepad, and accessibility devices;\n- changed/removed mapping assets after an update;\n- plugin context registered while not loaded;\n- reset to defaults;\n- corrupted/missing save fallback;\n- localized UI does not alter stable mapping identity.\n","webMarkdown":"Use UE 5.8 `UEnhancedInputUserSettings` and player-mappable key profiles for shipping remapping.\n\n## Authoring\n\n1. Enable Enhanced Input user settings in Enhanced Input developer/project settings.\n2. Mark each remappable action mapping with Player Mappable Key Settings at the mapping or\n   referenced Input Action according to its Setting Behavior.\n3. Assign a stable unique mapping `Name`, localized `DisplayName`, display category, supported\n   profiles, and optional metadata.\n4. Use mapping slots for multiple bindings to the same semantic row, such as primary and\n   secondary.\n5. Register every relevant Input Mapping Context with user settings, including unloaded plugin\n   contexts through the intended registration point.\n\nDo not use localized labels or asset display names as persistent identity.\n\n## Runtime remap\n\n1. Obtain user settings from the correct Enhanced Input subsystem/local player.\n2. Query the current key profile and mapping row/slot.\n3. Capture the new `FKey`.\n4. Query/report collisions according to project policy before mapping.\n5. Build `FMapPlayerKeyArgs` with stable mapping name, slot, new key, and hardware/profile data\n   required by the current API.\n6. Call `MapPlayerKey` and inspect the returned failure-reason tag container.\n7. Apply settings/rebuild UI as required.\n8. Save settings asynchronously for ordinary UX unless the project has a reason to block.\n\nProvide reset-row, reset-profile, clear-slot, cancel, and restore-default operations. Surface\nfailure reasons instead of silently failing.\n\n## Conflict policy\n\nChoose and communicate one:\n\n- reject duplicate;\n- ask to swap;\n- replace old binding;\n- allow duplicates only across mutually exclusive contexts;\n- allow duplicates for accessibility.\n\nCheck device family, context overlap, action consumption/priority, and profile slot—not only\nwhether the raw key appears anywhere.\n\n## Persistence tests\n\n- relaunch and load;\n- different local users/profiles;\n- primary/secondary slots;\n- keyboard, mouse, gamepad, and accessibility devices;\n- changed/removed mapping assets after an update;\n- plugin context registered while not loaded;\n- reset to defaults;\n- corrupted/missing save fallback;\n- localized UI does not alter stable mapping identity.\n","searchText":"rebinding and user settings use ue 5.8 uenhancedinputusersettings and player-mappable key profiles for shipping remapping. authoring 1. enable enhanced input user settings in enhanced input developer/project settings. 2. mark each remappable action mapping with player mappable key settings at the mapping or referenced input action according to its setting behavior. 3. assign a stable unique mapping name, localized displayname, display category, supported profiles, and optional metadata. 4. use mapping slots for multiple bindings to the same semantic row, such as primary and secondary. 5. register every relevant input mapping context with user settings, including unloaded plugin contexts through the intended registration point. do not use localized labels or asset display names as persistent identity. runtime remap 1. obtain user settings from the correct enhanced input subsystem/local player. 2. query the current key profile and mapping row/slot. 3. capture the new fkey. 4. query/report collisions according to project policy before mapping. 5. build fmapplayerkeyargs with stable mapping name, slot, new key, and hardware/profile data required by the current api. 6. call mapplayerkey and inspect the returned failure-reason tag container. 7. apply settings/rebuild ui as required. 8. save settings asynchronously for ordinary ux unless the project has a reason to block. provide reset-row, reset-profile, clear-slot, cancel, and restore-default operations. surface failure reasons instead of silently failing. conflict policy choose and communicate one: - reject duplicate; - ask to swap; - replace old binding; - allow duplicates only across mutually exclusive contexts; - allow duplicates for accessibility. check device family, context overlap, action consumption/priority, and profile slot—not only whether the raw key appears anywhere. persistence tests - relaunch and load; - different local users/profiles; - primary/secondary slots; - keyboard, mouse, gamepad, and accessibility devices; - changed/removed mapping assets after an update; - plugin context registered while not loaded; - reset to defaults; - corrupted/missing save fallback; - localized ui does not alter stable mapping identity."},{"slug":"sources","file":"sources.md","title":"UE 5.8 primary sources","rawMarkdown":"# UE 5.8 primary sources\n\nVerified 2026-07-19.\n\n- [Enhanced Input](https://dev.epicgames.com/documentation/en-us/unreal-engine/enhanced-input-in-unreal-engine)\n- [Enhanced Input API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/EnhancedInput)\n- [`ETriggerEvent` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/EnhancedInput/ETriggerEvent)\n- [`UEnhancedInputComponent` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/EnhancedInput/UEnhancedInputComponent)\n- [Add Mapping Context Blueprint API](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/Input/AddMappingContext)\n- [`UEnhancedInputUserSettings` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/EnhancedInput/UEnhancedInputUserSettings)\n- [`UEnhancedInputDeveloperSettings` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/EnhancedInput/UEnhancedInputDeveloperSettings)\n- [`UPlayerMappableKeySettings` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/EnhancedInput/UPlayerMappableKeySettings)\n- [Register Input Mapping Context](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/EnhancedInput/UserSettings/RegisterInputMappingContext)\n- [Save Settings](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/EnhancedInput/UserSettings/SaveSettings)\n- [Unreal Engine 5.8 Release Notes](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-8-release-notes)\n\nVersion note: UE 5.8 unifies Enhanced Input and Common Input/UI workflows and fixes state loss\nand re-firing around mapping rebuilds. Epic's current APIs expose `UEnhancedInputUserSettings`,\nplayer-mappable profiles, mapping rows/slots, failure reasons, apply, and save operations. The\ngameplay-buffer procedure in this skill is an explicit project-layer pattern, not a claim that\nEnhanced Input provides a built-in precondition buffer.\n","webMarkdown":"Verified 2026-07-19.\n\n- [Enhanced Input](https://dev.epicgames.com/documentation/en-us/unreal-engine/enhanced-input-in-unreal-engine)\n- [Enhanced Input API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/EnhancedInput)\n- [`ETriggerEvent` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/EnhancedInput/ETriggerEvent)\n- [`UEnhancedInputComponent` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/EnhancedInput/UEnhancedInputComponent)\n- [Add Mapping Context Blueprint API](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/Input/AddMappingContext)\n- [`UEnhancedInputUserSettings` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/EnhancedInput/UEnhancedInputUserSettings)\n- [`UEnhancedInputDeveloperSettings` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/EnhancedInput/UEnhancedInputDeveloperSettings)\n- [`UPlayerMappableKeySettings` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/EnhancedInput/UPlayerMappableKeySettings)\n- [Register Input Mapping Context](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/EnhancedInput/UserSettings/RegisterInputMappingContext)\n- [Save Settings](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/EnhancedInput/UserSettings/SaveSettings)\n- [Unreal Engine 5.8 Release Notes](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-8-release-notes)\n\nVersion note: UE 5.8 unifies Enhanced Input and Common Input/UI workflows and fixes state loss\nand re-firing around mapping rebuilds. Epic's current APIs expose `UEnhancedInputUserSettings`,\nplayer-mappable profiles, mapping rows/slots, failure reasons, apply, and save operations. The\ngameplay-buffer procedure in this skill is an explicit project-layer pattern, not a claim that\nEnhanced Input provides a built-in precondition buffer.\n","searchText":"ue 5.8 primary sources verified 2026-07-19. - enhanced input - enhanced input api - etriggerevent api - uenhancedinputcomponent api - add mapping context blueprint api - uenhancedinputusersettings api - uenhancedinputdevelopersettings api - uplayermappablekeysettings api - register input mapping context - save settings - unreal engine 5.8 release notes version note: ue 5.8 unifies enhanced input and common input/ui workflows and fixes state loss and re-firing around mapping rebuilds. epic's current apis expose uenhancedinputusersettings, player-mappable profiles, mapping rows/slots, failure reasons, apply, and save operations. the gameplay-buffer procedure in this skill is an explicit project-layer pattern, not a claim that enhanced input provides a built-in precondition buffer."},{"slug":"triggers-modifiers","file":"triggers-modifiers.md","title":"Triggers and modifiers","rawMarkdown":"# Triggers and modifiers\n\n## Processing order\n\nRaw device value → mapping/action modifiers → triggers → `ETriggerEvent` callbacks.\n\nUse modifiers for values and triggers for activation conditions.\n\n## Modifier patterns\n\n- Dead Zone: suppress small analog noise; choose axial or radial behavior deliberately.\n- Scalar: sensitivity or axis gain.\n- Negate: invert selected axes or turn positive digital keys into negative input.\n- Swizzle Input Axis Values: move a 1D key value to another axis.\n- Response/dead-zone custom modifier: only when built-ins cannot express the device curve.\n- World-space modifier: only when the receiver truly needs world-space input.\n\nFor WASD feeding Axis2D, Epic's documented pattern is:\n\n| Key | Desired value | Mapping modifiers |\n|---|---|---|\n| W | +Y | Swizzle axis |\n| A | −X | Negate |\n| S | −Y | Negate + Swizzle axis |\n| D | +X | None |\n\nNormalize/clamp only when the design requires it. Diagonal keyboard accumulation and analog\nmagnitude must be tested rather than assumed.\n\n## Trigger patterns\n\n- Pressed: one trigger as actuation crosses the threshold.\n- Released: trigger on release after actuation.\n- Hold: trigger after held duration; can be one-shot or repeated by configuration.\n- Hold And Release: trigger on release after minimum hold.\n- Tap: press/release within threshold.\n- Pulse: repeated interval while actuated.\n- Chord: requires another Input Action.\n- Blocker: prevents success when its condition succeeds.\n\n## Event binding semantics\n\n| Event | Use |\n|---|---|\n| `Started` | Begin evaluation/presentation, such as charging feedback |\n| `Ongoing` | Show incomplete hold/tap evaluation; may fire each tick |\n| `Triggered` | Execute successful semantic intent; repetition depends on trigger |\n| `Completed` | Handle normal end after a triggered action |\n| `Canceled` | Handle release/interruption before success |\n\nBind only the events the design needs. A raw action with no one-shot trigger can produce\nTriggered repeatedly while actuated; do not use it for a one-shot action without deliberate\ntrigger/event design.\n\n## Trigger composition\n\nExplicit triggers require at least one explicit success, implicit triggers all must succeed,\nand blocker success forces failure. When mixing types, write a truth table and inspect\n`showdebug enhancedinput`. Do not infer AND/OR behavior from asset ordering.\n\n## Stateful custom classes\n\nUE 5.8 preserves trigger/modifier state more reliably across mapping rebuilds. Stateful custom\nBlueprint/C++ triggers and modifiers should implement the current reinstancing callbacks so\nstate transfers when mappings are rebuilt without semantic change.\n","webMarkdown":"## Processing order\n\nRaw device value → mapping/action modifiers → triggers → `ETriggerEvent` callbacks.\n\nUse modifiers for values and triggers for activation conditions.\n\n## Modifier patterns\n\n- Dead Zone: suppress small analog noise; choose axial or radial behavior deliberately.\n- Scalar: sensitivity or axis gain.\n- Negate: invert selected axes or turn positive digital keys into negative input.\n- Swizzle Input Axis Values: move a 1D key value to another axis.\n- Response/dead-zone custom modifier: only when built-ins cannot express the device curve.\n- World-space modifier: only when the receiver truly needs world-space input.\n\nFor WASD feeding Axis2D, Epic's documented pattern is:\n\n| Key | Desired value | Mapping modifiers |\n|---|---|---|\n| W | +Y | Swizzle axis |\n| A | −X | Negate |\n| S | −Y | Negate + Swizzle axis |\n| D | +X | None |\n\nNormalize/clamp only when the design requires it. Diagonal keyboard accumulation and analog\nmagnitude must be tested rather than assumed.\n\n## Trigger patterns\n\n- Pressed: one trigger as actuation crosses the threshold.\n- Released: trigger on release after actuation.\n- Hold: trigger after held duration; can be one-shot or repeated by configuration.\n- Hold And Release: trigger on release after minimum hold.\n- Tap: press/release within threshold.\n- Pulse: repeated interval while actuated.\n- Chord: requires another Input Action.\n- Blocker: prevents success when its condition succeeds.\n\n## Event binding semantics\n\n| Event | Use |\n|---|---|\n| `Started` | Begin evaluation/presentation, such as charging feedback |\n| `Ongoing` | Show incomplete hold/tap evaluation; may fire each tick |\n| `Triggered` | Execute successful semantic intent; repetition depends on trigger |\n| `Completed` | Handle normal end after a triggered action |\n| `Canceled` | Handle release/interruption before success |\n\nBind only the events the design needs. A raw action with no one-shot trigger can produce\nTriggered repeatedly while actuated; do not use it for a one-shot action without deliberate\ntrigger/event design.\n\n## Trigger composition\n\nExplicit triggers require at least one explicit success, implicit triggers all must succeed,\nand blocker success forces failure. When mixing types, write a truth table and inspect\n`showdebug enhancedinput`. Do not infer AND/OR behavior from asset ordering.\n\n## Stateful custom classes\n\nUE 5.8 preserves trigger/modifier state more reliably across mapping rebuilds. Stateful custom\nBlueprint/C++ triggers and modifiers should implement the current reinstancing callbacks so\nstate transfers when mappings are rebuilt without semantic change.\n","searchText":"triggers and modifiers processing order raw device value → mapping/action modifiers → triggers → etriggerevent callbacks. use modifiers for values and triggers for activation conditions. modifier patterns - dead zone: suppress small analog noise; choose axial or radial behavior deliberately. - scalar: sensitivity or axis gain. - negate: invert selected axes or turn positive digital keys into negative input. - swizzle input axis values: move a 1d key value to another axis. - response/dead-zone custom modifier: only when built-ins cannot express the device curve. - world-space modifier: only when the receiver truly needs world-space input. for wasd feeding axis2d, epic's documented pattern is: | key | desired value | mapping modifiers | |---|---|---| | w | +y | swizzle axis | | a | −x | negate | | s | −y | negate + swizzle axis | | d | +x | none | normalize/clamp only when the design requires it. diagonal keyboard accumulation and analog magnitude must be tested rather than assumed. trigger patterns - pressed: one trigger as actuation crosses the threshold. - released: trigger on release after actuation. - hold: trigger after held duration; can be one-shot or repeated by configuration. - hold and release: trigger on release after minimum hold. - tap: press/release within threshold. - pulse: repeated interval while actuated. - chord: requires another input action. - blocker: prevents success when its condition succeeds. event binding semantics | event | use | |---|---| | started | begin evaluation/presentation, such as charging feedback | | ongoing | show incomplete hold/tap evaluation; may fire each tick | | triggered | execute successful semantic intent; repetition depends on trigger | | completed | handle normal end after a triggered action | | canceled | handle release/interruption before success | bind only the events the design needs. a raw action with no one-shot trigger can produce triggered repeatedly while actuated; do not use it for a one-shot action without deliberate trigger/event design. trigger composition explicit triggers require at least one explicit success, implicit triggers all must succeed, and blocker success forces failure. when mixing types, write a truth table and inspect showdebug enhancedinput. do not infer and/or behavior from asset ordering. stateful custom classes ue 5.8 preserves trigger/modifier state more reliably across mapping rebuilds. stateful custom blueprint/c++ triggers and modifiers should implement the current reinstancing callbacks so state transfers when mappings are rebuilt without semantic change."},{"slug":"troubleshooting","file":"troubleshooting.md","title":"Troubleshooting","rawMarkdown":"# Troubleshooting\n\n## Action never fires\n\n- Confirm the correct Mapping Context is applied to the correct Local Player.\n- Inspect context priority/collisions with `showdebug enhancedinput`.\n- Confirm value type matches mapping and callback extraction.\n- Inspect modifier output and trigger state/threshold.\n- Confirm action is bound after possession/input component setup.\n\n## Action fires every frame instead of once\n\n- Raw actuation with no one-shot trigger can Trigger each tick.\n- Use Pressed or another deliberate one-shot trigger, or bind the correct event.\n- Do not patch with a gameplay bool before understanding trigger semantics.\n\n## Hold never completes or tap fires unexpectedly\n\n- Inspect Hold/Tap threshold, actuation threshold, explicit/implicit/blocker composition.\n- Handle Completed and Canceled separately.\n- Test focus loss and mapping rebuild while held.\n- Ensure two actions sharing the key have intentional chord/blocker/priority behavior.\n\n## Input becomes stuck after opening UI\n\n- Confirm UI input routing/focus and gameplay context lifecycle.\n- Handle flushed input and Canceled/Completed cleanup.\n- Clear gameplay held state when context/pawn changes.\n- In UE 5.8, check custom stateful modifier/trigger reinstancing implementation.\n\n## Context added but wrong action wins\n\n- Inspect all active contexts and their priorities.\n- Remove mutually exclusive context instead of relying only on priority.\n- Check whether the same key maps to the same versus different actions.\n- Revisit consume/chord behavior and UE 5.8 Common UI integration.\n\n## Duplicate callback after respawn\n\n- Bind actions once in the correct input-component lifecycle.\n- Check repeated `BindAction` calls and stale Pawn/component references.\n- Keep context management separate from Pawn callback binding.\n\n## Rebinding appears in UI but does not work\n\n- Confirm mapping context is registered with user settings.\n- Confirm stable mapping name, slot, profile, and device data.\n- Inspect `MapPlayerKey` failure-reason tags.\n- Apply/rebuild as required and save the correct Local Player's settings.\n- Query the active profile, not only the default asset mapping.\n\n## Keyboard diagonal is too fast\n\n- Inspect accumulated Axis2D magnitude after Negate/Swizzle.\n- Clamp/normalize in the appropriate input/gameplay layer only if the design requires equal\n  cardinal and diagonal magnitude.\n- Preserve analog magnitude when normalizing digital input; one rule may not fit both devices.\n\n## Buffered action fires in the wrong state\n\n- Clear on context removal, pawn replacement, death, cancel, or expiry.\n- Revalidate legality at consumption time.\n- Consume exactly once and log request/consume timestamps.\n- Decide whether direction/target is captured at press or at execution.\n","webMarkdown":"## Action never fires\n\n- Confirm the correct Mapping Context is applied to the correct Local Player.\n- Inspect context priority/collisions with `showdebug enhancedinput`.\n- Confirm value type matches mapping and callback extraction.\n- Inspect modifier output and trigger state/threshold.\n- Confirm action is bound after possession/input component setup.\n\n## Action fires every frame instead of once\n\n- Raw actuation with no one-shot trigger can Trigger each tick.\n- Use Pressed or another deliberate one-shot trigger, or bind the correct event.\n- Do not patch with a gameplay bool before understanding trigger semantics.\n\n## Hold never completes or tap fires unexpectedly\n\n- Inspect Hold/Tap threshold, actuation threshold, explicit/implicit/blocker composition.\n- Handle Completed and Canceled separately.\n- Test focus loss and mapping rebuild while held.\n- Ensure two actions sharing the key have intentional chord/blocker/priority behavior.\n\n## Input becomes stuck after opening UI\n\n- Confirm UI input routing/focus and gameplay context lifecycle.\n- Handle flushed input and Canceled/Completed cleanup.\n- Clear gameplay held state when context/pawn changes.\n- In UE 5.8, check custom stateful modifier/trigger reinstancing implementation.\n\n## Context added but wrong action wins\n\n- Inspect all active contexts and their priorities.\n- Remove mutually exclusive context instead of relying only on priority.\n- Check whether the same key maps to the same versus different actions.\n- Revisit consume/chord behavior and UE 5.8 Common UI integration.\n\n## Duplicate callback after respawn\n\n- Bind actions once in the correct input-component lifecycle.\n- Check repeated `BindAction` calls and stale Pawn/component references.\n- Keep context management separate from Pawn callback binding.\n\n## Rebinding appears in UI but does not work\n\n- Confirm mapping context is registered with user settings.\n- Confirm stable mapping name, slot, profile, and device data.\n- Inspect `MapPlayerKey` failure-reason tags.\n- Apply/rebuild as required and save the correct Local Player's settings.\n- Query the active profile, not only the default asset mapping.\n\n## Keyboard diagonal is too fast\n\n- Inspect accumulated Axis2D magnitude after Negate/Swizzle.\n- Clamp/normalize in the appropriate input/gameplay layer only if the design requires equal\n  cardinal and diagonal magnitude.\n- Preserve analog magnitude when normalizing digital input; one rule may not fit both devices.\n\n## Buffered action fires in the wrong state\n\n- Clear on context removal, pawn replacement, death, cancel, or expiry.\n- Revalidate legality at consumption time.\n- Consume exactly once and log request/consume timestamps.\n- Decide whether direction/target is captured at press or at execution.\n","searchText":"troubleshooting action never fires - confirm the correct mapping context is applied to the correct local player. - inspect context priority/collisions with showdebug enhancedinput. - confirm value type matches mapping and callback extraction. - inspect modifier output and trigger state/threshold. - confirm action is bound after possession/input component setup. action fires every frame instead of once - raw actuation with no one-shot trigger can trigger each tick. - use pressed or another deliberate one-shot trigger, or bind the correct event. - do not patch with a gameplay bool before understanding trigger semantics. hold never completes or tap fires unexpectedly - inspect hold/tap threshold, actuation threshold, explicit/implicit/blocker composition. - handle completed and canceled separately. - test focus loss and mapping rebuild while held. - ensure two actions sharing the key have intentional chord/blocker/priority behavior. input becomes stuck after opening ui - confirm ui input routing/focus and gameplay context lifecycle. - handle flushed input and canceled/completed cleanup. - clear gameplay held state when context/pawn changes. - in ue 5.8, check custom stateful modifier/trigger reinstancing implementation. context added but wrong action wins - inspect all active contexts and their priorities. - remove mutually exclusive context instead of relying only on priority. - check whether the same key maps to the same versus different actions. - revisit consume/chord behavior and ue 5.8 common ui integration. duplicate callback after respawn - bind actions once in the correct input-component lifecycle. - check repeated bindaction calls and stale pawn/component references. - keep context management separate from pawn callback binding. rebinding appears in ui but does not work - confirm mapping context is registered with user settings. - confirm stable mapping name, slot, profile, and device data. - inspect mapplayerkey failure-reason tags. - apply/rebuild as required and save the correct local player's settings. - query the active profile, not only the default asset mapping. keyboard diagonal is too fast - inspect accumulated axis2d magnitude after negate/swizzle. - clamp/normalize in the appropriate input/gameplay layer only if the design requires equal cardinal and diagonal magnitude. - preserve analog magnitude when normalizing digital input; one rule may not fit both devices. buffered action fires in the wrong state - clear on context removal, pawn replacement, death, cancel, or expiry. - revalidate legality at consumption time. - consume exactly once and log request/consume timestamps. - decide whether direction/target is captured at press or at execution."}]}
{"slug":"unreal-gameplay-tags","name":"unreal-gameplay-tags","title":"Unreal 5.8 Gameplay Tags","description":"Design, govern, implement, query, replicate, and debug Gameplay Tags in Unreal Engine 5.8. Use for tag taxonomies, native or config tags, tag containers, exact versus hierarchical matching, Gameplay Tag Queries, restricted tags, state and identity tags, GAS gating, gameplay events, UI categories, migration from booleans or enums, or failures caused by missing, redirected, or mismatched tags.","shortDescription":"Design and apply governed gameplay tag systems","category":"Systems & Networking","referenceCount":5,"rawMarkdown":"---\nname: unreal-gameplay-tags\ndescription: Design, govern, implement, query, replicate, and debug Gameplay Tags in Unreal Engine 5.8. Use for tag taxonomies, native or config tags, tag containers, exact versus hierarchical matching, Gameplay Tag Queries, restricted tags, state and identity tags, GAS gating, gameplay events, UI categories, migration from booleans or enums, or failures caused by missing, redirected, or mismatched tags.\n---\n\n# Unreal 5.8 Gameplay Tags\n\n## Design the vocabulary first\n\nRead [`references/taxonomy.md`](references/taxonomy.md).\n\n1. State what each root means and who owns it.\n2. Separate semantic roles, for example `State.*`, `Ability.*`, `Event.*`, `InputTag.*`,\n   `Item.*`, `Damage.*`, and `UI.*`.\n3. Use one canonical tag for one concept. Add redirects for renames; do not leave synonyms.\n4. Declare stable code-facing tags natively. Use config sources for designer-managed sets.\n5. Restrict editing of core roots on teams that need ownership enforcement.\n\n## Select the operation\n\nRead [`references/operations.md`](references/operations.md).\n\n- Use `FGameplayTag` for one registered tag.\n- Use `FGameplayTagContainer` for a set; it tracks explicitly added tags and their parents.\n- Use hierarchical matching when a broad rule should include descendants.\n- Use exact matching when only the literal tag is valid.\n- Use `FGameplayTagQuery` for authored combinations of any/all/none expressions.\n- Use a Gameplay Event tag for an occurrence with payload; use a state tag for a condition\n  that remains true.\n\n## Execute\n\n1. Register tags before use through native definitions, config, Project Settings, or a\n   Data Table source.\n2. Store containers, not arrays of tag strings.\n3. Choose exact or hierarchical semantics explicitly at every comparison.\n4. Apply and remove runtime tags through the system that owns their lifetime—often an ASC\n   effect or ability—rather than unrelated objects editing a loose container.\n5. Keep input routing tags separate from gameplay state and ability identity.\n6. Test parent/child direction, empty containers/queries, tag removal, redirects, cooked\n   builds, replication, and save migration.\n\nRead [`references/patterns.md`](references/patterns.md) for state, gating, events, identity,\nand UI examples. Read [`references/migration-troubleshooting.md`](references/migration-troubleshooting.md)\nwhen converting bools/enums or diagnosing invalid and non-matching tags.\n\n## Required answer format\n\nReturn:\n\n1. **Proposed taxonomy**, owners, and definitions.\n2. **Storage type** and exact/hierarchical/query semantics.\n3. **Ordered Blueprint nodes or C++ calls** using verified UE names.\n4. **Lifetime and authority** for every runtime tag.\n5. **Rename/save/replication consequences**.\n6. **Truth-table tests** covering parent, child, exact, absent, and empty cases.\n\nDo not invent tags, APIs, editor paths, or GAS behavior.\n\n## Hard rules\n\n- Never compare tag text manually.\n- Never assume matching is symmetric: `A.B` matches query `A`, but `A` does not match\n  query `A.B`.\n- Never use exact matching accidentally when parent semantics are intended, or vice versa.\n- Never use tags as an ungoverned replacement for every bool, enum, identifier, or value.\n- Never make a gameplay event tag double as persistent state.\n- Never rename a shipped tag without a redirect and save/content migration plan.\n\nSee [`references/sources.md`](references/sources.md) for the UE 5.8 source trail.\n","webMarkdown":"## Design the vocabulary first\n\nRead [`references/taxonomy.md`](/unreal/unreal-gameplay-tags/taxonomy/).\n\n1. State what each root means and who owns it.\n2. Separate semantic roles, for example `State.*`, `Ability.*`, `Event.*`, `InputTag.*`,\n   `Item.*`, `Damage.*`, and `UI.*`.\n3. Use one canonical tag for one concept. Add redirects for renames; do not leave synonyms.\n4. Declare stable code-facing tags natively. Use config sources for designer-managed sets.\n5. Restrict editing of core roots on teams that need ownership enforcement.\n\n## Select the operation\n\nRead [`references/operations.md`](/unreal/unreal-gameplay-tags/operations/).\n\n- Use `FGameplayTag` for one registered tag.\n- Use `FGameplayTagContainer` for a set; it tracks explicitly added tags and their parents.\n- Use hierarchical matching when a broad rule should include descendants.\n- Use exact matching when only the literal tag is valid.\n- Use `FGameplayTagQuery` for authored combinations of any/all/none expressions.\n- Use a Gameplay Event tag for an occurrence with payload; use a state tag for a condition\n  that remains true.\n\n## Execute\n\n1. Register tags before use through native definitions, config, Project Settings, or a\n   Data Table source.\n2. Store containers, not arrays of tag strings.\n3. Choose exact or hierarchical semantics explicitly at every comparison.\n4. Apply and remove runtime tags through the system that owns their lifetime—often an ASC\n   effect or ability—rather than unrelated objects editing a loose container.\n5. Keep input routing tags separate from gameplay state and ability identity.\n6. Test parent/child direction, empty containers/queries, tag removal, redirects, cooked\n   builds, replication, and save migration.\n\nRead [`references/patterns.md`](/unreal/unreal-gameplay-tags/patterns/) for state, gating, events, identity,\nand UI examples. Read [`references/migration-troubleshooting.md`](/unreal/unreal-gameplay-tags/migration-troubleshooting/)\nwhen converting bools/enums or diagnosing invalid and non-matching tags.\n\n## Required answer format\n\nReturn:\n\n1. **Proposed taxonomy**, owners, and definitions.\n2. **Storage type** and exact/hierarchical/query semantics.\n3. **Ordered Blueprint nodes or C++ calls** using verified UE names.\n4. **Lifetime and authority** for every runtime tag.\n5. **Rename/save/replication consequences**.\n6. **Truth-table tests** covering parent, child, exact, absent, and empty cases.\n\nDo not invent tags, APIs, editor paths, or GAS behavior.\n\n## Hard rules\n\n- Never compare tag text manually.\n- Never assume matching is symmetric: `A.B` matches query `A`, but `A` does not match\n  query `A.B`.\n- Never use exact matching accidentally when parent semantics are intended, or vice versa.\n- Never use tags as an ungoverned replacement for every bool, enum, identifier, or value.\n- Never make a gameplay event tag double as persistent state.\n- Never rename a shipped tag without a redirect and save/content migration plan.\n\nSee [`references/sources.md`](/unreal/unreal-gameplay-tags/sources/) for the UE 5.8 source trail.\n","searchText":"unreal 5.8 gameplay tags design, govern, implement, query, replicate, and debug gameplay tags in unreal engine 5.8. use for tag taxonomies, native or config tags, tag containers, exact versus hierarchical matching, gameplay tag queries, restricted tags, state and identity tags, gas gating, gameplay events, ui categories, migration from booleans or enums, or failures caused by missing, redirected, or mismatched tags. migration and troubleshooting migration and troubleshooting bool to tag convert a bool when the state is cross-system, needs gas gating, has multiple sources, or is part of a growing family. 1. define the canonical tag and its owner/lifetime. 2. replace writers with owned add/remove behavior. 3. replace readers with exact or hierarchical queries. 4. add source-count/lifetime handling if multiple systems can grant the state; do not let one source remove another source's truth. 5. remove the bool after tests prove parity. keep a private, local, performance-critical bool when a global vocabulary adds no value. enum to tags keep an enum for one mutually exclusive closed state machine. use tags when categories are open-ended, hierarchical, or multiple values can coexist. if converting: 1. state whether exclusivity still applies; 2. enforce removal of sibling state tags centrally; 3. migrate serialized enum values; 4. test no-state and invalid multi-state cases. tag is invalid - confirm it exists in the registered dictionary in the cooked build. - confirm the config/tag source is included and plugin/module loads when expected. - for native request apis, do not suppress a missing critical tag without logging. - avoid constructing/comparing raw strings. parent query fails - check direction: stored child can satisfy queried parent, not the reverse. - confirm exact variant was not used. - inspect explicit container tags and expected parents. - confirm both tags are valid and registered. tag remains after state ends - identify the granting source: loose asc tag, active effect, ability-owned tag, or custom container. - pair lifetime with that source and remove by effect/ability handle when possible. - check multiple grants/stacks; one removal may correctly leave another source active. rename breaks content or saves - add a gameplay tag redirect from old to new. - resave/migrate dependent assets and serialized data. - audit text/config/data tables and native constants. - remove the redirect only after all supported content/save versions are migrated. query permits everything - inspect empty all/no expressions and empty containers. - build truth-table tests for required present, required absent, blocker present, no tags, parent only, and child only. tag operations tag operations types - fgameplaytag: one registered hierarchical name. - fgameplaytagcontainer: explicit tags plus cached parent relationships. - fgameplaytagquery: serialized any/all/none expression tree evaluated against a container. use containers instead of tarray<fgameplaytag> for tag-set behavior. matching direction given stored tag state.movement.sprinting: | test | result | |---|---| | hierarchical hastag(state.movement) | true | | exact hastagexact(state.movement) | false | | hierarchical query for state.movement.sprinting.fast | false | | exact query for state.movement.sprinting | true | matching is directional. a child satisfies a parent query; a parent does not satisfy a more specific child query. for individual tags, matchestag includes parent matching and matchestagexact requires the literal tag. for containers, use hastag, hasany, and hasall or their exact variants. empty semantics epic documents that an empty input container returns false for hastag/any-style tests, while all-style tests return true because no required tag is missing. empty query expressions have similar logical identities. test empty authored queries; a missing requirement can otherwise silently allow everything. query selection use direct container operations for simple code-owned checks. use fgameplaytagquery when: - designers author nested any/all/none logic; - the rule is stored in a data asset/table; - multiple systems evaluate the same serialized rule. example prerequisite: all(any(state.weapon.rifle, state.weapon.pistol), none(state.disabled, state.dead)) keep queries named/documented. dense anonymous query trees become difficult to debug. blueprint implementation use gameplay tag and gameplay tag container variable types and the gameplay tags blueprint library functions shown by the context menu. confirm exact versus non-exact node choice in ue 5.8; do not compare tostring output. gameplay tag patterns gameplay tag patterns persistent state use state.stunned, state.dead, or state.movement.sprinting while the condition is true. one system owns addition/removal. in gas, prefer state granted by the active effect/ability whose lifetime creates the state so removal is deterministic. test: - tag present during condition; - parent queries succeed; - exact sibling queries fail; - tag removes on expiry, cancellation, death, and teardown. ability gating separate: - ability identity: ability.movement.dash; - state owned while active: state.movement.dashing; - activation blocker: state.stunned; - input route: inputtag.ability.dash; - activation event: event.ability.dashrequested if an event path is used. configure required/blocked/cancel relationships through gas's current tag relationship settings/components and verify with failure tags. route full ability procedure to $unreal-gas-abilities. gameplay event use an event tag for a momentary occurrence plus fgameplayeventdata, such as event.combat.hitconfirmed. do not add/remove it as though it were state. define which machine sends/handles it and validate its payload and targets. identity and categorization use tags for extensible categories and cross-system queries, for example item.weapon.ranged.bow or damage.element.fire. keep a stable primary identifier separate when save identity must distinguish two assets that share the same categories. tags classify; they are not automatically unique ids. ui categories ui can map gameplay categories to presentation, but do not let display wording become the canonical gameplay taxonomy. localize labels separately. keep ui-only navigation/action tags under a ui root. message channels tags work well as channel identifiers for a scoped message system. define payload type and network scope separately. hierarchical listener semantics must be explicit; do not assume a message bus uses the same parent matching as a tag container. ue 5.8 primary sources ue 5.8 primary sources verified 2026-07-19. - using gameplay tags - fgameplaytag api - fgameplaytagcontainer api - gameplay ability system overview - abilities in lyra version note: these epic pages currently resolve to unreal engine 5.8. the exact versus hierarchical truth tables in this skill follow epic's 5.8 fgameplaytag and fgameplaytagcontainer api descriptions, including directional parent matching and empty all-container behavior. gameplay tag taxonomy gameplay tag taxonomy root design define roots by semantic role, not by whichever feature first needs a tag. | root example | meaning | |---|---| | state. | condition currently true on an entity | | ability. | ability identity/family | | event. | occurrence or request carrying an event payload | | inputtag. | semantic input routing identifier | | item. | item identity/category | | damage. | damage type/category | | gameplaycue. | cosmetic cue identity used by gas | | ui. | ui layer/action/category identity | do not mix these roles. inputtag.ability.primary may activate ability.weapon.fire, but neither should be used as state.firing unless that is genuinely the same semantic fact. naming rules - use pascalcase or the project's chosen stable convention consistently per segment. - make parent meaning include all descendants. - prefer nouns/categories for identity and adjectives/conditions for state where readable. - avoid synonyms: choose state.stunned or status.stunned, not both. - avoid implementation names such as a blueprint class path in the taxonomy. - add developer comments describing ownership and lifetime for non-obvious tags. definition method - native tags: stable tags referenced from c++; use epic's native declaration/definition macros and inspect lyra's tag files for the 5.8 pattern. - config tags: designer-managed dictionary, optionally separated into config/tags sources for ownership and merge clarity. - data table tags: useful when an external table workflow is deliberate. - project settings: convenient management ui over configured sources. governance 1. assign an owner for every root. 2. review new parents because their semantics affect all descendants. 3. use restricted tag settings for protected roots when team scale requires it. 4. add redirects for renames and remove obsolete references through a migration pass. 5. validate assets and saves before deleting the redirect. the taxonomy is an api. version it with the same care as function names and serialized ids.","references":[{"slug":"migration-troubleshooting","file":"migration-troubleshooting.md","title":"Migration and troubleshooting","rawMarkdown":"# Migration and troubleshooting\n\n## Bool to tag\n\nConvert a bool when the state is cross-system, needs GAS gating, has multiple sources, or is\npart of a growing family.\n\n1. Define the canonical tag and its owner/lifetime.\n2. Replace writers with owned add/remove behavior.\n3. Replace readers with exact or hierarchical queries.\n4. Add source-count/lifetime handling if multiple systems can grant the state; do not let one\n   source remove another source's truth.\n5. Remove the bool after tests prove parity.\n\nKeep a private, local, performance-critical bool when a global vocabulary adds no value.\n\n## Enum to tags\n\nKeep an enum for one mutually exclusive closed state machine. Use tags when categories are\nopen-ended, hierarchical, or multiple values can coexist. If converting:\n\n1. state whether exclusivity still applies;\n2. enforce removal of sibling state tags centrally;\n3. migrate serialized enum values;\n4. test no-state and invalid multi-state cases.\n\n## Tag is invalid\n\n- Confirm it exists in the registered dictionary in the cooked build.\n- Confirm the config/tag source is included and plugin/module loads when expected.\n- For native request APIs, do not suppress a missing critical tag without logging.\n- Avoid constructing/comparing raw strings.\n\n## Parent query fails\n\n- Check direction: stored child can satisfy queried parent, not the reverse.\n- Confirm exact variant was not used.\n- Inspect explicit container tags and expected parents.\n- Confirm both tags are valid and registered.\n\n## Tag remains after state ends\n\n- Identify the granting source: loose ASC tag, active effect, ability-owned tag, or custom\n  container.\n- Pair lifetime with that source and remove by effect/ability handle when possible.\n- Check multiple grants/stacks; one removal may correctly leave another source active.\n\n## Rename breaks content or saves\n\n- Add a Gameplay Tag redirect from old to new.\n- Resave/migrate dependent assets and serialized data.\n- Audit text/config/Data Tables and native constants.\n- Remove the redirect only after all supported content/save versions are migrated.\n\n## Query permits everything\n\n- Inspect empty All/No expressions and empty containers.\n- Build truth-table tests for required present, required absent, blocker present, no tags,\n  parent only, and child only.\n","webMarkdown":"## Bool to tag\n\nConvert a bool when the state is cross-system, needs GAS gating, has multiple sources, or is\npart of a growing family.\n\n1. Define the canonical tag and its owner/lifetime.\n2. Replace writers with owned add/remove behavior.\n3. Replace readers with exact or hierarchical queries.\n4. Add source-count/lifetime handling if multiple systems can grant the state; do not let one\n   source remove another source's truth.\n5. Remove the bool after tests prove parity.\n\nKeep a private, local, performance-critical bool when a global vocabulary adds no value.\n\n## Enum to tags\n\nKeep an enum for one mutually exclusive closed state machine. Use tags when categories are\nopen-ended, hierarchical, or multiple values can coexist. If converting:\n\n1. state whether exclusivity still applies;\n2. enforce removal of sibling state tags centrally;\n3. migrate serialized enum values;\n4. test no-state and invalid multi-state cases.\n\n## Tag is invalid\n\n- Confirm it exists in the registered dictionary in the cooked build.\n- Confirm the config/tag source is included and plugin/module loads when expected.\n- For native request APIs, do not suppress a missing critical tag without logging.\n- Avoid constructing/comparing raw strings.\n\n## Parent query fails\n\n- Check direction: stored child can satisfy queried parent, not the reverse.\n- Confirm exact variant was not used.\n- Inspect explicit container tags and expected parents.\n- Confirm both tags are valid and registered.\n\n## Tag remains after state ends\n\n- Identify the granting source: loose ASC tag, active effect, ability-owned tag, or custom\n  container.\n- Pair lifetime with that source and remove by effect/ability handle when possible.\n- Check multiple grants/stacks; one removal may correctly leave another source active.\n\n## Rename breaks content or saves\n\n- Add a Gameplay Tag redirect from old to new.\n- Resave/migrate dependent assets and serialized data.\n- Audit text/config/Data Tables and native constants.\n- Remove the redirect only after all supported content/save versions are migrated.\n\n## Query permits everything\n\n- Inspect empty All/No expressions and empty containers.\n- Build truth-table tests for required present, required absent, blocker present, no tags,\n  parent only, and child only.\n","searchText":"migration and troubleshooting bool to tag convert a bool when the state is cross-system, needs gas gating, has multiple sources, or is part of a growing family. 1. define the canonical tag and its owner/lifetime. 2. replace writers with owned add/remove behavior. 3. replace readers with exact or hierarchical queries. 4. add source-count/lifetime handling if multiple systems can grant the state; do not let one source remove another source's truth. 5. remove the bool after tests prove parity. keep a private, local, performance-critical bool when a global vocabulary adds no value. enum to tags keep an enum for one mutually exclusive closed state machine. use tags when categories are open-ended, hierarchical, or multiple values can coexist. if converting: 1. state whether exclusivity still applies; 2. enforce removal of sibling state tags centrally; 3. migrate serialized enum values; 4. test no-state and invalid multi-state cases. tag is invalid - confirm it exists in the registered dictionary in the cooked build. - confirm the config/tag source is included and plugin/module loads when expected. - for native request apis, do not suppress a missing critical tag without logging. - avoid constructing/comparing raw strings. parent query fails - check direction: stored child can satisfy queried parent, not the reverse. - confirm exact variant was not used. - inspect explicit container tags and expected parents. - confirm both tags are valid and registered. tag remains after state ends - identify the granting source: loose asc tag, active effect, ability-owned tag, or custom container. - pair lifetime with that source and remove by effect/ability handle when possible. - check multiple grants/stacks; one removal may correctly leave another source active. rename breaks content or saves - add a gameplay tag redirect from old to new. - resave/migrate dependent assets and serialized data. - audit text/config/data tables and native constants. - remove the redirect only after all supported content/save versions are migrated. query permits everything - inspect empty all/no expressions and empty containers. - build truth-table tests for required present, required absent, blocker present, no tags, parent only, and child only."},{"slug":"operations","file":"operations.md","title":"Tag operations","rawMarkdown":"# Tag operations\n\n## Types\n\n- `FGameplayTag`: one registered hierarchical name.\n- `FGameplayTagContainer`: explicit tags plus cached parent relationships.\n- `FGameplayTagQuery`: serialized any/all/none expression tree evaluated against a container.\n\nUse containers instead of `TArray<FGameplayTag>` for tag-set behavior.\n\n## Matching direction\n\nGiven stored tag `State.Movement.Sprinting`:\n\n| Test | Result |\n|---|---|\n| hierarchical `HasTag(State.Movement)` | true |\n| exact `HasTagExact(State.Movement)` | false |\n| hierarchical query for `State.Movement.Sprinting.Fast` | false |\n| exact query for `State.Movement.Sprinting` | true |\n\nMatching is directional. A child satisfies a parent query; a parent does not satisfy a more\nspecific child query.\n\nFor individual tags, `MatchesTag` includes parent matching and `MatchesTagExact` requires the\nliteral tag. For containers, use `HasTag`, `HasAny`, and `HasAll` or their `Exact` variants.\n\n## Empty semantics\n\nEpic documents that an empty input container returns false for HasTag/Any-style tests, while\nAll-style tests return true because no required tag is missing. Empty query expressions have\nsimilar logical identities. Test empty authored queries; a missing requirement can otherwise\nsilently allow everything.\n\n## Query selection\n\nUse direct container operations for simple code-owned checks. Use `FGameplayTagQuery` when:\n\n- designers author nested any/all/none logic;\n- the rule is stored in a Data Asset/Table;\n- multiple systems evaluate the same serialized rule.\n\nExample prerequisite:\n\n`ALL(ANY(State.Weapon.Rifle, State.Weapon.Pistol), NONE(State.Disabled, State.Dead))`\n\nKeep queries named/documented. Dense anonymous query trees become difficult to debug.\n\n## Blueprint implementation\n\nUse Gameplay Tag and Gameplay Tag Container variable types and the Gameplay Tags Blueprint\nlibrary functions shown by the context menu. Confirm exact versus non-exact node choice in\nUE 5.8; do not compare `ToString` output.\n","webMarkdown":"## Types\n\n- `FGameplayTag`: one registered hierarchical name.\n- `FGameplayTagContainer`: explicit tags plus cached parent relationships.\n- `FGameplayTagQuery`: serialized any/all/none expression tree evaluated against a container.\n\nUse containers instead of `TArray<FGameplayTag>` for tag-set behavior.\n\n## Matching direction\n\nGiven stored tag `State.Movement.Sprinting`:\n\n| Test | Result |\n|---|---|\n| hierarchical `HasTag(State.Movement)` | true |\n| exact `HasTagExact(State.Movement)` | false |\n| hierarchical query for `State.Movement.Sprinting.Fast` | false |\n| exact query for `State.Movement.Sprinting` | true |\n\nMatching is directional. A child satisfies a parent query; a parent does not satisfy a more\nspecific child query.\n\nFor individual tags, `MatchesTag` includes parent matching and `MatchesTagExact` requires the\nliteral tag. For containers, use `HasTag`, `HasAny`, and `HasAll` or their `Exact` variants.\n\n## Empty semantics\n\nEpic documents that an empty input container returns false for HasTag/Any-style tests, while\nAll-style tests return true because no required tag is missing. Empty query expressions have\nsimilar logical identities. Test empty authored queries; a missing requirement can otherwise\nsilently allow everything.\n\n## Query selection\n\nUse direct container operations for simple code-owned checks. Use `FGameplayTagQuery` when:\n\n- designers author nested any/all/none logic;\n- the rule is stored in a Data Asset/Table;\n- multiple systems evaluate the same serialized rule.\n\nExample prerequisite:\n\n`ALL(ANY(State.Weapon.Rifle, State.Weapon.Pistol), NONE(State.Disabled, State.Dead))`\n\nKeep queries named/documented. Dense anonymous query trees become difficult to debug.\n\n## Blueprint implementation\n\nUse Gameplay Tag and Gameplay Tag Container variable types and the Gameplay Tags Blueprint\nlibrary functions shown by the context menu. Confirm exact versus non-exact node choice in\nUE 5.8; do not compare `ToString` output.\n","searchText":"tag operations types - fgameplaytag: one registered hierarchical name. - fgameplaytagcontainer: explicit tags plus cached parent relationships. - fgameplaytagquery: serialized any/all/none expression tree evaluated against a container. use containers instead of tarray<fgameplaytag> for tag-set behavior. matching direction given stored tag state.movement.sprinting: | test | result | |---|---| | hierarchical hastag(state.movement) | true | | exact hastagexact(state.movement) | false | | hierarchical query for state.movement.sprinting.fast | false | | exact query for state.movement.sprinting | true | matching is directional. a child satisfies a parent query; a parent does not satisfy a more specific child query. for individual tags, matchestag includes parent matching and matchestagexact requires the literal tag. for containers, use hastag, hasany, and hasall or their exact variants. empty semantics epic documents that an empty input container returns false for hastag/any-style tests, while all-style tests return true because no required tag is missing. empty query expressions have similar logical identities. test empty authored queries; a missing requirement can otherwise silently allow everything. query selection use direct container operations for simple code-owned checks. use fgameplaytagquery when: - designers author nested any/all/none logic; - the rule is stored in a data asset/table; - multiple systems evaluate the same serialized rule. example prerequisite: all(any(state.weapon.rifle, state.weapon.pistol), none(state.disabled, state.dead)) keep queries named/documented. dense anonymous query trees become difficult to debug. blueprint implementation use gameplay tag and gameplay tag container variable types and the gameplay tags blueprint library functions shown by the context menu. confirm exact versus non-exact node choice in ue 5.8; do not compare tostring output."},{"slug":"patterns","file":"patterns.md","title":"Gameplay Tag patterns","rawMarkdown":"# Gameplay Tag patterns\n\n## Persistent state\n\nUse `State.Stunned`, `State.Dead`, or `State.Movement.Sprinting` while the condition is true.\nOne system owns addition/removal. In GAS, prefer state granted by the active effect/ability\nwhose lifetime creates the state so removal is deterministic.\n\nTest:\n\n- tag present during condition;\n- parent queries succeed;\n- exact sibling queries fail;\n- tag removes on expiry, cancellation, death, and teardown.\n\n## Ability gating\n\nSeparate:\n\n- ability identity: `Ability.Movement.Dash`;\n- state owned while active: `State.Movement.Dashing`;\n- activation blocker: `State.Stunned`;\n- input route: `InputTag.Ability.Dash`;\n- activation event: `Event.Ability.DashRequested` if an event path is used.\n\nConfigure required/blocked/cancel relationships through GAS's current tag relationship\nsettings/components and verify with failure tags. Route full ability procedure to\n`$unreal-gas-abilities`.\n\n## Gameplay Event\n\nUse an Event tag for a momentary occurrence plus `FGameplayEventData`, such as\n`Event.Combat.HitConfirmed`. Do not add/remove it as though it were state. Define which\nmachine sends/handles it and validate its payload and targets.\n\n## Identity and categorization\n\nUse tags for extensible categories and cross-system queries, for example\n`Item.Weapon.Ranged.Bow` or `Damage.Element.Fire`. Keep a stable primary identifier separate\nwhen save identity must distinguish two assets that share the same categories.\n\nTags classify; they are not automatically unique IDs.\n\n## UI categories\n\nUI can map gameplay categories to presentation, but do not let display wording become the\ncanonical gameplay taxonomy. Localize labels separately. Keep UI-only navigation/action tags\nunder a UI root.\n\n## Message channels\n\nTags work well as channel identifiers for a scoped message system. Define payload type and\nnetwork scope separately. Hierarchical listener semantics must be explicit; do not assume a\nmessage bus uses the same parent matching as a tag container.\n","webMarkdown":"## Persistent state\n\nUse `State.Stunned`, `State.Dead`, or `State.Movement.Sprinting` while the condition is true.\nOne system owns addition/removal. In GAS, prefer state granted by the active effect/ability\nwhose lifetime creates the state so removal is deterministic.\n\nTest:\n\n- tag present during condition;\n- parent queries succeed;\n- exact sibling queries fail;\n- tag removes on expiry, cancellation, death, and teardown.\n\n## Ability gating\n\nSeparate:\n\n- ability identity: `Ability.Movement.Dash`;\n- state owned while active: `State.Movement.Dashing`;\n- activation blocker: `State.Stunned`;\n- input route: `InputTag.Ability.Dash`;\n- activation event: `Event.Ability.DashRequested` if an event path is used.\n\nConfigure required/blocked/cancel relationships through GAS's current tag relationship\nsettings/components and verify with failure tags. Route full ability procedure to\n`$unreal-gas-abilities`.\n\n## Gameplay Event\n\nUse an Event tag for a momentary occurrence plus `FGameplayEventData`, such as\n`Event.Combat.HitConfirmed`. Do not add/remove it as though it were state. Define which\nmachine sends/handles it and validate its payload and targets.\n\n## Identity and categorization\n\nUse tags for extensible categories and cross-system queries, for example\n`Item.Weapon.Ranged.Bow` or `Damage.Element.Fire`. Keep a stable primary identifier separate\nwhen save identity must distinguish two assets that share the same categories.\n\nTags classify; they are not automatically unique IDs.\n\n## UI categories\n\nUI can map gameplay categories to presentation, but do not let display wording become the\ncanonical gameplay taxonomy. Localize labels separately. Keep UI-only navigation/action tags\nunder a UI root.\n\n## Message channels\n\nTags work well as channel identifiers for a scoped message system. Define payload type and\nnetwork scope separately. Hierarchical listener semantics must be explicit; do not assume a\nmessage bus uses the same parent matching as a tag container.\n","searchText":"gameplay tag patterns persistent state use state.stunned, state.dead, or state.movement.sprinting while the condition is true. one system owns addition/removal. in gas, prefer state granted by the active effect/ability whose lifetime creates the state so removal is deterministic. test: - tag present during condition; - parent queries succeed; - exact sibling queries fail; - tag removes on expiry, cancellation, death, and teardown. ability gating separate: - ability identity: ability.movement.dash; - state owned while active: state.movement.dashing; - activation blocker: state.stunned; - input route: inputtag.ability.dash; - activation event: event.ability.dashrequested if an event path is used. configure required/blocked/cancel relationships through gas's current tag relationship settings/components and verify with failure tags. route full ability procedure to $unreal-gas-abilities. gameplay event use an event tag for a momentary occurrence plus fgameplayeventdata, such as event.combat.hitconfirmed. do not add/remove it as though it were state. define which machine sends/handles it and validate its payload and targets. identity and categorization use tags for extensible categories and cross-system queries, for example item.weapon.ranged.bow or damage.element.fire. keep a stable primary identifier separate when save identity must distinguish two assets that share the same categories. tags classify; they are not automatically unique ids. ui categories ui can map gameplay categories to presentation, but do not let display wording become the canonical gameplay taxonomy. localize labels separately. keep ui-only navigation/action tags under a ui root. message channels tags work well as channel identifiers for a scoped message system. define payload type and network scope separately. hierarchical listener semantics must be explicit; do not assume a message bus uses the same parent matching as a tag container."},{"slug":"sources","file":"sources.md","title":"UE 5.8 primary sources","rawMarkdown":"# UE 5.8 primary sources\n\nVerified 2026-07-19.\n\n- [Using Gameplay Tags](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-gameplay-tags-in-unreal-engine)\n- [`FGameplayTag` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/GameplayTags/FGameplayTag)\n- [`FGameplayTagContainer` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/GameplayTags/FGameplayTagContainer)\n- [Gameplay Ability System Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/understanding-the-unreal-engine-gameplay-ability-system)\n- [Abilities in Lyra](https://dev.epicgames.com/documentation/en-us/unreal-engine/abilities-in-lyra-in-unreal-engine)\n\nVersion note: these Epic pages currently resolve to Unreal Engine 5.8. The exact versus\nhierarchical truth tables in this skill follow Epic's 5.8 `FGameplayTag` and\n`FGameplayTagContainer` API descriptions, including directional parent matching and empty\nAll-container behavior.\n","webMarkdown":"Verified 2026-07-19.\n\n- [Using Gameplay Tags](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-gameplay-tags-in-unreal-engine)\n- [`FGameplayTag` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/GameplayTags/FGameplayTag)\n- [`FGameplayTagContainer` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/GameplayTags/FGameplayTagContainer)\n- [Gameplay Ability System Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/understanding-the-unreal-engine-gameplay-ability-system)\n- [Abilities in Lyra](https://dev.epicgames.com/documentation/en-us/unreal-engine/abilities-in-lyra-in-unreal-engine)\n\nVersion note: these Epic pages currently resolve to Unreal Engine 5.8. The exact versus\nhierarchical truth tables in this skill follow Epic's 5.8 `FGameplayTag` and\n`FGameplayTagContainer` API descriptions, including directional parent matching and empty\nAll-container behavior.\n","searchText":"ue 5.8 primary sources verified 2026-07-19. - using gameplay tags - fgameplaytag api - fgameplaytagcontainer api - gameplay ability system overview - abilities in lyra version note: these epic pages currently resolve to unreal engine 5.8. the exact versus hierarchical truth tables in this skill follow epic's 5.8 fgameplaytag and fgameplaytagcontainer api descriptions, including directional parent matching and empty all-container behavior."},{"slug":"taxonomy","file":"taxonomy.md","title":"Gameplay Tag taxonomy","rawMarkdown":"# Gameplay Tag taxonomy\n\n## Root design\n\nDefine roots by semantic role, not by whichever feature first needs a tag.\n\n| Root example | Meaning |\n|---|---|\n| `State.*` | Condition currently true on an entity |\n| `Ability.*` | Ability identity/family |\n| `Event.*` | Occurrence or request carrying an event payload |\n| `InputTag.*` | Semantic input routing identifier |\n| `Item.*` | Item identity/category |\n| `Damage.*` | Damage type/category |\n| `GameplayCue.*` | Cosmetic cue identity used by GAS |\n| `UI.*` | UI layer/action/category identity |\n\nDo not mix these roles. `InputTag.Ability.Primary` may activate `Ability.Weapon.Fire`, but\nneither should be used as `State.Firing` unless that is genuinely the same semantic fact.\n\n## Naming rules\n\n- Use PascalCase or the project's chosen stable convention consistently per segment.\n- Make parent meaning include all descendants.\n- Prefer nouns/categories for identity and adjectives/conditions for state where readable.\n- Avoid synonyms: choose `State.Stunned` or `Status.Stunned`, not both.\n- Avoid implementation names such as a Blueprint class path in the taxonomy.\n- Add developer comments describing ownership and lifetime for non-obvious tags.\n\n## Definition method\n\n- Native tags: stable tags referenced from C++; use Epic's native declaration/definition\n  macros and inspect Lyra's tag files for the 5.8 pattern.\n- Config tags: designer-managed dictionary, optionally separated into `Config/Tags` sources\n  for ownership and merge clarity.\n- Data Table tags: useful when an external table workflow is deliberate.\n- Project Settings: convenient management UI over configured sources.\n\n## Governance\n\n1. Assign an owner for every root.\n2. Review new parents because their semantics affect all descendants.\n3. Use restricted tag settings for protected roots when team scale requires it.\n4. Add redirects for renames and remove obsolete references through a migration pass.\n5. Validate assets and saves before deleting the redirect.\n\nThe taxonomy is an API. Version it with the same care as function names and serialized IDs.\n","webMarkdown":"## Root design\n\nDefine roots by semantic role, not by whichever feature first needs a tag.\n\n| Root example | Meaning |\n|---|---|\n| `State.*` | Condition currently true on an entity |\n| `Ability.*` | Ability identity/family |\n| `Event.*` | Occurrence or request carrying an event payload |\n| `InputTag.*` | Semantic input routing identifier |\n| `Item.*` | Item identity/category |\n| `Damage.*` | Damage type/category |\n| `GameplayCue.*` | Cosmetic cue identity used by GAS |\n| `UI.*` | UI layer/action/category identity |\n\nDo not mix these roles. `InputTag.Ability.Primary` may activate `Ability.Weapon.Fire`, but\nneither should be used as `State.Firing` unless that is genuinely the same semantic fact.\n\n## Naming rules\n\n- Use PascalCase or the project's chosen stable convention consistently per segment.\n- Make parent meaning include all descendants.\n- Prefer nouns/categories for identity and adjectives/conditions for state where readable.\n- Avoid synonyms: choose `State.Stunned` or `Status.Stunned`, not both.\n- Avoid implementation names such as a Blueprint class path in the taxonomy.\n- Add developer comments describing ownership and lifetime for non-obvious tags.\n\n## Definition method\n\n- Native tags: stable tags referenced from C++; use Epic's native declaration/definition\n  macros and inspect Lyra's tag files for the 5.8 pattern.\n- Config tags: designer-managed dictionary, optionally separated into `Config/Tags` sources\n  for ownership and merge clarity.\n- Data Table tags: useful when an external table workflow is deliberate.\n- Project Settings: convenient management UI over configured sources.\n\n## Governance\n\n1. Assign an owner for every root.\n2. Review new parents because their semantics affect all descendants.\n3. Use restricted tag settings for protected roots when team scale requires it.\n4. Add redirects for renames and remove obsolete references through a migration pass.\n5. Validate assets and saves before deleting the redirect.\n\nThe taxonomy is an API. Version it with the same care as function names and serialized IDs.\n","searchText":"gameplay tag taxonomy root design define roots by semantic role, not by whichever feature first needs a tag. | root example | meaning | |---|---| | state. | condition currently true on an entity | | ability. | ability identity/family | | event. | occurrence or request carrying an event payload | | inputtag. | semantic input routing identifier | | item. | item identity/category | | damage. | damage type/category | | gameplaycue. | cosmetic cue identity used by gas | | ui. | ui layer/action/category identity | do not mix these roles. inputtag.ability.primary may activate ability.weapon.fire, but neither should be used as state.firing unless that is genuinely the same semantic fact. naming rules - use pascalcase or the project's chosen stable convention consistently per segment. - make parent meaning include all descendants. - prefer nouns/categories for identity and adjectives/conditions for state where readable. - avoid synonyms: choose state.stunned or status.stunned, not both. - avoid implementation names such as a blueprint class path in the taxonomy. - add developer comments describing ownership and lifetime for non-obvious tags. definition method - native tags: stable tags referenced from c++; use epic's native declaration/definition macros and inspect lyra's tag files for the 5.8 pattern. - config tags: designer-managed dictionary, optionally separated into config/tags sources for ownership and merge clarity. - data table tags: useful when an external table workflow is deliberate. - project settings: convenient management ui over configured sources. governance 1. assign an owner for every root. 2. review new parents because their semantics affect all descendants. 3. use restricted tag settings for protected roots when team scale requires it. 4. add redirects for renames and remove obsolete references through a migration pass. 5. validate assets and saves before deleting the redirect. the taxonomy is an api. version it with the same care as function names and serialized ids."}]}
{"slug":"unreal-gas-abilities","name":"unreal-gas-abilities","title":"Unreal 5.8 GAS Abilities","description":"Design, implement, network, and debug Gameplay Abilities with Unreal Engine 5.8 Gameplay Ability System. Use for Ability System Component ownership, granting, activation, input or Gameplay Event triggers, costs, cooldowns, instancing, net execution, prediction, targeting, Ability Tasks, cancellation, animation, passive abilities, or ability lifecycle failures.","shortDescription":"Build reliable network-ready GAS abilities","category":"Systems & Networking","referenceCount":6,"rawMarkdown":"---\nname: unreal-gas-abilities\ndescription: Design, implement, network, and debug Gameplay Abilities with Unreal Engine 5.8 Gameplay Ability System. Use for Ability System Component ownership, granting, activation, input or Gameplay Event triggers, costs, cooldowns, instancing, net execution, prediction, targeting, Ability Tasks, cancellation, animation, passive abilities, or ability lifecycle failures.\n---\n\n# Unreal 5.8 GAS Abilities\n\n## Establish the GAS boundary\n\nRead [`references/architecture.md`](references/architecture.md) before implementation.\n\n- Put the Ability System Component on the Pawn/Character when abilities should reset with\n  that avatar.\n- Put it on PlayerState when abilities, attributes, or cooldowns must survive pawn death or\n  replacement; initialize Owner Actor and Avatar Actor correctly on server and owning client.\n- Grant and remove abilities on authority. Store returned ability spec handles when later\n  removal or mutation is required.\n- Route attribute/effect work to `$unreal-gas-attributes-effects` and taxonomy/query work\n  to `$unreal-gameplay-tags`.\n\n## Execute the lifecycle\n\n1. Define activation trigger, ownership, instancing policy, net execution policy, tags,\n   cost, cooldown, targeting, and cancellation behavior.\n2. Request activation through `TryActivateAbility`, a Gameplay Event, or the project's\n   input-to-ability mapping. Do not call `CallActivateAbility` as a normal public entry.\n3. Let GAS run activation checks. Add custom checks only for conditions not represented by\n   tags, costs, cooldowns, or target requirements.\n4. In `ActivateAbility`, commit at the intended point. If `CommitAbility` fails, end the\n   ability without applying authoritative gameplay.\n5. Use Ability Tasks for multi-frame waits, animation, input, targeting, and events.\n6. Apply authoritative effects on the server or through a supported predicted path.\n7. Handle success, cancel, interruption, failed targeting, and montage interruption.\n8. Call `EndAbility` on every terminal path and undo non-effect side effects.\n\nRead [`references/ability-lifecycle.md`](references/ability-lifecycle.md) for the ordered\nflow, [`references/patterns.md`](references/patterns.md) for concrete ability shapes, and\n[`references/networking.md`](references/networking.md) before choosing prediction.\n\n## Required answer format\n\nReturn:\n\n1. **ASC owner/avatar layout** and initialization points.\n2. **Ability configuration**: grant path, trigger, instancing, net policy, tags, cost,\n   cooldown, and targeting.\n3. **Ordered activation graph or C++ flow**.\n4. **Authority/prediction split** and rollback limitations.\n5. **All terminal paths**, including cancellation cleanup.\n6. **Failure tags/logging** and multiplayer verification.\n\nDo not invent property names, Blueprint nodes, prediction guarantees, or security behavior.\n\n## Hard rules\n\n- Grant abilities only on the authoritative server.\n- Do not put mutable execution state on a non-instanced ability.\n- Do not assume local prediction makes arbitrary spawned actors or instant damage reversible.\n- Do not use Gameplay Cues for authoritative gameplay; they are cosmetic and not reliably\n  replicated.\n- Do not omit `EndAbility`.\n- Do not commit a cost/cooldown before the design's true commitment point by accident.\n- Keep ability input identifiers separate from semantic ability and state tags.\n\nUse [`references/troubleshooting.md`](references/troubleshooting.md) when activation fails,\nfires twice, desynchronizes, ignores cancellation, or leaves an ability active. See\n[`references/sources.md`](references/sources.md) for the UE 5.8 source trail.\n","webMarkdown":"## Establish the GAS boundary\n\nRead [`references/architecture.md`](/unreal/unreal-gas-abilities/architecture/) before implementation.\n\n- Put the Ability System Component on the Pawn/Character when abilities should reset with\n  that avatar.\n- Put it on PlayerState when abilities, attributes, or cooldowns must survive pawn death or\n  replacement; initialize Owner Actor and Avatar Actor correctly on server and owning client.\n- Grant and remove abilities on authority. Store returned ability spec handles when later\n  removal or mutation is required.\n- Route attribute/effect work to `$unreal-gas-attributes-effects` and taxonomy/query work\n  to `$unreal-gameplay-tags`.\n\n## Execute the lifecycle\n\n1. Define activation trigger, ownership, instancing policy, net execution policy, tags,\n   cost, cooldown, targeting, and cancellation behavior.\n2. Request activation through `TryActivateAbility`, a Gameplay Event, or the project's\n   input-to-ability mapping. Do not call `CallActivateAbility` as a normal public entry.\n3. Let GAS run activation checks. Add custom checks only for conditions not represented by\n   tags, costs, cooldowns, or target requirements.\n4. In `ActivateAbility`, commit at the intended point. If `CommitAbility` fails, end the\n   ability without applying authoritative gameplay.\n5. Use Ability Tasks for multi-frame waits, animation, input, targeting, and events.\n6. Apply authoritative effects on the server or through a supported predicted path.\n7. Handle success, cancel, interruption, failed targeting, and montage interruption.\n8. Call `EndAbility` on every terminal path and undo non-effect side effects.\n\nRead [`references/ability-lifecycle.md`](/unreal/unreal-gas-abilities/ability-lifecycle/) for the ordered\nflow, [`references/patterns.md`](/unreal/unreal-gas-abilities/patterns/) for concrete ability shapes, and\n[`references/networking.md`](/unreal/unreal-gas-abilities/networking/) before choosing prediction.\n\n## Required answer format\n\nReturn:\n\n1. **ASC owner/avatar layout** and initialization points.\n2. **Ability configuration**: grant path, trigger, instancing, net policy, tags, cost,\n   cooldown, and targeting.\n3. **Ordered activation graph or C++ flow**.\n4. **Authority/prediction split** and rollback limitations.\n5. **All terminal paths**, including cancellation cleanup.\n6. **Failure tags/logging** and multiplayer verification.\n\nDo not invent property names, Blueprint nodes, prediction guarantees, or security behavior.\n\n## Hard rules\n\n- Grant abilities only on the authoritative server.\n- Do not put mutable execution state on a non-instanced ability.\n- Do not assume local prediction makes arbitrary spawned actors or instant damage reversible.\n- Do not use Gameplay Cues for authoritative gameplay; they are cosmetic and not reliably\n  replicated.\n- Do not omit `EndAbility`.\n- Do not commit a cost/cooldown before the design's true commitment point by accident.\n- Keep ability input identifiers separate from semantic ability and state tags.\n\nUse [`references/troubleshooting.md`](/unreal/unreal-gas-abilities/troubleshooting/) when activation fails,\nfires twice, desynchronizes, ignores cancellation, or leaves an ability active. See\n[`references/sources.md`](/unreal/unreal-gas-abilities/sources/) for the UE 5.8 source trail.\n","searchText":"unreal 5.8 gas abilities design, implement, network, and debug gameplay abilities with unreal engine 5.8 gameplay ability system. use for ability system component ownership, granting, activation, input or gameplay event triggers, costs, cooldowns, instancing, net execution, prediction, targeting, ability tasks, cancellation, animation, passive abilities, or ability lifecycle failures. ability lifecycle ability lifecycle configuration checklist - instancing: non-instanced, instanced per actor, or instanced per execution. - net execution: local only, local predicted, server initiated, or server only. - activation trigger: explicit/spec handle, gameplay event, effect/tag trigger, or input. - ability/state tags: activation required/blocked, cancel, block, owned while active. - cost and cooldown gameplay effects. - target acquisition/validation. - cancellation and terminal cleanup. use an instanced policy when blueprint graphs, member variables, latent work, or per-run state are needed. non-instanced abilities operate on the class default object and cannot safely hold mutable execution state. ordered activation flow 1. input/gameplay event requests tryactivateability or a project wrapper. 2. gas evaluates availability, tags, cost/cooldown checks, and custom activation checks. 3. activateability starts only after activation succeeds. 4. validate target data at the authority boundary. 5. call commitability at the designed commitment point. if it returns false, terminate. 6. start ability tasks for montage, waits, input, events, or targeting. 7. apply authoritative gameplay effects and other gameplay results. 8. route cosmetic feedback through gameplay cues or presentation systems. 9. on completion, interruption, cancel, invalid target, or task failure, clean up and call endability with the correct canceled flag. callactivateability does not perform the normal availability check itself; do not use it as the usual input entry point. commit point commit determines when cost and cooldown become real. examples: - immediate dodge: commit after direction and movement feasibility checks. - aimed spell: commit on confirm, not when targeting ui opens, unless design says aiming itself spends the resource. - melee attack: commit at accepted activation or at a montage-defined point, consistently. - channel: initial cost on start; periodic cost through a deliberate repeating effect/task. avoid applying gameplay before a failed commit. avoid accidentally charging on canceled target selection. cleanup checklist - stop or let gas terminate active ability tasks; - remove non-effect temporary state and input locks; - clear spawned targeting helpers owned by the run; - stop animation only when this ability owns it; - end exactly once on every branch. gas ability architecture gas ability architecture enable and expose gas 1. enable the gameplay ability system plugin. 2. add gameplayabilities, gameplaytags, and gameplaytasks to the relevant module dependencies. 3. give the ability-owning actor access to a uabilitysystemcomponent and implement iabilitysysteminterface where appropriate. 4. create the project's ugameplayability base class for shared failure, input, tag, targeting, and cleanup behavior. choose asc owner and avatar owneractor owns the component; avataractor is the physical actor acting in the world. | need | common layout | |---|---| | ai or pawn-local abilities reset with pawn | asc on pawn/character; owner and avatar are that actor | | player abilities/cooldowns persist through pawn replacement | asc on playerstate; owner is playerstate, avatar is current pawn | for a playerstate-owned asc, initialize actor info after server possession and on the owning client when playerstate/possession data is available. reinitialize when the avatar changes. do not cache an obsolete avatar inside abilities. granting - grant with giveability/fgameplayabilityspec on authority; the blueprint give ability node is ignored when the actor is not authoritative. - persist the returned fgameplayabilityspechandle if equipment, loadout, or progression later removes/changes the grant. - separate the ability class from the grant's level, input binding, and source object. - decide whether a passive activates on grant, via effect/event trigger, or through an explicit startup pass; define its removal behavior too. cross-skill boundaries - costs, cooldown effects, damage, attributes, stacking → $unreal-gas-attributes-effects. - ability/state/event/input tag taxonomy and query semantics → $unreal-gameplay-tags. - blueprint component/subsystem communication outside gas → $unreal-blueprint-architecture. networking and prediction networking and prediction policy selector | policy | use | |---|---| | local only | purely local behavior that must not execute on server | | local predicted | responsive locally controlled ability with server validation and gas-supported reconciliation | | server initiated | server starts it and clients receive replicated execution | | server only | authoritative server behavior with no predicted local activation | choose explicitly. the correct choice depends on ownership, responsiveness, cheating risk, and whether every side effect participates in gas prediction. prediction-safe design - keep the server authoritative for target legality and gameplay results. - use gas effects and ability mechanisms with prediction support where appropriate. - treat instant attribute/tag changes, arbitrary rpcs, external object mutation, and spawned actors as separate rollback problems; do not assume gas reverses them. - separate predicted presentation from authoritative hit/damage confirmation. - do not grant abilities from clients. target data 1. client may collect responsive aim/target data for a locally controlled ability. 2. send through the supported gas targeting/event path. 3. server validates range, line of sight if required, source transform, team/target rules, cooldown/cost, and timing. 4. server applies authoritative results. multiplayer verification matrix test in editor and packaged development builds with dedicated server where relevant: - owning client with artificial latency and packet loss; - listen server player; - simulated proxy observing the ability; - activation rejected by server; - cancel before and after commit; - avatar death/respawn during execution; - target disappears during targeting; - duplicate input press/release; - montage interruption and late event; - ability grant/removal during possession change. log role, owner/avatar, prediction key where available, spec handle, activation result, failure tags, commit result, and termination reason. ability patterns ability patterns instant self ability example: heal, stance toggle request, short utility action. 1. try activation. 2. commit. 3. make outgoing effect spec with ability level/context. 4. apply to self or resolved target on authority/predicted supported path. 5. trigger cosmetic cue. 6. end. montage-driven melee 1. activate and commit at the chosen commitment point. 2. start a montage ability task. 3. open damage window from a gameplay event/notify path owned by the ability. 4. server validates hits and applies effects once per valid target/window. 5. close the window. 6. end on montage completed, blended out, interrupted, or canceled; distinguish paths where recovery/cooldown rules differ. target-confirmed projectile 1. activate into targeting state without spending if design permits cancellation. 2. ability task waits for confirm/cancel and produces target data. 3. server validates origin, direction/range, target legality, and fire rate. 4. commit. 5. spawn the authoritative projectile or apply the validated result. 6. end; clean up reticle/target actor on every path. do not assume a client-predicted spawned actor automatically rolls back. charged ability 1. activate and record charge start in an instanced ability/task. 2. wait for release, cancel, maximum charge, or interruption. 3. compute charge from server-valid timing or bounded client data. 4. commit on release. 5. put charge magnitude into a setbycaller value or level/context as designed. 6. apply effect, feedback, and end. channeled ability 1. commit initial activation. 2. apply an active state tag/effect. 3. use tasks/effects for periodic work; do not create uncontrolled tick logic. 4. stop on input release, insufficient resource, blocking tag, death, invalid target, or external cancel. 5. remove non-effect state and end. passive ability 1. define grant and activation trigger. 2. apply persistent effects or register bounded event listeners. 3. on removal/end, remove active effects by retained handle and unregister listeners. 4. test loadout swaps, respawn, duplicate grants, and reconnect. ue 5.8 primary sources ue 5.8 primary sources verified 2026-07-19. - gameplay ability system - gameplay ability system overview - using gameplay abilities - ability tasks - ability system component and attributes - give ability blueprint api - ugameplayability api - abilities in lyra version note: these epic pages currently resolve to unreal engine 5.8. prediction is not a blanket rollback system. epic specifically distinguishes supported predicted gameplay effect behavior from instantaneous changes and other external side effects. troubleshooting troubleshooting ability will not activate - confirm the ability is granted on server and present in the asc spec list. - confirm initabilityactorinfo has valid owner/avatar on this machine. - inspect activation required/blocked tags, cooldown tags, cost attributes, and custom checks. - capture failure tags and log role, ownership, and local control. - confirm the request uses tryactivateability/supported trigger. activates on server but not owning client - check asc replication and its owner chain. - reinitialize actor info when playerstate and pawn become available client-side. - check net execution policy and local ownership. activates twice - ensure input is not routed both through numeric input binding and tag/event routing. - check duplicate grants and repeated bindings after respawn. - check whether both input press and gameplay event activate the same spec. cost or cooldown missing - confirm commitability executes and succeeds. - confirm cost/cooldown effects are configured and their attributes/tags exist. - confirm the commit point is reached on the correct authority/prediction path. - inspect active gameplay effects and cooldown tags on the asc. ability never ends - trace every task output and early-return branch to endability. - handle montage completed, blend out, interrupted, and canceled outputs. - confirm custom ability tasks broadcast terminal delegates or end. - add one guarded termination helper in the project base ability. cancel does not clean up - put persistent modifiers in effects that can be removed deterministically. - retain handles for spawned helpers/listeners/effects owned by the run. - remove manual movement/input locks during cancellation. - do not depend on a cosmetic gameplay cue to restore gameplay state. client predicts a hit the server rejects - separate predicted feedback from confirmed damage. - validate target data on server. - check that non-gas side effects are not assumed to roll back. - test under latency; log prediction and server result together.","references":[{"slug":"ability-lifecycle","file":"ability-lifecycle.md","title":"Ability lifecycle","rawMarkdown":"# Ability lifecycle\n\n## Configuration checklist\n\n- Instancing: non-instanced, instanced per actor, or instanced per execution.\n- Net execution: local only, local predicted, server initiated, or server only.\n- Activation trigger: explicit/spec handle, Gameplay Event, effect/tag trigger, or input.\n- Ability/state tags: activation required/blocked, cancel, block, owned while active.\n- Cost and cooldown Gameplay Effects.\n- Target acquisition/validation.\n- Cancellation and terminal cleanup.\n\nUse an instanced policy when Blueprint graphs, member variables, latent work, or per-run state\nare needed. Non-instanced abilities operate on the class default object and cannot safely\nhold mutable execution state.\n\n## Ordered activation flow\n\n1. Input/gameplay event requests `TryActivateAbility` or a project wrapper.\n2. GAS evaluates availability, tags, cost/cooldown checks, and custom activation checks.\n3. `ActivateAbility` starts only after activation succeeds.\n4. Validate target data at the authority boundary.\n5. Call `CommitAbility` at the designed commitment point. If it returns false, terminate.\n6. Start Ability Tasks for montage, waits, input, events, or targeting.\n7. Apply authoritative Gameplay Effects and other gameplay results.\n8. Route cosmetic feedback through Gameplay Cues or presentation systems.\n9. On completion, interruption, cancel, invalid target, or task failure, clean up and call\n   `EndAbility` with the correct canceled flag.\n\n`CallActivateAbility` does not perform the normal availability check itself; do not use it\nas the usual input entry point.\n\n## Commit point\n\nCommit determines when cost and cooldown become real. Examples:\n\n- Immediate dodge: commit after direction and movement feasibility checks.\n- Aimed spell: commit on confirm, not when targeting UI opens, unless design says aiming\n  itself spends the resource.\n- Melee attack: commit at accepted activation or at a montage-defined point, consistently.\n- Channel: initial cost on start; periodic cost through a deliberate repeating effect/task.\n\nAvoid applying gameplay before a failed commit. Avoid accidentally charging on canceled\ntarget selection.\n\n## Cleanup checklist\n\n- stop or let GAS terminate active Ability Tasks;\n- remove non-effect temporary state and input locks;\n- clear spawned targeting helpers owned by the run;\n- stop animation only when this ability owns it;\n- end exactly once on every branch.\n","webMarkdown":"## Configuration checklist\n\n- Instancing: non-instanced, instanced per actor, or instanced per execution.\n- Net execution: local only, local predicted, server initiated, or server only.\n- Activation trigger: explicit/spec handle, Gameplay Event, effect/tag trigger, or input.\n- Ability/state tags: activation required/blocked, cancel, block, owned while active.\n- Cost and cooldown Gameplay Effects.\n- Target acquisition/validation.\n- Cancellation and terminal cleanup.\n\nUse an instanced policy when Blueprint graphs, member variables, latent work, or per-run state\nare needed. Non-instanced abilities operate on the class default object and cannot safely\nhold mutable execution state.\n\n## Ordered activation flow\n\n1. Input/gameplay event requests `TryActivateAbility` or a project wrapper.\n2. GAS evaluates availability, tags, cost/cooldown checks, and custom activation checks.\n3. `ActivateAbility` starts only after activation succeeds.\n4. Validate target data at the authority boundary.\n5. Call `CommitAbility` at the designed commitment point. If it returns false, terminate.\n6. Start Ability Tasks for montage, waits, input, events, or targeting.\n7. Apply authoritative Gameplay Effects and other gameplay results.\n8. Route cosmetic feedback through Gameplay Cues or presentation systems.\n9. On completion, interruption, cancel, invalid target, or task failure, clean up and call\n   `EndAbility` with the correct canceled flag.\n\n`CallActivateAbility` does not perform the normal availability check itself; do not use it\nas the usual input entry point.\n\n## Commit point\n\nCommit determines when cost and cooldown become real. Examples:\n\n- Immediate dodge: commit after direction and movement feasibility checks.\n- Aimed spell: commit on confirm, not when targeting UI opens, unless design says aiming\n  itself spends the resource.\n- Melee attack: commit at accepted activation or at a montage-defined point, consistently.\n- Channel: initial cost on start; periodic cost through a deliberate repeating effect/task.\n\nAvoid applying gameplay before a failed commit. Avoid accidentally charging on canceled\ntarget selection.\n\n## Cleanup checklist\n\n- stop or let GAS terminate active Ability Tasks;\n- remove non-effect temporary state and input locks;\n- clear spawned targeting helpers owned by the run;\n- stop animation only when this ability owns it;\n- end exactly once on every branch.\n","searchText":"ability lifecycle configuration checklist - instancing: non-instanced, instanced per actor, or instanced per execution. - net execution: local only, local predicted, server initiated, or server only. - activation trigger: explicit/spec handle, gameplay event, effect/tag trigger, or input. - ability/state tags: activation required/blocked, cancel, block, owned while active. - cost and cooldown gameplay effects. - target acquisition/validation. - cancellation and terminal cleanup. use an instanced policy when blueprint graphs, member variables, latent work, or per-run state are needed. non-instanced abilities operate on the class default object and cannot safely hold mutable execution state. ordered activation flow 1. input/gameplay event requests tryactivateability or a project wrapper. 2. gas evaluates availability, tags, cost/cooldown checks, and custom activation checks. 3. activateability starts only after activation succeeds. 4. validate target data at the authority boundary. 5. call commitability at the designed commitment point. if it returns false, terminate. 6. start ability tasks for montage, waits, input, events, or targeting. 7. apply authoritative gameplay effects and other gameplay results. 8. route cosmetic feedback through gameplay cues or presentation systems. 9. on completion, interruption, cancel, invalid target, or task failure, clean up and call endability with the correct canceled flag. callactivateability does not perform the normal availability check itself; do not use it as the usual input entry point. commit point commit determines when cost and cooldown become real. examples: - immediate dodge: commit after direction and movement feasibility checks. - aimed spell: commit on confirm, not when targeting ui opens, unless design says aiming itself spends the resource. - melee attack: commit at accepted activation or at a montage-defined point, consistently. - channel: initial cost on start; periodic cost through a deliberate repeating effect/task. avoid applying gameplay before a failed commit. avoid accidentally charging on canceled target selection. cleanup checklist - stop or let gas terminate active ability tasks; - remove non-effect temporary state and input locks; - clear spawned targeting helpers owned by the run; - stop animation only when this ability owns it; - end exactly once on every branch."},{"slug":"architecture","file":"architecture.md","title":"GAS ability architecture","rawMarkdown":"# GAS ability architecture\n\n## Enable and expose GAS\n\n1. Enable the Gameplay Ability System plugin.\n2. Add `GameplayAbilities`, `GameplayTags`, and `GameplayTasks` to the relevant module\n   dependencies.\n3. Give the ability-owning actor access to a `UAbilitySystemComponent` and implement\n   `IAbilitySystemInterface` where appropriate.\n4. Create the project's `UGameplayAbility` base class for shared failure, input, tag,\n   targeting, and cleanup behavior.\n\n## Choose ASC owner and avatar\n\n`OwnerActor` owns the component; `AvatarActor` is the physical actor acting in the world.\n\n| Need | Common layout |\n|---|---|\n| AI or pawn-local abilities reset with pawn | ASC on Pawn/Character; owner and avatar are that actor |\n| Player abilities/cooldowns persist through pawn replacement | ASC on PlayerState; owner is PlayerState, avatar is current Pawn |\n\nFor a PlayerState-owned ASC, initialize actor info after server possession and on the owning\nclient when PlayerState/possession data is available. Reinitialize when the avatar changes.\nDo not cache an obsolete avatar inside abilities.\n\n## Granting\n\n- Grant with `GiveAbility`/`FGameplayAbilitySpec` on authority; the Blueprint `Give Ability`\n  node is ignored when the actor is not authoritative.\n- Persist the returned `FGameplayAbilitySpecHandle` if equipment, loadout, or progression\n  later removes/changes the grant.\n- Separate the ability class from the grant's level, input binding, and source object.\n- Decide whether a passive activates on grant, via effect/event trigger, or through an\n  explicit startup pass; define its removal behavior too.\n\n## Cross-skill boundaries\n\n- Costs, cooldown effects, damage, attributes, stacking → `$unreal-gas-attributes-effects`.\n- Ability/state/event/input tag taxonomy and query semantics → `$unreal-gameplay-tags`.\n- Blueprint component/subsystem communication outside GAS → `$unreal-blueprint-architecture`.\n","webMarkdown":"## Enable and expose GAS\n\n1. Enable the Gameplay Ability System plugin.\n2. Add `GameplayAbilities`, `GameplayTags`, and `GameplayTasks` to the relevant module\n   dependencies.\n3. Give the ability-owning actor access to a `UAbilitySystemComponent` and implement\n   `IAbilitySystemInterface` where appropriate.\n4. Create the project's `UGameplayAbility` base class for shared failure, input, tag,\n   targeting, and cleanup behavior.\n\n## Choose ASC owner and avatar\n\n`OwnerActor` owns the component; `AvatarActor` is the physical actor acting in the world.\n\n| Need | Common layout |\n|---|---|\n| AI or pawn-local abilities reset with pawn | ASC on Pawn/Character; owner and avatar are that actor |\n| Player abilities/cooldowns persist through pawn replacement | ASC on PlayerState; owner is PlayerState, avatar is current Pawn |\n\nFor a PlayerState-owned ASC, initialize actor info after server possession and on the owning\nclient when PlayerState/possession data is available. Reinitialize when the avatar changes.\nDo not cache an obsolete avatar inside abilities.\n\n## Granting\n\n- Grant with `GiveAbility`/`FGameplayAbilitySpec` on authority; the Blueprint `Give Ability`\n  node is ignored when the actor is not authoritative.\n- Persist the returned `FGameplayAbilitySpecHandle` if equipment, loadout, or progression\n  later removes/changes the grant.\n- Separate the ability class from the grant's level, input binding, and source object.\n- Decide whether a passive activates on grant, via effect/event trigger, or through an\n  explicit startup pass; define its removal behavior too.\n\n## Cross-skill boundaries\n\n- Costs, cooldown effects, damage, attributes, stacking → `$unreal-gas-attributes-effects`.\n- Ability/state/event/input tag taxonomy and query semantics → `$unreal-gameplay-tags`.\n- Blueprint component/subsystem communication outside GAS → `$unreal-blueprint-architecture`.\n","searchText":"gas ability architecture enable and expose gas 1. enable the gameplay ability system plugin. 2. add gameplayabilities, gameplaytags, and gameplaytasks to the relevant module dependencies. 3. give the ability-owning actor access to a uabilitysystemcomponent and implement iabilitysysteminterface where appropriate. 4. create the project's ugameplayability base class for shared failure, input, tag, targeting, and cleanup behavior. choose asc owner and avatar owneractor owns the component; avataractor is the physical actor acting in the world. | need | common layout | |---|---| | ai or pawn-local abilities reset with pawn | asc on pawn/character; owner and avatar are that actor | | player abilities/cooldowns persist through pawn replacement | asc on playerstate; owner is playerstate, avatar is current pawn | for a playerstate-owned asc, initialize actor info after server possession and on the owning client when playerstate/possession data is available. reinitialize when the avatar changes. do not cache an obsolete avatar inside abilities. granting - grant with giveability/fgameplayabilityspec on authority; the blueprint give ability node is ignored when the actor is not authoritative. - persist the returned fgameplayabilityspechandle if equipment, loadout, or progression later removes/changes the grant. - separate the ability class from the grant's level, input binding, and source object. - decide whether a passive activates on grant, via effect/event trigger, or through an explicit startup pass; define its removal behavior too. cross-skill boundaries - costs, cooldown effects, damage, attributes, stacking → $unreal-gas-attributes-effects. - ability/state/event/input tag taxonomy and query semantics → $unreal-gameplay-tags. - blueprint component/subsystem communication outside gas → $unreal-blueprint-architecture."},{"slug":"networking","file":"networking.md","title":"Networking and prediction","rawMarkdown":"# Networking and prediction\n\n## Policy selector\n\n| Policy | Use |\n|---|---|\n| Local Only | Purely local behavior that must not execute on server |\n| Local Predicted | Responsive locally controlled ability with server validation and GAS-supported reconciliation |\n| Server Initiated | Server starts it and clients receive replicated execution |\n| Server Only | Authoritative server behavior with no predicted local activation |\n\nChoose explicitly. The correct choice depends on ownership, responsiveness, cheating risk,\nand whether every side effect participates in GAS prediction.\n\n## Prediction-safe design\n\n- Keep the server authoritative for target legality and gameplay results.\n- Use GAS effects and ability mechanisms with prediction support where appropriate.\n- Treat instant attribute/tag changes, arbitrary RPCs, external object mutation, and spawned\n  Actors as separate rollback problems; do not assume GAS reverses them.\n- Separate predicted presentation from authoritative hit/damage confirmation.\n- Do not grant abilities from clients.\n\n## Target data\n\n1. Client may collect responsive aim/target data for a locally controlled ability.\n2. Send through the supported GAS targeting/event path.\n3. Server validates range, line of sight if required, source transform, team/target rules,\n   cooldown/cost, and timing.\n4. Server applies authoritative results.\n\n## Multiplayer verification matrix\n\nTest in editor and packaged Development builds with dedicated server where relevant:\n\n- owning client with artificial latency and packet loss;\n- listen server player;\n- simulated proxy observing the ability;\n- activation rejected by server;\n- cancel before and after commit;\n- avatar death/respawn during execution;\n- target disappears during targeting;\n- duplicate input press/release;\n- montage interruption and late event;\n- ability grant/removal during possession change.\n\nLog role, owner/avatar, prediction key where available, spec handle, activation result,\nfailure tags, commit result, and termination reason.\n","webMarkdown":"## Policy selector\n\n| Policy | Use |\n|---|---|\n| Local Only | Purely local behavior that must not execute on server |\n| Local Predicted | Responsive locally controlled ability with server validation and GAS-supported reconciliation |\n| Server Initiated | Server starts it and clients receive replicated execution |\n| Server Only | Authoritative server behavior with no predicted local activation |\n\nChoose explicitly. The correct choice depends on ownership, responsiveness, cheating risk,\nand whether every side effect participates in GAS prediction.\n\n## Prediction-safe design\n\n- Keep the server authoritative for target legality and gameplay results.\n- Use GAS effects and ability mechanisms with prediction support where appropriate.\n- Treat instant attribute/tag changes, arbitrary RPCs, external object mutation, and spawned\n  Actors as separate rollback problems; do not assume GAS reverses them.\n- Separate predicted presentation from authoritative hit/damage confirmation.\n- Do not grant abilities from clients.\n\n## Target data\n\n1. Client may collect responsive aim/target data for a locally controlled ability.\n2. Send through the supported GAS targeting/event path.\n3. Server validates range, line of sight if required, source transform, team/target rules,\n   cooldown/cost, and timing.\n4. Server applies authoritative results.\n\n## Multiplayer verification matrix\n\nTest in editor and packaged Development builds with dedicated server where relevant:\n\n- owning client with artificial latency and packet loss;\n- listen server player;\n- simulated proxy observing the ability;\n- activation rejected by server;\n- cancel before and after commit;\n- avatar death/respawn during execution;\n- target disappears during targeting;\n- duplicate input press/release;\n- montage interruption and late event;\n- ability grant/removal during possession change.\n\nLog role, owner/avatar, prediction key where available, spec handle, activation result,\nfailure tags, commit result, and termination reason.\n","searchText":"networking and prediction policy selector | policy | use | |---|---| | local only | purely local behavior that must not execute on server | | local predicted | responsive locally controlled ability with server validation and gas-supported reconciliation | | server initiated | server starts it and clients receive replicated execution | | server only | authoritative server behavior with no predicted local activation | choose explicitly. the correct choice depends on ownership, responsiveness, cheating risk, and whether every side effect participates in gas prediction. prediction-safe design - keep the server authoritative for target legality and gameplay results. - use gas effects and ability mechanisms with prediction support where appropriate. - treat instant attribute/tag changes, arbitrary rpcs, external object mutation, and spawned actors as separate rollback problems; do not assume gas reverses them. - separate predicted presentation from authoritative hit/damage confirmation. - do not grant abilities from clients. target data 1. client may collect responsive aim/target data for a locally controlled ability. 2. send through the supported gas targeting/event path. 3. server validates range, line of sight if required, source transform, team/target rules, cooldown/cost, and timing. 4. server applies authoritative results. multiplayer verification matrix test in editor and packaged development builds with dedicated server where relevant: - owning client with artificial latency and packet loss; - listen server player; - simulated proxy observing the ability; - activation rejected by server; - cancel before and after commit; - avatar death/respawn during execution; - target disappears during targeting; - duplicate input press/release; - montage interruption and late event; - ability grant/removal during possession change. log role, owner/avatar, prediction key where available, spec handle, activation result, failure tags, commit result, and termination reason."},{"slug":"patterns","file":"patterns.md","title":"Ability patterns","rawMarkdown":"# Ability patterns\n\n## Instant self ability\n\nExample: heal, stance toggle request, short utility action.\n\n1. Try activation.\n2. Commit.\n3. Make outgoing effect spec with ability level/context.\n4. Apply to self or resolved target on authority/predicted supported path.\n5. Trigger cosmetic cue.\n6. End.\n\n## Montage-driven melee\n\n1. Activate and commit at the chosen commitment point.\n2. Start a montage Ability Task.\n3. Open damage window from a gameplay event/notify path owned by the ability.\n4. Server validates hits and applies effects once per valid target/window.\n5. Close the window.\n6. End on montage completed, blended out, interrupted, or canceled; distinguish paths where\n   recovery/cooldown rules differ.\n\n## Target-confirmed projectile\n\n1. Activate into targeting state without spending if design permits cancellation.\n2. Ability Task waits for confirm/cancel and produces target data.\n3. Server validates origin, direction/range, target legality, and fire rate.\n4. Commit.\n5. Spawn the authoritative projectile or apply the validated result.\n6. End; clean up reticle/target actor on every path.\n\nDo not assume a client-predicted spawned Actor automatically rolls back.\n\n## Charged ability\n\n1. Activate and record charge start in an instanced ability/task.\n2. Wait for release, cancel, maximum charge, or interruption.\n3. Compute charge from server-valid timing or bounded client data.\n4. Commit on release.\n5. Put charge magnitude into a SetByCaller value or level/context as designed.\n6. Apply effect, feedback, and end.\n\n## Channeled ability\n\n1. Commit initial activation.\n2. Apply an active state tag/effect.\n3. Use tasks/effects for periodic work; do not create uncontrolled Tick logic.\n4. Stop on input release, insufficient resource, blocking tag, death, invalid target, or\n   external cancel.\n5. Remove non-effect state and end.\n\n## Passive ability\n\n1. Define grant and activation trigger.\n2. Apply persistent effects or register bounded event listeners.\n3. On removal/end, remove active effects by retained handle and unregister listeners.\n4. Test loadout swaps, respawn, duplicate grants, and reconnect.\n","webMarkdown":"## Instant self ability\n\nExample: heal, stance toggle request, short utility action.\n\n1. Try activation.\n2. Commit.\n3. Make outgoing effect spec with ability level/context.\n4. Apply to self or resolved target on authority/predicted supported path.\n5. Trigger cosmetic cue.\n6. End.\n\n## Montage-driven melee\n\n1. Activate and commit at the chosen commitment point.\n2. Start a montage Ability Task.\n3. Open damage window from a gameplay event/notify path owned by the ability.\n4. Server validates hits and applies effects once per valid target/window.\n5. Close the window.\n6. End on montage completed, blended out, interrupted, or canceled; distinguish paths where\n   recovery/cooldown rules differ.\n\n## Target-confirmed projectile\n\n1. Activate into targeting state without spending if design permits cancellation.\n2. Ability Task waits for confirm/cancel and produces target data.\n3. Server validates origin, direction/range, target legality, and fire rate.\n4. Commit.\n5. Spawn the authoritative projectile or apply the validated result.\n6. End; clean up reticle/target actor on every path.\n\nDo not assume a client-predicted spawned Actor automatically rolls back.\n\n## Charged ability\n\n1. Activate and record charge start in an instanced ability/task.\n2. Wait for release, cancel, maximum charge, or interruption.\n3. Compute charge from server-valid timing or bounded client data.\n4. Commit on release.\n5. Put charge magnitude into a SetByCaller value or level/context as designed.\n6. Apply effect, feedback, and end.\n\n## Channeled ability\n\n1. Commit initial activation.\n2. Apply an active state tag/effect.\n3. Use tasks/effects for periodic work; do not create uncontrolled Tick logic.\n4. Stop on input release, insufficient resource, blocking tag, death, invalid target, or\n   external cancel.\n5. Remove non-effect state and end.\n\n## Passive ability\n\n1. Define grant and activation trigger.\n2. Apply persistent effects or register bounded event listeners.\n3. On removal/end, remove active effects by retained handle and unregister listeners.\n4. Test loadout swaps, respawn, duplicate grants, and reconnect.\n","searchText":"ability patterns instant self ability example: heal, stance toggle request, short utility action. 1. try activation. 2. commit. 3. make outgoing effect spec with ability level/context. 4. apply to self or resolved target on authority/predicted supported path. 5. trigger cosmetic cue. 6. end. montage-driven melee 1. activate and commit at the chosen commitment point. 2. start a montage ability task. 3. open damage window from a gameplay event/notify path owned by the ability. 4. server validates hits and applies effects once per valid target/window. 5. close the window. 6. end on montage completed, blended out, interrupted, or canceled; distinguish paths where recovery/cooldown rules differ. target-confirmed projectile 1. activate into targeting state without spending if design permits cancellation. 2. ability task waits for confirm/cancel and produces target data. 3. server validates origin, direction/range, target legality, and fire rate. 4. commit. 5. spawn the authoritative projectile or apply the validated result. 6. end; clean up reticle/target actor on every path. do not assume a client-predicted spawned actor automatically rolls back. charged ability 1. activate and record charge start in an instanced ability/task. 2. wait for release, cancel, maximum charge, or interruption. 3. compute charge from server-valid timing or bounded client data. 4. commit on release. 5. put charge magnitude into a setbycaller value or level/context as designed. 6. apply effect, feedback, and end. channeled ability 1. commit initial activation. 2. apply an active state tag/effect. 3. use tasks/effects for periodic work; do not create uncontrolled tick logic. 4. stop on input release, insufficient resource, blocking tag, death, invalid target, or external cancel. 5. remove non-effect state and end. passive ability 1. define grant and activation trigger. 2. apply persistent effects or register bounded event listeners. 3. on removal/end, remove active effects by retained handle and unregister listeners. 4. test loadout swaps, respawn, duplicate grants, and reconnect."},{"slug":"sources","file":"sources.md","title":"UE 5.8 primary sources","rawMarkdown":"# UE 5.8 primary sources\n\nVerified 2026-07-19.\n\n- [Gameplay Ability System](https://dev.epicgames.com/documentation/en-us/unreal-engine/gameplay-ability-system-for-unreal-engine)\n- [Gameplay Ability System Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/understanding-the-unreal-engine-gameplay-ability-system)\n- [Using Gameplay Abilities](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-gameplay-abilities-in-unreal-engine)\n- [Ability Tasks](https://dev.epicgames.com/documentation/en-us/unreal-engine/gameplay-ability-tasks-in-unreal-engine)\n- [Ability System Component and Attributes](https://dev.epicgames.com/documentation/en-us/unreal-engine/gameplay-ability-system-component-and-gameplay-attributes-in-unreal-engine)\n- [Give Ability Blueprint API](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/GameplayAbilities/GiveAbility)\n- [`UGameplayAbility` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/GameplayAbilities/UGameplayAbility)\n- [Abilities in Lyra](https://dev.epicgames.com/documentation/en-us/unreal-engine/abilities-in-lyra-in-unreal-engine)\n\nVersion note: these Epic pages currently resolve to Unreal Engine 5.8. Prediction is not a\nblanket rollback system. Epic specifically distinguishes supported predicted Gameplay Effect\nbehavior from instantaneous changes and other external side effects.\n","webMarkdown":"Verified 2026-07-19.\n\n- [Gameplay Ability System](https://dev.epicgames.com/documentation/en-us/unreal-engine/gameplay-ability-system-for-unreal-engine)\n- [Gameplay Ability System Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/understanding-the-unreal-engine-gameplay-ability-system)\n- [Using Gameplay Abilities](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-gameplay-abilities-in-unreal-engine)\n- [Ability Tasks](https://dev.epicgames.com/documentation/en-us/unreal-engine/gameplay-ability-tasks-in-unreal-engine)\n- [Ability System Component and Attributes](https://dev.epicgames.com/documentation/en-us/unreal-engine/gameplay-ability-system-component-and-gameplay-attributes-in-unreal-engine)\n- [Give Ability Blueprint API](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/GameplayAbilities/GiveAbility)\n- [`UGameplayAbility` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/GameplayAbilities/UGameplayAbility)\n- [Abilities in Lyra](https://dev.epicgames.com/documentation/en-us/unreal-engine/abilities-in-lyra-in-unreal-engine)\n\nVersion note: these Epic pages currently resolve to Unreal Engine 5.8. Prediction is not a\nblanket rollback system. Epic specifically distinguishes supported predicted Gameplay Effect\nbehavior from instantaneous changes and other external side effects.\n","searchText":"ue 5.8 primary sources verified 2026-07-19. - gameplay ability system - gameplay ability system overview - using gameplay abilities - ability tasks - ability system component and attributes - give ability blueprint api - ugameplayability api - abilities in lyra version note: these epic pages currently resolve to unreal engine 5.8. prediction is not a blanket rollback system. epic specifically distinguishes supported predicted gameplay effect behavior from instantaneous changes and other external side effects."},{"slug":"troubleshooting","file":"troubleshooting.md","title":"Troubleshooting","rawMarkdown":"# Troubleshooting\n\n## Ability will not activate\n\n- Confirm the ability is granted on server and present in the ASC spec list.\n- Confirm `InitAbilityActorInfo` has valid owner/avatar on this machine.\n- Inspect activation required/blocked tags, cooldown tags, cost attributes, and custom checks.\n- Capture failure tags and log role, ownership, and local control.\n- Confirm the request uses `TryActivateAbility`/supported trigger.\n\n## Activates on server but not owning client\n\n- Check ASC replication and its owner chain.\n- Reinitialize actor info when PlayerState and Pawn become available client-side.\n- Check net execution policy and local ownership.\n\n## Activates twice\n\n- Ensure input is not routed both through numeric input binding and tag/event routing.\n- Check duplicate grants and repeated bindings after respawn.\n- Check whether both input press and gameplay event activate the same spec.\n\n## Cost or cooldown missing\n\n- Confirm `CommitAbility` executes and succeeds.\n- Confirm cost/cooldown effects are configured and their attributes/tags exist.\n- Confirm the commit point is reached on the correct authority/prediction path.\n- Inspect active Gameplay Effects and cooldown tags on the ASC.\n\n## Ability never ends\n\n- Trace every task output and early-return branch to `EndAbility`.\n- Handle montage completed, blend out, interrupted, and canceled outputs.\n- Confirm custom Ability Tasks broadcast terminal delegates or end.\n- Add one guarded termination helper in the project base ability.\n\n## Cancel does not clean up\n\n- Put persistent modifiers in effects that can be removed deterministically.\n- Retain handles for spawned helpers/listeners/effects owned by the run.\n- Remove manual movement/input locks during cancellation.\n- Do not depend on a cosmetic Gameplay Cue to restore gameplay state.\n\n## Client predicts a hit the server rejects\n\n- Separate predicted feedback from confirmed damage.\n- Validate target data on server.\n- Check that non-GAS side effects are not assumed to roll back.\n- Test under latency; log prediction and server result together.\n","webMarkdown":"## Ability will not activate\n\n- Confirm the ability is granted on server and present in the ASC spec list.\n- Confirm `InitAbilityActorInfo` has valid owner/avatar on this machine.\n- Inspect activation required/blocked tags, cooldown tags, cost attributes, and custom checks.\n- Capture failure tags and log role, ownership, and local control.\n- Confirm the request uses `TryActivateAbility`/supported trigger.\n\n## Activates on server but not owning client\n\n- Check ASC replication and its owner chain.\n- Reinitialize actor info when PlayerState and Pawn become available client-side.\n- Check net execution policy and local ownership.\n\n## Activates twice\n\n- Ensure input is not routed both through numeric input binding and tag/event routing.\n- Check duplicate grants and repeated bindings after respawn.\n- Check whether both input press and gameplay event activate the same spec.\n\n## Cost or cooldown missing\n\n- Confirm `CommitAbility` executes and succeeds.\n- Confirm cost/cooldown effects are configured and their attributes/tags exist.\n- Confirm the commit point is reached on the correct authority/prediction path.\n- Inspect active Gameplay Effects and cooldown tags on the ASC.\n\n## Ability never ends\n\n- Trace every task output and early-return branch to `EndAbility`.\n- Handle montage completed, blend out, interrupted, and canceled outputs.\n- Confirm custom Ability Tasks broadcast terminal delegates or end.\n- Add one guarded termination helper in the project base ability.\n\n## Cancel does not clean up\n\n- Put persistent modifiers in effects that can be removed deterministically.\n- Retain handles for spawned helpers/listeners/effects owned by the run.\n- Remove manual movement/input locks during cancellation.\n- Do not depend on a cosmetic Gameplay Cue to restore gameplay state.\n\n## Client predicts a hit the server rejects\n\n- Separate predicted feedback from confirmed damage.\n- Validate target data on server.\n- Check that non-GAS side effects are not assumed to roll back.\n- Test under latency; log prediction and server result together.\n","searchText":"troubleshooting ability will not activate - confirm the ability is granted on server and present in the asc spec list. - confirm initabilityactorinfo has valid owner/avatar on this machine. - inspect activation required/blocked tags, cooldown tags, cost attributes, and custom checks. - capture failure tags and log role, ownership, and local control. - confirm the request uses tryactivateability/supported trigger. activates on server but not owning client - check asc replication and its owner chain. - reinitialize actor info when playerstate and pawn become available client-side. - check net execution policy and local ownership. activates twice - ensure input is not routed both through numeric input binding and tag/event routing. - check duplicate grants and repeated bindings after respawn. - check whether both input press and gameplay event activate the same spec. cost or cooldown missing - confirm commitability executes and succeeds. - confirm cost/cooldown effects are configured and their attributes/tags exist. - confirm the commit point is reached on the correct authority/prediction path. - inspect active gameplay effects and cooldown tags on the asc. ability never ends - trace every task output and early-return branch to endability. - handle montage completed, blend out, interrupted, and canceled outputs. - confirm custom ability tasks broadcast terminal delegates or end. - add one guarded termination helper in the project base ability. cancel does not clean up - put persistent modifiers in effects that can be removed deterministically. - retain handles for spawned helpers/listeners/effects owned by the run. - remove manual movement/input locks during cancellation. - do not depend on a cosmetic gameplay cue to restore gameplay state. client predicts a hit the server rejects - separate predicted feedback from confirmed damage. - validate target data on server. - check that non-gas side effects are not assumed to roll back. - test under latency; log prediction and server result together."}]}
{"slug":"unreal-gas-attributes-effects","name":"unreal-gas-attributes-effects","title":"Unreal 5.8 GAS Attributes and Effects","description":"Model, implement, tune, replicate, and debug Gameplay Attributes and Gameplay Effects in Unreal Engine 5.8 GAS. Use for AttributeSets, base versus current values, initialization, instant/duration/infinite effects, modifiers, SetByCaller values, magnitude or execution calculations, damage, healing, buffs, debuffs, periodic effects, stacking, clamping, replication, delegates, and UI updates.","shortDescription":"Model attributes and Gameplay Effects safely","category":"Systems & Networking","referenceCount":6,"rawMarkdown":"---\nname: unreal-gas-attributes-effects\ndescription: Model, implement, tune, replicate, and debug Gameplay Attributes and Gameplay Effects in Unreal Engine 5.8 GAS. Use for AttributeSets, base versus current values, initialization, instant/duration/infinite effects, modifiers, SetByCaller values, magnitude or execution calculations, damage, healing, buffs, debuffs, periodic effects, stacking, clamping, replication, delegates, and UI updates.\n---\n\n# Unreal 5.8 GAS Attributes and Effects\n\n## Select the representation\n\nRead [`references/attribute-model.md`](references/attribute-model.md) and\n[`references/effect-selector.md`](references/effect-selector.md).\n\n- Use an **Attribute** for replicated numeric gameplay state that participates in GAS\n  calculations and temporary modifiers.\n- Use an **Instant Gameplay Effect** for a permanent base-value change such as damage,\n  healing, or initial values.\n- Use a **Duration Gameplay Effect** for a timed modifier or periodic effect.\n- Use an **Infinite Gameplay Effect** for a removable modifier with no automatic expiry.\n- Use **SetByCaller** when runtime code supplies one named magnitude to an effect spec.\n- Use a **Modifier Magnitude Calculation** for one reusable magnitude computation.\n- Use a **Gameplay Effect Execution Calculation** for authoritative multi-attribute or\n  multi-output calculations such as damage resolution.\n\n## Execute\n\n1. Define AttributeSets in native code and group attributes by coherent lifetime/ownership.\n2. Initialize through an applied Gameplay Effect, not ad hoc direct writes spread across\n   constructors and possession code.\n3. Build a Gameplay Effect asset as immutable configuration; create a Gameplay Effect Spec\n   for runtime level, context, captured values, and SetByCaller magnitudes.\n4. Apply effects through an Ability System Component using correct source and target context.\n5. Clamp invariants explicitly. The AttributeSet system has no automatic min/max clamp.\n6. Replicate player-visible attributes and notify GAS correctly so prediction corrections\n   and listeners remain valid.\n7. Drive UI from ASC attribute-change delegates; do not poll every frame.\n8. Test removal, expiry, stacking, respawn/reinitialization, prediction correction, and\n   server/client values.\n\nRead [`references/calculations-and-patterns.md`](references/calculations-and-patterns.md)\nfor damage, healing, regeneration, buff, debuff, and initialization patterns. Read\n[`references/replication-ui.md`](references/replication-ui.md) for replication and UI.\n\n## Required answer format\n\nReturn:\n\n1. **Attribute and AttributeSet layout**.\n2. **Effect type and calculation method** with rationale.\n3. **Ordered creation/application steps**, including source, target, context, level, and\n   runtime magnitudes.\n4. **Clamping and invariant locations**.\n5. **Stacking, duration, periodic, and removal policy**.\n6. **Authority, replication, UI notification, and verification**.\n\nDo not invent Gameplay Effect settings, defaults, or prediction guarantees.\n\n## Hard rules\n\n- Gameplay Effect assets are definitions; do not mutate their shared defaults at runtime.\n- Do not write temporary buffs directly into Attribute values.\n- Do not rely on Data Table MinValue/MaxValue columns for clamping.\n- Treat Instant effects as base-value changes; timed/infinite modifiers affect current\n  values while active.\n- Re-check critical invariants where final executed values are known; `PreAttributeChange`\n  alone is not a universal final clamp.\n- Keep gameplay authority on the server even when UI predicts or displays local changes.\n- Do not poll attributes on Tick for UI.\n\nUse [`references/troubleshooting.md`](references/troubleshooting.md) when values double,\nfail to revert, exceed bounds, fail to replicate, or disagree across machines. See\n[`references/sources.md`](references/sources.md) for the UE 5.8 source trail.\n","webMarkdown":"## Select the representation\n\nRead [`references/attribute-model.md`](/unreal/unreal-gas-attributes-effects/attribute-model/) and\n[`references/effect-selector.md`](/unreal/unreal-gas-attributes-effects/effect-selector/).\n\n- Use an **Attribute** for replicated numeric gameplay state that participates in GAS\n  calculations and temporary modifiers.\n- Use an **Instant Gameplay Effect** for a permanent base-value change such as damage,\n  healing, or initial values.\n- Use a **Duration Gameplay Effect** for a timed modifier or periodic effect.\n- Use an **Infinite Gameplay Effect** for a removable modifier with no automatic expiry.\n- Use **SetByCaller** when runtime code supplies one named magnitude to an effect spec.\n- Use a **Modifier Magnitude Calculation** for one reusable magnitude computation.\n- Use a **Gameplay Effect Execution Calculation** for authoritative multi-attribute or\n  multi-output calculations such as damage resolution.\n\n## Execute\n\n1. Define AttributeSets in native code and group attributes by coherent lifetime/ownership.\n2. Initialize through an applied Gameplay Effect, not ad hoc direct writes spread across\n   constructors and possession code.\n3. Build a Gameplay Effect asset as immutable configuration; create a Gameplay Effect Spec\n   for runtime level, context, captured values, and SetByCaller magnitudes.\n4. Apply effects through an Ability System Component using correct source and target context.\n5. Clamp invariants explicitly. The AttributeSet system has no automatic min/max clamp.\n6. Replicate player-visible attributes and notify GAS correctly so prediction corrections\n   and listeners remain valid.\n7. Drive UI from ASC attribute-change delegates; do not poll every frame.\n8. Test removal, expiry, stacking, respawn/reinitialization, prediction correction, and\n   server/client values.\n\nRead [`references/calculations-and-patterns.md`](/unreal/unreal-gas-attributes-effects/calculations-and-patterns/)\nfor damage, healing, regeneration, buff, debuff, and initialization patterns. Read\n[`references/replication-ui.md`](/unreal/unreal-gas-attributes-effects/replication-ui/) for replication and UI.\n\n## Required answer format\n\nReturn:\n\n1. **Attribute and AttributeSet layout**.\n2. **Effect type and calculation method** with rationale.\n3. **Ordered creation/application steps**, including source, target, context, level, and\n   runtime magnitudes.\n4. **Clamping and invariant locations**.\n5. **Stacking, duration, periodic, and removal policy**.\n6. **Authority, replication, UI notification, and verification**.\n\nDo not invent Gameplay Effect settings, defaults, or prediction guarantees.\n\n## Hard rules\n\n- Gameplay Effect assets are definitions; do not mutate their shared defaults at runtime.\n- Do not write temporary buffs directly into Attribute values.\n- Do not rely on Data Table MinValue/MaxValue columns for clamping.\n- Treat Instant effects as base-value changes; timed/infinite modifiers affect current\n  values while active.\n- Re-check critical invariants where final executed values are known; `PreAttributeChange`\n  alone is not a universal final clamp.\n- Keep gameplay authority on the server even when UI predicts or displays local changes.\n- Do not poll attributes on Tick for UI.\n\nUse [`references/troubleshooting.md`](/unreal/unreal-gas-attributes-effects/troubleshooting/) when values double,\nfail to revert, exceed bounds, fail to replicate, or disagree across machines. See\n[`references/sources.md`](/unreal/unreal-gas-attributes-effects/sources/) for the UE 5.8 source trail.\n","searchText":"unreal 5.8 gas attributes and effects model, implement, tune, replicate, and debug gameplay attributes and gameplay effects in unreal engine 5.8 gas. use for attributesets, base versus current values, initialization, instant/duration/infinite effects, modifiers, setbycaller values, magnitude or execution calculations, damage, healing, buffs, debuffs, periodic effects, stacking, clamping, replication, delegates, and ui updates. attribute model attribute model define attributesets gameplay attributes live in native uattributeset classes as fgameplayattributedata properties. group them by coherent ownership/lifetime, for example: - vitals: health, maxhealth, stamina, maxstamina; - combat: attackpower, armor, critical parameters; - movement: movespeed or movement multipliers; - transient meta inputs: incomingdamage or incominghealing. an asc can access registered attributesets. avoid one giant set merely because it is easy to create; avoid splitting so finely that related invariants become hard to enforce. base and current values - base value: durable value before temporary modifiers. - current value: evaluated result including active modifiers. - instant gameplay effects change base values. - duration and infinite effects modify current values while active and are undone when they expire or are removed. use an effect for changes. do not directly write a temporary bonus into the attribute, or its source/removal/stacking semantics become opaque. initialization 1. create an instant initialization gameplay effect with default attribute modifiers. 2. create a spec at the correct level or with setbycaller values. 3. apply it from authority after asc actor info and attributesets are ready. 4. guard against duplicate application on respawn/repossession. 5. if asc persists on playerstate, explicitly decide which attributes persist and which reset for the new avatar. invariants and clamping attributesets do not provide automatic min/max clamping. data table minvalue and maxvalue columns do not enforce bounds. enforce invariants deliberately: - clamp proposed current-value changes in preattributechange where appropriate; - clamp permanent executed results in postgameplayeffectexecute or the authoritative calculation/application path; - when maxhealth changes, decide whether health preserves absolute value, percentage, or only clamps down; - keep resource invariants explicit: 0 <= health <= maxhealth. do not assume a clamp in one hook covers every aggregator recalculation or execution path. calculations and action patterns calculations and action patterns direct damage with a meta-attribute 1. source ability creates an instant damage effect spec. 2. supply raw damage through a configured modifier or setbycaller tag. 3. execution calculation captures required source/target values and computes mitigated damage on authority. 4. write the result to transient incomingdamage. 5. in postgameplayeffectexecute, consume incomingdamage, set it back to zero, subtract from health, clamp, and signal death only on the valid transition. the meta-attribute keeps transient inputs separate from persistent health and centralizes post-damage rules. healing 1. create an instant effect with a positive health change or incominghealing meta value. 2. apply on authority with source context. 3. clamp final health to maxhealth. 4. emit ui/gameplay reactions after final value is known. timed buff 1. create a has duration effect. 2. add a modifier to the target attribute. 3. configure duration and stacking explicitly. 4. add owned/status tags through the current gameplay effect component model where needed. 5. apply and retain the active effect handle only if a later targeted removal needs it. 6. verify attribute returns exactly when the effect expires/removes. equipment or passive modifier 1. create an infinite effect per coherent source or bundle. 2. apply when equipped/granted. 3. store factivegameplayeffecthandle with the runtime equipment/passive instance. 4. remove by that handle on unequip/revoke. 5. test duplicate equip, load restore, owner change, and removal order. regeneration choose one model: - periodic gameplay effect for discrete authoritative ticks; - continuous modifier if the attribute semantics support it; - server-owned timer/system applying instant effects. define delay after damage, period, first tick timing, max clamp, stacking, and pause/block tags. do not add per-character tick without a measured need. max-value change pick and document one policy: - preserve absolute current value, then clamp; - preserve percentage: newcurrent = oldcurrent / oldmax newmax; - apply the same delta to current and max; - refill on increase. implement deliberately; no policy is universally correct. gameplay effect selector gameplay effect selector duration policy | need | duration policy | notes | |---|---|---| | damage, healing, purchase, permanent progression, initialization | instant | changes base value | | timed buff/debuff | has duration | modifier exists while active | | equipped/aura/passive modifier removed by handle/condition | infinite | explicit removal required | | damage/heal over time | has duration or infinite with period | period and duration/removal are separate decisions | magnitude method | need | method | |---|---| | constant or level-scaled data | scalable float / configured magnitude | | runtime caller supplies one named amount | setbycaller on the gameplay effect spec | | reusable magnitude from captured source/target attributes | modifier magnitude calculation | | multi-stage authoritative result, multiple captures/outputs, custom damage resolution | gameplay effect execution calculation | prefer the simplest method that expresses the rule. calculations add implementation and prediction constraints; fixed/scalable modifiers remain easier to inspect. modifier operation choose the operation from the desired math—additive, multiplicative, division, or override— and test multiple simultaneous sources. document whether percentages are intended to combine additively or multiplicatively; do not infer it from ui wording. runtime data gameplay effect assets are immutable definitions. at runtime: 1. make a gameplay effect context with instigator/source information. 2. make an outgoing gameplay effect spec at the desired level. 3. set setbycaller magnitudes and other spec data before application. 4. apply the spec to self or target asc. 5. retain the active effect handle when explicit removal or inspection is required. stacking design questions - aggregate by source or by target? - maximum stack count? - refresh, extend, or preserve duration on reapplication? - reset period on reapplication? - overflow behavior? - is each source independent, or should all instances combine? - which tags identify and inhibit the effect? test the exact configured behavior; stacking policy changes gameplay semantics, not just implementation. replication and ui replication and ui authority the server owns final gameplay state. clients may predict supported gas changes, but every effect and calculation must still be designed for rejection/correction. attribute replication for replicated attributes in native attributesets: 1. mark the attribute property for replication with a repnotify function. 2. add it to getlifetimereplicatedprops with the chosen replication condition/notification. 3. in the repnotify function, invoke gameplayattributerepnotify for that attributeset, attribute, and old value. 4. verify simulated proxies and the owning client receive expected changes and prediction corrections. follow the exact current engine macro/api signature in the 5.8 headers or epic sample code. ui update pattern 1. widget/view model obtains the correct asc for the represented actor. 2. read initial value once. 3. subscribe to getgameplayattributevaluechangedelegate(attribute) or the project wrapper. 4. on callback, format current/max values and update presentation. 5. unsubscribe/rebind when the represented actor or asc changes. do not poll attributes each frame. do not make the widget authoritative or apply gameplay effects from display logic. useful diagnostics log or inspect: - source and target asc owner/avatar; - effect class, spec level, context/instigator; - setbycaller keys and values; - active effect handle, duration, period, and stack count; - old/new base and current values where available; - server and client roles; - attribute delegate and repnotify execution. test initial join, late join, respawn, possession swap, effect expiry, effect removal, prediction rejection, and ui rebind. ue 5.8 primary sources ue 5.8 primary sources verified 2026-07-19. - gameplay attributes and attribute sets - gameplay effects - gameplay ability system overview - ability system component and attributes - ugameplayeffect api - egameplayeffectdurationtype api version note: these epic pages currently resolve to unreal engine 5.8. epic's 5.8 attributeset documentation explicitly states that the system has no built-in clamp and that the example metadata table's minvalue/maxvalue columns do not enforce bounds. troubleshooting troubleshooting value exceeds min/max - attributesets do not automatically clamp. - confirm both proposed current changes and final executed base changes are covered. - reapply invariant after max-value changes and aggregator recalculation where required. - do not rely on attributemetadata table minvalue/maxvalue columns. buff never reverts - confirm it is duration/infinite, not instant. - confirm removal targets the retained active effect handle or matching query. - check stacking: another source/stack may remain. - check manual direct writes that bypassed the effect aggregator. modifier applies twice - log every application site and active effect handle. - check duplicate initialization after possession/respawn. - check both server and client applying an unsupported non-predicted effect. - inspect stacking configuration and source aggregation. setbycaller is zero/missing - confirm the magnitude tag/name on the spec exactly matches the effect modifier. - set the value before application. - log missing keys as errors during development; do not silently accept zero for critical gameplay. client ui is stale - confirm attribute replicates and repnotify calls gameplayattributerepnotify. - confirm widget binds to the current asc after respawn/possession. - read initial value before waiting for changes. - ensure the ui listens to the attribute delegate rather than a local effect event only. server and client damage disagree - keep final damage execution authoritative. - verify captured attributes and snapshot/non-snapshot intent. - log source/target context, spec level, runtime magnitudes, and prediction path. - separate predicted hit feedback from confirmed health change. death fires repeatedly - detect the transition from above zero to zero after final clamping. - centralize death signaling in one authoritative path. - guard against repeated instant effects on an already-dead target with a state tag/rule.","references":[{"slug":"attribute-model","file":"attribute-model.md","title":"Attribute model","rawMarkdown":"# Attribute model\n\n## Define AttributeSets\n\nGameplay Attributes live in native `UAttributeSet` classes as `FGameplayAttributeData`\nproperties. Group them by coherent ownership/lifetime, for example:\n\n- vitals: Health, MaxHealth, Stamina, MaxStamina;\n- combat: AttackPower, Armor, critical parameters;\n- movement: MoveSpeed or movement multipliers;\n- transient meta inputs: IncomingDamage or IncomingHealing.\n\nAn ASC can access registered AttributeSets. Avoid one giant set merely because it is easy to\ncreate; avoid splitting so finely that related invariants become hard to enforce.\n\n## Base and current values\n\n- **Base value**: durable value before temporary modifiers.\n- **Current value**: evaluated result including active modifiers.\n- Instant Gameplay Effects change base values.\n- Duration and Infinite effects modify current values while active and are undone when they\n  expire or are removed.\n\nUse an effect for changes. Do not directly write a temporary bonus into the attribute, or its\nsource/removal/stacking semantics become opaque.\n\n## Initialization\n\n1. Create an Instant initialization Gameplay Effect with default attribute modifiers.\n2. Create a spec at the correct level or with SetByCaller values.\n3. Apply it from authority after ASC actor info and AttributeSets are ready.\n4. Guard against duplicate application on respawn/repossession.\n5. If ASC persists on PlayerState, explicitly decide which attributes persist and which reset\n   for the new avatar.\n\n## Invariants and clamping\n\nAttributeSets do not provide automatic min/max clamping. Data Table `MinValue` and `MaxValue`\ncolumns do not enforce bounds.\n\nEnforce invariants deliberately:\n\n- clamp proposed current-value changes in `PreAttributeChange` where appropriate;\n- clamp permanent executed results in `PostGameplayEffectExecute` or the authoritative\n  calculation/application path;\n- when MaxHealth changes, decide whether Health preserves absolute value, percentage, or only\n  clamps down;\n- keep resource invariants explicit: `0 <= Health <= MaxHealth`.\n\nDo not assume a clamp in one hook covers every aggregator recalculation or execution path.\n","webMarkdown":"## Define AttributeSets\n\nGameplay Attributes live in native `UAttributeSet` classes as `FGameplayAttributeData`\nproperties. Group them by coherent ownership/lifetime, for example:\n\n- vitals: Health, MaxHealth, Stamina, MaxStamina;\n- combat: AttackPower, Armor, critical parameters;\n- movement: MoveSpeed or movement multipliers;\n- transient meta inputs: IncomingDamage or IncomingHealing.\n\nAn ASC can access registered AttributeSets. Avoid one giant set merely because it is easy to\ncreate; avoid splitting so finely that related invariants become hard to enforce.\n\n## Base and current values\n\n- **Base value**: durable value before temporary modifiers.\n- **Current value**: evaluated result including active modifiers.\n- Instant Gameplay Effects change base values.\n- Duration and Infinite effects modify current values while active and are undone when they\n  expire or are removed.\n\nUse an effect for changes. Do not directly write a temporary bonus into the attribute, or its\nsource/removal/stacking semantics become opaque.\n\n## Initialization\n\n1. Create an Instant initialization Gameplay Effect with default attribute modifiers.\n2. Create a spec at the correct level or with SetByCaller values.\n3. Apply it from authority after ASC actor info and AttributeSets are ready.\n4. Guard against duplicate application on respawn/repossession.\n5. If ASC persists on PlayerState, explicitly decide which attributes persist and which reset\n   for the new avatar.\n\n## Invariants and clamping\n\nAttributeSets do not provide automatic min/max clamping. Data Table `MinValue` and `MaxValue`\ncolumns do not enforce bounds.\n\nEnforce invariants deliberately:\n\n- clamp proposed current-value changes in `PreAttributeChange` where appropriate;\n- clamp permanent executed results in `PostGameplayEffectExecute` or the authoritative\n  calculation/application path;\n- when MaxHealth changes, decide whether Health preserves absolute value, percentage, or only\n  clamps down;\n- keep resource invariants explicit: `0 <= Health <= MaxHealth`.\n\nDo not assume a clamp in one hook covers every aggregator recalculation or execution path.\n","searchText":"attribute model define attributesets gameplay attributes live in native uattributeset classes as fgameplayattributedata properties. group them by coherent ownership/lifetime, for example: - vitals: health, maxhealth, stamina, maxstamina; - combat: attackpower, armor, critical parameters; - movement: movespeed or movement multipliers; - transient meta inputs: incomingdamage or incominghealing. an asc can access registered attributesets. avoid one giant set merely because it is easy to create; avoid splitting so finely that related invariants become hard to enforce. base and current values - base value: durable value before temporary modifiers. - current value: evaluated result including active modifiers. - instant gameplay effects change base values. - duration and infinite effects modify current values while active and are undone when they expire or are removed. use an effect for changes. do not directly write a temporary bonus into the attribute, or its source/removal/stacking semantics become opaque. initialization 1. create an instant initialization gameplay effect with default attribute modifiers. 2. create a spec at the correct level or with setbycaller values. 3. apply it from authority after asc actor info and attributesets are ready. 4. guard against duplicate application on respawn/repossession. 5. if asc persists on playerstate, explicitly decide which attributes persist and which reset for the new avatar. invariants and clamping attributesets do not provide automatic min/max clamping. data table minvalue and maxvalue columns do not enforce bounds. enforce invariants deliberately: - clamp proposed current-value changes in preattributechange where appropriate; - clamp permanent executed results in postgameplayeffectexecute or the authoritative calculation/application path; - when maxhealth changes, decide whether health preserves absolute value, percentage, or only clamps down; - keep resource invariants explicit: 0 <= health <= maxhealth. do not assume a clamp in one hook covers every aggregator recalculation or execution path."},{"slug":"calculations-and-patterns","file":"calculations-and-patterns.md","title":"Calculations and action patterns","rawMarkdown":"# Calculations and action patterns\n\n## Direct damage with a meta-attribute\n\n1. Source ability creates an Instant damage effect spec.\n2. Supply raw damage through a configured modifier or SetByCaller tag.\n3. Execution calculation captures required source/target values and computes mitigated damage\n   on authority.\n4. Write the result to transient `IncomingDamage`.\n5. In `PostGameplayEffectExecute`, consume IncomingDamage, set it back to zero, subtract from\n   Health, clamp, and signal death only on the valid transition.\n\nThe meta-attribute keeps transient inputs separate from persistent Health and centralizes\npost-damage rules.\n\n## Healing\n\n1. Create an Instant effect with a positive health change or IncomingHealing meta value.\n2. Apply on authority with source context.\n3. Clamp final Health to MaxHealth.\n4. Emit UI/gameplay reactions after final value is known.\n\n## Timed buff\n\n1. Create a Has Duration effect.\n2. Add a modifier to the target Attribute.\n3. Configure duration and stacking explicitly.\n4. Add owned/status tags through the current Gameplay Effect component model where needed.\n5. Apply and retain the active effect handle only if a later targeted removal needs it.\n6. Verify attribute returns exactly when the effect expires/removes.\n\n## Equipment or passive modifier\n\n1. Create an Infinite effect per coherent source or bundle.\n2. Apply when equipped/granted.\n3. Store `FActiveGameplayEffectHandle` with the runtime equipment/passive instance.\n4. Remove by that handle on unequip/revoke.\n5. Test duplicate equip, load restore, owner change, and removal order.\n\n## Regeneration\n\nChoose one model:\n\n- periodic Gameplay Effect for discrete authoritative ticks;\n- continuous modifier if the Attribute semantics support it;\n- server-owned timer/system applying instant effects.\n\nDefine delay after damage, period, first tick timing, max clamp, stacking, and pause/block tags.\nDo not add per-character Tick without a measured need.\n\n## Max-value change\n\nPick and document one policy:\n\n- preserve absolute current value, then clamp;\n- preserve percentage: `NewCurrent = OldCurrent / OldMax * NewMax`;\n- apply the same delta to current and max;\n- refill on increase.\n\nImplement deliberately; no policy is universally correct.\n","webMarkdown":"## Direct damage with a meta-attribute\n\n1. Source ability creates an Instant damage effect spec.\n2. Supply raw damage through a configured modifier or SetByCaller tag.\n3. Execution calculation captures required source/target values and computes mitigated damage\n   on authority.\n4. Write the result to transient `IncomingDamage`.\n5. In `PostGameplayEffectExecute`, consume IncomingDamage, set it back to zero, subtract from\n   Health, clamp, and signal death only on the valid transition.\n\nThe meta-attribute keeps transient inputs separate from persistent Health and centralizes\npost-damage rules.\n\n## Healing\n\n1. Create an Instant effect with a positive health change or IncomingHealing meta value.\n2. Apply on authority with source context.\n3. Clamp final Health to MaxHealth.\n4. Emit UI/gameplay reactions after final value is known.\n\n## Timed buff\n\n1. Create a Has Duration effect.\n2. Add a modifier to the target Attribute.\n3. Configure duration and stacking explicitly.\n4. Add owned/status tags through the current Gameplay Effect component model where needed.\n5. Apply and retain the active effect handle only if a later targeted removal needs it.\n6. Verify attribute returns exactly when the effect expires/removes.\n\n## Equipment or passive modifier\n\n1. Create an Infinite effect per coherent source or bundle.\n2. Apply when equipped/granted.\n3. Store `FActiveGameplayEffectHandle` with the runtime equipment/passive instance.\n4. Remove by that handle on unequip/revoke.\n5. Test duplicate equip, load restore, owner change, and removal order.\n\n## Regeneration\n\nChoose one model:\n\n- periodic Gameplay Effect for discrete authoritative ticks;\n- continuous modifier if the Attribute semantics support it;\n- server-owned timer/system applying instant effects.\n\nDefine delay after damage, period, first tick timing, max clamp, stacking, and pause/block tags.\nDo not add per-character Tick without a measured need.\n\n## Max-value change\n\nPick and document one policy:\n\n- preserve absolute current value, then clamp;\n- preserve percentage: `NewCurrent = OldCurrent / OldMax * NewMax`;\n- apply the same delta to current and max;\n- refill on increase.\n\nImplement deliberately; no policy is universally correct.\n","searchText":"calculations and action patterns direct damage with a meta-attribute 1. source ability creates an instant damage effect spec. 2. supply raw damage through a configured modifier or setbycaller tag. 3. execution calculation captures required source/target values and computes mitigated damage on authority. 4. write the result to transient incomingdamage. 5. in postgameplayeffectexecute, consume incomingdamage, set it back to zero, subtract from health, clamp, and signal death only on the valid transition. the meta-attribute keeps transient inputs separate from persistent health and centralizes post-damage rules. healing 1. create an instant effect with a positive health change or incominghealing meta value. 2. apply on authority with source context. 3. clamp final health to maxhealth. 4. emit ui/gameplay reactions after final value is known. timed buff 1. create a has duration effect. 2. add a modifier to the target attribute. 3. configure duration and stacking explicitly. 4. add owned/status tags through the current gameplay effect component model where needed. 5. apply and retain the active effect handle only if a later targeted removal needs it. 6. verify attribute returns exactly when the effect expires/removes. equipment or passive modifier 1. create an infinite effect per coherent source or bundle. 2. apply when equipped/granted. 3. store factivegameplayeffecthandle with the runtime equipment/passive instance. 4. remove by that handle on unequip/revoke. 5. test duplicate equip, load restore, owner change, and removal order. regeneration choose one model: - periodic gameplay effect for discrete authoritative ticks; - continuous modifier if the attribute semantics support it; - server-owned timer/system applying instant effects. define delay after damage, period, first tick timing, max clamp, stacking, and pause/block tags. do not add per-character tick without a measured need. max-value change pick and document one policy: - preserve absolute current value, then clamp; - preserve percentage: newcurrent = oldcurrent / oldmax newmax; - apply the same delta to current and max; - refill on increase. implement deliberately; no policy is universally correct."},{"slug":"effect-selector","file":"effect-selector.md","title":"Gameplay Effect selector","rawMarkdown":"# Gameplay Effect selector\n\n## Duration policy\n\n| Need | Duration policy | Notes |\n|---|---|---|\n| Damage, healing, purchase, permanent progression, initialization | Instant | Changes base value |\n| Timed buff/debuff | Has Duration | Modifier exists while active |\n| Equipped/aura/passive modifier removed by handle/condition | Infinite | Explicit removal required |\n| Damage/heal over time | Has Duration or Infinite with Period | Period and duration/removal are separate decisions |\n\n## Magnitude method\n\n| Need | Method |\n|---|---|\n| Constant or level-scaled data | Scalable Float / configured magnitude |\n| Runtime caller supplies one named amount | SetByCaller on the Gameplay Effect Spec |\n| Reusable magnitude from captured source/target attributes | Modifier Magnitude Calculation |\n| Multi-stage authoritative result, multiple captures/outputs, custom damage resolution | Gameplay Effect Execution Calculation |\n\nPrefer the simplest method that expresses the rule. Calculations add implementation and\nprediction constraints; fixed/scalable modifiers remain easier to inspect.\n\n## Modifier operation\n\nChoose the operation from the desired math—additive, multiplicative, division, or override—\nand test multiple simultaneous sources. Document whether percentages are intended to combine\nadditively or multiplicatively; do not infer it from UI wording.\n\n## Runtime data\n\nGameplay Effect assets are immutable definitions. At runtime:\n\n1. Make a Gameplay Effect Context with instigator/source information.\n2. Make an outgoing Gameplay Effect Spec at the desired level.\n3. Set SetByCaller magnitudes and other spec data before application.\n4. Apply the spec to self or target ASC.\n5. Retain the active effect handle when explicit removal or inspection is required.\n\n## Stacking design questions\n\n- Aggregate by source or by target?\n- Maximum stack count?\n- Refresh, extend, or preserve duration on reapplication?\n- Reset period on reapplication?\n- Overflow behavior?\n- Is each source independent, or should all instances combine?\n- Which tags identify and inhibit the effect?\n\nTest the exact configured behavior; stacking policy changes gameplay semantics, not just\nimplementation.\n","webMarkdown":"## Duration policy\n\n| Need | Duration policy | Notes |\n|---|---|---|\n| Damage, healing, purchase, permanent progression, initialization | Instant | Changes base value |\n| Timed buff/debuff | Has Duration | Modifier exists while active |\n| Equipped/aura/passive modifier removed by handle/condition | Infinite | Explicit removal required |\n| Damage/heal over time | Has Duration or Infinite with Period | Period and duration/removal are separate decisions |\n\n## Magnitude method\n\n| Need | Method |\n|---|---|\n| Constant or level-scaled data | Scalable Float / configured magnitude |\n| Runtime caller supplies one named amount | SetByCaller on the Gameplay Effect Spec |\n| Reusable magnitude from captured source/target attributes | Modifier Magnitude Calculation |\n| Multi-stage authoritative result, multiple captures/outputs, custom damage resolution | Gameplay Effect Execution Calculation |\n\nPrefer the simplest method that expresses the rule. Calculations add implementation and\nprediction constraints; fixed/scalable modifiers remain easier to inspect.\n\n## Modifier operation\n\nChoose the operation from the desired math—additive, multiplicative, division, or override—\nand test multiple simultaneous sources. Document whether percentages are intended to combine\nadditively or multiplicatively; do not infer it from UI wording.\n\n## Runtime data\n\nGameplay Effect assets are immutable definitions. At runtime:\n\n1. Make a Gameplay Effect Context with instigator/source information.\n2. Make an outgoing Gameplay Effect Spec at the desired level.\n3. Set SetByCaller magnitudes and other spec data before application.\n4. Apply the spec to self or target ASC.\n5. Retain the active effect handle when explicit removal or inspection is required.\n\n## Stacking design questions\n\n- Aggregate by source or by target?\n- Maximum stack count?\n- Refresh, extend, or preserve duration on reapplication?\n- Reset period on reapplication?\n- Overflow behavior?\n- Is each source independent, or should all instances combine?\n- Which tags identify and inhibit the effect?\n\nTest the exact configured behavior; stacking policy changes gameplay semantics, not just\nimplementation.\n","searchText":"gameplay effect selector duration policy | need | duration policy | notes | |---|---|---| | damage, healing, purchase, permanent progression, initialization | instant | changes base value | | timed buff/debuff | has duration | modifier exists while active | | equipped/aura/passive modifier removed by handle/condition | infinite | explicit removal required | | damage/heal over time | has duration or infinite with period | period and duration/removal are separate decisions | magnitude method | need | method | |---|---| | constant or level-scaled data | scalable float / configured magnitude | | runtime caller supplies one named amount | setbycaller on the gameplay effect spec | | reusable magnitude from captured source/target attributes | modifier magnitude calculation | | multi-stage authoritative result, multiple captures/outputs, custom damage resolution | gameplay effect execution calculation | prefer the simplest method that expresses the rule. calculations add implementation and prediction constraints; fixed/scalable modifiers remain easier to inspect. modifier operation choose the operation from the desired math—additive, multiplicative, division, or override— and test multiple simultaneous sources. document whether percentages are intended to combine additively or multiplicatively; do not infer it from ui wording. runtime data gameplay effect assets are immutable definitions. at runtime: 1. make a gameplay effect context with instigator/source information. 2. make an outgoing gameplay effect spec at the desired level. 3. set setbycaller magnitudes and other spec data before application. 4. apply the spec to self or target asc. 5. retain the active effect handle when explicit removal or inspection is required. stacking design questions - aggregate by source or by target? - maximum stack count? - refresh, extend, or preserve duration on reapplication? - reset period on reapplication? - overflow behavior? - is each source independent, or should all instances combine? - which tags identify and inhibit the effect? test the exact configured behavior; stacking policy changes gameplay semantics, not just implementation."},{"slug":"replication-ui","file":"replication-ui.md","title":"Replication and UI","rawMarkdown":"# Replication and UI\n\n## Authority\n\nThe server owns final gameplay state. Clients may predict supported GAS changes, but every\neffect and calculation must still be designed for rejection/correction.\n\n## Attribute replication\n\nFor replicated attributes in native AttributeSets:\n\n1. Mark the attribute property for replication with a RepNotify function.\n2. Add it to `GetLifetimeReplicatedProps` with the chosen replication condition/notification.\n3. In the RepNotify function, invoke `GAMEPLAYATTRIBUTE_REPNOTIFY` for that AttributeSet,\n   attribute, and old value.\n4. Verify simulated proxies and the owning client receive expected changes and prediction\n   corrections.\n\nFollow the exact current engine macro/API signature in the 5.8 headers or Epic sample code.\n\n## UI update pattern\n\n1. Widget/view model obtains the correct ASC for the represented actor.\n2. Read initial value once.\n3. Subscribe to `GetGameplayAttributeValueChangeDelegate(Attribute)` or the project wrapper.\n4. On callback, format current/max values and update presentation.\n5. Unsubscribe/rebind when the represented actor or ASC changes.\n\nDo not poll attributes each frame. Do not make the widget authoritative or apply gameplay\neffects from display logic.\n\n## Useful diagnostics\n\nLog or inspect:\n\n- source and target ASC owner/avatar;\n- effect class, spec level, context/instigator;\n- SetByCaller keys and values;\n- active effect handle, duration, period, and stack count;\n- old/new base and current values where available;\n- server and client roles;\n- attribute delegate and RepNotify execution.\n\nTest initial join, late join, respawn, possession swap, effect expiry, effect removal,\nprediction rejection, and UI rebind.\n","webMarkdown":"## Authority\n\nThe server owns final gameplay state. Clients may predict supported GAS changes, but every\neffect and calculation must still be designed for rejection/correction.\n\n## Attribute replication\n\nFor replicated attributes in native AttributeSets:\n\n1. Mark the attribute property for replication with a RepNotify function.\n2. Add it to `GetLifetimeReplicatedProps` with the chosen replication condition/notification.\n3. In the RepNotify function, invoke `GAMEPLAYATTRIBUTE_REPNOTIFY` for that AttributeSet,\n   attribute, and old value.\n4. Verify simulated proxies and the owning client receive expected changes and prediction\n   corrections.\n\nFollow the exact current engine macro/API signature in the 5.8 headers or Epic sample code.\n\n## UI update pattern\n\n1. Widget/view model obtains the correct ASC for the represented actor.\n2. Read initial value once.\n3. Subscribe to `GetGameplayAttributeValueChangeDelegate(Attribute)` or the project wrapper.\n4. On callback, format current/max values and update presentation.\n5. Unsubscribe/rebind when the represented actor or ASC changes.\n\nDo not poll attributes each frame. Do not make the widget authoritative or apply gameplay\neffects from display logic.\n\n## Useful diagnostics\n\nLog or inspect:\n\n- source and target ASC owner/avatar;\n- effect class, spec level, context/instigator;\n- SetByCaller keys and values;\n- active effect handle, duration, period, and stack count;\n- old/new base and current values where available;\n- server and client roles;\n- attribute delegate and RepNotify execution.\n\nTest initial join, late join, respawn, possession swap, effect expiry, effect removal,\nprediction rejection, and UI rebind.\n","searchText":"replication and ui authority the server owns final gameplay state. clients may predict supported gas changes, but every effect and calculation must still be designed for rejection/correction. attribute replication for replicated attributes in native attributesets: 1. mark the attribute property for replication with a repnotify function. 2. add it to getlifetimereplicatedprops with the chosen replication condition/notification. 3. in the repnotify function, invoke gameplayattributerepnotify for that attributeset, attribute, and old value. 4. verify simulated proxies and the owning client receive expected changes and prediction corrections. follow the exact current engine macro/api signature in the 5.8 headers or epic sample code. ui update pattern 1. widget/view model obtains the correct asc for the represented actor. 2. read initial value once. 3. subscribe to getgameplayattributevaluechangedelegate(attribute) or the project wrapper. 4. on callback, format current/max values and update presentation. 5. unsubscribe/rebind when the represented actor or asc changes. do not poll attributes each frame. do not make the widget authoritative or apply gameplay effects from display logic. useful diagnostics log or inspect: - source and target asc owner/avatar; - effect class, spec level, context/instigator; - setbycaller keys and values; - active effect handle, duration, period, and stack count; - old/new base and current values where available; - server and client roles; - attribute delegate and repnotify execution. test initial join, late join, respawn, possession swap, effect expiry, effect removal, prediction rejection, and ui rebind."},{"slug":"sources","file":"sources.md","title":"UE 5.8 primary sources","rawMarkdown":"# UE 5.8 primary sources\n\nVerified 2026-07-19.\n\n- [Gameplay Attributes and Attribute Sets](https://dev.epicgames.com/documentation/en-us/unreal-engine/gameplay-attributes-and-attribute-sets-for-the-gameplay-ability-system-in-unreal-engine)\n- [Gameplay Effects](https://dev.epicgames.com/documentation/en-us/unreal-engine/gameplay-effects-for-the-gameplay-ability-system-in-unreal-engine)\n- [Gameplay Ability System Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/understanding-the-unreal-engine-gameplay-ability-system)\n- [Ability System Component and Attributes](https://dev.epicgames.com/documentation/en-us/unreal-engine/gameplay-ability-system-component-and-gameplay-attributes-in-unreal-engine)\n- [`UGameplayEffect` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/GameplayAbilities/UGameplayEffect)\n- [`EGameplayEffectDurationType` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/GameplayAbilities/EGameplayEffectDurationType)\n\nVersion note: these Epic pages currently resolve to Unreal Engine 5.8. Epic's 5.8\nAttributeSet documentation explicitly states that the system has no built-in clamp and that\nthe example metadata table's MinValue/MaxValue columns do not enforce bounds.\n","webMarkdown":"Verified 2026-07-19.\n\n- [Gameplay Attributes and Attribute Sets](https://dev.epicgames.com/documentation/en-us/unreal-engine/gameplay-attributes-and-attribute-sets-for-the-gameplay-ability-system-in-unreal-engine)\n- [Gameplay Effects](https://dev.epicgames.com/documentation/en-us/unreal-engine/gameplay-effects-for-the-gameplay-ability-system-in-unreal-engine)\n- [Gameplay Ability System Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/understanding-the-unreal-engine-gameplay-ability-system)\n- [Ability System Component and Attributes](https://dev.epicgames.com/documentation/en-us/unreal-engine/gameplay-ability-system-component-and-gameplay-attributes-in-unreal-engine)\n- [`UGameplayEffect` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/GameplayAbilities/UGameplayEffect)\n- [`EGameplayEffectDurationType` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/GameplayAbilities/EGameplayEffectDurationType)\n\nVersion note: these Epic pages currently resolve to Unreal Engine 5.8. Epic's 5.8\nAttributeSet documentation explicitly states that the system has no built-in clamp and that\nthe example metadata table's MinValue/MaxValue columns do not enforce bounds.\n","searchText":"ue 5.8 primary sources verified 2026-07-19. - gameplay attributes and attribute sets - gameplay effects - gameplay ability system overview - ability system component and attributes - ugameplayeffect api - egameplayeffectdurationtype api version note: these epic pages currently resolve to unreal engine 5.8. epic's 5.8 attributeset documentation explicitly states that the system has no built-in clamp and that the example metadata table's minvalue/maxvalue columns do not enforce bounds."},{"slug":"troubleshooting","file":"troubleshooting.md","title":"Troubleshooting","rawMarkdown":"# Troubleshooting\n\n## Value exceeds min/max\n\n- AttributeSets do not automatically clamp.\n- Confirm both proposed current changes and final executed base changes are covered.\n- Reapply invariant after Max-value changes and aggregator recalculation where required.\n- Do not rely on AttributeMetaData table MinValue/MaxValue columns.\n\n## Buff never reverts\n\n- Confirm it is Duration/Infinite, not Instant.\n- Confirm removal targets the retained active effect handle or matching query.\n- Check stacking: another source/stack may remain.\n- Check manual direct writes that bypassed the effect aggregator.\n\n## Modifier applies twice\n\n- Log every application site and active effect handle.\n- Check duplicate initialization after possession/respawn.\n- Check both server and client applying an unsupported non-predicted effect.\n- Inspect stacking configuration and source aggregation.\n\n## SetByCaller is zero/missing\n\n- Confirm the magnitude tag/name on the spec exactly matches the effect modifier.\n- Set the value before application.\n- Log missing keys as errors during development; do not silently accept zero for critical\n  gameplay.\n\n## Client UI is stale\n\n- Confirm attribute replicates and RepNotify calls `GAMEPLAYATTRIBUTE_REPNOTIFY`.\n- Confirm widget binds to the current ASC after respawn/possession.\n- Read initial value before waiting for changes.\n- Ensure the UI listens to the attribute delegate rather than a local effect event only.\n\n## Server and client damage disagree\n\n- Keep final damage execution authoritative.\n- Verify captured attributes and snapshot/non-snapshot intent.\n- Log source/target context, spec level, runtime magnitudes, and prediction path.\n- Separate predicted hit feedback from confirmed Health change.\n\n## Death fires repeatedly\n\n- Detect the transition from above zero to zero after final clamping.\n- Centralize death signaling in one authoritative path.\n- Guard against repeated Instant effects on an already-dead target with a state tag/rule.\n","webMarkdown":"## Value exceeds min/max\n\n- AttributeSets do not automatically clamp.\n- Confirm both proposed current changes and final executed base changes are covered.\n- Reapply invariant after Max-value changes and aggregator recalculation where required.\n- Do not rely on AttributeMetaData table MinValue/MaxValue columns.\n\n## Buff never reverts\n\n- Confirm it is Duration/Infinite, not Instant.\n- Confirm removal targets the retained active effect handle or matching query.\n- Check stacking: another source/stack may remain.\n- Check manual direct writes that bypassed the effect aggregator.\n\n## Modifier applies twice\n\n- Log every application site and active effect handle.\n- Check duplicate initialization after possession/respawn.\n- Check both server and client applying an unsupported non-predicted effect.\n- Inspect stacking configuration and source aggregation.\n\n## SetByCaller is zero/missing\n\n- Confirm the magnitude tag/name on the spec exactly matches the effect modifier.\n- Set the value before application.\n- Log missing keys as errors during development; do not silently accept zero for critical\n  gameplay.\n\n## Client UI is stale\n\n- Confirm attribute replicates and RepNotify calls `GAMEPLAYATTRIBUTE_REPNOTIFY`.\n- Confirm widget binds to the current ASC after respawn/possession.\n- Read initial value before waiting for changes.\n- Ensure the UI listens to the attribute delegate rather than a local effect event only.\n\n## Server and client damage disagree\n\n- Keep final damage execution authoritative.\n- Verify captured attributes and snapshot/non-snapshot intent.\n- Log source/target context, spec level, runtime magnitudes, and prediction path.\n- Separate predicted hit feedback from confirmed Health change.\n\n## Death fires repeatedly\n\n- Detect the transition from above zero to zero after final clamping.\n- Centralize death signaling in one authoritative path.\n- Guard against repeated Instant effects on an already-dead target with a state tag/rule.\n","searchText":"troubleshooting value exceeds min/max - attributesets do not automatically clamp. - confirm both proposed current changes and final executed base changes are covered. - reapply invariant after max-value changes and aggregator recalculation where required. - do not rely on attributemetadata table minvalue/maxvalue columns. buff never reverts - confirm it is duration/infinite, not instant. - confirm removal targets the retained active effect handle or matching query. - check stacking: another source/stack may remain. - check manual direct writes that bypassed the effect aggregator. modifier applies twice - log every application site and active effect handle. - check duplicate initialization after possession/respawn. - check both server and client applying an unsupported non-predicted effect. - inspect stacking configuration and source aggregation. setbycaller is zero/missing - confirm the magnitude tag/name on the spec exactly matches the effect modifier. - set the value before application. - log missing keys as errors during development; do not silently accept zero for critical gameplay. client ui is stale - confirm attribute replicates and repnotify calls gameplayattributerepnotify. - confirm widget binds to the current asc after respawn/possession. - read initial value before waiting for changes. - ensure the ui listens to the attribute delegate rather than a local effect event only. server and client damage disagree - keep final damage execution authoritative. - verify captured attributes and snapshot/non-snapshot intent. - log source/target context, spec level, runtime magnitudes, and prediction path. - separate predicted hit feedback from confirmed health change. death fires repeatedly - detect the transition from above zero to zero after final clamping. - centralize death signaling in one authoritative path. - guard against repeated instant effects on an already-dead target with a state tag/rule."}]}
{"slug":"unreal-insights-profiling","name":"unreal-insights-profiling","title":"Unreal 5.8 Insights Profiling","description":"Capture, analyze, compare, and automate performance evidence in Unreal Engine 5.8. Use for Unreal Insights, Timing Insights, Memory Insights, Networking Insights, Task Graph Insights, stat unit, stat commands, GPU Profiler, trace channels, CPU/GPU/thread bottlenecks, hitches, stalls, garbage collection, asset loading, memory growth, packet cost, custom trace instrumentation, performance budgets, or before/after regression captures.","shortDescription":"Capture and isolate Unreal performance bottlenecks","category":"Data, Tools & Shipping","referenceCount":11,"rawMarkdown":"---\nname: unreal-insights-profiling\ndescription: Capture, analyze, compare, and automate performance evidence in Unreal Engine 5.8. Use for Unreal Insights, Timing Insights, Memory Insights, Networking Insights, Task Graph Insights, stat unit, stat commands, GPU Profiler, trace channels, CPU/GPU/thread bottlenecks, hitches, stalls, garbage collection, asset loading, memory growth, packet cost, custom trace instrumentation, performance budgets, or before/after regression captures.\n---\n\n# Unreal 5.8 Insights Profiling\n\n## Establish the measurement contract\n\nRead [`references/capture-contract.md`](references/capture-contract.md), then choose the narrowest\ntool in [`references/tool-selector.md`](references/tool-selector.md).\n\n1. State target platform, hardware class, build configuration, resolution, quality tier, map,\n   camera path, player count, and workload.\n2. State the frame, hitch, memory, load-time, or bandwidth budget in measurable units.\n3. Reproduce without editor-only noise when possible; use a Development or Test packaged build.\n4. Triage with `stat unit`/`stat unitgraph`; identify Game, Draw, RHI, GPU, memory, loading, or net.\n5. Capture only the trace channels needed for the hypothesis and mark the measured interval.\n6. Analyze inclusive/exclusive cost, thread dependencies, spikes, counts, and the critical path.\n7. Change one causal variable, repeat the same workload, and compare milliseconds or bytes.\n8. Preserve the baseline, candidate, capture metadata, and acceptance result.\n\nLoad only what applies:\n\n- [`references/first-pass-triage.md`](references/first-pass-triage.md)\n- [`references/timing-insights-cpu.md`](references/timing-insights-cpu.md)\n- [`references/gpu-and-render-thread.md`](references/gpu-and-render-thread.md)\n- [`references/hitches-loading-and-gc.md`](references/hitches-loading-and-gc.md)\n- [`references/memory-insights.md`](references/memory-insights.md)\n- [`references/network-task-and-ui.md`](references/network-task-and-ui.md)\n- [`references/instrumentation-and-exports.md`](references/instrumentation-and-exports.md)\n- [`references/regression-workflow.md`](references/regression-workflow.md)\n\n## Required answer format\n\nReturn:\n\n1. **Question and budget** being tested.\n2. **Representative workload** and capture environment.\n3. **Exact tool, channels, commands, and capture interval**.\n4. **Observed bound and evidence**, separating sustained cost from spikes.\n5. **Ranked causal suspects**, with inclusive/exclusive time or byte evidence.\n6. **Single next experiment or fix** and its predicted measurable effect.\n7. **Before/after comparison** and pass/fail result.\n8. **Uncertainty**, capture overhead, and missing evidence.\n\n## Hard rules\n\n- Report frame time in milliseconds; FPS alone hides magnitude and variability.\n- Do not profile a Debug build or treat PIE/editor numbers as shipping evidence.\n- Do not infer CPU- versus GPU-bound from FPS; use thread/GPU timing and synchronization context.\n- Do not treat GPU time as causal when it includes idle/wait time; inspect the frame and GPU event tree.\n- Keep trace channels narrow. Tracing consumes CPU, memory, disk, and bandwidth and can perturb results.\n- Capture spikes and steady state separately; averages can hide harmful hitches.\n- Memory allocation tracing must start with the process; late connect cannot reconstruct earlier allocations.\n- Use bookmarks for infrequent state changes, timers/counters for high-frequency events.\n- Preserve same hardware, build, resolution, quality, workload, and capture length for A/B comparisons.\n- Optimize the current top cost, re-profile, and stop when the declared budget is met.\n\nSee [`references/sources.md`](references/sources.md) for the UE 5.8 primary-source trail.\n","webMarkdown":"## Establish the measurement contract\n\nRead [`references/capture-contract.md`](/unreal/unreal-insights-profiling/capture-contract/), then choose the narrowest\ntool in [`references/tool-selector.md`](/unreal/unreal-insights-profiling/tool-selector/).\n\n1. State target platform, hardware class, build configuration, resolution, quality tier, map,\n   camera path, player count, and workload.\n2. State the frame, hitch, memory, load-time, or bandwidth budget in measurable units.\n3. Reproduce without editor-only noise when possible; use a Development or Test packaged build.\n4. Triage with `stat unit`/`stat unitgraph`; identify Game, Draw, RHI, GPU, memory, loading, or net.\n5. Capture only the trace channels needed for the hypothesis and mark the measured interval.\n6. Analyze inclusive/exclusive cost, thread dependencies, spikes, counts, and the critical path.\n7. Change one causal variable, repeat the same workload, and compare milliseconds or bytes.\n8. Preserve the baseline, candidate, capture metadata, and acceptance result.\n\nLoad only what applies:\n\n- [`references/first-pass-triage.md`](/unreal/unreal-insights-profiling/first-pass-triage/)\n- [`references/timing-insights-cpu.md`](/unreal/unreal-insights-profiling/timing-insights-cpu/)\n- [`references/gpu-and-render-thread.md`](/unreal/unreal-insights-profiling/gpu-and-render-thread/)\n- [`references/hitches-loading-and-gc.md`](/unreal/unreal-insights-profiling/hitches-loading-and-gc/)\n- [`references/memory-insights.md`](/unreal/unreal-insights-profiling/memory-insights/)\n- [`references/network-task-and-ui.md`](/unreal/unreal-insights-profiling/network-task-and-ui/)\n- [`references/instrumentation-and-exports.md`](/unreal/unreal-insights-profiling/instrumentation-and-exports/)\n- [`references/regression-workflow.md`](/unreal/unreal-insights-profiling/regression-workflow/)\n\n## Required answer format\n\nReturn:\n\n1. **Question and budget** being tested.\n2. **Representative workload** and capture environment.\n3. **Exact tool, channels, commands, and capture interval**.\n4. **Observed bound and evidence**, separating sustained cost from spikes.\n5. **Ranked causal suspects**, with inclusive/exclusive time or byte evidence.\n6. **Single next experiment or fix** and its predicted measurable effect.\n7. **Before/after comparison** and pass/fail result.\n8. **Uncertainty**, capture overhead, and missing evidence.\n\n## Hard rules\n\n- Report frame time in milliseconds; FPS alone hides magnitude and variability.\n- Do not profile a Debug build or treat PIE/editor numbers as shipping evidence.\n- Do not infer CPU- versus GPU-bound from FPS; use thread/GPU timing and synchronization context.\n- Do not treat GPU time as causal when it includes idle/wait time; inspect the frame and GPU event tree.\n- Keep trace channels narrow. Tracing consumes CPU, memory, disk, and bandwidth and can perturb results.\n- Capture spikes and steady state separately; averages can hide harmful hitches.\n- Memory allocation tracing must start with the process; late connect cannot reconstruct earlier allocations.\n- Use bookmarks for infrequent state changes, timers/counters for high-frequency events.\n- Preserve same hardware, build, resolution, quality, workload, and capture length for A/B comparisons.\n- Optimize the current top cost, re-profile, and stop when the declared budget is met.\n\nSee [`references/sources.md`](/unreal/unreal-insights-profiling/sources/) for the UE 5.8 primary-source trail.\n","searchText":"unreal 5.8 insights profiling capture, analyze, compare, and automate performance evidence in unreal engine 5.8. use for unreal insights, timing insights, memory insights, networking insights, task graph insights, stat unit, stat commands, gpu profiler, trace channels, cpu/gpu/thread bottlenecks, hitches, stalls, garbage collection, asset loading, memory growth, packet cost, custom trace instrumentation, performance budgets, or before/after regression captures. capture contract capture contract record this metadata before interpreting a trace: | field | required value | |---|---| | target | platform, device model/cpu/gpu/ram, driver/os | | build | changelist/commit, development/test/shipping, packaged/editor | | display | output resolution, screen percentage/dynamic resolution, refresh/vsync | | quality | device profile, scalability groups, ray tracing/upscaler path | | workload | map, save/state, camera path, player/ai/effect counts, duration | | budget | frame ms and percentile/hitch threshold; memory/load/net budget if relevant | | capture | command line, channels, warm-up, marked start/end, trace filename | frame budgets before platform overhead or safety margin: | target | frame time | |---|---:| | 30 fps | 33.33 ms | | 60 fps | 16.67 ms | | 90 fps | 11.11 ms | | 120 fps | 8.33 ms | use a repeatable traversal or automated scenario. warm shader/asset caches only when measuring steady state; preserve a cold-start run when first-use hitch or loading is the question. record both if players experience both. reject comparisons that changed more than the intended variable, ran different content paths, used different thermal/power states, or silently changed resolution/scalability. first-pass triage first-pass triage establish the bound 1. run a non-debug build with the target device profile and resolution. 2. disable smoothing/vsync/frame caps only when they conceal the bound; record the change. 3. enter stat unit; add stat unitgraph and stat raw when spikes or filtering matter. 4. reproduce the workload for a fixed interval. 5. compare frame with game, draw, rhit, and gpu. interpretation: | pattern | working classification | next capture | |---|---|---| | frame follows game | game-thread bound | cpu/frame/bookmark; inspect game thread | | frame follows draw | render-thread bound | cpu/frame/gpu; inspect rendering submission | | frame follows rhit | rhi/submission/driver bound | cpu/gpu plus platform graphics profiler | | gpu stands alone near frame | gpu bound | profilegpu, gpu trace | | all appear below frame | cap, wait, sync, present, task dependency | timing + context switch; inspect waits | | rare raw spikes | hitch | bookmark and narrow hitch capture | stat unit is directional, not final proof. parallel cpu and gpu work, pipelining, idle time, vsync, and asynchronous compute can make similar numbers misleading. fast probes - lower primary resolution/screen percentage while holding content constant. a material gpu gain implicates pixel/resolution-scaled work; no gain does not prove a cpu bottleneck. - pause or freeze simulation to separate simulation-fed rendering changes from a stable frame. - disable one major feature with a supported cvar for diagnosis, then restore it. treat the delta as attribution evidence, not automatically as the shipping fix. - use stat scenerendering, stat rhi, stat gpu, stat game, stat anim, stat slate, or the subsystem stat only after the first bound is known. gpu and render thread gpu and render thread attribute gpu cost 1. confirm gpu is plausibly the bound with stat unit. 2. run stat gpu for a live overview. 3. capture one representative frame with profilegpu or ctrl+shift+;. 4. expand the event tree from the largest millisecond pass to its children. 5. repeat at the same camera, resolution, screen percentage, and quality. 6. toggle one supported renderer feature or quality control and compare the same pass. gpu time may contain idle time. asynchronous compute overlaps passes, so individual event totals can overlap or appear inflated. disable async compute only for isolated diagnosis when epic's subsystem guide explicitly recommends it; restore it for the real end-to-end measurement. separate submission from shading | evidence | likely direction | |---|---| | draw/render thread dominates, many primitives/sections | reduce submissions, components, sections, visibility work | | gpu base pass dominates | material/pixel coverage/geometry path | | shadows dominate | light/shadow method, invalidation, caster coverage | | translucency/post dominates | screen coverage, layer count, resolution, effect quality | | lowering resolution helps strongly | pixel-bound passes/upscaler tradeoff | | lowering resolution barely helps | geometry/submission/cpu or fixed-cost gpu work | use the rendering-performance skill only after the pass or submission cost is identified. hitches, loading, and garbage collection hitches, loading, and garbage collection capture a hitch 1. set an explicit hitch threshold for the target experience; use stat hitches or stat dumphitches for fast detection where useful. 2. display stat unitgraph, toggle stat raw, and reproduce the hitch. 3. add bookmarks immediately before/after the action that triggers it. 4. trace cpu,frame,bookmark plus only the suspected channel: loadtime, file, or stats. 5. inspect the exact slow frame and the preceding work; asynchronous requests often cause a later wait. symptom routing | hitch shape | inspect | |---|---| | first use of asset/effect | async load, shader/pso readiness, construction, audio decode | | periodic spike | gc, streaming update, autosave/telemetry, scheduled subsystem | | entering region | world partition/level/texture/nanite streaming and file io | | mass spawn/despawn | object construction, registration, physics/nav, gc pressure | | camera cut | visibility burst, vsm pages, streaming, post/upscaler history | for loading, correlate asset loading events with file reads and game-thread waits. a long async load is not necessarily a hitch unless the critical thread blocks for it or the workload saturates io/cpu. for gc, inspect allocation/object churn before the collection, collection duration, unreachable-object processing, and post-gc work. reduce avoidable churn or distribute work; do not merely raise the gc interval if that creates a larger eventual pause or excess memory. instrumentation and exports instrumentation and exports use built-in trace events before inventing a custom event stream. c++ instrumentation - wrap important cpu scopes with the tracecpuprofilereventscope macro family. - emit tracebookmark for infrequent state transitions such as entering a boss phase or opening a menu. - use trace counters for quantities that change frequently: active enemies, queued requests, bytes, or pool occupancy. - use llmscope tags for memory categories that should appear in llm and allocation traces. do not emit per-object bookmarks every frame. excess instrumentation changes the workload and can make traces too large to analyze. export for repeatable analysis unreal insights supports headless analysis and response commands. a representative invocation is: text unrealinsights.exe -opentracefile=path/file.utrace -autoquit -noui -execonanalysiscompletecmd=\"@=d:\\tests\\export.rsp\" use timinginsights.exporttimerstatistics in the response workflow to export aggregate timer data for named regions. store the response file, capture contract, and threshold logic beside the test. keep raw .utrace files for regressions that require timeline inspection; csv summaries cannot explain dependencies or wait chains by themselves. memory insights memory insights allocation tracing must be enabled from process start. for a packaged project, use development mode. text mygame.exe -trace=default,memory mygame.exe -trace=default,memory,metadata,assetmetadata the metadata channels enable asset/class filtering but add trace cost and volume. select them only when the question requires attribution at that level. query patterns | question | comparison/query | |---|---| | what is live at time t? | live allocations at t, grouped by tag/callstack | | what grew during action a? | allocations between pre-a and post-a markers still live afterward | | is it a leak? | repeat a several times; inspect monotonic retained growth after cleanup | | what churns? | high allocation/free event rate with limited net growth | | which asset/class owns memory? | metadata/assetmetadata grouping and callstacks | correlate detailed allocation graphs, llm tag tracks, modules, and timing events. distinguish: - committed/resident/platform memory from traced allocations; - cpu memory from gpu memory; - cache growth that stabilizes from unbounded retained growth; - expected streaming residency from leaked ownership. capture startup when startup allocations matter. late connect cannot reconstruct allocations made before the memory channel was active. network, task graph, and ui traces network, task graph, and ui traces networking insights start each relevant client instance with: text -trace=net -nettrace=1 when tracing an editor instance to a separate local insights store, add -tracehost=localhost as required. choose verbosity greater than zero and raise it only when the missing packet detail justifies the overhead. inspect packet sizes/timeline, connection direction, object/property/rpc content, inclusive/exclusive net stats, frequency, bursts, and retransmission/transport context. optimize semantic frequency and payload ownership before compressing an already-wrong replication pattern. task graph use: text -trace=default,task inspect task prerequisites, worker occupancy, critical path, parent waits, queue delay, and task size. do not split work into smaller tasks when scheduling overhead already dominates; do not merge tasks when one serial task blocks the frame and parallelism is available. ui and slate triage with stat slate, stat ui, and widget-specific tools. enable the built-in slate insights plugin and capture with -trace=slate. in slate frame view, correlate invalidation reasons, update reasons, layout/prepass, paint, volatility, draw-element growth, and game/render thread cost. repeated full-tree invalidation or per-frame binding work is usually a structural issue; confirm it in the trace before adding caches or invalidation panels. regression workflow regression workflow baseline and candidate 1. freeze scenario, device profile, build settings, camera/input script, warm/cold state, and duration. 2. run multiple baseline samples; retain raw traces and summary metrics. 3. apply one change. 4. run the same number of candidate samples in comparable thermal/background conditions. 5. compare milliseconds, memory, bandwidth, hitch count, and percentile relevant to the budget. 6. inspect a representative trace when the aggregate moved unexpectedly. minimum report: | metric | baseline | candidate | delta | budget | result | |---|---:|---:|---:|---:|---| | median frame ms | | | | | | | p95/p99 or worst-frame ms | | | | | | | bound thread/pass ms | | | | | | | hitch count over threshold | | | | | | | memory/load/net metric | | | | | | do not call a change a win when it shifts cost outside the sampled interval, trades a rare severe hitch for a better average, changes image quality/gameplay, or exceeds another budget. keep a safety margin; meeting 16.67 ms only in an ideal trace is not a robust 60 fps target. ue 5.8 primary sources ue 5.8 primary sources - introduction to performance profiling and configuration - unreal insights - unreal insights trace quick start - unreal insights reference - timing insights timers and counters - trace developer guide - memory insights - networking insights - task graph insights - slate insights - stat commands - graphics programming overview - common performance considerations pages were checked against ue 5.8 documentation on 2026-07-19. reconfirm channel presets, platform support, trace overhead, command syntax, and export commands after an engine upgrade. timing insights and cpu timing insights and cpu capture launch with a narrow set such as: text -trace=default,cpu,frame,bookmark or start a file capture at runtime: text trace.file perfcase.utrace cpu,frame,bookmark trace.bookmark warmupcomplete trace.bookmark testbegin trace.bookmark testend trace.stop without an explicit path, trace files go under saved/profiling. check active channels with trace.status. use trace.enable, trace.disable, trace.pause, and trace.resume to reduce unwanted data, but do not expect late-enabled channels to reconstruct prior events. analyze 1. select only the marked test interval. 2. inspect game, render, rhi, worker, and named threads; do not rank timers across unrelated frames. 3. sort timer aggregation by inclusive time to find large subtrees, then exclusive time to find the scope itself. high inclusive/low exclusive cost means the children own the time. 4. inspect call count. a small scope called thousands of times may need structural batching. 5. open a slow frame and follow the critical dependency path, waits, task prerequisites, and long serial regions. 6. compare median/typical frames separately from worst hitches. common cpu shapes - long game-thread scope -> gameplay/blueprint/tick/ai/physics/gc work. - render-thread submissions -> primitive count, material sections, visibility, shadow/light setup. - worker tasks complete after parent waits -> imbalance, insufficient parallel work, dependency chain. - large gaps/waits -> synchronization, io, locks, frame cap, or starvation; not necessarily \"free cpu.\" - thousands of tiny events -> per-object/tick architecture, dispatch overhead, or trace over-detail. tool selector tool selector | question | start with | escalate to | |---|---|---| | which side owns the frame? | stat unit, stat unitgraph | timing insights + gpu events | | which cpu scope/thread is slow? | timing insights cpu tracks | task/context-switch trace, custom scopes | | which gpu pass is slow? | stat gpu, profilegpu | gpu trace, renderdoc/platform profiler | | why did one frame hitch? | stat unitgraph, bookmark | timing insights, load/file/gc tracks | | why is memory growing? | platform/llm stats | memory insights from process start | | which asset loaded or blocked? | async-loading stats | asset loading insights + file/loadtime channels | | what consumes bandwidth? | stat net where applicable | networking insights packet/content/stats | | are tasks waiting or serialized? | cpu trace | task graph + context-switch channels | | is ui/slate expensive? | stat slate, stat ui | slate trace/insights tracks | | did a change regress? | repeatable stat/trace capture | exported timer statistics in ci | use renderdoc or a platform graphics debugger for pipeline/resource correctness inside one frame; use insights and profilegpu to decide which frame/pass deserves that inspection.","references":[{"slug":"capture-contract","file":"capture-contract.md","title":"Capture contract","rawMarkdown":"# Capture contract\n\nRecord this metadata before interpreting a trace:\n\n| Field | Required value |\n|---|---|\n| Target | platform, device model/CPU/GPU/RAM, driver/OS |\n| Build | changelist/commit, Development/Test/Shipping, packaged/editor |\n| Display | output resolution, screen percentage/dynamic resolution, refresh/VSync |\n| Quality | device profile, scalability groups, ray tracing/upscaler path |\n| Workload | map, save/state, camera path, player/AI/effect counts, duration |\n| Budget | frame ms and percentile/hitch threshold; memory/load/net budget if relevant |\n| Capture | command line, channels, warm-up, marked start/end, trace filename |\n\nFrame budgets before platform overhead or safety margin:\n\n| Target | Frame time |\n|---|---:|\n| 30 fps | 33.33 ms |\n| 60 fps | 16.67 ms |\n| 90 fps | 11.11 ms |\n| 120 fps | 8.33 ms |\n\nUse a repeatable traversal or automated scenario. Warm shader/asset caches only when measuring\nsteady state; preserve a cold-start run when first-use hitch or loading is the question. Record both\nif players experience both.\n\nReject comparisons that changed more than the intended variable, ran different content paths, used\ndifferent thermal/power states, or silently changed resolution/scalability.\n","webMarkdown":"Record this metadata before interpreting a trace:\n\n| Field | Required value |\n|---|---|\n| Target | platform, device model/CPU/GPU/RAM, driver/OS |\n| Build | changelist/commit, Development/Test/Shipping, packaged/editor |\n| Display | output resolution, screen percentage/dynamic resolution, refresh/VSync |\n| Quality | device profile, scalability groups, ray tracing/upscaler path |\n| Workload | map, save/state, camera path, player/AI/effect counts, duration |\n| Budget | frame ms and percentile/hitch threshold; memory/load/net budget if relevant |\n| Capture | command line, channels, warm-up, marked start/end, trace filename |\n\nFrame budgets before platform overhead or safety margin:\n\n| Target | Frame time |\n|---|---:|\n| 30 fps | 33.33 ms |\n| 60 fps | 16.67 ms |\n| 90 fps | 11.11 ms |\n| 120 fps | 8.33 ms |\n\nUse a repeatable traversal or automated scenario. Warm shader/asset caches only when measuring\nsteady state; preserve a cold-start run when first-use hitch or loading is the question. Record both\nif players experience both.\n\nReject comparisons that changed more than the intended variable, ran different content paths, used\ndifferent thermal/power states, or silently changed resolution/scalability.\n","searchText":"capture contract record this metadata before interpreting a trace: | field | required value | |---|---| | target | platform, device model/cpu/gpu/ram, driver/os | | build | changelist/commit, development/test/shipping, packaged/editor | | display | output resolution, screen percentage/dynamic resolution, refresh/vsync | | quality | device profile, scalability groups, ray tracing/upscaler path | | workload | map, save/state, camera path, player/ai/effect counts, duration | | budget | frame ms and percentile/hitch threshold; memory/load/net budget if relevant | | capture | command line, channels, warm-up, marked start/end, trace filename | frame budgets before platform overhead or safety margin: | target | frame time | |---|---:| | 30 fps | 33.33 ms | | 60 fps | 16.67 ms | | 90 fps | 11.11 ms | | 120 fps | 8.33 ms | use a repeatable traversal or automated scenario. warm shader/asset caches only when measuring steady state; preserve a cold-start run when first-use hitch or loading is the question. record both if players experience both. reject comparisons that changed more than the intended variable, ran different content paths, used different thermal/power states, or silently changed resolution/scalability."},{"slug":"first-pass-triage","file":"first-pass-triage.md","title":"First-pass triage","rawMarkdown":"# First-pass triage\n\n## Establish the bound\n\n1. Run a non-Debug build with the target device profile and resolution.\n2. Disable smoothing/VSync/frame caps only when they conceal the bound; record the change.\n3. Enter `stat unit`; add `stat unitgraph` and `stat raw` when spikes or filtering matter.\n4. Reproduce the workload for a fixed interval.\n5. Compare Frame with Game, Draw, RHIT, and GPU.\n\nInterpretation:\n\n| Pattern | Working classification | Next capture |\n|---|---|---|\n| Frame follows Game | game-thread bound | CPU/frame/bookmark; inspect Game thread |\n| Frame follows Draw | render-thread bound | CPU/frame/gpu; inspect rendering submission |\n| Frame follows RHIT | RHI/submission/driver bound | CPU/GPU plus platform graphics profiler |\n| GPU stands alone near Frame | GPU bound | `profilegpu`, GPU trace |\n| all appear below Frame | cap, wait, sync, present, task dependency | timing + context switch; inspect waits |\n| rare raw spikes | hitch | bookmark and narrow hitch capture |\n\n`stat unit` is directional, not final proof. Parallel CPU and GPU work, pipelining, idle time, VSync,\nand asynchronous compute can make similar numbers misleading.\n\n## Fast probes\n\n- Lower primary resolution/screen percentage while holding content constant. A material GPU gain\n  implicates pixel/resolution-scaled work; no gain does not prove a CPU bottleneck.\n- Pause or freeze simulation to separate simulation-fed rendering changes from a stable frame.\n- Disable one major feature with a supported CVar for diagnosis, then restore it. Treat the delta as\n  attribution evidence, not automatically as the shipping fix.\n- Use `stat sceneRendering`, `stat rhi`, `stat gpu`, `stat game`, `stat anim`, `stat slate`, or the\n  subsystem stat only after the first bound is known.\n","webMarkdown":"## Establish the bound\n\n1. Run a non-Debug build with the target device profile and resolution.\n2. Disable smoothing/VSync/frame caps only when they conceal the bound; record the change.\n3. Enter `stat unit`; add `stat unitgraph` and `stat raw` when spikes or filtering matter.\n4. Reproduce the workload for a fixed interval.\n5. Compare Frame with Game, Draw, RHIT, and GPU.\n\nInterpretation:\n\n| Pattern | Working classification | Next capture |\n|---|---|---|\n| Frame follows Game | game-thread bound | CPU/frame/bookmark; inspect Game thread |\n| Frame follows Draw | render-thread bound | CPU/frame/gpu; inspect rendering submission |\n| Frame follows RHIT | RHI/submission/driver bound | CPU/GPU plus platform graphics profiler |\n| GPU stands alone near Frame | GPU bound | `profilegpu`, GPU trace |\n| all appear below Frame | cap, wait, sync, present, task dependency | timing + context switch; inspect waits |\n| rare raw spikes | hitch | bookmark and narrow hitch capture |\n\n`stat unit` is directional, not final proof. Parallel CPU and GPU work, pipelining, idle time, VSync,\nand asynchronous compute can make similar numbers misleading.\n\n## Fast probes\n\n- Lower primary resolution/screen percentage while holding content constant. A material GPU gain\n  implicates pixel/resolution-scaled work; no gain does not prove a CPU bottleneck.\n- Pause or freeze simulation to separate simulation-fed rendering changes from a stable frame.\n- Disable one major feature with a supported CVar for diagnosis, then restore it. Treat the delta as\n  attribution evidence, not automatically as the shipping fix.\n- Use `stat sceneRendering`, `stat rhi`, `stat gpu`, `stat game`, `stat anim`, `stat slate`, or the\n  subsystem stat only after the first bound is known.\n","searchText":"first-pass triage establish the bound 1. run a non-debug build with the target device profile and resolution. 2. disable smoothing/vsync/frame caps only when they conceal the bound; record the change. 3. enter stat unit; add stat unitgraph and stat raw when spikes or filtering matter. 4. reproduce the workload for a fixed interval. 5. compare frame with game, draw, rhit, and gpu. interpretation: | pattern | working classification | next capture | |---|---|---| | frame follows game | game-thread bound | cpu/frame/bookmark; inspect game thread | | frame follows draw | render-thread bound | cpu/frame/gpu; inspect rendering submission | | frame follows rhit | rhi/submission/driver bound | cpu/gpu plus platform graphics profiler | | gpu stands alone near frame | gpu bound | profilegpu, gpu trace | | all appear below frame | cap, wait, sync, present, task dependency | timing + context switch; inspect waits | | rare raw spikes | hitch | bookmark and narrow hitch capture | stat unit is directional, not final proof. parallel cpu and gpu work, pipelining, idle time, vsync, and asynchronous compute can make similar numbers misleading. fast probes - lower primary resolution/screen percentage while holding content constant. a material gpu gain implicates pixel/resolution-scaled work; no gain does not prove a cpu bottleneck. - pause or freeze simulation to separate simulation-fed rendering changes from a stable frame. - disable one major feature with a supported cvar for diagnosis, then restore it. treat the delta as attribution evidence, not automatically as the shipping fix. - use stat scenerendering, stat rhi, stat gpu, stat game, stat anim, stat slate, or the subsystem stat only after the first bound is known."},{"slug":"gpu-and-render-thread","file":"gpu-and-render-thread.md","title":"GPU and render thread","rawMarkdown":"# GPU and render thread\n\n## Attribute GPU cost\n\n1. Confirm GPU is plausibly the bound with `stat unit`.\n2. Run `stat gpu` for a live overview.\n3. Capture one representative frame with `profilegpu` or `Ctrl+Shift+;`.\n4. Expand the event tree from the largest millisecond pass to its children.\n5. Repeat at the same camera, resolution, screen percentage, and quality.\n6. Toggle one supported renderer feature or quality control and compare the same pass.\n\nGPU time may contain idle time. Asynchronous compute overlaps passes, so individual event totals can\noverlap or appear inflated. Disable async compute only for isolated diagnosis when Epic's subsystem\nguide explicitly recommends it; restore it for the real end-to-end measurement.\n\n## Separate submission from shading\n\n| Evidence | Likely direction |\n|---|---|\n| Draw/Render thread dominates, many primitives/sections | reduce submissions, components, sections, visibility work |\n| GPU base pass dominates | material/pixel coverage/geometry path |\n| shadows dominate | light/shadow method, invalidation, caster coverage |\n| translucency/post dominates | screen coverage, layer count, resolution, effect quality |\n| lowering resolution helps strongly | pixel-bound passes/upscaler tradeoff |\n| lowering resolution barely helps | geometry/submission/CPU or fixed-cost GPU work |\n\nUse the rendering-performance skill only after the pass or submission cost is identified.\n","webMarkdown":"## Attribute GPU cost\n\n1. Confirm GPU is plausibly the bound with `stat unit`.\n2. Run `stat gpu` for a live overview.\n3. Capture one representative frame with `profilegpu` or `Ctrl+Shift+;`.\n4. Expand the event tree from the largest millisecond pass to its children.\n5. Repeat at the same camera, resolution, screen percentage, and quality.\n6. Toggle one supported renderer feature or quality control and compare the same pass.\n\nGPU time may contain idle time. Asynchronous compute overlaps passes, so individual event totals can\noverlap or appear inflated. Disable async compute only for isolated diagnosis when Epic's subsystem\nguide explicitly recommends it; restore it for the real end-to-end measurement.\n\n## Separate submission from shading\n\n| Evidence | Likely direction |\n|---|---|\n| Draw/Render thread dominates, many primitives/sections | reduce submissions, components, sections, visibility work |\n| GPU base pass dominates | material/pixel coverage/geometry path |\n| shadows dominate | light/shadow method, invalidation, caster coverage |\n| translucency/post dominates | screen coverage, layer count, resolution, effect quality |\n| lowering resolution helps strongly | pixel-bound passes/upscaler tradeoff |\n| lowering resolution barely helps | geometry/submission/CPU or fixed-cost GPU work |\n\nUse the rendering-performance skill only after the pass or submission cost is identified.\n","searchText":"gpu and render thread attribute gpu cost 1. confirm gpu is plausibly the bound with stat unit. 2. run stat gpu for a live overview. 3. capture one representative frame with profilegpu or ctrl+shift+;. 4. expand the event tree from the largest millisecond pass to its children. 5. repeat at the same camera, resolution, screen percentage, and quality. 6. toggle one supported renderer feature or quality control and compare the same pass. gpu time may contain idle time. asynchronous compute overlaps passes, so individual event totals can overlap or appear inflated. disable async compute only for isolated diagnosis when epic's subsystem guide explicitly recommends it; restore it for the real end-to-end measurement. separate submission from shading | evidence | likely direction | |---|---| | draw/render thread dominates, many primitives/sections | reduce submissions, components, sections, visibility work | | gpu base pass dominates | material/pixel coverage/geometry path | | shadows dominate | light/shadow method, invalidation, caster coverage | | translucency/post dominates | screen coverage, layer count, resolution, effect quality | | lowering resolution helps strongly | pixel-bound passes/upscaler tradeoff | | lowering resolution barely helps | geometry/submission/cpu or fixed-cost gpu work | use the rendering-performance skill only after the pass or submission cost is identified."},{"slug":"hitches-loading-and-gc","file":"hitches-loading-and-gc.md","title":"Hitches, loading, and garbage collection","rawMarkdown":"# Hitches, loading, and garbage collection\n\n## Capture a hitch\n\n1. Set an explicit hitch threshold for the target experience; use `stat hitches` or `stat dumphitches`\n   for fast detection where useful.\n2. Display `stat unitgraph`, toggle `stat raw`, and reproduce the hitch.\n3. Add bookmarks immediately before/after the action that triggers it.\n4. Trace `cpu,frame,bookmark` plus only the suspected channel: `loadtime`, `file`, or `stats`.\n5. Inspect the exact slow frame and the preceding work; asynchronous requests often cause a later wait.\n\n## Symptom routing\n\n| Hitch shape | Inspect |\n|---|---|\n| first use of asset/effect | async load, shader/PSO readiness, construction, audio decode |\n| periodic spike | GC, streaming update, autosave/telemetry, scheduled subsystem |\n| entering region | World Partition/level/texture/Nanite streaming and file IO |\n| mass spawn/despawn | object construction, registration, physics/nav, GC pressure |\n| camera cut | visibility burst, VSM pages, streaming, post/upscaler history |\n\nFor loading, correlate Asset Loading events with file reads and Game-thread waits. A long async load is\nnot necessarily a hitch unless the critical thread blocks for it or the workload saturates IO/CPU.\n\nFor GC, inspect allocation/object churn before the collection, collection duration, unreachable-object\nprocessing, and post-GC work. Reduce avoidable churn or distribute work; do not merely raise the GC\ninterval if that creates a larger eventual pause or excess memory.\n","webMarkdown":"## Capture a hitch\n\n1. Set an explicit hitch threshold for the target experience; use `stat hitches` or `stat dumphitches`\n   for fast detection where useful.\n2. Display `stat unitgraph`, toggle `stat raw`, and reproduce the hitch.\n3. Add bookmarks immediately before/after the action that triggers it.\n4. Trace `cpu,frame,bookmark` plus only the suspected channel: `loadtime`, `file`, or `stats`.\n5. Inspect the exact slow frame and the preceding work; asynchronous requests often cause a later wait.\n\n## Symptom routing\n\n| Hitch shape | Inspect |\n|---|---|\n| first use of asset/effect | async load, shader/PSO readiness, construction, audio decode |\n| periodic spike | GC, streaming update, autosave/telemetry, scheduled subsystem |\n| entering region | World Partition/level/texture/Nanite streaming and file IO |\n| mass spawn/despawn | object construction, registration, physics/nav, GC pressure |\n| camera cut | visibility burst, VSM pages, streaming, post/upscaler history |\n\nFor loading, correlate Asset Loading events with file reads and Game-thread waits. A long async load is\nnot necessarily a hitch unless the critical thread blocks for it or the workload saturates IO/CPU.\n\nFor GC, inspect allocation/object churn before the collection, collection duration, unreachable-object\nprocessing, and post-GC work. Reduce avoidable churn or distribute work; do not merely raise the GC\ninterval if that creates a larger eventual pause or excess memory.\n","searchText":"hitches, loading, and garbage collection capture a hitch 1. set an explicit hitch threshold for the target experience; use stat hitches or stat dumphitches for fast detection where useful. 2. display stat unitgraph, toggle stat raw, and reproduce the hitch. 3. add bookmarks immediately before/after the action that triggers it. 4. trace cpu,frame,bookmark plus only the suspected channel: loadtime, file, or stats. 5. inspect the exact slow frame and the preceding work; asynchronous requests often cause a later wait. symptom routing | hitch shape | inspect | |---|---| | first use of asset/effect | async load, shader/pso readiness, construction, audio decode | | periodic spike | gc, streaming update, autosave/telemetry, scheduled subsystem | | entering region | world partition/level/texture/nanite streaming and file io | | mass spawn/despawn | object construction, registration, physics/nav, gc pressure | | camera cut | visibility burst, vsm pages, streaming, post/upscaler history | for loading, correlate asset loading events with file reads and game-thread waits. a long async load is not necessarily a hitch unless the critical thread blocks for it or the workload saturates io/cpu. for gc, inspect allocation/object churn before the collection, collection duration, unreachable-object processing, and post-gc work. reduce avoidable churn or distribute work; do not merely raise the gc interval if that creates a larger eventual pause or excess memory."},{"slug":"instrumentation-and-exports","file":"instrumentation-and-exports.md","title":"Instrumentation and exports","rawMarkdown":"# Instrumentation and exports\n\nUse built-in trace events before inventing a custom event stream.\n\n## C++ instrumentation\n\n- Wrap important CPU scopes with the `TRACE_CPUPROFILER_EVENT_SCOPE_*` macro family.\n- Emit `TRACE_BOOKMARK` for infrequent state transitions such as entering a boss phase or opening a\n  menu.\n- Use trace counters for quantities that change frequently: active enemies, queued requests, bytes,\n  or pool occupancy.\n- Use `LLM_SCOPE` tags for memory categories that should appear in LLM and allocation traces.\n\nDo not emit per-object bookmarks every frame. Excess instrumentation changes the workload and can\nmake traces too large to analyze.\n\n## Export for repeatable analysis\n\nUnreal Insights supports headless analysis and response commands. A representative invocation is:\n\n```text\nUnrealInsights.exe -OpenTraceFile=path/file.utrace -AutoQuit -NoUI -ExecOnAnalysisCompleteCmd=\"@=D:\\Tests\\export.rsp\"\n```\n\nUse `TimingInsights.ExportTimerStatistics` in the response workflow to export aggregate timer data for\nnamed regions. Store the response file, capture contract, and threshold logic beside the test. Keep\nraw `.utrace` files for regressions that require timeline inspection; CSV summaries cannot explain\ndependencies or wait chains by themselves.\n","webMarkdown":"Use built-in trace events before inventing a custom event stream.\n\n## C++ instrumentation\n\n- Wrap important CPU scopes with the `TRACE_CPUPROFILER_EVENT_SCOPE_*` macro family.\n- Emit `TRACE_BOOKMARK` for infrequent state transitions such as entering a boss phase or opening a\n  menu.\n- Use trace counters for quantities that change frequently: active enemies, queued requests, bytes,\n  or pool occupancy.\n- Use `LLM_SCOPE` tags for memory categories that should appear in LLM and allocation traces.\n\nDo not emit per-object bookmarks every frame. Excess instrumentation changes the workload and can\nmake traces too large to analyze.\n\n## Export for repeatable analysis\n\nUnreal Insights supports headless analysis and response commands. A representative invocation is:\n\n```text\nUnrealInsights.exe -OpenTraceFile=path/file.utrace -AutoQuit -NoUI -ExecOnAnalysisCompleteCmd=\"@=D:\\Tests\\export.rsp\"\n```\n\nUse `TimingInsights.ExportTimerStatistics` in the response workflow to export aggregate timer data for\nnamed regions. Store the response file, capture contract, and threshold logic beside the test. Keep\nraw `.utrace` files for regressions that require timeline inspection; CSV summaries cannot explain\ndependencies or wait chains by themselves.\n","searchText":"instrumentation and exports use built-in trace events before inventing a custom event stream. c++ instrumentation - wrap important cpu scopes with the tracecpuprofilereventscope macro family. - emit tracebookmark for infrequent state transitions such as entering a boss phase or opening a menu. - use trace counters for quantities that change frequently: active enemies, queued requests, bytes, or pool occupancy. - use llmscope tags for memory categories that should appear in llm and allocation traces. do not emit per-object bookmarks every frame. excess instrumentation changes the workload and can make traces too large to analyze. export for repeatable analysis unreal insights supports headless analysis and response commands. a representative invocation is: text unrealinsights.exe -opentracefile=path/file.utrace -autoquit -noui -execonanalysiscompletecmd=\"@=d:\\tests\\export.rsp\" use timinginsights.exporttimerstatistics in the response workflow to export aggregate timer data for named regions. store the response file, capture contract, and threshold logic beside the test. keep raw .utrace files for regressions that require timeline inspection; csv summaries cannot explain dependencies or wait chains by themselves."},{"slug":"memory-insights","file":"memory-insights.md","title":"Memory Insights","rawMarkdown":"# Memory Insights\n\nAllocation tracing must be enabled from process start. For a packaged project, use Development mode.\n\n```text\nMyGame.exe -trace=default,memory\nMyGame.exe -trace=default,memory,metadata,assetmetadata\n```\n\nThe metadata channels enable asset/class filtering but add trace cost and volume. Select them only\nwhen the question requires attribution at that level.\n\n## Query patterns\n\n| Question | Comparison/query |\n|---|---|\n| What is live at time T? | live allocations at T, grouped by tag/callstack |\n| What grew during action A? | allocations between pre-A and post-A markers still live afterward |\n| Is it a leak? | repeat A several times; inspect monotonic retained growth after cleanup |\n| What churns? | high allocation/free event rate with limited net growth |\n| Which asset/class owns memory? | metadata/assetmetadata grouping and callstacks |\n\nCorrelate detailed allocation graphs, LLM tag tracks, modules, and Timing events. Distinguish:\n\n- committed/resident/platform memory from traced allocations;\n- CPU memory from GPU memory;\n- cache growth that stabilizes from unbounded retained growth;\n- expected streaming residency from leaked ownership.\n\nCapture startup when startup allocations matter. Late connect cannot reconstruct allocations made\nbefore the memory channel was active.\n","webMarkdown":"Allocation tracing must be enabled from process start. For a packaged project, use Development mode.\n\n```text\nMyGame.exe -trace=default,memory\nMyGame.exe -trace=default,memory,metadata,assetmetadata\n```\n\nThe metadata channels enable asset/class filtering but add trace cost and volume. Select them only\nwhen the question requires attribution at that level.\n\n## Query patterns\n\n| Question | Comparison/query |\n|---|---|\n| What is live at time T? | live allocations at T, grouped by tag/callstack |\n| What grew during action A? | allocations between pre-A and post-A markers still live afterward |\n| Is it a leak? | repeat A several times; inspect monotonic retained growth after cleanup |\n| What churns? | high allocation/free event rate with limited net growth |\n| Which asset/class owns memory? | metadata/assetmetadata grouping and callstacks |\n\nCorrelate detailed allocation graphs, LLM tag tracks, modules, and Timing events. Distinguish:\n\n- committed/resident/platform memory from traced allocations;\n- CPU memory from GPU memory;\n- cache growth that stabilizes from unbounded retained growth;\n- expected streaming residency from leaked ownership.\n\nCapture startup when startup allocations matter. Late connect cannot reconstruct allocations made\nbefore the memory channel was active.\n","searchText":"memory insights allocation tracing must be enabled from process start. for a packaged project, use development mode. text mygame.exe -trace=default,memory mygame.exe -trace=default,memory,metadata,assetmetadata the metadata channels enable asset/class filtering but add trace cost and volume. select them only when the question requires attribution at that level. query patterns | question | comparison/query | |---|---| | what is live at time t? | live allocations at t, grouped by tag/callstack | | what grew during action a? | allocations between pre-a and post-a markers still live afterward | | is it a leak? | repeat a several times; inspect monotonic retained growth after cleanup | | what churns? | high allocation/free event rate with limited net growth | | which asset/class owns memory? | metadata/assetmetadata grouping and callstacks | correlate detailed allocation graphs, llm tag tracks, modules, and timing events. distinguish: - committed/resident/platform memory from traced allocations; - cpu memory from gpu memory; - cache growth that stabilizes from unbounded retained growth; - expected streaming residency from leaked ownership. capture startup when startup allocations matter. late connect cannot reconstruct allocations made before the memory channel was active."},{"slug":"network-task-and-ui","file":"network-task-and-ui.md","title":"Network, task graph, and UI traces","rawMarkdown":"# Network, task graph, and UI traces\n\n## Networking Insights\n\nStart each relevant client instance with:\n\n```text\n-trace=net -NetTrace=1\n```\n\nWhen tracing an editor instance to a separate local Insights store, add `-tracehost=localhost` as\nrequired. Choose verbosity greater than zero and raise it only when the missing packet detail justifies\nthe overhead.\n\nInspect packet sizes/timeline, connection direction, object/property/RPC content, inclusive/exclusive\nNet Stats, frequency, bursts, and retransmission/transport context. Optimize semantic frequency and\npayload ownership before compressing an already-wrong replication pattern.\n\n## Task Graph\n\nUse:\n\n```text\n-trace=default,task\n```\n\nInspect task prerequisites, worker occupancy, critical path, parent waits, queue delay, and task size.\nDo not split work into smaller tasks when scheduling overhead already dominates; do not merge tasks\nwhen one serial task blocks the frame and parallelism is available.\n\n## UI and Slate\n\nTriage with `stat slate`, `stat ui`, and widget-specific tools. Enable the built-in Slate Insights\nplugin and capture with `-trace=slate`. In Slate Frame View, correlate invalidation reasons, update\nreasons, layout/prepass, paint, volatility, draw-element growth, and Game/Render thread cost. Repeated\nfull-tree invalidation or per-frame binding work is usually a structural issue; confirm it in the trace\nbefore adding caches or invalidation panels.\n","webMarkdown":"## Networking Insights\n\nStart each relevant client instance with:\n\n```text\n-trace=net -NetTrace=1\n```\n\nWhen tracing an editor instance to a separate local Insights store, add `-tracehost=localhost` as\nrequired. Choose verbosity greater than zero and raise it only when the missing packet detail justifies\nthe overhead.\n\nInspect packet sizes/timeline, connection direction, object/property/RPC content, inclusive/exclusive\nNet Stats, frequency, bursts, and retransmission/transport context. Optimize semantic frequency and\npayload ownership before compressing an already-wrong replication pattern.\n\n## Task Graph\n\nUse:\n\n```text\n-trace=default,task\n```\n\nInspect task prerequisites, worker occupancy, critical path, parent waits, queue delay, and task size.\nDo not split work into smaller tasks when scheduling overhead already dominates; do not merge tasks\nwhen one serial task blocks the frame and parallelism is available.\n\n## UI and Slate\n\nTriage with `stat slate`, `stat ui`, and widget-specific tools. Enable the built-in Slate Insights\nplugin and capture with `-trace=slate`. In Slate Frame View, correlate invalidation reasons, update\nreasons, layout/prepass, paint, volatility, draw-element growth, and Game/Render thread cost. Repeated\nfull-tree invalidation or per-frame binding work is usually a structural issue; confirm it in the trace\nbefore adding caches or invalidation panels.\n","searchText":"network, task graph, and ui traces networking insights start each relevant client instance with: text -trace=net -nettrace=1 when tracing an editor instance to a separate local insights store, add -tracehost=localhost as required. choose verbosity greater than zero and raise it only when the missing packet detail justifies the overhead. inspect packet sizes/timeline, connection direction, object/property/rpc content, inclusive/exclusive net stats, frequency, bursts, and retransmission/transport context. optimize semantic frequency and payload ownership before compressing an already-wrong replication pattern. task graph use: text -trace=default,task inspect task prerequisites, worker occupancy, critical path, parent waits, queue delay, and task size. do not split work into smaller tasks when scheduling overhead already dominates; do not merge tasks when one serial task blocks the frame and parallelism is available. ui and slate triage with stat slate, stat ui, and widget-specific tools. enable the built-in slate insights plugin and capture with -trace=slate. in slate frame view, correlate invalidation reasons, update reasons, layout/prepass, paint, volatility, draw-element growth, and game/render thread cost. repeated full-tree invalidation or per-frame binding work is usually a structural issue; confirm it in the trace before adding caches or invalidation panels."},{"slug":"regression-workflow","file":"regression-workflow.md","title":"Regression workflow","rawMarkdown":"# Regression workflow\n\n## Baseline and candidate\n\n1. Freeze scenario, device profile, build settings, camera/input script, warm/cold state, and duration.\n2. Run multiple baseline samples; retain raw traces and summary metrics.\n3. Apply one change.\n4. Run the same number of candidate samples in comparable thermal/background conditions.\n5. Compare milliseconds, memory, bandwidth, hitch count, and percentile relevant to the budget.\n6. Inspect a representative trace when the aggregate moved unexpectedly.\n\nMinimum report:\n\n| Metric | Baseline | Candidate | Delta | Budget | Result |\n|---|---:|---:|---:|---:|---|\n| median frame ms | | | | | |\n| p95/p99 or worst-frame ms | | | | | |\n| bound thread/pass ms | | | | | |\n| hitch count over threshold | | | | | |\n| memory/load/net metric | | | | | |\n\nDo not call a change a win when it shifts cost outside the sampled interval, trades a rare severe hitch\nfor a better average, changes image quality/gameplay, or exceeds another budget. Keep a safety margin;\nmeeting 16.67 ms only in an ideal trace is not a robust 60 fps target.\n","webMarkdown":"## Baseline and candidate\n\n1. Freeze scenario, device profile, build settings, camera/input script, warm/cold state, and duration.\n2. Run multiple baseline samples; retain raw traces and summary metrics.\n3. Apply one change.\n4. Run the same number of candidate samples in comparable thermal/background conditions.\n5. Compare milliseconds, memory, bandwidth, hitch count, and percentile relevant to the budget.\n6. Inspect a representative trace when the aggregate moved unexpectedly.\n\nMinimum report:\n\n| Metric | Baseline | Candidate | Delta | Budget | Result |\n|---|---:|---:|---:|---:|---|\n| median frame ms | | | | | |\n| p95/p99 or worst-frame ms | | | | | |\n| bound thread/pass ms | | | | | |\n| hitch count over threshold | | | | | |\n| memory/load/net metric | | | | | |\n\nDo not call a change a win when it shifts cost outside the sampled interval, trades a rare severe hitch\nfor a better average, changes image quality/gameplay, or exceeds another budget. Keep a safety margin;\nmeeting 16.67 ms only in an ideal trace is not a robust 60 fps target.\n","searchText":"regression workflow baseline and candidate 1. freeze scenario, device profile, build settings, camera/input script, warm/cold state, and duration. 2. run multiple baseline samples; retain raw traces and summary metrics. 3. apply one change. 4. run the same number of candidate samples in comparable thermal/background conditions. 5. compare milliseconds, memory, bandwidth, hitch count, and percentile relevant to the budget. 6. inspect a representative trace when the aggregate moved unexpectedly. minimum report: | metric | baseline | candidate | delta | budget | result | |---|---:|---:|---:|---:|---| | median frame ms | | | | | | | p95/p99 or worst-frame ms | | | | | | | bound thread/pass ms | | | | | | | hitch count over threshold | | | | | | | memory/load/net metric | | | | | | do not call a change a win when it shifts cost outside the sampled interval, trades a rare severe hitch for a better average, changes image quality/gameplay, or exceeds another budget. keep a safety margin; meeting 16.67 ms only in an ideal trace is not a robust 60 fps target."},{"slug":"sources","file":"sources.md","title":"UE 5.8 primary sources","rawMarkdown":"# UE 5.8 primary sources\n\n- [Introduction to Performance Profiling and Configuration](https://dev.epicgames.com/documentation/en-us/unreal-engine/introduction-to-performance-profiling-and-configuration-in-unreal-engine)\n- [Unreal Insights](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-insights-in-unreal-engine)\n- [Unreal Insights Trace Quick Start](https://dev.epicgames.com/documentation/en-us/unreal-engine/trace-quick-start-guide-in-unreal-engine)\n- [Unreal Insights Reference](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-insights-reference-in-unreal-engine-5)\n- [Timing Insights Timers and Counters](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-the-timers-and-counters-tabs-in-unreal-insights-for-unreal-engine)\n- [Trace Developer Guide](https://dev.epicgames.com/documentation/en-us/unreal-engine/developer-guide-to-tracing-in-unreal-engine)\n- [Memory Insights](https://dev.epicgames.com/documentation/en-us/unreal-engine/memory-insights-in-unreal-engine)\n- [Networking Insights](https://dev.epicgames.com/documentation/en-us/unreal-engine/networking-insights-in-unreal-engine)\n- [Task Graph Insights](https://dev.epicgames.com/documentation/en-us/unreal-engine/task-graph-insights-in-unreal-engine-5)\n- [Slate Insights](https://dev.epicgames.com/documentation/en-us/unreal-engine/slate-insights-in-unreal-engine)\n- [Stat Commands](https://dev.epicgames.com/documentation/en-us/unreal-engine/stat-commands-in-unreal-engine)\n- [Graphics Programming Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/graphics-programming-overview-for-unreal-engine)\n- [Common Performance Considerations](https://dev.epicgames.com/documentation/en-us/unreal-engine/common-memory-and-cpu-performance-considerations-in-unreal-engine)\n\nPages were checked against UE 5.8 documentation on 2026-07-19. Reconfirm channel presets,\nplatform support, trace overhead, command syntax, and export commands after an engine upgrade.\n","webMarkdown":"- [Introduction to Performance Profiling and Configuration](https://dev.epicgames.com/documentation/en-us/unreal-engine/introduction-to-performance-profiling-and-configuration-in-unreal-engine)\n- [Unreal Insights](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-insights-in-unreal-engine)\n- [Unreal Insights Trace Quick Start](https://dev.epicgames.com/documentation/en-us/unreal-engine/trace-quick-start-guide-in-unreal-engine)\n- [Unreal Insights Reference](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-insights-reference-in-unreal-engine-5)\n- [Timing Insights Timers and Counters](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-the-timers-and-counters-tabs-in-unreal-insights-for-unreal-engine)\n- [Trace Developer Guide](https://dev.epicgames.com/documentation/en-us/unreal-engine/developer-guide-to-tracing-in-unreal-engine)\n- [Memory Insights](https://dev.epicgames.com/documentation/en-us/unreal-engine/memory-insights-in-unreal-engine)\n- [Networking Insights](https://dev.epicgames.com/documentation/en-us/unreal-engine/networking-insights-in-unreal-engine)\n- [Task Graph Insights](https://dev.epicgames.com/documentation/en-us/unreal-engine/task-graph-insights-in-unreal-engine-5)\n- [Slate Insights](https://dev.epicgames.com/documentation/en-us/unreal-engine/slate-insights-in-unreal-engine)\n- [Stat Commands](https://dev.epicgames.com/documentation/en-us/unreal-engine/stat-commands-in-unreal-engine)\n- [Graphics Programming Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/graphics-programming-overview-for-unreal-engine)\n- [Common Performance Considerations](https://dev.epicgames.com/documentation/en-us/unreal-engine/common-memory-and-cpu-performance-considerations-in-unreal-engine)\n\nPages were checked against UE 5.8 documentation on 2026-07-19. Reconfirm channel presets,\nplatform support, trace overhead, command syntax, and export commands after an engine upgrade.\n","searchText":"ue 5.8 primary sources - introduction to performance profiling and configuration - unreal insights - unreal insights trace quick start - unreal insights reference - timing insights timers and counters - trace developer guide - memory insights - networking insights - task graph insights - slate insights - stat commands - graphics programming overview - common performance considerations pages were checked against ue 5.8 documentation on 2026-07-19. reconfirm channel presets, platform support, trace overhead, command syntax, and export commands after an engine upgrade."},{"slug":"timing-insights-cpu","file":"timing-insights-cpu.md","title":"Timing Insights and CPU","rawMarkdown":"# Timing Insights and CPU\n\n## Capture\n\nLaunch with a narrow set such as:\n\n```text\n-trace=default,cpu,frame,bookmark\n```\n\nOr start a file capture at runtime:\n\n```text\nTrace.File PerfCase.utrace cpu,frame,bookmark\nTrace.Bookmark WarmupComplete\nTrace.Bookmark TestBegin\nTrace.Bookmark TestEnd\nTrace.Stop\n```\n\nWithout an explicit path, trace files go under `Saved/Profiling`. Check active channels with\n`Trace.Status`. Use `Trace.Enable`, `Trace.Disable`, `Trace.Pause`, and `Trace.Resume` to reduce\nunwanted data, but do not expect late-enabled channels to reconstruct prior events.\n\n## Analyze\n\n1. Select only the marked test interval.\n2. Inspect Game, Render, RHI, worker, and named threads; do not rank timers across unrelated frames.\n3. Sort timer aggregation by inclusive time to find large subtrees, then exclusive time to find the\n   scope itself. High inclusive/low exclusive cost means the children own the time.\n4. Inspect call count. A small scope called thousands of times may need structural batching.\n5. Open a slow frame and follow the critical dependency path, waits, task prerequisites, and long\n   serial regions.\n6. Compare median/typical frames separately from worst hitches.\n\n## Common CPU shapes\n\n- Long Game-thread scope -> gameplay/Blueprint/tick/AI/physics/GC work.\n- Render-thread submissions -> primitive count, material sections, visibility, shadow/light setup.\n- Worker tasks complete after parent waits -> imbalance, insufficient parallel work, dependency chain.\n- Large gaps/waits -> synchronization, IO, locks, frame cap, or starvation; not necessarily \"free CPU.\"\n- Thousands of tiny events -> per-object/tick architecture, dispatch overhead, or trace over-detail.\n","webMarkdown":"## Capture\n\nLaunch with a narrow set such as:\n\n```text\n-trace=default,cpu,frame,bookmark\n```\n\nOr start a file capture at runtime:\n\n```text\nTrace.File PerfCase.utrace cpu,frame,bookmark\nTrace.Bookmark WarmupComplete\nTrace.Bookmark TestBegin\nTrace.Bookmark TestEnd\nTrace.Stop\n```\n\nWithout an explicit path, trace files go under `Saved/Profiling`. Check active channels with\n`Trace.Status`. Use `Trace.Enable`, `Trace.Disable`, `Trace.Pause`, and `Trace.Resume` to reduce\nunwanted data, but do not expect late-enabled channels to reconstruct prior events.\n\n## Analyze\n\n1. Select only the marked test interval.\n2. Inspect Game, Render, RHI, worker, and named threads; do not rank timers across unrelated frames.\n3. Sort timer aggregation by inclusive time to find large subtrees, then exclusive time to find the\n   scope itself. High inclusive/low exclusive cost means the children own the time.\n4. Inspect call count. A small scope called thousands of times may need structural batching.\n5. Open a slow frame and follow the critical dependency path, waits, task prerequisites, and long\n   serial regions.\n6. Compare median/typical frames separately from worst hitches.\n\n## Common CPU shapes\n\n- Long Game-thread scope -> gameplay/Blueprint/tick/AI/physics/GC work.\n- Render-thread submissions -> primitive count, material sections, visibility, shadow/light setup.\n- Worker tasks complete after parent waits -> imbalance, insufficient parallel work, dependency chain.\n- Large gaps/waits -> synchronization, IO, locks, frame cap, or starvation; not necessarily \"free CPU.\"\n- Thousands of tiny events -> per-object/tick architecture, dispatch overhead, or trace over-detail.\n","searchText":"timing insights and cpu capture launch with a narrow set such as: text -trace=default,cpu,frame,bookmark or start a file capture at runtime: text trace.file perfcase.utrace cpu,frame,bookmark trace.bookmark warmupcomplete trace.bookmark testbegin trace.bookmark testend trace.stop without an explicit path, trace files go under saved/profiling. check active channels with trace.status. use trace.enable, trace.disable, trace.pause, and trace.resume to reduce unwanted data, but do not expect late-enabled channels to reconstruct prior events. analyze 1. select only the marked test interval. 2. inspect game, render, rhi, worker, and named threads; do not rank timers across unrelated frames. 3. sort timer aggregation by inclusive time to find large subtrees, then exclusive time to find the scope itself. high inclusive/low exclusive cost means the children own the time. 4. inspect call count. a small scope called thousands of times may need structural batching. 5. open a slow frame and follow the critical dependency path, waits, task prerequisites, and long serial regions. 6. compare median/typical frames separately from worst hitches. common cpu shapes - long game-thread scope -> gameplay/blueprint/tick/ai/physics/gc work. - render-thread submissions -> primitive count, material sections, visibility, shadow/light setup. - worker tasks complete after parent waits -> imbalance, insufficient parallel work, dependency chain. - large gaps/waits -> synchronization, io, locks, frame cap, or starvation; not necessarily \"free cpu.\" - thousands of tiny events -> per-object/tick architecture, dispatch overhead, or trace over-detail."},{"slug":"tool-selector","file":"tool-selector.md","title":"Tool selector","rawMarkdown":"# Tool selector\n\n| Question | Start with | Escalate to |\n|---|---|---|\n| Which side owns the frame? | `stat unit`, `stat unitgraph` | Timing Insights + GPU events |\n| Which CPU scope/thread is slow? | Timing Insights CPU tracks | task/context-switch trace, custom scopes |\n| Which GPU pass is slow? | `stat gpu`, `profilegpu` | GPU trace, RenderDoc/platform profiler |\n| Why did one frame hitch? | `stat unitgraph`, bookmark | Timing Insights, load/file/GC tracks |\n| Why is memory growing? | platform/LLM stats | Memory Insights from process start |\n| Which asset loaded or blocked? | async-loading stats | Asset Loading Insights + file/loadtime channels |\n| What consumes bandwidth? | `stat net` where applicable | Networking Insights packet/content/stats |\n| Are tasks waiting or serialized? | CPU trace | Task Graph + context-switch channels |\n| Is UI/Slate expensive? | `stat slate`, `stat ui` | Slate trace/Insights tracks |\n| Did a change regress? | repeatable stat/trace capture | exported timer statistics in CI |\n\nUse RenderDoc or a platform graphics debugger for pipeline/resource correctness inside one frame;\nuse Insights and `profilegpu` to decide which frame/pass deserves that inspection.\n","webMarkdown":"| Question | Start with | Escalate to |\n|---|---|---|\n| Which side owns the frame? | `stat unit`, `stat unitgraph` | Timing Insights + GPU events |\n| Which CPU scope/thread is slow? | Timing Insights CPU tracks | task/context-switch trace, custom scopes |\n| Which GPU pass is slow? | `stat gpu`, `profilegpu` | GPU trace, RenderDoc/platform profiler |\n| Why did one frame hitch? | `stat unitgraph`, bookmark | Timing Insights, load/file/GC tracks |\n| Why is memory growing? | platform/LLM stats | Memory Insights from process start |\n| Which asset loaded or blocked? | async-loading stats | Asset Loading Insights + file/loadtime channels |\n| What consumes bandwidth? | `stat net` where applicable | Networking Insights packet/content/stats |\n| Are tasks waiting or serialized? | CPU trace | Task Graph + context-switch channels |\n| Is UI/Slate expensive? | `stat slate`, `stat ui` | Slate trace/Insights tracks |\n| Did a change regress? | repeatable stat/trace capture | exported timer statistics in CI |\n\nUse RenderDoc or a platform graphics debugger for pipeline/resource correctness inside one frame;\nuse Insights and `profilegpu` to decide which frame/pass deserves that inspection.\n","searchText":"tool selector | question | start with | escalate to | |---|---|---| | which side owns the frame? | stat unit, stat unitgraph | timing insights + gpu events | | which cpu scope/thread is slow? | timing insights cpu tracks | task/context-switch trace, custom scopes | | which gpu pass is slow? | stat gpu, profilegpu | gpu trace, renderdoc/platform profiler | | why did one frame hitch? | stat unitgraph, bookmark | timing insights, load/file/gc tracks | | why is memory growing? | platform/llm stats | memory insights from process start | | which asset loaded or blocked? | async-loading stats | asset loading insights + file/loadtime channels | | what consumes bandwidth? | stat net where applicable | networking insights packet/content/stats | | are tasks waiting or serialized? | cpu trace | task graph + context-switch channels | | is ui/slate expensive? | stat slate, stat ui | slate trace/insights tracks | | did a change regress? | repeatable stat/trace capture | exported timer statistics in ci | use renderdoc or a platform graphics debugger for pipeline/resource correctness inside one frame; use insights and profilegpu to decide which frame/pass deserves that inspection."}]}
{"slug":"unreal-landscape","name":"unreal-landscape","title":"Unreal 5.8 Landscape","description":"Operational Unreal Engine 5.8 guidance for Landscape creation and import, valid component topology, scale, sculpting, non-destructive Edit Layers, Landscape Patches and Splines, materials, Target Layers, physical surfaces, grass and foliage, Runtime Virtual Texturing, World Partition integration, Nanite Landscapes, collision, performance, and debugging. Use when designing, building, automating, profiling, or repairing terrain and outdoor-world workflows.","shortDescription":"Build and optimize Unreal landscapes","category":"World & AI","referenceCount":10,"rawMarkdown":"---\nname: unreal-landscape\ndescription: Operational Unreal Engine 5.8 guidance for Landscape creation and import, valid component topology, scale, sculpting, non-destructive Edit Layers, Landscape Patches and Splines, materials, Target Layers, physical surfaces, grass and foliage, Runtime Virtual Texturing, World Partition integration, Nanite Landscapes, collision, performance, and debugging. Use when designing, building, automating, profiling, or repairing terrain and outdoor-world workflows.\n---\n\n# Unreal 5.8 Landscape\n\n## Ownership boundary\n\nThis skill owns heightfield topology, sculpt/paint state, Landscape materials, terrain collision, and\nLandscape-specific Splines/Patches. Route generic path math to\n[`unreal-splines`](../unreal-splines/SKILL.md), procedural population to\n[`unreal-pcg`](../unreal-pcg/SKILL.md), and cell/source/Data Layer/HLOD policy to\n[`unreal-world-partition`](../unreal-world-partition/SKILL.md).\n\nRoute a terrain task to the smallest relevant reference. Tie terrain decisions to gameplay traversal, sightlines, collision, navigation, streaming, and target-device budgets.\n\n## Select the terrain representation\n\n- Use **Landscape** for large heightfield terrain that needs efficient LOD, painting, foliage, collision, and world streaming.\n- Use **Static Meshes/Nanite meshes** for caves, overhangs, vertical cliffs, floating geometry, small hero formations, or topology a heightfield cannot represent.\n- Combine them: Landscape supplies broad traversable ground; meshes supply silhouettes and non-heightfield forms.\n- Use **Landscape Splines** when a road/path must deform or paint terrain. Use a normal Spline Component when deformation is not required.\n- Use **Landscape Patches** for procedural, non-destructive height/weight edits baked into the final Landscape.\n- Use **PCG**, Landscape Grass, Foliage Mode, or Procedural Foliage according to output lifetime and authoring needs; do not let several systems own the same vegetation population.\n\nRead [selector-import-layout.md](references/selector-import-layout.md) before creating or importing a Landscape.\n\n## Route by task\n\n| Need | Load |\n|---|---|\n| Choose terrain system, import/export, establish scale | [selector-import-layout.md](references/selector-import-layout.md) |\n| Choose components, sections, quads, dimensions, resolution | [components-dimensions-scale.md](references/components-dimensions-scale.md) |\n| Sculpt non-destructively; use Edit Layers or Patches | [edit-layers-sculpting-patches.md](references/edit-layers-sculpting-patches.md) |\n| Build materials, paint Target Layers, physical surfaces | [materials-painting.md](references/materials-painting.md) |\n| Select Landscape Grass, foliage painting, procedural foliage, or PCG | [grass-foliage-pcg.md](references/grass-foliage-pcg.md) |\n| Build roads, water deformation, decals, and terrain/object blends | [splines-water-rvt.md](references/splines-water-rvt.md) |\n| Stream Landscape with World Partition | [world-partition-streaming.md](references/world-partition-streaming.md) |\n| Tune Nanite, LOD, collision, rendering, and memory | [nanite-performance-collision.md](references/nanite-performance-collision.md) |\n| Diagnose artifacts and run production test gates | [debugging-patterns.md](references/debugging-patterns.md) |\n| Verify claims and maturity | [sources.md](references/sources.md) |\n\n## Execute in this order\n\n1. State playable bounds, elevation range, smallest required terrain feature, movement agents, target hardware, and streaming model.\n2. Choose Landscape versus mesh ownership for each terrain form.\n3. Choose valid heightmap dimensions, component/section topology, XY vertex spacing, and Z scale before detailed authoring.\n4. Enable Edit Layers at creation and define a named layer stack: base import, broad sculpt, gameplay corrections, splines, patches, and paint as needed.\n5. Prove graybox traversal, slopes, sightlines, landmarks, collision, and navigation before expensive material/foliage work.\n6. Build a small material layer contract and matching Layer Info assets; validate physical surfaces.\n7. Add roads/water and other procedural deformation on dedicated special layers.\n8. Add vegetation with one clear owner per population and explicit collision/nav/HLOD requirements.\n9. Configure World Partition, Nanite, RVT, LOD, and collision only from measured needs.\n10. Rebuild derived data and test a cooked target build through representative and worst-case routes.\n\n## Hard rules\n\n- Landscape is a heightfield. Do not force caves, overhangs, or arbitrary topology into it.\n- **Edit Layers** store non-destructive height/weight edits; material **Target Layers** store named paint weights. Never use the terms interchangeably.\n- Component count and section count have CPU/draw-call cost. More resolution is not free terrain detail.\n- Do not rescale a finished Landscape casually. Scale changes invalidate assumptions about slope, texture density, foliage, collision, navigation, water, and world coordinates.\n- Nanite does not remove the non-Nanite Landscape data. UE 5.8 retains both for systems including RVT and water, increasing streaming and memory requirements.\n- A stale Nanite representation is not a trustworthy editor preview. Rebuild/save before visual or performance conclusions.\n- Do not paint gameplay-critical surface identity only into an unvalidated visual material. Confirm Layer Info and physical-material results through traces and movement/audio tests.\n- Do not use dense Actor Foliage for decoration; it costs like ordinary actors.\n- Never tune Landscape in the editor alone. Profile cooked target builds for rendering, collision, navigation, streaming, memory, and shader compilation.\n\n## Answer contract\n\nReturn:\n\n1. **Selected representation and assumptions**.\n2. **Topology and scale** — dimensions, components, sections, XY/Z scale, elevation range.\n3. **Ownership** — Edit Layers, Target Layers, splines/patches, vegetation system, streaming.\n4. **Exact actions and parameter effects**.\n5. **Performance, collision, navigation, and packaging consequences**.\n6. **Failure checks and recovery**.\n7. **Verification** — visible and measured pass criteria on target hardware.\n\nDo not invent a universal Landscape size, material-layer count, or component layout. Derive them from world extent, required precision, content density, and measured budgets.\n","webMarkdown":"## Ownership boundary\n\nThis skill owns heightfield topology, sculpt/paint state, Landscape materials, terrain collision, and\nLandscape-specific Splines/Patches. Route generic path math to\n[`unreal-splines`](/unreal/unreal-splines/), procedural population to\n[`unreal-pcg`](/unreal/unreal-pcg/), and cell/source/Data Layer/HLOD policy to\n[`unreal-world-partition`](/unreal/unreal-world-partition/).\n\nRoute a terrain task to the smallest relevant reference. Tie terrain decisions to gameplay traversal, sightlines, collision, navigation, streaming, and target-device budgets.\n\n## Select the terrain representation\n\n- Use **Landscape** for large heightfield terrain that needs efficient LOD, painting, foliage, collision, and world streaming.\n- Use **Static Meshes/Nanite meshes** for caves, overhangs, vertical cliffs, floating geometry, small hero formations, or topology a heightfield cannot represent.\n- Combine them: Landscape supplies broad traversable ground; meshes supply silhouettes and non-heightfield forms.\n- Use **Landscape Splines** when a road/path must deform or paint terrain. Use a normal Spline Component when deformation is not required.\n- Use **Landscape Patches** for procedural, non-destructive height/weight edits baked into the final Landscape.\n- Use **PCG**, Landscape Grass, Foliage Mode, or Procedural Foliage according to output lifetime and authoring needs; do not let several systems own the same vegetation population.\n\nRead [selector-import-layout.md](/unreal/unreal-landscape/selector-import-layout/) before creating or importing a Landscape.\n\n## Route by task\n\n| Need | Load |\n|---|---|\n| Choose terrain system, import/export, establish scale | [selector-import-layout.md](/unreal/unreal-landscape/selector-import-layout/) |\n| Choose components, sections, quads, dimensions, resolution | [components-dimensions-scale.md](/unreal/unreal-landscape/components-dimensions-scale/) |\n| Sculpt non-destructively; use Edit Layers or Patches | [edit-layers-sculpting-patches.md](/unreal/unreal-landscape/edit-layers-sculpting-patches/) |\n| Build materials, paint Target Layers, physical surfaces | [materials-painting.md](/unreal/unreal-landscape/materials-painting/) |\n| Select Landscape Grass, foliage painting, procedural foliage, or PCG | [grass-foliage-pcg.md](/unreal/unreal-landscape/grass-foliage-pcg/) |\n| Build roads, water deformation, decals, and terrain/object blends | [splines-water-rvt.md](/unreal/unreal-landscape/splines-water-rvt/) |\n| Stream Landscape with World Partition | [world-partition-streaming.md](/unreal/unreal-landscape/world-partition-streaming/) |\n| Tune Nanite, LOD, collision, rendering, and memory | [nanite-performance-collision.md](/unreal/unreal-landscape/nanite-performance-collision/) |\n| Diagnose artifacts and run production test gates | [debugging-patterns.md](/unreal/unreal-landscape/debugging-patterns/) |\n| Verify claims and maturity | [sources.md](/unreal/unreal-landscape/sources/) |\n\n## Execute in this order\n\n1. State playable bounds, elevation range, smallest required terrain feature, movement agents, target hardware, and streaming model.\n2. Choose Landscape versus mesh ownership for each terrain form.\n3. Choose valid heightmap dimensions, component/section topology, XY vertex spacing, and Z scale before detailed authoring.\n4. Enable Edit Layers at creation and define a named layer stack: base import, broad sculpt, gameplay corrections, splines, patches, and paint as needed.\n5. Prove graybox traversal, slopes, sightlines, landmarks, collision, and navigation before expensive material/foliage work.\n6. Build a small material layer contract and matching Layer Info assets; validate physical surfaces.\n7. Add roads/water and other procedural deformation on dedicated special layers.\n8. Add vegetation with one clear owner per population and explicit collision/nav/HLOD requirements.\n9. Configure World Partition, Nanite, RVT, LOD, and collision only from measured needs.\n10. Rebuild derived data and test a cooked target build through representative and worst-case routes.\n\n## Hard rules\n\n- Landscape is a heightfield. Do not force caves, overhangs, or arbitrary topology into it.\n- **Edit Layers** store non-destructive height/weight edits; material **Target Layers** store named paint weights. Never use the terms interchangeably.\n- Component count and section count have CPU/draw-call cost. More resolution is not free terrain detail.\n- Do not rescale a finished Landscape casually. Scale changes invalidate assumptions about slope, texture density, foliage, collision, navigation, water, and world coordinates.\n- Nanite does not remove the non-Nanite Landscape data. UE 5.8 retains both for systems including RVT and water, increasing streaming and memory requirements.\n- A stale Nanite representation is not a trustworthy editor preview. Rebuild/save before visual or performance conclusions.\n- Do not paint gameplay-critical surface identity only into an unvalidated visual material. Confirm Layer Info and physical-material results through traces and movement/audio tests.\n- Do not use dense Actor Foliage for decoration; it costs like ordinary actors.\n- Never tune Landscape in the editor alone. Profile cooked target builds for rendering, collision, navigation, streaming, memory, and shader compilation.\n\n## Answer contract\n\nReturn:\n\n1. **Selected representation and assumptions**.\n2. **Topology and scale** — dimensions, components, sections, XY/Z scale, elevation range.\n3. **Ownership** — Edit Layers, Target Layers, splines/patches, vegetation system, streaming.\n4. **Exact actions and parameter effects**.\n5. **Performance, collision, navigation, and packaging consequences**.\n6. **Failure checks and recovery**.\n7. **Verification** — visible and measured pass criteria on target hardware.\n\nDo not invent a universal Landscape size, material-layer count, or component layout. Derive them from world extent, required precision, content density, and measured budgets.\n","searchText":"unreal 5.8 landscape operational unreal engine 5.8 guidance for landscape creation and import, valid component topology, scale, sculpting, non-destructive edit layers, landscape patches and splines, materials, target layers, physical surfaces, grass and foliage, runtime virtual texturing, world partition integration, nanite landscapes, collision, performance, and debugging. use when designing, building, automating, profiling, or repairing terrain and outdoor-world workflows. components, dimensions, and scale components, dimensions, and scale topology landscape components are the base units for rendering, visibility, collision, and streaming proxies. all components in one landscape are square and use the same size. - a component uses one section or 2×2 sections. - a section is the unit of landscape lod transition. - each section is a draw call, and every component carries render-thread cpu cost. - valid component quad dimensions follow the landscape texture/mip layout: power-of-two vertices produce power-of-two-minus-one quads for one section, or power-of-two-minus-two component quads for 2×2 sections. - epic recommends no more than 1024 components for the largest landscapes; treat this as an upper guideline, not a target. use epic's valid-dimensions table or the creation ui rather than cropping an arbitrary image to “almost” fit. tradeoffs more, smaller components - finer culling and lod granularity; - smaller localized edit/stream units; - more component cpu overhead and potentially more section draw calls. fewer, larger components - lower component count; - coarser culling, lod, collision, and streaming granularity; - heavier individual visible/rebuild units. 2×2 subsections can provide the same terrain resolution with fewer components than four separate one-section components, but still create four section draw calls per component. xy scale xy scale defines vertex spacing in centimeters. at 100, adjacent vertices are one meter apart. - smaller spacing expresses smaller terrain features but covers less world area for the same heightmap and can increase pressure for more components. - larger spacing covers more area but produces coarser silhouettes, collision, slopes, and deformation. do not chase texture detail with geometry. use materials, normal/detail maps, meshes, decals, and vegetation for sub-vertex detail. z scale z scale maps 16-bit height values into world height. increasing it expands vertical range but also magnifies each height step and changes gameplay slopes. pick the range before sculpting and leave headroom for intentional edits. layout procedure 1. convert desired world width to centimeters. 2. choose the coarsest xy vertex spacing that still represents required gameplay terrain. 3. select a valid overall resolution and component topology that covers the extent. 4. calculate z scale from the source elevation range. 5. create a small representative slice with the intended topology. 6. test terrain silhouette, traversal, collision, navigation, lod, material, and edit speed. 7. profile component/section cost before committing the entire world. never infer from resolution alone two landscapes with the same vertex resolution can have different physical sizes, precision, component counts, and runtime behavior. always report resolution together with xy/z scale, section size, sections per component, and component count. debugging and production patterns debugging and production patterns diagnose by layer 1. topology — valid resolution, correct component/section layout, xy/z scale. 2. authoring stack — correct active edit layer, order, visibility, lock, alpha, procedural owner. 3. paint contract — material name, target layer, layer info type, filled base, weight data. 4. derived systems — splines, water, patches, grass/foliage/pcg, rvt, nanite, collision, navigation. 5. streaming — loaded region/proxy and dependent world partition cells. 6. runtime budget — shader, texture, virtual texture, geometry, shadow, instances, collision, i/o. useful visualizers and stats - landscape component/section/quads color overlays in manage mode. - view > landscape visualizers > layer debug for target layer channels. - lit > visualizers > layer contribution for edit layer contribution. - player collision and visibility collision view modes. - landscape.rendernanite 0/1 for controlled representation comparison. - stat virtualtexturing and stat virtualtexturememory for rvt. - stat unit, stat gpu, gpu visualizer, unreal insights. restore diagnostic overrides before final captures. common symptom table | symptom | first checks | |---|---| | tile seam/crack | source edge pixels, flip y, xy/z scale, proxy freshness, nanite skirt | | sculpt has no effect | wrong/locked edit layer, special procedural layer, alpha zero | | spline does not deform | missing spline edit layer, raise/lower disabled, width/falloff | | black/default material | compile error, missing layer info/base fill, sampler/permutation | | wrong physical surface | dominant target layer and physical material assignment | | grass missing | grass output name/mask, grass type, landscape-only boundary, culling | | rvt contribution missing | bounds, asset type, writer list, pass type, sort priority | | nanite visual stale | dirty proxy; build/save/cook nanite representation | | character floats/clips | collision mip or render displacement differs from collision | | navmesh breaks after sculpt | navigation not rebuilt or slope/step/agent settings no longer fit | production test matrix | axis | minimum cases | |---|---| | edit | sculpt/paint, undo, save/reload, layer reorder/hide, neighbor regions | | import | clean reimport, tiled seams, round-trip export, source checksum | | traversal | walk, fastest vehicle, steepest intended slope, world edge, teleport | | rendering | near/far, nanite on/off, scalability tiers, target feature levels | | surface | each target layer, transitions, traces, footsteps/effects | | derived | splines, water, patches, vegetation, pcg, nav, hlod/rvt | | build | pie, standalone, cooked development, shipping-equivalent target | | soak | repeated cross-world route and memory stabilization | acceptance - terrain supports intended mental map, sightlines, and traversal; - no missing collision or navigation at streaming/edit boundaries; - layer ownership is understandable and reversible; - derived data can be rebuilt reproducibly; - target frame, memory, disk, cook, and streaming budgets are met; - no final conclusion relies on stale nanite/rvt/nav/pcg data. edit layers, sculpting, and patches edit layers, sculpting, and patches edit layer contract landscape edit layers are stack-based, non-destructive containers for heightmap, weightmap, and visibility data. new landscapes enable them automatically in ue 5.8. the default project limit is eight and is configurable. use a small semantic stack, for example: text baseimport broadsculpt gameplaycorrections splineprocedural patchprocedural paintartdirection more layers increase evaluation, authoring, merge, and diagnosis cost. add a layer only when it represents distinct ownership or must be independently hidden/reordered. editing rules - lock completed/owned layers. - use visibility and layer contribution (lit > visualizers > layer contribution) to isolate effects. - record whether height/paint alpha is intentionally additive, subtractive, or zero. - erase on an edit layer removes that layer's contribution; it is not necessarily “sculpt terrain downward.” - collapse and collapse all layers are destructive. save/source-control before flattening. - deleting a layer deletes its height, weight, visibility, and assigned blueprint brush data. sculpting workflow 1. sculpt broad landforms before detail. 2. establish playable grades, ledges, sightlines, drainage/water bounds, and landmarks. 3. use smooth sparingly; repeated smoothing erases intentional terrain language. 4. put gameplay corrections on a separate layer so art changes cannot silently remove them. 5. rebuild/check collision and navmesh after meaningful height changes. 6. test movement agents and cameras, not only the landscape viewport. special procedural layers spline edit layer stores landscape spline deformation/paint. it accepts procedural spline data and cannot be hand-sculpted or painted. patch edit layer stores landscape patch components. patches can read textures/render targets and alter height/weight data. patch inputs are editor-only and results are baked into the final landscape, so the procedural source does not add runtime memory/performance by itself. use patches for reusable stamps, local terrain fitting, or actor-owned deformation that must remain editable. use ordinary sculpt layers for unique manual art. change validation after reordering, changing alpha, importing, or modifying a procedural layer: - isolate every layer contribution; - inspect boundaries between loaded regions/components; - recheck landscape splines, water, and patches; - validate painted target layers and physical surfaces; - rebuild nanite representation if enabled; - rebuild navigation and dependent pcg/hlod as applicable; - save/reload and cook a representative map. grass, foliage, and pcg grass, foliage, and pcg choose one owner per population | need | default system | boundary | |---|---|---| | material/paint-driven passive ground cover | landscape grass output + landscape grass type | works only with landscape terrain; coupled to material layer weights | | hand-authored instance painting | foliage mode + static mesh foliage | efficient instancing and direct art control | | ecological offline simulation | procedural foliage | experimental editor workflow in current documentation | | rule-driven spatial generation, exclusions, runtime generation | pcg | route graph implementation to $unreal-pcg | | unique behavior/identity | actor or pcg spawn actor | costs like actors; keep density low | do not simultaneously generate the same grass/tree class through landscape grass, foliage, and pcg. establish ownership, exclusion, regeneration, and source-control policy. landscape grass workflow 1. derive a mask from a named landscape target layer using landscapegrassoutput. 2. create a landscape grass type and entries for meshes, density, scale, rotation, alignment, and cull distances. 3. attach the grass type to the corresponding grass output input. 4. paint/fill the driving landscape layer. 5. validate density, collision expectations, shadows, wind, lod/nanite, and culling in a cooked build. landscape grass is appropriate for passive visual distribution. if individual plants need durable identity, interaction, or authoritative state, they are not merely grass instances. foliage mode workflow - prefer static mesh foliage for decoration; it is hardware-instanced and batched. - actor foliage has the rendering/gameplay cost of ordinary actors. use only where behavior requires it. - define slope, height, scale, alignment, collision, density scaling, cull distance, shadow, and navigation impact in governed foliage type assets. - use reapply deliberately; it can change many existing instances. - validate instance attachment after landscape edits and choose the ue 5.8 foliage snapping behavior intentionally. procedural foliage the current guide still places procedural foliage under experimental editor settings. use it only after validating plugin availability, resimulation determinism, source-control output, cook behavior, and iteration cost. performance and gameplay - use foliage.densityscale only for types configured to participate in scalability. - cull distances, lod/nanite, shadow policy, wpo/wind, overdraw, and material cost determine final expense—not draw calls alone. - collision on dense small foliage is usually wasteful; collision/navigation blockers on important trees require explicit testing. - rebuild or update navigation after collision-relevant vegetation changes. - treat visually dense forests as ai sightline and path-design content, not only rendering content. acceptance - no duplicate ownership; - deterministic regeneration where required; - no vegetation on roads, entrances, traversal clearance, or critical sightlines; - expected collision/nav/physical-surface behavior; - stable memory and frame time through density scalability extremes; - no visible cull/lod transition beyond the project's budget. landscape materials and painting landscape materials and painting keep three concepts separate - edit layer: non-destructive authoring stack for height/weight/visibility edits. - target layer: named weightmap channel exposed by the landscape material and painted/imported in paint mode. - layer info asset: defines storage/blending behavior and can associate a physical material with a target layer. names are case-insensitive in the material system but must remain stable and governed. renaming one side of the contract can turn a layer weight into zero. blend selector - use weight blending for mutually normalized base surfaces such as soil/grass/rock. - use alpha/non-weight blending for an independent overlay whose ordering is intentional. - use height blending when per-layer height data should influence the transition; verify zero-weight intersections and normal behavior. weight-blended layers share a normalized total. erasing a fully weighted layer cannot reveal a nonexistent underlying weight; paint the desired replacement layer instead. authoring workflow 1. define a small semantic layer list and required outputs: base color, normal, roughness, displacement, physical surface, grass mask, pcg mask. 2. build reusable material functions and parameters rather than duplicating graphs per layer. 3. create matching landscapelayerblend, landscapelayersample, or custom weight logic. 4. assign the material to a test landscape. 5. create the correct weight-blended or non weight-blended layer info for each target layer. 6. fill a deliberate base layer before local painting. 7. paint boundary, full-weight, zero-weight, steep-slope, distant-lod, and wet/snow overlay cases. 8. trace/test physical surfaces and derived grass/pcg masks. performance controls - every visible component compiles the material permutation needed by the layers used there. - use landscapelayerswitch to remove operations when a layer contributes zero in a region. - share samplers/material functions where correct and watch texture-sampler limits on target feature levels. - prefer a few meaningful layers to many nearly identical variants. - mobile technically supports multiple layers subject to sampler limits; epic recommends only three. treat target measurement as the deciding constraint. - use rvt when caching complex terrain shading or terrain/object blending produces a measured benefit, not as mandatory architecture. physical surface validation assign physical materials through the intended landscape layer/material path. test several points per surface, transitions, thin paint, and cooked builds with traces returning physical material. visual appearance and returned physical surface must agree wherever footsteps, effects, friction, or gameplay depend on it. common failures - black/default landscape: material compile error, missing layer info, no filled base layer, or unsupported sampler/permutation. - paint layer absent: name mismatch or material never samples it. - erase seems ineffective: weight normalization; paint the replacement layer. - wrong footsteps: dominant layer/physical material assignment differs from visual expectation. - shader explosion/hitch: too many expensive layers/combinations and unbounded permutations. nanite, performance, lod, and collision nanite, performance, lod, and collision nanite landscape boundary nanite can improve landscape rendering performance, especially with virtual shadow maps. it does not add source terrain detail or inherently improve image quality; the source data is identical. ue 5.8 keeps both representations at runtime: - nanite landscape data for nanite rendering; - non-nanite landscape data for systems including rvt, water, and other landscape functions. therefore nanite adds streaming and memory data. measure the total system rather than assuming “nanite replaces landscape lod.” workflow 1. capture non-nanite target performance and memory. 2. enable nanite on the landscape. 3. build nanite data through the documented landscape build/save path. 4. confirm every proxy is up to date before comparing visuals or timing. 5. inspect seams; enable nanite skirt and tune skirt depth only if needed. 6. if using nanite tessellation/displacement, validate material settings, rebuilt data, shadows, collision mismatch, and scalability. 7. compare gpu, cpu, memory, streaming, cook time, disk size, and edit iteration. landscape.nanite.liverebuildonmodification is experimental and live rebuild can significantly slow editing. keep it off by default and perform controlled rebuilds. epic's page also shows a differently ordered legacy spelling in prose; confirm the exact cvar through console help in the installed build before scripting it. landscape performance levers - component and section count; - visible component count and lod distribution; - material shader/texture cost and layer permutations; - grass/foliage instance count, wpo, shadows, overdraw, culling; - rvt page generation/uploads and pool memory; - nanite/vsm/tessellation cost; - collision mip and physics queries; - streaming and derived-data readiness. profile the dominant cost; do not apply every lever at once. collision mip - collision mip level controls complex/visibility collision detail. - simple collision mip level controls simple/player collision detail. - higher mip values reduce geometry/memory but increase mismatch from rendered terrain. - epic notes that common cases keep collision mip at 0 and simple collision mip at 1 or 2; validate against the actual movement/query requirements rather than adopting this blindly. - per-component overrides can reduce cost in inaccessible areas. render displacement/tessellation does not automatically redefine gameplay collision. keep visible displacement within the acceptable collision error or provide another collision/gameplay solution. target capture record: - stat unit, stat gpu, insights trace, gpu profile; - visible components/sections and draw calls; - landscape/material/gpu time; - texture, rvt, nanite, and total memory; - streaming hitches at fastest traversal; - collision query behavior and navigation rebuild/pathing; - cold cook/load and warm traversal. terrain selector, import, and initial layout terrain selector, import, and initial layout representation selector | requirement | default representation | |---|---| | broad continuous ground, hills, valleys | landscape | | cave, arch, overhang, vertical cut | static/nanite mesh integrated with landscape | | small isolated terrain prop | static mesh | | road that raises/lowers and paints terrain | landscape spline on a spline edit layer | | local procedural height/weight stamp | landscape patch on a patch edit layer | | runtime deformable arbitrary surface | a dedicated runtime deformation/mesh solution; landscape authoring is not the default | prototype the transition between landscape and meshes. hide seams through placement, material/rvt blending, decals, rocks, or vegetation; do not rely on a single shading trick. before creation/import record: - playable xy extent and non-playable vista extent; - minimum and maximum elevation, including depth below datum; - desired xy vertex spacing and smallest shape the heightfield must express; - valid heightmap resolution and component topology; - world partition use and tiled-import convention; - coordinate origin, tile naming/order, y-axis orientation, units, and z-scale formula; - source heightmap version and checksum/path for reproducibility. supported heightmap paths ue 5.8 supports 16-bit grayscale png, 8-bit .r8, 16-bit .r16, and raw with a json sidecar. prefer 16-bit source data for smooth elevation precision. target-layer weightmaps are normally single-channel 8-bit data. for a new landscape: 1. enter landscape mode (shift+2). 2. choose import from file or create new. 3. enable edit layers. 4. select the material only if its target layer contract is already known. 5. for world partition tiled import, set and record partition grid/region settings and accept the tiled path prompt. 6. confirm heightmap resolution, component topology, xy scale, z scale, and flip y axis before import. 7. import, then immediately verify seams, orientation, elevation extrema, and world size. z-scale calculation epic documents: text z scale = elevation range in meters × 100 × 0.001953125 the source range must include the full desired vertical span, not merely the height above sea level. document where the source zero/datum maps into the ue height range. existing landscape import modes - original: original resolution at gizmo location. - expand: expand data to fit. - resample: resample to the existing landscape. - subregion: import without resolution checks; used for world partition subregions. resampling changes data. keep the source and export a verification copy after the operation. acceptance - no tile rotation/flip/seam mismatch; - known world points match source coordinates and elevations; - slopes and plateaus support intended movement/camera; - a round-trip export records the blended result or selected edit layer intentionally; - the import can be repeated from a clean checkout with the same result. ue 5.8 primary sources ue 5.8 primary sources checked against epic's unreal engine 5.8 documentation on 2026-07-19. landscape core - landscape overview - creating landscapes - landscape technical guide - importing and exporting landscape heightmaps - editing landscapes - landscape edit layers - landscape patch system - landscape splines shading and population - landscape materials - landscape paint mode - foliage mode - procedural foliage tool - runtime virtual texturing - water system runtime and performance - using nanite with landscapes - landscape collision guide - world partition - ue 5.8 release notes maturity notes - core landscape, edit layers, materials, splines, foliage, collision, and world partition integration are documented production workflows. - landscape.nanite.liverebuildonmodification is experimental. - procedural foliage remains under experimental editor settings in the current guide. - procedural vegetation editor is experimental and is intentionally not a default workflow in this skill. prefer the current 5.8 page and installed-engine console help over remembered behavior from earlier releases. landscape splines, water, and rvt landscape splines, water, and rvt landscape spline workflow use when a road, path, riverbed, or embankment must deform and optionally paint the landscape. 1. create a dedicated spline edit layer. 2. author control points and segments in landscape manage mode. 3. set width, side falloff, end falloff, tangent/rotation, and segment direction. 4. enable raise terrain and/or lower terrain only where the segment should deform height. 5. assign layer name when the spline should paint a target layer. 6. assign spline meshes with consistent forward axis, collision, lod/nanite, and material policy. 7. inspect intersections, sharp curvature, component boundaries, landscape seams, and navigation. landscape splines do not affect height until a spline edit layer exists. route general spline motion or spline mesh implementation to $unreal-splines. water integration boundary the water plugin supplies spline-driven oceans, lakes, and rivers integrated with landscape. establish before authoring: - water body type and spline ownership; - landscape deformation/edit layer ownership; - water surface height and terrain datum; - shore/riverbank material transition; - collision, swimming/boat physics, nav, and gameplay volumes; - world partition loading and distant representation. do not let a water body, landscape spline, manual sculpt, and patch all deform the same bank without a documented stack order. verify the terrain with each layer isolated. rvt selector use runtime virtual texturing when it materially helps: - cache expensive landscape shading; - blend static meshes/spline roads into terrain; - add decal-like static surface contributions; - provide a common terrain/object material-data surface. rvt is a gpu-generated cache, not durable gameplay data. writers are expected to be static; skeletal, movable, or animated components are poor writers. rvt workflow 1. enable virtual texture support and restart. 2. create an rvt asset with a material type and memory/resolution plan. 3. make the landscape material write through runtimevirtualtextureoutput and sample/fallback intentionally. 4. place an rvt volume and set bounds from the landscape/required writers. 5. add the rvt asset to writer components and choose main pass behavior. 6. use world-space normals for consistent blending. 7. define sort priority when multiple alpha writers overlap; equal-priority order is undefined. 8. validate a fallback path for feature levels without rvt when the content must remain visible. rvt performance/debug text stat virtualtexturing stat virtualtexturememory - larger/more detailed rvts consume more pool memory and uploads. - ycocg base-color encoding reduces banding but uses about 25% more memory and adds decode cost. - a writer rendered only to rvt may still have collision; disable it when not needed. - diagnose missing writers by checking volume bounds, asset/material type match, render to virtual textures, main pass setting, and sort priority. world partition and landscape streaming world partition and landscape streaming use with ../../unreal-world-partition/skill.md. landscape defines terrain topology; world partition defines cell residency and streaming sources. large-world setup 1. choose landscape topology and source tile convention before world partition import. 2. import tiled heightmaps with recorded world partition grid size, world partition region size, flip y axis, xy scale, and z scale. 3. verify all landscape streaming proxies, component boundaries, edit ownership, and source-control files. 4. establish streaming sources/ranges from maximum traversal speed and target-device readiness. 5. build and validate landscape-related hlod/distant content where applicable. 6. rebuild navigation, pcg, foliage, rvt streaming low mips, and nanite data after relevant landscape changes. do not assume landscape component, landscape streaming proxy, world partition cell, hlod cell, pcg grid, and navigation tile are the same unit. name each size explicitly. editor workflow - load only the region required for an edit, but check seams with neighboring regions loaded. - keep broad import/re-tile operations reproducible and coordinated; they can touch many external actor/proxy files. - disable automatic expensive derived rebuilds while making broad edits only when a deliberate final-build step exists. - use location/region loading and source control to prevent invisible work on unloaded neighbors. seam validation at each tile/proxy boundary inspect: - height continuity and normals; - target layer/weightmap continuity; - material/rvt and virtual-texture behavior; - landscape spline and water deformation; - collision and physical surface; - navmesh connectivity; - pcg/grass/foliage density and exclusion; - nanite proxy freshness and skirt behavior. runtime acceptance - fastest traversal cannot reach missing terrain collision; - camera vistas do not expose unloaded holes or unacceptable lod changes; - returning across cells does not grow memory indefinitely; - runtime data layer transitions do not leave terrain-dependent content inconsistent; - server and clients have compatible collision/navigation/world state; - cooked target traces show streaming, material, and landscape work inside budgets. route streaming-source, cell, data layer, hlod, and commandlet diagnosis to $unreal-world-partition.","references":[{"slug":"components-dimensions-scale","file":"components-dimensions-scale.md","title":"Components, dimensions, and scale","rawMarkdown":"# Components, dimensions, and scale\n\n## Topology\n\nLandscape Components are the base units for rendering, visibility, collision, and streaming proxies. All components in one Landscape are square and use the same size.\n\n- A component uses one section or `2×2` sections.\n- A section is the unit of Landscape LOD transition.\n- Each section is a draw call, and every component carries render-thread CPU cost.\n- Valid component quad dimensions follow the Landscape texture/mip layout: power-of-two vertices produce power-of-two-minus-one quads for one section, or power-of-two-minus-two component quads for `2×2` sections.\n- Epic recommends no more than 1024 components for the largest Landscapes; treat this as an upper guideline, not a target.\n\nUse Epic's valid-dimensions table or the creation UI rather than cropping an arbitrary image to “almost” fit.\n\n## Tradeoffs\n\n### More, smaller components\n\n- finer culling and LOD granularity;\n- smaller localized edit/stream units;\n- more component CPU overhead and potentially more section draw calls.\n\n### Fewer, larger components\n\n- lower component count;\n- coarser culling, LOD, collision, and streaming granularity;\n- heavier individual visible/rebuild units.\n\n`2×2` subsections can provide the same terrain resolution with fewer components than four separate one-section components, but still create four section draw calls per component.\n\n## XY scale\n\nXY scale defines vertex spacing in centimeters. At 100, adjacent vertices are one meter apart.\n\n- Smaller spacing expresses smaller terrain features but covers less world area for the same heightmap and can increase pressure for more components.\n- Larger spacing covers more area but produces coarser silhouettes, collision, slopes, and deformation.\n\nDo not chase texture detail with geometry. Use materials, normal/detail maps, meshes, decals, and vegetation for sub-vertex detail.\n\n## Z scale\n\nZ scale maps 16-bit height values into world height. Increasing it expands vertical range but also magnifies each height step and changes gameplay slopes. Pick the range before sculpting and leave headroom for intentional edits.\n\n## Layout procedure\n\n1. Convert desired world width to centimeters.\n2. Choose the coarsest XY vertex spacing that still represents required gameplay terrain.\n3. Select a valid overall resolution and component topology that covers the extent.\n4. Calculate Z scale from the source elevation range.\n5. Create a small representative slice with the intended topology.\n6. Test terrain silhouette, traversal, collision, navigation, LOD, material, and edit speed.\n7. Profile component/section cost before committing the entire world.\n\n## Never infer from resolution alone\n\nTwo Landscapes with the same vertex resolution can have different physical sizes, precision, component counts, and runtime behavior. Always report resolution together with XY/Z scale, section size, sections per component, and component count.\n","webMarkdown":"## Topology\n\nLandscape Components are the base units for rendering, visibility, collision, and streaming proxies. All components in one Landscape are square and use the same size.\n\n- A component uses one section or `2×2` sections.\n- A section is the unit of Landscape LOD transition.\n- Each section is a draw call, and every component carries render-thread CPU cost.\n- Valid component quad dimensions follow the Landscape texture/mip layout: power-of-two vertices produce power-of-two-minus-one quads for one section, or power-of-two-minus-two component quads for `2×2` sections.\n- Epic recommends no more than 1024 components for the largest Landscapes; treat this as an upper guideline, not a target.\n\nUse Epic's valid-dimensions table or the creation UI rather than cropping an arbitrary image to “almost” fit.\n\n## Tradeoffs\n\n### More, smaller components\n\n- finer culling and LOD granularity;\n- smaller localized edit/stream units;\n- more component CPU overhead and potentially more section draw calls.\n\n### Fewer, larger components\n\n- lower component count;\n- coarser culling, LOD, collision, and streaming granularity;\n- heavier individual visible/rebuild units.\n\n`2×2` subsections can provide the same terrain resolution with fewer components than four separate one-section components, but still create four section draw calls per component.\n\n## XY scale\n\nXY scale defines vertex spacing in centimeters. At 100, adjacent vertices are one meter apart.\n\n- Smaller spacing expresses smaller terrain features but covers less world area for the same heightmap and can increase pressure for more components.\n- Larger spacing covers more area but produces coarser silhouettes, collision, slopes, and deformation.\n\nDo not chase texture detail with geometry. Use materials, normal/detail maps, meshes, decals, and vegetation for sub-vertex detail.\n\n## Z scale\n\nZ scale maps 16-bit height values into world height. Increasing it expands vertical range but also magnifies each height step and changes gameplay slopes. Pick the range before sculpting and leave headroom for intentional edits.\n\n## Layout procedure\n\n1. Convert desired world width to centimeters.\n2. Choose the coarsest XY vertex spacing that still represents required gameplay terrain.\n3. Select a valid overall resolution and component topology that covers the extent.\n4. Calculate Z scale from the source elevation range.\n5. Create a small representative slice with the intended topology.\n6. Test terrain silhouette, traversal, collision, navigation, LOD, material, and edit speed.\n7. Profile component/section cost before committing the entire world.\n\n## Never infer from resolution alone\n\nTwo Landscapes with the same vertex resolution can have different physical sizes, precision, component counts, and runtime behavior. Always report resolution together with XY/Z scale, section size, sections per component, and component count.\n","searchText":"components, dimensions, and scale topology landscape components are the base units for rendering, visibility, collision, and streaming proxies. all components in one landscape are square and use the same size. - a component uses one section or 2×2 sections. - a section is the unit of landscape lod transition. - each section is a draw call, and every component carries render-thread cpu cost. - valid component quad dimensions follow the landscape texture/mip layout: power-of-two vertices produce power-of-two-minus-one quads for one section, or power-of-two-minus-two component quads for 2×2 sections. - epic recommends no more than 1024 components for the largest landscapes; treat this as an upper guideline, not a target. use epic's valid-dimensions table or the creation ui rather than cropping an arbitrary image to “almost” fit. tradeoffs more, smaller components - finer culling and lod granularity; - smaller localized edit/stream units; - more component cpu overhead and potentially more section draw calls. fewer, larger components - lower component count; - coarser culling, lod, collision, and streaming granularity; - heavier individual visible/rebuild units. 2×2 subsections can provide the same terrain resolution with fewer components than four separate one-section components, but still create four section draw calls per component. xy scale xy scale defines vertex spacing in centimeters. at 100, adjacent vertices are one meter apart. - smaller spacing expresses smaller terrain features but covers less world area for the same heightmap and can increase pressure for more components. - larger spacing covers more area but produces coarser silhouettes, collision, slopes, and deformation. do not chase texture detail with geometry. use materials, normal/detail maps, meshes, decals, and vegetation for sub-vertex detail. z scale z scale maps 16-bit height values into world height. increasing it expands vertical range but also magnifies each height step and changes gameplay slopes. pick the range before sculpting and leave headroom for intentional edits. layout procedure 1. convert desired world width to centimeters. 2. choose the coarsest xy vertex spacing that still represents required gameplay terrain. 3. select a valid overall resolution and component topology that covers the extent. 4. calculate z scale from the source elevation range. 5. create a small representative slice with the intended topology. 6. test terrain silhouette, traversal, collision, navigation, lod, material, and edit speed. 7. profile component/section cost before committing the entire world. never infer from resolution alone two landscapes with the same vertex resolution can have different physical sizes, precision, component counts, and runtime behavior. always report resolution together with xy/z scale, section size, sections per component, and component count."},{"slug":"debugging-patterns","file":"debugging-patterns.md","title":"Debugging and production patterns","rawMarkdown":"# Debugging and production patterns\n\n## Diagnose by layer\n\n1. **Topology** — valid resolution, correct component/section layout, XY/Z scale.\n2. **Authoring stack** — correct active Edit Layer, order, visibility, lock, alpha, procedural owner.\n3. **Paint contract** — material name, Target Layer, Layer Info type, filled base, weight data.\n4. **Derived systems** — splines, water, patches, grass/foliage/PCG, RVT, Nanite, collision, navigation.\n5. **Streaming** — loaded region/proxy and dependent World Partition cells.\n6. **Runtime budget** — shader, texture, virtual texture, geometry, shadow, instances, collision, I/O.\n\n## Useful visualizers and stats\n\n- Landscape component/section/quads color overlays in Manage mode.\n- `View > Landscape Visualizers > Layer Debug` for Target Layer channels.\n- `Lit > Visualizers > Layer Contribution` for Edit Layer contribution.\n- Player Collision and Visibility Collision view modes.\n- `Landscape.RenderNanite 0/1` for controlled representation comparison.\n- `stat virtualtexturing` and `stat virtualtexturememory` for RVT.\n- `stat unit`, `stat gpu`, GPU Visualizer, Unreal Insights.\n\nRestore diagnostic overrides before final captures.\n\n## Common symptom table\n\n| Symptom | First checks |\n|---|---|\n| Tile seam/crack | source edge pixels, Flip Y, XY/Z scale, proxy freshness, Nanite skirt |\n| Sculpt has no effect | wrong/locked Edit Layer, special procedural layer, alpha zero |\n| Spline does not deform | missing Spline Edit Layer, raise/lower disabled, width/falloff |\n| Black/default material | compile error, missing Layer Info/base fill, sampler/permutation |\n| Wrong physical surface | dominant Target Layer and Physical Material assignment |\n| Grass missing | Grass Output name/mask, Grass Type, Landscape-only boundary, culling |\n| RVT contribution missing | bounds, asset type, writer list, pass type, sort priority |\n| Nanite visual stale | dirty proxy; build/save/cook Nanite representation |\n| Character floats/clips | collision mip or render displacement differs from collision |\n| NavMesh breaks after sculpt | navigation not rebuilt or slope/step/agent settings no longer fit |\n\n## Production test matrix\n\n| Axis | Minimum cases |\n|---|---|\n| Edit | sculpt/paint, undo, save/reload, layer reorder/hide, neighbor regions |\n| Import | clean reimport, tiled seams, round-trip export, source checksum |\n| Traversal | walk, fastest vehicle, steepest intended slope, world edge, teleport |\n| Rendering | near/far, Nanite on/off, scalability tiers, target feature levels |\n| Surface | each Target Layer, transitions, traces, footsteps/effects |\n| Derived | splines, water, patches, vegetation, PCG, nav, HLOD/RVT |\n| Build | PIE, standalone, cooked Development, shipping-equivalent target |\n| Soak | repeated cross-world route and memory stabilization |\n\n## Acceptance\n\n- terrain supports intended mental map, sightlines, and traversal;\n- no missing collision or navigation at streaming/edit boundaries;\n- layer ownership is understandable and reversible;\n- derived data can be rebuilt reproducibly;\n- target frame, memory, disk, cook, and streaming budgets are met;\n- no final conclusion relies on stale Nanite/RVT/nav/PCG data.\n","webMarkdown":"## Diagnose by layer\n\n1. **Topology** — valid resolution, correct component/section layout, XY/Z scale.\n2. **Authoring stack** — correct active Edit Layer, order, visibility, lock, alpha, procedural owner.\n3. **Paint contract** — material name, Target Layer, Layer Info type, filled base, weight data.\n4. **Derived systems** — splines, water, patches, grass/foliage/PCG, RVT, Nanite, collision, navigation.\n5. **Streaming** — loaded region/proxy and dependent World Partition cells.\n6. **Runtime budget** — shader, texture, virtual texture, geometry, shadow, instances, collision, I/O.\n\n## Useful visualizers and stats\n\n- Landscape component/section/quads color overlays in Manage mode.\n- `View > Landscape Visualizers > Layer Debug` for Target Layer channels.\n- `Lit > Visualizers > Layer Contribution` for Edit Layer contribution.\n- Player Collision and Visibility Collision view modes.\n- `Landscape.RenderNanite 0/1` for controlled representation comparison.\n- `stat virtualtexturing` and `stat virtualtexturememory` for RVT.\n- `stat unit`, `stat gpu`, GPU Visualizer, Unreal Insights.\n\nRestore diagnostic overrides before final captures.\n\n## Common symptom table\n\n| Symptom | First checks |\n|---|---|\n| Tile seam/crack | source edge pixels, Flip Y, XY/Z scale, proxy freshness, Nanite skirt |\n| Sculpt has no effect | wrong/locked Edit Layer, special procedural layer, alpha zero |\n| Spline does not deform | missing Spline Edit Layer, raise/lower disabled, width/falloff |\n| Black/default material | compile error, missing Layer Info/base fill, sampler/permutation |\n| Wrong physical surface | dominant Target Layer and Physical Material assignment |\n| Grass missing | Grass Output name/mask, Grass Type, Landscape-only boundary, culling |\n| RVT contribution missing | bounds, asset type, writer list, pass type, sort priority |\n| Nanite visual stale | dirty proxy; build/save/cook Nanite representation |\n| Character floats/clips | collision mip or render displacement differs from collision |\n| NavMesh breaks after sculpt | navigation not rebuilt or slope/step/agent settings no longer fit |\n\n## Production test matrix\n\n| Axis | Minimum cases |\n|---|---|\n| Edit | sculpt/paint, undo, save/reload, layer reorder/hide, neighbor regions |\n| Import | clean reimport, tiled seams, round-trip export, source checksum |\n| Traversal | walk, fastest vehicle, steepest intended slope, world edge, teleport |\n| Rendering | near/far, Nanite on/off, scalability tiers, target feature levels |\n| Surface | each Target Layer, transitions, traces, footsteps/effects |\n| Derived | splines, water, patches, vegetation, PCG, nav, HLOD/RVT |\n| Build | PIE, standalone, cooked Development, shipping-equivalent target |\n| Soak | repeated cross-world route and memory stabilization |\n\n## Acceptance\n\n- terrain supports intended mental map, sightlines, and traversal;\n- no missing collision or navigation at streaming/edit boundaries;\n- layer ownership is understandable and reversible;\n- derived data can be rebuilt reproducibly;\n- target frame, memory, disk, cook, and streaming budgets are met;\n- no final conclusion relies on stale Nanite/RVT/nav/PCG data.\n","searchText":"debugging and production patterns diagnose by layer 1. topology — valid resolution, correct component/section layout, xy/z scale. 2. authoring stack — correct active edit layer, order, visibility, lock, alpha, procedural owner. 3. paint contract — material name, target layer, layer info type, filled base, weight data. 4. derived systems — splines, water, patches, grass/foliage/pcg, rvt, nanite, collision, navigation. 5. streaming — loaded region/proxy and dependent world partition cells. 6. runtime budget — shader, texture, virtual texture, geometry, shadow, instances, collision, i/o. useful visualizers and stats - landscape component/section/quads color overlays in manage mode. - view > landscape visualizers > layer debug for target layer channels. - lit > visualizers > layer contribution for edit layer contribution. - player collision and visibility collision view modes. - landscape.rendernanite 0/1 for controlled representation comparison. - stat virtualtexturing and stat virtualtexturememory for rvt. - stat unit, stat gpu, gpu visualizer, unreal insights. restore diagnostic overrides before final captures. common symptom table | symptom | first checks | |---|---| | tile seam/crack | source edge pixels, flip y, xy/z scale, proxy freshness, nanite skirt | | sculpt has no effect | wrong/locked edit layer, special procedural layer, alpha zero | | spline does not deform | missing spline edit layer, raise/lower disabled, width/falloff | | black/default material | compile error, missing layer info/base fill, sampler/permutation | | wrong physical surface | dominant target layer and physical material assignment | | grass missing | grass output name/mask, grass type, landscape-only boundary, culling | | rvt contribution missing | bounds, asset type, writer list, pass type, sort priority | | nanite visual stale | dirty proxy; build/save/cook nanite representation | | character floats/clips | collision mip or render displacement differs from collision | | navmesh breaks after sculpt | navigation not rebuilt or slope/step/agent settings no longer fit | production test matrix | axis | minimum cases | |---|---| | edit | sculpt/paint, undo, save/reload, layer reorder/hide, neighbor regions | | import | clean reimport, tiled seams, round-trip export, source checksum | | traversal | walk, fastest vehicle, steepest intended slope, world edge, teleport | | rendering | near/far, nanite on/off, scalability tiers, target feature levels | | surface | each target layer, transitions, traces, footsteps/effects | | derived | splines, water, patches, vegetation, pcg, nav, hlod/rvt | | build | pie, standalone, cooked development, shipping-equivalent target | | soak | repeated cross-world route and memory stabilization | acceptance - terrain supports intended mental map, sightlines, and traversal; - no missing collision or navigation at streaming/edit boundaries; - layer ownership is understandable and reversible; - derived data can be rebuilt reproducibly; - target frame, memory, disk, cook, and streaming budgets are met; - no final conclusion relies on stale nanite/rvt/nav/pcg data."},{"slug":"edit-layers-sculpting-patches","file":"edit-layers-sculpting-patches.md","title":"Edit Layers, sculpting, and patches","rawMarkdown":"# Edit Layers, sculpting, and patches\n\n## Edit Layer contract\n\nLandscape Edit Layers are stack-based, non-destructive containers for heightmap, weightmap, and visibility data. New Landscapes enable them automatically in UE 5.8. The default project limit is eight and is configurable.\n\nUse a small semantic stack, for example:\n\n```text\nBaseImport\nBroadSculpt\nGameplayCorrections\nSplineProcedural\nPatchProcedural\nPaintArtDirection\n```\n\nMore layers increase evaluation, authoring, merge, and diagnosis cost. Add a layer only when it represents distinct ownership or must be independently hidden/reordered.\n\n## Editing rules\n\n- Lock completed/owned layers.\n- Use visibility and **Layer Contribution** (`Lit > Visualizers > Layer Contribution`) to isolate effects.\n- Record whether height/paint alpha is intentionally additive, subtractive, or zero.\n- Erase on an Edit Layer removes that layer's contribution; it is not necessarily “sculpt terrain downward.”\n- `Collapse` and `Collapse All Layers` are destructive. Save/source-control before flattening.\n- Deleting a layer deletes its height, weight, visibility, and assigned Blueprint Brush data.\n\n## Sculpting workflow\n\n1. Sculpt broad landforms before detail.\n2. Establish playable grades, ledges, sightlines, drainage/water bounds, and landmarks.\n3. Use Smooth sparingly; repeated smoothing erases intentional terrain language.\n4. Put gameplay corrections on a separate layer so art changes cannot silently remove them.\n5. Rebuild/check collision and NavMesh after meaningful height changes.\n6. Test movement agents and cameras, not only the landscape viewport.\n\n## Special procedural layers\n\n### Spline Edit Layer\n\nStores Landscape Spline deformation/paint. It accepts procedural spline data and cannot be hand-sculpted or painted.\n\n### Patch Edit Layer\n\nStores Landscape Patch components. Patches can read textures/render targets and alter height/weight data. Patch inputs are editor-only and results are baked into the final Landscape, so the procedural source does not add runtime memory/performance by itself.\n\nUse patches for reusable stamps, local terrain fitting, or actor-owned deformation that must remain editable. Use ordinary sculpt layers for unique manual art.\n\n## Change validation\n\nAfter reordering, changing alpha, importing, or modifying a procedural layer:\n\n- isolate every layer contribution;\n- inspect boundaries between loaded regions/components;\n- recheck Landscape Splines, water, and patches;\n- validate painted Target Layers and physical surfaces;\n- rebuild Nanite representation if enabled;\n- rebuild navigation and dependent PCG/HLOD as applicable;\n- save/reload and cook a representative map.\n","webMarkdown":"## Edit Layer contract\n\nLandscape Edit Layers are stack-based, non-destructive containers for heightmap, weightmap, and visibility data. New Landscapes enable them automatically in UE 5.8. The default project limit is eight and is configurable.\n\nUse a small semantic stack, for example:\n\n```text\nBaseImport\nBroadSculpt\nGameplayCorrections\nSplineProcedural\nPatchProcedural\nPaintArtDirection\n```\n\nMore layers increase evaluation, authoring, merge, and diagnosis cost. Add a layer only when it represents distinct ownership or must be independently hidden/reordered.\n\n## Editing rules\n\n- Lock completed/owned layers.\n- Use visibility and **Layer Contribution** (`Lit > Visualizers > Layer Contribution`) to isolate effects.\n- Record whether height/paint alpha is intentionally additive, subtractive, or zero.\n- Erase on an Edit Layer removes that layer's contribution; it is not necessarily “sculpt terrain downward.”\n- `Collapse` and `Collapse All Layers` are destructive. Save/source-control before flattening.\n- Deleting a layer deletes its height, weight, visibility, and assigned Blueprint Brush data.\n\n## Sculpting workflow\n\n1. Sculpt broad landforms before detail.\n2. Establish playable grades, ledges, sightlines, drainage/water bounds, and landmarks.\n3. Use Smooth sparingly; repeated smoothing erases intentional terrain language.\n4. Put gameplay corrections on a separate layer so art changes cannot silently remove them.\n5. Rebuild/check collision and NavMesh after meaningful height changes.\n6. Test movement agents and cameras, not only the landscape viewport.\n\n## Special procedural layers\n\n### Spline Edit Layer\n\nStores Landscape Spline deformation/paint. It accepts procedural spline data and cannot be hand-sculpted or painted.\n\n### Patch Edit Layer\n\nStores Landscape Patch components. Patches can read textures/render targets and alter height/weight data. Patch inputs are editor-only and results are baked into the final Landscape, so the procedural source does not add runtime memory/performance by itself.\n\nUse patches for reusable stamps, local terrain fitting, or actor-owned deformation that must remain editable. Use ordinary sculpt layers for unique manual art.\n\n## Change validation\n\nAfter reordering, changing alpha, importing, or modifying a procedural layer:\n\n- isolate every layer contribution;\n- inspect boundaries between loaded regions/components;\n- recheck Landscape Splines, water, and patches;\n- validate painted Target Layers and physical surfaces;\n- rebuild Nanite representation if enabled;\n- rebuild navigation and dependent PCG/HLOD as applicable;\n- save/reload and cook a representative map.\n","searchText":"edit layers, sculpting, and patches edit layer contract landscape edit layers are stack-based, non-destructive containers for heightmap, weightmap, and visibility data. new landscapes enable them automatically in ue 5.8. the default project limit is eight and is configurable. use a small semantic stack, for example: text baseimport broadsculpt gameplaycorrections splineprocedural patchprocedural paintartdirection more layers increase evaluation, authoring, merge, and diagnosis cost. add a layer only when it represents distinct ownership or must be independently hidden/reordered. editing rules - lock completed/owned layers. - use visibility and layer contribution (lit > visualizers > layer contribution) to isolate effects. - record whether height/paint alpha is intentionally additive, subtractive, or zero. - erase on an edit layer removes that layer's contribution; it is not necessarily “sculpt terrain downward.” - collapse and collapse all layers are destructive. save/source-control before flattening. - deleting a layer deletes its height, weight, visibility, and assigned blueprint brush data. sculpting workflow 1. sculpt broad landforms before detail. 2. establish playable grades, ledges, sightlines, drainage/water bounds, and landmarks. 3. use smooth sparingly; repeated smoothing erases intentional terrain language. 4. put gameplay corrections on a separate layer so art changes cannot silently remove them. 5. rebuild/check collision and navmesh after meaningful height changes. 6. test movement agents and cameras, not only the landscape viewport. special procedural layers spline edit layer stores landscape spline deformation/paint. it accepts procedural spline data and cannot be hand-sculpted or painted. patch edit layer stores landscape patch components. patches can read textures/render targets and alter height/weight data. patch inputs are editor-only and results are baked into the final landscape, so the procedural source does not add runtime memory/performance by itself. use patches for reusable stamps, local terrain fitting, or actor-owned deformation that must remain editable. use ordinary sculpt layers for unique manual art. change validation after reordering, changing alpha, importing, or modifying a procedural layer: - isolate every layer contribution; - inspect boundaries between loaded regions/components; - recheck landscape splines, water, and patches; - validate painted target layers and physical surfaces; - rebuild nanite representation if enabled; - rebuild navigation and dependent pcg/hlod as applicable; - save/reload and cook a representative map."},{"slug":"grass-foliage-pcg","file":"grass-foliage-pcg.md","title":"Grass, foliage, and PCG","rawMarkdown":"# Grass, foliage, and PCG\n\n## Choose one owner per population\n\n| Need | Default system | Boundary |\n|---|---|---|\n| Material/paint-driven passive ground cover | Landscape Grass Output + Landscape Grass Type | Works only with Landscape terrain; coupled to material layer weights |\n| Hand-authored instance painting | Foliage Mode + Static Mesh Foliage | Efficient instancing and direct art control |\n| Ecological offline simulation | Procedural Foliage | Experimental editor workflow in current documentation |\n| Rule-driven spatial generation, exclusions, runtime generation | PCG | Route graph implementation to `$unreal-pcg` |\n| Unique behavior/identity | Actor or PCG Spawn Actor | Costs like actors; keep density low |\n\nDo not simultaneously generate the same grass/tree class through Landscape Grass, Foliage, and PCG. Establish ownership, exclusion, regeneration, and source-control policy.\n\n## Landscape Grass workflow\n\n1. Derive a mask from a named Landscape Target Layer using `LandscapeGrassOutput`.\n2. Create a Landscape Grass Type and entries for meshes, density, scale, rotation, alignment, and cull distances.\n3. Attach the Grass Type to the corresponding Grass Output input.\n4. Paint/fill the driving Landscape layer.\n5. Validate density, collision expectations, shadows, wind, LOD/Nanite, and culling in a cooked build.\n\nLandscape Grass is appropriate for passive visual distribution. If individual plants need durable identity, interaction, or authoritative state, they are not merely grass instances.\n\n## Foliage Mode workflow\n\n- Prefer **Static Mesh Foliage** for decoration; it is hardware-instanced and batched.\n- **Actor Foliage** has the rendering/gameplay cost of ordinary actors. Use only where behavior requires it.\n- Define slope, height, scale, alignment, collision, density scaling, cull distance, shadow, and navigation impact in governed Foliage Type assets.\n- Use Reapply deliberately; it can change many existing instances.\n- Validate instance attachment after Landscape edits and choose the UE 5.8 foliage snapping behavior intentionally.\n\n## Procedural Foliage\n\nThe current guide still places Procedural Foliage under Experimental editor settings. Use it only after validating plugin availability, resimulation determinism, source-control output, cook behavior, and iteration cost.\n\n## Performance and gameplay\n\n- Use `foliage.DensityScale` only for types configured to participate in scalability.\n- Cull distances, LOD/Nanite, shadow policy, WPO/wind, overdraw, and material cost determine final expense—not draw calls alone.\n- Collision on dense small foliage is usually wasteful; collision/navigation blockers on important trees require explicit testing.\n- Rebuild or update navigation after collision-relevant vegetation changes.\n- Treat visually dense forests as AI sightline and path-design content, not only rendering content.\n\n## Acceptance\n\n- no duplicate ownership;\n- deterministic regeneration where required;\n- no vegetation on roads, entrances, traversal clearance, or critical sightlines;\n- expected collision/nav/physical-surface behavior;\n- stable memory and frame time through density scalability extremes;\n- no visible cull/LOD transition beyond the project's budget.\n","webMarkdown":"## Choose one owner per population\n\n| Need | Default system | Boundary |\n|---|---|---|\n| Material/paint-driven passive ground cover | Landscape Grass Output + Landscape Grass Type | Works only with Landscape terrain; coupled to material layer weights |\n| Hand-authored instance painting | Foliage Mode + Static Mesh Foliage | Efficient instancing and direct art control |\n| Ecological offline simulation | Procedural Foliage | Experimental editor workflow in current documentation |\n| Rule-driven spatial generation, exclusions, runtime generation | PCG | Route graph implementation to `$unreal-pcg` |\n| Unique behavior/identity | Actor or PCG Spawn Actor | Costs like actors; keep density low |\n\nDo not simultaneously generate the same grass/tree class through Landscape Grass, Foliage, and PCG. Establish ownership, exclusion, regeneration, and source-control policy.\n\n## Landscape Grass workflow\n\n1. Derive a mask from a named Landscape Target Layer using `LandscapeGrassOutput`.\n2. Create a Landscape Grass Type and entries for meshes, density, scale, rotation, alignment, and cull distances.\n3. Attach the Grass Type to the corresponding Grass Output input.\n4. Paint/fill the driving Landscape layer.\n5. Validate density, collision expectations, shadows, wind, LOD/Nanite, and culling in a cooked build.\n\nLandscape Grass is appropriate for passive visual distribution. If individual plants need durable identity, interaction, or authoritative state, they are not merely grass instances.\n\n## Foliage Mode workflow\n\n- Prefer **Static Mesh Foliage** for decoration; it is hardware-instanced and batched.\n- **Actor Foliage** has the rendering/gameplay cost of ordinary actors. Use only where behavior requires it.\n- Define slope, height, scale, alignment, collision, density scaling, cull distance, shadow, and navigation impact in governed Foliage Type assets.\n- Use Reapply deliberately; it can change many existing instances.\n- Validate instance attachment after Landscape edits and choose the UE 5.8 foliage snapping behavior intentionally.\n\n## Procedural Foliage\n\nThe current guide still places Procedural Foliage under Experimental editor settings. Use it only after validating plugin availability, resimulation determinism, source-control output, cook behavior, and iteration cost.\n\n## Performance and gameplay\n\n- Use `foliage.DensityScale` only for types configured to participate in scalability.\n- Cull distances, LOD/Nanite, shadow policy, WPO/wind, overdraw, and material cost determine final expense—not draw calls alone.\n- Collision on dense small foliage is usually wasteful; collision/navigation blockers on important trees require explicit testing.\n- Rebuild or update navigation after collision-relevant vegetation changes.\n- Treat visually dense forests as AI sightline and path-design content, not only rendering content.\n\n## Acceptance\n\n- no duplicate ownership;\n- deterministic regeneration where required;\n- no vegetation on roads, entrances, traversal clearance, or critical sightlines;\n- expected collision/nav/physical-surface behavior;\n- stable memory and frame time through density scalability extremes;\n- no visible cull/LOD transition beyond the project's budget.\n","searchText":"grass, foliage, and pcg choose one owner per population | need | default system | boundary | |---|---|---| | material/paint-driven passive ground cover | landscape grass output + landscape grass type | works only with landscape terrain; coupled to material layer weights | | hand-authored instance painting | foliage mode + static mesh foliage | efficient instancing and direct art control | | ecological offline simulation | procedural foliage | experimental editor workflow in current documentation | | rule-driven spatial generation, exclusions, runtime generation | pcg | route graph implementation to $unreal-pcg | | unique behavior/identity | actor or pcg spawn actor | costs like actors; keep density low | do not simultaneously generate the same grass/tree class through landscape grass, foliage, and pcg. establish ownership, exclusion, regeneration, and source-control policy. landscape grass workflow 1. derive a mask from a named landscape target layer using landscapegrassoutput. 2. create a landscape grass type and entries for meshes, density, scale, rotation, alignment, and cull distances. 3. attach the grass type to the corresponding grass output input. 4. paint/fill the driving landscape layer. 5. validate density, collision expectations, shadows, wind, lod/nanite, and culling in a cooked build. landscape grass is appropriate for passive visual distribution. if individual plants need durable identity, interaction, or authoritative state, they are not merely grass instances. foliage mode workflow - prefer static mesh foliage for decoration; it is hardware-instanced and batched. - actor foliage has the rendering/gameplay cost of ordinary actors. use only where behavior requires it. - define slope, height, scale, alignment, collision, density scaling, cull distance, shadow, and navigation impact in governed foliage type assets. - use reapply deliberately; it can change many existing instances. - validate instance attachment after landscape edits and choose the ue 5.8 foliage snapping behavior intentionally. procedural foliage the current guide still places procedural foliage under experimental editor settings. use it only after validating plugin availability, resimulation determinism, source-control output, cook behavior, and iteration cost. performance and gameplay - use foliage.densityscale only for types configured to participate in scalability. - cull distances, lod/nanite, shadow policy, wpo/wind, overdraw, and material cost determine final expense—not draw calls alone. - collision on dense small foliage is usually wasteful; collision/navigation blockers on important trees require explicit testing. - rebuild or update navigation after collision-relevant vegetation changes. - treat visually dense forests as ai sightline and path-design content, not only rendering content. acceptance - no duplicate ownership; - deterministic regeneration where required; - no vegetation on roads, entrances, traversal clearance, or critical sightlines; - expected collision/nav/physical-surface behavior; - stable memory and frame time through density scalability extremes; - no visible cull/lod transition beyond the project's budget."},{"slug":"materials-painting","file":"materials-painting.md","title":"Landscape materials and painting","rawMarkdown":"# Landscape materials and painting\n\n## Keep three concepts separate\n\n- **Edit Layer**: non-destructive authoring stack for height/weight/visibility edits.\n- **Target Layer**: named weightmap channel exposed by the Landscape material and painted/imported in Paint mode.\n- **Layer Info asset**: defines storage/blending behavior and can associate a Physical Material with a Target Layer.\n\nNames are case-insensitive in the material system but must remain stable and governed. Renaming one side of the contract can turn a layer weight into zero.\n\n## Blend selector\n\n- Use **weight blending** for mutually normalized base surfaces such as soil/grass/rock.\n- Use **alpha/non-weight blending** for an independent overlay whose ordering is intentional.\n- Use **height blending** when per-layer height data should influence the transition; verify zero-weight intersections and normal behavior.\n\nWeight-blended layers share a normalized total. Erasing a fully weighted layer cannot reveal a nonexistent underlying weight; paint the desired replacement layer instead.\n\n## Authoring workflow\n\n1. Define a small semantic layer list and required outputs: base color, normal, roughness, displacement, physical surface, grass mask, PCG mask.\n2. Build reusable material functions and parameters rather than duplicating graphs per layer.\n3. Create matching `LandscapeLayerBlend`, `LandscapeLayerSample`, or custom weight logic.\n4. Assign the material to a test Landscape.\n5. Create the correct Weight-Blended or Non Weight-Blended Layer Info for each Target Layer.\n6. Fill a deliberate base layer before local painting.\n7. Paint boundary, full-weight, zero-weight, steep-slope, distant-LOD, and wet/snow overlay cases.\n8. Trace/test physical surfaces and derived grass/PCG masks.\n\n## Performance controls\n\n- Every visible component compiles the material permutation needed by the layers used there.\n- Use `LandscapeLayerSwitch` to remove operations when a layer contributes zero in a region.\n- Share samplers/material functions where correct and watch texture-sampler limits on target feature levels.\n- Prefer a few meaningful layers to many nearly identical variants.\n- Mobile technically supports multiple layers subject to sampler limits; Epic recommends only three. Treat target measurement as the deciding constraint.\n- Use RVT when caching complex terrain shading or terrain/object blending produces a measured benefit, not as mandatory architecture.\n\n## Physical surface validation\n\nAssign Physical Materials through the intended Landscape layer/material path. Test several points per surface, transitions, thin paint, and cooked builds with traces returning physical material. Visual appearance and returned physical surface must agree wherever footsteps, effects, friction, or gameplay depend on it.\n\n## Common failures\n\n- **Black/default Landscape**: material compile error, missing Layer Info, no filled base layer, or unsupported sampler/permutation.\n- **Paint layer absent**: name mismatch or material never samples it.\n- **Erase seems ineffective**: weight normalization; paint the replacement layer.\n- **Wrong footsteps**: dominant layer/Physical Material assignment differs from visual expectation.\n- **Shader explosion/hitch**: too many expensive layers/combinations and unbounded permutations.\n","webMarkdown":"## Keep three concepts separate\n\n- **Edit Layer**: non-destructive authoring stack for height/weight/visibility edits.\n- **Target Layer**: named weightmap channel exposed by the Landscape material and painted/imported in Paint mode.\n- **Layer Info asset**: defines storage/blending behavior and can associate a Physical Material with a Target Layer.\n\nNames are case-insensitive in the material system but must remain stable and governed. Renaming one side of the contract can turn a layer weight into zero.\n\n## Blend selector\n\n- Use **weight blending** for mutually normalized base surfaces such as soil/grass/rock.\n- Use **alpha/non-weight blending** for an independent overlay whose ordering is intentional.\n- Use **height blending** when per-layer height data should influence the transition; verify zero-weight intersections and normal behavior.\n\nWeight-blended layers share a normalized total. Erasing a fully weighted layer cannot reveal a nonexistent underlying weight; paint the desired replacement layer instead.\n\n## Authoring workflow\n\n1. Define a small semantic layer list and required outputs: base color, normal, roughness, displacement, physical surface, grass mask, PCG mask.\n2. Build reusable material functions and parameters rather than duplicating graphs per layer.\n3. Create matching `LandscapeLayerBlend`, `LandscapeLayerSample`, or custom weight logic.\n4. Assign the material to a test Landscape.\n5. Create the correct Weight-Blended or Non Weight-Blended Layer Info for each Target Layer.\n6. Fill a deliberate base layer before local painting.\n7. Paint boundary, full-weight, zero-weight, steep-slope, distant-LOD, and wet/snow overlay cases.\n8. Trace/test physical surfaces and derived grass/PCG masks.\n\n## Performance controls\n\n- Every visible component compiles the material permutation needed by the layers used there.\n- Use `LandscapeLayerSwitch` to remove operations when a layer contributes zero in a region.\n- Share samplers/material functions where correct and watch texture-sampler limits on target feature levels.\n- Prefer a few meaningful layers to many nearly identical variants.\n- Mobile technically supports multiple layers subject to sampler limits; Epic recommends only three. Treat target measurement as the deciding constraint.\n- Use RVT when caching complex terrain shading or terrain/object blending produces a measured benefit, not as mandatory architecture.\n\n## Physical surface validation\n\nAssign Physical Materials through the intended Landscape layer/material path. Test several points per surface, transitions, thin paint, and cooked builds with traces returning physical material. Visual appearance and returned physical surface must agree wherever footsteps, effects, friction, or gameplay depend on it.\n\n## Common failures\n\n- **Black/default Landscape**: material compile error, missing Layer Info, no filled base layer, or unsupported sampler/permutation.\n- **Paint layer absent**: name mismatch or material never samples it.\n- **Erase seems ineffective**: weight normalization; paint the replacement layer.\n- **Wrong footsteps**: dominant layer/Physical Material assignment differs from visual expectation.\n- **Shader explosion/hitch**: too many expensive layers/combinations and unbounded permutations.\n","searchText":"landscape materials and painting keep three concepts separate - edit layer: non-destructive authoring stack for height/weight/visibility edits. - target layer: named weightmap channel exposed by the landscape material and painted/imported in paint mode. - layer info asset: defines storage/blending behavior and can associate a physical material with a target layer. names are case-insensitive in the material system but must remain stable and governed. renaming one side of the contract can turn a layer weight into zero. blend selector - use weight blending for mutually normalized base surfaces such as soil/grass/rock. - use alpha/non-weight blending for an independent overlay whose ordering is intentional. - use height blending when per-layer height data should influence the transition; verify zero-weight intersections and normal behavior. weight-blended layers share a normalized total. erasing a fully weighted layer cannot reveal a nonexistent underlying weight; paint the desired replacement layer instead. authoring workflow 1. define a small semantic layer list and required outputs: base color, normal, roughness, displacement, physical surface, grass mask, pcg mask. 2. build reusable material functions and parameters rather than duplicating graphs per layer. 3. create matching landscapelayerblend, landscapelayersample, or custom weight logic. 4. assign the material to a test landscape. 5. create the correct weight-blended or non weight-blended layer info for each target layer. 6. fill a deliberate base layer before local painting. 7. paint boundary, full-weight, zero-weight, steep-slope, distant-lod, and wet/snow overlay cases. 8. trace/test physical surfaces and derived grass/pcg masks. performance controls - every visible component compiles the material permutation needed by the layers used there. - use landscapelayerswitch to remove operations when a layer contributes zero in a region. - share samplers/material functions where correct and watch texture-sampler limits on target feature levels. - prefer a few meaningful layers to many nearly identical variants. - mobile technically supports multiple layers subject to sampler limits; epic recommends only three. treat target measurement as the deciding constraint. - use rvt when caching complex terrain shading or terrain/object blending produces a measured benefit, not as mandatory architecture. physical surface validation assign physical materials through the intended landscape layer/material path. test several points per surface, transitions, thin paint, and cooked builds with traces returning physical material. visual appearance and returned physical surface must agree wherever footsteps, effects, friction, or gameplay depend on it. common failures - black/default landscape: material compile error, missing layer info, no filled base layer, or unsupported sampler/permutation. - paint layer absent: name mismatch or material never samples it. - erase seems ineffective: weight normalization; paint the replacement layer. - wrong footsteps: dominant layer/physical material assignment differs from visual expectation. - shader explosion/hitch: too many expensive layers/combinations and unbounded permutations."},{"slug":"nanite-performance-collision","file":"nanite-performance-collision.md","title":"Nanite, performance, LOD, and collision","rawMarkdown":"# Nanite, performance, LOD, and collision\n\n## Nanite Landscape boundary\n\nNanite can improve Landscape rendering performance, especially with Virtual Shadow Maps. It does not add source terrain detail or inherently improve image quality; the source data is identical.\n\nUE 5.8 keeps both representations at runtime:\n\n- Nanite Landscape data for Nanite rendering;\n- non-Nanite Landscape data for systems including RVT, water, and other Landscape functions.\n\nTherefore Nanite adds streaming and memory data. Measure the total system rather than assuming “Nanite replaces Landscape LOD.”\n\n## Workflow\n\n1. Capture non-Nanite target performance and memory.\n2. Enable `Nanite` on the Landscape.\n3. Build Nanite data through the documented Landscape build/save path.\n4. Confirm every proxy is up to date before comparing visuals or timing.\n5. Inspect seams; enable Nanite Skirt and tune skirt depth only if needed.\n6. If using Nanite tessellation/displacement, validate material settings, rebuilt data, shadows, collision mismatch, and scalability.\n7. Compare GPU, CPU, memory, streaming, cook time, disk size, and edit iteration.\n\n`Landscape.Nanite.LiveRebuildOnModification` is Experimental and live rebuild can significantly slow editing. Keep it off by default and perform controlled rebuilds. Epic's page also shows a differently ordered legacy spelling in prose; confirm the exact CVar through console help in the installed build before scripting it.\n\n## Landscape performance levers\n\n- component and section count;\n- visible component count and LOD distribution;\n- material shader/texture cost and layer permutations;\n- grass/foliage instance count, WPO, shadows, overdraw, culling;\n- RVT page generation/uploads and pool memory;\n- Nanite/VSM/tessellation cost;\n- collision mip and physics queries;\n- streaming and derived-data readiness.\n\nProfile the dominant cost; do not apply every lever at once.\n\n## Collision mip\n\n- `Collision Mip Level` controls complex/visibility collision detail.\n- `Simple Collision Mip Level` controls simple/player collision detail.\n- Higher mip values reduce geometry/memory but increase mismatch from rendered terrain.\n- Epic notes that common cases keep Collision Mip at 0 and Simple Collision Mip at 1 or 2; validate against the actual movement/query requirements rather than adopting this blindly.\n- Per-component overrides can reduce cost in inaccessible areas.\n\nRender displacement/tessellation does not automatically redefine gameplay collision. Keep visible displacement within the acceptable collision error or provide another collision/gameplay solution.\n\n## Target capture\n\nRecord:\n\n- `stat unit`, `stat gpu`, Insights trace, GPU profile;\n- visible components/sections and draw calls;\n- Landscape/material/GPU time;\n- texture, RVT, Nanite, and total memory;\n- streaming hitches at fastest traversal;\n- collision query behavior and navigation rebuild/pathing;\n- cold cook/load and warm traversal.\n","webMarkdown":"## Nanite Landscape boundary\n\nNanite can improve Landscape rendering performance, especially with Virtual Shadow Maps. It does not add source terrain detail or inherently improve image quality; the source data is identical.\n\nUE 5.8 keeps both representations at runtime:\n\n- Nanite Landscape data for Nanite rendering;\n- non-Nanite Landscape data for systems including RVT, water, and other Landscape functions.\n\nTherefore Nanite adds streaming and memory data. Measure the total system rather than assuming “Nanite replaces Landscape LOD.”\n\n## Workflow\n\n1. Capture non-Nanite target performance and memory.\n2. Enable `Nanite` on the Landscape.\n3. Build Nanite data through the documented Landscape build/save path.\n4. Confirm every proxy is up to date before comparing visuals or timing.\n5. Inspect seams; enable Nanite Skirt and tune skirt depth only if needed.\n6. If using Nanite tessellation/displacement, validate material settings, rebuilt data, shadows, collision mismatch, and scalability.\n7. Compare GPU, CPU, memory, streaming, cook time, disk size, and edit iteration.\n\n`Landscape.Nanite.LiveRebuildOnModification` is Experimental and live rebuild can significantly slow editing. Keep it off by default and perform controlled rebuilds. Epic's page also shows a differently ordered legacy spelling in prose; confirm the exact CVar through console help in the installed build before scripting it.\n\n## Landscape performance levers\n\n- component and section count;\n- visible component count and LOD distribution;\n- material shader/texture cost and layer permutations;\n- grass/foliage instance count, WPO, shadows, overdraw, culling;\n- RVT page generation/uploads and pool memory;\n- Nanite/VSM/tessellation cost;\n- collision mip and physics queries;\n- streaming and derived-data readiness.\n\nProfile the dominant cost; do not apply every lever at once.\n\n## Collision mip\n\n- `Collision Mip Level` controls complex/visibility collision detail.\n- `Simple Collision Mip Level` controls simple/player collision detail.\n- Higher mip values reduce geometry/memory but increase mismatch from rendered terrain.\n- Epic notes that common cases keep Collision Mip at 0 and Simple Collision Mip at 1 or 2; validate against the actual movement/query requirements rather than adopting this blindly.\n- Per-component overrides can reduce cost in inaccessible areas.\n\nRender displacement/tessellation does not automatically redefine gameplay collision. Keep visible displacement within the acceptable collision error or provide another collision/gameplay solution.\n\n## Target capture\n\nRecord:\n\n- `stat unit`, `stat gpu`, Insights trace, GPU profile;\n- visible components/sections and draw calls;\n- Landscape/material/GPU time;\n- texture, RVT, Nanite, and total memory;\n- streaming hitches at fastest traversal;\n- collision query behavior and navigation rebuild/pathing;\n- cold cook/load and warm traversal.\n","searchText":"nanite, performance, lod, and collision nanite landscape boundary nanite can improve landscape rendering performance, especially with virtual shadow maps. it does not add source terrain detail or inherently improve image quality; the source data is identical. ue 5.8 keeps both representations at runtime: - nanite landscape data for nanite rendering; - non-nanite landscape data for systems including rvt, water, and other landscape functions. therefore nanite adds streaming and memory data. measure the total system rather than assuming “nanite replaces landscape lod.” workflow 1. capture non-nanite target performance and memory. 2. enable nanite on the landscape. 3. build nanite data through the documented landscape build/save path. 4. confirm every proxy is up to date before comparing visuals or timing. 5. inspect seams; enable nanite skirt and tune skirt depth only if needed. 6. if using nanite tessellation/displacement, validate material settings, rebuilt data, shadows, collision mismatch, and scalability. 7. compare gpu, cpu, memory, streaming, cook time, disk size, and edit iteration. landscape.nanite.liverebuildonmodification is experimental and live rebuild can significantly slow editing. keep it off by default and perform controlled rebuilds. epic's page also shows a differently ordered legacy spelling in prose; confirm the exact cvar through console help in the installed build before scripting it. landscape performance levers - component and section count; - visible component count and lod distribution; - material shader/texture cost and layer permutations; - grass/foliage instance count, wpo, shadows, overdraw, culling; - rvt page generation/uploads and pool memory; - nanite/vsm/tessellation cost; - collision mip and physics queries; - streaming and derived-data readiness. profile the dominant cost; do not apply every lever at once. collision mip - collision mip level controls complex/visibility collision detail. - simple collision mip level controls simple/player collision detail. - higher mip values reduce geometry/memory but increase mismatch from rendered terrain. - epic notes that common cases keep collision mip at 0 and simple collision mip at 1 or 2; validate against the actual movement/query requirements rather than adopting this blindly. - per-component overrides can reduce cost in inaccessible areas. render displacement/tessellation does not automatically redefine gameplay collision. keep visible displacement within the acceptable collision error or provide another collision/gameplay solution. target capture record: - stat unit, stat gpu, insights trace, gpu profile; - visible components/sections and draw calls; - landscape/material/gpu time; - texture, rvt, nanite, and total memory; - streaming hitches at fastest traversal; - collision query behavior and navigation rebuild/pathing; - cold cook/load and warm traversal."},{"slug":"selector-import-layout","file":"selector-import-layout.md","title":"Terrain selector, import, and initial layout","rawMarkdown":"# Terrain selector, import, and initial layout\n\n## Representation selector\n\n| Requirement | Default representation |\n|---|---|\n| Broad continuous ground, hills, valleys | Landscape |\n| Cave, arch, overhang, vertical cut | Static/Nanite mesh integrated with Landscape |\n| Small isolated terrain prop | Static mesh |\n| Road that raises/lowers and paints terrain | Landscape Spline on a Spline Edit Layer |\n| Local procedural height/weight stamp | Landscape Patch on a Patch Edit Layer |\n| Runtime deformable arbitrary surface | A dedicated runtime deformation/mesh solution; Landscape authoring is not the default |\n\nPrototype the transition between Landscape and meshes. Hide seams through placement, material/RVT blending, decals, rocks, or vegetation; do not rely on a single shading trick.\n\n## Before creation/import\n\nRecord:\n\n- playable XY extent and non-playable vista extent;\n- minimum and maximum elevation, including depth below datum;\n- desired XY vertex spacing and smallest shape the heightfield must express;\n- valid heightmap resolution and component topology;\n- World Partition use and tiled-import convention;\n- coordinate origin, tile naming/order, Y-axis orientation, units, and Z-scale formula;\n- source heightmap version and checksum/path for reproducibility.\n\n## Supported heightmap paths\n\nUE 5.8 supports 16-bit grayscale PNG, 8-bit `.r8`, 16-bit `.r16`, and RAW with a JSON sidecar. Prefer 16-bit source data for smooth elevation precision. Target-layer weightmaps are normally single-channel 8-bit data.\n\nFor a new Landscape:\n\n1. Enter Landscape mode (`Shift+2`).\n2. Choose **Import from File** or **Create New**.\n3. Enable Edit Layers.\n4. Select the material only if its Target Layer contract is already known.\n5. For World Partition tiled import, set and record partition grid/region settings and accept the tiled path prompt.\n6. Confirm heightmap resolution, component topology, XY scale, Z scale, and `Flip Y Axis` before import.\n7. Import, then immediately verify seams, orientation, elevation extrema, and world size.\n\n## Z-scale calculation\n\nEpic documents:\n\n```text\nZ scale = elevation range in meters × 100 × 0.001953125\n```\n\nThe source range must include the full desired vertical span, not merely the height above sea level. Document where the source zero/datum maps into the UE height range.\n\n## Existing Landscape import modes\n\n- `Original`: original resolution at gizmo location.\n- `Expand`: expand data to fit.\n- `Resample`: resample to the existing Landscape.\n- `Subregion`: import without resolution checks; used for World Partition subregions.\n\nResampling changes data. Keep the source and export a verification copy after the operation.\n\n## Acceptance\n\n- no tile rotation/flip/seam mismatch;\n- known world points match source coordinates and elevations;\n- slopes and plateaus support intended movement/camera;\n- a round-trip export records the blended result or selected Edit Layer intentionally;\n- the import can be repeated from a clean checkout with the same result.\n","webMarkdown":"## Representation selector\n\n| Requirement | Default representation |\n|---|---|\n| Broad continuous ground, hills, valleys | Landscape |\n| Cave, arch, overhang, vertical cut | Static/Nanite mesh integrated with Landscape |\n| Small isolated terrain prop | Static mesh |\n| Road that raises/lowers and paints terrain | Landscape Spline on a Spline Edit Layer |\n| Local procedural height/weight stamp | Landscape Patch on a Patch Edit Layer |\n| Runtime deformable arbitrary surface | A dedicated runtime deformation/mesh solution; Landscape authoring is not the default |\n\nPrototype the transition between Landscape and meshes. Hide seams through placement, material/RVT blending, decals, rocks, or vegetation; do not rely on a single shading trick.\n\n## Before creation/import\n\nRecord:\n\n- playable XY extent and non-playable vista extent;\n- minimum and maximum elevation, including depth below datum;\n- desired XY vertex spacing and smallest shape the heightfield must express;\n- valid heightmap resolution and component topology;\n- World Partition use and tiled-import convention;\n- coordinate origin, tile naming/order, Y-axis orientation, units, and Z-scale formula;\n- source heightmap version and checksum/path for reproducibility.\n\n## Supported heightmap paths\n\nUE 5.8 supports 16-bit grayscale PNG, 8-bit `.r8`, 16-bit `.r16`, and RAW with a JSON sidecar. Prefer 16-bit source data for smooth elevation precision. Target-layer weightmaps are normally single-channel 8-bit data.\n\nFor a new Landscape:\n\n1. Enter Landscape mode (`Shift+2`).\n2. Choose **Import from File** or **Create New**.\n3. Enable Edit Layers.\n4. Select the material only if its Target Layer contract is already known.\n5. For World Partition tiled import, set and record partition grid/region settings and accept the tiled path prompt.\n6. Confirm heightmap resolution, component topology, XY scale, Z scale, and `Flip Y Axis` before import.\n7. Import, then immediately verify seams, orientation, elevation extrema, and world size.\n\n## Z-scale calculation\n\nEpic documents:\n\n```text\nZ scale = elevation range in meters × 100 × 0.001953125\n```\n\nThe source range must include the full desired vertical span, not merely the height above sea level. Document where the source zero/datum maps into the UE height range.\n\n## Existing Landscape import modes\n\n- `Original`: original resolution at gizmo location.\n- `Expand`: expand data to fit.\n- `Resample`: resample to the existing Landscape.\n- `Subregion`: import without resolution checks; used for World Partition subregions.\n\nResampling changes data. Keep the source and export a verification copy after the operation.\n\n## Acceptance\n\n- no tile rotation/flip/seam mismatch;\n- known world points match source coordinates and elevations;\n- slopes and plateaus support intended movement/camera;\n- a round-trip export records the blended result or selected Edit Layer intentionally;\n- the import can be repeated from a clean checkout with the same result.\n","searchText":"terrain selector, import, and initial layout representation selector | requirement | default representation | |---|---| | broad continuous ground, hills, valleys | landscape | | cave, arch, overhang, vertical cut | static/nanite mesh integrated with landscape | | small isolated terrain prop | static mesh | | road that raises/lowers and paints terrain | landscape spline on a spline edit layer | | local procedural height/weight stamp | landscape patch on a patch edit layer | | runtime deformable arbitrary surface | a dedicated runtime deformation/mesh solution; landscape authoring is not the default | prototype the transition between landscape and meshes. hide seams through placement, material/rvt blending, decals, rocks, or vegetation; do not rely on a single shading trick. before creation/import record: - playable xy extent and non-playable vista extent; - minimum and maximum elevation, including depth below datum; - desired xy vertex spacing and smallest shape the heightfield must express; - valid heightmap resolution and component topology; - world partition use and tiled-import convention; - coordinate origin, tile naming/order, y-axis orientation, units, and z-scale formula; - source heightmap version and checksum/path for reproducibility. supported heightmap paths ue 5.8 supports 16-bit grayscale png, 8-bit .r8, 16-bit .r16, and raw with a json sidecar. prefer 16-bit source data for smooth elevation precision. target-layer weightmaps are normally single-channel 8-bit data. for a new landscape: 1. enter landscape mode (shift+2). 2. choose import from file or create new. 3. enable edit layers. 4. select the material only if its target layer contract is already known. 5. for world partition tiled import, set and record partition grid/region settings and accept the tiled path prompt. 6. confirm heightmap resolution, component topology, xy scale, z scale, and flip y axis before import. 7. import, then immediately verify seams, orientation, elevation extrema, and world size. z-scale calculation epic documents: text z scale = elevation range in meters × 100 × 0.001953125 the source range must include the full desired vertical span, not merely the height above sea level. document where the source zero/datum maps into the ue height range. existing landscape import modes - original: original resolution at gizmo location. - expand: expand data to fit. - resample: resample to the existing landscape. - subregion: import without resolution checks; used for world partition subregions. resampling changes data. keep the source and export a verification copy after the operation. acceptance - no tile rotation/flip/seam mismatch; - known world points match source coordinates and elevations; - slopes and plateaus support intended movement/camera; - a round-trip export records the blended result or selected edit layer intentionally; - the import can be repeated from a clean checkout with the same result."},{"slug":"sources","file":"sources.md","title":"UE 5.8 primary sources","rawMarkdown":"# UE 5.8 primary sources\n\nChecked against Epic's Unreal Engine 5.8 documentation on 2026-07-19.\n\n## Landscape core\n\n- [Landscape Overview](https://dev.epicgames.com/documentation/unreal-engine/landscape-overview?lang=en-US)\n- [Creating Landscapes](https://dev.epicgames.com/documentation/en-us/unreal-engine/creating-landscapes-in-unreal-engine)\n- [Landscape Technical Guide](https://dev.epicgames.com/documentation/unreal-engine/landscape-technical-guide-in-unreal-engine?lang=en-US)\n- [Importing and Exporting Landscape Heightmaps](https://dev.epicgames.com/documentation/unreal-engine/importing-and-exporting-landscape-heightmaps-in-unreal-engine?lang=en-US)\n- [Editing Landscapes](https://dev.epicgames.com/documentation/unreal-engine/editing-landscapes-in-unreal-engine?lang=en-US)\n- [Landscape Edit Layers](https://dev.epicgames.com/documentation/unreal-engine/landscape-edit-layers-in-unreal-engine?lang=en-US)\n- [Landscape Patch System](https://dev.epicgames.com/documentation/en-us/unreal-engine/landscape-patch-system)\n- [Landscape Splines](https://dev.epicgames.com/documentation/unreal-engine/landscape-splines-in-unreal-engine?lang=en-US)\n\n## Shading and population\n\n- [Landscape Materials](https://dev.epicgames.com/documentation/en-us/unreal-engine/landscape-materials-in-unreal-engine)\n- [Landscape Paint Mode](https://dev.epicgames.com/documentation/en-us/unreal-engine/landscape-paint-mode-in-unreal-engine)\n- [Foliage Mode](https://dev.epicgames.com/documentation/en-us/unreal-engine/foliage-mode-in-unreal-engine)\n- [Procedural Foliage Tool](https://dev.epicgames.com/documentation/unreal-engine/procedural-foliage-tool-in-unreal-engine)\n- [Runtime Virtual Texturing](https://dev.epicgames.com/documentation/en-us/unreal-engine/runtime-virtual-texturing-in-unreal-engine)\n- [Water System](https://dev.epicgames.com/documentation/unreal-engine/water-system-in-unreal-engine?lang=en-US)\n\n## Runtime and performance\n\n- [Using Nanite with Landscapes](https://dev.epicgames.com/documentation/unreal-engine/using-nanite-with-landscapes-in-unreal-engine?lang=en-US)\n- [Landscape Collision Guide](https://dev.epicgames.com/documentation/unreal-engine/landscape-collision-guide-in-unreal-engine?lang=en-US)\n- [World Partition](https://dev.epicgames.com/documentation/en-us/unreal-engine/world-partition-in-unreal-engine)\n- [UE 5.8 Release Notes](https://dev.epicgames.com/documentation/unreal-engine/unreal-engine-5-8-release-notes?lang=en-US)\n\n## Maturity notes\n\n- Core Landscape, Edit Layers, materials, splines, foliage, collision, and World Partition integration are documented production workflows.\n- `Landscape.Nanite.LiveRebuildOnModification` is Experimental.\n- Procedural Foliage remains under Experimental editor settings in the current guide.\n- Procedural Vegetation Editor is Experimental and is intentionally not a default workflow in this skill.\n\nPrefer the current 5.8 page and installed-engine console help over remembered behavior from earlier releases.\n","webMarkdown":"Checked against Epic's Unreal Engine 5.8 documentation on 2026-07-19.\n\n## Landscape core\n\n- [Landscape Overview](https://dev.epicgames.com/documentation/unreal-engine/landscape-overview?lang=en-US)\n- [Creating Landscapes](https://dev.epicgames.com/documentation/en-us/unreal-engine/creating-landscapes-in-unreal-engine)\n- [Landscape Technical Guide](https://dev.epicgames.com/documentation/unreal-engine/landscape-technical-guide-in-unreal-engine?lang=en-US)\n- [Importing and Exporting Landscape Heightmaps](https://dev.epicgames.com/documentation/unreal-engine/importing-and-exporting-landscape-heightmaps-in-unreal-engine?lang=en-US)\n- [Editing Landscapes](https://dev.epicgames.com/documentation/unreal-engine/editing-landscapes-in-unreal-engine?lang=en-US)\n- [Landscape Edit Layers](https://dev.epicgames.com/documentation/unreal-engine/landscape-edit-layers-in-unreal-engine?lang=en-US)\n- [Landscape Patch System](https://dev.epicgames.com/documentation/en-us/unreal-engine/landscape-patch-system)\n- [Landscape Splines](https://dev.epicgames.com/documentation/unreal-engine/landscape-splines-in-unreal-engine?lang=en-US)\n\n## Shading and population\n\n- [Landscape Materials](https://dev.epicgames.com/documentation/en-us/unreal-engine/landscape-materials-in-unreal-engine)\n- [Landscape Paint Mode](https://dev.epicgames.com/documentation/en-us/unreal-engine/landscape-paint-mode-in-unreal-engine)\n- [Foliage Mode](https://dev.epicgames.com/documentation/en-us/unreal-engine/foliage-mode-in-unreal-engine)\n- [Procedural Foliage Tool](https://dev.epicgames.com/documentation/unreal-engine/procedural-foliage-tool-in-unreal-engine)\n- [Runtime Virtual Texturing](https://dev.epicgames.com/documentation/en-us/unreal-engine/runtime-virtual-texturing-in-unreal-engine)\n- [Water System](https://dev.epicgames.com/documentation/unreal-engine/water-system-in-unreal-engine?lang=en-US)\n\n## Runtime and performance\n\n- [Using Nanite with Landscapes](https://dev.epicgames.com/documentation/unreal-engine/using-nanite-with-landscapes-in-unreal-engine?lang=en-US)\n- [Landscape Collision Guide](https://dev.epicgames.com/documentation/unreal-engine/landscape-collision-guide-in-unreal-engine?lang=en-US)\n- [World Partition](https://dev.epicgames.com/documentation/en-us/unreal-engine/world-partition-in-unreal-engine)\n- [UE 5.8 Release Notes](https://dev.epicgames.com/documentation/unreal-engine/unreal-engine-5-8-release-notes?lang=en-US)\n\n## Maturity notes\n\n- Core Landscape, Edit Layers, materials, splines, foliage, collision, and World Partition integration are documented production workflows.\n- `Landscape.Nanite.LiveRebuildOnModification` is Experimental.\n- Procedural Foliage remains under Experimental editor settings in the current guide.\n- Procedural Vegetation Editor is Experimental and is intentionally not a default workflow in this skill.\n\nPrefer the current 5.8 page and installed-engine console help over remembered behavior from earlier releases.\n","searchText":"ue 5.8 primary sources checked against epic's unreal engine 5.8 documentation on 2026-07-19. landscape core - landscape overview - creating landscapes - landscape technical guide - importing and exporting landscape heightmaps - editing landscapes - landscape edit layers - landscape patch system - landscape splines shading and population - landscape materials - landscape paint mode - foliage mode - procedural foliage tool - runtime virtual texturing - water system runtime and performance - using nanite with landscapes - landscape collision guide - world partition - ue 5.8 release notes maturity notes - core landscape, edit layers, materials, splines, foliage, collision, and world partition integration are documented production workflows. - landscape.nanite.liverebuildonmodification is experimental. - procedural foliage remains under experimental editor settings in the current guide. - procedural vegetation editor is experimental and is intentionally not a default workflow in this skill. prefer the current 5.8 page and installed-engine console help over remembered behavior from earlier releases."},{"slug":"splines-water-rvt","file":"splines-water-rvt.md","title":"Landscape Splines, water, and RVT","rawMarkdown":"# Landscape Splines, water, and RVT\n\n## Landscape Spline workflow\n\nUse when a road, path, riverbed, or embankment must deform and optionally paint the Landscape.\n\n1. Create a dedicated **Spline Edit Layer**.\n2. Author control points and segments in Landscape Manage mode.\n3. Set width, side falloff, end falloff, tangent/rotation, and segment direction.\n4. Enable `Raise Terrain` and/or `Lower Terrain` only where the segment should deform height.\n5. Assign `Layer Name` when the spline should paint a Target Layer.\n6. Assign spline meshes with consistent forward axis, collision, LOD/Nanite, and material policy.\n7. Inspect intersections, sharp curvature, component boundaries, landscape seams, and navigation.\n\nLandscape Splines do not affect height until a Spline Edit Layer exists. Route general spline motion or spline mesh implementation to `$unreal-splines`.\n\n## Water integration boundary\n\nThe Water plugin supplies spline-driven oceans, lakes, and rivers integrated with Landscape. Establish before authoring:\n\n- water body type and spline ownership;\n- Landscape deformation/Edit Layer ownership;\n- water surface height and terrain datum;\n- shore/riverbank material transition;\n- collision, swimming/boat physics, nav, and gameplay volumes;\n- World Partition loading and distant representation.\n\nDo not let a Water Body, Landscape Spline, manual sculpt, and Patch all deform the same bank without a documented stack order. Verify the terrain with each layer isolated.\n\n## RVT selector\n\nUse Runtime Virtual Texturing when it materially helps:\n\n- cache expensive Landscape shading;\n- blend static meshes/spline roads into terrain;\n- add decal-like static surface contributions;\n- provide a common terrain/object material-data surface.\n\nRVT is a GPU-generated cache, not durable gameplay data. Writers are expected to be static; skeletal, movable, or animated components are poor writers.\n\n## RVT workflow\n\n1. Enable Virtual Texture support and restart.\n2. Create an RVT Asset with a material type and memory/resolution plan.\n3. Make the Landscape material write through `RuntimeVirtualTextureOutput` and sample/fallback intentionally.\n4. Place an RVT Volume and set bounds from the Landscape/required writers.\n5. Add the RVT asset to writer components and choose Main Pass behavior.\n6. Use world-space normals for consistent blending.\n7. Define sort priority when multiple alpha writers overlap; equal-priority order is undefined.\n8. Validate a fallback path for feature levels without RVT when the content must remain visible.\n\n## RVT performance/debug\n\n```text\nstat virtualtexturing\nstat virtualtexturememory\n```\n\n- Larger/more detailed RVTs consume more pool memory and uploads.\n- YCoCg base-color encoding reduces banding but uses about 25% more memory and adds decode cost.\n- A writer rendered only to RVT may still have collision; disable it when not needed.\n- Diagnose missing writers by checking volume bounds, asset/material type match, Render to Virtual Textures, Main Pass setting, and sort priority.\n","webMarkdown":"## Landscape Spline workflow\n\nUse when a road, path, riverbed, or embankment must deform and optionally paint the Landscape.\n\n1. Create a dedicated **Spline Edit Layer**.\n2. Author control points and segments in Landscape Manage mode.\n3. Set width, side falloff, end falloff, tangent/rotation, and segment direction.\n4. Enable `Raise Terrain` and/or `Lower Terrain` only where the segment should deform height.\n5. Assign `Layer Name` when the spline should paint a Target Layer.\n6. Assign spline meshes with consistent forward axis, collision, LOD/Nanite, and material policy.\n7. Inspect intersections, sharp curvature, component boundaries, landscape seams, and navigation.\n\nLandscape Splines do not affect height until a Spline Edit Layer exists. Route general spline motion or spline mesh implementation to `$unreal-splines`.\n\n## Water integration boundary\n\nThe Water plugin supplies spline-driven oceans, lakes, and rivers integrated with Landscape. Establish before authoring:\n\n- water body type and spline ownership;\n- Landscape deformation/Edit Layer ownership;\n- water surface height and terrain datum;\n- shore/riverbank material transition;\n- collision, swimming/boat physics, nav, and gameplay volumes;\n- World Partition loading and distant representation.\n\nDo not let a Water Body, Landscape Spline, manual sculpt, and Patch all deform the same bank without a documented stack order. Verify the terrain with each layer isolated.\n\n## RVT selector\n\nUse Runtime Virtual Texturing when it materially helps:\n\n- cache expensive Landscape shading;\n- blend static meshes/spline roads into terrain;\n- add decal-like static surface contributions;\n- provide a common terrain/object material-data surface.\n\nRVT is a GPU-generated cache, not durable gameplay data. Writers are expected to be static; skeletal, movable, or animated components are poor writers.\n\n## RVT workflow\n\n1. Enable Virtual Texture support and restart.\n2. Create an RVT Asset with a material type and memory/resolution plan.\n3. Make the Landscape material write through `RuntimeVirtualTextureOutput` and sample/fallback intentionally.\n4. Place an RVT Volume and set bounds from the Landscape/required writers.\n5. Add the RVT asset to writer components and choose Main Pass behavior.\n6. Use world-space normals for consistent blending.\n7. Define sort priority when multiple alpha writers overlap; equal-priority order is undefined.\n8. Validate a fallback path for feature levels without RVT when the content must remain visible.\n\n## RVT performance/debug\n\n```text\nstat virtualtexturing\nstat virtualtexturememory\n```\n\n- Larger/more detailed RVTs consume more pool memory and uploads.\n- YCoCg base-color encoding reduces banding but uses about 25% more memory and adds decode cost.\n- A writer rendered only to RVT may still have collision; disable it when not needed.\n- Diagnose missing writers by checking volume bounds, asset/material type match, Render to Virtual Textures, Main Pass setting, and sort priority.\n","searchText":"landscape splines, water, and rvt landscape spline workflow use when a road, path, riverbed, or embankment must deform and optionally paint the landscape. 1. create a dedicated spline edit layer. 2. author control points and segments in landscape manage mode. 3. set width, side falloff, end falloff, tangent/rotation, and segment direction. 4. enable raise terrain and/or lower terrain only where the segment should deform height. 5. assign layer name when the spline should paint a target layer. 6. assign spline meshes with consistent forward axis, collision, lod/nanite, and material policy. 7. inspect intersections, sharp curvature, component boundaries, landscape seams, and navigation. landscape splines do not affect height until a spline edit layer exists. route general spline motion or spline mesh implementation to $unreal-splines. water integration boundary the water plugin supplies spline-driven oceans, lakes, and rivers integrated with landscape. establish before authoring: - water body type and spline ownership; - landscape deformation/edit layer ownership; - water surface height and terrain datum; - shore/riverbank material transition; - collision, swimming/boat physics, nav, and gameplay volumes; - world partition loading and distant representation. do not let a water body, landscape spline, manual sculpt, and patch all deform the same bank without a documented stack order. verify the terrain with each layer isolated. rvt selector use runtime virtual texturing when it materially helps: - cache expensive landscape shading; - blend static meshes/spline roads into terrain; - add decal-like static surface contributions; - provide a common terrain/object material-data surface. rvt is a gpu-generated cache, not durable gameplay data. writers are expected to be static; skeletal, movable, or animated components are poor writers. rvt workflow 1. enable virtual texture support and restart. 2. create an rvt asset with a material type and memory/resolution plan. 3. make the landscape material write through runtimevirtualtextureoutput and sample/fallback intentionally. 4. place an rvt volume and set bounds from the landscape/required writers. 5. add the rvt asset to writer components and choose main pass behavior. 6. use world-space normals for consistent blending. 7. define sort priority when multiple alpha writers overlap; equal-priority order is undefined. 8. validate a fallback path for feature levels without rvt when the content must remain visible. rvt performance/debug text stat virtualtexturing stat virtualtexturememory - larger/more detailed rvts consume more pool memory and uploads. - ycocg base-color encoding reduces banding but uses about 25% more memory and adds decode cost. - a writer rendered only to rvt may still have collision; disable it when not needed. - diagnose missing writers by checking volume bounds, asset/material type match, render to virtual textures, main pass setting, and sort priority."},{"slug":"world-partition-streaming","file":"world-partition-streaming.md","title":"World Partition and Landscape streaming","rawMarkdown":"# World Partition and Landscape streaming\n\nUse with [`../../unreal-world-partition/SKILL.md`](../../unreal-world-partition/SKILL.md). Landscape defines terrain topology; World Partition defines cell residency and streaming sources.\n\n## Large-world setup\n\n1. Choose Landscape topology and source tile convention before World Partition import.\n2. Import tiled heightmaps with recorded `World Partition Grid Size`, `World Partition Region Size`, `Flip Y Axis`, XY scale, and Z scale.\n3. Verify all Landscape Streaming Proxies, component boundaries, edit ownership, and source-control files.\n4. Establish streaming sources/ranges from maximum traversal speed and target-device readiness.\n5. Build and validate Landscape-related HLOD/distant content where applicable.\n6. Rebuild navigation, PCG, foliage, RVT streaming low mips, and Nanite data after relevant Landscape changes.\n\nDo not assume Landscape component, Landscape Streaming Proxy, World Partition cell, HLOD cell, PCG grid, and navigation tile are the same unit. Name each size explicitly.\n\n## Editor workflow\n\n- Load only the region required for an edit, but check seams with neighboring regions loaded.\n- Keep broad import/re-tile operations reproducible and coordinated; they can touch many external actor/proxy files.\n- Disable automatic expensive derived rebuilds while making broad edits only when a deliberate final-build step exists.\n- Use location/region loading and source control to prevent invisible work on unloaded neighbors.\n\n## Seam validation\n\nAt each tile/proxy boundary inspect:\n\n- height continuity and normals;\n- Target Layer/weightmap continuity;\n- material/RVT and virtual-texture behavior;\n- Landscape Spline and Water deformation;\n- collision and physical surface;\n- NavMesh connectivity;\n- PCG/grass/foliage density and exclusion;\n- Nanite proxy freshness and skirt behavior.\n\n## Runtime acceptance\n\n- fastest traversal cannot reach missing terrain collision;\n- camera vistas do not expose unloaded holes or unacceptable LOD changes;\n- returning across cells does not grow memory indefinitely;\n- Runtime Data Layer transitions do not leave terrain-dependent content inconsistent;\n- server and clients have compatible collision/navigation/world state;\n- cooked target traces show streaming, material, and Landscape work inside budgets.\n\nRoute streaming-source, cell, Data Layer, HLOD, and commandlet diagnosis to `$unreal-world-partition`.\n","webMarkdown":"Use with [`../../unreal-world-partition/SKILL.md`](/unreal/unreal-world-partition/). Landscape defines terrain topology; World Partition defines cell residency and streaming sources.\n\n## Large-world setup\n\n1. Choose Landscape topology and source tile convention before World Partition import.\n2. Import tiled heightmaps with recorded `World Partition Grid Size`, `World Partition Region Size`, `Flip Y Axis`, XY scale, and Z scale.\n3. Verify all Landscape Streaming Proxies, component boundaries, edit ownership, and source-control files.\n4. Establish streaming sources/ranges from maximum traversal speed and target-device readiness.\n5. Build and validate Landscape-related HLOD/distant content where applicable.\n6. Rebuild navigation, PCG, foliage, RVT streaming low mips, and Nanite data after relevant Landscape changes.\n\nDo not assume Landscape component, Landscape Streaming Proxy, World Partition cell, HLOD cell, PCG grid, and navigation tile are the same unit. Name each size explicitly.\n\n## Editor workflow\n\n- Load only the region required for an edit, but check seams with neighboring regions loaded.\n- Keep broad import/re-tile operations reproducible and coordinated; they can touch many external actor/proxy files.\n- Disable automatic expensive derived rebuilds while making broad edits only when a deliberate final-build step exists.\n- Use location/region loading and source control to prevent invisible work on unloaded neighbors.\n\n## Seam validation\n\nAt each tile/proxy boundary inspect:\n\n- height continuity and normals;\n- Target Layer/weightmap continuity;\n- material/RVT and virtual-texture behavior;\n- Landscape Spline and Water deformation;\n- collision and physical surface;\n- NavMesh connectivity;\n- PCG/grass/foliage density and exclusion;\n- Nanite proxy freshness and skirt behavior.\n\n## Runtime acceptance\n\n- fastest traversal cannot reach missing terrain collision;\n- camera vistas do not expose unloaded holes or unacceptable LOD changes;\n- returning across cells does not grow memory indefinitely;\n- Runtime Data Layer transitions do not leave terrain-dependent content inconsistent;\n- server and clients have compatible collision/navigation/world state;\n- cooked target traces show streaming, material, and Landscape work inside budgets.\n\nRoute streaming-source, cell, Data Layer, HLOD, and commandlet diagnosis to `$unreal-world-partition`.\n","searchText":"world partition and landscape streaming use with ../../unreal-world-partition/skill.md. landscape defines terrain topology; world partition defines cell residency and streaming sources. large-world setup 1. choose landscape topology and source tile convention before world partition import. 2. import tiled heightmaps with recorded world partition grid size, world partition region size, flip y axis, xy scale, and z scale. 3. verify all landscape streaming proxies, component boundaries, edit ownership, and source-control files. 4. establish streaming sources/ranges from maximum traversal speed and target-device readiness. 5. build and validate landscape-related hlod/distant content where applicable. 6. rebuild navigation, pcg, foliage, rvt streaming low mips, and nanite data after relevant landscape changes. do not assume landscape component, landscape streaming proxy, world partition cell, hlod cell, pcg grid, and navigation tile are the same unit. name each size explicitly. editor workflow - load only the region required for an edit, but check seams with neighboring regions loaded. - keep broad import/re-tile operations reproducible and coordinated; they can touch many external actor/proxy files. - disable automatic expensive derived rebuilds while making broad edits only when a deliberate final-build step exists. - use location/region loading and source control to prevent invisible work on unloaded neighbors. seam validation at each tile/proxy boundary inspect: - height continuity and normals; - target layer/weightmap continuity; - material/rvt and virtual-texture behavior; - landscape spline and water deformation; - collision and physical surface; - navmesh connectivity; - pcg/grass/foliage density and exclusion; - nanite proxy freshness and skirt behavior. runtime acceptance - fastest traversal cannot reach missing terrain collision; - camera vistas do not expose unloaded holes or unacceptable lod changes; - returning across cells does not grow memory indefinitely; - runtime data layer transitions do not leave terrain-dependent content inconsistent; - server and clients have compatible collision/navigation/world state; - cooked target traces show streaming, material, and landscape work inside budgets. route streaming-source, cell, data layer, hlod, and commandlet diagnosis to $unreal-world-partition."}]}
{"slug":"unreal-lighting","name":"unreal-lighting","title":"Unreal 5.8 Lighting","description":"Design, tune, profile, and debug lighting in Unreal Engine 5.8. Use for Lumen GI and reflections, MegaLights, physical light units, exposure and eye adaptation, Directional/Sky/Point/Spot/Rect Lights, Sky Atmosphere, fog, clouds, shadows, interiors, exteriors, day-night scenes, mood targets, or lighting performance problems.","shortDescription":"Tune Lumen, exposure, lights, and atmosphere","category":"Rendering & VFX","referenceCount":4,"rawMarkdown":"---\nname: unreal-lighting\ndescription: Design, tune, profile, and debug lighting in Unreal Engine 5.8. Use for Lumen GI and reflections, MegaLights, physical light units, exposure and eye adaptation, Directional/Sky/Point/Spot/Rect Lights, Sky Atmosphere, fog, clouds, shadows, interiors, exteriors, day-night scenes, mood targets, or lighting performance problems.\n---\n\n# Unreal 5.8 Lighting\n\n## Ownership boundary\n\nThis skill owns artistic light, exposure, atmosphere, physical units, and target-look setup. If the\nrequest is an unmeasured performance complaint, start with\n[`unreal-insights-profiling`](../unreal-insights-profiling/SKILL.md); after a render/GPU bound is\nmeasured, route optimization to\n[`unreal-rendering-performance`](../unreal-rendering-performance/SKILL.md). Route shader/surface graph\narchitecture to [`unreal-materials`](../unreal-materials/SKILL.md).\n\n## Establish constraints first\n\nRecord:\n\n- target platforms and frame-rate budget;\n- deferred/forward renderer and scalability target;\n- dynamic versus baked lighting requirement;\n- Lumen software or hardware ray tracing;\n- MegaLights enabled or disabled;\n- intended exposure behavior: fixed, bounded adaptation, or full adaptation;\n- reference image and desired focal hierarchy.\n\nDo not tune lighting before exposure behavior is deliberate. A changing camera exposure\ncan hide whether the light or the exposure is wrong.\n\n## Execute\n\n1. Choose the rendering path and mobility.\n2. Establish exposure and physical units.\n3. Build broad environment light before local accents.\n4. Add local lights with the smallest useful bounds.\n5. Tune shadow softness with emitter size, not arbitrary intensity changes.\n6. Inspect Lumen, exposure, shadow, and light-complexity visualizations.\n7. Profile on target hardware.\n\nRead:\n\n- [`references/parameter-effects.md`](references/parameter-effects.md) for control behavior.\n- [`references/recipes.md`](references/recipes.md) for concrete target looks.\n- [`references/diagnostics.md`](references/diagnostics.md) for failures and performance.\n\n## Required answer format\n\nReturn:\n\n1. **Rendering/exposure assumptions**.\n2. **Actor and component setup**.\n3. **Ordered changes**, naming UE 5.8 properties and editor locations.\n4. **Parameter direction**: what increasing or decreasing each value does.\n5. **Starting values only when documented or physically grounded**; otherwise give a\n   bounded tuning procedure.\n6. **Debug views and console checks**.\n7. **Performance validation** on the requested target.\n\nNever prescribe an isolated intensity number without its light type, units, exposure,\ndistance, source size, and target platform.\n\n## Hard rules\n\n- Use Lux for Directional Light, cd/m² for Sky Light luminance, and Candela/Lumens for\n  local lights when inverse-square falloff is enabled.\n- Treat attenuation radius as an influence bound, not a brightness control.\n- Treat exposure compensation in stops: `+1` doubles displayed brightness; `-1` halves it.\n- Equal Min/Max EV100 disables auto exposure.\n- With Lumen enabled, precomputed static lighting contributions are disabled/hidden.\n- MegaLights handles local lights. Sky Light remains outside it. Directional Light support is\n  opt-in with `r.MegaLights.DirectionalLights 1`, disabled by default, and has documented\n  quality limitations; prefer Deferred Lighting with VSM for a strong sun unless target tests\n  justify the MegaLights path.\n- Narrow overlapping light bounds. MegaLights has fixed sampling; excessive local\n  complexity reduces quality instead of scaling cost conventionally.\n- Mark experimental features as experimental and provide a shippable fallback.\n- Validate with visualizations and profiling, not the editor beauty view alone.\n\nSee [`references/sources.md`](references/sources.md) for the UE 5.8 source trail.\n","webMarkdown":"## Ownership boundary\n\nThis skill owns artistic light, exposure, atmosphere, physical units, and target-look setup. If the\nrequest is an unmeasured performance complaint, start with\n[`unreal-insights-profiling`](/unreal/unreal-insights-profiling/); after a render/GPU bound is\nmeasured, route optimization to\n[`unreal-rendering-performance`](/unreal/unreal-rendering-performance/). Route shader/surface graph\narchitecture to [`unreal-materials`](/unreal/unreal-materials/).\n\n## Establish constraints first\n\nRecord:\n\n- target platforms and frame-rate budget;\n- deferred/forward renderer and scalability target;\n- dynamic versus baked lighting requirement;\n- Lumen software or hardware ray tracing;\n- MegaLights enabled or disabled;\n- intended exposure behavior: fixed, bounded adaptation, or full adaptation;\n- reference image and desired focal hierarchy.\n\nDo not tune lighting before exposure behavior is deliberate. A changing camera exposure\ncan hide whether the light or the exposure is wrong.\n\n## Execute\n\n1. Choose the rendering path and mobility.\n2. Establish exposure and physical units.\n3. Build broad environment light before local accents.\n4. Add local lights with the smallest useful bounds.\n5. Tune shadow softness with emitter size, not arbitrary intensity changes.\n6. Inspect Lumen, exposure, shadow, and light-complexity visualizations.\n7. Profile on target hardware.\n\nRead:\n\n- [`references/parameter-effects.md`](/unreal/unreal-lighting/parameter-effects/) for control behavior.\n- [`references/recipes.md`](/unreal/unreal-lighting/recipes/) for concrete target looks.\n- [`references/diagnostics.md`](/unreal/unreal-lighting/diagnostics/) for failures and performance.\n\n## Required answer format\n\nReturn:\n\n1. **Rendering/exposure assumptions**.\n2. **Actor and component setup**.\n3. **Ordered changes**, naming UE 5.8 properties and editor locations.\n4. **Parameter direction**: what increasing or decreasing each value does.\n5. **Starting values only when documented or physically grounded**; otherwise give a\n   bounded tuning procedure.\n6. **Debug views and console checks**.\n7. **Performance validation** on the requested target.\n\nNever prescribe an isolated intensity number without its light type, units, exposure,\ndistance, source size, and target platform.\n\n## Hard rules\n\n- Use Lux for Directional Light, cd/m² for Sky Light luminance, and Candela/Lumens for\n  local lights when inverse-square falloff is enabled.\n- Treat attenuation radius as an influence bound, not a brightness control.\n- Treat exposure compensation in stops: `+1` doubles displayed brightness; `-1` halves it.\n- Equal Min/Max EV100 disables auto exposure.\n- With Lumen enabled, precomputed static lighting contributions are disabled/hidden.\n- MegaLights handles local lights. Sky Light remains outside it. Directional Light support is\n  opt-in with `r.MegaLights.DirectionalLights 1`, disabled by default, and has documented\n  quality limitations; prefer Deferred Lighting with VSM for a strong sun unless target tests\n  justify the MegaLights path.\n- Narrow overlapping light bounds. MegaLights has fixed sampling; excessive local\n  complexity reduces quality instead of scaling cost conventionally.\n- Mark experimental features as experimental and provide a shippable fallback.\n- Validate with visualizations and profiling, not the editor beauty view alone.\n\nSee [`references/sources.md`](/unreal/unreal-lighting/sources/) for the UE 5.8 source trail.\n","searchText":"unreal 5.8 lighting design, tune, profile, and debug lighting in unreal engine 5.8. use for lumen gi and reflections, megalights, physical light units, exposure and eye adaptation, directional/sky/point/spot/rect lights, sky atmosphere, fog, clouds, shadows, interiors, exteriors, day-night scenes, mood targets, or lighting performance problems. diagnostics and validation diagnostics and validation | symptom | check | action | |---|---|---| | everything is too bright/dark | exposure mode, ev100, compensation | lock manual exposure; establish light values; then restore bounded adaptation | | bright object at screen edge pumps exposure | hdr histogram / metering | add center-weighted exposure metering mask or narrow histogram selection | | interior is black with lumen | surface cache/card coverage, mesh scale/topology | split overly complex meshes; verify distance fields and lumen representation | | light leaks through thin walls | lumen representation, wall thickness, shadow method | increase physical thickness; inspect distance fields; choose appropriate tracing/shadow path | | reflections miss objects | lumen reflection mode/scene representation | inspect lumen scene; consider hardware rt where target supports it | | soft shadow is wrong | source size, not intensity | tune source radius/width/height/angle | | local light costs too much | bounds, shadows, overlaps | reduce attenuation, disable unnecessary shadows, profile megalights versus conventional path | | megalights looks noisy/blurry | too many important overlapping lights per pixel | narrow bounds, merge small lights, reduce local complexity | | megalights ghosts in motion | denoiser under high stochastic complexity | simplify overlapping lights; test shadow method and temporal behavior | | fog glows everywhere | volumetric scattering and large light bounds | lower scattering; narrow bounds; remove irrelevant fog contribution | | day/night color looks fake | manual tint fights sky atmosphere | return sun toward neutral and let atmospheric scattering drive color | | emissive surface does not light enough | emissive is visible but gi contribution is insufficient/noisy | add a matching controlled light; do not rely on tiny bright emissives alone | | shadow acne/peter-panning | bias settings or geometry | inspect geometry/normals; tune bias minimally; verify vsm/ray-traced path | debug sequence 1. disable stylistic post effects that obscure diagnosis. 2. lock exposure. 3. inspect unlit/material values where relevant. 4. inspect hdr (eye adaptation). 5. inspect lumen overview, surface cache, and reflection views. 6. inspect shadow/vsm or ray-tracing debug views. 7. inspect light bounds and overlapping influence. 8. measure gpu timing on target hardware and intended scalability. 9. re-enable post effects one category at a time. acceptance checks - focal subject reads at gameplay camera distance. - exposure transitions behave intentionally in both directions. - direct, indirect, reflection, emissive, and volumetric contributions are identifiable. - no major light leaks, black lumen surfaces, temporal ghosting, or unstable pumping. - scene remains legible at required scalability tiers. - gpu cost meets the declared budget on target hardware. parameter effects parameter effects contents - light selection - core light properties - mobility - exposure - physical-unit anchors - lumen - megalights light selection | need | light | |---|---| | sun, moon, or effectively infinite source | directional light | | captured environment/sky contribution | sky light | | bare bulb or omnidirectional fixture | point light | | flashlight, headlamp, stage cone | spot light | | window, panel, fluorescent fixture, softbox | rect light | core light properties | property | increase | decrease / caution | |---|---|---| | intensity | more direct contribution in the selected physical unit | interpret only with exposure and distance | | temperature | cooler/bluer at higher kelvin | warmer/oranger at lower kelvin; avoid double-tinting a physically scattered sun unless stylized | | attenuation radius | affects more geometry and increases overlap | not a brightness control; keep close to useful influence | | source radius / soft source radius | larger apparent emitter; softer, broader shadows/reflections | excessive size can erase contact definition | | source length | elongates emitter and shadow softness | match tube/strip fixture shape | | indirect lighting intensity | scales bounced contribution from this light | nonphysical artistic override; debug gi before using | | volumetric scattering intensity | stronger effect in participating media | can create fog glow/noise and flatten contrast | | specular scale | changes specular response | keep at default for physical work; use only as a deliberate art override | spot light - inner cone angle: fully lit core. - outer cone angle: full edge of influence. - larger gap between inner and outer angles creates a softer penumbra. - use ies profiles for fixture distribution when available instead of hand-shaping every falloff. rect light - source width/height define emitter size and reflection shape. - use for windows and panels where emitter geometry matters. - face the emitting side toward the scene. mobility | mobility | use | cost/constraint | |---|---|---| | static | never changes; baked lightmass workflow | requires precomputed lighting; not useful as a lumen dynamic source | | stationary | color/intensity may change, transform stays fixed | mixed baked/dynamic constraints; overlapping stationary limits apply | | movable | transform and properties change at runtime | fully dynamic shadows; profile shadow path | for lumen-first fully dynamic projects, movable lights are the normal baseline. do not choose mobility from habit; choose it from the rendering path. exposure | control | effect | |---|---| | metering mode: manual | fixed exposure; camera/light comparison is stable | | histogram | 64-bin adaptive exposure; default adaptive mode | | exposure compensation | offset in stops; +1 = 2× brighter, -1 = 2× darker | | min/max ev100 | clamp adaptation range; equal values disable adaptation | | speed up | adaptation rate from dark environment/view to bright | | speed down | adaptation rate from bright environment/view to dark | | metering mask | weights screen regions; center weighting reduces edge-light pumping | | low/high percent | select histogram range used for target exposure; extreme values can destabilize or clip | workflow: 1. use manual exposure while establishing physically plausible lights. 2. enable hdr (eye adaptation) visualization. 3. if adaptation is required, set a purposeful min/max ev100 range. 4. set speed from desired perceptual behavior. 5. add a metering mask if peripheral bright objects cause pumping. 6. use local exposure only after global exposure and light values are sound. physical-unit anchors - ue documents a zenith sun around 120,000 lux with a 0.545° angular diameter. - a perpendicular white diffuse surface under that sun may receive roughly 150,000 lux total. - point/spot/rect lights can use candela or lumens when inverse-square falloff is on. - 1000 cd produces 1000 lux at one meter for a perpendicular receiver in the documented example. use real fixture specifications as starting points. do not compensate for incorrect exposure by multiplying every light arbitrarily. lumen - dynamic global illumination: lumen. - reflection method: lumen. - software tracing requires generate mesh distance fields. - hardware ray tracing improves representation/quality in supported cases but costs more and requires compatible hardware. - high scalability targets lumen gi/reflections for 60 fps on current-generation consoles; epic targets cleaner indoor lighting at 30 fps. - inspect surface cache/card visualization when meshes appear black or fail to bounce light. megalights - enable under project settings > rendering > direct lighting. - hardware ray tracing support is recommended. - all local lights are handled when enabled; disable per light with allow megalights. - directional light support is disabled by default. enable it with r.megalights.directionallights 1 only after testing: epic recommends deferred lighting with vsm for a strong sun, while megalights may fit a dim, soft moonlight. sky light is not handled. - select ray tracing or virtual shadow maps per light as shadow method. - disable by scalability/device profile with r.megalights.allow 0. - avoid huge light bounds. merge many tiny emitters when they create noise, blur, or ghosting at the same pixels. lighting recipes lighting recipes physically based clear daylight 1. add directional light, sky atmosphere, sky light, and optional volumetric clouds. 2. enable atmosphere sun light on the directional light. 3. set directional light in lux; use approximately 120,000 lux for a documented zenith sun starting point. 4. enable sky light real time capture for dynamic time of day. 5. start with manual exposure; inspect hdr eye adaptation values. 6. rotate the directional light for time of day before altering intensity/color. 7. enable bounded auto exposure only after the noon reference is stable. 8. verify shadow, atmosphere, cloud, lumen, and target-platform cost. golden hour 1. lower the directional light angle near the horizon. 2. let sky atmosphere produce longer optical paths and warm scattering first. 3. increase mie contribution/anisotropy only when the desired haze is missing; inspect silhouettes and aerial perspective. 4. preserve a cooler sky light/environment contrast unless the art target is uniformly warm. 5. use restrained exposure compensation; do not turn sunset into daylight brightness. 6. add local practicals only to guide focal hierarchy. night exterior that still reads as night 1. use a second atmospheric directional light for moon if required; set atmosphere sun light index appropriately. 2. reduce broad environment contribution rather than crushing blacks with post color. 3. clamp auto exposure so the camera cannot adapt the night back to daytime. 4. place local lights in purposeful pools; minimize attenuation overlap. 5. keep navigable silhouettes and landmark contrast. 6. check emissives at gameplay distance; use real lights when they must illuminate. 7. verify local-light noise/ghosting with megalights enabled. interior lit by windows 1. establish exterior directional/sky lighting and exposure. 2. use lumen for indirect bounce. 3. add rect lights at important apertures only when the dynamic solution needs an art- directed key or stronger directionality. 4. match rect light dimensions/orientation to the opening. 5. keep attenuation bounds inside the useful room volume. 6. inspect lumen surface cache and mesh modularity when interiors stay black. 7. compare interior-to-exterior exposure transition and set speed up/down intentionally. practical-lit interior 1. give emissive materials plausible luminance for visible fixture surfaces. 2. pair important fixtures with point/spot/rect lights for controlled illumination. 3. match source size and shape to the fixture. 4. use ies profiles for real fixture distributions where available. 5. limit attenuation to the room/area of influence. 6. with megalights, merge clusters that produce stochastic blur or ghosting at the same pixels. 7. test with fog/translucency because megalights includes those paths. horror or high-contrast scene 1. lock or tightly bound exposure; uncontrolled eye adaptation destroys authored darkness. 2. preserve readable navigation and interactable silhouettes. 3. use small areas of motivated light rather than globally lowering every value. 4. control source radius: smaller sources create harder, more threatening shadows; larger sources create softer ambiguity. 5. use volumetric scattering only where it supports composition. 6. test black-level visibility on the target display and scalability tiers. stylized scene 1. start from stable exposure and functional key/fill separation. 2. use temperature/color and indirect intensity as deliberate nonphysical controls. 3. keep values consistent by light role, not per-object improvisation. 4. validate material roughness and albedo before fixing every problem with lights. 5. preserve performance rules: bounded lights, intentional shadows, target profiling. ue 5.8 primary sources ue 5.8 primary sources - epic games, lighting the environment - epic games, physical lighting units - epic games, auto exposure - epic games, light types and mobility - epic games, lumen global illumination and reflections - epic games, lumen technical details - epic games, megalights - epic games, environmental light with fog, clouds, sky and atmosphere - epic games, sky atmosphere - epic games, shadowing version target: unreal engine 5.8. recheck defaults, scalability behavior, and feature status before using this skill with a later engine version.","references":[{"slug":"diagnostics","file":"diagnostics.md","title":"Diagnostics and validation","rawMarkdown":"# Diagnostics and validation\n\n| Symptom | Check | Action |\n|---|---|---|\n| Everything is too bright/dark | Exposure mode, EV100, compensation | Lock Manual exposure; establish light values; then restore bounded adaptation |\n| Bright object at screen edge pumps exposure | HDR histogram / metering | Add center-weighted Exposure Metering Mask or narrow histogram selection |\n| Interior is black with Lumen | Surface Cache/Card coverage, mesh scale/topology | Split overly complex meshes; verify distance fields and Lumen representation |\n| Light leaks through thin walls | Lumen representation, wall thickness, shadow method | Increase physical thickness; inspect distance fields; choose appropriate tracing/shadow path |\n| Reflections miss objects | Lumen reflection mode/scene representation | Inspect Lumen scene; consider hardware RT where target supports it |\n| Soft shadow is wrong | Source size, not intensity | Tune Source Radius/Width/Height/Angle |\n| Local light costs too much | Bounds, shadows, overlaps | Reduce attenuation, disable unnecessary shadows, profile MegaLights versus conventional path |\n| MegaLights looks noisy/blurry | Too many important overlapping lights per pixel | Narrow bounds, merge small lights, reduce local complexity |\n| MegaLights ghosts in motion | Denoiser under high stochastic complexity | Simplify overlapping lights; test shadow method and temporal behavior |\n| Fog glows everywhere | Volumetric scattering and large light bounds | Lower scattering; narrow bounds; remove irrelevant fog contribution |\n| Day/night color looks fake | Manual tint fights Sky Atmosphere | Return sun toward neutral and let atmospheric scattering drive color |\n| Emissive surface does not light enough | Emissive is visible but GI contribution is insufficient/noisy | Add a matching controlled light; do not rely on tiny bright emissives alone |\n| Shadow acne/peter-panning | Bias settings or geometry | Inspect geometry/normals; tune bias minimally; verify VSM/ray-traced path |\n\n## Debug sequence\n\n1. Disable stylistic post effects that obscure diagnosis.\n2. Lock exposure.\n3. Inspect unlit/material values where relevant.\n4. Inspect HDR (Eye Adaptation).\n5. Inspect Lumen Overview, Surface Cache, and reflection views.\n6. Inspect shadow/VSM or ray-tracing debug views.\n7. Inspect light bounds and overlapping influence.\n8. Measure GPU timing on target hardware and intended scalability.\n9. Re-enable post effects one category at a time.\n\n## Acceptance checks\n\n- Focal subject reads at gameplay camera distance.\n- Exposure transitions behave intentionally in both directions.\n- Direct, indirect, reflection, emissive, and volumetric contributions are identifiable.\n- No major light leaks, black Lumen surfaces, temporal ghosting, or unstable pumping.\n- Scene remains legible at required scalability tiers.\n- GPU cost meets the declared budget on target hardware.\n","webMarkdown":"| Symptom | Check | Action |\n|---|---|---|\n| Everything is too bright/dark | Exposure mode, EV100, compensation | Lock Manual exposure; establish light values; then restore bounded adaptation |\n| Bright object at screen edge pumps exposure | HDR histogram / metering | Add center-weighted Exposure Metering Mask or narrow histogram selection |\n| Interior is black with Lumen | Surface Cache/Card coverage, mesh scale/topology | Split overly complex meshes; verify distance fields and Lumen representation |\n| Light leaks through thin walls | Lumen representation, wall thickness, shadow method | Increase physical thickness; inspect distance fields; choose appropriate tracing/shadow path |\n| Reflections miss objects | Lumen reflection mode/scene representation | Inspect Lumen scene; consider hardware RT where target supports it |\n| Soft shadow is wrong | Source size, not intensity | Tune Source Radius/Width/Height/Angle |\n| Local light costs too much | Bounds, shadows, overlaps | Reduce attenuation, disable unnecessary shadows, profile MegaLights versus conventional path |\n| MegaLights looks noisy/blurry | Too many important overlapping lights per pixel | Narrow bounds, merge small lights, reduce local complexity |\n| MegaLights ghosts in motion | Denoiser under high stochastic complexity | Simplify overlapping lights; test shadow method and temporal behavior |\n| Fog glows everywhere | Volumetric scattering and large light bounds | Lower scattering; narrow bounds; remove irrelevant fog contribution |\n| Day/night color looks fake | Manual tint fights Sky Atmosphere | Return sun toward neutral and let atmospheric scattering drive color |\n| Emissive surface does not light enough | Emissive is visible but GI contribution is insufficient/noisy | Add a matching controlled light; do not rely on tiny bright emissives alone |\n| Shadow acne/peter-panning | Bias settings or geometry | Inspect geometry/normals; tune bias minimally; verify VSM/ray-traced path |\n\n## Debug sequence\n\n1. Disable stylistic post effects that obscure diagnosis.\n2. Lock exposure.\n3. Inspect unlit/material values where relevant.\n4. Inspect HDR (Eye Adaptation).\n5. Inspect Lumen Overview, Surface Cache, and reflection views.\n6. Inspect shadow/VSM or ray-tracing debug views.\n7. Inspect light bounds and overlapping influence.\n8. Measure GPU timing on target hardware and intended scalability.\n9. Re-enable post effects one category at a time.\n\n## Acceptance checks\n\n- Focal subject reads at gameplay camera distance.\n- Exposure transitions behave intentionally in both directions.\n- Direct, indirect, reflection, emissive, and volumetric contributions are identifiable.\n- No major light leaks, black Lumen surfaces, temporal ghosting, or unstable pumping.\n- Scene remains legible at required scalability tiers.\n- GPU cost meets the declared budget on target hardware.\n","searchText":"diagnostics and validation | symptom | check | action | |---|---|---| | everything is too bright/dark | exposure mode, ev100, compensation | lock manual exposure; establish light values; then restore bounded adaptation | | bright object at screen edge pumps exposure | hdr histogram / metering | add center-weighted exposure metering mask or narrow histogram selection | | interior is black with lumen | surface cache/card coverage, mesh scale/topology | split overly complex meshes; verify distance fields and lumen representation | | light leaks through thin walls | lumen representation, wall thickness, shadow method | increase physical thickness; inspect distance fields; choose appropriate tracing/shadow path | | reflections miss objects | lumen reflection mode/scene representation | inspect lumen scene; consider hardware rt where target supports it | | soft shadow is wrong | source size, not intensity | tune source radius/width/height/angle | | local light costs too much | bounds, shadows, overlaps | reduce attenuation, disable unnecessary shadows, profile megalights versus conventional path | | megalights looks noisy/blurry | too many important overlapping lights per pixel | narrow bounds, merge small lights, reduce local complexity | | megalights ghosts in motion | denoiser under high stochastic complexity | simplify overlapping lights; test shadow method and temporal behavior | | fog glows everywhere | volumetric scattering and large light bounds | lower scattering; narrow bounds; remove irrelevant fog contribution | | day/night color looks fake | manual tint fights sky atmosphere | return sun toward neutral and let atmospheric scattering drive color | | emissive surface does not light enough | emissive is visible but gi contribution is insufficient/noisy | add a matching controlled light; do not rely on tiny bright emissives alone | | shadow acne/peter-panning | bias settings or geometry | inspect geometry/normals; tune bias minimally; verify vsm/ray-traced path | debug sequence 1. disable stylistic post effects that obscure diagnosis. 2. lock exposure. 3. inspect unlit/material values where relevant. 4. inspect hdr (eye adaptation). 5. inspect lumen overview, surface cache, and reflection views. 6. inspect shadow/vsm or ray-tracing debug views. 7. inspect light bounds and overlapping influence. 8. measure gpu timing on target hardware and intended scalability. 9. re-enable post effects one category at a time. acceptance checks - focal subject reads at gameplay camera distance. - exposure transitions behave intentionally in both directions. - direct, indirect, reflection, emissive, and volumetric contributions are identifiable. - no major light leaks, black lumen surfaces, temporal ghosting, or unstable pumping. - scene remains legible at required scalability tiers. - gpu cost meets the declared budget on target hardware."},{"slug":"parameter-effects","file":"parameter-effects.md","title":"Parameter effects","rawMarkdown":"# Parameter effects\n\n## Contents\n\n- [Light selection](#light-selection)\n- [Core light properties](#core-light-properties)\n- [Mobility](#mobility)\n- [Exposure](#exposure)\n- [Physical-unit anchors](#physical-unit-anchors)\n- [Lumen](#lumen)\n- [MegaLights](#megalights)\n\n## Light selection\n\n| Need | Light |\n|---|---|\n| Sun, moon, or effectively infinite source | Directional Light |\n| Captured environment/sky contribution | Sky Light |\n| Bare bulb or omnidirectional fixture | Point Light |\n| Flashlight, headlamp, stage cone | Spot Light |\n| Window, panel, fluorescent fixture, softbox | Rect Light |\n\n## Core light properties\n\n| Property | Increase | Decrease / caution |\n|---|---|---|\n| Intensity | More direct contribution in the selected physical unit | Interpret only with exposure and distance |\n| Temperature | Cooler/bluer at higher Kelvin | Warmer/oranger at lower Kelvin; avoid double-tinting a physically scattered sun unless stylized |\n| Attenuation Radius | Affects more geometry and increases overlap | Not a brightness control; keep close to useful influence |\n| Source Radius / Soft Source Radius | Larger apparent emitter; softer, broader shadows/reflections | Excessive size can erase contact definition |\n| Source Length | Elongates emitter and shadow softness | Match tube/strip fixture shape |\n| Indirect Lighting Intensity | Scales bounced contribution from this light | Nonphysical artistic override; debug GI before using |\n| Volumetric Scattering Intensity | Stronger effect in participating media | Can create fog glow/noise and flatten contrast |\n| Specular Scale | Changes specular response | Keep at default for physical work; use only as a deliberate art override |\n\n### Spot Light\n\n- Inner Cone Angle: fully lit core.\n- Outer Cone Angle: full edge of influence.\n- Larger gap between inner and outer angles creates a softer penumbra.\n- Use IES profiles for fixture distribution when available instead of hand-shaping every\n  falloff.\n\n### Rect Light\n\n- Source Width/Height define emitter size and reflection shape.\n- Use for windows and panels where emitter geometry matters.\n- Face the emitting side toward the scene.\n\n## Mobility\n\n| Mobility | Use | Cost/constraint |\n|---|---|---|\n| Static | Never changes; baked Lightmass workflow | Requires precomputed lighting; not useful as a Lumen dynamic source |\n| Stationary | Color/intensity may change, transform stays fixed | Mixed baked/dynamic constraints; overlapping Stationary limits apply |\n| Movable | Transform and properties change at runtime | Fully dynamic shadows; profile shadow path |\n\nFor Lumen-first fully dynamic projects, Movable lights are the normal baseline. Do not\nchoose mobility from habit; choose it from the rendering path.\n\n## Exposure\n\n| Control | Effect |\n|---|---|\n| Metering Mode: Manual | Fixed exposure; camera/light comparison is stable |\n| Histogram | 64-bin adaptive exposure; default adaptive mode |\n| Exposure Compensation | Offset in stops; `+1` = 2× brighter, `-1` = 2× darker |\n| Min/Max EV100 | Clamp adaptation range; equal values disable adaptation |\n| Speed Up | Adaptation rate from dark environment/view to bright |\n| Speed Down | Adaptation rate from bright environment/view to dark |\n| Metering Mask | Weights screen regions; center weighting reduces edge-light pumping |\n| Low/High Percent | Select histogram range used for target exposure; extreme values can destabilize or clip |\n\nWorkflow:\n\n1. Use Manual exposure while establishing physically plausible lights.\n2. Enable HDR (Eye Adaptation) visualization.\n3. If adaptation is required, set a purposeful Min/Max EV100 range.\n4. Set speed from desired perceptual behavior.\n5. Add a metering mask if peripheral bright objects cause pumping.\n6. Use Local Exposure only after global exposure and light values are sound.\n\n## Physical-unit anchors\n\n- UE documents a zenith sun around **120,000 lux** with a 0.545° angular diameter.\n- A perpendicular white diffuse surface under that sun may receive roughly **150,000\n  lux** total.\n- Point/Spot/Rect Lights can use Candela or Lumens when inverse-square falloff is on.\n- `1000 cd` produces `1000 lux` at one meter for a perpendicular receiver in the\n  documented example.\n\nUse real fixture specifications as starting points. Do not compensate for incorrect\nexposure by multiplying every light arbitrarily.\n\n## Lumen\n\n- Dynamic Global Illumination: Lumen.\n- Reflection Method: Lumen.\n- Software tracing requires Generate Mesh Distance Fields.\n- Hardware ray tracing improves representation/quality in supported cases but costs\n  more and requires compatible hardware.\n- High scalability targets Lumen GI/reflections for 60 FPS on current-generation\n  consoles; Epic targets cleaner indoor lighting at 30 FPS.\n- Inspect Surface Cache/Card visualization when meshes appear black or fail to bounce\n  light.\n\n## MegaLights\n\n- Enable under Project Settings > Rendering > Direct Lighting.\n- Hardware ray tracing support is recommended.\n- All local lights are handled when enabled; disable per light with `Allow MegaLights`.\n- Directional Light support is disabled by default. Enable it with\n  `r.MegaLights.DirectionalLights 1` only after testing: Epic recommends Deferred Lighting with\n  VSM for a strong sun, while MegaLights may fit a dim, soft moonlight. Sky Light is not handled.\n- Select Ray Tracing or Virtual Shadow Maps per light as shadow method.\n- Disable by scalability/device profile with `r.MegaLights.Allow 0`.\n- Avoid huge light bounds. Merge many tiny emitters when they create noise, blur, or\n  ghosting at the same pixels.\n","webMarkdown":"## Contents\n\n- [Light selection](#light-selection)\n- [Core light properties](#core-light-properties)\n- [Mobility](#mobility)\n- [Exposure](#exposure)\n- [Physical-unit anchors](#physical-unit-anchors)\n- [Lumen](#lumen)\n- [MegaLights](#megalights)\n\n## Light selection\n\n| Need | Light |\n|---|---|\n| Sun, moon, or effectively infinite source | Directional Light |\n| Captured environment/sky contribution | Sky Light |\n| Bare bulb or omnidirectional fixture | Point Light |\n| Flashlight, headlamp, stage cone | Spot Light |\n| Window, panel, fluorescent fixture, softbox | Rect Light |\n\n## Core light properties\n\n| Property | Increase | Decrease / caution |\n|---|---|---|\n| Intensity | More direct contribution in the selected physical unit | Interpret only with exposure and distance |\n| Temperature | Cooler/bluer at higher Kelvin | Warmer/oranger at lower Kelvin; avoid double-tinting a physically scattered sun unless stylized |\n| Attenuation Radius | Affects more geometry and increases overlap | Not a brightness control; keep close to useful influence |\n| Source Radius / Soft Source Radius | Larger apparent emitter; softer, broader shadows/reflections | Excessive size can erase contact definition |\n| Source Length | Elongates emitter and shadow softness | Match tube/strip fixture shape |\n| Indirect Lighting Intensity | Scales bounced contribution from this light | Nonphysical artistic override; debug GI before using |\n| Volumetric Scattering Intensity | Stronger effect in participating media | Can create fog glow/noise and flatten contrast |\n| Specular Scale | Changes specular response | Keep at default for physical work; use only as a deliberate art override |\n\n### Spot Light\n\n- Inner Cone Angle: fully lit core.\n- Outer Cone Angle: full edge of influence.\n- Larger gap between inner and outer angles creates a softer penumbra.\n- Use IES profiles for fixture distribution when available instead of hand-shaping every\n  falloff.\n\n### Rect Light\n\n- Source Width/Height define emitter size and reflection shape.\n- Use for windows and panels where emitter geometry matters.\n- Face the emitting side toward the scene.\n\n## Mobility\n\n| Mobility | Use | Cost/constraint |\n|---|---|---|\n| Static | Never changes; baked Lightmass workflow | Requires precomputed lighting; not useful as a Lumen dynamic source |\n| Stationary | Color/intensity may change, transform stays fixed | Mixed baked/dynamic constraints; overlapping Stationary limits apply |\n| Movable | Transform and properties change at runtime | Fully dynamic shadows; profile shadow path |\n\nFor Lumen-first fully dynamic projects, Movable lights are the normal baseline. Do not\nchoose mobility from habit; choose it from the rendering path.\n\n## Exposure\n\n| Control | Effect |\n|---|---|\n| Metering Mode: Manual | Fixed exposure; camera/light comparison is stable |\n| Histogram | 64-bin adaptive exposure; default adaptive mode |\n| Exposure Compensation | Offset in stops; `+1` = 2× brighter, `-1` = 2× darker |\n| Min/Max EV100 | Clamp adaptation range; equal values disable adaptation |\n| Speed Up | Adaptation rate from dark environment/view to bright |\n| Speed Down | Adaptation rate from bright environment/view to dark |\n| Metering Mask | Weights screen regions; center weighting reduces edge-light pumping |\n| Low/High Percent | Select histogram range used for target exposure; extreme values can destabilize or clip |\n\nWorkflow:\n\n1. Use Manual exposure while establishing physically plausible lights.\n2. Enable HDR (Eye Adaptation) visualization.\n3. If adaptation is required, set a purposeful Min/Max EV100 range.\n4. Set speed from desired perceptual behavior.\n5. Add a metering mask if peripheral bright objects cause pumping.\n6. Use Local Exposure only after global exposure and light values are sound.\n\n## Physical-unit anchors\n\n- UE documents a zenith sun around **120,000 lux** with a 0.545° angular diameter.\n- A perpendicular white diffuse surface under that sun may receive roughly **150,000\n  lux** total.\n- Point/Spot/Rect Lights can use Candela or Lumens when inverse-square falloff is on.\n- `1000 cd` produces `1000 lux` at one meter for a perpendicular receiver in the\n  documented example.\n\nUse real fixture specifications as starting points. Do not compensate for incorrect\nexposure by multiplying every light arbitrarily.\n\n## Lumen\n\n- Dynamic Global Illumination: Lumen.\n- Reflection Method: Lumen.\n- Software tracing requires Generate Mesh Distance Fields.\n- Hardware ray tracing improves representation/quality in supported cases but costs\n  more and requires compatible hardware.\n- High scalability targets Lumen GI/reflections for 60 FPS on current-generation\n  consoles; Epic targets cleaner indoor lighting at 30 FPS.\n- Inspect Surface Cache/Card visualization when meshes appear black or fail to bounce\n  light.\n\n## MegaLights\n\n- Enable under Project Settings > Rendering > Direct Lighting.\n- Hardware ray tracing support is recommended.\n- All local lights are handled when enabled; disable per light with `Allow MegaLights`.\n- Directional Light support is disabled by default. Enable it with\n  `r.MegaLights.DirectionalLights 1` only after testing: Epic recommends Deferred Lighting with\n  VSM for a strong sun, while MegaLights may fit a dim, soft moonlight. Sky Light is not handled.\n- Select Ray Tracing or Virtual Shadow Maps per light as shadow method.\n- Disable by scalability/device profile with `r.MegaLights.Allow 0`.\n- Avoid huge light bounds. Merge many tiny emitters when they create noise, blur, or\n  ghosting at the same pixels.\n","searchText":"parameter effects contents - light selection - core light properties - mobility - exposure - physical-unit anchors - lumen - megalights light selection | need | light | |---|---| | sun, moon, or effectively infinite source | directional light | | captured environment/sky contribution | sky light | | bare bulb or omnidirectional fixture | point light | | flashlight, headlamp, stage cone | spot light | | window, panel, fluorescent fixture, softbox | rect light | core light properties | property | increase | decrease / caution | |---|---|---| | intensity | more direct contribution in the selected physical unit | interpret only with exposure and distance | | temperature | cooler/bluer at higher kelvin | warmer/oranger at lower kelvin; avoid double-tinting a physically scattered sun unless stylized | | attenuation radius | affects more geometry and increases overlap | not a brightness control; keep close to useful influence | | source radius / soft source radius | larger apparent emitter; softer, broader shadows/reflections | excessive size can erase contact definition | | source length | elongates emitter and shadow softness | match tube/strip fixture shape | | indirect lighting intensity | scales bounced contribution from this light | nonphysical artistic override; debug gi before using | | volumetric scattering intensity | stronger effect in participating media | can create fog glow/noise and flatten contrast | | specular scale | changes specular response | keep at default for physical work; use only as a deliberate art override | spot light - inner cone angle: fully lit core. - outer cone angle: full edge of influence. - larger gap between inner and outer angles creates a softer penumbra. - use ies profiles for fixture distribution when available instead of hand-shaping every falloff. rect light - source width/height define emitter size and reflection shape. - use for windows and panels where emitter geometry matters. - face the emitting side toward the scene. mobility | mobility | use | cost/constraint | |---|---|---| | static | never changes; baked lightmass workflow | requires precomputed lighting; not useful as a lumen dynamic source | | stationary | color/intensity may change, transform stays fixed | mixed baked/dynamic constraints; overlapping stationary limits apply | | movable | transform and properties change at runtime | fully dynamic shadows; profile shadow path | for lumen-first fully dynamic projects, movable lights are the normal baseline. do not choose mobility from habit; choose it from the rendering path. exposure | control | effect | |---|---| | metering mode: manual | fixed exposure; camera/light comparison is stable | | histogram | 64-bin adaptive exposure; default adaptive mode | | exposure compensation | offset in stops; +1 = 2× brighter, -1 = 2× darker | | min/max ev100 | clamp adaptation range; equal values disable adaptation | | speed up | adaptation rate from dark environment/view to bright | | speed down | adaptation rate from bright environment/view to dark | | metering mask | weights screen regions; center weighting reduces edge-light pumping | | low/high percent | select histogram range used for target exposure; extreme values can destabilize or clip | workflow: 1. use manual exposure while establishing physically plausible lights. 2. enable hdr (eye adaptation) visualization. 3. if adaptation is required, set a purposeful min/max ev100 range. 4. set speed from desired perceptual behavior. 5. add a metering mask if peripheral bright objects cause pumping. 6. use local exposure only after global exposure and light values are sound. physical-unit anchors - ue documents a zenith sun around 120,000 lux with a 0.545° angular diameter. - a perpendicular white diffuse surface under that sun may receive roughly 150,000 lux total. - point/spot/rect lights can use candela or lumens when inverse-square falloff is on. - 1000 cd produces 1000 lux at one meter for a perpendicular receiver in the documented example. use real fixture specifications as starting points. do not compensate for incorrect exposure by multiplying every light arbitrarily. lumen - dynamic global illumination: lumen. - reflection method: lumen. - software tracing requires generate mesh distance fields. - hardware ray tracing improves representation/quality in supported cases but costs more and requires compatible hardware. - high scalability targets lumen gi/reflections for 60 fps on current-generation consoles; epic targets cleaner indoor lighting at 30 fps. - inspect surface cache/card visualization when meshes appear black or fail to bounce light. megalights - enable under project settings > rendering > direct lighting. - hardware ray tracing support is recommended. - all local lights are handled when enabled; disable per light with allow megalights. - directional light support is disabled by default. enable it with r.megalights.directionallights 1 only after testing: epic recommends deferred lighting with vsm for a strong sun, while megalights may fit a dim, soft moonlight. sky light is not handled. - select ray tracing or virtual shadow maps per light as shadow method. - disable by scalability/device profile with r.megalights.allow 0. - avoid huge light bounds. merge many tiny emitters when they create noise, blur, or ghosting at the same pixels."},{"slug":"recipes","file":"recipes.md","title":"Lighting recipes","rawMarkdown":"# Lighting recipes\n\n## Physically based clear daylight\n\n1. Add Directional Light, Sky Atmosphere, Sky Light, and optional Volumetric Clouds.\n2. Enable Atmosphere Sun Light on the Directional Light.\n3. Set Directional Light in Lux; use approximately 120,000 lux for a documented zenith\n   sun starting point.\n4. Enable Sky Light Real Time Capture for dynamic time of day.\n5. Start with Manual exposure; inspect HDR Eye Adaptation values.\n6. Rotate the Directional Light for time of day before altering intensity/color.\n7. Enable bounded auto exposure only after the noon reference is stable.\n8. Verify shadow, atmosphere, cloud, Lumen, and target-platform cost.\n\n## Golden hour\n\n1. Lower the Directional Light angle near the horizon.\n2. Let Sky Atmosphere produce longer optical paths and warm scattering first.\n3. Increase Mie contribution/anisotropy only when the desired haze is missing; inspect\n   silhouettes and aerial perspective.\n4. Preserve a cooler Sky Light/environment contrast unless the art target is uniformly\n   warm.\n5. Use restrained exposure compensation; do not turn sunset into daylight brightness.\n6. Add local practicals only to guide focal hierarchy.\n\n## Night exterior that still reads as night\n\n1. Use a second atmospheric Directional Light for moon if required; set Atmosphere Sun\n   Light Index appropriately.\n2. Reduce broad environment contribution rather than crushing blacks with post color.\n3. Clamp auto exposure so the camera cannot adapt the night back to daytime.\n4. Place local lights in purposeful pools; minimize attenuation overlap.\n5. Keep navigable silhouettes and landmark contrast.\n6. Check emissives at gameplay distance; use real lights when they must illuminate.\n7. Verify local-light noise/ghosting with MegaLights enabled.\n\n## Interior lit by windows\n\n1. Establish exterior Directional/Sky lighting and exposure.\n2. Use Lumen for indirect bounce.\n3. Add Rect Lights at important apertures only when the dynamic solution needs an art-\n   directed key or stronger directionality.\n4. Match Rect Light dimensions/orientation to the opening.\n5. Keep attenuation bounds inside the useful room volume.\n6. Inspect Lumen Surface Cache and mesh modularity when interiors stay black.\n7. Compare interior-to-exterior exposure transition and set Speed Up/Down intentionally.\n\n## Practical-lit interior\n\n1. Give emissive materials plausible luminance for visible fixture surfaces.\n2. Pair important fixtures with Point/Spot/Rect Lights for controlled illumination.\n3. Match source size and shape to the fixture.\n4. Use IES profiles for real fixture distributions where available.\n5. Limit attenuation to the room/area of influence.\n6. With MegaLights, merge clusters that produce stochastic blur or ghosting at the same\n   pixels.\n7. Test with fog/translucency because MegaLights includes those paths.\n\n## Horror or high-contrast scene\n\n1. Lock or tightly bound exposure; uncontrolled eye adaptation destroys authored\n   darkness.\n2. Preserve readable navigation and interactable silhouettes.\n3. Use small areas of motivated light rather than globally lowering every value.\n4. Control source radius: smaller sources create harder, more threatening shadows;\n   larger sources create softer ambiguity.\n5. Use volumetric scattering only where it supports composition.\n6. Test black-level visibility on the target display and scalability tiers.\n\n## Stylized scene\n\n1. Start from stable exposure and functional key/fill separation.\n2. Use temperature/color and indirect intensity as deliberate nonphysical controls.\n3. Keep values consistent by light role, not per-object improvisation.\n4. Validate material roughness and albedo before fixing every problem with lights.\n5. Preserve performance rules: bounded lights, intentional shadows, target profiling.\n","webMarkdown":"## Physically based clear daylight\n\n1. Add Directional Light, Sky Atmosphere, Sky Light, and optional Volumetric Clouds.\n2. Enable Atmosphere Sun Light on the Directional Light.\n3. Set Directional Light in Lux; use approximately 120,000 lux for a documented zenith\n   sun starting point.\n4. Enable Sky Light Real Time Capture for dynamic time of day.\n5. Start with Manual exposure; inspect HDR Eye Adaptation values.\n6. Rotate the Directional Light for time of day before altering intensity/color.\n7. Enable bounded auto exposure only after the noon reference is stable.\n8. Verify shadow, atmosphere, cloud, Lumen, and target-platform cost.\n\n## Golden hour\n\n1. Lower the Directional Light angle near the horizon.\n2. Let Sky Atmosphere produce longer optical paths and warm scattering first.\n3. Increase Mie contribution/anisotropy only when the desired haze is missing; inspect\n   silhouettes and aerial perspective.\n4. Preserve a cooler Sky Light/environment contrast unless the art target is uniformly\n   warm.\n5. Use restrained exposure compensation; do not turn sunset into daylight brightness.\n6. Add local practicals only to guide focal hierarchy.\n\n## Night exterior that still reads as night\n\n1. Use a second atmospheric Directional Light for moon if required; set Atmosphere Sun\n   Light Index appropriately.\n2. Reduce broad environment contribution rather than crushing blacks with post color.\n3. Clamp auto exposure so the camera cannot adapt the night back to daytime.\n4. Place local lights in purposeful pools; minimize attenuation overlap.\n5. Keep navigable silhouettes and landmark contrast.\n6. Check emissives at gameplay distance; use real lights when they must illuminate.\n7. Verify local-light noise/ghosting with MegaLights enabled.\n\n## Interior lit by windows\n\n1. Establish exterior Directional/Sky lighting and exposure.\n2. Use Lumen for indirect bounce.\n3. Add Rect Lights at important apertures only when the dynamic solution needs an art-\n   directed key or stronger directionality.\n4. Match Rect Light dimensions/orientation to the opening.\n5. Keep attenuation bounds inside the useful room volume.\n6. Inspect Lumen Surface Cache and mesh modularity when interiors stay black.\n7. Compare interior-to-exterior exposure transition and set Speed Up/Down intentionally.\n\n## Practical-lit interior\n\n1. Give emissive materials plausible luminance for visible fixture surfaces.\n2. Pair important fixtures with Point/Spot/Rect Lights for controlled illumination.\n3. Match source size and shape to the fixture.\n4. Use IES profiles for real fixture distributions where available.\n5. Limit attenuation to the room/area of influence.\n6. With MegaLights, merge clusters that produce stochastic blur or ghosting at the same\n   pixels.\n7. Test with fog/translucency because MegaLights includes those paths.\n\n## Horror or high-contrast scene\n\n1. Lock or tightly bound exposure; uncontrolled eye adaptation destroys authored\n   darkness.\n2. Preserve readable navigation and interactable silhouettes.\n3. Use small areas of motivated light rather than globally lowering every value.\n4. Control source radius: smaller sources create harder, more threatening shadows;\n   larger sources create softer ambiguity.\n5. Use volumetric scattering only where it supports composition.\n6. Test black-level visibility on the target display and scalability tiers.\n\n## Stylized scene\n\n1. Start from stable exposure and functional key/fill separation.\n2. Use temperature/color and indirect intensity as deliberate nonphysical controls.\n3. Keep values consistent by light role, not per-object improvisation.\n4. Validate material roughness and albedo before fixing every problem with lights.\n5. Preserve performance rules: bounded lights, intentional shadows, target profiling.\n","searchText":"lighting recipes physically based clear daylight 1. add directional light, sky atmosphere, sky light, and optional volumetric clouds. 2. enable atmosphere sun light on the directional light. 3. set directional light in lux; use approximately 120,000 lux for a documented zenith sun starting point. 4. enable sky light real time capture for dynamic time of day. 5. start with manual exposure; inspect hdr eye adaptation values. 6. rotate the directional light for time of day before altering intensity/color. 7. enable bounded auto exposure only after the noon reference is stable. 8. verify shadow, atmosphere, cloud, lumen, and target-platform cost. golden hour 1. lower the directional light angle near the horizon. 2. let sky atmosphere produce longer optical paths and warm scattering first. 3. increase mie contribution/anisotropy only when the desired haze is missing; inspect silhouettes and aerial perspective. 4. preserve a cooler sky light/environment contrast unless the art target is uniformly warm. 5. use restrained exposure compensation; do not turn sunset into daylight brightness. 6. add local practicals only to guide focal hierarchy. night exterior that still reads as night 1. use a second atmospheric directional light for moon if required; set atmosphere sun light index appropriately. 2. reduce broad environment contribution rather than crushing blacks with post color. 3. clamp auto exposure so the camera cannot adapt the night back to daytime. 4. place local lights in purposeful pools; minimize attenuation overlap. 5. keep navigable silhouettes and landmark contrast. 6. check emissives at gameplay distance; use real lights when they must illuminate. 7. verify local-light noise/ghosting with megalights enabled. interior lit by windows 1. establish exterior directional/sky lighting and exposure. 2. use lumen for indirect bounce. 3. add rect lights at important apertures only when the dynamic solution needs an art- directed key or stronger directionality. 4. match rect light dimensions/orientation to the opening. 5. keep attenuation bounds inside the useful room volume. 6. inspect lumen surface cache and mesh modularity when interiors stay black. 7. compare interior-to-exterior exposure transition and set speed up/down intentionally. practical-lit interior 1. give emissive materials plausible luminance for visible fixture surfaces. 2. pair important fixtures with point/spot/rect lights for controlled illumination. 3. match source size and shape to the fixture. 4. use ies profiles for real fixture distributions where available. 5. limit attenuation to the room/area of influence. 6. with megalights, merge clusters that produce stochastic blur or ghosting at the same pixels. 7. test with fog/translucency because megalights includes those paths. horror or high-contrast scene 1. lock or tightly bound exposure; uncontrolled eye adaptation destroys authored darkness. 2. preserve readable navigation and interactable silhouettes. 3. use small areas of motivated light rather than globally lowering every value. 4. control source radius: smaller sources create harder, more threatening shadows; larger sources create softer ambiguity. 5. use volumetric scattering only where it supports composition. 6. test black-level visibility on the target display and scalability tiers. stylized scene 1. start from stable exposure and functional key/fill separation. 2. use temperature/color and indirect intensity as deliberate nonphysical controls. 3. keep values consistent by light role, not per-object improvisation. 4. validate material roughness and albedo before fixing every problem with lights. 5. preserve performance rules: bounded lights, intentional shadows, target profiling."},{"slug":"sources","file":"sources.md","title":"UE 5.8 primary sources","rawMarkdown":"# UE 5.8 primary sources\n\n- Epic Games, [Lighting the Environment](https://dev.epicgames.com/documentation/en-us/unreal-engine/lighting-the-environment-in-unreal-engine)\n- Epic Games, [Physical Lighting Units](https://dev.epicgames.com/documentation/unreal-engine/using-physical-lighting-units-in-unreal-engine)\n- Epic Games, [Auto Exposure](https://dev.epicgames.com/documentation/en-us/unreal-engine/auto-exposure-in-unreal-engine)\n- Epic Games, [Light Types and Mobility](https://dev.epicgames.com/documentation/en-us/unreal-engine/light-types-and-their-mobility-in-unreal-engine)\n- Epic Games, [Lumen Global Illumination and Reflections](https://dev.epicgames.com/documentation/en-us/unreal-engine/lumen-global-illumination-and-reflections-in-unreal-engine)\n- Epic Games, [Lumen Technical Details](https://dev.epicgames.com/documentation/unreal-engine/lumen-technical-details-in-unreal-engine)\n- Epic Games, [MegaLights](https://dev.epicgames.com/documentation/en-us/unreal-engine/megalights-in-unreal-engine)\n- Epic Games, [Environmental Light with Fog, Clouds, Sky and Atmosphere](https://dev.epicgames.com/documentation/en-us/unreal-engine/environmental-light-with-fog-clouds-sky-and-atmosphere-in-unreal-engine)\n- Epic Games, [Sky Atmosphere](https://dev.epicgames.com/documentation/en-us/unreal-engine/sky-atmosphere-component-in-unreal-engine)\n- Epic Games, [Shadowing](https://dev.epicgames.com/documentation/en-us/unreal-engine/shadowing-in-unreal-engine)\n\nVersion target: Unreal Engine 5.8. Recheck defaults, scalability behavior, and feature\nstatus before using this skill with a later engine version.\n","webMarkdown":"- Epic Games, [Lighting the Environment](https://dev.epicgames.com/documentation/en-us/unreal-engine/lighting-the-environment-in-unreal-engine)\n- Epic Games, [Physical Lighting Units](https://dev.epicgames.com/documentation/unreal-engine/using-physical-lighting-units-in-unreal-engine)\n- Epic Games, [Auto Exposure](https://dev.epicgames.com/documentation/en-us/unreal-engine/auto-exposure-in-unreal-engine)\n- Epic Games, [Light Types and Mobility](https://dev.epicgames.com/documentation/en-us/unreal-engine/light-types-and-their-mobility-in-unreal-engine)\n- Epic Games, [Lumen Global Illumination and Reflections](https://dev.epicgames.com/documentation/en-us/unreal-engine/lumen-global-illumination-and-reflections-in-unreal-engine)\n- Epic Games, [Lumen Technical Details](https://dev.epicgames.com/documentation/unreal-engine/lumen-technical-details-in-unreal-engine)\n- Epic Games, [MegaLights](https://dev.epicgames.com/documentation/en-us/unreal-engine/megalights-in-unreal-engine)\n- Epic Games, [Environmental Light with Fog, Clouds, Sky and Atmosphere](https://dev.epicgames.com/documentation/en-us/unreal-engine/environmental-light-with-fog-clouds-sky-and-atmosphere-in-unreal-engine)\n- Epic Games, [Sky Atmosphere](https://dev.epicgames.com/documentation/en-us/unreal-engine/sky-atmosphere-component-in-unreal-engine)\n- Epic Games, [Shadowing](https://dev.epicgames.com/documentation/en-us/unreal-engine/shadowing-in-unreal-engine)\n\nVersion target: Unreal Engine 5.8. Recheck defaults, scalability behavior, and feature\nstatus before using this skill with a later engine version.\n","searchText":"ue 5.8 primary sources - epic games, lighting the environment - epic games, physical lighting units - epic games, auto exposure - epic games, light types and mobility - epic games, lumen global illumination and reflections - epic games, lumen technical details - epic games, megalights - epic games, environmental light with fog, clouds, sky and atmosphere - epic games, sky atmosphere - epic games, shadowing version target: unreal engine 5.8. recheck defaults, scalability behavior, and feature status before using this skill with a later engine version."}]}
{"slug":"unreal-materials","name":"unreal-materials","title":"Unreal 5.8 Materials","description":"Select, build, parameterize, layer, profile, and debug materials in Unreal Engine 5.8. Use for PBR inputs, blend modes, shading models, parent materials, instances, functions, static switches, Material Layers, Substrate, decals, Runtime Virtual Textures, Custom Primitive Data, animated material effects, shader permutations, overdraw, or material performance.","shortDescription":"Build, tune, and profile Unreal materials","category":"Rendering & VFX","referenceCount":8,"rawMarkdown":"---\nname: unreal-materials\ndescription: Select, build, parameterize, layer, profile, and debug materials in Unreal Engine 5.8. Use for PBR inputs, blend modes, shading models, parent materials, instances, functions, static switches, Material Layers, Substrate, decals, Runtime Virtual Textures, Custom Primitive Data, animated material effects, shader permutations, overdraw, or material performance.\n---\n\n# Unreal 5.8 Materials\n\n## Ownership boundary\n\nThis skill owns surface/shader graph architecture and material parameter behavior. Route artistic\nlight/exposure/atmosphere setup to [`unreal-lighting`](../unreal-lighting/SKILL.md). If material cost is\nonly suspected, start with [`unreal-insights-profiling`](../unreal-insights-profiling/SKILL.md); route a\nmeasured render/GPU optimization to\n[`unreal-rendering-performance`](../unreal-rendering-performance/SKILL.md).\n\n## Select the architecture first\n\nRead [`references/architecture-selector.md`](references/architecture-selector.md).\n\n- Shared surface family -> parent Material + Material Instances.\n- Reusable graph behavior -> Material Function.\n- Artist-reorderable surface stack -> Material Layers.\n- Global world state -> Material Parameter Collection.\n- Per-object variation without unique dynamic instances -> Custom Primitive Data.\n- Large static terrain shading cache -> Runtime Virtual Texture.\n- Local projected breakup/damage -> decal.\n\nDo not begin from a universal master material. Begin from a bounded surface family and measured\nplatform needs.\n\n## Execute\n\n1. State the target look, geometry, lighting path, platform, and performance constraints.\n2. Choose Material Domain, Blend Mode, Shading Model, and Two Sided behavior before graph work.\n3. Build a physically coherent minimum surface and validate texture import/sampler assumptions.\n4. Expose only parameters that represent intentional art controls.\n5. Extract reused logic into documented functions; use static branching sparingly.\n6. Add layers, decals, RVT, WPO, or translucency only when the use case requires them.\n7. Test representative instances and worst-case screen coverage.\n8. Inspect compile stats, permutations, Shader Complexity/overdraw, and target hardware.\n\nLoad only the relevant reference:\n\n- [`references/pbr-and-properties.md`](references/pbr-and-properties.md)\n- [`references/instances-functions-and-data.md`](references/instances-functions-and-data.md)\n- [`references/layers-substrate-and-decals.md`](references/layers-substrate-and-decals.md)\n- [`references/rvt-and-world-effects.md`](references/rvt-and-world-effects.md)\n- [`references/effect-recipes.md`](references/effect-recipes.md)\n- [`references/profiling-and-debugging.md`](references/profiling-and-debugging.md)\n\n## Required answer format\n\nReturn:\n\n1. **Chosen material architecture** and rejected alternatives.\n2. **Domain, blend, shading, lighting, and platform assumptions**.\n3. **Graph/function/layer structure in evaluation order**.\n4. **Parameters with units/ranges and visual effect of increase/decrease**.\n5. **Texture, UV, normal, and color-space requirements**.\n6. **Permutation, overdraw, memory, WPO, RVT, and lighting consequences**.\n7. **Debug views and acceptance shots on target hardware**.\n\n## Hard rules\n\n- Choose blend mode and shading model intentionally; they control available inputs and passes.\n- Treat Base Color, Metallic, Roughness, and Specular as physically related inputs, not arbitrary style sliders.\n- Use instances for variations and functions for reusable logic; document function inputs/outputs.\n- Static parameters create compile-time variants. Audit them; do not expose every feature as a switch.\n- Prefer masked over translucent when the look allows it; measure overlapping transparency.\n- WPO changes vertices and bounds, not collision. Expand bounds only as much as required.\n- Use RVT for suitable mostly static large-area shading; not as a continuously refreshed animation buffer.\n- Validate decals on the actual rendering path and receiving material settings.\n- Shader instruction count is a clue, not complete timing; profile target hardware and screen coverage.\n- Keep lighting diagnosis in `unreal-lighting`; this skill owns surface response.\n\nSee [`references/sources.md`](references/sources.md) for the UE 5.8 source trail.\n","webMarkdown":"## Ownership boundary\n\nThis skill owns surface/shader graph architecture and material parameter behavior. Route artistic\nlight/exposure/atmosphere setup to [`unreal-lighting`](/unreal/unreal-lighting/). If material cost is\nonly suspected, start with [`unreal-insights-profiling`](/unreal/unreal-insights-profiling/); route a\nmeasured render/GPU optimization to\n[`unreal-rendering-performance`](/unreal/unreal-rendering-performance/).\n\n## Select the architecture first\n\nRead [`references/architecture-selector.md`](/unreal/unreal-materials/architecture-selector/).\n\n- Shared surface family -> parent Material + Material Instances.\n- Reusable graph behavior -> Material Function.\n- Artist-reorderable surface stack -> Material Layers.\n- Global world state -> Material Parameter Collection.\n- Per-object variation without unique dynamic instances -> Custom Primitive Data.\n- Large static terrain shading cache -> Runtime Virtual Texture.\n- Local projected breakup/damage -> decal.\n\nDo not begin from a universal master material. Begin from a bounded surface family and measured\nplatform needs.\n\n## Execute\n\n1. State the target look, geometry, lighting path, platform, and performance constraints.\n2. Choose Material Domain, Blend Mode, Shading Model, and Two Sided behavior before graph work.\n3. Build a physically coherent minimum surface and validate texture import/sampler assumptions.\n4. Expose only parameters that represent intentional art controls.\n5. Extract reused logic into documented functions; use static branching sparingly.\n6. Add layers, decals, RVT, WPO, or translucency only when the use case requires them.\n7. Test representative instances and worst-case screen coverage.\n8. Inspect compile stats, permutations, Shader Complexity/overdraw, and target hardware.\n\nLoad only the relevant reference:\n\n- [`references/pbr-and-properties.md`](/unreal/unreal-materials/pbr-and-properties/)\n- [`references/instances-functions-and-data.md`](/unreal/unreal-materials/instances-functions-and-data/)\n- [`references/layers-substrate-and-decals.md`](/unreal/unreal-materials/layers-substrate-and-decals/)\n- [`references/rvt-and-world-effects.md`](/unreal/unreal-materials/rvt-and-world-effects/)\n- [`references/effect-recipes.md`](/unreal/unreal-materials/effect-recipes/)\n- [`references/profiling-and-debugging.md`](/unreal/unreal-materials/profiling-and-debugging/)\n\n## Required answer format\n\nReturn:\n\n1. **Chosen material architecture** and rejected alternatives.\n2. **Domain, blend, shading, lighting, and platform assumptions**.\n3. **Graph/function/layer structure in evaluation order**.\n4. **Parameters with units/ranges and visual effect of increase/decrease**.\n5. **Texture, UV, normal, and color-space requirements**.\n6. **Permutation, overdraw, memory, WPO, RVT, and lighting consequences**.\n7. **Debug views and acceptance shots on target hardware**.\n\n## Hard rules\n\n- Choose blend mode and shading model intentionally; they control available inputs and passes.\n- Treat Base Color, Metallic, Roughness, and Specular as physically related inputs, not arbitrary style sliders.\n- Use instances for variations and functions for reusable logic; document function inputs/outputs.\n- Static parameters create compile-time variants. Audit them; do not expose every feature as a switch.\n- Prefer masked over translucent when the look allows it; measure overlapping transparency.\n- WPO changes vertices and bounds, not collision. Expand bounds only as much as required.\n- Use RVT for suitable mostly static large-area shading; not as a continuously refreshed animation buffer.\n- Validate decals on the actual rendering path and receiving material settings.\n- Shader instruction count is a clue, not complete timing; profile target hardware and screen coverage.\n- Keep lighting diagnosis in `unreal-lighting`; this skill owns surface response.\n\nSee [`references/sources.md`](/unreal/unreal-materials/sources/) for the UE 5.8 source trail.\n","searchText":"unreal 5.8 materials select, build, parameterize, layer, profile, and debug materials in unreal engine 5.8. use for pbr inputs, blend modes, shading models, parent materials, instances, functions, static switches, material layers, substrate, decals, runtime virtual textures, custom primitive data, animated material effects, shader permutations, overdraw, or material performance. material architecture selector material architecture selector | need | use | cost/risk to check | |---|---|---| | variants of one surface family | parent + material instances | parent scope, static permutations | | repeated math or mapping | material function | propagation to every caller | | reorderable artist-facing layers | material layers | per-pixel layer cost and masks | | global scalar/vector state | material parameter collection | global coupling; not per-object | | unique values per primitive/instance | custom primitive data | index contract and update ownership | | landscape/object blending cache | rvt | page memory, uploads, static suitability | | local grime/damage/signage | dbuffer/deferred decal | receiving response, overlap, sort | | complex physical bsdf composition | substrate | project/platform support and cost | | one-off simple surface | direct material | avoid needless framework overhead | before choosing, answer: - how many assets and variants share the logic? - which parameters vary globally, per material, per object, or per frame? - does the choice create new shader permutations or only runtime uniform values? - is the surface opaque, masked, or truly translucent? - what is the largest screen coverage and overlap count? split parent families when domains, blend modes, shading models, or platform feature sets differ. material effect recipes material effect recipes dissolve / reveal compare a stable mask/noise field with a scalar threshold. use masked blend when a hard clipped edge is acceptable. derive a narrow edge band from the threshold difference for emissive/color. expose threshold, edge width, edge color/intensity, and coordinate controls. test temporal aliasing, shadows, depth, and bounds if wpo accompanies the dissolve. hit flash / selection pulse drive a scalar/vector parameter from gameplay on the owning material instance or primitive data. blend a bounded tint/emissive contribution over the existing surface. restore/default the value explicitly; do not continuously create new dynamic instances. uv panning / flow use time and panner (or equivalent math) with parameterized direction and speed. keep units and coordinate space explicit. for networked cosmetic effects, synchronize an event/start time only when visual phase agreement matters. triplanar/world-aligned texture blend projections by surface normal for assets lacking suitable uvs or for consistent world scale. it increases texture samples; reserve it for surfaces where seams or authoring cost justify it. foliage wind apply wpo weighted by vertex mask, keeping attachment points stable. parameterize amplitude and frequency, then test bounds, shadow stability, lod transitions, and worst-case instance counts. distance/quality reduction remove the cost that matters: texture reads, per-pixel layers, expensive math, or wpo. quality switches produce additional permutations and are not simultaneous distance lods. verify with the material stats and on hardware rather than assuming the simpler-looking graph is faster. instances, functions, and parameter data instances, functions, and parameter data parent and instances 1. define a bounded family: for example opaque hard surface, foliage, or translucent vfx. 2. put invariant graph structure in the parent. 3. convert only intentional art controls to scalar, vector, texture, or static parameters. 4. group and describe parameters; give safe defaults. 5. create material instances for asset variations. 6. use dynamic instances only when values must change on that object at runtime. static switches remove an inactive branch from a compiled variant but each distinct combination can create another shader permutation. use material analyzer (tools -> audit -> material analyzer) to inspect descendants, static overrides, and opportunities to reparent common configurations. material functions - package repeated calculations, not arbitrary portions of a graph. - name and describe every input/output; set meaningful preview defaults cautiously. - enable expose to library and choose a concise category for team functions. - apply/save changes deliberately: edits propagate to loaded callers, and deleted pins break links. - duplicate engine/default functions before modifying them. - avoid circular function dependencies. parameter ownership - material instance: per material/asset variant. - dynamic material instance: per runtime material slot/component. - custom primitive data: per primitive values exposed to a shared material. - material parameter collection: global or level-wide scalar/vector state. do not use a global collection for actor-local state or spawn a dynamic instance for every object when primitive data or instancing can express the variation. layers, substrate, and decals layers, substrate, and decals layering use material functions with material attributes when the graph author owns a fixed blend architecture. use material layers when artists need to reorder, swap, and tune layers in the material instance editor. every extra per-pixel layer and mask still has a rendering cost. for each layer define: - physical surface contribution; - blend mask source and coordinate space; - normal-combination method; - which values remain exposed; - fallback for lower quality/platform tiers. substrate use substrate when the surface requires bsdf composition that the conventional shading model cannot express cleanly. confirm project enablement, platform support, material complexity, and the ue 5.8 production decision before making it a shared dependency. do not migrate a simple surface merely because the framework is newer. decals 1. create a material with deferred decal domain and the required decal blend response. 2. display it through a decal actor/component or decal mesh. 3. confirm the receiving materials respond to the relevant dbuffer channels. 4. use sort priority only where overlap order matters; avoid a proliferation of unique priorities. 5. inspect angle stretch, projection depth, fade distance, overlap, and target-platform path. dbuffer is the default decal path for ue5 projects. decals are suited to localized breakup, grime, damage, and signage; do not replace base material structure with thousands of overlapping full-screen projections. pbr inputs and material properties pbr inputs and material properties minimum surface 1. select the material domain for the job: surface unless it is explicitly decal, light function, post process, ui, or another specialized domain. 2. choose blend mode. use opaque by default, masked for binary coverage, and translucent only when partial transmission is required. 3. choose the shading model that represents the surface response. 4. set two sided only when backfaces must render and the lighting result is acceptable. 5. connect base color, metallic, roughness, normal, and optional emissive/ao inputs. input meaning - base color: intrinsic surface color, without baked directional lighting. - metallic: normally 0 for dielectric or 1 for metal; avoid unexplained mid-values. - roughness: low sharpens reflections; high broadens them. - specular: dielectric specular level; leave the physically reasonable default unless the material calls for a measured exception. - normal: fine lighting orientation; verify tangent-space import and sampler type. - emissive: emitted radiance appearance; it is not a free replacement for actual lighting. - opacity mask: compared with clip threshold in masked mode. texture gates - color textures use the correct srgb interpretation; packed masks/data usually do not. - normal textures use the normal sampler/compression path. - confirm channel packing, uv set, tiling, addressing, mip behavior, and streaming size. - test at near, typical, and far viewing distances under representative neutral lighting. if an input is disabled, inspect domain, blend mode, and shading model before rebuilding the graph. profiling and debugging profiling and debugging visual defect ladder 1. preview texture channels and constants independently. 2. verify uv set/scale and object/world/tangent coordinate spaces. 3. verify srgb, normal sampler, compression, channel packing, and mip level. 4. reduce the graph to the minimum surface; re-enable functions/layers one at a time. 5. test neutral direct lighting before blaming the material or lighting system. 6. inspect bounds, decals, rvt writer/receiver assignment, and platform feature switches. cost ladder 1. record target resolution, view, material screen coverage, and overlapping transparency. 2. use material editor stats/platform stats for compiled shader information. 3. use shader complexity (alt+8) to locate costly pixel regions and particle/translucency overdraw. 4. use material analyzer for static-switch/permutation families. 5. use gpu profiling/insights on target hardware to verify actual passes and time. 6. change one suspected cost and compare the same capture. instruction count alone misses important differences such as texture fetches, bandwidth, divergent work, and vertex cost. a costly pixel shader matters most over large screen area; wpo/vertex work matters for every submitted vertex. translucent layers can repeatedly shade the same pixel. common causes: - pink/checker/default material -> compile error, missing shader, unsupported path. - flat/no normal response -> sampler/import type or tangent basis. - dark/bright mismatch -> color-space or packed-channel error. - flickering displacement -> bounds, precision, temporal aliasing, or lod discontinuity. - shader compile explosion -> unconstrained static switches and instance override combinations. runtime virtual textures and world effects runtime virtual textures and world effects rvt workflow 1. create a runtime virtual texture asset with the required material type/resolution. 2. add and size an rvt volume; assign the rvt asset. 3. configure writer materials with rvt output expressions. 4. configure receiving materials with rvt sample or rvt sample parameter. 5. assign the rvt asset to components that render into it. 6. verify main-pass behavior, virtual-texture support fallback, mips, memory, and page uploads. good writers are mostly static large-area contributors: landscape, landscape splines, static meshes, instances, and foliage. skeletal, movable, and frequently animated writers are poor fits because rvt acts as a shading cache rather than a fully refreshed render target. use ycocg base-color storage when smooth-gradient color quality justifies roughly 25% extra memory and decode cost. if overlapping writers disappear or order incorrectly, inspect translucency sort priority; equal priority order is undefined. world-space effects - global wetness/snow value -> material parameter collection. - local accumulation around many objects -> primitive data, masks, decals, or rvt according to scale. - vertex wind/displacement -> wpo with explicit amplitude, bounds, lod, shadow, and nanite checks. - camera-distance simplification -> explicit quality/lod design, not an unmeasured chain of branches. wpo does not move collision. when gameplay requires changed collision, modify the owning geometry or gameplay representation, not only the shader. ue 5.8 primary sources ue 5.8 primary sources - materials - material inputs - creating and using material instances - material functions - creating and using material functions - layering materials - using material layers - material parameter collections - decal materials - runtime virtual texturing - material analyzer - viewport modes / shader complexity - transparency - scalability reference pages were checked against the ue 5.8 documentation on 2026-07-19. reconfirm feature maturity, platform support, and shader behavior after an engine upgrade.","references":[{"slug":"architecture-selector","file":"architecture-selector.md","title":"Material architecture selector","rawMarkdown":"# Material architecture selector\n\n| Need | Use | Cost/risk to check |\n|---|---|---|\n| Variants of one surface family | Parent + Material Instances | parent scope, static permutations |\n| Repeated math or mapping | Material Function | propagation to every caller |\n| Reorderable artist-facing layers | Material Layers | per-pixel layer cost and masks |\n| Global scalar/vector state | Material Parameter Collection | global coupling; not per-object |\n| Unique values per primitive/instance | Custom Primitive Data | index contract and update ownership |\n| Landscape/object blending cache | RVT | page memory, uploads, static suitability |\n| Local grime/damage/signage | DBuffer/deferred decal | receiving response, overlap, sort |\n| Complex physical BSDF composition | Substrate | project/platform support and cost |\n| One-off simple surface | Direct Material | avoid needless framework overhead |\n\nBefore choosing, answer:\n\n- How many assets and variants share the logic?\n- Which parameters vary globally, per material, per object, or per frame?\n- Does the choice create new shader permutations or only runtime uniform values?\n- Is the surface opaque, masked, or truly translucent?\n- What is the largest screen coverage and overlap count?\n\nSplit parent families when domains, blend modes, shading models, or platform feature sets differ.\n","webMarkdown":"| Need | Use | Cost/risk to check |\n|---|---|---|\n| Variants of one surface family | Parent + Material Instances | parent scope, static permutations |\n| Repeated math or mapping | Material Function | propagation to every caller |\n| Reorderable artist-facing layers | Material Layers | per-pixel layer cost and masks |\n| Global scalar/vector state | Material Parameter Collection | global coupling; not per-object |\n| Unique values per primitive/instance | Custom Primitive Data | index contract and update ownership |\n| Landscape/object blending cache | RVT | page memory, uploads, static suitability |\n| Local grime/damage/signage | DBuffer/deferred decal | receiving response, overlap, sort |\n| Complex physical BSDF composition | Substrate | project/platform support and cost |\n| One-off simple surface | Direct Material | avoid needless framework overhead |\n\nBefore choosing, answer:\n\n- How many assets and variants share the logic?\n- Which parameters vary globally, per material, per object, or per frame?\n- Does the choice create new shader permutations or only runtime uniform values?\n- Is the surface opaque, masked, or truly translucent?\n- What is the largest screen coverage and overlap count?\n\nSplit parent families when domains, blend modes, shading models, or platform feature sets differ.\n","searchText":"material architecture selector | need | use | cost/risk to check | |---|---|---| | variants of one surface family | parent + material instances | parent scope, static permutations | | repeated math or mapping | material function | propagation to every caller | | reorderable artist-facing layers | material layers | per-pixel layer cost and masks | | global scalar/vector state | material parameter collection | global coupling; not per-object | | unique values per primitive/instance | custom primitive data | index contract and update ownership | | landscape/object blending cache | rvt | page memory, uploads, static suitability | | local grime/damage/signage | dbuffer/deferred decal | receiving response, overlap, sort | | complex physical bsdf composition | substrate | project/platform support and cost | | one-off simple surface | direct material | avoid needless framework overhead | before choosing, answer: - how many assets and variants share the logic? - which parameters vary globally, per material, per object, or per frame? - does the choice create new shader permutations or only runtime uniform values? - is the surface opaque, masked, or truly translucent? - what is the largest screen coverage and overlap count? split parent families when domains, blend modes, shading models, or platform feature sets differ."},{"slug":"effect-recipes","file":"effect-recipes.md","title":"Material effect recipes","rawMarkdown":"# Material effect recipes\n\n## Dissolve / reveal\n\nCompare a stable mask/noise field with a scalar threshold. Use Masked blend when a hard clipped\nedge is acceptable. Derive a narrow edge band from the threshold difference for emissive/color.\nExpose threshold, edge width, edge color/intensity, and coordinate controls. Test temporal aliasing,\nshadows, depth, and bounds if WPO accompanies the dissolve.\n\n## Hit flash / selection pulse\n\nDrive a scalar/vector parameter from gameplay on the owning material instance or primitive data.\nBlend a bounded tint/emissive contribution over the existing surface. Restore/default the value\nexplicitly; do not continuously create new dynamic instances.\n\n## UV panning / flow\n\nUse Time and Panner (or equivalent math) with parameterized direction and speed. Keep units and\ncoordinate space explicit. For networked cosmetic effects, synchronize an event/start time only\nwhen visual phase agreement matters.\n\n## Triplanar/world-aligned texture\n\nBlend projections by surface normal for assets lacking suitable UVs or for consistent world scale.\nIt increases texture samples; reserve it for surfaces where seams or authoring cost justify it.\n\n## Foliage wind\n\nApply WPO weighted by vertex mask, keeping attachment points stable. Parameterize amplitude and\nfrequency, then test bounds, shadow stability, LOD transitions, and worst-case instance counts.\n\n## Distance/quality reduction\n\nRemove the cost that matters: texture reads, per-pixel layers, expensive math, or WPO. Quality\nswitches produce additional permutations and are not simultaneous distance LODs. Verify with the\nmaterial stats and on hardware rather than assuming the simpler-looking graph is faster.\n","webMarkdown":"## Dissolve / reveal\n\nCompare a stable mask/noise field with a scalar threshold. Use Masked blend when a hard clipped\nedge is acceptable. Derive a narrow edge band from the threshold difference for emissive/color.\nExpose threshold, edge width, edge color/intensity, and coordinate controls. Test temporal aliasing,\nshadows, depth, and bounds if WPO accompanies the dissolve.\n\n## Hit flash / selection pulse\n\nDrive a scalar/vector parameter from gameplay on the owning material instance or primitive data.\nBlend a bounded tint/emissive contribution over the existing surface. Restore/default the value\nexplicitly; do not continuously create new dynamic instances.\n\n## UV panning / flow\n\nUse Time and Panner (or equivalent math) with parameterized direction and speed. Keep units and\ncoordinate space explicit. For networked cosmetic effects, synchronize an event/start time only\nwhen visual phase agreement matters.\n\n## Triplanar/world-aligned texture\n\nBlend projections by surface normal for assets lacking suitable UVs or for consistent world scale.\nIt increases texture samples; reserve it for surfaces where seams or authoring cost justify it.\n\n## Foliage wind\n\nApply WPO weighted by vertex mask, keeping attachment points stable. Parameterize amplitude and\nfrequency, then test bounds, shadow stability, LOD transitions, and worst-case instance counts.\n\n## Distance/quality reduction\n\nRemove the cost that matters: texture reads, per-pixel layers, expensive math, or WPO. Quality\nswitches produce additional permutations and are not simultaneous distance LODs. Verify with the\nmaterial stats and on hardware rather than assuming the simpler-looking graph is faster.\n","searchText":"material effect recipes dissolve / reveal compare a stable mask/noise field with a scalar threshold. use masked blend when a hard clipped edge is acceptable. derive a narrow edge band from the threshold difference for emissive/color. expose threshold, edge width, edge color/intensity, and coordinate controls. test temporal aliasing, shadows, depth, and bounds if wpo accompanies the dissolve. hit flash / selection pulse drive a scalar/vector parameter from gameplay on the owning material instance or primitive data. blend a bounded tint/emissive contribution over the existing surface. restore/default the value explicitly; do not continuously create new dynamic instances. uv panning / flow use time and panner (or equivalent math) with parameterized direction and speed. keep units and coordinate space explicit. for networked cosmetic effects, synchronize an event/start time only when visual phase agreement matters. triplanar/world-aligned texture blend projections by surface normal for assets lacking suitable uvs or for consistent world scale. it increases texture samples; reserve it for surfaces where seams or authoring cost justify it. foliage wind apply wpo weighted by vertex mask, keeping attachment points stable. parameterize amplitude and frequency, then test bounds, shadow stability, lod transitions, and worst-case instance counts. distance/quality reduction remove the cost that matters: texture reads, per-pixel layers, expensive math, or wpo. quality switches produce additional permutations and are not simultaneous distance lods. verify with the material stats and on hardware rather than assuming the simpler-looking graph is faster."},{"slug":"instances-functions-and-data","file":"instances-functions-and-data.md","title":"Instances, functions, and parameter data","rawMarkdown":"# Instances, functions, and parameter data\n\n## Parent and instances\n\n1. Define a bounded family: for example opaque hard surface, foliage, or translucent VFX.\n2. Put invariant graph structure in the parent.\n3. Convert only intentional art controls to scalar, vector, texture, or static parameters.\n4. Group and describe parameters; give safe defaults.\n5. Create Material Instances for asset variations.\n6. Use dynamic instances only when values must change on that object at runtime.\n\nStatic switches remove an inactive branch from a compiled variant but each distinct combination\ncan create another shader permutation. Use Material Analyzer (Tools -> Audit -> Material Analyzer)\nto inspect descendants, static overrides, and opportunities to reparent common configurations.\n\n## Material Functions\n\n- Package repeated calculations, not arbitrary portions of a graph.\n- Name and describe every input/output; set meaningful preview defaults cautiously.\n- Enable Expose to Library and choose a concise category for team functions.\n- Apply/save changes deliberately: edits propagate to loaded callers, and deleted pins break links.\n- Duplicate engine/default functions before modifying them.\n- Avoid circular function dependencies.\n\n## Parameter ownership\n\n- Material Instance: per material/asset variant.\n- Dynamic Material Instance: per runtime material slot/component.\n- Custom Primitive Data: per primitive values exposed to a shared material.\n- Material Parameter Collection: global or level-wide scalar/vector state.\n\nDo not use a global collection for actor-local state or spawn a dynamic instance for every object\nwhen primitive data or instancing can express the variation.\n","webMarkdown":"## Parent and instances\n\n1. Define a bounded family: for example opaque hard surface, foliage, or translucent VFX.\n2. Put invariant graph structure in the parent.\n3. Convert only intentional art controls to scalar, vector, texture, or static parameters.\n4. Group and describe parameters; give safe defaults.\n5. Create Material Instances for asset variations.\n6. Use dynamic instances only when values must change on that object at runtime.\n\nStatic switches remove an inactive branch from a compiled variant but each distinct combination\ncan create another shader permutation. Use Material Analyzer (Tools -> Audit -> Material Analyzer)\nto inspect descendants, static overrides, and opportunities to reparent common configurations.\n\n## Material Functions\n\n- Package repeated calculations, not arbitrary portions of a graph.\n- Name and describe every input/output; set meaningful preview defaults cautiously.\n- Enable Expose to Library and choose a concise category for team functions.\n- Apply/save changes deliberately: edits propagate to loaded callers, and deleted pins break links.\n- Duplicate engine/default functions before modifying them.\n- Avoid circular function dependencies.\n\n## Parameter ownership\n\n- Material Instance: per material/asset variant.\n- Dynamic Material Instance: per runtime material slot/component.\n- Custom Primitive Data: per primitive values exposed to a shared material.\n- Material Parameter Collection: global or level-wide scalar/vector state.\n\nDo not use a global collection for actor-local state or spawn a dynamic instance for every object\nwhen primitive data or instancing can express the variation.\n","searchText":"instances, functions, and parameter data parent and instances 1. define a bounded family: for example opaque hard surface, foliage, or translucent vfx. 2. put invariant graph structure in the parent. 3. convert only intentional art controls to scalar, vector, texture, or static parameters. 4. group and describe parameters; give safe defaults. 5. create material instances for asset variations. 6. use dynamic instances only when values must change on that object at runtime. static switches remove an inactive branch from a compiled variant but each distinct combination can create another shader permutation. use material analyzer (tools -> audit -> material analyzer) to inspect descendants, static overrides, and opportunities to reparent common configurations. material functions - package repeated calculations, not arbitrary portions of a graph. - name and describe every input/output; set meaningful preview defaults cautiously. - enable expose to library and choose a concise category for team functions. - apply/save changes deliberately: edits propagate to loaded callers, and deleted pins break links. - duplicate engine/default functions before modifying them. - avoid circular function dependencies. parameter ownership - material instance: per material/asset variant. - dynamic material instance: per runtime material slot/component. - custom primitive data: per primitive values exposed to a shared material. - material parameter collection: global or level-wide scalar/vector state. do not use a global collection for actor-local state or spawn a dynamic instance for every object when primitive data or instancing can express the variation."},{"slug":"layers-substrate-and-decals","file":"layers-substrate-and-decals.md","title":"Layers, Substrate, and decals","rawMarkdown":"# Layers, Substrate, and decals\n\n## Layering\n\nUse Material Functions with Material Attributes when the graph author owns a fixed blend\narchitecture. Use Material Layers when artists need to reorder, swap, and tune layers in the\nMaterial Instance Editor. Every extra per-pixel layer and mask still has a rendering cost.\n\nFor each layer define:\n\n- physical surface contribution;\n- blend mask source and coordinate space;\n- normal-combination method;\n- which values remain exposed;\n- fallback for lower quality/platform tiers.\n\n## Substrate\n\nUse Substrate when the surface requires BSDF composition that the conventional shading model\ncannot express cleanly. Confirm project enablement, platform support, material complexity, and\nthe UE 5.8 production decision before making it a shared dependency. Do not migrate a simple\nsurface merely because the framework is newer.\n\n## Decals\n\n1. Create a material with Deferred Decal domain and the required decal blend response.\n2. Display it through a Decal Actor/component or decal mesh.\n3. Confirm the receiving materials respond to the relevant DBuffer channels.\n4. Use sort priority only where overlap order matters; avoid a proliferation of unique priorities.\n5. Inspect angle stretch, projection depth, fade distance, overlap, and target-platform path.\n\nDBuffer is the default decal path for UE5 projects. Decals are suited to localized breakup,\ngrime, damage, and signage; do not replace base material structure with thousands of overlapping\nfull-screen projections.\n","webMarkdown":"## Layering\n\nUse Material Functions with Material Attributes when the graph author owns a fixed blend\narchitecture. Use Material Layers when artists need to reorder, swap, and tune layers in the\nMaterial Instance Editor. Every extra per-pixel layer and mask still has a rendering cost.\n\nFor each layer define:\n\n- physical surface contribution;\n- blend mask source and coordinate space;\n- normal-combination method;\n- which values remain exposed;\n- fallback for lower quality/platform tiers.\n\n## Substrate\n\nUse Substrate when the surface requires BSDF composition that the conventional shading model\ncannot express cleanly. Confirm project enablement, platform support, material complexity, and\nthe UE 5.8 production decision before making it a shared dependency. Do not migrate a simple\nsurface merely because the framework is newer.\n\n## Decals\n\n1. Create a material with Deferred Decal domain and the required decal blend response.\n2. Display it through a Decal Actor/component or decal mesh.\n3. Confirm the receiving materials respond to the relevant DBuffer channels.\n4. Use sort priority only where overlap order matters; avoid a proliferation of unique priorities.\n5. Inspect angle stretch, projection depth, fade distance, overlap, and target-platform path.\n\nDBuffer is the default decal path for UE5 projects. Decals are suited to localized breakup,\ngrime, damage, and signage; do not replace base material structure with thousands of overlapping\nfull-screen projections.\n","searchText":"layers, substrate, and decals layering use material functions with material attributes when the graph author owns a fixed blend architecture. use material layers when artists need to reorder, swap, and tune layers in the material instance editor. every extra per-pixel layer and mask still has a rendering cost. for each layer define: - physical surface contribution; - blend mask source and coordinate space; - normal-combination method; - which values remain exposed; - fallback for lower quality/platform tiers. substrate use substrate when the surface requires bsdf composition that the conventional shading model cannot express cleanly. confirm project enablement, platform support, material complexity, and the ue 5.8 production decision before making it a shared dependency. do not migrate a simple surface merely because the framework is newer. decals 1. create a material with deferred decal domain and the required decal blend response. 2. display it through a decal actor/component or decal mesh. 3. confirm the receiving materials respond to the relevant dbuffer channels. 4. use sort priority only where overlap order matters; avoid a proliferation of unique priorities. 5. inspect angle stretch, projection depth, fade distance, overlap, and target-platform path. dbuffer is the default decal path for ue5 projects. decals are suited to localized breakup, grime, damage, and signage; do not replace base material structure with thousands of overlapping full-screen projections."},{"slug":"pbr-and-properties","file":"pbr-and-properties.md","title":"PBR inputs and material properties","rawMarkdown":"# PBR inputs and material properties\n\n## Minimum surface\n\n1. Select the Material Domain for the job: Surface unless it is explicitly decal, light function,\n   post process, UI, or another specialized domain.\n2. Choose Blend Mode. Use Opaque by default, Masked for binary coverage, and Translucent only\n   when partial transmission is required.\n3. Choose the Shading Model that represents the surface response.\n4. Set Two Sided only when backfaces must render and the lighting result is acceptable.\n5. Connect Base Color, Metallic, Roughness, Normal, and optional Emissive/AO inputs.\n\n## Input meaning\n\n- **Base Color**: intrinsic surface color, without baked directional lighting.\n- **Metallic**: normally 0 for dielectric or 1 for metal; avoid unexplained mid-values.\n- **Roughness**: low sharpens reflections; high broadens them.\n- **Specular**: dielectric specular level; leave the physically reasonable default unless the\n  material calls for a measured exception.\n- **Normal**: fine lighting orientation; verify tangent-space import and sampler type.\n- **Emissive**: emitted radiance appearance; it is not a free replacement for actual lighting.\n- **Opacity Mask**: compared with clip threshold in Masked mode.\n\n## Texture gates\n\n- Color textures use the correct sRGB interpretation; packed masks/data usually do not.\n- Normal textures use the Normal sampler/compression path.\n- Confirm channel packing, UV set, tiling, addressing, mip behavior, and streaming size.\n- Test at near, typical, and far viewing distances under representative neutral lighting.\n\nIf an input is disabled, inspect Domain, Blend Mode, and Shading Model before rebuilding the graph.\n","webMarkdown":"## Minimum surface\n\n1. Select the Material Domain for the job: Surface unless it is explicitly decal, light function,\n   post process, UI, or another specialized domain.\n2. Choose Blend Mode. Use Opaque by default, Masked for binary coverage, and Translucent only\n   when partial transmission is required.\n3. Choose the Shading Model that represents the surface response.\n4. Set Two Sided only when backfaces must render and the lighting result is acceptable.\n5. Connect Base Color, Metallic, Roughness, Normal, and optional Emissive/AO inputs.\n\n## Input meaning\n\n- **Base Color**: intrinsic surface color, without baked directional lighting.\n- **Metallic**: normally 0 for dielectric or 1 for metal; avoid unexplained mid-values.\n- **Roughness**: low sharpens reflections; high broadens them.\n- **Specular**: dielectric specular level; leave the physically reasonable default unless the\n  material calls for a measured exception.\n- **Normal**: fine lighting orientation; verify tangent-space import and sampler type.\n- **Emissive**: emitted radiance appearance; it is not a free replacement for actual lighting.\n- **Opacity Mask**: compared with clip threshold in Masked mode.\n\n## Texture gates\n\n- Color textures use the correct sRGB interpretation; packed masks/data usually do not.\n- Normal textures use the Normal sampler/compression path.\n- Confirm channel packing, UV set, tiling, addressing, mip behavior, and streaming size.\n- Test at near, typical, and far viewing distances under representative neutral lighting.\n\nIf an input is disabled, inspect Domain, Blend Mode, and Shading Model before rebuilding the graph.\n","searchText":"pbr inputs and material properties minimum surface 1. select the material domain for the job: surface unless it is explicitly decal, light function, post process, ui, or another specialized domain. 2. choose blend mode. use opaque by default, masked for binary coverage, and translucent only when partial transmission is required. 3. choose the shading model that represents the surface response. 4. set two sided only when backfaces must render and the lighting result is acceptable. 5. connect base color, metallic, roughness, normal, and optional emissive/ao inputs. input meaning - base color: intrinsic surface color, without baked directional lighting. - metallic: normally 0 for dielectric or 1 for metal; avoid unexplained mid-values. - roughness: low sharpens reflections; high broadens them. - specular: dielectric specular level; leave the physically reasonable default unless the material calls for a measured exception. - normal: fine lighting orientation; verify tangent-space import and sampler type. - emissive: emitted radiance appearance; it is not a free replacement for actual lighting. - opacity mask: compared with clip threshold in masked mode. texture gates - color textures use the correct srgb interpretation; packed masks/data usually do not. - normal textures use the normal sampler/compression path. - confirm channel packing, uv set, tiling, addressing, mip behavior, and streaming size. - test at near, typical, and far viewing distances under representative neutral lighting. if an input is disabled, inspect domain, blend mode, and shading model before rebuilding the graph."},{"slug":"profiling-and-debugging","file":"profiling-and-debugging.md","title":"Profiling and debugging","rawMarkdown":"# Profiling and debugging\n\n## Visual defect ladder\n\n1. Preview texture channels and constants independently.\n2. Verify UV set/scale and object/world/tangent coordinate spaces.\n3. Verify sRGB, normal sampler, compression, channel packing, and mip level.\n4. Reduce the graph to the minimum surface; re-enable functions/layers one at a time.\n5. Test neutral direct lighting before blaming the material or lighting system.\n6. Inspect bounds, decals, RVT writer/receiver assignment, and platform feature switches.\n\n## Cost ladder\n\n1. Record target resolution, view, material screen coverage, and overlapping transparency.\n2. Use Material Editor stats/platform stats for compiled shader information.\n3. Use Shader Complexity (`Alt+8`) to locate costly pixel regions and particle/translucency overdraw.\n4. Use Material Analyzer for static-switch/permutation families.\n5. Use GPU profiling/Insights on target hardware to verify actual passes and time.\n6. Change one suspected cost and compare the same capture.\n\nInstruction count alone misses important differences such as texture fetches, bandwidth, divergent\nwork, and vertex cost. A costly pixel shader matters most over large screen area; WPO/vertex work\nmatters for every submitted vertex. Translucent layers can repeatedly shade the same pixel.\n\nCommon causes:\n\n- Pink/checker/default material -> compile error, missing shader, unsupported path.\n- Flat/no normal response -> sampler/import type or tangent basis.\n- Dark/bright mismatch -> color-space or packed-channel error.\n- Flickering displacement -> bounds, precision, temporal aliasing, or LOD discontinuity.\n- Shader compile explosion -> unconstrained static switches and instance override combinations.\n","webMarkdown":"## Visual defect ladder\n\n1. Preview texture channels and constants independently.\n2. Verify UV set/scale and object/world/tangent coordinate spaces.\n3. Verify sRGB, normal sampler, compression, channel packing, and mip level.\n4. Reduce the graph to the minimum surface; re-enable functions/layers one at a time.\n5. Test neutral direct lighting before blaming the material or lighting system.\n6. Inspect bounds, decals, RVT writer/receiver assignment, and platform feature switches.\n\n## Cost ladder\n\n1. Record target resolution, view, material screen coverage, and overlapping transparency.\n2. Use Material Editor stats/platform stats for compiled shader information.\n3. Use Shader Complexity (`Alt+8`) to locate costly pixel regions and particle/translucency overdraw.\n4. Use Material Analyzer for static-switch/permutation families.\n5. Use GPU profiling/Insights on target hardware to verify actual passes and time.\n6. Change one suspected cost and compare the same capture.\n\nInstruction count alone misses important differences such as texture fetches, bandwidth, divergent\nwork, and vertex cost. A costly pixel shader matters most over large screen area; WPO/vertex work\nmatters for every submitted vertex. Translucent layers can repeatedly shade the same pixel.\n\nCommon causes:\n\n- Pink/checker/default material -> compile error, missing shader, unsupported path.\n- Flat/no normal response -> sampler/import type or tangent basis.\n- Dark/bright mismatch -> color-space or packed-channel error.\n- Flickering displacement -> bounds, precision, temporal aliasing, or LOD discontinuity.\n- Shader compile explosion -> unconstrained static switches and instance override combinations.\n","searchText":"profiling and debugging visual defect ladder 1. preview texture channels and constants independently. 2. verify uv set/scale and object/world/tangent coordinate spaces. 3. verify srgb, normal sampler, compression, channel packing, and mip level. 4. reduce the graph to the minimum surface; re-enable functions/layers one at a time. 5. test neutral direct lighting before blaming the material or lighting system. 6. inspect bounds, decals, rvt writer/receiver assignment, and platform feature switches. cost ladder 1. record target resolution, view, material screen coverage, and overlapping transparency. 2. use material editor stats/platform stats for compiled shader information. 3. use shader complexity (alt+8) to locate costly pixel regions and particle/translucency overdraw. 4. use material analyzer for static-switch/permutation families. 5. use gpu profiling/insights on target hardware to verify actual passes and time. 6. change one suspected cost and compare the same capture. instruction count alone misses important differences such as texture fetches, bandwidth, divergent work, and vertex cost. a costly pixel shader matters most over large screen area; wpo/vertex work matters for every submitted vertex. translucent layers can repeatedly shade the same pixel. common causes: - pink/checker/default material -> compile error, missing shader, unsupported path. - flat/no normal response -> sampler/import type or tangent basis. - dark/bright mismatch -> color-space or packed-channel error. - flickering displacement -> bounds, precision, temporal aliasing, or lod discontinuity. - shader compile explosion -> unconstrained static switches and instance override combinations."},{"slug":"rvt-and-world-effects","file":"rvt-and-world-effects.md","title":"Runtime Virtual Textures and world effects","rawMarkdown":"# Runtime Virtual Textures and world effects\n\n## RVT workflow\n\n1. Create a Runtime Virtual Texture asset with the required material type/resolution.\n2. Add and size an RVT Volume; assign the RVT asset.\n3. Configure writer materials with RVT output expressions.\n4. Configure receiving materials with RVT Sample or RVT Sample Parameter.\n5. Assign the RVT asset to components that render into it.\n6. Verify main-pass behavior, virtual-texture support fallback, mips, memory, and page uploads.\n\nGood writers are mostly static large-area contributors: Landscape, Landscape Splines, static\nmeshes, instances, and foliage. Skeletal, movable, and frequently animated writers are poor fits\nbecause RVT acts as a shading cache rather than a fully refreshed render target.\n\nUse YCoCg base-color storage when smooth-gradient color quality justifies roughly 25% extra\nmemory and decode cost. If overlapping writers disappear or order incorrectly, inspect\nTranslucency Sort Priority; equal priority order is undefined.\n\n## World-space effects\n\n- Global wetness/snow value -> Material Parameter Collection.\n- Local accumulation around many objects -> primitive data, masks, decals, or RVT according to scale.\n- Vertex wind/displacement -> WPO with explicit amplitude, bounds, LOD, shadow, and Nanite checks.\n- Camera-distance simplification -> explicit quality/LOD design, not an unmeasured chain of branches.\n\nWPO does not move collision. When gameplay requires changed collision, modify the owning geometry\nor gameplay representation, not only the shader.\n","webMarkdown":"## RVT workflow\n\n1. Create a Runtime Virtual Texture asset with the required material type/resolution.\n2. Add and size an RVT Volume; assign the RVT asset.\n3. Configure writer materials with RVT output expressions.\n4. Configure receiving materials with RVT Sample or RVT Sample Parameter.\n5. Assign the RVT asset to components that render into it.\n6. Verify main-pass behavior, virtual-texture support fallback, mips, memory, and page uploads.\n\nGood writers are mostly static large-area contributors: Landscape, Landscape Splines, static\nmeshes, instances, and foliage. Skeletal, movable, and frequently animated writers are poor fits\nbecause RVT acts as a shading cache rather than a fully refreshed render target.\n\nUse YCoCg base-color storage when smooth-gradient color quality justifies roughly 25% extra\nmemory and decode cost. If overlapping writers disappear or order incorrectly, inspect\nTranslucency Sort Priority; equal priority order is undefined.\n\n## World-space effects\n\n- Global wetness/snow value -> Material Parameter Collection.\n- Local accumulation around many objects -> primitive data, masks, decals, or RVT according to scale.\n- Vertex wind/displacement -> WPO with explicit amplitude, bounds, LOD, shadow, and Nanite checks.\n- Camera-distance simplification -> explicit quality/LOD design, not an unmeasured chain of branches.\n\nWPO does not move collision. When gameplay requires changed collision, modify the owning geometry\nor gameplay representation, not only the shader.\n","searchText":"runtime virtual textures and world effects rvt workflow 1. create a runtime virtual texture asset with the required material type/resolution. 2. add and size an rvt volume; assign the rvt asset. 3. configure writer materials with rvt output expressions. 4. configure receiving materials with rvt sample or rvt sample parameter. 5. assign the rvt asset to components that render into it. 6. verify main-pass behavior, virtual-texture support fallback, mips, memory, and page uploads. good writers are mostly static large-area contributors: landscape, landscape splines, static meshes, instances, and foliage. skeletal, movable, and frequently animated writers are poor fits because rvt acts as a shading cache rather than a fully refreshed render target. use ycocg base-color storage when smooth-gradient color quality justifies roughly 25% extra memory and decode cost. if overlapping writers disappear or order incorrectly, inspect translucency sort priority; equal priority order is undefined. world-space effects - global wetness/snow value -> material parameter collection. - local accumulation around many objects -> primitive data, masks, decals, or rvt according to scale. - vertex wind/displacement -> wpo with explicit amplitude, bounds, lod, shadow, and nanite checks. - camera-distance simplification -> explicit quality/lod design, not an unmeasured chain of branches. wpo does not move collision. when gameplay requires changed collision, modify the owning geometry or gameplay representation, not only the shader."},{"slug":"sources","file":"sources.md","title":"UE 5.8 primary sources","rawMarkdown":"# UE 5.8 primary sources\n\n- [Materials](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-materials)\n- [Material Inputs](https://dev.epicgames.com/documentation/en-us/unreal-engine/material-inputs-in-unreal-engine)\n- [Creating and Using Material Instances](https://dev.epicgames.com/documentation/en-us/unreal-engine/creating-and-using-material-instances-in-unreal-engine)\n- [Material Functions](https://dev.epicgames.com/documentation/en-us/unreal-engine/material-functions-in-unreal-engine)\n- [Creating and Using Material Functions](https://dev.epicgames.com/documentation/en-us/unreal-engine/creating-and-using-material-functions-in-unreal-engine)\n- [Layering Materials](https://dev.epicgames.com/documentation/en-us/unreal-engine/layering-materials-in-unreal-engine)\n- [Using Material Layers](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-material-layers-in-unreal-engine)\n- [Material Parameter Collections](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-material-parameter-collections-in-unreal-engine)\n- [Decal Materials](https://dev.epicgames.com/documentation/en-us/unreal-engine/decal-materials-in-unreal-engine)\n- [Runtime Virtual Texturing](https://dev.epicgames.com/documentation/en-us/unreal-engine/runtime-virtual-texturing-in-unreal-engine)\n- [Material Analyzer](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-material-analyzer-tool)\n- [Viewport Modes / Shader Complexity](https://dev.epicgames.com/documentation/en-us/unreal-engine/viewport-modes-in-unreal-engine)\n- [Transparency](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-transparency-in-unreal-engine-materials)\n- [Scalability Reference](https://dev.epicgames.com/documentation/en-us/unreal-engine/scalability-reference-for-unreal-engine)\n\nPages were checked against the UE 5.8 documentation on 2026-07-19. Reconfirm feature maturity,\nplatform support, and shader behavior after an engine upgrade.\n","webMarkdown":"- [Materials](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-materials)\n- [Material Inputs](https://dev.epicgames.com/documentation/en-us/unreal-engine/material-inputs-in-unreal-engine)\n- [Creating and Using Material Instances](https://dev.epicgames.com/documentation/en-us/unreal-engine/creating-and-using-material-instances-in-unreal-engine)\n- [Material Functions](https://dev.epicgames.com/documentation/en-us/unreal-engine/material-functions-in-unreal-engine)\n- [Creating and Using Material Functions](https://dev.epicgames.com/documentation/en-us/unreal-engine/creating-and-using-material-functions-in-unreal-engine)\n- [Layering Materials](https://dev.epicgames.com/documentation/en-us/unreal-engine/layering-materials-in-unreal-engine)\n- [Using Material Layers](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-material-layers-in-unreal-engine)\n- [Material Parameter Collections](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-material-parameter-collections-in-unreal-engine)\n- [Decal Materials](https://dev.epicgames.com/documentation/en-us/unreal-engine/decal-materials-in-unreal-engine)\n- [Runtime Virtual Texturing](https://dev.epicgames.com/documentation/en-us/unreal-engine/runtime-virtual-texturing-in-unreal-engine)\n- [Material Analyzer](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-material-analyzer-tool)\n- [Viewport Modes / Shader Complexity](https://dev.epicgames.com/documentation/en-us/unreal-engine/viewport-modes-in-unreal-engine)\n- [Transparency](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-transparency-in-unreal-engine-materials)\n- [Scalability Reference](https://dev.epicgames.com/documentation/en-us/unreal-engine/scalability-reference-for-unreal-engine)\n\nPages were checked against the UE 5.8 documentation on 2026-07-19. Reconfirm feature maturity,\nplatform support, and shader behavior after an engine upgrade.\n","searchText":"ue 5.8 primary sources - materials - material inputs - creating and using material instances - material functions - creating and using material functions - layering materials - using material layers - material parameter collections - decal materials - runtime virtual texturing - material analyzer - viewport modes / shader complexity - transparency - scalability reference pages were checked against the ue 5.8 documentation on 2026-07-19. reconfirm feature maturity, platform support, and shader behavior after an engine upgrade."}]}
{"slug":"unreal-memory-streaming","name":"unreal-memory-streaming","title":"Unreal 5.8 Memory and Streaming","description":"Budget, load, retain, stream, evict, precache, and diagnose runtime content in Unreal Engine 5.8. Use for unexpected asset residency, hard and soft reference chains, Asset Manager load lifetimes, async loading, Memory Insights, LLM, texture streaming pools and mip quality, Streaming Virtual Texturing, Nanite streaming, World Partition readiness, load-time hitches, shader or PSO compilation hitches, PSO precaching, bundled PSO caches, or memory/load regression testing.","shortDescription":"Control Unreal residency, streaming, and hitches","category":"Data, Tools & Shipping","referenceCount":12,"rawMarkdown":"---\nname: unreal-memory-streaming\ndescription: Budget, load, retain, stream, evict, precache, and diagnose runtime content in Unreal Engine 5.8. Use for unexpected asset residency, hard and soft reference chains, Asset Manager load lifetimes, async loading, Memory Insights, LLM, texture streaming pools and mip quality, Streaming Virtual Texturing, Nanite streaming, World Partition readiness, load-time hitches, shader or PSO compilation hitches, PSO precaching, bundled PSO caches, or memory/load regression testing.\n---\n\n# Unreal 5.8 Memory and Streaming\n\n## Classify the failure before changing policy\n\nRead [`references/system-selector.md`](references/system-selector.md) and\n[`references/budgets-and-evidence.md`](references/budgets-and-evidence.md).\n\n1. Define target device, memory pools, storage, build, scenario, cold/warm state, and readiness budget.\n2. Classify the problem: dependency residency, retained allocation, streaming budget, IO/load latency,\n   render-resource readiness, or shader/PSO compilation.\n3. Capture the appropriate evidence: Reference Viewer/Size Map, Memory Insights/LLM, Asset Loading\n   Insights, texture/VT/Nanite stats, Render Resource Viewer, or PSO validation.\n4. Name the owner, load trigger, residency boundary, unload condition, and failure behavior.\n5. Change one dependency edge, budget, lead time, representation, or precache policy.\n6. Repeat the identical cold or warm traversal on target hardware and verify memory, quality, and hitch.\n\nUse neighboring skills for their owned decisions:\n\n- Asset schemas, Primary Asset rules, bundles, cook inclusion ->\n  [`../unreal-data-assets-tables/SKILL.md`](../unreal-data-assets-tables/SKILL.md)\n- World Partition cells, sources, loading range, teleports ->\n  [`../unreal-world-partition/SKILL.md`](../unreal-world-partition/SKILL.md)\n- Trace capture and Memory/Asset Loading Insights ->\n  [`../unreal-insights-profiling/SKILL.md`](../unreal-insights-profiling/SKILL.md)\n- GPU resource/pass budgets ->\n  [`../unreal-rendering-performance/SKILL.md`](../unreal-rendering-performance/SKILL.md)\n\nLoad only what applies:\n\n- [`references/reference-graphs-and-residency.md`](references/reference-graphs-and-residency.md)\n- [`references/async-loading-and-lifetime.md`](references/async-loading-and-lifetime.md)\n- [`references/texture-streaming.md`](references/texture-streaming.md)\n- [`references/virtual-texturing.md`](references/virtual-texturing.md)\n- [`references/geometry-and-world-readiness.md`](references/geometry-and-world-readiness.md)\n- [`references/pso-and-shader-hitches.md`](references/pso-and-shader-hitches.md)\n- [`references/memory-profiling.md`](references/memory-profiling.md)\n- [`references/load-hitch-diagnosis.md`](references/load-hitch-diagnosis.md)\n- [`references/regression-and-recipes.md`](references/regression-and-recipes.md)\n\n## Required answer format\n\nReturn:\n\n1. **Target budget and workload**, including cold/warm state.\n2. **Failure class and evidence source**.\n3. **Owner and dependency/residency graph**.\n4. **Load, readiness, use, retention, and unload sequence**.\n5. **Exact setting/API/policy change** and predicted memory/latency/quality effect.\n6. **Cooked-build A/B proof** and failure-path test.\n7. **Uncertainty**, profiler overhead, and adjacent skill routing.\n\n## Hard rules\n\n- Do not equate soft references with unloaded content; loaded assets require explicit lifetime ownership.\n- Do not replace every hard edge with a soft edge; use hard references inside one intentional residency unit.\n- Never synchronously load in latency-sensitive gameplay unless a measured, bounded exception is accepted.\n- Separate CPU memory, GPU allocations, texture pools, VT pools, Nanite pools, and package size.\n- Do not set `r.Streaming.PoolSize=0` or disable streaming as a shipping fix.\n- Do not raise a pool before proving the target budget has headroom and the content demand is valid.\n- Treat low mips, fallback meshes, collision, shaders/PSOs, registration, and gameplay initialization as\n  part of readiness—not only UObject load completion.\n- Memory allocation tracing must start with the process; a late trace cannot reconstruct old allocations.\n- Validate PSO precache misses and wait for required startup compiles; a warm driver cache can hide failure.\n- Prove behavior in a cooked target build. PIE, loose editor content, and a warm dev PC are insufficient.\n\nSee [`references/sources.md`](references/sources.md) for the UE 5.8 primary-source trail.\n","webMarkdown":"## Classify the failure before changing policy\n\nRead [`references/system-selector.md`](/unreal/unreal-memory-streaming/system-selector/) and\n[`references/budgets-and-evidence.md`](/unreal/unreal-memory-streaming/budgets-and-evidence/).\n\n1. Define target device, memory pools, storage, build, scenario, cold/warm state, and readiness budget.\n2. Classify the problem: dependency residency, retained allocation, streaming budget, IO/load latency,\n   render-resource readiness, or shader/PSO compilation.\n3. Capture the appropriate evidence: Reference Viewer/Size Map, Memory Insights/LLM, Asset Loading\n   Insights, texture/VT/Nanite stats, Render Resource Viewer, or PSO validation.\n4. Name the owner, load trigger, residency boundary, unload condition, and failure behavior.\n5. Change one dependency edge, budget, lead time, representation, or precache policy.\n6. Repeat the identical cold or warm traversal on target hardware and verify memory, quality, and hitch.\n\nUse neighboring skills for their owned decisions:\n\n- Asset schemas, Primary Asset rules, bundles, cook inclusion ->\n  [`../unreal-data-assets-tables/SKILL.md`](/unreal/unreal-data-assets-tables/)\n- World Partition cells, sources, loading range, teleports ->\n  [`../unreal-world-partition/SKILL.md`](/unreal/unreal-world-partition/)\n- Trace capture and Memory/Asset Loading Insights ->\n  [`../unreal-insights-profiling/SKILL.md`](/unreal/unreal-insights-profiling/)\n- GPU resource/pass budgets ->\n  [`../unreal-rendering-performance/SKILL.md`](/unreal/unreal-rendering-performance/)\n\nLoad only what applies:\n\n- [`references/reference-graphs-and-residency.md`](/unreal/unreal-memory-streaming/reference-graphs-and-residency/)\n- [`references/async-loading-and-lifetime.md`](/unreal/unreal-memory-streaming/async-loading-and-lifetime/)\n- [`references/texture-streaming.md`](/unreal/unreal-memory-streaming/texture-streaming/)\n- [`references/virtual-texturing.md`](/unreal/unreal-memory-streaming/virtual-texturing/)\n- [`references/geometry-and-world-readiness.md`](/unreal/unreal-memory-streaming/geometry-and-world-readiness/)\n- [`references/pso-and-shader-hitches.md`](/unreal/unreal-memory-streaming/pso-and-shader-hitches/)\n- [`references/memory-profiling.md`](/unreal/unreal-memory-streaming/memory-profiling/)\n- [`references/load-hitch-diagnosis.md`](/unreal/unreal-memory-streaming/load-hitch-diagnosis/)\n- [`references/regression-and-recipes.md`](/unreal/unreal-memory-streaming/regression-and-recipes/)\n\n## Required answer format\n\nReturn:\n\n1. **Target budget and workload**, including cold/warm state.\n2. **Failure class and evidence source**.\n3. **Owner and dependency/residency graph**.\n4. **Load, readiness, use, retention, and unload sequence**.\n5. **Exact setting/API/policy change** and predicted memory/latency/quality effect.\n6. **Cooked-build A/B proof** and failure-path test.\n7. **Uncertainty**, profiler overhead, and adjacent skill routing.\n\n## Hard rules\n\n- Do not equate soft references with unloaded content; loaded assets require explicit lifetime ownership.\n- Do not replace every hard edge with a soft edge; use hard references inside one intentional residency unit.\n- Never synchronously load in latency-sensitive gameplay unless a measured, bounded exception is accepted.\n- Separate CPU memory, GPU allocations, texture pools, VT pools, Nanite pools, and package size.\n- Do not set `r.Streaming.PoolSize=0` or disable streaming as a shipping fix.\n- Do not raise a pool before proving the target budget has headroom and the content demand is valid.\n- Treat low mips, fallback meshes, collision, shaders/PSOs, registration, and gameplay initialization as\n  part of readiness—not only UObject load completion.\n- Memory allocation tracing must start with the process; a late trace cannot reconstruct old allocations.\n- Validate PSO precache misses and wait for required startup compiles; a warm driver cache can hide failure.\n- Prove behavior in a cooked target build. PIE, loose editor content, and a warm dev PC are insufficient.\n\nSee [`references/sources.md`](/unreal/unreal-memory-streaming/sources/) for the UE 5.8 primary-source trail.\n","searchText":"unreal 5.8 memory and streaming budget, load, retain, stream, evict, precache, and diagnose runtime content in unreal engine 5.8. use for unexpected asset residency, hard and soft reference chains, asset manager load lifetimes, async loading, memory insights, llm, texture streaming pools and mip quality, streaming virtual texturing, nanite streaming, world partition readiness, load-time hitches, shader or pso compilation hitches, pso precaching, bundled pso caches, or memory/load regression testing. async loading and lifetime async loading and lifetime owned load sequence 1. gather soft paths or primary asset ids before the transition. 2. request through asset manager or fstreamablemanager::requestasyncload. 3. retain the fstreamablehandle when cancellation, progress, combined requests, or residency ownership matters. 4. on completion, verify request state and every required asset; callbacks may arrive after the caller's original state changed. 5. create/register render, physics, audio, and gameplay resources in a bounded readiness phase. 6. transfer assets into a hard owner for the exact use lifetime or keep the governing handle alive. 7. on cancellation/transition, stop dependent work, release owners/handles, and verify collection/eviction. fstreamablemanager keeps requested assets referenced through the completion delegate; afterward the caller must retain them if needed. a soft pointer path does not itself own residency. race and failure checks - owner destroyed before completion; - two requests for the same asset with different consumers; - cancel after io began but before callback; - partial bundle failure or missing cooked dependency; - async completion followed by synchronous resource creation hitch; - unload while a component/task/delegate still uses the asset; - stale callback applies content to a new state/level/character. use a request generation/token and weak owner where appropriate. completion means “asset available,” not automatically “gameplay-ready.” budgets and evidence budgets and evidence record before analysis: | dimension | required context | |---|---| | hardware | platform, ram/vram/unified memory, storage, driver/os | | build | commit, configuration, cooked/pie, device profile | | workload | map, path, speed, camera, content counts, duration | | cache state | cold process/os/driver/ddc versus warmed state | | budgets | peak/resident memory by pool, ready latency, hitch threshold, quality floor | | capture | trace channels/stats, markers, start/end, sampling overhead | measure separately: - process/platform committed and resident memory; - engine/llm allocation categories; - uobject/assets and retained ownership; - gpu resource allocations; - conventional texture streaming pool; - each virtual-texture physical pool and page-table memory; - nanite streaming pool; - transient load/decompression/pso compile peaks; - package/install size. do not sum overlapping counters. define whether each value is reserved, allocated, resident, wanted, budgeted, or transient. compare cold and warm runs when the player can experience both. geometry and world readiness geometry and world readiness nanite nanite streams fine-grained geometry pages. r.nanite.streaming.streamingpoolsize trades memory for fewer io/decompression requests; too small a pool can thrash even in a static view. use nanite streaming geometry visualization and nanitestats before changing it. validate package/storage cost separately. conventional meshes and skeletal content per-platform lods reduce render cost and may reduce memory when higher lods are stripped or excluded by platform policy. confirm which lod/render resources are resident in render resource viewer. do not assume an unseen mesh releases while a component, asset, or streaming handle still owns it. world partition readiness world partition cell loading is only one layer. ready-to-enter must include: - required cell activated/loaded state; - collision and navigation ready; - required assets and bundles loaded; - texture/nanite/vt quality above the declared floor; - render/physics components registered; - psos required for first visible use compiled; - gameplay initialization complete. derive preload lead distance from maximum approach speed × worst measured readiness latency plus look- ahead and safety margin. for teleports, use a temporary destination streaming source and wait on the world partition subsystem, then apply the broader readiness gate. avoid globally inflating loading range to solve one path; it raises residency and concurrent io everywhere. load and streaming hitch diagnosis load and streaming hitch diagnosis 1. mark the player action/region entry and capture timing plus loadtime/file channels as needed. 2. inspect asset loading insights package order, async priorities, serialization, and game-thread waits. 3. correlate file io, decompression, uobject creation, postload, component registration, render/physics resource creation, pso compile, and gc. 4. determine whether work is synchronous, async but completed too late, or async followed by a blocking readiness phase. 5. move/preload only the causal work, increase lead time, or amortize creation across frames. | symptom | first evidence | |---|---| | first pickup/effect hitches | package load, component registration, pso/decode readiness | | entering region hitches | world partition/cell activation, file io, texture/nanite demand | | memory spike then gc hitch | transient allocations, object churn, retained load handles | | asset says loaded but appears late | render/physics resource or pso readiness | | cold run hitches, warm run does not | os/driver/cache-sensitive io or compilation | | async request still stalls | late request, completion on critical path, sync dependency inside postload | never “fix” by hiding the trace interval behind a shorter loading screen. if blocking is required, own it with a real loading transition and an explicit complete/timeout/failure contract. memory profiling memory profiling memory insights start allocation tracing with the process: text mygame.exe -trace=default,memory mygame.exe -trace=default,memory,metadata,assetmetadata use marked a/b timestamps to query allocations live at a point, retained across an action, freed during an interval, or monotonically growing across repetitions. metadata improves asset/class attribution but increases trace volume. late connect cannot reconstruct allocations made before tracing began. low-level memory tracker launch with -llm for tagged totals or -llmcsv for periodic csv under saved/profiling/llm. inspect stat llm, stat llmfull, stat llmplatform, and stat llmoverhead where available. default tracker allocations are a subset of platform tracker totals; do not add them together. asset/assetclass tag sets are experimental and add memory/runtime overhead. use them only for targeted diagnosis and record that overhead. interpretation - growth that stabilizes may be an intentional cache; prove its cap and eviction; - repeated retained growth after teardown suggests surviving ownership; - high alloc/free rate with stable total is churn, not a leak; - llm category attribution and detailed allocation callstacks answer different questions; - gpu resources, driver memory, mapped files, and platform allocations may not equal uobject estimates. pso and shader compilation hitches pso and shader compilation hitches ue 5.8 enables pso precaching where the rhi supports it. component precaching gathers material, vertex- factory, render-state, and mesh-pass psos after load and compiles asynchronously. validate 1. test a cooked development build with an empty/cold driver cache on representative consumer cpu cores. 2. enable r.psoprecache.validation 1 for lightweight numbers or 2 for detailed miss logging. 3. inspect stat psoprecache and shader pipeline cache runtime hitch statistics. 4. correlate first-visible hitch with pso compilation rather than asset io/registration. 5. wait during a loading screen until required outstanding compiles reach zero; use fshaderpipelinecache::numprecompilesremaining() for the governing check. if a component's pso is not ready, the proxy delay strategy can skip the draw or show default material; allowing the draw to block risks a hitch. pick the visual/readiness policy explicitly. bundled cache boundary runtime precaching should cover most cases. add a manually recorded bundled graphics pso cache when validation proves misses or unsupported collection paths remain. record representative content on each platform/rhi, merge/stabilize through the documented cook pipeline, ship the cache, and repeat cold-cache validation. ray-tracing psos are not supported by the bundled-cache workflow documented for ue 5.8. do not judge from a warm developer driver cache. new materials, vertex factories, passes, quality tiers, rhi changes, and content patches require renewed coverage. reference graphs and residency reference graphs and residency audit an unexpected load 1. select the suspect asset and open reference viewer. 2. inspect referencers, dependencies, hard/soft edges, management references, and reference tree depth. 3. open size map for the asset and its dependencies; use asset audit for class/type/cooked-size detail. 4. confirm the runtime owner with memory insights/llm; editor graph size is not runtime residency proof. 5. identify the earliest hard edge that crosses the intended residency boundary. 6. convert only that boundary to a soft/primary asset load contract, then prove cook and lifetime. use a hard reference when owner and target must always be resident together. use tsoftobjectptr, tsoftclassptr, or fsoftobjectpath when the dependency must load on demand. use primary asset ids and bundles when many callers need governed discovery and phase-specific residency. common accidental roots: - gameinstance/subsystem/default object references; - always-loaded maps, huds, gamemodes, singletons, or data assets; - blueprint class defaults that reference presentation-heavy classes; - arrays/catalogs holding hard class or asset pointers; - an async-loaded object copied into a long-lived hard owner; - delegates/tasks/components retaining the owner after expected teardown. report the root and complete chain. removing the leaf from memory without changing its surviving owner does not fix retention. regression and recipes regression and recipes regression record | metric | baseline | candidate | budget/result | |---|---:|---:|---| | peak process/platform memory | | | | | steady memory after traversal | | | | | texture/vt/nanite pool pressure | | | | | ready latency / worst hitch ms | | | | | pso misses/runtime compile hitches | | | | | visual quality/fallback result | | | | run repeated cold and warm samples. preserve device profile, build, route, speed, camera, content, and cache preparation. reject wins that shift work past the capture, lower required quality, or break cook. symptom recipes | symptom | bounded experiment | |---|---| | opening one menu loads a level's content | reference viewer from widget/class default; soften first boundary | | textures stay blurry | build/inspect streaming data, then compare wanted versus budgeted mips | | texture pool over budget | identify valid demand/forced/non-streaming owners before pool or mip change | | vt tiles flicker | identify saturated format pool; a/b fixed pool size within vram budget | | static nanite view keeps streaming | inspect pool thrash; a/b pool or resident demand | | repeated spawn/despawn grows ram | marked memory insights retained-allocation query | | first material use hitches | cold pso validation; wait/precache or cover documented misses | | teleport arrives into missing world | destination source plus complete readiness gate and timeout | ue 5.8 primary sources ue 5.8 primary sources - memory insights - low-level memory tracker - reference viewer - asset management - asynchronous asset loading - texture streaming overview - building texture streaming data - texture streaming configuration - texture streaming metrics - streaming virtual texturing - virtual texture memory pools - runtime virtual texturing - pso precaching - creating a bundled pso cache - nanite technical details pages were checked against ue 5.8 documentation on 2026-07-19. reconfirm trace channels, pool semantics, platform/rhi support, pso workflow, defaults, and feature maturity after an engine upgrade. system selector system selector | question | primary evidence/system | |---|---| | why is this asset loaded? | reference viewer/reference tree, asset manager audit | | what owns retained cpu memory? | memory insights + llm tags/callstacks | | what owns gpu memory? | render resource viewer + platform/rhi metrics | | why are textures blurry or thrashing? | stat streaming, texture accuracy/resolution views | | why do virtual textures show low-res tiles? | vt pool stats/visualization and feedback/upload demand | | why does entering a region hitch? | asset loading insights, file/loadtime trace, world partition evidence | | why does first rendering hitch? | pso precache validation and shader pipeline cache hitch stats | | why does geometry pop or stream forever? | nanite stats/pool or world partition readiness | | why did memory grow after repeated action? | marked memory insights allocation query | do not combine all streaming systems into one “pool.” each has separate ownership, telemetry, eviction, and quality behavior. texture streaming texture streaming diagnose before changing the pool 1. build texture streaming data: build dropdown -> build texture streaming. 2. use primitive distance, mesh uv density, material texture scales, and required texture resolution accuracy/view modes to find bad bounds, uv density, scale analysis, or insufficient residency. 3. run stat streaming and record texture, streaming, wanted, budget, over-budget, and update time. 4. reproduce the target camera path and distinguish temporary cached mips from sustained demand. controls | cvar | effect/tradeoff | |---|---| | r.streaming.poolsize | texture-pool mb; larger reduces pressure but consumes target memory | | r.streaming.framesforfullupdate | larger lowers streamer cpu work but reacts more slowly | | r.streaming.maxtempmemoryallowed | more staging may improve throughput but raises transient memory | | r.streaming.mipbias | larger bias reduces wanted resolution and quality | | r.streaming.usepertexturebias | applies bias selectively to fit the pool rather than degrading every wanted mip | | r.streaming.limitpoolsizetovram | caps pool against available gpu memory where supported | r.texturestreaming 0, r.streaming.poolsize 0, r.streaming.useallmips, and r.streaming.fullyloadusedtextures are diagnostic/showcase controls, not default shipping fixes. for a controlled wanted-resolution test, r.streaming.dropmips 2 removes cached/hidden mips so the required texture resolution view reflects visible demand; restore it before final measurement. fix stale material-instance streaming data, wrong mesh uv density, oversized bounds, forced residency, incorrect texture groups, and excessive source resolution before buying a larger pool. streaming and runtime virtual texturing streaming and runtime virtual texturing use streaming virtual texturing (svt) for large cooked textures/udims when tile-level residency beats whole-mip streaming. use runtime virtual texturing (rvt) for gpu-generated/cacheable surface data such as landscape blending. do not convert content solely because conventional texture streaming is poorly configured. physical pools - page-table memory grows on demand and generally remains until all related content is released. - each vt physical pool is a fixed-size lru cache matched by format/tile configuration. - configure serialized pools under project settings -> engine -> virtual texture pool. - transient auto-grown pools exist only for the editor session; copy validated estimates into fixed pools for cooked builds. - if visible tiles exceed a matching pool, continual eviction produces low-resolution/flickering tiles. use stat virtualtexturing for update/upload cost and page-table counters; use stat virtualtexturememory for pool memory. inspect each format/layer pool independently. larger pools reduce eviction but permanently reserve more gpu memory. increasing upload limits/feedback resolution can reduce latency while increasing cpu/gpu/upload work. tune a repeatable traversal and test camera cuts, fast motion, multiple views, and every device profile. rvt low mips for large worlds may require far-away actors to remain resident. bake/stream low mips when that trades runtime generation and residency for acceptable disk/streaming cost.","references":[{"slug":"async-loading-and-lifetime","file":"async-loading-and-lifetime.md","title":"Async loading and lifetime","rawMarkdown":"# Async loading and lifetime\n\n## Owned load sequence\n\n1. Gather soft paths or Primary Asset IDs before the transition.\n2. Request through Asset Manager or `FStreamableManager::RequestAsyncLoad`.\n3. Retain the `FStreamableHandle` when cancellation, progress, combined requests, or residency ownership\n   matters.\n4. On completion, verify request state and every required asset; callbacks may arrive after the caller's\n   original state changed.\n5. Create/register render, physics, audio, and gameplay resources in a bounded readiness phase.\n6. Transfer assets into a hard owner for the exact use lifetime or keep the governing handle alive.\n7. On cancellation/transition, stop dependent work, release owners/handles, and verify collection/eviction.\n\n`FStreamableManager` keeps requested assets referenced through the completion delegate; afterward the\ncaller must retain them if needed. A soft pointer path does not itself own residency.\n\n## Race and failure checks\n\n- owner destroyed before completion;\n- two requests for the same asset with different consumers;\n- cancel after IO began but before callback;\n- partial bundle failure or missing cooked dependency;\n- async completion followed by synchronous resource creation hitch;\n- unload while a component/task/delegate still uses the asset;\n- stale callback applies content to a new state/level/character.\n\nUse a request generation/token and weak owner where appropriate. Completion means “asset available,”\nnot automatically “gameplay-ready.”\n","webMarkdown":"## Owned load sequence\n\n1. Gather soft paths or Primary Asset IDs before the transition.\n2. Request through Asset Manager or `FStreamableManager::RequestAsyncLoad`.\n3. Retain the `FStreamableHandle` when cancellation, progress, combined requests, or residency ownership\n   matters.\n4. On completion, verify request state and every required asset; callbacks may arrive after the caller's\n   original state changed.\n5. Create/register render, physics, audio, and gameplay resources in a bounded readiness phase.\n6. Transfer assets into a hard owner for the exact use lifetime or keep the governing handle alive.\n7. On cancellation/transition, stop dependent work, release owners/handles, and verify collection/eviction.\n\n`FStreamableManager` keeps requested assets referenced through the completion delegate; afterward the\ncaller must retain them if needed. A soft pointer path does not itself own residency.\n\n## Race and failure checks\n\n- owner destroyed before completion;\n- two requests for the same asset with different consumers;\n- cancel after IO began but before callback;\n- partial bundle failure or missing cooked dependency;\n- async completion followed by synchronous resource creation hitch;\n- unload while a component/task/delegate still uses the asset;\n- stale callback applies content to a new state/level/character.\n\nUse a request generation/token and weak owner where appropriate. Completion means “asset available,”\nnot automatically “gameplay-ready.”\n","searchText":"async loading and lifetime owned load sequence 1. gather soft paths or primary asset ids before the transition. 2. request through asset manager or fstreamablemanager::requestasyncload. 3. retain the fstreamablehandle when cancellation, progress, combined requests, or residency ownership matters. 4. on completion, verify request state and every required asset; callbacks may arrive after the caller's original state changed. 5. create/register render, physics, audio, and gameplay resources in a bounded readiness phase. 6. transfer assets into a hard owner for the exact use lifetime or keep the governing handle alive. 7. on cancellation/transition, stop dependent work, release owners/handles, and verify collection/eviction. fstreamablemanager keeps requested assets referenced through the completion delegate; afterward the caller must retain them if needed. a soft pointer path does not itself own residency. race and failure checks - owner destroyed before completion; - two requests for the same asset with different consumers; - cancel after io began but before callback; - partial bundle failure or missing cooked dependency; - async completion followed by synchronous resource creation hitch; - unload while a component/task/delegate still uses the asset; - stale callback applies content to a new state/level/character. use a request generation/token and weak owner where appropriate. completion means “asset available,” not automatically “gameplay-ready.”"},{"slug":"budgets-and-evidence","file":"budgets-and-evidence.md","title":"Budgets and evidence","rawMarkdown":"# Budgets and evidence\n\nRecord before analysis:\n\n| Dimension | Required context |\n|---|---|\n| Hardware | platform, RAM/VRAM/unified memory, storage, driver/OS |\n| Build | commit, configuration, cooked/PIE, device profile |\n| Workload | map, path, speed, camera, content counts, duration |\n| Cache state | cold process/OS/driver/DDC versus warmed state |\n| Budgets | peak/resident memory by pool, ready latency, hitch threshold, quality floor |\n| Capture | trace channels/stats, markers, start/end, sampling overhead |\n\nMeasure separately:\n\n- process/platform committed and resident memory;\n- engine/LLM allocation categories;\n- UObject/assets and retained ownership;\n- GPU resource allocations;\n- conventional texture streaming pool;\n- each virtual-texture physical pool and page-table memory;\n- Nanite streaming pool;\n- transient load/decompression/PSO compile peaks;\n- package/install size.\n\nDo not sum overlapping counters. Define whether each value is reserved, allocated, resident, wanted,\nbudgeted, or transient. Compare cold and warm runs when the player can experience both.\n","webMarkdown":"Record before analysis:\n\n| Dimension | Required context |\n|---|---|\n| Hardware | platform, RAM/VRAM/unified memory, storage, driver/OS |\n| Build | commit, configuration, cooked/PIE, device profile |\n| Workload | map, path, speed, camera, content counts, duration |\n| Cache state | cold process/OS/driver/DDC versus warmed state |\n| Budgets | peak/resident memory by pool, ready latency, hitch threshold, quality floor |\n| Capture | trace channels/stats, markers, start/end, sampling overhead |\n\nMeasure separately:\n\n- process/platform committed and resident memory;\n- engine/LLM allocation categories;\n- UObject/assets and retained ownership;\n- GPU resource allocations;\n- conventional texture streaming pool;\n- each virtual-texture physical pool and page-table memory;\n- Nanite streaming pool;\n- transient load/decompression/PSO compile peaks;\n- package/install size.\n\nDo not sum overlapping counters. Define whether each value is reserved, allocated, resident, wanted,\nbudgeted, or transient. Compare cold and warm runs when the player can experience both.\n","searchText":"budgets and evidence record before analysis: | dimension | required context | |---|---| | hardware | platform, ram/vram/unified memory, storage, driver/os | | build | commit, configuration, cooked/pie, device profile | | workload | map, path, speed, camera, content counts, duration | | cache state | cold process/os/driver/ddc versus warmed state | | budgets | peak/resident memory by pool, ready latency, hitch threshold, quality floor | | capture | trace channels/stats, markers, start/end, sampling overhead | measure separately: - process/platform committed and resident memory; - engine/llm allocation categories; - uobject/assets and retained ownership; - gpu resource allocations; - conventional texture streaming pool; - each virtual-texture physical pool and page-table memory; - nanite streaming pool; - transient load/decompression/pso compile peaks; - package/install size. do not sum overlapping counters. define whether each value is reserved, allocated, resident, wanted, budgeted, or transient. compare cold and warm runs when the player can experience both."},{"slug":"geometry-and-world-readiness","file":"geometry-and-world-readiness.md","title":"Geometry and world readiness","rawMarkdown":"# Geometry and world readiness\n\n## Nanite\n\nNanite streams fine-grained geometry pages. `r.Nanite.Streaming.StreamingPoolSize` trades memory for\nfewer IO/decompression requests; too small a pool can thrash even in a static view. Use Nanite Streaming\nGeometry visualization and `NaniteStats` before changing it. Validate package/storage cost separately.\n\n## Conventional meshes and skeletal content\n\nPer-platform LODs reduce render cost and may reduce memory when higher LODs are stripped or excluded by\nplatform policy. Confirm which LOD/render resources are resident in Render Resource Viewer. Do not assume\nan unseen mesh releases while a component, asset, or streaming handle still owns it.\n\n## World Partition readiness\n\nWorld Partition cell loading is only one layer. Ready-to-enter must include:\n\n- required cell activated/loaded state;\n- collision and navigation ready;\n- required assets and bundles loaded;\n- texture/Nanite/VT quality above the declared floor;\n- render/physics components registered;\n- PSOs required for first visible use compiled;\n- gameplay initialization complete.\n\nDerive preload lead distance from maximum approach speed × worst measured readiness latency plus look-\nahead and safety margin. For teleports, use a temporary destination streaming source and wait on the\nWorld Partition subsystem, then apply the broader readiness gate. Avoid globally inflating loading range\nto solve one path; it raises residency and concurrent IO everywhere.\n","webMarkdown":"## Nanite\n\nNanite streams fine-grained geometry pages. `r.Nanite.Streaming.StreamingPoolSize` trades memory for\nfewer IO/decompression requests; too small a pool can thrash even in a static view. Use Nanite Streaming\nGeometry visualization and `NaniteStats` before changing it. Validate package/storage cost separately.\n\n## Conventional meshes and skeletal content\n\nPer-platform LODs reduce render cost and may reduce memory when higher LODs are stripped or excluded by\nplatform policy. Confirm which LOD/render resources are resident in Render Resource Viewer. Do not assume\nan unseen mesh releases while a component, asset, or streaming handle still owns it.\n\n## World Partition readiness\n\nWorld Partition cell loading is only one layer. Ready-to-enter must include:\n\n- required cell activated/loaded state;\n- collision and navigation ready;\n- required assets and bundles loaded;\n- texture/Nanite/VT quality above the declared floor;\n- render/physics components registered;\n- PSOs required for first visible use compiled;\n- gameplay initialization complete.\n\nDerive preload lead distance from maximum approach speed × worst measured readiness latency plus look-\nahead and safety margin. For teleports, use a temporary destination streaming source and wait on the\nWorld Partition subsystem, then apply the broader readiness gate. Avoid globally inflating loading range\nto solve one path; it raises residency and concurrent IO everywhere.\n","searchText":"geometry and world readiness nanite nanite streams fine-grained geometry pages. r.nanite.streaming.streamingpoolsize trades memory for fewer io/decompression requests; too small a pool can thrash even in a static view. use nanite streaming geometry visualization and nanitestats before changing it. validate package/storage cost separately. conventional meshes and skeletal content per-platform lods reduce render cost and may reduce memory when higher lods are stripped or excluded by platform policy. confirm which lod/render resources are resident in render resource viewer. do not assume an unseen mesh releases while a component, asset, or streaming handle still owns it. world partition readiness world partition cell loading is only one layer. ready-to-enter must include: - required cell activated/loaded state; - collision and navigation ready; - required assets and bundles loaded; - texture/nanite/vt quality above the declared floor; - render/physics components registered; - psos required for first visible use compiled; - gameplay initialization complete. derive preload lead distance from maximum approach speed × worst measured readiness latency plus look- ahead and safety margin. for teleports, use a temporary destination streaming source and wait on the world partition subsystem, then apply the broader readiness gate. avoid globally inflating loading range to solve one path; it raises residency and concurrent io everywhere."},{"slug":"load-hitch-diagnosis","file":"load-hitch-diagnosis.md","title":"Load and streaming hitch diagnosis","rawMarkdown":"# Load and streaming hitch diagnosis\n\n1. Mark the player action/region entry and capture Timing plus `loadtime`/`file` channels as needed.\n2. Inspect Asset Loading Insights package order, async priorities, serialization, and Game-thread waits.\n3. Correlate file IO, decompression, UObject creation, PostLoad, component registration, render/physics\n   resource creation, PSO compile, and GC.\n4. Determine whether work is synchronous, async but completed too late, or async followed by a blocking\n   readiness phase.\n5. Move/preload only the causal work, increase lead time, or amortize creation across frames.\n\n| Symptom | First evidence |\n|---|---|\n| first pickup/effect hitches | package load, component registration, PSO/decode readiness |\n| entering region hitches | World Partition/cell activation, file IO, texture/Nanite demand |\n| memory spike then GC hitch | transient allocations, object churn, retained load handles |\n| asset says loaded but appears late | render/physics resource or PSO readiness |\n| cold run hitches, warm run does not | OS/driver/cache-sensitive IO or compilation |\n| async request still stalls | late request, completion on critical path, sync dependency inside PostLoad |\n\nNever “fix” by hiding the trace interval behind a shorter loading screen. If blocking is required, own it\nwith a real loading transition and an explicit complete/timeout/failure contract.\n","webMarkdown":"1. Mark the player action/region entry and capture Timing plus `loadtime`/`file` channels as needed.\n2. Inspect Asset Loading Insights package order, async priorities, serialization, and Game-thread waits.\n3. Correlate file IO, decompression, UObject creation, PostLoad, component registration, render/physics\n   resource creation, PSO compile, and GC.\n4. Determine whether work is synchronous, async but completed too late, or async followed by a blocking\n   readiness phase.\n5. Move/preload only the causal work, increase lead time, or amortize creation across frames.\n\n| Symptom | First evidence |\n|---|---|\n| first pickup/effect hitches | package load, component registration, PSO/decode readiness |\n| entering region hitches | World Partition/cell activation, file IO, texture/Nanite demand |\n| memory spike then GC hitch | transient allocations, object churn, retained load handles |\n| asset says loaded but appears late | render/physics resource or PSO readiness |\n| cold run hitches, warm run does not | OS/driver/cache-sensitive IO or compilation |\n| async request still stalls | late request, completion on critical path, sync dependency inside PostLoad |\n\nNever “fix” by hiding the trace interval behind a shorter loading screen. If blocking is required, own it\nwith a real loading transition and an explicit complete/timeout/failure contract.\n","searchText":"load and streaming hitch diagnosis 1. mark the player action/region entry and capture timing plus loadtime/file channels as needed. 2. inspect asset loading insights package order, async priorities, serialization, and game-thread waits. 3. correlate file io, decompression, uobject creation, postload, component registration, render/physics resource creation, pso compile, and gc. 4. determine whether work is synchronous, async but completed too late, or async followed by a blocking readiness phase. 5. move/preload only the causal work, increase lead time, or amortize creation across frames. | symptom | first evidence | |---|---| | first pickup/effect hitches | package load, component registration, pso/decode readiness | | entering region hitches | world partition/cell activation, file io, texture/nanite demand | | memory spike then gc hitch | transient allocations, object churn, retained load handles | | asset says loaded but appears late | render/physics resource or pso readiness | | cold run hitches, warm run does not | os/driver/cache-sensitive io or compilation | | async request still stalls | late request, completion on critical path, sync dependency inside postload | never “fix” by hiding the trace interval behind a shorter loading screen. if blocking is required, own it with a real loading transition and an explicit complete/timeout/failure contract."},{"slug":"memory-profiling","file":"memory-profiling.md","title":"Memory profiling","rawMarkdown":"# Memory profiling\n\n## Memory Insights\n\nStart allocation tracing with the process:\n\n```text\nMyGame.exe -trace=default,memory\nMyGame.exe -trace=default,memory,metadata,assetmetadata\n```\n\nUse marked A/B timestamps to query allocations live at a point, retained across an action, freed during\nan interval, or monotonically growing across repetitions. Metadata improves asset/class attribution but\nincreases trace volume. Late connect cannot reconstruct allocations made before tracing began.\n\n## Low-Level Memory Tracker\n\nLaunch with `-LLM` for tagged totals or `-LLMCSV` for periodic CSV under `Saved/Profiling/LLM`.\nInspect `stat LLM`, `stat LLMFULL`, `stat LLMPlatform`, and `stat LLMOverhead` where available. Default\ntracker allocations are a subset of platform tracker totals; do not add them together.\n\nAsset/AssetClass tag sets are Experimental and add memory/runtime overhead. Use them only for targeted\ndiagnosis and record that overhead.\n\n## Interpretation\n\n- growth that stabilizes may be an intentional cache; prove its cap and eviction;\n- repeated retained growth after teardown suggests surviving ownership;\n- high alloc/free rate with stable total is churn, not a leak;\n- LLM category attribution and detailed allocation callstacks answer different questions;\n- GPU resources, driver memory, mapped files, and platform allocations may not equal UObject estimates.\n","webMarkdown":"## Memory Insights\n\nStart allocation tracing with the process:\n\n```text\nMyGame.exe -trace=default,memory\nMyGame.exe -trace=default,memory,metadata,assetmetadata\n```\n\nUse marked A/B timestamps to query allocations live at a point, retained across an action, freed during\nan interval, or monotonically growing across repetitions. Metadata improves asset/class attribution but\nincreases trace volume. Late connect cannot reconstruct allocations made before tracing began.\n\n## Low-Level Memory Tracker\n\nLaunch with `-LLM` for tagged totals or `-LLMCSV` for periodic CSV under `Saved/Profiling/LLM`.\nInspect `stat LLM`, `stat LLMFULL`, `stat LLMPlatform`, and `stat LLMOverhead` where available. Default\ntracker allocations are a subset of platform tracker totals; do not add them together.\n\nAsset/AssetClass tag sets are Experimental and add memory/runtime overhead. Use them only for targeted\ndiagnosis and record that overhead.\n\n## Interpretation\n\n- growth that stabilizes may be an intentional cache; prove its cap and eviction;\n- repeated retained growth after teardown suggests surviving ownership;\n- high alloc/free rate with stable total is churn, not a leak;\n- LLM category attribution and detailed allocation callstacks answer different questions;\n- GPU resources, driver memory, mapped files, and platform allocations may not equal UObject estimates.\n","searchText":"memory profiling memory insights start allocation tracing with the process: text mygame.exe -trace=default,memory mygame.exe -trace=default,memory,metadata,assetmetadata use marked a/b timestamps to query allocations live at a point, retained across an action, freed during an interval, or monotonically growing across repetitions. metadata improves asset/class attribution but increases trace volume. late connect cannot reconstruct allocations made before tracing began. low-level memory tracker launch with -llm for tagged totals or -llmcsv for periodic csv under saved/profiling/llm. inspect stat llm, stat llmfull, stat llmplatform, and stat llmoverhead where available. default tracker allocations are a subset of platform tracker totals; do not add them together. asset/assetclass tag sets are experimental and add memory/runtime overhead. use them only for targeted diagnosis and record that overhead. interpretation - growth that stabilizes may be an intentional cache; prove its cap and eviction; - repeated retained growth after teardown suggests surviving ownership; - high alloc/free rate with stable total is churn, not a leak; - llm category attribution and detailed allocation callstacks answer different questions; - gpu resources, driver memory, mapped files, and platform allocations may not equal uobject estimates."},{"slug":"pso-and-shader-hitches","file":"pso-and-shader-hitches.md","title":"PSO and shader compilation hitches","rawMarkdown":"# PSO and shader compilation hitches\n\nUE 5.8 enables PSO precaching where the RHI supports it. Component precaching gathers material, vertex-\nfactory, render-state, and mesh-pass PSOs after load and compiles asynchronously.\n\n## Validate\n\n1. Test a cooked Development build with an empty/cold driver cache on representative consumer CPU cores.\n2. Enable `r.PSOPrecache.Validation 1` for lightweight numbers or `2` for detailed miss logging.\n3. Inspect `stat PSOPrecache` and Shader Pipeline Cache runtime hitch statistics.\n4. Correlate first-visible hitch with PSO compilation rather than asset IO/registration.\n5. Wait during a loading screen until required outstanding compiles reach zero; use\n   `FShaderPipelineCache::NumPrecompilesRemaining()` for the governing check.\n\nIf a component's PSO is not ready, the proxy delay strategy can skip the draw or show default material;\nallowing the draw to block risks a hitch. Pick the visual/readiness policy explicitly.\n\n## Bundled cache boundary\n\nRuntime precaching should cover most cases. Add a manually recorded bundled graphics PSO cache when\nvalidation proves misses or unsupported collection paths remain. Record representative content on each\nplatform/RHI, merge/stabilize through the documented cook pipeline, ship the cache, and repeat cold-cache\nvalidation. Ray-tracing PSOs are not supported by the bundled-cache workflow documented for UE 5.8.\n\nDo not judge from a warm developer driver cache. New materials, vertex factories, passes, quality tiers,\nRHI changes, and content patches require renewed coverage.\n","webMarkdown":"UE 5.8 enables PSO precaching where the RHI supports it. Component precaching gathers material, vertex-\nfactory, render-state, and mesh-pass PSOs after load and compiles asynchronously.\n\n## Validate\n\n1. Test a cooked Development build with an empty/cold driver cache on representative consumer CPU cores.\n2. Enable `r.PSOPrecache.Validation 1` for lightweight numbers or `2` for detailed miss logging.\n3. Inspect `stat PSOPrecache` and Shader Pipeline Cache runtime hitch statistics.\n4. Correlate first-visible hitch with PSO compilation rather than asset IO/registration.\n5. Wait during a loading screen until required outstanding compiles reach zero; use\n   `FShaderPipelineCache::NumPrecompilesRemaining()` for the governing check.\n\nIf a component's PSO is not ready, the proxy delay strategy can skip the draw or show default material;\nallowing the draw to block risks a hitch. Pick the visual/readiness policy explicitly.\n\n## Bundled cache boundary\n\nRuntime precaching should cover most cases. Add a manually recorded bundled graphics PSO cache when\nvalidation proves misses or unsupported collection paths remain. Record representative content on each\nplatform/RHI, merge/stabilize through the documented cook pipeline, ship the cache, and repeat cold-cache\nvalidation. Ray-tracing PSOs are not supported by the bundled-cache workflow documented for UE 5.8.\n\nDo not judge from a warm developer driver cache. New materials, vertex factories, passes, quality tiers,\nRHI changes, and content patches require renewed coverage.\n","searchText":"pso and shader compilation hitches ue 5.8 enables pso precaching where the rhi supports it. component precaching gathers material, vertex- factory, render-state, and mesh-pass psos after load and compiles asynchronously. validate 1. test a cooked development build with an empty/cold driver cache on representative consumer cpu cores. 2. enable r.psoprecache.validation 1 for lightweight numbers or 2 for detailed miss logging. 3. inspect stat psoprecache and shader pipeline cache runtime hitch statistics. 4. correlate first-visible hitch with pso compilation rather than asset io/registration. 5. wait during a loading screen until required outstanding compiles reach zero; use fshaderpipelinecache::numprecompilesremaining() for the governing check. if a component's pso is not ready, the proxy delay strategy can skip the draw or show default material; allowing the draw to block risks a hitch. pick the visual/readiness policy explicitly. bundled cache boundary runtime precaching should cover most cases. add a manually recorded bundled graphics pso cache when validation proves misses or unsupported collection paths remain. record representative content on each platform/rhi, merge/stabilize through the documented cook pipeline, ship the cache, and repeat cold-cache validation. ray-tracing psos are not supported by the bundled-cache workflow documented for ue 5.8. do not judge from a warm developer driver cache. new materials, vertex factories, passes, quality tiers, rhi changes, and content patches require renewed coverage."},{"slug":"reference-graphs-and-residency","file":"reference-graphs-and-residency.md","title":"Reference graphs and residency","rawMarkdown":"# Reference graphs and residency\n\n## Audit an unexpected load\n\n1. Select the suspect asset and open Reference Viewer.\n2. Inspect referencers, dependencies, hard/soft edges, management references, and Reference Tree depth.\n3. Open Size Map for the asset and its dependencies; use Asset Audit for class/type/cooked-size detail.\n4. Confirm the runtime owner with Memory Insights/LLM; editor graph size is not runtime residency proof.\n5. Identify the earliest hard edge that crosses the intended residency boundary.\n6. Convert only that boundary to a soft/Primary Asset load contract, then prove cook and lifetime.\n\nUse a hard reference when owner and target must always be resident together. Use `TSoftObjectPtr`,\n`TSoftClassPtr`, or `FSoftObjectPath` when the dependency must load on demand. Use Primary Asset IDs and\nbundles when many callers need governed discovery and phase-specific residency.\n\nCommon accidental roots:\n\n- GameInstance/subsystem/default object references;\n- always-loaded maps, HUDs, GameModes, singletons, or Data Assets;\n- Blueprint class defaults that reference presentation-heavy classes;\n- arrays/catalogs holding hard class or asset pointers;\n- an async-loaded object copied into a long-lived hard owner;\n- delegates/tasks/components retaining the owner after expected teardown.\n\nReport the root and complete chain. Removing the leaf from memory without changing its surviving owner\ndoes not fix retention.\n","webMarkdown":"## Audit an unexpected load\n\n1. Select the suspect asset and open Reference Viewer.\n2. Inspect referencers, dependencies, hard/soft edges, management references, and Reference Tree depth.\n3. Open Size Map for the asset and its dependencies; use Asset Audit for class/type/cooked-size detail.\n4. Confirm the runtime owner with Memory Insights/LLM; editor graph size is not runtime residency proof.\n5. Identify the earliest hard edge that crosses the intended residency boundary.\n6. Convert only that boundary to a soft/Primary Asset load contract, then prove cook and lifetime.\n\nUse a hard reference when owner and target must always be resident together. Use `TSoftObjectPtr`,\n`TSoftClassPtr`, or `FSoftObjectPath` when the dependency must load on demand. Use Primary Asset IDs and\nbundles when many callers need governed discovery and phase-specific residency.\n\nCommon accidental roots:\n\n- GameInstance/subsystem/default object references;\n- always-loaded maps, HUDs, GameModes, singletons, or Data Assets;\n- Blueprint class defaults that reference presentation-heavy classes;\n- arrays/catalogs holding hard class or asset pointers;\n- an async-loaded object copied into a long-lived hard owner;\n- delegates/tasks/components retaining the owner after expected teardown.\n\nReport the root and complete chain. Removing the leaf from memory without changing its surviving owner\ndoes not fix retention.\n","searchText":"reference graphs and residency audit an unexpected load 1. select the suspect asset and open reference viewer. 2. inspect referencers, dependencies, hard/soft edges, management references, and reference tree depth. 3. open size map for the asset and its dependencies; use asset audit for class/type/cooked-size detail. 4. confirm the runtime owner with memory insights/llm; editor graph size is not runtime residency proof. 5. identify the earliest hard edge that crosses the intended residency boundary. 6. convert only that boundary to a soft/primary asset load contract, then prove cook and lifetime. use a hard reference when owner and target must always be resident together. use tsoftobjectptr, tsoftclassptr, or fsoftobjectpath when the dependency must load on demand. use primary asset ids and bundles when many callers need governed discovery and phase-specific residency. common accidental roots: - gameinstance/subsystem/default object references; - always-loaded maps, huds, gamemodes, singletons, or data assets; - blueprint class defaults that reference presentation-heavy classes; - arrays/catalogs holding hard class or asset pointers; - an async-loaded object copied into a long-lived hard owner; - delegates/tasks/components retaining the owner after expected teardown. report the root and complete chain. removing the leaf from memory without changing its surviving owner does not fix retention."},{"slug":"regression-and-recipes","file":"regression-and-recipes.md","title":"Regression and recipes","rawMarkdown":"# Regression and recipes\n\n## Regression record\n\n| Metric | Baseline | Candidate | Budget/result |\n|---|---:|---:|---|\n| peak process/platform memory | | | |\n| steady memory after traversal | | | |\n| texture/VT/Nanite pool pressure | | | |\n| ready latency / worst hitch ms | | | |\n| PSO misses/runtime compile hitches | | | |\n| visual quality/fallback result | | | |\n\nRun repeated cold and warm samples. Preserve device profile, build, route, speed, camera, content, and\ncache preparation. Reject wins that shift work past the capture, lower required quality, or break cook.\n\n## Symptom recipes\n\n| Symptom | Bounded experiment |\n|---|---|\n| opening one menu loads a level's content | Reference Viewer from widget/class default; soften first boundary |\n| textures stay blurry | build/inspect streaming data, then compare wanted versus budgeted mips |\n| texture pool over budget | identify valid demand/forced/non-streaming owners before pool or mip change |\n| VT tiles flicker | identify saturated format pool; A/B fixed pool size within VRAM budget |\n| static Nanite view keeps streaming | inspect pool thrash; A/B pool or resident demand |\n| repeated spawn/despawn grows RAM | marked Memory Insights retained-allocation query |\n| first material use hitches | cold PSO validation; wait/precache or cover documented misses |\n| teleport arrives into missing world | destination source plus complete readiness gate and timeout |\n","webMarkdown":"## Regression record\n\n| Metric | Baseline | Candidate | Budget/result |\n|---|---:|---:|---|\n| peak process/platform memory | | | |\n| steady memory after traversal | | | |\n| texture/VT/Nanite pool pressure | | | |\n| ready latency / worst hitch ms | | | |\n| PSO misses/runtime compile hitches | | | |\n| visual quality/fallback result | | | |\n\nRun repeated cold and warm samples. Preserve device profile, build, route, speed, camera, content, and\ncache preparation. Reject wins that shift work past the capture, lower required quality, or break cook.\n\n## Symptom recipes\n\n| Symptom | Bounded experiment |\n|---|---|\n| opening one menu loads a level's content | Reference Viewer from widget/class default; soften first boundary |\n| textures stay blurry | build/inspect streaming data, then compare wanted versus budgeted mips |\n| texture pool over budget | identify valid demand/forced/non-streaming owners before pool or mip change |\n| VT tiles flicker | identify saturated format pool; A/B fixed pool size within VRAM budget |\n| static Nanite view keeps streaming | inspect pool thrash; A/B pool or resident demand |\n| repeated spawn/despawn grows RAM | marked Memory Insights retained-allocation query |\n| first material use hitches | cold PSO validation; wait/precache or cover documented misses |\n| teleport arrives into missing world | destination source plus complete readiness gate and timeout |\n","searchText":"regression and recipes regression record | metric | baseline | candidate | budget/result | |---|---:|---:|---| | peak process/platform memory | | | | | steady memory after traversal | | | | | texture/vt/nanite pool pressure | | | | | ready latency / worst hitch ms | | | | | pso misses/runtime compile hitches | | | | | visual quality/fallback result | | | | run repeated cold and warm samples. preserve device profile, build, route, speed, camera, content, and cache preparation. reject wins that shift work past the capture, lower required quality, or break cook. symptom recipes | symptom | bounded experiment | |---|---| | opening one menu loads a level's content | reference viewer from widget/class default; soften first boundary | | textures stay blurry | build/inspect streaming data, then compare wanted versus budgeted mips | | texture pool over budget | identify valid demand/forced/non-streaming owners before pool or mip change | | vt tiles flicker | identify saturated format pool; a/b fixed pool size within vram budget | | static nanite view keeps streaming | inspect pool thrash; a/b pool or resident demand | | repeated spawn/despawn grows ram | marked memory insights retained-allocation query | | first material use hitches | cold pso validation; wait/precache or cover documented misses | | teleport arrives into missing world | destination source plus complete readiness gate and timeout |"},{"slug":"sources","file":"sources.md","title":"UE 5.8 primary sources","rawMarkdown":"# UE 5.8 primary sources\n\n- [Memory Insights](https://dev.epicgames.com/documentation/en-us/unreal-engine/memory-insights-in-unreal-engine)\n- [Low-Level Memory Tracker](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-the-low-level-memory-tracker-in-unreal-engine)\n- [Reference Viewer](https://dev.epicgames.com/documentation/en-us/unreal-engine/reference-viewer-in-unreal-engine)\n- [Asset Management](https://dev.epicgames.com/documentation/en-us/unreal-engine/asset-management-in-unreal-engine)\n- [Asynchronous Asset Loading](https://dev.epicgames.com/documentation/en-us/unreal-engine/asynchronous-asset-loading-in-unreal-engine)\n- [Texture Streaming Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/texture-streaming-overview-for-unreal-engine)\n- [Building Texture Streaming Data](https://dev.epicgames.com/documentation/en-us/unreal-engine/building-texture-streaming-data-in-unreal-engine)\n- [Texture Streaming Configuration](https://dev.epicgames.com/documentation/en-us/unreal-engine/texture-streaming-configuration-in-unreal-engine)\n- [Texture Streaming Metrics](https://dev.epicgames.com/documentation/en-us/unreal-engine/texture-streaming-metrics-in-unreal-engine)\n- [Streaming Virtual Texturing](https://dev.epicgames.com/documentation/en-us/unreal-engine/streaming-virtual-texturing-in-unreal-engine)\n- [Virtual Texture Memory Pools](https://dev.epicgames.com/documentation/en-us/unreal-engine/virtual-texture-memory-pools-in-unreal-engine)\n- [Runtime Virtual Texturing](https://dev.epicgames.com/documentation/en-us/unreal-engine/runtime-virtual-texturing-in-unreal-engine)\n- [PSO Precaching](https://dev.epicgames.com/documentation/en-us/unreal-engine/pso-precaching-for-unreal-engine)\n- [Creating a Bundled PSO Cache](https://dev.epicgames.com/documentation/en-us/unreal-engine/manually-creating-bundled-pso-caches-in-unreal-engine)\n- [Nanite Technical Details](https://dev.epicgames.com/documentation/en-us/unreal-engine/nanite-technical-details)\n\nPages were checked against UE 5.8 documentation on 2026-07-19. Reconfirm trace channels, pool semantics,\nplatform/RHI support, PSO workflow, defaults, and feature maturity after an engine upgrade.\n","webMarkdown":"- [Memory Insights](https://dev.epicgames.com/documentation/en-us/unreal-engine/memory-insights-in-unreal-engine)\n- [Low-Level Memory Tracker](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-the-low-level-memory-tracker-in-unreal-engine)\n- [Reference Viewer](https://dev.epicgames.com/documentation/en-us/unreal-engine/reference-viewer-in-unreal-engine)\n- [Asset Management](https://dev.epicgames.com/documentation/en-us/unreal-engine/asset-management-in-unreal-engine)\n- [Asynchronous Asset Loading](https://dev.epicgames.com/documentation/en-us/unreal-engine/asynchronous-asset-loading-in-unreal-engine)\n- [Texture Streaming Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/texture-streaming-overview-for-unreal-engine)\n- [Building Texture Streaming Data](https://dev.epicgames.com/documentation/en-us/unreal-engine/building-texture-streaming-data-in-unreal-engine)\n- [Texture Streaming Configuration](https://dev.epicgames.com/documentation/en-us/unreal-engine/texture-streaming-configuration-in-unreal-engine)\n- [Texture Streaming Metrics](https://dev.epicgames.com/documentation/en-us/unreal-engine/texture-streaming-metrics-in-unreal-engine)\n- [Streaming Virtual Texturing](https://dev.epicgames.com/documentation/en-us/unreal-engine/streaming-virtual-texturing-in-unreal-engine)\n- [Virtual Texture Memory Pools](https://dev.epicgames.com/documentation/en-us/unreal-engine/virtual-texture-memory-pools-in-unreal-engine)\n- [Runtime Virtual Texturing](https://dev.epicgames.com/documentation/en-us/unreal-engine/runtime-virtual-texturing-in-unreal-engine)\n- [PSO Precaching](https://dev.epicgames.com/documentation/en-us/unreal-engine/pso-precaching-for-unreal-engine)\n- [Creating a Bundled PSO Cache](https://dev.epicgames.com/documentation/en-us/unreal-engine/manually-creating-bundled-pso-caches-in-unreal-engine)\n- [Nanite Technical Details](https://dev.epicgames.com/documentation/en-us/unreal-engine/nanite-technical-details)\n\nPages were checked against UE 5.8 documentation on 2026-07-19. Reconfirm trace channels, pool semantics,\nplatform/RHI support, PSO workflow, defaults, and feature maturity after an engine upgrade.\n","searchText":"ue 5.8 primary sources - memory insights - low-level memory tracker - reference viewer - asset management - asynchronous asset loading - texture streaming overview - building texture streaming data - texture streaming configuration - texture streaming metrics - streaming virtual texturing - virtual texture memory pools - runtime virtual texturing - pso precaching - creating a bundled pso cache - nanite technical details pages were checked against ue 5.8 documentation on 2026-07-19. reconfirm trace channels, pool semantics, platform/rhi support, pso workflow, defaults, and feature maturity after an engine upgrade."},{"slug":"system-selector","file":"system-selector.md","title":"System selector","rawMarkdown":"# System selector\n\n| Question | Primary evidence/system |\n|---|---|\n| Why is this asset loaded? | Reference Viewer/Reference Tree, Asset Manager audit |\n| What owns retained CPU memory? | Memory Insights + LLM tags/callstacks |\n| What owns GPU memory? | Render Resource Viewer + platform/RHI metrics |\n| Why are textures blurry or thrashing? | `stat streaming`, texture accuracy/resolution views |\n| Why do virtual textures show low-res tiles? | VT pool stats/visualization and feedback/upload demand |\n| Why does entering a region hitch? | Asset Loading Insights, file/loadtime trace, World Partition evidence |\n| Why does first rendering hitch? | PSO precache validation and Shader Pipeline Cache hitch stats |\n| Why does geometry pop or stream forever? | Nanite stats/pool or World Partition readiness |\n| Why did memory grow after repeated action? | marked Memory Insights allocation query |\n\nDo not combine all streaming systems into one “pool.” Each has separate ownership, telemetry, eviction,\nand quality behavior.\n","webMarkdown":"| Question | Primary evidence/system |\n|---|---|\n| Why is this asset loaded? | Reference Viewer/Reference Tree, Asset Manager audit |\n| What owns retained CPU memory? | Memory Insights + LLM tags/callstacks |\n| What owns GPU memory? | Render Resource Viewer + platform/RHI metrics |\n| Why are textures blurry or thrashing? | `stat streaming`, texture accuracy/resolution views |\n| Why do virtual textures show low-res tiles? | VT pool stats/visualization and feedback/upload demand |\n| Why does entering a region hitch? | Asset Loading Insights, file/loadtime trace, World Partition evidence |\n| Why does first rendering hitch? | PSO precache validation and Shader Pipeline Cache hitch stats |\n| Why does geometry pop or stream forever? | Nanite stats/pool or World Partition readiness |\n| Why did memory grow after repeated action? | marked Memory Insights allocation query |\n\nDo not combine all streaming systems into one “pool.” Each has separate ownership, telemetry, eviction,\nand quality behavior.\n","searchText":"system selector | question | primary evidence/system | |---|---| | why is this asset loaded? | reference viewer/reference tree, asset manager audit | | what owns retained cpu memory? | memory insights + llm tags/callstacks | | what owns gpu memory? | render resource viewer + platform/rhi metrics | | why are textures blurry or thrashing? | stat streaming, texture accuracy/resolution views | | why do virtual textures show low-res tiles? | vt pool stats/visualization and feedback/upload demand | | why does entering a region hitch? | asset loading insights, file/loadtime trace, world partition evidence | | why does first rendering hitch? | pso precache validation and shader pipeline cache hitch stats | | why does geometry pop or stream forever? | nanite stats/pool or world partition readiness | | why did memory grow after repeated action? | marked memory insights allocation query | do not combine all streaming systems into one “pool.” each has separate ownership, telemetry, eviction, and quality behavior."},{"slug":"texture-streaming","file":"texture-streaming.md","title":"Texture streaming","rawMarkdown":"# Texture streaming\n\n## Diagnose before changing the pool\n\n1. Build texture streaming data: Build dropdown -> Build Texture Streaming.\n2. Use Primitive Distance, Mesh UV Density, Material Texture Scales, and Required Texture Resolution\n   accuracy/view modes to find bad bounds, UV density, scale analysis, or insufficient residency.\n3. Run `stat streaming` and record Texture, Streaming, Wanted, budget, over-budget, and update time.\n4. Reproduce the target camera path and distinguish temporary cached mips from sustained demand.\n\n## Controls\n\n| CVar | Effect/tradeoff |\n|---|---|\n| `r.Streaming.PoolSize` | texture-pool MB; larger reduces pressure but consumes target memory |\n| `r.Streaming.FramesForFullUpdate` | larger lowers streamer CPU work but reacts more slowly |\n| `r.Streaming.MaxTempMemoryAllowed` | more staging may improve throughput but raises transient memory |\n| `r.Streaming.MipBias` | larger bias reduces wanted resolution and quality |\n| `r.Streaming.UsePerTextureBias` | applies bias selectively to fit the pool rather than degrading every wanted mip |\n| `r.Streaming.LimitPoolSizeToVRAM` | caps pool against available GPU memory where supported |\n\n`r.TextureStreaming 0`, `r.Streaming.PoolSize 0`, `r.Streaming.UseAllMips`, and\n`r.Streaming.FullyLoadUsedTextures` are diagnostic/showcase controls, not default shipping fixes.\n\nFor a controlled wanted-resolution test, `r.Streaming.DropMips 2` removes cached/hidden mips so the\nRequired Texture Resolution view reflects visible demand; restore it before final measurement.\n\nFix stale material-instance streaming data, wrong mesh UV density, oversized bounds, forced residency,\nincorrect texture groups, and excessive source resolution before buying a larger pool.\n","webMarkdown":"## Diagnose before changing the pool\n\n1. Build texture streaming data: Build dropdown -> Build Texture Streaming.\n2. Use Primitive Distance, Mesh UV Density, Material Texture Scales, and Required Texture Resolution\n   accuracy/view modes to find bad bounds, UV density, scale analysis, or insufficient residency.\n3. Run `stat streaming` and record Texture, Streaming, Wanted, budget, over-budget, and update time.\n4. Reproduce the target camera path and distinguish temporary cached mips from sustained demand.\n\n## Controls\n\n| CVar | Effect/tradeoff |\n|---|---|\n| `r.Streaming.PoolSize` | texture-pool MB; larger reduces pressure but consumes target memory |\n| `r.Streaming.FramesForFullUpdate` | larger lowers streamer CPU work but reacts more slowly |\n| `r.Streaming.MaxTempMemoryAllowed` | more staging may improve throughput but raises transient memory |\n| `r.Streaming.MipBias` | larger bias reduces wanted resolution and quality |\n| `r.Streaming.UsePerTextureBias` | applies bias selectively to fit the pool rather than degrading every wanted mip |\n| `r.Streaming.LimitPoolSizeToVRAM` | caps pool against available GPU memory where supported |\n\n`r.TextureStreaming 0`, `r.Streaming.PoolSize 0`, `r.Streaming.UseAllMips`, and\n`r.Streaming.FullyLoadUsedTextures` are diagnostic/showcase controls, not default shipping fixes.\n\nFor a controlled wanted-resolution test, `r.Streaming.DropMips 2` removes cached/hidden mips so the\nRequired Texture Resolution view reflects visible demand; restore it before final measurement.\n\nFix stale material-instance streaming data, wrong mesh UV density, oversized bounds, forced residency,\nincorrect texture groups, and excessive source resolution before buying a larger pool.\n","searchText":"texture streaming diagnose before changing the pool 1. build texture streaming data: build dropdown -> build texture streaming. 2. use primitive distance, mesh uv density, material texture scales, and required texture resolution accuracy/view modes to find bad bounds, uv density, scale analysis, or insufficient residency. 3. run stat streaming and record texture, streaming, wanted, budget, over-budget, and update time. 4. reproduce the target camera path and distinguish temporary cached mips from sustained demand. controls | cvar | effect/tradeoff | |---|---| | r.streaming.poolsize | texture-pool mb; larger reduces pressure but consumes target memory | | r.streaming.framesforfullupdate | larger lowers streamer cpu work but reacts more slowly | | r.streaming.maxtempmemoryallowed | more staging may improve throughput but raises transient memory | | r.streaming.mipbias | larger bias reduces wanted resolution and quality | | r.streaming.usepertexturebias | applies bias selectively to fit the pool rather than degrading every wanted mip | | r.streaming.limitpoolsizetovram | caps pool against available gpu memory where supported | r.texturestreaming 0, r.streaming.poolsize 0, r.streaming.useallmips, and r.streaming.fullyloadusedtextures are diagnostic/showcase controls, not default shipping fixes. for a controlled wanted-resolution test, r.streaming.dropmips 2 removes cached/hidden mips so the required texture resolution view reflects visible demand; restore it before final measurement. fix stale material-instance streaming data, wrong mesh uv density, oversized bounds, forced residency, incorrect texture groups, and excessive source resolution before buying a larger pool."},{"slug":"virtual-texturing","file":"virtual-texturing.md","title":"Streaming and runtime virtual texturing","rawMarkdown":"# Streaming and runtime virtual texturing\n\nUse Streaming Virtual Texturing (SVT) for large cooked textures/UDIMs when tile-level residency beats\nwhole-mip streaming. Use Runtime Virtual Texturing (RVT) for GPU-generated/cacheable surface data such\nas landscape blending. Do not convert content solely because conventional texture streaming is poorly\nconfigured.\n\n## Physical pools\n\n- Page-table memory grows on demand and generally remains until all related content is released.\n- Each VT physical pool is a fixed-size LRU cache matched by format/tile configuration.\n- Configure serialized pools under Project Settings -> Engine -> Virtual Texture Pool.\n- Transient auto-grown pools exist only for the editor session; copy validated estimates into Fixed\n  Pools for cooked builds.\n- If visible tiles exceed a matching pool, continual eviction produces low-resolution/flickering tiles.\n\nUse `stat virtualtexturing` for update/upload cost and page-table counters; use\n`stat virtualtexturememory` for pool memory. Inspect each format/layer pool independently.\n\nLarger pools reduce eviction but permanently reserve more GPU memory. Increasing upload limits/feedback\nresolution can reduce latency while increasing CPU/GPU/upload work. Tune a repeatable traversal and test\ncamera cuts, fast motion, multiple views, and every device profile.\n\nRVT low mips for large worlds may require far-away actors to remain resident. Bake/stream low mips when\nthat trades runtime generation and residency for acceptable disk/streaming cost.\n","webMarkdown":"Use Streaming Virtual Texturing (SVT) for large cooked textures/UDIMs when tile-level residency beats\nwhole-mip streaming. Use Runtime Virtual Texturing (RVT) for GPU-generated/cacheable surface data such\nas landscape blending. Do not convert content solely because conventional texture streaming is poorly\nconfigured.\n\n## Physical pools\n\n- Page-table memory grows on demand and generally remains until all related content is released.\n- Each VT physical pool is a fixed-size LRU cache matched by format/tile configuration.\n- Configure serialized pools under Project Settings -> Engine -> Virtual Texture Pool.\n- Transient auto-grown pools exist only for the editor session; copy validated estimates into Fixed\n  Pools for cooked builds.\n- If visible tiles exceed a matching pool, continual eviction produces low-resolution/flickering tiles.\n\nUse `stat virtualtexturing` for update/upload cost and page-table counters; use\n`stat virtualtexturememory` for pool memory. Inspect each format/layer pool independently.\n\nLarger pools reduce eviction but permanently reserve more GPU memory. Increasing upload limits/feedback\nresolution can reduce latency while increasing CPU/GPU/upload work. Tune a repeatable traversal and test\ncamera cuts, fast motion, multiple views, and every device profile.\n\nRVT low mips for large worlds may require far-away actors to remain resident. Bake/stream low mips when\nthat trades runtime generation and residency for acceptable disk/streaming cost.\n","searchText":"streaming and runtime virtual texturing use streaming virtual texturing (svt) for large cooked textures/udims when tile-level residency beats whole-mip streaming. use runtime virtual texturing (rvt) for gpu-generated/cacheable surface data such as landscape blending. do not convert content solely because conventional texture streaming is poorly configured. physical pools - page-table memory grows on demand and generally remains until all related content is released. - each vt physical pool is a fixed-size lru cache matched by format/tile configuration. - configure serialized pools under project settings -> engine -> virtual texture pool. - transient auto-grown pools exist only for the editor session; copy validated estimates into fixed pools for cooked builds. - if visible tiles exceed a matching pool, continual eviction produces low-resolution/flickering tiles. use stat virtualtexturing for update/upload cost and page-table counters; use stat virtualtexturememory for pool memory. inspect each format/layer pool independently. larger pools reduce eviction but permanently reserve more gpu memory. increasing upload limits/feedback resolution can reduce latency while increasing cpu/gpu/upload work. tune a repeatable traversal and test camera cuts, fast motion, multiple views, and every device profile. rvt low mips for large worlds may require far-away actors to remain resident. bake/stream low mips when that trades runtime generation and residency for acceptable disk/streaming cost."}]}
{"slug":"unreal-metasounds","name":"unreal-metasounds","title":"Unreal 5.8 MetaSounds","description":"Design, parameterize, vary, mix, optimize, and debug procedural audio in Unreal Engine 5.8. Use for MetaSound Sources, Patches, Presets, graph Inputs and Triggers, runtime Audio Component parameters, random variation, sample playback, procedural synthesis, music timing, Quartz, Audio Modulation, Control Buses, attenuation and spatialization, interfaces, concurrency, looping sounds, output watching, Builder API, or silent/clicking/expensive audio.","shortDescription":"Build and debug procedural game audio","category":"Presentation","referenceCount":10,"rawMarkdown":"---\nname: unreal-metasounds\ndescription: Design, parameterize, vary, mix, optimize, and debug procedural audio in Unreal Engine 5.8. Use for MetaSound Sources, Patches, Presets, graph Inputs and Triggers, runtime Audio Component parameters, random variation, sample playback, procedural synthesis, music timing, Quartz, Audio Modulation, Control Buses, attenuation and spatialization, interfaces, concurrency, looping sounds, output watching, Builder API, or silent/clicking/expensive audio.\n---\n\n# Unreal 5.8 MetaSounds\n\n## Select the audio layer first\n\nRead [`references/system-selector.md`](references/system-selector.md).\n\n- One playable procedural/parameterized sound -> MetaSound Source.\n- Reusable graph behavior inside other MetaSounds -> Patch.\n- Same graph with different default inputs -> Preset.\n- Cross-category volume/filter/pitch control -> Audio Modulation/Control Buses.\n- Sample-accurate musical scheduling -> Quartz plus MetaSound where needed.\n- Fixed simple one-shot -> Sound Wave or simple source may be enough.\n\nKeep gameplay authority outside the audio graph. MetaSound consumes events and parameters to render\nfeedback; it does not decide whether a hit, purchase, cooldown, or state transition is valid.\n\n## Execute\n\n1. Define the sound's informational job, duration, spatial context, variation, and mix priority.\n2. Choose Source, Patch, Preset, or a simpler asset and define the public input/output interface.\n3. Build a minimum audible signal path and correct one-shot or indefinite lifetime.\n4. Add deterministic/random variation, envelopes, filters, synthesis, or layering in bounded stages.\n5. Drive runtime changes through MetaSound Inputs/Triggers on the playing Audio Component.\n6. Configure attenuation, spatialization, concurrency, sound class/submix, and modulation routing.\n7. Test repeated triggering, virtualization/lifecycle, listener distance, and worst-case voice counts.\n8. Profile audio/render-thread cost and the complete mix during representative gameplay.\n\nLoad only what applies:\n\n- [`references/assets-and-graph-contract.md`](references/assets-and-graph-contract.md)\n- [`references/runtime-parameters-and-events.md`](references/runtime-parameters-and-events.md)\n- [`references/variation-and-recipes.md`](references/variation-and-recipes.md)\n- [`references/spatialization-lifetime-and-concurrency.md`](references/spatialization-lifetime-and-concurrency.md)\n- [`references/modulation-mixing-and-quartz.md`](references/modulation-mixing-and-quartz.md)\n- [`references/presets-patches-and-interfaces.md`](references/presets-patches-and-interfaces.md)\n- [`references/builder-api-and-output-watch.md`](references/builder-api-and-output-watch.md)\n- [`references/debugging-and-performance.md`](references/debugging-and-performance.md)\n\n## Required answer format\n\nReturn:\n\n1. **Sound's gameplay/readability job** and chosen asset architecture.\n2. **Input/output/trigger interface**, units, defaults, and ownership.\n3. **Graph signal/control flow in evaluation order**.\n4. **Variation rules and deterministic requirements**.\n5. **Lifetime, concurrency, attenuation, spatialization, class/submix, and modulation settings**.\n6. **Network/cosmetic, accessibility, and performance consequences**.\n7. **Audition, debug, and mix acceptance checks**.\n\n## Hard rules\n\n- Only a MetaSound Source is directly playable; Patches encapsulate reusable graph behavior.\n- Use Presets for inherited graphs with overridden default Inputs; do not duplicate the graph.\n- Use Inputs for values that change during playback. MetaSound Variables are graph-internal, cannot\n  be accessed from Blueprint, and do not register external playback-time changes.\n- Set runtime parameters on the Audio Component before Play when the first audio block depends on them.\n- Keep `UE.Source.OneShot` and its `On Finished` contract for finite sounds; remove it from indefinite sounds.\n- Remove DC, avoid discontinuous waveform jumps, and bound gain before output.\n- Define concurrency and cleanup for every repeatedly triggered or looping source.\n- Use Audio Modulation for shared mix state; do not update every MetaSound instance each frame.\n- Critical gameplay information must have a non-audio equivalent and survive mix/accessibility settings.\n- Profile at realistic simultaneous voice counts; graph complexity alone is not the final cost.\n\nSee [`references/sources.md`](references/sources.md) for the UE 5.8 source trail.\n","webMarkdown":"## Select the audio layer first\n\nRead [`references/system-selector.md`](/unreal/unreal-metasounds/system-selector/).\n\n- One playable procedural/parameterized sound -> MetaSound Source.\n- Reusable graph behavior inside other MetaSounds -> Patch.\n- Same graph with different default inputs -> Preset.\n- Cross-category volume/filter/pitch control -> Audio Modulation/Control Buses.\n- Sample-accurate musical scheduling -> Quartz plus MetaSound where needed.\n- Fixed simple one-shot -> Sound Wave or simple source may be enough.\n\nKeep gameplay authority outside the audio graph. MetaSound consumes events and parameters to render\nfeedback; it does not decide whether a hit, purchase, cooldown, or state transition is valid.\n\n## Execute\n\n1. Define the sound's informational job, duration, spatial context, variation, and mix priority.\n2. Choose Source, Patch, Preset, or a simpler asset and define the public input/output interface.\n3. Build a minimum audible signal path and correct one-shot or indefinite lifetime.\n4. Add deterministic/random variation, envelopes, filters, synthesis, or layering in bounded stages.\n5. Drive runtime changes through MetaSound Inputs/Triggers on the playing Audio Component.\n6. Configure attenuation, spatialization, concurrency, sound class/submix, and modulation routing.\n7. Test repeated triggering, virtualization/lifecycle, listener distance, and worst-case voice counts.\n8. Profile audio/render-thread cost and the complete mix during representative gameplay.\n\nLoad only what applies:\n\n- [`references/assets-and-graph-contract.md`](/unreal/unreal-metasounds/assets-and-graph-contract/)\n- [`references/runtime-parameters-and-events.md`](/unreal/unreal-metasounds/runtime-parameters-and-events/)\n- [`references/variation-and-recipes.md`](/unreal/unreal-metasounds/variation-and-recipes/)\n- [`references/spatialization-lifetime-and-concurrency.md`](/unreal/unreal-metasounds/spatialization-lifetime-and-concurrency/)\n- [`references/modulation-mixing-and-quartz.md`](/unreal/unreal-metasounds/modulation-mixing-and-quartz/)\n- [`references/presets-patches-and-interfaces.md`](/unreal/unreal-metasounds/presets-patches-and-interfaces/)\n- [`references/builder-api-and-output-watch.md`](/unreal/unreal-metasounds/builder-api-and-output-watch/)\n- [`references/debugging-and-performance.md`](/unreal/unreal-metasounds/debugging-and-performance/)\n\n## Required answer format\n\nReturn:\n\n1. **Sound's gameplay/readability job** and chosen asset architecture.\n2. **Input/output/trigger interface**, units, defaults, and ownership.\n3. **Graph signal/control flow in evaluation order**.\n4. **Variation rules and deterministic requirements**.\n5. **Lifetime, concurrency, attenuation, spatialization, class/submix, and modulation settings**.\n6. **Network/cosmetic, accessibility, and performance consequences**.\n7. **Audition, debug, and mix acceptance checks**.\n\n## Hard rules\n\n- Only a MetaSound Source is directly playable; Patches encapsulate reusable graph behavior.\n- Use Presets for inherited graphs with overridden default Inputs; do not duplicate the graph.\n- Use Inputs for values that change during playback. MetaSound Variables are graph-internal, cannot\n  be accessed from Blueprint, and do not register external playback-time changes.\n- Set runtime parameters on the Audio Component before Play when the first audio block depends on them.\n- Keep `UE.Source.OneShot` and its `On Finished` contract for finite sounds; remove it from indefinite sounds.\n- Remove DC, avoid discontinuous waveform jumps, and bound gain before output.\n- Define concurrency and cleanup for every repeatedly triggered or looping source.\n- Use Audio Modulation for shared mix state; do not update every MetaSound instance each frame.\n- Critical gameplay information must have a non-audio equivalent and survive mix/accessibility settings.\n- Profile at realistic simultaneous voice counts; graph complexity alone is not the final cost.\n\nSee [`references/sources.md`](/unreal/unreal-metasounds/sources/) for the UE 5.8 source trail.\n","searchText":"unreal 5.8 metasounds design, parameterize, vary, mix, optimize, and debug procedural audio in unreal engine 5.8. use for metasound sources, patches, presets, graph inputs and triggers, runtime audio component parameters, random variation, sample playback, procedural synthesis, music timing, quartz, audio modulation, control buses, attenuation and spatialization, interfaces, concurrency, looping sounds, output watching, builder api, or silent/clicking/expensive audio. assets and graph contract assets and graph contract create a source via content browser -> add -> audio -> metasound source and a patch via audio -> metasounds -> metasound patch. a source produces playable audio; a patch must be embedded in a source or another metasound. minimum source 1. choose mono/stereo/output format deliberately. 2. route wave player or synthesis output through gain/envelope/filter stages to audio output. 3. expose semantic inputs and triggers in the members panel. 4. for a finite sound, keep ue.source.oneshot and connect the terminal trigger to on finished. 5. for an indefinite loop/sustain, remove the one-shot interface and define external stop/fade cleanup. 6. audition with extreme public-input values before composing into gameplay. metasound is a flow graph, not a blueprint execution graph. audio-rate signals, block/control-rate values, and triggers have different timing semantics. keep pin types/units explicit. public contract name inputs by meaning and unit: impactstrength01, speedcmpersec, surfacetype, release, pitchsemitones. clamp/map raw gameplay values once at the boundary. provide defaults that render a safe, audible result if the caller omits an optional input. do not expose implementation knobs merely because nodes have pins. public inputs should represent stable design controls; internal constants and variables remain graph details. builder api and output watching builder api and output watching builder api use the metasound builder subsystem for runtime/editor creation and mutation of transient sources or patches. use the metasound editor subsystem for editor-only asset creation/serialization workflows. prefer authored assets unless dynamic graph topology is a real requirement. builder handles identify graph nodes/pins but may change when documents rebuild/version. never serialize them as durable identity. define ownership of transient builders, audition/live-update state, dependency loading, and teardown. validate generated graphs before playback/export. output watching watch output can observe supported source outputs—float, int32, bool, time, string, and trigger—while the source is playing. patch outputs cannot be watched directly. the delegate can fire for every output update, including multiple updates within a frame. use watched outputs for presentation/analysis callbacks, not audio-thread authority over gameplay. throttle or aggregate high-rate outputs before expensive game-thread work. for envelope data, watch the audio output with epic's envelope follower analyzer identifiers. failure gates: - no callback -> source not playing, wrong exact output/analyzer name, unsupported type, or patch; - excessive callbacks -> output updates multiple times per frame; - stale builder handle -> graph rebuilt/versioned; - live changes absent -> not auditioning with supported live updates or wrong builder instance. debugging and performance debugging and performance symptom matrix | symptom | inspect first | |---|---| | silent | source playing, audio output route, gain/envelope, one-shot finish timing | | stops immediately | on finished triggered early or one-shot interface on indefinite graph | | never stops | missing finish/release or owner cleanup | | runtime value ignored | using variable instead of input, wrong name/type/component, constructor pin | | click/pop | waveform/gain discontinuity, no release, abrupt stop, dc | | repeats audibly | random pool/history/seed and concurrency stealing | | wrong distance/direction | attenuation/spatialization asset/interface and listener | | mix parameter ignored | modulation routing/activation/proxy update | | hitches on first play | asset/stream/decode/graph readiness and packaged behavior | | audio overload | voice count, per-source graph/dsp, sample rate, effects/submix cost | isolation ladder 1. audition one source with constant values and a minimal signal path. 2. watch meters/output and verify envelope/lifetime. 3. add graph stages one at a time. 4. test through the exact gameplay audio component and parameter order. 5. add attenuation, concurrency, modulation, class, and submix routing individually. 6. reproduce maximum simultaneous voices and full mix on target hardware. 7. use audio diagnostics/insights and mix matrix debugger where applicable. measure audio-render thread, source/voice count, underruns, streaming/decode, effects/submixes, and game-thread parameter traffic. reduce voice count and redundant graph work before degrading the cue that carries critical information. audio modulation, mixing, and quartz audio modulation, mixing, and quartz audio modulation enable the audio modulation plugin when shared dynamic mix control is needed. build: 1. modulation parameters with defined unit/normalized mapping. 2. control buses for categories such as master, music, sfx, dialogue, ambience, or accessibility. 3. control bus mixes for gameplay/menu/state profiles. 4. modulation destinations on metasound sources, sound classes, components, submixes, or effects. 5. blueprint/c++ activation/update/clear ownership and debugging. routing can disable, inherit, override, or union at supported destinations. sound class hierarchy is not automatically equivalent to modulation routing; assign required buses deliberately. when an api edits only the uobject representation, use the appropriate update call to push it to the audio-thread proxy. use metasound get modulator value/mix modulators when the graph must react to a bus. modulation is block-rate, not sample-rate. use graph/audio-rate signals for true audio-rate modulation. mix hierarchy protect critical cues through class/submix routing, concurrency priority, headroom, ducking, and state mixes. test the whole combat/ambience/music/dialogue mix, not soloed assets. provide category volume controls and non-audio equivalents for critical signals. quartz use quartz clocks for beat/bar/subdivision-aligned scheduling. keep transport/clock ownership stable, schedule sufficiently ahead for the audio renderer, and define pause, tempo change, world transition, and late-event behavior. metasound produces/varies sound; quartz owns musical-time scheduling. presets, patches, and interfaces presets, patches, and interfaces patch extract a patch when the same bounded dsp/control behavior is reused: randomized wave choice, envelope mapping, surface selection, filter chain, or musical utility. document every pin, unit, default, and timing assumption. changes propagate to containing graphs; test representative callers. preset right-click a source/patch -> create metasound preset. a preset inherits a read-only graph and overrides selected default inputs. parent changes propagate. use presets for variants sharing the same behavior contract; convert from preset only when the graph must diverge. constructor-pin status cannot be overridden on presets. interfaces interfaces supply standardized inputs/outputs connecting metasounds to audio-engine systems: - ue.source.oneshot: on finished for finite source lifetime. - ue.attenuation: listener distance input. - ue.spatialization: azimuth/elevation inputs. add/remove interfaces in the metasound interfaces panel. do not retain oneshot on indefinite sources. treat interface changes like an api migration because dependent graphs/callers may rely on members. use templates only when repeated asset construction and curated designer controls justify the extra framework. for a small graph, a normal source/patch/preset is clearer. runtime parameters and events runtime parameters and events spawned/owned audio component 1. create or spawn an audio component with the metasound source assigned. 2. set all first-block-critical parameters before calling play. 3. send later values through matching audio component parameter setters. 4. send trigger inputs for discrete audio events such as release, reroll, or next layer. 5. retain component ownership when later updates/stops are required. 6. stop/fade and release the component on owner destruction, state exit, or cancellation. parameter names and types must exactly match graph inputs. if a value appears ignored, confirm the component is the playing instance, the input is not a constructor-only pin, and a later graph node is not overwriting/masking it. variables are not runtime api metasound variables support internal get/set flow. they cannot be accessed by blueprint, and changing them externally while a sound plays is not the live-control path. use inputs for caller-driven state. use get delayed variable only when a one-block delay is intentional, commonly to break a graph cycle. network boundary replicate the compact gameplay event/state when other machines need to hear it, then create/update local audio components. do not replicate dsp samples or every modulation value. define whether a one-shot may be dropped, whether a loop must reconstruct for late relevance, and whether predicted audio must be cancelled or deduplicated after server response. ue 5.8 primary sources ue 5.8 primary sources - metasounds overview - metasounds reference guide - metasound plugin api - metasound builder api - metasound pages - metasound templates quick start - audio modulation overview - audio modulation quick start - audio modulation reference - quartz overview - quartz quick start pages were checked against the ue 5.8 documentation on 2026-07-19. reconfirm interfaces, builder api, template behavior, parameter timing, and modulation routing after an engine upgrade. spatialization, lifetime, and concurrency spatialization, lifetime, and concurrency metasound generates a source; standard unreal audio systems still own attenuation, spatialization, occlusion, classes, submixes, concurrency, priority, and virtualization. spatial contract - use attenuation assets/settings for distance curves, shape, spatialization, air absorption, occlusion, and focus according to the game. - add ue.attenuation when graph behavior needs listener distance. - add ue.spatialization when graph behavior needs azimuth/elevation. - test listener motion, split screen if supported, occlusion transitions, and teleport/discontinuity. do not synthesize manual left/right panning as a substitute for the engine spatializer when true 3d audio is required. lifetime - finite source: terminal trigger -> on finished; component auto-destroy/pool policy verified. - indefinite source: no one-shot interface; external owner controls release/stop. - looping wave player: graph/source must still define when the overall sound ends. - virtualized source: define whether time advances silently or restarts when audible. concurrency group semantically interchangeable voices and choose maximum count/resolution rule by information priority. test bursts, nearby identical sources, quiet-loop accumulation, and modulation interaction. concurrency voice stealing is a mix/design decision: never allow a low-value decorative sound to steal a critical warning merely because it started later. system selector system selector | need | prefer | verify | |---|---|---| | playable generated/processed source | metasound source | output format, lifetime, concurrency | | reused dsp/control subgraph | metasound patch | documented pins and propagation risk | | variants of one graph | metasound preset | inherited defaults, constructor pins | | simple fixed sample | sound wave/simple playback | no procedural complexity required | | category/world mix state | audio modulation + control buses | routing, activation, unit conversion | | beat/bar scheduling | quartz | clock ownership, latency, quantization | | dynamic graph construction | builder api | lifecycle, handles, asset/runtime boundary | decision questions: 1. does the sound need runtime variation or parameter response? 2. is change per play, during playback, per category, or global? 3. must events be sample-accurate or merely frame-aligned? 4. is the source finite, looping, sustained, or procedurally terminated? 5. how many voices can coexist and which may be stolen/virtualized? use the simplest layer that owns the requirement. metasound handles per-source generation; audio modulation handles shared mix control; gameplay provides semantic events/state. variation and recipes variation and recipes impact/weapon one-shot input surface/material category, normalized magnitude, and optional seed. select from a curated wave array, avoid immediate repetition, map magnitude to bounded gain/pitch/filter/transient layers, apply a short envelope, then finish explicitly. keep hit validation in gameplay. footsteps select material-aware sample sets, randomize within narrow authored bounds, and optionally scale by speed/weight. concurrency should prevent impossible stacking. treat footsteps as feedback: preserve distinguishability from ambience and pair critical enemy cues with visual/accessibility alternatives. engine/machine loop maintain an owned indefinite source. map normalized rpm/load to crossfade, pitch, filtering, and layers; smooth control changes. separate start, sustain, and stop/release behavior. stop/fade on owner shutdown and test virtualization/re-entry. adaptive ambience use independent bounded layers with randomized intervals and controlled density. drive broad state via modulation or infrequent parameters rather than per-frame updates to every voice. preserve silence and headroom; random does not mean unbounded simultaneous playback. procedural tone/ui oscillator -> envelope -> filter/gain -> output. start/end at zero amplitude and avoid instantaneous frequency/gain jumps to prevent clicks. limit spectrum and loudness across headphones/speakers. for deterministic replays or synchronized musical structure, own and pass a seed/clock deliberately. for ordinary cosmetic variation, exact cross-client random identity is usually unnecessary.","references":[{"slug":"assets-and-graph-contract","file":"assets-and-graph-contract.md","title":"Assets and graph contract","rawMarkdown":"# Assets and graph contract\n\nCreate a Source via Content Browser -> Add -> Audio -> MetaSound Source and a Patch via Audio ->\nMetaSounds -> MetaSound Patch. A Source produces playable audio; a Patch must be embedded in a Source\nor another MetaSound.\n\n## Minimum Source\n\n1. Choose mono/stereo/output format deliberately.\n2. Route Wave Player or synthesis output through gain/envelope/filter stages to Audio Output.\n3. Expose semantic Inputs and Triggers in the Members panel.\n4. For a finite sound, keep `UE.Source.OneShot` and connect the terminal trigger to `On Finished`.\n5. For an indefinite loop/sustain, remove the one-shot interface and define external stop/fade cleanup.\n6. Audition with extreme public-input values before composing into gameplay.\n\nMetaSound is a flow graph, not a Blueprint execution graph. Audio-rate signals, block/control-rate\nvalues, and Triggers have different timing semantics. Keep pin types/units explicit.\n\n## Public contract\n\nName Inputs by meaning and unit: `ImpactStrength01`, `SpeedCmPerSec`, `SurfaceType`, `Release`,\n`PitchSemitones`. Clamp/map raw gameplay values once at the boundary. Provide defaults that render a\nsafe, audible result if the caller omits an optional input.\n\nDo not expose implementation knobs merely because nodes have pins. Public inputs should represent\nstable design controls; internal constants and Variables remain graph details.\n","webMarkdown":"Create a Source via Content Browser -> Add -> Audio -> MetaSound Source and a Patch via Audio ->\nMetaSounds -> MetaSound Patch. A Source produces playable audio; a Patch must be embedded in a Source\nor another MetaSound.\n\n## Minimum Source\n\n1. Choose mono/stereo/output format deliberately.\n2. Route Wave Player or synthesis output through gain/envelope/filter stages to Audio Output.\n3. Expose semantic Inputs and Triggers in the Members panel.\n4. For a finite sound, keep `UE.Source.OneShot` and connect the terminal trigger to `On Finished`.\n5. For an indefinite loop/sustain, remove the one-shot interface and define external stop/fade cleanup.\n6. Audition with extreme public-input values before composing into gameplay.\n\nMetaSound is a flow graph, not a Blueprint execution graph. Audio-rate signals, block/control-rate\nvalues, and Triggers have different timing semantics. Keep pin types/units explicit.\n\n## Public contract\n\nName Inputs by meaning and unit: `ImpactStrength01`, `SpeedCmPerSec`, `SurfaceType`, `Release`,\n`PitchSemitones`. Clamp/map raw gameplay values once at the boundary. Provide defaults that render a\nsafe, audible result if the caller omits an optional input.\n\nDo not expose implementation knobs merely because nodes have pins. Public inputs should represent\nstable design controls; internal constants and Variables remain graph details.\n","searchText":"assets and graph contract create a source via content browser -> add -> audio -> metasound source and a patch via audio -> metasounds -> metasound patch. a source produces playable audio; a patch must be embedded in a source or another metasound. minimum source 1. choose mono/stereo/output format deliberately. 2. route wave player or synthesis output through gain/envelope/filter stages to audio output. 3. expose semantic inputs and triggers in the members panel. 4. for a finite sound, keep ue.source.oneshot and connect the terminal trigger to on finished. 5. for an indefinite loop/sustain, remove the one-shot interface and define external stop/fade cleanup. 6. audition with extreme public-input values before composing into gameplay. metasound is a flow graph, not a blueprint execution graph. audio-rate signals, block/control-rate values, and triggers have different timing semantics. keep pin types/units explicit. public contract name inputs by meaning and unit: impactstrength01, speedcmpersec, surfacetype, release, pitchsemitones. clamp/map raw gameplay values once at the boundary. provide defaults that render a safe, audible result if the caller omits an optional input. do not expose implementation knobs merely because nodes have pins. public inputs should represent stable design controls; internal constants and variables remain graph details."},{"slug":"builder-api-and-output-watch","file":"builder-api-and-output-watch.md","title":"Builder API and output watching","rawMarkdown":"# Builder API and output watching\n\n## Builder API\n\nUse the MetaSound Builder Subsystem for runtime/editor creation and mutation of transient Sources or\nPatches. Use the MetaSound Editor Subsystem for editor-only asset creation/serialization workflows.\nPrefer authored assets unless dynamic graph topology is a real requirement.\n\nBuilder handles identify graph nodes/pins but may change when documents rebuild/version. Never\nserialize them as durable identity. Define ownership of transient builders, audition/live-update\nstate, dependency loading, and teardown. Validate generated graphs before playback/export.\n\n## Output watching\n\n`Watch Output` can observe supported Source Outputs—Float, Int32, Bool, Time, String, and Trigger—while\nthe Source is playing. Patch Outputs cannot be watched directly. The delegate can fire for every\noutput update, including multiple updates within a frame.\n\nUse watched outputs for presentation/analysis callbacks, not audio-thread authority over gameplay.\nThrottle or aggregate high-rate outputs before expensive game-thread work. For envelope data, watch\nthe Audio Output with Epic's Envelope Follower analyzer identifiers.\n\nFailure gates:\n\n- no callback -> Source not playing, wrong exact output/analyzer name, unsupported type, or Patch;\n- excessive callbacks -> output updates multiple times per frame;\n- stale builder handle -> graph rebuilt/versioned;\n- live changes absent -> not auditioning with supported Live Updates or wrong builder instance.\n","webMarkdown":"## Builder API\n\nUse the MetaSound Builder Subsystem for runtime/editor creation and mutation of transient Sources or\nPatches. Use the MetaSound Editor Subsystem for editor-only asset creation/serialization workflows.\nPrefer authored assets unless dynamic graph topology is a real requirement.\n\nBuilder handles identify graph nodes/pins but may change when documents rebuild/version. Never\nserialize them as durable identity. Define ownership of transient builders, audition/live-update\nstate, dependency loading, and teardown. Validate generated graphs before playback/export.\n\n## Output watching\n\n`Watch Output` can observe supported Source Outputs—Float, Int32, Bool, Time, String, and Trigger—while\nthe Source is playing. Patch Outputs cannot be watched directly. The delegate can fire for every\noutput update, including multiple updates within a frame.\n\nUse watched outputs for presentation/analysis callbacks, not audio-thread authority over gameplay.\nThrottle or aggregate high-rate outputs before expensive game-thread work. For envelope data, watch\nthe Audio Output with Epic's Envelope Follower analyzer identifiers.\n\nFailure gates:\n\n- no callback -> Source not playing, wrong exact output/analyzer name, unsupported type, or Patch;\n- excessive callbacks -> output updates multiple times per frame;\n- stale builder handle -> graph rebuilt/versioned;\n- live changes absent -> not auditioning with supported Live Updates or wrong builder instance.\n","searchText":"builder api and output watching builder api use the metasound builder subsystem for runtime/editor creation and mutation of transient sources or patches. use the metasound editor subsystem for editor-only asset creation/serialization workflows. prefer authored assets unless dynamic graph topology is a real requirement. builder handles identify graph nodes/pins but may change when documents rebuild/version. never serialize them as durable identity. define ownership of transient builders, audition/live-update state, dependency loading, and teardown. validate generated graphs before playback/export. output watching watch output can observe supported source outputs—float, int32, bool, time, string, and trigger—while the source is playing. patch outputs cannot be watched directly. the delegate can fire for every output update, including multiple updates within a frame. use watched outputs for presentation/analysis callbacks, not audio-thread authority over gameplay. throttle or aggregate high-rate outputs before expensive game-thread work. for envelope data, watch the audio output with epic's envelope follower analyzer identifiers. failure gates: - no callback -> source not playing, wrong exact output/analyzer name, unsupported type, or patch; - excessive callbacks -> output updates multiple times per frame; - stale builder handle -> graph rebuilt/versioned; - live changes absent -> not auditioning with supported live updates or wrong builder instance."},{"slug":"debugging-and-performance","file":"debugging-and-performance.md","title":"Debugging and performance","rawMarkdown":"# Debugging and performance\n\n## Symptom matrix\n\n| Symptom | Inspect first |\n|---|---|\n| Silent | source playing, audio output route, gain/envelope, one-shot finish timing |\n| Stops immediately | `On Finished` triggered early or one-shot interface on indefinite graph |\n| Never stops | missing finish/release or owner cleanup |\n| Runtime value ignored | using Variable instead of Input, wrong name/type/component, constructor pin |\n| Click/pop | waveform/gain discontinuity, no release, abrupt stop, DC |\n| Repeats audibly | random pool/history/seed and concurrency stealing |\n| Wrong distance/direction | attenuation/spatialization asset/interface and listener |\n| Mix parameter ignored | modulation routing/activation/proxy update |\n| Hitches on first play | asset/stream/decode/graph readiness and packaged behavior |\n| Audio overload | voice count, per-source graph/DSP, sample rate, effects/submix cost |\n\n## Isolation ladder\n\n1. Audition one Source with constant values and a minimal signal path.\n2. Watch meters/output and verify envelope/lifetime.\n3. Add graph stages one at a time.\n4. Test through the exact gameplay Audio Component and parameter order.\n5. Add attenuation, concurrency, modulation, class, and submix routing individually.\n6. Reproduce maximum simultaneous voices and full mix on target hardware.\n7. Use audio diagnostics/Insights and Mix Matrix Debugger where applicable.\n\nMeasure audio-render thread, source/voice count, underruns, streaming/decode, effects/submixes, and\ngame-thread parameter traffic. Reduce voice count and redundant graph work before degrading the cue\nthat carries critical information.\n","webMarkdown":"## Symptom matrix\n\n| Symptom | Inspect first |\n|---|---|\n| Silent | source playing, audio output route, gain/envelope, one-shot finish timing |\n| Stops immediately | `On Finished` triggered early or one-shot interface on indefinite graph |\n| Never stops | missing finish/release or owner cleanup |\n| Runtime value ignored | using Variable instead of Input, wrong name/type/component, constructor pin |\n| Click/pop | waveform/gain discontinuity, no release, abrupt stop, DC |\n| Repeats audibly | random pool/history/seed and concurrency stealing |\n| Wrong distance/direction | attenuation/spatialization asset/interface and listener |\n| Mix parameter ignored | modulation routing/activation/proxy update |\n| Hitches on first play | asset/stream/decode/graph readiness and packaged behavior |\n| Audio overload | voice count, per-source graph/DSP, sample rate, effects/submix cost |\n\n## Isolation ladder\n\n1. Audition one Source with constant values and a minimal signal path.\n2. Watch meters/output and verify envelope/lifetime.\n3. Add graph stages one at a time.\n4. Test through the exact gameplay Audio Component and parameter order.\n5. Add attenuation, concurrency, modulation, class, and submix routing individually.\n6. Reproduce maximum simultaneous voices and full mix on target hardware.\n7. Use audio diagnostics/Insights and Mix Matrix Debugger where applicable.\n\nMeasure audio-render thread, source/voice count, underruns, streaming/decode, effects/submixes, and\ngame-thread parameter traffic. Reduce voice count and redundant graph work before degrading the cue\nthat carries critical information.\n","searchText":"debugging and performance symptom matrix | symptom | inspect first | |---|---| | silent | source playing, audio output route, gain/envelope, one-shot finish timing | | stops immediately | on finished triggered early or one-shot interface on indefinite graph | | never stops | missing finish/release or owner cleanup | | runtime value ignored | using variable instead of input, wrong name/type/component, constructor pin | | click/pop | waveform/gain discontinuity, no release, abrupt stop, dc | | repeats audibly | random pool/history/seed and concurrency stealing | | wrong distance/direction | attenuation/spatialization asset/interface and listener | | mix parameter ignored | modulation routing/activation/proxy update | | hitches on first play | asset/stream/decode/graph readiness and packaged behavior | | audio overload | voice count, per-source graph/dsp, sample rate, effects/submix cost | isolation ladder 1. audition one source with constant values and a minimal signal path. 2. watch meters/output and verify envelope/lifetime. 3. add graph stages one at a time. 4. test through the exact gameplay audio component and parameter order. 5. add attenuation, concurrency, modulation, class, and submix routing individually. 6. reproduce maximum simultaneous voices and full mix on target hardware. 7. use audio diagnostics/insights and mix matrix debugger where applicable. measure audio-render thread, source/voice count, underruns, streaming/decode, effects/submixes, and game-thread parameter traffic. reduce voice count and redundant graph work before degrading the cue that carries critical information."},{"slug":"modulation-mixing-and-quartz","file":"modulation-mixing-and-quartz.md","title":"Audio Modulation, mixing, and Quartz","rawMarkdown":"# Audio Modulation, mixing, and Quartz\n\n## Audio Modulation\n\nEnable the Audio Modulation plugin when shared dynamic mix control is needed. Build:\n\n1. Modulation Parameters with defined unit/normalized mapping.\n2. Control Buses for categories such as master, music, SFX, dialogue, ambience, or accessibility.\n3. Control Bus Mixes for gameplay/menu/state profiles.\n4. Modulation Destinations on MetaSound Sources, Sound Classes, Components, Submixes, or effects.\n5. Blueprint/C++ activation/update/clear ownership and debugging.\n\nRouting can Disable, Inherit, Override, or Union at supported destinations. Sound Class hierarchy is\nnot automatically equivalent to modulation routing; assign required buses deliberately. When an API\nedits only the UObject representation, use the appropriate Update call to push it to the audio-thread\nproxy.\n\nUse MetaSound `Get Modulator Value`/`Mix Modulators` when the graph must react to a bus. Modulation is\nblock-rate, not sample-rate. Use graph/audio-rate signals for true audio-rate modulation.\n\n## Mix hierarchy\n\nProtect critical cues through class/submix routing, concurrency priority, headroom, ducking, and\nstate mixes. Test the whole combat/ambience/music/dialogue mix, not soloed assets. Provide category\nvolume controls and non-audio equivalents for critical signals.\n\n## Quartz\n\nUse Quartz clocks for beat/bar/subdivision-aligned scheduling. Keep transport/clock ownership stable,\nschedule sufficiently ahead for the audio renderer, and define pause, tempo change, world transition,\nand late-event behavior. MetaSound produces/varies sound; Quartz owns musical-time scheduling.\n","webMarkdown":"## Audio Modulation\n\nEnable the Audio Modulation plugin when shared dynamic mix control is needed. Build:\n\n1. Modulation Parameters with defined unit/normalized mapping.\n2. Control Buses for categories such as master, music, SFX, dialogue, ambience, or accessibility.\n3. Control Bus Mixes for gameplay/menu/state profiles.\n4. Modulation Destinations on MetaSound Sources, Sound Classes, Components, Submixes, or effects.\n5. Blueprint/C++ activation/update/clear ownership and debugging.\n\nRouting can Disable, Inherit, Override, or Union at supported destinations. Sound Class hierarchy is\nnot automatically equivalent to modulation routing; assign required buses deliberately. When an API\nedits only the UObject representation, use the appropriate Update call to push it to the audio-thread\nproxy.\n\nUse MetaSound `Get Modulator Value`/`Mix Modulators` when the graph must react to a bus. Modulation is\nblock-rate, not sample-rate. Use graph/audio-rate signals for true audio-rate modulation.\n\n## Mix hierarchy\n\nProtect critical cues through class/submix routing, concurrency priority, headroom, ducking, and\nstate mixes. Test the whole combat/ambience/music/dialogue mix, not soloed assets. Provide category\nvolume controls and non-audio equivalents for critical signals.\n\n## Quartz\n\nUse Quartz clocks for beat/bar/subdivision-aligned scheduling. Keep transport/clock ownership stable,\nschedule sufficiently ahead for the audio renderer, and define pause, tempo change, world transition,\nand late-event behavior. MetaSound produces/varies sound; Quartz owns musical-time scheduling.\n","searchText":"audio modulation, mixing, and quartz audio modulation enable the audio modulation plugin when shared dynamic mix control is needed. build: 1. modulation parameters with defined unit/normalized mapping. 2. control buses for categories such as master, music, sfx, dialogue, ambience, or accessibility. 3. control bus mixes for gameplay/menu/state profiles. 4. modulation destinations on metasound sources, sound classes, components, submixes, or effects. 5. blueprint/c++ activation/update/clear ownership and debugging. routing can disable, inherit, override, or union at supported destinations. sound class hierarchy is not automatically equivalent to modulation routing; assign required buses deliberately. when an api edits only the uobject representation, use the appropriate update call to push it to the audio-thread proxy. use metasound get modulator value/mix modulators when the graph must react to a bus. modulation is block-rate, not sample-rate. use graph/audio-rate signals for true audio-rate modulation. mix hierarchy protect critical cues through class/submix routing, concurrency priority, headroom, ducking, and state mixes. test the whole combat/ambience/music/dialogue mix, not soloed assets. provide category volume controls and non-audio equivalents for critical signals. quartz use quartz clocks for beat/bar/subdivision-aligned scheduling. keep transport/clock ownership stable, schedule sufficiently ahead for the audio renderer, and define pause, tempo change, world transition, and late-event behavior. metasound produces/varies sound; quartz owns musical-time scheduling."},{"slug":"presets-patches-and-interfaces","file":"presets-patches-and-interfaces.md","title":"Presets, Patches, and interfaces","rawMarkdown":"# Presets, Patches, and interfaces\n\n## Patch\n\nExtract a Patch when the same bounded DSP/control behavior is reused: randomized wave choice,\nenvelope mapping, surface selection, filter chain, or musical utility. Document every pin, unit,\ndefault, and timing assumption. Changes propagate to containing graphs; test representative callers.\n\n## Preset\n\nRight-click a Source/Patch -> Create MetaSound Preset. A Preset inherits a read-only graph and\noverrides selected default Inputs. Parent changes propagate. Use Presets for variants sharing the\nsame behavior contract; convert from Preset only when the graph must diverge. Constructor-pin status\ncannot be overridden on Presets.\n\n## Interfaces\n\nInterfaces supply standardized Inputs/Outputs connecting MetaSounds to audio-engine systems:\n\n- `UE.Source.OneShot`: `On Finished` for finite source lifetime.\n- `UE.Attenuation`: listener distance input.\n- `UE.Spatialization`: azimuth/elevation inputs.\n\nAdd/remove interfaces in the MetaSound Interfaces panel. Do not retain OneShot on indefinite sources.\nTreat interface changes like an API migration because dependent graphs/callers may rely on members.\n\nUse templates only when repeated asset construction and curated designer controls justify the extra\nframework. For a small graph, a normal Source/Patch/Preset is clearer.\n","webMarkdown":"## Patch\n\nExtract a Patch when the same bounded DSP/control behavior is reused: randomized wave choice,\nenvelope mapping, surface selection, filter chain, or musical utility. Document every pin, unit,\ndefault, and timing assumption. Changes propagate to containing graphs; test representative callers.\n\n## Preset\n\nRight-click a Source/Patch -> Create MetaSound Preset. A Preset inherits a read-only graph and\noverrides selected default Inputs. Parent changes propagate. Use Presets for variants sharing the\nsame behavior contract; convert from Preset only when the graph must diverge. Constructor-pin status\ncannot be overridden on Presets.\n\n## Interfaces\n\nInterfaces supply standardized Inputs/Outputs connecting MetaSounds to audio-engine systems:\n\n- `UE.Source.OneShot`: `On Finished` for finite source lifetime.\n- `UE.Attenuation`: listener distance input.\n- `UE.Spatialization`: azimuth/elevation inputs.\n\nAdd/remove interfaces in the MetaSound Interfaces panel. Do not retain OneShot on indefinite sources.\nTreat interface changes like an API migration because dependent graphs/callers may rely on members.\n\nUse templates only when repeated asset construction and curated designer controls justify the extra\nframework. For a small graph, a normal Source/Patch/Preset is clearer.\n","searchText":"presets, patches, and interfaces patch extract a patch when the same bounded dsp/control behavior is reused: randomized wave choice, envelope mapping, surface selection, filter chain, or musical utility. document every pin, unit, default, and timing assumption. changes propagate to containing graphs; test representative callers. preset right-click a source/patch -> create metasound preset. a preset inherits a read-only graph and overrides selected default inputs. parent changes propagate. use presets for variants sharing the same behavior contract; convert from preset only when the graph must diverge. constructor-pin status cannot be overridden on presets. interfaces interfaces supply standardized inputs/outputs connecting metasounds to audio-engine systems: - ue.source.oneshot: on finished for finite source lifetime. - ue.attenuation: listener distance input. - ue.spatialization: azimuth/elevation inputs. add/remove interfaces in the metasound interfaces panel. do not retain oneshot on indefinite sources. treat interface changes like an api migration because dependent graphs/callers may rely on members. use templates only when repeated asset construction and curated designer controls justify the extra framework. for a small graph, a normal source/patch/preset is clearer."},{"slug":"runtime-parameters-and-events","file":"runtime-parameters-and-events.md","title":"Runtime parameters and events","rawMarkdown":"# Runtime parameters and events\n\n## Spawned/owned Audio Component\n\n1. Create or spawn an Audio Component with the MetaSound Source assigned.\n2. Set all first-block-critical parameters before calling Play.\n3. Send later values through matching Audio Component parameter setters.\n4. Send Trigger inputs for discrete audio events such as release, reroll, or next layer.\n5. Retain component ownership when later updates/stops are required.\n6. Stop/fade and release the component on owner destruction, state exit, or cancellation.\n\nParameter names and types must exactly match graph Inputs. If a value appears ignored, confirm the\ncomponent is the playing instance, the input is not a constructor-only pin, and a later graph node is\nnot overwriting/masking it.\n\n## Variables are not runtime API\n\nMetaSound Variables support internal Get/Set flow. They cannot be accessed by Blueprint, and changing\nthem externally while a sound plays is not the live-control path. Use Inputs for caller-driven state.\nUse Get Delayed Variable only when a one-block delay is intentional, commonly to break a graph cycle.\n\n## Network boundary\n\nReplicate the compact gameplay event/state when other machines need to hear it, then create/update\nlocal Audio Components. Do not replicate DSP samples or every modulation value. Define whether a\none-shot may be dropped, whether a loop must reconstruct for late relevance, and whether predicted\naudio must be cancelled or deduplicated after server response.\n","webMarkdown":"## Spawned/owned Audio Component\n\n1. Create or spawn an Audio Component with the MetaSound Source assigned.\n2. Set all first-block-critical parameters before calling Play.\n3. Send later values through matching Audio Component parameter setters.\n4. Send Trigger inputs for discrete audio events such as release, reroll, or next layer.\n5. Retain component ownership when later updates/stops are required.\n6. Stop/fade and release the component on owner destruction, state exit, or cancellation.\n\nParameter names and types must exactly match graph Inputs. If a value appears ignored, confirm the\ncomponent is the playing instance, the input is not a constructor-only pin, and a later graph node is\nnot overwriting/masking it.\n\n## Variables are not runtime API\n\nMetaSound Variables support internal Get/Set flow. They cannot be accessed by Blueprint, and changing\nthem externally while a sound plays is not the live-control path. Use Inputs for caller-driven state.\nUse Get Delayed Variable only when a one-block delay is intentional, commonly to break a graph cycle.\n\n## Network boundary\n\nReplicate the compact gameplay event/state when other machines need to hear it, then create/update\nlocal Audio Components. Do not replicate DSP samples or every modulation value. Define whether a\none-shot may be dropped, whether a loop must reconstruct for late relevance, and whether predicted\naudio must be cancelled or deduplicated after server response.\n","searchText":"runtime parameters and events spawned/owned audio component 1. create or spawn an audio component with the metasound source assigned. 2. set all first-block-critical parameters before calling play. 3. send later values through matching audio component parameter setters. 4. send trigger inputs for discrete audio events such as release, reroll, or next layer. 5. retain component ownership when later updates/stops are required. 6. stop/fade and release the component on owner destruction, state exit, or cancellation. parameter names and types must exactly match graph inputs. if a value appears ignored, confirm the component is the playing instance, the input is not a constructor-only pin, and a later graph node is not overwriting/masking it. variables are not runtime api metasound variables support internal get/set flow. they cannot be accessed by blueprint, and changing them externally while a sound plays is not the live-control path. use inputs for caller-driven state. use get delayed variable only when a one-block delay is intentional, commonly to break a graph cycle. network boundary replicate the compact gameplay event/state when other machines need to hear it, then create/update local audio components. do not replicate dsp samples or every modulation value. define whether a one-shot may be dropped, whether a loop must reconstruct for late relevance, and whether predicted audio must be cancelled or deduplicated after server response."},{"slug":"sources","file":"sources.md","title":"UE 5.8 primary sources","rawMarkdown":"# UE 5.8 primary sources\n\n- [MetaSounds Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/metasounds-the-next-generation-sound-sources-in-unreal-engine)\n- [MetaSounds Reference Guide](https://dev.epicgames.com/documentation/en-us/unreal-engine/metasounds-reference-guide-in-unreal-engine)\n- [MetaSound Plugin API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/PluginIndex/Metasound)\n- [MetaSound Builder API](https://dev.epicgames.com/documentation/en-us/unreal-engine/metasound-builder-api-in-unreal-engine)\n- [MetaSound Pages](https://dev.epicgames.com/documentation/en-us/unreal-engine/metasound-pages-in-unreal-engine)\n- [MetaSound Templates Quick Start](https://dev.epicgames.com/documentation/en-us/unreal-engine/metasound-templates-quick-start-in-unreal-engine)\n- [Audio Modulation Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/audio-modulation-overview-in-unreal-engine)\n- [Audio Modulation Quick Start](https://dev.epicgames.com/documentation/en-us/unreal-engine/audio-modulation-quick-start-guide)\n- [Audio Modulation Reference](https://dev.epicgames.com/documentation/en-us/unreal-engine/audio-modulation-reference-guide-in-unreal-engine)\n- [Quartz Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/overview-of-quartz-in-unreal-engine)\n- [Quartz Quick Start](https://dev.epicgames.com/documentation/en-us/unreal-engine/quartz-quick-start)\n\nPages were checked against the UE 5.8 documentation on 2026-07-19. Reconfirm interfaces, Builder\nAPI, template behavior, parameter timing, and modulation routing after an engine upgrade.\n","webMarkdown":"- [MetaSounds Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/metasounds-the-next-generation-sound-sources-in-unreal-engine)\n- [MetaSounds Reference Guide](https://dev.epicgames.com/documentation/en-us/unreal-engine/metasounds-reference-guide-in-unreal-engine)\n- [MetaSound Plugin API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/PluginIndex/Metasound)\n- [MetaSound Builder API](https://dev.epicgames.com/documentation/en-us/unreal-engine/metasound-builder-api-in-unreal-engine)\n- [MetaSound Pages](https://dev.epicgames.com/documentation/en-us/unreal-engine/metasound-pages-in-unreal-engine)\n- [MetaSound Templates Quick Start](https://dev.epicgames.com/documentation/en-us/unreal-engine/metasound-templates-quick-start-in-unreal-engine)\n- [Audio Modulation Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/audio-modulation-overview-in-unreal-engine)\n- [Audio Modulation Quick Start](https://dev.epicgames.com/documentation/en-us/unreal-engine/audio-modulation-quick-start-guide)\n- [Audio Modulation Reference](https://dev.epicgames.com/documentation/en-us/unreal-engine/audio-modulation-reference-guide-in-unreal-engine)\n- [Quartz Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/overview-of-quartz-in-unreal-engine)\n- [Quartz Quick Start](https://dev.epicgames.com/documentation/en-us/unreal-engine/quartz-quick-start)\n\nPages were checked against the UE 5.8 documentation on 2026-07-19. Reconfirm interfaces, Builder\nAPI, template behavior, parameter timing, and modulation routing after an engine upgrade.\n","searchText":"ue 5.8 primary sources - metasounds overview - metasounds reference guide - metasound plugin api - metasound builder api - metasound pages - metasound templates quick start - audio modulation overview - audio modulation quick start - audio modulation reference - quartz overview - quartz quick start pages were checked against the ue 5.8 documentation on 2026-07-19. reconfirm interfaces, builder api, template behavior, parameter timing, and modulation routing after an engine upgrade."},{"slug":"spatialization-lifetime-and-concurrency","file":"spatialization-lifetime-and-concurrency.md","title":"Spatialization, lifetime, and concurrency","rawMarkdown":"# Spatialization, lifetime, and concurrency\n\nMetaSound generates a source; standard Unreal audio systems still own attenuation, spatialization,\nocclusion, classes, submixes, concurrency, priority, and virtualization.\n\n## Spatial contract\n\n- Use attenuation assets/settings for distance curves, shape, spatialization, air absorption,\n  occlusion, and focus according to the game.\n- Add `UE.Attenuation` when graph behavior needs listener distance.\n- Add `UE.Spatialization` when graph behavior needs azimuth/elevation.\n- Test listener motion, split screen if supported, occlusion transitions, and teleport/discontinuity.\n\nDo not synthesize manual left/right panning as a substitute for the engine spatializer when true 3D\naudio is required.\n\n## Lifetime\n\n- Finite Source: terminal trigger -> `On Finished`; component auto-destroy/pool policy verified.\n- Indefinite Source: no one-shot interface; external owner controls release/stop.\n- Looping Wave Player: graph/source must still define when the overall sound ends.\n- Virtualized source: define whether time advances silently or restarts when audible.\n\n## Concurrency\n\nGroup semantically interchangeable voices and choose maximum count/resolution rule by information\npriority. Test bursts, nearby identical sources, quiet-loop accumulation, and modulation interaction.\nConcurrency voice stealing is a mix/design decision: never allow a low-value decorative sound to\nsteal a critical warning merely because it started later.\n","webMarkdown":"MetaSound generates a source; standard Unreal audio systems still own attenuation, spatialization,\nocclusion, classes, submixes, concurrency, priority, and virtualization.\n\n## Spatial contract\n\n- Use attenuation assets/settings for distance curves, shape, spatialization, air absorption,\n  occlusion, and focus according to the game.\n- Add `UE.Attenuation` when graph behavior needs listener distance.\n- Add `UE.Spatialization` when graph behavior needs azimuth/elevation.\n- Test listener motion, split screen if supported, occlusion transitions, and teleport/discontinuity.\n\nDo not synthesize manual left/right panning as a substitute for the engine spatializer when true 3D\naudio is required.\n\n## Lifetime\n\n- Finite Source: terminal trigger -> `On Finished`; component auto-destroy/pool policy verified.\n- Indefinite Source: no one-shot interface; external owner controls release/stop.\n- Looping Wave Player: graph/source must still define when the overall sound ends.\n- Virtualized source: define whether time advances silently or restarts when audible.\n\n## Concurrency\n\nGroup semantically interchangeable voices and choose maximum count/resolution rule by information\npriority. Test bursts, nearby identical sources, quiet-loop accumulation, and modulation interaction.\nConcurrency voice stealing is a mix/design decision: never allow a low-value decorative sound to\nsteal a critical warning merely because it started later.\n","searchText":"spatialization, lifetime, and concurrency metasound generates a source; standard unreal audio systems still own attenuation, spatialization, occlusion, classes, submixes, concurrency, priority, and virtualization. spatial contract - use attenuation assets/settings for distance curves, shape, spatialization, air absorption, occlusion, and focus according to the game. - add ue.attenuation when graph behavior needs listener distance. - add ue.spatialization when graph behavior needs azimuth/elevation. - test listener motion, split screen if supported, occlusion transitions, and teleport/discontinuity. do not synthesize manual left/right panning as a substitute for the engine spatializer when true 3d audio is required. lifetime - finite source: terminal trigger -> on finished; component auto-destroy/pool policy verified. - indefinite source: no one-shot interface; external owner controls release/stop. - looping wave player: graph/source must still define when the overall sound ends. - virtualized source: define whether time advances silently or restarts when audible. concurrency group semantically interchangeable voices and choose maximum count/resolution rule by information priority. test bursts, nearby identical sources, quiet-loop accumulation, and modulation interaction. concurrency voice stealing is a mix/design decision: never allow a low-value decorative sound to steal a critical warning merely because it started later."},{"slug":"system-selector","file":"system-selector.md","title":"System selector","rawMarkdown":"# System selector\n\n| Need | Prefer | Verify |\n|---|---|---|\n| Playable generated/processed source | MetaSound Source | output format, lifetime, concurrency |\n| Reused DSP/control subgraph | MetaSound Patch | documented pins and propagation risk |\n| Variants of one graph | MetaSound Preset | inherited defaults, constructor pins |\n| Simple fixed sample | Sound Wave/simple playback | no procedural complexity required |\n| Category/world mix state | Audio Modulation + Control Buses | routing, activation, unit conversion |\n| Beat/bar scheduling | Quartz | clock ownership, latency, quantization |\n| Dynamic graph construction | Builder API | lifecycle, handles, asset/runtime boundary |\n\nDecision questions:\n\n1. Does the sound need runtime variation or parameter response?\n2. Is change per play, during playback, per category, or global?\n3. Must events be sample-accurate or merely frame-aligned?\n4. Is the source finite, looping, sustained, or procedurally terminated?\n5. How many voices can coexist and which may be stolen/virtualized?\n\nUse the simplest layer that owns the requirement. MetaSound handles per-source generation; Audio\nModulation handles shared mix control; gameplay provides semantic events/state.\n","webMarkdown":"| Need | Prefer | Verify |\n|---|---|---|\n| Playable generated/processed source | MetaSound Source | output format, lifetime, concurrency |\n| Reused DSP/control subgraph | MetaSound Patch | documented pins and propagation risk |\n| Variants of one graph | MetaSound Preset | inherited defaults, constructor pins |\n| Simple fixed sample | Sound Wave/simple playback | no procedural complexity required |\n| Category/world mix state | Audio Modulation + Control Buses | routing, activation, unit conversion |\n| Beat/bar scheduling | Quartz | clock ownership, latency, quantization |\n| Dynamic graph construction | Builder API | lifecycle, handles, asset/runtime boundary |\n\nDecision questions:\n\n1. Does the sound need runtime variation or parameter response?\n2. Is change per play, during playback, per category, or global?\n3. Must events be sample-accurate or merely frame-aligned?\n4. Is the source finite, looping, sustained, or procedurally terminated?\n5. How many voices can coexist and which may be stolen/virtualized?\n\nUse the simplest layer that owns the requirement. MetaSound handles per-source generation; Audio\nModulation handles shared mix control; gameplay provides semantic events/state.\n","searchText":"system selector | need | prefer | verify | |---|---|---| | playable generated/processed source | metasound source | output format, lifetime, concurrency | | reused dsp/control subgraph | metasound patch | documented pins and propagation risk | | variants of one graph | metasound preset | inherited defaults, constructor pins | | simple fixed sample | sound wave/simple playback | no procedural complexity required | | category/world mix state | audio modulation + control buses | routing, activation, unit conversion | | beat/bar scheduling | quartz | clock ownership, latency, quantization | | dynamic graph construction | builder api | lifecycle, handles, asset/runtime boundary | decision questions: 1. does the sound need runtime variation or parameter response? 2. is change per play, during playback, per category, or global? 3. must events be sample-accurate or merely frame-aligned? 4. is the source finite, looping, sustained, or procedurally terminated? 5. how many voices can coexist and which may be stolen/virtualized? use the simplest layer that owns the requirement. metasound handles per-source generation; audio modulation handles shared mix control; gameplay provides semantic events/state."},{"slug":"variation-and-recipes","file":"variation-and-recipes.md","title":"Variation and recipes","rawMarkdown":"# Variation and recipes\n\n## Impact/weapon one-shot\n\nInput surface/material category, normalized magnitude, and optional seed. Select from a curated wave\narray, avoid immediate repetition, map magnitude to bounded gain/pitch/filter/transient layers, apply a\nshort envelope, then finish explicitly. Keep hit validation in gameplay.\n\n## Footsteps\n\nSelect material-aware sample sets, randomize within narrow authored bounds, and optionally scale by\nspeed/weight. Concurrency should prevent impossible stacking. Treat footsteps as feedback: preserve\ndistinguishability from ambience and pair critical enemy cues with visual/accessibility alternatives.\n\n## Engine/machine loop\n\nMaintain an owned indefinite Source. Map normalized RPM/load to crossfade, pitch, filtering, and\nlayers; smooth control changes. Separate start, sustain, and stop/release behavior. Stop/fade on owner\nshutdown and test virtualization/re-entry.\n\n## Adaptive ambience\n\nUse independent bounded layers with randomized intervals and controlled density. Drive broad state via\nModulation or infrequent parameters rather than per-frame updates to every voice. Preserve silence and\nheadroom; random does not mean unbounded simultaneous playback.\n\n## Procedural tone/UI\n\nOscillator -> envelope -> filter/gain -> output. Start/end at zero amplitude and avoid instantaneous\nfrequency/gain jumps to prevent clicks. Limit spectrum and loudness across headphones/speakers.\n\nFor deterministic replays or synchronized musical structure, own and pass a seed/clock deliberately.\nFor ordinary cosmetic variation, exact cross-client random identity is usually unnecessary.\n","webMarkdown":"## Impact/weapon one-shot\n\nInput surface/material category, normalized magnitude, and optional seed. Select from a curated wave\narray, avoid immediate repetition, map magnitude to bounded gain/pitch/filter/transient layers, apply a\nshort envelope, then finish explicitly. Keep hit validation in gameplay.\n\n## Footsteps\n\nSelect material-aware sample sets, randomize within narrow authored bounds, and optionally scale by\nspeed/weight. Concurrency should prevent impossible stacking. Treat footsteps as feedback: preserve\ndistinguishability from ambience and pair critical enemy cues with visual/accessibility alternatives.\n\n## Engine/machine loop\n\nMaintain an owned indefinite Source. Map normalized RPM/load to crossfade, pitch, filtering, and\nlayers; smooth control changes. Separate start, sustain, and stop/release behavior. Stop/fade on owner\nshutdown and test virtualization/re-entry.\n\n## Adaptive ambience\n\nUse independent bounded layers with randomized intervals and controlled density. Drive broad state via\nModulation or infrequent parameters rather than per-frame updates to every voice. Preserve silence and\nheadroom; random does not mean unbounded simultaneous playback.\n\n## Procedural tone/UI\n\nOscillator -> envelope -> filter/gain -> output. Start/end at zero amplitude and avoid instantaneous\nfrequency/gain jumps to prevent clicks. Limit spectrum and loudness across headphones/speakers.\n\nFor deterministic replays or synchronized musical structure, own and pass a seed/clock deliberately.\nFor ordinary cosmetic variation, exact cross-client random identity is usually unnecessary.\n","searchText":"variation and recipes impact/weapon one-shot input surface/material category, normalized magnitude, and optional seed. select from a curated wave array, avoid immediate repetition, map magnitude to bounded gain/pitch/filter/transient layers, apply a short envelope, then finish explicitly. keep hit validation in gameplay. footsteps select material-aware sample sets, randomize within narrow authored bounds, and optionally scale by speed/weight. concurrency should prevent impossible stacking. treat footsteps as feedback: preserve distinguishability from ambience and pair critical enemy cues with visual/accessibility alternatives. engine/machine loop maintain an owned indefinite source. map normalized rpm/load to crossfade, pitch, filtering, and layers; smooth control changes. separate start, sustain, and stop/release behavior. stop/fade on owner shutdown and test virtualization/re-entry. adaptive ambience use independent bounded layers with randomized intervals and controlled density. drive broad state via modulation or infrequent parameters rather than per-frame updates to every voice. preserve silence and headroom; random does not mean unbounded simultaneous playback. procedural tone/ui oscillator -> envelope -> filter/gain -> output. start/end at zero amplitude and avoid instantaneous frequency/gain jumps to prevent clicks. limit spectrum and loudness across headphones/speakers. for deterministic replays or synchronized musical structure, own and pass a seed/clock deliberately. for ordinary cosmetic variation, exact cross-client random identity is usually unnecessary."}]}
{"slug":"unreal-motion-matching","name":"unreal-motion-matching","title":"Unreal 5.8 Motion Matching","description":"Select, build, tune, optimize, and debug Motion Matching and Pose Search animation systems in Unreal Engine 5.8. Use for Pose Search schemas and databases, trajectory queries, Pose History, channels and weights, Choosers, database filtering, starts/stops/pivots, root-motion locomotion, cost bias, pose thrashing, foot sliding, animation coverage, warping, Rewind Debugger, or the Game Animation Sample.","shortDescription":"Build and debug motion-matched animation","category":"Animation","referenceCount":9,"rawMarkdown":"---\nname: unreal-motion-matching\ndescription: Select, build, tune, optimize, and debug Motion Matching and Pose Search animation systems in Unreal Engine 5.8. Use for Pose Search schemas and databases, trajectory queries, Pose History, channels and weights, Choosers, database filtering, starts/stops/pivots, root-motion locomotion, cost bias, pose thrashing, foot sliding, animation coverage, warping, Rewind Debugger, or the Game Animation Sample.\n---\n\n# Unreal 5.8 Motion Matching\n\n## Ownership boundary\n\nThis skill owns Pose Search data, filtering, query construction, and selection cost. Route final\nAnimGraph layering/transitions to\n[`unreal-animation-blending`](../unreal-animation-blending/SKILL.md), movement trajectory and network\nauthority to [`unreal-character-movement`](../unreal-character-movement/SKILL.md), and retargeting or\npost-selection IK/contact correction to [`unreal-control-rig-ik`](../unreal-control-rig-ik/SKILL.md).\n\n## Decide whether it fits\n\nRead [`references/system-selector.md`](references/system-selector.md).\n\nUse Motion Matching when a sufficiently broad, coherent animation set should drive responsive\nlocomotion or traversal through runtime pose selection. Keep a State Machine/Blend Space when the\nmoveset is small, stylized, intentionally discrete, or lacks the data coverage to justify search.\n\nMotion Matching does not manufacture missing motion. Coverage, trajectory quality, database\nfiltering, and movement-model agreement matter before weight tuning.\n\n## Execute\n\n1. Define movement states, required transitions, target skeleton, and root-motion contract.\n2. Audit clips for speeds, directions, starts, stops, pivots, loops, contacts, and bad frames.\n3. Enable Pose Search and create the smallest useful Schema.\n4. Build focused Databases with compatible Schema and correctly prepared animation assets.\n5. Add Motion Matching and Pose History to the AnimGraph; generate or supply trajectory.\n6. Use gameplay context and Choosers to restrict which databases can be searched.\n7. Diagnose selection in Rewind Debugger before changing weights or adding warping.\n8. Add bias, notifies, warping, IK, and performance tuning one measured need at a time.\n\nLoad only what applies:\n\n- [`references/schema-and-database.md`](references/schema-and-database.md)\n- [`references/trajectory-and-pose-history.md`](references/trajectory-and-pose-history.md)\n- [`references/filtering-and-choosers.md`](references/filtering-and-choosers.md)\n- [`references/selection-tuning.md`](references/selection-tuning.md)\n- [`references/coverage-warping-and-contact.md`](references/coverage-warping-and-contact.md)\n- [`references/debugging-and-performance.md`](references/debugging-and-performance.md)\n- [`references/implementation-patterns.md`](references/implementation-patterns.md)\n\n## Required answer format\n\nReturn:\n\n1. **Motion Matching fitness decision** and rejected alternative.\n2. **Movement/root-motion/data assumptions** and coverage gaps.\n3. **Schema channels/samples and why each changes selection**.\n4. **Database partition and Chooser/filter rules**.\n5. **AnimGraph order, trajectory source, Pose History, and overlays**.\n6. **Selection-tuning changes tied to Rewind evidence**.\n7. **Memory/search/LOD/network consequences and acceptance maneuvers**.\n\n## Hard rules\n\n- Enable the Pose Search plugin and use compatible skeleton/schema/database assets.\n- UE's documented locomotion setup expects root-motion animation with Root Motion enabled.\n- Use the fewest trajectory and pose samples that distinguish the required motions.\n- Search only context-valid databases; do not use weights to make impossible states compete.\n- Negative cost bias makes a pose/category more likely; positive bias penalizes it.\n- Fix data coverage or movement-speed disagreement before suppressing symptoms with weights.\n- Use Pose Search notify states to exclude invalid ranges or control branch-in eligibility.\n- Anim Notify filtering can suppress repeat Notifies but does not filter Notify States.\n- Diagnose with Rewind Debugger selection candidates/costs before changing several variables.\n- Treat VPTree, Permutation Time, Crashing Legs, and Character Blueprint montage selection\n  according to their Experimental UE 5.8 status.\n- Keep discrete gameplay actions in `unreal-animation-montages`; layer final IK after the base pose.\n\nSee [`references/sources.md`](references/sources.md) for the UE 5.8 source trail.\n","webMarkdown":"## Ownership boundary\n\nThis skill owns Pose Search data, filtering, query construction, and selection cost. Route final\nAnimGraph layering/transitions to\n[`unreal-animation-blending`](/unreal/unreal-animation-blending/), movement trajectory and network\nauthority to [`unreal-character-movement`](/unreal/unreal-character-movement/), and retargeting or\npost-selection IK/contact correction to [`unreal-control-rig-ik`](/unreal/unreal-control-rig-ik/).\n\n## Decide whether it fits\n\nRead [`references/system-selector.md`](/unreal/unreal-motion-matching/system-selector/).\n\nUse Motion Matching when a sufficiently broad, coherent animation set should drive responsive\nlocomotion or traversal through runtime pose selection. Keep a State Machine/Blend Space when the\nmoveset is small, stylized, intentionally discrete, or lacks the data coverage to justify search.\n\nMotion Matching does not manufacture missing motion. Coverage, trajectory quality, database\nfiltering, and movement-model agreement matter before weight tuning.\n\n## Execute\n\n1. Define movement states, required transitions, target skeleton, and root-motion contract.\n2. Audit clips for speeds, directions, starts, stops, pivots, loops, contacts, and bad frames.\n3. Enable Pose Search and create the smallest useful Schema.\n4. Build focused Databases with compatible Schema and correctly prepared animation assets.\n5. Add Motion Matching and Pose History to the AnimGraph; generate or supply trajectory.\n6. Use gameplay context and Choosers to restrict which databases can be searched.\n7. Diagnose selection in Rewind Debugger before changing weights or adding warping.\n8. Add bias, notifies, warping, IK, and performance tuning one measured need at a time.\n\nLoad only what applies:\n\n- [`references/schema-and-database.md`](/unreal/unreal-motion-matching/schema-and-database/)\n- [`references/trajectory-and-pose-history.md`](/unreal/unreal-motion-matching/trajectory-and-pose-history/)\n- [`references/filtering-and-choosers.md`](/unreal/unreal-motion-matching/filtering-and-choosers/)\n- [`references/selection-tuning.md`](/unreal/unreal-motion-matching/selection-tuning/)\n- [`references/coverage-warping-and-contact.md`](/unreal/unreal-motion-matching/coverage-warping-and-contact/)\n- [`references/debugging-and-performance.md`](/unreal/unreal-motion-matching/debugging-and-performance/)\n- [`references/implementation-patterns.md`](/unreal/unreal-motion-matching/implementation-patterns/)\n\n## Required answer format\n\nReturn:\n\n1. **Motion Matching fitness decision** and rejected alternative.\n2. **Movement/root-motion/data assumptions** and coverage gaps.\n3. **Schema channels/samples and why each changes selection**.\n4. **Database partition and Chooser/filter rules**.\n5. **AnimGraph order, trajectory source, Pose History, and overlays**.\n6. **Selection-tuning changes tied to Rewind evidence**.\n7. **Memory/search/LOD/network consequences and acceptance maneuvers**.\n\n## Hard rules\n\n- Enable the Pose Search plugin and use compatible skeleton/schema/database assets.\n- UE's documented locomotion setup expects root-motion animation with Root Motion enabled.\n- Use the fewest trajectory and pose samples that distinguish the required motions.\n- Search only context-valid databases; do not use weights to make impossible states compete.\n- Negative cost bias makes a pose/category more likely; positive bias penalizes it.\n- Fix data coverage or movement-speed disagreement before suppressing symptoms with weights.\n- Use Pose Search notify states to exclude invalid ranges or control branch-in eligibility.\n- Anim Notify filtering can suppress repeat Notifies but does not filter Notify States.\n- Diagnose with Rewind Debugger selection candidates/costs before changing several variables.\n- Treat VPTree, Permutation Time, Crashing Legs, and Character Blueprint montage selection\n  according to their Experimental UE 5.8 status.\n- Keep discrete gameplay actions in `unreal-animation-montages`; layer final IK after the base pose.\n\nSee [`references/sources.md`](/unreal/unreal-motion-matching/sources/) for the UE 5.8 source trail.\n","searchText":"unreal 5.8 motion matching select, build, tune, optimize, and debug motion matching and pose search animation systems in unreal engine 5.8. use for pose search schemas and databases, trajectory queries, pose history, channels and weights, choosers, database filtering, starts/stops/pivots, root-motion locomotion, cost bias, pose thrashing, foot sliding, animation coverage, warping, rewind debugger, or the game animation sample. coverage, warping, and contact coverage, warping, and contact coverage matrix inventory animation data across: - gait/speed bands and direction; - stationary starts and moving accelerations; - decelerations/stops by lead foot; - pivots and turn angles; - sustained loops and curved paths; - slopes/stairs/crouch/carry/weapon states as required; - interruption and transition poses. compare the root-motion speed distribution with the movement model. when gameplay moves faster than the fastest data, the database can repeatedly choose its maximum-speed pose; reducing that pose's weight hides the real mismatch. procedural correction use orientation, stride, and related animation-warping nodes to extend nearby data, not replace whole missing movement categories. establish a correct selected pose/root trajectory first, then add one warp and test its maximum acceptable deviation. layer leg/foot ik after the base locomotion and warping result. foot sliding checks: 1. root-motion clip speed versus capsule/trajectory speed; 2. chosen frame and phase continuity; 3. blend duration/profile; 4. stride/orientation warp scale; 5. ground-contact ik and moving-base handling. for duplicate footsteps caused by rapid adjacent pose selections, use anim notify filtering on the notify. it does not apply to notify states. do not let a cosmetic footstep notify drive authoritative gameplay. debugging and performance debugging and performance rewind debugger enable pose search and animation insights, then open tools -> debug -> rewind debugger and rewind debugger details. record the shortest gameplay segment that shows the defect. select the character, expand animation blueprint -> pose search, and inspect: - active pose; - continuing pose; - pose candidates and their color-coded feature costs; - database searched and candidates excluded; - selected clip/time, blend, trajectory, and current gameplay context. green cost cells are more favorable, red less favorable, and gray ignored. diagnose why the expected candidate lost rather than blindly raising its category weight. symptom matrix | symptom | first check | |---|---| | wrong gait/stance | chooser/database filtering | | thrashes between clips | continuing bias, reselect history, noisy trajectory | | stays in one loop | missing candidates, negative continuing/loop bias | | bad start/stop | coverage and future trajectory | | pops at selection | selectable ranges, pose continuity, blend profile | | feet slide | data/movement speed, root motion, phase, warping | | high runtime cost | search set size, channels/samples, search mode/frequency | | high memory | database density, pruning, principal components, lod | profile representative characters and databases on target hardware. compare brute force for quality diagnosis, then optimized search. reduce invalid search breadth before lowering quality. use database lod/density policies deliberately; verify that sparse tiers still preserve starts, stops, pivots, and readability. database filtering and choosers database filtering and choosers high-level context should remove invalid candidates before low-level pose cost ranks valid ones. pattern 1. convert gameplay state into stable animation-facing enums/tags/booleans: locomotion mode, stance, gait, airborne, carried-object class, injury, or traversal context. 2. evaluate a chooser in the motion matching node update function. 3. return only the pose search databases valid for that context. 4. feed the returned database array to the motion matching node. 5. optionally cache the selected database/tags in a post-selection function for downstream presentation. the game animation sample uses this pattern to prevent, for example, run data from competing while the player intends to walk. it also prevents a pivot from being interrupted by misclassifying its second half as a new start. use database partition/filtering for categorical differences. use schema weights to rank continuous differences inside a valid candidate set. use per-segment cost bias for a small preference, not to override a contradictory gameplay category. keep chooser inputs thread-safe and animation-facing. gameplay owns authoritative state; the animbp copies the minimal values it needs. define a fallback database when context is unknown and log empty search sets during development. implementation patterns implementation patterns locomotion base gameplay movement -> animation-facing state/trajectory -> chooser -> valid databases -> motion matching -> pose history -> orientation/stride warping -> leg ik -> upper-body/action slots. validate: idle-to-walk/run, stop both feet, 45/90/180-degree pivots, analog direction changes, acceleration/braking extremes, slopes, low frame rate, network correction, and animation lod. traversal entry selection gameplay detects and validates the obstacle. pose search chooses a compatible authored entry from a bounded traversal set using relative obstacle/character features. the action system then owns the committed traversal, collision/movement, interruption, and exit. do not let pose selection decide whether gameplay traversal is legal. discrete action alongside motion matching keep locomotion motion matching active as the base. play attack/reload/interact through a montage slot and layer by body region when appropriate. for full-body actions, intentionally suppress or replace base motion and define root-motion ownership. see unreal-animation-montages. retargeted database retarget clips first, verify root motion and contact across the complete dataset, then index the target data. a correct reference pose is insufficient: test starts, stops, pivots, extremes, and curves/notifies. see unreal-control-rig-ik for retarget diagnostics. network boundary replicate gameplay movement/state; let each client select cosmetic locomotion poses from equivalent data. do not replicate pose-search candidates every frame. ensure discrete authoritative actions use their own replicated gameplay contract. schema and database schema and database schema create via content browser -> add -> animation -> motion matching -> pose search schema, then assign the character skeleton. for basic locomotion begin with: - trajectory channel: a few past/future samples of position/facing/velocity that distinguish continue, start, stop, and turn intent. - pose channel: bones whose position/velocity distinguish phase and continuity, commonly feet for locomotion or hands for climbing. every channel and sample increases feature dimensionality and search work. add one only when a recorded failure cannot be separated by existing features. component stripping can ignore irrelevant axes; character-space values help localized motion comparisons. database create via add -> animation -> motion matching -> pose search database and assign the schema. 1. add compatible sequences, composites, or blend spaces needed for the bounded state. 2. for documented locomotion, ensure clips contain root motion and enable root motion is set. 3. trim/exclude unusable entry/exit ranges; preserve frames needed to blend. 4. use pose search notify states to block branch-in, exclude ranges, or bias specific intervals. 5. inspect every indexed clip in the database editor. partition by gameplay meaning—walk/run, stance, carried object, injury, traversal type—when only a subset is valid at once. a normalization set can compare related databases consistently; a chooser can select the context-valid set at runtime. prefer pcakdtree for an optimized search after verifying quality against brute force. vptree is experimental in ue 5.8. higher principal-component counts can improve represented variance while increasing memory and cost; tune with evidence. selection tuning selection tuning tune in this order: 1. candidate validity and database coverage. 2. trajectory accuracy relative to real movement. 3. bad selectable ranges and branch-in rules. 4. schema channels/samples. 5. channel and per-sample weights. 6. cost bias and reselection behavior. 7. blend time/profile and procedural warping. controls - channel/sample weight: raises that feature's influence. weights are normalized unless the schema data processor disables normalization. - continuing pose cost bias: negative favors staying; positive encourages leaving. - looping cost bias: negative favors loops; positive penalizes them. - pose reselect history: blocks recently chosen poses for the specified history window. - search throttle time: controls how often a new search occurs; higher values reduce search frequency but can delay response. - blend time/profile/mode: changes visual transition, not candidate correctness. avoid tuning by appearance alone. record the bad moment and compare active pose, continuing pose, and pose candidates. if the desired clip is absent, fix filtering/data. if present but expensive, inspect the exact feature costs. if selected but visually poor, inspect clip ranges, blend, pose continuity, root motion, warping, and ik. use pose search: override base cost bias or override continuing pose cost bias notify states for bounded clip regions. negative is a bonus; positive is a penalty. change one variable and replay the same maneuver. ue 5.8 primary sources ue 5.8 primary sources - motion matching - motion matching debugging - game animation sample project - motion match blueprint api - motion trajectory api - root motion pages were checked against the ue 5.8 documentation on 2026-07-19. reconfirm feature maturity, search modes, channel availability, and sample-project architecture after an engine upgrade. system selector system selector | situation | prefer | reason | |---|---|---| | large realistic locomotion set with dense transitions | motion matching | search scales with compatible data coverage | | small/stylized moveset with deliberate states | state machine/blend space | lower data/tooling cost, direct control | | one-off attack, dodge, interaction, reload | montage | explicit action lifecycle/sections/notifies | | traversal entry needs contextual pose selection | pose search/motion match query plus action system | choose a compatible entry, then own the action | | missing directional/speed coverage | author/retarget data first | weights cannot select absent motion | adoption gates: - the animation set covers the movement model's speed and direction envelope. - starts, stops, pivots, loops, and transitions have valid selectable ranges. - the team can curate schemas/databases and use rewind debugger. - memory and runtime search cost fit target platforms. - root-motion versus capsule-driven intent is explicit. start with one locomotion mode and a representative test map. do not migrate every character state before the first database proves better than the existing system under real input. trajectory and pose history trajectory and pose history minimal animgraph 1. add a motion matching node and assign its searchable database(s). 2. feed its pose through a pose history node to output pose. 3. on pose history, enable generate trajectory for the simplest documented setup, or supply the project's explicit query trajectory. 4. add every schema-sampled bone to collected bones. 5. compile, then visualize current and predicted trajectory during pie. pose history caches prior pose samples and supplies trajectory/query history used by pose search. if the schema asks for a bone that pose history does not collect, the query contract is incomplete. trajectory contract past samples describe actual recent motion; future samples describe movement intent/model prediction. positive sample offsets look forward and negative offsets look backward. build prediction from the same acceleration, braking, facing, and movement constraints the character will actually obey. symptom mapping: - starts selected too late -> future trajectory does not anticipate acceleration/input. - stops never selected -> prediction continues motion too long or stop data is filtered out. - wrong turn direction -> facing basis/coordinate space or future heading is wrong. - correct query but wrong pose -> database coverage, schema weights, bias, or candidate filtering. - query jumps after teleport -> reset history/state when the node becomes newly relevant or movement discontinuity invalidates previous samples. do not smooth trajectory until it looks plausible but sluggish. compare raw intent, predicted path, capsule movement, and selected animation in the same recording.","references":[{"slug":"coverage-warping-and-contact","file":"coverage-warping-and-contact.md","title":"Coverage, warping, and contact","rawMarkdown":"# Coverage, warping, and contact\n\n## Coverage matrix\n\nInventory animation data across:\n\n- gait/speed bands and direction;\n- stationary starts and moving accelerations;\n- decelerations/stops by lead foot;\n- pivots and turn angles;\n- sustained loops and curved paths;\n- slopes/stairs/crouch/carry/weapon states as required;\n- interruption and transition poses.\n\nCompare the root-motion speed distribution with the movement model. When gameplay moves faster than\nthe fastest data, the database can repeatedly choose its maximum-speed pose; reducing that pose's\nweight hides the real mismatch.\n\n## Procedural correction\n\nUse Orientation, Stride, and related animation-warping nodes to extend nearby data, not replace whole\nmissing movement categories. Establish a correct selected pose/root trajectory first, then add one\nwarp and test its maximum acceptable deviation. Layer leg/foot IK after the base locomotion and\nwarping result.\n\nFoot sliding checks:\n\n1. root-motion clip speed versus capsule/trajectory speed;\n2. chosen frame and phase continuity;\n3. blend duration/profile;\n4. stride/orientation warp scale;\n5. ground-contact IK and moving-base handling.\n\nFor duplicate footsteps caused by rapid adjacent pose selections, use Anim Notify filtering on the\nNotify. It does not apply to Notify States. Do not let a cosmetic footstep Notify drive authoritative\ngameplay.\n","webMarkdown":"## Coverage matrix\n\nInventory animation data across:\n\n- gait/speed bands and direction;\n- stationary starts and moving accelerations;\n- decelerations/stops by lead foot;\n- pivots and turn angles;\n- sustained loops and curved paths;\n- slopes/stairs/crouch/carry/weapon states as required;\n- interruption and transition poses.\n\nCompare the root-motion speed distribution with the movement model. When gameplay moves faster than\nthe fastest data, the database can repeatedly choose its maximum-speed pose; reducing that pose's\nweight hides the real mismatch.\n\n## Procedural correction\n\nUse Orientation, Stride, and related animation-warping nodes to extend nearby data, not replace whole\nmissing movement categories. Establish a correct selected pose/root trajectory first, then add one\nwarp and test its maximum acceptable deviation. Layer leg/foot IK after the base locomotion and\nwarping result.\n\nFoot sliding checks:\n\n1. root-motion clip speed versus capsule/trajectory speed;\n2. chosen frame and phase continuity;\n3. blend duration/profile;\n4. stride/orientation warp scale;\n5. ground-contact IK and moving-base handling.\n\nFor duplicate footsteps caused by rapid adjacent pose selections, use Anim Notify filtering on the\nNotify. It does not apply to Notify States. Do not let a cosmetic footstep Notify drive authoritative\ngameplay.\n","searchText":"coverage, warping, and contact coverage matrix inventory animation data across: - gait/speed bands and direction; - stationary starts and moving accelerations; - decelerations/stops by lead foot; - pivots and turn angles; - sustained loops and curved paths; - slopes/stairs/crouch/carry/weapon states as required; - interruption and transition poses. compare the root-motion speed distribution with the movement model. when gameplay moves faster than the fastest data, the database can repeatedly choose its maximum-speed pose; reducing that pose's weight hides the real mismatch. procedural correction use orientation, stride, and related animation-warping nodes to extend nearby data, not replace whole missing movement categories. establish a correct selected pose/root trajectory first, then add one warp and test its maximum acceptable deviation. layer leg/foot ik after the base locomotion and warping result. foot sliding checks: 1. root-motion clip speed versus capsule/trajectory speed; 2. chosen frame and phase continuity; 3. blend duration/profile; 4. stride/orientation warp scale; 5. ground-contact ik and moving-base handling. for duplicate footsteps caused by rapid adjacent pose selections, use anim notify filtering on the notify. it does not apply to notify states. do not let a cosmetic footstep notify drive authoritative gameplay."},{"slug":"debugging-and-performance","file":"debugging-and-performance.md","title":"Debugging and performance","rawMarkdown":"# Debugging and performance\n\n## Rewind Debugger\n\nEnable Pose Search and Animation Insights, then open Tools -> Debug -> Rewind Debugger and Rewind\nDebugger Details. Record the shortest gameplay segment that shows the defect. Select the character,\nexpand Animation Blueprint -> Pose Search, and inspect:\n\n- Active Pose;\n- Continuing Pose;\n- Pose Candidates and their color-coded feature costs;\n- database searched and candidates excluded;\n- selected clip/time, blend, trajectory, and current gameplay context.\n\nGreen cost cells are more favorable, red less favorable, and gray ignored. Diagnose why the expected\ncandidate lost rather than blindly raising its category weight.\n\n## Symptom matrix\n\n| Symptom | First check |\n|---|---|\n| Wrong gait/stance | Chooser/database filtering |\n| Thrashes between clips | continuing bias, reselect history, noisy trajectory |\n| Stays in one loop | missing candidates, negative continuing/loop bias |\n| Bad start/stop | coverage and future trajectory |\n| Pops at selection | selectable ranges, pose continuity, blend profile |\n| Feet slide | data/movement speed, root motion, phase, warping |\n| High runtime cost | search set size, channels/samples, search mode/frequency |\n| High memory | database density, pruning, principal components, LOD |\n\nProfile representative characters and databases on target hardware. Compare Brute Force for quality\ndiagnosis, then optimized search. Reduce invalid search breadth before lowering quality. Use database\nLOD/density policies deliberately; verify that sparse tiers still preserve starts, stops, pivots, and\nreadability.\n","webMarkdown":"## Rewind Debugger\n\nEnable Pose Search and Animation Insights, then open Tools -> Debug -> Rewind Debugger and Rewind\nDebugger Details. Record the shortest gameplay segment that shows the defect. Select the character,\nexpand Animation Blueprint -> Pose Search, and inspect:\n\n- Active Pose;\n- Continuing Pose;\n- Pose Candidates and their color-coded feature costs;\n- database searched and candidates excluded;\n- selected clip/time, blend, trajectory, and current gameplay context.\n\nGreen cost cells are more favorable, red less favorable, and gray ignored. Diagnose why the expected\ncandidate lost rather than blindly raising its category weight.\n\n## Symptom matrix\n\n| Symptom | First check |\n|---|---|\n| Wrong gait/stance | Chooser/database filtering |\n| Thrashes between clips | continuing bias, reselect history, noisy trajectory |\n| Stays in one loop | missing candidates, negative continuing/loop bias |\n| Bad start/stop | coverage and future trajectory |\n| Pops at selection | selectable ranges, pose continuity, blend profile |\n| Feet slide | data/movement speed, root motion, phase, warping |\n| High runtime cost | search set size, channels/samples, search mode/frequency |\n| High memory | database density, pruning, principal components, LOD |\n\nProfile representative characters and databases on target hardware. Compare Brute Force for quality\ndiagnosis, then optimized search. Reduce invalid search breadth before lowering quality. Use database\nLOD/density policies deliberately; verify that sparse tiers still preserve starts, stops, pivots, and\nreadability.\n","searchText":"debugging and performance rewind debugger enable pose search and animation insights, then open tools -> debug -> rewind debugger and rewind debugger details. record the shortest gameplay segment that shows the defect. select the character, expand animation blueprint -> pose search, and inspect: - active pose; - continuing pose; - pose candidates and their color-coded feature costs; - database searched and candidates excluded; - selected clip/time, blend, trajectory, and current gameplay context. green cost cells are more favorable, red less favorable, and gray ignored. diagnose why the expected candidate lost rather than blindly raising its category weight. symptom matrix | symptom | first check | |---|---| | wrong gait/stance | chooser/database filtering | | thrashes between clips | continuing bias, reselect history, noisy trajectory | | stays in one loop | missing candidates, negative continuing/loop bias | | bad start/stop | coverage and future trajectory | | pops at selection | selectable ranges, pose continuity, blend profile | | feet slide | data/movement speed, root motion, phase, warping | | high runtime cost | search set size, channels/samples, search mode/frequency | | high memory | database density, pruning, principal components, lod | profile representative characters and databases on target hardware. compare brute force for quality diagnosis, then optimized search. reduce invalid search breadth before lowering quality. use database lod/density policies deliberately; verify that sparse tiers still preserve starts, stops, pivots, and readability."},{"slug":"filtering-and-choosers","file":"filtering-and-choosers.md","title":"Database filtering and Choosers","rawMarkdown":"# Database filtering and Choosers\n\nHigh-level context should remove invalid candidates before low-level pose cost ranks valid ones.\n\n## Pattern\n\n1. Convert gameplay state into stable animation-facing enums/tags/booleans: locomotion mode, stance,\n   gait, airborne, carried-object class, injury, or traversal context.\n2. Evaluate a Chooser in the Motion Matching node update function.\n3. Return only the Pose Search Databases valid for that context.\n4. Feed the returned database array to the Motion Matching node.\n5. Optionally cache the selected database/tags in a post-selection function for downstream presentation.\n\nThe Game Animation Sample uses this pattern to prevent, for example, run data from competing while\nthe player intends to walk. It also prevents a pivot from being interrupted by misclassifying its\nsecond half as a new start.\n\nUse database partition/filtering for categorical differences. Use schema weights to rank continuous\ndifferences inside a valid candidate set. Use per-segment cost bias for a small preference, not to\noverride a contradictory gameplay category.\n\nKeep chooser inputs thread-safe and animation-facing. Gameplay owns authoritative state; the AnimBP\ncopies the minimal values it needs. Define a fallback database when context is unknown and log empty\nsearch sets during development.\n","webMarkdown":"High-level context should remove invalid candidates before low-level pose cost ranks valid ones.\n\n## Pattern\n\n1. Convert gameplay state into stable animation-facing enums/tags/booleans: locomotion mode, stance,\n   gait, airborne, carried-object class, injury, or traversal context.\n2. Evaluate a Chooser in the Motion Matching node update function.\n3. Return only the Pose Search Databases valid for that context.\n4. Feed the returned database array to the Motion Matching node.\n5. Optionally cache the selected database/tags in a post-selection function for downstream presentation.\n\nThe Game Animation Sample uses this pattern to prevent, for example, run data from competing while\nthe player intends to walk. It also prevents a pivot from being interrupted by misclassifying its\nsecond half as a new start.\n\nUse database partition/filtering for categorical differences. Use schema weights to rank continuous\ndifferences inside a valid candidate set. Use per-segment cost bias for a small preference, not to\noverride a contradictory gameplay category.\n\nKeep chooser inputs thread-safe and animation-facing. Gameplay owns authoritative state; the AnimBP\ncopies the minimal values it needs. Define a fallback database when context is unknown and log empty\nsearch sets during development.\n","searchText":"database filtering and choosers high-level context should remove invalid candidates before low-level pose cost ranks valid ones. pattern 1. convert gameplay state into stable animation-facing enums/tags/booleans: locomotion mode, stance, gait, airborne, carried-object class, injury, or traversal context. 2. evaluate a chooser in the motion matching node update function. 3. return only the pose search databases valid for that context. 4. feed the returned database array to the motion matching node. 5. optionally cache the selected database/tags in a post-selection function for downstream presentation. the game animation sample uses this pattern to prevent, for example, run data from competing while the player intends to walk. it also prevents a pivot from being interrupted by misclassifying its second half as a new start. use database partition/filtering for categorical differences. use schema weights to rank continuous differences inside a valid candidate set. use per-segment cost bias for a small preference, not to override a contradictory gameplay category. keep chooser inputs thread-safe and animation-facing. gameplay owns authoritative state; the animbp copies the minimal values it needs. define a fallback database when context is unknown and log empty search sets during development."},{"slug":"implementation-patterns","file":"implementation-patterns.md","title":"Implementation patterns","rawMarkdown":"# Implementation patterns\n\n## Locomotion base\n\nGameplay movement -> animation-facing state/trajectory -> Chooser -> valid databases -> Motion\nMatching -> Pose History -> orientation/stride warping -> leg IK -> upper-body/action Slots.\n\nValidate: idle-to-walk/run, stop both feet, 45/90/180-degree pivots, analog direction changes,\nacceleration/braking extremes, slopes, low frame rate, network correction, and animation LOD.\n\n## Traversal entry selection\n\nGameplay detects and validates the obstacle. Pose Search chooses a compatible authored entry from a\nbounded traversal set using relative obstacle/character features. The action system then owns the\ncommitted traversal, collision/movement, interruption, and exit. Do not let pose selection decide\nwhether gameplay traversal is legal.\n\n## Discrete action alongside Motion Matching\n\nKeep locomotion Motion Matching active as the base. Play attack/reload/interact through a Montage\nSlot and layer by body region when appropriate. For full-body actions, intentionally suppress or\nreplace base motion and define root-motion ownership. See `unreal-animation-montages`.\n\n## Retargeted database\n\nRetarget clips first, verify root motion and contact across the complete dataset, then index the\ntarget data. A correct reference pose is insufficient: test starts, stops, pivots, extremes, and\ncurves/notifies. See `unreal-control-rig-ik` for retarget diagnostics.\n\n## Network boundary\n\nReplicate gameplay movement/state; let each client select cosmetic locomotion poses from equivalent\ndata. Do not replicate pose-search candidates every frame. Ensure discrete authoritative actions use\ntheir own replicated gameplay contract.\n","webMarkdown":"## Locomotion base\n\nGameplay movement -> animation-facing state/trajectory -> Chooser -> valid databases -> Motion\nMatching -> Pose History -> orientation/stride warping -> leg IK -> upper-body/action Slots.\n\nValidate: idle-to-walk/run, stop both feet, 45/90/180-degree pivots, analog direction changes,\nacceleration/braking extremes, slopes, low frame rate, network correction, and animation LOD.\n\n## Traversal entry selection\n\nGameplay detects and validates the obstacle. Pose Search chooses a compatible authored entry from a\nbounded traversal set using relative obstacle/character features. The action system then owns the\ncommitted traversal, collision/movement, interruption, and exit. Do not let pose selection decide\nwhether gameplay traversal is legal.\n\n## Discrete action alongside Motion Matching\n\nKeep locomotion Motion Matching active as the base. Play attack/reload/interact through a Montage\nSlot and layer by body region when appropriate. For full-body actions, intentionally suppress or\nreplace base motion and define root-motion ownership. See `unreal-animation-montages`.\n\n## Retargeted database\n\nRetarget clips first, verify root motion and contact across the complete dataset, then index the\ntarget data. A correct reference pose is insufficient: test starts, stops, pivots, extremes, and\ncurves/notifies. See `unreal-control-rig-ik` for retarget diagnostics.\n\n## Network boundary\n\nReplicate gameplay movement/state; let each client select cosmetic locomotion poses from equivalent\ndata. Do not replicate pose-search candidates every frame. Ensure discrete authoritative actions use\ntheir own replicated gameplay contract.\n","searchText":"implementation patterns locomotion base gameplay movement -> animation-facing state/trajectory -> chooser -> valid databases -> motion matching -> pose history -> orientation/stride warping -> leg ik -> upper-body/action slots. validate: idle-to-walk/run, stop both feet, 45/90/180-degree pivots, analog direction changes, acceleration/braking extremes, slopes, low frame rate, network correction, and animation lod. traversal entry selection gameplay detects and validates the obstacle. pose search chooses a compatible authored entry from a bounded traversal set using relative obstacle/character features. the action system then owns the committed traversal, collision/movement, interruption, and exit. do not let pose selection decide whether gameplay traversal is legal. discrete action alongside motion matching keep locomotion motion matching active as the base. play attack/reload/interact through a montage slot and layer by body region when appropriate. for full-body actions, intentionally suppress or replace base motion and define root-motion ownership. see unreal-animation-montages. retargeted database retarget clips first, verify root motion and contact across the complete dataset, then index the target data. a correct reference pose is insufficient: test starts, stops, pivots, extremes, and curves/notifies. see unreal-control-rig-ik for retarget diagnostics. network boundary replicate gameplay movement/state; let each client select cosmetic locomotion poses from equivalent data. do not replicate pose-search candidates every frame. ensure discrete authoritative actions use their own replicated gameplay contract."},{"slug":"schema-and-database","file":"schema-and-database.md","title":"Schema and database","rawMarkdown":"# Schema and database\n\n## Schema\n\nCreate via Content Browser -> Add -> Animation -> Motion Matching -> Pose Search Schema, then assign\nthe character Skeleton. For basic locomotion begin with:\n\n- **Trajectory channel**: a few past/future samples of position/facing/velocity that distinguish\n  continue, start, stop, and turn intent.\n- **Pose channel**: bones whose position/velocity distinguish phase and continuity, commonly feet\n  for locomotion or hands for climbing.\n\nEvery channel and sample increases feature dimensionality and search work. Add one only when a\nrecorded failure cannot be separated by existing features. Component stripping can ignore irrelevant\naxes; character-space values help localized motion comparisons.\n\n## Database\n\nCreate via Add -> Animation -> Motion Matching -> Pose Search Database and assign the Schema.\n\n1. Add compatible Sequences, Composites, or Blend Spaces needed for the bounded state.\n2. For documented locomotion, ensure clips contain root motion and Enable Root Motion is set.\n3. Trim/exclude unusable entry/exit ranges; preserve frames needed to blend.\n4. Use Pose Search notify states to block branch-in, exclude ranges, or bias specific intervals.\n5. Inspect every indexed clip in the database editor.\n\nPartition by gameplay meaning—walk/run, stance, carried object, injury, traversal type—when only a\nsubset is valid at once. A Normalization Set can compare related databases consistently; a Chooser can\nselect the context-valid set at runtime.\n\nPrefer PCAKDTree for an optimized search after verifying quality against Brute Force. VPTree is\nExperimental in UE 5.8. Higher principal-component counts can improve represented variance while\nincreasing memory and cost; tune with evidence.\n","webMarkdown":"## Schema\n\nCreate via Content Browser -> Add -> Animation -> Motion Matching -> Pose Search Schema, then assign\nthe character Skeleton. For basic locomotion begin with:\n\n- **Trajectory channel**: a few past/future samples of position/facing/velocity that distinguish\n  continue, start, stop, and turn intent.\n- **Pose channel**: bones whose position/velocity distinguish phase and continuity, commonly feet\n  for locomotion or hands for climbing.\n\nEvery channel and sample increases feature dimensionality and search work. Add one only when a\nrecorded failure cannot be separated by existing features. Component stripping can ignore irrelevant\naxes; character-space values help localized motion comparisons.\n\n## Database\n\nCreate via Add -> Animation -> Motion Matching -> Pose Search Database and assign the Schema.\n\n1. Add compatible Sequences, Composites, or Blend Spaces needed for the bounded state.\n2. For documented locomotion, ensure clips contain root motion and Enable Root Motion is set.\n3. Trim/exclude unusable entry/exit ranges; preserve frames needed to blend.\n4. Use Pose Search notify states to block branch-in, exclude ranges, or bias specific intervals.\n5. Inspect every indexed clip in the database editor.\n\nPartition by gameplay meaning—walk/run, stance, carried object, injury, traversal type—when only a\nsubset is valid at once. A Normalization Set can compare related databases consistently; a Chooser can\nselect the context-valid set at runtime.\n\nPrefer PCAKDTree for an optimized search after verifying quality against Brute Force. VPTree is\nExperimental in UE 5.8. Higher principal-component counts can improve represented variance while\nincreasing memory and cost; tune with evidence.\n","searchText":"schema and database schema create via content browser -> add -> animation -> motion matching -> pose search schema, then assign the character skeleton. for basic locomotion begin with: - trajectory channel: a few past/future samples of position/facing/velocity that distinguish continue, start, stop, and turn intent. - pose channel: bones whose position/velocity distinguish phase and continuity, commonly feet for locomotion or hands for climbing. every channel and sample increases feature dimensionality and search work. add one only when a recorded failure cannot be separated by existing features. component stripping can ignore irrelevant axes; character-space values help localized motion comparisons. database create via add -> animation -> motion matching -> pose search database and assign the schema. 1. add compatible sequences, composites, or blend spaces needed for the bounded state. 2. for documented locomotion, ensure clips contain root motion and enable root motion is set. 3. trim/exclude unusable entry/exit ranges; preserve frames needed to blend. 4. use pose search notify states to block branch-in, exclude ranges, or bias specific intervals. 5. inspect every indexed clip in the database editor. partition by gameplay meaning—walk/run, stance, carried object, injury, traversal type—when only a subset is valid at once. a normalization set can compare related databases consistently; a chooser can select the context-valid set at runtime. prefer pcakdtree for an optimized search after verifying quality against brute force. vptree is experimental in ue 5.8. higher principal-component counts can improve represented variance while increasing memory and cost; tune with evidence."},{"slug":"selection-tuning","file":"selection-tuning.md","title":"Selection tuning","rawMarkdown":"# Selection tuning\n\nTune in this order:\n\n1. Candidate validity and database coverage.\n2. Trajectory accuracy relative to real movement.\n3. Bad selectable ranges and branch-in rules.\n4. Schema channels/samples.\n5. Channel and per-sample weights.\n6. Cost bias and reselection behavior.\n7. Blend time/profile and procedural warping.\n\n## Controls\n\n- **Channel/sample weight**: raises that feature's influence. Weights are normalized unless the\n  schema Data Processor disables normalization.\n- **Continuing Pose Cost Bias**: negative favors staying; positive encourages leaving.\n- **Looping Cost Bias**: negative favors loops; positive penalizes them.\n- **Pose Reselect History**: blocks recently chosen poses for the specified history window.\n- **Search Throttle Time**: controls how often a new search occurs; higher values reduce search\n  frequency but can delay response.\n- **Blend Time/Profile/Mode**: changes visual transition, not candidate correctness.\n\nAvoid tuning by appearance alone. Record the bad moment and compare Active Pose, Continuing Pose,\nand Pose Candidates. If the desired clip is absent, fix filtering/data. If present but expensive,\ninspect the exact feature costs. If selected but visually poor, inspect clip ranges, blend, pose\ncontinuity, root motion, warping, and IK.\n\nUse `Pose Search: Override Base Cost Bias` or `Override Continuing Pose Cost Bias` notify states for\nbounded clip regions. Negative is a bonus; positive is a penalty. Change one variable and replay the\nsame maneuver.\n","webMarkdown":"Tune in this order:\n\n1. Candidate validity and database coverage.\n2. Trajectory accuracy relative to real movement.\n3. Bad selectable ranges and branch-in rules.\n4. Schema channels/samples.\n5. Channel and per-sample weights.\n6. Cost bias and reselection behavior.\n7. Blend time/profile and procedural warping.\n\n## Controls\n\n- **Channel/sample weight**: raises that feature's influence. Weights are normalized unless the\n  schema Data Processor disables normalization.\n- **Continuing Pose Cost Bias**: negative favors staying; positive encourages leaving.\n- **Looping Cost Bias**: negative favors loops; positive penalizes them.\n- **Pose Reselect History**: blocks recently chosen poses for the specified history window.\n- **Search Throttle Time**: controls how often a new search occurs; higher values reduce search\n  frequency but can delay response.\n- **Blend Time/Profile/Mode**: changes visual transition, not candidate correctness.\n\nAvoid tuning by appearance alone. Record the bad moment and compare Active Pose, Continuing Pose,\nand Pose Candidates. If the desired clip is absent, fix filtering/data. If present but expensive,\ninspect the exact feature costs. If selected but visually poor, inspect clip ranges, blend, pose\ncontinuity, root motion, warping, and IK.\n\nUse `Pose Search: Override Base Cost Bias` or `Override Continuing Pose Cost Bias` notify states for\nbounded clip regions. Negative is a bonus; positive is a penalty. Change one variable and replay the\nsame maneuver.\n","searchText":"selection tuning tune in this order: 1. candidate validity and database coverage. 2. trajectory accuracy relative to real movement. 3. bad selectable ranges and branch-in rules. 4. schema channels/samples. 5. channel and per-sample weights. 6. cost bias and reselection behavior. 7. blend time/profile and procedural warping. controls - channel/sample weight: raises that feature's influence. weights are normalized unless the schema data processor disables normalization. - continuing pose cost bias: negative favors staying; positive encourages leaving. - looping cost bias: negative favors loops; positive penalizes them. - pose reselect history: blocks recently chosen poses for the specified history window. - search throttle time: controls how often a new search occurs; higher values reduce search frequency but can delay response. - blend time/profile/mode: changes visual transition, not candidate correctness. avoid tuning by appearance alone. record the bad moment and compare active pose, continuing pose, and pose candidates. if the desired clip is absent, fix filtering/data. if present but expensive, inspect the exact feature costs. if selected but visually poor, inspect clip ranges, blend, pose continuity, root motion, warping, and ik. use pose search: override base cost bias or override continuing pose cost bias notify states for bounded clip regions. negative is a bonus; positive is a penalty. change one variable and replay the same maneuver."},{"slug":"sources","file":"sources.md","title":"UE 5.8 primary sources","rawMarkdown":"# UE 5.8 primary sources\n\n- [Motion Matching](https://dev.epicgames.com/documentation/en-us/unreal-engine/motion-matching-in-unreal-engine)\n- [Motion Matching Debugging](https://dev.epicgames.com/documentation/en-us/unreal-engine/motion-matching-debugging-in-unreal-engine)\n- [Game Animation Sample Project](https://dev.epicgames.com/documentation/en-us/unreal-engine/game-animation-sample-project-in-unreal-engine)\n- [Motion Match Blueprint API](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/Animation/PoseSearch/MotionMatch)\n- [Motion Trajectory API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/MotionTrajectory)\n- [Root Motion](https://dev.epicgames.com/documentation/en-us/unreal-engine/root-motion-in-unreal-engine)\n\nPages were checked against the UE 5.8 documentation on 2026-07-19. Reconfirm feature maturity,\nsearch modes, channel availability, and sample-project architecture after an engine upgrade.\n","webMarkdown":"- [Motion Matching](https://dev.epicgames.com/documentation/en-us/unreal-engine/motion-matching-in-unreal-engine)\n- [Motion Matching Debugging](https://dev.epicgames.com/documentation/en-us/unreal-engine/motion-matching-debugging-in-unreal-engine)\n- [Game Animation Sample Project](https://dev.epicgames.com/documentation/en-us/unreal-engine/game-animation-sample-project-in-unreal-engine)\n- [Motion Match Blueprint API](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/Animation/PoseSearch/MotionMatch)\n- [Motion Trajectory API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/MotionTrajectory)\n- [Root Motion](https://dev.epicgames.com/documentation/en-us/unreal-engine/root-motion-in-unreal-engine)\n\nPages were checked against the UE 5.8 documentation on 2026-07-19. Reconfirm feature maturity,\nsearch modes, channel availability, and sample-project architecture after an engine upgrade.\n","searchText":"ue 5.8 primary sources - motion matching - motion matching debugging - game animation sample project - motion match blueprint api - motion trajectory api - root motion pages were checked against the ue 5.8 documentation on 2026-07-19. reconfirm feature maturity, search modes, channel availability, and sample-project architecture after an engine upgrade."},{"slug":"system-selector","file":"system-selector.md","title":"System selector","rawMarkdown":"# System selector\n\n| Situation | Prefer | Reason |\n|---|---|---|\n| Large realistic locomotion set with dense transitions | Motion Matching | search scales with compatible data coverage |\n| Small/stylized moveset with deliberate states | State Machine/Blend Space | lower data/tooling cost, direct control |\n| One-off attack, dodge, interaction, reload | Montage | explicit action lifecycle/sections/notifies |\n| Traversal entry needs contextual pose selection | Pose Search/Motion Match query plus action system | choose a compatible entry, then own the action |\n| Missing directional/speed coverage | Author/retarget data first | weights cannot select absent motion |\n\nAdoption gates:\n\n- The animation set covers the movement model's speed and direction envelope.\n- Starts, stops, pivots, loops, and transitions have valid selectable ranges.\n- The team can curate schemas/databases and use Rewind Debugger.\n- Memory and runtime search cost fit target platforms.\n- Root-motion versus capsule-driven intent is explicit.\n\nStart with one locomotion mode and a representative test map. Do not migrate every character state\nbefore the first database proves better than the existing system under real input.\n","webMarkdown":"| Situation | Prefer | Reason |\n|---|---|---|\n| Large realistic locomotion set with dense transitions | Motion Matching | search scales with compatible data coverage |\n| Small/stylized moveset with deliberate states | State Machine/Blend Space | lower data/tooling cost, direct control |\n| One-off attack, dodge, interaction, reload | Montage | explicit action lifecycle/sections/notifies |\n| Traversal entry needs contextual pose selection | Pose Search/Motion Match query plus action system | choose a compatible entry, then own the action |\n| Missing directional/speed coverage | Author/retarget data first | weights cannot select absent motion |\n\nAdoption gates:\n\n- The animation set covers the movement model's speed and direction envelope.\n- Starts, stops, pivots, loops, and transitions have valid selectable ranges.\n- The team can curate schemas/databases and use Rewind Debugger.\n- Memory and runtime search cost fit target platforms.\n- Root-motion versus capsule-driven intent is explicit.\n\nStart with one locomotion mode and a representative test map. Do not migrate every character state\nbefore the first database proves better than the existing system under real input.\n","searchText":"system selector | situation | prefer | reason | |---|---|---| | large realistic locomotion set with dense transitions | motion matching | search scales with compatible data coverage | | small/stylized moveset with deliberate states | state machine/blend space | lower data/tooling cost, direct control | | one-off attack, dodge, interaction, reload | montage | explicit action lifecycle/sections/notifies | | traversal entry needs contextual pose selection | pose search/motion match query plus action system | choose a compatible entry, then own the action | | missing directional/speed coverage | author/retarget data first | weights cannot select absent motion | adoption gates: - the animation set covers the movement model's speed and direction envelope. - starts, stops, pivots, loops, and transitions have valid selectable ranges. - the team can curate schemas/databases and use rewind debugger. - memory and runtime search cost fit target platforms. - root-motion versus capsule-driven intent is explicit. start with one locomotion mode and a representative test map. do not migrate every character state before the first database proves better than the existing system under real input."},{"slug":"trajectory-and-pose-history","file":"trajectory-and-pose-history.md","title":"Trajectory and Pose History","rawMarkdown":"# Trajectory and Pose History\n\n## Minimal AnimGraph\n\n1. Add a Motion Matching node and assign its searchable Database(s).\n2. Feed its pose through a Pose History node to Output Pose.\n3. On Pose History, enable Generate Trajectory for the simplest documented setup, or supply the\n   project's explicit query trajectory.\n4. Add every schema-sampled bone to Collected Bones.\n5. Compile, then visualize current and predicted trajectory during PIE.\n\nPose History caches prior pose samples and supplies trajectory/query history used by Pose Search.\nIf the schema asks for a bone that Pose History does not collect, the query contract is incomplete.\n\n## Trajectory contract\n\nPast samples describe actual recent motion; future samples describe movement intent/model prediction.\nPositive sample offsets look forward and negative offsets look backward. Build prediction from the\nsame acceleration, braking, facing, and movement constraints the character will actually obey.\n\nSymptom mapping:\n\n- Starts selected too late -> future trajectory does not anticipate acceleration/input.\n- Stops never selected -> prediction continues motion too long or stop data is filtered out.\n- Wrong turn direction -> facing basis/coordinate space or future heading is wrong.\n- Correct query but wrong pose -> database coverage, schema weights, bias, or candidate filtering.\n- Query jumps after teleport -> reset history/state when the node becomes newly relevant or movement\n  discontinuity invalidates previous samples.\n\nDo not smooth trajectory until it looks plausible but sluggish. Compare raw intent, predicted path,\ncapsule movement, and selected animation in the same recording.\n","webMarkdown":"## Minimal AnimGraph\n\n1. Add a Motion Matching node and assign its searchable Database(s).\n2. Feed its pose through a Pose History node to Output Pose.\n3. On Pose History, enable Generate Trajectory for the simplest documented setup, or supply the\n   project's explicit query trajectory.\n4. Add every schema-sampled bone to Collected Bones.\n5. Compile, then visualize current and predicted trajectory during PIE.\n\nPose History caches prior pose samples and supplies trajectory/query history used by Pose Search.\nIf the schema asks for a bone that Pose History does not collect, the query contract is incomplete.\n\n## Trajectory contract\n\nPast samples describe actual recent motion; future samples describe movement intent/model prediction.\nPositive sample offsets look forward and negative offsets look backward. Build prediction from the\nsame acceleration, braking, facing, and movement constraints the character will actually obey.\n\nSymptom mapping:\n\n- Starts selected too late -> future trajectory does not anticipate acceleration/input.\n- Stops never selected -> prediction continues motion too long or stop data is filtered out.\n- Wrong turn direction -> facing basis/coordinate space or future heading is wrong.\n- Correct query but wrong pose -> database coverage, schema weights, bias, or candidate filtering.\n- Query jumps after teleport -> reset history/state when the node becomes newly relevant or movement\n  discontinuity invalidates previous samples.\n\nDo not smooth trajectory until it looks plausible but sluggish. Compare raw intent, predicted path,\ncapsule movement, and selected animation in the same recording.\n","searchText":"trajectory and pose history minimal animgraph 1. add a motion matching node and assign its searchable database(s). 2. feed its pose through a pose history node to output pose. 3. on pose history, enable generate trajectory for the simplest documented setup, or supply the project's explicit query trajectory. 4. add every schema-sampled bone to collected bones. 5. compile, then visualize current and predicted trajectory during pie. pose history caches prior pose samples and supplies trajectory/query history used by pose search. if the schema asks for a bone that pose history does not collect, the query contract is incomplete. trajectory contract past samples describe actual recent motion; future samples describe movement intent/model prediction. positive sample offsets look forward and negative offsets look backward. build prediction from the same acceleration, braking, facing, and movement constraints the character will actually obey. symptom mapping: - starts selected too late -> future trajectory does not anticipate acceleration/input. - stops never selected -> prediction continues motion too long or stop data is filtered out. - wrong turn direction -> facing basis/coordinate space or future heading is wrong. - correct query but wrong pose -> database coverage, schema weights, bias, or candidate filtering. - query jumps after teleport -> reset history/state when the node becomes newly relevant or movement discontinuity invalidates previous samples. do not smooth trajectory until it looks plausible but sluggish. compare raw intent, predicted path, capsule movement, and selected animation in the same recording."}]}
{"slug":"unreal-navigation-ai","name":"unreal-navigation-ai","title":"Unreal 5.8 Navigation and AI","description":"Operational Unreal Engine 5.8 guidance for Recast NavMesh generation and agent settings, static/dynamic/invoker/world-partition navigation, areas, modifiers, links, path following, Behavior Trees and Blackboards, StateTree, AI Perception, EQS, Smart Objects, RVO and Detour Crowd avoidance, multiplayer authority, performance, and AI debugging. Use when designing, implementing, optimizing, testing, or diagnosing Unreal navigation and gameplay AI.","shortDescription":"Build and debug Unreal navigation and AI","category":"World & AI","referenceCount":11,"rawMarkdown":"---\nname: unreal-navigation-ai\ndescription: Operational Unreal Engine 5.8 guidance for Recast NavMesh generation and agent settings, static/dynamic/invoker/world-partition navigation, areas, modifiers, links, path following, Behavior Trees and Blackboards, StateTree, AI Perception, EQS, Smart Objects, RVO and Detour Crowd avoidance, multiplayer authority, performance, and AI debugging. Use when designing, implementing, optimizing, testing, or diagnosing Unreal navigation and gameplay AI.\n---\n\n# Unreal 5.8 Navigation and AI\n\nSeparate path data, movement execution, sensing, decision logic, spatial queries, interaction reservation, and local avoidance. Route only the current subsystem's details into context.\n\n## Select systems before building\n\n- Use **NavMesh** for pathfinding over traversable collision. It does not decide goals or execute animations.\n- Use **Behavior Tree + Blackboard** for event-driven, priority-ordered reactive decisions with observable aborts.\n- Use **StateTree** for explicit hierarchical modes, transitions, sequences, and shared task data.\n- Use a small component/enum/timer for trivial behavior; a graph asset is not mandatory.\n- Use **AI Perception** for sensed stimuli and memory. Perception is evidence, not omniscient authoritative truth.\n- Use **EQS** to generate, filter, and score environmental candidates. Do not run it continuously for facts a direct query already knows.\n- Use **Smart Objects** to find and reserve interaction slots. The interactor executes the behavior and must release the claim.\n- Use **RVO** or **Detour Crowd**, exclusively, for local avoidance. They complement pathfinding; they do not replace world paths.\n\nRead [system-selector-architecture.md](references/system-selector-architecture.md) first when choosing between these systems.\n\n## Route by task\n\n| Need | Load |\n|---|---|\n| Choose systems, ownership, update model | [system-selector-architecture.md](references/system-selector-architecture.md) |\n| Build NavMesh and tune agents/tiles/resolution | [navmesh-generation-agents.md](references/navmesh-generation-agents.md) |\n| Choose static/dynamic/invoker/World Partition navigation | [dynamic-navigation-world-partition.md](references/dynamic-navigation-world-partition.md) |\n| Tune MoveTo, areas, filters, modifiers, links, failure recovery | [movement-paths-links.md](references/movement-paths-links.md) |\n| Build Behavior Trees, Blackboards, decorators, services, tasks | [behavior-trees.md](references/behavior-trees.md) |\n| Build StateTree states, tasks, data, and transitions | [statetree.md](references/statetree.md) |\n| Configure AI Perception and EQS | [perception-eqs.md](references/perception-eqs.md) |\n| Build reservable interactions and crowd avoidance | [smart-objects-crowds.md](references/smart-objects-crowds.md) |\n| Debug, profile, network, and run test gates | [debugging-performance.md](references/debugging-performance.md) |\n| Apply common behavior patterns | [patterns.md](references/patterns.md) |\n| Verify claims and maturity | [sources.md](references/sources.md) |\n\n## Execute in this order\n\n1. State agent shapes, locomotion abilities, decision latency, maximum population, world/streaming model, network authority, and target hardware.\n2. Establish correct collision and supported-agent settings; build the simplest static NavMesh that proves paths.\n3. Choose navigation generation mode from actual world changes. Do not default to fully Dynamic.\n4. Prove movement, arrival, path failure, off-mesh traversal, interruption, and recovery before decision graphs.\n5. Choose one primary decision architecture and define its data contract.\n6. Add Perception as event-fed observations; define forgetting and last-known-state semantics.\n7. Add EQS only for candidate selection that needs scoring/filtering.\n8. Add Smart Objects and crowd avoidance only after single-agent behavior is reliable.\n9. Make authoritative AI decisions on the server in networked games; replicate observable gameplay results.\n10. Debug selected agents and profile worst-case populations in a cooked target build.\n\n## Hard rules\n\n- NavMesh green coverage does not prove an agent can move: controller, movement component, supported-agent selection, projection, path following, collision, links, and runtime availability must agree.\n- Agent radius, height, slope, and step settings are gameplay contracts. Do not shrink them merely to force paths through invalid geometry.\n- Do not make NavMesh fully Dynamic when static data, Dynamic Modifiers Only, streamed chunks, or invokers satisfy the requirement.\n- World Partition NavMesh is explicitly **Experimental** in UE 5.8.\n- Behavior Tree tasks must finish exactly once and clean up latent work when aborted. Use observer aborts deliberately.\n- StateTree Tasks on active states run concurrently; the first completing task can trigger completion. Do not model an intended sequence as parallel tasks.\n- Current UE 5.8 EQS documentation still describes the system as experimental. Bound query size/frequency and keep a fallback.\n- AI Perception expiration is not the same as forgetting unless the project setting and state logic support it.\n- Smart Objects contain opportunity/reservation data, not execution logic. Release claims on success, failure, abort, death, unload, or invalidation.\n- RVO and Detour Crowd are independent alternatives and should not both control one agent.\n- AI does not need to tick every decision every frame. Prefer events, observed data changes, bounded service intervals, and staggered work.\n\n## Answer contract\n\nReturn:\n\n1. **Selected systems and assumptions**.\n2. **Authority and data ownership** — server/client, controller/pawn, Blackboard/StateTree/context.\n3. **Navigation contract** — agents, generation mode, areas/links, movement and failure behavior.\n4. **Exact actions and parameter effects**.\n5. **Cancellation, unload, death, and invalidation recovery**.\n6. **Performance/scaling consequences**.\n7. **Verification** — visible debug evidence and target-build pass criteria.\n\nDo not invent universal NavMesh cell sizes, perception ranges, service intervals, or crowd limits. Derive them from agent geometry, level metrics, reaction design, population, and profiling.\n","webMarkdown":"Separate path data, movement execution, sensing, decision logic, spatial queries, interaction reservation, and local avoidance. Route only the current subsystem's details into context.\n\n## Select systems before building\n\n- Use **NavMesh** for pathfinding over traversable collision. It does not decide goals or execute animations.\n- Use **Behavior Tree + Blackboard** for event-driven, priority-ordered reactive decisions with observable aborts.\n- Use **StateTree** for explicit hierarchical modes, transitions, sequences, and shared task data.\n- Use a small component/enum/timer for trivial behavior; a graph asset is not mandatory.\n- Use **AI Perception** for sensed stimuli and memory. Perception is evidence, not omniscient authoritative truth.\n- Use **EQS** to generate, filter, and score environmental candidates. Do not run it continuously for facts a direct query already knows.\n- Use **Smart Objects** to find and reserve interaction slots. The interactor executes the behavior and must release the claim.\n- Use **RVO** or **Detour Crowd**, exclusively, for local avoidance. They complement pathfinding; they do not replace world paths.\n\nRead [system-selector-architecture.md](/unreal/unreal-navigation-ai/system-selector-architecture/) first when choosing between these systems.\n\n## Route by task\n\n| Need | Load |\n|---|---|\n| Choose systems, ownership, update model | [system-selector-architecture.md](/unreal/unreal-navigation-ai/system-selector-architecture/) |\n| Build NavMesh and tune agents/tiles/resolution | [navmesh-generation-agents.md](/unreal/unreal-navigation-ai/navmesh-generation-agents/) |\n| Choose static/dynamic/invoker/World Partition navigation | [dynamic-navigation-world-partition.md](/unreal/unreal-navigation-ai/dynamic-navigation-world-partition/) |\n| Tune MoveTo, areas, filters, modifiers, links, failure recovery | [movement-paths-links.md](/unreal/unreal-navigation-ai/movement-paths-links/) |\n| Build Behavior Trees, Blackboards, decorators, services, tasks | [behavior-trees.md](/unreal/unreal-navigation-ai/behavior-trees/) |\n| Build StateTree states, tasks, data, and transitions | [statetree.md](/unreal/unreal-navigation-ai/statetree/) |\n| Configure AI Perception and EQS | [perception-eqs.md](/unreal/unreal-navigation-ai/perception-eqs/) |\n| Build reservable interactions and crowd avoidance | [smart-objects-crowds.md](/unreal/unreal-navigation-ai/smart-objects-crowds/) |\n| Debug, profile, network, and run test gates | [debugging-performance.md](/unreal/unreal-navigation-ai/debugging-performance/) |\n| Apply common behavior patterns | [patterns.md](/unreal/unreal-navigation-ai/patterns/) |\n| Verify claims and maturity | [sources.md](/unreal/unreal-navigation-ai/sources/) |\n\n## Execute in this order\n\n1. State agent shapes, locomotion abilities, decision latency, maximum population, world/streaming model, network authority, and target hardware.\n2. Establish correct collision and supported-agent settings; build the simplest static NavMesh that proves paths.\n3. Choose navigation generation mode from actual world changes. Do not default to fully Dynamic.\n4. Prove movement, arrival, path failure, off-mesh traversal, interruption, and recovery before decision graphs.\n5. Choose one primary decision architecture and define its data contract.\n6. Add Perception as event-fed observations; define forgetting and last-known-state semantics.\n7. Add EQS only for candidate selection that needs scoring/filtering.\n8. Add Smart Objects and crowd avoidance only after single-agent behavior is reliable.\n9. Make authoritative AI decisions on the server in networked games; replicate observable gameplay results.\n10. Debug selected agents and profile worst-case populations in a cooked target build.\n\n## Hard rules\n\n- NavMesh green coverage does not prove an agent can move: controller, movement component, supported-agent selection, projection, path following, collision, links, and runtime availability must agree.\n- Agent radius, height, slope, and step settings are gameplay contracts. Do not shrink them merely to force paths through invalid geometry.\n- Do not make NavMesh fully Dynamic when static data, Dynamic Modifiers Only, streamed chunks, or invokers satisfy the requirement.\n- World Partition NavMesh is explicitly **Experimental** in UE 5.8.\n- Behavior Tree tasks must finish exactly once and clean up latent work when aborted. Use observer aborts deliberately.\n- StateTree Tasks on active states run concurrently; the first completing task can trigger completion. Do not model an intended sequence as parallel tasks.\n- Current UE 5.8 EQS documentation still describes the system as experimental. Bound query size/frequency and keep a fallback.\n- AI Perception expiration is not the same as forgetting unless the project setting and state logic support it.\n- Smart Objects contain opportunity/reservation data, not execution logic. Release claims on success, failure, abort, death, unload, or invalidation.\n- RVO and Detour Crowd are independent alternatives and should not both control one agent.\n- AI does not need to tick every decision every frame. Prefer events, observed data changes, bounded service intervals, and staggered work.\n\n## Answer contract\n\nReturn:\n\n1. **Selected systems and assumptions**.\n2. **Authority and data ownership** — server/client, controller/pawn, Blackboard/StateTree/context.\n3. **Navigation contract** — agents, generation mode, areas/links, movement and failure behavior.\n4. **Exact actions and parameter effects**.\n5. **Cancellation, unload, death, and invalidation recovery**.\n6. **Performance/scaling consequences**.\n7. **Verification** — visible debug evidence and target-build pass criteria.\n\nDo not invent universal NavMesh cell sizes, perception ranges, service intervals, or crowd limits. Derive them from agent geometry, level metrics, reaction design, population, and profiling.\n","searchText":"unreal 5.8 navigation and ai operational unreal engine 5.8 guidance for recast navmesh generation and agent settings, static/dynamic/invoker/world-partition navigation, areas, modifiers, links, path following, behavior trees and blackboards, statetree, ai perception, eqs, smart objects, rvo and detour crowd avoidance, multiplayer authority, performance, and ai debugging. use when designing, implementing, optimizing, testing, or diagnosing unreal navigation and gameplay ai. behavior trees and blackboards behavior trees and blackboards execution model ue behavior trees are event-driven. search/execution proceeds left-to-right and top-down; left branches represent higher priority. blackboard observers and decorators can trigger reevaluation and abort running work. asset/data contract - blackboard keys are typed working memory: target actor, last-known location, state flags, timestamps, current smart object handle wrapper, or requested action. - use a blackboard parent only for genuinely shared keys. - keep durable/shared game truth in the owning gameplay system, not only in a blackboard. - name keys semantically and distinguish observation (seenactor) from conclusion (combattarget). node responsibilities - composite: controls branch traversal. - decorator: gates execution and optionally observes changes/aborts branches. - task: performs one bounded action and reports success/failure/in-progress. - service: periodically updates data while its branch is active. observer aborts - self: abort the decorated running branch when its condition fails. - lower priority: abort branches to the right when this higher-priority condition becomes valid. - both: applies both behaviors. use the smallest abort scope that expresses intent. broad aborts create churn and can repeatedly cancel expensive actions. task contract 1. validate controller, pawn, keys, and required subsystem. 2. start the bounded action. 3. if latent, retain only the handles/state required for completion and return in progress. 4. complete exactly once with success or failure. 5. on abort, cancel delegates/timers/moves/abilities/claims and release resources. 6. prevent stale callbacks from finishing a newer task instance. prefer native tasks/services in measured hot paths; epic notes blueprint versions are less performant. services set an interval and random deviation from reaction needs and population budget. do not use a service as disguised per-frame tick. prefer perception/blackboard events for facts that already publish changes. common architecture text selector combat (target valid) [abort lower priority] sequence: choose position -> move -> execute action investigate (lastknownlocation set) sequence: move -> search -> clear patrol sequence: choose point -> move -> wait keep sensing outside the tree where possible; the tree reacts to well-defined working memory. debug acceptance - live behavior tree shows the expected active branch; - blackboard values change at the responsible event; - aborts cancel latent work and release claims; - every task result is handled; - no high-priority condition causes search/restart oscillation; - worst-case agent count stays inside the ai frame budget. debugging, performance, networking, and testing debugging, performance, networking, and testing diagnose in order 1. authority/lifetime — correct server/controller/pawn, possessed and initialized. 2. nav data — bounds, collision, agent/navdata selection, generation mode, loaded tile. 3. path request — valid projected start/goal, filter, partial-path policy, result. 4. path following/movement — movement mode, speed, collision, root motion, avoidance, link. 5. observation/data — perception stimulus, blackboard/statetree values and age. 6. decision — active bt branch/statetree path and transition/abort cause. 7. action cleanup — move, task, ability, montage, timer, delegate, claim. 8. budget — number/frequency/cost of agents, queries, traces, rebuilds, and replication. gameplay debugger during play, press apostrophe (') while looking at an ai to select/debug it. - numpad 0: navmesh. - numpad 1: general ai/controller/path following. - numpad 2: behavior tree and blackboard. - numpad 3: eqs when available in the current configuration. - numpad 4: perception. use show navigation true/false for runtime navmesh visualization. statetree uses its asset debugger and trace-backed instance timeline. performance capture record: - active/sleeping ai count and distance bands; - game-thread time by controller, bt/statetree task/service/evaluator; - path requests and path time percentile; - dynamic tile rebuild count/time and dirty causes; - perception listeners/sources/stimuli and sight trace load; - eqs queries, candidates/tests, duration, and failures; - smart object searches/claims/contention; - crowd neighbor/sample cost; - replication bandwidth and character movement corrections. use unreal insights and before/after captures on target hardware. stagger periodic work and apply significance/distance-based update policies only when behavior quality remains acceptable. network rules - server owns ai decisions, authoritative navigation, smart object reservation, and gameplay effects. - clients receive replicated pawns/state and render presentation. - test dedicated server, late join, relevancy loss/regain, dormancy, possession, server travel, and packet impairment. - a client debug overlay may not contain server-only internal data unless the gameplay debugger category replicates it. required failure tests - unreachable/invalid destination and partial path; - runtime obstacle and navmesh rebuild latency; - agent knocked off mesh or movement mode changes; - target dies/unloads/becomes irrelevant; - task/state abort during moveto, montage, ability, or smart object use; - claim contention and invalidation; - perception gain/loss/expiration and late stimulus; - eqs returns none or result becomes invalid; - streamed cell/navdata unload; - crowd congestion above configured maximum. acceptance requires bounded recovery—no per-frame retry loops, leaked claims/delegates, zombie moves, or silent permanent stalls. dynamic navigation, invokers, and world partition dynamic navigation, invokers, and world partition generation mode selector | mode | use when | constraint | |---|---|---| | static | navigable collision does not change at runtime | build/cook data; cheapest runtime | | dynamic modifiers only | base surface is static; runtime obstacles/areas modify it | cannot create arbitrary new navigable surface absent from base data | | dynamic | runtime geometry changes require tile regeneration | highest runtime generation cost | | dynamic + navigation invokers | very large/procedural world needs local generation around seeds | readiness radius, generation latency, and removal policy become gameplay constraints | prefer the least dynamic mode that represents real changes. runtime modifier pattern - use navmodifiervolume or navmodifiercomponent with an area class to change cost or mark navareanull. - for moving obstacles that should block rather than become walking surface, mark them as dynamic obstacles/appropriate modifiers so only affected data is dirtied. - batch or debounce frequent changes; continuous transform noise can cause rebuild thrash. navigation invokers 1. enable generate navigation only around navigation invokers in navigation system settings. 2. use dynamic runtime generation. 3. keep a navmeshboundsvolume covering the possible generation domain. 4. add navigationinvokercomponent or register an invoker. 5. set generation radius from movement speed × worst tile-ready latency + path/look-ahead margin. 6. set removal radius larger than generation radius to prevent boundary churn. 7. test fast motion, teleport, multiple invokers, invokers far from seeds, and no-invoker cleanup. do not allow an agent to request a route beyond generated navigation without a waiting, partial-route, or fallback policy. world partition navmesh world partitioned navigation mesh is experimental in ue 5.8. it splits navmesh into chunk actors that stream with world partition and supports static, dynamic modifiers only, and dynamic modes. key rules: - enable is world partitioned navmesh on the recastnavmesh; - enable fixed tile pool size for streaming and size the pool for the maximum loaded navigation bubble plus editor visualization needs; - disable automatic editor navigation updates for very large maps and require a deliberate final build; - understand base navmesh data layers: base navigation includes navigation-relevant objects outside data layers, editor data layers, and configured base navmesh data layers; - dynamic tile generation is limited to loaded space; - build static wp navigation with worldpartitionnavigationdatabuilder through the world partition builder commandlet. acceptance - clean commandlet build from source control; - correct chunks load/unload with cells; - no route crosses unloaded/missing collision; - pool exhaustion and rapid traversal have explicit behavior; - runtime data layer state produces expected base/dynamic navigation; - server paths and replicated movement remain correct; - experimental dependency and fallback are recorded for shipping review. movement, paths, areas, filters, and links movement, paths, areas, filters, and links move request contract define for every move: - actor target versus location target; - pathfinding required and partial paths allowed/forbidden; - destination projection policy and failure if projection fails; - acceptance radius and whether agent/goal radii contribute; - strafing/focus/rotation ownership; - timeout or stuck policy; - response to target movement, new priority, damage, death, unload, or possession change; - completion result handling: success, blocked, off-path, invalid, aborted. an acceptance radius is design tolerance, not a patch for bad reachability. verify actual interaction range and animation alignment. areas and filters nav areas assign traversal cost or exclusion to polygons. - high cost means “avoid if a cheaper path exists,” not “forbidden.” - use navareanull for impassable space. - use query filters to vary cost/permissions by agent or decision without rebuilding world geometry. - keep area costs positive, bounded, named semantically, and tested against path length tradeoffs. use modifiers for mud, danger, crouch zones, doors, temporary hazards, or preferred lanes only when the cost model represents gameplay intent. nav links use navlinkproxy to connect disconnected navmesh regions such as drops, jumps, ladders, doors, lifts, or teleport transitions. - simple links express a connection and direction. - smart links allow runtime/custom traversal handling. - link endpoints must touch/project to compatible navigation. - direction, agent support, area/cost, enable state, capacity, and traversal behavior must agree. for custom traversal: 1. pause/hand off normal path following at the smart link. 2. execute the movement/animation/gameplay action with authority and cancellation. 3. validate landing/exit position and collision. 4. resume/finish path following exactly once. 5. recover on interruption, link disable, moving endpoint, or streamed destination loss. stuck recovery ladder 1. confirm a valid path and correct navdata/agent. 2. confirm movement mode, collision, root motion, speed/acceleration, and controller ownership. 3. repath when the target or relevant navigation changed. 4. use a bounded retry with backoff or alternate candidate. 5. abort to a higher-level decision; do not loop moveto every frame. 6. teleport only when the design explicitly permits it and destination collision/navigation is ready. verification draw the path, areas, links, and agent corridor; log request/result identifiers and timing. test successful, unreachable, partial, invalid, aborted, moving-target, link, and streamed-boundary cases. navmesh generation and agents navmesh generation and agents basic setup 1. place a navmeshboundsvolume over intended traversable space. 2. press p to visualize generated navigation. 3. configure supported agents from real capsule/body dimensions and traversal abilities. 4. confirm the pawn uses an aicontroller and a movement/path-following-compatible movement component. 5. project representative starts/goals and run actual path/movement tests. navmesh is generated from collision, not visible triangles alone. inspect collision channels, can ever affect navigation, mobility, modifier components/volumes, and runtime generation. agent settings - agent radius: clearance from obstacles; too small permits paths the body cannot traverse. - agent height: vertical clearance requirement. - agent max slope: steepest navigable surface. - agent max step height: largest vertical step represented as traversable. keep character movement step/slope/capsule constraints compatible. multiple materially different agent shapes may require separate supported-agent/navdata configurations; validate which navdata each controller selects. tile and voxel settings - smaller cell size/cell height: more accurate geometry, slower generation, higher data cost. - larger cells: faster/smaller, but narrow paths and steps can disappear. - larger tile size uu: fewer heavier rebuild units. - smaller tiles: more localized rebuilds but more border/management overhead. - min region area: discards small isolated regions. - max simplification error: trades polygon fidelity for simpler data. epic recommends making cells as large as possible while preserving required paths and using roughly 32–128 cells per tile side for dynamic rebuild performance. treat this as a measured range, not a copied value. multiple resolutions ue 5.8 supports low/default/high tile resolutions in one navmesh through nav modifier components/areas. - use low resolution in open areas for faster generation/lower memory. - use default/high resolution only where narrow geometry needs it. - make resolution cell sizes multiples and keep tile size uu divisible by each cell size. - visualize tile resolutions and build-time heat maps on the recastnavmesh actor. validation grid test every agent at: - narrowest intended doorway/corridor; - lowest overhead clearance; - steepest intended slope and largest intended step; - moving platform/link endpoints; - material/collision transitions and landscape edits; - navmesh bounds edge and streamed-cell boundary; - exact and slightly invalid start/goal positions. never approve settings only because the green overlay exists. record successful path query, movement completion, arrival distance, and body collision. common navigation and ai patterns common navigation and ai patterns patrol -> investigate -> combat - perception event stores current stimulus and last-known location/time. - behavior tree priorities or statetree transitions own mode selection. - patrol follows authored points/spline goals through navmesh, not direct spline locomotion through obstacles. - investigate moves to last-known location, performs a bounded search, then clears/ages state. - combat chooses an action/position; interruption aborts lower-priority movement cleanly. ranged cover selection 1. generate a bounded candidate set around the querier/target. 2. filter unreachable, exposed, occupied, too-close/far, or invalid-team candidates. 3. score path cost, line of sight, distance band, spacing, and tactical direction. 4. choose best or controlled random top percentile. 5. reserve the position if multiple agents compete. 6. revalidate on arrival and use a cooldown before re-querying. eqs finds a candidate; it does not own the combat state, path lifecycle, or reservation by itself. door/ladder/jump - nav link expresses connectivity and direction. - link traversal task owns door claim/open, alignment, animation/root motion, collision changes, and resume. - abort closes/releases/restores state safely. - the destination cell and landing navigation must be loaded before traversal. smart object activity - query a bounded set at a modest interval/event. - claim before committing movement. - move to the slot transform with appropriate filter. - use returned behavior definition to execute the interactor-owned behavior. - release in one cleanup path shared by success/failure/abort/death. large-world agents - server keeps only design-required agents fully simulated. - streaming and ai significance/lifetime policies agree. - static/streamed navmesh is preferred; use dynamic/invoker generation only where world changes require it. - world partition navmesh remains experimental and needs a fallback/shipping review. - durable world state survives actor unload; controllers/tasks/claims do not assume cells remain loaded. crowd through a choke point - use one avoidance system. - spread destinations and approach slots. - keep agent radius/corridor valid; do not shrink navmesh agent settings below bodies. - add lanes, queue smart objects, token/capacity control, or encounter scheduling when geometry cannot support simultaneous flow. - stress above expected population and record deadlocks, arrival time, and cpu. acceptance for any behavior - correct under success, failure, abort, unload, and death; - explainable in debugger from observation through action; - no authoritative client-only decisions; - deterministic where design requires it and varied where repetition should be hidden; - meets reaction-quality and frame budgets at worst population on target hardware. ai perception and eqs ai perception and eqs ai perception setup place aiperceptioncomponent on the authoritative ai owner, commonly the aicontroller. add only required sense configs and select a dominant sense when location resolution needs it. sight - sight radius: range at which an unseen target can begin perception. - lose sight radius: hysteresis range for losing an already seen target; keep it at least as large as sight radius. - peripheral vision half angle degrees: angle from the forward vector, not total cone width. - auto success range from last seen location: retains sight within a local region; use only if it matches the fiction. - affiliation is fully defined through team interfaces/c++; blueprint-only projects commonly detect neutrals and filter through tags/team logic. hearing configure range/affiliation and emit explicit report noise event data with location, loudness, instigator, and tag as required. audio playback alone is not automatically a gameplay hearing stimulus. memory max age controls stimulus aging; 0 means it never expires. to actually forget stale actors through the perception system, enable project settings > engine > ai system > forget stale actors. keep last-known position/time and “currently sensed” as distinct state. use aiperceptionstimulisourcecomponent or registration apis for designated sources. unregister runtime sources when their lifetime ends. perception event pattern 1. receive ontargetperceptionupdated/appropriate batched event. 2. validate actor and stimulus sense/success. 3. update observation data and timestamp. 4. let decision logic choose whether the actor becomes a threat/target. 5. on loss/expiration, preserve or clear last-known state according to design. 6. rate-limit expensive follow-up queries across populations. eqs boundary eqs generates candidate actors/locations, then tests filter and score them relative to contexts. use it for “best valid option,” not for direct known facts. workflow: 1. define the smallest candidate generator/domain. 2. supply explicit contexts: querier, target, squad, objective, custom location. 3. apply hard invalidity as filters. 4. score surviving candidates with named, normalized design criteria. 5. select a deliberate run mode: best, random from top 5%, random from top 25%, or all matching. 6. handle no-result and stale-result cases. 7. cache/reuse only while inputs remain valid. current ue 5.8 documentation still calls eqs experimental. bound candidate count, trace/path tests, query frequency, and simultaneous agents. use an eqstestingpawn for editor visualization, but clear its query template while editing expensive queries to avoid continuous heavy updates. debugging - gameplay debugger: apostrophe, perception on numpad 4; eqs category when executing. - eqs testing pawn: blue failed/filtered candidates; green-to-red scored desirability. - record query template, owner, contexts, named parameters, run mode, candidate counts, duration, result, and failure reason. perception/eqs do not replicate internal truth automatically. run authoritative decisions on the server and replicate resulting gameplay state. smart objects and crowd avoidance smart objects and crowd avoidance smart object boundary smart objects describe spatial interaction opportunities and reserve slots. they do not contain the execution logic; each interactor implements the returned behavior definition. core pieces: - smartobject subsystem and spatial database; - smartobject component on the world actor; - smart object definition asset shared across instances; - slots with transforms, filters/tags, and behavior definitions; - optional persistent collection influencing runtime-instance lifetime. claim lifecycle text find matching objects -> choose result -> claim slot -> validate handle -> navigate to slot -> use/occupy -> execute behavior -> release rules: - search with bounded area, activity tags, user tags, behavior class, and other filters. - a search result is not a reservation; always validate the returned claim handle. - revalidate slot/location and object state before/after approach. - release on success, failure, abort, death, possession change, timeout, and task/state exit. - handle onslotinvalidateddelegate; the object may disable/unload/destroy while claimed or occupied. - keep durable gameplay outcome outside the transient claim. a persistent collection keeps included smart object runtime instances in the simulation even if source actors stream out. that is a lifetime decision, not permission to execute interaction against unloaded visuals/collision. rvo versus detour crowd | system | use | constraint | |---|---|---| | rvo | charactermovement-local velocity avoidance, including without navmesh | character only, less configurable, can push agents outside navmesh | | detour crowd | path-corridor-aware crowd avoidance for pawns | fixed max agents/max agent radius and crowd manager tuning | epic states the two systems work independently and should be used exclusively. do not enable both for one agent. crowd tuning start without avoidance and prove paths. then add one system and test: - maximum simultaneous agents and radius support; - consideration radius/neighbors and wall samples; - corridor width, opposing flows, doors, corners, merges, and destinations; - separation/collision resolution and movement-component interaction; - agents leaving navmesh, deadlocks, oscillation, and arrival congestion; - cpu cost at worst population. crowd avoidance cannot solve a level whose doorway is narrower than the throughput the encounter requires. fix geometry, lane design, destination distribution, or scheduling when appropriate. smart object + crowd pattern reserve before entering a congested approach, expose one slot per true simultaneous user, move to a reachable slot transform, queue outside the interaction corridor, and release immediately on cancellation. do not let every waiting agent continuously re-query every object. ue 5.8 primary sources ue 5.8 primary sources checked against epic's unreal engine 5.8 documentation on 2026-07-19. navigation - navigation system - basic navigation - navigation mesh settings - navigation mesh resolutions - modifying the navigation mesh - optimizing navmesh generation - navigation invokers - world partitioned navigation mesh decisions and queries - behavior tree overview - behavior tree user guide - behavior tree decorators - behavior tree services - statetree overview - statetree debugger - ai perception - environment query system - eqs testing pawn interaction, crowds, and diagnosis - smart objects overview - avoidance with the navigation system - crowd manager settings - ai debugging - gameplay debugger maturity notes - core recast navmesh, behavior trees, statetree, ai perception, smart objects, and avoidance workflows have current 5.8 documentation. - world partitioned navigation mesh is explicitly experimental. - the current eqs testing pawn guide still refers to the experimental nature of eqs; keep eqs bounded and validated. - do not infer that all ai systems replicate or run on clients. authoritative gameplay ai remains a project/network architecture decision. prefer the 5.8 page, installed engine source, console help, and working sample behavior over remembered earlier-version defaults. statetree statetree execution model statetree combines hierarchical state-machine transitions with tree-based state selection. - selection evaluates enter conditions from the target/root path toward a selectable leaf. - the selected leaf and all parent states on its active path become active. - tasks on all active states start and run concurrently. - the first completing task can trigger completion-based transition evaluation. - transitions are the only way to change the selected state. do not place sequential actions as sibling tasks in one state. use child states and next transitions for ordered steps. data roles - parameters: configured per asset/instance inputs. - context/external data: required owner, actor, subsystem, or component data supplied by the schema/runtime. - evaluators: expose/update data used by states, tasks, conditions, and transitions. - tasks: perform bounded work while their state is active. - conditions: gate state entry or transitions. choose the correct schema for the owner, such as an actor/component-oriented schema. fail early when required external data is absent. authoring workflow 1. define top-level modes with mutually understandable ownership: idle, patrol, alert, combat, disabled. 2. put shared always-active responsibilities on parent states only when concurrency is intended. 3. decompose ordered behavior into child states and success/failure/next transitions. 4. make transition priority and destination explicit. 5. expose typed data once and bind deliberately; avoid long invisible binding chains. 6. define enter/exit/cancel cleanup for moves, delegates, abilities, animation, and smart object claims. 7. use linked/subtrees only when their interface is stable and reuse is real. common failure patterns - sequence completes instantly/wrong action wins: sibling tasks ran concurrently and one finished first. - no state selected: enter conditions reject every path or required context is missing. - transition loop: a condition remains true on entry and immediately selects again. - stale data: evaluator/binding lifetime differs from the assumed update moment. - action survives state exit: task failed to cancel latent work or release resources. debugging use the statetree debugger (window > debugger in the asset editor), instance selection, traces, state/task breakpoints, and recorded transitions. the debugger can consume trace analyzer data from editor, client, and dedicated server processes. acceptance requires the active state path, task lifetimes, data values, transition cause, and cleanup to match the authored contract under interruption and failure. system selector and architecture system selector and architecture layer the problem text world collision -> navmesh/path graph -> path following/movement stimuli/events -> perception/memory -> decision architecture world candidates -> eqs/direct query -> chosen goal interaction opportunities -> smart object claim -> interactor behavior nearby moving agents -> rvo or detour crowd -> local velocity adjustment a bug belongs to one layer until evidence shows otherwise. do not “fix ai” by changing several layers together. decision selector | need | default | |---|---| | one or two simple modes | component/enum/timers/events | | reactive priorities, conditions, abort-to-higher-priority behavior | behavior tree + blackboard | | explicit hierarchical state, transitions, sequences, shared task data | statetree | | large data-oriented crowds | evaluate mass/statetree architecture separately; ordinary actor ai may not scale | behavior tree and statetree can coexist at a system boundary, but do not duplicate the same state machine in both. assign one owner and exchange compact state/events. query selector - direct known actor/location: use the known reference or subsystem lookup. - reachable random point: navigation query. - “best cover/attack/resource point” from multiple constraints: eqs. - reusable reservable activity: smart object query/claim. - long-range route: navmesh pathfinding. - short-range agent avoidance: rvo or detour crowd. authority model in networked games: - run authoritative ai controller, decisions, path requests, smart object claims, damage, and gameplay state on the server; - replicate the pawn and observable gameplay state/animation inputs as designed; - keep client-only cosmetic prediction/presentation non-authoritative; - do not replicate entire blackboards or internal decision graphs by default. route replication details to $unreal-replication. data ownership - controller owns decision/path-following concerns tied to possession. - pawn/character owns body, movement component, collision, animation-facing state. - blackboard holds behavior tree working memory, not universal game truth. - statetree context/external data supplies required owner/world data; parameters configure instances. - subsystems/game state own durable shared facts. - perception stores observations; gameplay systems decide what those observations mean. update policy prefer event-driven updates for target acquired/lost, damage, state changes, path completion, smart object invalidation, and blackboard changes. use bounded timers/services for genuinely periodic sensing or scoring. stagger expensive work across agents and treat reaction delay as a design variable, not merely a performance defect.","references":[{"slug":"behavior-trees","file":"behavior-trees.md","title":"Behavior Trees and Blackboards","rawMarkdown":"# Behavior Trees and Blackboards\n\n## Execution model\n\nUE Behavior Trees are event-driven. Search/execution proceeds left-to-right and top-down; left branches represent higher priority. Blackboard observers and decorators can trigger reevaluation and abort running work.\n\n## Asset/data contract\n\n- Blackboard keys are typed working memory: target actor, last-known location, state flags, timestamps, current Smart Object handle wrapper, or requested action.\n- Use a Blackboard parent only for genuinely shared keys.\n- Keep durable/shared game truth in the owning gameplay system, not only in a Blackboard.\n- Name keys semantically and distinguish observation (`SeenActor`) from conclusion (`CombatTarget`).\n\n## Node responsibilities\n\n- **Composite**: controls branch traversal.\n- **Decorator**: gates execution and optionally observes changes/aborts branches.\n- **Task**: performs one bounded action and reports success/failure/in-progress.\n- **Service**: periodically updates data while its branch is active.\n\n## Observer aborts\n\n- `Self`: abort the decorated running branch when its condition fails.\n- `Lower Priority`: abort branches to the right when this higher-priority condition becomes valid.\n- `Both`: applies both behaviors.\n\nUse the smallest abort scope that expresses intent. Broad aborts create churn and can repeatedly cancel expensive actions.\n\n## Task contract\n\n1. Validate controller, pawn, keys, and required subsystem.\n2. Start the bounded action.\n3. If latent, retain only the handles/state required for completion and return In Progress.\n4. Complete exactly once with success or failure.\n5. On abort, cancel delegates/timers/moves/abilities/claims and release resources.\n6. Prevent stale callbacks from finishing a newer task instance.\n\nPrefer native Tasks/Services in measured hot paths; Epic notes Blueprint versions are less performant.\n\n## Services\n\nSet an interval and random deviation from reaction needs and population budget. Do not use a service as disguised per-frame Tick. Prefer Perception/Blackboard events for facts that already publish changes.\n\n## Common architecture\n\n```text\nSelector\n  Combat (Target valid) [abort lower priority]\n    Sequence: choose position -> move -> execute action\n  Investigate (LastKnownLocation set)\n    Sequence: move -> search -> clear\n  Patrol\n    Sequence: choose point -> move -> wait\n```\n\nKeep sensing outside the tree where possible; the tree reacts to well-defined working memory.\n\n## Debug acceptance\n\n- live Behavior Tree shows the expected active branch;\n- Blackboard values change at the responsible event;\n- aborts cancel latent work and release claims;\n- every task result is handled;\n- no high-priority condition causes search/restart oscillation;\n- worst-case agent count stays inside the AI frame budget.\n","webMarkdown":"## Execution model\n\nUE Behavior Trees are event-driven. Search/execution proceeds left-to-right and top-down; left branches represent higher priority. Blackboard observers and decorators can trigger reevaluation and abort running work.\n\n## Asset/data contract\n\n- Blackboard keys are typed working memory: target actor, last-known location, state flags, timestamps, current Smart Object handle wrapper, or requested action.\n- Use a Blackboard parent only for genuinely shared keys.\n- Keep durable/shared game truth in the owning gameplay system, not only in a Blackboard.\n- Name keys semantically and distinguish observation (`SeenActor`) from conclusion (`CombatTarget`).\n\n## Node responsibilities\n\n- **Composite**: controls branch traversal.\n- **Decorator**: gates execution and optionally observes changes/aborts branches.\n- **Task**: performs one bounded action and reports success/failure/in-progress.\n- **Service**: periodically updates data while its branch is active.\n\n## Observer aborts\n\n- `Self`: abort the decorated running branch when its condition fails.\n- `Lower Priority`: abort branches to the right when this higher-priority condition becomes valid.\n- `Both`: applies both behaviors.\n\nUse the smallest abort scope that expresses intent. Broad aborts create churn and can repeatedly cancel expensive actions.\n\n## Task contract\n\n1. Validate controller, pawn, keys, and required subsystem.\n2. Start the bounded action.\n3. If latent, retain only the handles/state required for completion and return In Progress.\n4. Complete exactly once with success or failure.\n5. On abort, cancel delegates/timers/moves/abilities/claims and release resources.\n6. Prevent stale callbacks from finishing a newer task instance.\n\nPrefer native Tasks/Services in measured hot paths; Epic notes Blueprint versions are less performant.\n\n## Services\n\nSet an interval and random deviation from reaction needs and population budget. Do not use a service as disguised per-frame Tick. Prefer Perception/Blackboard events for facts that already publish changes.\n\n## Common architecture\n\n```text\nSelector\n  Combat (Target valid) [abort lower priority]\n    Sequence: choose position -> move -> execute action\n  Investigate (LastKnownLocation set)\n    Sequence: move -> search -> clear\n  Patrol\n    Sequence: choose point -> move -> wait\n```\n\nKeep sensing outside the tree where possible; the tree reacts to well-defined working memory.\n\n## Debug acceptance\n\n- live Behavior Tree shows the expected active branch;\n- Blackboard values change at the responsible event;\n- aborts cancel latent work and release claims;\n- every task result is handled;\n- no high-priority condition causes search/restart oscillation;\n- worst-case agent count stays inside the AI frame budget.\n","searchText":"behavior trees and blackboards execution model ue behavior trees are event-driven. search/execution proceeds left-to-right and top-down; left branches represent higher priority. blackboard observers and decorators can trigger reevaluation and abort running work. asset/data contract - blackboard keys are typed working memory: target actor, last-known location, state flags, timestamps, current smart object handle wrapper, or requested action. - use a blackboard parent only for genuinely shared keys. - keep durable/shared game truth in the owning gameplay system, not only in a blackboard. - name keys semantically and distinguish observation (seenactor) from conclusion (combattarget). node responsibilities - composite: controls branch traversal. - decorator: gates execution and optionally observes changes/aborts branches. - task: performs one bounded action and reports success/failure/in-progress. - service: periodically updates data while its branch is active. observer aborts - self: abort the decorated running branch when its condition fails. - lower priority: abort branches to the right when this higher-priority condition becomes valid. - both: applies both behaviors. use the smallest abort scope that expresses intent. broad aborts create churn and can repeatedly cancel expensive actions. task contract 1. validate controller, pawn, keys, and required subsystem. 2. start the bounded action. 3. if latent, retain only the handles/state required for completion and return in progress. 4. complete exactly once with success or failure. 5. on abort, cancel delegates/timers/moves/abilities/claims and release resources. 6. prevent stale callbacks from finishing a newer task instance. prefer native tasks/services in measured hot paths; epic notes blueprint versions are less performant. services set an interval and random deviation from reaction needs and population budget. do not use a service as disguised per-frame tick. prefer perception/blackboard events for facts that already publish changes. common architecture text selector combat (target valid) [abort lower priority] sequence: choose position -> move -> execute action investigate (lastknownlocation set) sequence: move -> search -> clear patrol sequence: choose point -> move -> wait keep sensing outside the tree where possible; the tree reacts to well-defined working memory. debug acceptance - live behavior tree shows the expected active branch; - blackboard values change at the responsible event; - aborts cancel latent work and release claims; - every task result is handled; - no high-priority condition causes search/restart oscillation; - worst-case agent count stays inside the ai frame budget."},{"slug":"debugging-performance","file":"debugging-performance.md","title":"Debugging, performance, networking, and testing","rawMarkdown":"# Debugging, performance, networking, and testing\n\n## Diagnose in order\n\n1. **Authority/lifetime** — correct server/controller/pawn, possessed and initialized.\n2. **Nav data** — bounds, collision, agent/NavData selection, generation mode, loaded tile.\n3. **Path request** — valid projected start/goal, filter, partial-path policy, result.\n4. **Path following/movement** — movement mode, speed, collision, root motion, avoidance, link.\n5. **Observation/data** — Perception stimulus, Blackboard/StateTree values and age.\n6. **Decision** — active BT branch/StateTree path and transition/abort cause.\n7. **Action cleanup** — move, task, ability, montage, timer, delegate, claim.\n8. **Budget** — number/frequency/cost of agents, queries, traces, rebuilds, and replication.\n\n## Gameplay Debugger\n\nDuring play, press apostrophe (`'`) while looking at an AI to select/debug it.\n\n- Numpad `0`: NavMesh.\n- Numpad `1`: general AI/controller/path following.\n- Numpad `2`: Behavior Tree and Blackboard.\n- Numpad `3`: EQS when available in the current configuration.\n- Numpad `4`: Perception.\n\nUse `show Navigation true/false` for runtime NavMesh visualization. StateTree uses its asset Debugger and trace-backed instance timeline.\n\n## Performance capture\n\nRecord:\n\n- active/sleeping AI count and distance bands;\n- game-thread time by controller, BT/StateTree task/service/evaluator;\n- path requests and path time percentile;\n- dynamic tile rebuild count/time and dirty causes;\n- Perception listeners/sources/stimuli and sight trace load;\n- EQS queries, candidates/tests, duration, and failures;\n- Smart Object searches/claims/contention;\n- crowd neighbor/sample cost;\n- replication bandwidth and Character Movement corrections.\n\nUse Unreal Insights and before/after captures on target hardware. Stagger periodic work and apply significance/distance-based update policies only when behavior quality remains acceptable.\n\n## Network rules\n\n- Server owns AI decisions, authoritative navigation, Smart Object reservation, and gameplay effects.\n- Clients receive replicated Pawns/state and render presentation.\n- Test dedicated server, late join, relevancy loss/regain, dormancy, possession, server travel, and packet impairment.\n- A client debug overlay may not contain server-only internal data unless the Gameplay Debugger category replicates it.\n\n## Required failure tests\n\n- unreachable/invalid destination and partial path;\n- runtime obstacle and NavMesh rebuild latency;\n- agent knocked off mesh or movement mode changes;\n- target dies/unloads/becomes irrelevant;\n- task/state abort during MoveTo, montage, ability, or Smart Object use;\n- claim contention and invalidation;\n- Perception gain/loss/expiration and late stimulus;\n- EQS returns none or result becomes invalid;\n- streamed cell/NavData unload;\n- crowd congestion above configured maximum.\n\nAcceptance requires bounded recovery—no per-frame retry loops, leaked claims/delegates, zombie moves, or silent permanent stalls.\n","webMarkdown":"## Diagnose in order\n\n1. **Authority/lifetime** — correct server/controller/pawn, possessed and initialized.\n2. **Nav data** — bounds, collision, agent/NavData selection, generation mode, loaded tile.\n3. **Path request** — valid projected start/goal, filter, partial-path policy, result.\n4. **Path following/movement** — movement mode, speed, collision, root motion, avoidance, link.\n5. **Observation/data** — Perception stimulus, Blackboard/StateTree values and age.\n6. **Decision** — active BT branch/StateTree path and transition/abort cause.\n7. **Action cleanup** — move, task, ability, montage, timer, delegate, claim.\n8. **Budget** — number/frequency/cost of agents, queries, traces, rebuilds, and replication.\n\n## Gameplay Debugger\n\nDuring play, press apostrophe (`'`) while looking at an AI to select/debug it.\n\n- Numpad `0`: NavMesh.\n- Numpad `1`: general AI/controller/path following.\n- Numpad `2`: Behavior Tree and Blackboard.\n- Numpad `3`: EQS when available in the current configuration.\n- Numpad `4`: Perception.\n\nUse `show Navigation true/false` for runtime NavMesh visualization. StateTree uses its asset Debugger and trace-backed instance timeline.\n\n## Performance capture\n\nRecord:\n\n- active/sleeping AI count and distance bands;\n- game-thread time by controller, BT/StateTree task/service/evaluator;\n- path requests and path time percentile;\n- dynamic tile rebuild count/time and dirty causes;\n- Perception listeners/sources/stimuli and sight trace load;\n- EQS queries, candidates/tests, duration, and failures;\n- Smart Object searches/claims/contention;\n- crowd neighbor/sample cost;\n- replication bandwidth and Character Movement corrections.\n\nUse Unreal Insights and before/after captures on target hardware. Stagger periodic work and apply significance/distance-based update policies only when behavior quality remains acceptable.\n\n## Network rules\n\n- Server owns AI decisions, authoritative navigation, Smart Object reservation, and gameplay effects.\n- Clients receive replicated Pawns/state and render presentation.\n- Test dedicated server, late join, relevancy loss/regain, dormancy, possession, server travel, and packet impairment.\n- A client debug overlay may not contain server-only internal data unless the Gameplay Debugger category replicates it.\n\n## Required failure tests\n\n- unreachable/invalid destination and partial path;\n- runtime obstacle and NavMesh rebuild latency;\n- agent knocked off mesh or movement mode changes;\n- target dies/unloads/becomes irrelevant;\n- task/state abort during MoveTo, montage, ability, or Smart Object use;\n- claim contention and invalidation;\n- Perception gain/loss/expiration and late stimulus;\n- EQS returns none or result becomes invalid;\n- streamed cell/NavData unload;\n- crowd congestion above configured maximum.\n\nAcceptance requires bounded recovery—no per-frame retry loops, leaked claims/delegates, zombie moves, or silent permanent stalls.\n","searchText":"debugging, performance, networking, and testing diagnose in order 1. authority/lifetime — correct server/controller/pawn, possessed and initialized. 2. nav data — bounds, collision, agent/navdata selection, generation mode, loaded tile. 3. path request — valid projected start/goal, filter, partial-path policy, result. 4. path following/movement — movement mode, speed, collision, root motion, avoidance, link. 5. observation/data — perception stimulus, blackboard/statetree values and age. 6. decision — active bt branch/statetree path and transition/abort cause. 7. action cleanup — move, task, ability, montage, timer, delegate, claim. 8. budget — number/frequency/cost of agents, queries, traces, rebuilds, and replication. gameplay debugger during play, press apostrophe (') while looking at an ai to select/debug it. - numpad 0: navmesh. - numpad 1: general ai/controller/path following. - numpad 2: behavior tree and blackboard. - numpad 3: eqs when available in the current configuration. - numpad 4: perception. use show navigation true/false for runtime navmesh visualization. statetree uses its asset debugger and trace-backed instance timeline. performance capture record: - active/sleeping ai count and distance bands; - game-thread time by controller, bt/statetree task/service/evaluator; - path requests and path time percentile; - dynamic tile rebuild count/time and dirty causes; - perception listeners/sources/stimuli and sight trace load; - eqs queries, candidates/tests, duration, and failures; - smart object searches/claims/contention; - crowd neighbor/sample cost; - replication bandwidth and character movement corrections. use unreal insights and before/after captures on target hardware. stagger periodic work and apply significance/distance-based update policies only when behavior quality remains acceptable. network rules - server owns ai decisions, authoritative navigation, smart object reservation, and gameplay effects. - clients receive replicated pawns/state and render presentation. - test dedicated server, late join, relevancy loss/regain, dormancy, possession, server travel, and packet impairment. - a client debug overlay may not contain server-only internal data unless the gameplay debugger category replicates it. required failure tests - unreachable/invalid destination and partial path; - runtime obstacle and navmesh rebuild latency; - agent knocked off mesh or movement mode changes; - target dies/unloads/becomes irrelevant; - task/state abort during moveto, montage, ability, or smart object use; - claim contention and invalidation; - perception gain/loss/expiration and late stimulus; - eqs returns none or result becomes invalid; - streamed cell/navdata unload; - crowd congestion above configured maximum. acceptance requires bounded recovery—no per-frame retry loops, leaked claims/delegates, zombie moves, or silent permanent stalls."},{"slug":"dynamic-navigation-world-partition","file":"dynamic-navigation-world-partition.md","title":"Dynamic navigation, invokers, and World Partition","rawMarkdown":"# Dynamic navigation, invokers, and World Partition\n\n## Generation mode selector\n\n| Mode | Use when | Constraint |\n|---|---|---|\n| Static | Navigable collision does not change at runtime | Build/cook data; cheapest runtime |\n| Dynamic Modifiers Only | Base surface is static; runtime obstacles/areas modify it | Cannot create arbitrary new navigable surface absent from base data |\n| Dynamic | Runtime geometry changes require tile regeneration | Highest runtime generation cost |\n| Dynamic + Navigation Invokers | Very large/procedural world needs local generation around seeds | Readiness radius, generation latency, and removal policy become gameplay constraints |\n\nPrefer the least dynamic mode that represents real changes.\n\n## Runtime modifier pattern\n\n- Use `NavModifierVolume` or `NavModifierComponent` with an Area Class to change cost or mark `NavArea_Null`.\n- For moving obstacles that should block rather than become walking surface, mark them as Dynamic Obstacles/appropriate modifiers so only affected data is dirtied.\n- Batch or debounce frequent changes; continuous transform noise can cause rebuild thrash.\n\n## Navigation Invokers\n\n1. Enable `Generate Navigation Only Around Navigation Invokers` in Navigation System settings.\n2. Use Dynamic runtime generation.\n3. Keep a NavMeshBoundsVolume covering the possible generation domain.\n4. Add `NavigationInvokerComponent` or register an invoker.\n5. Set generation radius from movement speed × worst tile-ready latency + path/look-ahead margin.\n6. Set removal radius larger than generation radius to prevent boundary churn.\n7. Test fast motion, teleport, multiple invokers, invokers far from seeds, and no-invoker cleanup.\n\nDo not allow an agent to request a route beyond generated navigation without a waiting, partial-route, or fallback policy.\n\n## World Partition NavMesh\n\nWorld Partitioned Navigation Mesh is **Experimental** in UE 5.8. It splits NavMesh into chunk Actors that stream with World Partition and supports Static, Dynamic Modifiers Only, and Dynamic modes.\n\nKey rules:\n\n- enable `Is World Partitioned Navmesh` on the RecastNavMesh;\n- enable Fixed Tile Pool Size for streaming and size the pool for the maximum loaded navigation bubble plus editor visualization needs;\n- disable automatic editor navigation updates for very large maps and require a deliberate final build;\n- understand Base NavMesh Data Layers: base navigation includes navigation-relevant objects outside Data Layers, Editor Data Layers, and configured Base NavMesh Data Layers;\n- Dynamic tile generation is limited to loaded space;\n- build static WP navigation with `WorldPartitionNavigationDataBuilder` through the World Partition Builder Commandlet.\n\n## Acceptance\n\n- clean commandlet build from source control;\n- correct chunks load/unload with cells;\n- no route crosses unloaded/missing collision;\n- pool exhaustion and rapid traversal have explicit behavior;\n- Runtime Data Layer state produces expected base/dynamic navigation;\n- server paths and replicated movement remain correct;\n- Experimental dependency and fallback are recorded for shipping review.\n","webMarkdown":"## Generation mode selector\n\n| Mode | Use when | Constraint |\n|---|---|---|\n| Static | Navigable collision does not change at runtime | Build/cook data; cheapest runtime |\n| Dynamic Modifiers Only | Base surface is static; runtime obstacles/areas modify it | Cannot create arbitrary new navigable surface absent from base data |\n| Dynamic | Runtime geometry changes require tile regeneration | Highest runtime generation cost |\n| Dynamic + Navigation Invokers | Very large/procedural world needs local generation around seeds | Readiness radius, generation latency, and removal policy become gameplay constraints |\n\nPrefer the least dynamic mode that represents real changes.\n\n## Runtime modifier pattern\n\n- Use `NavModifierVolume` or `NavModifierComponent` with an Area Class to change cost or mark `NavArea_Null`.\n- For moving obstacles that should block rather than become walking surface, mark them as Dynamic Obstacles/appropriate modifiers so only affected data is dirtied.\n- Batch or debounce frequent changes; continuous transform noise can cause rebuild thrash.\n\n## Navigation Invokers\n\n1. Enable `Generate Navigation Only Around Navigation Invokers` in Navigation System settings.\n2. Use Dynamic runtime generation.\n3. Keep a NavMeshBoundsVolume covering the possible generation domain.\n4. Add `NavigationInvokerComponent` or register an invoker.\n5. Set generation radius from movement speed × worst tile-ready latency + path/look-ahead margin.\n6. Set removal radius larger than generation radius to prevent boundary churn.\n7. Test fast motion, teleport, multiple invokers, invokers far from seeds, and no-invoker cleanup.\n\nDo not allow an agent to request a route beyond generated navigation without a waiting, partial-route, or fallback policy.\n\n## World Partition NavMesh\n\nWorld Partitioned Navigation Mesh is **Experimental** in UE 5.8. It splits NavMesh into chunk Actors that stream with World Partition and supports Static, Dynamic Modifiers Only, and Dynamic modes.\n\nKey rules:\n\n- enable `Is World Partitioned Navmesh` on the RecastNavMesh;\n- enable Fixed Tile Pool Size for streaming and size the pool for the maximum loaded navigation bubble plus editor visualization needs;\n- disable automatic editor navigation updates for very large maps and require a deliberate final build;\n- understand Base NavMesh Data Layers: base navigation includes navigation-relevant objects outside Data Layers, Editor Data Layers, and configured Base NavMesh Data Layers;\n- Dynamic tile generation is limited to loaded space;\n- build static WP navigation with `WorldPartitionNavigationDataBuilder` through the World Partition Builder Commandlet.\n\n## Acceptance\n\n- clean commandlet build from source control;\n- correct chunks load/unload with cells;\n- no route crosses unloaded/missing collision;\n- pool exhaustion and rapid traversal have explicit behavior;\n- Runtime Data Layer state produces expected base/dynamic navigation;\n- server paths and replicated movement remain correct;\n- Experimental dependency and fallback are recorded for shipping review.\n","searchText":"dynamic navigation, invokers, and world partition generation mode selector | mode | use when | constraint | |---|---|---| | static | navigable collision does not change at runtime | build/cook data; cheapest runtime | | dynamic modifiers only | base surface is static; runtime obstacles/areas modify it | cannot create arbitrary new navigable surface absent from base data | | dynamic | runtime geometry changes require tile regeneration | highest runtime generation cost | | dynamic + navigation invokers | very large/procedural world needs local generation around seeds | readiness radius, generation latency, and removal policy become gameplay constraints | prefer the least dynamic mode that represents real changes. runtime modifier pattern - use navmodifiervolume or navmodifiercomponent with an area class to change cost or mark navareanull. - for moving obstacles that should block rather than become walking surface, mark them as dynamic obstacles/appropriate modifiers so only affected data is dirtied. - batch or debounce frequent changes; continuous transform noise can cause rebuild thrash. navigation invokers 1. enable generate navigation only around navigation invokers in navigation system settings. 2. use dynamic runtime generation. 3. keep a navmeshboundsvolume covering the possible generation domain. 4. add navigationinvokercomponent or register an invoker. 5. set generation radius from movement speed × worst tile-ready latency + path/look-ahead margin. 6. set removal radius larger than generation radius to prevent boundary churn. 7. test fast motion, teleport, multiple invokers, invokers far from seeds, and no-invoker cleanup. do not allow an agent to request a route beyond generated navigation without a waiting, partial-route, or fallback policy. world partition navmesh world partitioned navigation mesh is experimental in ue 5.8. it splits navmesh into chunk actors that stream with world partition and supports static, dynamic modifiers only, and dynamic modes. key rules: - enable is world partitioned navmesh on the recastnavmesh; - enable fixed tile pool size for streaming and size the pool for the maximum loaded navigation bubble plus editor visualization needs; - disable automatic editor navigation updates for very large maps and require a deliberate final build; - understand base navmesh data layers: base navigation includes navigation-relevant objects outside data layers, editor data layers, and configured base navmesh data layers; - dynamic tile generation is limited to loaded space; - build static wp navigation with worldpartitionnavigationdatabuilder through the world partition builder commandlet. acceptance - clean commandlet build from source control; - correct chunks load/unload with cells; - no route crosses unloaded/missing collision; - pool exhaustion and rapid traversal have explicit behavior; - runtime data layer state produces expected base/dynamic navigation; - server paths and replicated movement remain correct; - experimental dependency and fallback are recorded for shipping review."},{"slug":"movement-paths-links","file":"movement-paths-links.md","title":"Movement, paths, areas, filters, and links","rawMarkdown":"# Movement, paths, areas, filters, and links\n\n## Move request contract\n\nDefine for every move:\n\n- actor target versus location target;\n- pathfinding required and partial paths allowed/forbidden;\n- destination projection policy and failure if projection fails;\n- acceptance radius and whether agent/goal radii contribute;\n- strafing/focus/rotation ownership;\n- timeout or stuck policy;\n- response to target movement, new priority, damage, death, unload, or possession change;\n- completion result handling: success, blocked, off-path, invalid, aborted.\n\nAn acceptance radius is design tolerance, not a patch for bad reachability. Verify actual interaction range and animation alignment.\n\n## Areas and filters\n\nNav Areas assign traversal cost or exclusion to polygons.\n\n- High cost means “avoid if a cheaper path exists,” not “forbidden.”\n- Use `NavArea_Null` for impassable space.\n- Use query filters to vary cost/permissions by agent or decision without rebuilding world geometry.\n- Keep area costs positive, bounded, named semantically, and tested against path length tradeoffs.\n\nUse modifiers for mud, danger, crouch zones, doors, temporary hazards, or preferred lanes only when the cost model represents gameplay intent.\n\n## Nav Links\n\nUse `NavLinkProxy` to connect disconnected NavMesh regions such as drops, jumps, ladders, doors, lifts, or teleport transitions.\n\n- Simple links express a connection and direction.\n- Smart links allow runtime/custom traversal handling.\n- Link endpoints must touch/project to compatible navigation.\n- Direction, agent support, area/cost, enable state, capacity, and traversal behavior must agree.\n\nFor custom traversal:\n\n1. Pause/hand off normal path following at the smart link.\n2. Execute the movement/animation/gameplay action with authority and cancellation.\n3. Validate landing/exit position and collision.\n4. Resume/finish path following exactly once.\n5. Recover on interruption, link disable, moving endpoint, or streamed destination loss.\n\n## Stuck recovery ladder\n\n1. Confirm a valid path and correct NavData/agent.\n2. Confirm movement mode, collision, root motion, speed/acceleration, and controller ownership.\n3. Repath when the target or relevant navigation changed.\n4. Use a bounded retry with backoff or alternate candidate.\n5. Abort to a higher-level decision; do not loop MoveTo every frame.\n6. Teleport only when the design explicitly permits it and destination collision/navigation is ready.\n\n## Verification\n\nDraw the path, areas, links, and agent corridor; log request/result identifiers and timing. Test successful, unreachable, partial, invalid, aborted, moving-target, link, and streamed-boundary cases.\n","webMarkdown":"## Move request contract\n\nDefine for every move:\n\n- actor target versus location target;\n- pathfinding required and partial paths allowed/forbidden;\n- destination projection policy and failure if projection fails;\n- acceptance radius and whether agent/goal radii contribute;\n- strafing/focus/rotation ownership;\n- timeout or stuck policy;\n- response to target movement, new priority, damage, death, unload, or possession change;\n- completion result handling: success, blocked, off-path, invalid, aborted.\n\nAn acceptance radius is design tolerance, not a patch for bad reachability. Verify actual interaction range and animation alignment.\n\n## Areas and filters\n\nNav Areas assign traversal cost or exclusion to polygons.\n\n- High cost means “avoid if a cheaper path exists,” not “forbidden.”\n- Use `NavArea_Null` for impassable space.\n- Use query filters to vary cost/permissions by agent or decision without rebuilding world geometry.\n- Keep area costs positive, bounded, named semantically, and tested against path length tradeoffs.\n\nUse modifiers for mud, danger, crouch zones, doors, temporary hazards, or preferred lanes only when the cost model represents gameplay intent.\n\n## Nav Links\n\nUse `NavLinkProxy` to connect disconnected NavMesh regions such as drops, jumps, ladders, doors, lifts, or teleport transitions.\n\n- Simple links express a connection and direction.\n- Smart links allow runtime/custom traversal handling.\n- Link endpoints must touch/project to compatible navigation.\n- Direction, agent support, area/cost, enable state, capacity, and traversal behavior must agree.\n\nFor custom traversal:\n\n1. Pause/hand off normal path following at the smart link.\n2. Execute the movement/animation/gameplay action with authority and cancellation.\n3. Validate landing/exit position and collision.\n4. Resume/finish path following exactly once.\n5. Recover on interruption, link disable, moving endpoint, or streamed destination loss.\n\n## Stuck recovery ladder\n\n1. Confirm a valid path and correct NavData/agent.\n2. Confirm movement mode, collision, root motion, speed/acceleration, and controller ownership.\n3. Repath when the target or relevant navigation changed.\n4. Use a bounded retry with backoff or alternate candidate.\n5. Abort to a higher-level decision; do not loop MoveTo every frame.\n6. Teleport only when the design explicitly permits it and destination collision/navigation is ready.\n\n## Verification\n\nDraw the path, areas, links, and agent corridor; log request/result identifiers and timing. Test successful, unreachable, partial, invalid, aborted, moving-target, link, and streamed-boundary cases.\n","searchText":"movement, paths, areas, filters, and links move request contract define for every move: - actor target versus location target; - pathfinding required and partial paths allowed/forbidden; - destination projection policy and failure if projection fails; - acceptance radius and whether agent/goal radii contribute; - strafing/focus/rotation ownership; - timeout or stuck policy; - response to target movement, new priority, damage, death, unload, or possession change; - completion result handling: success, blocked, off-path, invalid, aborted. an acceptance radius is design tolerance, not a patch for bad reachability. verify actual interaction range and animation alignment. areas and filters nav areas assign traversal cost or exclusion to polygons. - high cost means “avoid if a cheaper path exists,” not “forbidden.” - use navareanull for impassable space. - use query filters to vary cost/permissions by agent or decision without rebuilding world geometry. - keep area costs positive, bounded, named semantically, and tested against path length tradeoffs. use modifiers for mud, danger, crouch zones, doors, temporary hazards, or preferred lanes only when the cost model represents gameplay intent. nav links use navlinkproxy to connect disconnected navmesh regions such as drops, jumps, ladders, doors, lifts, or teleport transitions. - simple links express a connection and direction. - smart links allow runtime/custom traversal handling. - link endpoints must touch/project to compatible navigation. - direction, agent support, area/cost, enable state, capacity, and traversal behavior must agree. for custom traversal: 1. pause/hand off normal path following at the smart link. 2. execute the movement/animation/gameplay action with authority and cancellation. 3. validate landing/exit position and collision. 4. resume/finish path following exactly once. 5. recover on interruption, link disable, moving endpoint, or streamed destination loss. stuck recovery ladder 1. confirm a valid path and correct navdata/agent. 2. confirm movement mode, collision, root motion, speed/acceleration, and controller ownership. 3. repath when the target or relevant navigation changed. 4. use a bounded retry with backoff or alternate candidate. 5. abort to a higher-level decision; do not loop moveto every frame. 6. teleport only when the design explicitly permits it and destination collision/navigation is ready. verification draw the path, areas, links, and agent corridor; log request/result identifiers and timing. test successful, unreachable, partial, invalid, aborted, moving-target, link, and streamed-boundary cases."},{"slug":"navmesh-generation-agents","file":"navmesh-generation-agents.md","title":"NavMesh generation and agents","rawMarkdown":"# NavMesh generation and agents\n\n## Basic setup\n\n1. Place a `NavMeshBoundsVolume` over intended traversable space.\n2. Press `P` to visualize generated navigation.\n3. Configure Supported Agents from real capsule/body dimensions and traversal abilities.\n4. Confirm the Pawn uses an AIController and a movement/path-following-compatible movement component.\n5. Project representative starts/goals and run actual path/movement tests.\n\nNavMesh is generated from collision, not visible triangles alone. Inspect collision channels, `Can Ever Affect Navigation`, mobility, modifier components/volumes, and runtime generation.\n\n## Agent settings\n\n- `Agent Radius`: clearance from obstacles; too small permits paths the body cannot traverse.\n- `Agent Height`: vertical clearance requirement.\n- `Agent Max Slope`: steepest navigable surface.\n- `Agent Max Step Height`: largest vertical step represented as traversable.\n\nKeep Character Movement step/slope/capsule constraints compatible. Multiple materially different agent shapes may require separate supported-agent/NavData configurations; validate which NavData each controller selects.\n\n## Tile and voxel settings\n\n- Smaller `Cell Size`/`Cell Height`: more accurate geometry, slower generation, higher data cost.\n- Larger cells: faster/smaller, but narrow paths and steps can disappear.\n- Larger `Tile Size UU`: fewer heavier rebuild units.\n- Smaller tiles: more localized rebuilds but more border/management overhead.\n- `Min Region Area`: discards small isolated regions.\n- `Max Simplification Error`: trades polygon fidelity for simpler data.\n\nEpic recommends making cells as large as possible while preserving required paths and using roughly 32–128 cells per tile side for dynamic rebuild performance. Treat this as a measured range, not a copied value.\n\n## Multiple resolutions\n\nUE 5.8 supports low/default/high tile resolutions in one NavMesh through Nav Modifier components/areas.\n\n- Use low resolution in open areas for faster generation/lower memory.\n- Use default/high resolution only where narrow geometry needs it.\n- Make resolution Cell Sizes multiples and keep `Tile Size UU` divisible by each Cell Size.\n- Visualize tile resolutions and build-time heat maps on the RecastNavMesh actor.\n\n## Validation grid\n\nTest every agent at:\n\n- narrowest intended doorway/corridor;\n- lowest overhead clearance;\n- steepest intended slope and largest intended step;\n- moving platform/link endpoints;\n- material/collision transitions and Landscape edits;\n- NavMesh bounds edge and streamed-cell boundary;\n- exact and slightly invalid start/goal positions.\n\nNever approve settings only because the green overlay exists. Record successful path query, movement completion, arrival distance, and body collision.\n","webMarkdown":"## Basic setup\n\n1. Place a `NavMeshBoundsVolume` over intended traversable space.\n2. Press `P` to visualize generated navigation.\n3. Configure Supported Agents from real capsule/body dimensions and traversal abilities.\n4. Confirm the Pawn uses an AIController and a movement/path-following-compatible movement component.\n5. Project representative starts/goals and run actual path/movement tests.\n\nNavMesh is generated from collision, not visible triangles alone. Inspect collision channels, `Can Ever Affect Navigation`, mobility, modifier components/volumes, and runtime generation.\n\n## Agent settings\n\n- `Agent Radius`: clearance from obstacles; too small permits paths the body cannot traverse.\n- `Agent Height`: vertical clearance requirement.\n- `Agent Max Slope`: steepest navigable surface.\n- `Agent Max Step Height`: largest vertical step represented as traversable.\n\nKeep Character Movement step/slope/capsule constraints compatible. Multiple materially different agent shapes may require separate supported-agent/NavData configurations; validate which NavData each controller selects.\n\n## Tile and voxel settings\n\n- Smaller `Cell Size`/`Cell Height`: more accurate geometry, slower generation, higher data cost.\n- Larger cells: faster/smaller, but narrow paths and steps can disappear.\n- Larger `Tile Size UU`: fewer heavier rebuild units.\n- Smaller tiles: more localized rebuilds but more border/management overhead.\n- `Min Region Area`: discards small isolated regions.\n- `Max Simplification Error`: trades polygon fidelity for simpler data.\n\nEpic recommends making cells as large as possible while preserving required paths and using roughly 32–128 cells per tile side for dynamic rebuild performance. Treat this as a measured range, not a copied value.\n\n## Multiple resolutions\n\nUE 5.8 supports low/default/high tile resolutions in one NavMesh through Nav Modifier components/areas.\n\n- Use low resolution in open areas for faster generation/lower memory.\n- Use default/high resolution only where narrow geometry needs it.\n- Make resolution Cell Sizes multiples and keep `Tile Size UU` divisible by each Cell Size.\n- Visualize tile resolutions and build-time heat maps on the RecastNavMesh actor.\n\n## Validation grid\n\nTest every agent at:\n\n- narrowest intended doorway/corridor;\n- lowest overhead clearance;\n- steepest intended slope and largest intended step;\n- moving platform/link endpoints;\n- material/collision transitions and Landscape edits;\n- NavMesh bounds edge and streamed-cell boundary;\n- exact and slightly invalid start/goal positions.\n\nNever approve settings only because the green overlay exists. Record successful path query, movement completion, arrival distance, and body collision.\n","searchText":"navmesh generation and agents basic setup 1. place a navmeshboundsvolume over intended traversable space. 2. press p to visualize generated navigation. 3. configure supported agents from real capsule/body dimensions and traversal abilities. 4. confirm the pawn uses an aicontroller and a movement/path-following-compatible movement component. 5. project representative starts/goals and run actual path/movement tests. navmesh is generated from collision, not visible triangles alone. inspect collision channels, can ever affect navigation, mobility, modifier components/volumes, and runtime generation. agent settings - agent radius: clearance from obstacles; too small permits paths the body cannot traverse. - agent height: vertical clearance requirement. - agent max slope: steepest navigable surface. - agent max step height: largest vertical step represented as traversable. keep character movement step/slope/capsule constraints compatible. multiple materially different agent shapes may require separate supported-agent/navdata configurations; validate which navdata each controller selects. tile and voxel settings - smaller cell size/cell height: more accurate geometry, slower generation, higher data cost. - larger cells: faster/smaller, but narrow paths and steps can disappear. - larger tile size uu: fewer heavier rebuild units. - smaller tiles: more localized rebuilds but more border/management overhead. - min region area: discards small isolated regions. - max simplification error: trades polygon fidelity for simpler data. epic recommends making cells as large as possible while preserving required paths and using roughly 32–128 cells per tile side for dynamic rebuild performance. treat this as a measured range, not a copied value. multiple resolutions ue 5.8 supports low/default/high tile resolutions in one navmesh through nav modifier components/areas. - use low resolution in open areas for faster generation/lower memory. - use default/high resolution only where narrow geometry needs it. - make resolution cell sizes multiples and keep tile size uu divisible by each cell size. - visualize tile resolutions and build-time heat maps on the recastnavmesh actor. validation grid test every agent at: - narrowest intended doorway/corridor; - lowest overhead clearance; - steepest intended slope and largest intended step; - moving platform/link endpoints; - material/collision transitions and landscape edits; - navmesh bounds edge and streamed-cell boundary; - exact and slightly invalid start/goal positions. never approve settings only because the green overlay exists. record successful path query, movement completion, arrival distance, and body collision."},{"slug":"patterns","file":"patterns.md","title":"Common navigation and AI patterns","rawMarkdown":"# Common navigation and AI patterns\n\n## Patrol -> investigate -> combat\n\n- Perception event stores current stimulus and last-known location/time.\n- Behavior Tree priorities or StateTree transitions own mode selection.\n- Patrol follows authored points/spline goals through NavMesh, not direct spline locomotion through obstacles.\n- Investigate moves to last-known location, performs a bounded search, then clears/ages state.\n- Combat chooses an action/position; interruption aborts lower-priority movement cleanly.\n\n## Ranged cover selection\n\n1. Generate a bounded candidate set around the querier/target.\n2. Filter unreachable, exposed, occupied, too-close/far, or invalid-team candidates.\n3. Score path cost, line of sight, distance band, spacing, and tactical direction.\n4. Choose best or controlled random top percentile.\n5. Reserve the position if multiple agents compete.\n6. Revalidate on arrival and use a cooldown before re-querying.\n\nEQS finds a candidate; it does not own the combat state, path lifecycle, or reservation by itself.\n\n## Door/ladder/jump\n\n- Nav Link expresses connectivity and direction.\n- Link traversal task owns door claim/open, alignment, animation/root motion, collision changes, and resume.\n- Abort closes/releases/restores state safely.\n- The destination cell and landing navigation must be loaded before traversal.\n\n## Smart Object activity\n\n- Query a bounded set at a modest interval/event.\n- Claim before committing movement.\n- Move to the Slot transform with appropriate filter.\n- Use returned Behavior Definition to execute the interactor-owned behavior.\n- Release in one cleanup path shared by success/failure/abort/death.\n\n## Large-world agents\n\n- Server keeps only design-required agents fully simulated.\n- Streaming and AI significance/lifetime policies agree.\n- Static/streamed NavMesh is preferred; use dynamic/invoker generation only where world changes require it.\n- World Partition NavMesh remains Experimental and needs a fallback/shipping review.\n- Durable world state survives actor unload; controllers/tasks/claims do not assume cells remain loaded.\n\n## Crowd through a choke point\n\n- Use one avoidance system.\n- Spread destinations and approach slots.\n- Keep agent radius/corridor valid; do not shrink NavMesh agent settings below bodies.\n- Add lanes, queue Smart Objects, token/capacity control, or encounter scheduling when geometry cannot support simultaneous flow.\n- Stress above expected population and record deadlocks, arrival time, and CPU.\n\n## Acceptance for any behavior\n\n- correct under success, failure, abort, unload, and death;\n- explainable in debugger from observation through action;\n- no authoritative client-only decisions;\n- deterministic where design requires it and varied where repetition should be hidden;\n- meets reaction-quality and frame budgets at worst population on target hardware.\n","webMarkdown":"## Patrol -> investigate -> combat\n\n- Perception event stores current stimulus and last-known location/time.\n- Behavior Tree priorities or StateTree transitions own mode selection.\n- Patrol follows authored points/spline goals through NavMesh, not direct spline locomotion through obstacles.\n- Investigate moves to last-known location, performs a bounded search, then clears/ages state.\n- Combat chooses an action/position; interruption aborts lower-priority movement cleanly.\n\n## Ranged cover selection\n\n1. Generate a bounded candidate set around the querier/target.\n2. Filter unreachable, exposed, occupied, too-close/far, or invalid-team candidates.\n3. Score path cost, line of sight, distance band, spacing, and tactical direction.\n4. Choose best or controlled random top percentile.\n5. Reserve the position if multiple agents compete.\n6. Revalidate on arrival and use a cooldown before re-querying.\n\nEQS finds a candidate; it does not own the combat state, path lifecycle, or reservation by itself.\n\n## Door/ladder/jump\n\n- Nav Link expresses connectivity and direction.\n- Link traversal task owns door claim/open, alignment, animation/root motion, collision changes, and resume.\n- Abort closes/releases/restores state safely.\n- The destination cell and landing navigation must be loaded before traversal.\n\n## Smart Object activity\n\n- Query a bounded set at a modest interval/event.\n- Claim before committing movement.\n- Move to the Slot transform with appropriate filter.\n- Use returned Behavior Definition to execute the interactor-owned behavior.\n- Release in one cleanup path shared by success/failure/abort/death.\n\n## Large-world agents\n\n- Server keeps only design-required agents fully simulated.\n- Streaming and AI significance/lifetime policies agree.\n- Static/streamed NavMesh is preferred; use dynamic/invoker generation only where world changes require it.\n- World Partition NavMesh remains Experimental and needs a fallback/shipping review.\n- Durable world state survives actor unload; controllers/tasks/claims do not assume cells remain loaded.\n\n## Crowd through a choke point\n\n- Use one avoidance system.\n- Spread destinations and approach slots.\n- Keep agent radius/corridor valid; do not shrink NavMesh agent settings below bodies.\n- Add lanes, queue Smart Objects, token/capacity control, or encounter scheduling when geometry cannot support simultaneous flow.\n- Stress above expected population and record deadlocks, arrival time, and CPU.\n\n## Acceptance for any behavior\n\n- correct under success, failure, abort, unload, and death;\n- explainable in debugger from observation through action;\n- no authoritative client-only decisions;\n- deterministic where design requires it and varied where repetition should be hidden;\n- meets reaction-quality and frame budgets at worst population on target hardware.\n","searchText":"common navigation and ai patterns patrol -> investigate -> combat - perception event stores current stimulus and last-known location/time. - behavior tree priorities or statetree transitions own mode selection. - patrol follows authored points/spline goals through navmesh, not direct spline locomotion through obstacles. - investigate moves to last-known location, performs a bounded search, then clears/ages state. - combat chooses an action/position; interruption aborts lower-priority movement cleanly. ranged cover selection 1. generate a bounded candidate set around the querier/target. 2. filter unreachable, exposed, occupied, too-close/far, or invalid-team candidates. 3. score path cost, line of sight, distance band, spacing, and tactical direction. 4. choose best or controlled random top percentile. 5. reserve the position if multiple agents compete. 6. revalidate on arrival and use a cooldown before re-querying. eqs finds a candidate; it does not own the combat state, path lifecycle, or reservation by itself. door/ladder/jump - nav link expresses connectivity and direction. - link traversal task owns door claim/open, alignment, animation/root motion, collision changes, and resume. - abort closes/releases/restores state safely. - the destination cell and landing navigation must be loaded before traversal. smart object activity - query a bounded set at a modest interval/event. - claim before committing movement. - move to the slot transform with appropriate filter. - use returned behavior definition to execute the interactor-owned behavior. - release in one cleanup path shared by success/failure/abort/death. large-world agents - server keeps only design-required agents fully simulated. - streaming and ai significance/lifetime policies agree. - static/streamed navmesh is preferred; use dynamic/invoker generation only where world changes require it. - world partition navmesh remains experimental and needs a fallback/shipping review. - durable world state survives actor unload; controllers/tasks/claims do not assume cells remain loaded. crowd through a choke point - use one avoidance system. - spread destinations and approach slots. - keep agent radius/corridor valid; do not shrink navmesh agent settings below bodies. - add lanes, queue smart objects, token/capacity control, or encounter scheduling when geometry cannot support simultaneous flow. - stress above expected population and record deadlocks, arrival time, and cpu. acceptance for any behavior - correct under success, failure, abort, unload, and death; - explainable in debugger from observation through action; - no authoritative client-only decisions; - deterministic where design requires it and varied where repetition should be hidden; - meets reaction-quality and frame budgets at worst population on target hardware."},{"slug":"perception-eqs","file":"perception-eqs.md","title":"AI Perception and EQS","rawMarkdown":"# AI Perception and EQS\n\n## AI Perception setup\n\nPlace `AIPerceptionComponent` on the authoritative AI owner, commonly the AIController. Add only required sense configs and select a Dominant Sense when location resolution needs it.\n\n### Sight\n\n- `Sight Radius`: range at which an unseen target can begin perception.\n- `Lose Sight Radius`: hysteresis range for losing an already seen target; keep it at least as large as Sight Radius.\n- `Peripheral Vision Half Angle Degrees`: angle from the forward vector, not total cone width.\n- `Auto Success Range from Last Seen Location`: retains sight within a local region; use only if it matches the fiction.\n- Affiliation is fully defined through team interfaces/C++; Blueprint-only projects commonly detect neutrals and filter through tags/team logic.\n\n### Hearing\n\nConfigure range/affiliation and emit explicit `Report Noise Event` data with location, loudness, instigator, and tag as required. Audio playback alone is not automatically a gameplay hearing stimulus.\n\n### Memory\n\n`Max Age` controls stimulus aging; `0` means it never expires. To actually forget stale actors through the Perception system, enable `Project Settings > Engine > AI System > Forget Stale Actors`. Keep last-known position/time and “currently sensed” as distinct state.\n\nUse `AIPerceptionStimuliSourceComponent` or registration APIs for designated sources. Unregister runtime sources when their lifetime ends.\n\n## Perception event pattern\n\n1. Receive `OnTargetPerceptionUpdated`/appropriate batched event.\n2. Validate actor and stimulus sense/success.\n3. Update observation data and timestamp.\n4. Let decision logic choose whether the actor becomes a threat/target.\n5. On loss/expiration, preserve or clear last-known state according to design.\n6. Rate-limit expensive follow-up queries across populations.\n\n## EQS boundary\n\nEQS generates candidate Actors/locations, then Tests filter and score them relative to Contexts. Use it for “best valid option,” not for direct known facts.\n\nWorkflow:\n\n1. Define the smallest candidate Generator/domain.\n2. Supply explicit Contexts: querier, target, squad, objective, custom location.\n3. Apply hard invalidity as filters.\n4. Score surviving candidates with named, normalized design criteria.\n5. Select a deliberate run mode: best, random from top 5%, random from top 25%, or all matching.\n6. Handle no-result and stale-result cases.\n7. Cache/reuse only while inputs remain valid.\n\nCurrent UE 5.8 documentation still calls EQS experimental. Bound candidate count, trace/path tests, query frequency, and simultaneous agents. Use an `EQSTestingPawn` for editor visualization, but clear its Query Template while editing expensive queries to avoid continuous heavy updates.\n\n## Debugging\n\n- Gameplay Debugger: apostrophe, Perception on Numpad `4`; EQS category when executing.\n- EQS Testing Pawn: blue failed/filtered candidates; green-to-red scored desirability.\n- Record query template, owner, contexts, named parameters, run mode, candidate counts, duration, result, and failure reason.\n\nPerception/EQS do not replicate internal truth automatically. Run authoritative decisions on the server and replicate resulting gameplay state.\n","webMarkdown":"## AI Perception setup\n\nPlace `AIPerceptionComponent` on the authoritative AI owner, commonly the AIController. Add only required sense configs and select a Dominant Sense when location resolution needs it.\n\n### Sight\n\n- `Sight Radius`: range at which an unseen target can begin perception.\n- `Lose Sight Radius`: hysteresis range for losing an already seen target; keep it at least as large as Sight Radius.\n- `Peripheral Vision Half Angle Degrees`: angle from the forward vector, not total cone width.\n- `Auto Success Range from Last Seen Location`: retains sight within a local region; use only if it matches the fiction.\n- Affiliation is fully defined through team interfaces/C++; Blueprint-only projects commonly detect neutrals and filter through tags/team logic.\n\n### Hearing\n\nConfigure range/affiliation and emit explicit `Report Noise Event` data with location, loudness, instigator, and tag as required. Audio playback alone is not automatically a gameplay hearing stimulus.\n\n### Memory\n\n`Max Age` controls stimulus aging; `0` means it never expires. To actually forget stale actors through the Perception system, enable `Project Settings > Engine > AI System > Forget Stale Actors`. Keep last-known position/time and “currently sensed” as distinct state.\n\nUse `AIPerceptionStimuliSourceComponent` or registration APIs for designated sources. Unregister runtime sources when their lifetime ends.\n\n## Perception event pattern\n\n1. Receive `OnTargetPerceptionUpdated`/appropriate batched event.\n2. Validate actor and stimulus sense/success.\n3. Update observation data and timestamp.\n4. Let decision logic choose whether the actor becomes a threat/target.\n5. On loss/expiration, preserve or clear last-known state according to design.\n6. Rate-limit expensive follow-up queries across populations.\n\n## EQS boundary\n\nEQS generates candidate Actors/locations, then Tests filter and score them relative to Contexts. Use it for “best valid option,” not for direct known facts.\n\nWorkflow:\n\n1. Define the smallest candidate Generator/domain.\n2. Supply explicit Contexts: querier, target, squad, objective, custom location.\n3. Apply hard invalidity as filters.\n4. Score surviving candidates with named, normalized design criteria.\n5. Select a deliberate run mode: best, random from top 5%, random from top 25%, or all matching.\n6. Handle no-result and stale-result cases.\n7. Cache/reuse only while inputs remain valid.\n\nCurrent UE 5.8 documentation still calls EQS experimental. Bound candidate count, trace/path tests, query frequency, and simultaneous agents. Use an `EQSTestingPawn` for editor visualization, but clear its Query Template while editing expensive queries to avoid continuous heavy updates.\n\n## Debugging\n\n- Gameplay Debugger: apostrophe, Perception on Numpad `4`; EQS category when executing.\n- EQS Testing Pawn: blue failed/filtered candidates; green-to-red scored desirability.\n- Record query template, owner, contexts, named parameters, run mode, candidate counts, duration, result, and failure reason.\n\nPerception/EQS do not replicate internal truth automatically. Run authoritative decisions on the server and replicate resulting gameplay state.\n","searchText":"ai perception and eqs ai perception setup place aiperceptioncomponent on the authoritative ai owner, commonly the aicontroller. add only required sense configs and select a dominant sense when location resolution needs it. sight - sight radius: range at which an unseen target can begin perception. - lose sight radius: hysteresis range for losing an already seen target; keep it at least as large as sight radius. - peripheral vision half angle degrees: angle from the forward vector, not total cone width. - auto success range from last seen location: retains sight within a local region; use only if it matches the fiction. - affiliation is fully defined through team interfaces/c++; blueprint-only projects commonly detect neutrals and filter through tags/team logic. hearing configure range/affiliation and emit explicit report noise event data with location, loudness, instigator, and tag as required. audio playback alone is not automatically a gameplay hearing stimulus. memory max age controls stimulus aging; 0 means it never expires. to actually forget stale actors through the perception system, enable project settings > engine > ai system > forget stale actors. keep last-known position/time and “currently sensed” as distinct state. use aiperceptionstimulisourcecomponent or registration apis for designated sources. unregister runtime sources when their lifetime ends. perception event pattern 1. receive ontargetperceptionupdated/appropriate batched event. 2. validate actor and stimulus sense/success. 3. update observation data and timestamp. 4. let decision logic choose whether the actor becomes a threat/target. 5. on loss/expiration, preserve or clear last-known state according to design. 6. rate-limit expensive follow-up queries across populations. eqs boundary eqs generates candidate actors/locations, then tests filter and score them relative to contexts. use it for “best valid option,” not for direct known facts. workflow: 1. define the smallest candidate generator/domain. 2. supply explicit contexts: querier, target, squad, objective, custom location. 3. apply hard invalidity as filters. 4. score surviving candidates with named, normalized design criteria. 5. select a deliberate run mode: best, random from top 5%, random from top 25%, or all matching. 6. handle no-result and stale-result cases. 7. cache/reuse only while inputs remain valid. current ue 5.8 documentation still calls eqs experimental. bound candidate count, trace/path tests, query frequency, and simultaneous agents. use an eqstestingpawn for editor visualization, but clear its query template while editing expensive queries to avoid continuous heavy updates. debugging - gameplay debugger: apostrophe, perception on numpad 4; eqs category when executing. - eqs testing pawn: blue failed/filtered candidates; green-to-red scored desirability. - record query template, owner, contexts, named parameters, run mode, candidate counts, duration, result, and failure reason. perception/eqs do not replicate internal truth automatically. run authoritative decisions on the server and replicate resulting gameplay state."},{"slug":"smart-objects-crowds","file":"smart-objects-crowds.md","title":"Smart Objects and crowd avoidance","rawMarkdown":"# Smart Objects and crowd avoidance\n\n## Smart Object boundary\n\nSmart Objects describe spatial interaction opportunities and reserve Slots. They do **not** contain the execution logic; each interactor implements the returned Behavior Definition.\n\nCore pieces:\n\n- SmartObject subsystem and spatial database;\n- SmartObject component on the world actor;\n- Smart Object Definition asset shared across instances;\n- Slots with transforms, filters/tags, and behavior definitions;\n- optional Persistent Collection influencing runtime-instance lifetime.\n\n## Claim lifecycle\n\n```text\nFind matching objects -> choose result -> claim slot -> validate handle\n-> navigate to slot -> use/occupy -> execute behavior -> release\n```\n\nRules:\n\n- Search with bounded area, activity tags, user tags, behavior class, and other filters.\n- A search result is not a reservation; always validate the returned Claim Handle.\n- Revalidate slot/location and object state before/after approach.\n- Release on success, failure, abort, death, possession change, timeout, and task/state exit.\n- Handle `OnSlotInvalidatedDelegate`; the object may disable/unload/destroy while claimed or occupied.\n- Keep durable gameplay outcome outside the transient claim.\n\nA Persistent Collection keeps included Smart Object runtime instances in the simulation even if source actors stream out. That is a lifetime decision, not permission to execute interaction against unloaded visuals/collision.\n\n## RVO versus Detour Crowd\n\n| System | Use | Constraint |\n|---|---|---|\n| RVO | CharacterMovement-local velocity avoidance, including without NavMesh | Character only, less configurable, can push agents outside NavMesh |\n| Detour Crowd | path-corridor-aware crowd avoidance for Pawns | fixed Max Agents/Max Agent Radius and Crowd Manager tuning |\n\nEpic states the two systems work independently and should be used exclusively. Do not enable both for one agent.\n\n## Crowd tuning\n\nStart without avoidance and prove paths. Then add one system and test:\n\n- maximum simultaneous agents and radius support;\n- consideration radius/neighbors and wall samples;\n- corridor width, opposing flows, doors, corners, merges, and destinations;\n- separation/collision resolution and movement-component interaction;\n- agents leaving NavMesh, deadlocks, oscillation, and arrival congestion;\n- CPU cost at worst population.\n\nCrowd avoidance cannot solve a level whose doorway is narrower than the throughput the encounter requires. Fix geometry, lane design, destination distribution, or scheduling when appropriate.\n\n## Smart Object + crowd pattern\n\nReserve before entering a congested approach, expose one Slot per true simultaneous user, move to a reachable slot transform, queue outside the interaction corridor, and release immediately on cancellation. Do not let every waiting agent continuously re-query every object.\n","webMarkdown":"## Smart Object boundary\n\nSmart Objects describe spatial interaction opportunities and reserve Slots. They do **not** contain the execution logic; each interactor implements the returned Behavior Definition.\n\nCore pieces:\n\n- SmartObject subsystem and spatial database;\n- SmartObject component on the world actor;\n- Smart Object Definition asset shared across instances;\n- Slots with transforms, filters/tags, and behavior definitions;\n- optional Persistent Collection influencing runtime-instance lifetime.\n\n## Claim lifecycle\n\n```text\nFind matching objects -> choose result -> claim slot -> validate handle\n-> navigate to slot -> use/occupy -> execute behavior -> release\n```\n\nRules:\n\n- Search with bounded area, activity tags, user tags, behavior class, and other filters.\n- A search result is not a reservation; always validate the returned Claim Handle.\n- Revalidate slot/location and object state before/after approach.\n- Release on success, failure, abort, death, possession change, timeout, and task/state exit.\n- Handle `OnSlotInvalidatedDelegate`; the object may disable/unload/destroy while claimed or occupied.\n- Keep durable gameplay outcome outside the transient claim.\n\nA Persistent Collection keeps included Smart Object runtime instances in the simulation even if source actors stream out. That is a lifetime decision, not permission to execute interaction against unloaded visuals/collision.\n\n## RVO versus Detour Crowd\n\n| System | Use | Constraint |\n|---|---|---|\n| RVO | CharacterMovement-local velocity avoidance, including without NavMesh | Character only, less configurable, can push agents outside NavMesh |\n| Detour Crowd | path-corridor-aware crowd avoidance for Pawns | fixed Max Agents/Max Agent Radius and Crowd Manager tuning |\n\nEpic states the two systems work independently and should be used exclusively. Do not enable both for one agent.\n\n## Crowd tuning\n\nStart without avoidance and prove paths. Then add one system and test:\n\n- maximum simultaneous agents and radius support;\n- consideration radius/neighbors and wall samples;\n- corridor width, opposing flows, doors, corners, merges, and destinations;\n- separation/collision resolution and movement-component interaction;\n- agents leaving NavMesh, deadlocks, oscillation, and arrival congestion;\n- CPU cost at worst population.\n\nCrowd avoidance cannot solve a level whose doorway is narrower than the throughput the encounter requires. Fix geometry, lane design, destination distribution, or scheduling when appropriate.\n\n## Smart Object + crowd pattern\n\nReserve before entering a congested approach, expose one Slot per true simultaneous user, move to a reachable slot transform, queue outside the interaction corridor, and release immediately on cancellation. Do not let every waiting agent continuously re-query every object.\n","searchText":"smart objects and crowd avoidance smart object boundary smart objects describe spatial interaction opportunities and reserve slots. they do not contain the execution logic; each interactor implements the returned behavior definition. core pieces: - smartobject subsystem and spatial database; - smartobject component on the world actor; - smart object definition asset shared across instances; - slots with transforms, filters/tags, and behavior definitions; - optional persistent collection influencing runtime-instance lifetime. claim lifecycle text find matching objects -> choose result -> claim slot -> validate handle -> navigate to slot -> use/occupy -> execute behavior -> release rules: - search with bounded area, activity tags, user tags, behavior class, and other filters. - a search result is not a reservation; always validate the returned claim handle. - revalidate slot/location and object state before/after approach. - release on success, failure, abort, death, possession change, timeout, and task/state exit. - handle onslotinvalidateddelegate; the object may disable/unload/destroy while claimed or occupied. - keep durable gameplay outcome outside the transient claim. a persistent collection keeps included smart object runtime instances in the simulation even if source actors stream out. that is a lifetime decision, not permission to execute interaction against unloaded visuals/collision. rvo versus detour crowd | system | use | constraint | |---|---|---| | rvo | charactermovement-local velocity avoidance, including without navmesh | character only, less configurable, can push agents outside navmesh | | detour crowd | path-corridor-aware crowd avoidance for pawns | fixed max agents/max agent radius and crowd manager tuning | epic states the two systems work independently and should be used exclusively. do not enable both for one agent. crowd tuning start without avoidance and prove paths. then add one system and test: - maximum simultaneous agents and radius support; - consideration radius/neighbors and wall samples; - corridor width, opposing flows, doors, corners, merges, and destinations; - separation/collision resolution and movement-component interaction; - agents leaving navmesh, deadlocks, oscillation, and arrival congestion; - cpu cost at worst population. crowd avoidance cannot solve a level whose doorway is narrower than the throughput the encounter requires. fix geometry, lane design, destination distribution, or scheduling when appropriate. smart object + crowd pattern reserve before entering a congested approach, expose one slot per true simultaneous user, move to a reachable slot transform, queue outside the interaction corridor, and release immediately on cancellation. do not let every waiting agent continuously re-query every object."},{"slug":"sources","file":"sources.md","title":"UE 5.8 primary sources","rawMarkdown":"# UE 5.8 primary sources\n\nChecked against Epic's Unreal Engine 5.8 documentation on 2026-07-19.\n\n## Navigation\n\n- [Navigation System](https://dev.epicgames.com/documentation/en-us/unreal-engine/navigation-system-in-unreal-engine)\n- [Basic Navigation](https://dev.epicgames.com/documentation/unreal-engine/basic-navigation-in-unreal-engine?lang=en-US)\n- [Navigation Mesh Settings](https://dev.epicgames.com/documentation/unreal-engine/navigation-mesh-settings-in-the-unreal-engine-project-settings?lang=en-US)\n- [Navigation Mesh Resolutions](https://dev.epicgames.com/documentation/unreal-engine/navigation-mesh-resolutions-user-guide?lang=en-US)\n- [Modifying the Navigation Mesh](https://dev.epicgames.com/documentation/unreal-engine/overview-of-how-to-modify-the-navigation-mesh-in-unreal-engine?lang=en-US)\n- [Optimizing NavMesh Generation](https://dev.epicgames.com/documentation/unreal-engine/optimizing-navigation-mesh-generation-speed-in-unreal-engine)\n- [Navigation Invokers](https://dev.epicgames.com/documentation/unreal-engine/using-navigation-invokers-in-unreal-engine?lang=en-US)\n- [World Partitioned Navigation Mesh](https://dev.epicgames.com/documentation/unreal-engine/world-partitioned-navigation-mesh?lang=en-US)\n\n## Decisions and queries\n\n- [Behavior Tree Overview](https://dev.epicgames.com/documentation/unreal-engine/behavior-tree-in-unreal-engine---overview?lang=en-US)\n- [Behavior Tree User Guide](https://dev.epicgames.com/documentation/unreal-engine/behavior-tree-in-unreal-engine---user-guide)\n- [Behavior Tree Decorators](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-behavior-tree-node-reference-decorators)\n- [Behavior Tree Services](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-behavior-tree-node-reference-services)\n- [StateTree Overview](https://dev.epicgames.com/documentation/unreal-engine/overview-of-state-tree-in-unreal-engine?lang=en-US)\n- [StateTree Debugger](https://dev.epicgames.com/documentation/unreal-engine/statetree-debugger-quick-start-guide)\n- [AI Perception](https://dev.epicgames.com/documentation/unreal-engine/ai-perception-in-unreal-engine?lang=en-US)\n- [Environment Query System](https://dev.epicgames.com/documentation/en-us/unreal-engine/environment-query-system-in-unreal-engine)\n- [EQS Testing Pawn](https://dev.epicgames.com/documentation/en-us/unreal-engine/environment-query-testing-pawn-in-unreal-engine)\n\n## Interaction, crowds, and diagnosis\n\n- [Smart Objects Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/smart-objects-in-unreal-engine---overview)\n- [Avoidance with the Navigation System](https://dev.epicgames.com/documentation/unreal-engine/using-avoidance-with-the-navigation-system-in-unreal-engine)\n- [Crowd Manager Settings](https://dev.epicgames.com/documentation/en-us/unreal-engine/crowd-manager-settings-in-the-the-unreal-engine-project-settings)\n- [AI Debugging](https://dev.epicgames.com/documentation/unreal-engine/ai-debugging-in-unreal-engine?lang=en-US)\n- [Gameplay Debugger](https://dev.epicgames.com/documentation/unreal-engine/using-the-gameplay-debugger-in-unreal-engine)\n\n## Maturity notes\n\n- Core Recast NavMesh, Behavior Trees, StateTree, AI Perception, Smart Objects, and avoidance workflows have current 5.8 documentation.\n- World Partitioned Navigation Mesh is explicitly Experimental.\n- The current EQS Testing Pawn guide still refers to the experimental nature of EQS; keep EQS bounded and validated.\n- Do not infer that all AI systems replicate or run on clients. Authoritative gameplay AI remains a project/network architecture decision.\n\nPrefer the 5.8 page, installed engine source, console help, and working sample behavior over remembered earlier-version defaults.\n","webMarkdown":"Checked against Epic's Unreal Engine 5.8 documentation on 2026-07-19.\n\n## Navigation\n\n- [Navigation System](https://dev.epicgames.com/documentation/en-us/unreal-engine/navigation-system-in-unreal-engine)\n- [Basic Navigation](https://dev.epicgames.com/documentation/unreal-engine/basic-navigation-in-unreal-engine?lang=en-US)\n- [Navigation Mesh Settings](https://dev.epicgames.com/documentation/unreal-engine/navigation-mesh-settings-in-the-unreal-engine-project-settings?lang=en-US)\n- [Navigation Mesh Resolutions](https://dev.epicgames.com/documentation/unreal-engine/navigation-mesh-resolutions-user-guide?lang=en-US)\n- [Modifying the Navigation Mesh](https://dev.epicgames.com/documentation/unreal-engine/overview-of-how-to-modify-the-navigation-mesh-in-unreal-engine?lang=en-US)\n- [Optimizing NavMesh Generation](https://dev.epicgames.com/documentation/unreal-engine/optimizing-navigation-mesh-generation-speed-in-unreal-engine)\n- [Navigation Invokers](https://dev.epicgames.com/documentation/unreal-engine/using-navigation-invokers-in-unreal-engine?lang=en-US)\n- [World Partitioned Navigation Mesh](https://dev.epicgames.com/documentation/unreal-engine/world-partitioned-navigation-mesh?lang=en-US)\n\n## Decisions and queries\n\n- [Behavior Tree Overview](https://dev.epicgames.com/documentation/unreal-engine/behavior-tree-in-unreal-engine---overview?lang=en-US)\n- [Behavior Tree User Guide](https://dev.epicgames.com/documentation/unreal-engine/behavior-tree-in-unreal-engine---user-guide)\n- [Behavior Tree Decorators](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-behavior-tree-node-reference-decorators)\n- [Behavior Tree Services](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-behavior-tree-node-reference-services)\n- [StateTree Overview](https://dev.epicgames.com/documentation/unreal-engine/overview-of-state-tree-in-unreal-engine?lang=en-US)\n- [StateTree Debugger](https://dev.epicgames.com/documentation/unreal-engine/statetree-debugger-quick-start-guide)\n- [AI Perception](https://dev.epicgames.com/documentation/unreal-engine/ai-perception-in-unreal-engine?lang=en-US)\n- [Environment Query System](https://dev.epicgames.com/documentation/en-us/unreal-engine/environment-query-system-in-unreal-engine)\n- [EQS Testing Pawn](https://dev.epicgames.com/documentation/en-us/unreal-engine/environment-query-testing-pawn-in-unreal-engine)\n\n## Interaction, crowds, and diagnosis\n\n- [Smart Objects Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/smart-objects-in-unreal-engine---overview)\n- [Avoidance with the Navigation System](https://dev.epicgames.com/documentation/unreal-engine/using-avoidance-with-the-navigation-system-in-unreal-engine)\n- [Crowd Manager Settings](https://dev.epicgames.com/documentation/en-us/unreal-engine/crowd-manager-settings-in-the-the-unreal-engine-project-settings)\n- [AI Debugging](https://dev.epicgames.com/documentation/unreal-engine/ai-debugging-in-unreal-engine?lang=en-US)\n- [Gameplay Debugger](https://dev.epicgames.com/documentation/unreal-engine/using-the-gameplay-debugger-in-unreal-engine)\n\n## Maturity notes\n\n- Core Recast NavMesh, Behavior Trees, StateTree, AI Perception, Smart Objects, and avoidance workflows have current 5.8 documentation.\n- World Partitioned Navigation Mesh is explicitly Experimental.\n- The current EQS Testing Pawn guide still refers to the experimental nature of EQS; keep EQS bounded and validated.\n- Do not infer that all AI systems replicate or run on clients. Authoritative gameplay AI remains a project/network architecture decision.\n\nPrefer the 5.8 page, installed engine source, console help, and working sample behavior over remembered earlier-version defaults.\n","searchText":"ue 5.8 primary sources checked against epic's unreal engine 5.8 documentation on 2026-07-19. navigation - navigation system - basic navigation - navigation mesh settings - navigation mesh resolutions - modifying the navigation mesh - optimizing navmesh generation - navigation invokers - world partitioned navigation mesh decisions and queries - behavior tree overview - behavior tree user guide - behavior tree decorators - behavior tree services - statetree overview - statetree debugger - ai perception - environment query system - eqs testing pawn interaction, crowds, and diagnosis - smart objects overview - avoidance with the navigation system - crowd manager settings - ai debugging - gameplay debugger maturity notes - core recast navmesh, behavior trees, statetree, ai perception, smart objects, and avoidance workflows have current 5.8 documentation. - world partitioned navigation mesh is explicitly experimental. - the current eqs testing pawn guide still refers to the experimental nature of eqs; keep eqs bounded and validated. - do not infer that all ai systems replicate or run on clients. authoritative gameplay ai remains a project/network architecture decision. prefer the 5.8 page, installed engine source, console help, and working sample behavior over remembered earlier-version defaults."},{"slug":"statetree","file":"statetree.md","title":"StateTree","rawMarkdown":"# StateTree\n\n## Execution model\n\nStateTree combines hierarchical state-machine transitions with tree-based state selection.\n\n- Selection evaluates Enter Conditions from the target/root path toward a selectable leaf.\n- The selected leaf and all parent states on its active path become active.\n- Tasks on all active states start and run concurrently.\n- The first completing Task can trigger completion-based transition evaluation.\n- Transitions are the only way to change the selected state.\n\nDo not place sequential actions as sibling Tasks in one state. Use child states and `Next` transitions for ordered steps.\n\n## Data roles\n\n- **Parameters**: configured per asset/instance inputs.\n- **Context/External Data**: required owner, actor, subsystem, or component data supplied by the schema/runtime.\n- **Evaluators**: expose/update data used by states, tasks, conditions, and transitions.\n- **Tasks**: perform bounded work while their state is active.\n- **Conditions**: gate state entry or transitions.\n\nChoose the correct schema for the owner, such as an Actor/Component-oriented schema. Fail early when required external data is absent.\n\n## Authoring workflow\n\n1. Define top-level modes with mutually understandable ownership: Idle, Patrol, Alert, Combat, Disabled.\n2. Put shared always-active responsibilities on parent states only when concurrency is intended.\n3. Decompose ordered behavior into child states and success/failure/`Next` transitions.\n4. Make transition priority and destination explicit.\n5. Expose typed data once and bind deliberately; avoid long invisible binding chains.\n6. Define enter/exit/cancel cleanup for moves, delegates, abilities, animation, and Smart Object claims.\n7. Use linked/subtrees only when their interface is stable and reuse is real.\n\n## Common failure patterns\n\n- **Sequence completes instantly/wrong action wins**: sibling tasks ran concurrently and one finished first.\n- **No state selected**: Enter Conditions reject every path or required context is missing.\n- **Transition loop**: a condition remains true on entry and immediately selects again.\n- **Stale data**: evaluator/binding lifetime differs from the assumed update moment.\n- **Action survives state exit**: task failed to cancel latent work or release resources.\n\n## Debugging\n\nUse the StateTree Debugger (`Window > Debugger` in the asset editor), instance selection, traces, state/task breakpoints, and recorded transitions. The debugger can consume Trace Analyzer data from Editor, Client, and Dedicated Server processes.\n\nAcceptance requires the active state path, task lifetimes, data values, transition cause, and cleanup to match the authored contract under interruption and failure.\n","webMarkdown":"## Execution model\n\nStateTree combines hierarchical state-machine transitions with tree-based state selection.\n\n- Selection evaluates Enter Conditions from the target/root path toward a selectable leaf.\n- The selected leaf and all parent states on its active path become active.\n- Tasks on all active states start and run concurrently.\n- The first completing Task can trigger completion-based transition evaluation.\n- Transitions are the only way to change the selected state.\n\nDo not place sequential actions as sibling Tasks in one state. Use child states and `Next` transitions for ordered steps.\n\n## Data roles\n\n- **Parameters**: configured per asset/instance inputs.\n- **Context/External Data**: required owner, actor, subsystem, or component data supplied by the schema/runtime.\n- **Evaluators**: expose/update data used by states, tasks, conditions, and transitions.\n- **Tasks**: perform bounded work while their state is active.\n- **Conditions**: gate state entry or transitions.\n\nChoose the correct schema for the owner, such as an Actor/Component-oriented schema. Fail early when required external data is absent.\n\n## Authoring workflow\n\n1. Define top-level modes with mutually understandable ownership: Idle, Patrol, Alert, Combat, Disabled.\n2. Put shared always-active responsibilities on parent states only when concurrency is intended.\n3. Decompose ordered behavior into child states and success/failure/`Next` transitions.\n4. Make transition priority and destination explicit.\n5. Expose typed data once and bind deliberately; avoid long invisible binding chains.\n6. Define enter/exit/cancel cleanup for moves, delegates, abilities, animation, and Smart Object claims.\n7. Use linked/subtrees only when their interface is stable and reuse is real.\n\n## Common failure patterns\n\n- **Sequence completes instantly/wrong action wins**: sibling tasks ran concurrently and one finished first.\n- **No state selected**: Enter Conditions reject every path or required context is missing.\n- **Transition loop**: a condition remains true on entry and immediately selects again.\n- **Stale data**: evaluator/binding lifetime differs from the assumed update moment.\n- **Action survives state exit**: task failed to cancel latent work or release resources.\n\n## Debugging\n\nUse the StateTree Debugger (`Window > Debugger` in the asset editor), instance selection, traces, state/task breakpoints, and recorded transitions. The debugger can consume Trace Analyzer data from Editor, Client, and Dedicated Server processes.\n\nAcceptance requires the active state path, task lifetimes, data values, transition cause, and cleanup to match the authored contract under interruption and failure.\n","searchText":"statetree execution model statetree combines hierarchical state-machine transitions with tree-based state selection. - selection evaluates enter conditions from the target/root path toward a selectable leaf. - the selected leaf and all parent states on its active path become active. - tasks on all active states start and run concurrently. - the first completing task can trigger completion-based transition evaluation. - transitions are the only way to change the selected state. do not place sequential actions as sibling tasks in one state. use child states and next transitions for ordered steps. data roles - parameters: configured per asset/instance inputs. - context/external data: required owner, actor, subsystem, or component data supplied by the schema/runtime. - evaluators: expose/update data used by states, tasks, conditions, and transitions. - tasks: perform bounded work while their state is active. - conditions: gate state entry or transitions. choose the correct schema for the owner, such as an actor/component-oriented schema. fail early when required external data is absent. authoring workflow 1. define top-level modes with mutually understandable ownership: idle, patrol, alert, combat, disabled. 2. put shared always-active responsibilities on parent states only when concurrency is intended. 3. decompose ordered behavior into child states and success/failure/next transitions. 4. make transition priority and destination explicit. 5. expose typed data once and bind deliberately; avoid long invisible binding chains. 6. define enter/exit/cancel cleanup for moves, delegates, abilities, animation, and smart object claims. 7. use linked/subtrees only when their interface is stable and reuse is real. common failure patterns - sequence completes instantly/wrong action wins: sibling tasks ran concurrently and one finished first. - no state selected: enter conditions reject every path or required context is missing. - transition loop: a condition remains true on entry and immediately selects again. - stale data: evaluator/binding lifetime differs from the assumed update moment. - action survives state exit: task failed to cancel latent work or release resources. debugging use the statetree debugger (window > debugger in the asset editor), instance selection, traces, state/task breakpoints, and recorded transitions. the debugger can consume trace analyzer data from editor, client, and dedicated server processes. acceptance requires the active state path, task lifetimes, data values, transition cause, and cleanup to match the authored contract under interruption and failure."},{"slug":"system-selector-architecture","file":"system-selector-architecture.md","title":"System selector and architecture","rawMarkdown":"# System selector and architecture\n\n## Layer the problem\n\n```text\nWorld collision -> NavMesh/path graph -> Path following/movement\nStimuli/events -> Perception/memory -> Decision architecture\nWorld candidates -> EQS/direct query -> chosen goal\nInteraction opportunities -> Smart Object claim -> interactor behavior\nNearby moving agents -> RVO or Detour Crowd -> local velocity adjustment\n```\n\nA bug belongs to one layer until evidence shows otherwise. Do not “fix AI” by changing several layers together.\n\n## Decision selector\n\n| Need | Default |\n|---|---|\n| One or two simple modes | component/enum/timers/events |\n| Reactive priorities, conditions, abort-to-higher-priority behavior | Behavior Tree + Blackboard |\n| Explicit hierarchical state, transitions, sequences, shared task data | StateTree |\n| Large data-oriented crowds | Evaluate Mass/StateTree architecture separately; ordinary Actor AI may not scale |\n\nBehavior Tree and StateTree can coexist at a system boundary, but do not duplicate the same state machine in both. Assign one owner and exchange compact state/events.\n\n## Query selector\n\n- Direct known actor/location: use the known reference or subsystem lookup.\n- Reachable random point: navigation query.\n- “Best cover/attack/resource point” from multiple constraints: EQS.\n- Reusable reservable activity: Smart Object query/claim.\n- Long-range route: NavMesh pathfinding.\n- Short-range agent avoidance: RVO or Detour Crowd.\n\n## Authority model\n\nIn networked games:\n\n- run authoritative AI controller, decisions, path requests, Smart Object claims, damage, and gameplay state on the server;\n- replicate the Pawn and observable gameplay state/animation inputs as designed;\n- keep client-only cosmetic prediction/presentation non-authoritative;\n- do not replicate entire Blackboards or internal decision graphs by default.\n\nRoute replication details to `$unreal-replication`.\n\n## Data ownership\n\n- Controller owns decision/path-following concerns tied to possession.\n- Pawn/Character owns body, movement component, collision, animation-facing state.\n- Blackboard holds Behavior Tree working memory, not universal game truth.\n- StateTree context/external data supplies required owner/world data; Parameters configure instances.\n- Subsystems/game state own durable shared facts.\n- Perception stores observations; gameplay systems decide what those observations mean.\n\n## Update policy\n\nPrefer event-driven updates for target acquired/lost, damage, state changes, path completion, Smart Object invalidation, and Blackboard changes. Use bounded timers/services for genuinely periodic sensing or scoring. Stagger expensive work across agents and treat reaction delay as a design variable, not merely a performance defect.\n","webMarkdown":"## Layer the problem\n\n```text\nWorld collision -> NavMesh/path graph -> Path following/movement\nStimuli/events -> Perception/memory -> Decision architecture\nWorld candidates -> EQS/direct query -> chosen goal\nInteraction opportunities -> Smart Object claim -> interactor behavior\nNearby moving agents -> RVO or Detour Crowd -> local velocity adjustment\n```\n\nA bug belongs to one layer until evidence shows otherwise. Do not “fix AI” by changing several layers together.\n\n## Decision selector\n\n| Need | Default |\n|---|---|\n| One or two simple modes | component/enum/timers/events |\n| Reactive priorities, conditions, abort-to-higher-priority behavior | Behavior Tree + Blackboard |\n| Explicit hierarchical state, transitions, sequences, shared task data | StateTree |\n| Large data-oriented crowds | Evaluate Mass/StateTree architecture separately; ordinary Actor AI may not scale |\n\nBehavior Tree and StateTree can coexist at a system boundary, but do not duplicate the same state machine in both. Assign one owner and exchange compact state/events.\n\n## Query selector\n\n- Direct known actor/location: use the known reference or subsystem lookup.\n- Reachable random point: navigation query.\n- “Best cover/attack/resource point” from multiple constraints: EQS.\n- Reusable reservable activity: Smart Object query/claim.\n- Long-range route: NavMesh pathfinding.\n- Short-range agent avoidance: RVO or Detour Crowd.\n\n## Authority model\n\nIn networked games:\n\n- run authoritative AI controller, decisions, path requests, Smart Object claims, damage, and gameplay state on the server;\n- replicate the Pawn and observable gameplay state/animation inputs as designed;\n- keep client-only cosmetic prediction/presentation non-authoritative;\n- do not replicate entire Blackboards or internal decision graphs by default.\n\nRoute replication details to `$unreal-replication`.\n\n## Data ownership\n\n- Controller owns decision/path-following concerns tied to possession.\n- Pawn/Character owns body, movement component, collision, animation-facing state.\n- Blackboard holds Behavior Tree working memory, not universal game truth.\n- StateTree context/external data supplies required owner/world data; Parameters configure instances.\n- Subsystems/game state own durable shared facts.\n- Perception stores observations; gameplay systems decide what those observations mean.\n\n## Update policy\n\nPrefer event-driven updates for target acquired/lost, damage, state changes, path completion, Smart Object invalidation, and Blackboard changes. Use bounded timers/services for genuinely periodic sensing or scoring. Stagger expensive work across agents and treat reaction delay as a design variable, not merely a performance defect.\n","searchText":"system selector and architecture layer the problem text world collision -> navmesh/path graph -> path following/movement stimuli/events -> perception/memory -> decision architecture world candidates -> eqs/direct query -> chosen goal interaction opportunities -> smart object claim -> interactor behavior nearby moving agents -> rvo or detour crowd -> local velocity adjustment a bug belongs to one layer until evidence shows otherwise. do not “fix ai” by changing several layers together. decision selector | need | default | |---|---| | one or two simple modes | component/enum/timers/events | | reactive priorities, conditions, abort-to-higher-priority behavior | behavior tree + blackboard | | explicit hierarchical state, transitions, sequences, shared task data | statetree | | large data-oriented crowds | evaluate mass/statetree architecture separately; ordinary actor ai may not scale | behavior tree and statetree can coexist at a system boundary, but do not duplicate the same state machine in both. assign one owner and exchange compact state/events. query selector - direct known actor/location: use the known reference or subsystem lookup. - reachable random point: navigation query. - “best cover/attack/resource point” from multiple constraints: eqs. - reusable reservable activity: smart object query/claim. - long-range route: navmesh pathfinding. - short-range agent avoidance: rvo or detour crowd. authority model in networked games: - run authoritative ai controller, decisions, path requests, smart object claims, damage, and gameplay state on the server; - replicate the pawn and observable gameplay state/animation inputs as designed; - keep client-only cosmetic prediction/presentation non-authoritative; - do not replicate entire blackboards or internal decision graphs by default. route replication details to $unreal-replication. data ownership - controller owns decision/path-following concerns tied to possession. - pawn/character owns body, movement component, collision, animation-facing state. - blackboard holds behavior tree working memory, not universal game truth. - statetree context/external data supplies required owner/world data; parameters configure instances. - subsystems/game state own durable shared facts. - perception stores observations; gameplay systems decide what those observations mean. update policy prefer event-driven updates for target acquired/lost, damage, state changes, path completion, smart object invalidation, and blackboard changes. use bounded timers/services for genuinely periodic sensing or scoring. stagger expensive work across agents and treat reaction delay as a design variable, not merely a performance defect."}]}
{"slug":"unreal-niagara","name":"unreal-niagara","title":"Unreal 5.8 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.","shortDescription":"Build and optimize Unreal Niagara effects","category":"Rendering & VFX","referenceCount":9,"rawMarkdown":"---\nname: unreal-niagara\ndescription: 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.\n---\n\n# Unreal 5.8 Niagara\n\n## Select the simulation before authoring\n\nRead [`references/system-selector.md`](references/system-selector.md).\n\n- Simple high-count noninteractive effect -> lightweight/stateless emitter candidate.\n- Per-particle game-thread data, events, or CPU-only interfaces -> CPU simulation.\n- Very high particle count with GPU-supported behavior -> GPU simulation.\n- Many repeated gameplay bursts -> shared listener plus Niagara Data Channel candidate.\n- Volumetric grid simulation -> Niagara Fluids only after platform/budget review; bake when possible.\n\nBuild the cheapest representation that preserves the required read, not the most elaborate simulation.\n\n## Execute\n\n1. Define the visual read, duration, scale, camera range, gameplay contract, and target platforms.\n2. Split the effect into semantic emitters; choose renderer and simulation target per emitter.\n3. Establish spawn, initialize, update, render, and completion behavior with built-in modules first.\n4. Expose a small user-parameter contract; keep gameplay authority outside Niagara.\n5. Add collision, events, data interfaces, or Data Channels only for a specific requirement.\n6. Set bounds, warmup/pre-roll assumptions, pooling/reuse, and deactivation behavior.\n7. Add Effect Type and platform scalability/culling rules before content multiplies.\n8. Use Niagara Debugger and target-hardware captures at realistic instance counts and overdraw.\n\nLoad only what applies:\n\n- [`references/architecture-and-stack.md`](references/architecture-and-stack.md)\n- [`references/gameplay-integration.md`](references/gameplay-integration.md)\n- [`references/cpu-gpu-collision-events.md`](references/cpu-gpu-collision-events.md)\n- [`references/data-channels-and-interfaces.md`](references/data-channels-and-interfaces.md)\n- [`references/scalability-and-pooling.md`](references/scalability-and-pooling.md)\n- [`references/recipes.md`](references/recipes.md)\n- [`references/debugging-and-profiling.md`](references/debugging-and-profiling.md)\n\n## Required answer format\n\nReturn:\n\n1. **Visual/gameplay contract** and chosen representation.\n2. **System/emitter architecture**, simulation target, renderers, and module order.\n3. **Spawn/lifetime/completion behavior**.\n4. **User parameters and ownership/update frequency**.\n5. **Collision/event/data-interface assumptions and fallbacks**.\n6. **Bounds, pooling, Effect Type, culling, quality tiers, and platform consequences**.\n7. **Debugger metrics and visual acceptance checks at realistic counts**.\n\n## Hard rules\n\n- Niagara presents effects; authoritative damage, hits, inventory, and progression remain gameplay-owned.\n- Prefer existing modules/templates before custom Scratch Pad or HLSL modules.\n- Choose CPU/GPU simulation from data-access, determinism, event, collision, and scale needs.\n- Set and test bounds. GPU systems can disappear or waste work when bounds are wrong.\n- Every looping system needs an explicit owner and stop/deactivate path.\n- Pool only effects that reset cleanly; verify user parameters and persistent state on reuse.\n- Use Effect Types for families of effects and platform-aware culling/scalability.\n- Measure translucent overdraw as well as simulation time.\n- Lightweight emitters trade flexibility for lower CPU/memory cost; verify feature compatibility.\n- Niagara Fluids are Beta in UE 5.8 and can be graphically intensive; use 2D/game templates or\n  baked flipbooks when they satisfy the effect.\n\nSee [`references/sources.md`](references/sources.md) for the UE 5.8 source trail.\n","webMarkdown":"## Select the simulation before authoring\n\nRead [`references/system-selector.md`](/unreal/unreal-niagara/system-selector/).\n\n- Simple high-count noninteractive effect -> lightweight/stateless emitter candidate.\n- Per-particle game-thread data, events, or CPU-only interfaces -> CPU simulation.\n- Very high particle count with GPU-supported behavior -> GPU simulation.\n- Many repeated gameplay bursts -> shared listener plus Niagara Data Channel candidate.\n- Volumetric grid simulation -> Niagara Fluids only after platform/budget review; bake when possible.\n\nBuild the cheapest representation that preserves the required read, not the most elaborate simulation.\n\n## Execute\n\n1. Define the visual read, duration, scale, camera range, gameplay contract, and target platforms.\n2. Split the effect into semantic emitters; choose renderer and simulation target per emitter.\n3. Establish spawn, initialize, update, render, and completion behavior with built-in modules first.\n4. Expose a small user-parameter contract; keep gameplay authority outside Niagara.\n5. Add collision, events, data interfaces, or Data Channels only for a specific requirement.\n6. Set bounds, warmup/pre-roll assumptions, pooling/reuse, and deactivation behavior.\n7. Add Effect Type and platform scalability/culling rules before content multiplies.\n8. Use Niagara Debugger and target-hardware captures at realistic instance counts and overdraw.\n\nLoad only what applies:\n\n- [`references/architecture-and-stack.md`](/unreal/unreal-niagara/architecture-and-stack/)\n- [`references/gameplay-integration.md`](/unreal/unreal-niagara/gameplay-integration/)\n- [`references/cpu-gpu-collision-events.md`](/unreal/unreal-niagara/cpu-gpu-collision-events/)\n- [`references/data-channels-and-interfaces.md`](/unreal/unreal-niagara/data-channels-and-interfaces/)\n- [`references/scalability-and-pooling.md`](/unreal/unreal-niagara/scalability-and-pooling/)\n- [`references/recipes.md`](/unreal/unreal-niagara/recipes/)\n- [`references/debugging-and-profiling.md`](/unreal/unreal-niagara/debugging-and-profiling/)\n\n## Required answer format\n\nReturn:\n\n1. **Visual/gameplay contract** and chosen representation.\n2. **System/emitter architecture**, simulation target, renderers, and module order.\n3. **Spawn/lifetime/completion behavior**.\n4. **User parameters and ownership/update frequency**.\n5. **Collision/event/data-interface assumptions and fallbacks**.\n6. **Bounds, pooling, Effect Type, culling, quality tiers, and platform consequences**.\n7. **Debugger metrics and visual acceptance checks at realistic counts**.\n\n## Hard rules\n\n- Niagara presents effects; authoritative damage, hits, inventory, and progression remain gameplay-owned.\n- Prefer existing modules/templates before custom Scratch Pad or HLSL modules.\n- Choose CPU/GPU simulation from data-access, determinism, event, collision, and scale needs.\n- Set and test bounds. GPU systems can disappear or waste work when bounds are wrong.\n- Every looping system needs an explicit owner and stop/deactivate path.\n- Pool only effects that reset cleanly; verify user parameters and persistent state on reuse.\n- Use Effect Types for families of effects and platform-aware culling/scalability.\n- Measure translucent overdraw as well as simulation time.\n- Lightweight emitters trade flexibility for lower CPU/memory cost; verify feature compatibility.\n- Niagara Fluids are Beta in UE 5.8 and can be graphically intensive; use 2D/game templates or\n  baked flipbooks when they satisfy the effect.\n\nSee [`references/sources.md`](/unreal/unreal-niagara/sources/) for the UE 5.8 source trail.\n","searchText":"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.","references":[{"slug":"architecture-and-stack","file":"architecture-and-stack.md","title":"System architecture and stack order","rawMarkdown":"# System architecture and stack order\n\n## Asset roles\n\n- **System**: complete effect, timelines, system-level parameters and scalability.\n- **Emitter**: one particle population and behavior stream.\n- **Module**: reusable operation in a stage/stack.\n- **Parameter**: typed data in engine, user, system, emitter, or particle namespace.\n- **Renderer**: converts particle/system data to sprites, meshes, ribbons, lights, or other output.\n\n## Build order\n\n1. Create a System from the closest template or an empty system.\n2. Add one emitter per semantic layer: core flash, debris, smoke, trail, decal handoff, and so on.\n3. Establish emitter/system lifecycle and loop behavior.\n4. In spawn stages, initialize values that are constant over a particle's life.\n5. In update stages, integrate motion and change values over time.\n6. Bind renderer attributes explicitly; remove unused attributes/modules.\n7. Add user parameters only at the system's public integration seam.\n8. Validate each emitter alone, then the composed effect.\n\nModule order is behavior order. When a later module overwrites an attribute, earlier work can be\ninvisible. Debug by watching the attribute and disabling modules from the end of the relevant stack.\n\nUse local/module inputs for internal implementation, particle attributes for per-particle state,\nsystem/emitter parameters for shared simulation state, and user parameters for caller-controlled\nvalues. Name user parameters by meaning and units, not by the current graph node.\n","webMarkdown":"## Asset roles\n\n- **System**: complete effect, timelines, system-level parameters and scalability.\n- **Emitter**: one particle population and behavior stream.\n- **Module**: reusable operation in a stage/stack.\n- **Parameter**: typed data in engine, user, system, emitter, or particle namespace.\n- **Renderer**: converts particle/system data to sprites, meshes, ribbons, lights, or other output.\n\n## Build order\n\n1. Create a System from the closest template or an empty system.\n2. Add one emitter per semantic layer: core flash, debris, smoke, trail, decal handoff, and so on.\n3. Establish emitter/system lifecycle and loop behavior.\n4. In spawn stages, initialize values that are constant over a particle's life.\n5. In update stages, integrate motion and change values over time.\n6. Bind renderer attributes explicitly; remove unused attributes/modules.\n7. Add user parameters only at the system's public integration seam.\n8. Validate each emitter alone, then the composed effect.\n\nModule order is behavior order. When a later module overwrites an attribute, earlier work can be\ninvisible. Debug by watching the attribute and disabling modules from the end of the relevant stack.\n\nUse local/module inputs for internal implementation, particle attributes for per-particle state,\nsystem/emitter parameters for shared simulation state, and user parameters for caller-controlled\nvalues. Name user parameters by meaning and units, not by the current graph node.\n","searchText":"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."},{"slug":"cpu-gpu-collision-events","file":"cpu-gpu-collision-events.md","title":"CPU/GPU simulation, collision, and events","rawMarkdown":"# CPU/GPU simulation, collision, and events\n\n## CPU simulation\n\nChoose CPU when required data interfaces, per-particle game-thread interaction, CPU events, or\nsmall counts outweigh the extra CPU cost. Profile many simultaneous system instances, not only one.\n\n## GPU simulation\n\nChoose GPU for large counts and GPU-supported operations. Define fixed bounds or a validated bounds\nstrategy. Confirm target-platform compute support, data-interface compatibility, collision method,\nsort cost, and any CPU readback requirement.\n\n## Collision selection\n\n- Scene/depth-based GPU collision is view-dependent; off-screen or hidden geometry may not exist\n  in the collision representation.\n- Distance-field or hardware ray-tracing paths have their own platform/project requirements.\n- CPU collision can query world collision but costs grow with particles and queries.\n- Cheap effects may use analytic planes, kill volumes, or authored timing instead of scene collision.\n\n## Events\n\nUse Niagara events when one simulation layer must react to another and the chosen simulation target\nsupports the path. For gameplay events, let gameplay own the event and pass Niagara the result.\nEvent-driven secondary particles can multiply work abruptly; cap spawn counts and test burst storms.\n\nWhen choosing a custom module, first confirm no built-in module already produces the behavior.\nDocument execution stage, required attributes, units, coordinate space, and supported simulation target.\n","webMarkdown":"## CPU simulation\n\nChoose CPU when required data interfaces, per-particle game-thread interaction, CPU events, or\nsmall counts outweigh the extra CPU cost. Profile many simultaneous system instances, not only one.\n\n## GPU simulation\n\nChoose GPU for large counts and GPU-supported operations. Define fixed bounds or a validated bounds\nstrategy. Confirm target-platform compute support, data-interface compatibility, collision method,\nsort cost, and any CPU readback requirement.\n\n## Collision selection\n\n- Scene/depth-based GPU collision is view-dependent; off-screen or hidden geometry may not exist\n  in the collision representation.\n- Distance-field or hardware ray-tracing paths have their own platform/project requirements.\n- CPU collision can query world collision but costs grow with particles and queries.\n- Cheap effects may use analytic planes, kill volumes, or authored timing instead of scene collision.\n\n## Events\n\nUse Niagara events when one simulation layer must react to another and the chosen simulation target\nsupports the path. For gameplay events, let gameplay own the event and pass Niagara the result.\nEvent-driven secondary particles can multiply work abruptly; cap spawn counts and test burst storms.\n\nWhen choosing a custom module, first confirm no built-in module already produces the behavior.\nDocument execution stage, required attributes, units, coordinate space, and supported simulation target.\n","searchText":"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."},{"slug":"data-channels-and-interfaces","file":"data-channels-and-interfaces.md","title":"Data Channels and data interfaces","rawMarkdown":"# Data Channels and data interfaces\n\n## Data interfaces\n\nUse a data interface when the system needs structured access to an object or dataset such as a\nSkeletal Mesh, Static Mesh, curve, texture, render target, audio, or scene data. Verify whether the\ninterface supports CPU, GPU, both, and the required access mode on target platforms.\n\nPrefer passing a stable owning component/object once over updating arrays of equivalent values every\nframe. Guard invalid/destroyed references and define a fallback pose/value.\n\n## Niagara Data Channels\n\nNDCs carry a defined payload between gameplay code and Niagara, or between Niagara systems. They are\nuseful for combining many repeated bursts into a shared listener simulation.\n\n1. Create a Data Channel asset and define the smallest typed payload.\n2. Associate the listener system(s).\n3. Configure a continuous listener with an intentional lifetime; Epic's pattern uses infinite loop\n   behavior plus Complete If Unused for cleanup.\n4. Read the channel and spawn particles from received entries.\n5. Have Blueprint/C++ publish events with consistent coordinate space and units.\n6. Test maximum event rate, island bounds/extents, unused cleanup, and dropped/late events.\n\nUse direct system user parameters for a few long-lived instances. Use NDC when repeated system spawn\noverhead and many same-schema events justify a shared simulation. Do not turn the channel into an\nunbounded general gameplay message bus.\n","webMarkdown":"## Data interfaces\n\nUse a data interface when the system needs structured access to an object or dataset such as a\nSkeletal Mesh, Static Mesh, curve, texture, render target, audio, or scene data. Verify whether the\ninterface supports CPU, GPU, both, and the required access mode on target platforms.\n\nPrefer passing a stable owning component/object once over updating arrays of equivalent values every\nframe. Guard invalid/destroyed references and define a fallback pose/value.\n\n## Niagara Data Channels\n\nNDCs carry a defined payload between gameplay code and Niagara, or between Niagara systems. They are\nuseful for combining many repeated bursts into a shared listener simulation.\n\n1. Create a Data Channel asset and define the smallest typed payload.\n2. Associate the listener system(s).\n3. Configure a continuous listener with an intentional lifetime; Epic's pattern uses infinite loop\n   behavior plus Complete If Unused for cleanup.\n4. Read the channel and spawn particles from received entries.\n5. Have Blueprint/C++ publish events with consistent coordinate space and units.\n6. Test maximum event rate, island bounds/extents, unused cleanup, and dropped/late events.\n\nUse direct system user parameters for a few long-lived instances. Use NDC when repeated system spawn\noverhead and many same-schema events justify a shared simulation. Do not turn the channel into an\nunbounded general gameplay message bus.\n","searchText":"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."},{"slug":"debugging-and-profiling","file":"debugging-and-profiling.md","title":"Debugging and profiling","rawMarkdown":"# Debugging and profiling\n\n## Symptom ladder\n\n| Symptom | Inspect first | Then |\n|---|---|---|\n| Nothing renders | system/component active, emitter enabled, spawn count | bounds, renderer binding, compile errors |\n| Disappears at angle/distance | fixed bounds | scalability/culling, LOD/platform |\n| Particles at origin | parameter binding and coordinate space | invalid data interface/source |\n| Pooled effect keeps old color/target | reset contract | persistent age/emitter state |\n| GPU collision fails off-screen | collision representation | switch method or design fallback |\n| Effect never ends | loop/lifetime/completion | owner cleanup, Auto Deactivate |\n| Hitch on first use | compilation/PSO/assets | prewarm/readiness strategy and packaged capture |\n| Frame time spikes during bursts | system count and spawn multiplication | simulation, renderer, overdraw, collision |\n\n## Debug procedure\n\n1. Isolate one system and disable all but one emitter.\n2. Check compile messages and parameter bindings.\n3. Use attribute/parameter watch and Niagara Debugger (Tools -> Debug -> Niagara Debugger).\n4. Visualize bounds and collision/debug drawing where supported.\n5. Recreate the expected maximum system count and camera overlap.\n6. Use the Debug Overview Performance view for system/game-thread comparison.\n7. Inspect Shader Complexity for translucent overdraw and use GPU/CPU profiling for actual timing.\n8. Compare one change under the same capture conditions.\n\nTrack system/emitter instance counts, active particles, tick/simulation time, render cost, material\noverdraw, collision/events, and memory. A cheap simulation can still be expensive to render; a cheap\nsprite can still become costly through overlap, sorting, lights, or full-screen coverage.\n","webMarkdown":"## Symptom ladder\n\n| Symptom | Inspect first | Then |\n|---|---|---|\n| Nothing renders | system/component active, emitter enabled, spawn count | bounds, renderer binding, compile errors |\n| Disappears at angle/distance | fixed bounds | scalability/culling, LOD/platform |\n| Particles at origin | parameter binding and coordinate space | invalid data interface/source |\n| Pooled effect keeps old color/target | reset contract | persistent age/emitter state |\n| GPU collision fails off-screen | collision representation | switch method or design fallback |\n| Effect never ends | loop/lifetime/completion | owner cleanup, Auto Deactivate |\n| Hitch on first use | compilation/PSO/assets | prewarm/readiness strategy and packaged capture |\n| Frame time spikes during bursts | system count and spawn multiplication | simulation, renderer, overdraw, collision |\n\n## Debug procedure\n\n1. Isolate one system and disable all but one emitter.\n2. Check compile messages and parameter bindings.\n3. Use attribute/parameter watch and Niagara Debugger (Tools -> Debug -> Niagara Debugger).\n4. Visualize bounds and collision/debug drawing where supported.\n5. Recreate the expected maximum system count and camera overlap.\n6. Use the Debug Overview Performance view for system/game-thread comparison.\n7. Inspect Shader Complexity for translucent overdraw and use GPU/CPU profiling for actual timing.\n8. Compare one change under the same capture conditions.\n\nTrack system/emitter instance counts, active particles, tick/simulation time, render cost, material\noverdraw, collision/events, and memory. A cheap simulation can still be expensive to render; a cheap\nsprite can still become costly through overlap, sorting, lights, or full-screen coverage.\n","searchText":"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."},{"slug":"gameplay-integration","file":"gameplay-integration.md","title":"Gameplay integration","rawMarkdown":"# Gameplay integration\n\n## Ownership contract\n\nGameplay decides that an event occurred and supplies stable effect inputs. Niagara renders the\nresponse. Do not make particle collision the sole authority for damage or other persistent state.\n\nTypical user parameters:\n\n- world position/normal or source transform;\n- color, intensity, size, duration, or normalized charge;\n- source/target actor or component for a data interface;\n- gameplay-owned seed/event identifier when repeatability matters.\n\n## Spawned burst\n\n1. Gameplay validates the event.\n2. Spawn/activate the Niagara System at the authoritative visual location on the relevant clients.\n3. Set user parameters before activation when the first frame depends on them.\n4. Let finite emitters complete, then release/destroy/pool the component.\n\n## Attached/continuous effect\n\n1. The owning actor/component creates or activates the effect.\n2. Attach using the intended transform rule and expose changing values at a bounded frequency.\n3. Stop spawning first when a graceful tail is needed; deactivate or destroy when complete.\n4. Clean up on owner end play, state exit, cancellation, and network relevancy changes.\n\nReplicate compact gameplay state/events, then spawn cosmetic effects locally. Do not replicate every\nparticle. Decide whether late joiners need current continuous state, whether unreliable one-shot\nevents may be dropped, and whether prediction requires a reconciliation/cancellation path.\n","webMarkdown":"## Ownership contract\n\nGameplay decides that an event occurred and supplies stable effect inputs. Niagara renders the\nresponse. Do not make particle collision the sole authority for damage or other persistent state.\n\nTypical user parameters:\n\n- world position/normal or source transform;\n- color, intensity, size, duration, or normalized charge;\n- source/target actor or component for a data interface;\n- gameplay-owned seed/event identifier when repeatability matters.\n\n## Spawned burst\n\n1. Gameplay validates the event.\n2. Spawn/activate the Niagara System at the authoritative visual location on the relevant clients.\n3. Set user parameters before activation when the first frame depends on them.\n4. Let finite emitters complete, then release/destroy/pool the component.\n\n## Attached/continuous effect\n\n1. The owning actor/component creates or activates the effect.\n2. Attach using the intended transform rule and expose changing values at a bounded frequency.\n3. Stop spawning first when a graceful tail is needed; deactivate or destroy when complete.\n4. Clean up on owner end play, state exit, cancellation, and network relevancy changes.\n\nReplicate compact gameplay state/events, then spawn cosmetic effects locally. Do not replicate every\nparticle. Decide whether late joiners need current continuous state, whether unreliable one-shot\nevents may be dropped, and whether prediction requires a reconciliation/cancellation path.\n","searchText":"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."},{"slug":"recipes","file":"recipes.md","title":"Effect recipes","rawMarkdown":"# Effect recipes\n\n## Impact burst\n\nFinite system: flash sprite, directional debris, short smoke, optional decal handoff. Inputs are\nposition, surface normal, physical-surface style, scale, and seed. Align directional particles to\nthe normal, cap secondary spawns, auto-deactivate, and batch high-frequency impacts through a Data\nChannel when measurement supports it.\n\n## Character trail\n\nAttach to a stable component/socket or sample a skeletal data interface. Use ribbons when continuous\nhistory is required; reset ribbon identity on teleport/reuse. Bound width, tessellation, lifetime,\nand translucency. Stop spawning on state exit and allow a deliberate tail.\n\n## Area telegraph\n\nPrefer a simple mesh/decal/material plus Niagara accents. Gameplay owns radius, timing, and damage;\nthe effect consumes normalized progress and dimensions. Preserve contrast and shape at low quality.\n\n## Environmental ambient\n\nUse large controlled bounds, distance scalability, low update frequency where valid, and camera/local\nspace only when it matches the illusion. Avoid one independent system per tiny ambient element when\none shared system or lightweight emitters suffice.\n\n## Smoke/fire\n\nStart with sprites/flipbooks. Use 2D Niagara Fluids templates when simulation materially improves a\ngame effect and the budget supports it. Reserve 3D fluids for high-end/cinematic cases unless proven.\nBake a fluid simulation to a flipbook when dynamic interaction is unnecessary.\n\n## Beam/target link\n\nPass source and target explicitly, define behavior when either is invalid, and update only as often\nas visual motion requires. Ribbons/beams are presentation; gameplay traces determine hits.\n","webMarkdown":"## Impact burst\n\nFinite system: flash sprite, directional debris, short smoke, optional decal handoff. Inputs are\nposition, surface normal, physical-surface style, scale, and seed. Align directional particles to\nthe normal, cap secondary spawns, auto-deactivate, and batch high-frequency impacts through a Data\nChannel when measurement supports it.\n\n## Character trail\n\nAttach to a stable component/socket or sample a skeletal data interface. Use ribbons when continuous\nhistory is required; reset ribbon identity on teleport/reuse. Bound width, tessellation, lifetime,\nand translucency. Stop spawning on state exit and allow a deliberate tail.\n\n## Area telegraph\n\nPrefer a simple mesh/decal/material plus Niagara accents. Gameplay owns radius, timing, and damage;\nthe effect consumes normalized progress and dimensions. Preserve contrast and shape at low quality.\n\n## Environmental ambient\n\nUse large controlled bounds, distance scalability, low update frequency where valid, and camera/local\nspace only when it matches the illusion. Avoid one independent system per tiny ambient element when\none shared system or lightweight emitters suffice.\n\n## Smoke/fire\n\nStart with sprites/flipbooks. Use 2D Niagara Fluids templates when simulation materially improves a\ngame effect and the budget supports it. Reserve 3D fluids for high-end/cinematic cases unless proven.\nBake a fluid simulation to a flipbook when dynamic interaction is unnecessary.\n\n## Beam/target link\n\nPass source and target explicitly, define behavior when either is invalid, and update only as often\nas visual motion requires. Ribbons/beams are presentation; gameplay traces determine hits.\n","searchText":"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."},{"slug":"scalability-and-pooling","file":"scalability-and-pooling.md","title":"Scalability, bounds, lifetime, and pooling","rawMarkdown":"# Scalability, bounds, lifetime, and pooling\n\n## Effect Type policy\n\nCreate Effect Types by semantic/cost family, such as impacts, ambient, character, or critical\ntelegraphs. They centralize system/emitter scalability, significance, cull reactions, update\nfrequency, validation rules, and performance baselines. Use system overrides only for justified\nexceptions.\n\n## Quality plan\n\nFor each platform/tier decide:\n\n- maximum system/particle instances;\n- distance, visibility, and instance-count culling;\n- response when culled: deactivate, pause, or another supported reaction;\n- emitter spawn-rate/count scaling;\n- renderer/material simplification;\n- collision, lights, shadows, sorting, ribbons, and fluids availability.\n\nGameplay-critical telegraphs need a legible fallback; do not cull their information content merely\nbecause decorative effects are culled.\n\n## Bounds and lifetime\n\n- Visualize and test bounds through the complete motion envelope.\n- Overlarge bounds reduce culling efficiency; undersized bounds cause popping/disappearance.\n- Enable Auto Deactivate when finite emitters should deactivate after spawning ends.\n- Every loop needs a caller-owned stop path and cleanup on owner destruction.\n\n## Pooling\n\nPool only when repeated component creation is measured and the system resets reliably. Before reuse,\nreset user parameters, attachments/transforms, age, loop state, data-interface bindings, and any\npersistent emitter state. Test cancellation, rapid reuse, and owner destruction. Lightweight emitters\nare another lever for many simple effects; compare them in Niagara Debugger rather than assuming.\n","webMarkdown":"## Effect Type policy\n\nCreate Effect Types by semantic/cost family, such as impacts, ambient, character, or critical\ntelegraphs. They centralize system/emitter scalability, significance, cull reactions, update\nfrequency, validation rules, and performance baselines. Use system overrides only for justified\nexceptions.\n\n## Quality plan\n\nFor each platform/tier decide:\n\n- maximum system/particle instances;\n- distance, visibility, and instance-count culling;\n- response when culled: deactivate, pause, or another supported reaction;\n- emitter spawn-rate/count scaling;\n- renderer/material simplification;\n- collision, lights, shadows, sorting, ribbons, and fluids availability.\n\nGameplay-critical telegraphs need a legible fallback; do not cull their information content merely\nbecause decorative effects are culled.\n\n## Bounds and lifetime\n\n- Visualize and test bounds through the complete motion envelope.\n- Overlarge bounds reduce culling efficiency; undersized bounds cause popping/disappearance.\n- Enable Auto Deactivate when finite emitters should deactivate after spawning ends.\n- Every loop needs a caller-owned stop path and cleanup on owner destruction.\n\n## Pooling\n\nPool only when repeated component creation is measured and the system resets reliably. Before reuse,\nreset user parameters, attachments/transforms, age, loop state, data-interface bindings, and any\npersistent emitter state. Test cancellation, rapid reuse, and owner destruction. Lightweight emitters\nare another lever for many simple effects; compare them in Niagara Debugger rather than assuming.\n","searchText":"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."},{"slug":"sources","file":"sources.md","title":"UE 5.8 primary sources","rawMarkdown":"# UE 5.8 primary sources\n\n- [Niagara Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/overview-of-niagara-effects-for-unreal-engine)\n- [Creating Visual Effects in Niagara](https://dev.epicgames.com/documentation/en-us/unreal-engine/creating-visual-effects-in-niagara-for-unreal-engine)\n- [Niagara Debugger](https://dev.epicgames.com/documentation/en-us/unreal-engine/niagara-debugger-for-unreal-engine)\n- [System Settings Reference](https://dev.epicgames.com/documentation/en-us/unreal-engine/system-settings-reference-for-niagara-effects-in-unreal-engine)\n- [Niagara Effect Type API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/Niagara/UNiagaraEffectType)\n- [Niagara Data Channels](https://dev.epicgames.com/documentation/en-us/unreal-engine/data-channels-in-niagara-for-unreal-engine)\n- [Niagara Data Channels Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/niagara-data-channels-overview)\n- [Lightweight Emitters Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/niagara-lightweight-emitters-overview)\n- [Lightweight Emitters Quick Start](https://dev.epicgames.com/documentation/en-us/unreal-engine/lightweight-emitters-quick-start-for-niagara-in-unreal-engine)\n- [Niagara Fluids](https://dev.epicgames.com/documentation/en-us/unreal-engine/niagara-fluids-in-unreal-engine)\n- [Fluid Simulation Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/fluid-simulation-in-unreal-engine---overview)\n\nPages were checked against the UE 5.8 documentation on 2026-07-19. Reconfirm feature maturity,\nsimulation-target support, and platform behavior after an engine upgrade.\n","webMarkdown":"- [Niagara Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/overview-of-niagara-effects-for-unreal-engine)\n- [Creating Visual Effects in Niagara](https://dev.epicgames.com/documentation/en-us/unreal-engine/creating-visual-effects-in-niagara-for-unreal-engine)\n- [Niagara Debugger](https://dev.epicgames.com/documentation/en-us/unreal-engine/niagara-debugger-for-unreal-engine)\n- [System Settings Reference](https://dev.epicgames.com/documentation/en-us/unreal-engine/system-settings-reference-for-niagara-effects-in-unreal-engine)\n- [Niagara Effect Type API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/Niagara/UNiagaraEffectType)\n- [Niagara Data Channels](https://dev.epicgames.com/documentation/en-us/unreal-engine/data-channels-in-niagara-for-unreal-engine)\n- [Niagara Data Channels Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/niagara-data-channels-overview)\n- [Lightweight Emitters Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/niagara-lightweight-emitters-overview)\n- [Lightweight Emitters Quick Start](https://dev.epicgames.com/documentation/en-us/unreal-engine/lightweight-emitters-quick-start-for-niagara-in-unreal-engine)\n- [Niagara Fluids](https://dev.epicgames.com/documentation/en-us/unreal-engine/niagara-fluids-in-unreal-engine)\n- [Fluid Simulation Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/fluid-simulation-in-unreal-engine---overview)\n\nPages were checked against the UE 5.8 documentation on 2026-07-19. Reconfirm feature maturity,\nsimulation-target support, and platform behavior after an engine upgrade.\n","searchText":"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."},{"slug":"system-selector","file":"system-selector.md","title":"Niagara system selector","rawMarkdown":"# Niagara system selector\n\n| Requirement | Prefer | Verify |\n|---|---|---|\n| Simple repeatable particles, many emitters | Lightweight/stateless emitter | required modules/renderers are supported |\n| Gameplay-readable particle data or CPU-only interface | CPU sim | particle count and game-thread cost |\n| Large particle count, supported GPU behavior | GPU compute sim | bounds, GPU collision/data access, readback limits |\n| Many same-type impacts/bursts | Data Channel + shared listener | batching semantics, island/extents, lifetime |\n| Trail/beam | Ribbon or beam-style module setup | source continuity, tessellation, UVs |\n| Volumetric smoke/fire/liquid | Niagara Fluids or flipbook | Beta maturity, GPU/memory budget, platform |\n| Pure camera-facing illusion | Sprite/flipbook | overdraw, sorting, lighting |\n| Shape and parallax matter | Mesh particles | triangles, draw calls, material cost |\n\nDecision questions:\n\n1. What must the player perceive, and for how long?\n2. Must particles affect gameplay, or only respond to gameplay?\n3. Does the simulation need scene/depth/distance-field collision?\n4. How many systems and particles coexist in the worst representative view?\n5. Can a material animation, decal, mesh animation, or flipbook communicate the same effect cheaper?\n\nMixed systems may contain both stateful and lightweight emitters. Choose per emitter, not by habit.\n","webMarkdown":"| Requirement | Prefer | Verify |\n|---|---|---|\n| Simple repeatable particles, many emitters | Lightweight/stateless emitter | required modules/renderers are supported |\n| Gameplay-readable particle data or CPU-only interface | CPU sim | particle count and game-thread cost |\n| Large particle count, supported GPU behavior | GPU compute sim | bounds, GPU collision/data access, readback limits |\n| Many same-type impacts/bursts | Data Channel + shared listener | batching semantics, island/extents, lifetime |\n| Trail/beam | Ribbon or beam-style module setup | source continuity, tessellation, UVs |\n| Volumetric smoke/fire/liquid | Niagara Fluids or flipbook | Beta maturity, GPU/memory budget, platform |\n| Pure camera-facing illusion | Sprite/flipbook | overdraw, sorting, lighting |\n| Shape and parallax matter | Mesh particles | triangles, draw calls, material cost |\n\nDecision questions:\n\n1. What must the player perceive, and for how long?\n2. Must particles affect gameplay, or only respond to gameplay?\n3. Does the simulation need scene/depth/distance-field collision?\n4. How many systems and particles coexist in the worst representative view?\n5. Can a material animation, decal, mesh animation, or flipbook communicate the same effect cheaper?\n\nMixed systems may contain both stateful and lightweight emitters. Choose per emitter, not by habit.\n","searchText":"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."}]}
{"slug":"unreal-packaging-deployment","name":"unreal-packaging-deployment","title":"Unreal 5.8 Packaging and 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.","shortDescription":"Build, cook, package, deploy, and diagnose Unreal","category":"Data, Tools & Shipping","referenceCount":12,"rawMarkdown":"---\nname: unreal-packaging-deployment\ndescription: 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.\n---\n\n# Unreal 5.8 Packaging and Deployment\n\n## Establish the artifact contract\n\nRead [`references/system-selector.md`](references/system-selector.md).\n\n1. Record engine revision, project commit, target platform, architecture, target type, build\n   configuration, device profile, distribution channel, and base release when patching.\n2. Define the artifact: Development/Test/Shipping, client/server, container format, chunks, symbols,\n   prerequisites, archive, deploy destination, and acceptance tests.\n3. Separate Build, Cook, Stage, Package, Deploy, and Run. Identify the first failing phase.\n4. Reproduce with a saved Project Launcher profile or recorded AutomationTool command.\n5. Preserve the complete log, exit code, manifests, artifact hashes, size report, and symbol identity.\n6. Run from a clean staging/archive location and test without editor binaries, loose source content,\n   developer config, or a cook server.\n7. Promote the exact tested artifact; do not rebuild after approval.\n\nRoute neighboring work deliberately:\n\n- asset schemas, Primary Asset rules, and content-to-chunk ownership -> `unreal-data-assets-tables`;\n- commandlets, Data Validation, and automation tests -> `unreal-editor-automation`;\n- runtime loading, residency, PSOs, and load hitches -> `unreal-memory-streaming`;\n- packaged performance captures -> `unreal-insights-profiling`;\n- save-format compatibility across releases -> `unreal-save-load`.\n\nLoad only what applies:\n\n- [`references/build-configurations-targets.md`](references/build-configurations-targets.md)\n- [`references/build-cook-stage-package.md`](references/build-cook-stage-package.md)\n- [`references/cooking-inclusion-validation.md`](references/cooking-inclusion-validation.md)\n- [`references/uat-project-launcher-ci.md`](references/uat-project-launcher-ci.md)\n- [`references/containers-chunks-patches-dlc.md`](references/containers-chunks-patches-dlc.md)\n- [`references/config-staging-runtime-dependencies.md`](references/config-staging-runtime-dependencies.md)\n- [`references/plugins-sdks-platforms.md`](references/plugins-sdks-platforms.md)\n- [`references/symbols-logs-crash-reporting.md`](references/symbols-logs-crash-reporting.md)\n- [`references/release-reproducibility-security.md`](references/release-reproducibility-security.md)\n- [`references/diagnostics-recipes.md`](references/diagnostics-recipes.md)\n\n## Required answer format\n\nReturn:\n\n1. **Artifact contract** and target matrix.\n2. **Exact pipeline surface**: editor, Project Launcher, commandlet, UAT, or CI.\n3. **Ordered Build/Cook/Stage/Package/Deploy actions** and owned configuration.\n4. **Cook roots, maps, chunks, staged files, plugins, SDKs, and platform prerequisites**.\n5. **Symbols, logs, crash collection, version/build ID, archive, and security policy**.\n6. **Clean-device verification**, failure injection, patch/base compatibility, and pass criteria.\n7. **First causal error** with the smallest confirming experiment when diagnosing.\n\n## Hard rules\n\n- Use Cook By the Book and a packaged target build for QA/release evidence; Cook On the Fly is an\n  iteration service, not a distributable artifact.\n- Never use `-cookall`, broad always-cook directories, or loose copied assets as the first fix for a\n  missing dependency. Identify the intended cook root and prove it in manifests/artifacts.\n- Never infer success from AutomationTool exit alone. Launch, traverse, save/load, network, suspend,\n  and platform-test the staged artifact required by the release contract.\n- Keep source defaults, platform overrides, generated user config, and secrets separate. Inspect the\n  staged effective configuration and strip denied keys/sections.\n- Declare third-party runtime files through build/staging rules; do not repair a release by manually\n  copying an untracked DLL beside one machine's executable.\n- Preserve symbols outside the public artifact and map them to the exact executable/build identity.\n- Build a patch against the exact retained base release. Never regenerate or silently replace the base.\n- Treat signing/encryption keys as release secrets. Encryption can increase patch entropy and IO cost;\n  measure the chosen policy.\n- Test the distribution path on clean target hardware with the correct account, SDK/runtime,\n  permissions, storage state, and no editor installation.\n- Do not invent UAT flags or platform requirements. Inspect `BuildCookRun -Help`, the generated Project\n  Launcher command, UE 5.8 source, and the target platform's current restricted documentation.\n\nSee [`references/sources.md`](references/sources.md) for the UE 5.8 primary-source trail.\n","webMarkdown":"## Establish the artifact contract\n\nRead [`references/system-selector.md`](/unreal/unreal-packaging-deployment/system-selector/).\n\n1. Record engine revision, project commit, target platform, architecture, target type, build\n   configuration, device profile, distribution channel, and base release when patching.\n2. Define the artifact: Development/Test/Shipping, client/server, container format, chunks, symbols,\n   prerequisites, archive, deploy destination, and acceptance tests.\n3. Separate Build, Cook, Stage, Package, Deploy, and Run. Identify the first failing phase.\n4. Reproduce with a saved Project Launcher profile or recorded AutomationTool command.\n5. Preserve the complete log, exit code, manifests, artifact hashes, size report, and symbol identity.\n6. Run from a clean staging/archive location and test without editor binaries, loose source content,\n   developer config, or a cook server.\n7. Promote the exact tested artifact; do not rebuild after approval.\n\nRoute neighboring work deliberately:\n\n- asset schemas, Primary Asset rules, and content-to-chunk ownership -> `unreal-data-assets-tables`;\n- commandlets, Data Validation, and automation tests -> `unreal-editor-automation`;\n- runtime loading, residency, PSOs, and load hitches -> `unreal-memory-streaming`;\n- packaged performance captures -> `unreal-insights-profiling`;\n- save-format compatibility across releases -> `unreal-save-load`.\n\nLoad only what applies:\n\n- [`references/build-configurations-targets.md`](/unreal/unreal-packaging-deployment/build-configurations-targets/)\n- [`references/build-cook-stage-package.md`](/unreal/unreal-packaging-deployment/build-cook-stage-package/)\n- [`references/cooking-inclusion-validation.md`](/unreal/unreal-packaging-deployment/cooking-inclusion-validation/)\n- [`references/uat-project-launcher-ci.md`](/unreal/unreal-packaging-deployment/uat-project-launcher-ci/)\n- [`references/containers-chunks-patches-dlc.md`](/unreal/unreal-packaging-deployment/containers-chunks-patches-dlc/)\n- [`references/config-staging-runtime-dependencies.md`](/unreal/unreal-packaging-deployment/config-staging-runtime-dependencies/)\n- [`references/plugins-sdks-platforms.md`](/unreal/unreal-packaging-deployment/plugins-sdks-platforms/)\n- [`references/symbols-logs-crash-reporting.md`](/unreal/unreal-packaging-deployment/symbols-logs-crash-reporting/)\n- [`references/release-reproducibility-security.md`](/unreal/unreal-packaging-deployment/release-reproducibility-security/)\n- [`references/diagnostics-recipes.md`](/unreal/unreal-packaging-deployment/diagnostics-recipes/)\n\n## Required answer format\n\nReturn:\n\n1. **Artifact contract** and target matrix.\n2. **Exact pipeline surface**: editor, Project Launcher, commandlet, UAT, or CI.\n3. **Ordered Build/Cook/Stage/Package/Deploy actions** and owned configuration.\n4. **Cook roots, maps, chunks, staged files, plugins, SDKs, and platform prerequisites**.\n5. **Symbols, logs, crash collection, version/build ID, archive, and security policy**.\n6. **Clean-device verification**, failure injection, patch/base compatibility, and pass criteria.\n7. **First causal error** with the smallest confirming experiment when diagnosing.\n\n## Hard rules\n\n- Use Cook By the Book and a packaged target build for QA/release evidence; Cook On the Fly is an\n  iteration service, not a distributable artifact.\n- Never use `-cookall`, broad always-cook directories, or loose copied assets as the first fix for a\n  missing dependency. Identify the intended cook root and prove it in manifests/artifacts.\n- Never infer success from AutomationTool exit alone. Launch, traverse, save/load, network, suspend,\n  and platform-test the staged artifact required by the release contract.\n- Keep source defaults, platform overrides, generated user config, and secrets separate. Inspect the\n  staged effective configuration and strip denied keys/sections.\n- Declare third-party runtime files through build/staging rules; do not repair a release by manually\n  copying an untracked DLL beside one machine's executable.\n- Preserve symbols outside the public artifact and map them to the exact executable/build identity.\n- Build a patch against the exact retained base release. Never regenerate or silently replace the base.\n- Treat signing/encryption keys as release secrets. Encryption can increase patch entropy and IO cost;\n  measure the chosen policy.\n- Test the distribution path on clean target hardware with the correct account, SDK/runtime,\n  permissions, storage state, and no editor installation.\n- Do not invent UAT flags or platform requirements. Inspect `BuildCookRun -Help`, the generated Project\n  Launcher command, UE 5.8 source, and the target platform's current restricted documentation.\n\nSee [`references/sources.md`](/unreal/unreal-packaging-deployment/sources/) for the UE 5.8 primary-source trail.\n","searchText":"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.","references":[{"slug":"build-configurations-targets","file":"build-configurations-targets.md","title":"Build configurations and targets","rawMarkdown":"# Build configurations and targets\n\n## State configuration\n\n| Configuration | Use | Important behavior |\n|---|---|---|\n| Debug | engine and game debugging | no optimization; slow; source engine context |\n| DebugGame | game-module debugging | game code unoptimized; engine remains optimized |\n| Development | daily packaged testing and profiling | most optimization; console/tools available |\n| Test | shipping-like QA with selected stats/profiling | Shipping base with some diagnostic tools |\n| Shipping | distribution candidate | full optimization; end-user console/stats stripped |\n\nShipping can still produce symbols. Store them securely rather than assuming an optimized build is\nunsymbolicatable.\n\n## Target type\n\n- **Game**: standalone executable requiring cooked target content.\n- **Editor**: editor executable/module target; never a runtime distribution artifact.\n- **Client**: multiplayer client target when `<Project>Client.Target.cs` exists.\n- **Server**: dedicated server target when `<Project>Server.Target.cs` exists.\n\nRecord both dimensions, for example `Development Game`, `Test Client`, or `Shipping Server`. Do not\ncompare performance, config, modules, or cook output across unlike targets and call it an A/B test.\n\nUse Development first to retain logs/console/profile access, then repeat the release suite in Test and\nShipping. Verify exit UI and recovery paths that relied on a console during development.\n","webMarkdown":"## State configuration\n\n| Configuration | Use | Important behavior |\n|---|---|---|\n| Debug | engine and game debugging | no optimization; slow; source engine context |\n| DebugGame | game-module debugging | game code unoptimized; engine remains optimized |\n| Development | daily packaged testing and profiling | most optimization; console/tools available |\n| Test | shipping-like QA with selected stats/profiling | Shipping base with some diagnostic tools |\n| Shipping | distribution candidate | full optimization; end-user console/stats stripped |\n\nShipping can still produce symbols. Store them securely rather than assuming an optimized build is\nunsymbolicatable.\n\n## Target type\n\n- **Game**: standalone executable requiring cooked target content.\n- **Editor**: editor executable/module target; never a runtime distribution artifact.\n- **Client**: multiplayer client target when `<Project>Client.Target.cs` exists.\n- **Server**: dedicated server target when `<Project>Server.Target.cs` exists.\n\nRecord both dimensions, for example `Development Game`, `Test Client`, or `Shipping Server`. Do not\ncompare performance, config, modules, or cook output across unlike targets and call it an A/B test.\n\nUse Development first to retain logs/console/profile access, then repeat the release suite in Test and\nShipping. Verify exit UI and recovery paths that relied on a console during development.\n","searchText":"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."},{"slug":"build-cook-stage-package","file":"build-cook-stage-package.md","title":"Build, cook, stage, package, deploy","rawMarkdown":"# Build, cook, stage, package, deploy\n\n| Phase | Produces | Diagnose here when |\n|---|---|---|\n| Build | target binaries/modules | compile, link, module, architecture, or symbol failure |\n| Cook | platform-ready assets/registry/shaders | serializer, asset, map, validation, DDC, or inclusion failure |\n| Stage | runnable directory assembled from products | missing config, DLL, movie, prerequisite, or wrong file class |\n| Package | native distributable/container set | signing, compression, container, store-format failure |\n| Deploy | copy/install to device | connection, account, capacity, permission, or install failure |\n| Run | launched staged build | startup, default map, runtime dependency, config, or content failure |\n\nThe standard packaging pipeline is executed by AutomationTool `BuildCookRun`. Use the editor for a quick\nsmoke build, Project Launcher for a reviewable profile, and UAT/BuildGraph for CI.\n\nFor an isolated cook, Epic documents:\n\n```text\nUnrealEditor-Cmd.exe <Project.uproject> -run=cook -targetplatform=<Platform> -map=<MapA>+<MapB>\n```\n\nDo not paste a generic release command blindly. Create the intended Project Launcher profile, execute\nonce, capture its generated `BuildCookRun` command, then parameterize only project, platform, output,\nversion, and credentials in CI. Query the installed engine with `RunUAT.bat BuildCookRun -Help` before\nadding flags.\n\nArchive outside the source tree. Keep stage and archive paths unique per build identity so stale files\ncannot satisfy the next build accidentally.\n","webMarkdown":"| Phase | Produces | Diagnose here when |\n|---|---|---|\n| Build | target binaries/modules | compile, link, module, architecture, or symbol failure |\n| Cook | platform-ready assets/registry/shaders | serializer, asset, map, validation, DDC, or inclusion failure |\n| Stage | runnable directory assembled from products | missing config, DLL, movie, prerequisite, or wrong file class |\n| Package | native distributable/container set | signing, compression, container, store-format failure |\n| Deploy | copy/install to device | connection, account, capacity, permission, or install failure |\n| Run | launched staged build | startup, default map, runtime dependency, config, or content failure |\n\nThe standard packaging pipeline is executed by AutomationTool `BuildCookRun`. Use the editor for a quick\nsmoke build, Project Launcher for a reviewable profile, and UAT/BuildGraph for CI.\n\nFor an isolated cook, Epic documents:\n\n```text\nUnrealEditor-Cmd.exe <Project.uproject> -run=cook -targetplatform=<Platform> -map=<MapA>+<MapB>\n```\n\nDo not paste a generic release command blindly. Create the intended Project Launcher profile, execute\nonce, capture its generated `BuildCookRun` command, then parameterize only project, platform, output,\nversion, and credentials in CI. Query the installed engine with `RunUAT.bat BuildCookRun -Help` before\nadding flags.\n\nArchive outside the source tree. Keep stage and archive paths unique per build identity so stale files\ncannot satisfy the next build accidentally.\n","searchText":"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."},{"slug":"config-staging-runtime-dependencies","file":"config-staging-runtime-dependencies.md","title":"Config, staging, and runtime dependencies","rawMarkdown":"# Config, staging, and runtime dependencies\n\n## Configuration\n\nUE config resolves through an ordered hierarchy: engine bases, platform bases, project defaults,\nplatform project overrides, then user layers. Diagnose the effective staged value, not one source file.\n\n- commit project defaults and deliberate platform overrides;\n- keep generated `Saved/Config` user/machine state out of release inputs;\n- use Packaging **Ini Key/Section Denylist** for values that must not ship;\n- never put private signing, store, backend, or service secrets in staged client config;\n- verify maps, cultures, device profiles, scalability, online subsystem, and log settings in the artifact.\n\nGame plugin config has a documented packaging caveat: plugin config files are not automatically packaged\nas an independent config layer. Merge required runtime defaults into the project's config and validate\nthe staged result.\n\n## Files outside assets\n\nUse `RuntimeDependencies` in `.Build.cs` for third-party libraries and staged files. Choose:\n\n- `UFS`: accessed through Unreal file APIs and eligible for a container;\n- `NonUFS`: loose file required by native/external IO;\n- `DebugNonUFS`: loose debug file staged only when debug files are requested;\n- `SystemNonUFS`: loose system file outside normal remapping.\n\nDLLs/shared libraries loaded by the OS must remain loose. Use the packaging settings for intentional\nnon-asset directories only when build rules are not the right owner. Verify license files, movies,\ncertificates, prerequisites, and dynamic-library search paths on a clean machine.\n","webMarkdown":"## Configuration\n\nUE config resolves through an ordered hierarchy: engine bases, platform bases, project defaults,\nplatform project overrides, then user layers. Diagnose the effective staged value, not one source file.\n\n- commit project defaults and deliberate platform overrides;\n- keep generated `Saved/Config` user/machine state out of release inputs;\n- use Packaging **Ini Key/Section Denylist** for values that must not ship;\n- never put private signing, store, backend, or service secrets in staged client config;\n- verify maps, cultures, device profiles, scalability, online subsystem, and log settings in the artifact.\n\nGame plugin config has a documented packaging caveat: plugin config files are not automatically packaged\nas an independent config layer. Merge required runtime defaults into the project's config and validate\nthe staged result.\n\n## Files outside assets\n\nUse `RuntimeDependencies` in `.Build.cs` for third-party libraries and staged files. Choose:\n\n- `UFS`: accessed through Unreal file APIs and eligible for a container;\n- `NonUFS`: loose file required by native/external IO;\n- `DebugNonUFS`: loose debug file staged only when debug files are requested;\n- `SystemNonUFS`: loose system file outside normal remapping.\n\nDLLs/shared libraries loaded by the OS must remain loose. Use the packaging settings for intentional\nnon-asset directories only when build rules are not the right owner. Verify license files, movies,\ncertificates, prerequisites, and dynamic-library search paths on a clean machine.\n","searchText":"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."},{"slug":"containers-chunks-patches-dlc","file":"containers-chunks-patches-dlc.md","title":"Containers, chunks, patches, and DLC","rawMarkdown":"# Containers, chunks, patches, and DLC\n\n## Containers and chunks\n\nPackaging settings can use Pak files or IoStore `.utoc`/`.ucas` containers. Choose from platform and\ndelivery requirements; verify mount, load, patch size, startup, IO, and tooling on the target.\n\nAsset Manager rules/Primary Asset Labels own content-to-chunk assignment. This skill owns generation,\nartifact inspection, delivery order, and release testing. Audit shared dependencies and duplicate files;\nfolder layout does not guarantee chunk ownership.\n\nDesign chunk 0 for content required before optional chunks are available. Test missing, partial, delayed,\nwrong-version, and corrupted optional installs. Never let core startup reference unavailable content.\n\n## Patch contract\n\n1. Retain the exact released binaries, containers, manifests, registry, config, keys, and version metadata.\n2. Build the patch against that base using the target platform's approved pipeline.\n3. Compare changed files/container blocks and investigate unexpected churn.\n4. Test base -> patch on a clean device; also test fresh full install at the patched version.\n5. Verify save migration, online compatibility, rollback policy, DLC entitlement, and disk-space behavior.\n\nCompression, encryption, shader ordering, bulk-data changes, engine/toolchain changes, asset renames, and\nresaves can enlarge a patch. Deterministic shader order may improve patch similarity while trading load\nbehavior; measure both.\n\nPlatform stores own final patch/DLC constraints. Do not infer console/mobile/store rules from a desktop\nPak example.\n","webMarkdown":"## Containers and chunks\n\nPackaging settings can use Pak files or IoStore `.utoc`/`.ucas` containers. Choose from platform and\ndelivery requirements; verify mount, load, patch size, startup, IO, and tooling on the target.\n\nAsset Manager rules/Primary Asset Labels own content-to-chunk assignment. This skill owns generation,\nartifact inspection, delivery order, and release testing. Audit shared dependencies and duplicate files;\nfolder layout does not guarantee chunk ownership.\n\nDesign chunk 0 for content required before optional chunks are available. Test missing, partial, delayed,\nwrong-version, and corrupted optional installs. Never let core startup reference unavailable content.\n\n## Patch contract\n\n1. Retain the exact released binaries, containers, manifests, registry, config, keys, and version metadata.\n2. Build the patch against that base using the target platform's approved pipeline.\n3. Compare changed files/container blocks and investigate unexpected churn.\n4. Test base -> patch on a clean device; also test fresh full install at the patched version.\n5. Verify save migration, online compatibility, rollback policy, DLC entitlement, and disk-space behavior.\n\nCompression, encryption, shader ordering, bulk-data changes, engine/toolchain changes, asset renames, and\nresaves can enlarge a patch. Deterministic shader order may improve patch similarity while trading load\nbehavior; measure both.\n\nPlatform stores own final patch/DLC constraints. Do not infer console/mobile/store rules from a desktop\nPak example.\n","searchText":"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."},{"slug":"cooking-inclusion-validation","file":"cooking-inclusion-validation.md","title":"Cooking, inclusion, and validation","rawMarkdown":"# Cooking, inclusion, and validation\n\n## Define roots\n\nCook inclusion comes from maps, hard dependencies, Asset Manager rules, Primary Asset Labels, explicitly\nconfigured directories/assets, plugins, or command-line/profile selections. A soft path alone does not\nprove inclusion.\n\n1. Set Game Default Map and required maps explicitly.\n2. Identify every on-demand asset's owning Primary Asset/rule or other cook root.\n3. Run Data Validation and Map Check; use cook validation options when appropriate.\n4. Cook the exact target platform By the Book.\n5. Inspect Asset Audit, cook/staging manifests, Asset Registry, container listing, and warnings.\n6. Run the cold path with no editor content or cook server.\n\nUseful documented cook diagnostics include `-verbosecookerwarnings`, `-RunAssetValidation`,\n`-RunMapValidation`, and `-ValidationErrorsAreFatal`. Confirm support against the installed 5.8 engine.\n\n## Avoid masking the cause\n\n- `-cookall` and **Cook Everything** increase size and can hide missing ownership.\n- broad **Additional Asset Directories to Cook** create implicit contracts that are hard to audit.\n- skipping soft/hard references is diagnostic and can create unloadable content.\n- iterative cooks accelerate iteration but can retain stale evidence; require a clean cook for release.\n- **Exclude Editor Content** can expose an improper runtime dependency on editor content; fix the edge.\n\nTreat warnings about unknown assets, redirectors, missing packages, shader formats, serialization, or\nnever-cook conflicts as build defects until dispositioned.\n","webMarkdown":"## Define roots\n\nCook inclusion comes from maps, hard dependencies, Asset Manager rules, Primary Asset Labels, explicitly\nconfigured directories/assets, plugins, or command-line/profile selections. A soft path alone does not\nprove inclusion.\n\n1. Set Game Default Map and required maps explicitly.\n2. Identify every on-demand asset's owning Primary Asset/rule or other cook root.\n3. Run Data Validation and Map Check; use cook validation options when appropriate.\n4. Cook the exact target platform By the Book.\n5. Inspect Asset Audit, cook/staging manifests, Asset Registry, container listing, and warnings.\n6. Run the cold path with no editor content or cook server.\n\nUseful documented cook diagnostics include `-verbosecookerwarnings`, `-RunAssetValidation`,\n`-RunMapValidation`, and `-ValidationErrorsAreFatal`. Confirm support against the installed 5.8 engine.\n\n## Avoid masking the cause\n\n- `-cookall` and **Cook Everything** increase size and can hide missing ownership.\n- broad **Additional Asset Directories to Cook** create implicit contracts that are hard to audit.\n- skipping soft/hard references is diagnostic and can create unloadable content.\n- iterative cooks accelerate iteration but can retain stale evidence; require a clean cook for release.\n- **Exclude Editor Content** can expose an improper runtime dependency on editor content; fix the edge.\n\nTreat warnings about unknown assets, redirectors, missing packages, shader formats, serialization, or\nnever-cook conflicts as build defects until dispositioned.\n","searchText":"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."},{"slug":"diagnostics-recipes","file":"diagnostics-recipes.md","title":"Diagnostic recipes","rawMarkdown":"# Diagnostic recipes\n\n| Symptom | First evidence | Bounded next step |\n|---|---|---|\n| black screen at startup | Game Default Map and runtime log | verify cooked map and staged effective config |\n| works in PIE, asset missing packaged | cook root and manifest | trace owning map/Primary Asset/rule; clean target cook |\n| plugin module missing | target/module/plugin descriptor and binary | build exact target; remove editor-only/runtime mismatch |\n| DLL/shared library missing | staged tree and OS loader log | declare `RuntimeDependencies`; verify architecture/search path |\n| wrong config in package | staged effective ini/device profile | identify later hierarchy override; remove generated input |\n| cook succeeds, stage fails | UAT phase boundary and staging manifest | inspect non-asset source path, permissions, disk, stale output |\n| Shipping behaves unlike Development | logs via Test/diagnostic candidate | compare compiled flags, modules, config, timing, stripped tools |\n| package unexpectedly huge | container/chunk/file size report | rank largest additions and duplicate chunk ownership |\n| tiny change creates huge patch | retained base/delta manifests | inspect resaves, compression/encryption, shader order, tool changes |\n| crash has unreadable callstack | build ID and symbol match | retrieve exact private symbols; never use rebuilt equivalents |\n| clean machine will not launch | OS loader/prerequisite/platform log | verify prerequisites and loose runtime dependencies |\n| device platform unavailable | SDK/toolchain/platform component status | install supported version and re-run platform validation |\n\nAfter each fix, rerun the smallest failing phase, then the complete clean artifact and acceptance suite.\n","webMarkdown":"| Symptom | First evidence | Bounded next step |\n|---|---|---|\n| black screen at startup | Game Default Map and runtime log | verify cooked map and staged effective config |\n| works in PIE, asset missing packaged | cook root and manifest | trace owning map/Primary Asset/rule; clean target cook |\n| plugin module missing | target/module/plugin descriptor and binary | build exact target; remove editor-only/runtime mismatch |\n| DLL/shared library missing | staged tree and OS loader log | declare `RuntimeDependencies`; verify architecture/search path |\n| wrong config in package | staged effective ini/device profile | identify later hierarchy override; remove generated input |\n| cook succeeds, stage fails | UAT phase boundary and staging manifest | inspect non-asset source path, permissions, disk, stale output |\n| Shipping behaves unlike Development | logs via Test/diagnostic candidate | compare compiled flags, modules, config, timing, stripped tools |\n| package unexpectedly huge | container/chunk/file size report | rank largest additions and duplicate chunk ownership |\n| tiny change creates huge patch | retained base/delta manifests | inspect resaves, compression/encryption, shader order, tool changes |\n| crash has unreadable callstack | build ID and symbol match | retrieve exact private symbols; never use rebuilt equivalents |\n| clean machine will not launch | OS loader/prerequisite/platform log | verify prerequisites and loose runtime dependencies |\n| device platform unavailable | SDK/toolchain/platform component status | install supported version and re-run platform validation |\n\nAfter each fix, rerun the smallest failing phase, then the complete clean artifact and acceptance suite.\n","searchText":"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."},{"slug":"plugins-sdks-platforms","file":"plugins-sdks-platforms.md","title":"Plugins, SDKs, and target platforms","rawMarkdown":"# Plugins, SDKs, and target platforms\n\n## Plugins and modules\n\nFor each enabled plugin, verify:\n\n- supported target platforms and architectures;\n- runtime versus editor/developer module type and loading phase;\n- source availability or matching prebuilt binaries;\n- `CanContainContent` and cook inclusion when content is required;\n- dependencies declared in `.uproject`, `.uplugin`, and module rules;\n- third-party libraries staged through `RuntimeDependencies`;\n- Shipping compile and startup with editor-only code excluded.\n\nDisable unused plugins before the release branch stabilizes, then recook and run the full suite. A plugin\nthat loads in Editor can still lack a target binary, include an editor-only dependency, or omit content.\n\n## Platform readiness\n\nPin the engine-supported SDK, compiler/toolchain, platform extension, architecture, signing identity,\nentitlements/capabilities, device OS, and store tooling. Validate with the platform's setup checker and\nrestricted documentation. Some platforms require additional SDKs/components; console packaging requires\na source engine build according to Epic's public UE 5.8 packaging guide.\n\nDo not publish restricted platform paths, flags, certification rules, or keys into a general skill.\nRoute them to the authorized platform documentation and record only the verified outcome in private CI.\n","webMarkdown":"## Plugins and modules\n\nFor each enabled plugin, verify:\n\n- supported target platforms and architectures;\n- runtime versus editor/developer module type and loading phase;\n- source availability or matching prebuilt binaries;\n- `CanContainContent` and cook inclusion when content is required;\n- dependencies declared in `.uproject`, `.uplugin`, and module rules;\n- third-party libraries staged through `RuntimeDependencies`;\n- Shipping compile and startup with editor-only code excluded.\n\nDisable unused plugins before the release branch stabilizes, then recook and run the full suite. A plugin\nthat loads in Editor can still lack a target binary, include an editor-only dependency, or omit content.\n\n## Platform readiness\n\nPin the engine-supported SDK, compiler/toolchain, platform extension, architecture, signing identity,\nentitlements/capabilities, device OS, and store tooling. Validate with the platform's setup checker and\nrestricted documentation. Some platforms require additional SDKs/components; console packaging requires\na source engine build according to Epic's public UE 5.8 packaging guide.\n\nDo not publish restricted platform paths, flags, certification rules, or keys into a general skill.\nRoute them to the authorized platform documentation and record only the verified outcome in private CI.\n","searchText":"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."},{"slug":"release-reproducibility-security","file":"release-reproducibility-security.md","title":"Release reproducibility and security","rawMarkdown":"# Release reproducibility and security\n\n## Candidate gate\n\n- clean source revision; recorded submodules/plugins and no undeclared local files;\n- pinned engine, SDK, compiler, build tools, platform extensions, and environment;\n- clean By-the-Book cook/full rebuild according to release policy;\n- zero undispositioned validation/cook/package warnings;\n- expected maps, cultures, chunks, config, dependencies, prerequisites, and licenses;\n- artifact hash/size/build ID, matching symbols, manifests, and retained base release;\n- automated smoke plus human target-device acceptance;\n- fresh install, upgrade/patch, uninstall/reinstall, low disk, offline, and permission tests;\n- save migration and online/backend compatibility verified;\n- exact candidate promoted without rebuild.\n\n## Security boundaries\n\nSigning establishes artifact authenticity/integrity for its supported workflow; encryption limits casual\ncontent inspection. Neither makes client code/data trusted. Keep authoritative economy, entitlements,\nmatch results, and anti-cheat decisions server-side.\n\nStore private keys outside source, artifacts, logs, profiles, and command history. Rotate/revoke through\nthe platform process. Inspect staged config and loose files for credentials, internal URLs, test accounts,\ndebug endpoints, source paths, and unintended symbols.\n\nMeasure encrypted/compressed container startup, IO, memory, build time, store size, and patch delta.\n","webMarkdown":"## Candidate gate\n\n- clean source revision; recorded submodules/plugins and no undeclared local files;\n- pinned engine, SDK, compiler, build tools, platform extensions, and environment;\n- clean By-the-Book cook/full rebuild according to release policy;\n- zero undispositioned validation/cook/package warnings;\n- expected maps, cultures, chunks, config, dependencies, prerequisites, and licenses;\n- artifact hash/size/build ID, matching symbols, manifests, and retained base release;\n- automated smoke plus human target-device acceptance;\n- fresh install, upgrade/patch, uninstall/reinstall, low disk, offline, and permission tests;\n- save migration and online/backend compatibility verified;\n- exact candidate promoted without rebuild.\n\n## Security boundaries\n\nSigning establishes artifact authenticity/integrity for its supported workflow; encryption limits casual\ncontent inspection. Neither makes client code/data trusted. Keep authoritative economy, entitlements,\nmatch results, and anti-cheat decisions server-side.\n\nStore private keys outside source, artifacts, logs, profiles, and command history. Rotate/revoke through\nthe platform process. Inspect staged config and loose files for credentials, internal URLs, test accounts,\ndebug endpoints, source paths, and unintended symbols.\n\nMeasure encrypted/compressed container startup, IO, memory, build time, store size, and patch delta.\n","searchText":"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."},{"slug":"sources","file":"sources.md","title":"UE 5.8 primary sources","rawMarkdown":"# UE 5.8 primary sources\n\n- [Packaging Your Project](https://dev.epicgames.com/documentation/en-us/unreal-engine/packaging-your-project)\n- [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)\n- [Build Configurations Reference](https://dev.epicgames.com/documentation/en-us/unreal-engine/build-configurations-reference-for-unreal-engine)\n- [Content Cooking](https://dev.epicgames.com/documentation/en-us/unreal-engine/cooking-content-in-unreal-engine)\n- [Cooking and Chunking](https://dev.epicgames.com/documentation/en-us/unreal-engine/cooking-content-and-creating-chunks-in-unreal-engine)\n- [Project Launcher](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-the-project-launcher-in-unreal-engine)\n- [Project Settings: Packaging](https://dev.epicgames.com/documentation/en-us/unreal-engine/project-section-of-the-unreal-engine-project-settings)\n- [Configuration Files](https://dev.epicgames.com/documentation/en-us/unreal-engine/configuration-files-in-unreal-engine)\n- [Plugins](https://dev.epicgames.com/documentation/en-us/unreal-engine/plugins-in-unreal-engine)\n- [Integrating Third-Party Libraries](https://dev.epicgames.com/documentation/en-us/unreal-engine/integrating-third-party-libraries-into-unreal-engine)\n- [Updating Projects With Patches](https://dev.epicgames.com/documentation/en-us/unreal-engine/updating-unreal-engine-projects-with-patches-after-release)\n- [General Patching Information](https://dev.epicgames.com/documentation/en-us/unreal-engine/general-patching-information-in-unreal-engine)\n- [Crash Reporting](https://dev.epicgames.com/documentation/en-us/unreal-engine/crash-reporting-in-unreal-engine)\n- [Versioning Assets and Packages](https://dev.epicgames.com/documentation/en-us/unreal-engine/versioning-of-assets-and-packages-in-unreal-engine)\n\nPages were checked against UE 5.8 documentation on 2026-07-19. Reconfirm platform SDK/toolchain\nrequirements, UAT arguments, container and patch workflows, packaging defaults, and store/certification\nrules after an engine or platform update.\n","webMarkdown":"- [Packaging Your Project](https://dev.epicgames.com/documentation/en-us/unreal-engine/packaging-your-project)\n- [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)\n- [Build Configurations Reference](https://dev.epicgames.com/documentation/en-us/unreal-engine/build-configurations-reference-for-unreal-engine)\n- [Content Cooking](https://dev.epicgames.com/documentation/en-us/unreal-engine/cooking-content-in-unreal-engine)\n- [Cooking and Chunking](https://dev.epicgames.com/documentation/en-us/unreal-engine/cooking-content-and-creating-chunks-in-unreal-engine)\n- [Project Launcher](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-the-project-launcher-in-unreal-engine)\n- [Project Settings: Packaging](https://dev.epicgames.com/documentation/en-us/unreal-engine/project-section-of-the-unreal-engine-project-settings)\n- [Configuration Files](https://dev.epicgames.com/documentation/en-us/unreal-engine/configuration-files-in-unreal-engine)\n- [Plugins](https://dev.epicgames.com/documentation/en-us/unreal-engine/plugins-in-unreal-engine)\n- [Integrating Third-Party Libraries](https://dev.epicgames.com/documentation/en-us/unreal-engine/integrating-third-party-libraries-into-unreal-engine)\n- [Updating Projects With Patches](https://dev.epicgames.com/documentation/en-us/unreal-engine/updating-unreal-engine-projects-with-patches-after-release)\n- [General Patching Information](https://dev.epicgames.com/documentation/en-us/unreal-engine/general-patching-information-in-unreal-engine)\n- [Crash Reporting](https://dev.epicgames.com/documentation/en-us/unreal-engine/crash-reporting-in-unreal-engine)\n- [Versioning Assets and Packages](https://dev.epicgames.com/documentation/en-us/unreal-engine/versioning-of-assets-and-packages-in-unreal-engine)\n\nPages were checked against UE 5.8 documentation on 2026-07-19. Reconfirm platform SDK/toolchain\nrequirements, UAT arguments, container and patch workflows, packaging defaults, and store/certification\nrules after an engine or platform update.\n","searchText":"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."},{"slug":"symbols-logs-crash-reporting","file":"symbols-logs-crash-reporting.md","title":"Symbols, logs, and crash reporting","rawMarkdown":"# Symbols, logs, and crash reporting\n\n## Packaging failure\n\nPreserve the full Output Log/UAT log and exit code. Search backward from the final AutomationTool summary\nfor the first specific compiler, cooker, staging, signing, or platform error. Later “Unknown Error” and\ncascade failures are usually not causal.\n\nRecord command, phase, asset/module/file, target, and the smallest rerun that reproduces it. Delete only\nphase-appropriate generated output after preserving evidence; do not begin by deleting every cache.\n\n## Runtime failure\n\nUse a Development/Test packaged build with logs, symbols, and the same content/config as Shipping. Capture:\n\n- project runtime log and platform/device log;\n- command line, map, account, locale, hardware, driver/OS;\n- crash GUID, callstacks, minidump/context, and build identity;\n- exact executable/modules and matching symbols.\n\nShipping symbols can be produced and retained without publicly staging them. Symbolicate against the\nexact binary; symbols from a rebuild of the same source are not guaranteed to match.\n\nPackaged games do not automatically send reports to Epic. Include/configure Crash Reporter only when a\nprivacy-reviewed collection endpoint and consent policy exist. Test offline, unattended, user-decline,\nupload failure, rate/size limits, PII redaction, and server symbolication.\n","webMarkdown":"## Packaging failure\n\nPreserve the full Output Log/UAT log and exit code. Search backward from the final AutomationTool summary\nfor the first specific compiler, cooker, staging, signing, or platform error. Later “Unknown Error” and\ncascade failures are usually not causal.\n\nRecord command, phase, asset/module/file, target, and the smallest rerun that reproduces it. Delete only\nphase-appropriate generated output after preserving evidence; do not begin by deleting every cache.\n\n## Runtime failure\n\nUse a Development/Test packaged build with logs, symbols, and the same content/config as Shipping. Capture:\n\n- project runtime log and platform/device log;\n- command line, map, account, locale, hardware, driver/OS;\n- crash GUID, callstacks, minidump/context, and build identity;\n- exact executable/modules and matching symbols.\n\nShipping symbols can be produced and retained without publicly staging them. Symbolicate against the\nexact binary; symbols from a rebuild of the same source are not guaranteed to match.\n\nPackaged games do not automatically send reports to Epic. Include/configure Crash Reporter only when a\nprivacy-reviewed collection endpoint and consent policy exist. Test offline, unattended, user-decline,\nupload failure, rate/size limits, PII redaction, and server symbolication.\n","searchText":"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."},{"slug":"system-selector","file":"system-selector.md","title":"System selector","rawMarkdown":"# System selector\n\n| Need | Primary surface |\n|---|---|\n| quick local packaged smoke test | Platforms menu -> Package Project |\n| repeatable multi-step/device profile | Project Launcher custom launch profile |\n| unattended CI/release artifact | AutomationTool `BuildCookRun` or BuildGraph |\n| isolate content conversion | Cook commandlet |\n| validate selected assets/maps during cook | cook validation flags plus validation reports |\n| content ownership/chunk assignment | Asset Manager/Primary Asset Labels |\n| inspect staged non-assets/config | staging manifest and archive tree |\n| deploy/run on device | Project Launcher/AutomationTool plus platform tools |\n| symbolicate packaged crash | exact executable, symbols, build identity, crash context |\n| patch/DLC | retained base release plus platform delivery workflow |\n\nBefore acting, ask which phase produced the observed failure. “Packaging” is not a phase-specific\ndiagnosis.\n","webMarkdown":"| Need | Primary surface |\n|---|---|\n| quick local packaged smoke test | Platforms menu -> Package Project |\n| repeatable multi-step/device profile | Project Launcher custom launch profile |\n| unattended CI/release artifact | AutomationTool `BuildCookRun` or BuildGraph |\n| isolate content conversion | Cook commandlet |\n| validate selected assets/maps during cook | cook validation flags plus validation reports |\n| content ownership/chunk assignment | Asset Manager/Primary Asset Labels |\n| inspect staged non-assets/config | staging manifest and archive tree |\n| deploy/run on device | Project Launcher/AutomationTool plus platform tools |\n| symbolicate packaged crash | exact executable, symbols, build identity, crash context |\n| patch/DLC | retained base release plus platform delivery workflow |\n\nBefore acting, ask which phase produced the observed failure. “Packaging” is not a phase-specific\ndiagnosis.\n","searchText":"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."},{"slug":"uat-project-launcher-ci","file":"uat-project-launcher-ci.md","title":"Project Launcher, UAT, and CI","rawMarkdown":"# Project Launcher, UAT, and CI\n\n## Project Launcher\n\nCreate named custom profiles for repeatable build, cook, package, deploy, and run choices. Record:\n\n- project and target platform/device;\n- build configuration and target;\n- By-the-Book versus On-the-Fly cook;\n- maps/cultures/chunks/DLC/release version;\n- package/archive/deploy method;\n- command-line arguments and launch map.\n\nUse its Output Log to capture the generated UAT command. Treat the profile as a reviewed specification,\nnot the only record; engine/profile changes can alter generated flags.\n\n## CI record\n\nPersist for every candidate:\n\n```text\nengine version + source changelist\nproject commit and dirty-state policy\nUAT command/profile export and environment\nSDK/toolchain/plugin versions\nfull UTF-8 log and exit code\ncook/stage/container manifests and warnings\nartifact hashes, sizes, build ID, symbols\ntest results and promotion decision\n```\n\nFail on missing expected artifacts and selected warnings, not only a nonzero exit. Make credentials\nephemeral and redact logs. Keep DDC/cache state observable: warm caches may change duration, never the\nintended output contract.\n\nPromote an immutable artifact through QA/store lanes. Rebuilding “the same commit” can change toolchain,\nSDK, generated data, timestamps, or dependencies.\n","webMarkdown":"## Project Launcher\n\nCreate named custom profiles for repeatable build, cook, package, deploy, and run choices. Record:\n\n- project and target platform/device;\n- build configuration and target;\n- By-the-Book versus On-the-Fly cook;\n- maps/cultures/chunks/DLC/release version;\n- package/archive/deploy method;\n- command-line arguments and launch map.\n\nUse its Output Log to capture the generated UAT command. Treat the profile as a reviewed specification,\nnot the only record; engine/profile changes can alter generated flags.\n\n## CI record\n\nPersist for every candidate:\n\n```text\nengine version + source changelist\nproject commit and dirty-state policy\nUAT command/profile export and environment\nSDK/toolchain/plugin versions\nfull UTF-8 log and exit code\ncook/stage/container manifests and warnings\nartifact hashes, sizes, build ID, symbols\ntest results and promotion decision\n```\n\nFail on missing expected artifacts and selected warnings, not only a nonzero exit. Make credentials\nephemeral and redact logs. Keep DDC/cache state observable: warm caches may change duration, never the\nintended output contract.\n\nPromote an immutable artifact through QA/store lanes. Rebuilding “the same commit” can change toolchain,\nSDK, generated data, timestamps, or dependencies.\n","searchText":"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."}]}
{"slug":"unreal-pcg","name":"unreal-pcg","title":"Unreal 5.8 PCG","description":"Design, implement, optimize, automate, and debug Procedural Content Generation workflows in Unreal Engine 5.8. Use for PCG Graphs, points, density, metadata attributes, spatial data, samplers, filters, exclusion zones, Static Mesh Spawner, splines, graph parameters, subgraphs, editor tools, manual overrides, deterministic seeds, partitioned or hierarchical generation, runtime generation, PCG with World Partition/Data Layers/HLOD, GPU execution, procedural GPU instancing, PCG Builder commandlets, profiling, caching, validation, or PCG-based vegetation, roads, fences, buildings, biomes, and world population.","shortDescription":"Build and optimize procedural content graphs","category":"World & AI","referenceCount":10,"rawMarkdown":"---\nname: unreal-pcg\ndescription: Design, implement, optimize, automate, and debug Procedural Content Generation workflows in Unreal Engine 5.8. Use for PCG Graphs, points, density, metadata attributes, spatial data, samplers, filters, exclusion zones, Static Mesh Spawner, splines, graph parameters, subgraphs, editor tools, manual overrides, deterministic seeds, partitioned or hierarchical generation, runtime generation, PCG with World Partition/Data Layers/HLOD, GPU execution, procedural GPU instancing, PCG Builder commandlets, profiling, caching, validation, or PCG-based vegetation, roads, fences, buildings, biomes, and world population.\n---\n\n# Unreal 5.8 PCG\n\n## Ownership boundary\n\nThis skill owns procedural sampling, graph data, generation, cleanup, and generated-output ownership.\nRoute source-path mechanics to [`unreal-splines`](../unreal-splines/SKILL.md), source-terrain\ndeformation/paint to [`unreal-landscape`](../unreal-landscape/SKILL.md), and World Partition cells,\nstreaming sources, Data Layers, and HLODs to\n[`unreal-world-partition`](../unreal-world-partition/SKILL.md).\n\n## Select generation ownership\n\n- Use **editor generation** for authored world content that must persist, cook, build HLODs,\n  support collision/navigation, or be manually reviewed before shipping.\n- Use **non-partitioned generation** for bounded tools and small generation domains.\n- Use **partitioned generation** when a large domain must split into streamable cells.\n- Use **hierarchical generation** when large-scale shared work and small-scale detail require\n  different grid sizes.\n- Use **runtime generation** only when content genuinely depends on runtime sources/state and\n  its generation, cleanup, memory, and visual-pop costs fit the target budget.\n- Use GPU execution only after a representative CPU/GPU trace proves enough parallel work to\n  amortize transfers and dispatch preparation.\n\nRead [`references/system-selector.md`](references/system-selector.md) before choosing.\n\n## Design the data contract first\n\n1. Identify the spatial source: volume, surface, spline/line, points, actor data, or polygon.\n2. Declare each metadata attribute's name, type, units, producer, consumer, and default.\n3. Define stable seeds and which operations intentionally mutate them.\n4. Separate selection data from spawn/presentation data.\n5. Define exclusion/clearance rules before adding variation.\n6. Choose output ownership: instances, Actors, data assets, or downstream graph data.\n7. Decide what is authoritative, persisted, streamed, rebuilt, or disposable.\n\nRead [`references/data-model-graph-design.md`](references/data-model-graph-design.md).\n\n## Build in dependency order\n\n1. Confirm the PCG plugin and any required interop plugins are enabled.\n2. Create the smallest graph: input -> sample -> debug/inspect -> output.\n3. Establish bounds, projection, point density, and deterministic seed behavior.\n4. Filter invalid slopes, heights, surfaces, tags, and exclusion volumes.\n5. Add transforms and mesh/actor selection through explicit attributes.\n6. Spawn only after point data is correct.\n7. Expose instance parameters and extract reusable subgraphs/templates.\n8. Choose partition/hierarchy/runtime grids from content scale and streaming ownership.\n9. Integrate Data Layers/HLOD and batch builders for persistent large-world output.\n10. Profile node cost, scheduling, instance count, memory, CPU/GPU transfers, and visual pops.\n\nUse [`references/sampling-spawning-patterns.md`](references/sampling-spawning-patterns.md),\n[`references/parameters-tools-overrides.md`](references/parameters-tools-overrides.md), and\n[`references/world-partition-integration.md`](references/world-partition-integration.md).\n\n## Respect UE 5.8 maturity boundaries\n\n- PCG Editor Mode is **Experimental**.\n- UE 5.8's non-destructive manual editing/Data Override system is **Experimental**.\n- PCG GPU Processing is **Beta**.\n- GPU Procedural Instancing in the GPU Static Mesh Spawner path is **Experimental** and lacks\n  persisted instances, collision, navigation, ray tracing, distance-field lighting, HLOD, and\n  static baked-lighting support.\n- PCG Biome Core/Sample remains **Experimental**; treat it as an example architecture.\n\nRead [`references/gpu-processing.md`](references/gpu-processing.md).\n\n## Required answer format\n\nReturn:\n\n1. **Generation-mode and output-ownership choice**.\n2. **Spatial/attribute/seed contract**.\n3. **Ordered graph procedure** with exact node categories/names and parameter effects.\n4. **Partition, hierarchy, runtime, Data Layer, and HLOD design** where applicable.\n5. **Maturity and platform constraints** for editor/manual/GPU features.\n6. **Debug views, validation cases, profiling captures, and regeneration test**.\n\nDo not invent node names, defaults, supported GPU features, determinism, or performance wins.\n\n## Hard rules\n\n- Inspect points and attributes before spawning content.\n- Keep graph parameters typed, named, documented, and instance-overridable only when intentional.\n- Never rely on uncontrolled randomness; preserve a reproducible seed path.\n- Do not use runtime PCG for content that can be baked without losing the required behavior.\n- Do not alternate CPU/GPU nodes repeatedly; transfers can erase GPU gains.\n- Do not use Experimental GPU instances when collision, nav, ray tracing, HLOD, or persistence is\n  required.\n- Never assume generated gameplay Actors replicate or become authoritative automatically.\n- Preserve artist-authored/manual overrides through the supported override system; do not bake\n  accidental edits into opaque graph logic.\n- Cleanup, regenerate, cook, and test from a clean state before declaring a graph reliable.\n- Profile on target hardware and at shipping content density.\n\nRead [`references/runtime-scheduling.md`](references/runtime-scheduling.md),\n[`references/debugging-validation.md`](references/debugging-validation.md), and\n[`references/use-cases.md`](references/use-cases.md). See\n[`references/sources.md`](references/sources.md) for the UE 5.8 source trail.\n","webMarkdown":"## Ownership boundary\n\nThis skill owns procedural sampling, graph data, generation, cleanup, and generated-output ownership.\nRoute source-path mechanics to [`unreal-splines`](/unreal/unreal-splines/), source-terrain\ndeformation/paint to [`unreal-landscape`](/unreal/unreal-landscape/), and World Partition cells,\nstreaming sources, Data Layers, and HLODs to\n[`unreal-world-partition`](/unreal/unreal-world-partition/).\n\n## Select generation ownership\n\n- Use **editor generation** for authored world content that must persist, cook, build HLODs,\n  support collision/navigation, or be manually reviewed before shipping.\n- Use **non-partitioned generation** for bounded tools and small generation domains.\n- Use **partitioned generation** when a large domain must split into streamable cells.\n- Use **hierarchical generation** when large-scale shared work and small-scale detail require\n  different grid sizes.\n- Use **runtime generation** only when content genuinely depends on runtime sources/state and\n  its generation, cleanup, memory, and visual-pop costs fit the target budget.\n- Use GPU execution only after a representative CPU/GPU trace proves enough parallel work to\n  amortize transfers and dispatch preparation.\n\nRead [`references/system-selector.md`](/unreal/unreal-pcg/system-selector/) before choosing.\n\n## Design the data contract first\n\n1. Identify the spatial source: volume, surface, spline/line, points, actor data, or polygon.\n2. Declare each metadata attribute's name, type, units, producer, consumer, and default.\n3. Define stable seeds and which operations intentionally mutate them.\n4. Separate selection data from spawn/presentation data.\n5. Define exclusion/clearance rules before adding variation.\n6. Choose output ownership: instances, Actors, data assets, or downstream graph data.\n7. Decide what is authoritative, persisted, streamed, rebuilt, or disposable.\n\nRead [`references/data-model-graph-design.md`](/unreal/unreal-pcg/data-model-graph-design/).\n\n## Build in dependency order\n\n1. Confirm the PCG plugin and any required interop plugins are enabled.\n2. Create the smallest graph: input -> sample -> debug/inspect -> output.\n3. Establish bounds, projection, point density, and deterministic seed behavior.\n4. Filter invalid slopes, heights, surfaces, tags, and exclusion volumes.\n5. Add transforms and mesh/actor selection through explicit attributes.\n6. Spawn only after point data is correct.\n7. Expose instance parameters and extract reusable subgraphs/templates.\n8. Choose partition/hierarchy/runtime grids from content scale and streaming ownership.\n9. Integrate Data Layers/HLOD and batch builders for persistent large-world output.\n10. Profile node cost, scheduling, instance count, memory, CPU/GPU transfers, and visual pops.\n\nUse [`references/sampling-spawning-patterns.md`](/unreal/unreal-pcg/sampling-spawning-patterns/),\n[`references/parameters-tools-overrides.md`](/unreal/unreal-pcg/parameters-tools-overrides/), and\n[`references/world-partition-integration.md`](/unreal/unreal-pcg/world-partition-integration/).\n\n## Respect UE 5.8 maturity boundaries\n\n- PCG Editor Mode is **Experimental**.\n- UE 5.8's non-destructive manual editing/Data Override system is **Experimental**.\n- PCG GPU Processing is **Beta**.\n- GPU Procedural Instancing in the GPU Static Mesh Spawner path is **Experimental** and lacks\n  persisted instances, collision, navigation, ray tracing, distance-field lighting, HLOD, and\n  static baked-lighting support.\n- PCG Biome Core/Sample remains **Experimental**; treat it as an example architecture.\n\nRead [`references/gpu-processing.md`](/unreal/unreal-pcg/gpu-processing/).\n\n## Required answer format\n\nReturn:\n\n1. **Generation-mode and output-ownership choice**.\n2. **Spatial/attribute/seed contract**.\n3. **Ordered graph procedure** with exact node categories/names and parameter effects.\n4. **Partition, hierarchy, runtime, Data Layer, and HLOD design** where applicable.\n5. **Maturity and platform constraints** for editor/manual/GPU features.\n6. **Debug views, validation cases, profiling captures, and regeneration test**.\n\nDo not invent node names, defaults, supported GPU features, determinism, or performance wins.\n\n## Hard rules\n\n- Inspect points and attributes before spawning content.\n- Keep graph parameters typed, named, documented, and instance-overridable only when intentional.\n- Never rely on uncontrolled randomness; preserve a reproducible seed path.\n- Do not use runtime PCG for content that can be baked without losing the required behavior.\n- Do not alternate CPU/GPU nodes repeatedly; transfers can erase GPU gains.\n- Do not use Experimental GPU instances when collision, nav, ray tracing, HLOD, or persistence is\n  required.\n- Never assume generated gameplay Actors replicate or become authoritative automatically.\n- Preserve artist-authored/manual overrides through the supported override system; do not bake\n  accidental edits into opaque graph logic.\n- Cleanup, regenerate, cook, and test from a clean state before declaring a graph reliable.\n- Profile on target hardware and at shipping content density.\n\nRead [`references/runtime-scheduling.md`](/unreal/unreal-pcg/runtime-scheduling/),\n[`references/debugging-validation.md`](/unreal/unreal-pcg/debugging-validation/), and\n[`references/use-cases.md`](/unreal/unreal-pcg/use-cases/). See\n[`references/sources.md`](/unreal/unreal-pcg/sources/) for the UE 5.8 source trail.\n","searchText":"unreal 5.8 pcg design, implement, optimize, automate, and debug procedural content generation workflows in unreal engine 5.8. use for pcg graphs, points, density, metadata attributes, spatial data, samplers, filters, exclusion zones, static mesh spawner, splines, graph parameters, subgraphs, editor tools, manual overrides, deterministic seeds, partitioned or hierarchical generation, runtime generation, pcg with world partition/data layers/hlod, gpu execution, procedural gpu instancing, pcg builder commandlets, profiling, caching, validation, or pcg-based vegetation, roads, fences, buildings, biomes, and world population. data model and graph design data model and graph design pcg data shapes | shape | use | |---|---| | volume | bounded 3d domain and boolean/spatial sampling | | surface | landscape/2d domain projected into the world | | line | spline and landscape spline data | | point data | explicit candidates with transform, bounds, density, steepness, color, seed | | polygon 2d | closed planar areas and polygon union/intersection/difference | | composite data | lazy spatial union/intersection/difference before concretizing | | attribute set | nonspatial typed metadata/parameters | keep spatial operations lazy as long as useful; convert/sample to explicit points only when a downstream point operation or spawner requires it. point contract for every point stream, document: - coordinate space and projection surface; - bounds represented by each point; - density meaning and expected range [0,1]; - seed source and any mutate seed boundary; - required metadata attributes, types, units, and defaults; - whether transform scale is semantic size or spawn transform; - which node owns rejection versus presentation. point seeds are derived in part from position for world-position consistency. operations that duplicate points can also duplicate random behavior; use mutate seed where independent random branches are intentional. graph layering use a readable staged graph: text input and bounds -> sampling/projection -> environmental attributes -> hard filters and exclusion -> density/weight shaping -> selection attributes -> transform variation -> spawn/output name reroutes and comment the contract at each stage. delete temporary attributes before expensive copy/spawn operations when they are no longer needed. attribute rules - prefer semantic names such as surfaceslopedegrees, biomeid, mesh, clearancecm. - do not silently reuse one attribute with multiple units or meanings. - use graph parameters for tool-level inputs; use point attributes for per-point decisions. - use match and set attributes for data-driven selection tables and weighted choices. - use typed complex attributes in ue 5.8 only when downstream nodes/cook targets support them. determinism test generate, record point count/transforms/selected assets, cleanup, and regenerate with unchanged inputs. results must match wherever deterministic output is required. then change only the exposed seed and confirm intended variation changes without violating hard constraints. debugging, validation, and profiling debugging, validation, and profiling graph-debug procedure 1. enable node debug on the earliest suspicious stage. 2. inspect the data view and attributes list: count, bounds, density, transforms, seed, attributes. 3. move the debug point downstream one stage at a time. 4. disable spawners while validating data. 5. use graph/node profiling to identify cpu cost; use unreal insights for system-level cost. 6. cleanup and regenerate to eliminate stale output. runtime tools - pcg.runtimegeneration.enabledebugoverlay 1: scheduler/runtime overview. - pcg.graphexecution.debugdrawgeneratedcells 1: sources, generating cells, grid/coordinates. - pcg.runtimegeneration.enabledebugging: verbose scheduler logging. - pcg.runtimegeneration.refresh: cleanup and schedule regeneration. - pcg.runtimegeneration.enable: freeze/enable runtime generation. - pcg.gpu.fuzzmemory: expose uninitialized gpu output assumptions. debug overlays are not generally available in shipping and may differ by build configuration. validation matrix - empty input and zero points; - smallest and largest bounds; - steep/vertical/overhanging surfaces; - overlapping exclusion volumes and data layers; - seed zero, repeated seed, and changed seed; - missing asset/table row/soft reference; - cleanup -> regenerate -> reload -> cook; - source control clean checkout and commandlet generation; - target platform scalability/feature-level switches; - fast traversal/teleport and multiple runtime sources; - maximum shipping density plus hlod/nav/collision build where required. common failures | symptom | first check | |---|---| | points exist but nothing spawns | mesh/actor selector attribute, bounds, node enabled, output path | | same random choice repeats | duplicated seeds; place mutate seed at intentional branch | | content leaks into roads/buildings | exclusion input/bounds and difference mode/order | | graph regenerates constantly | tracked actor/component changes or circular dependencies | | runtime pop-in | generation radius, bounds modifier, scheduler budget, traversal speed | | cleanup leaves stale actors | generation ownership, partition actors, grid change cleanup sequence | | gpu path slower | transfers, small data, compute-graph fragmentation, preparation cost | | packaged result differs | editor-only input/node, unsupported platform path, unbuilt persistent output | performance record record point count, spawned instance/actor count, cpu node times, gpu execution/memory, generation latency percentile, cache memory, cleanup time, streaming overlap, and final render cost. pcg graph time alone does not include the lifetime cost of what it spawned. gpu processing gpu processing maturity - pcg gpu processing: beta in ue 5.8. - gpu execution is available only on a subset of nodes, including custom hlsl and supported point/ spawner operations. - gpu procedural instancing through gpu static mesh spawner: experimental. adoption procedure 1. profile the cpu graph and record node cost/point count. 2. confirm the target nodes support gpu execution on every shipping platform/feature level. 3. form one or a few long connected gpu compute regions. 4. minimize cpu -> gpu uploads and gpu -> cpu downloads. 5. compare end-to-end time, frame spikes, memory, and time-to-visible—not kernel time alone. 6. verify output equality/acceptable variation and regenerate under stress. 7. keep a cpu fallback or platform branch when coverage requires it. gpu setup and transfer have cpu cost. small data sets or graphs that bounce between cpu and gpu can be slower than cpu-only execution. experimental gpu procedural instances use only for runtime visual meshes that do not require: - persisted/saved instance data; - collision or physics; - navigation; - ray tracing; - distance-field lighting contribution; - static baked lighting; - hlod. these instances live only at runtime in gpu memory. a gpu visual forest is not automatically a walkable, collidable, nav-aware, hlod-buildable forest. custom hlsl - declare inputs/outputs and created attributes explicitly or use ue 5.8's supported source parsing path. - initialize every output; test with pcg.gpu.fuzzmemory to expose uninitialized memory use. - bound threads/data sizes and handle empty inputs. - use platform/feature-level switches for unsupported paths. - keep the hlsl contract documented beside the node; shader code is not self-validating. profiling ue 5.8 adds gpu execution time and gpu-created memory to the pcg profiling window. use platform gpu tools for kernel detail. runtime pcg is bursty; use profile kernel index only as a controlled profiling aid and disable it afterward. parameters, subgraphs, tools, and manual overrides parameters, subgraphs, tools, and manual overrides expose parameters deliberately expose only values that define a meaningful tool instance: - density/count target; - seed; - allowed slope/height; - clearance distance; - asset set or selection table; - scale/rotation range; - grid/runtime generation settings when instance variation is legitimate. give each parameter a category, order, description, unit, safe range, and default in ue 5.8's graph parameters hierarchy editor. do not expose internal scratch attributes. reuse hierarchy - use named subgraphs for reusable pipeline stages. - use ue 5.8 embedded subgraphs for graph-local function-like logic. - use graph instances for variations that share implementation but override parameters. - mark a graph as a template when it is a starting structure, not a live shared dependency. - keep the interface small; sprawling pins usually indicate missing stage boundaries. pcg editor mode pcg editor mode is experimental in ue 5.8. it provides draw spline, draw spline surface, paint, and volume tools driven by graphs/presets. for a tool graph: 1. set compatible tool tags (splinetool, splinesurfacetool, painttool, volumetool). 2. define the initial actor class and a clear spawned-actor/component naming policy. 3. expose only instance parameters the artist needs while interacting. 4. define raycast rules for landscapes, meshes, ignored pcg components, allowed classes, and selection constraints. 5. test apply, cancel, undo/redo, reload, source control, and regeneration. ue 5.8 manual editing/data overrides the new non-destructive manual-editing/data override system is experimental. - mark only the node/output that owns artist-editable data for manual editing. - use selection, exclusion, modification, and restore rather than detaching the whole result. - inspect all overrides in the data overrides window. - define team policy: override intent, author, and whether it survives graph regeneration. - verify overrides after upstream graph edits, cleanup/regenerate, map reload, cook, and merge. - prefer a source input/exclusion layer when an exception is systemic; reserve manual overrides for genuine local art direction. do not silently convert override data into graph constants or delete it during cleanup. runtime generation and scheduling runtime generation and scheduling configure runtime generation 1. set the pcg component generation trigger to generate at runtime. 2. enable hierarchical generation if multiple grid scales are required. 3. configure generation radius for each grid size. 4. configure cleanup radius multiplier so content is not destroyed immediately at the generation boundary. 5. use generate/cleanup bounds modifiers to begin work before the source looks toward content and reduce visible pops. 6. define generation sources: player/camera, editor viewport for testing, or custom sources. 7. choose a scheduling policy from actual traversal direction, distance, and urgency needs. 8. test source teleport, rapid direction reversal, fast vehicles, multiple players/sources, and no-source cleanup. budget controls relevant ue 5.8 variables include: - pcg.frametime: runtime pcg execution budget in milliseconds. - pcg.runtimegeneration.numgeneratingcomponents: parallel generating components. - pcg.runtimegeneration.framesbetweengraphschedules: scheduler delay between schedule passes. - pcg.runtimegeneration.enablepooling: partition-actor pooling. - pcg.cache.runtime.enabled: runtime cpu-node cache; disabled by default. - pcg.cache.runtime.memorybudgetmb: runtime cache memory cap. do not copy documented defaults blindly. tune on target hardware for time-to-screen, hitching, memory, and background contention with gameplay/streaming. failure policy define behavior when generation is late: - hide with fog/distance/occlusion; - preserve lower-detail/baked fallback; - prevent access until generation completes; - reduce small-grid detail before missing large silhouette content; - prioritize forward/travel-direction cells. do not let missing collision or gameplay actors become a visual-pop problem; that is a correctness failure. multiplayer pcg output is not automatically authoritative or replicated. choose explicitly: - identical local cosmetic generation from controlled inputs/seeds; - server-generated replicated gameplay actors; - baked/persisted world content streamed normally; - server-authored compact state that each client converts into local presentation. test determinism across builds/platforms before relying on identical local generation for anything more than cosmetic presentation. sampling, filtering, and spawning sampling, filtering, and spawning surface scatter procedure 1. obtain actor/landscape/surface data within explicit component bounds. 2. use surface sampler or the appropriate sampler to produce candidate points. 3. project/re-project after transforms that move points off the target surface. 4. compute slope, height, surface type/tag, density, and clearance attributes. 5. apply hard filters before random thinning. 6. subtract roads, structures, water, paths, and gameplay-clearance shapes with difference or point filters. 7. use density/weights for natural distribution and mesh choice. 8. transform points within bounded rotation/scale ranges. 9. inspect points and bounds before static mesh spawner/spawn actor. exclusion and spacing - use spatial difference for clear exclusion shapes. - use distance to create a gradient near another point set; filter/remap the result. - use self pruning or neighborhood logic for overlap/spacing, choosing bounds and pruning order intentionally. - account for final mesh bounds, not only pivot distance. - keep critical traversal and gameplay sightlines as hard constraints, never probability alone. mesh selection - drive mesh/material/scale selection from explicit attributes or weighted selector data. - use data tables/attribute sets plus match and set attributes for editable catalogs. - keep asset references soft/async where the generation and loading model requires it. - prefer instancing for repeated static meshes; use actors only when actor behavior is required. spline pattern 1. get spline data from the intended actor/component. 2. sample by distance, subdivision, or control-point semantics appropriate to the asset. 3. write tangent/orientation/width/side attributes. 4. offset or project candidates. 5. exclude intersections and invalid surface regions. 6. spawn fence posts, roadside objects, or downstream spline/mesh data. use shape grammar when a repeatable module grammar materially simplifies fences/buildings; do not force grammar onto free-form scatter. spawn-output selector | output | use | |---|---| | ism/hism/static mesh spawner | repeated static visual content | | spawn actor | behavior, identity, components, or independent lifecycle required | | output node data | downstream pcg component/subgraph consumes points/attributes | | pcg data asset | reusable baked data exchange | do not spawn thousands of actors for decoration. do not use gpu procedural instances for outputs that need collision, nav, hlod, persistence, ray tracing, or distance fields. ue 5.8 primary sources ue 5.8 primary sources all links were checked against epic's ue 5.8 documentation on 2026-07-19. core framework - pcg framework - pcg overview - pcg data types reference - pcg node reference - pcg generation modes ue 5.8 workflows and performance - ue 5.8 release notes: pcg - pcg editor mode - pcg with gpu processing - pcg runtime generation debugging - shape grammar with pcg - pcg biome core overview large-world integration and automation - pcg with world partition - world partition builder commandlets - working with pcg and llms using unreal mcp ue 5.8 maturity notes - pcg editor mode and the new manual data override system are experimental. - pcg gpu processing is beta. - gpu procedural instancing and pcg biome core/sample are experimental. pcg system selector pcg system selector choose the generation mode | need | mode | cost/constraint | |---|---|---| | small bounded authoring tool | non-partitioned editor generation | simplest; one component domain | | large persistent generated area | partitioned editor generation | grid cells integrate with streaming | | multiple detail scales | hierarchical generation | shared large-grid work feeds smaller grids | | viewer/source-dependent transient content | runtime generation | scheduler, memory, cleanup, and pop budget | pcg generation modes are not visual-quality settings. select them from domain size, update frequency, output lifetime, and streaming requirements. bake versus runtime prefer editor-generated/baked output when content needs: - manual art review and source-control visibility; - hlod or static baked lighting; - persistent instance data; - collision, navigation, ray tracing, or distance-field participation; - deterministic cook output without runtime generation stalls. use runtime generation when player position, runtime terrain/state, or effectively unbounded content makes baking impractical. runtime generation must define generation sources, radii, cleanup radii, scheduling policy, memory/caching, and what happens when generation falls behind. partitioned versus hierarchical - partitioned generation divides one component's domain into pcg grid cells. - hierarchical generation lets branches execute at different grid sizes through grid size nodes. - put broad, reusable calculations on larger grids and dense local detail on smaller grids. - data produced on a larger hierarchical grid is cached for smaller-grid execution. - choose cell/grid size from content size and cost, not one universal number. cpu versus gpu stay on cpu for small point counts, frequent cpu consumers, actor spawning, unsupported nodes, or when transfer overhead dominates. evaluate gpu when long connected gpu-capable regions process enough points to amortize upload/download and compute-graph setup. pcg gpu processing is beta. gpu procedural instancing is a narrower experimental output path with major persistence and feature limitations. see gpu-processing.md. related skills - route world partition/data layer/hlod ownership to $unreal-world-partition. - route spline construction and spline meshes to $unreal-splines. - route asset definitions/soft loading to the future unreal-data-assets-tables skill. - route final bottleneck work to $unreal-insights-profiling when available. use cases use cases vegetation scatter - landscape/surface -> slope/height/surface attributes -> road/water/poi difference -> density noise -> weighted species selection -> bounded transform -> instanced mesh spawn. - partition/hierarchy by plant scale: trees on larger grids, grass/flowers/stones on smaller. - keep gameplay clearance, landmarks, paths, and sightlines as hard filters. - use persistent cpu instances when hlod/collision/nav are required; gpu instances only for the supported purely visual runtime case. roadside/fence generator - spline input -> distance sampling -> tangent/side/width -> terrain projection -> intersection/ endpoint rules -> post/module selection -> spawn. - use shape grammar for repeating modules and corner/end pieces when rules stay legible. - route spline deformation/mesh segment details to $unreal-splines. building/city blocks - polygon 2d city boundary -> cut/subdivide by splines -> offset for setbacks -> create surfaces -> sample parcels -> attribute-driven building archetype -> spawn actor/level instance. - keep roads and utility corridors as source geometry, not late random exclusions. - validate entrances, navigation, collision, streaming ownership, and hlod output. biome architecture - separate climate/biome classification, broad distribution, species selection, local exclusion, and spawn into subgraphs. - use data assets/tables for species rules and weights. - pcg biome core is experimental; mine it for patterns rather than treating it as a production guarantee. authored exceptions - use input splines/volumes/tags for repeatable design rules. - use ue 5.8 manual overrides for isolated art-directed exceptions only after accepting the experimental status and defining merge/regeneration policy. - if the same override occurs repeatedly, promote it into graph input or rule data. acceptance test for any generator the generator must produce valid constraints across at least ten representative seeds, regenerate identically for a fixed seed/input, survive cleanup/reload/cook, remain editable by intended creators, and meet total runtime/render/streaming budgets on target hardware. world partition integration world partition integration ownership model treat the systems as separate layers: - pcg decides what data/content to generate. - pcg partition/hierarchy decides where and at what generation grid work executes. - world partition decides which persisted actors/cells stream. - data layers decide which authored/runtime content set is loaded or activated. - hlod decides what distant proxy represents unloaded source content. do not assume pcg grid size and world partition runtime cell size are the same setting or must match one-to-one. persistent generated content 1. choose partitioned/hierarchical editor generation for the large domain. 2. assign the source pcg actor/component to the intended data layer and hlod layer. 3. configure spawn actor/create target actor data layer source type intentionally. self inherits source-component data layers. 4. generate and inspect actor/data layer/hlod assignment. 5. build hlods after stable generation. 6. cleanup and regenerate after grid changes; stale partition actors are not evidence of the new configuration. 7. run the pcg world partition builder commandlet from a clean source state for reproducibility. pcg-generated actors assigned through the source asset inherit matching data layer/hlod ownership according to the documented integration path. runtime generation in a partitioned world - define runtime pcg generation sources independently from world partition streaming sources. - set generation and cleanup radii by pcg grid level. - ensure world partition cells and required source data load early enough for generation. - prewarm teleport destinations before player arrival; verify both streaming completion and pcg generation completion rather than assuming one implies the other. - keep gameplay-critical collision/nav content persisted or use a runtime path that explicitly supports and finishes it before access. data layer transitions if pcg content follows a runtime data layer: 1. server/gameplay authority changes the data layer state in networked play. 2. separate loaded from activated behavior. 3. test generated content cleanup/reappearance through state changes. 4. measure the burst; activating many assets/layers together can degrade streaming performance. route detailed streaming, data layer, and hlod configuration to $unreal-world-partition.","references":[{"slug":"data-model-graph-design","file":"data-model-graph-design.md","title":"Data model and graph design","rawMarkdown":"# Data model and graph design\n\n## PCG data shapes\n\n| Shape | Use |\n|---|---|\n| Volume | bounded 3D domain and boolean/spatial sampling |\n| Surface | landscape/2D domain projected into the world |\n| Line | Spline and Landscape Spline data |\n| Point Data | explicit candidates with transform, bounds, density, steepness, color, seed |\n| Polygon 2D | closed planar areas and polygon union/intersection/difference |\n| Composite Data | lazy spatial union/intersection/difference before concretizing |\n| Attribute Set | nonspatial typed metadata/parameters |\n\nKeep spatial operations lazy as long as useful; convert/sample to explicit points only when a\ndownstream point operation or spawner requires it.\n\n## Point contract\n\nFor every point stream, document:\n\n- coordinate space and projection surface;\n- bounds represented by each point;\n- density meaning and expected range `[0,1]`;\n- seed source and any `Mutate Seed` boundary;\n- required metadata attributes, types, units, and defaults;\n- whether transform scale is semantic size or spawn transform;\n- which node owns rejection versus presentation.\n\nPoint seeds are derived in part from position for world-position consistency. Operations that\nduplicate points can also duplicate random behavior; use `Mutate Seed` where independent random\nbranches are intentional.\n\n## Graph layering\n\nUse a readable staged graph:\n\n```text\nInput and bounds\n  -> Sampling/projection\n  -> Environmental attributes\n  -> Hard filters and exclusion\n  -> Density/weight shaping\n  -> Selection attributes\n  -> Transform variation\n  -> Spawn/output\n```\n\nName reroutes and comment the contract at each stage. Delete temporary attributes before expensive\ncopy/spawn operations when they are no longer needed.\n\n## Attribute rules\n\n- Prefer semantic names such as `SurfaceSlopeDegrees`, `BiomeId`, `Mesh`, `ClearanceCm`.\n- Do not silently reuse one attribute with multiple units or meanings.\n- Use graph parameters for tool-level inputs; use point attributes for per-point decisions.\n- Use `Match And Set Attributes` for data-driven selection tables and weighted choices.\n- Use typed complex attributes in UE 5.8 only when downstream nodes/cook targets support them.\n\n## Determinism test\n\nGenerate, record point count/transforms/selected assets, cleanup, and regenerate with unchanged\ninputs. Results must match wherever deterministic output is required. Then change only the exposed\nseed and confirm intended variation changes without violating hard constraints.\n","webMarkdown":"## PCG data shapes\n\n| Shape | Use |\n|---|---|\n| Volume | bounded 3D domain and boolean/spatial sampling |\n| Surface | landscape/2D domain projected into the world |\n| Line | Spline and Landscape Spline data |\n| Point Data | explicit candidates with transform, bounds, density, steepness, color, seed |\n| Polygon 2D | closed planar areas and polygon union/intersection/difference |\n| Composite Data | lazy spatial union/intersection/difference before concretizing |\n| Attribute Set | nonspatial typed metadata/parameters |\n\nKeep spatial operations lazy as long as useful; convert/sample to explicit points only when a\ndownstream point operation or spawner requires it.\n\n## Point contract\n\nFor every point stream, document:\n\n- coordinate space and projection surface;\n- bounds represented by each point;\n- density meaning and expected range `[0,1]`;\n- seed source and any `Mutate Seed` boundary;\n- required metadata attributes, types, units, and defaults;\n- whether transform scale is semantic size or spawn transform;\n- which node owns rejection versus presentation.\n\nPoint seeds are derived in part from position for world-position consistency. Operations that\nduplicate points can also duplicate random behavior; use `Mutate Seed` where independent random\nbranches are intentional.\n\n## Graph layering\n\nUse a readable staged graph:\n\n```text\nInput and bounds\n  -> Sampling/projection\n  -> Environmental attributes\n  -> Hard filters and exclusion\n  -> Density/weight shaping\n  -> Selection attributes\n  -> Transform variation\n  -> Spawn/output\n```\n\nName reroutes and comment the contract at each stage. Delete temporary attributes before expensive\ncopy/spawn operations when they are no longer needed.\n\n## Attribute rules\n\n- Prefer semantic names such as `SurfaceSlopeDegrees`, `BiomeId`, `Mesh`, `ClearanceCm`.\n- Do not silently reuse one attribute with multiple units or meanings.\n- Use graph parameters for tool-level inputs; use point attributes for per-point decisions.\n- Use `Match And Set Attributes` for data-driven selection tables and weighted choices.\n- Use typed complex attributes in UE 5.8 only when downstream nodes/cook targets support them.\n\n## Determinism test\n\nGenerate, record point count/transforms/selected assets, cleanup, and regenerate with unchanged\ninputs. Results must match wherever deterministic output is required. Then change only the exposed\nseed and confirm intended variation changes without violating hard constraints.\n","searchText":"data model and graph design pcg data shapes | shape | use | |---|---| | volume | bounded 3d domain and boolean/spatial sampling | | surface | landscape/2d domain projected into the world | | line | spline and landscape spline data | | point data | explicit candidates with transform, bounds, density, steepness, color, seed | | polygon 2d | closed planar areas and polygon union/intersection/difference | | composite data | lazy spatial union/intersection/difference before concretizing | | attribute set | nonspatial typed metadata/parameters | keep spatial operations lazy as long as useful; convert/sample to explicit points only when a downstream point operation or spawner requires it. point contract for every point stream, document: - coordinate space and projection surface; - bounds represented by each point; - density meaning and expected range [0,1]; - seed source and any mutate seed boundary; - required metadata attributes, types, units, and defaults; - whether transform scale is semantic size or spawn transform; - which node owns rejection versus presentation. point seeds are derived in part from position for world-position consistency. operations that duplicate points can also duplicate random behavior; use mutate seed where independent random branches are intentional. graph layering use a readable staged graph: text input and bounds -> sampling/projection -> environmental attributes -> hard filters and exclusion -> density/weight shaping -> selection attributes -> transform variation -> spawn/output name reroutes and comment the contract at each stage. delete temporary attributes before expensive copy/spawn operations when they are no longer needed. attribute rules - prefer semantic names such as surfaceslopedegrees, biomeid, mesh, clearancecm. - do not silently reuse one attribute with multiple units or meanings. - use graph parameters for tool-level inputs; use point attributes for per-point decisions. - use match and set attributes for data-driven selection tables and weighted choices. - use typed complex attributes in ue 5.8 only when downstream nodes/cook targets support them. determinism test generate, record point count/transforms/selected assets, cleanup, and regenerate with unchanged inputs. results must match wherever deterministic output is required. then change only the exposed seed and confirm intended variation changes without violating hard constraints."},{"slug":"debugging-validation","file":"debugging-validation.md","title":"Debugging, validation, and profiling","rawMarkdown":"# Debugging, validation, and profiling\n\n## Graph-debug procedure\n\n1. Enable node Debug on the earliest suspicious stage.\n2. Inspect the Data View and Attributes List: count, bounds, density, transforms, seed, attributes.\n3. Move the debug point downstream one stage at a time.\n4. Disable spawners while validating data.\n5. Use graph/node profiling to identify CPU cost; use Unreal Insights for system-level cost.\n6. Cleanup and regenerate to eliminate stale output.\n\n## Runtime tools\n\n- `pcg.RuntimeGeneration.EnableDebugOverlay 1`: scheduler/runtime overview.\n- `pcg.GraphExecution.DebugDrawGeneratedCells 1`: sources, generating cells, grid/coordinates.\n- `pcg.RuntimeGeneration.EnableDebugging`: verbose scheduler logging.\n- `pcg.RuntimeGeneration.Refresh`: cleanup and schedule regeneration.\n- `pcg.RuntimeGeneration.Enable`: freeze/enable runtime generation.\n- `pcg.GPU.FuzzMemory`: expose uninitialized GPU output assumptions.\n\nDebug overlays are not generally available in Shipping and may differ by build configuration.\n\n## Validation matrix\n\n- empty input and zero points;\n- smallest and largest bounds;\n- steep/vertical/overhanging surfaces;\n- overlapping exclusion volumes and Data Layers;\n- seed zero, repeated seed, and changed seed;\n- missing asset/table row/soft reference;\n- cleanup -> regenerate -> reload -> cook;\n- source control clean checkout and commandlet generation;\n- target platform scalability/feature-level switches;\n- fast traversal/teleport and multiple runtime sources;\n- maximum shipping density plus HLOD/nav/collision build where required.\n\n## Common failures\n\n| Symptom | First check |\n|---|---|\n| Points exist but nothing spawns | mesh/actor selector attribute, bounds, node enabled, output path |\n| Same random choice repeats | duplicated seeds; place `Mutate Seed` at intentional branch |\n| Content leaks into roads/buildings | exclusion input/bounds and Difference mode/order |\n| Graph regenerates constantly | tracked actor/component changes or circular dependencies |\n| Runtime pop-in | generation radius, bounds modifier, scheduler budget, traversal speed |\n| Cleanup leaves stale actors | generation ownership, partition actors, grid change cleanup sequence |\n| GPU path slower | transfers, small data, compute-graph fragmentation, preparation cost |\n| Packaged result differs | editor-only input/node, unsupported platform path, unbuilt persistent output |\n\n## Performance record\n\nRecord point count, spawned instance/Actor count, CPU node times, GPU execution/memory, generation\nlatency percentile, cache memory, cleanup time, streaming overlap, and final render cost. PCG graph\ntime alone does not include the lifetime cost of what it spawned.\n","webMarkdown":"## Graph-debug procedure\n\n1. Enable node Debug on the earliest suspicious stage.\n2. Inspect the Data View and Attributes List: count, bounds, density, transforms, seed, attributes.\n3. Move the debug point downstream one stage at a time.\n4. Disable spawners while validating data.\n5. Use graph/node profiling to identify CPU cost; use Unreal Insights for system-level cost.\n6. Cleanup and regenerate to eliminate stale output.\n\n## Runtime tools\n\n- `pcg.RuntimeGeneration.EnableDebugOverlay 1`: scheduler/runtime overview.\n- `pcg.GraphExecution.DebugDrawGeneratedCells 1`: sources, generating cells, grid/coordinates.\n- `pcg.RuntimeGeneration.EnableDebugging`: verbose scheduler logging.\n- `pcg.RuntimeGeneration.Refresh`: cleanup and schedule regeneration.\n- `pcg.RuntimeGeneration.Enable`: freeze/enable runtime generation.\n- `pcg.GPU.FuzzMemory`: expose uninitialized GPU output assumptions.\n\nDebug overlays are not generally available in Shipping and may differ by build configuration.\n\n## Validation matrix\n\n- empty input and zero points;\n- smallest and largest bounds;\n- steep/vertical/overhanging surfaces;\n- overlapping exclusion volumes and Data Layers;\n- seed zero, repeated seed, and changed seed;\n- missing asset/table row/soft reference;\n- cleanup -> regenerate -> reload -> cook;\n- source control clean checkout and commandlet generation;\n- target platform scalability/feature-level switches;\n- fast traversal/teleport and multiple runtime sources;\n- maximum shipping density plus HLOD/nav/collision build where required.\n\n## Common failures\n\n| Symptom | First check |\n|---|---|\n| Points exist but nothing spawns | mesh/actor selector attribute, bounds, node enabled, output path |\n| Same random choice repeats | duplicated seeds; place `Mutate Seed` at intentional branch |\n| Content leaks into roads/buildings | exclusion input/bounds and Difference mode/order |\n| Graph regenerates constantly | tracked actor/component changes or circular dependencies |\n| Runtime pop-in | generation radius, bounds modifier, scheduler budget, traversal speed |\n| Cleanup leaves stale actors | generation ownership, partition actors, grid change cleanup sequence |\n| GPU path slower | transfers, small data, compute-graph fragmentation, preparation cost |\n| Packaged result differs | editor-only input/node, unsupported platform path, unbuilt persistent output |\n\n## Performance record\n\nRecord point count, spawned instance/Actor count, CPU node times, GPU execution/memory, generation\nlatency percentile, cache memory, cleanup time, streaming overlap, and final render cost. PCG graph\ntime alone does not include the lifetime cost of what it spawned.\n","searchText":"debugging, validation, and profiling graph-debug procedure 1. enable node debug on the earliest suspicious stage. 2. inspect the data view and attributes list: count, bounds, density, transforms, seed, attributes. 3. move the debug point downstream one stage at a time. 4. disable spawners while validating data. 5. use graph/node profiling to identify cpu cost; use unreal insights for system-level cost. 6. cleanup and regenerate to eliminate stale output. runtime tools - pcg.runtimegeneration.enabledebugoverlay 1: scheduler/runtime overview. - pcg.graphexecution.debugdrawgeneratedcells 1: sources, generating cells, grid/coordinates. - pcg.runtimegeneration.enabledebugging: verbose scheduler logging. - pcg.runtimegeneration.refresh: cleanup and schedule regeneration. - pcg.runtimegeneration.enable: freeze/enable runtime generation. - pcg.gpu.fuzzmemory: expose uninitialized gpu output assumptions. debug overlays are not generally available in shipping and may differ by build configuration. validation matrix - empty input and zero points; - smallest and largest bounds; - steep/vertical/overhanging surfaces; - overlapping exclusion volumes and data layers; - seed zero, repeated seed, and changed seed; - missing asset/table row/soft reference; - cleanup -> regenerate -> reload -> cook; - source control clean checkout and commandlet generation; - target platform scalability/feature-level switches; - fast traversal/teleport and multiple runtime sources; - maximum shipping density plus hlod/nav/collision build where required. common failures | symptom | first check | |---|---| | points exist but nothing spawns | mesh/actor selector attribute, bounds, node enabled, output path | | same random choice repeats | duplicated seeds; place mutate seed at intentional branch | | content leaks into roads/buildings | exclusion input/bounds and difference mode/order | | graph regenerates constantly | tracked actor/component changes or circular dependencies | | runtime pop-in | generation radius, bounds modifier, scheduler budget, traversal speed | | cleanup leaves stale actors | generation ownership, partition actors, grid change cleanup sequence | | gpu path slower | transfers, small data, compute-graph fragmentation, preparation cost | | packaged result differs | editor-only input/node, unsupported platform path, unbuilt persistent output | performance record record point count, spawned instance/actor count, cpu node times, gpu execution/memory, generation latency percentile, cache memory, cleanup time, streaming overlap, and final render cost. pcg graph time alone does not include the lifetime cost of what it spawned."},{"slug":"gpu-processing","file":"gpu-processing.md","title":"GPU processing","rawMarkdown":"# GPU processing\n\n## Maturity\n\n- PCG GPU Processing: **Beta** in UE 5.8.\n- GPU execution is available only on a subset of nodes, including Custom HLSL and supported point/\n  spawner operations.\n- GPU Procedural Instancing through GPU Static Mesh Spawner: **Experimental**.\n\n## Adoption procedure\n\n1. Profile the CPU graph and record node cost/point count.\n2. Confirm the target nodes support GPU execution on every shipping platform/feature level.\n3. Form one or a few long connected GPU compute regions.\n4. Minimize CPU -> GPU uploads and GPU -> CPU downloads.\n5. Compare end-to-end time, frame spikes, memory, and time-to-visible—not kernel time alone.\n6. Verify output equality/acceptable variation and regenerate under stress.\n7. Keep a CPU fallback or platform branch when coverage requires it.\n\nGPU setup and transfer have CPU cost. Small data sets or graphs that bounce between CPU and GPU\ncan be slower than CPU-only execution.\n\n## Experimental GPU procedural instances\n\nUse only for runtime visual meshes that do **not** require:\n\n- persisted/saved instance data;\n- collision or physics;\n- navigation;\n- ray tracing;\n- distance-field lighting contribution;\n- static baked lighting;\n- HLOD.\n\nThese instances live only at runtime in GPU memory. A GPU visual forest is not automatically a\nwalkable, collidable, nav-aware, HLOD-buildable forest.\n\n## Custom HLSL\n\n- Declare inputs/outputs and created attributes explicitly or use UE 5.8's supported source\n  parsing path.\n- Initialize every output; test with `pcg.GPU.FuzzMemory` to expose uninitialized memory use.\n- Bound threads/data sizes and handle empty inputs.\n- Use platform/feature-level switches for unsupported paths.\n- Keep the HLSL contract documented beside the node; shader code is not self-validating.\n\n## Profiling\n\nUE 5.8 adds GPU execution time and GPU-created memory to the PCG Profiling window. Use platform GPU\ntools for kernel detail. Runtime PCG is bursty; use Profile Kernel Index only as a controlled\nprofiling aid and disable it afterward.\n","webMarkdown":"## Maturity\n\n- PCG GPU Processing: **Beta** in UE 5.8.\n- GPU execution is available only on a subset of nodes, including Custom HLSL and supported point/\n  spawner operations.\n- GPU Procedural Instancing through GPU Static Mesh Spawner: **Experimental**.\n\n## Adoption procedure\n\n1. Profile the CPU graph and record node cost/point count.\n2. Confirm the target nodes support GPU execution on every shipping platform/feature level.\n3. Form one or a few long connected GPU compute regions.\n4. Minimize CPU -> GPU uploads and GPU -> CPU downloads.\n5. Compare end-to-end time, frame spikes, memory, and time-to-visible—not kernel time alone.\n6. Verify output equality/acceptable variation and regenerate under stress.\n7. Keep a CPU fallback or platform branch when coverage requires it.\n\nGPU setup and transfer have CPU cost. Small data sets or graphs that bounce between CPU and GPU\ncan be slower than CPU-only execution.\n\n## Experimental GPU procedural instances\n\nUse only for runtime visual meshes that do **not** require:\n\n- persisted/saved instance data;\n- collision or physics;\n- navigation;\n- ray tracing;\n- distance-field lighting contribution;\n- static baked lighting;\n- HLOD.\n\nThese instances live only at runtime in GPU memory. A GPU visual forest is not automatically a\nwalkable, collidable, nav-aware, HLOD-buildable forest.\n\n## Custom HLSL\n\n- Declare inputs/outputs and created attributes explicitly or use UE 5.8's supported source\n  parsing path.\n- Initialize every output; test with `pcg.GPU.FuzzMemory` to expose uninitialized memory use.\n- Bound threads/data sizes and handle empty inputs.\n- Use platform/feature-level switches for unsupported paths.\n- Keep the HLSL contract documented beside the node; shader code is not self-validating.\n\n## Profiling\n\nUE 5.8 adds GPU execution time and GPU-created memory to the PCG Profiling window. Use platform GPU\ntools for kernel detail. Runtime PCG is bursty; use Profile Kernel Index only as a controlled\nprofiling aid and disable it afterward.\n","searchText":"gpu processing maturity - pcg gpu processing: beta in ue 5.8. - gpu execution is available only on a subset of nodes, including custom hlsl and supported point/ spawner operations. - gpu procedural instancing through gpu static mesh spawner: experimental. adoption procedure 1. profile the cpu graph and record node cost/point count. 2. confirm the target nodes support gpu execution on every shipping platform/feature level. 3. form one or a few long connected gpu compute regions. 4. minimize cpu -> gpu uploads and gpu -> cpu downloads. 5. compare end-to-end time, frame spikes, memory, and time-to-visible—not kernel time alone. 6. verify output equality/acceptable variation and regenerate under stress. 7. keep a cpu fallback or platform branch when coverage requires it. gpu setup and transfer have cpu cost. small data sets or graphs that bounce between cpu and gpu can be slower than cpu-only execution. experimental gpu procedural instances use only for runtime visual meshes that do not require: - persisted/saved instance data; - collision or physics; - navigation; - ray tracing; - distance-field lighting contribution; - static baked lighting; - hlod. these instances live only at runtime in gpu memory. a gpu visual forest is not automatically a walkable, collidable, nav-aware, hlod-buildable forest. custom hlsl - declare inputs/outputs and created attributes explicitly or use ue 5.8's supported source parsing path. - initialize every output; test with pcg.gpu.fuzzmemory to expose uninitialized memory use. - bound threads/data sizes and handle empty inputs. - use platform/feature-level switches for unsupported paths. - keep the hlsl contract documented beside the node; shader code is not self-validating. profiling ue 5.8 adds gpu execution time and gpu-created memory to the pcg profiling window. use platform gpu tools for kernel detail. runtime pcg is bursty; use profile kernel index only as a controlled profiling aid and disable it afterward."},{"slug":"parameters-tools-overrides","file":"parameters-tools-overrides.md","title":"Parameters, subgraphs, tools, and manual overrides","rawMarkdown":"# Parameters, subgraphs, tools, and manual overrides\n\n## Expose parameters deliberately\n\nExpose only values that define a meaningful tool instance:\n\n- density/count target;\n- seed;\n- allowed slope/height;\n- clearance distance;\n- asset set or selection table;\n- scale/rotation range;\n- grid/runtime generation settings when instance variation is legitimate.\n\nGive each parameter a category, order, description, unit, safe range, and default in UE 5.8's\nGraph Parameters hierarchy editor. Do not expose internal scratch attributes.\n\n## Reuse hierarchy\n\n- Use named subgraphs for reusable pipeline stages.\n- Use UE 5.8 embedded subgraphs for graph-local function-like logic.\n- Use graph instances for variations that share implementation but override parameters.\n- Mark a graph as a template when it is a starting structure, not a live shared dependency.\n- Keep the interface small; sprawling pins usually indicate missing stage boundaries.\n\n## PCG Editor Mode\n\nPCG Editor Mode is Experimental in UE 5.8. It provides Draw Spline, Draw Spline Surface, Paint,\nand Volume tools driven by graphs/presets.\n\nFor a tool graph:\n\n1. Set compatible tool tags (`SplineTool`, `SplineSurfaceTool`, `PaintTool`, `VolumeTool`).\n2. Define the initial actor class and a clear spawned-actor/component naming policy.\n3. Expose only instance parameters the artist needs while interacting.\n4. Define raycast rules for landscapes, meshes, ignored PCG components, allowed classes, and\n   selection constraints.\n5. Test Apply, Cancel, undo/redo, reload, source control, and regeneration.\n\n## UE 5.8 manual editing/data overrides\n\nThe new non-destructive manual-editing/Data Override system is Experimental.\n\n- Mark only the node/output that owns artist-editable data for manual editing.\n- Use selection, exclusion, modification, and restore rather than detaching the whole result.\n- Inspect all overrides in the Data Overrides window.\n- Define team policy: override intent, author, and whether it survives graph regeneration.\n- Verify overrides after upstream graph edits, cleanup/regenerate, map reload, cook, and merge.\n- Prefer a source input/exclusion layer when an exception is systemic; reserve manual overrides\n  for genuine local art direction.\n\nDo not silently convert override data into graph constants or delete it during cleanup.\n","webMarkdown":"## Expose parameters deliberately\n\nExpose only values that define a meaningful tool instance:\n\n- density/count target;\n- seed;\n- allowed slope/height;\n- clearance distance;\n- asset set or selection table;\n- scale/rotation range;\n- grid/runtime generation settings when instance variation is legitimate.\n\nGive each parameter a category, order, description, unit, safe range, and default in UE 5.8's\nGraph Parameters hierarchy editor. Do not expose internal scratch attributes.\n\n## Reuse hierarchy\n\n- Use named subgraphs for reusable pipeline stages.\n- Use UE 5.8 embedded subgraphs for graph-local function-like logic.\n- Use graph instances for variations that share implementation but override parameters.\n- Mark a graph as a template when it is a starting structure, not a live shared dependency.\n- Keep the interface small; sprawling pins usually indicate missing stage boundaries.\n\n## PCG Editor Mode\n\nPCG Editor Mode is Experimental in UE 5.8. It provides Draw Spline, Draw Spline Surface, Paint,\nand Volume tools driven by graphs/presets.\n\nFor a tool graph:\n\n1. Set compatible tool tags (`SplineTool`, `SplineSurfaceTool`, `PaintTool`, `VolumeTool`).\n2. Define the initial actor class and a clear spawned-actor/component naming policy.\n3. Expose only instance parameters the artist needs while interacting.\n4. Define raycast rules for landscapes, meshes, ignored PCG components, allowed classes, and\n   selection constraints.\n5. Test Apply, Cancel, undo/redo, reload, source control, and regeneration.\n\n## UE 5.8 manual editing/data overrides\n\nThe new non-destructive manual-editing/Data Override system is Experimental.\n\n- Mark only the node/output that owns artist-editable data for manual editing.\n- Use selection, exclusion, modification, and restore rather than detaching the whole result.\n- Inspect all overrides in the Data Overrides window.\n- Define team policy: override intent, author, and whether it survives graph regeneration.\n- Verify overrides after upstream graph edits, cleanup/regenerate, map reload, cook, and merge.\n- Prefer a source input/exclusion layer when an exception is systemic; reserve manual overrides\n  for genuine local art direction.\n\nDo not silently convert override data into graph constants or delete it during cleanup.\n","searchText":"parameters, subgraphs, tools, and manual overrides expose parameters deliberately expose only values that define a meaningful tool instance: - density/count target; - seed; - allowed slope/height; - clearance distance; - asset set or selection table; - scale/rotation range; - grid/runtime generation settings when instance variation is legitimate. give each parameter a category, order, description, unit, safe range, and default in ue 5.8's graph parameters hierarchy editor. do not expose internal scratch attributes. reuse hierarchy - use named subgraphs for reusable pipeline stages. - use ue 5.8 embedded subgraphs for graph-local function-like logic. - use graph instances for variations that share implementation but override parameters. - mark a graph as a template when it is a starting structure, not a live shared dependency. - keep the interface small; sprawling pins usually indicate missing stage boundaries. pcg editor mode pcg editor mode is experimental in ue 5.8. it provides draw spline, draw spline surface, paint, and volume tools driven by graphs/presets. for a tool graph: 1. set compatible tool tags (splinetool, splinesurfacetool, painttool, volumetool). 2. define the initial actor class and a clear spawned-actor/component naming policy. 3. expose only instance parameters the artist needs while interacting. 4. define raycast rules for landscapes, meshes, ignored pcg components, allowed classes, and selection constraints. 5. test apply, cancel, undo/redo, reload, source control, and regeneration. ue 5.8 manual editing/data overrides the new non-destructive manual-editing/data override system is experimental. - mark only the node/output that owns artist-editable data for manual editing. - use selection, exclusion, modification, and restore rather than detaching the whole result. - inspect all overrides in the data overrides window. - define team policy: override intent, author, and whether it survives graph regeneration. - verify overrides after upstream graph edits, cleanup/regenerate, map reload, cook, and merge. - prefer a source input/exclusion layer when an exception is systemic; reserve manual overrides for genuine local art direction. do not silently convert override data into graph constants or delete it during cleanup."},{"slug":"runtime-scheduling","file":"runtime-scheduling.md","title":"Runtime generation and scheduling","rawMarkdown":"# Runtime generation and scheduling\n\n## Configure runtime generation\n\n1. Set the PCG Component Generation Trigger to Generate at Runtime.\n2. Enable Hierarchical Generation if multiple grid scales are required.\n3. Configure generation radius for each grid size.\n4. Configure Cleanup Radius Multiplier so content is not destroyed immediately at the generation\n   boundary.\n5. Use Generate/Cleanup Bounds Modifiers to begin work before the source looks toward content and\n   reduce visible pops.\n6. Define generation sources: player/camera, editor viewport for testing, or custom sources.\n7. Choose a scheduling policy from actual traversal direction, distance, and urgency needs.\n8. Test source teleport, rapid direction reversal, fast vehicles, multiple players/sources, and\n   no-source cleanup.\n\n## Budget controls\n\nRelevant UE 5.8 variables include:\n\n- `pcg.FrameTime`: runtime PCG execution budget in milliseconds.\n- `pcg.RuntimeGeneration.NumGeneratingComponents`: parallel generating components.\n- `pcg.RuntimeGeneration.FramesBetweenGraphSchedules`: scheduler delay between schedule passes.\n- `pcg.RuntimeGeneration.EnablePooling`: partition-actor pooling.\n- `pcg.Cache.Runtime.Enabled`: runtime CPU-node cache; disabled by default.\n- `pcg.Cache.Runtime.MemoryBudgetMB`: runtime cache memory cap.\n\nDo not copy documented defaults blindly. Tune on target hardware for time-to-screen, hitching,\nmemory, and background contention with gameplay/streaming.\n\n## Failure policy\n\nDefine behavior when generation is late:\n\n- hide with fog/distance/occlusion;\n- preserve lower-detail/baked fallback;\n- prevent access until generation completes;\n- reduce small-grid detail before missing large silhouette content;\n- prioritize forward/travel-direction cells.\n\nDo not let missing collision or gameplay Actors become a visual-pop problem; that is a correctness\nfailure.\n\n## Multiplayer\n\nPCG output is not automatically authoritative or replicated. Choose explicitly:\n\n- identical local cosmetic generation from controlled inputs/seeds;\n- server-generated replicated gameplay Actors;\n- baked/persisted world content streamed normally;\n- server-authored compact state that each client converts into local presentation.\n\nTest determinism across builds/platforms before relying on identical local generation for anything\nmore than cosmetic presentation.\n","webMarkdown":"## Configure runtime generation\n\n1. Set the PCG Component Generation Trigger to Generate at Runtime.\n2. Enable Hierarchical Generation if multiple grid scales are required.\n3. Configure generation radius for each grid size.\n4. Configure Cleanup Radius Multiplier so content is not destroyed immediately at the generation\n   boundary.\n5. Use Generate/Cleanup Bounds Modifiers to begin work before the source looks toward content and\n   reduce visible pops.\n6. Define generation sources: player/camera, editor viewport for testing, or custom sources.\n7. Choose a scheduling policy from actual traversal direction, distance, and urgency needs.\n8. Test source teleport, rapid direction reversal, fast vehicles, multiple players/sources, and\n   no-source cleanup.\n\n## Budget controls\n\nRelevant UE 5.8 variables include:\n\n- `pcg.FrameTime`: runtime PCG execution budget in milliseconds.\n- `pcg.RuntimeGeneration.NumGeneratingComponents`: parallel generating components.\n- `pcg.RuntimeGeneration.FramesBetweenGraphSchedules`: scheduler delay between schedule passes.\n- `pcg.RuntimeGeneration.EnablePooling`: partition-actor pooling.\n- `pcg.Cache.Runtime.Enabled`: runtime CPU-node cache; disabled by default.\n- `pcg.Cache.Runtime.MemoryBudgetMB`: runtime cache memory cap.\n\nDo not copy documented defaults blindly. Tune on target hardware for time-to-screen, hitching,\nmemory, and background contention with gameplay/streaming.\n\n## Failure policy\n\nDefine behavior when generation is late:\n\n- hide with fog/distance/occlusion;\n- preserve lower-detail/baked fallback;\n- prevent access until generation completes;\n- reduce small-grid detail before missing large silhouette content;\n- prioritize forward/travel-direction cells.\n\nDo not let missing collision or gameplay Actors become a visual-pop problem; that is a correctness\nfailure.\n\n## Multiplayer\n\nPCG output is not automatically authoritative or replicated. Choose explicitly:\n\n- identical local cosmetic generation from controlled inputs/seeds;\n- server-generated replicated gameplay Actors;\n- baked/persisted world content streamed normally;\n- server-authored compact state that each client converts into local presentation.\n\nTest determinism across builds/platforms before relying on identical local generation for anything\nmore than cosmetic presentation.\n","searchText":"runtime generation and scheduling configure runtime generation 1. set the pcg component generation trigger to generate at runtime. 2. enable hierarchical generation if multiple grid scales are required. 3. configure generation radius for each grid size. 4. configure cleanup radius multiplier so content is not destroyed immediately at the generation boundary. 5. use generate/cleanup bounds modifiers to begin work before the source looks toward content and reduce visible pops. 6. define generation sources: player/camera, editor viewport for testing, or custom sources. 7. choose a scheduling policy from actual traversal direction, distance, and urgency needs. 8. test source teleport, rapid direction reversal, fast vehicles, multiple players/sources, and no-source cleanup. budget controls relevant ue 5.8 variables include: - pcg.frametime: runtime pcg execution budget in milliseconds. - pcg.runtimegeneration.numgeneratingcomponents: parallel generating components. - pcg.runtimegeneration.framesbetweengraphschedules: scheduler delay between schedule passes. - pcg.runtimegeneration.enablepooling: partition-actor pooling. - pcg.cache.runtime.enabled: runtime cpu-node cache; disabled by default. - pcg.cache.runtime.memorybudgetmb: runtime cache memory cap. do not copy documented defaults blindly. tune on target hardware for time-to-screen, hitching, memory, and background contention with gameplay/streaming. failure policy define behavior when generation is late: - hide with fog/distance/occlusion; - preserve lower-detail/baked fallback; - prevent access until generation completes; - reduce small-grid detail before missing large silhouette content; - prioritize forward/travel-direction cells. do not let missing collision or gameplay actors become a visual-pop problem; that is a correctness failure. multiplayer pcg output is not automatically authoritative or replicated. choose explicitly: - identical local cosmetic generation from controlled inputs/seeds; - server-generated replicated gameplay actors; - baked/persisted world content streamed normally; - server-authored compact state that each client converts into local presentation. test determinism across builds/platforms before relying on identical local generation for anything more than cosmetic presentation."},{"slug":"sampling-spawning-patterns","file":"sampling-spawning-patterns.md","title":"Sampling, filtering, and spawning","rawMarkdown":"# Sampling, filtering, and spawning\n\n## Surface scatter procedure\n\n1. Obtain actor/landscape/surface data within explicit component bounds.\n2. Use Surface Sampler or the appropriate sampler to produce candidate points.\n3. Project/re-project after transforms that move points off the target surface.\n4. Compute slope, height, surface type/tag, density, and clearance attributes.\n5. Apply hard filters before random thinning.\n6. Subtract roads, structures, water, paths, and gameplay-clearance shapes with Difference or\n   point filters.\n7. Use density/weights for natural distribution and mesh choice.\n8. Transform points within bounded rotation/scale ranges.\n9. Inspect points and bounds before Static Mesh Spawner/Spawn Actor.\n\n## Exclusion and spacing\n\n- Use spatial Difference for clear exclusion shapes.\n- Use Distance to create a gradient near another point set; filter/remap the result.\n- Use Self Pruning or neighborhood logic for overlap/spacing, choosing bounds and pruning order\n  intentionally.\n- Account for final mesh bounds, not only pivot distance.\n- Keep critical traversal and gameplay sightlines as hard constraints, never probability alone.\n\n## Mesh selection\n\n- Drive mesh/material/scale selection from explicit attributes or weighted selector data.\n- Use Data Tables/Attribute Sets plus `Match And Set Attributes` for editable catalogs.\n- Keep asset references soft/async where the generation and loading model requires it.\n- Prefer instancing for repeated static meshes; use Actors only when Actor behavior is required.\n\n## Spline pattern\n\n1. Get Spline Data from the intended actor/component.\n2. Sample by distance, subdivision, or control-point semantics appropriate to the asset.\n3. Write tangent/orientation/width/side attributes.\n4. Offset or project candidates.\n5. Exclude intersections and invalid surface regions.\n6. Spawn fence posts, roadside objects, or downstream spline/mesh data.\n\nUse Shape Grammar when a repeatable module grammar materially simplifies fences/buildings; do not\nforce grammar onto free-form scatter.\n\n## Spawn-output selector\n\n| Output | Use |\n|---|---|\n| ISM/HISM/static mesh spawner | repeated static visual content |\n| Spawn Actor | behavior, identity, components, or independent lifecycle required |\n| Output node data | downstream PCG component/subgraph consumes points/attributes |\n| PCG Data Asset | reusable baked data exchange |\n\nDo not spawn thousands of Actors for decoration. Do not use GPU procedural instances for outputs\nthat need collision, nav, HLOD, persistence, ray tracing, or distance fields.\n","webMarkdown":"## Surface scatter procedure\n\n1. Obtain actor/landscape/surface data within explicit component bounds.\n2. Use Surface Sampler or the appropriate sampler to produce candidate points.\n3. Project/re-project after transforms that move points off the target surface.\n4. Compute slope, height, surface type/tag, density, and clearance attributes.\n5. Apply hard filters before random thinning.\n6. Subtract roads, structures, water, paths, and gameplay-clearance shapes with Difference or\n   point filters.\n7. Use density/weights for natural distribution and mesh choice.\n8. Transform points within bounded rotation/scale ranges.\n9. Inspect points and bounds before Static Mesh Spawner/Spawn Actor.\n\n## Exclusion and spacing\n\n- Use spatial Difference for clear exclusion shapes.\n- Use Distance to create a gradient near another point set; filter/remap the result.\n- Use Self Pruning or neighborhood logic for overlap/spacing, choosing bounds and pruning order\n  intentionally.\n- Account for final mesh bounds, not only pivot distance.\n- Keep critical traversal and gameplay sightlines as hard constraints, never probability alone.\n\n## Mesh selection\n\n- Drive mesh/material/scale selection from explicit attributes or weighted selector data.\n- Use Data Tables/Attribute Sets plus `Match And Set Attributes` for editable catalogs.\n- Keep asset references soft/async where the generation and loading model requires it.\n- Prefer instancing for repeated static meshes; use Actors only when Actor behavior is required.\n\n## Spline pattern\n\n1. Get Spline Data from the intended actor/component.\n2. Sample by distance, subdivision, or control-point semantics appropriate to the asset.\n3. Write tangent/orientation/width/side attributes.\n4. Offset or project candidates.\n5. Exclude intersections and invalid surface regions.\n6. Spawn fence posts, roadside objects, or downstream spline/mesh data.\n\nUse Shape Grammar when a repeatable module grammar materially simplifies fences/buildings; do not\nforce grammar onto free-form scatter.\n\n## Spawn-output selector\n\n| Output | Use |\n|---|---|\n| ISM/HISM/static mesh spawner | repeated static visual content |\n| Spawn Actor | behavior, identity, components, or independent lifecycle required |\n| Output node data | downstream PCG component/subgraph consumes points/attributes |\n| PCG Data Asset | reusable baked data exchange |\n\nDo not spawn thousands of Actors for decoration. Do not use GPU procedural instances for outputs\nthat need collision, nav, HLOD, persistence, ray tracing, or distance fields.\n","searchText":"sampling, filtering, and spawning surface scatter procedure 1. obtain actor/landscape/surface data within explicit component bounds. 2. use surface sampler or the appropriate sampler to produce candidate points. 3. project/re-project after transforms that move points off the target surface. 4. compute slope, height, surface type/tag, density, and clearance attributes. 5. apply hard filters before random thinning. 6. subtract roads, structures, water, paths, and gameplay-clearance shapes with difference or point filters. 7. use density/weights for natural distribution and mesh choice. 8. transform points within bounded rotation/scale ranges. 9. inspect points and bounds before static mesh spawner/spawn actor. exclusion and spacing - use spatial difference for clear exclusion shapes. - use distance to create a gradient near another point set; filter/remap the result. - use self pruning or neighborhood logic for overlap/spacing, choosing bounds and pruning order intentionally. - account for final mesh bounds, not only pivot distance. - keep critical traversal and gameplay sightlines as hard constraints, never probability alone. mesh selection - drive mesh/material/scale selection from explicit attributes or weighted selector data. - use data tables/attribute sets plus match and set attributes for editable catalogs. - keep asset references soft/async where the generation and loading model requires it. - prefer instancing for repeated static meshes; use actors only when actor behavior is required. spline pattern 1. get spline data from the intended actor/component. 2. sample by distance, subdivision, or control-point semantics appropriate to the asset. 3. write tangent/orientation/width/side attributes. 4. offset or project candidates. 5. exclude intersections and invalid surface regions. 6. spawn fence posts, roadside objects, or downstream spline/mesh data. use shape grammar when a repeatable module grammar materially simplifies fences/buildings; do not force grammar onto free-form scatter. spawn-output selector | output | use | |---|---| | ism/hism/static mesh spawner | repeated static visual content | | spawn actor | behavior, identity, components, or independent lifecycle required | | output node data | downstream pcg component/subgraph consumes points/attributes | | pcg data asset | reusable baked data exchange | do not spawn thousands of actors for decoration. do not use gpu procedural instances for outputs that need collision, nav, hlod, persistence, ray tracing, or distance fields."},{"slug":"sources","file":"sources.md","title":"UE 5.8 primary sources","rawMarkdown":"# UE 5.8 primary sources\n\nAll links were checked against Epic's UE 5.8 documentation on 2026-07-19.\n\n## Core framework\n\n- [PCG framework](https://dev.epicgames.com/documentation/en-us/unreal-engine/procedural-content-generation-framework-in-unreal-engine)\n- [PCG overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/procedural-content-generation-overview)\n- [PCG data types reference](https://dev.epicgames.com/documentation/en-us/unreal-engine/procedural-content-generation-framework-data-types-reference-in-unreal-engine)\n- [PCG node reference](https://dev.epicgames.com/documentation/en-us/unreal-engine/procedural-content-generation-framework-node-reference-in-unreal-engine)\n- [PCG generation modes](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-pcg-generation-modes-in-unreal-engine)\n\n## UE 5.8 workflows and performance\n\n- [UE 5.8 release notes: PCG](https://dev.epicgames.com/documentation/unreal-engine/unreal-engine-5-8-release-notes?lang=en-US)\n- [PCG Editor Mode](https://dev.epicgames.com/documentation/en-us/unreal-engine/pcg-editor-mode-in-unreal-engine)\n- [PCG with GPU Processing](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-pcg-with-gpu-processing-in-unreal-engine)\n- [PCG Runtime Generation Debugging](https://dev.epicgames.com/documentation/en-us/unreal-engine/pcg-runtime-generation-debugging-in-unreal-engine)\n- [Shape Grammar with PCG](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-shape-grammar-with-pcg-in-unreal-engine)\n- [PCG Biome Core overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/procedural-content-generation-pcg-biome-core-and-sample-plugins-overview-guide-in-unreal-engine)\n\n## Large-world integration and automation\n\n- [PCG with World Partition](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-pcg-with-world-partition-in-unreal-engine)\n- [World Partition Builder commandlets](https://dev.epicgames.com/documentation/en-us/unreal-engine/world-partition-builder-commandlet-reference)\n- [Working with PCG and LLMs using Unreal MCP](https://dev.epicgames.com/documentation/unreal-engine/working-with-pcg-and-llms-using-unreal-mcp-in-unreal-engine)\n\n## UE 5.8 maturity notes\n\n- PCG Editor Mode and the new manual Data Override system are Experimental.\n- PCG GPU Processing is Beta.\n- GPU Procedural Instancing and PCG Biome Core/Sample are Experimental.\n","webMarkdown":"All links were checked against Epic's UE 5.8 documentation on 2026-07-19.\n\n## Core framework\n\n- [PCG framework](https://dev.epicgames.com/documentation/en-us/unreal-engine/procedural-content-generation-framework-in-unreal-engine)\n- [PCG overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/procedural-content-generation-overview)\n- [PCG data types reference](https://dev.epicgames.com/documentation/en-us/unreal-engine/procedural-content-generation-framework-data-types-reference-in-unreal-engine)\n- [PCG node reference](https://dev.epicgames.com/documentation/en-us/unreal-engine/procedural-content-generation-framework-node-reference-in-unreal-engine)\n- [PCG generation modes](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-pcg-generation-modes-in-unreal-engine)\n\n## UE 5.8 workflows and performance\n\n- [UE 5.8 release notes: PCG](https://dev.epicgames.com/documentation/unreal-engine/unreal-engine-5-8-release-notes?lang=en-US)\n- [PCG Editor Mode](https://dev.epicgames.com/documentation/en-us/unreal-engine/pcg-editor-mode-in-unreal-engine)\n- [PCG with GPU Processing](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-pcg-with-gpu-processing-in-unreal-engine)\n- [PCG Runtime Generation Debugging](https://dev.epicgames.com/documentation/en-us/unreal-engine/pcg-runtime-generation-debugging-in-unreal-engine)\n- [Shape Grammar with PCG](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-shape-grammar-with-pcg-in-unreal-engine)\n- [PCG Biome Core overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/procedural-content-generation-pcg-biome-core-and-sample-plugins-overview-guide-in-unreal-engine)\n\n## Large-world integration and automation\n\n- [PCG with World Partition](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-pcg-with-world-partition-in-unreal-engine)\n- [World Partition Builder commandlets](https://dev.epicgames.com/documentation/en-us/unreal-engine/world-partition-builder-commandlet-reference)\n- [Working with PCG and LLMs using Unreal MCP](https://dev.epicgames.com/documentation/unreal-engine/working-with-pcg-and-llms-using-unreal-mcp-in-unreal-engine)\n\n## UE 5.8 maturity notes\n\n- PCG Editor Mode and the new manual Data Override system are Experimental.\n- PCG GPU Processing is Beta.\n- GPU Procedural Instancing and PCG Biome Core/Sample are Experimental.\n","searchText":"ue 5.8 primary sources all links were checked against epic's ue 5.8 documentation on 2026-07-19. core framework - pcg framework - pcg overview - pcg data types reference - pcg node reference - pcg generation modes ue 5.8 workflows and performance - ue 5.8 release notes: pcg - pcg editor mode - pcg with gpu processing - pcg runtime generation debugging - shape grammar with pcg - pcg biome core overview large-world integration and automation - pcg with world partition - world partition builder commandlets - working with pcg and llms using unreal mcp ue 5.8 maturity notes - pcg editor mode and the new manual data override system are experimental. - pcg gpu processing is beta. - gpu procedural instancing and pcg biome core/sample are experimental."},{"slug":"system-selector","file":"system-selector.md","title":"PCG system selector","rawMarkdown":"# PCG system selector\n\n## Choose the generation mode\n\n| Need | Mode | Cost/constraint |\n|---|---|---|\n| Small bounded authoring tool | Non-partitioned editor generation | simplest; one component domain |\n| Large persistent generated area | Partitioned editor generation | grid cells integrate with streaming |\n| Multiple detail scales | Hierarchical generation | shared large-grid work feeds smaller grids |\n| Viewer/source-dependent transient content | Runtime generation | scheduler, memory, cleanup, and pop budget |\n\nPCG generation modes are not visual-quality settings. Select them from domain size, update\nfrequency, output lifetime, and streaming requirements.\n\n## Bake versus runtime\n\nPrefer editor-generated/baked output when content needs:\n\n- manual art review and source-control visibility;\n- HLOD or static baked lighting;\n- persistent instance data;\n- collision, navigation, ray tracing, or distance-field participation;\n- deterministic cook output without runtime generation stalls.\n\nUse runtime generation when player position, runtime terrain/state, or effectively unbounded\ncontent makes baking impractical. Runtime generation must define generation sources, radii,\ncleanup radii, scheduling policy, memory/caching, and what happens when generation falls behind.\n\n## Partitioned versus hierarchical\n\n- Partitioned generation divides one component's domain into PCG grid cells.\n- Hierarchical generation lets branches execute at different grid sizes through Grid Size nodes.\n- Put broad, reusable calculations on larger grids and dense local detail on smaller grids.\n- Data produced on a larger hierarchical grid is cached for smaller-grid execution.\n- Choose cell/grid size from content size and cost, not one universal number.\n\n## CPU versus GPU\n\nStay on CPU for small point counts, frequent CPU consumers, Actor spawning, unsupported nodes, or\nwhen transfer overhead dominates. Evaluate GPU when long connected GPU-capable regions process\nenough points to amortize upload/download and compute-graph setup.\n\nPCG GPU Processing is Beta. GPU procedural instancing is a narrower Experimental output path with\nmajor persistence and feature limitations. See `gpu-processing.md`.\n\n## Related skills\n\n- Route World Partition/Data Layer/HLOD ownership to `$unreal-world-partition`.\n- Route spline construction and spline meshes to `$unreal-splines`.\n- Route asset definitions/soft loading to the future `unreal-data-assets-tables` skill.\n- Route final bottleneck work to `$unreal-insights-profiling` when available.\n","webMarkdown":"## Choose the generation mode\n\n| Need | Mode | Cost/constraint |\n|---|---|---|\n| Small bounded authoring tool | Non-partitioned editor generation | simplest; one component domain |\n| Large persistent generated area | Partitioned editor generation | grid cells integrate with streaming |\n| Multiple detail scales | Hierarchical generation | shared large-grid work feeds smaller grids |\n| Viewer/source-dependent transient content | Runtime generation | scheduler, memory, cleanup, and pop budget |\n\nPCG generation modes are not visual-quality settings. Select them from domain size, update\nfrequency, output lifetime, and streaming requirements.\n\n## Bake versus runtime\n\nPrefer editor-generated/baked output when content needs:\n\n- manual art review and source-control visibility;\n- HLOD or static baked lighting;\n- persistent instance data;\n- collision, navigation, ray tracing, or distance-field participation;\n- deterministic cook output without runtime generation stalls.\n\nUse runtime generation when player position, runtime terrain/state, or effectively unbounded\ncontent makes baking impractical. Runtime generation must define generation sources, radii,\ncleanup radii, scheduling policy, memory/caching, and what happens when generation falls behind.\n\n## Partitioned versus hierarchical\n\n- Partitioned generation divides one component's domain into PCG grid cells.\n- Hierarchical generation lets branches execute at different grid sizes through Grid Size nodes.\n- Put broad, reusable calculations on larger grids and dense local detail on smaller grids.\n- Data produced on a larger hierarchical grid is cached for smaller-grid execution.\n- Choose cell/grid size from content size and cost, not one universal number.\n\n## CPU versus GPU\n\nStay on CPU for small point counts, frequent CPU consumers, Actor spawning, unsupported nodes, or\nwhen transfer overhead dominates. Evaluate GPU when long connected GPU-capable regions process\nenough points to amortize upload/download and compute-graph setup.\n\nPCG GPU Processing is Beta. GPU procedural instancing is a narrower Experimental output path with\nmajor persistence and feature limitations. See `gpu-processing.md`.\n\n## Related skills\n\n- Route World Partition/Data Layer/HLOD ownership to `$unreal-world-partition`.\n- Route spline construction and spline meshes to `$unreal-splines`.\n- Route asset definitions/soft loading to the future `unreal-data-assets-tables` skill.\n- Route final bottleneck work to `$unreal-insights-profiling` when available.\n","searchText":"pcg system selector choose the generation mode | need | mode | cost/constraint | |---|---|---| | small bounded authoring tool | non-partitioned editor generation | simplest; one component domain | | large persistent generated area | partitioned editor generation | grid cells integrate with streaming | | multiple detail scales | hierarchical generation | shared large-grid work feeds smaller grids | | viewer/source-dependent transient content | runtime generation | scheduler, memory, cleanup, and pop budget | pcg generation modes are not visual-quality settings. select them from domain size, update frequency, output lifetime, and streaming requirements. bake versus runtime prefer editor-generated/baked output when content needs: - manual art review and source-control visibility; - hlod or static baked lighting; - persistent instance data; - collision, navigation, ray tracing, or distance-field participation; - deterministic cook output without runtime generation stalls. use runtime generation when player position, runtime terrain/state, or effectively unbounded content makes baking impractical. runtime generation must define generation sources, radii, cleanup radii, scheduling policy, memory/caching, and what happens when generation falls behind. partitioned versus hierarchical - partitioned generation divides one component's domain into pcg grid cells. - hierarchical generation lets branches execute at different grid sizes through grid size nodes. - put broad, reusable calculations on larger grids and dense local detail on smaller grids. - data produced on a larger hierarchical grid is cached for smaller-grid execution. - choose cell/grid size from content size and cost, not one universal number. cpu versus gpu stay on cpu for small point counts, frequent cpu consumers, actor spawning, unsupported nodes, or when transfer overhead dominates. evaluate gpu when long connected gpu-capable regions process enough points to amortize upload/download and compute-graph setup. pcg gpu processing is beta. gpu procedural instancing is a narrower experimental output path with major persistence and feature limitations. see gpu-processing.md. related skills - route world partition/data layer/hlod ownership to $unreal-world-partition. - route spline construction and spline meshes to $unreal-splines. - route asset definitions/soft loading to the future unreal-data-assets-tables skill. - route final bottleneck work to $unreal-insights-profiling when available."},{"slug":"use-cases","file":"use-cases.md","title":"Use cases","rawMarkdown":"# Use cases\n\n## Vegetation scatter\n\n- Landscape/surface -> slope/height/surface attributes -> road/water/POI Difference -> density\n  noise -> weighted species selection -> bounded transform -> instanced mesh spawn.\n- Partition/hierarchy by plant scale: trees on larger grids, grass/flowers/stones on smaller.\n- Keep gameplay clearance, landmarks, paths, and sightlines as hard filters.\n- Use persistent CPU instances when HLOD/collision/nav are required; GPU instances only for the\n  supported purely visual runtime case.\n\n## Roadside/fence generator\n\n- Spline input -> distance sampling -> tangent/side/width -> terrain projection -> intersection/\n  endpoint rules -> post/module selection -> spawn.\n- Use Shape Grammar for repeating modules and corner/end pieces when rules stay legible.\n- Route spline deformation/mesh segment details to `$unreal-splines`.\n\n## Building/city blocks\n\n- Polygon 2D city boundary -> cut/subdivide by splines -> offset for setbacks -> create surfaces ->\n  sample parcels -> attribute-driven building archetype -> Spawn Actor/Level Instance.\n- Keep roads and utility corridors as source geometry, not late random exclusions.\n- Validate entrances, navigation, collision, streaming ownership, and HLOD output.\n\n## Biome architecture\n\n- Separate climate/biome classification, broad distribution, species selection, local exclusion,\n  and spawn into subgraphs.\n- Use Data Assets/Tables for species rules and weights.\n- PCG Biome Core is Experimental; mine it for patterns rather than treating it as a production\n  guarantee.\n\n## Authored exceptions\n\n- Use input splines/volumes/tags for repeatable design rules.\n- Use UE 5.8 manual overrides for isolated art-directed exceptions only after accepting the\n  Experimental status and defining merge/regeneration policy.\n- If the same override occurs repeatedly, promote it into graph input or rule data.\n\n## Acceptance test for any generator\n\nThe generator must produce valid constraints across at least ten representative seeds, regenerate\nidentically for a fixed seed/input, survive cleanup/reload/cook, remain editable by intended\ncreators, and meet total runtime/render/streaming budgets on target hardware.\n","webMarkdown":"## Vegetation scatter\n\n- Landscape/surface -> slope/height/surface attributes -> road/water/POI Difference -> density\n  noise -> weighted species selection -> bounded transform -> instanced mesh spawn.\n- Partition/hierarchy by plant scale: trees on larger grids, grass/flowers/stones on smaller.\n- Keep gameplay clearance, landmarks, paths, and sightlines as hard filters.\n- Use persistent CPU instances when HLOD/collision/nav are required; GPU instances only for the\n  supported purely visual runtime case.\n\n## Roadside/fence generator\n\n- Spline input -> distance sampling -> tangent/side/width -> terrain projection -> intersection/\n  endpoint rules -> post/module selection -> spawn.\n- Use Shape Grammar for repeating modules and corner/end pieces when rules stay legible.\n- Route spline deformation/mesh segment details to `$unreal-splines`.\n\n## Building/city blocks\n\n- Polygon 2D city boundary -> cut/subdivide by splines -> offset for setbacks -> create surfaces ->\n  sample parcels -> attribute-driven building archetype -> Spawn Actor/Level Instance.\n- Keep roads and utility corridors as source geometry, not late random exclusions.\n- Validate entrances, navigation, collision, streaming ownership, and HLOD output.\n\n## Biome architecture\n\n- Separate climate/biome classification, broad distribution, species selection, local exclusion,\n  and spawn into subgraphs.\n- Use Data Assets/Tables for species rules and weights.\n- PCG Biome Core is Experimental; mine it for patterns rather than treating it as a production\n  guarantee.\n\n## Authored exceptions\n\n- Use input splines/volumes/tags for repeatable design rules.\n- Use UE 5.8 manual overrides for isolated art-directed exceptions only after accepting the\n  Experimental status and defining merge/regeneration policy.\n- If the same override occurs repeatedly, promote it into graph input or rule data.\n\n## Acceptance test for any generator\n\nThe generator must produce valid constraints across at least ten representative seeds, regenerate\nidentically for a fixed seed/input, survive cleanup/reload/cook, remain editable by intended\ncreators, and meet total runtime/render/streaming budgets on target hardware.\n","searchText":"use cases vegetation scatter - landscape/surface -> slope/height/surface attributes -> road/water/poi difference -> density noise -> weighted species selection -> bounded transform -> instanced mesh spawn. - partition/hierarchy by plant scale: trees on larger grids, grass/flowers/stones on smaller. - keep gameplay clearance, landmarks, paths, and sightlines as hard filters. - use persistent cpu instances when hlod/collision/nav are required; gpu instances only for the supported purely visual runtime case. roadside/fence generator - spline input -> distance sampling -> tangent/side/width -> terrain projection -> intersection/ endpoint rules -> post/module selection -> spawn. - use shape grammar for repeating modules and corner/end pieces when rules stay legible. - route spline deformation/mesh segment details to $unreal-splines. building/city blocks - polygon 2d city boundary -> cut/subdivide by splines -> offset for setbacks -> create surfaces -> sample parcels -> attribute-driven building archetype -> spawn actor/level instance. - keep roads and utility corridors as source geometry, not late random exclusions. - validate entrances, navigation, collision, streaming ownership, and hlod output. biome architecture - separate climate/biome classification, broad distribution, species selection, local exclusion, and spawn into subgraphs. - use data assets/tables for species rules and weights. - pcg biome core is experimental; mine it for patterns rather than treating it as a production guarantee. authored exceptions - use input splines/volumes/tags for repeatable design rules. - use ue 5.8 manual overrides for isolated art-directed exceptions only after accepting the experimental status and defining merge/regeneration policy. - if the same override occurs repeatedly, promote it into graph input or rule data. acceptance test for any generator the generator must produce valid constraints across at least ten representative seeds, regenerate identically for a fixed seed/input, survive cleanup/reload/cook, remain editable by intended creators, and meet total runtime/render/streaming budgets on target hardware."},{"slug":"world-partition-integration","file":"world-partition-integration.md","title":"World Partition integration","rawMarkdown":"# World Partition integration\n\n## Ownership model\n\nTreat the systems as separate layers:\n\n- PCG decides **what** data/content to generate.\n- PCG partition/hierarchy decides **where and at what generation grid** work executes.\n- World Partition decides **which persisted actors/cells stream**.\n- Data Layers decide **which authored/runtime content set is loaded or activated**.\n- HLOD decides **what distant proxy represents unloaded source content**.\n\nDo not assume PCG grid size and World Partition runtime cell size are the same setting or must\nmatch one-to-one.\n\n## Persistent generated content\n\n1. Choose partitioned/hierarchical editor generation for the large domain.\n2. Assign the source PCG actor/component to the intended Data Layer and HLOD Layer.\n3. Configure Spawn Actor/Create Target Actor Data Layer Source Type intentionally. `Self` inherits\n   source-component Data Layers.\n4. Generate and inspect actor/Data Layer/HLOD assignment.\n5. Build HLODs after stable generation.\n6. Cleanup and regenerate after grid changes; stale partition actors are not evidence of the new\n   configuration.\n7. Run the PCG World Partition Builder commandlet from a clean source state for reproducibility.\n\nPCG-generated actors assigned through the source asset inherit matching Data Layer/HLOD ownership\naccording to the documented integration path.\n\n## Runtime generation in a partitioned world\n\n- Define runtime PCG generation sources independently from World Partition streaming sources.\n- Set generation and cleanup radii by PCG grid level.\n- Ensure World Partition cells and required source data load early enough for generation.\n- Prewarm teleport destinations before player arrival; verify both streaming completion and PCG\n  generation completion rather than assuming one implies the other.\n- Keep gameplay-critical collision/nav content persisted or use a runtime path that explicitly\n  supports and finishes it before access.\n\n## Data Layer transitions\n\nIf PCG content follows a Runtime Data Layer:\n\n1. Server/gameplay authority changes the Data Layer state in networked play.\n2. Separate Loaded from Activated behavior.\n3. Test generated content cleanup/reappearance through state changes.\n4. Measure the burst; activating many assets/layers together can degrade streaming performance.\n\nRoute detailed streaming, Data Layer, and HLOD configuration to `$unreal-world-partition`.\n","webMarkdown":"## Ownership model\n\nTreat the systems as separate layers:\n\n- PCG decides **what** data/content to generate.\n- PCG partition/hierarchy decides **where and at what generation grid** work executes.\n- World Partition decides **which persisted actors/cells stream**.\n- Data Layers decide **which authored/runtime content set is loaded or activated**.\n- HLOD decides **what distant proxy represents unloaded source content**.\n\nDo not assume PCG grid size and World Partition runtime cell size are the same setting or must\nmatch one-to-one.\n\n## Persistent generated content\n\n1. Choose partitioned/hierarchical editor generation for the large domain.\n2. Assign the source PCG actor/component to the intended Data Layer and HLOD Layer.\n3. Configure Spawn Actor/Create Target Actor Data Layer Source Type intentionally. `Self` inherits\n   source-component Data Layers.\n4. Generate and inspect actor/Data Layer/HLOD assignment.\n5. Build HLODs after stable generation.\n6. Cleanup and regenerate after grid changes; stale partition actors are not evidence of the new\n   configuration.\n7. Run the PCG World Partition Builder commandlet from a clean source state for reproducibility.\n\nPCG-generated actors assigned through the source asset inherit matching Data Layer/HLOD ownership\naccording to the documented integration path.\n\n## Runtime generation in a partitioned world\n\n- Define runtime PCG generation sources independently from World Partition streaming sources.\n- Set generation and cleanup radii by PCG grid level.\n- Ensure World Partition cells and required source data load early enough for generation.\n- Prewarm teleport destinations before player arrival; verify both streaming completion and PCG\n  generation completion rather than assuming one implies the other.\n- Keep gameplay-critical collision/nav content persisted or use a runtime path that explicitly\n  supports and finishes it before access.\n\n## Data Layer transitions\n\nIf PCG content follows a Runtime Data Layer:\n\n1. Server/gameplay authority changes the Data Layer state in networked play.\n2. Separate Loaded from Activated behavior.\n3. Test generated content cleanup/reappearance through state changes.\n4. Measure the burst; activating many assets/layers together can degrade streaming performance.\n\nRoute detailed streaming, Data Layer, and HLOD configuration to `$unreal-world-partition`.\n","searchText":"world partition integration ownership model treat the systems as separate layers: - pcg decides what data/content to generate. - pcg partition/hierarchy decides where and at what generation grid work executes. - world partition decides which persisted actors/cells stream. - data layers decide which authored/runtime content set is loaded or activated. - hlod decides what distant proxy represents unloaded source content. do not assume pcg grid size and world partition runtime cell size are the same setting or must match one-to-one. persistent generated content 1. choose partitioned/hierarchical editor generation for the large domain. 2. assign the source pcg actor/component to the intended data layer and hlod layer. 3. configure spawn actor/create target actor data layer source type intentionally. self inherits source-component data layers. 4. generate and inspect actor/data layer/hlod assignment. 5. build hlods after stable generation. 6. cleanup and regenerate after grid changes; stale partition actors are not evidence of the new configuration. 7. run the pcg world partition builder commandlet from a clean source state for reproducibility. pcg-generated actors assigned through the source asset inherit matching data layer/hlod ownership according to the documented integration path. runtime generation in a partitioned world - define runtime pcg generation sources independently from world partition streaming sources. - set generation and cleanup radii by pcg grid level. - ensure world partition cells and required source data load early enough for generation. - prewarm teleport destinations before player arrival; verify both streaming completion and pcg generation completion rather than assuming one implies the other. - keep gameplay-critical collision/nav content persisted or use a runtime path that explicitly supports and finishes it before access. data layer transitions if pcg content follows a runtime data layer: 1. server/gameplay authority changes the data layer state in networked play. 2. separate loaded from activated behavior. 3. test generated content cleanup/reappearance through state changes. 4. measure the burst; activating many assets/layers together can degrade streaming performance. route detailed streaming, data layer, and hlod configuration to $unreal-world-partition."}]}
{"slug":"unreal-rendering-performance","name":"unreal-rendering-performance","title":"Unreal 5.8 Rendering Performance","description":"Diagnose, budget, scale, and optimize real-time rendering in Unreal Engine 5.8 after profiling identifies a render-thread or GPU bottleneck. Use for GPU Profiler results, draw calls, primitive and material cost, Nanite, Lumen, Lumen Lite, Virtual Shadow Maps, MegaLights, TSR, screen percentage, Dynamic Resolution, translucency, overdraw, culling, LOD/HLOD, GPU memory, Render Resource Viewer, Primitive Debugger, scalability groups, device profiles, or platform rendering tiers.","shortDescription":"Diagnose and optimize Unreal rendering cost","category":"Rendering & VFX","referenceCount":13,"rawMarkdown":"---\nname: unreal-rendering-performance\ndescription: Diagnose, budget, scale, and optimize real-time rendering in Unreal Engine 5.8 after profiling identifies a render-thread or GPU bottleneck. Use for GPU Profiler results, draw calls, primitive and material cost, Nanite, Lumen, Lumen Lite, Virtual Shadow Maps, MegaLights, TSR, screen percentage, Dynamic Resolution, translucency, overdraw, culling, LOD/HLOD, GPU memory, Render Resource Viewer, Primitive Debugger, scalability groups, device profiles, or platform rendering tiers.\n---\n\n# Unreal 5.8 Rendering Performance\n\n## Start from measured evidence\n\nUse `unreal-insights-profiling` first when no trustworthy bound/pass/capture exists. Read\n[`references/diagnostic-selector.md`](references/diagnostic-selector.md) and\n[`references/budgets-and-baselines.md`](references/budgets-and-baselines.md).\n\n1. Lock target hardware, renderer, resolution, quality tier, scene/camera, and frame budget.\n2. Identify whether the cost is Render/RHI-thread submission, GPU pass time, GPU memory, or a hitch.\n3. Name the largest measured pass/resource/submission category and its millisecond or byte cost.\n4. Use the subsystem visualization/stats to locate causal content or settings.\n5. Choose the least destructive lever that changes the measured cost: visibility, workload count,\n   quality, resolution, representation, update frequency, or feature path.\n6. Change one lever, capture the identical workload, and compare cost plus visual/gameplay impact.\n7. Encode approved changes in scalability/device profiles and test every supported tier.\n\nLoad only what applies:\n\n- [`references/resolution-tsr-and-dynamic-resolution.md`](references/resolution-tsr-and-dynamic-resolution.md)\n- [`references/nanite-geometry.md`](references/nanite-geometry.md)\n- [`references/lumen-and-reflections.md`](references/lumen-and-reflections.md)\n- [`references/virtual-shadow-maps.md`](references/virtual-shadow-maps.md)\n- [`references/megalights.md`](references/megalights.md)\n- [`references/materials-translucency-and-overdraw.md`](references/materials-translucency-and-overdraw.md)\n- [`references/submission-culling-and-lods.md`](references/submission-culling-and-lods.md)\n- [`references/scalability-and-device-profiles.md`](references/scalability-and-device-profiles.md)\n- [`references/gpu-memory-and-resources.md`](references/gpu-memory-and-resources.md)\n- [`references/symptom-recipes.md`](references/symptom-recipes.md)\n\n## Required answer format\n\nReturn:\n\n1. **Target, renderer, budget, capture, and measured bound**.\n2. **Dominant pass/submission/resource** with current cost.\n3. **Diagnostic visualization or command** and expected evidence.\n4. **Ranked changes**, each with mechanism, quality risk, platform scope, and predicted delta.\n5. **Exact property/CVar/scalability/device-profile action** for the chosen experiment.\n6. **A/B verification** at the same camera and settings.\n7. **Tier and fallback behavior**, including unsupported/experimental paths.\n\n## Hard rules\n\n- Do not prescribe renderer CVars from symptoms alone; require a measured pass or bounded experiment.\n- Do not compare GPU captures at different resolution, screen percentage, camera, or warm/cold state.\n- Optimize milliseconds, not triangle/draw-call/instruction counts in isolation.\n- Treat editor view modes and visualization overlays as diagnostic overhead; disable them for final timing.\n- Preserve gameplay readability and fairness across tiers; scalability must not hide actionable content.\n- Prefer scalability groups and device profiles over scattered runtime CVars.\n- Treat Lumen Lite as Beta in UE 5.8 and Primitive Debugger/Nanite Foliage as Experimental.\n- MegaLights is Production Ready in UE 5.8, but its quality still degrades as per-pixel light complexity\n  exceeds its fixed sampling budget.\n- Nanite does not make materials, masked overdraw, WPO, shadows, streaming, or storage free.\n- Dynamic resolution mitigates GPU spikes; it does not repair a CPU/render-thread bottleneck.\n- Preserve a supported fallback for target platforms that lack Nanite/Lumen/TSR/hardware ray tracing.\n\nSee [`references/sources.md`](references/sources.md) for the UE 5.8 primary-source trail.\n","webMarkdown":"## Start from measured evidence\n\nUse `unreal-insights-profiling` first when no trustworthy bound/pass/capture exists. Read\n[`references/diagnostic-selector.md`](/unreal/unreal-rendering-performance/diagnostic-selector/) and\n[`references/budgets-and-baselines.md`](/unreal/unreal-rendering-performance/budgets-and-baselines/).\n\n1. Lock target hardware, renderer, resolution, quality tier, scene/camera, and frame budget.\n2. Identify whether the cost is Render/RHI-thread submission, GPU pass time, GPU memory, or a hitch.\n3. Name the largest measured pass/resource/submission category and its millisecond or byte cost.\n4. Use the subsystem visualization/stats to locate causal content or settings.\n5. Choose the least destructive lever that changes the measured cost: visibility, workload count,\n   quality, resolution, representation, update frequency, or feature path.\n6. Change one lever, capture the identical workload, and compare cost plus visual/gameplay impact.\n7. Encode approved changes in scalability/device profiles and test every supported tier.\n\nLoad only what applies:\n\n- [`references/resolution-tsr-and-dynamic-resolution.md`](/unreal/unreal-rendering-performance/resolution-tsr-and-dynamic-resolution/)\n- [`references/nanite-geometry.md`](/unreal/unreal-rendering-performance/nanite-geometry/)\n- [`references/lumen-and-reflections.md`](/unreal/unreal-rendering-performance/lumen-and-reflections/)\n- [`references/virtual-shadow-maps.md`](/unreal/unreal-rendering-performance/virtual-shadow-maps/)\n- [`references/megalights.md`](/unreal/unreal-rendering-performance/megalights/)\n- [`references/materials-translucency-and-overdraw.md`](/unreal/unreal-rendering-performance/materials-translucency-and-overdraw/)\n- [`references/submission-culling-and-lods.md`](/unreal/unreal-rendering-performance/submission-culling-and-lods/)\n- [`references/scalability-and-device-profiles.md`](/unreal/unreal-rendering-performance/scalability-and-device-profiles/)\n- [`references/gpu-memory-and-resources.md`](/unreal/unreal-rendering-performance/gpu-memory-and-resources/)\n- [`references/symptom-recipes.md`](/unreal/unreal-rendering-performance/symptom-recipes/)\n\n## Required answer format\n\nReturn:\n\n1. **Target, renderer, budget, capture, and measured bound**.\n2. **Dominant pass/submission/resource** with current cost.\n3. **Diagnostic visualization or command** and expected evidence.\n4. **Ranked changes**, each with mechanism, quality risk, platform scope, and predicted delta.\n5. **Exact property/CVar/scalability/device-profile action** for the chosen experiment.\n6. **A/B verification** at the same camera and settings.\n7. **Tier and fallback behavior**, including unsupported/experimental paths.\n\n## Hard rules\n\n- Do not prescribe renderer CVars from symptoms alone; require a measured pass or bounded experiment.\n- Do not compare GPU captures at different resolution, screen percentage, camera, or warm/cold state.\n- Optimize milliseconds, not triangle/draw-call/instruction counts in isolation.\n- Treat editor view modes and visualization overlays as diagnostic overhead; disable them for final timing.\n- Preserve gameplay readability and fairness across tiers; scalability must not hide actionable content.\n- Prefer scalability groups and device profiles over scattered runtime CVars.\n- Treat Lumen Lite as Beta in UE 5.8 and Primitive Debugger/Nanite Foliage as Experimental.\n- MegaLights is Production Ready in UE 5.8, but its quality still degrades as per-pixel light complexity\n  exceeds its fixed sampling budget.\n- Nanite does not make materials, masked overdraw, WPO, shadows, streaming, or storage free.\n- Dynamic resolution mitigates GPU spikes; it does not repair a CPU/render-thread bottleneck.\n- Preserve a supported fallback for target platforms that lack Nanite/Lumen/TSR/hardware ray tracing.\n\nSee [`references/sources.md`](/unreal/unreal-rendering-performance/sources/) for the UE 5.8 primary-source trail.\n","searchText":"unreal 5.8 rendering performance diagnose, budget, scale, and optimize real-time rendering in unreal engine 5.8 after profiling identifies a render-thread or gpu bottleneck. use for gpu profiler results, draw calls, primitive and material cost, nanite, lumen, lumen lite, virtual shadow maps, megalights, tsr, screen percentage, dynamic resolution, translucency, overdraw, culling, lod/hlod, gpu memory, render resource viewer, primitive debugger, scalability groups, device profiles, or platform rendering tiers. budgets and baselines budgets and baselines specify: - target fps and full frame budget; - rendering-thread and gpu sub-budget with safety margin; - output resolution and primary/secondary screen percentage; - renderer path, rhi, shader model, ray-tracing state, upscaler; - device profile and every sg. quality group; - scene, camera, time/weather, dynamic objects/lights/effects; - memory/thermal/power constraints. use milliseconds: | target | whole-frame deadline | |---|---:| | 30 fps | 33.33 ms | | 60 fps | 16.67 ms | | 90 fps | 11.11 ms | | 120 fps | 8.33 ms | keep margin for unsampled combat, traversal, streaming, platform services, and thermal variance. test representative worst cases, not an empty editor viewport. resolution sensitivity test 1. capture at production resolution/screen percentage. 2. lower primary screen percentage while preserving camera/content/quality. 3. compare total gpu and each pass. 4. classify passes that fall with pixel count versus fixed/geometry/submission costs. a resolution response localizes pixel-scaled work; it does not identify the specific effect. a weak response does not by itself prove cpu-bound because some gpu passes are weakly resolution-dependent. diagnostic selector diagnostic selector | measured problem | first inspection | route | |---|---|---| | gpu cost scales strongly with resolution | profilegpu, pass event tree | tsr/resolution, pixel-heavy pass | | draw/render thread dominates | primitive debugger, stat scenerendering, primitive/section counts | submission/culling/lod | | basepass high | shader complexity, material/primitive isolation | materials/overdraw | | translucency/post high | shader complexity, screen coverage, effect toggles | translucency/resolution | | nanite pass/streaming issue | nanite visualization, nanitestats | nanite geometry | | lumen gi/reflection high | lumen overview/visualizations, quality a/b | lumen | | shadow depths/projection high | vsm cache/caster views, light isolation | vsm or megalights | | many local lights/noisy direct light | megalights light/ray/caster visualizers | megalights | | tsr cost or ghosting | temporal upscaler visualization, gpu event | tsr | | gpu memory over budget | render resource viewer, rhi/platform memory stats | resources/streaming | | camera-cut spike | gpu/timing trace, vsm/visibility/streaming evidence | subsystem causing burst | disable diagnostic views before the timed a/b capture. their value is attribution, not the final number. gpu memory and render resources gpu memory and render resources open tools -> render resource viewer. it is a snapshot taken when opened; press refresh for a new snapshot. sort/filter by size, type, owner, resident, streaming, transient, and other flags. audit 1. record platform gpu-memory budget and current resident/allocated metrics. 2. capture the representative map/camera after expected streaming settles. 3. sort the largest resources and map each to an owning asset/lod. 4. separate persistent/resident allocations from transient aliased render-graph resources. 5. compare before/after at the same location and streaming state. common actions: - reduce texture resolution/format or correct texture groups/mips; - correct non-streaming or always-resident resources that do not require it; - reduce oversized render targets, history buffers, shadow pools, or feature buffers only after identifying their owner and quality effect; - review nanite streaming pool versus cache-thrashing tradeoff; - remove duplicate/unused assets and unexpectedly loaded references; - set per-platform lod/texture/device-profile limits. gpu resource allocation is not the same as process ram, package size, or streaming pool occupancy. track each budget with the appropriate tool and avoid summing overlapping categories. lumen gi and reflections lumen gi and reflections select quality by target - high-quality lumen is the modern dynamic gi/reflection path for capable targets. - ue 5.8 lumen lite is beta. medium gi quality (sg.globalilluminationquality 1) selects its irradiance field final gather (r.lumen.finalgathermethod 0) for faster, lower-quality gi. - medium reflection quality (sg.reflectionquality 1) disables lumen reflections, uses ssr on smooth surfaces, and retains rough specular from lumen gi. - below lumen, use the project/platform's supported baked or simpler gi/reflection fallback. start from epic's basescalability.ini and platform device profiles; they coordinate many interdependent settings to preserve a reasonably consistent look. isolate cost 1. confirm lumen passes are material in profilegpu/gpu trace. 2. capture lumen visualization/overview modes to find scene representation, update, reflection, or screen-trace problems. 3. a/b gi and reflection scalability independently. 4. test worst-case dynamic lights, camera motion, emissive content, interiors/exteriors, and distance. 5. validate temporal stability and lighting continuity on every tier. lumen uses async compute on supported consoles and can overlap other work. per-pass timings can include overlap. disable lumen async compute only for isolated profiling, then restore it and judge total frame time; overlap is part of the shipping performance strategy. materials, translucency, and overdraw materials, translucency, and overdraw diagnose 1. confirm basepass, translucency, post, or a material-bound draw is significant in gpu timing. 2. use shader complexity (alt+8 / viewmode shadercomplexity) to locate expensive pixel regions. 3. inspect quad overdraw/other supported view modes when tiny triangles or repeated coverage is suspected. 4. isolate the material/primitive/effect and re-capture the same frame. shader complexity primarily visualizes instruction count. it does not reliably price texture fetches, bandwidth, divergent loops, vertex/wpo work, or platform-specific scheduling. use it to locate suspects, then prove cost with gpu milliseconds. levers - reduce full-screen or large-screen material coverage before micro-optimizing a tiny object. - reduce overlapping translucent/masked layers, particle size, spawn density, and unnecessary sorting. - replace translucent effects with opaque/masked/dithered/mesh alternatives only when the visual result and temporal stability remain acceptable. - remove unused texture samples/features; move invariant work out of per-pixel paths where supported. - bound wpo and stop distant/imperceptible deformation. - reduce unique static-switch combinations/permutations; do not convert runtime decisions to static switches without considering compile/package/pso cost. - reduce material slots/sections when submission evidence supports it; preserve authoring flexibility where the measured cost is elsewhere. optimize the exact platform permutation and worst visible overlap. editor shader stats alone are not a shipping gpu measurement. megalights megalights megalights is production ready in ue 5.8. it replaces several deferred direct-lighting/shadow paths for local lights and supports many dynamic shadowed area lights. hardware ray tracing is recommended; each light can use ray-traced or vsm shadowing. directional light support is opt-in with r.megalights.directionallights 1 and disabled by default. epic recommends deferred lighting with vsm for a strong sun because the megalights path has quality limitations; a dim, soft moonlight can be a better fit. sky light remains outside megalights. understand the budget megalights traces a fixed sample budget per pixel toward important lights. runtime cost is more stable than per-light traditional paths, but quality/noise worsens when too many important lights compete at one pixel. more lights are not free artistically even when the timing remains bounded. diagnose 1. use megalights light finder, ray visualizer, and shadow-caster/mismatch views. 2. compare complete gpu frame time, not only one megalights event; it replaces multiple passes. 3. inspect off-screen and tiny bright lights, huge attenuation radii, overlapping volumes, and shadow methods. 4. test motion/noise at target internal resolution and tsr quality. scale | control | effect | |---|---| | r.megalights.allow 0 | disable per tier/device profile for a fallback path | | r.megalights.downsamplemode | adjust sampling/tracing resolution; stronger downsampling saves work but can reduce quality | | r.megalights.numsamplesperpixel | more samples improve stability/quality and increase gpu cost | | allow megalights per light | remove incompatible/problem lights from the path | | shadow method per light | choose ray tracing or vsm with different quality/cpu/memory/gpu tradeoffs | start from the shadow quality scalability group in basescalability.ini. high-quality translucency, volumetric fog, hair, textured area lights, and soft shadows have their own cost; scale only after the visualizer identifies them. nanite geometry nanite geometry use nanite for supported high-detail static/skeletal content when its virtualized path matches the target. preserve conventional lod/fallback behavior for unsupported platforms and features. diagnose - open view modes -> nanite visualization for triangles/clusters/overdraw/streaming/fallback evidence. - run nanitestats; use nanitestats list and a named view such as nanitestats virtualshadowmaps when applicable. - toggle r.nanite 0 only as a diagnostic/fallback-platform experiment; a scene authored around nanite may explode into conventional draw calls or unusable fallback cost. cost levers | evidence | action | |---|---| | streaming pool thrashes in a static view | increase r.nanite.streaming.streamingpoolsize if memory permits, or reduce resident demand | | gpu memory/storage excess | reduce source detail where imperceptible; review fallback and texture payloads | | masked/stacked surface overdraw | simplify aggregate geometry/material coverage; inspect nanite overdraw | | deformation/wpo cost | bound affected content and distance; remove deformation when imperceptible | | blinking/missing clusters at extreme complexity | inspect clusterssw/clustershw; size candidate/visible limits conservatively in config | | foliage loses area | evaluate preserve area and foliage-specific representation/lod | larger streaming pools reduce io/decompression churn but consume more memory. max edge length factor should remain 0 unless solving observed over-simplification on deforming/spline content; increasing it preserves detail at additional cost. do not use triangle count alone as a performance target. measure nanite passes, material/shadow cost, streaming, storage, and fallback behavior. resolution, tsr, and dynamic resolution resolution, tsr, and dynamic resolution tsr tsr renders at a lower internal resolution and reconstructs the display image. its work includes input-resolution and display-resolution costs, so lowering screen percentage may not reduce the tsr pass itself in direct proportion even when it reduces the rest of the frame. actions: 1. capture gpu cost at the production output resolution. 2. compare controlled primary screen percentages with identical content. 3. set anti-aliasing scalability through sg.antialiasingquality (0 low through 4 cinematic). 4. inspect show -> visualize -> temporal upscaler for velocity, rejection, translucency, exposure, input/output, and active quality information. 5. inspect the scene > postprocessing > temporalsuperresolution event in gpu tools. 6. fix velocity/translucency/material history defects before raising global quality to conceal them. avoid routine input screen percentages below 50%; epic reserves extreme upscaling for exceptional cases such as output beyond 4k or brief dynamic-resolution pressure. dynamic resolution enable through game user settings/c++ for supported targets, then configure: | cvar | effect | |---|---| | r.dynamicres.minscreenpercentage | lower bound; decreasing permits more quality loss to recover gpu time | | r.dynamicres.maxscreenpercentage | allocation/quality ceiling | | r.dynamicres.frametimebudget | gpu-frame target in milliseconds | | r.dynamicres.historysize | larger smooths decisions but reacts more slowly; smaller reacts faster but is noisier | use stat unitgraph, then stat raw, to inspect raw gpu time and selected primary screen percentage. dynamic resolution reacts to prior gpu workload and may panic downward after consecutive over-budget frames. it cannot predict every camera cut/effect burst and cannot recover a cpu-bound frame by doing less gpu pixel work. scalability and device profiles scalability and device profiles ownership - use scalability groups for player-facing quality families. - use device profiles for platform/device defaults, feature support, memory buckets, and overrides. - store project overrides in project config, not edited engine base files. - treat engine/config/basescalability.ini and platform base device profiles as current reference implementations, then override only measured needs. core groups include resolution, view distance, anti-aliasing, shadows, global illumination, reflections, post processing, textures, effects, foliage, and shading. validate the exact ue 5.8 group contents; one sg. value can change many cvars. tier workflow 1. define minimum/recommended target hardware and renderer feature support. 2. establish low/medium/high/epic intent with a stable gameplay-readability floor. 3. begin with engine group defaults; measure every target device. 4. override subsystem controls only when the group misses the budget or quality target. 5. expose settings whose visual/performance trade is meaningful to players. 6. restart/reload when a feature path or shader permutation requires it; label settings accordingly. 7. test saved settings, auto-detection/defaults, upgrades, and unsupported hardware fallback. never let a low tier remove enemies, hazards, navigation cues, competitive visibility, or essential feedback. scale visual richness and representation, not game rules. ue 5.8 primary sources ue 5.8 primary sources - ue 5.8 release notes - optimizing and debugging real-time rendering - scalability reference - setting device profiles - temporal super resolution - temporal upscalers - dynamic resolution - nanite virtualized geometry - working with nanite-enabled content - nanite technical details - lumen performance guide - virtual shadow maps - megalights - viewport modes - visibility and occlusion culling - primitive debugger - render resource viewer pages were checked against ue 5.8 documentation on 2026-07-19. reconfirm feature maturity, renderer/platform support, scalability-group contents, visualization names, and cvars after an engine upgrade. submission, culling, and lods submission, culling, and lods render-thread cost often follows visible primitive/component/section/light counts and state diversity, not raw triangle count alone. inspect - stat unit, stat scenerendering, stat rhi, and timing insights render/rhi tracks. - runtime primitive debugger (primitivedebugger.open) in development/test builds for primitive, draw-call, and lod data. it is experimental in ue 5.8; use it diagnostically, not as shipping logic. - freeze rendering/occlusion and r.visualizeoccludedprimitives 1 to inspect culling behavior. reduce submissions and visibility work - instance repeated meshes when transforms/material requirements permit. - merge actors/sections only when it does not destroy culling granularity, streaming, interaction, or authoring needs. - use hlod for distant groups and conventional skeletal/static lods where nanite is not the path. - set max draw distance or cull distance volumes for content that becomes irrelevant. - keep bounds accurate; oversized bounds harm culling, shadows, and streaming decisions. - avoid thousands of independently ticking/updating render components when a batched representation fits. - remove material slots/sections only when section submission is measured. unreal applies distance, frustum, precomputed visibility, then dynamic occlusion according to method and platform. hardware occlusion queries are enabled by default on supported paths. precomputed visibility trades build/runtime memory for reduced runtime rendering work and best fits constrained, mostly static, small-to-medium environments. test occlusion changes during camera motion. more aggressive culling can add popping or query cost and can be worse than rendering small cheap objects. symptom recipes symptom recipes | symptom | prove first | first bounded experiment | |---|---|---| | slow only at high resolution | pixel-scaled gpu passes | lower screen percentage; compare pass deltas | | slow in dense city/forest | render thread, nanite/material/vsm/visibility | isolate primitive/section, overdraw, caster invalidation | | shadow spike while foliage moves | vsm uncached pages/casters | disable distant wpo/shadows on one foliage class | | camera cuts hitch | visibility/vsm/streaming/upscaler history | marked trace plus cache/streaming views | | many lights stay fast but noisy | megalights sample competition | reduce competing radii/lights or raise samples in controlled a/b | | reflections dominate | lumen reflection pass | compare reflection scalability separately from gi | | translucent combat effect tanks gpu | translucency/overdraw event | cut overlap/coverage for one effect | | render thread slow, gpu has headroom | primitive/section/submission count | instance/cull one high-count category | | gpu memory grows by location | resource snapshot and streaming residency | identify largest new owners and correct residency/lod | | low tier changes nothing | device profile/group not applied or restart needed | display active cvars/profile and verify packaged build | | dynamic resolution bottoms out | sustained gpu cost exceeds minimum-resolution budget or cpu bound | inspect gpu at minimum percentage; optimize dominant pass | for every recipe, restore the toggle, implement the production-quality change through owned settings, and capture the same worst case again. virtual shadow maps virtual shadow maps vsms are designed to pair with nanite and large dynamically lit worlds. if the target does not use nanite, validate whether conventional shadow maps are a better fit. diagnose the two cost buckets - shadow depths: rendering/updating caster depth pages. - shadow projection under lights: sampling/projecting shadows into the frame. use view modes -> virtual shadow map: - cached page: green cached, red uncached, blue static-only cached; - shadow casters: locate invalidators; - nanite overdraw: locate costly caster coverage; - virtual page/clipmap-mip: inspect page demand/resolution. disable visualization before timing. for counters, use trace.enable counters,vsm; csv profiling can enable the vsm category. reduce invalidation largest invalidators commonly include moving lights, moving/added/removed casters, component render- state churn, wpo/pdo, skeletal deformation, large bounds, camera cuts, and rapid disocclusion. actions: - stop needless light/primitive updates; - keep deforming bounds tight; - remove wpo/pdo or shadow casting at distance when visually safe; - use material/mesh lods that disable deformation in the distance; - use contact or distance field shadows where the content/target supports the trade; - use shadow cache invalidation behavior overrides only when the asserted rigidity/static state is true; incorrect suppression produces undefined/stale shadows. r.shadow.virtual.cache 0 is a diagnostic to expose caching benefit, not a shipping optimization. resolution lod bias trades shadow detail for pages/work. moving-light biases exist because moving lights cannot reuse cache like stationary ones. when profiling individual vsm passes, r.rdg.asynccompute 0 can make timings more representative; never ship that profiling-only override.","references":[{"slug":"budgets-and-baselines","file":"budgets-and-baselines.md","title":"Budgets and baselines","rawMarkdown":"# Budgets and baselines\n\nSpecify:\n\n- target FPS and full frame budget;\n- rendering-thread and GPU sub-budget with safety margin;\n- output resolution and primary/secondary screen percentage;\n- renderer path, RHI, shader model, ray-tracing state, upscaler;\n- device profile and every `sg.*` quality group;\n- scene, camera, time/weather, dynamic objects/lights/effects;\n- memory/thermal/power constraints.\n\nUse milliseconds:\n\n| Target | Whole-frame deadline |\n|---|---:|\n| 30 fps | 33.33 ms |\n| 60 fps | 16.67 ms |\n| 90 fps | 11.11 ms |\n| 120 fps | 8.33 ms |\n\nKeep margin for unsampled combat, traversal, streaming, platform services, and thermal variance. Test\nrepresentative worst cases, not an empty editor viewport.\n\n## Resolution sensitivity test\n\n1. Capture at production resolution/screen percentage.\n2. Lower primary screen percentage while preserving camera/content/quality.\n3. Compare total GPU and each pass.\n4. Classify passes that fall with pixel count versus fixed/geometry/submission costs.\n\nA resolution response localizes pixel-scaled work; it does not identify the specific effect. A weak\nresponse does not by itself prove CPU-bound because some GPU passes are weakly resolution-dependent.\n","webMarkdown":"Specify:\n\n- target FPS and full frame budget;\n- rendering-thread and GPU sub-budget with safety margin;\n- output resolution and primary/secondary screen percentage;\n- renderer path, RHI, shader model, ray-tracing state, upscaler;\n- device profile and every `sg.*` quality group;\n- scene, camera, time/weather, dynamic objects/lights/effects;\n- memory/thermal/power constraints.\n\nUse milliseconds:\n\n| Target | Whole-frame deadline |\n|---|---:|\n| 30 fps | 33.33 ms |\n| 60 fps | 16.67 ms |\n| 90 fps | 11.11 ms |\n| 120 fps | 8.33 ms |\n\nKeep margin for unsampled combat, traversal, streaming, platform services, and thermal variance. Test\nrepresentative worst cases, not an empty editor viewport.\n\n## Resolution sensitivity test\n\n1. Capture at production resolution/screen percentage.\n2. Lower primary screen percentage while preserving camera/content/quality.\n3. Compare total GPU and each pass.\n4. Classify passes that fall with pixel count versus fixed/geometry/submission costs.\n\nA resolution response localizes pixel-scaled work; it does not identify the specific effect. A weak\nresponse does not by itself prove CPU-bound because some GPU passes are weakly resolution-dependent.\n","searchText":"budgets and baselines specify: - target fps and full frame budget; - rendering-thread and gpu sub-budget with safety margin; - output resolution and primary/secondary screen percentage; - renderer path, rhi, shader model, ray-tracing state, upscaler; - device profile and every sg. quality group; - scene, camera, time/weather, dynamic objects/lights/effects; - memory/thermal/power constraints. use milliseconds: | target | whole-frame deadline | |---|---:| | 30 fps | 33.33 ms | | 60 fps | 16.67 ms | | 90 fps | 11.11 ms | | 120 fps | 8.33 ms | keep margin for unsampled combat, traversal, streaming, platform services, and thermal variance. test representative worst cases, not an empty editor viewport. resolution sensitivity test 1. capture at production resolution/screen percentage. 2. lower primary screen percentage while preserving camera/content/quality. 3. compare total gpu and each pass. 4. classify passes that fall with pixel count versus fixed/geometry/submission costs. a resolution response localizes pixel-scaled work; it does not identify the specific effect. a weak response does not by itself prove cpu-bound because some gpu passes are weakly resolution-dependent."},{"slug":"diagnostic-selector","file":"diagnostic-selector.md","title":"Diagnostic selector","rawMarkdown":"# Diagnostic selector\n\n| Measured problem | First inspection | Route |\n|---|---|---|\n| GPU cost scales strongly with resolution | `profilegpu`, pass event tree | TSR/resolution, pixel-heavy pass |\n| Draw/Render thread dominates | Primitive Debugger, `stat sceneRendering`, primitive/section counts | submission/culling/LOD |\n| BasePass high | Shader Complexity, material/primitive isolation | materials/overdraw |\n| Translucency/post high | Shader Complexity, screen coverage, effect toggles | translucency/resolution |\n| Nanite pass/streaming issue | Nanite visualization, `NaniteStats` | Nanite geometry |\n| Lumen GI/reflection high | Lumen overview/visualizations, quality A/B | Lumen |\n| Shadow Depths/Projection high | VSM cache/caster views, light isolation | VSM or MegaLights |\n| many local lights/noisy direct light | MegaLights light/ray/caster visualizers | MegaLights |\n| TSR cost or ghosting | Temporal Upscaler visualization, GPU event | TSR |\n| GPU memory over budget | Render Resource Viewer, RHI/platform memory stats | resources/streaming |\n| camera-cut spike | GPU/Timing trace, VSM/visibility/streaming evidence | subsystem causing burst |\n\nDisable diagnostic views before the timed A/B capture. Their value is attribution, not the final\nnumber.\n","webMarkdown":"| Measured problem | First inspection | Route |\n|---|---|---|\n| GPU cost scales strongly with resolution | `profilegpu`, pass event tree | TSR/resolution, pixel-heavy pass |\n| Draw/Render thread dominates | Primitive Debugger, `stat sceneRendering`, primitive/section counts | submission/culling/LOD |\n| BasePass high | Shader Complexity, material/primitive isolation | materials/overdraw |\n| Translucency/post high | Shader Complexity, screen coverage, effect toggles | translucency/resolution |\n| Nanite pass/streaming issue | Nanite visualization, `NaniteStats` | Nanite geometry |\n| Lumen GI/reflection high | Lumen overview/visualizations, quality A/B | Lumen |\n| Shadow Depths/Projection high | VSM cache/caster views, light isolation | VSM or MegaLights |\n| many local lights/noisy direct light | MegaLights light/ray/caster visualizers | MegaLights |\n| TSR cost or ghosting | Temporal Upscaler visualization, GPU event | TSR |\n| GPU memory over budget | Render Resource Viewer, RHI/platform memory stats | resources/streaming |\n| camera-cut spike | GPU/Timing trace, VSM/visibility/streaming evidence | subsystem causing burst |\n\nDisable diagnostic views before the timed A/B capture. Their value is attribution, not the final\nnumber.\n","searchText":"diagnostic selector | measured problem | first inspection | route | |---|---|---| | gpu cost scales strongly with resolution | profilegpu, pass event tree | tsr/resolution, pixel-heavy pass | | draw/render thread dominates | primitive debugger, stat scenerendering, primitive/section counts | submission/culling/lod | | basepass high | shader complexity, material/primitive isolation | materials/overdraw | | translucency/post high | shader complexity, screen coverage, effect toggles | translucency/resolution | | nanite pass/streaming issue | nanite visualization, nanitestats | nanite geometry | | lumen gi/reflection high | lumen overview/visualizations, quality a/b | lumen | | shadow depths/projection high | vsm cache/caster views, light isolation | vsm or megalights | | many local lights/noisy direct light | megalights light/ray/caster visualizers | megalights | | tsr cost or ghosting | temporal upscaler visualization, gpu event | tsr | | gpu memory over budget | render resource viewer, rhi/platform memory stats | resources/streaming | | camera-cut spike | gpu/timing trace, vsm/visibility/streaming evidence | subsystem causing burst | disable diagnostic views before the timed a/b capture. their value is attribution, not the final number."},{"slug":"gpu-memory-and-resources","file":"gpu-memory-and-resources.md","title":"GPU memory and render resources","rawMarkdown":"# GPU memory and render resources\n\nOpen Tools -> Render Resource Viewer. It is a snapshot taken when opened; press Refresh for a new\nsnapshot. Sort/filter by size, type, owner, resident, streaming, transient, and other flags.\n\n## Audit\n\n1. Record platform GPU-memory budget and current resident/allocated metrics.\n2. Capture the representative map/camera after expected streaming settles.\n3. Sort the largest resources and map each to an owning asset/LOD.\n4. Separate persistent/resident allocations from transient aliased render-graph resources.\n5. Compare before/after at the same location and streaming state.\n\nCommon actions:\n\n- reduce texture resolution/format or correct texture groups/mips;\n- correct non-streaming or always-resident resources that do not require it;\n- reduce oversized render targets, history buffers, shadow pools, or feature buffers only after\n  identifying their owner and quality effect;\n- review Nanite streaming pool versus cache-thrashing tradeoff;\n- remove duplicate/unused assets and unexpectedly loaded references;\n- set per-platform LOD/texture/device-profile limits.\n\nGPU resource allocation is not the same as process RAM, package size, or streaming pool occupancy.\nTrack each budget with the appropriate tool and avoid summing overlapping categories.\n","webMarkdown":"Open Tools -> Render Resource Viewer. It is a snapshot taken when opened; press Refresh for a new\nsnapshot. Sort/filter by size, type, owner, resident, streaming, transient, and other flags.\n\n## Audit\n\n1. Record platform GPU-memory budget and current resident/allocated metrics.\n2. Capture the representative map/camera after expected streaming settles.\n3. Sort the largest resources and map each to an owning asset/LOD.\n4. Separate persistent/resident allocations from transient aliased render-graph resources.\n5. Compare before/after at the same location and streaming state.\n\nCommon actions:\n\n- reduce texture resolution/format or correct texture groups/mips;\n- correct non-streaming or always-resident resources that do not require it;\n- reduce oversized render targets, history buffers, shadow pools, or feature buffers only after\n  identifying their owner and quality effect;\n- review Nanite streaming pool versus cache-thrashing tradeoff;\n- remove duplicate/unused assets and unexpectedly loaded references;\n- set per-platform LOD/texture/device-profile limits.\n\nGPU resource allocation is not the same as process RAM, package size, or streaming pool occupancy.\nTrack each budget with the appropriate tool and avoid summing overlapping categories.\n","searchText":"gpu memory and render resources open tools -> render resource viewer. it is a snapshot taken when opened; press refresh for a new snapshot. sort/filter by size, type, owner, resident, streaming, transient, and other flags. audit 1. record platform gpu-memory budget and current resident/allocated metrics. 2. capture the representative map/camera after expected streaming settles. 3. sort the largest resources and map each to an owning asset/lod. 4. separate persistent/resident allocations from transient aliased render-graph resources. 5. compare before/after at the same location and streaming state. common actions: - reduce texture resolution/format or correct texture groups/mips; - correct non-streaming or always-resident resources that do not require it; - reduce oversized render targets, history buffers, shadow pools, or feature buffers only after identifying their owner and quality effect; - review nanite streaming pool versus cache-thrashing tradeoff; - remove duplicate/unused assets and unexpectedly loaded references; - set per-platform lod/texture/device-profile limits. gpu resource allocation is not the same as process ram, package size, or streaming pool occupancy. track each budget with the appropriate tool and avoid summing overlapping categories."},{"slug":"lumen-and-reflections","file":"lumen-and-reflections.md","title":"Lumen GI and reflections","rawMarkdown":"# Lumen GI and reflections\n\n## Select quality by target\n\n- High-quality Lumen is the modern dynamic GI/reflection path for capable targets.\n- UE 5.8 Lumen Lite is **Beta**. Medium GI quality (`sg.GlobalIlluminationQuality 1`) selects its\n  Irradiance Field Final Gather (`r.Lumen.FinalGatherMethod 0`) for faster, lower-quality GI.\n- Medium reflection quality (`sg.ReflectionQuality 1`) disables Lumen Reflections, uses SSR on smooth\n  surfaces, and retains rough specular from Lumen GI.\n- Below Lumen, use the project/platform's supported baked or simpler GI/reflection fallback.\n\nStart from Epic's `BaseScalability.ini` and platform device profiles; they coordinate many interdependent\nsettings to preserve a reasonably consistent look.\n\n## Isolate cost\n\n1. Confirm Lumen passes are material in `profilegpu`/GPU trace.\n2. Capture Lumen visualization/overview modes to find scene representation, update, reflection, or\n   screen-trace problems.\n3. A/B GI and reflection scalability independently.\n4. Test worst-case dynamic lights, camera motion, emissive content, interiors/exteriors, and distance.\n5. Validate temporal stability and lighting continuity on every tier.\n\nLumen uses async compute on supported consoles and can overlap other work. Per-pass timings can include\noverlap. Disable Lumen async compute only for isolated profiling, then restore it and judge total frame\ntime; overlap is part of the shipping performance strategy.\n","webMarkdown":"## Select quality by target\n\n- High-quality Lumen is the modern dynamic GI/reflection path for capable targets.\n- UE 5.8 Lumen Lite is **Beta**. Medium GI quality (`sg.GlobalIlluminationQuality 1`) selects its\n  Irradiance Field Final Gather (`r.Lumen.FinalGatherMethod 0`) for faster, lower-quality GI.\n- Medium reflection quality (`sg.ReflectionQuality 1`) disables Lumen Reflections, uses SSR on smooth\n  surfaces, and retains rough specular from Lumen GI.\n- Below Lumen, use the project/platform's supported baked or simpler GI/reflection fallback.\n\nStart from Epic's `BaseScalability.ini` and platform device profiles; they coordinate many interdependent\nsettings to preserve a reasonably consistent look.\n\n## Isolate cost\n\n1. Confirm Lumen passes are material in `profilegpu`/GPU trace.\n2. Capture Lumen visualization/overview modes to find scene representation, update, reflection, or\n   screen-trace problems.\n3. A/B GI and reflection scalability independently.\n4. Test worst-case dynamic lights, camera motion, emissive content, interiors/exteriors, and distance.\n5. Validate temporal stability and lighting continuity on every tier.\n\nLumen uses async compute on supported consoles and can overlap other work. Per-pass timings can include\noverlap. Disable Lumen async compute only for isolated profiling, then restore it and judge total frame\ntime; overlap is part of the shipping performance strategy.\n","searchText":"lumen gi and reflections select quality by target - high-quality lumen is the modern dynamic gi/reflection path for capable targets. - ue 5.8 lumen lite is beta. medium gi quality (sg.globalilluminationquality 1) selects its irradiance field final gather (r.lumen.finalgathermethod 0) for faster, lower-quality gi. - medium reflection quality (sg.reflectionquality 1) disables lumen reflections, uses ssr on smooth surfaces, and retains rough specular from lumen gi. - below lumen, use the project/platform's supported baked or simpler gi/reflection fallback. start from epic's basescalability.ini and platform device profiles; they coordinate many interdependent settings to preserve a reasonably consistent look. isolate cost 1. confirm lumen passes are material in profilegpu/gpu trace. 2. capture lumen visualization/overview modes to find scene representation, update, reflection, or screen-trace problems. 3. a/b gi and reflection scalability independently. 4. test worst-case dynamic lights, camera motion, emissive content, interiors/exteriors, and distance. 5. validate temporal stability and lighting continuity on every tier. lumen uses async compute on supported consoles and can overlap other work. per-pass timings can include overlap. disable lumen async compute only for isolated profiling, then restore it and judge total frame time; overlap is part of the shipping performance strategy."},{"slug":"materials-translucency-and-overdraw","file":"materials-translucency-and-overdraw.md","title":"Materials, translucency, and overdraw","rawMarkdown":"# Materials, translucency, and overdraw\n\n## Diagnose\n\n1. Confirm BasePass, translucency, post, or a material-bound draw is significant in GPU timing.\n2. Use Shader Complexity (`Alt+8` / `viewmode shadercomplexity`) to locate expensive pixel regions.\n3. Inspect Quad Overdraw/other supported view modes when tiny triangles or repeated coverage is suspected.\n4. Isolate the material/primitive/effect and re-capture the same frame.\n\nShader Complexity primarily visualizes instruction count. It does not reliably price texture fetches,\nbandwidth, divergent loops, vertex/WPO work, or platform-specific scheduling. Use it to locate suspects,\nthen prove cost with GPU milliseconds.\n\n## Levers\n\n- Reduce full-screen or large-screen material coverage before micro-optimizing a tiny object.\n- Reduce overlapping translucent/masked layers, particle size, spawn density, and unnecessary sorting.\n- Replace translucent effects with opaque/masked/dithered/mesh alternatives only when the visual result\n  and temporal stability remain acceptable.\n- Remove unused texture samples/features; move invariant work out of per-pixel paths where supported.\n- Bound WPO and stop distant/imperceptible deformation.\n- Reduce unique static-switch combinations/permutations; do not convert runtime decisions to static\n  switches without considering compile/package/PSO cost.\n- Reduce material slots/sections when submission evidence supports it; preserve authoring flexibility\n  where the measured cost is elsewhere.\n\nOptimize the exact platform permutation and worst visible overlap. Editor shader stats alone are not a\nshipping GPU measurement.\n","webMarkdown":"## Diagnose\n\n1. Confirm BasePass, translucency, post, or a material-bound draw is significant in GPU timing.\n2. Use Shader Complexity (`Alt+8` / `viewmode shadercomplexity`) to locate expensive pixel regions.\n3. Inspect Quad Overdraw/other supported view modes when tiny triangles or repeated coverage is suspected.\n4. Isolate the material/primitive/effect and re-capture the same frame.\n\nShader Complexity primarily visualizes instruction count. It does not reliably price texture fetches,\nbandwidth, divergent loops, vertex/WPO work, or platform-specific scheduling. Use it to locate suspects,\nthen prove cost with GPU milliseconds.\n\n## Levers\n\n- Reduce full-screen or large-screen material coverage before micro-optimizing a tiny object.\n- Reduce overlapping translucent/masked layers, particle size, spawn density, and unnecessary sorting.\n- Replace translucent effects with opaque/masked/dithered/mesh alternatives only when the visual result\n  and temporal stability remain acceptable.\n- Remove unused texture samples/features; move invariant work out of per-pixel paths where supported.\n- Bound WPO and stop distant/imperceptible deformation.\n- Reduce unique static-switch combinations/permutations; do not convert runtime decisions to static\n  switches without considering compile/package/PSO cost.\n- Reduce material slots/sections when submission evidence supports it; preserve authoring flexibility\n  where the measured cost is elsewhere.\n\nOptimize the exact platform permutation and worst visible overlap. Editor shader stats alone are not a\nshipping GPU measurement.\n","searchText":"materials, translucency, and overdraw diagnose 1. confirm basepass, translucency, post, or a material-bound draw is significant in gpu timing. 2. use shader complexity (alt+8 / viewmode shadercomplexity) to locate expensive pixel regions. 3. inspect quad overdraw/other supported view modes when tiny triangles or repeated coverage is suspected. 4. isolate the material/primitive/effect and re-capture the same frame. shader complexity primarily visualizes instruction count. it does not reliably price texture fetches, bandwidth, divergent loops, vertex/wpo work, or platform-specific scheduling. use it to locate suspects, then prove cost with gpu milliseconds. levers - reduce full-screen or large-screen material coverage before micro-optimizing a tiny object. - reduce overlapping translucent/masked layers, particle size, spawn density, and unnecessary sorting. - replace translucent effects with opaque/masked/dithered/mesh alternatives only when the visual result and temporal stability remain acceptable. - remove unused texture samples/features; move invariant work out of per-pixel paths where supported. - bound wpo and stop distant/imperceptible deformation. - reduce unique static-switch combinations/permutations; do not convert runtime decisions to static switches without considering compile/package/pso cost. - reduce material slots/sections when submission evidence supports it; preserve authoring flexibility where the measured cost is elsewhere. optimize the exact platform permutation and worst visible overlap. editor shader stats alone are not a shipping gpu measurement."},{"slug":"megalights","file":"megalights.md","title":"MegaLights","rawMarkdown":"# MegaLights\n\nMegaLights is **Production Ready in UE 5.8**. It replaces several deferred direct-lighting/shadow paths\nfor local lights and supports many dynamic shadowed area lights. Hardware ray tracing is recommended;\neach light can use ray-traced or VSM shadowing.\n\nDirectional Light support is opt-in with `r.MegaLights.DirectionalLights 1` and disabled by default.\nEpic recommends Deferred Lighting with VSM for a strong sun because the MegaLights path has quality\nlimitations; a dim, soft moonlight can be a better fit. Sky Light remains outside MegaLights.\n\n## Understand the budget\n\nMegaLights traces a fixed sample budget per pixel toward important lights. Runtime cost is more stable\nthan per-light traditional paths, but quality/noise worsens when too many important lights compete at\none pixel. More lights are not free artistically even when the timing remains bounded.\n\n## Diagnose\n\n1. Use MegaLights light finder, ray visualizer, and shadow-caster/mismatch views.\n2. Compare complete GPU frame time, not only one MegaLights event; it replaces multiple passes.\n3. Inspect off-screen and tiny bright lights, huge attenuation radii, overlapping volumes, and shadow\n   methods.\n4. Test motion/noise at target internal resolution and TSR quality.\n\n## Scale\n\n| Control | Effect |\n|---|---|\n| `r.MegaLights.Allow 0` | disable per tier/device profile for a fallback path |\n| `r.MegaLights.DownsampleMode` | adjust sampling/tracing resolution; stronger downsampling saves work but can reduce quality |\n| `r.MegaLights.NumSamplesPerPixel` | more samples improve stability/quality and increase GPU cost |\n| Allow MegaLights per light | remove incompatible/problem lights from the path |\n| Shadow Method per light | choose ray tracing or VSM with different quality/CPU/memory/GPU tradeoffs |\n\nStart from the Shadow Quality scalability group in `BaseScalability.ini`. High-quality translucency,\nvolumetric fog, hair, textured area lights, and soft shadows have their own cost; scale only after the\nvisualizer identifies them.\n","webMarkdown":"MegaLights is **Production Ready in UE 5.8**. It replaces several deferred direct-lighting/shadow paths\nfor local lights and supports many dynamic shadowed area lights. Hardware ray tracing is recommended;\neach light can use ray-traced or VSM shadowing.\n\nDirectional Light support is opt-in with `r.MegaLights.DirectionalLights 1` and disabled by default.\nEpic recommends Deferred Lighting with VSM for a strong sun because the MegaLights path has quality\nlimitations; a dim, soft moonlight can be a better fit. Sky Light remains outside MegaLights.\n\n## Understand the budget\n\nMegaLights traces a fixed sample budget per pixel toward important lights. Runtime cost is more stable\nthan per-light traditional paths, but quality/noise worsens when too many important lights compete at\none pixel. More lights are not free artistically even when the timing remains bounded.\n\n## Diagnose\n\n1. Use MegaLights light finder, ray visualizer, and shadow-caster/mismatch views.\n2. Compare complete GPU frame time, not only one MegaLights event; it replaces multiple passes.\n3. Inspect off-screen and tiny bright lights, huge attenuation radii, overlapping volumes, and shadow\n   methods.\n4. Test motion/noise at target internal resolution and TSR quality.\n\n## Scale\n\n| Control | Effect |\n|---|---|\n| `r.MegaLights.Allow 0` | disable per tier/device profile for a fallback path |\n| `r.MegaLights.DownsampleMode` | adjust sampling/tracing resolution; stronger downsampling saves work but can reduce quality |\n| `r.MegaLights.NumSamplesPerPixel` | more samples improve stability/quality and increase GPU cost |\n| Allow MegaLights per light | remove incompatible/problem lights from the path |\n| Shadow Method per light | choose ray tracing or VSM with different quality/CPU/memory/GPU tradeoffs |\n\nStart from the Shadow Quality scalability group in `BaseScalability.ini`. High-quality translucency,\nvolumetric fog, hair, textured area lights, and soft shadows have their own cost; scale only after the\nvisualizer identifies them.\n","searchText":"megalights megalights is production ready in ue 5.8. it replaces several deferred direct-lighting/shadow paths for local lights and supports many dynamic shadowed area lights. hardware ray tracing is recommended; each light can use ray-traced or vsm shadowing. directional light support is opt-in with r.megalights.directionallights 1 and disabled by default. epic recommends deferred lighting with vsm for a strong sun because the megalights path has quality limitations; a dim, soft moonlight can be a better fit. sky light remains outside megalights. understand the budget megalights traces a fixed sample budget per pixel toward important lights. runtime cost is more stable than per-light traditional paths, but quality/noise worsens when too many important lights compete at one pixel. more lights are not free artistically even when the timing remains bounded. diagnose 1. use megalights light finder, ray visualizer, and shadow-caster/mismatch views. 2. compare complete gpu frame time, not only one megalights event; it replaces multiple passes. 3. inspect off-screen and tiny bright lights, huge attenuation radii, overlapping volumes, and shadow methods. 4. test motion/noise at target internal resolution and tsr quality. scale | control | effect | |---|---| | r.megalights.allow 0 | disable per tier/device profile for a fallback path | | r.megalights.downsamplemode | adjust sampling/tracing resolution; stronger downsampling saves work but can reduce quality | | r.megalights.numsamplesperpixel | more samples improve stability/quality and increase gpu cost | | allow megalights per light | remove incompatible/problem lights from the path | | shadow method per light | choose ray tracing or vsm with different quality/cpu/memory/gpu tradeoffs | start from the shadow quality scalability group in basescalability.ini. high-quality translucency, volumetric fog, hair, textured area lights, and soft shadows have their own cost; scale only after the visualizer identifies them."},{"slug":"nanite-geometry","file":"nanite-geometry.md","title":"Nanite geometry","rawMarkdown":"# Nanite geometry\n\nUse Nanite for supported high-detail static/skeletal content when its virtualized path matches the\ntarget. Preserve conventional LOD/fallback behavior for unsupported platforms and features.\n\n## Diagnose\n\n- Open View Modes -> Nanite Visualization for triangles/clusters/overdraw/streaming/fallback evidence.\n- Run `NaniteStats`; use `NaniteStats List` and a named view such as\n  `NaniteStats VirtualShadowMaps` when applicable.\n- Toggle `r.Nanite 0` only as a diagnostic/fallback-platform experiment; a scene authored around\n  Nanite may explode into conventional draw calls or unusable fallback cost.\n\n## Cost levers\n\n| Evidence | Action |\n|---|---|\n| streaming pool thrashes in a static view | increase `r.Nanite.Streaming.StreamingPoolSize` if memory permits, or reduce resident demand |\n| GPU memory/storage excess | reduce source detail where imperceptible; review fallback and texture payloads |\n| masked/stacked surface overdraw | simplify aggregate geometry/material coverage; inspect Nanite Overdraw |\n| deformation/WPO cost | bound affected content and distance; remove deformation when imperceptible |\n| blinking/missing clusters at extreme complexity | inspect `ClustersSW`/`ClustersHW`; size candidate/visible limits conservatively in config |\n| foliage loses area | evaluate Preserve Area and foliage-specific representation/LOD |\n\nLarger streaming pools reduce IO/decompression churn but consume more memory. `Max Edge Length Factor`\nshould remain `0` unless solving observed over-simplification on deforming/spline content; increasing\nit preserves detail at additional cost.\n\nDo not use triangle count alone as a performance target. Measure Nanite passes, material/shadow cost,\nstreaming, storage, and fallback behavior.\n","webMarkdown":"Use Nanite for supported high-detail static/skeletal content when its virtualized path matches the\ntarget. Preserve conventional LOD/fallback behavior for unsupported platforms and features.\n\n## Diagnose\n\n- Open View Modes -> Nanite Visualization for triangles/clusters/overdraw/streaming/fallback evidence.\n- Run `NaniteStats`; use `NaniteStats List` and a named view such as\n  `NaniteStats VirtualShadowMaps` when applicable.\n- Toggle `r.Nanite 0` only as a diagnostic/fallback-platform experiment; a scene authored around\n  Nanite may explode into conventional draw calls or unusable fallback cost.\n\n## Cost levers\n\n| Evidence | Action |\n|---|---|\n| streaming pool thrashes in a static view | increase `r.Nanite.Streaming.StreamingPoolSize` if memory permits, or reduce resident demand |\n| GPU memory/storage excess | reduce source detail where imperceptible; review fallback and texture payloads |\n| masked/stacked surface overdraw | simplify aggregate geometry/material coverage; inspect Nanite Overdraw |\n| deformation/WPO cost | bound affected content and distance; remove deformation when imperceptible |\n| blinking/missing clusters at extreme complexity | inspect `ClustersSW`/`ClustersHW`; size candidate/visible limits conservatively in config |\n| foliage loses area | evaluate Preserve Area and foliage-specific representation/LOD |\n\nLarger streaming pools reduce IO/decompression churn but consume more memory. `Max Edge Length Factor`\nshould remain `0` unless solving observed over-simplification on deforming/spline content; increasing\nit preserves detail at additional cost.\n\nDo not use triangle count alone as a performance target. Measure Nanite passes, material/shadow cost,\nstreaming, storage, and fallback behavior.\n","searchText":"nanite geometry use nanite for supported high-detail static/skeletal content when its virtualized path matches the target. preserve conventional lod/fallback behavior for unsupported platforms and features. diagnose - open view modes -> nanite visualization for triangles/clusters/overdraw/streaming/fallback evidence. - run nanitestats; use nanitestats list and a named view such as nanitestats virtualshadowmaps when applicable. - toggle r.nanite 0 only as a diagnostic/fallback-platform experiment; a scene authored around nanite may explode into conventional draw calls or unusable fallback cost. cost levers | evidence | action | |---|---| | streaming pool thrashes in a static view | increase r.nanite.streaming.streamingpoolsize if memory permits, or reduce resident demand | | gpu memory/storage excess | reduce source detail where imperceptible; review fallback and texture payloads | | masked/stacked surface overdraw | simplify aggregate geometry/material coverage; inspect nanite overdraw | | deformation/wpo cost | bound affected content and distance; remove deformation when imperceptible | | blinking/missing clusters at extreme complexity | inspect clusterssw/clustershw; size candidate/visible limits conservatively in config | | foliage loses area | evaluate preserve area and foliage-specific representation/lod | larger streaming pools reduce io/decompression churn but consume more memory. max edge length factor should remain 0 unless solving observed over-simplification on deforming/spline content; increasing it preserves detail at additional cost. do not use triangle count alone as a performance target. measure nanite passes, material/shadow cost, streaming, storage, and fallback behavior."},{"slug":"resolution-tsr-and-dynamic-resolution","file":"resolution-tsr-and-dynamic-resolution.md","title":"Resolution, TSR, and Dynamic Resolution","rawMarkdown":"# Resolution, TSR, and Dynamic Resolution\n\n## TSR\n\nTSR renders at a lower internal resolution and reconstructs the display image. Its work includes\ninput-resolution and display-resolution costs, so lowering screen percentage may not reduce the TSR\npass itself in direct proportion even when it reduces the rest of the frame.\n\nActions:\n\n1. Capture GPU cost at the production output resolution.\n2. Compare controlled primary screen percentages with identical content.\n3. Set Anti-Aliasing scalability through `sg.AntiAliasingQuality` (`0` Low through `4` Cinematic).\n4. Inspect Show -> Visualize -> Temporal Upscaler for velocity, rejection, translucency, exposure,\n   input/output, and active quality information.\n5. Inspect the `Scene > PostProcessing > TemporalSuperResolution` event in GPU tools.\n6. Fix velocity/translucency/material history defects before raising global quality to conceal them.\n\nAvoid routine input screen percentages below 50%; Epic reserves extreme upscaling for exceptional\ncases such as output beyond 4K or brief dynamic-resolution pressure.\n\n## Dynamic Resolution\n\nEnable through Game User Settings/C++ for supported targets, then configure:\n\n| CVar | Effect |\n|---|---|\n| `r.DynamicRes.MinScreenPercentage` | lower bound; decreasing permits more quality loss to recover GPU time |\n| `r.DynamicRes.MaxScreenPercentage` | allocation/quality ceiling |\n| `r.DynamicRes.FrameTimeBudget` | GPU-frame target in milliseconds |\n| `r.DynamicRes.HistorySize` | larger smooths decisions but reacts more slowly; smaller reacts faster but is noisier |\n\nUse `stat unitgraph`, then `stat raw`, to inspect raw GPU time and selected primary screen percentage.\nDynamic resolution reacts to prior GPU workload and may panic downward after consecutive over-budget\nframes. It cannot predict every camera cut/effect burst and cannot recover a CPU-bound frame by doing\nless GPU pixel work.\n","webMarkdown":"## TSR\n\nTSR renders at a lower internal resolution and reconstructs the display image. Its work includes\ninput-resolution and display-resolution costs, so lowering screen percentage may not reduce the TSR\npass itself in direct proportion even when it reduces the rest of the frame.\n\nActions:\n\n1. Capture GPU cost at the production output resolution.\n2. Compare controlled primary screen percentages with identical content.\n3. Set Anti-Aliasing scalability through `sg.AntiAliasingQuality` (`0` Low through `4` Cinematic).\n4. Inspect Show -> Visualize -> Temporal Upscaler for velocity, rejection, translucency, exposure,\n   input/output, and active quality information.\n5. Inspect the `Scene > PostProcessing > TemporalSuperResolution` event in GPU tools.\n6. Fix velocity/translucency/material history defects before raising global quality to conceal them.\n\nAvoid routine input screen percentages below 50%; Epic reserves extreme upscaling for exceptional\ncases such as output beyond 4K or brief dynamic-resolution pressure.\n\n## Dynamic Resolution\n\nEnable through Game User Settings/C++ for supported targets, then configure:\n\n| CVar | Effect |\n|---|---|\n| `r.DynamicRes.MinScreenPercentage` | lower bound; decreasing permits more quality loss to recover GPU time |\n| `r.DynamicRes.MaxScreenPercentage` | allocation/quality ceiling |\n| `r.DynamicRes.FrameTimeBudget` | GPU-frame target in milliseconds |\n| `r.DynamicRes.HistorySize` | larger smooths decisions but reacts more slowly; smaller reacts faster but is noisier |\n\nUse `stat unitgraph`, then `stat raw`, to inspect raw GPU time and selected primary screen percentage.\nDynamic resolution reacts to prior GPU workload and may panic downward after consecutive over-budget\nframes. It cannot predict every camera cut/effect burst and cannot recover a CPU-bound frame by doing\nless GPU pixel work.\n","searchText":"resolution, tsr, and dynamic resolution tsr tsr renders at a lower internal resolution and reconstructs the display image. its work includes input-resolution and display-resolution costs, so lowering screen percentage may not reduce the tsr pass itself in direct proportion even when it reduces the rest of the frame. actions: 1. capture gpu cost at the production output resolution. 2. compare controlled primary screen percentages with identical content. 3. set anti-aliasing scalability through sg.antialiasingquality (0 low through 4 cinematic). 4. inspect show -> visualize -> temporal upscaler for velocity, rejection, translucency, exposure, input/output, and active quality information. 5. inspect the scene > postprocessing > temporalsuperresolution event in gpu tools. 6. fix velocity/translucency/material history defects before raising global quality to conceal them. avoid routine input screen percentages below 50%; epic reserves extreme upscaling for exceptional cases such as output beyond 4k or brief dynamic-resolution pressure. dynamic resolution enable through game user settings/c++ for supported targets, then configure: | cvar | effect | |---|---| | r.dynamicres.minscreenpercentage | lower bound; decreasing permits more quality loss to recover gpu time | | r.dynamicres.maxscreenpercentage | allocation/quality ceiling | | r.dynamicres.frametimebudget | gpu-frame target in milliseconds | | r.dynamicres.historysize | larger smooths decisions but reacts more slowly; smaller reacts faster but is noisier | use stat unitgraph, then stat raw, to inspect raw gpu time and selected primary screen percentage. dynamic resolution reacts to prior gpu workload and may panic downward after consecutive over-budget frames. it cannot predict every camera cut/effect burst and cannot recover a cpu-bound frame by doing less gpu pixel work."},{"slug":"scalability-and-device-profiles","file":"scalability-and-device-profiles.md","title":"Scalability and device profiles","rawMarkdown":"# Scalability and device profiles\n\n## Ownership\n\n- Use scalability groups for player-facing quality families.\n- Use device profiles for platform/device defaults, feature support, memory buckets, and overrides.\n- Store project overrides in project `Config`, not edited engine base files.\n- Treat `Engine/Config/BaseScalability.ini` and platform base device profiles as current reference\n  implementations, then override only measured needs.\n\nCore groups include resolution, view distance, anti-aliasing, shadows, global illumination, reflections,\npost processing, textures, effects, foliage, and shading. Validate the exact UE 5.8 group contents;\none `sg.*` value can change many CVars.\n\n## Tier workflow\n\n1. Define minimum/recommended target hardware and renderer feature support.\n2. Establish Low/Medium/High/Epic intent with a stable gameplay-readability floor.\n3. Begin with engine group defaults; measure every target device.\n4. Override subsystem controls only when the group misses the budget or quality target.\n5. Expose settings whose visual/performance trade is meaningful to players.\n6. Restart/reload when a feature path or shader permutation requires it; label settings accordingly.\n7. Test saved settings, auto-detection/defaults, upgrades, and unsupported hardware fallback.\n\nNever let a low tier remove enemies, hazards, navigation cues, competitive visibility, or essential\nfeedback. Scale visual richness and representation, not game rules.\n","webMarkdown":"## Ownership\n\n- Use scalability groups for player-facing quality families.\n- Use device profiles for platform/device defaults, feature support, memory buckets, and overrides.\n- Store project overrides in project `Config`, not edited engine base files.\n- Treat `Engine/Config/BaseScalability.ini` and platform base device profiles as current reference\n  implementations, then override only measured needs.\n\nCore groups include resolution, view distance, anti-aliasing, shadows, global illumination, reflections,\npost processing, textures, effects, foliage, and shading. Validate the exact UE 5.8 group contents;\none `sg.*` value can change many CVars.\n\n## Tier workflow\n\n1. Define minimum/recommended target hardware and renderer feature support.\n2. Establish Low/Medium/High/Epic intent with a stable gameplay-readability floor.\n3. Begin with engine group defaults; measure every target device.\n4. Override subsystem controls only when the group misses the budget or quality target.\n5. Expose settings whose visual/performance trade is meaningful to players.\n6. Restart/reload when a feature path or shader permutation requires it; label settings accordingly.\n7. Test saved settings, auto-detection/defaults, upgrades, and unsupported hardware fallback.\n\nNever let a low tier remove enemies, hazards, navigation cues, competitive visibility, or essential\nfeedback. Scale visual richness and representation, not game rules.\n","searchText":"scalability and device profiles ownership - use scalability groups for player-facing quality families. - use device profiles for platform/device defaults, feature support, memory buckets, and overrides. - store project overrides in project config, not edited engine base files. - treat engine/config/basescalability.ini and platform base device profiles as current reference implementations, then override only measured needs. core groups include resolution, view distance, anti-aliasing, shadows, global illumination, reflections, post processing, textures, effects, foliage, and shading. validate the exact ue 5.8 group contents; one sg. value can change many cvars. tier workflow 1. define minimum/recommended target hardware and renderer feature support. 2. establish low/medium/high/epic intent with a stable gameplay-readability floor. 3. begin with engine group defaults; measure every target device. 4. override subsystem controls only when the group misses the budget or quality target. 5. expose settings whose visual/performance trade is meaningful to players. 6. restart/reload when a feature path or shader permutation requires it; label settings accordingly. 7. test saved settings, auto-detection/defaults, upgrades, and unsupported hardware fallback. never let a low tier remove enemies, hazards, navigation cues, competitive visibility, or essential feedback. scale visual richness and representation, not game rules."},{"slug":"sources","file":"sources.md","title":"UE 5.8 primary sources","rawMarkdown":"# UE 5.8 primary sources\n\n- [UE 5.8 Release Notes](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-8-release-notes)\n- [Optimizing and Debugging Real-Time Rendering](https://dev.epicgames.com/documentation/en-us/unreal-engine/optimizing-and-debugging-projects-for-realtime-rendering-in-unreal-engine)\n- [Scalability Reference](https://dev.epicgames.com/documentation/en-us/unreal-engine/scalability-reference-for-unreal-engine)\n- [Setting Device Profiles](https://dev.epicgames.com/documentation/en-us/unreal-engine/setting-up-device-profiles-in-unreal-engine)\n- [Temporal Super Resolution](https://dev.epicgames.com/documentation/en-us/unreal-engine/temporal-super-resolution-in-unreal-engine)\n- [Temporal Upscalers](https://dev.epicgames.com/documentation/en-us/unreal-engine/temporal-upscalers-in-unreal-engine)\n- [Dynamic Resolution](https://dev.epicgames.com/documentation/en-us/unreal-engine/dynamic-resolution-in-unreal-engine)\n- [Nanite Virtualized Geometry](https://dev.epicgames.com/documentation/en-us/unreal-engine/nanite-virtualized-geometry-in-unreal-engine)\n- [Working with Nanite-Enabled Content](https://dev.epicgames.com/documentation/en-us/unreal-engine/working-with-naniteenabled-content)\n- [Nanite Technical Details](https://dev.epicgames.com/documentation/en-us/unreal-engine/nanite-technical-details)\n- [Lumen Performance Guide](https://dev.epicgames.com/documentation/en-us/unreal-engine/lumen-performance-guide-for-unreal-engine)\n- [Virtual Shadow Maps](https://dev.epicgames.com/documentation/en-us/unreal-engine/virtual-shadow-maps-in-unreal-engine)\n- [MegaLights](https://dev.epicgames.com/documentation/en-us/unreal-engine/megalights-in-unreal-engine)\n- [Viewport Modes](https://dev.epicgames.com/documentation/en-us/unreal-engine/viewport-modes-in-unreal-engine)\n- [Visibility and Occlusion Culling](https://dev.epicgames.com/documentation/en-us/unreal-engine/visibility-and-occlusion-culling-in-unreal-engine)\n- [Primitive Debugger](https://dev.epicgames.com/documentation/en-us/unreal-engine/primitive-debugger-in-unreal-engine)\n- [Render Resource Viewer](https://dev.epicgames.com/documentation/en-us/unreal-engine/render-resource-viewer-in-unreal-engine)\n\nPages were checked against UE 5.8 documentation on 2026-07-19. Reconfirm feature maturity,\nrenderer/platform support, scalability-group contents, visualization names, and CVars after an engine\nupgrade.\n","webMarkdown":"- [UE 5.8 Release Notes](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-8-release-notes)\n- [Optimizing and Debugging Real-Time Rendering](https://dev.epicgames.com/documentation/en-us/unreal-engine/optimizing-and-debugging-projects-for-realtime-rendering-in-unreal-engine)\n- [Scalability Reference](https://dev.epicgames.com/documentation/en-us/unreal-engine/scalability-reference-for-unreal-engine)\n- [Setting Device Profiles](https://dev.epicgames.com/documentation/en-us/unreal-engine/setting-up-device-profiles-in-unreal-engine)\n- [Temporal Super Resolution](https://dev.epicgames.com/documentation/en-us/unreal-engine/temporal-super-resolution-in-unreal-engine)\n- [Temporal Upscalers](https://dev.epicgames.com/documentation/en-us/unreal-engine/temporal-upscalers-in-unreal-engine)\n- [Dynamic Resolution](https://dev.epicgames.com/documentation/en-us/unreal-engine/dynamic-resolution-in-unreal-engine)\n- [Nanite Virtualized Geometry](https://dev.epicgames.com/documentation/en-us/unreal-engine/nanite-virtualized-geometry-in-unreal-engine)\n- [Working with Nanite-Enabled Content](https://dev.epicgames.com/documentation/en-us/unreal-engine/working-with-naniteenabled-content)\n- [Nanite Technical Details](https://dev.epicgames.com/documentation/en-us/unreal-engine/nanite-technical-details)\n- [Lumen Performance Guide](https://dev.epicgames.com/documentation/en-us/unreal-engine/lumen-performance-guide-for-unreal-engine)\n- [Virtual Shadow Maps](https://dev.epicgames.com/documentation/en-us/unreal-engine/virtual-shadow-maps-in-unreal-engine)\n- [MegaLights](https://dev.epicgames.com/documentation/en-us/unreal-engine/megalights-in-unreal-engine)\n- [Viewport Modes](https://dev.epicgames.com/documentation/en-us/unreal-engine/viewport-modes-in-unreal-engine)\n- [Visibility and Occlusion Culling](https://dev.epicgames.com/documentation/en-us/unreal-engine/visibility-and-occlusion-culling-in-unreal-engine)\n- [Primitive Debugger](https://dev.epicgames.com/documentation/en-us/unreal-engine/primitive-debugger-in-unreal-engine)\n- [Render Resource Viewer](https://dev.epicgames.com/documentation/en-us/unreal-engine/render-resource-viewer-in-unreal-engine)\n\nPages were checked against UE 5.8 documentation on 2026-07-19. Reconfirm feature maturity,\nrenderer/platform support, scalability-group contents, visualization names, and CVars after an engine\nupgrade.\n","searchText":"ue 5.8 primary sources - ue 5.8 release notes - optimizing and debugging real-time rendering - scalability reference - setting device profiles - temporal super resolution - temporal upscalers - dynamic resolution - nanite virtualized geometry - working with nanite-enabled content - nanite technical details - lumen performance guide - virtual shadow maps - megalights - viewport modes - visibility and occlusion culling - primitive debugger - render resource viewer pages were checked against ue 5.8 documentation on 2026-07-19. reconfirm feature maturity, renderer/platform support, scalability-group contents, visualization names, and cvars after an engine upgrade."},{"slug":"submission-culling-and-lods","file":"submission-culling-and-lods.md","title":"Submission, culling, and LODs","rawMarkdown":"# Submission, culling, and LODs\n\nRender-thread cost often follows visible primitive/component/section/light counts and state diversity,\nnot raw triangle count alone.\n\n## Inspect\n\n- `stat unit`, `stat sceneRendering`, `stat rhi`, and Timing Insights Render/RHI tracks.\n- Runtime **Primitive Debugger** (`PrimitiveDebugger.Open`) in Development/Test builds for primitive,\n  draw-call, and LOD data. It is Experimental in UE 5.8; use it diagnostically, not as shipping logic.\n- Freeze rendering/occlusion and `r.VisualizeOccludedPrimitives 1` to inspect culling behavior.\n\n## Reduce submissions and visibility work\n\n- Instance repeated meshes when transforms/material requirements permit.\n- Merge actors/sections only when it does not destroy culling granularity, streaming, interaction, or\n  authoring needs.\n- Use HLOD for distant groups and conventional skeletal/static LODs where Nanite is not the path.\n- Set Max Draw Distance or Cull Distance Volumes for content that becomes irrelevant.\n- Keep bounds accurate; oversized bounds harm culling, shadows, and streaming decisions.\n- Avoid thousands of independently ticking/updating render components when a batched representation fits.\n- Remove material slots/sections only when section submission is measured.\n\nUnreal applies distance, frustum, precomputed visibility, then dynamic occlusion according to method and\nplatform. Hardware occlusion queries are enabled by default on supported paths. Precomputed Visibility\ntrades build/runtime memory for reduced runtime rendering work and best fits constrained, mostly static,\nsmall-to-medium environments.\n\nTest occlusion changes during camera motion. More aggressive culling can add popping or query cost and\ncan be worse than rendering small cheap objects.\n","webMarkdown":"Render-thread cost often follows visible primitive/component/section/light counts and state diversity,\nnot raw triangle count alone.\n\n## Inspect\n\n- `stat unit`, `stat sceneRendering`, `stat rhi`, and Timing Insights Render/RHI tracks.\n- Runtime **Primitive Debugger** (`PrimitiveDebugger.Open`) in Development/Test builds for primitive,\n  draw-call, and LOD data. It is Experimental in UE 5.8; use it diagnostically, not as shipping logic.\n- Freeze rendering/occlusion and `r.VisualizeOccludedPrimitives 1` to inspect culling behavior.\n\n## Reduce submissions and visibility work\n\n- Instance repeated meshes when transforms/material requirements permit.\n- Merge actors/sections only when it does not destroy culling granularity, streaming, interaction, or\n  authoring needs.\n- Use HLOD for distant groups and conventional skeletal/static LODs where Nanite is not the path.\n- Set Max Draw Distance or Cull Distance Volumes for content that becomes irrelevant.\n- Keep bounds accurate; oversized bounds harm culling, shadows, and streaming decisions.\n- Avoid thousands of independently ticking/updating render components when a batched representation fits.\n- Remove material slots/sections only when section submission is measured.\n\nUnreal applies distance, frustum, precomputed visibility, then dynamic occlusion according to method and\nplatform. Hardware occlusion queries are enabled by default on supported paths. Precomputed Visibility\ntrades build/runtime memory for reduced runtime rendering work and best fits constrained, mostly static,\nsmall-to-medium environments.\n\nTest occlusion changes during camera motion. More aggressive culling can add popping or query cost and\ncan be worse than rendering small cheap objects.\n","searchText":"submission, culling, and lods render-thread cost often follows visible primitive/component/section/light counts and state diversity, not raw triangle count alone. inspect - stat unit, stat scenerendering, stat rhi, and timing insights render/rhi tracks. - runtime primitive debugger (primitivedebugger.open) in development/test builds for primitive, draw-call, and lod data. it is experimental in ue 5.8; use it diagnostically, not as shipping logic. - freeze rendering/occlusion and r.visualizeoccludedprimitives 1 to inspect culling behavior. reduce submissions and visibility work - instance repeated meshes when transforms/material requirements permit. - merge actors/sections only when it does not destroy culling granularity, streaming, interaction, or authoring needs. - use hlod for distant groups and conventional skeletal/static lods where nanite is not the path. - set max draw distance or cull distance volumes for content that becomes irrelevant. - keep bounds accurate; oversized bounds harm culling, shadows, and streaming decisions. - avoid thousands of independently ticking/updating render components when a batched representation fits. - remove material slots/sections only when section submission is measured. unreal applies distance, frustum, precomputed visibility, then dynamic occlusion according to method and platform. hardware occlusion queries are enabled by default on supported paths. precomputed visibility trades build/runtime memory for reduced runtime rendering work and best fits constrained, mostly static, small-to-medium environments. test occlusion changes during camera motion. more aggressive culling can add popping or query cost and can be worse than rendering small cheap objects."},{"slug":"symptom-recipes","file":"symptom-recipes.md","title":"Symptom recipes","rawMarkdown":"# Symptom recipes\n\n| Symptom | Prove first | First bounded experiment |\n|---|---|---|\n| slow only at high resolution | pixel-scaled GPU passes | lower screen percentage; compare pass deltas |\n| slow in dense city/forest | Render thread, Nanite/material/VSM/visibility | isolate primitive/section, overdraw, caster invalidation |\n| shadow spike while foliage moves | VSM uncached pages/casters | disable distant WPO/shadows on one foliage class |\n| camera cuts hitch | visibility/VSM/streaming/upscaler history | marked trace plus cache/streaming views |\n| many lights stay fast but noisy | MegaLights sample competition | reduce competing radii/lights or raise samples in controlled A/B |\n| reflections dominate | Lumen reflection pass | compare reflection scalability separately from GI |\n| translucent combat effect tanks GPU | translucency/overdraw event | cut overlap/coverage for one effect |\n| render thread slow, GPU has headroom | primitive/section/submission count | instance/cull one high-count category |\n| GPU memory grows by location | resource snapshot and streaming residency | identify largest new owners and correct residency/LOD |\n| low tier changes nothing | device profile/group not applied or restart needed | display active CVars/profile and verify packaged build |\n| dynamic resolution bottoms out | sustained GPU cost exceeds minimum-resolution budget or CPU bound | inspect GPU at minimum percentage; optimize dominant pass |\n\nFor every recipe, restore the toggle, implement the production-quality change through owned settings,\nand capture the same worst case again.\n","webMarkdown":"| Symptom | Prove first | First bounded experiment |\n|---|---|---|\n| slow only at high resolution | pixel-scaled GPU passes | lower screen percentage; compare pass deltas |\n| slow in dense city/forest | Render thread, Nanite/material/VSM/visibility | isolate primitive/section, overdraw, caster invalidation |\n| shadow spike while foliage moves | VSM uncached pages/casters | disable distant WPO/shadows on one foliage class |\n| camera cuts hitch | visibility/VSM/streaming/upscaler history | marked trace plus cache/streaming views |\n| many lights stay fast but noisy | MegaLights sample competition | reduce competing radii/lights or raise samples in controlled A/B |\n| reflections dominate | Lumen reflection pass | compare reflection scalability separately from GI |\n| translucent combat effect tanks GPU | translucency/overdraw event | cut overlap/coverage for one effect |\n| render thread slow, GPU has headroom | primitive/section/submission count | instance/cull one high-count category |\n| GPU memory grows by location | resource snapshot and streaming residency | identify largest new owners and correct residency/LOD |\n| low tier changes nothing | device profile/group not applied or restart needed | display active CVars/profile and verify packaged build |\n| dynamic resolution bottoms out | sustained GPU cost exceeds minimum-resolution budget or CPU bound | inspect GPU at minimum percentage; optimize dominant pass |\n\nFor every recipe, restore the toggle, implement the production-quality change through owned settings,\nand capture the same worst case again.\n","searchText":"symptom recipes | symptom | prove first | first bounded experiment | |---|---|---| | slow only at high resolution | pixel-scaled gpu passes | lower screen percentage; compare pass deltas | | slow in dense city/forest | render thread, nanite/material/vsm/visibility | isolate primitive/section, overdraw, caster invalidation | | shadow spike while foliage moves | vsm uncached pages/casters | disable distant wpo/shadows on one foliage class | | camera cuts hitch | visibility/vsm/streaming/upscaler history | marked trace plus cache/streaming views | | many lights stay fast but noisy | megalights sample competition | reduce competing radii/lights or raise samples in controlled a/b | | reflections dominate | lumen reflection pass | compare reflection scalability separately from gi | | translucent combat effect tanks gpu | translucency/overdraw event | cut overlap/coverage for one effect | | render thread slow, gpu has headroom | primitive/section/submission count | instance/cull one high-count category | | gpu memory grows by location | resource snapshot and streaming residency | identify largest new owners and correct residency/lod | | low tier changes nothing | device profile/group not applied or restart needed | display active cvars/profile and verify packaged build | | dynamic resolution bottoms out | sustained gpu cost exceeds minimum-resolution budget or cpu bound | inspect gpu at minimum percentage; optimize dominant pass | for every recipe, restore the toggle, implement the production-quality change through owned settings, and capture the same worst case again."},{"slug":"virtual-shadow-maps","file":"virtual-shadow-maps.md","title":"Virtual Shadow Maps","rawMarkdown":"# Virtual Shadow Maps\n\nVSMs are designed to pair with Nanite and large dynamically lit worlds. If the target does not use\nNanite, validate whether conventional shadow maps are a better fit.\n\n## Diagnose the two cost buckets\n\n- **Shadow Depths**: rendering/updating caster depth pages.\n- **Shadow Projection** under Lights: sampling/projecting shadows into the frame.\n\nUse View Modes -> Virtual Shadow Map:\n\n- Cached Page: green cached, red uncached, blue static-only cached;\n- Shadow Casters: locate invalidators;\n- Nanite Overdraw: locate costly caster coverage;\n- Virtual Page/Clipmap-Mip: inspect page demand/resolution.\n\nDisable visualization before timing. For counters, use `trace.enable counters,vsm`; CSV profiling can\nenable the VSM category.\n\n## Reduce invalidation\n\nLargest invalidators commonly include moving lights, moving/added/removed casters, component render-\nstate churn, WPO/PDO, skeletal deformation, large bounds, camera cuts, and rapid disocclusion.\n\nActions:\n\n- stop needless light/primitive updates;\n- keep deforming bounds tight;\n- remove WPO/PDO or shadow casting at distance when visually safe;\n- use material/mesh LODs that disable deformation in the distance;\n- use Contact or Distance Field shadows where the content/target supports the trade;\n- use `Shadow Cache Invalidation Behavior` overrides only when the asserted rigidity/static state is\n  true; incorrect suppression produces undefined/stale shadows.\n\n`r.Shadow.Virtual.Cache 0` is a diagnostic to expose caching benefit, not a shipping optimization.\nResolution LOD bias trades shadow detail for pages/work. Moving-light biases exist because moving lights\ncannot reuse cache like stationary ones.\n\nWhen profiling individual VSM passes, `r.RDG.AsyncCompute 0` can make timings more representative;\nnever ship that profiling-only override.\n","webMarkdown":"VSMs are designed to pair with Nanite and large dynamically lit worlds. If the target does not use\nNanite, validate whether conventional shadow maps are a better fit.\n\n## Diagnose the two cost buckets\n\n- **Shadow Depths**: rendering/updating caster depth pages.\n- **Shadow Projection** under Lights: sampling/projecting shadows into the frame.\n\nUse View Modes -> Virtual Shadow Map:\n\n- Cached Page: green cached, red uncached, blue static-only cached;\n- Shadow Casters: locate invalidators;\n- Nanite Overdraw: locate costly caster coverage;\n- Virtual Page/Clipmap-Mip: inspect page demand/resolution.\n\nDisable visualization before timing. For counters, use `trace.enable counters,vsm`; CSV profiling can\nenable the VSM category.\n\n## Reduce invalidation\n\nLargest invalidators commonly include moving lights, moving/added/removed casters, component render-\nstate churn, WPO/PDO, skeletal deformation, large bounds, camera cuts, and rapid disocclusion.\n\nActions:\n\n- stop needless light/primitive updates;\n- keep deforming bounds tight;\n- remove WPO/PDO or shadow casting at distance when visually safe;\n- use material/mesh LODs that disable deformation in the distance;\n- use Contact or Distance Field shadows where the content/target supports the trade;\n- use `Shadow Cache Invalidation Behavior` overrides only when the asserted rigidity/static state is\n  true; incorrect suppression produces undefined/stale shadows.\n\n`r.Shadow.Virtual.Cache 0` is a diagnostic to expose caching benefit, not a shipping optimization.\nResolution LOD bias trades shadow detail for pages/work. Moving-light biases exist because moving lights\ncannot reuse cache like stationary ones.\n\nWhen profiling individual VSM passes, `r.RDG.AsyncCompute 0` can make timings more representative;\nnever ship that profiling-only override.\n","searchText":"virtual shadow maps vsms are designed to pair with nanite and large dynamically lit worlds. if the target does not use nanite, validate whether conventional shadow maps are a better fit. diagnose the two cost buckets - shadow depths: rendering/updating caster depth pages. - shadow projection under lights: sampling/projecting shadows into the frame. use view modes -> virtual shadow map: - cached page: green cached, red uncached, blue static-only cached; - shadow casters: locate invalidators; - nanite overdraw: locate costly caster coverage; - virtual page/clipmap-mip: inspect page demand/resolution. disable visualization before timing. for counters, use trace.enable counters,vsm; csv profiling can enable the vsm category. reduce invalidation largest invalidators commonly include moving lights, moving/added/removed casters, component render- state churn, wpo/pdo, skeletal deformation, large bounds, camera cuts, and rapid disocclusion. actions: - stop needless light/primitive updates; - keep deforming bounds tight; - remove wpo/pdo or shadow casting at distance when visually safe; - use material/mesh lods that disable deformation in the distance; - use contact or distance field shadows where the content/target supports the trade; - use shadow cache invalidation behavior overrides only when the asserted rigidity/static state is true; incorrect suppression produces undefined/stale shadows. r.shadow.virtual.cache 0 is a diagnostic to expose caching benefit, not a shipping optimization. resolution lod bias trades shadow detail for pages/work. moving-light biases exist because moving lights cannot reuse cache like stationary ones. when profiling individual vsm passes, r.rdg.asynccompute 0 can make timings more representative; never ship that profiling-only override."}]}
{"slug":"unreal-replication","name":"unreal-replication","title":"Unreal 5.8 Replication","description":"Design, implement, optimize, test, and debug server-authoritative multiplayer replication in Unreal Engine 5.8. Use for authority, roles, ownership, owning connections, replicated actors/components/properties, RepNotify, RPCs, relevancy, priority, dormancy, conditions, Fast Arrays, replicated UObjects/subobjects, Generic Replication, Replication Graph, Iris, bandwidth, ordering, prediction boundaries, Network Insights, packet emulation, or multiplayer UI state.","shortDescription":"Design and debug authoritative network state","category":"Systems & Networking","referenceCount":9,"rawMarkdown":"---\nname: unreal-replication\ndescription: Design, implement, optimize, test, and debug server-authoritative multiplayer replication in Unreal Engine 5.8. Use for authority, roles, ownership, owning connections, replicated actors/components/properties, RepNotify, RPCs, relevancy, priority, dormancy, conditions, Fast Arrays, replicated UObjects/subobjects, Generic Replication, Replication Graph, Iris, bandwidth, ordering, prediction boundaries, Network Insights, packet emulation, or multiplayer UI state.\n---\n\n# Unreal 5.8 Replication\n\n## Ownership boundary\n\nThis skill owns general Actor/property/RPC authority, ownership, relevancy, dormancy, and state\ntransport. Prediction remains subsystem-owned: route Character saved moves/root motion to\n[`unreal-character-movement`](../unreal-character-movement/SKILL.md), network physics/ragdolls to\n[`unreal-chaos-physics`](../unreal-chaos-physics/SKILL.md), and ability prediction to\n[`unreal-gas-abilities`](../unreal-gas-abilities/SKILL.md).\n\n## Select the replication system\n\n- Start with **Generic Replication**, UE 5.8's default, unless measured scale requires another\n  system.\n- Evaluate **Replication Graph** for many replicated actors and connections. It is Beta and does\n  not currently support split screen on console builds.\n- Evaluate **Iris** for its filtering/prioritization/scalability architecture only with an\n  explicit migration and compatibility plan. UE 5.8 still marks Iris Experimental and Generic\n  Replication remains the default.\n- Do not combine selection with gameplay prediction. Replication moves authoritative state;\n  prediction is subsystem-specific behavior.\n\nRead [`references/system-selector.md`](references/system-selector.md) before choosing.\n\n## Design the network contract first\n\nFor every multiplayer action, state:\n\n1. Which server object owns the canonical state?\n2. Which client owns the connection allowed to request it?\n3. What untrusted intent does the client submit?\n4. What does the server validate and execute?\n5. Which state persists for late join/relevancy and therefore uses properties?\n6. Which transient occurrence uses an RPC or local reaction?\n7. Which connections need the result, at what frequency and precision?\n8. What may be predicted locally, and how is it reconciled?\n\nRead [`references/authority-ownership.md`](references/authority-ownership.md).\n\n## Choose state versus event\n\n- Use replicated properties/RepNotify for durable state and late-joining/re-entering clients.\n- Use Server RPCs for client intent on an actor/component owned by that client's connection.\n- Use Client RPCs for targeted transient messages to the owning client.\n- Use NetMulticast sparingly for transient effects visible to currently relevant clients.\n- If every occurrence matters, do not encode it as repeated writes to one replicated scalar.\n- Keep related values that require coherent handling in one replicated struct; OnRep order across\n  separate properties is not deterministic.\n\nUse [`references/properties-repnotify.md`](references/properties-repnotify.md) and\n[`references/rpcs-ordering.md`](references/rpcs-ordering.md).\n\n## Implement in dependency order\n\n1. Set actor/component replication and server-only spawn/destruction.\n2. Establish owner and owning connection; do not confuse ownership with authority.\n3. Define replicated state, conditions, RepNotify handlers, and state invariants.\n4. Define minimal client-intent Server RPCs with server validation/rate limits.\n5. Add relevancy, priority, update frequency, and dormancy only from real requirements.\n6. Use registered replicated subobjects and Fast Arrays for the relevant data shape.\n7. Reuse CMC, GAS, or another subsystem's prediction rather than inventing generic prediction.\n8. Test dedicated server and remote clients under lag, loss, jitter, reordering, reconnect, and\n   relevancy transitions.\n9. Capture Network Insights before optimizing bandwidth or selecting a scalable driver.\n\n## Required answer format\n\nReturn:\n\n1. **Authority/ownership table** per actor and action.\n2. **Network contract**: client intent, server validation, canonical mutation, client result.\n3. **Property/RPC/condition choice** with exact C++/Blueprint actions.\n4. **Relevancy, dormancy, frequency, and scale strategy**.\n5. **Prediction/reconciliation owner**, if any.\n6. **Network test matrix and trace-based performance check**.\n\nDo not invent ownership, delivery/order guarantees, maturity status, or bandwidth savings.\n\n## Hard rules\n\n- The server owns gameplay truth; client parameters are requests, never proof.\n- `HasAuthority`/network role is not the owning connection.\n- A client can call a Server RPC only through an actor/component it owns through its connection.\n- Spawn and destroy replicated gameplay actors on the server.\n- Never use reliable RPCs for high-frequency input/tick traffic.\n- A client-called NetMulticast executes only on that invoking client.\n- Do not rely on ordering across actors or between separate RepNotifies.\n- Wake/flush a dormant actor **before** mutating replicated state.\n- Replicate gameplay state, not widgets; local UI observes replicated models.\n- Do not manually replicate Character transforms instead of CMC network movement.\n- Profile before adopting Replication Graph, Iris, custom relevancy, or custom priority.\n\nRead [`references/relevancy-dormancy.md`](references/relevancy-dormancy.md),\n[`references/components-subobjects-fastarrays.md`](references/components-subobjects-fastarrays.md),\n[`references/patterns.md`](references/patterns.md), and\n[`references/debugging-testing.md`](references/debugging-testing.md). See\n[`references/sources.md`](references/sources.md) for the UE 5.8 source trail.\n","webMarkdown":"## Ownership boundary\n\nThis skill owns general Actor/property/RPC authority, ownership, relevancy, dormancy, and state\ntransport. Prediction remains subsystem-owned: route Character saved moves/root motion to\n[`unreal-character-movement`](/unreal/unreal-character-movement/), network physics/ragdolls to\n[`unreal-chaos-physics`](/unreal/unreal-chaos-physics/), and ability prediction to\n[`unreal-gas-abilities`](/unreal/unreal-gas-abilities/).\n\n## Select the replication system\n\n- Start with **Generic Replication**, UE 5.8's default, unless measured scale requires another\n  system.\n- Evaluate **Replication Graph** for many replicated actors and connections. It is Beta and does\n  not currently support split screen on console builds.\n- Evaluate **Iris** for its filtering/prioritization/scalability architecture only with an\n  explicit migration and compatibility plan. UE 5.8 still marks Iris Experimental and Generic\n  Replication remains the default.\n- Do not combine selection with gameplay prediction. Replication moves authoritative state;\n  prediction is subsystem-specific behavior.\n\nRead [`references/system-selector.md`](/unreal/unreal-replication/system-selector/) before choosing.\n\n## Design the network contract first\n\nFor every multiplayer action, state:\n\n1. Which server object owns the canonical state?\n2. Which client owns the connection allowed to request it?\n3. What untrusted intent does the client submit?\n4. What does the server validate and execute?\n5. Which state persists for late join/relevancy and therefore uses properties?\n6. Which transient occurrence uses an RPC or local reaction?\n7. Which connections need the result, at what frequency and precision?\n8. What may be predicted locally, and how is it reconciled?\n\nRead [`references/authority-ownership.md`](/unreal/unreal-replication/authority-ownership/).\n\n## Choose state versus event\n\n- Use replicated properties/RepNotify for durable state and late-joining/re-entering clients.\n- Use Server RPCs for client intent on an actor/component owned by that client's connection.\n- Use Client RPCs for targeted transient messages to the owning client.\n- Use NetMulticast sparingly for transient effects visible to currently relevant clients.\n- If every occurrence matters, do not encode it as repeated writes to one replicated scalar.\n- Keep related values that require coherent handling in one replicated struct; OnRep order across\n  separate properties is not deterministic.\n\nUse [`references/properties-repnotify.md`](/unreal/unreal-replication/properties-repnotify/) and\n[`references/rpcs-ordering.md`](/unreal/unreal-replication/rpcs-ordering/).\n\n## Implement in dependency order\n\n1. Set actor/component replication and server-only spawn/destruction.\n2. Establish owner and owning connection; do not confuse ownership with authority.\n3. Define replicated state, conditions, RepNotify handlers, and state invariants.\n4. Define minimal client-intent Server RPCs with server validation/rate limits.\n5. Add relevancy, priority, update frequency, and dormancy only from real requirements.\n6. Use registered replicated subobjects and Fast Arrays for the relevant data shape.\n7. Reuse CMC, GAS, or another subsystem's prediction rather than inventing generic prediction.\n8. Test dedicated server and remote clients under lag, loss, jitter, reordering, reconnect, and\n   relevancy transitions.\n9. Capture Network Insights before optimizing bandwidth or selecting a scalable driver.\n\n## Required answer format\n\nReturn:\n\n1. **Authority/ownership table** per actor and action.\n2. **Network contract**: client intent, server validation, canonical mutation, client result.\n3. **Property/RPC/condition choice** with exact C++/Blueprint actions.\n4. **Relevancy, dormancy, frequency, and scale strategy**.\n5. **Prediction/reconciliation owner**, if any.\n6. **Network test matrix and trace-based performance check**.\n\nDo not invent ownership, delivery/order guarantees, maturity status, or bandwidth savings.\n\n## Hard rules\n\n- The server owns gameplay truth; client parameters are requests, never proof.\n- `HasAuthority`/network role is not the owning connection.\n- A client can call a Server RPC only through an actor/component it owns through its connection.\n- Spawn and destroy replicated gameplay actors on the server.\n- Never use reliable RPCs for high-frequency input/tick traffic.\n- A client-called NetMulticast executes only on that invoking client.\n- Do not rely on ordering across actors or between separate RepNotifies.\n- Wake/flush a dormant actor **before** mutating replicated state.\n- Replicate gameplay state, not widgets; local UI observes replicated models.\n- Do not manually replicate Character transforms instead of CMC network movement.\n- Profile before adopting Replication Graph, Iris, custom relevancy, or custom priority.\n\nRead [`references/relevancy-dormancy.md`](/unreal/unreal-replication/relevancy-dormancy/),\n[`references/components-subobjects-fastarrays.md`](/unreal/unreal-replication/components-subobjects-fastarrays/),\n[`references/patterns.md`](/unreal/unreal-replication/patterns/), and\n[`references/debugging-testing.md`](/unreal/unreal-replication/debugging-testing/). See\n[`references/sources.md`](/unreal/unreal-replication/sources/) for the UE 5.8 source trail.\n","searchText":"unreal 5.8 replication design, implement, optimize, test, and debug server-authoritative multiplayer replication in unreal engine 5.8. use for authority, roles, ownership, owning connections, replicated actors/components/properties, repnotify, rpcs, relevancy, priority, dormancy, conditions, fast arrays, replicated uobjects/subobjects, generic replication, replication graph, iris, bandwidth, ordering, prediction boundaries, network insights, packet emulation, or multiplayer ui state. authority, role, and owning connection authority, role, and owning connection keep the concepts separate | concept | answers | |---|---| | authority / local role | which machine owns this actor's canonical replicated copy? | | owner | which actor is this actor's ue owner? | | owning connection | which client connection is reached through the owner chain to a playercontroller? | | local control | is this pawn/controller controlled by a local player on this machine? | | relevancy | should this connection currently receive this actor? | network role is not ownership. a server has authority over replicated gameplay actors, while a client may own a connection to its playercontroller/pawn and therefore be permitted to call server rpcs through that chain. client request path text local input/ui -> locally owned playercontroller, pawn, or owned replicated component -> server rpc carrying minimal intent -> server validates current canonical state, range, permissions, rate, and target -> server mutates canonical state -> properties/rpcs replicate the result do not put server rpcs on arbitrary world actors and expect clients to call them. route the request through an owned actor, then have server code interact with the target. validation checklist validate on the server: - requesting connection may perform the action; - actor and target still exist and are relevant to the rule; - distance, line of sight, cooldown, resources, and state preconditions; - numeric values are bounded and derived server-side where possible; - request rate/sequence is acceptable; - the request cannot select objects hidden from that player; - repeated or reordered requests are safe/idempotent where needed. withvalidation is an available c++ rpc mechanism, but server gameplay logic must still enforce rules regardless of where validation is written. spawn and destruction - spawn replicated gameplay actors on the server. - destroy them on the server. - a client-spawned actor is local to that client unless it participates through another authoritative mechanism; setting replicates on the client copy does not create the server copy. - cosmetic local actors are allowed when they have no gameplay authority. ui boundary widgets are not replicated actors and should not own rpcs. a widget emits intent to its owning local controller/pawn/component. it observes replicated state through a presenter/viewmodel. components, subobjects, and fast arrays components, subobjects, and fast arrays replicated actorcomponents both must be true: - owning actor replicates; - actorcomponent replicates (setisreplicatedbydefault(true) in the component constructor for a default behavior, or the appropriate instance setup). components can replicate properties, rpcs, and their own subobjects. component rpcs add more overhead than actor rpcs; route high-volume calls through the actor when appropriate. replicated uobjects/subobjects use a uobject subobject when state belongs to an actor/component but needs its own identity and replicated properties without becoming a world actor. preferred forward-compatible procedure: 1. make the outer/owner a replicated actor or replicated actorcomponent. 2. enable breplicateusingregisteredsubobjectlist on that owner. 3. create the subobject on the server with a stable ownership relationship. 4. register it with addreplicatedsubobject and an optional condition. 5. remove/unregister it before deletion when required by the lifetime path. 6. wake/flush the owning actor before changing a dormant subobject. the registered subobject list works with generic replication and repgraph and is the only supported subobject method for iris. do not enable iris while relying only on legacy replicatesubobjects overrides. fast arrays use ffastarrayserializer for replicated collections with item-level additions, removals, and changes where a normal whole-array representation is too costly or lacks item callbacks. implementation contract: - item struct derives from ffastarrayserializeritem; - container struct derives from ffastarrayserializer and owns the item array; - provide the required delta serialization trait/function for the chosen pattern; - call markitemdirty after an item changes; - call markarraydirty for structural changes when required by the operation; - handle add/change/remove callbacks as received-state reactions; - use stable item identity and do not retain pointers to entries that may move. verify exact signatures against fastarrayserializer.h for the engine build; do not invent them from memory. iris has a native fast array path, but iris itself remains experimental. selection | data | representation | |---|---| | a few scalar states | actor/component replicated properties | | cohesive values needing ordered handling | one replicated struct | | large changing item collection | fast array | | modular owned state object | registered replicated uobject subobject | | independent world relevance/transform | replicated actor | debugging, testing, and profiling debugging, testing, and profiling minimum topology matrix test each feature in: - dedicated server + two remote clients; - listen server + remote client; - late join after state changed; - leave and re-enter relevancy; - disconnect/reconnect or respawn where supported; - two local players if split screen is supported. do not accept a listen-server-only pass; the host combines authority and local control and can hide ownership defects. adverse network matrix use ue network emulation, then turn it off after each test: - latency (netemulation.pktlag or a named emulation profile); - packet loss (netemulation.pktloss); - jitter/lag variance; - packet duplication; - packet reordering, when compatible with the chosen lag settings. verify input responsiveness, correction, reliable-queue health, stale-state rejection, and eventual authoritative convergence. network insights launch instances with networking trace enabled, for example: text -trace=net -nettrace=1 for editor capture, add -tracehost=localhost when needed. inspect: - packet overview for timing and size; - packet content for actors, properties, and rpcs; - net stats for inclusive/exclusive byte cost; - connection direction and selected connection; - spikes during spawn, relevance changes, or ui-driven action spam. useful commands - net.actorreport: active replicated actor information. - net.dumprelevantactors: actors relevant on the next update. - net.listactorchannels: open actor channels. - net.forceonepacketperbunch: stress ordering assumptions. - net.dormancyenable 0/1: isolate dormancy-related failures. - showdebug enhancedinput: inspect input before blaming rpcs. confirm command availability/side effects in the 5.8 console-command reference before adding to automation or shipping tooling. failure tree | symptom | first checks | |---|---| | server rpc never runs | caller owns actor, actor/component replicates, call made on client copy | | property only updates for owner | replication condition and actor relevancy/ownership | | works until actor sleeps | wake/flush before mutation, including component/subobject | | remote client misses effect | actor relevance at multicast time; should it be durable state? | | duplicate/late effect | repnotify treated as a new event instead of current state | | character rubber-bands | server/client movement divergence; use cmc trace/saved moves | | bandwidth spike | high-frequency rpc/property, always-relevant actors, large collections | | only host works | local-control/authority branch conflated or wrong owner | shipping gate - server remains correct with malicious/out-of-range/repeated client requests. - all durable state reconstructs for late and re-relevant clients. - reliable rpc rate is bounded under worst input spam. - ordering assumptions survive forced packet/bunch stress. - network insights meets server cpu and per-connection bandwidth budgets at target scale. - experimental/beta system risks and rollback are documented. replication patterns replication patterns networked door 1. server owns bisopen (repnotify) and interaction rules. 2. client sends servertryinteract(door) through its owned pawn/controller. 3. server validates range, line of sight, permissions, and current state. 4. wake the dormant door before mutation. 5. repnotify sets door presentation from current state. 6. return the door to dormancy after it settles. do not multicast the only open event; a late-relevant client needs durable state. health and ui 1. server applies damage and owns health. 2. health replicates/uses gas attribute replication. 3. repnotify/attribute delegate updates a local presentation model. 4. local hud pushes the display change. 5. death state is authoritative; cosmetic hit/death cues may be transient. route gas details to $unreal-gas-attributes-effects and ui details to $unreal-umg-commonui. inventory - server owns the collection and validates add/remove/equip/drop. - client submits item identity and requested verb, never a new inventory total. - use a fast array when item-level delta replication and callbacks justify it. - use owner-only conditions for private inventory; replicate public equipped presentation separately when other clients need it. - ui selection is local and keyed by stable item identity. projectile selector - important persistent/colliding projectile: server-spawned replicated actor with an appropriate movement/prediction model. - high-volume cosmetic tracer: local cosmetic driven from an authoritative hit/result event. - never accept a client claim that a hit occurred without server validation or the game's deliberate lag-compensation model. character movement use acharacter + ucharactermovementcomponent network prediction/correction for standard characters. do not send per-tick transform rpcs or use client setactorlocation as prediction. route custom movement serialization to $unreal-character-movement. match state placement - gamemode: server-only rules and authority. - gamestate: replicated match-wide state clients need. - playerstate: replicated player state that should outlive pawn possession and be visible as designed. - playercontroller: owner-only control/request channel; each client gets its own controller. - pawn/character: current possessed avatar and movement/gameplay state. choose placement from lifetime, visibility, and ownership—not convenience. replicated properties and repnotify replicated properties and repnotify use properties for state choose a replicated property when a client becoming relevant later must learn the current truth: - health, score, inventory contents, team, door open/closed state; - match phase and timestamps; - equipped item or persistent ability state. on the server, mutate the canonical property. clients apply received values; client edits to a replica are not authoritative and may be overwritten. c++ setup 1. set the actor to replicate. 2. mark the property uproperty(replicated) or uproperty(replicatedusing=onrepname). 3. override getlifetimereplicatedprops and call super. 4. register with doreplifetime, a condition macro, or lifetime params. 5. put client-side reaction in the repnotify; it may accept the previous value. use blueprint replicated/repnotify settings for blueprint actors, but keep the same ownership and state rules. repnotify design - treat repnotify as \"received/applied current replicated state,\" not proof that the event just happened in the viewer's timeline. - make presentation reactions idempotent. - if server and clients require the same reaction, put it in a shared non-rpc function and call it from the authoritative mutation path and repnotify as appropriate. do not assume all c++ and blueprint repnotify server behaviors are identical. - use the previous-value parameter when transition logic needs old versus new. - put values requiring coherent ordering in one replicated struct. epic states there is no deterministic order between onreps for separate variables. conditions use the narrowest correct built-in condition: - condowneronly: private owner state; - condskipowner: remote-only correction/presentation when owner predicts; - condinitialonly: immutable setup state after initial replication; - condsimulatedonly / condautonomousonly: role-specific state; - conddynamic or custom active override only when simpler static conditions cannot express it. conditions are per registered property layout; avoid per-instance assumptions in lifetime setup. state versus occurrence repeated writes can collapse to the latest received state. if every occurrence matters, use an appropriate event/rpc, counter/sequence, or replicated collection—not a bool toggled too quickly. for a chest, replicate bisopen for durable state; emit/derive the opening effect only when its timing is still meaningful. ui hookup repnotify or a gameplay delegate updates a local presenter/viewmodel, which pushes into widgets. never bind ui to poll replicated properties every frame. relevancy, priority, frequency, and dormancy relevancy, priority, frequency, and dormancy relevancy relevancy is per connection: should this actor affect this viewer now? use built-in settings before overriding isnetrelevantfor: - balwaysrelevant for genuinely global actors only; - bonlyrelevanttoowner for private actors such as a playercontroller; - bnetuseownerrelevancy for actors that should follow their owner; - netculldistancesquared for distance-based relevance where enabled. dynamically spawned replicated actors can be destroyed on a client when they become irrelevant and recreated when relevant again. durable state must survive that transition through replication, not a one-shot multicast. update frequency and priority - netupdatefrequency determines how often an actor is considered for updates in generic replication. - priority decides which actors replicate first when a connection saturates; elapsed time since last update contributes, preventing simple starvation. - do not set every actor always relevant or high frequency. - change frequency/priority only from measured responsiveness and bandwidth evidence. dormancy use dormancy for actors that replicate state but remain unchanged for long periods. epic calls it one of the most impactful server replication optimizations. procedure: 1. map-placed initially static actor: start with dorminitial when appropriate. 2. runtime/static actor: use dormdormantall when all connections can sleep it. 3. before changing replicated actor/component/subobject state, call flushnetdormancy, forcenetupdate, or set dormawake as the update pattern requires. 4. for continuous changes, wake with setnetdormancy(dormawake) and return to dormdormantall after state settles. 5. do not return a once-awakened map actor to dorminitial. blueprint actor replicated-property writes may flush automatically, but replicated actorcomponent blueprint properties do not have the same guarantee. keep the explicit wake-before-mutate rule. diagnostic sequence if a property updates only sometimes: 1. confirm mutation occurs on the server. 2. confirm the actor/component/property replicates. 3. confirm the connection owns/is relevant as required. 4. check dormancy and wake order. 5. check condition and update frequency. 6. inspect the packet/property in network insights. use lognetdormancy, net.dumprelevantactors, and net.actorreport for targeted evidence. rpcs, reliability, and ordering rpcs, reliability, and ordering rpc selector | need | mechanism | |---|---| | client requests authoritative action | server rpc on client-owned actor/component | | server targets one owning client | client rpc | | server sends transient effect to currently relevant clients | netmulticast, sparingly | | durable state for late relevance/join | replicated property, not rpc | | local-only presentation | local function/event | rpcs are unidirectional and do not return values. return outcomes through replicated state or a separate targeted response. execution truths - a client server rpc runs remotely only when invoked through that client's owning connection; otherwise it is dropped. - a server client rpc targets the actor's owning client. - a server netmulticast runs on the server and clients for which the actor is currently relevant. - a client-called netmulticast runs only on the invoking client. - rpcs require a replicated actor/component and valid ownership conditions. reliable versus unreliable use reliable only when loss would break a low-frequency essential transition and the call rate is strictly bounded. reliable rpcs consume an ordered reliable queue; input spam can overflow it. use unreliable for frequent, replaceable, or cosmetic occurrences. design behavior that remains correct when unreliable calls are dropped. never send reliable rpcs from tick or directly from unbounded button repeat. prefer replicated state when the current result matters more than each call. ordering rules - do not rely on rpc call order across different actors. - reliable rpc ordering guarantees are scoped; do not infer a global event timeline. - multicast versus unicast ordering is not universally preserved. - separate repnotify callback order is nondeterministic. - if values must be interpreted atomically/coherently, group them in one struct or add an explicit sequence/state-machine contract. design receivers to be idempotent, tolerate missing obsolete events, and reject stale sequence numbers when correctness requires it. request payload rule send minimum intent, for example tryinteract(target) or tryequip(itemid). do not send trusted results such as new balance, damage dealt, final position, or permission flags. the server derives and validates results from canonical state. ue 5.8 primary sources ue 5.8 primary sources all links were checked against epic's ue 5.8 documentation on 2026-07-19. fundamentals - networking overview - actor owner and owning connection - actor role and remote role - replicate actor properties - remote procedure calls - replicated object execution order filtering and performance - actor relevancy - actor priority - actor network dormancy - detailed actor replication flow - replication graph components, subobjects, and scale systems - replicating actor components - replicating uobjects - ffastarrayserializer - introduction to iris - migrate to iris testing and subsystem boundaries - testing, debugging, and optimization - networking insights - console commands for network debugging - networked character movement ue 5.8 maturity notes - generic replication is the default. - replication graph is marked beta. - iris is compiled in but remains experimental and is not the default. - the registered subobject list is the only subobject method compatible with iris. replication-system selector replication-system selector generic replication use by default. it supports replicated actors, properties, rpcs, relevancy, priority, update frequency, dormancy, components, and subobjects. most ue networking documentation assumes it. remain on generic replication when actor/connection counts fit the server budget and its model meets the game's filtering needs. tune content and dormancy before replacing the driver. replication graph evaluate when the server must repeatedly build per-connection replication lists for large actor and connection counts. repgraph keeps persistent graph nodes/lists that share work across frames and connections. adoption gate: - a network insights/server trace shows replication-list gathering or per-connection actor evaluation is a material bottleneck; - actor categories have clear spatial, always-relevant, owner-only, team, or dormancy rules; - the team can implement and test custom graph nodes; - the project accepts beta maturity; - console split screen is not required, because epic documents that limitation. iris iris is compiled into ue but is not the default replication system. ue 5.8 marks it experimental. it changes relevancy into filtering and priority into iris prioritization, shares quantized replicated state work, and aims for stronger scalability/concurrency. adoption gate: - a specific iris capability or measured scale need justifies experimental risk; - all plugins/subsystems and custom serializers are compatibility-tested; - replicated subobjects use the registered subobject list; - migration differences are documented and both network correctness and performance are tested; - rollback to generic replication is planned until the shipping gate is passed. do not select iris because it is newer. do not assume generic settings map unchanged: consult the 5.8 migration guide. selection output return: | candidate | measured need | maturity/constraint | decision | |---|---|---|---| | generic | baseline | default/stable path | use/reject | | repgraph | large actor x connection filtering cost | beta; console split-screen limitation | use/reject | | iris | specific filtering/prioritization/scalability need | experimental; migration work | use/reject | no selection is complete without a representative server trace and target-player-count test.","references":[{"slug":"authority-ownership","file":"authority-ownership.md","title":"Authority, role, and owning connection","rawMarkdown":"# Authority, role, and owning connection\n\n## Keep the concepts separate\n\n| Concept | Answers |\n|---|---|\n| Authority / local role | Which machine owns this actor's canonical replicated copy? |\n| Owner | Which Actor is this actor's UE owner? |\n| Owning connection | Which client connection is reached through the owner chain to a PlayerController? |\n| Local control | Is this Pawn/Controller controlled by a local player on this machine? |\n| Relevancy | Should this connection currently receive this actor? |\n\nNetwork role is not ownership. A server has authority over replicated gameplay actors, while a\nclient may own a connection to its PlayerController/Pawn and therefore be permitted to call\nServer RPCs through that chain.\n\n## Client request path\n\n```text\nlocal input/UI\n  -> locally owned PlayerController, Pawn, or owned replicated component\n  -> Server RPC carrying minimal intent\n  -> server validates current canonical state, range, permissions, rate, and target\n  -> server mutates canonical state\n  -> properties/RPCs replicate the result\n```\n\nDo not put Server RPCs on arbitrary world actors and expect clients to call them. Route the\nrequest through an owned actor, then have server code interact with the target.\n\n## Validation checklist\n\nValidate on the server:\n\n- requesting connection may perform the action;\n- actor and target still exist and are relevant to the rule;\n- distance, line of sight, cooldown, resources, and state preconditions;\n- numeric values are bounded and derived server-side where possible;\n- request rate/sequence is acceptable;\n- the request cannot select objects hidden from that player;\n- repeated or reordered requests are safe/idempotent where needed.\n\n`WithValidation` is an available C++ RPC mechanism, but server gameplay logic must still enforce\nrules regardless of where validation is written.\n\n## Spawn and destruction\n\n- Spawn replicated gameplay actors on the server.\n- Destroy them on the server.\n- A client-spawned actor is local to that client unless it participates through another\n  authoritative mechanism; setting Replicates on the client copy does not create the server copy.\n- Cosmetic local actors are allowed when they have no gameplay authority.\n\n## UI boundary\n\nWidgets are not replicated actors and should not own RPCs. A widget emits intent to its owning\nlocal controller/pawn/component. It observes replicated state through a presenter/Viewmodel.\n","webMarkdown":"## Keep the concepts separate\n\n| Concept | Answers |\n|---|---|\n| Authority / local role | Which machine owns this actor's canonical replicated copy? |\n| Owner | Which Actor is this actor's UE owner? |\n| Owning connection | Which client connection is reached through the owner chain to a PlayerController? |\n| Local control | Is this Pawn/Controller controlled by a local player on this machine? |\n| Relevancy | Should this connection currently receive this actor? |\n\nNetwork role is not ownership. A server has authority over replicated gameplay actors, while a\nclient may own a connection to its PlayerController/Pawn and therefore be permitted to call\nServer RPCs through that chain.\n\n## Client request path\n\n```text\nlocal input/UI\n  -> locally owned PlayerController, Pawn, or owned replicated component\n  -> Server RPC carrying minimal intent\n  -> server validates current canonical state, range, permissions, rate, and target\n  -> server mutates canonical state\n  -> properties/RPCs replicate the result\n```\n\nDo not put Server RPCs on arbitrary world actors and expect clients to call them. Route the\nrequest through an owned actor, then have server code interact with the target.\n\n## Validation checklist\n\nValidate on the server:\n\n- requesting connection may perform the action;\n- actor and target still exist and are relevant to the rule;\n- distance, line of sight, cooldown, resources, and state preconditions;\n- numeric values are bounded and derived server-side where possible;\n- request rate/sequence is acceptable;\n- the request cannot select objects hidden from that player;\n- repeated or reordered requests are safe/idempotent where needed.\n\n`WithValidation` is an available C++ RPC mechanism, but server gameplay logic must still enforce\nrules regardless of where validation is written.\n\n## Spawn and destruction\n\n- Spawn replicated gameplay actors on the server.\n- Destroy them on the server.\n- A client-spawned actor is local to that client unless it participates through another\n  authoritative mechanism; setting Replicates on the client copy does not create the server copy.\n- Cosmetic local actors are allowed when they have no gameplay authority.\n\n## UI boundary\n\nWidgets are not replicated actors and should not own RPCs. A widget emits intent to its owning\nlocal controller/pawn/component. It observes replicated state through a presenter/Viewmodel.\n","searchText":"authority, role, and owning connection keep the concepts separate | concept | answers | |---|---| | authority / local role | which machine owns this actor's canonical replicated copy? | | owner | which actor is this actor's ue owner? | | owning connection | which client connection is reached through the owner chain to a playercontroller? | | local control | is this pawn/controller controlled by a local player on this machine? | | relevancy | should this connection currently receive this actor? | network role is not ownership. a server has authority over replicated gameplay actors, while a client may own a connection to its playercontroller/pawn and therefore be permitted to call server rpcs through that chain. client request path text local input/ui -> locally owned playercontroller, pawn, or owned replicated component -> server rpc carrying minimal intent -> server validates current canonical state, range, permissions, rate, and target -> server mutates canonical state -> properties/rpcs replicate the result do not put server rpcs on arbitrary world actors and expect clients to call them. route the request through an owned actor, then have server code interact with the target. validation checklist validate on the server: - requesting connection may perform the action; - actor and target still exist and are relevant to the rule; - distance, line of sight, cooldown, resources, and state preconditions; - numeric values are bounded and derived server-side where possible; - request rate/sequence is acceptable; - the request cannot select objects hidden from that player; - repeated or reordered requests are safe/idempotent where needed. withvalidation is an available c++ rpc mechanism, but server gameplay logic must still enforce rules regardless of where validation is written. spawn and destruction - spawn replicated gameplay actors on the server. - destroy them on the server. - a client-spawned actor is local to that client unless it participates through another authoritative mechanism; setting replicates on the client copy does not create the server copy. - cosmetic local actors are allowed when they have no gameplay authority. ui boundary widgets are not replicated actors and should not own rpcs. a widget emits intent to its owning local controller/pawn/component. it observes replicated state through a presenter/viewmodel."},{"slug":"components-subobjects-fastarrays","file":"components-subobjects-fastarrays.md","title":"Components, subobjects, and Fast Arrays","rawMarkdown":"# Components, subobjects, and Fast Arrays\n\n## Replicated ActorComponents\n\nBoth must be true:\n\n- owning Actor replicates;\n- ActorComponent replicates (`SetIsReplicatedByDefault(true)` in the component constructor for a\n  default behavior, or the appropriate instance setup).\n\nComponents can replicate properties, RPCs, and their own subobjects. Component RPCs add more\noverhead than Actor RPCs; route high-volume calls through the Actor when appropriate.\n\n## Replicated UObjects/subobjects\n\nUse a UObject subobject when state belongs to an Actor/component but needs its own identity and\nreplicated properties without becoming a world Actor.\n\nPreferred forward-compatible procedure:\n\n1. Make the outer/owner a replicated Actor or replicated ActorComponent.\n2. Enable `bReplicateUsingRegisteredSubObjectList` on that owner.\n3. Create the subobject on the server with a stable ownership relationship.\n4. Register it with `AddReplicatedSubObject` and an optional condition.\n5. Remove/unregister it before deletion when required by the lifetime path.\n6. Wake/flush the owning Actor before changing a dormant subobject.\n\nThe registered subobject list works with Generic Replication and RepGraph and is the only\nsupported subobject method for Iris. Do not enable Iris while relying only on legacy\n`ReplicateSubobjects` overrides.\n\n## Fast Arrays\n\nUse `FFastArraySerializer` for replicated collections with item-level additions, removals, and\nchanges where a normal whole-array representation is too costly or lacks item callbacks.\n\nImplementation contract:\n\n- item struct derives from `FFastArraySerializerItem`;\n- container struct derives from `FFastArraySerializer` and owns the item array;\n- provide the required delta serialization trait/function for the chosen pattern;\n- call `MarkItemDirty` after an item changes;\n- call `MarkArrayDirty` for structural changes when required by the operation;\n- handle add/change/remove callbacks as received-state reactions;\n- use stable item identity and do not retain pointers to entries that may move.\n\nVerify exact signatures against `FastArraySerializer.h` for the engine build; do not invent them\nfrom memory. Iris has a native Fast Array path, but Iris itself remains Experimental.\n\n## Selection\n\n| Data | Representation |\n|---|---|\n| A few scalar states | actor/component replicated properties |\n| Cohesive values needing ordered handling | one replicated struct |\n| Large changing item collection | Fast Array |\n| Modular owned state object | registered replicated UObject subobject |\n| Independent world relevance/transform | replicated Actor |\n","webMarkdown":"## Replicated ActorComponents\n\nBoth must be true:\n\n- owning Actor replicates;\n- ActorComponent replicates (`SetIsReplicatedByDefault(true)` in the component constructor for a\n  default behavior, or the appropriate instance setup).\n\nComponents can replicate properties, RPCs, and their own subobjects. Component RPCs add more\noverhead than Actor RPCs; route high-volume calls through the Actor when appropriate.\n\n## Replicated UObjects/subobjects\n\nUse a UObject subobject when state belongs to an Actor/component but needs its own identity and\nreplicated properties without becoming a world Actor.\n\nPreferred forward-compatible procedure:\n\n1. Make the outer/owner a replicated Actor or replicated ActorComponent.\n2. Enable `bReplicateUsingRegisteredSubObjectList` on that owner.\n3. Create the subobject on the server with a stable ownership relationship.\n4. Register it with `AddReplicatedSubObject` and an optional condition.\n5. Remove/unregister it before deletion when required by the lifetime path.\n6. Wake/flush the owning Actor before changing a dormant subobject.\n\nThe registered subobject list works with Generic Replication and RepGraph and is the only\nsupported subobject method for Iris. Do not enable Iris while relying only on legacy\n`ReplicateSubobjects` overrides.\n\n## Fast Arrays\n\nUse `FFastArraySerializer` for replicated collections with item-level additions, removals, and\nchanges where a normal whole-array representation is too costly or lacks item callbacks.\n\nImplementation contract:\n\n- item struct derives from `FFastArraySerializerItem`;\n- container struct derives from `FFastArraySerializer` and owns the item array;\n- provide the required delta serialization trait/function for the chosen pattern;\n- call `MarkItemDirty` after an item changes;\n- call `MarkArrayDirty` for structural changes when required by the operation;\n- handle add/change/remove callbacks as received-state reactions;\n- use stable item identity and do not retain pointers to entries that may move.\n\nVerify exact signatures against `FastArraySerializer.h` for the engine build; do not invent them\nfrom memory. Iris has a native Fast Array path, but Iris itself remains Experimental.\n\n## Selection\n\n| Data | Representation |\n|---|---|\n| A few scalar states | actor/component replicated properties |\n| Cohesive values needing ordered handling | one replicated struct |\n| Large changing item collection | Fast Array |\n| Modular owned state object | registered replicated UObject subobject |\n| Independent world relevance/transform | replicated Actor |\n","searchText":"components, subobjects, and fast arrays replicated actorcomponents both must be true: - owning actor replicates; - actorcomponent replicates (setisreplicatedbydefault(true) in the component constructor for a default behavior, or the appropriate instance setup). components can replicate properties, rpcs, and their own subobjects. component rpcs add more overhead than actor rpcs; route high-volume calls through the actor when appropriate. replicated uobjects/subobjects use a uobject subobject when state belongs to an actor/component but needs its own identity and replicated properties without becoming a world actor. preferred forward-compatible procedure: 1. make the outer/owner a replicated actor or replicated actorcomponent. 2. enable breplicateusingregisteredsubobjectlist on that owner. 3. create the subobject on the server with a stable ownership relationship. 4. register it with addreplicatedsubobject and an optional condition. 5. remove/unregister it before deletion when required by the lifetime path. 6. wake/flush the owning actor before changing a dormant subobject. the registered subobject list works with generic replication and repgraph and is the only supported subobject method for iris. do not enable iris while relying only on legacy replicatesubobjects overrides. fast arrays use ffastarrayserializer for replicated collections with item-level additions, removals, and changes where a normal whole-array representation is too costly or lacks item callbacks. implementation contract: - item struct derives from ffastarrayserializeritem; - container struct derives from ffastarrayserializer and owns the item array; - provide the required delta serialization trait/function for the chosen pattern; - call markitemdirty after an item changes; - call markarraydirty for structural changes when required by the operation; - handle add/change/remove callbacks as received-state reactions; - use stable item identity and do not retain pointers to entries that may move. verify exact signatures against fastarrayserializer.h for the engine build; do not invent them from memory. iris has a native fast array path, but iris itself remains experimental. selection | data | representation | |---|---| | a few scalar states | actor/component replicated properties | | cohesive values needing ordered handling | one replicated struct | | large changing item collection | fast array | | modular owned state object | registered replicated uobject subobject | | independent world relevance/transform | replicated actor |"},{"slug":"debugging-testing","file":"debugging-testing.md","title":"Debugging, testing, and profiling","rawMarkdown":"# Debugging, testing, and profiling\n\n## Minimum topology matrix\n\nTest each feature in:\n\n- dedicated server + two remote clients;\n- listen server + remote client;\n- late join after state changed;\n- leave and re-enter relevancy;\n- disconnect/reconnect or respawn where supported;\n- two local players if split screen is supported.\n\nDo not accept a listen-server-only pass; the host combines authority and local control and can\nhide ownership defects.\n\n## Adverse network matrix\n\nUse UE network emulation, then turn it off after each test:\n\n- latency (`NetEmulation.PktLag` or a named emulation profile);\n- packet loss (`NetEmulation.PktLoss`);\n- jitter/lag variance;\n- packet duplication;\n- packet reordering, when compatible with the chosen lag settings.\n\nVerify input responsiveness, correction, reliable-queue health, stale-state rejection, and\neventual authoritative convergence.\n\n## Network Insights\n\nLaunch instances with networking trace enabled, for example:\n\n```text\n-trace=net -NetTrace=1\n```\n\nFor editor capture, add `-tracehost=localhost` when needed. Inspect:\n\n- Packet Overview for timing and size;\n- Packet Content for actors, properties, and RPCs;\n- Net Stats for inclusive/exclusive byte cost;\n- connection direction and selected connection;\n- spikes during spawn, relevance changes, or UI-driven action spam.\n\n## Useful commands\n\n- `net.ActorReport`: active replicated actor information.\n- `net.DumpRelevantActors`: actors relevant on the next update.\n- `net.ListActorChannels`: open actor channels.\n- `net.ForceOnePacketPerBunch`: stress ordering assumptions.\n- `net.DormancyEnable 0/1`: isolate dormancy-related failures.\n- `showdebug enhancedinput`: inspect input before blaming RPCs.\n\nConfirm command availability/side effects in the 5.8 console-command reference before adding to\nautomation or shipping tooling.\n\n## Failure tree\n\n| Symptom | First checks |\n|---|---|\n| Server RPC never runs | caller owns actor, actor/component replicates, call made on client copy |\n| Property only updates for owner | replication condition and actor relevancy/ownership |\n| Works until actor sleeps | wake/flush before mutation, including component/subobject |\n| Remote client misses effect | actor relevance at multicast time; should it be durable state? |\n| Duplicate/late effect | RepNotify treated as a new event instead of current state |\n| Character rubber-bands | server/client movement divergence; use CMC trace/saved moves |\n| Bandwidth spike | high-frequency RPC/property, always-relevant actors, large collections |\n| Only host works | local-control/authority branch conflated or wrong owner |\n\n## Shipping gate\n\n- Server remains correct with malicious/out-of-range/repeated client requests.\n- All durable state reconstructs for late and re-relevant clients.\n- Reliable RPC rate is bounded under worst input spam.\n- Ordering assumptions survive forced packet/bunch stress.\n- Network Insights meets server CPU and per-connection bandwidth budgets at target scale.\n- Experimental/Beta system risks and rollback are documented.\n","webMarkdown":"## Minimum topology matrix\n\nTest each feature in:\n\n- dedicated server + two remote clients;\n- listen server + remote client;\n- late join after state changed;\n- leave and re-enter relevancy;\n- disconnect/reconnect or respawn where supported;\n- two local players if split screen is supported.\n\nDo not accept a listen-server-only pass; the host combines authority and local control and can\nhide ownership defects.\n\n## Adverse network matrix\n\nUse UE network emulation, then turn it off after each test:\n\n- latency (`NetEmulation.PktLag` or a named emulation profile);\n- packet loss (`NetEmulation.PktLoss`);\n- jitter/lag variance;\n- packet duplication;\n- packet reordering, when compatible with the chosen lag settings.\n\nVerify input responsiveness, correction, reliable-queue health, stale-state rejection, and\neventual authoritative convergence.\n\n## Network Insights\n\nLaunch instances with networking trace enabled, for example:\n\n```text\n-trace=net -NetTrace=1\n```\n\nFor editor capture, add `-tracehost=localhost` when needed. Inspect:\n\n- Packet Overview for timing and size;\n- Packet Content for actors, properties, and RPCs;\n- Net Stats for inclusive/exclusive byte cost;\n- connection direction and selected connection;\n- spikes during spawn, relevance changes, or UI-driven action spam.\n\n## Useful commands\n\n- `net.ActorReport`: active replicated actor information.\n- `net.DumpRelevantActors`: actors relevant on the next update.\n- `net.ListActorChannels`: open actor channels.\n- `net.ForceOnePacketPerBunch`: stress ordering assumptions.\n- `net.DormancyEnable 0/1`: isolate dormancy-related failures.\n- `showdebug enhancedinput`: inspect input before blaming RPCs.\n\nConfirm command availability/side effects in the 5.8 console-command reference before adding to\nautomation or shipping tooling.\n\n## Failure tree\n\n| Symptom | First checks |\n|---|---|\n| Server RPC never runs | caller owns actor, actor/component replicates, call made on client copy |\n| Property only updates for owner | replication condition and actor relevancy/ownership |\n| Works until actor sleeps | wake/flush before mutation, including component/subobject |\n| Remote client misses effect | actor relevance at multicast time; should it be durable state? |\n| Duplicate/late effect | RepNotify treated as a new event instead of current state |\n| Character rubber-bands | server/client movement divergence; use CMC trace/saved moves |\n| Bandwidth spike | high-frequency RPC/property, always-relevant actors, large collections |\n| Only host works | local-control/authority branch conflated or wrong owner |\n\n## Shipping gate\n\n- Server remains correct with malicious/out-of-range/repeated client requests.\n- All durable state reconstructs for late and re-relevant clients.\n- Reliable RPC rate is bounded under worst input spam.\n- Ordering assumptions survive forced packet/bunch stress.\n- Network Insights meets server CPU and per-connection bandwidth budgets at target scale.\n- Experimental/Beta system risks and rollback are documented.\n","searchText":"debugging, testing, and profiling minimum topology matrix test each feature in: - dedicated server + two remote clients; - listen server + remote client; - late join after state changed; - leave and re-enter relevancy; - disconnect/reconnect or respawn where supported; - two local players if split screen is supported. do not accept a listen-server-only pass; the host combines authority and local control and can hide ownership defects. adverse network matrix use ue network emulation, then turn it off after each test: - latency (netemulation.pktlag or a named emulation profile); - packet loss (netemulation.pktloss); - jitter/lag variance; - packet duplication; - packet reordering, when compatible with the chosen lag settings. verify input responsiveness, correction, reliable-queue health, stale-state rejection, and eventual authoritative convergence. network insights launch instances with networking trace enabled, for example: text -trace=net -nettrace=1 for editor capture, add -tracehost=localhost when needed. inspect: - packet overview for timing and size; - packet content for actors, properties, and rpcs; - net stats for inclusive/exclusive byte cost; - connection direction and selected connection; - spikes during spawn, relevance changes, or ui-driven action spam. useful commands - net.actorreport: active replicated actor information. - net.dumprelevantactors: actors relevant on the next update. - net.listactorchannels: open actor channels. - net.forceonepacketperbunch: stress ordering assumptions. - net.dormancyenable 0/1: isolate dormancy-related failures. - showdebug enhancedinput: inspect input before blaming rpcs. confirm command availability/side effects in the 5.8 console-command reference before adding to automation or shipping tooling. failure tree | symptom | first checks | |---|---| | server rpc never runs | caller owns actor, actor/component replicates, call made on client copy | | property only updates for owner | replication condition and actor relevancy/ownership | | works until actor sleeps | wake/flush before mutation, including component/subobject | | remote client misses effect | actor relevance at multicast time; should it be durable state? | | duplicate/late effect | repnotify treated as a new event instead of current state | | character rubber-bands | server/client movement divergence; use cmc trace/saved moves | | bandwidth spike | high-frequency rpc/property, always-relevant actors, large collections | | only host works | local-control/authority branch conflated or wrong owner | shipping gate - server remains correct with malicious/out-of-range/repeated client requests. - all durable state reconstructs for late and re-relevant clients. - reliable rpc rate is bounded under worst input spam. - ordering assumptions survive forced packet/bunch stress. - network insights meets server cpu and per-connection bandwidth budgets at target scale. - experimental/beta system risks and rollback are documented."},{"slug":"patterns","file":"patterns.md","title":"Replication patterns","rawMarkdown":"# Replication patterns\n\n## Networked door\n\n1. Server owns `bIsOpen` (RepNotify) and interaction rules.\n2. Client sends `ServerTryInteract(Door)` through its owned Pawn/Controller.\n3. Server validates range, line of sight, permissions, and current state.\n4. Wake the dormant door before mutation.\n5. RepNotify sets door presentation from current state.\n6. Return the door to dormancy after it settles.\n\nDo not multicast the only open event; a late-relevant client needs durable state.\n\n## Health and UI\n\n1. Server applies damage and owns health.\n2. Health replicates/uses GAS attribute replication.\n3. RepNotify/attribute delegate updates a local presentation model.\n4. Local HUD pushes the display change.\n5. Death state is authoritative; cosmetic hit/death cues may be transient.\n\nRoute GAS details to `$unreal-gas-attributes-effects` and UI details to\n`$unreal-umg-commonui`.\n\n## Inventory\n\n- Server owns the collection and validates add/remove/equip/drop.\n- Client submits item identity and requested verb, never a new inventory total.\n- Use a Fast Array when item-level delta replication and callbacks justify it.\n- Use owner-only conditions for private inventory; replicate public equipped presentation\n  separately when other clients need it.\n- UI selection is local and keyed by stable item identity.\n\n## Projectile selector\n\n- Important persistent/colliding projectile: server-spawned replicated Actor with an appropriate\n  movement/prediction model.\n- High-volume cosmetic tracer: local cosmetic driven from an authoritative hit/result event.\n- Never accept a client claim that a hit occurred without server validation or the game's\n  deliberate lag-compensation model.\n\n## Character movement\n\nUse `ACharacter` + `UCharacterMovementComponent` network prediction/correction for standard\ncharacters. Do not send per-tick transform RPCs or use client `SetActorLocation` as prediction.\nRoute custom movement serialization to `$unreal-character-movement`.\n\n## Match state placement\n\n- `GameMode`: server-only rules and authority.\n- `GameState`: replicated match-wide state clients need.\n- `PlayerState`: replicated player state that should outlive Pawn possession and be visible as\n  designed.\n- `PlayerController`: owner-only control/request channel; each client gets its own controller.\n- `Pawn/Character`: current possessed avatar and movement/gameplay state.\n\nChoose placement from lifetime, visibility, and ownership—not convenience.\n","webMarkdown":"## Networked door\n\n1. Server owns `bIsOpen` (RepNotify) and interaction rules.\n2. Client sends `ServerTryInteract(Door)` through its owned Pawn/Controller.\n3. Server validates range, line of sight, permissions, and current state.\n4. Wake the dormant door before mutation.\n5. RepNotify sets door presentation from current state.\n6. Return the door to dormancy after it settles.\n\nDo not multicast the only open event; a late-relevant client needs durable state.\n\n## Health and UI\n\n1. Server applies damage and owns health.\n2. Health replicates/uses GAS attribute replication.\n3. RepNotify/attribute delegate updates a local presentation model.\n4. Local HUD pushes the display change.\n5. Death state is authoritative; cosmetic hit/death cues may be transient.\n\nRoute GAS details to `$unreal-gas-attributes-effects` and UI details to\n`$unreal-umg-commonui`.\n\n## Inventory\n\n- Server owns the collection and validates add/remove/equip/drop.\n- Client submits item identity and requested verb, never a new inventory total.\n- Use a Fast Array when item-level delta replication and callbacks justify it.\n- Use owner-only conditions for private inventory; replicate public equipped presentation\n  separately when other clients need it.\n- UI selection is local and keyed by stable item identity.\n\n## Projectile selector\n\n- Important persistent/colliding projectile: server-spawned replicated Actor with an appropriate\n  movement/prediction model.\n- High-volume cosmetic tracer: local cosmetic driven from an authoritative hit/result event.\n- Never accept a client claim that a hit occurred without server validation or the game's\n  deliberate lag-compensation model.\n\n## Character movement\n\nUse `ACharacter` + `UCharacterMovementComponent` network prediction/correction for standard\ncharacters. Do not send per-tick transform RPCs or use client `SetActorLocation` as prediction.\nRoute custom movement serialization to `$unreal-character-movement`.\n\n## Match state placement\n\n- `GameMode`: server-only rules and authority.\n- `GameState`: replicated match-wide state clients need.\n- `PlayerState`: replicated player state that should outlive Pawn possession and be visible as\n  designed.\n- `PlayerController`: owner-only control/request channel; each client gets its own controller.\n- `Pawn/Character`: current possessed avatar and movement/gameplay state.\n\nChoose placement from lifetime, visibility, and ownership—not convenience.\n","searchText":"replication patterns networked door 1. server owns bisopen (repnotify) and interaction rules. 2. client sends servertryinteract(door) through its owned pawn/controller. 3. server validates range, line of sight, permissions, and current state. 4. wake the dormant door before mutation. 5. repnotify sets door presentation from current state. 6. return the door to dormancy after it settles. do not multicast the only open event; a late-relevant client needs durable state. health and ui 1. server applies damage and owns health. 2. health replicates/uses gas attribute replication. 3. repnotify/attribute delegate updates a local presentation model. 4. local hud pushes the display change. 5. death state is authoritative; cosmetic hit/death cues may be transient. route gas details to $unreal-gas-attributes-effects and ui details to $unreal-umg-commonui. inventory - server owns the collection and validates add/remove/equip/drop. - client submits item identity and requested verb, never a new inventory total. - use a fast array when item-level delta replication and callbacks justify it. - use owner-only conditions for private inventory; replicate public equipped presentation separately when other clients need it. - ui selection is local and keyed by stable item identity. projectile selector - important persistent/colliding projectile: server-spawned replicated actor with an appropriate movement/prediction model. - high-volume cosmetic tracer: local cosmetic driven from an authoritative hit/result event. - never accept a client claim that a hit occurred without server validation or the game's deliberate lag-compensation model. character movement use acharacter + ucharactermovementcomponent network prediction/correction for standard characters. do not send per-tick transform rpcs or use client setactorlocation as prediction. route custom movement serialization to $unreal-character-movement. match state placement - gamemode: server-only rules and authority. - gamestate: replicated match-wide state clients need. - playerstate: replicated player state that should outlive pawn possession and be visible as designed. - playercontroller: owner-only control/request channel; each client gets its own controller. - pawn/character: current possessed avatar and movement/gameplay state. choose placement from lifetime, visibility, and ownership—not convenience."},{"slug":"properties-repnotify","file":"properties-repnotify.md","title":"Replicated properties and RepNotify","rawMarkdown":"# Replicated properties and RepNotify\n\n## Use properties for state\n\nChoose a replicated property when a client becoming relevant later must learn the current truth:\n\n- health, score, inventory contents, team, door open/closed state;\n- match phase and timestamps;\n- equipped item or persistent ability state.\n\nOn the server, mutate the canonical property. Clients apply received values; client edits to a\nreplica are not authoritative and may be overwritten.\n\n## C++ setup\n\n1. Set the actor to replicate.\n2. Mark the property `UPROPERTY(Replicated)` or `UPROPERTY(ReplicatedUsing=OnRep_Name)`.\n3. Override `GetLifetimeReplicatedProps` and call `Super`.\n4. Register with `DOREPLIFETIME`, a condition macro, or lifetime params.\n5. Put client-side reaction in the RepNotify; it may accept the previous value.\n\nUse Blueprint Replicated/RepNotify settings for Blueprint actors, but keep the same ownership and\nstate rules.\n\n## RepNotify design\n\n- Treat RepNotify as \"received/applied current replicated state,\" not proof that the event just\n  happened in the viewer's timeline.\n- Make presentation reactions idempotent.\n- If server and clients require the same reaction, put it in a shared non-RPC function and call it\n  from the authoritative mutation path and RepNotify as appropriate. Do not assume all C++ and\n  Blueprint RepNotify server behaviors are identical.\n- Use the previous-value parameter when transition logic needs old versus new.\n- Put values requiring coherent ordering in one replicated struct. Epic states there is no\n  deterministic order between OnReps for separate variables.\n\n## Conditions\n\nUse the narrowest correct built-in condition:\n\n- `COND_OwnerOnly`: private owner state;\n- `COND_SkipOwner`: remote-only correction/presentation when owner predicts;\n- `COND_InitialOnly`: immutable setup state after initial replication;\n- `COND_SimulatedOnly` / `COND_AutonomousOnly`: role-specific state;\n- `COND_Dynamic` or custom active override only when simpler static conditions cannot express it.\n\nConditions are per registered property layout; avoid per-instance assumptions in lifetime setup.\n\n## State versus occurrence\n\nRepeated writes can collapse to the latest received state. If every occurrence matters, use an\nappropriate event/RPC, counter/sequence, or replicated collection—not a bool toggled too quickly.\nFor a chest, replicate `bIsOpen` for durable state; emit/derive the opening effect only when its\ntiming is still meaningful.\n\n## UI hookup\n\nRepNotify or a gameplay delegate updates a local presenter/Viewmodel, which pushes into widgets.\nNever bind UI to poll replicated properties every frame.\n","webMarkdown":"## Use properties for state\n\nChoose a replicated property when a client becoming relevant later must learn the current truth:\n\n- health, score, inventory contents, team, door open/closed state;\n- match phase and timestamps;\n- equipped item or persistent ability state.\n\nOn the server, mutate the canonical property. Clients apply received values; client edits to a\nreplica are not authoritative and may be overwritten.\n\n## C++ setup\n\n1. Set the actor to replicate.\n2. Mark the property `UPROPERTY(Replicated)` or `UPROPERTY(ReplicatedUsing=OnRep_Name)`.\n3. Override `GetLifetimeReplicatedProps` and call `Super`.\n4. Register with `DOREPLIFETIME`, a condition macro, or lifetime params.\n5. Put client-side reaction in the RepNotify; it may accept the previous value.\n\nUse Blueprint Replicated/RepNotify settings for Blueprint actors, but keep the same ownership and\nstate rules.\n\n## RepNotify design\n\n- Treat RepNotify as \"received/applied current replicated state,\" not proof that the event just\n  happened in the viewer's timeline.\n- Make presentation reactions idempotent.\n- If server and clients require the same reaction, put it in a shared non-RPC function and call it\n  from the authoritative mutation path and RepNotify as appropriate. Do not assume all C++ and\n  Blueprint RepNotify server behaviors are identical.\n- Use the previous-value parameter when transition logic needs old versus new.\n- Put values requiring coherent ordering in one replicated struct. Epic states there is no\n  deterministic order between OnReps for separate variables.\n\n## Conditions\n\nUse the narrowest correct built-in condition:\n\n- `COND_OwnerOnly`: private owner state;\n- `COND_SkipOwner`: remote-only correction/presentation when owner predicts;\n- `COND_InitialOnly`: immutable setup state after initial replication;\n- `COND_SimulatedOnly` / `COND_AutonomousOnly`: role-specific state;\n- `COND_Dynamic` or custom active override only when simpler static conditions cannot express it.\n\nConditions are per registered property layout; avoid per-instance assumptions in lifetime setup.\n\n## State versus occurrence\n\nRepeated writes can collapse to the latest received state. If every occurrence matters, use an\nappropriate event/RPC, counter/sequence, or replicated collection—not a bool toggled too quickly.\nFor a chest, replicate `bIsOpen` for durable state; emit/derive the opening effect only when its\ntiming is still meaningful.\n\n## UI hookup\n\nRepNotify or a gameplay delegate updates a local presenter/Viewmodel, which pushes into widgets.\nNever bind UI to poll replicated properties every frame.\n","searchText":"replicated properties and repnotify use properties for state choose a replicated property when a client becoming relevant later must learn the current truth: - health, score, inventory contents, team, door open/closed state; - match phase and timestamps; - equipped item or persistent ability state. on the server, mutate the canonical property. clients apply received values; client edits to a replica are not authoritative and may be overwritten. c++ setup 1. set the actor to replicate. 2. mark the property uproperty(replicated) or uproperty(replicatedusing=onrepname). 3. override getlifetimereplicatedprops and call super. 4. register with doreplifetime, a condition macro, or lifetime params. 5. put client-side reaction in the repnotify; it may accept the previous value. use blueprint replicated/repnotify settings for blueprint actors, but keep the same ownership and state rules. repnotify design - treat repnotify as \"received/applied current replicated state,\" not proof that the event just happened in the viewer's timeline. - make presentation reactions idempotent. - if server and clients require the same reaction, put it in a shared non-rpc function and call it from the authoritative mutation path and repnotify as appropriate. do not assume all c++ and blueprint repnotify server behaviors are identical. - use the previous-value parameter when transition logic needs old versus new. - put values requiring coherent ordering in one replicated struct. epic states there is no deterministic order between onreps for separate variables. conditions use the narrowest correct built-in condition: - condowneronly: private owner state; - condskipowner: remote-only correction/presentation when owner predicts; - condinitialonly: immutable setup state after initial replication; - condsimulatedonly / condautonomousonly: role-specific state; - conddynamic or custom active override only when simpler static conditions cannot express it. conditions are per registered property layout; avoid per-instance assumptions in lifetime setup. state versus occurrence repeated writes can collapse to the latest received state. if every occurrence matters, use an appropriate event/rpc, counter/sequence, or replicated collection—not a bool toggled too quickly. for a chest, replicate bisopen for durable state; emit/derive the opening effect only when its timing is still meaningful. ui hookup repnotify or a gameplay delegate updates a local presenter/viewmodel, which pushes into widgets. never bind ui to poll replicated properties every frame."},{"slug":"relevancy-dormancy","file":"relevancy-dormancy.md","title":"Relevancy, priority, frequency, and dormancy","rawMarkdown":"# Relevancy, priority, frequency, and dormancy\n\n## Relevancy\n\nRelevancy is per connection: should this actor affect this viewer now? Use built-in settings before\noverriding `IsNetRelevantFor`:\n\n- `bAlwaysRelevant` for genuinely global actors only;\n- `bOnlyRelevantToOwner` for private actors such as a PlayerController;\n- `bNetUseOwnerRelevancy` for actors that should follow their owner;\n- `NetCullDistanceSquared` for distance-based relevance where enabled.\n\nDynamically spawned replicated actors can be destroyed on a client when they become irrelevant\nand recreated when relevant again. Durable state must survive that transition through replication,\nnot a one-shot multicast.\n\n## Update frequency and priority\n\n- `NetUpdateFrequency` determines how often an actor is considered for updates in Generic\n  Replication.\n- Priority decides which actors replicate first when a connection saturates; elapsed time since\n  last update contributes, preventing simple starvation.\n- Do not set every actor always relevant or high frequency.\n- Change frequency/priority only from measured responsiveness and bandwidth evidence.\n\n## Dormancy\n\nUse dormancy for actors that replicate state but remain unchanged for long periods. Epic calls it\none of the most impactful server replication optimizations.\n\nProcedure:\n\n1. Map-placed initially static actor: start with `DORM_Initial` when appropriate.\n2. Runtime/static actor: use `DORM_DormantAll` when all connections can sleep it.\n3. **Before** changing replicated actor/component/subobject state, call `FlushNetDormancy`,\n   `ForceNetUpdate`, or set `DORM_Awake` as the update pattern requires.\n4. For continuous changes, wake with `SetNetDormancy(DORM_Awake)` and return to\n   `DORM_DormantAll` after state settles.\n5. Do not return a once-awakened map actor to `DORM_Initial`.\n\nBlueprint actor replicated-property writes may flush automatically, but replicated ActorComponent\nBlueprint properties do not have the same guarantee. Keep the explicit wake-before-mutate rule.\n\n## Diagnostic sequence\n\nIf a property updates only sometimes:\n\n1. Confirm mutation occurs on the server.\n2. Confirm the actor/component/property replicates.\n3. Confirm the connection owns/is relevant as required.\n4. Check dormancy and wake order.\n5. Check condition and update frequency.\n6. Inspect the packet/property in Network Insights.\n\nUse `LogNetDormancy`, `net.DumpRelevantActors`, and `net.ActorReport` for targeted evidence.\n","webMarkdown":"## Relevancy\n\nRelevancy is per connection: should this actor affect this viewer now? Use built-in settings before\noverriding `IsNetRelevantFor`:\n\n- `bAlwaysRelevant` for genuinely global actors only;\n- `bOnlyRelevantToOwner` for private actors such as a PlayerController;\n- `bNetUseOwnerRelevancy` for actors that should follow their owner;\n- `NetCullDistanceSquared` for distance-based relevance where enabled.\n\nDynamically spawned replicated actors can be destroyed on a client when they become irrelevant\nand recreated when relevant again. Durable state must survive that transition through replication,\nnot a one-shot multicast.\n\n## Update frequency and priority\n\n- `NetUpdateFrequency` determines how often an actor is considered for updates in Generic\n  Replication.\n- Priority decides which actors replicate first when a connection saturates; elapsed time since\n  last update contributes, preventing simple starvation.\n- Do not set every actor always relevant or high frequency.\n- Change frequency/priority only from measured responsiveness and bandwidth evidence.\n\n## Dormancy\n\nUse dormancy for actors that replicate state but remain unchanged for long periods. Epic calls it\none of the most impactful server replication optimizations.\n\nProcedure:\n\n1. Map-placed initially static actor: start with `DORM_Initial` when appropriate.\n2. Runtime/static actor: use `DORM_DormantAll` when all connections can sleep it.\n3. **Before** changing replicated actor/component/subobject state, call `FlushNetDormancy`,\n   `ForceNetUpdate`, or set `DORM_Awake` as the update pattern requires.\n4. For continuous changes, wake with `SetNetDormancy(DORM_Awake)` and return to\n   `DORM_DormantAll` after state settles.\n5. Do not return a once-awakened map actor to `DORM_Initial`.\n\nBlueprint actor replicated-property writes may flush automatically, but replicated ActorComponent\nBlueprint properties do not have the same guarantee. Keep the explicit wake-before-mutate rule.\n\n## Diagnostic sequence\n\nIf a property updates only sometimes:\n\n1. Confirm mutation occurs on the server.\n2. Confirm the actor/component/property replicates.\n3. Confirm the connection owns/is relevant as required.\n4. Check dormancy and wake order.\n5. Check condition and update frequency.\n6. Inspect the packet/property in Network Insights.\n\nUse `LogNetDormancy`, `net.DumpRelevantActors`, and `net.ActorReport` for targeted evidence.\n","searchText":"relevancy, priority, frequency, and dormancy relevancy relevancy is per connection: should this actor affect this viewer now? use built-in settings before overriding isnetrelevantfor: - balwaysrelevant for genuinely global actors only; - bonlyrelevanttoowner for private actors such as a playercontroller; - bnetuseownerrelevancy for actors that should follow their owner; - netculldistancesquared for distance-based relevance where enabled. dynamically spawned replicated actors can be destroyed on a client when they become irrelevant and recreated when relevant again. durable state must survive that transition through replication, not a one-shot multicast. update frequency and priority - netupdatefrequency determines how often an actor is considered for updates in generic replication. - priority decides which actors replicate first when a connection saturates; elapsed time since last update contributes, preventing simple starvation. - do not set every actor always relevant or high frequency. - change frequency/priority only from measured responsiveness and bandwidth evidence. dormancy use dormancy for actors that replicate state but remain unchanged for long periods. epic calls it one of the most impactful server replication optimizations. procedure: 1. map-placed initially static actor: start with dorminitial when appropriate. 2. runtime/static actor: use dormdormantall when all connections can sleep it. 3. before changing replicated actor/component/subobject state, call flushnetdormancy, forcenetupdate, or set dormawake as the update pattern requires. 4. for continuous changes, wake with setnetdormancy(dormawake) and return to dormdormantall after state settles. 5. do not return a once-awakened map actor to dorminitial. blueprint actor replicated-property writes may flush automatically, but replicated actorcomponent blueprint properties do not have the same guarantee. keep the explicit wake-before-mutate rule. diagnostic sequence if a property updates only sometimes: 1. confirm mutation occurs on the server. 2. confirm the actor/component/property replicates. 3. confirm the connection owns/is relevant as required. 4. check dormancy and wake order. 5. check condition and update frequency. 6. inspect the packet/property in network insights. use lognetdormancy, net.dumprelevantactors, and net.actorreport for targeted evidence."},{"slug":"rpcs-ordering","file":"rpcs-ordering.md","title":"RPCs, reliability, and ordering","rawMarkdown":"# RPCs, reliability, and ordering\n\n## RPC selector\n\n| Need | Mechanism |\n|---|---|\n| Client requests authoritative action | Server RPC on client-owned actor/component |\n| Server targets one owning client | Client RPC |\n| Server sends transient effect to currently relevant clients | NetMulticast, sparingly |\n| Durable state for late relevance/join | Replicated property, not RPC |\n| Local-only presentation | Local function/event |\n\nRPCs are unidirectional and do not return values. Return outcomes through replicated state or a\nseparate targeted response.\n\n## Execution truths\n\n- A client Server RPC runs remotely only when invoked through that client's owning connection;\n  otherwise it is dropped.\n- A server Client RPC targets the actor's owning client.\n- A server NetMulticast runs on the server and clients for which the actor is currently relevant.\n- A client-called NetMulticast runs only on the invoking client.\n- RPCs require a replicated actor/component and valid ownership conditions.\n\n## Reliable versus unreliable\n\nUse reliable only when loss would break a low-frequency essential transition and the call rate is\nstrictly bounded. Reliable RPCs consume an ordered reliable queue; input spam can overflow it.\n\nUse unreliable for frequent, replaceable, or cosmetic occurrences. Design behavior that remains\ncorrect when unreliable calls are dropped.\n\nNever send reliable RPCs from Tick or directly from unbounded button repeat. Prefer replicated\nstate when the current result matters more than each call.\n\n## Ordering rules\n\n- Do not rely on RPC call order across different actors.\n- Reliable RPC ordering guarantees are scoped; do not infer a global event timeline.\n- Multicast versus unicast ordering is not universally preserved.\n- Separate RepNotify callback order is nondeterministic.\n- If values must be interpreted atomically/coherently, group them in one struct or add an explicit\n  sequence/state-machine contract.\n\nDesign receivers to be idempotent, tolerate missing obsolete events, and reject stale sequence\nnumbers when correctness requires it.\n\n## Request payload rule\n\nSend minimum intent, for example `TryInteract(Target)` or `TryEquip(ItemId)`. Do not send trusted\nresults such as new balance, damage dealt, final position, or permission flags. The server derives\nand validates results from canonical state.\n","webMarkdown":"## RPC selector\n\n| Need | Mechanism |\n|---|---|\n| Client requests authoritative action | Server RPC on client-owned actor/component |\n| Server targets one owning client | Client RPC |\n| Server sends transient effect to currently relevant clients | NetMulticast, sparingly |\n| Durable state for late relevance/join | Replicated property, not RPC |\n| Local-only presentation | Local function/event |\n\nRPCs are unidirectional and do not return values. Return outcomes through replicated state or a\nseparate targeted response.\n\n## Execution truths\n\n- A client Server RPC runs remotely only when invoked through that client's owning connection;\n  otherwise it is dropped.\n- A server Client RPC targets the actor's owning client.\n- A server NetMulticast runs on the server and clients for which the actor is currently relevant.\n- A client-called NetMulticast runs only on the invoking client.\n- RPCs require a replicated actor/component and valid ownership conditions.\n\n## Reliable versus unreliable\n\nUse reliable only when loss would break a low-frequency essential transition and the call rate is\nstrictly bounded. Reliable RPCs consume an ordered reliable queue; input spam can overflow it.\n\nUse unreliable for frequent, replaceable, or cosmetic occurrences. Design behavior that remains\ncorrect when unreliable calls are dropped.\n\nNever send reliable RPCs from Tick or directly from unbounded button repeat. Prefer replicated\nstate when the current result matters more than each call.\n\n## Ordering rules\n\n- Do not rely on RPC call order across different actors.\n- Reliable RPC ordering guarantees are scoped; do not infer a global event timeline.\n- Multicast versus unicast ordering is not universally preserved.\n- Separate RepNotify callback order is nondeterministic.\n- If values must be interpreted atomically/coherently, group them in one struct or add an explicit\n  sequence/state-machine contract.\n\nDesign receivers to be idempotent, tolerate missing obsolete events, and reject stale sequence\nnumbers when correctness requires it.\n\n## Request payload rule\n\nSend minimum intent, for example `TryInteract(Target)` or `TryEquip(ItemId)`. Do not send trusted\nresults such as new balance, damage dealt, final position, or permission flags. The server derives\nand validates results from canonical state.\n","searchText":"rpcs, reliability, and ordering rpc selector | need | mechanism | |---|---| | client requests authoritative action | server rpc on client-owned actor/component | | server targets one owning client | client rpc | | server sends transient effect to currently relevant clients | netmulticast, sparingly | | durable state for late relevance/join | replicated property, not rpc | | local-only presentation | local function/event | rpcs are unidirectional and do not return values. return outcomes through replicated state or a separate targeted response. execution truths - a client server rpc runs remotely only when invoked through that client's owning connection; otherwise it is dropped. - a server client rpc targets the actor's owning client. - a server netmulticast runs on the server and clients for which the actor is currently relevant. - a client-called netmulticast runs only on the invoking client. - rpcs require a replicated actor/component and valid ownership conditions. reliable versus unreliable use reliable only when loss would break a low-frequency essential transition and the call rate is strictly bounded. reliable rpcs consume an ordered reliable queue; input spam can overflow it. use unreliable for frequent, replaceable, or cosmetic occurrences. design behavior that remains correct when unreliable calls are dropped. never send reliable rpcs from tick or directly from unbounded button repeat. prefer replicated state when the current result matters more than each call. ordering rules - do not rely on rpc call order across different actors. - reliable rpc ordering guarantees are scoped; do not infer a global event timeline. - multicast versus unicast ordering is not universally preserved. - separate repnotify callback order is nondeterministic. - if values must be interpreted atomically/coherently, group them in one struct or add an explicit sequence/state-machine contract. design receivers to be idempotent, tolerate missing obsolete events, and reject stale sequence numbers when correctness requires it. request payload rule send minimum intent, for example tryinteract(target) or tryequip(itemid). do not send trusted results such as new balance, damage dealt, final position, or permission flags. the server derives and validates results from canonical state."},{"slug":"sources","file":"sources.md","title":"UE 5.8 primary sources","rawMarkdown":"# UE 5.8 primary sources\n\nAll links were checked against Epic's UE 5.8 documentation on 2026-07-19.\n\n## Fundamentals\n\n- [Networking Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/networking-overview-for-unreal-engine)\n- [Actor owner and owning connection](https://dev.epicgames.com/documentation/en-us/unreal-engine/actor-owner-and-owning-connection-in-unreal-engine)\n- [Actor role and remote role](https://dev.epicgames.com/documentation/en-us/unreal-engine/actor-role-and-remote-role-in-unreal-engine)\n- [Replicate Actor Properties](https://dev.epicgames.com/documentation/en-us/unreal-engine/replicate-actor-properties-in-unreal-engine)\n- [Remote Procedure Calls](https://dev.epicgames.com/documentation/en-us/unreal-engine/remote-procedure-calls-in-unreal-engine)\n- [Replicated Object Execution Order](https://dev.epicgames.com/documentation/en-us/unreal-engine/replicated-object-execution-order-in-unreal-engine)\n\n## Filtering and performance\n\n- [Actor Relevancy](https://dev.epicgames.com/documentation/en-us/unreal-engine/actor-relevancy-in-unreal-engine)\n- [Actor Priority](https://dev.epicgames.com/documentation/en-us/unreal-engine/actor-priority-in-unreal-engine)\n- [Actor Network Dormancy](https://dev.epicgames.com/documentation/en-us/unreal-engine/actor-network-dormancy-in-unreal-engine)\n- [Detailed Actor Replication Flow](https://dev.epicgames.com/documentation/en-us/unreal-engine/detailed-actor-replication-flow-in-unreal-engine)\n- [Replication Graph](https://dev.epicgames.com/documentation/en-us/unreal-engine/replication-graph-in-unreal-engine)\n\n## Components, subobjects, and scale systems\n\n- [Replicating Actor Components](https://dev.epicgames.com/documentation/en-us/unreal-engine/replicating-actor-components-in-unreal-engine)\n- [Replicating UObjects](https://dev.epicgames.com/documentation/en-us/unreal-engine/replicating-uobjects-in-unreal-engine)\n- [`FFastArraySerializer`](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/NetCore/FFastArraySerializer)\n- [Introduction to Iris](https://dev.epicgames.com/documentation/en-us/unreal-engine/introduction-to-iris-in-unreal-engine)\n- [Migrate to Iris](https://dev.epicgames.com/documentation/en-us/unreal-engine/migrate-to-iris-in-unreal-engine)\n\n## Testing and subsystem boundaries\n\n- [Testing, Debugging, and Optimization](https://dev.epicgames.com/documentation/en-us/unreal-engine/network-debugging-for-unreal-engine)\n- [Networking Insights](https://dev.epicgames.com/documentation/en-us/unreal-engine/networking-insights-in-unreal-engine)\n- [Console Commands for Network Debugging](https://dev.epicgames.com/documentation/en-us/unreal-engine/console-commands-for-network-debugging-in-unreal-engine)\n- [Networked Character Movement](https://dev.epicgames.com/documentation/en-us/unreal-engine/understanding-networked-movement-in-the-character-movement-component-for-unreal-engine)\n\n## UE 5.8 maturity notes\n\n- Generic Replication is the default.\n- Replication Graph is marked **Beta**.\n- Iris is compiled in but remains **Experimental** and is not the default.\n- The registered subobject list is the only subobject method compatible with Iris.\n","webMarkdown":"All links were checked against Epic's UE 5.8 documentation on 2026-07-19.\n\n## Fundamentals\n\n- [Networking Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/networking-overview-for-unreal-engine)\n- [Actor owner and owning connection](https://dev.epicgames.com/documentation/en-us/unreal-engine/actor-owner-and-owning-connection-in-unreal-engine)\n- [Actor role and remote role](https://dev.epicgames.com/documentation/en-us/unreal-engine/actor-role-and-remote-role-in-unreal-engine)\n- [Replicate Actor Properties](https://dev.epicgames.com/documentation/en-us/unreal-engine/replicate-actor-properties-in-unreal-engine)\n- [Remote Procedure Calls](https://dev.epicgames.com/documentation/en-us/unreal-engine/remote-procedure-calls-in-unreal-engine)\n- [Replicated Object Execution Order](https://dev.epicgames.com/documentation/en-us/unreal-engine/replicated-object-execution-order-in-unreal-engine)\n\n## Filtering and performance\n\n- [Actor Relevancy](https://dev.epicgames.com/documentation/en-us/unreal-engine/actor-relevancy-in-unreal-engine)\n- [Actor Priority](https://dev.epicgames.com/documentation/en-us/unreal-engine/actor-priority-in-unreal-engine)\n- [Actor Network Dormancy](https://dev.epicgames.com/documentation/en-us/unreal-engine/actor-network-dormancy-in-unreal-engine)\n- [Detailed Actor Replication Flow](https://dev.epicgames.com/documentation/en-us/unreal-engine/detailed-actor-replication-flow-in-unreal-engine)\n- [Replication Graph](https://dev.epicgames.com/documentation/en-us/unreal-engine/replication-graph-in-unreal-engine)\n\n## Components, subobjects, and scale systems\n\n- [Replicating Actor Components](https://dev.epicgames.com/documentation/en-us/unreal-engine/replicating-actor-components-in-unreal-engine)\n- [Replicating UObjects](https://dev.epicgames.com/documentation/en-us/unreal-engine/replicating-uobjects-in-unreal-engine)\n- [`FFastArraySerializer`](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/NetCore/FFastArraySerializer)\n- [Introduction to Iris](https://dev.epicgames.com/documentation/en-us/unreal-engine/introduction-to-iris-in-unreal-engine)\n- [Migrate to Iris](https://dev.epicgames.com/documentation/en-us/unreal-engine/migrate-to-iris-in-unreal-engine)\n\n## Testing and subsystem boundaries\n\n- [Testing, Debugging, and Optimization](https://dev.epicgames.com/documentation/en-us/unreal-engine/network-debugging-for-unreal-engine)\n- [Networking Insights](https://dev.epicgames.com/documentation/en-us/unreal-engine/networking-insights-in-unreal-engine)\n- [Console Commands for Network Debugging](https://dev.epicgames.com/documentation/en-us/unreal-engine/console-commands-for-network-debugging-in-unreal-engine)\n- [Networked Character Movement](https://dev.epicgames.com/documentation/en-us/unreal-engine/understanding-networked-movement-in-the-character-movement-component-for-unreal-engine)\n\n## UE 5.8 maturity notes\n\n- Generic Replication is the default.\n- Replication Graph is marked **Beta**.\n- Iris is compiled in but remains **Experimental** and is not the default.\n- The registered subobject list is the only subobject method compatible with Iris.\n","searchText":"ue 5.8 primary sources all links were checked against epic's ue 5.8 documentation on 2026-07-19. fundamentals - networking overview - actor owner and owning connection - actor role and remote role - replicate actor properties - remote procedure calls - replicated object execution order filtering and performance - actor relevancy - actor priority - actor network dormancy - detailed actor replication flow - replication graph components, subobjects, and scale systems - replicating actor components - replicating uobjects - ffastarrayserializer - introduction to iris - migrate to iris testing and subsystem boundaries - testing, debugging, and optimization - networking insights - console commands for network debugging - networked character movement ue 5.8 maturity notes - generic replication is the default. - replication graph is marked beta. - iris is compiled in but remains experimental and is not the default. - the registered subobject list is the only subobject method compatible with iris."},{"slug":"system-selector","file":"system-selector.md","title":"Replication-system selector","rawMarkdown":"# Replication-system selector\n\n## Generic Replication\n\nUse by default. It supports replicated actors, properties, RPCs, relevancy, priority, update\nfrequency, dormancy, components, and subobjects. Most UE networking documentation assumes it.\n\nRemain on Generic Replication when actor/connection counts fit the server budget and its model\nmeets the game's filtering needs. Tune content and dormancy before replacing the driver.\n\n## Replication Graph\n\nEvaluate when the server must repeatedly build per-connection replication lists for large actor\nand connection counts. RepGraph keeps persistent graph nodes/lists that share work across frames\nand connections.\n\nAdoption gate:\n\n- a Network Insights/server trace shows replication-list gathering or per-connection actor\n  evaluation is a material bottleneck;\n- actor categories have clear spatial, always-relevant, owner-only, team, or dormancy rules;\n- the team can implement and test custom graph nodes;\n- the project accepts Beta maturity;\n- console split screen is not required, because Epic documents that limitation.\n\n## Iris\n\nIris is compiled into UE but is not the default replication system. UE 5.8 marks it\n**Experimental**. It changes relevancy into filtering and priority into Iris prioritization,\nshares quantized replicated state work, and aims for stronger scalability/concurrency.\n\nAdoption gate:\n\n- a specific Iris capability or measured scale need justifies Experimental risk;\n- all plugins/subsystems and custom serializers are compatibility-tested;\n- replicated subobjects use the registered subobject list;\n- migration differences are documented and both network correctness and performance are tested;\n- rollback to Generic Replication is planned until the shipping gate is passed.\n\nDo not select Iris because it is newer. Do not assume Generic settings map unchanged: consult the\n5.8 migration guide.\n\n## Selection output\n\nReturn:\n\n| Candidate | Measured need | Maturity/constraint | Decision |\n|---|---|---|---|\n| Generic | baseline | default/stable path | use/reject |\n| RepGraph | large actor x connection filtering cost | Beta; console split-screen limitation | use/reject |\n| Iris | specific filtering/prioritization/scalability need | Experimental; migration work | use/reject |\n\nNo selection is complete without a representative server trace and target-player-count test.\n","webMarkdown":"## Generic Replication\n\nUse by default. It supports replicated actors, properties, RPCs, relevancy, priority, update\nfrequency, dormancy, components, and subobjects. Most UE networking documentation assumes it.\n\nRemain on Generic Replication when actor/connection counts fit the server budget and its model\nmeets the game's filtering needs. Tune content and dormancy before replacing the driver.\n\n## Replication Graph\n\nEvaluate when the server must repeatedly build per-connection replication lists for large actor\nand connection counts. RepGraph keeps persistent graph nodes/lists that share work across frames\nand connections.\n\nAdoption gate:\n\n- a Network Insights/server trace shows replication-list gathering or per-connection actor\n  evaluation is a material bottleneck;\n- actor categories have clear spatial, always-relevant, owner-only, team, or dormancy rules;\n- the team can implement and test custom graph nodes;\n- the project accepts Beta maturity;\n- console split screen is not required, because Epic documents that limitation.\n\n## Iris\n\nIris is compiled into UE but is not the default replication system. UE 5.8 marks it\n**Experimental**. It changes relevancy into filtering and priority into Iris prioritization,\nshares quantized replicated state work, and aims for stronger scalability/concurrency.\n\nAdoption gate:\n\n- a specific Iris capability or measured scale need justifies Experimental risk;\n- all plugins/subsystems and custom serializers are compatibility-tested;\n- replicated subobjects use the registered subobject list;\n- migration differences are documented and both network correctness and performance are tested;\n- rollback to Generic Replication is planned until the shipping gate is passed.\n\nDo not select Iris because it is newer. Do not assume Generic settings map unchanged: consult the\n5.8 migration guide.\n\n## Selection output\n\nReturn:\n\n| Candidate | Measured need | Maturity/constraint | Decision |\n|---|---|---|---|\n| Generic | baseline | default/stable path | use/reject |\n| RepGraph | large actor x connection filtering cost | Beta; console split-screen limitation | use/reject |\n| Iris | specific filtering/prioritization/scalability need | Experimental; migration work | use/reject |\n\nNo selection is complete without a representative server trace and target-player-count test.\n","searchText":"replication-system selector generic replication use by default. it supports replicated actors, properties, rpcs, relevancy, priority, update frequency, dormancy, components, and subobjects. most ue networking documentation assumes it. remain on generic replication when actor/connection counts fit the server budget and its model meets the game's filtering needs. tune content and dormancy before replacing the driver. replication graph evaluate when the server must repeatedly build per-connection replication lists for large actor and connection counts. repgraph keeps persistent graph nodes/lists that share work across frames and connections. adoption gate: - a network insights/server trace shows replication-list gathering or per-connection actor evaluation is a material bottleneck; - actor categories have clear spatial, always-relevant, owner-only, team, or dormancy rules; - the team can implement and test custom graph nodes; - the project accepts beta maturity; - console split screen is not required, because epic documents that limitation. iris iris is compiled into ue but is not the default replication system. ue 5.8 marks it experimental. it changes relevancy into filtering and priority into iris prioritization, shares quantized replicated state work, and aims for stronger scalability/concurrency. adoption gate: - a specific iris capability or measured scale need justifies experimental risk; - all plugins/subsystems and custom serializers are compatibility-tested; - replicated subobjects use the registered subobject list; - migration differences are documented and both network correctness and performance are tested; - rollback to generic replication is planned until the shipping gate is passed. do not select iris because it is newer. do not assume generic settings map unchanged: consult the 5.8 migration guide. selection output return: | candidate | measured need | maturity/constraint | decision | |---|---|---|---| | generic | baseline | default/stable path | use/reject | | repgraph | large actor x connection filtering cost | beta; console split-screen limitation | use/reject | | iris | specific filtering/prioritization/scalability need | experimental; migration work | use/reject | no selection is complete without a representative server trace and target-player-count test."}]}
{"slug":"unreal-save-load","name":"unreal-save-load","title":"Unreal 5.8 Save and Load","description":"Design, implement, version, migrate, optimize, and debug persistent game state in Unreal Engine 5.8. Use for USaveGame, ULocalPlayerSaveGame, UGameplayStatics save/load APIs, slots, platform users, profiles, checkpoints, autosaves, world and actor state, stable identifiers, serialization, FArchive custom versions, schema migration, asynchronous persistence, corruption and recovery, cloud conflicts, multiplayer save authority, GameUserSettings, missing or incompatible saves, save hitches, or packaged save behavior.","shortDescription":"Build durable versioned Unreal persistence","category":"Data, Tools & Shipping","referenceCount":12,"rawMarkdown":"---\nname: unreal-save-load\ndescription: Design, implement, version, migrate, optimize, and debug persistent game state in Unreal Engine 5.8. Use for USaveGame, ULocalPlayerSaveGame, UGameplayStatics save/load APIs, slots, platform users, profiles, checkpoints, autosaves, world and actor state, stable identifiers, serialization, FArchive custom versions, schema migration, asynchronous persistence, corruption and recovery, cloud conflicts, multiplayer save authority, GameUserSettings, missing or incompatible saves, save hitches, or packaged save behavior.\n---\n\n# Unreal 5.8 Save and Load\n\n## Define the persistence contract first\n\nRead [`references/system-selector.md`](references/system-selector.md).\n\n1. List state that must survive a checkpoint, map travel, application restart, device change, patch,\n   account change, and multiplayer session separately.\n2. Assign each datum an authority, stable ID, owner file/slot, lifetime, default, validation rule, and\n   migration policy.\n3. Separate immutable definitions from mutable saved state. Persist definition IDs, not asset objects.\n4. Capture a consistent snapshot, write through a serialized per-user operation queue, and acknowledge\n   success/failure visibly.\n5. Load into data first; validate type/header/version, migrate, resolve definitions, travel/construct the\n   world, then apply state in a deterministic phase.\n6. Preserve a last-known-good path and never overwrite a readable older/newer save after a failed load.\n7. Test real previous-version files, corruption, missing content, low storage, interrupted operations,\n   multiple users, and packaged target builds.\n\nRoute neighboring work deliberately:\n\n- definition assets, Primary Asset IDs, tables, and redirects -> `unreal-data-assets-tables`;\n- subsystem/Actor interface architecture -> `unreal-blueprint-architecture`;\n- save-related loading/memory hitches -> `unreal-memory-streaming` and `unreal-insights-profiling`;\n- release artifact, patch, platform packaging, and crash collection -> `unreal-packaging-deployment`;\n- replicated runtime authority -> `unreal-replication`.\n\nLoad only what applies:\n\n- [`references/schema-stable-identifiers.md`](references/schema-stable-identifiers.md)\n- [`references/save-load-sequence-async.md`](references/save-load-sequence-async.md)\n- [`references/world-state-actors.md`](references/world-state-actors.md)\n- [`references/checkpoints-autosaves.md`](references/checkpoints-autosaves.md)\n- [`references/versioning-migrations.md`](references/versioning-migrations.md)\n- [`references/slots-users-platforms-cloud.md`](references/slots-users-platforms-cloud.md)\n- [`references/corruption-failure-recovery.md`](references/corruption-failure-recovery.md)\n- [`references/multiplayer-authority-security.md`](references/multiplayer-authority-security.md)\n- [`references/performance-testing-debugging.md`](references/performance-testing-debugging.md)\n- [`references/use-case-recipes.md`](references/use-case-recipes.md)\n\n## Required answer format\n\nReturn:\n\n1. **Persistence matrix** by datum, authority, lifetime, owner, stable ID, and slot.\n2. **Save schema/header** with current version, defaults, validation, and size budget.\n3. **Snapshot and write sequence**, concurrency policy, callbacks, UI, and failure behavior.\n4. **Load, migration, definition resolution, world travel, and apply sequence**.\n5. **Actor/world identity**, spawn/destroy state, missing-content behavior, and authority boundary.\n6. **Backup/recovery/cloud conflict policy** without unsupported atomicity claims.\n7. **Previous-version, corruption, interruption, platform-user, multiplayer, and packaged tests**.\n\n## Hard rules\n\n- Do not serialize live Actor/UObject pointers as durable identity. Persist stable domain IDs, Primary\n  Asset IDs, tags, names, GUIDs, and value records with explicit resolution behavior.\n- Do not save immutable definition data into every slot. Save the definition ID plus minimal mutable state.\n- `AsyncSaveGameToSlot` still serializes on the game thread; it moves the platform write to a worker.\n  Keep snapshot/schema cost bounded and measure hitches.\n- Serialize save/load operations per platform user/slot. UE warns that some platforms may not support\n  simultaneous save and load; completion order must not decide data authority.\n- Treat callbacks as stale-capable. Bind weak ownership/request generations and verify slot/user/request.\n- Never mutate the live world incrementally from unvalidated bytes. Validate and migrate a data snapshot\n  before applying it.\n- Never overwrite an unknown newer-version, corrupt, or failed-to-migrate save automatically.\n- Do not rely on application shutdown as the only persistence point.\n- Local save data is untrusted for competitive authority, paid entitlement, or server economy.\n- `SaveGameToSlot` documents that it writes all non-transient properties and does not check the\n  `SaveGame` property flag. Do not repeat the common claim that the flag filters this built-in call.\n- Verify path, quota, user identity, slot enumeration, cloud behavior, suspend/resume, and atomicity with\n  the target platform's current save API; desktop `.sav` behavior is not a universal contract.\n\nSee [`references/sources.md`](references/sources.md) for the UE 5.8 primary-source trail.\n","webMarkdown":"## Define the persistence contract first\n\nRead [`references/system-selector.md`](/unreal/unreal-save-load/system-selector/).\n\n1. List state that must survive a checkpoint, map travel, application restart, device change, patch,\n   account change, and multiplayer session separately.\n2. Assign each datum an authority, stable ID, owner file/slot, lifetime, default, validation rule, and\n   migration policy.\n3. Separate immutable definitions from mutable saved state. Persist definition IDs, not asset objects.\n4. Capture a consistent snapshot, write through a serialized per-user operation queue, and acknowledge\n   success/failure visibly.\n5. Load into data first; validate type/header/version, migrate, resolve definitions, travel/construct the\n   world, then apply state in a deterministic phase.\n6. Preserve a last-known-good path and never overwrite a readable older/newer save after a failed load.\n7. Test real previous-version files, corruption, missing content, low storage, interrupted operations,\n   multiple users, and packaged target builds.\n\nRoute neighboring work deliberately:\n\n- definition assets, Primary Asset IDs, tables, and redirects -> `unreal-data-assets-tables`;\n- subsystem/Actor interface architecture -> `unreal-blueprint-architecture`;\n- save-related loading/memory hitches -> `unreal-memory-streaming` and `unreal-insights-profiling`;\n- release artifact, patch, platform packaging, and crash collection -> `unreal-packaging-deployment`;\n- replicated runtime authority -> `unreal-replication`.\n\nLoad only what applies:\n\n- [`references/schema-stable-identifiers.md`](/unreal/unreal-save-load/schema-stable-identifiers/)\n- [`references/save-load-sequence-async.md`](/unreal/unreal-save-load/save-load-sequence-async/)\n- [`references/world-state-actors.md`](/unreal/unreal-save-load/world-state-actors/)\n- [`references/checkpoints-autosaves.md`](/unreal/unreal-save-load/checkpoints-autosaves/)\n- [`references/versioning-migrations.md`](/unreal/unreal-save-load/versioning-migrations/)\n- [`references/slots-users-platforms-cloud.md`](/unreal/unreal-save-load/slots-users-platforms-cloud/)\n- [`references/corruption-failure-recovery.md`](/unreal/unreal-save-load/corruption-failure-recovery/)\n- [`references/multiplayer-authority-security.md`](/unreal/unreal-save-load/multiplayer-authority-security/)\n- [`references/performance-testing-debugging.md`](/unreal/unreal-save-load/performance-testing-debugging/)\n- [`references/use-case-recipes.md`](/unreal/unreal-save-load/use-case-recipes/)\n\n## Required answer format\n\nReturn:\n\n1. **Persistence matrix** by datum, authority, lifetime, owner, stable ID, and slot.\n2. **Save schema/header** with current version, defaults, validation, and size budget.\n3. **Snapshot and write sequence**, concurrency policy, callbacks, UI, and failure behavior.\n4. **Load, migration, definition resolution, world travel, and apply sequence**.\n5. **Actor/world identity**, spawn/destroy state, missing-content behavior, and authority boundary.\n6. **Backup/recovery/cloud conflict policy** without unsupported atomicity claims.\n7. **Previous-version, corruption, interruption, platform-user, multiplayer, and packaged tests**.\n\n## Hard rules\n\n- Do not serialize live Actor/UObject pointers as durable identity. Persist stable domain IDs, Primary\n  Asset IDs, tags, names, GUIDs, and value records with explicit resolution behavior.\n- Do not save immutable definition data into every slot. Save the definition ID plus minimal mutable state.\n- `AsyncSaveGameToSlot` still serializes on the game thread; it moves the platform write to a worker.\n  Keep snapshot/schema cost bounded and measure hitches.\n- Serialize save/load operations per platform user/slot. UE warns that some platforms may not support\n  simultaneous save and load; completion order must not decide data authority.\n- Treat callbacks as stale-capable. Bind weak ownership/request generations and verify slot/user/request.\n- Never mutate the live world incrementally from unvalidated bytes. Validate and migrate a data snapshot\n  before applying it.\n- Never overwrite an unknown newer-version, corrupt, or failed-to-migrate save automatically.\n- Do not rely on application shutdown as the only persistence point.\n- Local save data is untrusted for competitive authority, paid entitlement, or server economy.\n- `SaveGameToSlot` documents that it writes all non-transient properties and does not check the\n  `SaveGame` property flag. Do not repeat the common claim that the flag filters this built-in call.\n- Verify path, quota, user identity, slot enumeration, cloud behavior, suspend/resume, and atomicity with\n  the target platform's current save API; desktop `.sav` behavior is not a universal contract.\n\nSee [`references/sources.md`](/unreal/unreal-save-load/sources/) for the UE 5.8 primary-source trail.\n","searchText":"unreal 5.8 save and load design, implement, version, migrate, optimize, and debug persistent game state in unreal engine 5.8. use for usavegame, ulocalplayersavegame, ugameplaystatics save/load apis, slots, platform users, profiles, checkpoints, autosaves, world and actor state, stable identifiers, serialization, farchive custom versions, schema migration, asynchronous persistence, corruption and recovery, cloud conflicts, multiplayer save authority, gameusersettings, missing or incompatible saves, save hitches, or packaged save behavior. checkpoints and autosaves checkpoints and autosaves checkpoint contract define whether a checkpoint restores exact simulation, strategic progress, or a curated restart state. exact physics/ai/projectile snapshots are expensive and often unstable; prefer authoritative semantic state plus deterministic reset rules when the design allows it. trigger only after an atomic gameplay milestone: encounter settled, inventory transaction committed, streaming destination ready, and no incompatible transition in progress. freeze or snapshot through the coordinator so systems agree on one logical time. autosave queue - debounce bursts and coalesce redundant requests; - never run two writes whose completion order could regress the slot; - preserve the newest dirty generation until a successful write includes it; - show a saving indicator and prevent unsafe quit/slot deletion while required; - rate-limit storage writes and platform ui; - retry only classified transient failures with a bounded policy; - keep manual and autosave histories distinct when overwriting would surprise the player. save before risky transitions and periodically at safe moments. shutdown/suspend callbacks may provide little or no time; they are a last chance, not the primary design. for roguelike/anti-save-scum constraints, enforce design rules through commit points and authoritative state. do not corrupt reliability or hide failed writes to manufacture permanence. corruption, failure, and recovery corruption, failure, and recovery classify results instead of collapsing them into “no save”: - absent slot/new user; - unsupported/newer version; - corrupt/truncated/wrong class; - migration or validation failure; - missing content/definition; - permission, quota, storage, account, native ui, or platform failure; - canceled/stale request. recovery policy 1. never apply partial or unvalidated state. 2. preserve the original bytes/slot when policy and privacy permit. 3. try a known-good backup/history only after validating its identity/version. 4. surface which progress may be lost and require confirmation before reset/delete. 5. record non-sensitive result code, schema/build, stage, size, duration, and recovery outcome. do not claim savegametoslot is atomic across every platform. if robust replacement is required, use the target platform's documented transaction/container behavior or implement a validated generation scheme with multiple slots: write candidate generation, confirm success/readability, then advance a small index or choose the highest valid generation. test power loss at each boundary on real hardware. checksums detect accidental corruption; they do not make client data trustworthy. encryption without secure key ownership does not create server authority. multiplayer authority and security multiplayer authority and security the server owns shared world state, competitive progression, match results, inventories/economy, and entitlements. a client savegame may cache presentation or offline progress but must not become trusted input merely because it was produced by ue serialization. dedicated/listen server persistence 1. snapshot authoritative server state at a transaction/checkpoint boundary. 2. identify players by authenticated account/domain id, not controller index or connection object. 3. quiesce or version concurrent mutations so the snapshot is internally consistent. 4. persist to the server/backend with idempotency/version checks. 5. acknowledge only after durable success; retry without duplicating rewards/items. 6. on load, validate/migrate before spawning the world and accepting players. for host migration or listen-server saves, define which state can transfer and how a new authority proves freshness. do not trust the host's local file for paid/competitive state without backend verification. keep local accessibility, graphics, controls, and cosmetic preferences per local player/device as appropriate. avoid sending private local settings to the server unless gameplay requires and consent permits it. never log full save payloads, auth tokens, personal identifiers, or encryption keys. treat imported/cloud saves as hostile input: cap sizes/counts, validate enums/ids/ranges, and reject impossible relationships. performance, testing, and debugging performance, testing, and debugging measure stages bookmark and time separately: - snapshot gathering and lock/quiesce time; - savegame object construction and validation; - game-thread serialization; - worker/platform write and callback latency; - read latency; - game-thread object creation/deserialization; - migration, asset resolution, world travel, actor apply, and post-load rebuilds; - payload bytes and record counts by subsystem. async persistence prevents the device io from blocking the game thread, but ue 5.8 still serializes/ creates savegame objects on the game thread. use unreal insights and packaged target builds to enforce a snapshot/serialization hitch budget. test matrix - first boot, new profile, overwrite, manual/autosave rotation, delete; - every supported released schema and a multi-version skip upgrade; - newer/unknown, wrong class, truncated, bit-corrupt, zero-byte, oversized, duplicate-id saves; - removed/renamed definition, missing optional content, changed map/actor class; - disk/quota full, read-only, permission/native ui denial, unplug/suspend/kill at each boundary; - rapid requests, save during load, travel, death, logout, and stale callbacks; - multiple local/platform users, account switch, split screen, offline/cloud conflict; - dedicated/listen server authority, disconnect/reconnect, idempotent backend retry; - development/test/shipping packaged builds and every target platform. never ship migration code without immutable real-world fixtures and expected post-migration assertions. keep a diagnostic command/ui to report slot metadata and result codes without exposing payload secrets. save/load sequence and async behavior save/load sequence and async behavior save 1. coalesce a request and capture reason, user, slot, generation, and checkpoint id. 2. on the game thread, ask owned systems for a consistent value snapshot in a declared order. 3. validate required ids/ranges and create/populate the savegame object. 4. call asyncsavegametoslot; keep ui/state pending until its completion callback. 5. verify callback generation, slot, user, and success. update last-good metadata only on confirmed success. ue 5.8 performs asyncsavegametoslot serialization on the game thread, platform write on a worker, and completion on the game thread. large object graphs can still hitch during serialization. delegate payload is copied to a worker thread, so copied payload must be thread-safe by value. load 1. select user/slot and queue behind conflicting persistence operations. 2. call asyncloadgamefromslot; handle null/failure as a distinct result, not “new game” silently. 3. on callback, verify request identity and cast/type/header/version. 4. migrate a data object; validate it without mutating live gameplay. 5. resolve required definition ids/assets asynchronously and decide missing-content policy. 6. travel/load the target world if needed. 7. when registered systems/actors are ready, apply global -> world -> spawned -> placed actor -> player state in a documented order; then emit one load-complete event. ue 5.8 performs the platform read on a worker, then object creation/deserialization and callback on the game thread. keep migration/apply work bounded or split it behind a loading transition. synchronous apis are acceptable only for proven-small data at a blocking menu/boot boundary. schema and stable identifiers schema and stable identifiers split definition from state text definition: primary asset id / row id / tag -> display, class, tuning, soft assets save record: stable instance id -> definition id + minimal mutable values runtime: resolved definition + validated mutable record + transient caches use value structs/arrays/maps in the savegame object. avoid world pointers, components, delegates, latent actions, timers, ui objects, replicated caches, and derived presentation data. header fields include at least: - format magic/product namespace when using a custom envelope; - save schema version and optional subsystem versions; - build/content compatibility identifier; - slot/profile id and platform-user binding policy; - creation/update time for display only, not authority; - map/checkpoint identity and playtime if needed; - payload validation/checksum metadata when your format provides it. identity - placed persistent actor: authored stable guid/domain id stored with the actor; - runtime-spawned actor: generated persistent instance id plus definition id and spawn record; - item/quest/ability: stable domain/primary asset id, never display text or array index; - map: soft world/primary asset identity or governed map id; - destroyed/consumed placed actor: tombstone/state record keyed by stable actor id. validate uniqueness in editor/ci. duplication workflows must generate or deliberately preserve ids based on semantic identity; accidental duplicate guids make load order decide state. slots, users, platforms, and cloud slots, users, platforms, and cloud slot taxonomy use explicit namespaces, for example: - global machine/user settings; - account/profile unlocks; - manual playthrough slots; - autosave/checkpoint ring; - optional per-world/server cache. store display metadata in a small header/index that can be read without loading the entire world payload when the platform permits. rebuild a cacheable index from authoritative slots when it is missing. userindex identifies the platform user but is ignored on some platforms. ulocalplayersavegame binds a savegame to a local player and supplies load/create, version, pre/post-save, and async helper lifecycle. use it for per-local-player state; keep machine-wide settings separate. the lower-level isavegamesystem exposes platform capabilities including multiple-user support, native ui, async operations, and save-name enumeration. enumeration is not possible on every platform. query capability rather than assuming desktop behavior. cloud/backend the online services user file interface is beta in ue 5.8. if used, treat local and remote copies as two versioned replicas with account identity, revision/generation, timestamp, and conflict policy. time alone is not enough when clocks differ. offer keep-local/keep-cloud/manual resolution when merging is unsafe. never upload before validating the account, schema, payload, and entitlement. test offline creation, reconnect, concurrent devices, sign-out, account switching, deletion, quota, and interrupted transfer. ue 5.8 primary sources ue 5.8 primary sources - saving and loading your game - ugameplaystatics::asyncsavegametoslot - ugameplaystatics::asyncloadgamefromslot - save game to slot - async save game to slot - async load game from slot - does save game exist - delete game in slot - ulocalplayersavegame - isavegamesystem - usavegame - ugameusersettings - enhanced input user settings: save settings - versioning assets and packages - farchive::usingcustomversion - fcustomversion - online services user file interface — beta pages were checked against ue 5.8 documentation on 2026-07-19. reconfirm threading, platform-user/save capabilities, slot enumeration, online services maturity, cloud behavior, quotas, and certification requirements after an engine or platform update. system selector system selector | state | prefer | |---|---| | playthrough/profile/world progress | custom usavegame schema and coordinator | | per-local-player data with lifecycle/version helpers | ulocalplayersavegame | | resolution/window/scalability | ugameusersettings | | enhanced input key profiles | enhanced input user settings or integrated custom serialization | | immutable item/quest/ability definitions | data asset/table/registry; save stable id only | | map-travel-only runtime state | gameinstance/subsystem/player state, not necessarily disk | | server-owned persistent world/account | authoritative backend/database; client save is cache/ui only | | interoperable/external data format | explicit custom format plus validation/versioning | choose one coordinator, commonly a gameinstance subsystem, to own slot/user policy, snapshot requests, operation serialization, migration registry, callbacks, and telemetry. individual actors contribute records; they do not independently race writes to the same slot. use-case recipes use-case recipes small single-player checkpoint use one profile savegame plus a short autosave ring. persist checkpoint id, player semantic state, inventory records by stable definition/instance id, quest state, and placed-actor tombstones. on load, migrate, travel to the checkpoint map, resolve definitions, apply world records, then player state. multiple campaigns plus global unlocks separate global profile/unlocks from each campaign slot. a campaign save references the owning profile id and its own schema/checkpoint. deleting a campaign must not delete account settings/unlocks accidentally. per-player settings use ugameusersettings for resolution/window/scalability. use ulocalplayersavegame or the owning feature's user-settings api for per-player controls/accessibility/custom preferences. bind to platform user, handle split screen/account switch, and do not put world progress in machine graphics config. open-world actors assign authored stable ids to placed savable actors. store a sparse map of changed state/tombstones plus records for persistent runtime-spawned actors. keep records independent of world partition residency; apply when the owning actor registers or after its cell loads. server-owned progression persist authenticated account/domain records through a server/backend transaction. keep the local file to settings/cache/offline mode. use idempotency keys and compare-and-set/version checks so retries cannot duplicate or roll back rewards. versioning and migrations versioning and migrations use a monotonic save schema version independent of marketing/build version. add subsystem/record versions when they can migrate independently. migration pipeline text read version n validate minimum header n -> n+1 pure data transform validate invariants repeat to current resolve current definitions write upgraded copy only after full success and player/platform policy migration functions must be deterministic, idempotent at their declared boundary, and unable to mutate the live world. preserve fixtures for every supported released version. never maintain only “current-1” if players may skip multiple releases. use safe defaults for added fields. for removed/renamed ids, maintain explicit old-to-new maps, gameplay tag/primary asset redirects where applicable, and domain migrations. asset redirectors do not migrate arbitrary saved strings or external keys. for custom uobject serialization, register a guid with fcustomversionregistration, call farchive::usingcustomversion, and branch on customver. do not change an existing serialized layout without advancing its version. keep custom archive logic narrow and test both save and load. if the file version is newer than the running game, reject it read-only with an actionable message. do not downgrade or overwrite it. world and actor state world and actor state use an interface/component/registry to gather and apply records; do not enumerate every actor and dump arbitrary properties. for each savable actor record: text persistentinstanceid definitionorclassid when runtime-spawned owningmaporpartitionid transform only if design permits movement small explicit gameplay state struct record schema/version when independently migrated apply order 1. load/map travel and wait for the intended world readiness boundary. 2. apply global progression and subsystem registries. 3. spawn saved runtime actors not already present. 4. match placed actors by stable id; apply state or tombstone. 5. resolve cross-record references by stable id after all participants exist. 6. apply player pawn/inventory/checkpoint state and re-enable input/gameplay. do not use actor label, array order, transient object name, pointer, or world partition runtime cell as durable identity. a streamed-out actor is not destroyed progress; retain its record independently of current cell residency. define behavior for removed definitions/maps, duplicate ids, actor class replacement, invalid transforms, blocked spawn points, and a record whose owning content is not installed. quarantine/skipping with a clear player-facing status is safer than an unchecked spawn or null dereference.","references":[{"slug":"checkpoints-autosaves","file":"checkpoints-autosaves.md","title":"Checkpoints and autosaves","rawMarkdown":"# Checkpoints and autosaves\n\n## Checkpoint contract\n\nDefine whether a checkpoint restores exact simulation, strategic progress, or a curated restart state.\nExact physics/AI/projectile snapshots are expensive and often unstable; prefer authoritative semantic\nstate plus deterministic reset rules when the design allows it.\n\nTrigger only after an atomic gameplay milestone: encounter settled, inventory transaction committed,\nstreaming destination ready, and no incompatible transition in progress. Freeze or snapshot through the\ncoordinator so systems agree on one logical time.\n\n## Autosave queue\n\n- debounce bursts and coalesce redundant requests;\n- never run two writes whose completion order could regress the slot;\n- preserve the newest dirty generation until a successful write includes it;\n- show a saving indicator and prevent unsafe quit/slot deletion while required;\n- rate-limit storage writes and platform UI;\n- retry only classified transient failures with a bounded policy;\n- keep manual and autosave histories distinct when overwriting would surprise the player.\n\nSave before risky transitions and periodically at safe moments. Shutdown/suspend callbacks may provide\nlittle or no time; they are a last chance, not the primary design.\n\nFor roguelike/anti-save-scum constraints, enforce design rules through commit points and authoritative\nstate. Do not corrupt reliability or hide failed writes to manufacture permanence.\n","webMarkdown":"## Checkpoint contract\n\nDefine whether a checkpoint restores exact simulation, strategic progress, or a curated restart state.\nExact physics/AI/projectile snapshots are expensive and often unstable; prefer authoritative semantic\nstate plus deterministic reset rules when the design allows it.\n\nTrigger only after an atomic gameplay milestone: encounter settled, inventory transaction committed,\nstreaming destination ready, and no incompatible transition in progress. Freeze or snapshot through the\ncoordinator so systems agree on one logical time.\n\n## Autosave queue\n\n- debounce bursts and coalesce redundant requests;\n- never run two writes whose completion order could regress the slot;\n- preserve the newest dirty generation until a successful write includes it;\n- show a saving indicator and prevent unsafe quit/slot deletion while required;\n- rate-limit storage writes and platform UI;\n- retry only classified transient failures with a bounded policy;\n- keep manual and autosave histories distinct when overwriting would surprise the player.\n\nSave before risky transitions and periodically at safe moments. Shutdown/suspend callbacks may provide\nlittle or no time; they are a last chance, not the primary design.\n\nFor roguelike/anti-save-scum constraints, enforce design rules through commit points and authoritative\nstate. Do not corrupt reliability or hide failed writes to manufacture permanence.\n","searchText":"checkpoints and autosaves checkpoint contract define whether a checkpoint restores exact simulation, strategic progress, or a curated restart state. exact physics/ai/projectile snapshots are expensive and often unstable; prefer authoritative semantic state plus deterministic reset rules when the design allows it. trigger only after an atomic gameplay milestone: encounter settled, inventory transaction committed, streaming destination ready, and no incompatible transition in progress. freeze or snapshot through the coordinator so systems agree on one logical time. autosave queue - debounce bursts and coalesce redundant requests; - never run two writes whose completion order could regress the slot; - preserve the newest dirty generation until a successful write includes it; - show a saving indicator and prevent unsafe quit/slot deletion while required; - rate-limit storage writes and platform ui; - retry only classified transient failures with a bounded policy; - keep manual and autosave histories distinct when overwriting would surprise the player. save before risky transitions and periodically at safe moments. shutdown/suspend callbacks may provide little or no time; they are a last chance, not the primary design. for roguelike/anti-save-scum constraints, enforce design rules through commit points and authoritative state. do not corrupt reliability or hide failed writes to manufacture permanence."},{"slug":"corruption-failure-recovery","file":"corruption-failure-recovery.md","title":"Corruption, failure, and recovery","rawMarkdown":"# Corruption, failure, and recovery\n\nClassify results instead of collapsing them into “no save”:\n\n- absent slot/new user;\n- unsupported/newer version;\n- corrupt/truncated/wrong class;\n- migration or validation failure;\n- missing content/definition;\n- permission, quota, storage, account, native UI, or platform failure;\n- canceled/stale request.\n\n## Recovery policy\n\n1. Never apply partial or unvalidated state.\n2. Preserve the original bytes/slot when policy and privacy permit.\n3. Try a known-good backup/history only after validating its identity/version.\n4. Surface which progress may be lost and require confirmation before reset/delete.\n5. Record non-sensitive result code, schema/build, stage, size, duration, and recovery outcome.\n\nDo not claim `SaveGameToSlot` is atomic across every platform. If robust replacement is required, use the\ntarget platform's documented transaction/container behavior or implement a validated generation scheme\nwith multiple slots: write candidate generation, confirm success/readability, then advance a small index\nor choose the highest valid generation. Test power loss at each boundary on real hardware.\n\nChecksums detect accidental corruption; they do not make client data trustworthy. Encryption without\nsecure key ownership does not create server authority.\n","webMarkdown":"Classify results instead of collapsing them into “no save”:\n\n- absent slot/new user;\n- unsupported/newer version;\n- corrupt/truncated/wrong class;\n- migration or validation failure;\n- missing content/definition;\n- permission, quota, storage, account, native UI, or platform failure;\n- canceled/stale request.\n\n## Recovery policy\n\n1. Never apply partial or unvalidated state.\n2. Preserve the original bytes/slot when policy and privacy permit.\n3. Try a known-good backup/history only after validating its identity/version.\n4. Surface which progress may be lost and require confirmation before reset/delete.\n5. Record non-sensitive result code, schema/build, stage, size, duration, and recovery outcome.\n\nDo not claim `SaveGameToSlot` is atomic across every platform. If robust replacement is required, use the\ntarget platform's documented transaction/container behavior or implement a validated generation scheme\nwith multiple slots: write candidate generation, confirm success/readability, then advance a small index\nor choose the highest valid generation. Test power loss at each boundary on real hardware.\n\nChecksums detect accidental corruption; they do not make client data trustworthy. Encryption without\nsecure key ownership does not create server authority.\n","searchText":"corruption, failure, and recovery classify results instead of collapsing them into “no save”: - absent slot/new user; - unsupported/newer version; - corrupt/truncated/wrong class; - migration or validation failure; - missing content/definition; - permission, quota, storage, account, native ui, or platform failure; - canceled/stale request. recovery policy 1. never apply partial or unvalidated state. 2. preserve the original bytes/slot when policy and privacy permit. 3. try a known-good backup/history only after validating its identity/version. 4. surface which progress may be lost and require confirmation before reset/delete. 5. record non-sensitive result code, schema/build, stage, size, duration, and recovery outcome. do not claim savegametoslot is atomic across every platform. if robust replacement is required, use the target platform's documented transaction/container behavior or implement a validated generation scheme with multiple slots: write candidate generation, confirm success/readability, then advance a small index or choose the highest valid generation. test power loss at each boundary on real hardware. checksums detect accidental corruption; they do not make client data trustworthy. encryption without secure key ownership does not create server authority."},{"slug":"multiplayer-authority-security","file":"multiplayer-authority-security.md","title":"Multiplayer authority and security","rawMarkdown":"# Multiplayer authority and security\n\nThe server owns shared world state, competitive progression, match results, inventories/economy, and\nentitlements. A client SaveGame may cache presentation or offline progress but must not become trusted\ninput merely because it was produced by UE serialization.\n\n## Dedicated/listen server persistence\n\n1. Snapshot authoritative server state at a transaction/checkpoint boundary.\n2. Identify players by authenticated account/domain ID, not controller index or connection object.\n3. Quiesce or version concurrent mutations so the snapshot is internally consistent.\n4. Persist to the server/backend with idempotency/version checks.\n5. Acknowledge only after durable success; retry without duplicating rewards/items.\n6. On load, validate/migrate before spawning the world and accepting players.\n\nFor host migration or listen-server saves, define which state can transfer and how a new authority proves\nfreshness. Do not trust the host's local file for paid/competitive state without backend verification.\n\nKeep local accessibility, graphics, controls, and cosmetic preferences per local player/device as\nappropriate. Avoid sending private local settings to the server unless gameplay requires and consent\npermits it.\n\nNever log full save payloads, auth tokens, personal identifiers, or encryption keys. Treat imported/cloud\nsaves as hostile input: cap sizes/counts, validate enums/IDs/ranges, and reject impossible relationships.\n","webMarkdown":"The server owns shared world state, competitive progression, match results, inventories/economy, and\nentitlements. A client SaveGame may cache presentation or offline progress but must not become trusted\ninput merely because it was produced by UE serialization.\n\n## Dedicated/listen server persistence\n\n1. Snapshot authoritative server state at a transaction/checkpoint boundary.\n2. Identify players by authenticated account/domain ID, not controller index or connection object.\n3. Quiesce or version concurrent mutations so the snapshot is internally consistent.\n4. Persist to the server/backend with idempotency/version checks.\n5. Acknowledge only after durable success; retry without duplicating rewards/items.\n6. On load, validate/migrate before spawning the world and accepting players.\n\nFor host migration or listen-server saves, define which state can transfer and how a new authority proves\nfreshness. Do not trust the host's local file for paid/competitive state without backend verification.\n\nKeep local accessibility, graphics, controls, and cosmetic preferences per local player/device as\nappropriate. Avoid sending private local settings to the server unless gameplay requires and consent\npermits it.\n\nNever log full save payloads, auth tokens, personal identifiers, or encryption keys. Treat imported/cloud\nsaves as hostile input: cap sizes/counts, validate enums/IDs/ranges, and reject impossible relationships.\n","searchText":"multiplayer authority and security the server owns shared world state, competitive progression, match results, inventories/economy, and entitlements. a client savegame may cache presentation or offline progress but must not become trusted input merely because it was produced by ue serialization. dedicated/listen server persistence 1. snapshot authoritative server state at a transaction/checkpoint boundary. 2. identify players by authenticated account/domain id, not controller index or connection object. 3. quiesce or version concurrent mutations so the snapshot is internally consistent. 4. persist to the server/backend with idempotency/version checks. 5. acknowledge only after durable success; retry without duplicating rewards/items. 6. on load, validate/migrate before spawning the world and accepting players. for host migration or listen-server saves, define which state can transfer and how a new authority proves freshness. do not trust the host's local file for paid/competitive state without backend verification. keep local accessibility, graphics, controls, and cosmetic preferences per local player/device as appropriate. avoid sending private local settings to the server unless gameplay requires and consent permits it. never log full save payloads, auth tokens, personal identifiers, or encryption keys. treat imported/cloud saves as hostile input: cap sizes/counts, validate enums/ids/ranges, and reject impossible relationships."},{"slug":"performance-testing-debugging","file":"performance-testing-debugging.md","title":"Performance, testing, and debugging","rawMarkdown":"# Performance, testing, and debugging\n\n## Measure stages\n\nBookmark and time separately:\n\n- snapshot gathering and lock/quiesce time;\n- SaveGame object construction and validation;\n- game-thread serialization;\n- worker/platform write and callback latency;\n- read latency;\n- game-thread object creation/deserialization;\n- migration, asset resolution, world travel, actor apply, and post-load rebuilds;\n- payload bytes and record counts by subsystem.\n\nAsync persistence prevents the device IO from blocking the game thread, but UE 5.8 still serializes/\ncreates SaveGame objects on the game thread. Use Unreal Insights and packaged target builds to enforce a\nsnapshot/serialization hitch budget.\n\n## Test matrix\n\n- first boot, new profile, overwrite, manual/autosave rotation, delete;\n- every supported released schema and a multi-version skip upgrade;\n- newer/unknown, wrong class, truncated, bit-corrupt, zero-byte, oversized, duplicate-ID saves;\n- removed/renamed definition, missing optional content, changed map/actor class;\n- disk/quota full, read-only, permission/native UI denial, unplug/suspend/kill at each boundary;\n- rapid requests, save during load, travel, death, logout, and stale callbacks;\n- multiple local/platform users, account switch, split screen, offline/cloud conflict;\n- dedicated/listen server authority, disconnect/reconnect, idempotent backend retry;\n- Development/Test/Shipping packaged builds and every target platform.\n\nNever ship migration code without immutable real-world fixtures and expected post-migration assertions.\nKeep a diagnostic command/UI to report slot metadata and result codes without exposing payload secrets.\n","webMarkdown":"## Measure stages\n\nBookmark and time separately:\n\n- snapshot gathering and lock/quiesce time;\n- SaveGame object construction and validation;\n- game-thread serialization;\n- worker/platform write and callback latency;\n- read latency;\n- game-thread object creation/deserialization;\n- migration, asset resolution, world travel, actor apply, and post-load rebuilds;\n- payload bytes and record counts by subsystem.\n\nAsync persistence prevents the device IO from blocking the game thread, but UE 5.8 still serializes/\ncreates SaveGame objects on the game thread. Use Unreal Insights and packaged target builds to enforce a\nsnapshot/serialization hitch budget.\n\n## Test matrix\n\n- first boot, new profile, overwrite, manual/autosave rotation, delete;\n- every supported released schema and a multi-version skip upgrade;\n- newer/unknown, wrong class, truncated, bit-corrupt, zero-byte, oversized, duplicate-ID saves;\n- removed/renamed definition, missing optional content, changed map/actor class;\n- disk/quota full, read-only, permission/native UI denial, unplug/suspend/kill at each boundary;\n- rapid requests, save during load, travel, death, logout, and stale callbacks;\n- multiple local/platform users, account switch, split screen, offline/cloud conflict;\n- dedicated/listen server authority, disconnect/reconnect, idempotent backend retry;\n- Development/Test/Shipping packaged builds and every target platform.\n\nNever ship migration code without immutable real-world fixtures and expected post-migration assertions.\nKeep a diagnostic command/UI to report slot metadata and result codes without exposing payload secrets.\n","searchText":"performance, testing, and debugging measure stages bookmark and time separately: - snapshot gathering and lock/quiesce time; - savegame object construction and validation; - game-thread serialization; - worker/platform write and callback latency; - read latency; - game-thread object creation/deserialization; - migration, asset resolution, world travel, actor apply, and post-load rebuilds; - payload bytes and record counts by subsystem. async persistence prevents the device io from blocking the game thread, but ue 5.8 still serializes/ creates savegame objects on the game thread. use unreal insights and packaged target builds to enforce a snapshot/serialization hitch budget. test matrix - first boot, new profile, overwrite, manual/autosave rotation, delete; - every supported released schema and a multi-version skip upgrade; - newer/unknown, wrong class, truncated, bit-corrupt, zero-byte, oversized, duplicate-id saves; - removed/renamed definition, missing optional content, changed map/actor class; - disk/quota full, read-only, permission/native ui denial, unplug/suspend/kill at each boundary; - rapid requests, save during load, travel, death, logout, and stale callbacks; - multiple local/platform users, account switch, split screen, offline/cloud conflict; - dedicated/listen server authority, disconnect/reconnect, idempotent backend retry; - development/test/shipping packaged builds and every target platform. never ship migration code without immutable real-world fixtures and expected post-migration assertions. keep a diagnostic command/ui to report slot metadata and result codes without exposing payload secrets."},{"slug":"save-load-sequence-async","file":"save-load-sequence-async.md","title":"Save/load sequence and async behavior","rawMarkdown":"# Save/load sequence and async behavior\n\n## Save\n\n1. Coalesce a request and capture reason, user, slot, generation, and checkpoint ID.\n2. On the game thread, ask owned systems for a consistent value snapshot in a declared order.\n3. Validate required IDs/ranges and create/populate the SaveGame object.\n4. Call `AsyncSaveGameToSlot`; keep UI/state pending until its completion callback.\n5. Verify callback generation, slot, user, and success. Update last-good metadata only on confirmed success.\n\nUE 5.8 performs `AsyncSaveGameToSlot` serialization on the game thread, platform write on a worker, and\ncompletion on the game thread. Large object graphs can still hitch during serialization. Delegate payload\nis copied to a worker thread, so copied payload must be thread-safe by value.\n\n## Load\n\n1. Select user/slot and queue behind conflicting persistence operations.\n2. Call `AsyncLoadGameFromSlot`; handle null/failure as a distinct result, not “new game” silently.\n3. On callback, verify request identity and cast/type/header/version.\n4. Migrate a data object; validate it without mutating live gameplay.\n5. Resolve required definition IDs/assets asynchronously and decide missing-content policy.\n6. Travel/load the target world if needed.\n7. When registered systems/actors are ready, apply global -> world -> spawned -> placed actor -> player\n   state in a documented order; then emit one load-complete event.\n\nUE 5.8 performs the platform read on a worker, then object creation/deserialization and callback on the\ngame thread. Keep migration/apply work bounded or split it behind a loading transition.\n\nSynchronous APIs are acceptable only for proven-small data at a blocking menu/boot boundary.\n","webMarkdown":"## Save\n\n1. Coalesce a request and capture reason, user, slot, generation, and checkpoint ID.\n2. On the game thread, ask owned systems for a consistent value snapshot in a declared order.\n3. Validate required IDs/ranges and create/populate the SaveGame object.\n4. Call `AsyncSaveGameToSlot`; keep UI/state pending until its completion callback.\n5. Verify callback generation, slot, user, and success. Update last-good metadata only on confirmed success.\n\nUE 5.8 performs `AsyncSaveGameToSlot` serialization on the game thread, platform write on a worker, and\ncompletion on the game thread. Large object graphs can still hitch during serialization. Delegate payload\nis copied to a worker thread, so copied payload must be thread-safe by value.\n\n## Load\n\n1. Select user/slot and queue behind conflicting persistence operations.\n2. Call `AsyncLoadGameFromSlot`; handle null/failure as a distinct result, not “new game” silently.\n3. On callback, verify request identity and cast/type/header/version.\n4. Migrate a data object; validate it without mutating live gameplay.\n5. Resolve required definition IDs/assets asynchronously and decide missing-content policy.\n6. Travel/load the target world if needed.\n7. When registered systems/actors are ready, apply global -> world -> spawned -> placed actor -> player\n   state in a documented order; then emit one load-complete event.\n\nUE 5.8 performs the platform read on a worker, then object creation/deserialization and callback on the\ngame thread. Keep migration/apply work bounded or split it behind a loading transition.\n\nSynchronous APIs are acceptable only for proven-small data at a blocking menu/boot boundary.\n","searchText":"save/load sequence and async behavior save 1. coalesce a request and capture reason, user, slot, generation, and checkpoint id. 2. on the game thread, ask owned systems for a consistent value snapshot in a declared order. 3. validate required ids/ranges and create/populate the savegame object. 4. call asyncsavegametoslot; keep ui/state pending until its completion callback. 5. verify callback generation, slot, user, and success. update last-good metadata only on confirmed success. ue 5.8 performs asyncsavegametoslot serialization on the game thread, platform write on a worker, and completion on the game thread. large object graphs can still hitch during serialization. delegate payload is copied to a worker thread, so copied payload must be thread-safe by value. load 1. select user/slot and queue behind conflicting persistence operations. 2. call asyncloadgamefromslot; handle null/failure as a distinct result, not “new game” silently. 3. on callback, verify request identity and cast/type/header/version. 4. migrate a data object; validate it without mutating live gameplay. 5. resolve required definition ids/assets asynchronously and decide missing-content policy. 6. travel/load the target world if needed. 7. when registered systems/actors are ready, apply global -> world -> spawned -> placed actor -> player state in a documented order; then emit one load-complete event. ue 5.8 performs the platform read on a worker, then object creation/deserialization and callback on the game thread. keep migration/apply work bounded or split it behind a loading transition. synchronous apis are acceptable only for proven-small data at a blocking menu/boot boundary."},{"slug":"schema-stable-identifiers","file":"schema-stable-identifiers.md","title":"Schema and stable identifiers","rawMarkdown":"# Schema and stable identifiers\n\n## Split definition from state\n\n```text\nDefinition: Primary Asset ID / row ID / tag -> display, class, tuning, soft assets\nSave record: stable instance ID -> definition ID + minimal mutable values\nRuntime: resolved definition + validated mutable record + transient caches\n```\n\nUse value structs/arrays/maps in the SaveGame object. Avoid world pointers, components, delegates, latent\nactions, timers, UI objects, replicated caches, and derived presentation data.\n\n## Header fields\n\nInclude at least:\n\n- format magic/product namespace when using a custom envelope;\n- save schema version and optional subsystem versions;\n- build/content compatibility identifier;\n- slot/profile ID and platform-user binding policy;\n- creation/update time for display only, not authority;\n- map/checkpoint identity and playtime if needed;\n- payload validation/checksum metadata when your format provides it.\n\n## Identity\n\n- placed persistent actor: authored stable GUID/domain ID stored with the actor;\n- runtime-spawned actor: generated persistent instance ID plus definition ID and spawn record;\n- item/quest/ability: stable domain/Primary Asset ID, never display text or array index;\n- map: soft world/Primary Asset identity or governed map ID;\n- destroyed/consumed placed actor: tombstone/state record keyed by stable actor ID.\n\nValidate uniqueness in editor/CI. Duplication workflows must generate or deliberately preserve IDs based\non semantic identity; accidental duplicate GUIDs make load order decide state.\n","webMarkdown":"## Split definition from state\n\n```text\nDefinition: Primary Asset ID / row ID / tag -> display, class, tuning, soft assets\nSave record: stable instance ID -> definition ID + minimal mutable values\nRuntime: resolved definition + validated mutable record + transient caches\n```\n\nUse value structs/arrays/maps in the SaveGame object. Avoid world pointers, components, delegates, latent\nactions, timers, UI objects, replicated caches, and derived presentation data.\n\n## Header fields\n\nInclude at least:\n\n- format magic/product namespace when using a custom envelope;\n- save schema version and optional subsystem versions;\n- build/content compatibility identifier;\n- slot/profile ID and platform-user binding policy;\n- creation/update time for display only, not authority;\n- map/checkpoint identity and playtime if needed;\n- payload validation/checksum metadata when your format provides it.\n\n## Identity\n\n- placed persistent actor: authored stable GUID/domain ID stored with the actor;\n- runtime-spawned actor: generated persistent instance ID plus definition ID and spawn record;\n- item/quest/ability: stable domain/Primary Asset ID, never display text or array index;\n- map: soft world/Primary Asset identity or governed map ID;\n- destroyed/consumed placed actor: tombstone/state record keyed by stable actor ID.\n\nValidate uniqueness in editor/CI. Duplication workflows must generate or deliberately preserve IDs based\non semantic identity; accidental duplicate GUIDs make load order decide state.\n","searchText":"schema and stable identifiers split definition from state text definition: primary asset id / row id / tag -> display, class, tuning, soft assets save record: stable instance id -> definition id + minimal mutable values runtime: resolved definition + validated mutable record + transient caches use value structs/arrays/maps in the savegame object. avoid world pointers, components, delegates, latent actions, timers, ui objects, replicated caches, and derived presentation data. header fields include at least: - format magic/product namespace when using a custom envelope; - save schema version and optional subsystem versions; - build/content compatibility identifier; - slot/profile id and platform-user binding policy; - creation/update time for display only, not authority; - map/checkpoint identity and playtime if needed; - payload validation/checksum metadata when your format provides it. identity - placed persistent actor: authored stable guid/domain id stored with the actor; - runtime-spawned actor: generated persistent instance id plus definition id and spawn record; - item/quest/ability: stable domain/primary asset id, never display text or array index; - map: soft world/primary asset identity or governed map id; - destroyed/consumed placed actor: tombstone/state record keyed by stable actor id. validate uniqueness in editor/ci. duplication workflows must generate or deliberately preserve ids based on semantic identity; accidental duplicate guids make load order decide state."},{"slug":"slots-users-platforms-cloud","file":"slots-users-platforms-cloud.md","title":"Slots, users, platforms, and cloud","rawMarkdown":"# Slots, users, platforms, and cloud\n\n## Slot taxonomy\n\nUse explicit namespaces, for example:\n\n- global machine/user settings;\n- account/profile unlocks;\n- manual playthrough slots;\n- autosave/checkpoint ring;\n- optional per-world/server cache.\n\nStore display metadata in a small header/index that can be read without loading the entire world payload\nwhen the platform permits. Rebuild a cacheable index from authoritative slots when it is missing.\n\n`UserIndex` identifies the platform user but is ignored on some platforms. `ULocalPlayerSaveGame` binds a\nSaveGame to a Local Player and supplies load/create, version, pre/post-save, and async helper lifecycle.\nUse it for per-local-player state; keep machine-wide settings separate.\n\nThe lower-level `ISaveGameSystem` exposes platform capabilities including multiple-user support, native\nUI, async operations, and save-name enumeration. Enumeration is not possible on every platform. Query\ncapability rather than assuming desktop behavior.\n\n## Cloud/backend\n\nThe Online Services User File Interface is **Beta** in UE 5.8. If used, treat local and remote copies as\ntwo versioned replicas with account identity, revision/generation, timestamp, and conflict policy. Time\nalone is not enough when clocks differ.\n\nOffer keep-local/keep-cloud/manual resolution when merging is unsafe. Never upload before validating the\naccount, schema, payload, and entitlement. Test offline creation, reconnect, concurrent devices, sign-out,\naccount switching, deletion, quota, and interrupted transfer.\n","webMarkdown":"## Slot taxonomy\n\nUse explicit namespaces, for example:\n\n- global machine/user settings;\n- account/profile unlocks;\n- manual playthrough slots;\n- autosave/checkpoint ring;\n- optional per-world/server cache.\n\nStore display metadata in a small header/index that can be read without loading the entire world payload\nwhen the platform permits. Rebuild a cacheable index from authoritative slots when it is missing.\n\n`UserIndex` identifies the platform user but is ignored on some platforms. `ULocalPlayerSaveGame` binds a\nSaveGame to a Local Player and supplies load/create, version, pre/post-save, and async helper lifecycle.\nUse it for per-local-player state; keep machine-wide settings separate.\n\nThe lower-level `ISaveGameSystem` exposes platform capabilities including multiple-user support, native\nUI, async operations, and save-name enumeration. Enumeration is not possible on every platform. Query\ncapability rather than assuming desktop behavior.\n\n## Cloud/backend\n\nThe Online Services User File Interface is **Beta** in UE 5.8. If used, treat local and remote copies as\ntwo versioned replicas with account identity, revision/generation, timestamp, and conflict policy. Time\nalone is not enough when clocks differ.\n\nOffer keep-local/keep-cloud/manual resolution when merging is unsafe. Never upload before validating the\naccount, schema, payload, and entitlement. Test offline creation, reconnect, concurrent devices, sign-out,\naccount switching, deletion, quota, and interrupted transfer.\n","searchText":"slots, users, platforms, and cloud slot taxonomy use explicit namespaces, for example: - global machine/user settings; - account/profile unlocks; - manual playthrough slots; - autosave/checkpoint ring; - optional per-world/server cache. store display metadata in a small header/index that can be read without loading the entire world payload when the platform permits. rebuild a cacheable index from authoritative slots when it is missing. userindex identifies the platform user but is ignored on some platforms. ulocalplayersavegame binds a savegame to a local player and supplies load/create, version, pre/post-save, and async helper lifecycle. use it for per-local-player state; keep machine-wide settings separate. the lower-level isavegamesystem exposes platform capabilities including multiple-user support, native ui, async operations, and save-name enumeration. enumeration is not possible on every platform. query capability rather than assuming desktop behavior. cloud/backend the online services user file interface is beta in ue 5.8. if used, treat local and remote copies as two versioned replicas with account identity, revision/generation, timestamp, and conflict policy. time alone is not enough when clocks differ. offer keep-local/keep-cloud/manual resolution when merging is unsafe. never upload before validating the account, schema, payload, and entitlement. test offline creation, reconnect, concurrent devices, sign-out, account switching, deletion, quota, and interrupted transfer."},{"slug":"sources","file":"sources.md","title":"UE 5.8 primary sources","rawMarkdown":"# UE 5.8 primary sources\n\n- [Saving and Loading Your Game](https://dev.epicgames.com/documentation/en-us/unreal-engine/saving-and-loading-your-game-in-unreal-engine)\n- [`UGameplayStatics::AsyncSaveGameToSlot`](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/UGameplayStatics/AsyncSaveGameToSlot)\n- [`UGameplayStatics::AsyncLoadGameFromSlot`](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/UGameplayStatics/AsyncLoadGameFromSlot)\n- [Save Game to Slot](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/SaveGame/SaveGametoSlot)\n- [Async Save Game to Slot](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/SaveGame/AsyncSaveGametoSlot)\n- [Async Load Game from Slot](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/SaveGame/AsyncLoadGamefromSlot)\n- [Does Save Game Exist](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/SaveGame/DoesSaveGameExist)\n- [Delete Game in Slot](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/SaveGame/DeleteGameinSlot)\n- [`ULocalPlayerSaveGame`](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/ULocalPlayerSaveGame)\n- [`ISaveGameSystem`](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/ISaveGameSystem)\n- [`USaveGame`](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/USaveGame)\n- [`UGameUserSettings`](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/UGameUserSettings)\n- [Enhanced Input User Settings: Save Settings](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/EnhancedInput/UEnhancedInputUserSettings/SaveSettings)\n- [Versioning Assets and Packages](https://dev.epicgames.com/documentation/en-us/unreal-engine/versioning-of-assets-and-packages-in-unreal-engine)\n- [`FArchive::UsingCustomVersion`](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Core/FArchive/UsingCustomVersion)\n- [`FCustomVersion`](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Core/FCustomVersion)\n- [Online Services User File Interface — Beta](https://dev.epicgames.com/documentation/en-us/unreal-engine/user-file-interface-in-unreal-engine)\n\nPages were checked against UE 5.8 documentation on 2026-07-19. Reconfirm threading, platform-user/save\ncapabilities, slot enumeration, Online Services maturity, cloud behavior, quotas, and certification\nrequirements after an engine or platform update.\n","webMarkdown":"- [Saving and Loading Your Game](https://dev.epicgames.com/documentation/en-us/unreal-engine/saving-and-loading-your-game-in-unreal-engine)\n- [`UGameplayStatics::AsyncSaveGameToSlot`](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/UGameplayStatics/AsyncSaveGameToSlot)\n- [`UGameplayStatics::AsyncLoadGameFromSlot`](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/UGameplayStatics/AsyncLoadGameFromSlot)\n- [Save Game to Slot](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/SaveGame/SaveGametoSlot)\n- [Async Save Game to Slot](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/SaveGame/AsyncSaveGametoSlot)\n- [Async Load Game from Slot](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/SaveGame/AsyncLoadGamefromSlot)\n- [Does Save Game Exist](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/SaveGame/DoesSaveGameExist)\n- [Delete Game in Slot](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/SaveGame/DeleteGameinSlot)\n- [`ULocalPlayerSaveGame`](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/ULocalPlayerSaveGame)\n- [`ISaveGameSystem`](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/ISaveGameSystem)\n- [`USaveGame`](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/USaveGame)\n- [`UGameUserSettings`](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/UGameUserSettings)\n- [Enhanced Input User Settings: Save Settings](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/EnhancedInput/UEnhancedInputUserSettings/SaveSettings)\n- [Versioning Assets and Packages](https://dev.epicgames.com/documentation/en-us/unreal-engine/versioning-of-assets-and-packages-in-unreal-engine)\n- [`FArchive::UsingCustomVersion`](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Core/FArchive/UsingCustomVersion)\n- [`FCustomVersion`](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Core/FCustomVersion)\n- [Online Services User File Interface — Beta](https://dev.epicgames.com/documentation/en-us/unreal-engine/user-file-interface-in-unreal-engine)\n\nPages were checked against UE 5.8 documentation on 2026-07-19. Reconfirm threading, platform-user/save\ncapabilities, slot enumeration, Online Services maturity, cloud behavior, quotas, and certification\nrequirements after an engine or platform update.\n","searchText":"ue 5.8 primary sources - saving and loading your game - ugameplaystatics::asyncsavegametoslot - ugameplaystatics::asyncloadgamefromslot - save game to slot - async save game to slot - async load game from slot - does save game exist - delete game in slot - ulocalplayersavegame - isavegamesystem - usavegame - ugameusersettings - enhanced input user settings: save settings - versioning assets and packages - farchive::usingcustomversion - fcustomversion - online services user file interface — beta pages were checked against ue 5.8 documentation on 2026-07-19. reconfirm threading, platform-user/save capabilities, slot enumeration, online services maturity, cloud behavior, quotas, and certification requirements after an engine or platform update."},{"slug":"system-selector","file":"system-selector.md","title":"System selector","rawMarkdown":"# System selector\n\n| State | Prefer |\n|---|---|\n| playthrough/profile/world progress | custom `USaveGame` schema and coordinator |\n| per-local-player data with lifecycle/version helpers | `ULocalPlayerSaveGame` |\n| resolution/window/scalability | `UGameUserSettings` |\n| Enhanced Input key profiles | Enhanced Input User Settings or integrated custom serialization |\n| immutable item/quest/ability definitions | Data Asset/Table/Registry; save stable ID only |\n| map-travel-only runtime state | GameInstance/subsystem/player state, not necessarily disk |\n| server-owned persistent world/account | authoritative backend/database; client save is cache/UI only |\n| interoperable/external data format | explicit custom format plus validation/versioning |\n\nChoose one coordinator, commonly a GameInstance Subsystem, to own slot/user policy, snapshot requests,\noperation serialization, migration registry, callbacks, and telemetry. Individual actors contribute\nrecords; they do not independently race writes to the same slot.\n","webMarkdown":"| State | Prefer |\n|---|---|\n| playthrough/profile/world progress | custom `USaveGame` schema and coordinator |\n| per-local-player data with lifecycle/version helpers | `ULocalPlayerSaveGame` |\n| resolution/window/scalability | `UGameUserSettings` |\n| Enhanced Input key profiles | Enhanced Input User Settings or integrated custom serialization |\n| immutable item/quest/ability definitions | Data Asset/Table/Registry; save stable ID only |\n| map-travel-only runtime state | GameInstance/subsystem/player state, not necessarily disk |\n| server-owned persistent world/account | authoritative backend/database; client save is cache/UI only |\n| interoperable/external data format | explicit custom format plus validation/versioning |\n\nChoose one coordinator, commonly a GameInstance Subsystem, to own slot/user policy, snapshot requests,\noperation serialization, migration registry, callbacks, and telemetry. Individual actors contribute\nrecords; they do not independently race writes to the same slot.\n","searchText":"system selector | state | prefer | |---|---| | playthrough/profile/world progress | custom usavegame schema and coordinator | | per-local-player data with lifecycle/version helpers | ulocalplayersavegame | | resolution/window/scalability | ugameusersettings | | enhanced input key profiles | enhanced input user settings or integrated custom serialization | | immutable item/quest/ability definitions | data asset/table/registry; save stable id only | | map-travel-only runtime state | gameinstance/subsystem/player state, not necessarily disk | | server-owned persistent world/account | authoritative backend/database; client save is cache/ui only | | interoperable/external data format | explicit custom format plus validation/versioning | choose one coordinator, commonly a gameinstance subsystem, to own slot/user policy, snapshot requests, operation serialization, migration registry, callbacks, and telemetry. individual actors contribute records; they do not independently race writes to the same slot."},{"slug":"use-case-recipes","file":"use-case-recipes.md","title":"Use-case recipes","rawMarkdown":"# Use-case recipes\n\n## Small single-player checkpoint\n\nUse one profile SaveGame plus a short autosave ring. Persist checkpoint ID, player semantic state,\ninventory records by stable definition/instance ID, quest state, and placed-actor tombstones. On load,\nmigrate, travel to the checkpoint map, resolve definitions, apply world records, then player state.\n\n## Multiple campaigns plus global unlocks\n\nSeparate global profile/unlocks from each campaign slot. A campaign save references the owning profile ID\nand its own schema/checkpoint. Deleting a campaign must not delete account settings/unlocks accidentally.\n\n## Per-player settings\n\nUse `UGameUserSettings` for resolution/window/scalability. Use `ULocalPlayerSaveGame` or the owning\nfeature's user-settings API for per-player controls/accessibility/custom preferences. Bind to platform\nuser, handle split screen/account switch, and do not put world progress in machine graphics config.\n\n## Open-world actors\n\nAssign authored stable IDs to placed savable actors. Store a sparse map of changed state/tombstones plus\nrecords for persistent runtime-spawned actors. Keep records independent of World Partition residency;\napply when the owning actor registers or after its cell loads.\n\n## Server-owned progression\n\nPersist authenticated account/domain records through a server/backend transaction. Keep the local file\nto settings/cache/offline mode. Use idempotency keys and compare-and-set/version checks so retries cannot\nduplicate or roll back rewards.\n","webMarkdown":"## Small single-player checkpoint\n\nUse one profile SaveGame plus a short autosave ring. Persist checkpoint ID, player semantic state,\ninventory records by stable definition/instance ID, quest state, and placed-actor tombstones. On load,\nmigrate, travel to the checkpoint map, resolve definitions, apply world records, then player state.\n\n## Multiple campaigns plus global unlocks\n\nSeparate global profile/unlocks from each campaign slot. A campaign save references the owning profile ID\nand its own schema/checkpoint. Deleting a campaign must not delete account settings/unlocks accidentally.\n\n## Per-player settings\n\nUse `UGameUserSettings` for resolution/window/scalability. Use `ULocalPlayerSaveGame` or the owning\nfeature's user-settings API for per-player controls/accessibility/custom preferences. Bind to platform\nuser, handle split screen/account switch, and do not put world progress in machine graphics config.\n\n## Open-world actors\n\nAssign authored stable IDs to placed savable actors. Store a sparse map of changed state/tombstones plus\nrecords for persistent runtime-spawned actors. Keep records independent of World Partition residency;\napply when the owning actor registers or after its cell loads.\n\n## Server-owned progression\n\nPersist authenticated account/domain records through a server/backend transaction. Keep the local file\nto settings/cache/offline mode. Use idempotency keys and compare-and-set/version checks so retries cannot\nduplicate or roll back rewards.\n","searchText":"use-case recipes small single-player checkpoint use one profile savegame plus a short autosave ring. persist checkpoint id, player semantic state, inventory records by stable definition/instance id, quest state, and placed-actor tombstones. on load, migrate, travel to the checkpoint map, resolve definitions, apply world records, then player state. multiple campaigns plus global unlocks separate global profile/unlocks from each campaign slot. a campaign save references the owning profile id and its own schema/checkpoint. deleting a campaign must not delete account settings/unlocks accidentally. per-player settings use ugameusersettings for resolution/window/scalability. use ulocalplayersavegame or the owning feature's user-settings api for per-player controls/accessibility/custom preferences. bind to platform user, handle split screen/account switch, and do not put world progress in machine graphics config. open-world actors assign authored stable ids to placed savable actors. store a sparse map of changed state/tombstones plus records for persistent runtime-spawned actors. keep records independent of world partition residency; apply when the owning actor registers or after its cell loads. server-owned progression persist authenticated account/domain records through a server/backend transaction. keep the local file to settings/cache/offline mode. use idempotency keys and compare-and-set/version checks so retries cannot duplicate or roll back rewards."},{"slug":"versioning-migrations","file":"versioning-migrations.md","title":"Versioning and migrations","rawMarkdown":"# Versioning and migrations\n\nUse a monotonic save schema version independent of marketing/build version. Add subsystem/record versions\nwhen they can migrate independently.\n\n## Migration pipeline\n\n```text\nread version N\nvalidate minimum header\nN -> N+1 pure data transform\nvalidate invariants\nrepeat to Current\nresolve current definitions\nwrite upgraded copy only after full success and player/platform policy\n```\n\nMigration functions must be deterministic, idempotent at their declared boundary, and unable to mutate\nthe live world. Preserve fixtures for every supported released version. Never maintain only “current-1”\nif players may skip multiple releases.\n\nUse safe defaults for added fields. For removed/renamed IDs, maintain explicit old-to-new maps, Gameplay\nTag/Primary Asset redirects where applicable, and domain migrations. Asset redirectors do not migrate\narbitrary saved strings or external keys.\n\nFor custom UObject serialization, register a GUID with `FCustomVersionRegistration`, call\n`FArchive::UsingCustomVersion`, and branch on `CustomVer`. Do not change an existing serialized layout\nwithout advancing its version. Keep custom archive logic narrow and test both save and load.\n\nIf the file version is newer than the running game, reject it read-only with an actionable message. Do\nnot downgrade or overwrite it.\n","webMarkdown":"Use a monotonic save schema version independent of marketing/build version. Add subsystem/record versions\nwhen they can migrate independently.\n\n## Migration pipeline\n\n```text\nread version N\nvalidate minimum header\nN -> N+1 pure data transform\nvalidate invariants\nrepeat to Current\nresolve current definitions\nwrite upgraded copy only after full success and player/platform policy\n```\n\nMigration functions must be deterministic, idempotent at their declared boundary, and unable to mutate\nthe live world. Preserve fixtures for every supported released version. Never maintain only “current-1”\nif players may skip multiple releases.\n\nUse safe defaults for added fields. For removed/renamed IDs, maintain explicit old-to-new maps, Gameplay\nTag/Primary Asset redirects where applicable, and domain migrations. Asset redirectors do not migrate\narbitrary saved strings or external keys.\n\nFor custom UObject serialization, register a GUID with `FCustomVersionRegistration`, call\n`FArchive::UsingCustomVersion`, and branch on `CustomVer`. Do not change an existing serialized layout\nwithout advancing its version. Keep custom archive logic narrow and test both save and load.\n\nIf the file version is newer than the running game, reject it read-only with an actionable message. Do\nnot downgrade or overwrite it.\n","searchText":"versioning and migrations use a monotonic save schema version independent of marketing/build version. add subsystem/record versions when they can migrate independently. migration pipeline text read version n validate minimum header n -> n+1 pure data transform validate invariants repeat to current resolve current definitions write upgraded copy only after full success and player/platform policy migration functions must be deterministic, idempotent at their declared boundary, and unable to mutate the live world. preserve fixtures for every supported released version. never maintain only “current-1” if players may skip multiple releases. use safe defaults for added fields. for removed/renamed ids, maintain explicit old-to-new maps, gameplay tag/primary asset redirects where applicable, and domain migrations. asset redirectors do not migrate arbitrary saved strings or external keys. for custom uobject serialization, register a guid with fcustomversionregistration, call farchive::usingcustomversion, and branch on customver. do not change an existing serialized layout without advancing its version. keep custom archive logic narrow and test both save and load. if the file version is newer than the running game, reject it read-only with an actionable message. do not downgrade or overwrite it."},{"slug":"world-state-actors","file":"world-state-actors.md","title":"World and actor state","rawMarkdown":"# World and actor state\n\nUse an interface/component/registry to gather and apply records; do not enumerate every actor and dump\narbitrary properties.\n\nFor each savable actor record:\n\n```text\nPersistentInstanceId\nDefinitionOrClassId when runtime-spawned\nOwningMapOrPartitionId\nTransform only if design permits movement\nsmall explicit gameplay state struct\nrecord schema/version when independently migrated\n```\n\n## Apply order\n\n1. Load/map travel and wait for the intended world readiness boundary.\n2. Apply global progression and subsystem registries.\n3. Spawn saved runtime actors not already present.\n4. Match placed actors by stable ID; apply state or tombstone.\n5. Resolve cross-record references by stable ID after all participants exist.\n6. Apply player pawn/inventory/checkpoint state and re-enable input/gameplay.\n\nDo not use Actor label, array order, transient object name, pointer, or World Partition runtime cell as\ndurable identity. A streamed-out actor is not destroyed progress; retain its record independently of\ncurrent cell residency.\n\nDefine behavior for removed definitions/maps, duplicate IDs, actor class replacement, invalid transforms,\nblocked spawn points, and a record whose owning content is not installed. Quarantine/skipping with a\nclear player-facing status is safer than an unchecked spawn or null dereference.\n","webMarkdown":"Use an interface/component/registry to gather and apply records; do not enumerate every actor and dump\narbitrary properties.\n\nFor each savable actor record:\n\n```text\nPersistentInstanceId\nDefinitionOrClassId when runtime-spawned\nOwningMapOrPartitionId\nTransform only if design permits movement\nsmall explicit gameplay state struct\nrecord schema/version when independently migrated\n```\n\n## Apply order\n\n1. Load/map travel and wait for the intended world readiness boundary.\n2. Apply global progression and subsystem registries.\n3. Spawn saved runtime actors not already present.\n4. Match placed actors by stable ID; apply state or tombstone.\n5. Resolve cross-record references by stable ID after all participants exist.\n6. Apply player pawn/inventory/checkpoint state and re-enable input/gameplay.\n\nDo not use Actor label, array order, transient object name, pointer, or World Partition runtime cell as\ndurable identity. A streamed-out actor is not destroyed progress; retain its record independently of\ncurrent cell residency.\n\nDefine behavior for removed definitions/maps, duplicate IDs, actor class replacement, invalid transforms,\nblocked spawn points, and a record whose owning content is not installed. Quarantine/skipping with a\nclear player-facing status is safer than an unchecked spawn or null dereference.\n","searchText":"world and actor state use an interface/component/registry to gather and apply records; do not enumerate every actor and dump arbitrary properties. for each savable actor record: text persistentinstanceid definitionorclassid when runtime-spawned owningmaporpartitionid transform only if design permits movement small explicit gameplay state struct record schema/version when independently migrated apply order 1. load/map travel and wait for the intended world readiness boundary. 2. apply global progression and subsystem registries. 3. spawn saved runtime actors not already present. 4. match placed actors by stable id; apply state or tombstone. 5. resolve cross-record references by stable id after all participants exist. 6. apply player pawn/inventory/checkpoint state and re-enable input/gameplay. do not use actor label, array order, transient object name, pointer, or world partition runtime cell as durable identity. a streamed-out actor is not destroyed progress; retain its record independently of current cell residency. define behavior for removed definitions/maps, duplicate ids, actor class replacement, invalid transforms, blocked spawn points, and a record whose owning content is not installed. quarantine/skipping with a clear player-facing status is safer than an unchecked spawn or null dereference."}]}
{"slug":"unreal-splines","name":"unreal-splines","title":"Unreal 5.8 Splines","description":"Design, implement, tune, and debug spline-driven systems in Unreal Engine 5.8. Use for Blueprint or C++ paths, Spline Components, Spline Mesh Components, roads, rails, pipes, cables, fences, patrol routes, camera rails, distance-based motion, repeated placement, Landscape Splines, or PCG spline tools.","shortDescription":"Build spline paths, meshes, and movement in UE 5.8","category":"World & AI","referenceCount":4,"rawMarkdown":"---\nname: unreal-splines\ndescription: Design, implement, tune, and debug spline-driven systems in Unreal Engine 5.8. Use for Blueprint or C++ paths, Spline Components, Spline Mesh Components, roads, rails, pipes, cables, fences, patrol routes, camera rails, distance-based motion, repeated placement, Landscape Splines, or PCG spline tools.\n---\n\n# Unreal 5.8 Splines\n\n## Ownership boundary\n\nThis skill owns path math, spline queries, spline-mesh deformation, distance travel, and rigid\nplacement along a path. Route terrain deformation/paint to\n[`unreal-landscape`](../unreal-landscape/SKILL.md), procedural population to\n[`unreal-pcg`](../unreal-pcg/SKILL.md), and streamed-cell/Data Layer/HLOD ownership to\n[`unreal-world-partition`](../unreal-world-partition/SKILL.md).\n\n## Select the system\n\nRead [`references/use-cases.md`](references/use-cases.md) before implementation.\n\n- Use `USplineComponent` for path data, transforms, distance queries, and movement.\n- Use one `USplineMeshComponent` per segment to deform a mesh between two endpoints.\n- Use Landscape Splines when the path must deform or paint Landscape terrain.\n- Use PCG spline tools when the spline is an authoring input for procedural placement.\n- Use ISM/HISM placement instead of spline meshes when repeated objects must remain rigid.\n\nDo not substitute one system for another merely because each contains “Spline” in its\nname.\n\n## Execute\n\n1. Classify the job: query path, move actor, deform continuous mesh, place rigid\n   instances, edit Landscape, or drive PCG.\n2. Declare coordinate space for every query. Prefer World for actor placement and\n   Local when feeding start/end data into a Spline Mesh Component owned by the same\n   actor.\n3. Use **distance along spline** for constant-speed travel and uniform spacing. Do not\n   assume spline point index or input key is proportional to physical distance.\n4. Put editor-generated geometry in the Construction Script. Put runtime mutation in\n   explicit runtime functions. Make both paths idempotent.\n5. Batch point edits, then update the spline once. Avoid rebuilding components every\n   tick.\n6. Validate start, midpoint, end, tightest bend, closed-loop seam, reverse travel,\n   collision, and cooked build behavior.\n\nRead [`references/action-patterns.md`](references/action-patterns.md) for exact patterns.\nRead [`references/troubleshooting.md`](references/troubleshooting.md) when output twists,\nstretches, bunches, duplicates, or moves at inconsistent speed.\n\n## Required answer format\n\nReturn:\n\n1. **System choice** and why.\n2. **Actor/component layout**.\n3. **Ordered Blueprint nodes or C++ calls**, including coordinate spaces.\n4. **Variables to expose**, with units and safe bounds where known.\n5. **Runtime/editor boundary**.\n6. **Failure checks**.\n7. **Verification procedure**.\n\nPrefer node and property names used by UE 5.8. Mark experimental PCG features as\nexperimental. Do not invent editor paths, node names, defaults, or performance claims.\n\n## Hard rules\n\n- Treat a Spline Component as a path, not rendered geometry.\n- Treat a Spline Mesh Component as a two-point deformation, not a multi-point path.\n- Derive repeated counts and spacing from `Get Spline Length`.\n- Scale motion by delta time.\n- Preserve an explicit mesh forward axis and up-vector convention.\n- Clean up previously generated components before regenerating them.\n- Keep spline mutation authoritative in networked gameplay; replicate state or results,\n  not divergent per-client construction.\n- Profile dense spline meshes and collision. Prefer instancing for large rigid repeats.\n\nSee [`references/sources.md`](references/sources.md) for the UE 5.8 source trail.\n","webMarkdown":"## Ownership boundary\n\nThis skill owns path math, spline queries, spline-mesh deformation, distance travel, and rigid\nplacement along a path. Route terrain deformation/paint to\n[`unreal-landscape`](/unreal/unreal-landscape/), procedural population to\n[`unreal-pcg`](/unreal/unreal-pcg/), and streamed-cell/Data Layer/HLOD ownership to\n[`unreal-world-partition`](/unreal/unreal-world-partition/).\n\n## Select the system\n\nRead [`references/use-cases.md`](/unreal/unreal-splines/use-cases/) before implementation.\n\n- Use `USplineComponent` for path data, transforms, distance queries, and movement.\n- Use one `USplineMeshComponent` per segment to deform a mesh between two endpoints.\n- Use Landscape Splines when the path must deform or paint Landscape terrain.\n- Use PCG spline tools when the spline is an authoring input for procedural placement.\n- Use ISM/HISM placement instead of spline meshes when repeated objects must remain rigid.\n\nDo not substitute one system for another merely because each contains “Spline” in its\nname.\n\n## Execute\n\n1. Classify the job: query path, move actor, deform continuous mesh, place rigid\n   instances, edit Landscape, or drive PCG.\n2. Declare coordinate space for every query. Prefer World for actor placement and\n   Local when feeding start/end data into a Spline Mesh Component owned by the same\n   actor.\n3. Use **distance along spline** for constant-speed travel and uniform spacing. Do not\n   assume spline point index or input key is proportional to physical distance.\n4. Put editor-generated geometry in the Construction Script. Put runtime mutation in\n   explicit runtime functions. Make both paths idempotent.\n5. Batch point edits, then update the spline once. Avoid rebuilding components every\n   tick.\n6. Validate start, midpoint, end, tightest bend, closed-loop seam, reverse travel,\n   collision, and cooked build behavior.\n\nRead [`references/action-patterns.md`](/unreal/unreal-splines/action-patterns/) for exact patterns.\nRead [`references/troubleshooting.md`](/unreal/unreal-splines/troubleshooting/) when output twists,\nstretches, bunches, duplicates, or moves at inconsistent speed.\n\n## Required answer format\n\nReturn:\n\n1. **System choice** and why.\n2. **Actor/component layout**.\n3. **Ordered Blueprint nodes or C++ calls**, including coordinate spaces.\n4. **Variables to expose**, with units and safe bounds where known.\n5. **Runtime/editor boundary**.\n6. **Failure checks**.\n7. **Verification procedure**.\n\nPrefer node and property names used by UE 5.8. Mark experimental PCG features as\nexperimental. Do not invent editor paths, node names, defaults, or performance claims.\n\n## Hard rules\n\n- Treat a Spline Component as a path, not rendered geometry.\n- Treat a Spline Mesh Component as a two-point deformation, not a multi-point path.\n- Derive repeated counts and spacing from `Get Spline Length`.\n- Scale motion by delta time.\n- Preserve an explicit mesh forward axis and up-vector convention.\n- Clean up previously generated components before regenerating them.\n- Keep spline mutation authoritative in networked gameplay; replicate state or results,\n  not divergent per-client construction.\n- Profile dense spline meshes and collision. Prefer instancing for large rigid repeats.\n\nSee [`references/sources.md`](/unreal/unreal-splines/sources/) for the UE 5.8 source trail.\n","searchText":"unreal 5.8 splines design, implement, tune, and debug spline-driven systems in unreal engine 5.8. use for blueprint or c++ paths, spline components, spline mesh components, roads, rails, pipes, cables, fences, patrol routes, camera rails, distance-based motion, repeated placement, landscape splines, or pcg spline tools. action patterns action patterns constant-speed actor movement variables: - distancecm — float - speedcmpersec — float - direction — 1.0 or -1.0 - loop — bool - orienttospline — bool per update: 1. length = spline -> get spline length. 2. distancecm += speedcmpersec direction deltaseconds. 3. loop: wrap into [0, length); non-loop: clamp into [0, length]. 4. get transform at distance along spline in world space. 5. if orientation is disabled, use only returned location. 6. apply with set actor transform or move the intended component. 7. define end behavior explicitly: stop, loop, reverse, fire event, or dwell. do not drive constant speed with get location at spline input key plus a linearly increasing key. parametric distance is not guaranteed to be uniform. closest progress to an actor 1. read actor world location. 2. use get distance along spline at location with world coordinate space. 3. use the returned distance for progress, ordering, or a subsequent transform query. 4. if the spline crosses itself, retain previous progress and constrain how far the result may jump between updates. rigid objects at uniform intervals 1. get spline length. 2. choose either: - fixed maximum spacing: count = ceil(length / maxspacing); - approximately target spacing with even end fit: count = round(length / targetspacing). 3. compute actualspacing = length / max(1, count). 4. iterate 0..count when both endpoints need objects; otherwise 0..count-1. 5. query transform at index actualspacing. 6. add an ism/hism instance for repeated meshes; spawn actors only when each instance needs independent behavior. 7. apply lateral offset in the sampled transform's right-vector direction. continuous deformed mesh for each consecutive pair of spline points: 1. create or reuse one spline mesh component. 2. query start/end locations and tangents in the spline owner's local space. 3. assign the static mesh and forward axis. 4. call set start and end with start position/tangent and end position/tangent. 5. apply start/end scale or roll only if required by the design. 6. register the component when created at runtime. 7. store generated components in an array. destroy/clear them before regeneration. for a closed loop, include the last-to-first segment. editable blueprint generator recommended layout: - actor root - spline component - exposed mesh/material/spacing/width/collision variables - generatedcomponents array - rebuild function used by construction script and explicit runtime updates rebuild: 1. destroy or clear previously generated components/instances. 2. validate spline point count and assets. 3. generate deterministically from current spline data. 4. do not modify the designer's control points unless that is the tool's explicit job. landscape road 1. enter landscape manage mode and select spline. 2. create/join/split control points and segments. 3. add a dedicated spline edit layer before expecting heightmap deformation. 4. set segment mesh, width, side falloff, layer name, and raise/lower behavior. 5. snap points to landscape where appropriate. 6. inspect intersections, steep grades, tangents, and material paint transitions. pcg spline authoring in ue 5.8 - enable and enter pcg editor mode. - use draw spline for roads, fences, and line placement. - use draw spline surface for closed fields or bounded scattering. - use graph refresh-rate controls when interactive generation is expensive. - use apply spline to component when pcg must update an existing spline component. - mark the workflow experimental in production documentation and provide a fallback. ue 5.8 primary sources ue 5.8 primary sources - epic games, blueprint spline components overview - epic games, usplinecomponent api - epic games, usplinemeshcomponent api - epic games, landscape splines - epic games, construction script - epic games, pcg editor mode - epic games, ue 5.8 release notes — pcg - epic games, get distance along spline at location version target: unreal engine 5.8. recheck api names and experimental status before using this skill with a later engine version. troubleshooting troubleshooting | symptom | likely cause | action | |---|---|---| | actor speeds up and slows down | sampling by input key or normalized parameter | advance and sample by distance along spline | | objects bunch on curves | sampling control-point intervals rather than arc length | use spline length and distance queries | | mesh is sideways | wrong source-mesh length axis / forward axis | identify source mesh longitudinal axis and match it | | mesh twists or flips | inconsistent up vector, roll, or extreme tangent change | set a stable up-vector convention; inspect point roll and tangents; add points at controlled bends | | visible kink at segment boundary | tangents or segment scale do not match | use spline-provided tangents at both ends; keep adjacent scale/roll continuous | | severe stretching | segment is too long for source mesh or tangent magnitude is extreme | increase segment count or author a longer/denser source mesh | | last fence gap is wrong | fixed spacing without fitting total length | recompute actual spacing from rounded interval count | | generated objects duplicate when editing | construction script is appending without cleanup | destroy/clear generated components or instances before rebuilding | | editor becomes slow while dragging points | heavy construction script, collision rebuild, or too many components | debounce/bake generation; disable unneeded collision; use ism/hism or pcg | | runtime mutation does not update queries | spline changed without final update | batch mutations and call the spline update once | | collision does not match deformation | collision disabled, stale, or expensive dynamic update | confirm collision settings; rebuild only after geometry changes; test cooked behavior | | closed-loop seam pops | missing last-to-first segment or discontinuous roll/tangent | generate closing segment and align seam properties | | camera looks unstable | tangent rotation is not the desired framing | separate position rail from look target; smooth look rotation independently | | patrol agent hits obstacles | spline is not obstacle-aware navigation | sample spline goals and move via navmesh/path following | | network clients disagree | each client mutates path independently | make spline/path state authoritative and replicate deterministic inputs or results | verification checklist - draw/debug the spline and inspect point order. - print spline length and sampled distance. - test distance 0, length / 2, and length. - test shortest and tightest segments. - test reverse and loop boundaries. - test editor reconstruction after moving, duplicating, and undoing the actor. - test collision in standalone and packaged builds. - profile component count, collision, construction script time, and runtime updates. system selector and use cases system selector and use cases choose by output | desired output | use | avoid | |---|---|---| | invisible path, rail, route, or transform field | spline component | spline mesh unless geometry must bend | | bent road strip, pipe, cable, hose, curb, or continuous fence rail | spline component + one spline mesh component per segment | one spline mesh for the whole path | | rigid posts, lamps, trees, signs, or modular props | spline component + ism/hism or spawned actors | deforming the props with spline mesh | | road/path that raises, lowers, or paints landscape | landscape splines on a dedicated spline edit layer | blueprint spline as a terrain-deformation substitute | | procedural content on a line | pcg draw spline / spline data | construction script spawning thousands of actors | | procedural content inside a closed shape | pcg draw spline surface | treating an open path as an area | | camera motion | spline component for position; optional second spline/target for aim | deriving look rotation from tangent when the camera must frame a subject | | ai patrol | spline component as route data plus explicit direction/dwell state | using spline motion as navigation around dynamic obstacles | use-case decisions roads and paths - use landscape splines when terrain conformity and terrain painting are primary. - use spline mesh components when road geometry is authored as deformable modular segments independent of landscape. - keep road width, shoulder width, falloff, material, mesh, collision, and segment length exposed as data. - for pcg-authored roads in ue 5.8, treat pcg editor mode as experimental. the 5.8 apply spline to component node can write pcg spline data to an existing component. cables, pipes, and hoses - use short-enough source meshes that bend without obvious shearing. - ensure source mesh length axis matches the spline mesh forward axis. - use tangent magnitude to control curvature; do not use point position alone. - disable collision unless gameplay needs it. test dynamic collision cost separately. fences - deform only continuous rails or walls. - place posts as rigid instances by distance. - compute the final interval from spline length so the last gap is not visibly short: count = max(1, round(length / targetspacing)), then actualspacing = length / count. camera rails - store travel as distance, not normalized time, if speed is specified in cm/s. - use a timeline/curve to remap time to distance for authored acceleration. - use spline tangent for forward-facing travel; use find look at rotation toward a target for subject framing. - apply camera easing separately from spline geometry. patrol paths - track distance, direction (+1 or -1), speedcmpersec, and dwell state. - closed loop: wrap distance by spline length. - ping-pong: clamp at ends, reverse direction, then apply dwell. - use navmesh pathing between sampled spline goals if agents must avoid obstacles. placement along a spline - uniform physical spacing: sample by distance. - one object per control point: sample by point index. - orientation: use transform/rotation at distance; optionally preserve world up for props that must remain vertical. - random variation: seed it; separate along-path distance jitter from lateral offset. construction versus runtime | need | location | |---|---| | designer drags points and sees generated geometry immediately | construction script | | path is fixed after level load | construction script or baked editor tool | | path changes during play | runtime function called only when data changes | | object travels along fixed path | tick, timeline, or movement task; do not rebuild spline | | thousands of procedural placements | pcg or instancing; avoid individual actor construction |","references":[{"slug":"action-patterns","file":"action-patterns.md","title":"Action patterns","rawMarkdown":"# Action patterns\n\n## Constant-speed actor movement\n\nVariables:\n\n- `DistanceCm` — float\n- `SpeedCmPerSec` — float\n- `Direction` — `1.0` or `-1.0`\n- `Loop` — bool\n- `OrientToSpline` — bool\n\nPer update:\n\n1. `Length = Spline -> Get Spline Length`.\n2. `DistanceCm += SpeedCmPerSec * Direction * DeltaSeconds`.\n3. Loop: wrap into `[0, Length)`; non-loop: clamp into `[0, Length]`.\n4. `Get Transform at Distance Along Spline` in World space.\n5. If orientation is disabled, use only returned location.\n6. Apply with `Set Actor Transform` or move the intended component.\n7. Define end behavior explicitly: stop, loop, reverse, fire event, or dwell.\n\nDo not drive constant speed with `Get Location at Spline Input Key` plus a linearly\nincreasing key. Parametric distance is not guaranteed to be uniform.\n\n## Closest progress to an actor\n\n1. Read actor world location.\n2. Use `Get Distance Along Spline at Location` with World coordinate space.\n3. Use the returned distance for progress, ordering, or a subsequent transform query.\n4. If the spline crosses itself, retain previous progress and constrain how far the\n   result may jump between updates.\n\n## Rigid objects at uniform intervals\n\n1. Get spline length.\n2. Choose either:\n   - fixed maximum spacing: `count = ceil(length / maxSpacing)`;\n   - approximately target spacing with even end fit: `count = round(length / targetSpacing)`.\n3. Compute `actualSpacing = length / max(1, count)`.\n4. Iterate `0..count` when both endpoints need objects; otherwise `0..count-1`.\n5. Query transform at `index * actualSpacing`.\n6. Add an ISM/HISM instance for repeated meshes; spawn actors only when each instance\n   needs independent behavior.\n7. Apply lateral offset in the sampled transform's right-vector direction.\n\n## Continuous deformed mesh\n\nFor each consecutive pair of spline points:\n\n1. Create or reuse one Spline Mesh Component.\n2. Query start/end locations and tangents in the spline owner's Local space.\n3. Assign the static mesh and `Forward Axis`.\n4. Call `Set Start and End` with start position/tangent and end position/tangent.\n5. Apply start/end scale or roll only if required by the design.\n6. Register the component when created at runtime.\n7. Store generated components in an array. Destroy/clear them before regeneration.\n\nFor a closed loop, include the last-to-first segment.\n\n## Editable Blueprint generator\n\nRecommended layout:\n\n- Actor root\n- Spline Component\n- Exposed mesh/material/spacing/width/collision variables\n- `GeneratedComponents` array\n- `Rebuild` function used by Construction Script and explicit runtime updates\n\n`Rebuild`:\n\n1. Destroy or clear previously generated components/instances.\n2. Validate spline point count and assets.\n3. Generate deterministically from current spline data.\n4. Do not modify the designer's control points unless that is the tool's explicit job.\n\n## Landscape road\n\n1. Enter Landscape Manage mode and select Spline.\n2. Create/join/split control points and segments.\n3. Add a dedicated Spline Edit Layer before expecting heightmap deformation.\n4. Set segment mesh, width, side falloff, layer name, and raise/lower behavior.\n5. Snap points to Landscape where appropriate.\n6. Inspect intersections, steep grades, tangents, and material paint transitions.\n\n## PCG spline authoring in UE 5.8\n\n- Enable and enter PCG Editor Mode.\n- Use Draw Spline for roads, fences, and line placement.\n- Use Draw Spline Surface for closed fields or bounded scattering.\n- Use graph refresh-rate controls when interactive generation is expensive.\n- Use `Apply Spline to Component` when PCG must update an existing Spline Component.\n- Mark the workflow experimental in production documentation and provide a fallback.\n","webMarkdown":"## Constant-speed actor movement\n\nVariables:\n\n- `DistanceCm` — float\n- `SpeedCmPerSec` — float\n- `Direction` — `1.0` or `-1.0`\n- `Loop` — bool\n- `OrientToSpline` — bool\n\nPer update:\n\n1. `Length = Spline -> Get Spline Length`.\n2. `DistanceCm += SpeedCmPerSec * Direction * DeltaSeconds`.\n3. Loop: wrap into `[0, Length)`; non-loop: clamp into `[0, Length]`.\n4. `Get Transform at Distance Along Spline` in World space.\n5. If orientation is disabled, use only returned location.\n6. Apply with `Set Actor Transform` or move the intended component.\n7. Define end behavior explicitly: stop, loop, reverse, fire event, or dwell.\n\nDo not drive constant speed with `Get Location at Spline Input Key` plus a linearly\nincreasing key. Parametric distance is not guaranteed to be uniform.\n\n## Closest progress to an actor\n\n1. Read actor world location.\n2. Use `Get Distance Along Spline at Location` with World coordinate space.\n3. Use the returned distance for progress, ordering, or a subsequent transform query.\n4. If the spline crosses itself, retain previous progress and constrain how far the\n   result may jump between updates.\n\n## Rigid objects at uniform intervals\n\n1. Get spline length.\n2. Choose either:\n   - fixed maximum spacing: `count = ceil(length / maxSpacing)`;\n   - approximately target spacing with even end fit: `count = round(length / targetSpacing)`.\n3. Compute `actualSpacing = length / max(1, count)`.\n4. Iterate `0..count` when both endpoints need objects; otherwise `0..count-1`.\n5. Query transform at `index * actualSpacing`.\n6. Add an ISM/HISM instance for repeated meshes; spawn actors only when each instance\n   needs independent behavior.\n7. Apply lateral offset in the sampled transform's right-vector direction.\n\n## Continuous deformed mesh\n\nFor each consecutive pair of spline points:\n\n1. Create or reuse one Spline Mesh Component.\n2. Query start/end locations and tangents in the spline owner's Local space.\n3. Assign the static mesh and `Forward Axis`.\n4. Call `Set Start and End` with start position/tangent and end position/tangent.\n5. Apply start/end scale or roll only if required by the design.\n6. Register the component when created at runtime.\n7. Store generated components in an array. Destroy/clear them before regeneration.\n\nFor a closed loop, include the last-to-first segment.\n\n## Editable Blueprint generator\n\nRecommended layout:\n\n- Actor root\n- Spline Component\n- Exposed mesh/material/spacing/width/collision variables\n- `GeneratedComponents` array\n- `Rebuild` function used by Construction Script and explicit runtime updates\n\n`Rebuild`:\n\n1. Destroy or clear previously generated components/instances.\n2. Validate spline point count and assets.\n3. Generate deterministically from current spline data.\n4. Do not modify the designer's control points unless that is the tool's explicit job.\n\n## Landscape road\n\n1. Enter Landscape Manage mode and select Spline.\n2. Create/join/split control points and segments.\n3. Add a dedicated Spline Edit Layer before expecting heightmap deformation.\n4. Set segment mesh, width, side falloff, layer name, and raise/lower behavior.\n5. Snap points to Landscape where appropriate.\n6. Inspect intersections, steep grades, tangents, and material paint transitions.\n\n## PCG spline authoring in UE 5.8\n\n- Enable and enter PCG Editor Mode.\n- Use Draw Spline for roads, fences, and line placement.\n- Use Draw Spline Surface for closed fields or bounded scattering.\n- Use graph refresh-rate controls when interactive generation is expensive.\n- Use `Apply Spline to Component` when PCG must update an existing Spline Component.\n- Mark the workflow experimental in production documentation and provide a fallback.\n","searchText":"action patterns constant-speed actor movement variables: - distancecm — float - speedcmpersec — float - direction — 1.0 or -1.0 - loop — bool - orienttospline — bool per update: 1. length = spline -> get spline length. 2. distancecm += speedcmpersec direction deltaseconds. 3. loop: wrap into [0, length); non-loop: clamp into [0, length]. 4. get transform at distance along spline in world space. 5. if orientation is disabled, use only returned location. 6. apply with set actor transform or move the intended component. 7. define end behavior explicitly: stop, loop, reverse, fire event, or dwell. do not drive constant speed with get location at spline input key plus a linearly increasing key. parametric distance is not guaranteed to be uniform. closest progress to an actor 1. read actor world location. 2. use get distance along spline at location with world coordinate space. 3. use the returned distance for progress, ordering, or a subsequent transform query. 4. if the spline crosses itself, retain previous progress and constrain how far the result may jump between updates. rigid objects at uniform intervals 1. get spline length. 2. choose either: - fixed maximum spacing: count = ceil(length / maxspacing); - approximately target spacing with even end fit: count = round(length / targetspacing). 3. compute actualspacing = length / max(1, count). 4. iterate 0..count when both endpoints need objects; otherwise 0..count-1. 5. query transform at index actualspacing. 6. add an ism/hism instance for repeated meshes; spawn actors only when each instance needs independent behavior. 7. apply lateral offset in the sampled transform's right-vector direction. continuous deformed mesh for each consecutive pair of spline points: 1. create or reuse one spline mesh component. 2. query start/end locations and tangents in the spline owner's local space. 3. assign the static mesh and forward axis. 4. call set start and end with start position/tangent and end position/tangent. 5. apply start/end scale or roll only if required by the design. 6. register the component when created at runtime. 7. store generated components in an array. destroy/clear them before regeneration. for a closed loop, include the last-to-first segment. editable blueprint generator recommended layout: - actor root - spline component - exposed mesh/material/spacing/width/collision variables - generatedcomponents array - rebuild function used by construction script and explicit runtime updates rebuild: 1. destroy or clear previously generated components/instances. 2. validate spline point count and assets. 3. generate deterministically from current spline data. 4. do not modify the designer's control points unless that is the tool's explicit job. landscape road 1. enter landscape manage mode and select spline. 2. create/join/split control points and segments. 3. add a dedicated spline edit layer before expecting heightmap deformation. 4. set segment mesh, width, side falloff, layer name, and raise/lower behavior. 5. snap points to landscape where appropriate. 6. inspect intersections, steep grades, tangents, and material paint transitions. pcg spline authoring in ue 5.8 - enable and enter pcg editor mode. - use draw spline for roads, fences, and line placement. - use draw spline surface for closed fields or bounded scattering. - use graph refresh-rate controls when interactive generation is expensive. - use apply spline to component when pcg must update an existing spline component. - mark the workflow experimental in production documentation and provide a fallback."},{"slug":"sources","file":"sources.md","title":"UE 5.8 primary sources","rawMarkdown":"# UE 5.8 primary sources\n\n- Epic Games, [Blueprint Spline Components Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/blueprint-spline-components-overview-in-unreal-engine)\n- Epic Games, [`USplineComponent` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/USplineComponent)\n- Epic Games, [`USplineMeshComponent` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/USplineMeshComponent)\n- Epic Games, [Landscape Splines](https://dev.epicgames.com/documentation/en-us/unreal-engine/landscape-splines-in-unreal-engine)\n- Epic Games, [Construction Script](https://dev.epicgames.com/documentation/en-us/unreal-engine/construction-script-in-unreal-engine)\n- Epic Games, [PCG Editor Mode](https://dev.epicgames.com/documentation/en-us/unreal-engine/pcg-editor-mode-in-unreal-engine)\n- Epic Games, [UE 5.8 Release Notes — PCG](https://dev.epicgames.com/documentation/unreal-engine/unreal-engine-5-8-release-notes?lang=en-US)\n- Epic Games, [`Get Distance Along Spline at Location`](https://dev.epicgames.com/documentation/unreal-engine/BlueprintAPI/Spline/GetDistanceAlongSplineatLocation)\n\nVersion target: Unreal Engine 5.8. Recheck API names and experimental status before\nusing this skill with a later engine version.\n","webMarkdown":"- Epic Games, [Blueprint Spline Components Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/blueprint-spline-components-overview-in-unreal-engine)\n- Epic Games, [`USplineComponent` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/USplineComponent)\n- Epic Games, [`USplineMeshComponent` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/USplineMeshComponent)\n- Epic Games, [Landscape Splines](https://dev.epicgames.com/documentation/en-us/unreal-engine/landscape-splines-in-unreal-engine)\n- Epic Games, [Construction Script](https://dev.epicgames.com/documentation/en-us/unreal-engine/construction-script-in-unreal-engine)\n- Epic Games, [PCG Editor Mode](https://dev.epicgames.com/documentation/en-us/unreal-engine/pcg-editor-mode-in-unreal-engine)\n- Epic Games, [UE 5.8 Release Notes — PCG](https://dev.epicgames.com/documentation/unreal-engine/unreal-engine-5-8-release-notes?lang=en-US)\n- Epic Games, [`Get Distance Along Spline at Location`](https://dev.epicgames.com/documentation/unreal-engine/BlueprintAPI/Spline/GetDistanceAlongSplineatLocation)\n\nVersion target: Unreal Engine 5.8. Recheck API names and experimental status before\nusing this skill with a later engine version.\n","searchText":"ue 5.8 primary sources - epic games, blueprint spline components overview - epic games, usplinecomponent api - epic games, usplinemeshcomponent api - epic games, landscape splines - epic games, construction script - epic games, pcg editor mode - epic games, ue 5.8 release notes — pcg - epic games, get distance along spline at location version target: unreal engine 5.8. recheck api names and experimental status before using this skill with a later engine version."},{"slug":"troubleshooting","file":"troubleshooting.md","title":"Troubleshooting","rawMarkdown":"# Troubleshooting\n\n| Symptom | Likely cause | Action |\n|---|---|---|\n| Actor speeds up and slows down | Sampling by input key or normalized parameter | Advance and sample by distance along spline |\n| Objects bunch on curves | Sampling control-point intervals rather than arc length | Use spline length and distance queries |\n| Mesh is sideways | Wrong source-mesh length axis / `Forward Axis` | Identify source mesh longitudinal axis and match it |\n| Mesh twists or flips | Inconsistent up vector, roll, or extreme tangent change | Set a stable up-vector convention; inspect point roll and tangents; add points at controlled bends |\n| Visible kink at segment boundary | Tangents or segment scale do not match | Use spline-provided tangents at both ends; keep adjacent scale/roll continuous |\n| Severe stretching | Segment is too long for source mesh or tangent magnitude is extreme | Increase segment count or author a longer/denser source mesh |\n| Last fence gap is wrong | Fixed spacing without fitting total length | Recompute actual spacing from rounded interval count |\n| Generated objects duplicate when editing | Construction Script is appending without cleanup | Destroy/clear generated components or instances before rebuilding |\n| Editor becomes slow while dragging points | Heavy Construction Script, collision rebuild, or too many components | Debounce/bake generation; disable unneeded collision; use ISM/HISM or PCG |\n| Runtime mutation does not update queries | Spline changed without final update | Batch mutations and call the spline update once |\n| Collision does not match deformation | Collision disabled, stale, or expensive dynamic update | Confirm collision settings; rebuild only after geometry changes; test cooked behavior |\n| Closed-loop seam pops | Missing last-to-first segment or discontinuous roll/tangent | Generate closing segment and align seam properties |\n| Camera looks unstable | Tangent rotation is not the desired framing | Separate position rail from look target; smooth look rotation independently |\n| Patrol agent hits obstacles | Spline is not obstacle-aware navigation | Sample spline goals and move via NavMesh/path following |\n| Network clients disagree | Each client mutates path independently | Make spline/path state authoritative and replicate deterministic inputs or results |\n\n## Verification checklist\n\n- Draw/debug the spline and inspect point order.\n- Print spline length and sampled distance.\n- Test distance `0`, `length / 2`, and `length`.\n- Test shortest and tightest segments.\n- Test reverse and loop boundaries.\n- Test editor reconstruction after moving, duplicating, and undoing the actor.\n- Test collision in standalone and packaged builds.\n- Profile component count, collision, Construction Script time, and runtime updates.\n","webMarkdown":"| Symptom | Likely cause | Action |\n|---|---|---|\n| Actor speeds up and slows down | Sampling by input key or normalized parameter | Advance and sample by distance along spline |\n| Objects bunch on curves | Sampling control-point intervals rather than arc length | Use spline length and distance queries |\n| Mesh is sideways | Wrong source-mesh length axis / `Forward Axis` | Identify source mesh longitudinal axis and match it |\n| Mesh twists or flips | Inconsistent up vector, roll, or extreme tangent change | Set a stable up-vector convention; inspect point roll and tangents; add points at controlled bends |\n| Visible kink at segment boundary | Tangents or segment scale do not match | Use spline-provided tangents at both ends; keep adjacent scale/roll continuous |\n| Severe stretching | Segment is too long for source mesh or tangent magnitude is extreme | Increase segment count or author a longer/denser source mesh |\n| Last fence gap is wrong | Fixed spacing without fitting total length | Recompute actual spacing from rounded interval count |\n| Generated objects duplicate when editing | Construction Script is appending without cleanup | Destroy/clear generated components or instances before rebuilding |\n| Editor becomes slow while dragging points | Heavy Construction Script, collision rebuild, or too many components | Debounce/bake generation; disable unneeded collision; use ISM/HISM or PCG |\n| Runtime mutation does not update queries | Spline changed without final update | Batch mutations and call the spline update once |\n| Collision does not match deformation | Collision disabled, stale, or expensive dynamic update | Confirm collision settings; rebuild only after geometry changes; test cooked behavior |\n| Closed-loop seam pops | Missing last-to-first segment or discontinuous roll/tangent | Generate closing segment and align seam properties |\n| Camera looks unstable | Tangent rotation is not the desired framing | Separate position rail from look target; smooth look rotation independently |\n| Patrol agent hits obstacles | Spline is not obstacle-aware navigation | Sample spline goals and move via NavMesh/path following |\n| Network clients disagree | Each client mutates path independently | Make spline/path state authoritative and replicate deterministic inputs or results |\n\n## Verification checklist\n\n- Draw/debug the spline and inspect point order.\n- Print spline length and sampled distance.\n- Test distance `0`, `length / 2`, and `length`.\n- Test shortest and tightest segments.\n- Test reverse and loop boundaries.\n- Test editor reconstruction after moving, duplicating, and undoing the actor.\n- Test collision in standalone and packaged builds.\n- Profile component count, collision, Construction Script time, and runtime updates.\n","searchText":"troubleshooting | symptom | likely cause | action | |---|---|---| | actor speeds up and slows down | sampling by input key or normalized parameter | advance and sample by distance along spline | | objects bunch on curves | sampling control-point intervals rather than arc length | use spline length and distance queries | | mesh is sideways | wrong source-mesh length axis / forward axis | identify source mesh longitudinal axis and match it | | mesh twists or flips | inconsistent up vector, roll, or extreme tangent change | set a stable up-vector convention; inspect point roll and tangents; add points at controlled bends | | visible kink at segment boundary | tangents or segment scale do not match | use spline-provided tangents at both ends; keep adjacent scale/roll continuous | | severe stretching | segment is too long for source mesh or tangent magnitude is extreme | increase segment count or author a longer/denser source mesh | | last fence gap is wrong | fixed spacing without fitting total length | recompute actual spacing from rounded interval count | | generated objects duplicate when editing | construction script is appending without cleanup | destroy/clear generated components or instances before rebuilding | | editor becomes slow while dragging points | heavy construction script, collision rebuild, or too many components | debounce/bake generation; disable unneeded collision; use ism/hism or pcg | | runtime mutation does not update queries | spline changed without final update | batch mutations and call the spline update once | | collision does not match deformation | collision disabled, stale, or expensive dynamic update | confirm collision settings; rebuild only after geometry changes; test cooked behavior | | closed-loop seam pops | missing last-to-first segment or discontinuous roll/tangent | generate closing segment and align seam properties | | camera looks unstable | tangent rotation is not the desired framing | separate position rail from look target; smooth look rotation independently | | patrol agent hits obstacles | spline is not obstacle-aware navigation | sample spline goals and move via navmesh/path following | | network clients disagree | each client mutates path independently | make spline/path state authoritative and replicate deterministic inputs or results | verification checklist - draw/debug the spline and inspect point order. - print spline length and sampled distance. - test distance 0, length / 2, and length. - test shortest and tightest segments. - test reverse and loop boundaries. - test editor reconstruction after moving, duplicating, and undoing the actor. - test collision in standalone and packaged builds. - profile component count, collision, construction script time, and runtime updates."},{"slug":"use-cases","file":"use-cases.md","title":"System selector and use cases","rawMarkdown":"# System selector and use cases\n\n## Choose by output\n\n| Desired output | Use | Avoid |\n|---|---|---|\n| Invisible path, rail, route, or transform field | Spline Component | Spline Mesh unless geometry must bend |\n| Bent road strip, pipe, cable, hose, curb, or continuous fence rail | Spline Component + one Spline Mesh Component per segment | One Spline Mesh for the whole path |\n| Rigid posts, lamps, trees, signs, or modular props | Spline Component + ISM/HISM or spawned actors | Deforming the props with Spline Mesh |\n| Road/path that raises, lowers, or paints Landscape | Landscape Splines on a dedicated Spline Edit Layer | Blueprint spline as a terrain-deformation substitute |\n| Procedural content on a line | PCG Draw Spline / spline data | Construction Script spawning thousands of actors |\n| Procedural content inside a closed shape | PCG Draw Spline Surface | Treating an open path as an area |\n| Camera motion | Spline Component for position; optional second spline/target for aim | Deriving look rotation from tangent when the camera must frame a subject |\n| AI patrol | Spline Component as route data plus explicit direction/dwell state | Using spline motion as navigation around dynamic obstacles |\n\n## Use-case decisions\n\n### Roads and paths\n\n- Use Landscape Splines when terrain conformity and terrain painting are primary.\n- Use Spline Mesh Components when road geometry is authored as deformable modular\n  segments independent of Landscape.\n- Keep road width, shoulder width, falloff, material, mesh, collision, and segment\n  length exposed as data.\n- For PCG-authored roads in UE 5.8, treat PCG Editor Mode as experimental. The 5.8\n  `Apply Spline to Component` node can write PCG spline data to an existing component.\n\n### Cables, pipes, and hoses\n\n- Use short-enough source meshes that bend without obvious shearing.\n- Ensure source mesh length axis matches the Spline Mesh `Forward Axis`.\n- Use tangent magnitude to control curvature; do not use point position alone.\n- Disable collision unless gameplay needs it. Test dynamic collision cost separately.\n\n### Fences\n\n- Deform only continuous rails or walls.\n- Place posts as rigid instances by distance.\n- Compute the final interval from spline length so the last gap is not visibly short:\n  `count = max(1, round(length / targetSpacing))`, then\n  `actualSpacing = length / count`.\n\n### Camera rails\n\n- Store travel as distance, not normalized time, if speed is specified in cm/s.\n- Use a Timeline/curve to remap time to distance for authored acceleration.\n- Use spline tangent for forward-facing travel; use `Find Look At Rotation` toward a\n  target for subject framing.\n- Apply camera easing separately from spline geometry.\n\n### Patrol paths\n\n- Track `Distance`, `Direction` (`+1` or `-1`), `SpeedCmPerSec`, and dwell state.\n- Closed loop: wrap distance by spline length.\n- Ping-pong: clamp at ends, reverse direction, then apply dwell.\n- Use NavMesh pathing between sampled spline goals if agents must avoid obstacles.\n\n### Placement along a spline\n\n- Uniform physical spacing: sample by distance.\n- One object per control point: sample by point index.\n- Orientation: use transform/rotation at distance; optionally preserve world up for\n  props that must remain vertical.\n- Random variation: seed it; separate along-path distance jitter from lateral offset.\n\n## Construction versus runtime\n\n| Need | Location |\n|---|---|\n| Designer drags points and sees generated geometry immediately | Construction Script |\n| Path is fixed after level load | Construction Script or baked editor tool |\n| Path changes during play | Runtime function called only when data changes |\n| Object travels along fixed path | Tick, Timeline, or movement task; do not rebuild spline |\n| Thousands of procedural placements | PCG or instancing; avoid individual actor construction |\n","webMarkdown":"## Choose by output\n\n| Desired output | Use | Avoid |\n|---|---|---|\n| Invisible path, rail, route, or transform field | Spline Component | Spline Mesh unless geometry must bend |\n| Bent road strip, pipe, cable, hose, curb, or continuous fence rail | Spline Component + one Spline Mesh Component per segment | One Spline Mesh for the whole path |\n| Rigid posts, lamps, trees, signs, or modular props | Spline Component + ISM/HISM or spawned actors | Deforming the props with Spline Mesh |\n| Road/path that raises, lowers, or paints Landscape | Landscape Splines on a dedicated Spline Edit Layer | Blueprint spline as a terrain-deformation substitute |\n| Procedural content on a line | PCG Draw Spline / spline data | Construction Script spawning thousands of actors |\n| Procedural content inside a closed shape | PCG Draw Spline Surface | Treating an open path as an area |\n| Camera motion | Spline Component for position; optional second spline/target for aim | Deriving look rotation from tangent when the camera must frame a subject |\n| AI patrol | Spline Component as route data plus explicit direction/dwell state | Using spline motion as navigation around dynamic obstacles |\n\n## Use-case decisions\n\n### Roads and paths\n\n- Use Landscape Splines when terrain conformity and terrain painting are primary.\n- Use Spline Mesh Components when road geometry is authored as deformable modular\n  segments independent of Landscape.\n- Keep road width, shoulder width, falloff, material, mesh, collision, and segment\n  length exposed as data.\n- For PCG-authored roads in UE 5.8, treat PCG Editor Mode as experimental. The 5.8\n  `Apply Spline to Component` node can write PCG spline data to an existing component.\n\n### Cables, pipes, and hoses\n\n- Use short-enough source meshes that bend without obvious shearing.\n- Ensure source mesh length axis matches the Spline Mesh `Forward Axis`.\n- Use tangent magnitude to control curvature; do not use point position alone.\n- Disable collision unless gameplay needs it. Test dynamic collision cost separately.\n\n### Fences\n\n- Deform only continuous rails or walls.\n- Place posts as rigid instances by distance.\n- Compute the final interval from spline length so the last gap is not visibly short:\n  `count = max(1, round(length / targetSpacing))`, then\n  `actualSpacing = length / count`.\n\n### Camera rails\n\n- Store travel as distance, not normalized time, if speed is specified in cm/s.\n- Use a Timeline/curve to remap time to distance for authored acceleration.\n- Use spline tangent for forward-facing travel; use `Find Look At Rotation` toward a\n  target for subject framing.\n- Apply camera easing separately from spline geometry.\n\n### Patrol paths\n\n- Track `Distance`, `Direction` (`+1` or `-1`), `SpeedCmPerSec`, and dwell state.\n- Closed loop: wrap distance by spline length.\n- Ping-pong: clamp at ends, reverse direction, then apply dwell.\n- Use NavMesh pathing between sampled spline goals if agents must avoid obstacles.\n\n### Placement along a spline\n\n- Uniform physical spacing: sample by distance.\n- One object per control point: sample by point index.\n- Orientation: use transform/rotation at distance; optionally preserve world up for\n  props that must remain vertical.\n- Random variation: seed it; separate along-path distance jitter from lateral offset.\n\n## Construction versus runtime\n\n| Need | Location |\n|---|---|\n| Designer drags points and sees generated geometry immediately | Construction Script |\n| Path is fixed after level load | Construction Script or baked editor tool |\n| Path changes during play | Runtime function called only when data changes |\n| Object travels along fixed path | Tick, Timeline, or movement task; do not rebuild spline |\n| Thousands of procedural placements | PCG or instancing; avoid individual actor construction |\n","searchText":"system selector and use cases choose by output | desired output | use | avoid | |---|---|---| | invisible path, rail, route, or transform field | spline component | spline mesh unless geometry must bend | | bent road strip, pipe, cable, hose, curb, or continuous fence rail | spline component + one spline mesh component per segment | one spline mesh for the whole path | | rigid posts, lamps, trees, signs, or modular props | spline component + ism/hism or spawned actors | deforming the props with spline mesh | | road/path that raises, lowers, or paints landscape | landscape splines on a dedicated spline edit layer | blueprint spline as a terrain-deformation substitute | | procedural content on a line | pcg draw spline / spline data | construction script spawning thousands of actors | | procedural content inside a closed shape | pcg draw spline surface | treating an open path as an area | | camera motion | spline component for position; optional second spline/target for aim | deriving look rotation from tangent when the camera must frame a subject | | ai patrol | spline component as route data plus explicit direction/dwell state | using spline motion as navigation around dynamic obstacles | use-case decisions roads and paths - use landscape splines when terrain conformity and terrain painting are primary. - use spline mesh components when road geometry is authored as deformable modular segments independent of landscape. - keep road width, shoulder width, falloff, material, mesh, collision, and segment length exposed as data. - for pcg-authored roads in ue 5.8, treat pcg editor mode as experimental. the 5.8 apply spline to component node can write pcg spline data to an existing component. cables, pipes, and hoses - use short-enough source meshes that bend without obvious shearing. - ensure source mesh length axis matches the spline mesh forward axis. - use tangent magnitude to control curvature; do not use point position alone. - disable collision unless gameplay needs it. test dynamic collision cost separately. fences - deform only continuous rails or walls. - place posts as rigid instances by distance. - compute the final interval from spline length so the last gap is not visibly short: count = max(1, round(length / targetspacing)), then actualspacing = length / count. camera rails - store travel as distance, not normalized time, if speed is specified in cm/s. - use a timeline/curve to remap time to distance for authored acceleration. - use spline tangent for forward-facing travel; use find look at rotation toward a target for subject framing. - apply camera easing separately from spline geometry. patrol paths - track distance, direction (+1 or -1), speedcmpersec, and dwell state. - closed loop: wrap distance by spline length. - ping-pong: clamp at ends, reverse direction, then apply dwell. - use navmesh pathing between sampled spline goals if agents must avoid obstacles. placement along a spline - uniform physical spacing: sample by distance. - one object per control point: sample by point index. - orientation: use transform/rotation at distance; optionally preserve world up for props that must remain vertical. - random variation: seed it; separate along-path distance jitter from lateral offset. construction versus runtime | need | location | |---|---| | designer drags points and sees generated geometry immediately | construction script | | path is fixed after level load | construction script or baked editor tool | | path changes during play | runtime function called only when data changes | | object travels along fixed path | tick, timeline, or movement task; do not rebuild spline | | thousands of procedural placements | pcg or instancing; avoid individual actor construction |"}]}
{"slug":"unreal-umg-commonui","name":"unreal-umg-commonui","title":"Unreal 5.8 UMG and CommonUI","description":"Design, implement, optimize, and debug game UI in Unreal Engine 5.8 with UMG and CommonUI. Use for widget architecture, HUDs, menus, modal layers, Common Activatable Widgets, input routing, Enhanced Input integration, focus, gamepad navigation, local-player ownership, split screen, responsive layout, DPI scaling, safe zones, accessibility, MVVM, event-driven updates, ListView virtualization, invalidation, pooling, or UI performance.","shortDescription":"Build scalable responsive game UI systems","category":"Presentation","referenceCount":9,"rawMarkdown":"---\nname: unreal-umg-commonui\ndescription: Design, implement, optimize, and debug game UI in Unreal Engine 5.8 with UMG and CommonUI. Use for widget architecture, HUDs, menus, modal layers, Common Activatable Widgets, input routing, Enhanced Input integration, focus, gamepad navigation, local-player ownership, split screen, responsive layout, DPI scaling, safe zones, accessibility, MVVM, event-driven updates, ListView virtualization, invalidation, pooling, or UI performance.\n---\n\n# Unreal 5.8 UMG and CommonUI\n\n## Ownership boundary\n\nThis skill owns widget lifecycle, screen layers, focus, navigation, and UI input routing. Route action,\ncontext, trigger, modifier, and key-profile semantics to\n[`unreal-enhanced-input`](../unreal-enhanced-input/SKILL.md), authoritative multiplayer state to\n[`unreal-replication`](../unreal-replication/SKILL.md), and durable slot/schema/migration policy to\n[`unreal-save-load`](../unreal-save-load/SKILL.md).\n\n## Select the UI stack\n\n- Use **UMG** for every game UI; it is the base authoring layer.\n- Add **CommonUI** when the product needs complex layered screens, robust gamepad navigation,\n  cross-platform input prompts, or consistent back/input routing.\n- Do not add CommonUI solely for a small mouse-driven HUD or a single simple menu.\n- Treat **UMG Viewmodel/MVVM as Beta in UE 5.8**. Use it when push binding and UI/backend\n  separation justify the maturity risk; otherwise use explicit delegates and setters.\n- In UE 5.8 prefer the unified CommonUI + Enhanced Input workflow. Do not copy older tutorials\n  that require a parallel UI action-data-table vocabulary unless maintaining legacy content.\n\nRead [`references/system-selector.md`](references/system-selector.md) before choosing.\n\n## Preserve the presentation boundary\n\n1. Keep authoritative gameplay state in gameplay systems, never in widgets.\n2. Expose a small local presentation model or Viewmodel per local player.\n3. Push changes into the UI with delegates, events, or FieldNotify.\n4. Let widgets submit semantic intent; let gameplay code validate and execute it.\n5. Replicate model state, not widget instances. Create and update UI locally.\n\nRead [`references/architecture-lifecycle.md`](references/architecture-lifecycle.md) and route\nnetwork-state design to `$unreal-replication`.\n\n## Build in dependency order\n\n1. Identify local-player ownership, screen layers, and the authority boundary.\n2. Establish one root layout and named HUD, menu, modal, and notification layers.\n3. Make screens activatable only when they own an input/focus boundary.\n4. Define activation, back, input mode, mouse capture, and desired-focus behavior.\n5. Build layouts with anchors, containers, DPI scaling, and Safe Zones.\n6. Push state changes; avoid Tick and raw property bindings.\n7. Virtualize long collections and load expensive, infrequent screens on demand.\n8. Test keyboard/mouse, gamepad, touch if supported, split screen, resolutions, safe zones,\n   localization expansion, and accessibility settings.\n9. Profile with Slate Insights/Unreal Insights before applying invalidation or retainers.\n\nUse [`references/commonui-routing.md`](references/commonui-routing.md),\n[`references/input-focus.md`](references/input-focus.md), and\n[`references/responsive-accessibility.md`](references/responsive-accessibility.md).\n\n## Required answer format\n\nReturn:\n\n1. **Stack choice**: UMG only, UMG + CommonUI, and whether Beta MVVM is justified.\n2. **Ownership diagram**: authoritative model, local presentation model, view, and intent path.\n3. **Layer/input/focus policy** for every screen type.\n4. **Exact implementation actions**: assets, classes, settings, nodes/APIs, and lifecycle hooks.\n5. **Responsive and accessibility matrix**.\n6. **Performance risks, measurement method, and verification checklist**.\n\nDo not invent property names, plugin maturity, focus behavior, or performance wins.\n\n## Hard rules\n\n- Never store authoritative gameplay state only in a widget.\n- Never replicate widgets or use a widget as a client-to-server RPC owner.\n- Use an owning `LocalPlayer`/`PlayerController`; prefer `AddToPlayerScreen` for player UI.\n- Do not assume `Construct` runs once; use initialization and activation hooks intentionally.\n- Do not make every CommonUI widget activatable.\n- Every gamepad screen must define a valid initial focus target and a back path.\n- Never encode critical information by color alone; support readable text scaling.\n- Avoid raw property binding, widget Tick, and nested Canvas Panels in production UI.\n- Do not add Invalidation Boxes or Retainer Panels without profiling and change-frequency analysis.\n\nRead [`references/binding-mvvm.md`](references/binding-mvvm.md),\n[`references/performance.md`](references/performance.md), and\n[`references/patterns-troubleshooting.md`](references/patterns-troubleshooting.md). See\n[`references/sources.md`](references/sources.md) for the UE 5.8 source trail.\n","webMarkdown":"## Ownership boundary\n\nThis skill owns widget lifecycle, screen layers, focus, navigation, and UI input routing. Route action,\ncontext, trigger, modifier, and key-profile semantics to\n[`unreal-enhanced-input`](/unreal/unreal-enhanced-input/), authoritative multiplayer state to\n[`unreal-replication`](/unreal/unreal-replication/), and durable slot/schema/migration policy to\n[`unreal-save-load`](/unreal/unreal-save-load/).\n\n## Select the UI stack\n\n- Use **UMG** for every game UI; it is the base authoring layer.\n- Add **CommonUI** when the product needs complex layered screens, robust gamepad navigation,\n  cross-platform input prompts, or consistent back/input routing.\n- Do not add CommonUI solely for a small mouse-driven HUD or a single simple menu.\n- Treat **UMG Viewmodel/MVVM as Beta in UE 5.8**. Use it when push binding and UI/backend\n  separation justify the maturity risk; otherwise use explicit delegates and setters.\n- In UE 5.8 prefer the unified CommonUI + Enhanced Input workflow. Do not copy older tutorials\n  that require a parallel UI action-data-table vocabulary unless maintaining legacy content.\n\nRead [`references/system-selector.md`](/unreal/unreal-umg-commonui/system-selector/) before choosing.\n\n## Preserve the presentation boundary\n\n1. Keep authoritative gameplay state in gameplay systems, never in widgets.\n2. Expose a small local presentation model or Viewmodel per local player.\n3. Push changes into the UI with delegates, events, or FieldNotify.\n4. Let widgets submit semantic intent; let gameplay code validate and execute it.\n5. Replicate model state, not widget instances. Create and update UI locally.\n\nRead [`references/architecture-lifecycle.md`](/unreal/unreal-umg-commonui/architecture-lifecycle/) and route\nnetwork-state design to `$unreal-replication`.\n\n## Build in dependency order\n\n1. Identify local-player ownership, screen layers, and the authority boundary.\n2. Establish one root layout and named HUD, menu, modal, and notification layers.\n3. Make screens activatable only when they own an input/focus boundary.\n4. Define activation, back, input mode, mouse capture, and desired-focus behavior.\n5. Build layouts with anchors, containers, DPI scaling, and Safe Zones.\n6. Push state changes; avoid Tick and raw property bindings.\n7. Virtualize long collections and load expensive, infrequent screens on demand.\n8. Test keyboard/mouse, gamepad, touch if supported, split screen, resolutions, safe zones,\n   localization expansion, and accessibility settings.\n9. Profile with Slate Insights/Unreal Insights before applying invalidation or retainers.\n\nUse [`references/commonui-routing.md`](/unreal/unreal-umg-commonui/commonui-routing/),\n[`references/input-focus.md`](/unreal/unreal-umg-commonui/input-focus/), and\n[`references/responsive-accessibility.md`](/unreal/unreal-umg-commonui/responsive-accessibility/).\n\n## Required answer format\n\nReturn:\n\n1. **Stack choice**: UMG only, UMG + CommonUI, and whether Beta MVVM is justified.\n2. **Ownership diagram**: authoritative model, local presentation model, view, and intent path.\n3. **Layer/input/focus policy** for every screen type.\n4. **Exact implementation actions**: assets, classes, settings, nodes/APIs, and lifecycle hooks.\n5. **Responsive and accessibility matrix**.\n6. **Performance risks, measurement method, and verification checklist**.\n\nDo not invent property names, plugin maturity, focus behavior, or performance wins.\n\n## Hard rules\n\n- Never store authoritative gameplay state only in a widget.\n- Never replicate widgets or use a widget as a client-to-server RPC owner.\n- Use an owning `LocalPlayer`/`PlayerController`; prefer `AddToPlayerScreen` for player UI.\n- Do not assume `Construct` runs once; use initialization and activation hooks intentionally.\n- Do not make every CommonUI widget activatable.\n- Every gamepad screen must define a valid initial focus target and a back path.\n- Never encode critical information by color alone; support readable text scaling.\n- Avoid raw property binding, widget Tick, and nested Canvas Panels in production UI.\n- Do not add Invalidation Boxes or Retainer Panels without profiling and change-frequency analysis.\n\nRead [`references/binding-mvvm.md`](/unreal/unreal-umg-commonui/binding-mvvm/),\n[`references/performance.md`](/unreal/unreal-umg-commonui/performance/), and\n[`references/patterns-troubleshooting.md`](/unreal/unreal-umg-commonui/patterns-troubleshooting/). See\n[`references/sources.md`](/unreal/unreal-umg-commonui/sources/) for the UE 5.8 source trail.\n","searchText":"unreal 5.8 umg and commonui design, implement, optimize, and debug game ui in unreal engine 5.8 with umg and commonui. use for widget architecture, huds, menus, modal layers, common activatable widgets, input routing, enhanced input integration, focus, gamepad navigation, local-player ownership, split screen, responsive layout, dpi scaling, safe zones, accessibility, mvvm, event-driven updates, listview virtualization, invalidation, pooling, or ui performance. architecture and lifecycle architecture and lifecycle ownership chain use this default chain: text server-authoritative gameplay state -> replicated actor/component/property -> local player presentation model or viewmodel -> local widget tree widget interaction -> semantic local intent -> owning playercontroller/pawn/component -> validated gameplay call or server rpc widgets are local presentation objects. they must not own canonical inventory, health, match, or save state. ui may predict presentation, but authoritative correction comes from gameplay. local-player ownership - create player ui with an owning playercontroller/localplayer. - prefer addtoplayerscreen for player-specific full-screen ui; it targets the player's viewport section. use addtoviewport only when the ui is intentionally viewport-global. - in split screen, keep one root layout/presentation model per local player. - set the owning player on world-space widget components when per-player display matters. - never fetch player zero as a substitute for correct ownership. widget lifecycle - oninitialized/nativeoninitialized: one-time instance initialization. - construct/nativeconstruct: slate construction; it may run multiple times when the widget leaves and re-enters the hierarchy. - destruct/nativedestruct: release hierarchy-time subscriptions/resources, while allowing that the uobject can still exist. - nativeonactivated/nativeondeactivated: common activatable widget screen-active lifetime. bind and unbind symmetrically. guard against duplicate delegate registration if construction or activation can repeat. keep activation-time subscriptions scoped to activation. state placement | state | owner | |---|---| | health, inventory, score, match phase | replicated gameplay model | | display-formatted health, selected tab, sorted rows | local presentation model/viewmodel | | hover, focus, animation progress | widget | | input mapping/profile | local player input subsystem/user settings | | screen stack and modal state | local root ui/commonui layer manager | failure checks - ui works for client 1 but not client 2: inspect owning local player and player-zero lookups. - callbacks duplicate after reopening: inspect construct/activation bindings and unbind path. - client ui changes but server state does not: route intent through an owned replicated actor. - listen server appears correct: repeat on a remote client; host-local ownership can hide bugs. event-driven binding and mvvm event-driven binding and mvvm default: explicit push updates 1. gameplay model exposes a typed change delegate/event. 2. local presenter subscribes and converts raw state into display state. 3. presenter calls a small widget setter such as sethealth(current, max). 4. widget updates only the affected controls. 5. unbind in the matching lifecycle hook. this keeps gameplay independent of widget classes and avoids per-frame polling. mvvm path use the umg viewmodel plugin when reusable view state and declarative bindings justify a beta dependency. 1. enable umg viewmodel. 2. create a umvvmviewmodelbase subclass or implement inotifyfieldvaluechanged in c++. 3. expose display fields with fieldnotify. 4. keep fields private/protected and mutate through setters that broadcast only on change. 5. prefer one-way-to-widget for authoritative/display state. 6. use two-way binding only for genuine editable form state; submit validated intent separately. 7. test cooked builds and reassignment paths. epic documents a current binding-invalidity caveat when a designer-bound viewmodel is reassigned in the details panel. record that mvvm is beta in ue 5.8 in the technical-risk register. replicated state to ui text server changes replicated property -> client repnotify/delegate -> local presenter or viewmodel setter -> fieldnotify/delegate -> widget update do not poll the replicated actor from a widget binding. do not play irreversible one-shot vfx solely because initial replication invoked a state onrep; distinguish current state from a newly observed event. rules - raw umg property/function binding is not the event-driven mvvm path. - directly setting a widget property can break a classic property binding. - a viewmodel formats and exposes presentation state; it does not become gameplay authority. - keep async asset/data readiness explicit with loading, ready, empty, and error states. - store list item identity in data objects, not recycled entry-widget instances. commonui routing and layers commonui routing and layers project setup 1. enable commonui and enhanced input. 2. set the game viewport client class to commongameviewportclient, or derive the custom viewport client from it. 3. in ue 5.8, enable/use the unified enhanced input support and attach commonui metadata to ui input actions as required by the project. 4. define default accept and back actions and controller/input glyph data. 5. build one root layout with explicit named layers. recommended layers | layer | typical content | container | |---|---|---| | hud | persistent nonmodal gameplay display | persistent root/content | | game menu | inventory, map, pause | activatable stack | | modal | confirmations, blocking dialogs | higher-priority activatable stack | | notification | toasts, rewards, transient messages | queue or nonblocking overlay | use a ucommonactivatablewidgetstack when only the top screen should be displayed and active. use a queue for sequential transient presentation. do not drive layer priority with scattered viewport z-orders once the ui has a layer system. activatable widget rule make a screen activatable when it is a meaningful node in the input hierarchy, needs an activation lifetime, or owns back behavior. keep leaf controls and passive display widgets as ucommonuserwidget or regular uuserwidget. on activation: 1. apply the screen's input configuration/mapping context. 2. bind activation-scoped model events. 3. establish the desired focus target. 4. start entrance presentation after valid data exists. on deactivation: 1. stop screen-owned async work and animation callbacks. 2. unbind activation-scoped events. 3. remove screen-owned input contexts/configuration. 4. let the stack restore the preceding active screen. routing mental model commonui routes input through the active activatable widget tree. the viewport hands input to the action router, which begins at the topmost painted active root and recursively checks active nodes/bindings. deactivated widgets are not routing nodes. back handling - define one universal back action. - the topmost dismissible activatable screen handles it. - a modal closes before the menu under it. - root screens either decline back or route it to an intentional product action. - never bind independent escape/gamepad-face-right handlers throughout the tree. verification - open two nested screens and a modal; back must unwind in exact reverse order. - switch mouse to gamepad at runtime; prompts and focus must update without a click. - deactivate a screen; it must no longer consume input. - reopen repeatedly; bindings and mapping contexts must not accumulate. input, focus, and navigation input, focus, and navigation define per-screen policy for each screen record: - input mode: game only, ui only, or game and ui; - mouse cursor/capture/lock policy; - enhanced input mapping contexts applied while active; - initial desired-focus widget; - back behavior; - whether gameplay input continues beneath the screen. do not let individual buttons decide global input mode. focus lifecycle 1. populate or restore screen data. 2. ensure the target widget is visible, enabled, focusable, and in the active hierarchy. 3. return/set the desired focus target during activation. 4. when a focused entry disappears, move focus to a deterministic neighbor or parent control. 5. when a modal closes, restore focus to the action that opened it when still valid. avoid arbitrary delays as a focus fix. a delay can mask invalid lifecycle or asynchronous list population. focus after the target exists, using the activation/data-ready event. navigation - build logical visual order so automatic cardinal navigation is predictable. - add explicit navigation rules only where spatial layout makes automatic choice ambiguous. - test keyboard tab/arrow navigation and gamepad cardinal navigation separately. - keep focus visible with a non-color-only indicator. - prevent focus from entering hidden, disabled, decorative, or offscreen controls. - for scroll/list screens, keep the selected entry scrolled into view. unified commonui + enhanced input - use semantic ui input actions, not hard-coded keys. - mark generic actions so commonui handles routing without broadcasting unwanted global enhanced input events. - apply screen-specific mapping contexts on activation and remove them on deactivation. - keep gameplay and ui action namespaces clear; prioritize contexts intentionally. - route remapping/profile details to $unreal-enhanced-input. split-screen check run with two local players. each player must have an independent focus user, root ui, action router/context state, and prompts. getplayercontroller(0) in reusable ui is a defect signal. common failures | symptom | check | |---|---| | gamepad moves character behind menu | input mode/context priority and screen activation | | accept fires twice | duplicate action binding or both generic and specific action paths | | focus vanishes after list refresh | recycled entry was focus target; restore by item identity | | mouse works, gamepad does not | focusability, desired focus, viewport class, navigation | | back closes wrong screen | layer priority or competing local back handlers | patterns and troubleshooting patterns and troubleshooting hud from replicated health 1. server owns and mutates health. 2. health replicates with repnotify or gas attribute delegates. 3. local presenter subscribes for the owning player. 4. presenter emits normalized value and formatted text. 5. hud updates progress/text once per change. route gas-owned health to $unreal-gas-attributes-effects and replication to $unreal-replication. pause/inventory screen 1. push an activatable screen onto the game-menu stack. 2. apply the screen input config and ui mapping context. 3. populate data before selecting desired focus. 4. back deactivates the top screen. 5. deactivation removes context/subscriptions and restores prior focus. remember that a local pause does not automatically pause an authoritative multiplayer server. inventory list - store inventory entries as item data/uobjects, not entry widgets. - use listview or tileview virtualization. - in entry initialization/assignment, overwrite every visual field and selection state. - preserve selection by stable item identity across refresh. - submit move/equip/drop intent to authoritative gameplay; wait for replicated confirmation. modal confirmation - push to the modal layer above menus. - give it an explicit default focus and cancel/back route. - disable duplicate submission after accept. - return a semantic result callback; do not let the modal mutate distant gameplay state directly. diagnostic table | symptom | likely cause | first check | |---|---|---| | ui only works for host | wrong local-player ownership or client lacks presentation hookup | remote client + owning player | | event fires repeatedly after reopen | duplicate construct/activation binding | symmetric unbind and guard | | controller cannot enter screen | no focusable desired target | activation focus path | | back leaks to gameplay | inactive/mis-layered screen or duplicate actions | action router and contexts | | list rows show stale data | pooled entry not fully reset | item-assignment handler | | screen hitches on first open | synchronous construction/asset load | trace load and split/preload | | static screen costs every frame | tick/raw bindings/invalidations | slate insights and compiler rules | | ui claims action succeeded early | local widget mutated canonical state | authoritative confirmation path | shipping gate - all screens operable with every supported input device. - deterministic focus and back behavior at every layer. - split-screen/local-player isolation verified if supported. - resolution, dpi, safe-zone, localization, and maximum-text-scale matrix passes. - remote-client state matches authoritative gameplay under latency and packet loss. - ui trace meets target budget with no growing widget/delegate count. ui performance ui performance measure first profile a representative screen on target hardware with unreal insights and slate insights. record cpu time, paint/layout invalidations, widget count, construction hitches, draw elements, and memory. apply one optimization, then re-profile. highest-value actions 1. replace raw property bindings and widget tick with events/delegates/fieldnotify. 2. remove unused children; hidden children are still loaded and constructed. 3. split huge screens into always-ready, preload, and asynchronously loaded sections. 4. use listview/tileview/treeview for large collections. they virtualize entries and create only enough entry widgets for the visible region. 5. reuse/pool dynamic widgets when churn is measured; clear all item state on reuse. 6. reduce nested canvas panels and rich text where simpler containers/text suffice. 7. avoid overlapping layers that create unnecessary slate layer/draw cost. invalidation selector - global invalidation: evaluate for broad mostly-static ui; measure project-wide behavior. - invalidation box: cache a mostly-static subtree whose geometry/paint rarely changes. - volatile widget: isolate a widget that changes every frame inside an invalidated tree. - retainer panel: flatten a subtree to a texture, optionally reducing render frequency or applying an effect; costs render-target memory and can add latency/artifacts. do not wrap constantly changing trees in invalidation and repeatedly destroy the cache benefit. do not use a retainer panel as a generic speed button. construction strategy | screen type | strategy | |---|---| | always-visible hud | create once; push small updates | | frequent critical menu | preload or keep pooled/hidden if memory permits | | rare expensive menu | async load and release when dismissed | | long inventory | virtualized list; item objects separate from entries | | transient notifications | queue + bounded pool | regression checks - open/close the screen 50 times: widget and delegate counts must stabilize. - scroll thousands of items: entry count should track visible rows, not item count. - change one field: confirm the entire tree is not invalidated unnecessarily. - profile editor and packaged target build; trust the representative target result. responsive layout and accessibility responsive layout and accessibility layout procedure 1. choose one design resolution and author screens consistently at it. 2. configure the project dpi scale rule and curve; shortest-side is the common default, not a universal law. 3. use anchors for edge/corner/center relationships. 4. prefer vertical/horizontal/grid/overlay containers to absolute canvas positioning. 5. put critical edge ui under a safe zone. 6. constrain text and dynamic content deliberately; test expansion rather than clipping it. 7. preview device profiles, aspect ratios, dpi scales, and portrait/landscape when applicable. accessibility baseline - user-adjustable text/ui scale; ue 5.8 also adds commonui.textglobalscaling for commonui text. - critical state encoded with text, icon/shape, or pattern in addition to color. - high-contrast focus state and readable selected/disabled states. - remappable semantic inputs and device-correct prompts. - captions/subtitles with size and contrast options when the game uses speech or critical sound. - toggle or scale screen shake, flashes, motion-heavy ui, and auto-advancing text where relevant. - avoid time-limited menu interactions unless the design truly requires them. test matrix test at minimum: - smallest and largest supported resolution; - 16:9, ultrawide, and supported narrow aspect ratios; - platform safe zones and mobile notches if applicable; - 100%, larger, and maximum supported ui/text scale; - keyboard/mouse, generic gamepad, and supported touch flow; - longest localized strings and right-to-left layout if supported; - color-vision simulation and grayscale readability; - focus-only operation without a pointer. failure recovery - edge content clipped: verify safe zone placement and anchors before adding offsets. - layout drifts by resolution: remove fixed pixel positioning and inspect dpi rule/curve. - large text overlaps: allow content-driven sizing/wrapping and define overflow behavior. - input glyph missing: verify active input type, platform controller data/metadata, and exact gamepad identifiers. ue 5.8 primary sources ue 5.8 primary sources all links were checked against epic's ue 5.8 documentation on 2026-07-19. commonui and input - common ui - commonui design guidelines - commonui overview - commonui input technical guide - commonui quickstart - ue 5.8 release notes: unified commonui and enhanced input - ucommonactivatablewidget - ucommonactivatablewidgetstack umg architecture, layout, and performance - umg viewmodel - umg optimization guidelines - widget designer team settings - dpi scaling - umg safe zones - uuserwidget - uuserwidget::construct - ulistview - using the invalidation box scope and maturity notes - commonui is appropriate principally for complex layered and cross-platform interfaces. - ue 5.8 release notes supersede the stale warning on the older commonui-with-enhanced-input guide by documenting the unified workflow. - umg viewmodel is marked beta in ue 5.8. system selector system selector use umg only choose plain umg when all are true: - screen layering is simple; - mouse/keyboard is primary or gamepad navigation is small; - input prompts do not need automatic platform/device swapping; - the team benefits more from a small dependency surface than commonui routing. umg remains the view layer even when commonui is added. add commonui choose commonui when one or more are load-bearing: - multiple stacked screens or modal layers; - controller-first focus and cardinal navigation; - a universal back action; - platform-specific button glyphs or runtime input-method switching; - selective input routing between overlapping ui layers. commonui is an extensive paradigm, not a general requirement. epic specifically identifies complex multi-layered and cross-platform interfaces as its main use cases. choose the update model | need | preferred mechanism | note | |---|---|---| | small explicit screen | delegates/events + widget setters | stable and easy to trace | | reusable presentation model | viewmodel + fieldnotify | mvvm is beta in ue 5.8 | | one-time construction data | expose-on-spawn/init function | do not poll it | | per-frame visual motion | umg animation/material/limited tick | profile and isolate | do not use raw property/function bindings as the default; they poll and can have a large performance impact. do not adopt beta mvvm without documenting fallback and platform testing. ue 5.8 input choice ue 5.8 release notes describe unification of enhanced input and common input/ui, including removing duplicate data assets. prefer enhanced input actions and metadata for new 5.8 work. treat older commonui action data tables as a legacy-compatible path, not the default new design. related constitution principles - gdc-l1-ux-0002: reveal complexity progressively. - gdc-l1-ux-0003: make the interface communicate. - gdc-l1-ux-0006: build accessibility in early. - gdc-l1-arch-0003: decouple cross-system reactions through events. - gdc-l1-arch-0006: distinguish authoritative from transient state.","references":[{"slug":"architecture-lifecycle","file":"architecture-lifecycle.md","title":"Architecture and lifecycle","rawMarkdown":"# Architecture and lifecycle\n\n## Ownership chain\n\nUse this default chain:\n\n```text\nserver-authoritative gameplay state\n  -> replicated actor/component/property\n  -> local player presentation model or Viewmodel\n  -> local widget tree\n\nwidget interaction\n  -> semantic local intent\n  -> owning PlayerController/Pawn/component\n  -> validated gameplay call or Server RPC\n```\n\nWidgets are local presentation objects. They must not own canonical inventory, health, match,\nor save state. UI may predict presentation, but authoritative correction comes from gameplay.\n\n## Local-player ownership\n\n- Create player UI with an owning `PlayerController`/`LocalPlayer`.\n- Prefer `AddToPlayerScreen` for player-specific full-screen UI; it targets the player's\n  viewport section. Use `AddToViewport` only when the UI is intentionally viewport-global.\n- In split screen, keep one root layout/presentation model per local player.\n- Set the owning player on world-space Widget Components when per-player display matters.\n- Never fetch player zero as a substitute for correct ownership.\n\n## Widget lifecycle\n\n- `OnInitialized`/`NativeOnInitialized`: one-time instance initialization.\n- `Construct`/`NativeConstruct`: Slate construction; it may run multiple times when the widget\n  leaves and re-enters the hierarchy.\n- `Destruct`/`NativeDestruct`: release hierarchy-time subscriptions/resources, while allowing\n  that the UObject can still exist.\n- `NativeOnActivated`/`NativeOnDeactivated`: Common Activatable Widget screen-active lifetime.\n\nBind and unbind symmetrically. Guard against duplicate delegate registration if construction or\nactivation can repeat. Keep activation-time subscriptions scoped to activation.\n\n## State placement\n\n| State | Owner |\n|---|---|\n| Health, inventory, score, match phase | Replicated gameplay model |\n| Display-formatted health, selected tab, sorted rows | Local presentation model/Viewmodel |\n| Hover, focus, animation progress | Widget |\n| Input mapping/profile | Local Player input subsystem/user settings |\n| Screen stack and modal state | Local root UI/CommonUI layer manager |\n\n## Failure checks\n\n- UI works for client 1 but not client 2: inspect owning local player and player-zero lookups.\n- callbacks duplicate after reopening: inspect Construct/activation bindings and unbind path.\n- client UI changes but server state does not: route intent through an owned replicated actor.\n- listen server appears correct: repeat on a remote client; host-local ownership can hide bugs.\n","webMarkdown":"## Ownership chain\n\nUse this default chain:\n\n```text\nserver-authoritative gameplay state\n  -> replicated actor/component/property\n  -> local player presentation model or Viewmodel\n  -> local widget tree\n\nwidget interaction\n  -> semantic local intent\n  -> owning PlayerController/Pawn/component\n  -> validated gameplay call or Server RPC\n```\n\nWidgets are local presentation objects. They must not own canonical inventory, health, match,\nor save state. UI may predict presentation, but authoritative correction comes from gameplay.\n\n## Local-player ownership\n\n- Create player UI with an owning `PlayerController`/`LocalPlayer`.\n- Prefer `AddToPlayerScreen` for player-specific full-screen UI; it targets the player's\n  viewport section. Use `AddToViewport` only when the UI is intentionally viewport-global.\n- In split screen, keep one root layout/presentation model per local player.\n- Set the owning player on world-space Widget Components when per-player display matters.\n- Never fetch player zero as a substitute for correct ownership.\n\n## Widget lifecycle\n\n- `OnInitialized`/`NativeOnInitialized`: one-time instance initialization.\n- `Construct`/`NativeConstruct`: Slate construction; it may run multiple times when the widget\n  leaves and re-enters the hierarchy.\n- `Destruct`/`NativeDestruct`: release hierarchy-time subscriptions/resources, while allowing\n  that the UObject can still exist.\n- `NativeOnActivated`/`NativeOnDeactivated`: Common Activatable Widget screen-active lifetime.\n\nBind and unbind symmetrically. Guard against duplicate delegate registration if construction or\nactivation can repeat. Keep activation-time subscriptions scoped to activation.\n\n## State placement\n\n| State | Owner |\n|---|---|\n| Health, inventory, score, match phase | Replicated gameplay model |\n| Display-formatted health, selected tab, sorted rows | Local presentation model/Viewmodel |\n| Hover, focus, animation progress | Widget |\n| Input mapping/profile | Local Player input subsystem/user settings |\n| Screen stack and modal state | Local root UI/CommonUI layer manager |\n\n## Failure checks\n\n- UI works for client 1 but not client 2: inspect owning local player and player-zero lookups.\n- callbacks duplicate after reopening: inspect Construct/activation bindings and unbind path.\n- client UI changes but server state does not: route intent through an owned replicated actor.\n- listen server appears correct: repeat on a remote client; host-local ownership can hide bugs.\n","searchText":"architecture and lifecycle ownership chain use this default chain: text server-authoritative gameplay state -> replicated actor/component/property -> local player presentation model or viewmodel -> local widget tree widget interaction -> semantic local intent -> owning playercontroller/pawn/component -> validated gameplay call or server rpc widgets are local presentation objects. they must not own canonical inventory, health, match, or save state. ui may predict presentation, but authoritative correction comes from gameplay. local-player ownership - create player ui with an owning playercontroller/localplayer. - prefer addtoplayerscreen for player-specific full-screen ui; it targets the player's viewport section. use addtoviewport only when the ui is intentionally viewport-global. - in split screen, keep one root layout/presentation model per local player. - set the owning player on world-space widget components when per-player display matters. - never fetch player zero as a substitute for correct ownership. widget lifecycle - oninitialized/nativeoninitialized: one-time instance initialization. - construct/nativeconstruct: slate construction; it may run multiple times when the widget leaves and re-enters the hierarchy. - destruct/nativedestruct: release hierarchy-time subscriptions/resources, while allowing that the uobject can still exist. - nativeonactivated/nativeondeactivated: common activatable widget screen-active lifetime. bind and unbind symmetrically. guard against duplicate delegate registration if construction or activation can repeat. keep activation-time subscriptions scoped to activation. state placement | state | owner | |---|---| | health, inventory, score, match phase | replicated gameplay model | | display-formatted health, selected tab, sorted rows | local presentation model/viewmodel | | hover, focus, animation progress | widget | | input mapping/profile | local player input subsystem/user settings | | screen stack and modal state | local root ui/commonui layer manager | failure checks - ui works for client 1 but not client 2: inspect owning local player and player-zero lookups. - callbacks duplicate after reopening: inspect construct/activation bindings and unbind path. - client ui changes but server state does not: route intent through an owned replicated actor. - listen server appears correct: repeat on a remote client; host-local ownership can hide bugs."},{"slug":"binding-mvvm","file":"binding-mvvm.md","title":"Event-driven binding and MVVM","rawMarkdown":"# Event-driven binding and MVVM\n\n## Default: explicit push updates\n\n1. Gameplay model exposes a typed change delegate/event.\n2. Local presenter subscribes and converts raw state into display state.\n3. Presenter calls a small widget setter such as `SetHealth(Current, Max)`.\n4. Widget updates only the affected controls.\n5. Unbind in the matching lifecycle hook.\n\nThis keeps gameplay independent of widget classes and avoids per-frame polling.\n\n## MVVM path\n\nUse the UMG Viewmodel plugin when reusable view state and declarative bindings justify a Beta\ndependency.\n\n1. Enable UMG Viewmodel.\n2. Create a `UMVVMViewModelBase` subclass or implement `INotifyFieldValueChanged` in C++.\n3. Expose display fields with `FieldNotify`.\n4. Keep fields private/protected and mutate through setters that broadcast only on change.\n5. Prefer one-way-to-widget for authoritative/display state.\n6. Use two-way binding only for genuine editable form state; submit validated intent separately.\n7. Test cooked builds and reassignment paths. Epic documents a current binding-invalidity caveat\n   when a designer-bound Viewmodel is reassigned in the Details panel.\n\nRecord that MVVM is **Beta in UE 5.8** in the technical-risk register.\n\n## Replicated state to UI\n\n```text\nserver changes replicated property\n  -> client RepNotify/delegate\n  -> local presenter or Viewmodel setter\n  -> FieldNotify/delegate\n  -> widget update\n```\n\nDo not poll the replicated actor from a widget binding. Do not play irreversible one-shot VFX\nsolely because initial replication invoked a state OnRep; distinguish current state from a newly\nobserved event.\n\n## Rules\n\n- Raw UMG property/function binding is not the event-driven MVVM path.\n- Directly setting a widget property can break a classic property binding.\n- A Viewmodel formats and exposes presentation state; it does not become gameplay authority.\n- Keep async asset/data readiness explicit with loading, ready, empty, and error states.\n- Store list item identity in data objects, not recycled entry-widget instances.\n","webMarkdown":"## Default: explicit push updates\n\n1. Gameplay model exposes a typed change delegate/event.\n2. Local presenter subscribes and converts raw state into display state.\n3. Presenter calls a small widget setter such as `SetHealth(Current, Max)`.\n4. Widget updates only the affected controls.\n5. Unbind in the matching lifecycle hook.\n\nThis keeps gameplay independent of widget classes and avoids per-frame polling.\n\n## MVVM path\n\nUse the UMG Viewmodel plugin when reusable view state and declarative bindings justify a Beta\ndependency.\n\n1. Enable UMG Viewmodel.\n2. Create a `UMVVMViewModelBase` subclass or implement `INotifyFieldValueChanged` in C++.\n3. Expose display fields with `FieldNotify`.\n4. Keep fields private/protected and mutate through setters that broadcast only on change.\n5. Prefer one-way-to-widget for authoritative/display state.\n6. Use two-way binding only for genuine editable form state; submit validated intent separately.\n7. Test cooked builds and reassignment paths. Epic documents a current binding-invalidity caveat\n   when a designer-bound Viewmodel is reassigned in the Details panel.\n\nRecord that MVVM is **Beta in UE 5.8** in the technical-risk register.\n\n## Replicated state to UI\n\n```text\nserver changes replicated property\n  -> client RepNotify/delegate\n  -> local presenter or Viewmodel setter\n  -> FieldNotify/delegate\n  -> widget update\n```\n\nDo not poll the replicated actor from a widget binding. Do not play irreversible one-shot VFX\nsolely because initial replication invoked a state OnRep; distinguish current state from a newly\nobserved event.\n\n## Rules\n\n- Raw UMG property/function binding is not the event-driven MVVM path.\n- Directly setting a widget property can break a classic property binding.\n- A Viewmodel formats and exposes presentation state; it does not become gameplay authority.\n- Keep async asset/data readiness explicit with loading, ready, empty, and error states.\n- Store list item identity in data objects, not recycled entry-widget instances.\n","searchText":"event-driven binding and mvvm default: explicit push updates 1. gameplay model exposes a typed change delegate/event. 2. local presenter subscribes and converts raw state into display state. 3. presenter calls a small widget setter such as sethealth(current, max). 4. widget updates only the affected controls. 5. unbind in the matching lifecycle hook. this keeps gameplay independent of widget classes and avoids per-frame polling. mvvm path use the umg viewmodel plugin when reusable view state and declarative bindings justify a beta dependency. 1. enable umg viewmodel. 2. create a umvvmviewmodelbase subclass or implement inotifyfieldvaluechanged in c++. 3. expose display fields with fieldnotify. 4. keep fields private/protected and mutate through setters that broadcast only on change. 5. prefer one-way-to-widget for authoritative/display state. 6. use two-way binding only for genuine editable form state; submit validated intent separately. 7. test cooked builds and reassignment paths. epic documents a current binding-invalidity caveat when a designer-bound viewmodel is reassigned in the details panel. record that mvvm is beta in ue 5.8 in the technical-risk register. replicated state to ui text server changes replicated property -> client repnotify/delegate -> local presenter or viewmodel setter -> fieldnotify/delegate -> widget update do not poll the replicated actor from a widget binding. do not play irreversible one-shot vfx solely because initial replication invoked a state onrep; distinguish current state from a newly observed event. rules - raw umg property/function binding is not the event-driven mvvm path. - directly setting a widget property can break a classic property binding. - a viewmodel formats and exposes presentation state; it does not become gameplay authority. - keep async asset/data readiness explicit with loading, ready, empty, and error states. - store list item identity in data objects, not recycled entry-widget instances."},{"slug":"commonui-routing","file":"commonui-routing.md","title":"CommonUI routing and layers","rawMarkdown":"# CommonUI routing and layers\n\n## Project setup\n\n1. Enable CommonUI and Enhanced Input.\n2. Set the Game Viewport Client Class to `CommonGameViewportClient`, or derive the custom\n   viewport client from it.\n3. In UE 5.8, enable/use the unified Enhanced Input support and attach CommonUI metadata to UI\n   Input Actions as required by the project.\n4. Define default Accept and Back actions and controller/input glyph data.\n5. Build one root layout with explicit named layers.\n\n## Recommended layers\n\n| Layer | Typical content | Container |\n|---|---|---|\n| HUD | persistent nonmodal gameplay display | persistent root/content |\n| Game menu | inventory, map, pause | activatable stack |\n| Modal | confirmations, blocking dialogs | higher-priority activatable stack |\n| Notification | toasts, rewards, transient messages | queue or nonblocking overlay |\n\nUse a `UCommonActivatableWidgetStack` when only the top screen should be displayed and active.\nUse a queue for sequential transient presentation. Do not drive layer priority with scattered\nviewport Z-orders once the UI has a layer system.\n\n## Activatable widget rule\n\nMake a screen activatable when it is a meaningful node in the input hierarchy, needs an\nactivation lifetime, or owns Back behavior. Keep leaf controls and passive display widgets as\n`UCommonUserWidget` or regular `UUserWidget`.\n\nOn activation:\n\n1. Apply the screen's input configuration/mapping context.\n2. Bind activation-scoped model events.\n3. Establish the desired focus target.\n4. Start entrance presentation after valid data exists.\n\nOn deactivation:\n\n1. Stop screen-owned async work and animation callbacks.\n2. Unbind activation-scoped events.\n3. Remove screen-owned input contexts/configuration.\n4. Let the stack restore the preceding active screen.\n\n## Routing mental model\n\nCommonUI routes input through the active Activatable Widget tree. The viewport hands input to\nthe action router, which begins at the topmost painted active root and recursively checks active\nnodes/bindings. Deactivated widgets are not routing nodes.\n\n## Back handling\n\n- Define one universal Back action.\n- The topmost dismissible activatable screen handles it.\n- A modal closes before the menu under it.\n- Root screens either decline Back or route it to an intentional product action.\n- Never bind independent Escape/Gamepad-Face-Right handlers throughout the tree.\n\n## Verification\n\n- Open two nested screens and a modal; Back must unwind in exact reverse order.\n- Switch mouse to gamepad at runtime; prompts and focus must update without a click.\n- Deactivate a screen; it must no longer consume input.\n- Reopen repeatedly; bindings and mapping contexts must not accumulate.\n","webMarkdown":"## Project setup\n\n1. Enable CommonUI and Enhanced Input.\n2. Set the Game Viewport Client Class to `CommonGameViewportClient`, or derive the custom\n   viewport client from it.\n3. In UE 5.8, enable/use the unified Enhanced Input support and attach CommonUI metadata to UI\n   Input Actions as required by the project.\n4. Define default Accept and Back actions and controller/input glyph data.\n5. Build one root layout with explicit named layers.\n\n## Recommended layers\n\n| Layer | Typical content | Container |\n|---|---|---|\n| HUD | persistent nonmodal gameplay display | persistent root/content |\n| Game menu | inventory, map, pause | activatable stack |\n| Modal | confirmations, blocking dialogs | higher-priority activatable stack |\n| Notification | toasts, rewards, transient messages | queue or nonblocking overlay |\n\nUse a `UCommonActivatableWidgetStack` when only the top screen should be displayed and active.\nUse a queue for sequential transient presentation. Do not drive layer priority with scattered\nviewport Z-orders once the UI has a layer system.\n\n## Activatable widget rule\n\nMake a screen activatable when it is a meaningful node in the input hierarchy, needs an\nactivation lifetime, or owns Back behavior. Keep leaf controls and passive display widgets as\n`UCommonUserWidget` or regular `UUserWidget`.\n\nOn activation:\n\n1. Apply the screen's input configuration/mapping context.\n2. Bind activation-scoped model events.\n3. Establish the desired focus target.\n4. Start entrance presentation after valid data exists.\n\nOn deactivation:\n\n1. Stop screen-owned async work and animation callbacks.\n2. Unbind activation-scoped events.\n3. Remove screen-owned input contexts/configuration.\n4. Let the stack restore the preceding active screen.\n\n## Routing mental model\n\nCommonUI routes input through the active Activatable Widget tree. The viewport hands input to\nthe action router, which begins at the topmost painted active root and recursively checks active\nnodes/bindings. Deactivated widgets are not routing nodes.\n\n## Back handling\n\n- Define one universal Back action.\n- The topmost dismissible activatable screen handles it.\n- A modal closes before the menu under it.\n- Root screens either decline Back or route it to an intentional product action.\n- Never bind independent Escape/Gamepad-Face-Right handlers throughout the tree.\n\n## Verification\n\n- Open two nested screens and a modal; Back must unwind in exact reverse order.\n- Switch mouse to gamepad at runtime; prompts and focus must update without a click.\n- Deactivate a screen; it must no longer consume input.\n- Reopen repeatedly; bindings and mapping contexts must not accumulate.\n","searchText":"commonui routing and layers project setup 1. enable commonui and enhanced input. 2. set the game viewport client class to commongameviewportclient, or derive the custom viewport client from it. 3. in ue 5.8, enable/use the unified enhanced input support and attach commonui metadata to ui input actions as required by the project. 4. define default accept and back actions and controller/input glyph data. 5. build one root layout with explicit named layers. recommended layers | layer | typical content | container | |---|---|---| | hud | persistent nonmodal gameplay display | persistent root/content | | game menu | inventory, map, pause | activatable stack | | modal | confirmations, blocking dialogs | higher-priority activatable stack | | notification | toasts, rewards, transient messages | queue or nonblocking overlay | use a ucommonactivatablewidgetstack when only the top screen should be displayed and active. use a queue for sequential transient presentation. do not drive layer priority with scattered viewport z-orders once the ui has a layer system. activatable widget rule make a screen activatable when it is a meaningful node in the input hierarchy, needs an activation lifetime, or owns back behavior. keep leaf controls and passive display widgets as ucommonuserwidget or regular uuserwidget. on activation: 1. apply the screen's input configuration/mapping context. 2. bind activation-scoped model events. 3. establish the desired focus target. 4. start entrance presentation after valid data exists. on deactivation: 1. stop screen-owned async work and animation callbacks. 2. unbind activation-scoped events. 3. remove screen-owned input contexts/configuration. 4. let the stack restore the preceding active screen. routing mental model commonui routes input through the active activatable widget tree. the viewport hands input to the action router, which begins at the topmost painted active root and recursively checks active nodes/bindings. deactivated widgets are not routing nodes. back handling - define one universal back action. - the topmost dismissible activatable screen handles it. - a modal closes before the menu under it. - root screens either decline back or route it to an intentional product action. - never bind independent escape/gamepad-face-right handlers throughout the tree. verification - open two nested screens and a modal; back must unwind in exact reverse order. - switch mouse to gamepad at runtime; prompts and focus must update without a click. - deactivate a screen; it must no longer consume input. - reopen repeatedly; bindings and mapping contexts must not accumulate."},{"slug":"input-focus","file":"input-focus.md","title":"Input, focus, and navigation","rawMarkdown":"# Input, focus, and navigation\n\n## Define per-screen policy\n\nFor each screen record:\n\n- input mode: game only, UI only, or game and UI;\n- mouse cursor/capture/lock policy;\n- Enhanced Input Mapping Contexts applied while active;\n- initial desired-focus widget;\n- Back behavior;\n- whether gameplay input continues beneath the screen.\n\nDo not let individual buttons decide global input mode.\n\n## Focus lifecycle\n\n1. Populate or restore screen data.\n2. Ensure the target widget is visible, enabled, focusable, and in the active hierarchy.\n3. Return/set the desired focus target during activation.\n4. When a focused entry disappears, move focus to a deterministic neighbor or parent control.\n5. When a modal closes, restore focus to the action that opened it when still valid.\n\nAvoid arbitrary delays as a focus fix. A delay can mask invalid lifecycle or asynchronous list\npopulation. Focus after the target exists, using the activation/data-ready event.\n\n## Navigation\n\n- Build logical visual order so automatic cardinal navigation is predictable.\n- Add explicit navigation rules only where spatial layout makes automatic choice ambiguous.\n- Test keyboard Tab/arrow navigation and gamepad cardinal navigation separately.\n- Keep focus visible with a non-color-only indicator.\n- Prevent focus from entering hidden, disabled, decorative, or offscreen controls.\n- For scroll/list screens, keep the selected entry scrolled into view.\n\n## Unified CommonUI + Enhanced Input\n\n- Use semantic UI Input Actions, not hard-coded keys.\n- Mark generic actions so CommonUI handles routing without broadcasting unwanted global\n  Enhanced Input events.\n- Apply screen-specific Mapping Contexts on activation and remove them on deactivation.\n- Keep gameplay and UI action namespaces clear; prioritize contexts intentionally.\n- Route remapping/profile details to `$unreal-enhanced-input`.\n\n## Split-screen check\n\nRun with two local players. Each player must have an independent focus user, root UI, action\nrouter/context state, and prompts. `GetPlayerController(0)` in reusable UI is a defect signal.\n\n## Common failures\n\n| Symptom | Check |\n|---|---|\n| Gamepad moves character behind menu | input mode/context priority and screen activation |\n| Accept fires twice | duplicate action binding or both generic and specific action paths |\n| Focus vanishes after list refresh | recycled entry was focus target; restore by item identity |\n| Mouse works, gamepad does not | focusability, desired focus, viewport class, navigation |\n| Back closes wrong screen | layer priority or competing local Back handlers |\n","webMarkdown":"## Define per-screen policy\n\nFor each screen record:\n\n- input mode: game only, UI only, or game and UI;\n- mouse cursor/capture/lock policy;\n- Enhanced Input Mapping Contexts applied while active;\n- initial desired-focus widget;\n- Back behavior;\n- whether gameplay input continues beneath the screen.\n\nDo not let individual buttons decide global input mode.\n\n## Focus lifecycle\n\n1. Populate or restore screen data.\n2. Ensure the target widget is visible, enabled, focusable, and in the active hierarchy.\n3. Return/set the desired focus target during activation.\n4. When a focused entry disappears, move focus to a deterministic neighbor or parent control.\n5. When a modal closes, restore focus to the action that opened it when still valid.\n\nAvoid arbitrary delays as a focus fix. A delay can mask invalid lifecycle or asynchronous list\npopulation. Focus after the target exists, using the activation/data-ready event.\n\n## Navigation\n\n- Build logical visual order so automatic cardinal navigation is predictable.\n- Add explicit navigation rules only where spatial layout makes automatic choice ambiguous.\n- Test keyboard Tab/arrow navigation and gamepad cardinal navigation separately.\n- Keep focus visible with a non-color-only indicator.\n- Prevent focus from entering hidden, disabled, decorative, or offscreen controls.\n- For scroll/list screens, keep the selected entry scrolled into view.\n\n## Unified CommonUI + Enhanced Input\n\n- Use semantic UI Input Actions, not hard-coded keys.\n- Mark generic actions so CommonUI handles routing without broadcasting unwanted global\n  Enhanced Input events.\n- Apply screen-specific Mapping Contexts on activation and remove them on deactivation.\n- Keep gameplay and UI action namespaces clear; prioritize contexts intentionally.\n- Route remapping/profile details to `$unreal-enhanced-input`.\n\n## Split-screen check\n\nRun with two local players. Each player must have an independent focus user, root UI, action\nrouter/context state, and prompts. `GetPlayerController(0)` in reusable UI is a defect signal.\n\n## Common failures\n\n| Symptom | Check |\n|---|---|\n| Gamepad moves character behind menu | input mode/context priority and screen activation |\n| Accept fires twice | duplicate action binding or both generic and specific action paths |\n| Focus vanishes after list refresh | recycled entry was focus target; restore by item identity |\n| Mouse works, gamepad does not | focusability, desired focus, viewport class, navigation |\n| Back closes wrong screen | layer priority or competing local Back handlers |\n","searchText":"input, focus, and navigation define per-screen policy for each screen record: - input mode: game only, ui only, or game and ui; - mouse cursor/capture/lock policy; - enhanced input mapping contexts applied while active; - initial desired-focus widget; - back behavior; - whether gameplay input continues beneath the screen. do not let individual buttons decide global input mode. focus lifecycle 1. populate or restore screen data. 2. ensure the target widget is visible, enabled, focusable, and in the active hierarchy. 3. return/set the desired focus target during activation. 4. when a focused entry disappears, move focus to a deterministic neighbor or parent control. 5. when a modal closes, restore focus to the action that opened it when still valid. avoid arbitrary delays as a focus fix. a delay can mask invalid lifecycle or asynchronous list population. focus after the target exists, using the activation/data-ready event. navigation - build logical visual order so automatic cardinal navigation is predictable. - add explicit navigation rules only where spatial layout makes automatic choice ambiguous. - test keyboard tab/arrow navigation and gamepad cardinal navigation separately. - keep focus visible with a non-color-only indicator. - prevent focus from entering hidden, disabled, decorative, or offscreen controls. - for scroll/list screens, keep the selected entry scrolled into view. unified commonui + enhanced input - use semantic ui input actions, not hard-coded keys. - mark generic actions so commonui handles routing without broadcasting unwanted global enhanced input events. - apply screen-specific mapping contexts on activation and remove them on deactivation. - keep gameplay and ui action namespaces clear; prioritize contexts intentionally. - route remapping/profile details to $unreal-enhanced-input. split-screen check run with two local players. each player must have an independent focus user, root ui, action router/context state, and prompts. getplayercontroller(0) in reusable ui is a defect signal. common failures | symptom | check | |---|---| | gamepad moves character behind menu | input mode/context priority and screen activation | | accept fires twice | duplicate action binding or both generic and specific action paths | | focus vanishes after list refresh | recycled entry was focus target; restore by item identity | | mouse works, gamepad does not | focusability, desired focus, viewport class, navigation | | back closes wrong screen | layer priority or competing local back handlers |"},{"slug":"patterns-troubleshooting","file":"patterns-troubleshooting.md","title":"Patterns and troubleshooting","rawMarkdown":"# Patterns and troubleshooting\n\n## HUD from replicated health\n\n1. Server owns and mutates health.\n2. Health replicates with RepNotify or GAS attribute delegates.\n3. Local presenter subscribes for the owning player.\n4. Presenter emits normalized value and formatted text.\n5. HUD updates progress/text once per change.\n\nRoute GAS-owned health to `$unreal-gas-attributes-effects` and replication to\n`$unreal-replication`.\n\n## Pause/inventory screen\n\n1. Push an activatable screen onto the game-menu stack.\n2. Apply the screen input config and UI Mapping Context.\n3. Populate data before selecting desired focus.\n4. Back deactivates the top screen.\n5. Deactivation removes context/subscriptions and restores prior focus.\n\nRemember that a local pause does not automatically pause an authoritative multiplayer server.\n\n## Inventory list\n\n- Store inventory entries as item data/UObjects, not entry widgets.\n- Use `ListView` or `TileView` virtualization.\n- In entry initialization/assignment, overwrite every visual field and selection state.\n- Preserve selection by stable item identity across refresh.\n- Submit move/equip/drop intent to authoritative gameplay; wait for replicated confirmation.\n\n## Modal confirmation\n\n- Push to the modal layer above menus.\n- Give it an explicit default focus and cancel/Back route.\n- Disable duplicate submission after accept.\n- Return a semantic result callback; do not let the modal mutate distant gameplay state directly.\n\n## Diagnostic table\n\n| Symptom | Likely cause | First check |\n|---|---|---|\n| UI only works for host | wrong local-player ownership or client lacks presentation hookup | remote client + owning player |\n| Event fires repeatedly after reopen | duplicate Construct/activation binding | symmetric unbind and guard |\n| Controller cannot enter screen | no focusable desired target | activation focus path |\n| Back leaks to gameplay | inactive/mis-layered screen or duplicate actions | action router and contexts |\n| List rows show stale data | pooled entry not fully reset | item-assignment handler |\n| Screen hitches on first open | synchronous construction/asset load | trace load and split/preload |\n| Static screen costs every frame | Tick/raw bindings/invalidations | Slate Insights and compiler rules |\n| UI claims action succeeded early | local widget mutated canonical state | authoritative confirmation path |\n\n## Shipping gate\n\n- All screens operable with every supported input device.\n- Deterministic focus and Back behavior at every layer.\n- Split-screen/local-player isolation verified if supported.\n- Resolution, DPI, safe-zone, localization, and maximum-text-scale matrix passes.\n- Remote-client state matches authoritative gameplay under latency and packet loss.\n- UI trace meets target budget with no growing widget/delegate count.\n","webMarkdown":"## HUD from replicated health\n\n1. Server owns and mutates health.\n2. Health replicates with RepNotify or GAS attribute delegates.\n3. Local presenter subscribes for the owning player.\n4. Presenter emits normalized value and formatted text.\n5. HUD updates progress/text once per change.\n\nRoute GAS-owned health to `$unreal-gas-attributes-effects` and replication to\n`$unreal-replication`.\n\n## Pause/inventory screen\n\n1. Push an activatable screen onto the game-menu stack.\n2. Apply the screen input config and UI Mapping Context.\n3. Populate data before selecting desired focus.\n4. Back deactivates the top screen.\n5. Deactivation removes context/subscriptions and restores prior focus.\n\nRemember that a local pause does not automatically pause an authoritative multiplayer server.\n\n## Inventory list\n\n- Store inventory entries as item data/UObjects, not entry widgets.\n- Use `ListView` or `TileView` virtualization.\n- In entry initialization/assignment, overwrite every visual field and selection state.\n- Preserve selection by stable item identity across refresh.\n- Submit move/equip/drop intent to authoritative gameplay; wait for replicated confirmation.\n\n## Modal confirmation\n\n- Push to the modal layer above menus.\n- Give it an explicit default focus and cancel/Back route.\n- Disable duplicate submission after accept.\n- Return a semantic result callback; do not let the modal mutate distant gameplay state directly.\n\n## Diagnostic table\n\n| Symptom | Likely cause | First check |\n|---|---|---|\n| UI only works for host | wrong local-player ownership or client lacks presentation hookup | remote client + owning player |\n| Event fires repeatedly after reopen | duplicate Construct/activation binding | symmetric unbind and guard |\n| Controller cannot enter screen | no focusable desired target | activation focus path |\n| Back leaks to gameplay | inactive/mis-layered screen or duplicate actions | action router and contexts |\n| List rows show stale data | pooled entry not fully reset | item-assignment handler |\n| Screen hitches on first open | synchronous construction/asset load | trace load and split/preload |\n| Static screen costs every frame | Tick/raw bindings/invalidations | Slate Insights and compiler rules |\n| UI claims action succeeded early | local widget mutated canonical state | authoritative confirmation path |\n\n## Shipping gate\n\n- All screens operable with every supported input device.\n- Deterministic focus and Back behavior at every layer.\n- Split-screen/local-player isolation verified if supported.\n- Resolution, DPI, safe-zone, localization, and maximum-text-scale matrix passes.\n- Remote-client state matches authoritative gameplay under latency and packet loss.\n- UI trace meets target budget with no growing widget/delegate count.\n","searchText":"patterns and troubleshooting hud from replicated health 1. server owns and mutates health. 2. health replicates with repnotify or gas attribute delegates. 3. local presenter subscribes for the owning player. 4. presenter emits normalized value and formatted text. 5. hud updates progress/text once per change. route gas-owned health to $unreal-gas-attributes-effects and replication to $unreal-replication. pause/inventory screen 1. push an activatable screen onto the game-menu stack. 2. apply the screen input config and ui mapping context. 3. populate data before selecting desired focus. 4. back deactivates the top screen. 5. deactivation removes context/subscriptions and restores prior focus. remember that a local pause does not automatically pause an authoritative multiplayer server. inventory list - store inventory entries as item data/uobjects, not entry widgets. - use listview or tileview virtualization. - in entry initialization/assignment, overwrite every visual field and selection state. - preserve selection by stable item identity across refresh. - submit move/equip/drop intent to authoritative gameplay; wait for replicated confirmation. modal confirmation - push to the modal layer above menus. - give it an explicit default focus and cancel/back route. - disable duplicate submission after accept. - return a semantic result callback; do not let the modal mutate distant gameplay state directly. diagnostic table | symptom | likely cause | first check | |---|---|---| | ui only works for host | wrong local-player ownership or client lacks presentation hookup | remote client + owning player | | event fires repeatedly after reopen | duplicate construct/activation binding | symmetric unbind and guard | | controller cannot enter screen | no focusable desired target | activation focus path | | back leaks to gameplay | inactive/mis-layered screen or duplicate actions | action router and contexts | | list rows show stale data | pooled entry not fully reset | item-assignment handler | | screen hitches on first open | synchronous construction/asset load | trace load and split/preload | | static screen costs every frame | tick/raw bindings/invalidations | slate insights and compiler rules | | ui claims action succeeded early | local widget mutated canonical state | authoritative confirmation path | shipping gate - all screens operable with every supported input device. - deterministic focus and back behavior at every layer. - split-screen/local-player isolation verified if supported. - resolution, dpi, safe-zone, localization, and maximum-text-scale matrix passes. - remote-client state matches authoritative gameplay under latency and packet loss. - ui trace meets target budget with no growing widget/delegate count."},{"slug":"performance","file":"performance.md","title":"UI performance","rawMarkdown":"# UI performance\n\n## Measure first\n\nProfile a representative screen on target hardware with Unreal Insights and Slate Insights.\nRecord CPU time, paint/layout invalidations, widget count, construction hitches, draw elements,\nand memory. Apply one optimization, then re-profile.\n\n## Highest-value actions\n\n1. Replace raw property bindings and widget Tick with events/delegates/FieldNotify.\n2. Remove unused children; hidden children are still loaded and constructed.\n3. Split huge screens into always-ready, preload, and asynchronously loaded sections.\n4. Use `ListView`/`TileView`/`TreeView` for large collections. They virtualize entries and create\n   only enough entry widgets for the visible region.\n5. Reuse/pool dynamic widgets when churn is measured; clear all item state on reuse.\n6. Reduce nested Canvas Panels and rich text where simpler containers/text suffice.\n7. Avoid overlapping layers that create unnecessary Slate layer/draw cost.\n\n## Invalidation selector\n\n- **Global Invalidation**: evaluate for broad mostly-static UI; measure project-wide behavior.\n- **Invalidation Box**: cache a mostly-static subtree whose geometry/paint rarely changes.\n- **Volatile widget**: isolate a widget that changes every frame inside an invalidated tree.\n- **Retainer Panel**: flatten a subtree to a texture, optionally reducing render frequency or\n  applying an effect; costs render-target memory and can add latency/artifacts.\n\nDo not wrap constantly changing trees in invalidation and repeatedly destroy the cache benefit.\nDo not use a Retainer Panel as a generic speed button.\n\n## Construction strategy\n\n| Screen type | Strategy |\n|---|---|\n| Always-visible HUD | create once; push small updates |\n| Frequent critical menu | preload or keep pooled/hidden if memory permits |\n| Rare expensive menu | async load and release when dismissed |\n| Long inventory | virtualized list; item objects separate from entries |\n| Transient notifications | queue + bounded pool |\n\n## Regression checks\n\n- Open/close the screen 50 times: widget and delegate counts must stabilize.\n- Scroll thousands of items: entry count should track visible rows, not item count.\n- Change one field: confirm the entire tree is not invalidated unnecessarily.\n- Profile editor and packaged target build; trust the representative target result.\n","webMarkdown":"## Measure first\n\nProfile a representative screen on target hardware with Unreal Insights and Slate Insights.\nRecord CPU time, paint/layout invalidations, widget count, construction hitches, draw elements,\nand memory. Apply one optimization, then re-profile.\n\n## Highest-value actions\n\n1. Replace raw property bindings and widget Tick with events/delegates/FieldNotify.\n2. Remove unused children; hidden children are still loaded and constructed.\n3. Split huge screens into always-ready, preload, and asynchronously loaded sections.\n4. Use `ListView`/`TileView`/`TreeView` for large collections. They virtualize entries and create\n   only enough entry widgets for the visible region.\n5. Reuse/pool dynamic widgets when churn is measured; clear all item state on reuse.\n6. Reduce nested Canvas Panels and rich text where simpler containers/text suffice.\n7. Avoid overlapping layers that create unnecessary Slate layer/draw cost.\n\n## Invalidation selector\n\n- **Global Invalidation**: evaluate for broad mostly-static UI; measure project-wide behavior.\n- **Invalidation Box**: cache a mostly-static subtree whose geometry/paint rarely changes.\n- **Volatile widget**: isolate a widget that changes every frame inside an invalidated tree.\n- **Retainer Panel**: flatten a subtree to a texture, optionally reducing render frequency or\n  applying an effect; costs render-target memory and can add latency/artifacts.\n\nDo not wrap constantly changing trees in invalidation and repeatedly destroy the cache benefit.\nDo not use a Retainer Panel as a generic speed button.\n\n## Construction strategy\n\n| Screen type | Strategy |\n|---|---|\n| Always-visible HUD | create once; push small updates |\n| Frequent critical menu | preload or keep pooled/hidden if memory permits |\n| Rare expensive menu | async load and release when dismissed |\n| Long inventory | virtualized list; item objects separate from entries |\n| Transient notifications | queue + bounded pool |\n\n## Regression checks\n\n- Open/close the screen 50 times: widget and delegate counts must stabilize.\n- Scroll thousands of items: entry count should track visible rows, not item count.\n- Change one field: confirm the entire tree is not invalidated unnecessarily.\n- Profile editor and packaged target build; trust the representative target result.\n","searchText":"ui performance measure first profile a representative screen on target hardware with unreal insights and slate insights. record cpu time, paint/layout invalidations, widget count, construction hitches, draw elements, and memory. apply one optimization, then re-profile. highest-value actions 1. replace raw property bindings and widget tick with events/delegates/fieldnotify. 2. remove unused children; hidden children are still loaded and constructed. 3. split huge screens into always-ready, preload, and asynchronously loaded sections. 4. use listview/tileview/treeview for large collections. they virtualize entries and create only enough entry widgets for the visible region. 5. reuse/pool dynamic widgets when churn is measured; clear all item state on reuse. 6. reduce nested canvas panels and rich text where simpler containers/text suffice. 7. avoid overlapping layers that create unnecessary slate layer/draw cost. invalidation selector - global invalidation: evaluate for broad mostly-static ui; measure project-wide behavior. - invalidation box: cache a mostly-static subtree whose geometry/paint rarely changes. - volatile widget: isolate a widget that changes every frame inside an invalidated tree. - retainer panel: flatten a subtree to a texture, optionally reducing render frequency or applying an effect; costs render-target memory and can add latency/artifacts. do not wrap constantly changing trees in invalidation and repeatedly destroy the cache benefit. do not use a retainer panel as a generic speed button. construction strategy | screen type | strategy | |---|---| | always-visible hud | create once; push small updates | | frequent critical menu | preload or keep pooled/hidden if memory permits | | rare expensive menu | async load and release when dismissed | | long inventory | virtualized list; item objects separate from entries | | transient notifications | queue + bounded pool | regression checks - open/close the screen 50 times: widget and delegate counts must stabilize. - scroll thousands of items: entry count should track visible rows, not item count. - change one field: confirm the entire tree is not invalidated unnecessarily. - profile editor and packaged target build; trust the representative target result."},{"slug":"responsive-accessibility","file":"responsive-accessibility.md","title":"Responsive layout and accessibility","rawMarkdown":"# Responsive layout and accessibility\n\n## Layout procedure\n\n1. Choose one design resolution and author screens consistently at it.\n2. Configure the project DPI Scale Rule and curve; shortest-side is the common default, not a\n   universal law.\n3. Use anchors for edge/corner/center relationships.\n4. Prefer Vertical/Horizontal/Grid/Overlay containers to absolute Canvas positioning.\n5. Put critical edge UI under a Safe Zone.\n6. Constrain text and dynamic content deliberately; test expansion rather than clipping it.\n7. Preview device profiles, aspect ratios, DPI scales, and portrait/landscape when applicable.\n\n## Accessibility baseline\n\n- User-adjustable text/UI scale; UE 5.8 also adds `CommonUI.TextGlobalScaling` for CommonUI text.\n- Critical state encoded with text, icon/shape, or pattern in addition to color.\n- High-contrast focus state and readable selected/disabled states.\n- Remappable semantic inputs and device-correct prompts.\n- Captions/subtitles with size and contrast options when the game uses speech or critical sound.\n- Toggle or scale screen shake, flashes, motion-heavy UI, and auto-advancing text where relevant.\n- Avoid time-limited menu interactions unless the design truly requires them.\n\n## Test matrix\n\nTest at minimum:\n\n- smallest and largest supported resolution;\n- 16:9, ultrawide, and supported narrow aspect ratios;\n- platform safe zones and mobile notches if applicable;\n- 100%, larger, and maximum supported UI/text scale;\n- keyboard/mouse, generic gamepad, and supported touch flow;\n- longest localized strings and right-to-left layout if supported;\n- color-vision simulation and grayscale readability;\n- focus-only operation without a pointer.\n\n## Failure recovery\n\n- Edge content clipped: verify Safe Zone placement and anchors before adding offsets.\n- Layout drifts by resolution: remove fixed pixel positioning and inspect DPI rule/curve.\n- Large text overlaps: allow content-driven sizing/wrapping and define overflow behavior.\n- Input glyph missing: verify active input type, platform Controller Data/metadata, and exact\n  gamepad identifiers.\n","webMarkdown":"## Layout procedure\n\n1. Choose one design resolution and author screens consistently at it.\n2. Configure the project DPI Scale Rule and curve; shortest-side is the common default, not a\n   universal law.\n3. Use anchors for edge/corner/center relationships.\n4. Prefer Vertical/Horizontal/Grid/Overlay containers to absolute Canvas positioning.\n5. Put critical edge UI under a Safe Zone.\n6. Constrain text and dynamic content deliberately; test expansion rather than clipping it.\n7. Preview device profiles, aspect ratios, DPI scales, and portrait/landscape when applicable.\n\n## Accessibility baseline\n\n- User-adjustable text/UI scale; UE 5.8 also adds `CommonUI.TextGlobalScaling` for CommonUI text.\n- Critical state encoded with text, icon/shape, or pattern in addition to color.\n- High-contrast focus state and readable selected/disabled states.\n- Remappable semantic inputs and device-correct prompts.\n- Captions/subtitles with size and contrast options when the game uses speech or critical sound.\n- Toggle or scale screen shake, flashes, motion-heavy UI, and auto-advancing text where relevant.\n- Avoid time-limited menu interactions unless the design truly requires them.\n\n## Test matrix\n\nTest at minimum:\n\n- smallest and largest supported resolution;\n- 16:9, ultrawide, and supported narrow aspect ratios;\n- platform safe zones and mobile notches if applicable;\n- 100%, larger, and maximum supported UI/text scale;\n- keyboard/mouse, generic gamepad, and supported touch flow;\n- longest localized strings and right-to-left layout if supported;\n- color-vision simulation and grayscale readability;\n- focus-only operation without a pointer.\n\n## Failure recovery\n\n- Edge content clipped: verify Safe Zone placement and anchors before adding offsets.\n- Layout drifts by resolution: remove fixed pixel positioning and inspect DPI rule/curve.\n- Large text overlaps: allow content-driven sizing/wrapping and define overflow behavior.\n- Input glyph missing: verify active input type, platform Controller Data/metadata, and exact\n  gamepad identifiers.\n","searchText":"responsive layout and accessibility layout procedure 1. choose one design resolution and author screens consistently at it. 2. configure the project dpi scale rule and curve; shortest-side is the common default, not a universal law. 3. use anchors for edge/corner/center relationships. 4. prefer vertical/horizontal/grid/overlay containers to absolute canvas positioning. 5. put critical edge ui under a safe zone. 6. constrain text and dynamic content deliberately; test expansion rather than clipping it. 7. preview device profiles, aspect ratios, dpi scales, and portrait/landscape when applicable. accessibility baseline - user-adjustable text/ui scale; ue 5.8 also adds commonui.textglobalscaling for commonui text. - critical state encoded with text, icon/shape, or pattern in addition to color. - high-contrast focus state and readable selected/disabled states. - remappable semantic inputs and device-correct prompts. - captions/subtitles with size and contrast options when the game uses speech or critical sound. - toggle or scale screen shake, flashes, motion-heavy ui, and auto-advancing text where relevant. - avoid time-limited menu interactions unless the design truly requires them. test matrix test at minimum: - smallest and largest supported resolution; - 16:9, ultrawide, and supported narrow aspect ratios; - platform safe zones and mobile notches if applicable; - 100%, larger, and maximum supported ui/text scale; - keyboard/mouse, generic gamepad, and supported touch flow; - longest localized strings and right-to-left layout if supported; - color-vision simulation and grayscale readability; - focus-only operation without a pointer. failure recovery - edge content clipped: verify safe zone placement and anchors before adding offsets. - layout drifts by resolution: remove fixed pixel positioning and inspect dpi rule/curve. - large text overlaps: allow content-driven sizing/wrapping and define overflow behavior. - input glyph missing: verify active input type, platform controller data/metadata, and exact gamepad identifiers."},{"slug":"sources","file":"sources.md","title":"UE 5.8 primary sources","rawMarkdown":"# UE 5.8 primary sources\n\nAll links were checked against Epic's UE 5.8 documentation on 2026-07-19.\n\n## CommonUI and input\n\n- [Common UI](https://dev.epicgames.com/documentation/en-us/unreal-engine/common-ui-plugin-for-advanced-user-interfaces-in-unreal-engine)\n- [CommonUI design guidelines](https://dev.epicgames.com/documentation/en-us/unreal-engine/design-guidelines-for-using-commonui-in-unreal-engine)\n- [CommonUI overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/overview-of-advanced-multiplatform-user-interfaces-with-common-ui-for-unreal-engine)\n- [CommonUI input technical guide](https://dev.epicgames.com/documentation/en-us/unreal-engine/commonui-input-technical-guide-for-unreal-engine)\n- [CommonUI quickstart](https://dev.epicgames.com/documentation/en-us/unreal-engine/common-ui-quickstart-guide-for-unreal-engine)\n- [UE 5.8 release notes: unified CommonUI and Enhanced Input](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-8-release-notes)\n- [`UCommonActivatableWidget`](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/CommonUI/UCommonActivatableWidget)\n- [`UCommonActivatableWidgetStack`](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/CommonUI/UCommonActivatableWidgetStack)\n\n## UMG architecture, layout, and performance\n\n- [UMG Viewmodel](https://dev.epicgames.com/documentation/en-us/unreal-engine/umg-viewmodel-for-unreal-engine)\n- [UMG optimization guidelines](https://dev.epicgames.com/documentation/en-us/unreal-engine/optimization-guidelines-for-umg-in-unreal-engine)\n- [Widget Designer team settings](https://dev.epicgames.com/documentation/en-us/unreal-engine/widget-designer-team-settings-in-the-unreal-engine-project-settings)\n- [DPI scaling](https://dev.epicgames.com/documentation/en-us/unreal-engine/dpi-scaling-in-unreal-engine)\n- [UMG Safe Zones](https://dev.epicgames.com/documentation/en-us/unreal-engine/umg-safe-zones-in-unreal-engine)\n- [`UUserWidget`](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/UMG/UUserWidget)\n- [`UUserWidget::Construct`](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/UMG/UUserWidget/Construct)\n- [`UListView`](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/UMG/UListView)\n- [Using the Invalidation Box](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-the-invalidation-box-for-umg-in-unreal-engine)\n\n## Scope and maturity notes\n\n- CommonUI is appropriate principally for complex layered and cross-platform interfaces.\n- UE 5.8 release notes supersede the stale warning on the older CommonUI-with-Enhanced-Input\n  guide by documenting the unified workflow.\n- UMG Viewmodel is marked **Beta** in UE 5.8.\n","webMarkdown":"All links were checked against Epic's UE 5.8 documentation on 2026-07-19.\n\n## CommonUI and input\n\n- [Common UI](https://dev.epicgames.com/documentation/en-us/unreal-engine/common-ui-plugin-for-advanced-user-interfaces-in-unreal-engine)\n- [CommonUI design guidelines](https://dev.epicgames.com/documentation/en-us/unreal-engine/design-guidelines-for-using-commonui-in-unreal-engine)\n- [CommonUI overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/overview-of-advanced-multiplatform-user-interfaces-with-common-ui-for-unreal-engine)\n- [CommonUI input technical guide](https://dev.epicgames.com/documentation/en-us/unreal-engine/commonui-input-technical-guide-for-unreal-engine)\n- [CommonUI quickstart](https://dev.epicgames.com/documentation/en-us/unreal-engine/common-ui-quickstart-guide-for-unreal-engine)\n- [UE 5.8 release notes: unified CommonUI and Enhanced Input](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-8-release-notes)\n- [`UCommonActivatableWidget`](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/CommonUI/UCommonActivatableWidget)\n- [`UCommonActivatableWidgetStack`](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/CommonUI/UCommonActivatableWidgetStack)\n\n## UMG architecture, layout, and performance\n\n- [UMG Viewmodel](https://dev.epicgames.com/documentation/en-us/unreal-engine/umg-viewmodel-for-unreal-engine)\n- [UMG optimization guidelines](https://dev.epicgames.com/documentation/en-us/unreal-engine/optimization-guidelines-for-umg-in-unreal-engine)\n- [Widget Designer team settings](https://dev.epicgames.com/documentation/en-us/unreal-engine/widget-designer-team-settings-in-the-unreal-engine-project-settings)\n- [DPI scaling](https://dev.epicgames.com/documentation/en-us/unreal-engine/dpi-scaling-in-unreal-engine)\n- [UMG Safe Zones](https://dev.epicgames.com/documentation/en-us/unreal-engine/umg-safe-zones-in-unreal-engine)\n- [`UUserWidget`](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/UMG/UUserWidget)\n- [`UUserWidget::Construct`](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/UMG/UUserWidget/Construct)\n- [`UListView`](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/UMG/UListView)\n- [Using the Invalidation Box](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-the-invalidation-box-for-umg-in-unreal-engine)\n\n## Scope and maturity notes\n\n- CommonUI is appropriate principally for complex layered and cross-platform interfaces.\n- UE 5.8 release notes supersede the stale warning on the older CommonUI-with-Enhanced-Input\n  guide by documenting the unified workflow.\n- UMG Viewmodel is marked **Beta** in UE 5.8.\n","searchText":"ue 5.8 primary sources all links were checked against epic's ue 5.8 documentation on 2026-07-19. commonui and input - common ui - commonui design guidelines - commonui overview - commonui input technical guide - commonui quickstart - ue 5.8 release notes: unified commonui and enhanced input - ucommonactivatablewidget - ucommonactivatablewidgetstack umg architecture, layout, and performance - umg viewmodel - umg optimization guidelines - widget designer team settings - dpi scaling - umg safe zones - uuserwidget - uuserwidget::construct - ulistview - using the invalidation box scope and maturity notes - commonui is appropriate principally for complex layered and cross-platform interfaces. - ue 5.8 release notes supersede the stale warning on the older commonui-with-enhanced-input guide by documenting the unified workflow. - umg viewmodel is marked beta in ue 5.8."},{"slug":"system-selector","file":"system-selector.md","title":"System selector","rawMarkdown":"# System selector\n\n## Use UMG only\n\nChoose plain UMG when all are true:\n\n- screen layering is simple;\n- mouse/keyboard is primary or gamepad navigation is small;\n- input prompts do not need automatic platform/device swapping;\n- the team benefits more from a small dependency surface than CommonUI routing.\n\nUMG remains the view layer even when CommonUI is added.\n\n## Add CommonUI\n\nChoose CommonUI when one or more are load-bearing:\n\n- multiple stacked screens or modal layers;\n- controller-first focus and cardinal navigation;\n- a universal back action;\n- platform-specific button glyphs or runtime input-method switching;\n- selective input routing between overlapping UI layers.\n\nCommonUI is an extensive paradigm, not a general requirement. Epic specifically identifies\ncomplex multi-layered and cross-platform interfaces as its main use cases.\n\n## Choose the update model\n\n| Need | Preferred mechanism | Note |\n|---|---|---|\n| Small explicit screen | Delegates/events + widget setters | Stable and easy to trace |\n| Reusable presentation model | Viewmodel + FieldNotify | MVVM is Beta in UE 5.8 |\n| One-time construction data | Expose-on-spawn/init function | Do not poll it |\n| Per-frame visual motion | UMG animation/material/limited Tick | Profile and isolate |\n\nDo not use raw property/function bindings as the default; they poll and can have a large\nperformance impact. Do not adopt Beta MVVM without documenting fallback and platform testing.\n\n## UE 5.8 input choice\n\nUE 5.8 release notes describe unification of Enhanced Input and Common Input/UI, including\nremoving duplicate data assets. Prefer Enhanced Input Actions and metadata for new 5.8 work.\nTreat older CommonUI action Data Tables as a legacy-compatible path, not the default new design.\n\n## Related Constitution principles\n\n- `GDC-L1-UX-0002`: reveal complexity progressively.\n- `GDC-L1-UX-0003`: make the interface communicate.\n- `GDC-L1-UX-0006`: build accessibility in early.\n- `GDC-L1-ARCH-0003`: decouple cross-system reactions through events.\n- `GDC-L1-ARCH-0006`: distinguish authoritative from transient state.\n","webMarkdown":"## Use UMG only\n\nChoose plain UMG when all are true:\n\n- screen layering is simple;\n- mouse/keyboard is primary or gamepad navigation is small;\n- input prompts do not need automatic platform/device swapping;\n- the team benefits more from a small dependency surface than CommonUI routing.\n\nUMG remains the view layer even when CommonUI is added.\n\n## Add CommonUI\n\nChoose CommonUI when one or more are load-bearing:\n\n- multiple stacked screens or modal layers;\n- controller-first focus and cardinal navigation;\n- a universal back action;\n- platform-specific button glyphs or runtime input-method switching;\n- selective input routing between overlapping UI layers.\n\nCommonUI is an extensive paradigm, not a general requirement. Epic specifically identifies\ncomplex multi-layered and cross-platform interfaces as its main use cases.\n\n## Choose the update model\n\n| Need | Preferred mechanism | Note |\n|---|---|---|\n| Small explicit screen | Delegates/events + widget setters | Stable and easy to trace |\n| Reusable presentation model | Viewmodel + FieldNotify | MVVM is Beta in UE 5.8 |\n| One-time construction data | Expose-on-spawn/init function | Do not poll it |\n| Per-frame visual motion | UMG animation/material/limited Tick | Profile and isolate |\n\nDo not use raw property/function bindings as the default; they poll and can have a large\nperformance impact. Do not adopt Beta MVVM without documenting fallback and platform testing.\n\n## UE 5.8 input choice\n\nUE 5.8 release notes describe unification of Enhanced Input and Common Input/UI, including\nremoving duplicate data assets. Prefer Enhanced Input Actions and metadata for new 5.8 work.\nTreat older CommonUI action Data Tables as a legacy-compatible path, not the default new design.\n\n## Related Constitution principles\n\n- `GDC-L1-UX-0002`: reveal complexity progressively.\n- `GDC-L1-UX-0003`: make the interface communicate.\n- `GDC-L1-UX-0006`: build accessibility in early.\n- `GDC-L1-ARCH-0003`: decouple cross-system reactions through events.\n- `GDC-L1-ARCH-0006`: distinguish authoritative from transient state.\n","searchText":"system selector use umg only choose plain umg when all are true: - screen layering is simple; - mouse/keyboard is primary or gamepad navigation is small; - input prompts do not need automatic platform/device swapping; - the team benefits more from a small dependency surface than commonui routing. umg remains the view layer even when commonui is added. add commonui choose commonui when one or more are load-bearing: - multiple stacked screens or modal layers; - controller-first focus and cardinal navigation; - a universal back action; - platform-specific button glyphs or runtime input-method switching; - selective input routing between overlapping ui layers. commonui is an extensive paradigm, not a general requirement. epic specifically identifies complex multi-layered and cross-platform interfaces as its main use cases. choose the update model | need | preferred mechanism | note | |---|---|---| | small explicit screen | delegates/events + widget setters | stable and easy to trace | | reusable presentation model | viewmodel + fieldnotify | mvvm is beta in ue 5.8 | | one-time construction data | expose-on-spawn/init function | do not poll it | | per-frame visual motion | umg animation/material/limited tick | profile and isolate | do not use raw property/function bindings as the default; they poll and can have a large performance impact. do not adopt beta mvvm without documenting fallback and platform testing. ue 5.8 input choice ue 5.8 release notes describe unification of enhanced input and common input/ui, including removing duplicate data assets. prefer enhanced input actions and metadata for new 5.8 work. treat older commonui action data tables as a legacy-compatible path, not the default new design. related constitution principles - gdc-l1-ux-0002: reveal complexity progressively. - gdc-l1-ux-0003: make the interface communicate. - gdc-l1-ux-0006: build accessibility in early. - gdc-l1-arch-0003: decouple cross-system reactions through events. - gdc-l1-arch-0006: distinguish authoritative from transient state."}]}
{"slug":"unreal-world-partition","name":"unreal-world-partition","title":"Unreal 5.8 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.","shortDescription":"Build and debug streamed large worlds","category":"World & AI","referenceCount":10,"rawMarkdown":"---\nname: unreal-world-partition\ndescription: 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.\n---\n\n# Unreal 5.8 World Partition\n\n## Ownership boundary\n\nThis skill owns cells, streaming sources, runtime grids, Data Layers, HLODs, and OFPA/Level Instance\nworld organization. Route procedural generation/output rules to\n[`unreal-pcg`](../unreal-pcg/SKILL.md), Landscape topology and deformation to\n[`unreal-landscape`](../unreal-landscape/SKILL.md), and cooked-asset residency/readiness to\n[`unreal-memory-streaming`](../unreal-memory-streaming/SKILL.md).\n\nRoute a world-streaming task to the smallest relevant reference. Give concrete editor actions, runtime ownership, failure checks, and a verification pass.\n\n## Select the world system first\n\n- Use **World Partition with Enable Streaming on** for a continuous world whose content should load by distance or explicit streaming sources.\n- 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.\n- Use **Level Instances** for reusable points of interest or gameplay assemblies. Prefer OFPA-backed Embedded Mode in a World Partition main world.\n- Use **Packed Level Blueprints** for repeated, dense, static-mesh arrangements. Do not assume arbitrary components survive packing.\n- 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.\n\nRead [system-selector-conversion.md](references/system-selector-conversion.md) before converting an existing world.\n\n## Route by task\n\n| Need | Load |\n|---|---|\n| Choose a world model or convert a map | [system-selector-conversion.md](references/system-selector-conversion.md) |\n| Decide spatial loading, references, ownership, persistence | [actor-placement-references.md](references/actor-placement-references.md) |\n| Configure sources, cells, grids, loading ranges, teleport gates | [streaming-sources-grids.md](references/streaming-sources-grids.md) |\n| Author editor/runtime variants and state changes | [data-layers.md](references/data-layers.md) |\n| Build and tune distant proxy content | [hlod.md](references/hlod.md) |\n| Reuse assemblies; understand OFPA and runtime modes | [level-instances-ofpa.md](references/level-instances-ofpa.md) |\n| Combine PCG with partitioning, Data Layers, and HLOD | [pcg-integration.md](references/pcg-integration.md) |\n| Diagnose loading or run unattended builds | [debugging-builders.md](references/debugging-builders.md) |\n| Apply common production patterns and test gates | [patterns-testing.md](references/patterns-testing.md) |\n| Verify claims or feature maturity | [sources.md](references/sources.md) |\n\n## Execute in this order\n\n1. State map scale, movement speed, multiplayer model, target hardware, memory budget, and whether transitions may block.\n2. Classify each important actor by spatial lifetime, Data Layer state, runtime grid, HLOD policy, and hard-reference dependencies.\n3. Begin with the default 2D Runtime Spatial Hash and one runtime grid. Add grids only after a measured requirement.\n4. Place or configure streaming sources. Derive initial loading range from maximum travel speed, worst observed load latency, and safety margin.\n5. Gate teleports and scripted arrivals on streaming completion; provide timeout and failure behavior.\n6. Add Runtime Data Layers for stateful world variants, not as a substitute for every gameplay visibility flag.\n7. Assign and build HLODs for distant, non-interactive representation. Compare proxies against sources at expected viewing distance.\n8. Validate editor, PIE, standalone, multiplayer, cooked build, target device, and worst-case traversal.\n9. Profile cell timing, memory, I/O, hitches, draw calls, and HLOD transitions before increasing ranges or making content always loaded.\n\n## Hard rules\n\n- Do not solve streaming bugs by marking broad content **not spatially loaded**; that converts uncertainty into permanent memory and initialization cost.\n- Treat hard actor references as streaming dependencies. Referenced actors can be bundled and loaded together even when spatially separated.\n- The server owns Runtime Data Layer state in networked play. Replicate gameplay state; do not let clients independently decide authoritative world state.\n- A distant HLOD is representation, not authoritative collision, interaction, AI, or gameplay state.\n- Do not teleport into an unloaded destination. Enable a destination streaming source, wait for completion, then move the player and retire the temporary source.\n- Do not tune only in the editor. Cooked packaging, I/O, memory pressure, and target hardware decide whether streaming works.\n- OFPA reduces file contention; it does not remove logical merge conflicts or make cross-actor ownership safe.\n- Keep Experimental features explicitly labeled. UE 5.8 World Partition Insights and Fast Geometry-related workflows require deliberate opt-in and validation.\n\n## Answer contract\n\nReturn:\n\n1. **Selected system and assumptions** — including why it fits.\n2. **Actor/content classification** — spatial loading, Data Layer, grid, HLOD, references.\n3. **Exact actions** — editor paths, properties, components, APIs, commands, or commandlets.\n4. **Parameter effects** — what changing cell size, loading range, priority, or state actually does.\n5. **Network and packaging consequences**.\n6. **Failure checks and recovery**.\n7. **Verification** — observable pass criteria on a cooked target build.\n\nDo not invent universal cell sizes, loading radii, or memory budgets. Supply a starting hypothesis only when its assumptions are stated, then require measurement.\n","webMarkdown":"## Ownership boundary\n\nThis skill owns cells, streaming sources, runtime grids, Data Layers, HLODs, and OFPA/Level Instance\nworld organization. Route procedural generation/output rules to\n[`unreal-pcg`](/unreal/unreal-pcg/), Landscape topology and deformation to\n[`unreal-landscape`](/unreal/unreal-landscape/), and cooked-asset residency/readiness to\n[`unreal-memory-streaming`](/unreal/unreal-memory-streaming/).\n\nRoute a world-streaming task to the smallest relevant reference. Give concrete editor actions, runtime ownership, failure checks, and a verification pass.\n\n## Select the world system first\n\n- Use **World Partition with Enable Streaming on** for a continuous world whose content should load by distance or explicit streaming sources.\n- 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.\n- Use **Level Instances** for reusable points of interest or gameplay assemblies. Prefer OFPA-backed Embedded Mode in a World Partition main world.\n- Use **Packed Level Blueprints** for repeated, dense, static-mesh arrangements. Do not assume arbitrary components survive packing.\n- 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.\n\nRead [system-selector-conversion.md](/unreal/unreal-world-partition/system-selector-conversion/) before converting an existing world.\n\n## Route by task\n\n| Need | Load |\n|---|---|\n| Choose a world model or convert a map | [system-selector-conversion.md](/unreal/unreal-world-partition/system-selector-conversion/) |\n| Decide spatial loading, references, ownership, persistence | [actor-placement-references.md](/unreal/unreal-world-partition/actor-placement-references/) |\n| Configure sources, cells, grids, loading ranges, teleport gates | [streaming-sources-grids.md](/unreal/unreal-world-partition/streaming-sources-grids/) |\n| Author editor/runtime variants and state changes | [data-layers.md](/unreal/unreal-world-partition/data-layers/) |\n| Build and tune distant proxy content | [hlod.md](/unreal/unreal-world-partition/hlod/) |\n| Reuse assemblies; understand OFPA and runtime modes | [level-instances-ofpa.md](/unreal/unreal-world-partition/level-instances-ofpa/) |\n| Combine PCG with partitioning, Data Layers, and HLOD | [pcg-integration.md](/unreal/unreal-world-partition/pcg-integration/) |\n| Diagnose loading or run unattended builds | [debugging-builders.md](/unreal/unreal-world-partition/debugging-builders/) |\n| Apply common production patterns and test gates | [patterns-testing.md](/unreal/unreal-world-partition/patterns-testing/) |\n| Verify claims or feature maturity | [sources.md](/unreal/unreal-world-partition/sources/) |\n\n## Execute in this order\n\n1. State map scale, movement speed, multiplayer model, target hardware, memory budget, and whether transitions may block.\n2. Classify each important actor by spatial lifetime, Data Layer state, runtime grid, HLOD policy, and hard-reference dependencies.\n3. Begin with the default 2D Runtime Spatial Hash and one runtime grid. Add grids only after a measured requirement.\n4. Place or configure streaming sources. Derive initial loading range from maximum travel speed, worst observed load latency, and safety margin.\n5. Gate teleports and scripted arrivals on streaming completion; provide timeout and failure behavior.\n6. Add Runtime Data Layers for stateful world variants, not as a substitute for every gameplay visibility flag.\n7. Assign and build HLODs for distant, non-interactive representation. Compare proxies against sources at expected viewing distance.\n8. Validate editor, PIE, standalone, multiplayer, cooked build, target device, and worst-case traversal.\n9. Profile cell timing, memory, I/O, hitches, draw calls, and HLOD transitions before increasing ranges or making content always loaded.\n\n## Hard rules\n\n- Do not solve streaming bugs by marking broad content **not spatially loaded**; that converts uncertainty into permanent memory and initialization cost.\n- Treat hard actor references as streaming dependencies. Referenced actors can be bundled and loaded together even when spatially separated.\n- The server owns Runtime Data Layer state in networked play. Replicate gameplay state; do not let clients independently decide authoritative world state.\n- A distant HLOD is representation, not authoritative collision, interaction, AI, or gameplay state.\n- Do not teleport into an unloaded destination. Enable a destination streaming source, wait for completion, then move the player and retire the temporary source.\n- Do not tune only in the editor. Cooked packaging, I/O, memory pressure, and target hardware decide whether streaming works.\n- OFPA reduces file contention; it does not remove logical merge conflicts or make cross-actor ownership safe.\n- Keep Experimental features explicitly labeled. UE 5.8 World Partition Insights and Fast Geometry-related workflows require deliberate opt-in and validation.\n\n## Answer contract\n\nReturn:\n\n1. **Selected system and assumptions** — including why it fits.\n2. **Actor/content classification** — spatial loading, Data Layer, grid, HLOD, references.\n3. **Exact actions** — editor paths, properties, components, APIs, commands, or commandlets.\n4. **Parameter effects** — what changing cell size, loading range, priority, or state actually does.\n5. **Network and packaging consequences**.\n6. **Failure checks and recovery**.\n7. **Verification** — observable pass criteria on a cooked target build.\n\nDo not invent universal cell sizes, loading radii, or memory budgets. Supply a starting hypothesis only when its assumptions are stated, then require measurement.\n","searchText":"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.","references":[{"slug":"actor-placement-references","file":"actor-placement-references.md","title":"Actor placement, references, and lifetime","rawMarkdown":"# Actor placement, references, and lifetime\n\n## Classify every load-bearing actor\n\nRecord five decisions:\n\n1. **Spatial lifetime** — source-distance loaded or always resident.\n2. **World state** — no Data Layer, Editor Data Layer, or Runtime Data Layer and initial state.\n3. **Runtime grid** — normally `None` so the partition system selects the default.\n4. **Distant representation** — HLOD layer or intentionally none.\n5. **Dependencies** — hard actor references, soft asset references, subsystem lookup, or stable identifier.\n\n## `Is Spatially Loaded`\n\n- Enabled: the actor loads when it is in range of a streaming source and is not excluded by a disabled Runtime Data Layer.\n- Disabled: the actor is not distance-streamed; Data Layer state can still control it.\n\nUse 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.\n\n## Reference rule\n\nA 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.\n\nPrefer, according to the requirement:\n\n- a subsystem or manager that resolves a nearby actor at use time;\n- an interface plus overlap/spatial query;\n- a soft asset reference for asynchronously loaded assets;\n- a stable gameplay identifier resolved through a registry;\n- an event/message carrying data rather than a stored pointer.\n\nDo 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.\n\n## Ownership patterns\n\n### Global rule or service\n\nPut state in GameMode/GameState, GameInstance, an appropriate subsystem, or a replicated service—not in a random placed actor that happens to remain loaded.\n\n### Spatial interactable\n\nKeep 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.\n\n### Cross-cell mission dependency\n\nStore mission state centrally. Resolve each endpoint when its cell is present and tolerate absence. Avoid direct endpoint-to-endpoint hard references across the world.\n\n### Attached actors\n\nKeep parent and child streaming policies compatible. Test attachment and absolute-transform behavior through unload/reload; editor visibility alone is insufficient.\n\n## Validation\n\n- Use the reference viewer and Size Map for suspicious asset chains.\n- Inspect streaming-generation warnings and unexpected actor bundles.\n- Traverse with debug cell visualization enabled and watch whether distant dependencies load.\n- Unload/reload the cell repeatedly; confirm durable gameplay state survives.\n- Test server and client separately because authoritative and client-visible actor sets can differ.\n","webMarkdown":"## Classify every load-bearing actor\n\nRecord five decisions:\n\n1. **Spatial lifetime** — source-distance loaded or always resident.\n2. **World state** — no Data Layer, Editor Data Layer, or Runtime Data Layer and initial state.\n3. **Runtime grid** — normally `None` so the partition system selects the default.\n4. **Distant representation** — HLOD layer or intentionally none.\n5. **Dependencies** — hard actor references, soft asset references, subsystem lookup, or stable identifier.\n\n## `Is Spatially Loaded`\n\n- Enabled: the actor loads when it is in range of a streaming source and is not excluded by a disabled Runtime Data Layer.\n- Disabled: the actor is not distance-streamed; Data Layer state can still control it.\n\nUse 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.\n\n## Reference rule\n\nA 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.\n\nPrefer, according to the requirement:\n\n- a subsystem or manager that resolves a nearby actor at use time;\n- an interface plus overlap/spatial query;\n- a soft asset reference for asynchronously loaded assets;\n- a stable gameplay identifier resolved through a registry;\n- an event/message carrying data rather than a stored pointer.\n\nDo 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.\n\n## Ownership patterns\n\n### Global rule or service\n\nPut state in GameMode/GameState, GameInstance, an appropriate subsystem, or a replicated service—not in a random placed actor that happens to remain loaded.\n\n### Spatial interactable\n\nKeep 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.\n\n### Cross-cell mission dependency\n\nStore mission state centrally. Resolve each endpoint when its cell is present and tolerate absence. Avoid direct endpoint-to-endpoint hard references across the world.\n\n### Attached actors\n\nKeep parent and child streaming policies compatible. Test attachment and absolute-transform behavior through unload/reload; editor visibility alone is insufficient.\n\n## Validation\n\n- Use the reference viewer and Size Map for suspicious asset chains.\n- Inspect streaming-generation warnings and unexpected actor bundles.\n- Traverse with debug cell visualization enabled and watch whether distant dependencies load.\n- Unload/reload the cell repeatedly; confirm durable gameplay state survives.\n- Test server and client separately because authoritative and client-visible actor sets can differ.\n","searchText":"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."},{"slug":"data-layers","file":"data-layers.md","title":"Data Layers","rawMarkdown":"# Data Layers\n\n## Data model\n\n- A **Data Layer Asset** is a project asset that declares an Editor or Runtime layer.\n- A **Data Layer Instance** is the world-specific instance and assignment surface.\n- **Editor Data Layers** organize authoring views and alternate editing sets; they do not define a runtime state machine.\n- **Runtime Data Layers** can be changed at runtime and participate in streaming.\n\nRuntime states:\n\n- **Unloaded**: content is not resident.\n- **Loaded**: content is resident but not visible/activated.\n- **Activated**: content is resident and visible/active.\n\nTreat `Loaded` as a preload state and `Activated` as presentation/gameplay availability. Verify component-specific behavior instead of assuming visibility is the only activation consequence.\n\n## Network authority\n\nIn 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.\n\nCosmetic 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.\n\n## Good uses\n\n- preloading a boss arena before revealing it;\n- switching repaired/destroyed or seasonal world variants;\n- phasing a location by authoritative quest state;\n- separating alternate set dressing while preserving shared terrain;\n- grouping editor-only disciplines or review passes.\n\n## Poor uses\n\n- replacing a local component visibility flag for one tiny object;\n- encoding every quest boolean as a separate layer;\n- assigning widely scattered actors to many Runtime Data Layers without measuring streaming cost;\n- hiding authoritative actors only on a client;\n- storing durable quest truth in the layer state itself.\n\n## State-transition pattern\n\n1. Author a Runtime Data Layer Asset and world instance.\n2. Assign only the content that shares the transition and lifetime.\n3. Set and document the initial runtime state.\n4. On the server, request `Loaded` early enough to cover worst load latency.\n5. Wait for readiness when the transition requires collision or interaction.\n6. Request `Activated` at the reveal/phase boundary.\n7. Persist the underlying gameplay state separately so load/save can reconstruct the layer state.\n8. Test late join, reconnect, respawn, and server travel.\n\n## Performance caution\n\nActors 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.\n\n## Debug commands\n\n```text\nwp.DumpDatalayers\nwp.Runtime.SetDataLayerRuntimeState\nwp.Runtime.ToggleDataLayerActivation\nwp.Runtime.ToggleDrawDataLayers\n```\n\nEpic'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.\n","webMarkdown":"## Data model\n\n- A **Data Layer Asset** is a project asset that declares an Editor or Runtime layer.\n- A **Data Layer Instance** is the world-specific instance and assignment surface.\n- **Editor Data Layers** organize authoring views and alternate editing sets; they do not define a runtime state machine.\n- **Runtime Data Layers** can be changed at runtime and participate in streaming.\n\nRuntime states:\n\n- **Unloaded**: content is not resident.\n- **Loaded**: content is resident but not visible/activated.\n- **Activated**: content is resident and visible/active.\n\nTreat `Loaded` as a preload state and `Activated` as presentation/gameplay availability. Verify component-specific behavior instead of assuming visibility is the only activation consequence.\n\n## Network authority\n\nIn 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.\n\nCosmetic 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.\n\n## Good uses\n\n- preloading a boss arena before revealing it;\n- switching repaired/destroyed or seasonal world variants;\n- phasing a location by authoritative quest state;\n- separating alternate set dressing while preserving shared terrain;\n- grouping editor-only disciplines or review passes.\n\n## Poor uses\n\n- replacing a local component visibility flag for one tiny object;\n- encoding every quest boolean as a separate layer;\n- assigning widely scattered actors to many Runtime Data Layers without measuring streaming cost;\n- hiding authoritative actors only on a client;\n- storing durable quest truth in the layer state itself.\n\n## State-transition pattern\n\n1. Author a Runtime Data Layer Asset and world instance.\n2. Assign only the content that shares the transition and lifetime.\n3. Set and document the initial runtime state.\n4. On the server, request `Loaded` early enough to cover worst load latency.\n5. Wait for readiness when the transition requires collision or interaction.\n6. Request `Activated` at the reveal/phase boundary.\n7. Persist the underlying gameplay state separately so load/save can reconstruct the layer state.\n8. Test late join, reconnect, respawn, and server travel.\n\n## Performance caution\n\nActors 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.\n\n## Debug commands\n\n```text\nwp.DumpDatalayers\nwp.Runtime.SetDataLayerRuntimeState\nwp.Runtime.ToggleDataLayerActivation\nwp.Runtime.ToggleDrawDataLayers\n```\n\nEpic'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.\n","searchText":"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."},{"slug":"debugging-builders","file":"debugging-builders.md","title":"Debugging and builder commandlets","rawMarkdown":"# Debugging and builder commandlets\n\n## Diagnose in layers\n\n1. **Source** — is an enabled source requesting the expected location, grid, shape, target state, and priority?\n2. **Cell** — is the expected runtime cell generated, requested, loaded, and activated?\n3. **Policy** — do `Is Spatially Loaded`, Data Layer state, grid assignment, and references agree?\n4. **Content** — did the actor initialize, register collision/rendering/navigation, and survive replication rules?\n5. **Representation** — is HLOD replacing the source as intended?\n6. **Budget** — did I/O, decompression, memory, game-thread work, or rendering miss the deadline?\n\n## Useful runtime commands\n\n```text\nwp.Runtime.ToggleDrawRuntimeHash2D\nwp.Runtime.ToggleDrawRuntimeHash3D\nwp.Runtime.ToggleDrawDataLayers\nwp.DumpDatalayers\nwp.Runtime.HLOD 0\n```\n\nUse `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.\n\n## World Partition Insights in 5.8\n\nUE 5.8 introduces per-cell streaming analysis and session playback in Unreal Insights. Epic documents enabling `WorldStreamingInsights` in Unreal Insights configuration and tracing with:\n\n```text\n-trace=WorldStreaming\n```\n\nOptional trace channels include:\n\n```text\n+WorldStreamingPriority\n+WorldStreamingDependencies\n```\n\nTreat the toolchain as version-specific. Confirm configuration in the installed 5.8 build and record trace overhead before using production timing as a baseline.\n\n## Repro capture\n\nRecord:\n\n- engine revision and build configuration;\n- map, start transform, route, speed, and source configuration;\n- cell size/loading range and Data Layer states;\n- cold versus warm cache;\n- platform/storage/memory state;\n- trace, log, hitch timestamp, and visible symptom.\n\n## Builder commandlet form\n\n```text\nUnrealEditor.exe <Project.uproject> <Map> -run=WorldPartitionBuilderCommandlet -Builder=<BuilderClass> -Unattended\n```\n\nCurrent documented builders include:\n\n- `WorldPartitionHLODsBuilder`\n- `WorldPartitionMiniMapBuilder`\n- `WorldPartitionRenameDuplicateBuilder`\n- `WorldPartitionResaveActorsBuilder`\n- `WorldPartitionFoliageBuilder`\n- `WorldPartitionNavigationDataBuilder`\n- `WorldPartitionSmartObjectCollectionBuilder`\n- `PCGWorldPartitionBuilder`\n- `WorldPartitionRuntimeVirtualTextureBuilder`\n\nSome 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.\n\n## Builder acceptance\n\n- command exits successfully with no ignored errors;\n- expected assets changed and unrelated assets did not;\n- a second identical run is stable or differences are explained;\n- source-control status is reviewable;\n- the map cooks and loads;\n- target traversal, Data Layer transitions, HLOD, navigation, and PCG behave as expected.\n","webMarkdown":"## Diagnose in layers\n\n1. **Source** — is an enabled source requesting the expected location, grid, shape, target state, and priority?\n2. **Cell** — is the expected runtime cell generated, requested, loaded, and activated?\n3. **Policy** — do `Is Spatially Loaded`, Data Layer state, grid assignment, and references agree?\n4. **Content** — did the actor initialize, register collision/rendering/navigation, and survive replication rules?\n5. **Representation** — is HLOD replacing the source as intended?\n6. **Budget** — did I/O, decompression, memory, game-thread work, or rendering miss the deadline?\n\n## Useful runtime commands\n\n```text\nwp.Runtime.ToggleDrawRuntimeHash2D\nwp.Runtime.ToggleDrawRuntimeHash3D\nwp.Runtime.ToggleDrawDataLayers\nwp.DumpDatalayers\nwp.Runtime.HLOD 0\n```\n\nUse `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.\n\n## World Partition Insights in 5.8\n\nUE 5.8 introduces per-cell streaming analysis and session playback in Unreal Insights. Epic documents enabling `WorldStreamingInsights` in Unreal Insights configuration and tracing with:\n\n```text\n-trace=WorldStreaming\n```\n\nOptional trace channels include:\n\n```text\n+WorldStreamingPriority\n+WorldStreamingDependencies\n```\n\nTreat the toolchain as version-specific. Confirm configuration in the installed 5.8 build and record trace overhead before using production timing as a baseline.\n\n## Repro capture\n\nRecord:\n\n- engine revision and build configuration;\n- map, start transform, route, speed, and source configuration;\n- cell size/loading range and Data Layer states;\n- cold versus warm cache;\n- platform/storage/memory state;\n- trace, log, hitch timestamp, and visible symptom.\n\n## Builder commandlet form\n\n```text\nUnrealEditor.exe <Project.uproject> <Map> -run=WorldPartitionBuilderCommandlet -Builder=<BuilderClass> -Unattended\n```\n\nCurrent documented builders include:\n\n- `WorldPartitionHLODsBuilder`\n- `WorldPartitionMiniMapBuilder`\n- `WorldPartitionRenameDuplicateBuilder`\n- `WorldPartitionResaveActorsBuilder`\n- `WorldPartitionFoliageBuilder`\n- `WorldPartitionNavigationDataBuilder`\n- `WorldPartitionSmartObjectCollectionBuilder`\n- `PCGWorldPartitionBuilder`\n- `WorldPartitionRuntimeVirtualTextureBuilder`\n\nSome 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.\n\n## Builder acceptance\n\n- command exits successfully with no ignored errors;\n- expected assets changed and unrelated assets did not;\n- a second identical run is stable or differences are explained;\n- source-control status is reviewable;\n- the map cooks and loads;\n- target traversal, Data Layer transitions, HLOD, navigation, and PCG behave as expected.\n","searchText":"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."},{"slug":"hlod","file":"hlod.md","title":"World Partition HLOD","rawMarkdown":"# World Partition HLOD\n\n## Purpose and boundary\n\nHLOD 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.\n\n## Layer type selector\n\n| HLOD layer type | Use when | Primary tradeoff |\n|---|---|---|\n| Instancing | Source actors share a mesh/material pattern | Low build complexity; less consolidation than merging |\n| Merged Mesh | A combined proxy can preserve adequate silhouette/material appearance | Fewer components/draw calls; asset and texture cost can grow |\n| Simplified Mesh | Distant geometry can tolerate reduction | Best geometric reduction; longer builds and more visual risk |\n\n## Authoring workflow\n\n1. Identify distant content that must remain visually present after its source cell unloads.\n2. Ensure source actors are Static and eligible to generate HLOD.\n3. Create focused HLOD Layer assets by content behavior, not one universal layer.\n4. Choose layer type and mesh/material settings from expected viewing distance and silhouette importance.\n5. Set HLOD layer `Cell Size`, `Loading Range`, optional parent layer, and `Always Loaded` only when justified.\n6. Assign actors or defaults deliberately.\n7. Build HLOD setup, then proxies.\n8. Compare source and proxy at the intended transition distance and in motion.\n9. Profile draw calls, GPU time, memory, disk size, and transition hitches.\n\n## Parameter effects\n\n- Larger HLOD cells merge more source content into fewer, heavier proxies.\n- Smaller HLOD cells improve granularity but increase actor/cell counts and transitions.\n- Larger HLOD loading range preserves distant representation longer and raises residency.\n- Parent HLOD layers create additional distance tiers; each tier adds build, storage, and validation cost.\n- `Always Loaded` removes transition risk for that HLOD layer but creates permanent residency.\n\n## UE 5.8 workflow additions\n\nUE 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.\n\nFeatures explicitly marked Experimental in the release notes—such as externalizing HLOD assets—must remain opt-in and receive cook/source-control/rollback validation.\n\n## Commandlet\n\nGeneral form:\n\n```text\nUnrealEditor.exe <Project.uproject> <Map> -run=WorldPartitionBuilderCommandlet -Builder=WorldPartitionHLODsBuilder -AllowCommandletRendering -Unattended\n```\n\nUseful builder switches include:\n\n- `-SetupHLODs`\n- `-BuildHLODs`\n- `-DeleteHLODs`\n\nAdd project source-control flags deliberately; do not let an unattended build unexpectedly check out or submit files.\n\n## Validation failures\n\n- **Proxy pops or changes silhouette**: adjust transition distance, simplification, materials, or layer grouping.\n- **Proxy shows stale state**: rebuild after source changes and verify Data Layer/HLOD assignment.\n- **Gameplay disappears with source cells**: gameplay was incorrectly assumed to live in the HLOD.\n- **Memory rises after HLOD**: inspect proxy textures/materials, overlapping tiers, always-loaded settings, and source residency.\n- **Build churn is excessive**: use 5.8 scoped iteration, stable grouping, and the perceptual-difference heuristic; still require a clean final build.\n\nFor rapid visual diagnosis, toggle HLODs with:\n\n```text\nwp.Runtime.HLOD 0\n```\n\nRestore the default after the comparison.\n","webMarkdown":"## Purpose and boundary\n\nHLOD 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.\n\n## Layer type selector\n\n| HLOD layer type | Use when | Primary tradeoff |\n|---|---|---|\n| Instancing | Source actors share a mesh/material pattern | Low build complexity; less consolidation than merging |\n| Merged Mesh | A combined proxy can preserve adequate silhouette/material appearance | Fewer components/draw calls; asset and texture cost can grow |\n| Simplified Mesh | Distant geometry can tolerate reduction | Best geometric reduction; longer builds and more visual risk |\n\n## Authoring workflow\n\n1. Identify distant content that must remain visually present after its source cell unloads.\n2. Ensure source actors are Static and eligible to generate HLOD.\n3. Create focused HLOD Layer assets by content behavior, not one universal layer.\n4. Choose layer type and mesh/material settings from expected viewing distance and silhouette importance.\n5. Set HLOD layer `Cell Size`, `Loading Range`, optional parent layer, and `Always Loaded` only when justified.\n6. Assign actors or defaults deliberately.\n7. Build HLOD setup, then proxies.\n8. Compare source and proxy at the intended transition distance and in motion.\n9. Profile draw calls, GPU time, memory, disk size, and transition hitches.\n\n## Parameter effects\n\n- Larger HLOD cells merge more source content into fewer, heavier proxies.\n- Smaller HLOD cells improve granularity but increase actor/cell counts and transitions.\n- Larger HLOD loading range preserves distant representation longer and raises residency.\n- Parent HLOD layers create additional distance tiers; each tier adds build, storage, and validation cost.\n- `Always Loaded` removes transition risk for that HLOD layer but creates permanent residency.\n\n## UE 5.8 workflow additions\n\nUE 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.\n\nFeatures explicitly marked Experimental in the release notes—such as externalizing HLOD assets—must remain opt-in and receive cook/source-control/rollback validation.\n\n## Commandlet\n\nGeneral form:\n\n```text\nUnrealEditor.exe <Project.uproject> <Map> -run=WorldPartitionBuilderCommandlet -Builder=WorldPartitionHLODsBuilder -AllowCommandletRendering -Unattended\n```\n\nUseful builder switches include:\n\n- `-SetupHLODs`\n- `-BuildHLODs`\n- `-DeleteHLODs`\n\nAdd project source-control flags deliberately; do not let an unattended build unexpectedly check out or submit files.\n\n## Validation failures\n\n- **Proxy pops or changes silhouette**: adjust transition distance, simplification, materials, or layer grouping.\n- **Proxy shows stale state**: rebuild after source changes and verify Data Layer/HLOD assignment.\n- **Gameplay disappears with source cells**: gameplay was incorrectly assumed to live in the HLOD.\n- **Memory rises after HLOD**: inspect proxy textures/materials, overlapping tiers, always-loaded settings, and source residency.\n- **Build churn is excessive**: use 5.8 scoped iteration, stable grouping, and the perceptual-difference heuristic; still require a clean final build.\n\nFor rapid visual diagnosis, toggle HLODs with:\n\n```text\nwp.Runtime.HLOD 0\n```\n\nRestore the default after the comparison.\n","searchText":"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."},{"slug":"level-instances-ofpa","file":"level-instances-ofpa.md","title":"Level Instances, Packed Level Blueprints, and OFPA","rawMarkdown":"# Level Instances, Packed Level Blueprints, and OFPA\n\n## Choose the reusable unit\n\n### Level Instance\n\nUse 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.\n\n### Packed Level Blueprint\n\nUse 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.\n\n## Runtime behavior in a World Partition main world\n\n### Embedded Mode\n\n- Default and recommended for OFPA Level Instances.\n- At runtime, the Level Instance wrapper is discarded and its external actors are added to the parent World Partition grid.\n- The Level Instance is primarily an editor authoring construct.\n- Non-OFPA actors such as the instance's `AWorldSettings` do not survive embedding. Do not place runtime logic there.\n\n### Level Streaming Mode\n\n- Used when the instance cannot be embedded, including non-OFPA content.\n- Loading the owning World Partition cell streams the associated Level.\n- Each streamed Level adds runtime overhead. Avoid high densities of Level Instances that require this mode.\n\nOutside a World Partition main world, Level Instances do not gain automatic World Partition streaming management.\n\n## Data Layers\n\nActors 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.\n\n## OFPA boundary\n\nOne 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.\n\nOFPA 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.\n\nOFPA does not prevent:\n\n- two people changing the same actor;\n- logical conflicts between related actors;\n- rename/move/delete coordination failures;\n- broad churn from derived HLOD or generated content.\n\n## Creation checklist\n\n1. Select the cohesive actors.\n2. Choose **Create Level Instance** for general assemblies or **Create Packed Level Actor** for supported static visual assemblies.\n3. Enable External Actors when the instance should use OFPA.\n4. Choose a stable pivot meaningful for placement and snapping.\n5. Save under the project's naming and ownership conventions.\n6. Test propagation to several instances.\n7. Verify Embedded versus Level Streaming behavior in a cooked build.\n8. Verify internal gameplay actors, Data Layers, HLODs, collision, navigation, and references.\n\nBreaking a Level Instance replaces it with its original actors and cannot be undone through the Level Instance operation. Commit/save before destructive restructuring.\n","webMarkdown":"## Choose the reusable unit\n\n### Level Instance\n\nUse 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.\n\n### Packed Level Blueprint\n\nUse 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.\n\n## Runtime behavior in a World Partition main world\n\n### Embedded Mode\n\n- Default and recommended for OFPA Level Instances.\n- At runtime, the Level Instance wrapper is discarded and its external actors are added to the parent World Partition grid.\n- The Level Instance is primarily an editor authoring construct.\n- Non-OFPA actors such as the instance's `AWorldSettings` do not survive embedding. Do not place runtime logic there.\n\n### Level Streaming Mode\n\n- Used when the instance cannot be embedded, including non-OFPA content.\n- Loading the owning World Partition cell streams the associated Level.\n- Each streamed Level adds runtime overhead. Avoid high densities of Level Instances that require this mode.\n\nOutside a World Partition main world, Level Instances do not gain automatic World Partition streaming management.\n\n## Data Layers\n\nActors 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.\n\n## OFPA boundary\n\nOne 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.\n\nOFPA 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.\n\nOFPA does not prevent:\n\n- two people changing the same actor;\n- logical conflicts between related actors;\n- rename/move/delete coordination failures;\n- broad churn from derived HLOD or generated content.\n\n## Creation checklist\n\n1. Select the cohesive actors.\n2. Choose **Create Level Instance** for general assemblies or **Create Packed Level Actor** for supported static visual assemblies.\n3. Enable External Actors when the instance should use OFPA.\n4. Choose a stable pivot meaningful for placement and snapping.\n5. Save under the project's naming and ownership conventions.\n6. Test propagation to several instances.\n7. Verify Embedded versus Level Streaming behavior in a cooked build.\n8. Verify internal gameplay actors, Data Layers, HLODs, collision, navigation, and references.\n\nBreaking a Level Instance replaces it with its original actors and cannot be undone through the Level Instance operation. Commit/save before destructive restructuring.\n","searchText":"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."},{"slug":"patterns-testing","file":"patterns-testing.md","title":"Production patterns and test gates","rawMarkdown":"# Production patterns and test gates\n\n## Pattern: open-world traversal\n\n- One default runtime grid until evidence requires another.\n- Player source plus a velocity/look-ahead strategy for fast travel.\n- Spatial environment actors; true global systems outside placed-world lifetime.\n- HLOD for distant static silhouette.\n- Runtime Data Layers only for cohesive world phases.\n- Cooked traversal benchmark covering slow walk, sprint, fastest vehicle, abrupt turn, and return path.\n\n## Pattern: seamless teleport or fast travel\n\n- Destination streaming source enabled before travel.\n- Loading/transition presentation begins.\n- Wait for streaming completion and project-specific gameplay readiness.\n- Server performs authoritative move.\n- Client camera/input resumes after possession and local presentation are ready.\n- Temporary source retires after the normal source owns the area.\n- Timeout returns to a known safe location or explicit failure UI.\n\n## Pattern: stateful location\n\n- Durable quest/state data lives in save/gameplay state.\n- Server maps that truth to Runtime Data Layer state.\n- `Loaded` prewarms the destination; `Activated` reveals the chosen phase.\n- Streamed interactables reconstruct local presentation from durable IDs/state.\n- Late join and load-game tests confirm the same phase.\n\n## Pattern: repeated point of interest\n\n- Level Instance for mixed gameplay/content assembly.\n- Packed Level Blueprint only when the assembly is supported static visual content.\n- OFPA for collaborative editing.\n- Instance-level Data Layer supplies the broad phase; internal layers only for truly reusable variants.\n- Validate every instance transform, HLOD, navigation, and references.\n\n## Pattern: persistent manager\n\nUse 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.\n\n## Required test matrix\n\n| Axis | Minimum cases |\n|---|---|\n| Build | PIE, standalone, cooked Development, shipping-equivalent target |\n| Cache | cold start and warm repeat |\n| Motion | slow, fastest sustained, burst/teleport, sudden reversal |\n| Network | listen/dedicated as applicable, late join, reconnect, packet impairment |\n| State | each Runtime Data Layer transition and save/load reconstruction |\n| Memory | baseline, worst vista, repeated round trip, long soak |\n| HLOD | source/proxy comparison, transition in motion, rebuild after source edit |\n| Failure | missing/late cell, timeout, cancelled travel, invalid reference |\n\n## Acceptance gates\n\n- No player reaches absent collision or interactive state.\n- No unbounded memory rise after repeated traversal.\n- Cell/HLOD transitions meet the project's visible-pop and hitch budgets.\n- Server and clients agree on authoritative Data Layer/gameplay state.\n- A clean builder run is reproducible from source control.\n- Packaged behavior matches editor intent.\n- Debug overrides are removed and experimental dependencies are documented.\n","webMarkdown":"## Pattern: open-world traversal\n\n- One default runtime grid until evidence requires another.\n- Player source plus a velocity/look-ahead strategy for fast travel.\n- Spatial environment actors; true global systems outside placed-world lifetime.\n- HLOD for distant static silhouette.\n- Runtime Data Layers only for cohesive world phases.\n- Cooked traversal benchmark covering slow walk, sprint, fastest vehicle, abrupt turn, and return path.\n\n## Pattern: seamless teleport or fast travel\n\n- Destination streaming source enabled before travel.\n- Loading/transition presentation begins.\n- Wait for streaming completion and project-specific gameplay readiness.\n- Server performs authoritative move.\n- Client camera/input resumes after possession and local presentation are ready.\n- Temporary source retires after the normal source owns the area.\n- Timeout returns to a known safe location or explicit failure UI.\n\n## Pattern: stateful location\n\n- Durable quest/state data lives in save/gameplay state.\n- Server maps that truth to Runtime Data Layer state.\n- `Loaded` prewarms the destination; `Activated` reveals the chosen phase.\n- Streamed interactables reconstruct local presentation from durable IDs/state.\n- Late join and load-game tests confirm the same phase.\n\n## Pattern: repeated point of interest\n\n- Level Instance for mixed gameplay/content assembly.\n- Packed Level Blueprint only when the assembly is supported static visual content.\n- OFPA for collaborative editing.\n- Instance-level Data Layer supplies the broad phase; internal layers only for truly reusable variants.\n- Validate every instance transform, HLOD, navigation, and references.\n\n## Pattern: persistent manager\n\nUse 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.\n\n## Required test matrix\n\n| Axis | Minimum cases |\n|---|---|\n| Build | PIE, standalone, cooked Development, shipping-equivalent target |\n| Cache | cold start and warm repeat |\n| Motion | slow, fastest sustained, burst/teleport, sudden reversal |\n| Network | listen/dedicated as applicable, late join, reconnect, packet impairment |\n| State | each Runtime Data Layer transition and save/load reconstruction |\n| Memory | baseline, worst vista, repeated round trip, long soak |\n| HLOD | source/proxy comparison, transition in motion, rebuild after source edit |\n| Failure | missing/late cell, timeout, cancelled travel, invalid reference |\n\n## Acceptance gates\n\n- No player reaches absent collision or interactive state.\n- No unbounded memory rise after repeated traversal.\n- Cell/HLOD transitions meet the project's visible-pop and hitch budgets.\n- Server and clients agree on authoritative Data Layer/gameplay state.\n- A clean builder run is reproducible from source control.\n- Packaged behavior matches editor intent.\n- Debug overrides are removed and experimental dependencies are documented.\n","searchText":"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."},{"slug":"pcg-integration","file":"pcg-integration.md","title":"PCG and World Partition integration","rawMarkdown":"# PCG and World Partition integration\n\nUse this with [`../../unreal-pcg/SKILL.md`](../../unreal-pcg/SKILL.md). World Partition owns spatial residency; PCG owns procedural generation. Keep their responsibilities explicit.\n\n## Partitioned generation\n\nA 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.\n\nDo not assume the PCG grid and World Partition runtime grid are the same thing. Name which grid a setting belongs to.\n\n## Integration workflow\n\n1. Decide whether output is authored/baked, generated on demand in editor, or generated at runtime.\n2. Decide whether the PCG component is partitioned and whether hierarchical generation is needed.\n3. Keep deterministic seeds and stable source data where reproducibility matters.\n4. Assign intended Data Layers and HLOD layers at the source/PCG settings level.\n5. Confirm generated actors inherit the intended Data Layer and HLOD assignments.\n6. Align generation/loading lead distance with player speed and worst generation latency.\n7. Define cleanup when a source cell unloads or runtime generation is cancelled.\n8. Re-run generation after relevant source or partition changes and validate in a cooked build.\n\n## Ownership rules\n\n- Durable gameplay state must not exist only in a generated actor that can be unloaded or regenerated.\n- Generated collision and navigation must be ready before gameplay relies on them.\n- Server-authoritative gameplay generation needs a replication/state plan; do not assume independently seeded clients produce authoritative equivalence.\n- Data Layer state should express world phase; PCG parameters should express generation inputs. Do not create two competing state machines.\n- HLOD represents distant generated visuals only after the output is eligible, assigned, and built appropriately.\n\n## Commandlet\n\nFor 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.\n\nDo not treat successful commandlet exit as sufficient. Check generated actor counts/bounds, warnings, determinism, Data Layers, HLOD inputs, and cooked runtime behavior.\n\n## Failure patterns\n\n- **Duplicate output**: generation ownership or cleanup overlaps across components/cells.\n- **Seams at cell boundaries**: sampling lacks neighbor context or grid sizes/seed domains disagree.\n- **Generated content never unloads**: output ownership, runtime mode, or cleanup is wrong.\n- **Content visible in the wrong phase**: generated actor Data Layer assignment was not inherited as assumed.\n- **HLOD excludes generated content**: output is not eligible/assigned or HLOD was not rebuilt after generation.\n- **Arrival hitch**: generation and cell streaming compete at the point of entry; preload earlier, reduce work, cache where valid, or bake stable content.\n","webMarkdown":"Use this with [`../../unreal-pcg/SKILL.md`](/unreal/unreal-pcg/). World Partition owns spatial residency; PCG owns procedural generation. Keep their responsibilities explicit.\n\n## Partitioned generation\n\nA 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.\n\nDo not assume the PCG grid and World Partition runtime grid are the same thing. Name which grid a setting belongs to.\n\n## Integration workflow\n\n1. Decide whether output is authored/baked, generated on demand in editor, or generated at runtime.\n2. Decide whether the PCG component is partitioned and whether hierarchical generation is needed.\n3. Keep deterministic seeds and stable source data where reproducibility matters.\n4. Assign intended Data Layers and HLOD layers at the source/PCG settings level.\n5. Confirm generated actors inherit the intended Data Layer and HLOD assignments.\n6. Align generation/loading lead distance with player speed and worst generation latency.\n7. Define cleanup when a source cell unloads or runtime generation is cancelled.\n8. Re-run generation after relevant source or partition changes and validate in a cooked build.\n\n## Ownership rules\n\n- Durable gameplay state must not exist only in a generated actor that can be unloaded or regenerated.\n- Generated collision and navigation must be ready before gameplay relies on them.\n- Server-authoritative gameplay generation needs a replication/state plan; do not assume independently seeded clients produce authoritative equivalence.\n- Data Layer state should express world phase; PCG parameters should express generation inputs. Do not create two competing state machines.\n- HLOD represents distant generated visuals only after the output is eligible, assigned, and built appropriately.\n\n## Commandlet\n\nFor 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.\n\nDo not treat successful commandlet exit as sufficient. Check generated actor counts/bounds, warnings, determinism, Data Layers, HLOD inputs, and cooked runtime behavior.\n\n## Failure patterns\n\n- **Duplicate output**: generation ownership or cleanup overlaps across components/cells.\n- **Seams at cell boundaries**: sampling lacks neighbor context or grid sizes/seed domains disagree.\n- **Generated content never unloads**: output ownership, runtime mode, or cleanup is wrong.\n- **Content visible in the wrong phase**: generated actor Data Layer assignment was not inherited as assumed.\n- **HLOD excludes generated content**: output is not eligible/assigned or HLOD was not rebuilt after generation.\n- **Arrival hitch**: generation and cell streaming compete at the point of entry; preload earlier, reduce work, cache where valid, or bake stable content.\n","searchText":"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."},{"slug":"sources","file":"sources.md","title":"Primary sources and maturity notes","rawMarkdown":"# Primary sources and maturity notes\n\nChecked against Unreal Engine 5.8 documentation on 2026-07-19.\n\n## Core documentation\n\n- [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.\n- [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.\n- [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.\n- [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.\n- [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.\n- [`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.\n- [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.\n- [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.\n- [`UWorldPartitionSubsystem::IsStreamingCompleted`](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/UWorldPartitionSubsystem/IsStreamingCompleted) — readiness API used in source-gated travel.\n- [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.\n\n## Maturity and interpretation\n\n- World Partition, Data Layers, HLOD, OFPA, Level Instances, and builder commandlets are established UE5 workflows.\n- World Partition Insights is new in 5.8; verify its configuration and capture overhead in the installed engine.\n- Release-note items marked Experimental, including Fast Geometry-related work and optional external HLOD asset workflows, are not production defaults.\n- `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.\n- Current Epic pages occasionally preserve command spelling quirks. Check console autocomplete/help in the exact engine build before scripting a command.\n\n## Source-use rule\n\nPrefer 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.\n","webMarkdown":"Checked against Unreal Engine 5.8 documentation on 2026-07-19.\n\n## Core documentation\n\n- [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.\n- [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.\n- [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.\n- [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.\n- [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.\n- [`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.\n- [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.\n- [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.\n- [`UWorldPartitionSubsystem::IsStreamingCompleted`](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/UWorldPartitionSubsystem/IsStreamingCompleted) — readiness API used in source-gated travel.\n- [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.\n\n## Maturity and interpretation\n\n- World Partition, Data Layers, HLOD, OFPA, Level Instances, and builder commandlets are established UE5 workflows.\n- World Partition Insights is new in 5.8; verify its configuration and capture overhead in the installed engine.\n- Release-note items marked Experimental, including Fast Geometry-related work and optional external HLOD asset workflows, are not production defaults.\n- `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.\n- Current Epic pages occasionally preserve command spelling quirks. Check console autocomplete/help in the exact engine build before scripting a command.\n\n## Source-use rule\n\nPrefer 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.\n","searchText":"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."},{"slug":"streaming-sources-grids","file":"streaming-sources-grids.md","title":"Streaming sources, runtime grids, and teleports","rawMarkdown":"# Streaming sources, runtime grids, and teleports\n\n## Source model\n\nPlayerControllers can act as streaming sources. Use a `WorldPartitionStreamingSourceComponent` for vehicles, cameras, scripted destinations, or temporary preloading.\n\nImportant source properties include:\n\n- **Target State**: request `Loaded` or `Activated`; when sources overlap, the highest requested state wins.\n- **Priority**: resolves competition between sources; higher priority wins.\n- **Shapes**: constrain the affected region instead of always using an unconstrained radius.\n- **Target Grid** and **Target HLOD Layer**: narrow a source only when a specific design requires it.\n\nAvoid leaving speculative sources active. Each one expands residency and I/O demand.\n\n## Loading-range model\n\nUse a measured lower bound:\n\n```text\nminimum lead distance = maximum approach speed × worst observed ready latency\n                       + camera/interaction look-ahead\n                       + safety margin\n```\n\n`ready latency` includes storage I/O, decompression, object creation, registration, render-resource readiness, and gameplay initialization on the target build.\n\n- Increasing loading range raises lead time but increases resident memory and concurrent work.\n- Decreasing it reduces residency but increases pop-in and arrival hitch risk.\n- Smaller cells increase cell count and management overhead while improving spatial granularity.\n- Larger cells reduce cell count but make each transition heavier and coarser.\n\nDo not tune cell size and range simultaneously. Change one variable, record a repeatable traversal, and compare.\n\n## Runtime grid policy\n\nStart 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.\n\nRelevant grid settings:\n\n- `Cell Size`\n- `Loading Range`\n- `Block on Slow Streaming`\n- `Priority`\n\nBlocking can protect world correctness but visibly stalls play. Decide explicitly which transitions may block and provide UI or transition design when needed.\n\n## Safe teleport pattern\n\n1. Place or move a temporary streaming-source component at the destination.\n2. Enable the source with an appropriate target state and shape.\n3. Poll `UWorldPartitionSubsystem::IsStreamingCompleted` for that source/provider.\n4. On success, teleport the pawn and camera.\n5. Retain the source until the normal player source owns the destination cells.\n6. Disable or remove the temporary source.\n7. On timeout, cancel, present a loading transition, or move to a safe fallback. Never silently teleport into missing collision.\n\n## High-speed traversal pattern\n\n- Lead the source in the velocity/look direction rather than merely inflating a symmetric range.\n- Test sudden turns, braking, respawn, spectating, network correction, and possession changes.\n- Keep gameplay-critical collision and navigation readiness in the acceptance check, not just visual presence.\n\n## Debug commands\n\n```text\nwp.Runtime.ToggleDrawRuntimeHash2D\nwp.Runtime.ToggleDrawRuntimeHash3D\nwp.Runtime.ShowRuntimeSpatialHashGridLevel\nwp.Runtime.ShowRuntimeSpatialHashGridLevelCount\nwp.Runtime.ShowRuntimeSpatialHashGridIndex\nwp.Runtime.OverrideRuntimeSpatialHashLoadingRange\nwp.Runtime.MaxLoadingLevelStreamingCells\n```\n\nUse overrides only for diagnosis. Return to authored settings before recording final performance.\n","webMarkdown":"## Source model\n\nPlayerControllers can act as streaming sources. Use a `WorldPartitionStreamingSourceComponent` for vehicles, cameras, scripted destinations, or temporary preloading.\n\nImportant source properties include:\n\n- **Target State**: request `Loaded` or `Activated`; when sources overlap, the highest requested state wins.\n- **Priority**: resolves competition between sources; higher priority wins.\n- **Shapes**: constrain the affected region instead of always using an unconstrained radius.\n- **Target Grid** and **Target HLOD Layer**: narrow a source only when a specific design requires it.\n\nAvoid leaving speculative sources active. Each one expands residency and I/O demand.\n\n## Loading-range model\n\nUse a measured lower bound:\n\n```text\nminimum lead distance = maximum approach speed × worst observed ready latency\n                       + camera/interaction look-ahead\n                       + safety margin\n```\n\n`ready latency` includes storage I/O, decompression, object creation, registration, render-resource readiness, and gameplay initialization on the target build.\n\n- Increasing loading range raises lead time but increases resident memory and concurrent work.\n- Decreasing it reduces residency but increases pop-in and arrival hitch risk.\n- Smaller cells increase cell count and management overhead while improving spatial granularity.\n- Larger cells reduce cell count but make each transition heavier and coarser.\n\nDo not tune cell size and range simultaneously. Change one variable, record a repeatable traversal, and compare.\n\n## Runtime grid policy\n\nStart 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.\n\nRelevant grid settings:\n\n- `Cell Size`\n- `Loading Range`\n- `Block on Slow Streaming`\n- `Priority`\n\nBlocking can protect world correctness but visibly stalls play. Decide explicitly which transitions may block and provide UI or transition design when needed.\n\n## Safe teleport pattern\n\n1. Place or move a temporary streaming-source component at the destination.\n2. Enable the source with an appropriate target state and shape.\n3. Poll `UWorldPartitionSubsystem::IsStreamingCompleted` for that source/provider.\n4. On success, teleport the pawn and camera.\n5. Retain the source until the normal player source owns the destination cells.\n6. Disable or remove the temporary source.\n7. On timeout, cancel, present a loading transition, or move to a safe fallback. Never silently teleport into missing collision.\n\n## High-speed traversal pattern\n\n- Lead the source in the velocity/look direction rather than merely inflating a symmetric range.\n- Test sudden turns, braking, respawn, spectating, network correction, and possession changes.\n- Keep gameplay-critical collision and navigation readiness in the acceptance check, not just visual presence.\n\n## Debug commands\n\n```text\nwp.Runtime.ToggleDrawRuntimeHash2D\nwp.Runtime.ToggleDrawRuntimeHash3D\nwp.Runtime.ShowRuntimeSpatialHashGridLevel\nwp.Runtime.ShowRuntimeSpatialHashGridLevelCount\nwp.Runtime.ShowRuntimeSpatialHashGridIndex\nwp.Runtime.OverrideRuntimeSpatialHashLoadingRange\nwp.Runtime.MaxLoadingLevelStreamingCells\n```\n\nUse overrides only for diagnosis. Return to authored settings before recording final performance.\n","searchText":"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."},{"slug":"system-selector-conversion","file":"system-selector-conversion.md","title":"System selector and conversion","rawMarkdown":"# System selector and conversion\n\n## Choose the smallest system that meets the need\n\n| Situation | Default choice | Reason |\n|---|---|---|\n| Continuous traversable world with bounded residency | World Partition, streaming enabled | Automatic source-distance streaming and one persistent authoring world |\n| Small map that fits budget | World Partition, streaming disabled, or a normal level | Avoid runtime streaming complexity while retaining the desired authoring workflow |\n| Repeated point of interest or gameplay assembly | Level Instance | Reusable sublevel edited in context |\n| Repeated static architectural/mesh assembly | Packed Level Blueprint | Packs supported static content into an optimized actor |\n| Existing UE5 World Partition project | Extend current model | Avoid a second overlapping streaming authority |\n| Legacy/discrete sublevel architecture | Existing level streaming until migration is justified | Conversion risk may exceed its value |\n\nWorld Partition is Epic's recommended UE5 large-world approach. It is not proof that every map needs cell streaming.\n\n## Conversion safety workflow\n\n1. Work on a source-controlled branch or verified backup.\n2. Inventory Level Blueprints, streaming volumes, scripted sublevel transitions, world settings, always-loaded managers, actor references, foliage, navigation, and HLODs.\n3. Resave the source level and correct unstable actor GUID warnings before conversion.\n4. Run the conversion commandlet with `-ReportOnly` first.\n5. Review actors that cannot be externalized, reference clusters, sublevel handling, and generated configuration.\n6. Convert a copy or use `-ConversionSuffix` until the result passes validation.\n7. Rebuild derived data: HLOD, navigation, foliage, PCG, minimap, or RVT as applicable.\n8. Compare gameplay and memory in a cooked build; keep the old map until parity is demonstrated.\n\nGeneral form:\n\n```text\nUnrealEditor.exe <Project.uproject> <MapName> -run=WorldPartitionConvertCommandlet -ReportOnly\n```\n\nUseful flags include:\n\n- `-ConversionSuffix`: preserve the source and write a converted map with a suffix.\n- `-ReportOnly`: analyze without converting.\n- `-GenerateIni`: emit conversion settings that can be reviewed and reused.\n- `-OnlyMergeSubLevels`: merge sublevels without otherwise converting the result to World Partition.\n\nAvoid `-SkipStableGUIDValidation` as a routine fix. Stable GUIDs are required for repeatable conversion; resave and repair the map instead.\n\n## Reject the conversion when\n\n- success depends on Level Blueprint state or streaming callbacks not yet replaced;\n- non-OFPA actors inside Level Instances must exist at runtime but the design assumes Embedded Mode;\n- reference bundles make most of the world resident;\n- target-device memory or traversal hitching regresses with no credible mitigation;\n- the team cannot rebuild and validate derived content reproducibly.\n\n## Version-sensitive note\n\nUE 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.\n","webMarkdown":"## Choose the smallest system that meets the need\n\n| Situation | Default choice | Reason |\n|---|---|---|\n| Continuous traversable world with bounded residency | World Partition, streaming enabled | Automatic source-distance streaming and one persistent authoring world |\n| Small map that fits budget | World Partition, streaming disabled, or a normal level | Avoid runtime streaming complexity while retaining the desired authoring workflow |\n| Repeated point of interest or gameplay assembly | Level Instance | Reusable sublevel edited in context |\n| Repeated static architectural/mesh assembly | Packed Level Blueprint | Packs supported static content into an optimized actor |\n| Existing UE5 World Partition project | Extend current model | Avoid a second overlapping streaming authority |\n| Legacy/discrete sublevel architecture | Existing level streaming until migration is justified | Conversion risk may exceed its value |\n\nWorld Partition is Epic's recommended UE5 large-world approach. It is not proof that every map needs cell streaming.\n\n## Conversion safety workflow\n\n1. Work on a source-controlled branch or verified backup.\n2. Inventory Level Blueprints, streaming volumes, scripted sublevel transitions, world settings, always-loaded managers, actor references, foliage, navigation, and HLODs.\n3. Resave the source level and correct unstable actor GUID warnings before conversion.\n4. Run the conversion commandlet with `-ReportOnly` first.\n5. Review actors that cannot be externalized, reference clusters, sublevel handling, and generated configuration.\n6. Convert a copy or use `-ConversionSuffix` until the result passes validation.\n7. Rebuild derived data: HLOD, navigation, foliage, PCG, minimap, or RVT as applicable.\n8. Compare gameplay and memory in a cooked build; keep the old map until parity is demonstrated.\n\nGeneral form:\n\n```text\nUnrealEditor.exe <Project.uproject> <MapName> -run=WorldPartitionConvertCommandlet -ReportOnly\n```\n\nUseful flags include:\n\n- `-ConversionSuffix`: preserve the source and write a converted map with a suffix.\n- `-ReportOnly`: analyze without converting.\n- `-GenerateIni`: emit conversion settings that can be reviewed and reused.\n- `-OnlyMergeSubLevels`: merge sublevels without otherwise converting the result to World Partition.\n\nAvoid `-SkipStableGUIDValidation` as a routine fix. Stable GUIDs are required for repeatable conversion; resave and repair the map instead.\n\n## Reject the conversion when\n\n- success depends on Level Blueprint state or streaming callbacks not yet replaced;\n- non-OFPA actors inside Level Instances must exist at runtime but the design assumes Embedded Mode;\n- reference bundles make most of the world resident;\n- target-device memory or traversal hitching regresses with no credible mitigation;\n- the team cannot rebuild and validate derived content reproducibly.\n\n## Version-sensitive note\n\nUE 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.\n","searchText":"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."}]}