MotionAnimInstance

MotionAnimInstance is an Animation Instance base class that connects Motion movement state to Animation Blueprints. It gives GAS tag-to-property mapping, cached ground detection, and ASC binding. It also exposes native first-person item configs, gameplay tag snapshots, and held pose animations. Upper-body item overlays can read active held-item presentation action snapshots.

Requirements

• You must set the Animation Blueprint parent class to UMotionAnimInstance.
• The Animation Blueprint must have a character owner.
• Motion must find an ASC for tag-to-property mapping. Motion uses IAbilitySystemInterface and direct ASC components on the owning actor. Then, it does a check for direct ASC components on the PlayerState.
• You must initialize the Gameplay Ability System if you use tag mapping.

For setup steps, see How to set up MotionAnimInstance.

UMotionAnimInstance exposes the active first-person item config to animation code. Automatic held pose overlays, custom graph layers, optional linked layers, and presentation actions can use this config. If MotionHeldItemComponent is not present, CurrentFirstPersonItemConfig remains null.

Behavior

During initialization, the animation instance caches the owning character and CharacterMovementComponent. It also caches the capsule, held-item, and ASC components when they are available. If PlayerState or ASC initialization is not ready, it tries binding again during animation update. After binding, it does periodic checks for controller, pawn, or ASC changes. These changes can initialize the tag map again.

During animation updates, the instance can:

• retry or revalidate ASC binding every 0.5 seconds
• refresh walking ground data each update and throttle airborne traces to about 30 Hz
• 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 and blend time from the active item config
• expose effective upper-body solve settings and control-rotation pitch for the automatic held pose overlay
• expose the active held-item presentation action snapshot owned by MotionHeldItemComponent

The animation instance initializes GameplayTagPropertyMap against the ASC and registers tag-change delegates. Mapped properties update when tag counts change. NativeUpdateAnimation does not poll the map each frame.

API

Lifecycle

• NativeInitializeAnimation() -> void: initializes cached references and starts ASC binding.
• NativeUninitializeAnimation() -> void: resets ASC binding and cached overlay/presentation state.
• NativeUpdateAnimation(float DeltaSeconds) -> void: handles binding retries, ground data, held-item state, and first-person overlay snapshots.
• InitializeWithAbilitySystem(UAbilitySystemComponent* ASC) -> void: initializes the animation instance with an ASC.

Protected ground detection

• GetGroundInfo() -> FMotionGroundInfo: Protected helper that returns cached ground information. Walking data can refresh during each animation update. Airborne line traces have a limit of one trace every 0.033 seconds.

ASC integration

• InitializeWithAbilitySystem(UAbilitySystemComponent* ASC) -> void: initializes or reinitializes GameplayTagPropertyMap with the resolved ASC. The animation instance calls this from initialization and retry paths when an ASC becomes available.

Native first-person item overlay

• 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 native overlay node reads this value. 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.
• GetNativeFirstPersonItemAutomaticOverlayBlendTime() -> float: thread-safe lookup for the active automatic overlay blend time, or 0.0 when automatic output is unavailable.
• GetNativeFirstPersonItemAutomaticOverlayBlendWeight() -> float: thread-safe lookup for the active automatic overlay blend weight, 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.
• GetNativeFirstPersonItemCustomOverlayLayerClass() -> TSubclassOf<UAnimInstance>: thread-safe lookup for the active custom overlay layer class, or null.
• GetNativeFirstPersonItemCustomOverlayLayerGraphName() -> FName: thread-safe lookup for the active custom overlay layer graph name, or None.
• ResolveNativeFirstPersonItemAutomaticHeldPoseAnimationWithDiagnostics(OutMessages) -> UAnimSequence*: setup/event-time lookup that emits overlay diagnostics through OutMessages and logs setup warnings once per config/message.
• GetNativeFirstPersonItemUpperBodySolveSettings() -> FMotionNativeFirstPersonItemUpperBodySolveSettings: Returns effective solve tuning for AnimGraph use from the active item config. Returns Motion defaults when no active config exists or when the solve settings are invalid.
• GetNativeFirstPersonControlRotationPitch() -> float: Returns normalized view pitch in the overlay pitch-solve convention. Local controllers use their control rotation. Controllerless observed pawns use replicated pawn base aim rotation. Thus, remote-player look pitch can control the overlay.
• HasNativeFirstPersonPresentationAction() -> bool: thread-safe availability flag for the active component-owned presentation action snapshot.
• GetNativeFirstPersonPresentationActionState() -> FMotionHeldItemPresentationActionState: thread-safe lookup for the active action instance ID, tag, sequence, playback time, duration, blend settings, terminal-snapshot flag, and source config.

Configuration

GameplayTagPropertyMap

Maps ASC-owned GameplayTags to Animation Blueprint properties. The usual pattern maps Motion state tags to Boolean properties. Examples include bIsWalking, bIsSprinting, bIsCrouching, and bIsJumping.

For pose, camera, and held-item presentation decisions, map active tags such as Motion.State.Sprinting and Motion.State.Crouching. Motion.State.WantsTo* tags are input intent and can be true before the active state is valid. On a locally controlled client, Motion predicts the WantsTo* intent tags as loose tags. Authority applies active movement-state tags.

Usual 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: This float is the cached distance to ground below the character. It is 0.0 during walking and keeps the last result between airborne traces.
• bIsAbilitySystemBound: This bool shows whether the instance bound to an ASC.
• CurrentFirstPersonItemConfig: This is the active usable UMotionNativeFirstPersonItemConfig. It is null when no held-item component or config is active.

Held-Item State Mapping

MotionAnimInstance reads MotionHeldItemComponent of the owning character during NativeUpdateAnimation. It uses the applied usable config of the component, not the raw replicated config. Thus, invalid mesh config data cannot continue to control the overlay.

Animation state	Runtime source
CurrentFirstPersonItemConfig	MotionHeldItemComponent::GetActiveUsableItemConfig()
NativeFirstPersonActiveGameplayTags	bound Ability System Component (ASC) owned tag snapshot
CurrentFirstPersonItemAutomaticHeldPoseAnimation	CurrentFirstPersonItemConfig->ResolveAutomaticHeldPoseAnimation(NativeFirstPersonActiveGameplayTags)
bHasNativeFirstPersonItemAutomaticHeldPoseAnimation	whether CurrentFirstPersonItemAutomaticHeldPoseAnimation is set
CurrentFirstPersonItemOverlayMode	CurrentFirstPersonItemConfig->OverlayMode
NativeFirstPersonItemAutomaticOverlayBlendTime	CurrentFirstPersonItemConfig->GetAutomaticOverlayBlendTime() when an automatic held pose is available, otherwise 0.0
NativeFirstPersonItemAutomaticOverlayBlendWeight	CurrentFirstPersonItemConfig->AutomaticHeldPoseSettings.OverlayBlendWeight when an automatic held pose is available, otherwise 0.0
NativeFirstPersonItemCustomOverlayLayerClass	CurrentFirstPersonItemConfig->GetCustomOverlayLayerClass()
NativeFirstPersonItemCustomOverlayLayerGraphName	CurrentFirstPersonItemConfig->GetCustomOverlayLayerGraphName()
NativeFirstPersonItemUpperBodySolveSettings	CurrentFirstPersonItemConfig->GetEffectiveUpperBodySolveSettings()
NativeFirstPersonControlRotationPitch	controller rotation or replicated pawn base aim rotation converted to Motion overlay pitch
NativeFirstPersonPresentationActionState	MotionHeldItemComponent::GetHeldItemPresentationActionState()

Automatic Held Pose Resolution

The automatic held pose resolver is for upper-body item held pose overlays. Stance-specific item variables are not necessary in host Animation Blueprints.

Resolution rules:

• MotionAnimInstance snapshots active ASC gameplay tags during update.
• The resolver validates the full automatic setup first. A fallback animation is necessary. An invalid rule or single-tag entry makes resolution return null.
• The active config evaluates AutomaticHeldPoseSettings.HeldPoseAnimationRules first. A rule matches when all necessary tags are present and no blocked tag is present.
• The applicable rule with the highest Priority wins. For equal priorities, the resolver selects the rule with more necessary and blocked tags. A second tie keeps array order.
• If no rule matches, the resolver evaluates the single-tag HeldPoseAnimations entries in array order. The first applicable entry wins.
• 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 automatic held pose asset, automatic blend time, and effective upper-body solve settings. The native Motion First Person Item Upper Body Overlay node reads this stable state. Per-item variables are not necessary in the host Animation Blueprint.

When no item config is active, GetNativeFirstPersonItemUpperBodySolveSettings returns Motion defaults without a warning. The automatic blend accessor returns zero. Invalid automatic setup makes the overlay node pass the host pose through. The pure getters are useful for debug UI, validation tools, or custom graph logic. Do not connect them to exposed overlay-node pins in the basic setup.

GetNativeFirstPersonControlRotationPitch is the Motion first-person overlay pitch source. UE camera look-down pitch is negative, but the overlay solve uses positive look-down pitch. For locally controlled pawns, controller rotation supplies the value. For controllerless simulated proxies, replicated Unreal base aim rotation supplies it. Thus, observers use the same Motion overlay convention.

Presentation Action Snapshot

MotionHeldItemComponent owns held-item presentation actions. During animation update, MotionAnimInstance copies the active action state of the component. It caches this snapshot for the native overlay node.

The snapshot is visual state only. It gives the finite action sequence and component-owned playback time to the overlay. It also shows whether a completed action remains available for the same frame before it clears. Presentation actions temporarily replace the selected automatic held pose. Project gameplay logic controls attack, reload, fire, inspect, melee, cooldown, ammo, and inventory permission.

CustomGraph items do not expose Motion presentation actions. Their action requests return Unsupported. The custom graph is responsible for custom action composition.

Ground Information

FMotionGroundInfo contains:

• GroundHitResult: This is the active floor hit of the movement component during walking, or the airborne line-trace hit.
• GroundDistance: This is 0.0 during walking. In the air, it is the traced distance. It is MaxGroundTraceDistance when the trace has no blocking hit. The default maximum is 100000.0. It is -1.0 when necessary character references are unavailable.
• LastUpdateTime: time in seconds when the value was last updated.

The instance caches ground information internally. Animation Blueprints read the exposed GroundDistance. The instance reuses airborne traces for the 0.033-second trace interval.

Internal Cached State

• CachedCharacter: owning character.
• CachedCharacterMovement: owning character movement component.
• CachedCapsuleComponent: owning capsule component.
• CachedAbilitySystemComponent: bound ASC.
• CachedGroundInfo: cached ground trace result.
• bShouldRetryASCBinding: Shows whether binding is pending. Attempts have a limit of one attempt every 0.5 seconds.

ASC Binding

ASC binding uses several fallback paths:

1. Bind immediately when an ASC resolves from the owning actor.
2. Retry during animation update when the ASC is not ready.
3. Recheck after binding so ASC destruction, controller swaps, pawn possession changes, or ASC replacement can reinitialize the mapping.
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
• GetNativeFirstPersonItemAutomaticOverlayBlendTime
• GetNativeFirstPersonItemAutomaticOverlayBlendWeight
• GetNativeFirstPersonActiveGameplayTags
• GetNativeFirstPersonItemCustomOverlayLayerClass
• GetNativeFirstPersonItemCustomOverlayLayerGraphName
• ResolveNativeFirstPersonItemAutomaticHeldPoseAnimationWithDiagnostics
• GetNativeFirstPersonItemUpperBodySolveSettings
• GetNativeFirstPersonControlRotationPitch
• HasNativeFirstPersonPresentationAction
• GetNativeFirstPersonPresentationActionState
• all properties mapped through GameplayTagPropertyMap

The instance initializes mapped properties from active ASC tag counts. Then, ASC tag-change delegates update the properties while the map 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 read mapped state before they start sounds or effects.

Debugging

Useful console commands:

log LogMotionCharacter Verbose
log LogMotionCore Verbose
log LogAbilitySystem Verbose
log LogGameplayTags Verbose
log LogAnimation Verbose
stat anim
stat game

Checks

If mapped properties do not update:

1. Make sure that tag names match exactly.
2. Make sure that property names exist in the Animation Blueprint.
3. Make sure that property types are correct.
4. Read bIsAbilitySystemBound and make sure that it is true at runtime.

If ASC binding does not complete:

1. Make sure that an ASC exists on the owning actor or its PlayerState. Or, make sure that the owning actor implements IAbilitySystemInterface.
2. Do a check of PlayerState initialization timing.
3. Wait for the 0.5-second retry interval.
4. Make sure that the ASC initialized owner/avatar actor info.

If ground distance is wrong:

1. Make sure that the capsule component exists and is configured.
2. Do a check of collision channels and trace distance.
3. Make sure that walking data refreshes during animation update. Airborne traces must refresh at approximately 30 Hz.