ue-character-movement

What this skill does

# 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:
```cpp
// BlueprintCallable
void CalcVelocity(float DeltaTime, float Friction, bool bFluid, float BrakingDeceleration);
```

**`SafeMoveUpdatedComponent`** moves the capsule and resolves penetration:
```cpp
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

```cpp
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

`FindFloor` is the primary method:
```cpp
void FindFloor(
    const FVector& CapsuleLocation,
    FFindFloorResult& OutFloorResult,
    bool bCanUseCachedLocation,
    const FHitResult* DownwardSweepResult = nullptr
);
```

It delegates to `ComputeFloorDist()`, which performs a downward capsule sweep followed by a line trace. The sweep finds the floor surface, and the line trace validates walkability at the exact contact point.

### Walkable Floor Angle

Two linked properties control what counts as "walkable":

- `WalkableFloorAngle` (default 44.765 degrees) — the maximum surface angle in degrees
- `WalkableFloorZ` — the corresponding Z component of the surface normal (auto-calculated from the angle)

Set the angle, not the Z value directly. `SetWalkableFloorAngle()` updates both.

---

## Custom Movement Modes

`MOVE_Custom` with a `uint8` sub-mode is the standard way to add new movement types. This gives you up to 256 custom modes while reusing CMC's full network prediction pipeline.

### Implementation Steps

1. Define custom mode constants:
```cpp
UENUM(BlueprintType)
enum class ECustomMovementMode : uint8
{
    WallRun = 0,
    Climb   = 1,
    Dash    = 2
};
```

2. Override `PhysCustom` in your CMC subclass:
```cpp
virtual void PhysCustom(float deltaTime, int32 Iterations) override;
```

3. Enter the mode using `SetMovementMode`:
```cpp
SetMovementMode(MOVE_Custom, static_cast<uint8>(ECustomMovementMode::WallRun));
```

4. Handle transitions in `OnMovementModeChanged`:
```cpp
virtual void OnMovementModeChanged(EMovementMode PrevMode, uint8 PrevCustomMode) override;
```

Inside `PhysCustom`, dispatch on `CustomMovementMode` and implement your simulation. Call `CalcVelocity` for acceleration, `SafeMoveUpdatedComponent` for capsule movement, and `SetMovementMode` when transitioning out.

See `references/cmc-extension-patterns.md` for a complete wall-run implementation.

---

## Network Prediction

CMC uses a client-side prediction and server reconciliation model. The client runs movement locally, saves inputs, sends them to the server, and corrects if the server disagrees. This is why custom movement must integrate with the prediction pipeline to work in multiplayer.

### FSavedMove_Character

Each client tick generates a saved move that records the input state:

Key fields: `bPressedJump`, `bWantsToCrouch`, `StartLocation`, `StartVelocity`, `SavedLocation`, `Acceleration`, `MaxSpeed`.

Key virtuals to override for custom data:
- `Clear()` — reset your custom