Ue Mover

UE Mover

Target engine: UE 5.8. APIs below are verified against the 5.8 headers; older forms are listed under "Deprecated — do not use".

Mover is Epic's modular movement system, shipped as the Mover plugin (Experimental in 5.8 — APIs and data formats are subject to change). Movement is composed from data-driven objects — UBaseMovementMode, FLayeredMoveBase, FMovementModifierBase, FInstantMovementEffect, UBaseMovementModeTransition — hosted by UMoverComponent and driven by an external backend liaison rather than by TickComponent. Build.cs module names: "Mover" (plus "ChaosMover" for physics-driven movement, "NetworkPrediction" for the rollback backend, "MoverMassIntegration" for Mass). Public headers live under Plugins/Experimental/Mover/Source/Mover/Public. Log category is LogMover; console commands are prefixed Mover. and mover..

Context

Read .agents/ue-project-context.md if it exists (module names, conventions, enabled plugins, GAS/networking setup). Do not stop if it is missing.

Identify the area from the request and the codebase. Ask only when two plausible readings would produce different code.

Full templates live in mover-recipes.md; the default movement set catalogue, data-model detail, utility libraries and debugging live in mover-reference.md.

CMC vs Mover

Mover is not a drop-in UCharacterMovementComponent replacement, and UMoverComponent does not require ACharacter — a USceneComponent root is the only hard requirement. This table matches the one in ue-character-movement.

Concept mapping: CMC movement modes → UBaseMovementMode objects; root motion sources → FLayeredMoveBase; LaunchCharacter/TeleportTo → FInstantMovementEffect; crouching → FMovementModifierBase; mode-change conditions scattered in Phys* → UBaseMovementModeTransition.

Do not put both components on one pawn. Unlike CMC, Mover state is not externally writable: there is no Velocity property to assign. Change motion only through modes, layered moves, modifiers and instant effects.

Setup

Enable Mover (Experimental in 5.8). It pulls in NetworkPrediction (Beta in 5.8), MotionWarping, PoseSearch, Water and ChaosVD. Optional companions: MoverExamples (Experimental — sample maps and pawns), ChaosMover (Experimental — physics backend), MoverAnimNext (Experimental — UAF bridge), MoverIntegrations (Experimental — Mass).

// MyGame.Build.cs
PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "Mover", "GameplayTags" });
// Add "EnhancedInput" when the pawn binds input actions (the pawn recipe includes EnhancedInputComponent.h).
// Add "ChaosMover" only for physics-driven Mover actors.
// Add "MoverMassIntegration" only when driving Mover pawns from Mass.

Project Settings → Plugins → Network Prediction (UNetworkPredictionSettingsObject, config=NetworkPrediction), recommended starting point from the plugin README:

With smoothing on, set the component's SmoothingMode to EMoverSmoothingMode::VisualComponentOffset (the default). Single-player: use ENetworkPredictionTickingPolicy::Independent, or drop Network Prediction entirely by setting BackendClass to UMoverStandaloneLiaisonComponent.

Architecture

AActor (any APawn or AActor with a USceneComponent root)
 └─ UMoverComponent (UActorComponent, IMovementInterface)
     ├─ BackendClass            -> a UActorComponent implementing IMoverBackendLiaisonInterface
     ├─ MovementModes           : TMap<FName, TObjectPtr<UBaseMovementMode>>   (Instanced)
     ├─ StartingMovementMode    : FName
     ├─ Transitions             : TArray<TObjectPtr<UBaseMovementModeTransition>>  (global)
     ├─ PersistentSyncStateDataTypes : TArray<FMoverDataPersistence>
     ├─ InputProducer / InputProducers : objects implementing IMoverInputProducerInterface
     ├─ MovementMixer           : UMovementMixer
     └─ SharedSettings          : auto-built from each mode's SharedSettingsClasses

UCharacterMoverComponent subclasses UMoverComponent and adds character verbs: Jump(), CanActorJump(), Crouch(), UnCrouch(), CanCrouch(), GetCrouchIntent(), IsCrouching(), IsFlying(), IsFalling(), IsAirborne(), IsOnGround(), IsSwimming(), IsSlopeSliding(), and the OnStanceChanged delegate. Use it for humanoid pawns.

Modes never own gameplay state. A mode is a shared, Instanced UObject whose tuning lives in UPROPERTY fields and in shared settings objects (IMovementSettingsInterface, e.g. UCommonLegacyMovementSettings); everything that changes per frame belongs in FMoverSyncState.

// Inside UMyClimbingMode::OnRegistered, after calling Super. Full class in mover-recipes.md.
const UCommonLegacyMovementSettings* Settings = GetMoverComponent()->FindSharedSettings<UCommonLegacyMovementSettings>();

Tick Flow

The backend liaison drives three phases (EMoverTickPhase::ProduceInput, SimulateMovement, ApplyState):

1. ProduceInput — UMoverComponent::ProduceInput(const int32 DeltaTimeMS, FMoverInputCmdContext* Cmd) calls IMoverInputProducerInterface::ProduceInput on every entry of InputProducers, which BeginPlay fills with InputProducer (defaulting to the owner when it implements the interface) plus every owner component implementing it — the 5.8 .cpp never reads bGatherInputFromAllInputProducerComponents. Runs only on the controlling instance; it is not re-run during resimulation.
2. SimulateMovement — OnPreSimulate(TimeStep, StartingData) fires OnPreSimulationTick, then the simulation runs the substep loop:
   • queued instant effects apply;
   • each active FLayeredMoveBase::GenerateMove produces an FProposedMove;
   • unless a layered move fully overrides movement (mover.perf.SkipGenerateMoveIfOverridden), the active mode's GenerateMove runs;
   • UMovementMixer::MixProposedMoves combines them by EMoveMixMode;
   • ProcessGeneratedMovement (bind via BindProcessGeneratedMovement) gets the last word;
   • mode-owned Transitions then global Transitions are evaluated; the first hit calls Trigger and sets FMovementModeTickEndState::NextModeName, otherwise UBaseMovementMode::SimulationTick executes the move;
   • FMovementModeTickEndState::RemainingMs refunds time, producing another substep in the same frame. Then OnPostSimulate(TimeStep, StartingData, EndingData) fires OnPostMovement and OnPostSimulationTick.
3. ApplyState — the liaison calls FinalizeFrame(SyncState, AuxState) (or FinalizeUnchangedFrame()), which moves the actor and fires OnPostFinalize.

Movement Modes

UBaseMovementMode is UCLASS(MinimalAPI, Abstract, Blueprintable, BlueprintType, EditInlineNew, DefaultToInstanced). Override these, verbatim:

virtual void OnRegistered(const FName ModeName, const FMoverSimContext& SimContext) override;
virtual void OnUnregistered(const FMoverSimContext& SimContext) override;
virtual void Activate(const FMoverEventContext& Context, FName PrevModeName, const FMoverSimContext& SimContext, const FMoverTickStartData& StartState, FMoverSyncState* OutSyncState, FMoverAuxStateContext* OutAuxState) override;
virtual void Deactivate(const FMoverEventContext& Context, FName NextModeName, const FMoverSimContext& SimContext) override;
virtual void GenerateMove_Implementation(const FMoverSimContext& SimContext, const FMoverTickStartData& StartState, const FMoverTimeStep& TimeStep, FProposedMove& OutProposedMove) const override;
virtual void SimulationTick_Implementation(const FSimulationTickParams& Params, FMoverTickEndData& OutputState) override;

GenerateMove is const and decides what motion is wanted; SimulationTick performs it (sweeps, floor checks) and writes the ending FMoverDefaultSyncState. Call Super:: on OnRegistered, OnUnregistered, Activate and Deactivate — the base implementations manage owned transitions and fire the Blueprint events. Set bSupportsAsync = true only when GenerateMove/SimulationTick touch no scene components or other game-thread state.

Default set: UWalkingMode, UFallingMode, UFlyingMode, USwimmingMode, UNavWalkingMode, plus the async variants UAsyncWalkingMode, UAsyncFallingMode, UAsyncFlyingMode, UAsyncNavWalkingMode and the simplified USimpleWalkingMode, USimpleFlyingMode, USimpleSpringWalkingMode, USmoothWalkingMode. Default mode names are DefaultModeNames::Walking, ::Falling, ::Flying, ::Swimming. Full catalogue in mover-reference.md.

Register and switch at runtime:

static void MyEnableClimbing(UMoverComponent& MoverComp)
{
    MoverComp.AddMovementModeFromClass(TEXT("Climbing"), UMyClimbingMode::StaticClass());
    MoverComp.QueueNextMode(TEXT("Climbing"), /*bShouldReenter=*/false);   // takes effect next sim frame
}

static void MyDisableClimbing(UMoverComponent& MoverComp)
{
    MoverComp.RemoveMovementMode(TEXT("Climbing"));
}

Layered Moves

FLayeredMoveBase is temporary additive or overriding motion: it only proposes, the active mode executes. Shared fields: MixMode (EMoveMixMode), Priority, DurationMs (>0 timed, 0 single tick, <0 manual), StartSimTimeMs, FinishVelocitySettings (FLayeredMoveFinishVelocitySettings). Overrides, verbatim:

virtual bool GenerateMove(const FMoverTickStartData& StartState, const FMoverTimeStep& TimeStep, const UMoverComponent* MoverComp, UMoverBlackboard* SimBlackboard, FProposedMove& OutProposedMove) override;
virtual bool IsFinished(double CurrentSimTimeMs) const override;
virtual FLayeredMoveBase* Clone() const override;
virtual void NetSerialize(FArchive& Ar) override;
virtual UScriptStruct* GetScriptStruct() const override;
virtual FString ToSimpleString() const override;
virtual void AddReferencedObjects(class FReferenceCollector& Collector) override;

NetSerialize must call Super::NetSerialize(Ar) first, then serialize your own fields — anything omitted will not survive a correction. Queueing stores your TSharedPtr as-is until a later simulation frame flushes it (it is cloned only when the sync state is copied), so fill it in completely first:

static void MyQueueDash(UMoverComponent& MoverComp, const FVector& DashDirection)
{
    TSharedPtr<FLayeredMove_LinearVelocity> Dash = MakeShared<FLayeredMove_LinearVelocity>();
    Dash->Velocity = DashDirection.GetSafeNormal() * 2000.f;
    Dash->DurationMs = 200.f;
    Dash->MixMode = EMoveMixMode::OverrideVelocity;
    MoverComp.QueueLayeredMove(Dash);
}

Shipped moves: FLayeredMove_LinearVelocity, FLayeredMove_JumpImpulseOverDuration, FLayeredMove_JumpTo, FLayeredMove_MoveTo, FLayeredMove_MoveToDynamic, FLayeredMove_RadialImpulse, FLayeredMove_MultiJump, FLayeredMove_Launch, FLayeredMove_AnimRootMotion, FLayeredMove_AnimRootMotion_SimDriven.

A second, instanced form is in progress: stateless logic in ULayeredMoveLogic plus replicated data in FLayeredMoveInstancedData, activated with FLayeredMoveActivationParams. Register the logic class with RegisterMove<T>() / K2_RegisterMove, then QueueLayeredMoveActivation(UMyMoveLogic::StaticClass()) or QueueLayeredMoveActivationWithContext(Params). Prefer FLayeredMoveBase for new C++ work until the instanced path lands; both live side by side in FMoverSyncState.

Movement Modifiers

FMovementModifierBase changes how the simulation behaves without proposing motion — stances, settings swaps, mode remaps. Overrides:

virtual void OnStart(UMoverComponent* MoverComp, const FMoverTimeStep& TimeStep, const FMoverSyncState& SyncState, const FMoverAuxStateContext& AuxState) override;
virtual void OnEnd(UMoverComponent* MoverComp, const FMoverTimeStep& TimeStep, const FMoverSyncState& SyncState, const FMoverAuxStateContext& AuxState) override;
virtual void OnPreMovement(UMoverComponent* MoverComp, const FMoverTimeStep& TimeStep) override;
virtual void OnPostMovement(UMoverComponent* MoverComp, const FMoverTimeStep& TimeStep, const FMoverSyncState& SyncState, const FMoverAuxStateContext& AuxState) override;
virtual FMovementModifierBase* Clone() const override;
virtual void NetSerialize(FArchive& Ar) override;
virtual UScriptStruct* GetScriptStruct() const override;
virtual bool Matches(const FMovementModifierBase* Other) const override;

static FMovementModifierHandle MyQueueStance(UMoverComponent& MoverComp)
{
    return MoverComp.QueueMovementModifier(MakeShared<FStanceModifier>());
}

static void MyCancelStance(UMoverComponent& MoverComp, const FMovementModifierHandle& Handle)
{
    if (MoverComp.IsModifierActiveOrQueued(Handle))
    {
        MoverComp.CancelModifierFromHandle(Handle);
    }
}

Mover assumes one modifier of a given type at a time; the default Matches compares type only. To allow several, override Matches using fields that NetSerialize also writes. FStanceModifier (with EStanceMode and UStanceSettings) is the shipped crouch implementation, driven by UCharacterMoverComponent::Crouch().

Instant Movement Effects

FInstantMovementEffect applies once, consuming no time, at the start or end of a substep. Override virtual bool ApplyMovementEffect(FApplyMovementEffectParams& ApplyEffectParams, FMoverSyncState& OutputState) override; and return true when you changed anything. Shipped: FTeleportEffect, FAsyncTeleportEffect, FJumpImpulseEffect, FApplyVelocityEffect.

static void MyQueueTeleport(UMoverComponent& MoverComp, const FVector& Destination)
{
    TSharedPtr<FTeleportEffect> Teleport = MakeShared<FTeleportEffect>();
    Teleport->TargetLocation = Destination;
    MoverComp.QueueInstantMovementEffect(Teleport);
}

ScheduleInstantMovementEffect / ScheduleLayeredMove delay execution so every endpoint runs them on the same frame; they matter only for ChaosMover's networked physics path. Default to the Queue* forms.

Transitions

UBaseMovementModeTransition decides mode changes from state. Override virtual FTransitionEvalResult Evaluate_Implementation(const FSimulationTickParams& Params) const override; (return FTransitionEvalResult(NextModeName) or FTransitionEvalResult::NoTransition) and virtual void Trigger_Implementation(const FSimulationTickParams& Params) override; for side effects. Put it in a mode's Transitions array for mode-scoped checks or the component's for global ones; bAllowModeReentry and bFirstSubStepOnly control re-entry and substep scope. Transitions are optional — QueueNextMode, FProposedMove::PreferredMode and FMovementModeTickEndState::NextModeName also change modes.

Input Production

Mover does not read Enhanced Input. Cache input on the game thread, then translate it inside ProduceInput:

// AMyMoverPawn : public APawn, public IMoverInputProducerInterface.
// CachedMoveInputIntent, bJumpHeld and bJumpPressedThisFrame are members filled by Enhanced Input handlers.
void AMyMoverPawn::ProduceInput_Implementation(int32 SimTimeMs, FMoverInputCmdContext& InputCmdResult)
{
    FCharacterDefaultInputs& CharacterInputs = InputCmdResult.InputCollection.FindOrAddMutableDataByType<FCharacterDefaultInputs>();
    CharacterInputs.ControlRotation = GetControlRotation();
    CharacterInputs.SetMoveInput(EMoveInputType::DirectionalIntent, CharacterInputs.ControlRotation.RotateVector(CachedMoveInputIntent));
    CharacterInputs.OrientationIntent = CharacterInputs.GetMoveInput().GetSafeNormal();
    CharacterInputs.bIsJumpPressed = bJumpHeld;
    CharacterInputs.bIsJumpJustPressed = bJumpPressedThisFrame;
    bJumpPressedThisFrame = false;
}

With fixed ticking, several render frames can feed one input cmd (or one frame can feed several ticks), so accumulate rather than sample. FCharacterDefaultInputs also carries SuggestedMovementMode, MovementBase/MovementBaseBoneName/bUsingMovementBase. FMoverAIInputs carries RVOVelocityDelta for AI. Full pawn in mover-recipes.md.

Input and Sync State

Both the input cmd and the sync state are dynamic collections (FMoverDataCollection) of FMoverDataStructBase-derived structs, so custom data needs no component subclass.

FMoverDefaultSyncState is required on every Mover actor. Read through the world/base-space accessors — GetLocation_WorldSpace(), GetVelocity_WorldSpace(), GetOrientation_WorldSpace(), GetAngularVelocityDegrees_WorldSpace(), GetTransform_WorldSpace() — and write with SetTransforms_WorldSpace(Location, Orient, Velocity, AngularVelocityDegrees, Base, BaseBone).

void UMyClimbingMode::SimulationTick_Implementation(const FSimulationTickParams& Params, FMoverTickEndData& OutputState)
{
    const FMoverDefaultSyncState* StartingSyncState = Params.StartState.SyncState.SyncStateCollection.FindDataByType<FMoverDefaultSyncState>();
    check(StartingSyncState);

    FMyClimbState& OutClimb = OutputState.SyncState.SyncStateCollection.FindOrAddMutableDataByType<FMyClimbState>();
    OutClimb.SurfaceNormal = StartingSyncState->GetOrientation_WorldSpace().Vector();
}

Custom state structs must override Clone, NetSerialize, GetScriptStruct, ToString, ShouldReconcile and Interpolate. Anything that must survive a frame without being rewritten goes in PersistentSyncStateDataTypes as an FMoverDataPersistence.

UMoverBlackboard (GetSimBlackboard() / GetSimBlackboard_Mutable()) caches derived values outside the networked state — CommonBlackboard::LastFloorResult, LastWaterResult, LastFoundDynamicMovementBase, TimeSinceSupported. It is being replaced by the rollback-aware blackboard (GetRollbackBlackboardExternal()), so always treat a lookup as possibly missing and provide a fallback. TryGet<T> and Set<T> are type-strict: store and read the same type (a value written as double must be read as double).