MotionAnimInstance

Advanced Animation Instance providing automatic GAS tag-to-property mapping, sophisticated ground distance calculations, and comprehensive caching system for high-performance animation blueprints. Features intelligent ASC binding with fallback mechanisms and frame-accurate ground information.

Requirements

• Character with Animation Blueprint
• MotionPlayerState configured in GameMode
• Gameplay Ability System (GAS) initialized
• Parent Class: Animation Blueprint must inherit from UMotionAnimInstance
• Component Dependencies: Automatically detects Character, CharacterMovementComponent, and CapsuleComponent
• Caching System: Frame-based caching for optimal performance

Installation

1. Create or open your Animation Blueprint
2. In Class Settings, set Parent Class to MotionAnimInstance
3. Configure the GameplayTagPropertyMap in Class Defaults
4. Map gameplay tags to animation blueprint variables
5. The instance will auto-bind to the character's Ability System Component
6. Ground information will be automatically calculated and cached
7. All component references are cached for performance

Image Placeholder: Animation Blueprint class settings showing MotionAnimInstance as parent

Functionality

MotionAnimInstance automatically syncs GAS tags with animation blueprint properties and provides utility functions.

Preview

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

UMotionAnimInstance now also exposes the active first-person item config to animation code so item-linked layers can react to the currently active item content setup. This is optional: if MotionHeldItemComponent is not present, CurrentFirstPersonItemConfig remains null and the anim instance continues to function normally. See First-Person Item Configs.

Animation Instance Initialization Flow

ASC Binding State Machine

Virtual Functions

Core Animation Functions

Function	Parameters	Return Type	Description
NativeInitializeAnimation()	None	void	Override to initialize custom animation systems
NativeUninitializeAnimation()	None	void	Override to cleanup custom animation systems
NativeUpdateAnimation()	float DeltaSeconds	void	Override to add custom animation update logic
InitializeWithAbilitySystem()	UAbilitySystemComponent* ASC	void	Initialize the animation instance with AbilitySystemComponent

Ground Detection Functions

Function	Parameters	Return Type	Description
GetGroundInfo()	None	FMotionGroundInfo	Calculate and cache ground distance information

ASC Integration Functions

Function	Parameters	Description
OnAbilitySystemAvailable()	UAbilitySystemComponent* ASC	Called when ASC becomes available via delegate

Configuration Properties

Gameplay Tag Property Mapping

Property	Type	Description
GameplayTagPropertyMap	FGameplayTagBlueprintPropertyMap	Maps gameplay tags to Blueprint properties for automatic updates

Animation State Properties

Property	Type	Category	Description
GroundDistance	float	Character State Data	Distance to ground below character (cached per frame)
bIsAbilitySystemBound	bool	Motion Animation	Whether successfully bound to AbilitySystemComponent
CurrentFirstPersonItemConfig	UMotionFirstPersonItemConfig*	Motion Animation	Active local first-person item config exposed from MotionHeldItemComponent, or null when no held-item component is present

Ground Information Structure

FMotionGroundInfo provides comprehensive ground detection:

Property	Type	Description
GroundHitResult	FHitResult	Complete hit information from ground trace
GroundDistance	float	Distance to ground (-1.0 if no ground detected)
LastUpdateTime	double	Time in seconds when last updated for caching

Read-Only State Properties

Cached Component References

Property	Type	Description
CachedCharacter	ACharacter*	Cached reference to the owning character
CachedCharacterMovement	UCharacterMovementComponent*	Cached reference to character movement component
CachedCapsuleComponent	UCapsuleComponent*	Cached reference to capsule component
CachedAbilitySystemComponent	UAbilitySystemComponent*	Cached reference to the ASC

Internal State Tracking

Property	Type	Description
CachedGroundInfo	FMotionGroundInfo	Cached ground information to avoid redundant calculations
bIsAbilitySystemBound	bool	Flag tracking successful ASC binding
bShouldRetryASCBinding	bool	Flag tracking need to retry ASC binding

Gameplay Tag Property Mapping Setup

In the Animation Blueprint's Class Defaults:

1. Find GameplayTagPropertyMap
2. Add entries for each tag-to-property mapping:
   • Tag: Motion.State.Walking
   • Property Name: bIsWalking
   • Property Type: Boolean

Common Motion Tag Mappings

Gameplay Tag	Property Name	Type	Usage
Motion.State.Walking	bIsWalking	Bool	Walking animation state
Motion.State.Sprinting	bIsSprinting	Bool	Sprint animation state
Motion.State.Crouching	bIsCrouching	Bool	Crouch animation state
Motion.State.Jumping	bIsJumping	Bool	Jump/fall animation state
Motion.State.WantsToSprint	bWantsToSprint	Bool	Sprint intention
Motion.State.WantsToCrouch	bWantsToCrouch	Bool	Crouch intention
Motion.State.WantsToJump	bWantsToJump	Bool	Jump intention
Motion.State.MovementHalted	bIsMovementHalted	Bool	Movement is halted
Motion.State.StaminaDepleted	bIsStaminaDepleted	Bool	Stamina is depleted
Motion.State.StaminaRegenBlocked	bIsStaminaRegenBlocked	Bool	Stamina regeneration blocked
Motion.State.StaminaRegenerating	bIsStaminaRegenerating	Bool	Stamina is regenerating

Advanced Ground Detection System

Sophisticated ground information with frame-based caching:

// FMotionGroundInfo structure provides:
struct FMotionGroundInfo
{
    FHitResult GroundHitResult;     // Complete collision information
    float GroundDistance;           // Distance to ground (-1.0 if none)
    double LastUpdateTime;           // Time in seconds for caching
};

Ground Detection Features

• Frame-Accurate Caching: Updates only once per frame for performance
• Complete Hit Information: Full collision data including surface normal
• Automatic Fallback: Returns -1.0 when no ground is detected
• Performance Optimized: Cached results prevent redundant calculations
• Blueprint Accessible: Direct access to GroundDistance property

Animation Blueprint Setup

// In your Animation Blueprint Event Graph
Event Blueprint Update Animation
├── Get Ground Distance
│   └── Use for foot IK or landing preparation
├── Check bIsWalking
│   └── Transition to walk state
├── Check bIsSprinting
│   └── Apply sprint pose
└── Check bIsCrouching
    └── Adjust crouch animations

Automatic ASC Binding

The system handles ASC availability automatically:

1. Attempts immediate binding on initialization
2. If PlayerState not ready, registers delegate
3. Retries binding when ASC becomes available
4. Handles both client and server scenarios

Advanced Features

Intelligent ASC Binding System

Sophisticated binding mechanism with multiple fallback strategies:

1. Immediate binding (PlayerState ready, ASC available)
2. Delegate registration (PlayerState ready, ASC not yet initialized)
3. Retry mechanism (PlayerState not ready, check each frame)
4. Graceful degradation (function without ASC if necessary)

Binding State Management

• bIsAbilitySystemBound: Tracks successful ASC connection
• bShouldRetryASCBinding: Needs retry in next update cycle

Performance Optimization Features

Frame-Based Caching System

// Ground information cached per frame
if (CachedGroundInfo.LastUpdateFrame != GFrameNumber)
{
    // Perform expensive ground trace
    CachedGroundInfo = PerformGroundTrace();
    CachedGroundInfo.LastUpdateFrame = GFrameNumber;
}
// Use cached result for all subsequent calls this frame
return CachedGroundInfo;

Component Reference Caching

• Initialization Caching: All component references cached once
• Null Checking: Safe access patterns with validation
• Memory Efficient: Minimal overhead per animation instance

Optimized Tag Processing

• Direct ASC Access: No component searches during updates
• Batch Processing: All tag mappings processed together
• Conditional Updates: Skip processing when ASC unavailable

Blueprint Integration

After inheriting from MotionAnimInstance, you gain access to:

Built-in Variables

Variable	Type	Category	Description
GroundDistance	float	Character State Data	Current distance to ground
bIsAbilitySystemBound	bool	Motion Animation	ASC binding status
CurrentFirstPersonItemConfig	Object Reference	Motion Animation	Current local first-person item config for item-linked animation logic, or null when the item system is not in use

Auto-Mapped Variables

All properties defined in GameplayTagPropertyMap:

• Automatically Updated: Each frame based on ASC tags
• Type-Safe Access: Full Blueprint IntelliSense support
• Performance Optimized: Direct property updates, no Blueprint calls

Advanced Blueprint Nodes

# Ground Information Access
Get Ground Info → Motion Ground Info Struct
├── Ground Hit Result → Hit Result
├── Ground Distance → Float  
└── Last Update Time → Float

# Binding Status Check
Is Ability System Bound → Boolean

# Component Access
Get Cached Character → Character Reference
Get Cached Character Movement → Character Movement Component
Get Cached Capsule Component → Capsule Component

Common Use Cases

State Machine Transitions

Can Enter Walk State:
- bIsWalking AND NOT bIsSprinting

Can Enter Sprint State:
- bIsSprinting AND GroundDistance <= 0

Can Enter Jump State:
- bIsJumping OR GroundDistance > 100

Blend Spaces

• Use mapped properties for blend space axes
• Combine with velocity for directional blending
• Apply ground distance for landing preparation

Animation Notifiers

• Check state properties before triggering sounds
• Validate movement state for particle effects
• Coordinate with MotionMovementSoundComponent

Debugging and Troubleshooting

Console Commands

Enable comprehensive logging for debugging:

# Motion animation system logging
log LogMotionAnimation Verbose
log LogMotionCore Verbose

# Ability system integration logging
log LogAbilitySystem Verbose
log LogGameplayTags Verbose

# Animation system logging
log LogAnimation Verbose
log LogAnimBlueprint Verbose

# Performance monitoring
stat anim
stat game

Common Issues and Solutions

Properties Not Updating

Problem: Gameplay tag properties not reflecting ASC state
Solutions:

1. Verify tag names match exactly (case sensitive)
2. Ensure property names exist in Blueprint
3. Confirm property types are correct (Bool for most tags)
4. Check bIsAbilitySystemBound is true in runtime

ASC Not Binding

Problem: bIsAbilitySystemBound remains false
Solutions:

• Verify MotionPlayerState is set in GameMode
• Check PlayerState initialization timing
• Monitor bShouldRetryASCBinding flag
• Ensure ASC is properly initialized on PlayerState

Ground Distance Issues

Problem: GroundDistance returning incorrect values
Solutions:

1. Verify capsule component exists and is properly configured
2. Ensure collision channels are set correctly
3. Check trace distance and collision settings
4. Monitor CachedGroundInfo.LastUpdateTime for caching issues

Performance Problems

Problem: Animation updates causing frame drops
Solutions:

• Monitor ground trace frequency (should be once per frame max)
• Check GameplayTagPropertyMap size (avoid excessive mappings)
• Verify component references are cached (no searches per frame)
• Use stat anim to identify bottlenecks

Development Tools

Blueprint Debugging

# Check binding status
Event Blueprint Update Animation
├── Is Ability System Bound?
│   ├── True: Process normally
│   └── False: Print "ASC Not Bound"

# Monitor ground information  
├── Get Ground Info
│   └── Print Ground Distance

# Verify tag mappings
└── For each mapped property
    └── Print property name and value

Runtime Validation

// In custom NativeUpdateAnimation override
void UMyAnimInstance::NativeUpdateAnimation(float DeltaSeconds)
{
    Super::NativeUpdateAnimation(DeltaSeconds);
    
    // Debug ASC binding
    if (!bIsAbilitySystemBound)
    {
        UE_LOG(LogTemp, Warning, TEXT("ASC not bound - Retry: %s"),
               bShouldRetryASCBinding ? TEXT("True") : TEXT("False"));
    }
    
    // Validate ground distance
    if (GroundDistance < -1.0f)
    {
        UE_LOG(LogTemp, Warning, TEXT("Invalid ground distance: %f"), GroundDistance);
    }
}

Performance Monitoring

# Monitor animation performance
stat startfile
stat anim
stat game
# ... play/test ...
stat stopfile

# Check frame timing
stat unit
stat fps

# Memory usage
stat memory
memreport