First-person item API reference

This page lists the native first-person held-item API surfaces used by Motion's item presentation path. For the concept overview, see First-person item configs. For the runtime component, see MotionHeldItemComponent.

Runtime ownership

Surface	Role
UMotionHeldItemComponent	Runtime owner for the active native item config, validated usable config, item components or actors, linked layers, holding tag, tuning bridge, and presentation actions.
UMotionNativeFirstPersonItemConfig	UPrimaryDataAsset that describes item presentations, overlay mode, automatic held pose data, optional custom graph, presentation actions, solve tuning, transforms, linked layer, and render tuning.
UMotionAnimInstance	Animation-state bridge that exposes the active usable config, tag snapshot, overlay mode, automatic held pose state, custom graph reference, solve settings, pitch, and presentation action snapshot.
Motion First Person Item Upper Body Overlay	Native AnimGraph node that wraps the host pose and applies either Motion's automatic held pose, optional presentation action, pitch solve, and hand IK, or a configured custom graph.

The component owns runtime state. The config owns authored defaults. The animation instance exposes state cached for AnimGraph use. The AnimGraph node consumes those cached values during animation update/evaluation.

UMotionNativeFirstPersonItemConfig

UMotionNativeFirstPersonItemConfig is a UPrimaryDataAsset consumed by UMotionHeldItemComponent.

Presentation fields

Field	Type	Description
FirstPersonStaticMesh	UStaticMesh*	Owner-view static mesh. Use with WorldStaticMesh.
WorldStaticMesh	UStaticMesh*	World-view static mesh. Use with FirstPersonStaticMesh.
FirstPersonSkeletalMesh	USkeletalMesh*	Owner-view skeletal mesh. Use with WorldSkeletalMesh.
WorldSkeletalMesh	USkeletalMesh*	World-view skeletal mesh. Use with FirstPersonSkeletalMesh.
FirstPersonActorClass	TSubclassOf<AActor>	Owner-view actor presentation. Use with WorldActorClass.
WorldActorClass	TSubclassOf<AActor>	World-view actor presentation. Use with FirstPersonActorClass.

Use one complete pair. Partial pairs and mixed static mesh, skeletal mesh, or actor presentation types fail validation.

Overlay and animation fields

Field	Type	Description
LinkedLayerClass	TSubclassOf<UAnimInstance>	Optional broader pose-set linked layer. Not required for automatic held pose.
OverlayMode	EMotionNativeFirstPersonItemOverlayMode	Selects Automatic or CustomGraph.
AutomaticHeldPoseSettings	FMotionNativeFirstPersonItemAutomaticHeldPoseSettings	Fallback held pose, conditional held pose rules, single-tag entries, overlay weight, and blend time.
CustomOverlaySettings	FMotionNativeFirstPersonItemCustomOverlaySettings	Animation Blueprint class and layer graph name for custom overlay modes.
PresentationActions	TArray<FMotionNativeFirstPersonPresentationActionEntry>	Finite visual actions keyed by gameplay tag.
UpperBodySolveSettings	FMotionNativeFirstPersonItemUpperBodySolveSettings	Branch, pitch solve, and hand-IK tuning for automatic output.

AutomaticHeldPoseSettings applies in Automatic. CustomOverlaySettings applies in CustomGraph.

Transform and render fields

Field	Type	Description
FirstPersonRelativeTransform	FTransform	Local transform applied to the item presentation for the local player's view.
WorldRelativeTransform	FTransform	Local transform applied to the world-view item presentation.
RenderTuning	FMotionNativeFirstPersonItemRenderTuning	Optional native first-person FOV and scale overrides.

Use transforms for item-specific grip and screen placement. Shared camera height, runtime camera offsets, Stable body clearance, and Stable presentation anchoring belong to MotionCameraComponent and its camera profile. Item configs do not provide baseline presentation curves or correction bounds, and equipping an item is not an input to Stable camera placement/correction. FirstPersonLowerBody remains at its authored grounded transform.

Config functions

Function	Returns	Purpose
ValidateNativeFirstPersonConfig()	FMotionNativeFirstPersonItemValidationResult	Validates the presentation pair for runtime item presentation.
ValidateNativeFirstPersonItemOverlay(OutMessages)	bool	Validates automatic/custom overlay setup and solve tuning.
ValidateNativeFirstPersonPresentationActions(OutMessages)	bool	Validates presentation action entries.
ResolvePresentationActionEntry(ActionTag, OutEntry)	bool	Resolves a valid action entry without diagnostics.
ResolvePresentationActionEntryWithDiagnostics(ActionTag, OutEntry, OutMessages)	bool	Resolves an action entry and returns validation messages.
ResolveAutomaticHeldPoseAnimation(ActiveGameplayTags)	UAnimSequence*	Selects the automatic held pose animation from active tags and fallback data.
ResolveAutomaticHeldPoseAnimationWithDiagnostics(ActiveGameplayTags, OutMessages)	UAnimSequence*	Selects the automatic held pose and returns overlay diagnostics.
GetEffectiveUpperBodySolveSettings()	FMotionNativeFirstPersonItemUpperBodySolveSettings	Returns the authored settings when valid, or Motion's default settings when validation fails.
GetAutomaticOverlayBlendTime()	float	Returns automatic overlay blend and crossfade time.
GetCustomOverlayLayerClass()	TSubclassOf<UAnimInstance>	Returns custom overlay Animation Blueprint class when configured.
GetCustomOverlayLayerGraphName()	FName	Returns the named Animation Layer graph used by custom overlay modes.
GetMeshType()	EMotionNativeFirstPersonItemMeshType	Returns the configured presentation family: StaticMesh, SkeletalMesh, Actor, or None. Use ValidateNativeFirstPersonConfig() to verify pair completeness.

Overlay modes

Enum value	Meaning
Automatic	Motion resolves the tag-driven held pose, blends it over the host pose, applies presentation actions, pitch solve, and hand IK.
CustomGraph	The custom layer graph receives the host pose as InPose and owns the full overlay result. Motion automatic held pose and Motion presentation actions are not used.

Use Automatic for normal held items. Use CustomGraph only when the item intentionally replaces Motion's automatic overlay.

Automatic held pose structs

Type	Fields	Purpose
FMotionNativeFirstPersonItemHeldPoseAnimationRule	RequiredTags, BlockedTags, HeldPoseAnimation, Priority	Selects a held pose animation from combined state conditions.
FMotionNativeFirstPersonItemHeldPoseAnimationEntry	GameplayTag, HeldPoseAnimation	Single-tag held pose entry. Use rules for combined states.
FMotionNativeFirstPersonItemAutomaticHeldPoseSettings	FallbackHeldPoseAnimation, HeldPoseAnimationRules, HeldPoseAnimations, OverlayBlendWeight, BlendTime	Configures automatic held pose selection, overlay weight, and blend timing.

Motion evaluates HeldPoseAnimationRules first. A rule matches when all RequiredTags are active and no BlockedTags are active. Highest Priority wins, then highest specificity (RequiredTags + BlockedTags), then array order. If no rule matches, Motion checks single-tag HeldPoseAnimations in array order, then uses FallbackHeldPoseAnimation. If pure CustomGraph mode is active, automatic held pose resolution returns null.

Presentation action types

Authoring structs

Type	Fields	Purpose
FMotionNativeFirstPersonPresentationActionEntry	ActionTag, ActionAnimation, blend times, play rate	Defines one finite visual action available on the active config.

Request and event enums

Enum	Values
EMotionNativeFirstPersonPresentationActionRequestResult	Started, StartedAndInterruptedPrevious, Invalid, Unsupported
EMotionNativeFirstPersonPresentationActionLifecycleEvent	None, Started, Completed, Canceled, Interrupted, Invalid, Unsupported

Invalid means the request or configured entry failed validation. Unsupported applies when a CustomGraph item receives a Motion presentation action request.

Runtime event and state structs

Type	Key fields	Purpose
FMotionHeldItemPresentationActionEvent	InstanceId, LifecycleEvent, RequestResult, ActionTag, PlaybackTime, SourceItemConfig	Payload for action-flow delegates.
FMotionHeldItemPresentationActionState	active flags, generation, action tag, source config, sequence, playback timing, lifecycle event	Snapshot copied by MotionAnimInstance for the overlay node.

The state is visual presentation state. It does not decide inventory, ammo, cooldown, damage, or gameplay authority.

Validation enums and messages

Type	Values or fields
EMotionNativeFirstPersonValidationState	Valid, NoMeshPair, IncompleteMeshPair, MixedMeshTypes
EMotionNativeFirstPersonOverlayValidationSeverity	Error, Warning
FMotionNativeFirstPersonItemValidationResult	State, Message, IsValid()
FMotionNativeFirstPersonOverlayValidationMessage	Severity, Code, GameplayTag, BoneName, Message

EMotionNativeFirstPersonOverlayValidationCode covers invalid blend values, invalid or duplicate automatic held pose rules, missing or duplicate single-tag held pose entries, missing animations, missing or invalid custom overlay graph setup, invalid configured bone names, invalid presentation actions, duplicate presentation action tags, and unsupported presentation action overlay mode.

Upper-body solve structs

Type	Fields	Purpose
FMotionNativeFirstPersonBoneWeight	BoneName, Weight	Pitch distribution entry for a bone.
FMotionNativeFirstPersonHandIKBonePair	IKBoneName, FKBoneName	Pair used by Motion's hand IK solve.
FMotionNativeFirstPersonItemUpperBodySolveSettings	branch root/depth, pitch enable/alpha/weights, hand-IK enable/alpha/bones	Configures automatic branch blend, camera pitch distribution, and hand IK.

FMotionNativeFirstPersonItemUpperBodySolveSettings starts with default pitch bone weights. GetEffectivePitchBoneWeights() restores those defaults when BoneWeights is intentionally left empty, and GetEffectiveHandIKBones() returns Motion defaults when hand-IK bones are left empty.

Render tuning helpers

FMotionNativeFirstPersonItemRenderTuning can request native first-person FOV and scale overrides.

Field	Meaning
bOverrideFirstPersonFieldOfView	Enables config-specific first-person FOV override.
FirstPersonFieldOfView	Requested first-person FOV.
bOverrideFirstPersonScale	Enables config-specific first-person scale override.
FirstPersonScale	Requested first-person render scale.

FMotionFinalCameraViewState and FMotionFirstPersonPresentationState expose read-only camera and upper-body presentation diagnostics, including Stable desired/evaluated anchors, curve contribution, correction, and clamp state. Their behavior is documented on MotionCameraComponent. The active first-person item inherits Stable correction through its FirstPersonUpperBody attachment; it is not a correction input, and FirstPersonLowerBody remains at its authored grounded transform.

Native first-person names

FMotionNativeFirstPersonNames defines the fixed component/socket names used by the native first-person item path:

Name	Purpose
FirstPersonUpperBodyComponent	Expected upper-body skeletal mesh component name for the local player's view.
FirstPersonLowerBodyComponent	Expected lower-body skeletal mesh component name for the local player's view.
CameraPresentationSocket	Standard MotionCamera name. Stable mode samples it only as the evaluated body-presentation reference; Socket mode may use it as the camera pivot.
HeldItemSocket	Item attachment socket, currently weapon_r.
FirstPersonStaticItemComponent	Generated static item component name for the local player's view.
WorldStaticItemComponent	Generated world-view static item component name.
FirstPersonSkeletalItemComponent	Generated skeletal item component name for the local player's view.
WorldSkeletalItemComponent	Generated world-view skeletal item component name.

Native first-person item tuning component

UMotionNativeFirstPersonItemTuningComponent is a PIE/editor bridge created by UMotionHeldItemComponent for locally controlled characters with an active usable native config.

Editable preview fields:

Field	Purpose
PreviewLinkedLayerClass	Linked layer class that will be written to LinkedLayerClass when saved.
PreviewFirstPersonRelativeTransform	Owner-view item transform preview and saved FirstPersonRelativeTransform value.
PreviewWorldRelativeTransform	World-view item transform preview and saved WorldRelativeTransform value.
PreviewRenderTuning	Native first-person render tuning preview and saved RenderTuning value.

Function	Purpose
InitializeTuning(InItemConfig, InHeldItemComponent)	Points the tuning component at the active item config and source held-item component. Pulls config values when the config changes.
ResetToConfig()	Pulls all preview values from the config and applies the transform and render-tuning values to the live presentation.
PullCurrentPresentationToPreview()	Copies the current first-person and world item component relative transforms into preview fields, then copies linked layer and render tuning from the config.
ApplyPreviewToPresentation()	Applies preview transforms and render tuning to the live active item, then calls SaveToConfig() so the preview linked layer, transforms, and render tuning are written to the config and the held-item presentation refreshes.
SaveToConfig()	Writes preview linked layer, transforms, and render tuning to the config asset, saves the package in editor builds, and refreshes held-item presentation.

Editing preview transform and render tuning properties in the Details panel applies them live through the internal apply path. Details-panel edits do not call SaveToConfig; linked-layer changes take effect after saving and refreshing the held-item presentation.

Native AnimGraph node

The runtime node is FAnimNode_MotionFirstPersonItemUpperBodyOverlay. The editor node class is UAnimGraphNode_MotionFirstPersonItemUpperBodyOverlay, displayed as Motion First Person Item Upper Body Overlay.

Editable pins and settings

Field	Meaning
BasePose	Host pose input. Route locomotion/body pose into this link.
bLoopHeldPoseAnimation	Whether the automatic held pose sequence loops.
HeldPoseAnimationPlayRate	Playback rate for automatic held pose sequence sampling.

Other overlay inputs are transient. The node reads them from the owning UMotionAnimInstance during update.

Runtime behavior

The node:

• passes through the host pose when no active item config is available
• reads active overlay mode, automatic held pose sequence, blend timing, solve settings, pitch, custom overlay class/name, and presentation action state from MotionAnimInstance
• in Automatic mode, crossfades held pose changes for the same item config
• in Automatic mode, blends the held pose over the configured branch
• in Automatic mode, applies presentation actions
• in Automatic mode, applies Motion's pitch solve and hand IK after the final Motion-owned presentation blend
• invokes a custom overlay layer graph for CustomGraph mode

Do not build a manual basic overlay with Sequence Player, generic Is Valid, and Blend Poses by bool. The native node owns that basic contract and keeps AnimGraph reads on cached MotionAnimInstance state.

MotionAnimInstance mapping

UMotionAnimInstance reads UMotionHeldItemComponent during NativeUpdateAnimation. See MotionAnimInstance held-item state mapping for the canonical state-source table, including the Ability System Component tag snapshot, automatic held pose state, custom overlay data, solve settings, pitch convention, and presentation action snapshot.