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.

Preview

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

The architecture below now includes a native local first-person item presentation path driven by MotionNativeFirstPersonItemConfig, MotionHeldItemComponent, and MotionCameraComponent. MotionCameraComponent also owns camera-relative native first-person framing for the non-socket camera path. See First-Person Item Configs.

Architecture Diagrams

High-Level Overview

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

Configuration Data

Motion separates shared component defaults from runtime state and item-specific authoring.

Component profiles are UPrimaryDataAsset assets assigned to walk, sprint, crouch, jump, breathing, movement sound, and camera components. Profiles own behavior-defining defaults such as movement settings, GameplayEffect references, camera curves, movement sound settings, surface sound tables, camera base eye offset and interpolation, and native first-person framing defaults. Standing and crouched camera heights stay derived from capsule and crouch-height math. Components copy profile values into runtime-owned state when play starts; profile assignment is setup-time configuration, not replicated gameplay state.

The current Motion-owned defaults are under Plugins/MotionCore/Content/Motion/Profiles/v2_0_0. Duplicate these profiles into project content before changing Motion's feel. Existing components stay pinned to the profile asset they already reference when Motion ships newer defaults.

Native first-person item configs remain separate DataAssets. They own per-item meshes, automatic tag-driven held pose animations or custom overlay graph selection, configurable upper-body solve bones, item transforms, optional linked animation layers, and optional render tuning for active held items. Camera profiles can tune shared camera and body-framing defaults, but they do not absorb item configs.

References:

• Component profiles
• First-person item configs

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 implementation steps, see How to integrate a custom camera with Motion.

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, usually exposed by your PlayerState through IAbilitySystemInterface

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
• MotionNativeFirstPersonItemConfig: Local first-person item presentation assets that choose paired first-person/world meshes, automatic tag-driven held pose animations or custom graph overlay mode, configurable upper-body solve bones, optional linked layer compatibility, relative transforms, and optional whole-set native render tuning
• MotionNativeFirstPersonItemTuningComponent: PIE/editor tuning bridge that previews and saves native item transforms and render tuning back to the active native config

Local First-Person Item Presentation

Motion's local first-person item path currently sits alongside the rest of the character stack:

• MotionHeldItemComponent owns the replicated active native item config at runtime
• MotionNativeFirstPersonItemConfig provides the content-facing paired mesh setup, automatic tag-driven held pose animations or custom graph overlay mode, and configurable upper-body solve tuning
• MotionNativeFirstPersonItemTuningComponent provides the native config saveback workflow for local PIE tuning
• MotionCameraComponent assigns UE native first-person primitive roles to the body meshes and keeps upper-body/item anchors framed in the final camera safe box
• UMotionAnimInstance exposes the active config, active gameplay tag snapshot, overlay mode, resolved automatic held pose animation, and automatic blend tuning
• a Motion First Person Item Upper Body Overlay node wraps the host final pose, applies baseline held pose to the configured owner-view upper-body/item region, and runs Motion's pitch and hand-IK solve
• linked layers remain optional compatibility or broader pose-set swaps; custom overlay graph references are separate from the normal linked-layer class

This keeps per-item transforms, mesh selection, held pose animation selection, optional custom overlay ownership, and solve topology in content, while keeping shared first-person body framing in Motion-owned final-view code. Project-owned item actions such as fire, reload, recoil, melee, and equip compose after baseline held pose when they need to override it.

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

Subsystem and GameplayEffect Integration

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

For API lookup, see UMotionSubsystem reference. For task-oriented usage, see How to coordinate components with UMotionSubsystem.

GameplayEffect Integration

Motion components use GameplayEffects directly for state management: