UMotionHeldItemComponent

UMotionHeldItemComponent owns Motion's native held-item presentation at runtime. It replicates the active item config, applies the usable config locally, manages first-person and world item components, updates the holding-item GameplayTag, links optional animation layers, and exposes finite presentation actions.

Requirements

• Character owner with a standard full-body mesh from GetMesh()
• MotionCameraComponent when native first-person render tuning or Stable body clearance is used
• Optional FirstPersonUpperBody skeletal mesh for item visuals in the local player's view
• Optional FirstPersonLowerBody skeletal mesh for native visible-body presentation
• weapon_r socket on the full-body mesh and first-person upper-body mesh
• Resolvable Ability System Component (ASC) when the Motion.State.HoldingItem tag should be applied
• Enhanced Input only when using the debug held-item toggle path

For production setup, see How to add a first-person item end to end. For config fields, see First-person item API reference.

Behavior

The component replicates ActiveItemConfig and applies a validated usable config into local presentation state. The owning client can predict a requested config immediately, then reconcile when the replicated server config arrives. Non-owning clients ignore local config-change requests.

When a usable native first-person item config is active, the component:

• applies Motion.State.HoldingItem through the ASC helper
• links the config's LinkedLayerClass, or the unarmed linked layer when no item is active
• creates and reuses native first-person and world static/skeletal item components, or spawns actor presentations
• attaches first-person items to FirstPersonUpperBody.weapon_r for the owner
• attaches world items to GetMesh().weapon_r for everyone
• applies supported native first-person render tuning through MotionCameraComponent
• creates or updates the PIE tuning bridge on locally controlled characters
• cancels active presentation actions whenever an item config is applied, or when a refresh changes the usable config

The component creates static and skeletal item components once and reuses them as the active config changes. Actor presentations are spawned for the active config and destroyed when presentation clears or changes. Dedicated servers skip native item component and actor creation because they are presentation-only.

Public API

Active item config

Function	Returns	Purpose
SetActiveItemConfig(UMotionNativeFirstPersonItemConfig* NewConfig)	void	Requests a new active native item config. Authority applies and replicates it; the owning client predicts and RPCs to the server.
GetActiveItemConfig()	UMotionNativeFirstPersonItemConfig*	Returns the predicted config while local prediction is active, otherwise the replicated server config.
GetActiveUsableItemConfig()	UMotionNativeFirstPersonItemConfig*	Returns the config currently validated and applied to presentation, or null.
RefreshHeldItemPresentation()	void	Revalidates the active config and reapplies tags, linked layers, item components, render tuning, and the tuning bridge.
ServerSetActiveItemConfig(UMotionNativeFirstPersonItemConfig* NewConfig)	void	Server RPC used by the owning client path.

Use GetActiveUsableItemConfig when animation or presentation code needs the config that passed runtime validation. The replicated pointer can be present while the usable config is null if validation failed.

Debug held-item path

Function	Returns	Purpose
ToggleDebugHeldItem()	void	Toggles between no active config and DefaultDebugItemConfig.
BindHeldItemInput()	bool	Binds the debug toggle input through component auto-discovery.

Active item components

Function	Returns	Purpose
GetActiveFirstPersonItemComponent()	UPrimitiveComponent*	Returns the resolved active item primitive for the local player's view, or null when none was created or resolved or this is not the owning view.
GetActiveWorldItemComponent()	UPrimitiveComponent*	Returns the resolved world-view active item primitive, or null when none was created or resolved.

These functions are useful for editor tooling, debug UI, and tuning workflows. Gameplay code should treat the config as the durable item presentation source.

Presentation actions

Function	Returns	Purpose
RequestHeldItemPresentationAction(FGameplayTag ActionTag)	EMotionNativeFirstPersonPresentationActionRequestResult	Starts a finite visual action from the active usable config when the action is valid and supported.
CancelHeldItemPresentationAction()	bool	Cancels the active presentation action, returning whether an action was active.
HasActiveHeldItemPresentationAction()	bool	Reports whether a presentation action snapshot is active.
GetHeldItemPresentationActionState()	FMotionHeldItemPresentationActionState	Returns the current component-owned action snapshot for animation.

Presentation actions use the active config's PresentationActions array. CustomGraph items return Unsupported; Automatic items can use Motion's configured action bridge.

Blueprint Events

Event	Payload	When it fires
OnPresentationActionLifecycle	FMotionHeldItemPresentationActionEvent	Action start, completion, cancellation, interruption, invalid request, or unsupported request.

Lifecycle events report the request result, action tag, playback time, source config, and action instance ID when an instance exists.

Configuration

Property	Type	Description
UnarmedLinkedLayerClass	TSubclassOf<UAnimInstance>	Linked layer restored when no item config is active. Motion loads the default unarmed layer if this is unset.
DefaultDebugItemConfig	UMotionNativeFirstPersonItemConfig*	Native config used by the debug toggle. Motion loads the sample pistol config if this is unset.
DebugToggleHeldItemAction	UInputAction*	Enhanced Input action used by the debug held-item toggle path. Motion loads the sample input action if this is unset.

For project equipment, call SetActiveItemConfig directly with the config selected by your inventory or item system.

Runtime State

These fields are state stored on the component during play. Use public query functions where possible.

• ActiveItemConfig: replicated server native item config pointer.
• AppliedItemConfig: validated usable config currently applied to local presentation.
• ActiveFirstPersonItemComponent: active primitive component for the local player's view.
• ActiveWorldItemComponent: active world-view primitive component.
• AppliedLinkedLayerClass: linked layer currently applied to the full-body mesh.
• ActivePresentationActionState: current finite presentation action snapshot.
• ItemPresentationGeneration: increments whenever ApplyItemConfig runs; RefreshHeldItemPresentation also increments it when validation changes the usable config, so animation can distinguish stale action state.
• bHoldingItemGameplayTagApplied: tracks whether the component applied Motion.State.HoldingItem.

Networking

Authority owns ActiveItemConfig. The owning client can call SetActiveItemConfig, immediately applies the requested config as prediction, and sends ServerSetActiveItemConfig. When replication confirms the same config, local prediction clears.

Same-config refresh is a local presentation refresh, not normal prediction. If the client and authority already agree on the config, the component reapplies the config without waiting for a replicated property change that may not happen.

Non-owning clients cannot request item config changes. They receive the replicated config and update their world item view from that value.

Native Presentation Boundaries

UMotionHeldItemComponent owns presentation plumbing, not gameplay item rules. It does not own:

• inventory state
• equip legality
• ammo or cooldowns
• damage or hit confirmation
• gameplay replication for firing, reload, melee, or inspect logic

Project systems should decide whether a gameplay action is allowed, then call RequestHeldItemPresentationAction when Motion should play a local visual action.

PIE Tuning Bridge

In PIE on a locally controlled character, the component creates or updates a MotionNativeFirstPersonItemTuning component when a usable native config is active. The bridge points at the active config and the source held-item component.

When the config clears, the tuning bridge component is destroyed. See First-person item API reference for the tuning functions.

Debugging

Useful commands:

log LogMotionCharacter Verbose
log LogMotionReplication Verbose
log LogMotionInput Verbose
log LogMotionAbilitySystem Verbose
showdebug abilitysystem

If a held item does not appear:

1. Confirm the active config has exactly one complete static mesh, skeletal mesh, or actor presentation pair.
2. Confirm the owner character has FirstPersonUpperBody for the local player's view.
3. Confirm weapon_r exists on the first-person upper-body and full-body meshes.
4. Check whether GetActiveUsableItemConfig is null.
5. Check Motion logs for validation, missing mesh, or missing input-action warnings.