/ue-character-movement

name: ue-character-movement
description: "Use this skill when working with character movement, CharacterMovementComponent, CMC, movement modes, walking, falling, swimming, flying, custom movement, network prediction, FSavedMove, root motion, floor detection, step-up, or character physics. Also use for 'PhysWalking', 'PhysCustom', 'LaunchCharacter', 'WalkableFloor', or 'movement replication'. See references/ for CMC extension patterns and movement pipeline details."
metadata:
  version: 1.0.0

UE Character Movement

You are an expert in Unreal Engine's `UCharacterMovementComponent` (CMC), the core system that drives character locomotion, floor detection, network prediction, and root motion integration. You understand the full Phys* pipeline, custom movement mode implementation, and the `FSavedMove_Character` prediction architecture.

Context Check

Read `.agents/ue-project-context.md` to determine:

• Whether the project uses `ACharacter` or a custom pawn with its own movement
• The UE version (UE 5.4+ adds `GravityDirection` support, UE 5.5 changes `DoJump` signature)
• Whether multiplayer is involved (affects prediction pipeline complexity)
• Any existing CMC subclass or custom movement modes already in use

Information Gathering

Ask the developer: 1. Are you extending `UCharacterMovementComponent` or configuring the default one? 2. Do you need custom movement modes (wall-running, climbing, dashing)? 3. Is this multiplayer? If so, do custom abilities need network prediction? 4. Are you integrating root motion from animations or gameplay code? 5. Do you need custom gravity directions (UE 5.4+)?

---

CMC Architecture

`UCharacterMovementComponent` sits at the end of a four-level class hierarchy:

UMovementComponent
  -> UNavMovementComponent
    -> UPawnMovementComponent
      -> UCharacterMovementComponent

CMC also implements `IRVOAvoidanceInterface` and `INetworkPredictionInterface`. It is declared `UCLASS(MinimalAPI)`.

CMC lives as a default subobject on `ACharacter`, created in the constructor. `ACharacter` provides the capsule, skeletal mesh, and high-level actions (`Jump`, `Crouch`, `LaunchCharacter`), while CMC handles the actual physics simulation, floor detection, and network prediction.

Movement Modes

CMC dispatches movement logic through `EMovementMode`:

| Mode | Value | Description | |------|-------|-------------| | `MOVE_None` | 0 | No movement processing | | `MOVE_Walking` | 1 | Ground movement with floor detection and step-up | | `MOVE_NavWalking` | 2 | Walking driven by navmesh projection | | `MOVE_Falling` | 3 | Airborne — gravity, air control, landing detection | | `MOVE_Swimming` | 4 | Fluid movement with buoyancy | | `MOVE_Flying` | 5 | Free 3D movement, no gravity | | `MOVE_Custom` | 6 | User-defined; dispatches to `PhysCustom` with a `uint8` sub-mode | | `MOVE_MAX` | 7 | Sentinel value |

Change modes with `SetMovementMode(EMovementMode, uint8 CustomMode = 0)`. The CMC calls `OnMovementModeChanged(PreviousMode, PreviousCustomMode)` after every transition, which is the correct place to handle enter/exit logic for custom modes.

---

Phys* Movement Pipeline

Every tick, CMC processes movement through a strict pipeline. Understanding this flow is essential for writing correct custom movement or debugging unexpected behavior.

`PerformMovement(float DeltaTime)` is the main entry point (protected). It calls `StartNewPhysics()`, which dispatches to the appropriate `Phys*` function based on the current `EMovementMode`. Each `Phys*` function is `protected virtual`:

• `PhysWalking(float deltaTime, int32 Iterations)` — ground movement
• `PhysNavWalking(float deltaTime, int32 Iterations)` — navmesh-projected walking
• `PhysFalling(float deltaTime, int32 Iterations)` — airborne/gravity
• `PhysSwimming(float deltaTime, int32 Iterations)` — fluid movement
• `PhysFlying(float deltaTime, int32 Iterations)` — free flight
• `PhysCustom(float deltaTime, int32 Iterations)` — your code here

Inside each `Phys*` function, two core methods do the heavy lifting:

**`CalcVelocity`** computes the velocity for this frame:

// BlueprintCallable
void CalcVelocity(float DeltaTime, float Friction, bool bFluid, float BrakingDeceleration);

**`SafeMoveUpdatedComponent`** moves the capsule and resolves penetration:

virtual bool SafeMoveUpdatedComponent(
    const FVector& Delta,
    const FQuat& NewRotation,
    bool bSweep,
    FHitResult& OutHit,
    ETeleportType Teleport = ETeleportType::None
);

It wraps `MoveUpdatedComponent` and automatically handles depenetration if the move results in an overlap. Always prefer `SafeMoveUpdatedComponent` over `MoveUpdatedComponent` in custom Phys* functions.

When a sweep hits a surface, `SlideAlongSurface` projects movement along it. When hits occur in a corner (two blocking surfaces), CMC calls `TwoWallAdjust` (virtual on `UMovementComponent`) to compute a safe movement direction that avoids both walls. During `PhysWalking`, `ComputeGroundMovementDelta` (virtual) adjusts the velocity delta to follow the floor slope — it projects horizontal input onto the floor plane so the character walks along inclines rather than into them.

See `references/movement-pipeline.md` for the full flow diagram and per-mode breakdown.

---

Floor Detection

CMC's walking mode relies on continuous floor detection to determine whether the character is grounded.

FFindFloorResult

struct FFindFloorResult
{
    uint32 bBlockingHit : 1;    // Sweep hit something
    uint32 bWalkableFloor : 1;  // Hit surface passes walkability test
    uint32 bLineTrace : 1;      // Result came from line trace (not sweep)
    float FloorDist;             // Distance from capsule bottom to floor
    float LineDist;              // Distance from line trace
    FHitResult HitResult;        // Full hit result data

    bool IsWalkableFloor() const { return bBlockingHit && bWalkableFloor; }
};

Floor Detection Methods

`Fi