How to add Motion to a character

Use this guide when you already have a project character and want to add Motion components to it.

Prerequisites

• Unreal Engine 5.6 or later
• MotionCore enabled in the project
• A PlayerState that implements IAbilitySystemInterface
• An AbilitySystemComponent and AttributeSet available from that PlayerState
• Enhanced Input configured for your project

Add the core components

1. Open your character Blueprint or C++ class.
2. Add the movement components you need:
   • MotionWalkComponent
   • MotionSprintingComponent
   • MotionCrouchingComponent
   • MotionJumpComponent
3. Add support components when the character needs them:
   • MotionCameraEventBus
   • MotionCameraComponent
   • MotionBreathingComponent
   • MotionMovementSoundComponent
   • MotionHeldItemComponent
4. Leave each component's Profile assigned to the current Motion default, or assign a project-owned duplicate profile when you need custom tuning.

Walk Speed Ownership

When MotionWalkComponent is active, set base walking speed on the assigned walk profile, not on the CharacterMovementComponent walk speed field. Motion applies the profile's BaseWalkSpeed to CharacterMovementComponent->MaxWalkSpeed during initialization, and later WalkSpeed attribute changes can overwrite MaxWalkSpeed again at runtime.

Assign component profiles

The covered components read their behavior defaults from DataAsset profiles. New components use the current Motion defaults in Plugins/MotionCore/Content/Motion/Profiles/v2_0_0:

Component	Default profile
MotionWalkComponent	DA_MotionWalkProfile_Default_v2_0_0
MotionSprintingComponent	DA_MotionSprintProfile_Default_v2_0_0
MotionCrouchingComponent	DA_MotionCrouchProfile_Default_v2_0_0
MotionJumpComponent	DA_MotionJumpProfile_Default_v2_0_0
MotionBreathingComponent	DA_MotionBreathingProfile_Default_v2_0_0
MotionMovementSoundComponent	DA_MotionMovementSoundProfile_Default_v2_0_0
MotionCameraComponent	DA_MotionCameraProfile_Default_v2_0_0

To customize Motion's feel, duplicate the matching profile into your project content, edit the duplicate, and assign it to the component's Profile property. See Component profiles for the full workflow and upgrade behavior.

Initialize GAS

If your project initializes GAS manually, initialize the character/ASC pair after possession or once PlayerState is available:

UMotionAbilitySystemHelper::InitializeCharacterAbilitySystemWithAttributeSet(
    this,
    UMotionAttributeSet::StaticClass(),
    true
);

Projects with a custom AttributeSet can use Motion's attribute discovery as long as the expected attribute names are available.

Bind input

1. Create or reuse Enhanced Input actions for sprint, crouch, and jump.
2. Add the mapping context from your PlayerController or character setup.
3. Bind actions through the component helper functions:

MotionSprintComponent->BindSprintInput(SprintAction);
MotionCrouchComponent->BindCrouchInput(CrouchAction);
MotionJumpComponent->BindJumpInput(JumpAction);

Use the explicit Bind*InputWithComponent variants when your project owns the UEnhancedInputComponent lookup.

For a guided walkthrough that creates a new action, adds it to IMC_Motion_KBM, and consumes it from either the character Blueprint or a custom Motion component, see Tutorial: create and use a Motion input.

Set up animation state

For Motion's built-in animation state mapping:

1. Set your Animation Blueprint parent class to UMotionAnimInstance.
2. Map Motion GameplayTags to Blueprint variables in GameplayTagPropertyMap.
3. Use the mapped variables in state machine transitions and blend spaces.

See How to set up MotionAnimInstance for the detailed animation workflow.

Add native first-person body meshes

If the character uses Motion's native first-person held-item path, add two skeletal mesh components to the character:

• FirstPersonUpperBody
• FirstPersonLowerBody

Keep the standard character mesh as the full-body/world-space representation. All three body meshes should share a skeleton and the weapon_r socket. UMotionCameraComponent assigns the native first-person primitive roles for the owning client at runtime.

If you leave CameraPivotSocketName empty, UMotionCameraComponent uses its capsule/ground camera path and keeps weighted FirstPersonUpperBody and attached-item anchors framed inside the final camera safe box. A Camera Offset Curve is optional camera polish, not required setup for native first-person arm or item visibility.

Verify the character

1. Start PIE.
2. Confirm walking, sprinting, crouching, and jumping work locally.
3. Enable Motion logging if a component does not initialize:

log LogMotionCore Verbose
showdebug abilitysystem

4. For multiplayer projects, follow How to test Motion multiplayer.