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 paired first-person/world presentation, automatic gameplay-tag-driven held pose animations or an advanced custom overlay graph, optional finite presentation actions, configurable upper-body solve bones, optional linked animation layer compatibility, local transforms for each presentation, and optional camera render tuning for the whole first-person set.

Component profiles are separate. Use the camera component profile for shared camera defaults and Stable body clearance. Use native first-person item configs for per-item presentations, held pose animation selection, finite visual actions, overlay graph mode, upper-body solve settings, 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.
• FirstPersonActorClass and WorldActorClass: paired actor classes for items that need component hierarchies or behavior beyond one mesh.
• OverlayMode: chooses Motion's automatic tag-driven overlay path or a project-authored custom graph.
• AutomaticHeldPoseSettings: fallback held pose animation, conditional tag rules, single-tag animation entries, overlay blend weight, and blend time for automatic mode.
• PresentationActions: finite action clips keyed by gameplay tag, with blend timing and play rate.
• CustomOverlaySettings: custom overlay layer class and graph 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 presentation.
• WorldRelativeTransform: local transform applied to the world item presentation.
• RenderTuning: optional first-person FOV and scale override for the whole first-person set.

Use exactly one static mesh, skeletal mesh, or actor pair. A config with no pair, a partial pair, or mixed presentation types is invalid.

The overlay path has its own validation path. In automatic mode, a valid overlay config needs AutomaticHeldPoseSettings.FallbackHeldPoseAnimation. Each held pose rule needs at least one required tag, no required/blocked overlap, and an animation. Duplicate rules are rejected. Each single-tag entry needs a valid gameplay tag and animation, and duplicate tags are rejected. Missing automatic data invalidates only the overlay path. The presentation pair can validate independently for held-item runtime presentation.

Presentation actions validate separately from basic held pose setup. Each action entry needs a valid action tag, finite action sequence, positive effective play rate, finite duration, and non-negative blend times. Invalid or duplicate action entries fail closed for action requests without breaking the automatic held pose fallback.

UpperBodySolveSettings tunes Motion's automatic shared body solve. The overlay reads tuning cached for AnimGraph use: the held pose branch root/depth, pitch-solve alpha, BoneWeights, hand-IK enablement, hand-IK alpha, and hand-IK bone pairs.

BoneWeights starts with Motion's mannequin-compatible pitch distribution. Leaving it empty uses that default effective pitch distribution; edit or replace the entries when your skeleton uses different names or needs different pitch behavior.

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 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 camera height, body clearance, or baseline presentation anchoring. MotionCameraComponent and its profile own the shared Stable clearance and presentation curves/bounds; item configs do not change camera placement or baseline presentation correction when equipped.

Runtime flow

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

The built-in debug toggle uses the component's DefaultDebugItemConfig. Assign that property when you want a config other than the bundled pistol. When it is null, Motion attempts to load the bundled pistol config; only if that fallback cannot be loaded does it log a warning and leave the held-item state unchanged.

The static and skeletal item components are created once by UMotionHeldItemComponent and reused as the active item changes. Actor-backed presentations are spawned for the active config and destroyed when the presentation is cleared or replaced.

In Stable mode, MotionCameraComponent derives forward camera clearance from the fully composed desired point and the owning capsule, then blends it by final view pitch. Camera placement never samples item state or animation pose. Stable presentation separately samples the full-body MotionCamera socket, aligns that animated reference to the pre-clearance Stable anchor, adds the shared pitch-vector curve, and moves FirstPersonUpperBody with its attached item. Socket mode uses the requested socket as the raw camera origin and bypasses Stable clearance/presentation correction. World-obstruction displacement remains compensated on FirstPersonUpperBody in both modes; FirstPersonLowerBody stays at its authored grounded transform.

Upper-body held pose overlay

The default basic held pose 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 your own 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.BlendTime, blends the resolved held pose over the configured upper-body/item branch, and applies Motion's pitch and hand-IK solve.

Automatic resolution uses the active ASC gameplay tags:

• AutomaticHeldPoseSettings.HeldPoseAnimationRules are evaluated first.
• A rule matches when all RequiredTags are active and no BlockedTags are active.
• Highest Priority wins, then the most specific rule, then array order.
• Single-tag HeldPoseAnimations entries are checked after rules and match a single active tag.
• If no entry matches, Motion uses AutomaticHeldPoseSettings.FallbackHeldPoseAnimation.
• Projects can use Motion tags such as Motion.State.Crouching, Motion.State.Walking, and Motion.State.Sprinting, or their own tags such as ADS, injured, swimming, or stance tags.

Use rules when one state should block another state. For example, a pistol can use RequiredTags = Motion.State.Crouching, Motion.State.Walking for crouch-walk, and RequiredTags = Motion.State.Crouching plus BlockedTags = Motion.State.Walking for crouch-idle.

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 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 BlendTime.

No active item config is a pass-through condition and does not warn. An active automatic config with no effective fallback animation fails the overlay path closed, so the host pose passes through. Use ValidateNativeFirstPersonItemOverlay or ResolveNativeFirstPersonItemAutomaticHeldPoseAnimationWithDiagnostics to retrieve setup errors; the graph-safe resolver does not emit them automatically. An active pure custom graph config bypasses Motion's automatic held pose resolution entirely.

Use CustomGraph only when an item intentionally owns the complete overlay. Custom mode validates the 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 layer graph instead of Motion's automatic held pose solve. In custom mode, InPose is the host pose before Motion's automatic overlay. The custom graph is responsible for its own pose logic, transition behavior, blend rules, affected bones, pitch solve, hand IK, and action composition. Keep the Motion overlay node in the host graph because it invokes the custom graph. Do not add another Motion overlay node inside the custom graph; nested instances pass their input through to prevent recursion.

When a pure custom graph only needs a held-pose branch, use the incoming InPose as the Layered Blend per Bone base pose and the held-pose Sequence Player as the blend pose. Enable mesh-space rotation blend and use the same branch root/depth as the automatic overlay unless the item deliberately affects different bones. A direct Sequence Player output replaces the whole host pose and will not inherit camera-pitch behavior. See How to add a first-person item end to end for concrete custom graph node examples.

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 basic 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.

Held-item presentation actions

Presentation actions are Motion's no-C++ bridge for one-shot visual actions on the active native first-person item. Use them for attack, fire, reload, inspect, melee, or similar item presentation when a finite UAnimSequence is enough and the action should compose inside the same built-in overlay node as the held pose.

Author actions in PresentationActions on the item config:

• ActionTag: the Blueprint request key.
• ActionAnimation: the finite sequence sampled by the overlay.
• BlendInTime, BlendOutTime, and PlayRate: visual timing for the action.

Blueprints request actions from the active MotionHeldItemComponent with RequestHeldItemPresentationAction(ActionTag). The immediate result is one of Started, StartedAndInterruptedPrevious, Invalid, or Unsupported. Completion, cancellation, interruption of the old action, invalid requests, and unsupported requests arrive through OnPresentationActionLifecycle.

Motion owns only the local visual action flow: one active action, playback time, completion, cancellation on item changes, automatic interruption by a new valid action, and terminal-frame sampling. Your project owns inventory, item-bar selection, input buffering, combat rules, ammo, cooldowns, replication, damage, and whether a requested action is allowed.

CustomGraph items return Unsupported for Motion presentation action requests. Put bespoke action composition inside the custom overlay graph.

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 preview transforms and render tuning to the live active item, then saves the preview linked layer, transforms, and render tuning back to the active config and refreshes the held-item presentation.
• 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.

Changing preview transform and render tuning fields in the Details panel applies them live without saving. Linked-layer preview changes take effect after saving and refreshing the held-item presentation. Use ApplyPreviewToPresentation when the current preview should become the saved config value.

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

Body component contract

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

• GetMesh(): full-body mesh for the world view.
• 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. Native Stable presentation requires MotionCamera on that skeleton as its evaluated reference. Socket mode requires the valid pivot named by CameraPivotSocketName.

Attachment contract

Motion attaches held items to weapon_r.

• The first-person item attaches to FirstPersonUpperBody.
• The world 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.

Stable clearance moves the camera rather than FirstPersonUpperBody; the attached item therefore keeps its authored hand relationship. FirstPersonLowerBody stays at its authored grounded transform. Item configuration and the world/full-body representation remain unchanged.

Render tuning

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

Per-item configs can request:

• bOverrideFirstPersonFieldOfView
• FirstPersonFieldOfView
• bOverrideFirstPersonScale
• FirstPersonScale

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

Animation responsibilities

Motion's basic first-person held pose path uses a host held pose overlay graph driven by the item config and MotionAnimInstance resolver APIs. Configured presentation actions can play inside that same overlay when a finite visual one-shot is enough. Firing, reload, recoil, melee, equip timing, and ability-specific animation from your project should still compose after that basic held pose through layers, slots, montages, or project item systems when they need gameplay scheduling, networking, branching, or custom graph behavior.

Linked layers remain available for broader pose-set swaps through the shipped layer interface's locomotion state functions, FullBody_Aiming, FullBody_SkeletalControls, and LeftHandPose_OverrideState. Custom overlay graphs are invoked separately by the Motion overlay node.

In automatic mode, the active native config may select a linked layer through LinkedLayerClass, but automatic held pose does not require ABP_ItemAnimLayersBase or sample item variables such as FirstPersonItem_Idle, FirstPersonItem_Move, or FirstPersonItem_Sprint. 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.

Scope

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

• inventory rules
• gameplay equip state
• muzzle logic
• damage, ammo, cooldowns, or combat rules
• hand target details
• 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. For API lookup, see MotionHeldItemComponent, MotionAnimInstance, and First-person item API reference.