How to create a first-person item config

Use this guide to add one MotionNativeFirstPersonItemConfig for Motion's local first-person item visuals. The config controls visuals; your project owns inventory, equipment rules, damage, ammo, and networking.

Create the config asset

1. Create a new MotionNativeFirstPersonItemConfig asset.
2. Choose one presentation mode:
   • set both FirstPersonStaticMesh and WorldStaticMesh, or
   • set both FirstPersonSkeletalMesh and WorldSkeletalMesh, or
   • set both FirstPersonActorClass and WorldActorClass.
3. Leave OverlayMode set to Automatic for Motion's built-in tag-driven held pose overlay.
4. Set AutomaticHeldPoseSettings.FallbackHeldPoseAnimation to the basic first-person held pose animation.
5. Add optional AutomaticHeldPoseSettings.HeldPoseAnimationRules for combined states such as crouch-walk. Use HeldPoseAnimations for simple single-tag variants.
6. Tune AutomaticHeldPoseSettings.BlendTime if the default does not match the item. It controls automatic overlay enable/disable against the host pose and 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. Optionally add PresentationActions for finite visual one-shots such as attack, fire, reload, inspect, or melee.
12. Activate the config through gameplay, Blueprint, or your equipment system.

If the item only needs a basic 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 intentionally replace Motion's built-in overlay result, set OverlayMode to CustomGraph. Assign CustomOverlaySettings.OverlayLayerClass to an Animation Blueprint that implements a named Animation Layer graph. Create that graph from the Animation Blueprint's My Blueprint panel with Animation Layers > Animation Layer, rename it to the exact value in CustomOverlaySettings.OverlayLayerGraphName, add exactly one input pose named InPose, add the item's pose logic after that input, and return the final overlay pose. In this mode, InPose is the host pose before Motion's automatic overlay and the custom layer must include any held-pose blend, pitch rotation, IK, recoil, or action composition the item still needs. Keep the Motion overlay node in the host graph because it invokes the custom graph. Do not add another Motion overlay node inside the custom graph; nested instances pass their input through to prevent recursion.

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

Add optional presentation actions

Use PresentationActions when the item needs a finite visual action but the project should not edit C++ or build a full inventory/weapon framework inside Motion.

For each action:

1. Set ActionTag to the gameplay tag your Blueprint will request.
2. Set ActionAnimation to a finite sequence on the first-person body skeleton.
3. Set BlendInTime, BlendOutTime, and PlayRate.

Blueprint calls RequestHeldItemPresentationAction on MotionHeldItemComponent. Treat the returned result as only the immediate presentation request outcome. Use OnPresentationActionLifecycle for visual completion, cancellation, interruption, invalid requests, and unsupported requests.

Motion does not decide whether the action is legal gameplay. Check ammo, cooldowns, inventory selection, ability state, networking, and damage in project code before or around the presentation request.

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 your own item action layers when those actions need to override configured Motion presentation actions or the basic 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 does not warn. An active automatic config with no effective fallback held pose animation also passes through. Call ValidateNativeFirstPersonItemOverlay or the diagnostic resolver when you need the specific setup errors; the graph-safe resolver itself does not emit them. Do not add external Blueprint state mirrors for the no-item state.

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

A character that uses native first-person item visuals needs the standard full-body mesh plus two fixed first-person body meshes:

• GetMesh(): full-body mesh for the world view.
• FirstPersonUpperBody: first-person upper body.
• FirstPersonLowerBody: first-person lower body.

All three body meshes should share a skeleton. The body meshes need weapon_r for item attachment, and native Stable presentation needs MotionCamera on the full-body skeleton as its evaluated reference. Socket mode additionally requires the valid pivot named by CameraPivotSocketName. When native first-person presentation is enabled and both named meshes are present, UMotionCameraComponent applies UE native first-person primitive roles to the locally controlled character during BeginPlay.

Attach item meshes

Motion uses the weapon_r socket for both item representations:

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

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

Use item transforms for authored grip and item-specific screen placement. Stable body clearance and baseline presentation correction belong to the camera profile's shared clearance/anchor/curve/budget fields; item configs do not override them or change the camera position when equipped.

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, linked layer, or render tuning on the component. Transform and render tuning edits preview live without saving; linked-layer changes take effect after saving and refreshing the held-item presentation.
4. Use ApplyPreviewToPresentation when the current transform/render preview should be applied and all preview values should be saved back to the active MotionNativeFirstPersonItemConfig asset.
5. Use SaveToConfig when you only need to write the current preview values and refresh the active presentation.

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. Adjust FirstPersonFieldOfView or FirstPersonScale.

UE 5.6 exposes native first-person FOV and scale on UCameraComponent, so Motion applies native overrides to the whole first-person set.

Validate the config

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

The config needs exactly one complete presentation pair:

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

Partial pairs and mixed static mesh, skeletal mesh, or actor presentation types are rejected at runtime and clear the active presentation.

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

• HeldPoseAnimationRules match first: all required tags must be active, and no blocked tags may be active.
• Highest rule priority wins, then highest specificity, then array order.
• HeldPoseAnimations entries match one active tag after rules.
• If no rule or single-tag entry matches, the fallback animation plays.
• Tags can be Motion movement tags or tags from your project.

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.

Presentation action validation is separate from automatic held pose validation. Invalid action tags, duplicate action tags, missing action clips, invalid effective play rate, invalid duration, and invalid blend timing make action requests fail closed without disabling the basic held pose.

For complete API lookup, see MotionHeldItemComponent and First-person item API reference.