Architecture

MotionCore is a universal character locomotion system for Unreal Engine 5. It provides first-person movement through modular components. Works with ANY ACharacter subclass - no inheritance required.

Architecture Diagrams

High-Level Overview

This diagram shows the core architecture of MotionCore and how components integrate with your character:

GAS Integration

This diagram shows how the Gameplay Ability System (GAS) integrates with Motion components:

Component Integration

This diagram details how Motion components integrate with your existing character:

Camera Event Bus

This diagram shows how Motion components communicate camera effects through a decoupled event bus pattern:

Why Event Bus?

The Camera Event Bus pattern decouples movement components from the camera implementation:

• Movement components broadcast events (camera shake, bob, height changes) without knowing which camera will receive them
• UMotionCameraComponent subscribes to these events and applies the effects
• Custom cameras can also subscribe to receive the same events and implement their own effect handling
• No direct dependencies - movement components work even if no camera subscribes

Event Types:

Event	Purpose	Example Use
OnMotionCurveEvent	Curve-based camera effects (shake, bob, breathing)	Walk bob, sprint shake, jump impact
OnCameraHeightEvent	Camera height transitions	Crouch/stand height changes

For Custom Camera Integration:

// Get the event bus from your character
UMotionCameraEventBus* EventBus = Character->FindComponentByClass<UMotionCameraEventBus>();
if (EventBus)
{
    // Subscribe to curve events
    EventBus->OnMotionCurveEvent.AddDynamic(this, &UYourCamera::HandleCurveEvent);

    // Subscribe to height events
    EventBus->OnCameraHeightEvent.AddDynamic(this, &UYourCamera::HandleHeightEvent);
}

Data Flow

This diagram shows how input flows through the system to create movement:

Networking & Multiplayer

This diagram shows the networking architecture for multiplayer games:

Functionality

Each layer in the architecture serves a specific purpose in the overall system:

Standard UE5 Framework Layer

This layer consists of standard Unreal Engine 5 classes that MotionCore integrates with:

• GameMode: Your existing GameMode class - set PlayerStateClass to your PlayerState that implements IAbilitySystemInterface
• PlayerController: Your existing PlayerController - no modifications required
• PlayerState: Your PlayerState must implement IAbilitySystemInterface to provide networked ASC ownership. Motion works with ANY PlayerState implementation.
• AbilitySystemComponent: Standard UE5 GAS component, owned by MotionPlayerState for proper networking

Character Core Layer

The foundation layer that MotionCore enhances without modification:

• ACharacter: ANY character class works - no inheritance from Motion classes required
• CharacterMovementComponent: Standard UE5 movement component that Motion components modify
• CapsuleComponent: Standard collision component used for crouch height adjustments
• MotionCameraComponent: Advanced first-person camera with procedural effects and curve support
• Animation Blueprint: Your existing animation system - Motion integrates via notifies and interfaces

Motion Component System

Modular components that add specific movement behaviors to any character:

• MotionComponentBase: Base class providing common functionality like auto-discovery of required components
• Movement Components: Walk, Sprint, Crouch, Jump - each modifies the standard CharacterMovementComponent
• Support Components: Sound and Breathing - add polish through audio and visual feedback
• Each component is optional and can be added independently based on project needs

Input & Control Layer

Handles player input and ability activation:

• Enhanced Input System: Standard UE5 input system with provided Motion input actions
• Motion Input Helpers: Static utility functions for input processing and ability binding
• GAS Integration: Input triggers abilities through the standard AbilitySystemComponent

Data & Configuration Layer

Content-driven configuration and runtime data:

• MotionAttributeSet: GAS attributes for stamina, movement speeds, and other gameplay values
• Gameplay Effects: Define state changes, attribute modifications, and ability costs
• Curves: UCurveVector assets for camera effects (location/rotation offsets), UCurveFloat for other parameters
• Sound Data: Surface-based footstep sounds with multi-variant support

Utilities & Validation Layer

Development tools and runtime helpers:

• Compatibility Validator: Ensures Motion works with your existing character setup
• Logging System: Comprehensive debug categories for troubleshooting
• Function Libraries: Blueprint-exposed utilities for curves, components, and GAS operations

Key Design Principles

Universal Compatibility

• Works with ANY ACharacter subclass without inheritance requirements
• Integrates with standard UE5 components (CharacterMovementComponent, AbilitySystemComponent)
• No conflicts with existing character implementations or marketplace assets

Modular Architecture

• Each Motion component is independent and optional
• Add only the components your project needs
• Components auto-discover required actors and systems at runtime

Standard UE5 Integration

• Uses established UE5 patterns and best practices
• Leverages built-in systems (GAS, Enhanced Input, Replication)
• Maintains compatibility with UE5 updates and features

Network-Ready Design

• Server-authoritative movement using standard CharacterMovementComponent
• PlayerState-owned ASC for proper ability persistence across respawns
• Client prediction and validation following UE5 networking patterns

Developer-Friendly

• Comprehensive Blueprint API for visual scripting
• Clear separation of concerns between layers
• Extensive logging and validation tools for debugging

Preview 3 Architecture Additions

Motion Subsystem

The UMotionSubsystem is a ULocalPlayerSubsystem that provides centralized component orchestration:

Key Responsibilities:

• Registry: Track all active Motion components per player
• Orchestration: Handle init order, dependencies, state transitions
• Ability Management: Auto-grant movement abilities when components register

// Access the subsystem
UMotionSubsystem* Subsystem = LocalPlayer->GetSubsystem<UMotionSubsystem>();

// Query active components
TArray<UMotionComponentBase*> Components = Subsystem->GetActiveComponents();
UMotionWalkComponent* WalkComp = Cast<UMotionWalkComponent>(
    Subsystem->GetComponentByClass(UMotionWalkComponent::StaticClass()));

// Auto-grant movement abilities
Subsystem->GrantMovementAbilities(ASC);

GameplayEffect Integration

Motion components use GameplayEffects directly for state management:

Gameplay Debugger

New "Motion" category in the UE5 Gameplay Debugger (' key in-game):

=== MOTION DEBUG ===

Components:
  [X] Walk
  [X] Sprint (ACTIVE)
  [+] Crouch
  [+] Jump (2/3)
  [+] Camera
  [ ] Breathing
  [ ] Sound

Movement:
  Current Speed: 600.0
  Walk Speed: 400.0
  Sprint Speed: 600.0

Stamina:
  75.0 / 100.0 (75%)

Camera Curves (2 active):
  WalkBob
  SprintShake

Gameplay Effects (3):
  GE_Motion_SprintSpeed
  GE_Motion_SprintStaminaDrain
  GE_Motion_SprintStaminaRegen

Gameplay Tags (2):
  Motion.State.Sprinting
  Motion.State.Moving

Subsystem:
  Active - 4 components registered

Enable via console: showdebug Motion

Editor Validation

Motion components validate configuration at Blueprint compile time:

#if WITH_EDITOR
EDataValidationResult UMotionWalkComponent::IsDataValid(FDataValidationContext& Context) const
{
    EDataValidationResult Result = Super::IsDataValid(Context);

    // Validate required configuration
    if (BaseWalkSpeed <= 0.0f)
    {
        Context.AddError(FText::FromString(TEXT("BaseWalkSpeed must be greater than 0")));
        Result = EDataValidationResult::Invalid;
    }

    return Result;
}
#endif

Validation checks include:

• Component attached to ACharacter subclass
• Required properties have valid values
• Curve assets are assigned when effects are enabled
• GAS configuration is correct