First-person item configs

Motion uses UE 5.6 native first-person rendering for local held items.

Each item is described by a UMotionNativeFirstPersonItemConfig asset. The asset provides a first-person mesh, a matching world-space mesh, automatic gameplay-tag-driven held pose animations or an advanced custom overlay graph, configurable upper-body solve bones, optional linked animation layer compatibility, local transforms for each mesh, and optional camera render tuning for the whole first-person set.

Component profiles are separate. Use the camera component profile for shared camera defaults, native first-person body presentation, and safe-box framing. Use native first-person item configs for per-item meshes, held pose animation selection, overlay graph mode, upper-body solve topology, transforms, optional linked layers, and per-item render tuning.

What a native first-person config is

A native first-person config is a UPrimaryDataAsset consumed by UMotionHeldItemComponent.

The asset owns these runtime fields:

• FirstPersonStaticMesh and WorldStaticMesh: paired static meshes for item presentation.
• FirstPersonSkeletalMesh and WorldSkeletalMesh: paired skeletal meshes for item presentation.
• OverlayMode: chooses Motion's automatic tag-driven overlay path or a project-authored custom graph.
• AutomaticHeldPoseSettings: fallback held pose animation, priority-scored gameplay tag and animation pairs, overlay blend weight, overlay blend time, and held pose transition blend time for automatic mode.
• CustomOverlaySettings: custom overlay layer class and function name for advanced graph mode.
• UpperBodySolveSettings: held pose branch root/depth, pitch-solve bone weights, and hand-IK bone pairs for the automatic overlay.
• LinkedLayerClass: optional item or stance layer for automatic-mode broader pose-set swaps.
• FirstPersonRelativeTransform: local transform applied to the first-person item component.
• WorldRelativeTransform: local transform applied to the world-space item component.
• RenderTuning: optional first-person FOV and scale override for the whole first-person set.

Use either the static mesh pair or the skeletal mesh pair. A config with no pair, a partial pair, or mixed static and skeletal pairs is invalid.

The overlay path has its own validation path. In automatic mode, a valid overlay config needs AutomaticHeldPoseSettings.FallbackHeldPoseAnimation. Each automatic entry must have a valid gameplay tag and animation, and duplicate tags are rejected. Missing automatic data invalidates only the overlay path. The mesh pair can still validate for held-item runtime presentation.

UpperBodySolveSettings tunes Motion's automatic shared body solve. The overlay uses graph-safe tuning from the configured held pose branch root/depth, pitch-solve alpha, BoneWeights, hand-IK enablement, hand-IK alpha, and hand-IK bone pairs. BoneWeights is populated with Motion's mannequin-compatible pitch distribution by default; edit or replace the entries when a project skeleton uses different names or needs a different pitch distribution. An empty BoneWeights array is invalid while pitch solve is enabled. Leaving HandIKBones empty uses Motion's mannequin-compatible hand-IK defaults. Invalid numeric values, missing bone names, duplicate pitch bone weights, or invalid held pose branch settings fail overlay validation and make graph-time solve access fall back to Motion defaults.

Use FirstPersonRelativeTransform for item-specific placement in the animated hand. Do not use item transforms to compensate for shared Motion camera height, pitch target offset, or non-socket camera behavior; MotionCameraComponent owns shared safe-box framing for the upper body and attached item.

Runtime flow

UMotionHeldItemComponent replicates only the active config. The owning client builds local first-person visuals from that config; other machines use the world-space item representation.

The built-in debug toggle uses the component's DefaultDebugItemConfig. Assign that property to a native config asset before using the debug held-item input. If it is not assigned, Motion logs a warning and leaves the held-item state unchanged.

The persistent item components are created once by UMotionHeldItemComponent and reused as the active item changes.

In non-socket camera mode, MotionCameraComponent keeps weighted upper-body and held-item anchors inside the configured final-view safe box. The first-person item inherits that correction because it remains attached to FirstPersonUpperBody.weapon_r.

Upper-body held pose overlay

The default baseline held pose presentation is one pose-in / pose-out upper-body overlay node in the host MotionAnimInstance Animation Blueprint. Route the locomotion/body pose into Motion First Person Item Upper Body Overlay, then route the node output to the final pose or to project-owned action layers. The node resolves the active native item config through UMotionAnimInstance, chooses the current automatic held pose animation from active gameplay tags, crossfades selected held pose animations over AutomaticHeldPoseSettings.HeldPoseTransitionBlendTime, blends the resolved held pose over the configured upper-body/item branch using OverlayBlendWeight and OverlayBlendTime, and applies Motion's pitch and hand-IK solve.

Automatic resolution uses the active ASC gameplay tags:

• The matching AutomaticHeldPoseSettings.HeldPoseAnimations entry with the highest priority value wins.
• Entries with equal priority keep array order, so put more specific tags before broader tags when priorities tie.
• If no entry matches, Motion uses AutomaticHeldPoseSettings.FallbackHeldPoseAnimation.
• Projects can use Motion tags such as Motion.State.Crouching and Motion.State.Sprinting, or project-specific tags such as ADS, injured, swimming, or stance tags.

When the winning automatic held pose animation changes for the same item config, Motion evaluates the outgoing and incoming held pose animations together and crossfades between them. First equip is treated as an item boundary, so the first valid automatic held pose appears immediately at the target overlay weight instead of fading in from the host/base socket pose. Unequip or invalid automatic output fades the last valid held pose back to the host pose using the last valid OverlayBlendTime.

No active item config is a pass-through condition and should not warn. An active automatic config with no effective fallback animation fails the overlay path closed: the host pose passes through and Motion emits a setup warning. An active custom graph config bypasses Motion's automatic held pose resolution entirely.

For advanced items, set OverlayMode to CustomGraph and assign CustomOverlaySettings.OverlayLayerClass. The class must be an Animation Blueprint that implements the function named by CustomOverlaySettings.OverlayLayerFunctionName, and that function must expose exactly one input pose for the host pose. Custom mode validates that graph reference, makes Motion's automatic held pose asset and timing accessors return null or zero, and lets the Motion First Person Item Upper Body Overlay node invoke the custom function instead of Motion's automatic held pose solve. The custom graph is responsible for its own pose logic, transition behavior, blend rules, affected bones, and action composition.

The pitch solve uses Motion's first-person visual pitch convention internally. Do not mirror held pose animation assets, availability flags, blend values, pitch, or solve settings into separate host Animation Blueprint variables for the baseline overlay. The Motion accessors are cached for graph use and remain useful for debug UI or advanced custom graph logic, but the built-in overlay node handles automatic pass-through and fail-closed behavior itself.

PIE tuning

When a valid native config is active in PIE on the locally controlled character, UMotionHeldItemComponent creates a UMotionNativeFirstPersonItemTuningComponent named MotionNativeFirstPersonItemTuning.

Use that component to tune the active native item without spawned preview actors:

• PullCurrentPresentationToPreview: copies the current first-person and world item component relative transforms into the tuning preview fields.
• ApplyPreviewToPresentation: applies the preview transforms and render tuning to the live active item.
• ResetToConfig: restores the preview values from the native config and applies them live.
• SaveToConfig: writes the preview linked layer, transforms, and render tuning back to the UMotionNativeFirstPersonItemConfig asset.

The tuning component edits the native config fields directly. It does not use spawned preview actors, actor-root offsets, or the removed non-native item config type.

Body component contract

Characters that use native first-person item rendering need these mesh components:

• GetMesh(): authoritative full-body mesh and world-space representation.
• FirstPersonUpperBody: first-person upper-body mesh.
• FirstPersonLowerBody: first-person lower-body mesh.

UMotionCameraComponent configures the native primitive roles on the owning client:

• full-body mesh: WorldSpaceRepresentation
• FirstPersonUpperBody: FirstPerson
• FirstPersonLowerBody: FirstPerson

The first-person body meshes follow the full-body pose through leader-pose setup. They should use the same skeleton as the full-body mesh.

Attachment contract

Motion attaches held items to weapon_r.

• The first-person item attaches to FirstPersonUpperBody.
• The world-space item attaches to GetMesh().

Keep the socket name stable across the full-body and first-person body meshes. Per-item offsets belong in the native config transforms, not in runtime spawned actors.

The upper-body and item share the camera-relative framing path. FirstPersonLowerBody stays grounded as the look-down body/legs presentation and is not pulled into the arm/item framing adjustment.

Render tuning

Native first-person FOV and scale are owned by UMotionCameraComponent.

Per-item configs can request:

• bOverrideFirstPersonFieldOfView
• FirstPersonFieldOfView
• bOverrideFirstPersonScale
• FirstPersonScale
• OverrideScope

Use WholeFirstPersonSet for supported overrides. ItemOnly currently logs a warning and leaves camera values unchanged because UE 5.6 exposes native first-person FOV and scale on the camera, not as per-primitive item-only overrides.

Animation responsibilities

Motion's baseline first-person held pose path uses a host held pose overlay graph driven by the item config and MotionAnimInstance resolver APIs. Project-owned firing, reload, recoil, melee, equip timing, and ability-specific action animation should compose after that baseline held pose in the host graph through layers, slots, montages, or project item systems.

Linked layers remain available for broader pose-set swaps:

• FullBody_FirstPersonItemItemSpace: item-specific helper-space or item-space adjustments.
• custom overlay layer functions that a project host graph intentionally routes to in custom graph mode.

In automatic mode, the active native config may select a linked layer through LinkedLayerClass, but automatic held pose does not require ABP_ItemAnimLayersBase or item movement states such as FirstPersonItemIdle, FirstPersonItemMove, or FirstPersonItemSprint. CustomOverlaySettings.OverlayLayerClass belongs to custom graph mode and is separate from the normal LinkedLayerClass pose-set swap. If no item config is active, Motion falls back to unarmed or pass-through behavior without overlay setup warnings.

Current scope

This system owns local first-person and world-space held-item presentation. It does not own:

• inventory semantics
• gameplay equip state
• muzzle logic
• hand target metadata
• generic item role resolution

For an end-to-end setup path, see How to add a first-person item end to end. For compact production steps, see How to create a first-person item config.