How to create a first-person item config

Use this guide to add a native local first-person item presentation asset for Motion.

Create the config asset

1. Create a new MotionNativeFirstPersonItemConfig asset.
2. Choose one mesh mode:
   • set both FirstPersonStaticMesh and WorldStaticMesh, or
   • set both FirstPersonSkeletalMesh and WorldSkeletalMesh.
3. Leave OverlayMode set to Automatic for Motion's built-in tag-driven held pose overlay.
4. Set AutomaticHeldPoseSettings.FallbackHeldPoseAnimation to the baseline first-person held pose animation.
5. Add optional AutomaticHeldPoseSettings.HeldPoseAnimations entries. Each entry pairs a gameplay tag with a held pose animation and priority; the highest-priority matching active tag wins.
6. Tune AutomaticHeldPoseSettings.OverlayBlendWeight, OverlayBlendTime, and HeldPoseTransitionBlendTime if the defaults do not match the item. OverlayBlendTime controls automatic overlay enable/disable against the host pose; HeldPoseTransitionBlendTime controls crossfades when a different automatic held pose animation wins.
7. Leave UpperBodySolveSettings at Motion defaults, or tune the held pose branch, pitch-solve BoneWeights, and hand-IK bones for this item.
8. Set FirstPersonRelativeTransform for item-specific local placement in the animated hand.
9. Set WorldRelativeTransform for the replicated/full-body view.
10. Optionally set LinkedLayerClass when this automatic-mode item also needs a broader item/stance pose-set swap.
11. Activate the config through gameplay, Blueprint, or your equipment system.

If the item only needs baseline first-person held pose, leave LinkedLayerClass unset and let the host's Motion First Person Item Upper Body Overlay node read AutomaticHeldPoseSettings from the active config. Use LinkedLayerClass only when the item also needs a broader pose-set swap.

For advanced items that need their own overlay graph, set OverlayMode to CustomGraph instead. Assign CustomOverlaySettings.OverlayLayerClass to an Animation Blueprint that implements the custom overlay function named by CustomOverlaySettings.OverlayLayerFunctionName; that function should take exactly one input pose. Custom graph mode bypasses Motion's automatic held pose animation resolver and automatic held pose transitions, so AutomaticHeldPoseSettings is not required for that item.

See How to add a first-person item end to end for the advanced custom graph contract in context.

Build the held pose overlay

The character Animation Blueprint should inherit from MotionAnimInstance. Around the host final pose, insert one Motion First Person Item Upper Body Overlay node as a pose-in / pose-out step:

1. Generate the host locomotion and body pose as usual.
2. Route that pose into the overlay node's BasePose.
3. Route the overlay node's output to the final pose, or into project-owned item action layers when those actions need to override baseline held pose.
4. Do not add host variables or manual pins for held pose animation assets, availability flags, blend values, pitch, or solve settings; the node reads the active config through MotionAnimInstance.

No active item config is a clean pass-through state and should not warn. An active automatic config with no effective fallback held pose animation should pass through and warn once for that setup. Do not add external Blueprint state mirrors just to avoid no-item warnings.

Missing upper-body solve tuning is not an error. The config's default struct supplies Motion's mannequin-compatible branch, pitch distribution, and hand-IK bones. Invalid numeric solve values, missing configured bone names, or invalid held pose branch settings fail overlay validation.

Prepare the character meshes

The owning character needs the standard full-body mesh plus two fixed first-person body meshes:

• GetMesh(): full-body mesh and world-space representation.
• FirstPersonUpperBody: first-person upper body.
• FirstPersonLowerBody: first-person lower body.

All three body meshes should share a skeleton. UMotionCameraComponent applies UE native first-person primitive roles locally during BeginPlay.

Attach item meshes

Motion uses the weapon_r socket for both item representations:

• the first-person item attaches to FirstPersonUpperBody
• the world-space item attaches to GetMesh()

Keep the socket present on both body meshes. Use the config transforms for per-item offsets.

Do not use item transforms as a workaround for the non-socket camera path. Motion's shared safe-box framing keeps FirstPersonUpperBody and the attached item aligned to the final camera view by default; item transforms are for authored item feel.

Tune the item in PIE

1. Start PIE with the item config active on the locally controlled character.
2. Select the generated MotionNativeFirstPersonItemTuning component on the character.
3. Adjust the preview transforms or render tuning on the component.
4. Use ApplyPreviewToPresentation to preview values live.
5. Use SaveToConfig to write the values back to the active MotionNativeFirstPersonItemConfig asset.

Use PullCurrentPresentationToPreview if you moved the generated first-person or world item components directly and want to capture those current relative transforms before saving.

Tune render values

Use the config's RenderTuning only when an item needs a different native first-person camera presentation:

1. Enable the FOV and/or scale override.
2. Set OverrideScope to WholeFirstPersonSet.
3. Adjust FirstPersonFieldOfView or FirstPersonScale.

ItemOnly scope is intentionally unsupported for now. UE 5.6 exposes native first-person FOV and scale on UCameraComponent, so Motion cannot apply an item-only native override without changing the entire first-person set.

Validate the config

Before testing in PIE, check the mesh pair and overlay setup separately.

The config needs exactly one complete mesh pair:

• static first-person mesh plus static world mesh
• or skeletal first-person mesh plus skeletal world mesh

Partial pairs and mixed static/skeletal pairs are rejected at runtime and leave the previous presentation cleared.

Automatic overlay mode needs AutomaticHeldPoseSettings.FallbackHeldPoseAnimation. Optional gameplay-tag entries are resolved from the active ASC tag container:

• The matching HeldPoseAnimations entry with the highest priority value wins.
• Entries with equal priority keep array order, so put more specific tags before broader tags when priorities tie.
• If no entry matches, the fallback animation plays.
• Tags can be Motion movement tags or project-owned tags.

For upper-body solve tuning, tune HeldPoseBranchRootBoneName, HeldPoseBranchBlendDepth, PitchSolveAlpha, BoneWeights, bEnableHandIK, HandIKAlpha, and HandIKBones. BoneWeights is populated with Motion's mannequin-compatible pitch distribution by default; edit or replace those entries when your skeleton uses different names or needs a different pitch distribution. Leave HandIKBones empty for Motion's mannequin-compatible hand-IK defaults.