UMotionHeldItemComponent

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

Build with Motion 2.0

Review the Unreal Engine 5 first-person controller overview, or get Motion 2.0 on Fab.

Requirements

• The character owner must have a standard full-body mesh from Mesh.
• The character must have MotionCameraComponent for native first-person render tuning or Stable body clearance.
• The character can have an optional FirstPersonUpperBody skeletal mesh for local-view item visuals.
• The character can have an optional FirstPersonLowerBody skeletal mesh for native visible-body presentation.
• The full-body and first-person upper-body meshes must have the weapon_r socket.
• Motion must find an Ability System Component (ASC) if Motion.State.HoldingItem is necessary.
• You must configure Enhanced Input only for 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:

• It applies Motion.State.HoldingItem through the ASC helper.
• It links LinkedLayerClass from the config. When no item is active, it links the unarmed layer.
• It creates and reuses native first-person and world item components. It can also spawn actor presentations.
• It attaches first-person items to FirstPersonUpperBody.weapon_r for the owner.
• It attaches world items to Mesh.weapon_r for all views.
• It applies supported native first-person render tuning through MotionCameraComponent.
• It creates or updates the PIE tuning bridge on locally controlled characters.
• It cancels active presentation actions when an item config is applied. It also cancels them when a refresh changes the usable config.

The component creates static and skeletal item components one time. It reuses them when the active config changes. The component spawns actor presentations for the active config. It destroys them when presentation clears or changes. Dedicated servers do not create native item components or actors 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 sends an RPC 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 uses the config that passed runtime validation. If validation fails, the replicated pointer can be present while the usable config is null.

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 view. Returns null when no primitive exists or when 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 must use 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. Returns true when 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 PresentationActions array of the active config. CustomGraph items return Unsupported. Automatic items can use the configured Motion 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

The component stores these fields during play. Use public query functions when possible.

• ActiveItemConfig: Stores the replicated server native item config pointer.
• AppliedItemConfig: Stores the validated usable config that local presentation uses.
• ActiveFirstPersonItemComponent: Stores the active primitive component for the local player view.
• ActiveWorldItemComponent: Stores the active world-view primitive component.
• AppliedLinkedLayerClass: Stores the linked layer that the full-body mesh uses.
• ActivePresentationActionState: Stores the active finite presentation action snapshot.
• ItemPresentationGeneration: Increases when ApplyItemConfig runs. It also increases when validation changes the usable config during RefreshHeldItemPresentation. Thus, animation can identify stale action state.
• bHoldingItemGameplayTagApplied: Shows 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 agree on the config, the component reapplies the config. It does not wait for a replicated property change that can fail to occur.

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 must decide whether a gameplay action is permitted. Then, call RequestHeldItemPresentationAction when Motion must 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 component destroys the tuning bridge. 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. Make sure that the active config has one valid static mesh, skeletal mesh, or actor presentation pair.
2. Make sure that the owner character has FirstPersonUpperBody for the local player view.
3. Make sure that weapon_r exists on the first-person upper-body and full-body meshes.
4. Read GetActiveUsableItemConfig and make sure that it is not null.
5. Read Motion logs for validation, unavailable mesh, or unavailable input-action warnings.