How to add a first-person item end to end

Use this guide to add one native first-person item to Motion. You will move from imported meshes and held pose animations to finished visuals for the local player's view in PIE.

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.

Check the character setup

1. Open the Motion character Blueprint.
2. Confirm the main character mesh is the full-body GetMesh() representation.
3. Confirm the character has skeletal mesh components named exactly FirstPersonUpperBody and FirstPersonLowerBody.
4. Confirm all three body meshes use the same character skeleton.
5. Open the skeleton and confirm weapon_r exists.
6. Confirm the full-body skeleton has MotionCamera for Stable presentation. If the camera profile selects Socket mode with another pivot, confirm that configured socket too.
7. Confirm the character has MotionCameraComponent and MotionHeldItemComponent.

The shipped Motion character is the reference layout: one full-body mesh, optional first-person body meshes, camera, and held-item components on the same character.

If the optional first-person body meshes are not ready yet, complete How to author optional first-person body meshes and held pose animations first.

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 complete presentation pair. Choose static meshes, skeletal meshes, or actor classes for the item, then stay in that family for both the local player's view and the world view.

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 both meshes and confirm their pivot/origin supports 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 when the item needs 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 requiring Motion.State.Crouching
Anim_Scanner_HeldPose_Sprint	HeldPoseAnimationRules rule requiring Motion.State.Sprinting
Anim_Scanner_HeldPose_Jump	HeldPoseAnimationRules rule requiring Motion.State.Jumping

The fallback can cover standing, idle, walking, and any state that does not need a special item hold. Add explicit rules only when the item should visibly change posture for that state.

Preview each clip on the character skeleton:

1. The hands should hold the item consistently.
2. The right hand should stay near the intended weapon_r grip.
3. The clip should loop without popping.
4. The configured solve bones should 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 complete 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 both blending the automatic overlay against the host pose and crossfades when a different tag-driven held pose animation wins while the same item remains equipped.

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 needs those clips.

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

Tune the upper-body solve

Leave UpperBodySolveSettings at the defaults for the first pass if your skeleton uses Motion's mannequin-compatible names.

Change these fields only when the animation skeleton or item grip needs it:

Field	Use it when
HeldPoseBranchRootBoneName	The held pose overlay should start from a different branch root
HeldPoseBranchBlendDepth	The upper-body blend includes too much or too little of the body
BoneWeights	Pitch distribution should 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. Confirm 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 the node's BasePose.
8. Route the node output to the final pose, or into your own item action layers that intentionally run after the basic held pose.
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 testing

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's debug held-item input or call the component's toggle path.

For project equipment code, call SetActiveItemConfig with DA_NativeFPItem_Scanner. The component validates the presentation pair first, then updates the holding tag, linked layer, item presentation, camera render tuning, and tuning bridge from the applied usable config. Overlay and presentation-action validation remain 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. Repeat until the item sits correctly in the owner camera.
6. Run ApplyPreviewToPresentation to apply the current transform/render preview and save all preview values back to the config.

The first-person item attaches to FirstPersonUpperBody.weapon_r. Use FirstPersonRelativeTransform for item-specific grip and screen placement. Shared Stable body clearance and presentation anchoring belong to MotionCameraComponent and its profile; item equip does not change camera placement or baseline correction. FirstPersonLowerBody remains grounded.

Tune the world transform

1. In PIE, switch to a second player or external view.
2. Confirm the world item attaches to GetMesh().weapon_r.
3. Use the tuning component's world transform preview fields.
4. Check the item from front, side, and behind as transform and render tuning edits preview live.
5. Run ApplyPreviewToPresentation to apply the current transform/render preview and save all preview values back to the config.

The world presentation is for non-owner visibility, shadows, reflections, and third-person readability. It does not need to match the first-person presentation's scale or silhouette exactly, but it should represent the same item.

Test movement-state presentation

1. Equip the item while standing still.
2. Confirm the fallback held pose appears immediately.
3. Walk without a special walking rule and confirm fallback remains acceptable.
4. Crouch and confirm the crouch held pose wins.
5. Sprint and confirm the sprint held pose wins.
6. Jump if you added a jump entry and confirm the jump held pose wins.
7. Switch quickly between crouch and sprint.
8. Confirm tag-driven changes crossfade over BlendTime.
9. Unequip and confirm the overlay fades back to the host pose.

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

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 and the overlay samples that playback time. Your project decides whether input is accepted, which item is active, what gameplay effect occurs, and whether any gameplay event should replicate.

Tune render values only when needed

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

1. Enable bOverrideFirstPersonFieldOfView only if this item needs a different native first-person FOV.
2. Enable bOverrideFirstPersonScale only if this item needs a different native first-person scale.
3. Test 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 normal held items. Use CustomGraph only when the item intentionally replaces Motion's automatic overlay and owns its held-pose blend, pitch solve, hand IK, recoil, reload, or other pose logic.

In Unreal, the custom overlay is authored as a named Animation Layer graph in the item overlay Animation Blueprint. It is still pose graph logic; Unreal exposes the named layer graph to Motion as an anim blueprint function at runtime. Do not add a second top-level AnimGraph to the host character Animation Blueprint for this path.

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 ensure the My Blueprint panel is visible.
3. In My Blueprint, use the add button for Animation Layers and choose Animation Layer. This creates a new named Animation Layer graph, usually with a temporary name such as NewAnimationLayer.
4. Rename the new Animation Layer graph to the exact value you will put in CustomOverlaySettings.OverlayLayerGraphName, for example FirstPersonItemUpperBodyOverlay.
5. Open the renamed Animation Layer graph.
6. Click the graph background so the graph Details panel is shown, then use Inputs > New Input Pose to add one input pose. Name it InPose.
7. Build the item's extra pose graph logic from that InPose.
8. Do not place another Motion First Person Item Upper Body Overlay node inside this graph. The host overlay node invokes the custom graph; a nested Motion overlay node passes its input through to prevent recursion.
9. Connect the final custom pose to the graph's output pose.
10. Set the item config OverlayMode to CustomGraph.
11. Set CustomOverlaySettings.OverlayLayerClass to the custom Animation Blueprint class.
12. Set CustomOverlaySettings.OverlayLayerGraphName to the Animation Layer graph name from step 4.
13. Compile the custom overlay Animation Blueprint, then compile and test the host Animation Blueprint again.

In CustomGraph mode, InPose is the host pose before Motion's automatic overlay. The layer must provide every pose operation it still needs.

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

1. Add a Sequence Player for the item's 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 custom alpha that should drive this item.
6. In Layer Setup > Branch Filters, add the same branch Motion uses for the automatic overlay unless this item needs a different branch. The default branch is bone pelvis with blend depth 4.
7. Enable Mesh Space Rotation Blend on the Layered Blend per Bone node.
8. Feed the blended pose into the rest of the custom logic, or directly to the output if the item does not need camera pitch, hand IK, recoil, reload, or other action composition.

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 a pure custom graph that should rotate with camera pitch, add the pitch solve inside the layer after the held-pose or action blend:

1. Read Get Native First Person Control Rotation Pitch from the owning MotionAnimInstance. This is Motion overlay pitch, not raw UE controller pitch: looking down is positive and looking up is negative. On observed remote pawns, the getter uses replicated pawn aim rotation so custom graphs receive the same convention without adding their own view-pitch replication.
2. Multiply that value by any 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. For Motion's mannequin-compatible setup, set the rotation Z/roll value to Pitch * Weight for that bone and leave the other rotation axes at 0.
7. Convert back with Convert Component To Local Space, then continue to the output or to more custom logic.

Motion's default 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 for that skeleton. If the pose rotates opposite the camera, multiply the value by -1 at the transform node; do not invert Get Native First Person Control Rotation Pitch globally because it already uses Motion's overlay convention.

If a layered blend makes the weapon rotate the wrong way, check these first:

1. InPose is connected to Base Pose, and the held-pose Sequence Player is connected to Blend Poses 0.
2. Mesh Space Rotation Blend is enabled.
3. The branch filter root and depth match the intended affected body area, usually pelvis with depth 4.
4. Pitch transforms run after the held-pose blend, not before it.
5. The held-pose animation was authored on the same skeleton and in the same weapon/aim convention as the first-person body.

CustomGraph mode bypasses automatic held pose resolution and the automatic upper-body solve. The fallback held pose animation, held pose rules, single-tag entries, automatic blend time, pitch solve, hand IK, and Motion presentation actions are not used for that item's overlay output.

Validate the finished item

Run this checklist before calling the item done:

1. The item config has exactly one complete static mesh, skeletal mesh, or actor presentation pair.
2. Automatic mode has a fallback held pose animation.
3. Each held pose rule has required tags and an animation; each single-tag entry has a valid tag and animation.
4. Configured solve bones exist on the held pose animation skeleton.
5. Presentation action entries have valid tags, finite clips, and positive play rates.
6. The host Animation Blueprint has one Motion overlay node after the host locomotion pose.
7. Owner view shows the first-person upper body and first-person item.
8. Look-down view shows a coherent connection between the upper- and lower-body meshes while the item remains attached to the upper body.
9. Non-owner view shows the world item attached to the full-body mesh.
10. Crouch, sprint, jump, and any movement tags from your project select the expected held pose assets.
11. Equip, unequip, and tag changes blend without stale meshes or stale linked layers.
12. Optional presentation actions start, complete or cancel, and return to the current held pose.

What you built

You added one native first-person item through Motion's 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 item and action state cached for AnimGraph use
• 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 only when the basic held pose is not enough.