MotionAbilitySystemHelper

This page describes helper functions for Motion integration with the Unreal Gameplay Ability System. The library contains ASC lookup, initialization, gameplay tag, attribute, and platform-relative movement functions.

ASC Discovery

GetAbilitySystemComponentFromActor(Actor, bLogErrors=false)

Finds a UAbilitySystemComponent in this order:

1. Does a check of IAbilitySystemInterface on the actor.
2. Does a check for an ASC component on the actor.
3. Does a check of the PlayerState of a Pawn or PlayerController.

If the Pawn PlayerState is not available on the local client, the helper also does a check of the local PlayerController PlayerState.

Attribute Discovery

These functions let Motion work with your AttributeSets by finding attributes by name.

FindAttributeByName(ASC, AttributeName)

Searches the spawned ASC AttributeSets for an FGameplayAttributeData property with the specified name. The search includes inherited properties.

Returns an FGameplayAttribute. The return value is invalid when the function does not find a match.

GetAttributeValueByName(ASC, AttributeName, OutValue)

Reads the current value of an attribute by name.

Returns true when the attribute exists.

SyncWalkSpeedToCharacterMovement(Character, NewWalkSpeed, OldWalkSpeed, bUpdateCrouchedSpeed=true)

Applies a walk speed value to CharacterMovementComponent->MaxWalkSpeed for the character.

When bUpdateCrouchedSpeed is true, the helper also sets MaxWalkSpeedCrouched. For a standing character with a MotionCrouchingComponent, it uses max(NewWalkSpeed + CrouchWalkSpeedModifier, 0). For other characters, it uses NewWalkSpeed. The function accepts OldWalkSpeed, but this value does not affect the result. Motion calls this helper from MotionAttributeSet, MotionWalkComponent, and MotionCrouchingComponent.

Returns false when the character or its CharacterMovementComponent is not available.

Attribute Example

FGameplayAttribute WalkSpeedAttr =
    UMotionAbilitySystemHelper::FindAttributeByName(ASC, "WalkSpeed");

if (WalkSpeedAttr.IsValid())
{
    float Value = ASC->GetNumericAttribute(WalkSpeedAttr);
}

float CurrentStamina = 0.0f;
if (UMotionAbilitySystemHelper::GetAttributeValueByName(ASC, "Stamina", CurrentStamina))
{
    // Use the stamina value.
}

if (UMotionAbilitySystemHelper::FindAttributeByName(ASC, "JumpVelocity").IsValid())
{
    // Jump velocity attribute is available.
}

The JumpVelocity lookup above is only an attribute-discovery example. MotionJumpComponent derives JumpZVelocity from its jump profile and does not query that attribute.

Gameplay Tags

ActorHasGameplayTag(Actor, Tag)

Returns whether the ASC of the actor has the specified GameplayTag.

AddGameplayTagToActor(Actor, Tag)

Adds a loose GameplayTag to the ASC of the actor.

Without authority, this is local-only and is intended for prediction. It does not replace a replicated GameplayEffect for shared multiplayer state.

RemoveGameplayTagFromActor(Actor, Tag)

Removes a loose GameplayTag from the ASC of the actor.

Removal works locally. Use it to remove predicted owner-only tags after server confirmation or rejection.

ApplyTagEffectFromClass(Actor, EffectClass, FallbackTag)

Applies EffectClass. If the function cannot apply the effect, it adds FallbackTag as a loose tag.

Use this when a component supports replicated GameplayEffects and owner-only prediction. A valid server-side effect returns an active handle. The loose-tag fallback returns an invalid handle. Remove it with the applicable fallback tag.

RemoveTagEffectWithFallback(Actor, EffectHandle, FallbackTag)

Removes the tag effect and its fallback loose tag. This function is idempotent. It handles a GameplayEffect or loose tag result from ApplyTagEffectFromClass.

ASC Initialization

InitializeCharacterAbilitySystem(Character, bLogErrors=true)

Initializes ASC owner/avatar bindings for a character.

The helper selects the ASC owner in this order: the ASC component owner, PlayerState, and the character. It returns immediately when the expected owner/avatar binding exists. For other conditions, it calls InitAbilityActorInfo.

Movement Helpers

GetPlatformRelativeVelocity(CMC)

Returns character velocity relative to the moving platform below the character. This function subtracts platform velocity for locomotion calculations.

The base component must report velocity through GetComponentVelocity. Platforms moved only through direct SetActorLocation calls can give no usable platform velocity.