First-Person Item Configs

Motion uses a data-driven first-person item presentation system for local first-person items.

Each item is described by a UMotionFirstPersonItemConfig asset. That asset tells Motion which actor to spawn for local first-person presentation, which linked animation layer to use, which socket to attach to, and which relative transform to apply.

The built-in pistol uses this system through DA_FPItem_Pistol.

What a first-person item config is

A first-person item config is a UPrimaryDataAsset that defines the content-side setup for one local first-person item presentation.

The asset is responsible for:

• choosing the presentation actor
• choosing the linked animation layer
• choosing the attach socket
• storing the local relative transform used for framing

This gives each item a compact content surface without moving Motion's shared first-person body logic into per-item assets.

What the system owns

Each first-person item config currently drives:

• PresentationActorClass
• LinkedLayerClass
• PresentationAttachSocket
• PresentationRelativeTransform

This scope is intentionally narrow. The config only exposes fields that are currently consumed by runtime code.

Runtime flow

At runtime, UMotionHeldItemComponent treats the active item config as the local first-person item definition for the held item path.

The flow is:

1. Gameplay sets an active UMotionFirstPersonItemConfig.
2. UMotionHeldItemComponent links the configured item Anim Layer class.
3. UMotionHeldItemComponent spawns the configured presentation actor.
4. The actor attaches to the configured socket on the presentation mesh.
5. The configured relative transform is applied.
6. UMotionAnimInstance exposes the active config to animation code.

This keeps shared Motion behavior in Motion-owned code and shared linked layers, while letting content choose the item-specific presentation setup.

Animation layer responsibilities

Motion uses two item-related linked layers for the current first-person path:

• FullBody_FirstPersonItemItemSpace
• FullBody_FirstPersonItemUpperBody

Recommended split:

• FullBody_FirstPersonItemItemSpace
  • item-specific extension point for helper-space or item-space adjustments
  • base implementation can remain pass-through
• FullBody_FirstPersonItemUpperBody
  • shared Motion-owned upper-body pitch/solve behavior

The main AnimGraph path in ABP_Mannequin_Base is set up so ItemItemSpace runs before UpperBody.

Built-in pistol asset

Motion ships with a default first-person pistol config:

• DA_FPItem_Pistol

That asset currently points to:

• PresentationActorClass = BP_Pistol
• LinkedLayerClass = ABP_PistolAnimLayers
• PresentationAttachSocket = weapon_r
• PresentationRelativeTransform = baseline pistol transform

B_MotionCharacter uses this through the MotionHeldItem component's DefaultDebugItemConfig.

Creating a new item

To add a new local first-person item:

1. Create a new MotionFirstPersonItemConfig asset.
2. Set PresentationActorClass to the item actor you want to spawn for local first-person presentation.
3. Set LinkedLayerClass to the item AnimBP that should be linked while the item is active.
4. Set PresentationAttachSocket to the socket on the character presentation mesh.
5. Set an initial PresentationRelativeTransform for on-screen framing.
6. Set that asset as the active item config through gameplay code, Blueprint, or your item/equipment system.

For items that need custom helper-space behavior, override FullBody_FirstPersonItemItemSpace in the item's linked layer.

PIE tuning workflow

Motion also includes a PIE tuning bridge so you can adjust the spawned local first-person item visually and save the result back into the config asset.

What gets a tuning component

When all of these are true:

• the item config is active
• the item has a presentation actor
• the owner is locally controlled
• the world is PIE

Motion adds MotionFirstPersonItemTuning to the spawned presentation actor.

How to tune

1. Start PIE.
2. Activate the item so its presentation actor is spawned.
3. Select the spawned item actor in the Outliner.
4. Move or rotate the actor root until the item looks correct.
5. In the MotionFirstPersonItemTuning component, click SaveCurrentTransformToConfig.

That writes the actor root relative transform back into the source item config asset and marks the asset dirty.

Resetting

If you want to discard live tweaks and go back to the asset values:

1. Select the spawned presentation actor.
2. In MotionFirstPersonItemTuning, click ResetToConfig.

This reapplies the config transform and refreshes the held-item presentation.

Important detail: edit the actor root

The saveback path captures the spawned actor root component's relative transform.

That means the intended workflow is:

• edit the spawned presentation actor root transform
• do not tune a child mesh component instead

If you only move a child component, the saved config will not match what you see.

Current scope

This system is currently scoped to local first-person presentation only.

It does not currently try to own:

• remote third-person item presentation
• inventory semantics
• gameplay equip state
• muzzle logic
• hand target metadata
• generic item role resolution

Those can be layered on later, but they are not part of the current runtime contract.

Current limitations

• The config currently drives presentation class, linked layer, socket, and transform only.
• The system assumes an explicit save step. It does not auto-save live tweaks.
• PIE verification depends on the editor actually being in a clean PIE session.
• New reflected editor buttons and properties may require an editor restart if they were added through Live Coding during development.

Practical recommendation

Use this system as the content-facing seam for item presentation, not as a full weapon framework.

Keep:

• item-specific attach and local framing in the config asset
• item-specific item-space graph logic in FullBody_FirstPersonItemItemSpace
• shared body/aim behavior in FullBody_FirstPersonItemUpperBody

That keeps per-item setup lightweight without duplicating Motion's shared first-person solve logic.