How to add a first-person item end to end

Use this guide to add one native first-person item to Motion. You will create final PIE visuals from imported meshes and held pose animations.

By the end, you will have:

• a valid MotionNativeFirstPersonItemConfig
• paired first-person and world item presentations
• automatic held pose animations for the movement states you choose
• optional presentation actions for finite item one-shots
• one Motion First Person Item Upper Body Overlay node in the host Animation Blueprint
• tuned first-person and world transforms saved back to the config

Use a simple item for the first pass, such as a pistol, tablet, scanner, or tool. Add firing, reload, inspect, recoil, inventory, and gameplay rules after the basic item visuals are working.

Examine the character setup

1. Open the Motion character Blueprint.
2. Make sure that the primary character mesh is the full-body one.
3. Make sure that the character has the two named first-person mesh components.
4. Make sure that the three body meshes use the same character skeleton.
5. Open the skeleton and make sure that weapon_r exists.
6. Make sure that the full-body skeleton has MotionCamera for the Stable camera / Motion 1.6 camera.
7. For Socket mode, make sure that the configured pivot socket exists.
8. Make sure that the character has MotionCameraComponent and MotionHeldItemComponent.

The supplied Motion character is the reference layout. It has one full-body mesh, optional first-person meshes, a camera, and a held-item component.

If the first-person body meshes are unavailable, first use How to author optional first-person body meshes and held pose animations.

Create the item asset folder

1. Create a folder for the item, such as Content/Motion/Items/Scanner.
2. Add subfolders for Meshes, Animations, and Configs.
3. Put first-person assets and world assets near each other so the pair is easy to review.

This guide uses Scanner as the item name. Replace it with your item name as you work.

Import the item meshes

Motion item configs use exactly one presentation pair. Choose static meshes, skeletal meshes, or actor classes / blueprints. Use the same type for the local and world views.

For a static mesh item:

1. Import the first-person item mesh as SM_Scanner_FP.
2. Import the world item mesh as SM_Scanner_World.
3. Open the two meshes and make sure that their origins support attachment to weapon_r.

For a skeletal mesh item:

1. Import the first-person item mesh as SKM_Scanner_FP.
2. Import the world item mesh as SKM_Scanner_World.
3. Assign the correct item skeleton or imported item skeleton.
4. Keep first-person and world meshes as a matching skeletal pair.

For an actor-backed item, create matching first-person and world actor classes. Use this type for a component hierarchy or behavior beyond one mesh.

Do not mix static mesh, skeletal mesh, and actor presentation types. Mixed and partial pairs are rejected.

Import the held pose animations

Import or retarget held pose animations onto the character skeleton used by FirstPersonUpperBody.

Start with these assets:

Animation	Config field or rule
Anim_Scanner_HeldPose_Idle	AutomaticHeldPoseSettings.FallbackHeldPoseAnimation
Anim_Scanner_HeldPose_Crouch	HeldPoseAnimationRules rule with Motion.State.Crouching
Anim_Scanner_HeldPose_Sprint	HeldPoseAnimationRules rule with Motion.State.Sprinting
Anim_Scanner_HeldPose_Jump	HeldPoseAnimationRules rule with Motion.State.Jumping

The fallback can apply to standing, idle, walk, and other standard states. Add a rule only when a state changes the item posture.

Preview each clip on the character skeleton:

1. The hands must hold the item consistently.
2. The right hand must stay near the specified weapon_r grip.
3. The clip must loop without movement at the boundary.
4. The configured solve bones must exist on the held pose animation skeleton.

Create the native item config

1. In the item Configs folder, create a MotionNativeFirstPersonItemConfig asset.
2. Name it DA_NativeFPItem_Scanner.
3. Open the config.
4. Set one presentation pair:

Presentation type	Fields
Static	FirstPersonStaticMesh = SM_Scanner_FP, WorldStaticMesh = SM_Scanner_World
Skeletal	FirstPersonSkeletalMesh = SKM_Scanner_FP, WorldSkeletalMesh = SKM_Scanner_World
Actor	FirstPersonActorClass = BP_Scanner_FP, WorldActorClass = BP_Scanner_World

5. Leave OverlayMode set to Automatic.
6. Set AutomaticHeldPoseSettings.FallbackHeldPoseAnimation to Anim_Scanner_HeldPose_Idle.
7. Start with AutomaticHeldPoseSettings.BlendTime = 0.12.

BlendTime controls the blend with the host pose. It also controls crossfades between tag-driven held pose animations for the same equipped item.

Add movement-state held pose rules

1. In AutomaticHeldPoseSettings.HeldPoseAnimationRules, add a crouch rule.
2. Set RequiredTags to Motion.State.Crouching.
3. Set BlockedTags to Motion.State.Walking when this clip is crouch-idle only.
4. Set HeldPoseAnimation to Anim_Scanner_HeldPose_Crouch.
5. Add a sprint rule with RequiredTags = Motion.State.Sprinting.
6. Set its HeldPoseAnimation to Anim_Scanner_HeldPose_Sprint.
7. Add a crouch-walk or jump rule only if the item uses these clips.

Rules match before single-tag entries. Highest Priority wins, then the most specific matching rule, then array order.

Tune the upper-body solve

Keep the default UpperBodySolveSettings for the first pass if the skeleton uses the mannequin-compatible Motion names.

Change these fields only when necessary for the animation skeleton or item grip:

Field	Use it when
HeldPoseBranchRootBoneName	The held pose overlay must start from a different branch root
HeldPoseBranchBlendDepth	The upper-body blend includes too much or too little of the body
BoneWeights	Pitch distribution must use different bones or weights
HandIKBones	Your skeleton does not use VB Hand_R, VB Hand_L, hand_r, and hand_l
PitchSolveAlpha and HandIKAlpha	Pitch or hand correction feels too strong

Motion validates configured bone names against the held pose animation skeleton. If a configured bone is missing, the automatic overlay fails closed instead of corrupting the pose.

Wire the host Animation Blueprint

1. Open the character Animation Blueprint used by the full-body mesh.
2. Open Class Settings.
3. Make sure that the parent class is MotionAnimInstance.
4. Open the AnimGraph.
5. Find the final locomotion/body pose before output or final skeletal controls.
6. Add one Motion First Person Item Upper Body Overlay node.
7. Route the host pose into BasePose on the node.
8. Route the node output to the final pose or project action layers.
9. Compile the Animation Blueprint.

Do not build a manual Sequence Player or Blend Poses by bool branch for the basic held pose. The Motion overlay node reads the active item config, selected held pose animation, blend timing, pitch, and solve settings through MotionAnimInstance.

Activate the item for a test

Use the debug path for the first pass:

1. Select the MotionHeldItemComponent on the character.
2. Set DefaultDebugItemConfig to DA_NativeFPItem_Scanner.
3. Start PIE.
4. Use the project debug held-item input (Default: "T") or call the component toggle path.

For project equipment code, call SetActiveItemConfig with DA_NativeFPItem_Scanner. The component validates the presentation pair first. Then, it updates the item presentation state from the usable config. Overlay and presentation-action validation stay separate.

Tune the first-person transform in PIE

1. Start PIE with the scanner equipped.
2. Select the character.
3. Select the generated MotionNativeFirstPersonItemTuning component.
4. Adjust the preview first-person transform. Transform and render tuning edits preview live without saving.
5. Adjust the item until its position in the local camera is correct.
6. Run ApplyPreviewToPresentation to apply and save all preview values.

The first-person item attaches to FirstPersonUpperBody.weapon_r. Use FirstPersonRelativeTransform for item-specific grip and screen placement. MotionCameraComponent and its profile control the Stable camera / Motion 1.6 camera. An equipped item does not change camera placement or baseline correction. FirstPersonLowerBody stays grounded.

Tune the world transform

1. In PIE, switch to a second player or external view.
2. Make sure that the world item attaches to Mesh.weapon_r.
3. Use the world transform preview fields on the tuning component.
4. Examine the item from the front, side, and rear.
5. Run ApplyPreviewToPresentation to apply and save all preview values.

The world presentation supports remote visibility, shadows, reflections, and third-person readability. Its scale and silhouette can differ from the first-person presentation. It must represent the same item.

Do a test of movement-state presentation

1. Equip the item while standing still.
2. Make sure that the fallback held pose appears immediately.
3. Walk without a special walk rule and make sure that the fallback stays correct.
4. Crouch and make sure that the crouch held pose wins.
5. Sprint and make sure that the sprint held pose wins.
6. If you added a jump entry, jump and make sure that the jump held pose wins.
7. Switch quickly between crouch and sprint.
8. Make sure that tag-driven changes crossfade during BlendTime.
9. Unequip and make sure that the overlay fades to the host pose.

If a state does not change item posture, first make sure that the gameplay tag is active. Use showdebug abilitysystem and Motion animation logs.

Expected owner-view composition with the item equipped:

Expected look-down composition keeps the lower body visible without pulling the item into the legs:

Expected look-up composition keeps the item in a usable owner-view position:

Expected owner-view composition in a walking pose:

Expected unequip cleanup leaves no stale item mesh:

Add optional presentation actions

Use presentation actions only after the basic held pose path works. They are for local visual one-shots on the active item, not for gameplay rules such as inventory, ammo, cooldowns, damage, or networking.

1. Import or retarget a finite action sequence such as Anim_Scanner_Inspect or Anim_Scanner_Attack.
2. Open DA_NativeFPItem_Scanner.
3. Add a PresentationActions entry.
4. Set ActionTag to the tag your Blueprint will request, such as your own Item.Action.Inspect.
5. Set ActionAnimation to the action sequence.
6. Set BlendInTime, BlendOutTime, and PlayRate.
7. From Blueprint, call RequestHeldItemPresentationAction on MotionHeldItemComponent.
8. Branch on the immediate result: Started, StartedAndInterruptedPrevious, Invalid, or Unsupported.
9. Bind OnPresentationActionLifecycle for completion, cancellation, interruption, invalid requests, and unsupported requests.

Motion advances presentation action playback locally. The overlay samples this playback time. Your project controls input, active items, gameplay effects, and replication.

Adjust render values only when necessary

Use RenderTuning after transforms and held pose animation are already working.

1. Enable bOverrideFirstPersonFieldOfView only for a different native first-person FOV.
2. Enable bOverrideFirstPersonScale only for a different native first-person scale.
3. Do a test of the upper body, lower body, and item together.

UE exposes native first-person FOV and scale through the camera, so Motion applies supported overrides to the whole first-person set.

Add a custom overlay graph only if automatic mode is not enough

Stay in automatic mode for standard held items. Use CustomGraph only when the item replaces all automatic Motion overlay behavior.

Create the custom overlay as a named Animation Layer graph in the item overlay Animation Blueprint. Unreal exposes this graph to Motion at runtime. Do not add a second top-level AnimGraph to the host character Animation Blueprint.

To create a custom overlay graph:

1. Create an Animation Blueprint on the same skeleton as the first-person body.
2. Open that Animation Blueprint and make sure that the My Blueprint panel is visible.
3. In My Blueprint, add an Animation Layer.
4. Rename the new graph to the exact CustomOverlaySettings.OverlayLayerGraphName value.
5. Open the renamed Animation Layer graph.
6. Select the graph background to show the graph Details panel.
7. Use Inputs > New Input Pose to add one input pose.
8. Name the input pose InPose.
9. Build the extra item pose logic from InPose.
10. Do not put another Motion overlay node in this graph.
11. Connect the final custom pose to the graph output pose.
12. Set the item config OverlayMode to CustomGraph.
13. Set CustomOverlaySettings.OverlayLayerClass to the custom Animation Blueprint class.
14. Set CustomOverlaySettings.OverlayLayerGraphName to the graph name from step 4.
15. Compile the custom overlay Animation Blueprint.
16. Compile the host Animation Blueprint and do a test again.

In CustomGraph mode, InPose is the host pose before the automatic Motion overlay. The layer must provide all applicable pose operations.

For a pure custom held-pose override that keeps the host pose:

1. Add a Sequence Player for the item held-pose animation.
2. Add a Layered Blend per Bone.
3. Connect InPose to the Layered Blend per Bone Base Pose.
4. Connect the Sequence Player to Blend Poses 0.
5. Set Blend Weights 0 to 1.0 or to the applicable custom alpha.
6. In Layer Setup > Branch Filters, add the automatic Motion overlay branch.
7. Use a different branch only if the item affects different bones.
8. Enable Mesh Space Rotation Blend on the Layered Blend per Bone node.
9. Connect the blended pose to the remaining custom logic or the output.

Do not connect a Sequence Player directly to the layer output unless the item intentionally replaces the whole host pose. A direct sequence output ignores InPose, so the first-person body will not inherit the host pose or camera-pitch behavior.

For camera-pitch rotation, add the pitch solve after the held-pose or action blend:

1. Read Get Native First Person Control Rotation Pitch from the local MotionAnimInstance.
2. Multiply that value by the item-specific pitch alpha.
3. Convert the blended local pose to component space with Convert Local To Component Space.
4. Add one Transform (Modify) Bone node per pitch bone.
5. Set each Transform (Modify) Bone node to Rotation Mode = Add to Existing and Rotation Space = Component Space.
6. Set rotation Z to Pitch * Weight for the mannequin-compatible Motion setup.
7. Keep the other rotation axes at 0.
8. Convert back with Convert Component To Local Space.

The getter uses the Motion overlay pitch convention. A downward view is positive, and an upward view is negative. On remote pawns, it uses replicated pawn aim rotation.

The default Motion pitch distribution is:

Bone	Weight
spine_01	0.15
spine_02	0.10
spine_03	0.10
spine_04	0.10
spine_05	0.10
neck_01	0.15
neck_02	0.20
head	0.10

If a project skeleton uses a different pitch axis, use the matching axis. If the pose turns opposite the camera, multiply the transform value by -1. Do not invert Get Native First Person Control Rotation Pitch globally. It already uses the Motion overlay convention.

If a layered blend turns the weapon in the wrong direction, examine these items:

1. Connect InPose to Base Pose.
2. Connect the held-pose Sequence Player to Blend Poses 0.
3. Enable Mesh Space Rotation Blend.
4. Make sure that the branch filter applies to the specified body area.
5. Run pitch transforms after the held-pose blend.
6. Use the same skeleton and aim convention for the held-pose animation.

CustomGraph mode does not use automatic held pose resolution or the automatic upper-body solve. It also does not use automatic pose, blend, solve, IK, or action settings.

Validate the finished item

Examine these items before you finish the item:

1. The item config has exactly one static mesh, skeletal mesh, or actor presentation pair.
2. Automatic mode has a fallback held pose animation.
3. Each held pose rule has necessary tags and an animation.
4. Each single-tag entry has a valid tag and animation.
5. Configured solve bones exist on the held pose animation skeleton.
6. Presentation action entries have valid tags, finite clips, and positive play rates.
7. The host Animation Blueprint has one Motion overlay node after the locomotion pose.
8. The local view shows the first-person upper body and item.
9. The downward view shows a continuous connection between the upper-body and lower-body meshes.
10. The remote view shows the world item on the full-body mesh.
11. Movement tags select the expected held pose assets.
12. Equip, unequip, and tag changes blend without stale meshes or linked layers.
13. Optional presentation actions end or cancel and return to the active held pose.

What you built

You added one native first-person item through the Motion item path:

• MotionNativeFirstPersonItemConfig owns the presentation pair, automatic held pose set, optional presentation actions, solve tuning, transforms, optional linked layer, optional custom graph, and render tuning
• MotionHeldItemComponent owns runtime presentation, validates the config before applying it, and exposes the optional action request/delegate bridge
• MotionAnimInstance exposes stored item and action state to the AnimGraph
• Motion First Person Item Upper Body Overlay owns the basic held pose, configured presentation action composition, pitch solve, hand IK, and automatic held pose transitions
• MotionCameraComponent owns native first-person render tuning, shared Stable camera clearance, and the shared bounded upper-body/item presentation correction while leaving FirstPersonLowerBody at its authored transform

Use the same path for the next item, then add item-specific gameplay actions after the presentation is stable.

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

First-person item configsReview the config fields and runtime relationships.Set up MotionAnimInstanceVerify the host Animation Blueprint parent, tag mapping, and accessors safe for the AnimGraph.Create a linked layerAdd a broader item or stance pose set.