MotionAnimInstance

MotionAnimInstance is an Animation Instance base class that connects Motion movement state to Animation Blueprints. It provides GAS tag-to-property mapping, frame-cached ground detection, ASC binding, native first-person item config exposure, active gameplay tag snapshots, and automatic held pose animation resolution for upper-body item held pose overlays.

Requirements

• Animation Blueprint parent class set to UMotionAnimInstance
• Character owner for the Animation Blueprint
• Resolvable ASC for tag-to-property mapping, commonly exposed by a PlayerState that implements IAbilitySystemInterface
• Gameplay Ability System initialized when tag mapping is used

For setup steps, see How to set up MotionAnimInstance.

Preview

Motion's native first-person item config workflow is currently in Preview.

UMotionAnimInstance exposes the active first-person item config to animation code so automatic held pose overlay graphs, custom graph layers, and optional linked layers can react to the currently active content setup. If MotionHeldItemComponent is not present, CurrentFirstPersonItemConfig remains null.

Behavior

During initialization, the animation instance caches the owning character, CharacterMovementComponent, capsule component, and ASC when available. If PlayerState or ASC initialization is not ready yet, it retries binding during update or waits for the ASC availability delegate.

During animation updates, the instance can:

• process GameplayTagPropertyMap
• set mapped Blueprint variables from ASC tags
• update ground information once per frame
• expose GroundDistance
• expose CurrentFirstPersonItemConfig when the held-item path is active
• cache active ASC gameplay tags for first-person item overlay decisions
• resolve the active automatic held pose animation from the item config and active gameplay tags
• expose the active item overlay mode
• expose automatic overlay blend weight, overlay blend time, and held pose transition blend time from the active item config
• expose effective upper-body solve settings and control-rotation pitch for the automatic held pose overlay

API

Lifecycle

• NativeInitializeAnimation() -> void: initializes cached references and starts ASC binding.
• NativeUninitializeAnimation() -> void: cleans up animation state.
• NativeUpdateAnimation(float DeltaSeconds) -> void: processes tag mapping, binding retries, and ground data.
• InitializeWithAbilitySystem(UAbilitySystemComponent* ASC) -> void: initializes the animation instance with an ASC.

Ground detection

• GetGroundInfo() -> FMotionGroundInfo: returns cached ground trace information for the current frame.

ASC integration

• OnAbilitySystemAvailable(UAbilitySystemComponent* ASC) -> void: callback used when ASC becomes available after initial animation setup.

Native first-person item overlay

• GetCurrentHeldItemType() -> EMotionHeldItemType: returns the current Motion held-item type, or None.
• GetCurrentFirstPersonItemConfig() -> UMotionNativeFirstPersonItemConfig*: returns the active native first-person item config, or null.
• ResolveNativeFirstPersonItemAutomaticHeldPoseAnimation() -> UAnimSequence*: thread-safe lookup for the cached automatic held pose animation from the active usable native config. The built-in overlay node reads this internally; use the getter for diagnostics or advanced inspection.
• HasNativeFirstPersonItemAutomaticHeldPoseAnimation() -> bool: thread-safe availability flag for the cached automatic held pose animation. The built-in overlay node handles pass-through internally.
• GetNativeFirstPersonItemOverlayMode() -> EMotionNativeFirstPersonItemOverlayMode: thread-safe graph-time lookup for the active item overlay mode.
• GetNativeFirstPersonItemAutomaticOverlayBlendWeight() -> float: thread-safe lookup for the active automatic overlay blend weight, or 0.0 when automatic output is unavailable.
• GetNativeFirstPersonItemAutomaticOverlayBlendTime() -> float: thread-safe lookup for the active automatic overlay enable/disable blend time, or 0.0 when automatic output is unavailable.
• GetNativeFirstPersonItemAutomaticHeldPoseTransitionBlendTime() -> float: thread-safe lookup for the active automatic held pose to held pose transition blend time, or 0.0 when automatic output is unavailable.
• GetNativeFirstPersonActiveGameplayTags() -> FGameplayTagContainer: thread-safe graph-time snapshot of active ASC gameplay tags used by item overlay resolution.
• ResolveNativeFirstPersonItemAutomaticHeldPoseAnimationWithDiagnostics(OutMessages) -> UAnimSequence*: setup/event-time lookup that emits overlay diagnostics through OutMessages and logs setup warnings once per config/message.
• GetNativeFirstPersonItemUpperBodySolveSettings() -> FMotionNativeFirstPersonItemUpperBodySolveSettings: returns graph-safe effective solve tuning from the active item config, or Motion defaults when no active config exists or numeric solve tuning is invalid.
• GetNativeFirstPersonControlRotationPitch() -> float: returns normalized owner control-rotation pitch converted to the overlay pitch-solve convention, or 0.0 when no controller is available.

Configuration

GameplayTagPropertyMap

Maps ASC-owned GameplayTags to Animation Blueprint properties. The common pattern is to map Motion state tags to Boolean properties such as bIsWalking, bIsSprinting, bIsCrouching, and bIsJumping.

Common mappings:

• Motion.State.Walking -> bIsWalking
• Motion.State.Sprinting -> bIsSprinting
• Motion.State.Crouching -> bIsCrouching
• Motion.State.Jumping -> bIsJumping
• Motion.State.HoldingItem -> bIsHoldingItem
• Motion.State.WantsToSprint -> bWantsToSprint
• Motion.State.WantsToCrouch -> bWantsToCrouch
• Motion.State.WantsToJump -> bWantsToJump
• Motion.State.MovementHalted -> bIsMovementHalted
• Motion.State.StaminaDepleted -> bIsStaminaDepleted
• Motion.State.StaminaRegenBlocked -> bIsStaminaRegenBlocked
• Motion.State.StaminaRegenerating -> bIsStaminaRegenerating

Animation State Properties

• GroundDistance: float; current distance to ground below the character, cached per frame.
• bIsAbilitySystemBound: bool; whether the instance successfully bound to an ASC.
• CurrentFirstPersonItemConfig: UMotionNativeFirstPersonItemConfig*; active local first-person item config, or null when no held-item component/config is active.

Automatic Held Pose Resolution

The automatic held pose resolver is for upper-body item held pose overlays. It does not require host Animation Blueprints to expose stance-specific item variables.

Resolution rules:

• MotionAnimInstance snapshots active ASC gameplay tags during update.
• The active config resolves matching AutomaticHeldPoseSettings.HeldPoseAnimations entries by priority.
• The matching entry with the highest priority value wins; equal priorities keep array order.
• If no entry matches, the config uses AutomaticHeldPoseSettings.FallbackHeldPoseAnimation.
• If OverlayMode is CustomGraph, automatic held pose resolution returns null.

If ASC binding is unavailable, the active tag snapshot is empty and the resolver uses the fallback animation. If no active native item config is available, automatic held pose resolution returns null without warning so the overlay can pass the input pose through.

Upper-Body Solve Access

MotionAnimInstance does not own item-specific animation tuning. It caches the active config's automatic held pose asset, overlay weight, overlay blend time, held pose transition blend time, and effective upper-body solve settings so the built-in Motion First Person Item Upper Body Overlay node can read stable state without adding per-item variables to the host Animation Blueprint.

When no item config is active, GetNativeFirstPersonItemUpperBodySolveSettings returns Motion defaults silently and automatic blend accessors return zero. Invalid automatic setup makes the overlay node pass the host pose through. The pure getters remain useful for debug UI, validation tools, or custom graph logic, but the minimum baseline setup should not wire them into exposed overlay-node pins.

GetNativeFirstPersonControlRotationPitch is Motion's first-person overlay pitch source. UE camera look-down pitch is negative, but the overlay solve expects look-down as positive; camera-derived pitch remains outside the current overlay contract.

Ground Information

FMotionGroundInfo contains:

• GroundHitResult: complete hit information from the ground trace.
• GroundDistance: distance to ground, or -1.0 if no ground is detected.
• LastUpdateTime: time in seconds when the value was last updated.

Ground information is cached per frame so multiple animation nodes can read it without repeating the trace.

Read-Only State

• CachedCharacter: owning character.
• CachedCharacterMovement: owning character movement component.
• CachedCapsuleComponent: owning capsule component.
• CachedAbilitySystemComponent: bound ASC.
• CachedGroundInfo: cached ground trace result.
• bShouldRetryASCBinding: whether binding should be retried on the next update.

ASC Binding

ASC binding uses several fallback paths:

1. Bind immediately when PlayerState and ASC are ready.
2. Register an availability delegate when PlayerState exists but ASC is not ready.
3. Retry during animation update when PlayerState is not ready.
4. Continue without tag mapping when ASC is unavailable.

bIsAbilitySystemBound tracks success. bShouldRetryASCBinding tracks pending retry work.

Blueprint Integration

After inheriting from MotionAnimInstance, Animation Blueprints can read:

• GroundDistance
• bIsAbilitySystemBound
• CurrentFirstPersonItemConfig
• GetCurrentFirstPersonItemConfig
• ResolveNativeFirstPersonItemAutomaticHeldPoseAnimation
• HasNativeFirstPersonItemAutomaticHeldPoseAnimation
• GetNativeFirstPersonItemOverlayMode
• GetNativeFirstPersonItemAutomaticOverlayBlendWeight
• GetNativeFirstPersonItemAutomaticOverlayBlendTime
• GetNativeFirstPersonItemAutomaticHeldPoseTransitionBlendTime
• GetNativeFirstPersonActiveGameplayTags
• ResolveNativeFirstPersonItemAutomaticHeldPoseAnimationWithDiagnostics
• GetNativeFirstPersonItemUpperBodySolveSettings
• GetNativeFirstPersonControlRotationPitch
• any properties mapped through GameplayTagPropertyMap

The mapped properties are updated directly from ASC tags each frame when the ASC is bound.

Reference Patterns

Typical state machine transition checks:

Can enter walk state:
- bIsWalking
- not bIsSprinting

Can enter sprint state:
- bIsSprinting
- GroundDistance <= 0

Can enter jump state:
- bIsJumping
- or GroundDistance > 100

Blend spaces usually combine mapped Motion state with velocity. Landing logic can use GroundDistance to prepare landing transitions.

Animation Notifiers can also check mapped state before triggering sounds or effects.

Debugging

Useful console commands:

log LogMotionAnimation Verbose
log LogMotionCore Verbose
log LogAbilitySystem Verbose
log LogGameplayTags Verbose
log LogAnimation Verbose
log LogAnimBlueprint Verbose
stat anim
stat game

Common Checks

If mapped properties do not update:

1. Verify tag names match exactly.
2. Ensure property names exist in the Animation Blueprint.
3. Confirm property types are correct.
4. Check that bIsAbilitySystemBound is true at runtime.

If ASC binding does not complete:

1. Verify the PlayerState implements IAbilitySystemInterface.
2. Check PlayerState initialization timing.
3. Monitor bShouldRetryASCBinding.
4. Ensure ASC is initialized on PlayerState.

If ground distance is wrong:

1. Verify the capsule component exists and is configured.
2. Check collision channels and trace distance.
3. Confirm CachedGroundInfo updates once per frame.