claude-code-arcane 2.2.0 → 2.4.0

package/skills/ue-character-movement/references/cmc-extension-patterns.md

@@ -0,0 +1,335 @@
+# CMC Extension Patterns
+
+Complete code templates for extending `UCharacterMovementComponent` with custom movement modes, networked prediction, and custom move data.
+
+---
+
+## Custom CMC Subclass Header
+
+```cpp
+// MyCMC.h
+#pragma once
+#include "GameFramework/CharacterMovementComponent.h"
+#include "MyCMC.generated.h"
+
+UENUM(BlueprintType)
+enum class ECustomMovementMode : uint8
+{
+    None     = 0,
+    WallRun  = 1,
+    Climb    = 2,
+    Dash     = 3
+};
+
+UCLASS()
+class MYGAME_API UMyCMC : public UCharacterMovementComponent
+{
+    GENERATED_BODY()
+
+public:
+    UMyCMC();
+
+    // --- Custom movement state ---
+    UPROPERTY(Transient)
+    uint8 bWantsToWallRun : 1;
+
+    UPROPERTY(Transient)
+    FVector WallRunNormal;
+
+    // --- Overrides ---
+    virtual void PhysCustom(float deltaTime, int32 Iterations) override;
+    virtual void OnMovementModeChanged(EMovementMode PrevMode, uint8 PrevCustomMode) override;
+    virtual FNetworkPredictionData_Client* GetPredictionData_Client() const override;
+
+protected:
+    void PhysWallRun(float deltaTime, int32 Iterations);
+    void PhysClimb(float deltaTime, int32 Iterations);
+    void PhysDash(float deltaTime, int32 Iterations);
+
+    bool CanWallRun() const;
+    void EnterWallRun(const FHitResult& WallHit);
+    void ExitWallRun();
+};
+```
+
+---
+
+## FSavedMove_Character Subclass
+
+```cpp
+// MySavedMove.h (can live in MyCMC.h)
+class FMySavedMove : public FSavedMove_Character
+{
+public:
+    typedef FSavedMove_Character Super;
+
+    // Custom saved state
+    uint8 bSavedWantsToWallRun : 1;
+    FVector SavedWallRunNormal;
+
+    virtual void Clear() override
+    {
+        Super::Clear();
+        bSavedWantsToWallRun = 0;
+        SavedWallRunNormal = FVector::ZeroVector;
+    }
+
+    virtual void SetMoveFor(
+        ACharacter* C,
+        float InDeltaTime,
+        FVector const& NewAccel,
+        FNetworkPredictionData_Client_Character& ClientData) override
+    {
+        Super::SetMoveFor(C, InDeltaTime, NewAccel, ClientData);
+
+        // Capture custom state from CMC before the move executes
+        UMyCMC* CMC = Cast<UMyCMC>(C->GetCharacterMovement());
+        if (CMC)
+        {
+            bSavedWantsToWallRun = CMC->bWantsToWallRun;
+            SavedWallRunNormal = CMC->WallRunNormal;
+        }
+    }
+
+    virtual void PrepMoveFor(ACharacter* C) override
+    {
+        Super::PrepMoveFor(C);
+
+        // Restore custom state before replaying this move
+        UMyCMC* CMC = Cast<UMyCMC>(C->GetCharacterMovement());
+        if (CMC)
+        {
+            CMC->bWantsToWallRun = bSavedWantsToWallRun;
+            CMC->WallRunNormal = SavedWallRunNormal;
+        }
+    }
+
+    virtual uint8 GetCompressedFlags() const override
+    {
+        uint8 Result = Super::GetCompressedFlags();
+
+        if (bSavedWantsToWallRun)
+        {
+            Result |= FLAG_Custom_0;  // 0x10
+        }
+
+        return Result;
+    }
+
+    virtual bool CanCombineWith(
+        const FSavedMovePtr& NewMove,
+        ACharacter* InCharacter,
+        float MaxDelta) const override
+    {
+        const FMySavedMove* Other = static_cast<const FMySavedMove*>(NewMove.Get());
+
+        if (bSavedWantsToWallRun != Other->bSavedWantsToWallRun)
+        {
+            return false;
+        }
+
+        if (bSavedWantsToWallRun && !SavedWallRunNormal.Equals(Other->SavedWallRunNormal, 0.1f))
+        {
+            return false;
+        }
+
+        return Super::CanCombineWith(NewMove, InCharacter, MaxDelta);
+    }
+};
+```
+
+---
+
+## FNetworkPredictionData_Client_Character Subclass
+
+```cpp
+class FMyNetworkPredictionData : public FNetworkPredictionData_Client_Character
+{
+public:
+    typedef FNetworkPredictionData_Client_Character Super;
+
+    FMyNetworkPredictionData(const UCharacterMovementComponent& ClientMovement)
+        : Super(ClientMovement) {}
+
+    virtual FSavedMovePtr AllocateNewMove() override
+    {
+        return FSavedMovePtr(new FMySavedMove());
+    }
+};
+```
+
+---
+
+## GetPredictionData_Client Override (Lazy-Init Pattern)
+
+Override on your CMC subclass. Uses `const_cast` because the base method is `const` but the prediction data is mutable state:
+
+```cpp
+FNetworkPredictionData_Client* UMyCMC::GetPredictionData_Client() const
+{
+    if (ClientPredictionData == nullptr)
+    {
+        UMyCMC* MutableThis = const_cast<UMyCMC*>(this);
+        MutableThis->ClientPredictionData = new FMyNetworkPredictionData(*this);
+    }
+
+    return ClientPredictionData;
+}
+```
+
+---
+
+## Wall-Run PhysCustom Implementation
+
+```cpp
+void UMyCMC::PhysCustom(float deltaTime, int32 Iterations)
+{
+    Super::PhysCustom(deltaTime, Iterations);
+
+    switch (static_cast<ECustomMovementMode>(CustomMovementMode))
+    {
+    case ECustomMovementMode::WallRun:
+        PhysWallRun(deltaTime, Iterations);
+        break;
+    case ECustomMovementMode::Climb:
+        PhysClimb(deltaTime, Iterations);
+        break;
+    case ECustomMovementMode::Dash:
+        PhysDash(deltaTime, Iterations);
+        break;
+    default:
+        UE_LOG(LogTemp, Warning, TEXT("Unknown custom movement mode: %d"), CustomMovementMode);
+        SetMovementMode(MOVE_Falling);
+        break;
+    }
+}
+
+void UMyCMC::PhysWallRun(float deltaTime, int32 Iterations)
+{
+    if (deltaTime < MIN_TICK_TIME) { return; }
+    if (!bWantsToWallRun || !CanWallRun())
+    {
+        ExitWallRun();
+        return;
+    }
+
+    // Wall-run direction: cross gravity up with wall normal
+    FVector RunDir = FVector::CrossProduct(WallRunNormal, FVector::UpVector);
+
+    // Match character's forward to determine left vs right wall
+    if (FVector::DotProduct(RunDir, UpdatedComponent->GetForwardVector()) < 0.f)
+    {
+        RunDir *= -1.f;
+    }
+
+    // Accelerate along wall
+    Velocity = RunDir * MaxCustomMovementSpeed;
+
+    // Apply slight gravity pull toward wall to maintain contact
+    Velocity += -WallRunNormal * 50.f;
+
+    // Move
+    FHitResult Hit;
+    SafeMoveUpdatedComponent(Velocity * deltaTime, UpdatedComponent->GetComponentQuat(),
+                             true, Hit);
+
+    // Verify wall is still there
+    if (Hit.bBlockingHit)
+    {
+        WallRunNormal = Hit.Normal;
+    }
+    else
+    {
+        // Lost wall contact — check with a trace
+        FHitResult WallCheck;
+        FVector TraceEnd = UpdatedComponent->GetComponentLocation()
+                           - WallRunNormal * 100.f;
+        bool bStillOnWall = GetWorld()->LineTraceSingleByChannel(
+            WallCheck,
+            UpdatedComponent->GetComponentLocation(),
+            TraceEnd,
+            ECC_Visibility);
+
+        if (!bStillOnWall)
+        {
+            ExitWallRun();
+        }
+    }
+}
+
+void UMyCMC::EnterWallRun(const FHitResult& WallHit)
+{
+    WallRunNormal = WallHit.Normal;
+    bWantsToWallRun = true;
+    SetMovementMode(MOVE_Custom, static_cast<uint8>(ECustomMovementMode::WallRun));
+}
+
+void UMyCMC::ExitWallRun()
+{
+    bWantsToWallRun = false;
+    WallRunNormal = FVector::ZeroVector;
+    SetMovementMode(MOVE_Falling);
+}
+```
+
+---
+
+## Custom Network Move Data
+
+For custom data that exceeds the four CompressedFlags bits, derive `FCharacterNetworkMoveData`:
+
+```cpp
+struct FMyNetworkMoveData : public FCharacterNetworkMoveData
+{
+    FVector CustomWallNormal = FVector::ZeroVector;
+    uint8 CustomMoveMode = 0;
+
+    virtual void ClientFillNetworkMoveData(
+        const FSavedMove_Character& ClientMove,
+        ENetworkMoveType MoveType) override
+    {
+        Super::ClientFillNetworkMoveData(ClientMove, MoveType);
+
+        const FMySavedMove& MyMove = static_cast<const FMySavedMove&>(ClientMove);
+        CustomWallNormal = MyMove.SavedWallRunNormal;
+    }
+
+    virtual bool Serialize(
+        UCharacterMovementComponent& CharacterMovement,
+        FArchive& Ar,
+        UPackageMap* PackageMap,
+        ENetworkMoveType MoveType) override
+    {
+        Super::Serialize(CharacterMovement, Ar, PackageMap, MoveType);
+
+        Ar << CustomWallNormal;
+        Ar << CustomMoveMode;
+
+        return !Ar.IsError();
+    }
+};
+
+struct FMyNetworkMoveDataContainer : public FCharacterNetworkMoveDataContainer
+{
+    FMyNetworkMoveData CustomDefaultMoveData[3];
+
+    FMyNetworkMoveDataContainer()
+    {
+        NewMoveData = &CustomDefaultMoveData[0];
+        PendingMoveData = &CustomDefaultMoveData[1];
+        OldMoveData = &CustomDefaultMoveData[2];
+    }
+};
+```
+
+Register the container in the CMC constructor:
+
+```cpp
+UMyCMC::UMyCMC()
+{
+    static FMyNetworkMoveDataContainer MoveDataContainer;
+    SetNetworkMoveDataContainer(MoveDataContainer);
+}
+```
+
+**Important:** The container must be `static` or otherwise outlive the CMC. `SetNetworkMoveDataContainer` stores a pointer, not a copy.

package/skills/ue-character-movement/references/movement-pipeline.md

@@ -0,0 +1,189 @@
+# Movement Pipeline
+
+Detailed breakdown of CMC's internal movement execution, floor detection, and root motion replication.
+
+---
+
+## Phys* Function Flow
+
+```
+TickComponent(DeltaTime)
+  |
+  v
+PerformMovement(DeltaTime)           [main entry point, protected]
+  |
+  +-- ControlledCharacterMove()       [applies input acceleration]
+  |
+  v
+StartNewPhysics(DeltaTime, Iterations)
+  |
+  +-- switch (MovementMode)
+  |     |
+  |     +-- MOVE_Walking   --> PhysWalking(dt, iter)
+  |     +-- MOVE_NavWalking --> PhysNavWalking(dt, iter)
+  |     +-- MOVE_Falling    --> PhysFalling(dt, iter)
+  |     +-- MOVE_Swimming   --> PhysSwimming(dt, iter)
+  |     +-- MOVE_Flying     --> PhysFlying(dt, iter)
+  |     +-- MOVE_Custom     --> PhysCustom(dt, iter)
+  |
+  v
+[Inside each Phys* function:]
+  CalcVelocity(dt, Friction, bFluid, BrakingDecel)
+    |
+    v
+  SafeMoveUpdatedComponent(Delta, Rotation, bSweep, Hit)
+    |
+    +-- MoveUpdatedComponent()        [actual primitive move]
+    +-- ResolvePenetration()          [if overlapping after move]
+```
+
+Each `Phys*` function may iterate multiple times within a single tick (up to `MaxSimulationIterations`) when sub-stepping is required, for example when a sweep hit blocks movement partway through the delta.
+
+---
+
+## Floor Detection Chain
+
+```
+FindFloor(CapsuleLocation, OutFloorResult, bCanUseCached, DownwardSweepResult)
+  |
+  v
+ComputeFloorDist(CapsuleLocation, LineDistance, SweepDistance, OutResult, SweepRadius, DownwardSweepResult)
+  |
+  +-- 1. Capsule sweep downward (SweepDistance)
+  |       - Uses capsule shape slightly smaller than actual (SweepRadius)
+  |       - Tests bBlockingHit and surface angle vs WalkableFloorZ
+  |
+  +-- 2. Line trace downward (LineDistance)
+  |       - From capsule center to below capsule bottom
+  |       - Validates the sweep result at the exact contact point
+  |       - Catches edges where the sweep capsule might miss
+  |
+  v
+FFindFloorResult populated:
+  bBlockingHit   = sweep found something
+  bWalkableFloor = surface normal Z >= WalkableFloorZ
+  bLineTrace     = result came from line trace fallback
+  FloorDist      = distance from capsule bottom to floor (sweep)
+  LineDist       = distance from line trace
+  HitResult      = full FHitResult
+```
+
+`IsWalkableFloor()` returns `true` only when both `bBlockingHit` and `bWalkableFloor` are set. A blocking hit on a steep surface (above `WalkableFloorAngle`) returns `bBlockingHit = true` but `bWalkableFloor = false`.
+
+---
+
+## Step-Up Logic
+
+When `PhysWalking` encounters a blocking hit during `SafeMoveUpdatedComponent`, it attempts a step-up if the obstacle height is within `MaxStepHeight`:
+
+```
+1. Hit blocking surface during horizontal move
+2. Check obstacle height <= MaxStepHeight
+3. Move capsule UP by MaxStepHeight
+4. Move capsule FORWARD by remaining Delta
+5. Move capsule DOWN to find new floor
+6. If new floor is walkable:
+     - Accept the step-up position
+     - Continue walking
+7. If no walkable floor found or obstacle too tall:
+     - Revert to pre-step-up position
+     - Slide along the wall or transition to falling
+```
+
+Step-up only triggers during walking mode. Characters in `MOVE_Falling` do not step up -- they slide along surfaces.
+
+---
+
+## PhysWalking Flow
+
+```
+PhysWalking(deltaTime, Iterations)
+  |
+  +-- CalcVelocity(dt, GroundFriction, false, BrakingDecelerationWalking)
+  |
+  +-- MoveAlongFloor(Velocity * dt, Hit)
+  |     |
+  |     +-- SafeMoveUpdatedComponent(Delta, Rotation, true, Hit)
+  |     +-- If blocked: attempt SlideAlongSurface or StepUp
+  |
+  +-- FindFloor(NewLocation, FloorResult, false)
+  |     |
+  |     +-- If walkable floor found: maintain MOVE_Walking
+  |     +-- If floor lost: SetMovementMode(MOVE_Falling)
+  |     +-- If floor too steep: slide down or fall
+  |
+  +-- AdjustFloorHeight()
+        |
+        +-- Snap capsule to floor within tolerance
+        +-- Prevents floating or sinking between frames
+```
+
+The `Iterations` parameter limits how many sub-steps occur if the character hits multiple surfaces in one frame. Each slide or step-up consumes an iteration.
+
+---
+
+## PhysFalling Flow
+
+```
+PhysFalling(deltaTime, Iterations)
+  |
+  +-- GetFallingLateralAcceleration()
+  |     +-- Applies AirControl to lateral input
+  |     +-- Scaled by GetAirControl() (0-1 range)
+  |
+  +-- CalcVelocity(dt, FallingLateralFriction, false, BrakingDecelerationFalling)
+  |
+  +-- Apply gravity: Velocity.Z += GetGravityZ() * dt
+  |
+  +-- SafeMoveUpdatedComponent(Velocity * dt, Rotation, true, Hit)
+  |     |
+  |     +-- If hit floor:
+  |     |     +-- ProcessLanded(Hit)
+  |     |     +-- FindFloor check
+  |     |     +-- If walkable: SetMovementMode(MOVE_Walking)
+  |     |     +-- ACharacter::Landed(Hit) called
+  |     |
+  |     +-- If hit wall:
+  |           +-- HandleImpact(Hit)
+  |           +-- SlideAlongSurface(Delta, 1-Hit.Time, Hit.Normal, Hit)
+  |
+  +-- If no hit: continue falling next frame
+```
+
+Air control: `AirControl` (0-1) scales the player's lateral input while falling. At 0, the character follows a pure ballistic arc. At 1, the character has full lateral control in air (feels unrealistic but common in platformers).
+
+---
+
+## Root Motion Replication
+
+Root motion from `FRootMotionSource` replicates through the CMC's network prediction system.
+
+```
+[Server]
+  ApplyRootMotionSource(Source)
+    |
+    +-- Source added to CurrentRootMotion.RootMotionSources
+    +-- Each tick: accumulated into FRootMotionMovementParams
+    +-- Applied during PerformMovement before physics
+    +-- Included in server move response
+
+[Client - Autonomous Proxy]
+  Receives source via replication
+    |
+    +-- Applies locally for prediction
+    +-- Corrections handled through normal FSavedMove replay
+    +-- Source duration tracked independently
+
+[Client - Simulated Proxy]
+  Receives replicated movement result
+    |
+    +-- Smoothing applied via NetworkSmoothingMode
+    +-- Root motion baked into final position/velocity
+```
+
+Key points:
+- Root motion sources with `Duration < 0` run infinitely until explicitly removed with `RemoveRootMotionSource(InstanceName)`
+- `AccumulateMode::Override` replaces velocity from other sources at the same or lower priority
+- `AccumulateMode::Additive` stacks on top of existing velocity
+- Animation root motion (`FRootMotionMovementParams` from `UAnimMontage`) takes a separate path: it is extracted from `UAnimInstance` each tick in `TickComponent`, accumulated in `RootMotionParams`, then applied in `PerformMovement`. This path is distinct from `FRootMotionSource` and is handled by the animation system, not the source list.
+- Both paths merge in `PerformMovement` where the final delta is applied