How to add a first-person item end to end

Use this guide to add one native first-person item to Motion from imported meshes and held pose animations through a finished owner-view presentation in PIE.

By the end, you will have:

• a valid MotionNativeFirstPersonItemConfig
• paired first-person and world item meshes
• automatic held pose animations for the movement states you choose
• 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, recoil, inventory, and gameplay semantics after the presentation path is 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 character has MotionCameraComponent and MotionHeldItemComponent.

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

[Screenshot placeholder: Character Blueprint Components tree showing MotionCameraComponent, MotionHeldItemComponent, GetMesh(), FirstPersonUpperBody, and FirstPersonLowerBody.]

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.

[Screenshot placeholder: Content Browser showing the item folder structure.]

Import the item meshes

Motion item configs use exactly one complete mesh pair. Choose static meshes or skeletal meshes for the item, then stay in that family for both owner-view and world presentation.

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.

Do not mix FirstPersonStaticMesh with WorldSkeletalMesh, or FirstPersonSkeletalMesh with WorldStaticMesh. Mixed and partial pairs are rejected.

[Screenshot placeholder: Imported first-person and world item meshes side by side in the Content Browser.]

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 tag entry
Anim_Scanner_HeldPose_Idle	AutomaticHeldPoseSettings.FallbackHeldPoseAnimation
Anim_Scanner_HeldPose_Crouch	HeldPoseAnimations entry for Motion.State.Crouching
Anim_Scanner_HeldPose_Sprint	HeldPoseAnimations entry for Motion.State.Sprinting
Anim_Scanner_HeldPose_Jump	HeldPoseAnimations entry for Motion.State.Jumping

The fallback can cover standing, idle, walking, and any state that does not need a special item hold. Add explicit tag entries 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.

[Screenshot placeholder: Animation Sequence preview with the baseline held pose animation and item grip reference.]

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 mesh pair:

Mesh type	Fields
Static	FirstPersonStaticMesh = SM_Scanner_FP, WorldStaticMesh = SM_Scanner_World
Skeletal	FirstPersonSkeletalMesh = SKM_Scanner_FP, WorldSkeletalMesh = SKM_Scanner_World

5. Leave OverlayMode set to Automatic.
6. Set AutomaticHeldPoseSettings.FallbackHeldPoseAnimation to Anim_Scanner_HeldPose_Idle.
7. Set AutomaticHeldPoseSettings.OverlayBlendWeight to 1.0.
8. Start with OverlayBlendTime = 0.12.
9. Start with HeldPoseTransitionBlendTime = 0.12.

OverlayBlendTime controls blending the whole automatic overlay on and off against the host pose. HeldPoseTransitionBlendTime controls crossfades when a different tag-driven held pose animation wins while the same item remains equipped.

[Screenshot placeholder: Item config asset showing the mesh pair and automatic held pose settings.]

Add movement-state held pose entries

1. In AutomaticHeldPoseSettings.HeldPoseAnimations, add an entry for crouch.
2. Set GameplayTag to Motion.State.Crouching.
3. Set HeldPoseAnimation to Anim_Scanner_HeldPose_Crouch.
4. Set Priority to 20.
5. Add an entry for sprint.
6. Set GameplayTag to Motion.State.Sprinting.
7. Set HeldPoseAnimation to Anim_Scanner_HeldPose_Sprint.
8. Set Priority to 30.
9. Add a jump entry only if the item needs a special jump hold.

Higher priority wins when multiple active gameplay tags match. If priorities tie, the earlier array entry wins. Use that rule to decide how a crouch-plus-ADS or sprint-plus-injured case should look.

[Screenshot placeholder: HeldPoseAnimations array showing crouch, sprint, and optional jump entries with priorities.]

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.

[Screenshot placeholder: UpperBodySolveSettings expanded with default or project-specific bone names.]

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 project-owned item action layers that intentionally run after baseline held pose.
9. Compile the Animation Blueprint.

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

[Screenshot placeholder: AnimGraph showing host locomotion pose flowing into Motion First Person Item Upper Body Overlay, then to the final pose.]

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 config first, then updates the holding tag, linked layer, item components, camera render tuning, and tuning bridge from the applied usable config.

[Screenshot placeholder: Character details panel showing DefaultDebugItemConfig assigned.]

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.
5. Run ApplyPreviewToPresentation.
6. Repeat until the item sits correctly in the owner camera.
7. Run SaveToConfig.

The first-person item attaches to FirstPersonUpperBody.weapon_r. Use FirstPersonRelativeTransform for item-specific grip and screen placement. Do not use it to compensate for global camera height or non-socket camera behavior; MotionCameraComponent owns safe-box framing for the upper body and attached item.

[Screenshot placeholder: PIE Details panel showing MotionNativeFirstPersonItemTuning preview transform controls.]

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. Run ApplyPreviewToPresentation.
5. Check the item from front, side, and behind.
6. Run SaveToConfig.

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

[Screenshot placeholder: Two-player PIE view showing owner-view item and non-owner world 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 tag entry 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 HeldPoseTransitionBlendTime.
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.

[Screenshot placeholder: Four-panel comparison of fallback, crouch, sprint, and jump held pose presentation.]

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. Keep OverrideScope set to WholeFirstPersonSet.
4. Test the upper body, lower body, and item together.

ItemOnly scope is intentionally unsupported. UE exposes native first-person FOV and scale through the camera, so Motion can apply supported overrides to the whole first-person set.

[Screenshot placeholder: Item config render tuning fields with whole first-person set scope.]

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

Stay in automatic mode for normal carried items. Use CustomGraph only when the item must own blend logic that Motion's automatic resolver should not own, such as recoil composition, unusual affected bones, or a special project action stack.

To create a custom graph:

1. Create an Animation Blueprint on the same skeleton as the first-person body.
2. Add the function named by CustomOverlaySettings.OverlayLayerFunctionName.
3. Give the function exactly one input pose.
4. Build the item's complete overlay logic inside that function.
5. Return the final overlay pose.
6. Set the item config OverlayMode to CustomGraph.
7. Set CustomOverlaySettings.OverlayLayerClass to the custom Animation Blueprint class.
8. Set CustomOverlaySettings.OverlayLayerFunctionName to the implemented function name.
9. Compile and test the host Animation Blueprint again.

Custom graph mode bypasses automatic held pose resolution. The fallback held pose animation, tag entries, automatic held pose transition timing, and automatic upper-body solve settings are not used for that item's overlay output.

[Screenshot placeholder: Custom overlay Animation Blueprint function with exactly one input pose.]

Validate the finished item

Run this checklist before calling the item done:

1. The item config has exactly one complete mesh pair.
2. Automatic mode has a fallback held pose animation.
3. Each tag entry has a valid gameplay tag, unique tag, priority, and held pose animation.
4. Configured solve bones exist on the held pose animation skeleton.
5. The host Animation Blueprint has one Motion overlay node after the host locomotion pose.
6. Owner view shows the first-person upper body and first-person item.
7. Look-down view shows the lower body without pulling it into arm/item framing.
8. Non-owner view shows the world item attached to the full-body mesh.
9. Crouch, sprint, jump, and any project-specific movement tags select the expected held pose assets.
10. Equip, unequip, and tag changes blend without stale meshes or stale linked layers.

[Screenshot placeholder: Final PIE owner-view shot with the item in the desired framing.]

What you built

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

• MotionNativeFirstPersonItemConfig owns the mesh pair, automatic held pose set, solve tuning, transforms, optional linked layer, optional custom graph, and render tuning
• MotionHeldItemComponent owns runtime presentation and validates the config before applying it
• MotionAnimInstance exposes graph-safe item state
• Motion First Person Item Upper Body Overlay owns baseline held pose, pitch solve, hand IK, and held pose to held pose crossfades
• MotionCameraComponent owns native first-person render tuning and safe-box framing

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

First-person item configsReview the config fields and runtime relationships.Set up MotionAnimInstanceVerify the host Animation Blueprint parent, tag mapping, and graph-safe accessors.Create a linked layerAdd a broader item or stance pose set only when baseline held pose is not enough.