First-person item configs

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

Each item uses a UMotionNativeFirstPersonItemConfig asset. The asset supplies paired first-person and world presentations. It also contains held poses, actions, solve settings, transforms, linked layers, and render settings.

Component profiles are separate. Use the camera component profile for shared camera defaults and Stable body clearance. Use item configs for item presentation, animation, solve, transform, layer, and render settings.

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 with component hierarchies or behavior beyond one mesh.
• OverlayMode: selects the automatic Motion overlay path or a project 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 has separate validation. In automatic mode, a valid config must have AutomaticHeldPoseSettings.FallbackHeldPoseAnimation. Each held pose rule must have one or more tags and an animation. Necessary tags and blocked tags must not overlap. Motion rejects duplicate rules.

Each single-tag entry must have a valid gameplay tag and animation. Motion rejects duplicate tags. Missing automatic data invalidates only the overlay. The presentation pair can pass validation independently.

Presentation actions validate separately from basic held pose setup. Each action entry must have valid tags, sequence, play rate, duration, and blend times. Invalid or duplicate action entries fail closed. They do not stop the automatic held pose fallback.

UpperBodySolveSettings adjusts the automatic shared Motion body solve. The overlay reads stored branch, pitch, and hand-IK settings for AnimGraph use.

BoneWeights starts with the mannequin-compatible Motion pitch distribution. An empty array uses this default distribution. Edit the entries for different bone names or pitch behavior.

An empty HandIKBones array uses the mannequin-compatible Motion defaults. Invalid solve data fails overlay validation. Solve access then uses the Motion defaults.

Use FirstPersonRelativeTransform for item-specific placement in the animated hand. Do not use item transforms to compensate for shared camera behavior. MotionCameraComponent and its profile control the Stable camera / Motion 1.6 camera. Item configs do not change camera placement or baseline presentation correction.

Runtime flow

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

The built-in debug control uses DefaultDebugItemConfig on the component. Assign this property to use a config other than the supplied pistol. If it is null, Motion tries to load the supplied pistol config. If loading fails, Motion logs a warning. It does not change the held-item state.

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 calculates forward camera clearance from the desired point and capsule. It blends this clearance by final view pitch. Camera placement does not use item state or animation pose. The Stable camera / Motion 1.6 camera samples the full-body MotionCamera socket. It aligns this reference with the Stable anchor before clearance. It adds the shared pitch-vector curve and moves FirstPersonUpperBody with the attached item.

Socket mode uses the requested socket as the raw camera origin. The Stable camera / Motion 1.6 camera is inactive. In the two modes, FirstPersonUpperBody compensates for world obstruction. FirstPersonLowerBody stays at its authored ground transform.

Upper-body held pose overlay

The default held pose uses one upper-body overlay node in the host MotionAnimInstance Animation Blueprint. Route the locomotion pose into Motion First Person Item Upper Body Overlay. Then, route the output to the final pose or project action layers. The node gets the active item config through UMotionAnimInstance.

It selects the automatic held pose from active gameplay tags. It crossfades pose changes during AutomaticHeldPoseSettings.BlendTime. Finally, it blends the pose with the configured branch and applies the Motion 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.
• Motion evaluates single-tag HeldPoseAnimations entries after rules. Each entry matches one active tag.
• If no entry matches, Motion uses AutomaticHeldPoseSettings.FallbackHeldPoseAnimation.
• Projects can use Motion tags or project tags such as ADS, injured, swimming, or stance tags.

Use rules when one state must block another state. For example, a pistol can use crouch and walk tags for crouch-walk. It can use crouch as necessary and walk as blocked for crouch-idle.

When the selected held pose changes, Motion evaluates the outgoing and incoming animations together. It crossfades between them. First equip is an item boundary. Thus, the first valid held pose appears immediately. Unequip or invalid output fades the last valid held pose to the host pose. It uses the last valid BlendTime.

If no item config is active, the node passes through the host pose without a warning. It also passes through an automatic config with no effective fallback animation. Use a validation function to get setup errors. The graph-safe resolver does not emit these errors automatically. A pure custom graph config does not use automatic held pose resolution.

Use CustomGraph only when an item owns all overlay behavior. Custom mode validates the graph reference. Automatic held pose asset and timing accessors return null or zero. The overlay node then calls the custom layer graph. In custom mode, InPose is the host pose before the automatic Motion overlay.

The custom graph controls pose logic, transitions, blend rules, bones, pitch solve, hand IK, and actions. Keep the Motion overlay node in the host graph because it calls the custom graph. Do not add this node to the custom graph. Nested instances pass through their input to prevent recursion.

For a custom held-pose branch, use InPose as the Layered Blend per Bone base pose. Use the held-pose Sequence Player as the blend pose. Enable mesh-space rotation blend. Use the automatic overlay branch settings unless the item affects different bones.

A direct Sequence Player output replaces the host pose. It does not inherit camera-pitch behavior. See How to add a first-person item end to end for examples.

The pitch solve uses the first-person visual pitch convention of Motion. Do not copy basic overlay data into separate host Animation Blueprint variables. The Motion accessors store data for graph use. They remain useful for debug UI and advanced custom graph logic. The built-in overlay node controls automatic pass-through and fail-closed behavior.

Held-item presentation actions

Presentation actions are the no-C++ Motion bridge for finite visual actions. Use them for attack, fire, reload, inspect, melee, and similar item presentation. The action plays in the built-in held pose overlay node.

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 call RequestHeldItemPresentationAction(ActionTag) on the active MotionHeldItemComponent. The immediate result describes the request outcome. Later lifecycle events arrive through OnPresentationActionLifecycle.

Motion controls only the local visual action flow. This flow includes playback, completion, cancellation, interruption, and final-frame sampling. Your project controls gameplay and replication.

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 values to the active item. It saves the values to the config and refreshes the 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.

When you change preview transform and render fields, the Details panel applies them without a save. Linked-layer preview changes apply after you save and refresh the presentation. Use ApplyPreviewToPresentation to save the preview to the config.

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 must have these mesh components:

• Mesh: 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 get the full-body pose through leader-pose setup. They must use the same skeleton as the full-body mesh. The native Stable camera / Motion 1.6 camera must have MotionCamera on that skeleton as its evaluated reference. Socket mode must have the valid pivot in CameraPivotSocketName.

Attachment contract

Motion attaches held items to weapon_r.

• The first-person item attaches to FirstPersonUpperBody.
• The world item attaches to Mesh.

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 instead of FirstPersonUpperBody. Thus, the attached item keeps its authored hand relationship. FirstPersonLowerBody stays at its authored ground transform. Item configuration and the world and full-body representations stay 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

The basic first-person held pose path uses a host overlay graph. The item config and MotionAnimInstance resolver APIs control this graph. Configured finite presentation actions can play in the same overlay. Add project animation after the basic held pose. Use layers, slots, montages, or item systems for gameplay scheduling, networking, branches, or custom behavior.

The supplied layer interface provides linked layers for broader pose sets. It includes locomotion functions, FullBody_Aiming, FullBody_SkeletalControls, and LeftHandPose_OverrideState. The Motion overlay node calls custom overlay graphs separately.

In automatic mode, the active config can select a linked layer through LinkedLayerClass. ABP_ItemAnimLayersBase and the sample item variables are not necessary for automatic held pose. CustomOverlaySettings.OverlayLayerClass belongs to custom graph mode. It is separate from the standard LinkedLayerClass pose-set change. If no item config is active, Motion uses unarmed or pass-through behavior without an overlay warning.

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.