How to create a first-person item config

Use this guide to add one MotionNativeFirstPersonItemConfig for local first-person item visuals. The config controls visuals. Your project controls gameplay and networking.

Create the config asset

1. Create a new MotionNativeFirstPersonItemConfig asset.
2. Choose one presentation mode.
   • Set FirstPersonStaticMesh and WorldStaticMesh.
   • Or, set FirstPersonSkeletalMesh and WorldSkeletalMesh.
   • Or, set FirstPersonActorClass and WorldActorClass.
3. Keep OverlayMode set to Automatic for the built-in Motion 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.
6. Use HeldPoseAnimations for simple single-tag variants.
7. Adjust AutomaticHeldPoseSettings.BlendTime if the default does not match the item.
8. Keep the default UpperBodySolveSettings, or adjust the branch, pitch weights, and hand-IK bones.
9. Set FirstPersonRelativeTransform for item-specific placement in the animated hand.
10. Set WorldRelativeTransform for the full-body view.
11. Set LinkedLayerClass if the item uses a broader item or stance pose set.
12. Add optional PresentationActions for finite visual actions.
13. Activate the config through gameplay, Blueprint, or your equipment system.

For a basic first-person held pose, keep LinkedLayerClass unset. The host overlay node reads AutomaticHeldPoseSettings from the active config. Use LinkedLayerClass only for a broader pose set.

For an item that replaces the built-in Motion overlay, use this setup:

1. Set OverlayMode to CustomGraph.
2. Assign an Animation Blueprint to CustomOverlaySettings.OverlayLayerClass.
3. Add a named Animation Layer graph to that Blueprint.
4. Set its name to the exact CustomOverlaySettings.OverlayLayerGraphName value.
5. Add exactly one input pose named InPose.
6. Add the custom item pose logic after InPose.
7. Return the final overlay pose.

InPose is the host pose before the automatic Motion overlay. The custom layer must include all necessary pose, pitch, IK, recoil, and action logic. Keep the Motion overlay node in the host graph because it calls the custom graph. Do not add a Motion overlay node to the custom graph. Nested instances pass through their input 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 for a finite visual item action. C++ changes and a Motion inventory framework are not necessary.

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. The result describes only the immediate presentation request. Use OnPresentationActionLifecycle for later lifecycle events.

Motion does not decide if gameplay permits the action. Evaluate ammo, cooldowns, inventory, abilities, networking, and damage in project code.

Build the held pose overlay

The character Animation Blueprint must inherit from MotionAnimInstance. Add one Motion First Person Item Upper Body Overlay node around the final host pose:

1. Generate the host locomotion and body pose as usual.
2. Route that pose into BasePose on the overlay node.
3. Route the overlay output to the final pose or to project item action layers.
4. Do not add host variables or manual pins for the config values.

If no item config is active, the node passes through the pose without a warning. It also passes through an automatic config with no effective fallback animation. Call ValidateNativeFirstPersonItemOverlay or the diagnostic resolver for specific setup errors. The graph-safe resolver does not emit these errors. Do not add external Blueprint state for the no-item state.

Missing upper-body solve settings do not cause an error. The default config struct supplies a mannequin-compatible branch, pitch distribution, and hand-IK bones. Invalid values, bone names, or branch settings fail overlay validation.

Prepare the character meshes

A character with native first-person item visuals uses one full-body mesh and two fixed first-person body meshes:

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

The three body meshes must share a skeleton. The body meshes must have weapon_r for item attachment. The native Stable camera / Motion 1.6 camera uses MotionCamera on the full-body skeleton as its evaluated reference. Socket mode must have the valid pivot in CameraPivotSocketName. During BeginPlay, UMotionCameraComponent applies native first-person primitive roles to the local character.

Attach item meshes

Motion uses the weapon_r socket for the two item representations:

• the first-person item attaches to FirstPersonUpperBody
• the world item attaches to Mesh

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

Use item transforms for authored grip and item-specific screen placement. Shared camera profile fields control the Stable camera / Motion 1.6 camera. Item configs do not override these fields. An equipped item does not change the camera position.

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 settings on the component.
4. Use ApplyPreviewToPresentation to apply and save all preview values.
5. Use SaveToConfig to save preview values and refresh the active presentation.

Use PullCurrentPresentationToPreview to copy direct item component changes to the preview before you save.

Tune render values

Use RenderTuning only for a different native first-person camera presentation:

1. Enable the FOV override, scale override, or the two overrides.
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 a PIE test, validate the presentation pair and overlay setup separately.

The config must have exactly one 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 must have AutomaticHeldPoseSettings.FallbackHeldPoseAnimation. Motion resolves optional gameplay-tag entries from the active ASC tag container:

• HeldPoseAnimationRules match first. All necessary tags must be active, and no blocked tags can 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.

Adjust the upper-body solve fields for the project skeleton. By default, BoneWeights contains the mannequin-compatible Motion pitch distribution. Edit these entries if the skeleton uses different names or pitch distribution. Keep HandIKBones empty to use the mannequin-compatible Motion defaults.

Presentation action validation is separate from automatic held pose validation. Invalid action data makes action requests fail closed. It does not disable the basic held pose.

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