unreal-control-rig-ik

Unreal 5.8 Control Rig and IK

Build and debug Unreal IK and retargeting

---
name: unreal-control-rig-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.
---

# Unreal 5.8 Control Rig and IK

## Ownership boundary

This skill owns skeleton transfer, IK Retargeter setup, retarget poses/operations, procedural solves,
contact correction, and animation baking. If a retargeted preview/export is correct but the final pose
is wrong, route to [`unreal-animation-blending`](../unreal-animation-blending/SKILL.md). Route capsule
movement, root-motion authority, and network prediction to
[`unreal-character-movement`](../unreal-character-movement/SKILL.md).

## Route before editing

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

- Transfer animation between skeletons -> IK Rig + IK Retargeter.
- Retarget live from another component -> Retarget Pose From Mesh.
- Procedurally solve a connected body -> Full Body IK.
- Adjust a few limbs at runtime -> IK Rig node or focused IK nodes.
- Author or repair poses/animation -> Control Rig or FK Control Rig in Sequencer.
- Pin contacts after the base transfer is correct -> goals, Speed Planting, or foot placement.

Do not add IK until the source animation, skeleton assignment, chain map, retarget pose,
pelvis, and root behavior have been checked.

## Diagnose first when the request is a bug

Read [`references/symptom-diagnostics.md`](references/symptom-diagnostics.md), then reproduce
with one source sequence and one target mesh. Record whether the defect appears in the IK
Retargeter preview, an exported sequence, runtime retargeting, or only the final AnimGraph.

## Execute

1. Classify the job and isolate the first stage where the pose becomes wrong.
2. Verify source animation, source/target meshes, skeletons, reference poses, and root bones.
3. Define matching retarget roots and chains; inspect every chain mapping.
4. Create and align a dedicated retarget pose.
5. Validate the operation stack from top to bottom, enabling one correction at a time.
6. Add goals/solvers only for contacts or procedural controls that need them.
7. Verify root motion, curves, notifies, runtime component order, LOD, and hidden-mesh ticking.
8. Test representative clips at speed; profile and bake only after the live result is correct.

Load only what applies:

- [`references/ik-retargeter-setup.md`](references/ik-retargeter-setup.md)
- [`references/poses-chains-and-operations.md`](references/poses-chains-and-operations.md)
- [`references/root-pelvis-and-contact.md`](references/root-pelvis-and-contact.md)
- [`references/runtime-retargeting.md`](references/runtime-retargeting.md)
- [`references/control-rig-and-fbik.md`](references/control-rig-and-fbik.md)
- [`references/runtime-foot-placement.md`](references/runtime-foot-placement.md)
- [`references/sequencer-and-baking.md`](references/sequencer-and-baking.md)

## Required answer format

Return:

1. **First broken stage** and evidence.
2. **Chosen system** and rejected alternatives.
3. **Required assets, roots, chains, goals, solvers, and pose assumptions**.
4. **Exact editor/runtime node order and settings to inspect or change**.
5. **One-change-at-a-time diagnostic procedure**.
6. **Root-motion, curve, notify, networking, LOD, and performance consequences**.
7. **Acceptance clips and debug checks**.

## Hard rules

- Set a retarget root on both IK Rigs, normally the pelvis/hips for bipeds.
- Chain names may differ, but source and target chain intent and boundaries must match.
- Create a new retarget pose for alignment; preserve the default pose as a baseline.
- A Retarget Pose operation belongs first in the operation stack.
- Prefer no FK translation for most chains; change translation mode only for a diagnosed need.
- An IK operation cannot move a chain unless the target chain has an IK goal.
- Fix chains, pose, pelvis, root, and speed before masking foot slide with Speed Planting.
- `Ignore Root Lock in Preview` is preview-only; export behavior uses export root-lock settings.
- A hidden runtime source mesh must still tick pose and refresh bones.
- Inertialization normally belongs before final IK; runtime IK belongs after the base pose exists.
- Treat Modular Control Rig according to its Experimental UE 5.8 maturity; do not silently make
  it a shipping dependency.
- Test multiple clips, not only the editor reference pose or one idle.

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

## Ownership boundary

This skill owns skeleton transfer, IK Retargeter setup, retarget poses/operations, procedural solves,
contact correction, and animation baking. If a retargeted preview/export is correct but the final pose
is wrong, route to [`unreal-animation-blending`](/unreal/unreal-animation-blending/). Route capsule
movement, root-motion authority, and network prediction to
[`unreal-character-movement`](/unreal/unreal-character-movement/).

## Route before editing

Read [`references/system-selector.md`](/unreal/unreal-control-rig-ik/system-selector/).

- Transfer animation between skeletons -> IK Rig + IK Retargeter.
- Retarget live from another component -> Retarget Pose From Mesh.
- Procedurally solve a connected body -> Full Body IK.
- Adjust a few limbs at runtime -> IK Rig node or focused IK nodes.
- Author or repair poses/animation -> Control Rig or FK Control Rig in Sequencer.
- Pin contacts after the base transfer is correct -> goals, Speed Planting, or foot placement.

Do not add IK until the source animation, skeleton assignment, chain map, retarget pose,
pelvis, and root behavior have been checked.

## Diagnose first when the request is a bug

Read [`references/symptom-diagnostics.md`](/unreal/unreal-control-rig-ik/symptom-diagnostics/), then reproduce
with one source sequence and one target mesh. Record whether the defect appears in the IK
Retargeter preview, an exported sequence, runtime retargeting, or only the final AnimGraph.

## Execute

1. Classify the job and isolate the first stage where the pose becomes wrong.
2. Verify source animation, source/target meshes, skeletons, reference poses, and root bones.
3. Define matching retarget roots and chains; inspect every chain mapping.
4. Create and align a dedicated retarget pose.
5. Validate the operation stack from top to bottom, enabling one correction at a time.
6. Add goals/solvers only for contacts or procedural controls that need them.
7. Verify root motion, curves, notifies, runtime component order, LOD, and hidden-mesh ticking.
8. Test representative clips at speed; profile and bake only after the live result is correct.

Load only what applies:

- [`references/ik-retargeter-setup.md`](/unreal/unreal-control-rig-ik/ik-retargeter-setup/)
- [`references/poses-chains-and-operations.md`](/unreal/unreal-control-rig-ik/poses-chains-and-operations/)
- [`references/root-pelvis-and-contact.md`](/unreal/unreal-control-rig-ik/root-pelvis-and-contact/)
- [`references/runtime-retargeting.md`](/unreal/unreal-control-rig-ik/runtime-retargeting/)
- [`references/control-rig-and-fbik.md`](/unreal/unreal-control-rig-ik/control-rig-and-fbik/)
- [`references/runtime-foot-placement.md`](/unreal/unreal-control-rig-ik/runtime-foot-placement/)
- [`references/sequencer-and-baking.md`](/unreal/unreal-control-rig-ik/sequencer-and-baking/)

## Required answer format

Return:

1. **First broken stage** and evidence.
2. **Chosen system** and rejected alternatives.
3. **Required assets, roots, chains, goals, solvers, and pose assumptions**.
4. **Exact editor/runtime node order and settings to inspect or change**.
5. **One-change-at-a-time diagnostic procedure**.
6. **Root-motion, curve, notify, networking, LOD, and performance consequences**.
7. **Acceptance clips and debug checks**.

## Hard rules

- Set a retarget root on both IK Rigs, normally the pelvis/hips for bipeds.
- Chain names may differ, but source and target chain intent and boundaries must match.
- Create a new retarget pose for alignment; preserve the default pose as a baseline.
- A Retarget Pose operation belongs first in the operation stack.
- Prefer no FK translation for most chains; change translation mode only for a diagnosed need.
- An IK operation cannot move a chain unless the target chain has an IK goal.
- Fix chains, pose, pelvis, root, and speed before masking foot slide with Speed Planting.
- `Ignore Root Lock in Preview` is preview-only; export behavior uses export root-lock settings.
- A hidden runtime source mesh must still tick pose and refresh bones.
- Inertialization normally belongs before final IK; runtime IK belongs after the base pose exists.
- Treat Modular Control Rig according to its Experimental UE 5.8 maturity; do not silently make
  it a shipping dependency.
- Test multiple clips, not only the editor reference pose or one idle.

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

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.

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

## 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](https://dev.epicgames.com/documentation/en-us/unreal-engine/ik-rig-animation-retargeting-in-unreal-engine)
- [Retargeting Bipeds with IK Rig](https://dev.epicgames.com/documentation/en-us/unreal-engine/retargeting-bipeds-with-ik-rig-in-unreal-engine)
- [Retargeting Operation Stack in UE 5.8](https://dev.epicgames.com/documentation/en-us/unreal-engine/retargeting-operation-stack-in-unreal-engine-5-8)
- [Auto Retargeting](https://dev.epicgames.com/documentation/en-us/unreal-engine/auto-retargeting-in-unreal-engine)
- [Runtime IK Retargeting](https://dev.epicgames.com/documentation/en-us/unreal-engine/runtime-ik-retargeting-in-unreal-engine)
- [Animating IK Retarget Settings / Retarget Profiles](https://dev.epicgames.com/documentation/en-us/unreal-engine/animating-ik-retarget-settings-in-unreal-engine)
- [Fix Foot Sliding with IK Retargeter](https://dev.epicgames.com/documentation/en-us/unreal-engine/fix-foot-sliding-with-ik-retargeter-in-unreal-engine)
- [IK Rig](https://dev.epicgames.com/documentation/en-us/unreal-engine/ik-rig-in-unreal-engine)
- [IK Rig in Animation Blueprints](https://dev.epicgames.com/documentation/en-us/unreal-engine/ik-rig-in-animation-blueprints-in-unreal-engine)
- [Control Rig](https://dev.epicgames.com/documentation/en-us/unreal-engine/control-rig-in-unreal-engine)
- [Create Control Rigs](https://dev.epicgames.com/documentation/en-us/unreal-engine/how-to-create-control-rigs-in-unreal-engine)
- [Full-Body IK](https://dev.epicgames.com/documentation/en-us/unreal-engine/control-rig-full-body-ik-in-unreal-engine)
- [FK Control Rig](https://dev.epicgames.com/documentation/en-us/unreal-engine/fk-control-rig-in-unreal-engine)
- [Control Rig Editor](https://dev.epicgames.com/documentation/en-us/unreal-engine/control-rig-editor-in-unreal-engine)
- [Root Motion](https://dev.epicgames.com/documentation/en-us/unreal-engine/root-motion-in-unreal-engine)

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.


unreal-data-assets-tables

Unreal 5.8 Data Assets and Tables

Design and load data-driven Unreal content

---
name: unreal-data-assets-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.
---

# Unreal 5.8 Data Assets and Tables

## Ownership boundary

This skill owns definition schemas, stable asset IDs, discovery, Asset Manager rules, bundles, and
content-to-cook/chunk ownership. Route runtime residency, reference-chain hitches, and unload policy to
[`unreal-memory-streaming`](../unreal-memory-streaming/SKILL.md), artifact construction and packaged-only
failure isolation to [`unreal-packaging-deployment`](../unreal-packaging-deployment/SKILL.md), and mutable
player/world persistence to [`unreal-save-load`](../unreal-save-load/SKILL.md).

## Select the representation

Read [`references/selector-model.md`](references/selector-model.md) before creating a schema.

- Use a **Data Asset** for one inspectable authored definition with heterogeneous fields.
- Use a **Primary Data Asset** when the definition needs a stable `FPrimaryAssetId`,
  Asset Manager discovery, bundles, explicit loading, or cook rules.
- Use a **Data-Only Blueprint** when authored definitions require inheritance.
- Use a **Data Table** for many homogeneous rows sharing one `FTableRowBase` schema.
- Use a **Curve Table** for keyed numeric progression and interpolation.
- Use a **Data Registry** when multiple read-only sources, override/fallback ordering,
  asynchronous acquisition, or managed caching justify its plugin and indirection.
- Use **SaveGame/runtime objects**, not authored assets, for mutable player or session state.

## Execute

1. State the definition/state boundary, stable identifier, ownership, load lifetime, and
   cook requirements.
2. Choose the smallest representation that satisfies those requirements.
3. Define the schema in C++ when type stability, validation, or broad reuse matters.
4. Choose hard references only for assets that must load with the owner. Use soft
   references when the dependency should load on demand.
5. If using the Asset Manager, configure the Primary Asset Type and scan path before
   relying on discovery. Keep each type in deliberate folders.
6. Load asynchronously before the asset is needed; retain the returned asset or handle
   for the required lifetime and define failure behavior.
7. Validate identifiers, ranges, references, duplicate rows, cross-row relationships,
   and cook inclusion before runtime.
8. Test in a cooked build. Editor discovery and successful PIE loading do not prove that
   an indirectly referenced asset was cooked.

Read the reference matching the task:

- authored definitions: [`references/data-assets-primary.md`](references/data-assets-primary.md)
- tabular schemas/import: [`references/data-tables-curves.md`](references/data-tables-curves.md)
- stable identity and state: [`references/identifiers-state-versioning.md`](references/identifiers-state-versioning.md)
- reference and loading choice: [`references/references-loading.md`](references/references-loading.md)
- Asset Manager/bundles: [`references/asset-manager-bundles.md`](references/asset-manager-bundles.md)
- unloaded discovery: [`references/asset-registry-discovery.md`](references/asset-registry-discovery.md)
- cooking/chunking: [`references/cooking-chunking-audit.md`](references/cooking-chunking-audit.md)
- validation and failures: [`references/validation-debugging.md`](references/validation-debugging.md)
- concrete layouts: [`references/patterns.md`](references/patterns.md)

## Required answer format

Return:

1. **Representation and schema**, including why nearby alternatives were rejected.
2. **Stable identifier and mutable-state boundary**.
3. **Reference graph**, naming hard and soft edges.
4. **Discovery, loading, ownership, and unload sequence**.
5. **Cook/chunk rules** and a packaged-build proof.
6. **Validation rules**, failure behavior, and migration consequences.

Do not invent editor paths, Blueprint nodes, APIs, metadata, or cook behavior.

## Hard rules

- Treat Data Assets, Data Tables, and Data Registries as read-only definitions at runtime.
- Never use an asset object or table-row pointer as persistent mutable game state.
- Never cache a Data Table row pointer beyond local use when the table may reimport.
- Never assume a soft reference loads or cooks its target merely because the path exists.
- Never replace every hard reference with a soft reference; loading boundaries must be
  explicit and worth their complexity.
- Never rename shipped Primary Asset IDs or row identifiers without redirects or migration.
- Query unloaded assets through metadata before calling an API that materializes `UObject`s.
- Validate the cooked artifact, not only the editor database.

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

## Ownership boundary

This skill owns definition schemas, stable asset IDs, discovery, Asset Manager rules, bundles, and
content-to-cook/chunk ownership. Route runtime residency, reference-chain hitches, and unload policy to
[`unreal-memory-streaming`](/unreal/unreal-memory-streaming/), artifact construction and packaged-only
failure isolation to [`unreal-packaging-deployment`](/unreal/unreal-packaging-deployment/), and mutable
player/world persistence to [`unreal-save-load`](/unreal/unreal-save-load/).

## Select the representation

Read [`references/selector-model.md`](/unreal/unreal-data-assets-tables/selector-model/) before creating a schema.

- Use a **Data Asset** for one inspectable authored definition with heterogeneous fields.
- Use a **Primary Data Asset** when the definition needs a stable `FPrimaryAssetId`,
  Asset Manager discovery, bundles, explicit loading, or cook rules.
- Use a **Data-Only Blueprint** when authored definitions require inheritance.
- Use a **Data Table** for many homogeneous rows sharing one `FTableRowBase` schema.
- Use a **Curve Table** for keyed numeric progression and interpolation.
- Use a **Data Registry** when multiple read-only sources, override/fallback ordering,
  asynchronous acquisition, or managed caching justify its plugin and indirection.
- Use **SaveGame/runtime objects**, not authored assets, for mutable player or session state.

## Execute

1. State the definition/state boundary, stable identifier, ownership, load lifetime, and
   cook requirements.
2. Choose the smallest representation that satisfies those requirements.
3. Define the schema in C++ when type stability, validation, or broad reuse matters.
4. Choose hard references only for assets that must load with the owner. Use soft
   references when the dependency should load on demand.
5. If using the Asset Manager, configure the Primary Asset Type and scan path before
   relying on discovery. Keep each type in deliberate folders.
6. Load asynchronously before the asset is needed; retain the returned asset or handle
   for the required lifetime and define failure behavior.
7. Validate identifiers, ranges, references, duplicate rows, cross-row relationships,
   and cook inclusion before runtime.
8. Test in a cooked build. Editor discovery and successful PIE loading do not prove that
   an indirectly referenced asset was cooked.

Read the reference matching the task:

- authored definitions: [`references/data-assets-primary.md`](/unreal/unreal-data-assets-tables/data-assets-primary/)
- tabular schemas/import: [`references/data-tables-curves.md`](/unreal/unreal-data-assets-tables/data-tables-curves/)
- stable identity and state: [`references/identifiers-state-versioning.md`](/unreal/unreal-data-assets-tables/identifiers-state-versioning/)
- reference and loading choice: [`references/references-loading.md`](/unreal/unreal-data-assets-tables/references-loading/)
- Asset Manager/bundles: [`references/asset-manager-bundles.md`](/unreal/unreal-data-assets-tables/asset-manager-bundles/)
- unloaded discovery: [`references/asset-registry-discovery.md`](/unreal/unreal-data-assets-tables/asset-registry-discovery/)
- cooking/chunking: [`references/cooking-chunking-audit.md`](/unreal/unreal-data-assets-tables/cooking-chunking-audit/)
- validation and failures: [`references/validation-debugging.md`](/unreal/unreal-data-assets-tables/validation-debugging/)
- concrete layouts: [`references/patterns.md`](/unreal/unreal-data-assets-tables/patterns/)

## Required answer format

Return:

1. **Representation and schema**, including why nearby alternatives were rejected.
2. **Stable identifier and mutable-state boundary**.
3. **Reference graph**, naming hard and soft edges.
4. **Discovery, loading, ownership, and unload sequence**.
5. **Cook/chunk rules** and a packaged-build proof.
6. **Validation rules**, failure behavior, and migration consequences.

Do not invent editor paths, Blueprint nodes, APIs, metadata, or cook behavior.

## Hard rules

- Treat Data Assets, Data Tables, and Data Registries as read-only definitions at runtime.
- Never use an asset object or table-row pointer as persistent mutable game state.
- Never cache a Data Table row pointer beyond local use when the table may reimport.
- Never assume a soft reference loads or cooks its target merely because the path exists.
- Never replace every hard reference with a soft reference; loading boundaries must be
  explicit and worth their complexity.
- Never rename shipped Primary Asset IDs or row identifiers without redirects or migration.
- Query unloaded assets through metadata before calling an API that materializes `UObject`s.
- Validate the cooked artifact, not only the editor database.

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

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.

# 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

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

## 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

## 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](https://dev.epicgames.com/documentation/en-us/unreal-engine/data-assets-in-unreal-engine)
- [Asset Management](https://dev.epicgames.com/documentation/en-us/unreal-engine/asset-management-in-unreal-engine)
- [Data Driven Gameplay Elements](https://dev.epicgames.com/documentation/en-us/unreal-engine/data-driven-gameplay-elements-in-unreal-engine)
- [Object Pointers](https://dev.epicgames.com/documentation/en-us/unreal-engine/object-pointers-in-unreal-engine)
- [Asynchronous Asset Loading](https://dev.epicgames.com/documentation/en-us/unreal-engine/asynchronous-asset-loading-in-unreal-engine)
- [Asset Registry](https://dev.epicgames.com/documentation/en-us/unreal-engine/asset-registry-in-unreal-engine)
- [Data Registries](https://dev.epicgames.com/documentation/en-us/unreal-engine/data-registries-in-unreal-engine)
- [Data Validation](https://dev.epicgames.com/documentation/en-us/unreal-engine/data-validation-in-unreal-engine)
- [Cooking and Chunking](https://dev.epicgames.com/documentation/en-us/unreal-engine/cooking-content-and-creating-chunks-in-unreal-engine)
- [Preparing Assets for Chunking](https://dev.epicgames.com/documentation/en-us/unreal-engine/preparing-assets-for-chunking-in-unreal-engine)
- [`UPrimaryDataAsset` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/UPrimaryDataAsset)
- [`UPrimaryAssetLabel` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/UPrimaryAssetLabel)
- [`UDataTable` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/UDataTable)
- [`FPrimaryAssetRules` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/FPrimaryAssetRules)

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.