First-person item API reference

This page lists the native first-person held-item APIs for Motion item presentation. 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 active item and overlay state to the AnimGraph.
Motion First Person Item Upper Body Overlay	Native AnimGraph node that applies the automatic Motion overlay or a configured custom graph to the host pose.

The component owns runtime state. The config owns authored defaults. The animation instance exposes stored state to the AnimGraph. The AnimGraph node uses these values during animation update and 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 pair. Partial pairs fail validation. Mixed static mesh, skeletal mesh, and actor presentation types also fail validation.

Overlay and animation fields

Field	Type	Description
LinkedLayerClass	TSubclassOf<UAnimInstance>	Optional broader pose-set linked layer. It is not necessary for an 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 for the item presentation in the local player 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. MotionCameraComponent and its camera profile control shared behavior for the Stable camera / Motion 1.6 camera. Item configs do not provide baseline presentation curves or correction limits. An equipped item is not an input to Stable camera placement or correction. FirstPersonLowerBody stays at its authored ground 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 valid authored settings. Returns the Motion defaults 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 and blends it with the host pose. It 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 standard held items. Use CustomGraph only when the item replaces the automatic Motion 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. The rule with the highest Priority wins. Motion then uses the highest specificity (RequiredTags + BlockedTags) and array order as secondary criteria.

If no rule matches, Motion evaluates single-tag HeldPoseAnimations in array order. It then uses FallbackHeldPoseAnimation. In pure CustomGraph mode, 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 includes codes for invalid blend values, held poses, custom graphs, bone names, presentation actions, and overlay modes.

Upper-body solve structs

Type	Fields	Purpose
FMotionNativeFirstPersonBoneWeight	BoneName, Weight	Pitch distribution entry for a bone.
FMotionNativeFirstPersonHandIKBonePair	IKBoneName, FKBoneName	Pair for the Motion 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 these defaults when BoneWeights is empty. GetEffectiveHandIKBones() returns the Motion defaults when hand-IK bones are 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. The diagnostics include Stable anchors, curve contribution, correction, and clamp state. See MotionCameraComponent for their behavior. The active first-person item receives Stable correction through its FirstPersonUpperBody attachment. It is not a correction input. FirstPersonLowerBody stays at its authored ground 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 view.
FirstPersonLowerBodyComponent	Expected lower-body skeletal mesh component name for the local player view.
CameraPresentationSocket	Standard MotionCamera name. Stable mode uses it as the evaluated body-presentation reference. Socket mode can use it as the camera pivot.
HeldItemSocket	Item attachment socket, currently weapon_r.
FirstPersonStaticItemComponent	Generated static item component name for the local player view.
WorldStaticItemComponent	Generated world-view static item component name.
FirstPersonSkeletalItemComponent	Generated skeletal item component name for the local player 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)	Sets the active item config and source held-item component. Gets config values when the config changes.
ResetToConfig()	Gets all preview values from the config. Applies the transform and render settings to the live presentation.
PullCurrentPresentationToPreview()	Copies the current item component transforms into preview fields. Then, it copies linked layer and render settings from the config.
ApplyPreviewToPresentation()	Applies preview transforms and render settings to the active item. Then, it calls SaveToConfig() and refreshes the presentation.
SaveToConfig()	Writes preview values to the config asset. Saves the package in editor builds and refreshes the held-item presentation.

When you edit preview transform and render properties, the Details panel applies them to the live presentation. Details-panel edits do not call SaveToConfig(). Linked-layer changes take effect after you save and refresh 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 with the configured branch
• in Automatic mode, applies presentation actions
• in Automatic mode, applies the Motion pitch solve and hand IK after the final Motion 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. It includes tag, pose, overlay, solve, pitch, and action state.