1
// ===== AnimInstance：C++ 动画逻辑的核心 =====
2
// AnimInstance 是动画蓝图的 C++ 父类
3
// 它不直接操作骨骼——它只负责为动画蓝图提供"决策数据"
4

5
UCLASS()
6
class UMyAnimInstance : public UAnimInstance
7
{
8
    GENERATED_BODY()
9

10
public:
11
    // ---------- 动画蓝图可读取的变量 ----------
12
    // 这些变量由 C++ 计算，AnimBP 的 Event Graph 读取后驱动状态机
13

14
    UPROPERTY(BlueprintReadOnly, Category = "Locomotion")
15
    float Speed;
16

17
    UPROPERTY(BlueprintReadOnly, Category = "Locomotion")
18
    float Direction;          // 移动方向角度（-180 ~ 180）
19

20
    UPROPERTY(BlueprintReadOnly, Category = "Locomotion")
21
    bool bIsInAir;
22

23
    UPROPERTY(BlueprintReadOnly, Category = "Locomotion")
24
    bool bIsCrouching;
25

26
    UPROPERTY(BlueprintReadOnly, Category = "Combat")
27
    bool bIsAiming;
28

29
    UPROPERTY(BlueprintReadOnly, Category = "Combat")
30
    float AimPitch;           // 瞄准俯仰角——用于 Aim Offset
31

32
    // ---------- 核心更新函数 ----------
33
    // NativeUpdateAnimation：每帧由引擎自动调用（渲染前）
34
    virtual void NativeUpdateAnimation(float DeltaSeconds) override
35
    {
36
        Super::NativeUpdateAnimation(DeltaSeconds);
37

38
        // 获取当前 Pawn
39
        APawn* OwnerPawn = TryGetPawnOwner();
40
        if (!OwnerPawn) return;
41

42
        // 计算速度和方向
43
        FVector Velocity = OwnerPawn->GetVelocity();
44
        Speed = Velocity.Size2D();                          // 水平速度
45
        // ⚠️ 注意函数名——UAnimInstance 基类已有 CalculateDirection()
46
        //    自定义函数用不同名称避免 shadow 基类的权威数学接口
47
        Direction = GetMovementDirectionAngle(Velocity, OwnerPawn->GetActorRotation());
48

49
        // 状态标志
50
        ACharacter* Character = Cast<ACharacter>(OwnerPawn);
51
        if (Character)
52
        {
53
            bIsInAir = Character->GetCharacterMovement()->IsFalling();
54
            bIsCrouching = Character->GetCharacterMovement()->IsCrouching();
55
        }
56
    }
57

58
    // NativeInitializeAnimation：动画实例初始化时调用一次
59
    virtual void NativeInitializeAnimation() override
60
    {
61
        Super::NativeInitializeAnimation();
62
        // 初始化外部引用等
63
    }
64

65
    // NativeThreadSafeUpdateAnimation：在工作线程上更新（性能优化）
66
    virtual void NativeThreadSafeUpdateAnimation(float DeltaSeconds) override
67
    {
68
        Super::NativeThreadSafeUpdateAnimation(DeltaSeconds);
69
        // ⚠️ 这里不能访问 World、Controller、GameMode 等非线程安全的对象！
70
        // 只做纯数学计算——更新 Speed、Direction 等不涉及 UObject 访问的值
71
    }
72

73
protected:
74
    // 计算移动方向（相对于角色朝向的角度）
75
    // ⚠️ 函数名不能叫 CalculateDirection——UAnimInstance 基类已有此函数
76
    //    同签名会 shadow 引擎内置的权威数学接口，导致运行期调用紊乱
77
    float GetMovementDirectionAngle(const FVector& Velocity, const FRotator& BaseRotation) const
78
    {
79
        if (Velocity.IsNearlyZero()) return 0.0f;
80

81
        FMatrix RotMatrix = FRotationMatrix(BaseRotation);
82
        FVector Forward = RotMatrix.GetScaledAxis(EAxis::X);
83
        FVector Right = RotMatrix.GetScaledAxis(EAxis::Y);
84

85
        float ForwardSpeed = FVector::DotProduct(Velocity, Forward);
86
        float RightSpeed = FVector::DotProduct(Velocity, Right);
87

88
        return FMath::RadiansToDegrees(FMath::Atan2(RightSpeed, ForwardSpeed));
89
    }
90
};

1
// ===== 状态机：定义动画状态及切换条件 =====
2
//
3
// 在 AnimBlueprint 的 AnimGraph 中可视化编辑：
4
//
5
// 典型运动状态机：
6
//
7
//   [Idle] ←──→ [Walk] ←──→ [Run]
8
//     ↑            ↑           ↑
9
//     └──── JumpStart → [Fall] → JumpLand ──┘
10
//
11
// 状态切换规则（Transition Rule）：
12
//   Idle → Walk：  Speed > 10
13
//   Walk → Run：   Speed > 300
14
//   Run → Walk：   Speed < 250
15
//   Walk → Idle：  Speed < 5
16
//   任意 → Fall：  bIsInAir == true
17
//
18
// Transition 的关键属性：
19
// - BlendDuration：两个动画之间的混合时间（秒）
20
// - BlendMode：Standard / Inertialization（UE5 新特性）
21
// - Automatic Rule Based on Sequence Player in State：自动根据动画长度过渡
22

23
// ===== C++ 中触发状态切换 =====
24
void UMyAnimInstance::SetMovementState(EMovementState NewState)
25
{
26
    // 直接设置枚举——AnimBP 状态机的 Transition Rule 读取这个值
27
    CurrentMovementState = NewState;
28
}

1
// ===== BlendSpace：基于连续参数的动画混合 =====
2
//
3
// BlendSpace 1D：一个参数轴
4
//   例：Speed(0 → 600) 映射到 Idle → Walk → Run
5
//   X 轴 = Speed，每个采样点放一个动画：
6
//     Speed=0   → Idle 动画
7
//     Speed=150 → Walk 动画
8
//     Speed=400 → Run 动画
9
//   Speed=200 时：Walk 和 Run 各 50% 混合
10
//
11
// BlendSpace 2D：两个参数轴
12
//   例：Speed(0→600) × Direction(-180→180)
13
//   X 轴 = Direction（前后左右），Y 轴 = Speed（快慢）
14
//   每个格子放一个动画：前向行走、左向行走、后退行走...
15
//   任意角度和速度自动混合相邻动画
16
//
17
// BlendSpace 的关键属性：
18
// - Target Weight Interpolation Speed Per Second：平滑过渡速度
19
// - Sample Interpolation：采样点之间的插值方式（Linear / Cubic）
20
// - Grid Division：将参数空间分成多少格（格子越多越平滑，越多越贵）
21

22
// ===== C++ 中设置 BlendSpace 参数 =====
23
void UMyAnimInstance::UpdateBlendSpaceParams()
24
{
25
    // 这些变量直接作为 BlendSpace 的输入参数
26
    // AnimBP 的 AnimGraph 中会有节点读取它们
27
    Speed = GetOwnerVelocity2D();
28
    Direction = GetMovementDirectionAngle();
29

30
    // BlendSpace 内部自动根据 (Speed, Direction) 找到最近的采样动画并混合
31
}

1
// ===== Aim Offset：在基础动画上叠加瞄准偏移 =====
2
//
3
// Aim Offset 是一种特殊的 BlendSpace——叠加式混合
4
// 基础动画（如步枪持握 Idle） + Aim Offset（上下左右瞄准偏移）
5
// 结果：角色身体保持 Idle，上半身随瞄准方向旋转
6

7
// 典型的 Aim Offset 参数：
8
//   Pitch：-90°（下）→ 90°（上）
9
//   Yaw：-90°（左）→ 90°（右）
10

11
void UMyAnimInstance::UpdateAimOffset()
12
{
13
    if (APlayerController* PC = Cast<APlayerController>(
14
            TryGetPawnOwner()->GetController()))
15
    {
16
        // 从 Controller 的 Aim Rotation 计算 Pitch 和 Yaw
17
        FRotator AimRot = PC->GetControlRotation();
18
        FRotator ActorRot = TryGetPawnOwner()->GetActorRotation();
19

20
        FRotator Delta = (AimRot - ActorRot).GetNormalized();
21
        AimPitch = FMath::Clamp(Delta.Pitch, -90.0f, 90.0f);
22
        AimYaw = FMath::Clamp(Delta.Yaw, -90.0f, 90.0f);
23
    }
24
}

1
// ===== IK 的本质：从末端位置反算中间关节 =====
2
//
3
// Forward Kinematics（FK）：肩 → 肘 → 手（已知关节角度 → 求手在哪）
4
// Inverse Kinematics（IK）：手在 (x,y,z) → 肩和肘该什么角度？
5
//
6
// UE 提供三种 IK 解算器（都在 AnimBP 的 AnimGraph 中使用）：
7

8
// ① Two Bone IK —— 最常用（两段骨骼：大腿→小腿→脚）
9
//    - 给定末端位置（脚底），反算两个关节的角度
10
//    - 适用：脚部贴地（Foot IK）、手部抓取
11
//    - 性能：极轻量——解析解，不迭代
12
//    - 限制：只能处理两段骨骼链
13

14
// ② CCD IK（Cyclic Coordinate Descent）—— 多段骨骼
15
//    - 从末端向根逐段迭代优化
16
//    - 适用：长骨骼链（尾巴、触手、脖子）
17
//    - 性能：迭代次数决定精度（通常 5~10 次）
18
//    - 局限：可能产生不自然的"拧麻花"姿态
19

20
// ③ FABRIK（Forward And Backward Reaching IK）—— 自然姿态
21
//    - 从末端向根 + 从根向末端双向迭代
22
//    - 适用：全身 IK（手摸墙、身体倾斜）
23
//    - 性能：双向迭代比 CCD 稍贵
24
//    - 优势：姿态比 CCD 更自然——没有"拧麻花"问题

1
// ===== Foot IK：让角色脚部适应不平坦地形 =====
2
//
3
// 问题：坡度上，一只脚悬空
4
// 解决：从脚底向下做射线检测 → 找到地面高度 → IK 将脚移到地面
5

6
UCLASS()
7
class UMyAnimInstance : public UAnimInstance
8
{
9
    GENERATED_BODY()
10

11
public:
12
    // ---------- Foot IK 数据 ----------
13
    UPROPERTY(BlueprintReadOnly, Category = "IK")
14
    FVector LeftFootIKLocation;     // 左脚 IK 目标位置
15

16
    UPROPERTY(BlueprintReadOnly, Category = "IK")
17
    FRotator LeftFootIKRotation;    // 左脚 IK 目标旋转（匹配地面法线）
18

19
    UPROPERTY(BlueprintReadOnly, Category = "IK")
20
    float LeftFootIKAlpha;          // IK 权重（行走时 ≈1，跳跃时 ≈0）
21

22
    UPROPERTY(BlueprintReadOnly, Category = "IK")
23
    FVector RightFootIKLocation;
24

25
    UPROPERTY(BlueprintReadOnly, Category = "IK")
26
    FRotator RightFootIKRotation;
27

28
    UPROPERTY(BlueprintReadOnly, Category = "IK")
29
    float RightFootIKAlpha;
30

31
    // ---------- Update Foot IK ----------
32
    virtual void NativeUpdateAnimation(float DeltaSeconds) override
33
    {
34
        Super::NativeUpdateAnimation(DeltaSeconds);
35
        UpdateFootIK(DeltaSeconds);
36
    }
37

38
    void UpdateFootIK(float DeltaSeconds)
39
    {
40
        ACharacter* Character = Cast<ACharacter>(TryGetPawnOwner());
41
        if (!Character) return;
42

43
        // 获取脚的骨骼位置（FK 位置）
44
        USkeletalMeshComponent* Mesh = Character->GetMesh();
45
        FVector LeftFootBone = Mesh->GetSocketLocation(TEXT("foot_l"));
46
        FVector RightFootBone = Mesh->GetSocketLocation(TEXT("foot_r"));
47

48
        // 对每只脚做射线检测——找到地面
49
        float TraceLength = 60.0f;  // 脚踝以下的最大搜索距离
50
        FVector TraceStart_L = LeftFootBone + FVector(0, 0, 30);  // 从脚踝上方开始
51
        FVector TraceEnd_L = LeftFootBone - FVector(0, 0, TraceLength);
52

53
        FHitResult Hit_L;
54
        if (GetWorld()->LineTraceSingleByChannel(Hit_L, TraceStart_L, TraceEnd_L,
55
                ECC_Visibility))
56
        {
57
            // ⚠️ 致命陷阱：Hit_L.Location 是世界绝对坐标！
58
            //    AnimGraph 的 TwoBoneIK 节点默认接收组件局部空间（Component Space）坐标，
59
            //    或者相对于脚踝骨骼的位移偏移量。如果直接把世界坐标丢给 IK 节点——
60
            //    角色离开世界原点后双脚会被拉伸到数万单位外的世界坐标点，产生恐怖畸变！
61
            // ✓ 标准做法：用 InverseTransformPosition 转回 Mesh 的组件局部空间
62
            FVector WorldHitLocation = Hit_L.Location;
63
            LeftFootIKLocation = Mesh->GetComponentTransform()
64
                                     .InverseTransformPosition(WorldHitLocation);
65

66
            // IK 旋转同样需要从世界空间转到组件局部空间
67
            FRotator WorldNormalRotation = FRotationMatrix::MakeFromZ(
68
                Hit_L.Normal).Rotator();
69
            LeftFootIKRotation = (Mesh->GetComponentQuat().Inverse() *
70
                                  WorldNormalRotation.Quaternion()).Rotator();
71

72
            LeftFootIKAlpha = 1.0f;  // 完全启用 IK
73
        }
74
        else
75
        {
76
            // 脚悬空——禁用 IK（跳跃/下落时）
77
            LeftFootIKAlpha = 0.0f;
78
        }
79

80
        // 右脚步骤同上...
81
        FVector TraceStart_R = RightFootBone + FVector(0, 0, 30);
82
        FVector TraceEnd_R = RightFootBone - FVector(0, 0, TraceLength);
83
        FHitResult Hit_R;
84
        if (GetWorld()->LineTraceSingleByChannel(Hit_R, TraceStart_R, TraceEnd_R,
85
                ECC_Visibility))
86
        {
87
            FVector WorldHitLocation = Hit_R.Location;
88
            RightFootIKLocation = Mesh->GetComponentTransform()
89
                                      .InverseTransformPosition(WorldHitLocation);
90

91
            FRotator WorldNormalRotation = FRotationMatrix::MakeFromZ(
92
                Hit_R.Normal).Rotator();
93
            RightFootIKRotation = (Mesh->GetComponentQuat().Inverse() *
94
                                   WorldNormalRotation.Quaternion()).Rotator();
95

96
            RightFootIKAlpha = 1.0f;
97
        }
98
        else
99
        {
100
            RightFootIKAlpha = 0.0f;
101
        }
102

103
        // 平滑过渡——避免 IK 开关时的"弹跳"
104
        float IKInterpSpeed = 10.0f;
105
        LeftFootIKAlpha = FMath::FInterpTo(LeftFootIKAlpha,
106
            LeftFootIKAlpha > 0.5f ? 1.0f : 0.0f, DeltaSeconds, IKInterpSpeed);
107
        RightFootIKAlpha = FMath::FInterpTo(RightFootIKAlpha,
108
            RightFootIKAlpha > 0.5f ? 1.0f : 0.0f, DeltaSeconds, IKInterpSpeed);
109
    }
110
};

1
// ===== AnimNotify：动画播放到特定帧时触发一次 =====
2
//
3
// 典型用途：
4
// - 脚步声：脚落地的那一帧 → 播放脚步声 + 生成脚印贴花
5
// - 攻击判定：武器挥到最前方的那一帧 → 检测碰撞
6
// - 投掷物生成：手举到最高点的那一帧 → 生成投掷物
7
// - 音效触发：武器出鞘的那一帧 → 播放拔剑音效
8

9
// ---------- 自定义 AnimNotify（C++） ----------
10
UCLASS()
11
class UAnimNotify_Footstep : public UAnimNotify
12
{
13
    GENERATED_BODY()
14

15
public:
16
    virtual void Notify(USkeletalMeshComponent* MeshComp,
17
                        UAnimSequenceBase* Animation,
18
                        const FAnimNotifyEventReference& EventReference) override
19
    {
20
        Super::Notify(MeshComp, Animation, EventReference);
21

22
        if (!MeshComp) return;
23

24
        AActor* Owner = MeshComp->GetOwner();
25
        if (!Owner) return;
26

27
        // 播放脚步声
28
        UGameplayStatics::PlaySoundAtLocation(
29
            Owner->GetWorld(),
30
            FootstepSound,
31
            Owner->GetActorLocation());
32

33
        // 根据脚下的物理材质选择不同的音效
34
        // （需要 PhysicalMaterial 系统配合——见 Ch17）
35
    }
36

37
    UPROPERTY(EditAnywhere, Category = "Footstep")
38
    TObjectPtr<USoundBase> FootstepSound;
39
};
40

41
// ---------- 自定义 AnimNotify：攻击判定 ----------
42
UCLASS()
43
class UAnimNotify_MeleeTrace : public UAnimNotify
44
{
45
    GENERATED_BODY()
46

47
public:
48
    virtual void Notify(USkeletalMeshComponent* MeshComp,
49
                        UAnimSequenceBase* Animation,
50
                        const FAnimNotifyEventReference& EventReference) override
51
    {
52
        Super::Notify(MeshComp, Animation, EventReference);
53

54
        AActor* Owner = MeshComp->GetOwner();
55
        if (!Owner) return;
56

57
        // 从武器的 Socket 位置做碰撞检测
58
        FVector TraceStart = MeshComp->GetSocketLocation(TEXT("weapon_tip_start"));
59
        FVector TraceEnd = MeshComp->GetSocketLocation(TEXT("weapon_tip_end"));
60

61
        TArray<FHitResult> Hits;
62
        FCollisionQueryParams Params;
63
        Params.AddIgnoredActor(Owner);
64

65
        if (Owner->GetWorld()->SweepMultiByChannel(
66
                Hits, TraceStart, TraceEnd, FQuat::Identity,
67
                ECC_GameTraceChannel1, FCollisionShape::MakeSphere(20.0f), Params))
68
        {
69
            for (const FHitResult& Hit : Hits)
70
            {
71
                if (AActor* HitActor = Hit.GetActor())
72
                {
73
                    UGameplayStatics::ApplyDamage(HitActor, Damage,
74
                        Owner->GetInstigatorController(), Owner,
75
                        UDamageType::StaticClass());
76
                }
77
            }
78
        }
79
    }
80

81
    UPROPERTY(EditAnywhere, Category = "Melee")
82
    float Damage = 25.0f;
83
};

1
// ===== AnimNotifyState：有 Begin / Tick / End 的持续事件 =====
2
//
3
// 典型用途：
4
// - 持续攻击判定（武器挥砍的整个弧线期间都检测碰撞）
5
// - 无敌时间窗口（翻滚动画期间不受伤害）
6
// - 蒙太奇锁定（技能动画期间禁止移动输入）
7

8
UCLASS()
9
class UAnimNotifyState_InvincibleWindow : public UAnimNotifyState
10
{
11
    GENERATED_BODY()
12

13
public:
14
    virtual void NotifyBegin(USkeletalMeshComponent* MeshComp,
15
        UAnimSequenceBase* Animation, float TotalDuration,
16
        const FAnimNotifyEventReference& EventReference) override
17
    {
18
        // 无敌开始
19
        if (AActor* Owner = MeshComp->GetOwner())
20
        {
21
            // 例如：设置一个 GameplayTag "Status.Invincible"
22
            UE_LOG(LogAnim, Log, TEXT("%s 进入无敌"), *Owner->GetName());
23
        }
24
    }
25

26
    virtual void NotifyEnd(USkeletalMeshComponent* MeshComp,
27
        UAnimSequenceBase* Animation,
28
        const FAnimNotifyEventReference& EventReference) override
29
    {
30
        // 无敌结束
31
        if (AActor* Owner = MeshComp->GetOwner())
32
        {
33
            UE_LOG(LogAnim, Log, TEXT("%s 退出无敌"), *Owner->GetName());
34
        }
35
    }
36

37
    virtual void NotifyTick(USkeletalMeshComponent* MeshComp,
38
        UAnimSequenceBase* Animation, float FrameDeltaTime,
39
        const FAnimNotifyEventReference& EventReference) override
40
    {
41
        // 每帧调用——可以在这里做持续碰撞检测
42
    }
43
};

1
// ===== Montage：多段动画的组合 + Slot 分层播放 =====
2
//
3
// Montage 解决的核心问题：
4
//   "角色在跑步，但我想播放'左手换弹夹'动画——只影响上半身"
5
//
6
// Slot（槽位）：
7
//   每个 Montage 被分配到特定的 Slot
8
//   不同 Slot 覆盖不同的骨骼区域：
9
//     - DefaultSlot：全身（默认——会覆盖基础运动）
10
//     - UpperBody：上半身（保留下半身的跑步动画）
11
//     - FullBody：全身（高优先级——覆盖一切）
12
//
13
// 典型的 Slot 配置（在 AnimBP 的 AnimGraph 中设置）：
14
//   DefaultSlot → 全身（运动动画：Idle/Walk/Run）
15
//   UpperBody  → 脊柱以上（换弹、瞄准偏移、挥手）
16
//   FullBody   → 全身（技能动画、死亡动画——最高优先级）
17

18
// ---------- C++ 播放 Montage ----------
19
UCLASS()
20
class UMyAnimInstance : public UAnimInstance
21
{
22
    GENERATED_BODY()
23

24
public:
25
    // 播放一次攻击动画
26
    float PlayAttackMontage(UAnimMontage* Montage)
27
    {
28
        if (!Montage) return 0.0f;
29

30
        // Montage_Play 的返回值 = Montage 的总时长（秒）
31
        float Duration = Montage_Play(
32
            Montage,
33
            1.0f,                    // PlayRate（1.0 = 正常速度）
34
            EMontagePlayReturnType::MontageLength,  // 返回总时长
35
            0.0f,                    // StartingPosition（从头开始）
36
            true                     // bStopAllMontages（停止其他 Montage）
37
        );
38

39
        return Duration;
40
    }
41

42
    // 播放上半身换弹动画（不影响跑步）
43
    void PlayReloadMontage_UpperBody(UAnimMontage* Montage)
44
    {
45
        if (!Montage) return;
46

47
        // 使用 FName Slot 指定到上半身槽位
48
        Montage_Play(
49
            Montage,
50
            1.0f,
51
            EMontagePlayReturnType::Duration,
52
            0.0f,
53
            false  // bStopAllMontages = false —— 不停止下半身的跑步动画
54
        );
55
    }
56

57
    // 停止 Montage
58
    void StopCurrentMontage(float BlendOutTime = 0.25f)
59
    {
60
        Montage_Stop(BlendOutTime);  // 0.25s 淡出
61
    }
62

63
    // 跳转到 Montage 的特定 Section
64
    void JumpToMontageSection(FName SectionName)
65
    {
66
        Montage_JumpToSection(SectionName);
67
        // Montage 中的每个 Section 有一个标签：
68
        // "Start" → "Loop" → "End"
69
        // 例如：攻击动画的"蓄力"→"挥砍"→"收招"
70
        // 可以从任意时刻跳转到特定 Section
71
    }
72

73
    // 检查是否正在播放特定 Montage
74
    bool IsPlayingMontage(UAnimMontage* Montage) const
75
    {
76
        return Montage_IsPlaying(Montage);
77
    }
78
};

1
// ===== Montage Section：动画的逻辑片段 =====
2
//
3
// 一个 Montage 被划分为多个 Section：
4
//
5
// [Section: Charge] ──→ [Section: Swing] ──→ [Section: Recovery]
6
//      蓄力                 挥砍                   收招
7
//
8
// 使用场景：
9
//   - 蓄力攻击：在 Charge 阶段循环 → 按键释放 → JumpTo Swing
10
//   - 连击：Swing1 → 在特定帧检测输入 → 如果有 → JumpTo Swing2
11
//   - 受击：正常状态 → 被击中 → JumpTo HitReaction Section
12

13
// ===== Blend Out：Montage 的淡出机制 =====
14
//
15
// Montage 有两种结束方式：
16
// 1. 自然结束：播放到最后一帧 → 自动退出
17
// 2. 提前中断：被打断（受击/死亡）→ Blend Out
18
//
19
// Blend Out Trigger Time：在这个时间点之后，Montage 允许被 Blend Out
20
// Blend Out Time：淡出持续时间（秒）
21
//   → 例如：攻击 Montage 的 BlendOutTime = 0.15s
22
//     受击时，手臂不会"瞬间弹回"Idle——而是 0.15s 平滑回到 Idle

1
// ===== Root Motion：让动画数据驱动角色移动 =====
2
//
3
// 常规移动：代码控制位置 + 动画配合播放
4
//   → MoveComponent 告诉角色"向前走 100 单位"
5
//   → 动画系统播放"走路动画"（原地踏步）
6
//   → 脚部滑动问题需要 Foot IK 补偿
7
//
8
// Root Motion：动画数据包含根骨骼的位移
9
//   → 动画师制作的动画中，根骨骼真正在移动
10
//   → 引擎提取根骨骼的运动数据
11
//   → 将这些数据应用到角色的实际位置
12
//   → 动画和移动完美同步——无脚部滑动
13

14
// ---------- 启用 Root Motion ----------
15
// 步骤 1：在 Montage/Animation 资产中启用 Root Motion
16
//   资产详情 → Root Motion → Enable Root Motion ✓
17
//   Root Motion Root Lock → RefPose（推荐）
18
//
19
// 步骤 2：在 Character Movement 中处理 Root Motion
20
//   通常由 ACharacter 的移动组件自动处理
21

22
// ---------- C++ 中提取 Root Motion 数据 ----------
23
void UMyAnimInstance::ExtractRootMotion()
24
{
25
    // 获取当前帧的 Root Motion 变换
26
    if (UCharacterMovementComponent* MoveComp =
27
            Cast<UCharacterMovementComponent>(
28
                TryGetPawnOwner()->GetMovementComponent()))
29
    {
30
        // bAllowPhysicsRotationDuringAnimRootMotion
31
        // = true → Root Motion 可以旋转角色（翻滚、转向攻击）
32
    }
33
}
34

35
// ---------- 常见 Root Motion 使用场景 ----------
36
// ① 翻滚/闪避：动画中的位移数据精确对应闪避距离
37
// ② 终结技：动画中的角色会靠近目标——Root Motion 让角色自动移动
38
// ③ 攀爬翻越：动画包含"手抓墙→身体上翻→站稳"——Root Motion 全部搞定
39
// ④ 网络友好：Root Motion 位移在服务器上复现——移动数据一致

1
// ===== Root Motion 陷阱 =====
2
//
3
// 问题 1：Root Motion 锁定移动方向
4
//   动画中的移动方向是固定的（动画师制作的）
5
//   如果角色朝向不对——Root Motion 会朝着错误方向移动
6
//   解决：Warping / Motion Warping（见 16.7）
7
//
8
// 问题 2：Root Motion 与代码移动的冲突
9
//   同一帧既有代码移动（AddMovementInput）又有 Root Motion
10
//   → 移动抖动或位移叠加错误
11
//   解决：使用 Root Motion 时禁止代码移动输入
12
//
13
// 问题 3：网络复制的精度
14
//   Root Motion 的位移在服务器和客户端可能有微小差异
15
//   长时间累积 → 位置不一致
16
//   解决：定期服务器校正 + 使用 Root Motion 源数据而非最终位移

1
// ===== Motion Warping：让动画自动适应目标位置 =====
2
//
3
// 传统问题：
4
//   "翻越掩体"的动画是固定的——从 A 点起跳，B 点落地
5
//   但掩体高度可能不同——固定的动画会导致手没抓到掩体边缘
6
//
7
// Motion Warping 的解决思路：
8
//   在动画中标记"关键帧"（Warp Target）
9
//   引擎在运行时将动画"扭曲"——让关键帧精确匹配目标位置
10
//
11
// 例：翻越掩体动画
12
//   Warp Target 1：手抓掩体边缘的那一帧 → 扭曲动画使手精确碰到掩体
13
//   Warp Target 2：脚落地的帧 → 扭曲使脚精确落到掩体后方地面上
14
//
15
// 结果：同一个动画适配所有掩体高度——不需要每种掩体做一个动画！
16

17
// ---------- C++ 中触发 Motion Warping ----------
18
UCLASS()
19
class AMyCharacter : public ACharacter
20
{
21
    GENERATED_BODY()
22

23
public:
24
    // 翻越掩体
25
    void VaultOverObstacle(FVector ObstacleLocation, float ObstacleHeight)
26
    {
27
        if (!VaultMontage) return;
28

29
        // ⚠️ 注意：
30
        // ① FMotionWarpingTarget 内部使用统一的 FTransform——没有独立的 .Location / .Rotation 属性
31
        // ② 官方 Motion Warping 框架中不存在 UAbilityTask_MotionWarping——
32
        //    如果需要与 GAS 协同，需自行编写 AbilityTask 封装
33

34
        // 设置 Warp Target：使用组件提供的专用工厂 API
35
        FVector TargetLocation = ObstacleLocation + FVector(0, 0, ObstacleHeight);
36
        FRotator TargetRotation = GetActorRotation();
37

38
        if (UMotionWarpingComponent* WarpComp =
39
                FindComponentByClass<UMotionWarpingComponent>())
40
        {
41
            // ✓ 正确 API：AddOrUpdateWarpTargetFromLocationAndRotation
42
            //    内部会将 FName + FVector + FRotator 组装为 FTransform 并存入 Warp Target 列表
43
            WarpComp->AddOrUpdateWarpTargetFromLocationAndRotation(
44
                FName(TEXT("VaultTarget")),  // 匹配动画中 Notify 的 Warp Target Name
45
                TargetLocation,
46
                TargetRotation
47
            );
48
        }
49

50
        // 播放 Montage（引擎在 Warp Target 对应的帧自动扭曲根骨骼位移）
51
        PlayAnimMontage(VaultMontage);
52
    }
53

54
protected:
55
    UPROPERTY(EditDefaultsOnly, Category = "Animation")
56
    TObjectPtr<UAnimMontage> VaultMontage;
57
};
58

59
// ===== Motion Warping 的关键概念 =====
60
//
61
// Warp Target Name：动画中预先定义的关键帧标签
62
//   动画师在 Montage 中添加 Notify "MotionWarping Target = VaultTarget"
63
//
64
// Warp Target 类型：
65
//   - Location Only：只扭曲位移——适用翻越掩体
66
//   - Rotation Only：只扭曲旋转——适用转向攻击
67
//   - Location + Rotation：同时扭曲——适用滑铲
68
//
69
// MotionWarpingComponent：
70
//   挂载在 Character 上的组件
71
//   管理所有活跃的 Warp Target
72
//   每帧计算扭曲变换并应用到 Root Motion

1
// ===== 完整 AnimInstance：运动 + 战斗 + IK + Montage =====
2
UCLASS()
3
class UCharacterAnimInstance : public UAnimInstance
4
{
5
    GENERATED_BODY()
6

7
public:
8
    // ---------- 运动数据 ----------
9
    UPROPERTY(BlueprintReadOnly, Category = "Locomotion")
10
    float Speed;
11

12
    UPROPERTY(BlueprintReadOnly, Category = "Locomotion")
13
    float Direction;
14

15
    UPROPERTY(BlueprintReadOnly, Category = "Locomotion")
16
    bool bIsInAir;
17

18
    UPROPERTY(BlueprintReadOnly, Category = "Locomotion")
19
    bool bIsCrouching;
20

21
    UPROPERTY(BlueprintReadOnly, Category = "Locomotion")
22
    float LeanAmount;  // 转弯时的身体倾斜（通过加速度计算）
23

24
    // ---------- 瞄准数据 ----------
25
    UPROPERTY(BlueprintReadOnly, Category = "Aim")
26
    float AimPitch;
27

28
    UPROPERTY(BlueprintReadOnly, Category = "Aim")
29
    float AimYaw;
30

31
    UPROPERTY(BlueprintReadOnly, Category = "Aim")
32
    bool bIsAiming;
33

34
    // ---------- 战斗数据 ----------
35
    UPROPERTY(BlueprintReadOnly, Category = "Combat")
36
    bool bIsAttacking;
37

38
    UPROPERTY(BlueprintReadOnly, Category = "Combat")
39
    EWeaponType CurrentWeaponType;  // Unarmed / Pistol / Rifle / Melee
40

41
    // ---------- 核心更新 ----------
42
    virtual void NativeUpdateAnimation(float DeltaSeconds) override
43
    {
44
        Super::NativeUpdateAnimation(DeltaSeconds);
45

46
        ACharacter* Character = Cast<ACharacter>(TryGetPawnOwner());
47
        if (!Character) return;
48

49
        // ---- 运动更新 ----
50
        FVector Velocity = Character->GetVelocity();
51
        Speed = Velocity.Size2D();
52
        Direction = GetMovementDirectionAngle(Velocity, Character->GetActorRotation());
53

54
        // ✓ 直接赋值给类成员变量——不是声明局部变量！否则 CalculateLean 中的 MoveComp 是 nullptr
55
        MoveComp = Character->GetCharacterMovement();
56
        bIsInAir = MoveComp->IsFalling();
57
        bIsCrouching = MoveComp->IsCrouching();
58

59
        // 倾斜计算——加速度方向
60
        FVector Acceleration = MoveComp->GetCurrentAcceleration();
61
        if (!Acceleration.IsNearlyZero())
62
        {
63
            LeanAmount = FMath::FInterpTo(LeanAmount,
64
                CalculateLean(Acceleration, Character->GetActorRotation()),
65
                DeltaSeconds, 5.0f);
66
        }
67
        else
68
        {
69
            LeanAmount = FMath::FInterpTo(LeanAmount, 0.0f,
70
                DeltaSeconds, 3.0f);
71
        }
72

73
        // ---- 瞄准更新 ----
74
        UpdateAimOffset(Character);
75

76
        // ---- IK 更新 ----
77
        UpdateFootIK(DeltaSeconds);
78
    }
79

80
private:
81
    float CalculateLean(const FVector& Accel, const FRotator& BaseRot) const
82
    {
83
        FVector LocalAccel = BaseRot.UnrotateVector(Accel);
84
        return FMath::Clamp(LocalAccel.Y / MoveComp->GetMaxAcceleration(),
85
                            -1.0f, 1.0f);
86
    }
87

88
    void UpdateAimOffset(ACharacter* Character)
89
    {
90
        if (AController* Controller = Character->GetController())
91
        {
92
            FRotator AimRot = Controller->GetControlRotation();
93
            FRotator ActorRot = Character->GetActorRotation();
94
            FRotator Delta = (AimRot - ActorRot).GetNormalized();
95
            AimPitch = Delta.Pitch;
96
            AimYaw = Delta.Yaw;
97
        }
98
    }
99

100
    // 其余函数声明（UpdateFootIK / GetMovementDirectionAngle / PlayMontage...）
101
    void UpdateFootIK(float DeltaSeconds);
102
    float GetMovementDirectionAngle(const FVector& Velocity, const FRotator& BaseRot) const;
103

104
    UCharacterMovementComponent* MoveComp;
105
};

1
动画调试控制台命令：
2

3
showdebug animation                  —— 显示当前 AnimInstance 的所有变量值
4
                                             包括 Speed、bIsInAir、当前状态机状态
5

6
a.visbones                           —— 显示骨骼（绿色线条）
7
a.visanim                            —— 显示动画数据
8
a.visik                              —— 显示 IK 目标和链
9
a.vismontage                         —— 显示 Montage 播放进度和 Section
10

11
showdebug character                  —— 显示角色移动状态
12

13
// 编辑器调试工具：
14
// Window → Developer Tools → Animation Insights
15
//   - 性能分析：每个 AnimBP 的求值开销
16
//   - 状态机可视化：实时查看当前状态 + 切换条件
17
//   - BlendSpace 可视化：当前混合参数的采样位置

1
// ===== 陷阱 #1：混淆了 NativeUpdateAnimation 和 NativeThreadSafeUpdateAnimation 的线程模型 =====
2
void UBadAnimInstance::NativeUpdateAnimation(float DeltaSeconds)
3
{
4
    Super::NativeUpdateAnimation(DeltaSeconds);
5

6
    // ✓ NativeUpdateAnimation 永远只在 GameThread 上运行——引擎保证！
7
    //    你在这里访问 GetWorld() / Controller / GameMode 是完全安全的。
8
    //    真正在工作线程上运行的是 NativeThreadSafeUpdateAnimation！
9
    AGameModeBase* GM = GetWorld()->GetAuthGameMode();  // ← 这里其实安全！
10

11
    // ⚠️ 但如果你把 World 访问写进了 NativeThreadSafeUpdateAnimation —— 那才是真正的崩溃点
12
}
13

14
// ✓ 正确分层：
15
// NativeThreadSafeUpdateAnimation  → 只做纯数学计算（Speed / Direction 等不涉及 UObject 的变量）
16
//                                    引擎可能将此函数调度到工作线程并行执行
17
// NativeUpdateAnimation            → 在 GameThread 上运行——可以安全访问 World / Controller
18
//                                    用于更新需要访问 UObject 的变量（如获取 Controller 引用）
19
//
20
// 如果 AnimBP 的线程设置是 "Use Default"（默认行为）：
21
//   NativeThreadSafeUpdateAnimation 会在工作线程执行（并行更新多个角色的动画变量）
22
//   NativeUpdateAnimation 在工作线程更新完成后，回到 GameThread 执行（安全访问所有 UObject）
23

24
// ===== 陷阱 #2：Montage_JumpToSection 在无活跃 Montage 时静默失效 =====
25
void BadMontageUsage()
26
{
27
    Montage_Play(SomeMontage);
28
    // ✗ Montage_Play 可能失败（资产为空/正在播放其他 Montage 被阻止）
29
    //    Montage_JumpToSection 内部有空指针保护——不会崩溃，但会静默 no-op
30
    //    → Section 没有跳转——动画停在原地，逻辑错乱但无报错，极难排查！
31
    Montage_JumpToSection(TEXT("Attack"));
32
}
33

34
// ✓ 正确：JumpToSection 不会崩溃但会无效——检查活跃状态确保逻辑正确
35
if (Montage_IsPlaying(SomeMontage))
36
{
37
    Montage_JumpToSection(TEXT("Attack"));
38
}
39

40
// ===== 陷阱 #3：AnimNotify 中的逻辑没有 Authority 检查 =====
41
void UAnimNotify_ApplyDamage::Notify(...)
42
{
43
    // ✗ 在客户端上触发了伤害！
44
    //    Montage 在所有客户端上播放 → Notify 在所有客户端上触发
45
    //    如果在 Notify 里直接 ApplyDamage → 客户端也在扣血！
46
    UGameplayStatics::ApplyDamage(Target, 25.0f, ...);  // ← 作弊漏洞！
47
}
48
// ✓ Notify 中只做本地表现（音效、VFX），伤害逻辑发 Server RPC
49
//   或者在 Notify 中先检查 HasAuthority()
50

51
// ===== 陷阱 #4：忘记设置 BlendSpace 的 Interpolation Time =====
52
// ✗ BlendSpace 默认插值时间 = 0.0
53
//    → Speed 从 0 跳到 600 → 动画瞬间从 Idle 切到 Run
54
//    → 无过渡——看起来像"抽搐"
55
// ✓ 设置 Target Weight Interp Speed = 5.0~10.0
56
//    → 动画参数平滑过渡——Idle → Walk → Run 有自然的混合过程
57

58
// ===== 陷阱 #5：Root Motion 驱动移动时仍在代码中 AddMovementInput =====
59
void ABadCharacter::Tick(float DeltaTime)
60
{
61
    Super::Tick(DeltaTime);
62

63
    if (bIsPlayingRootMotionMontage)
64
    {
65
        // ✗ Root Motion 已经驱动了移动——再加 AddMovementInput 导致双倍位移！
66
        AddMovementInput(GetActorForwardVector(), 1.0f);
67
    }
68
}
69
// ✓ Root Motion 播放期间禁止代码移动输入（或完全由 Montage 控制）
70

71
// ===== 陷阱 #6：IK Alpha 在跳跃时没有平滑过渡 =====
72
void UBadIK::UpdateFootIK()
73
{
74
    if (bIsInAir) LeftFootIKAlpha = 0.0f;
75
    else LeftFootIKAlpha = 1.0f;
76
    // ✗ 着陆瞬间 IK 从 0 跳到 1 → 脚部"弹跳"到地面位置
77
}
78
// ✓ 用 FMath::FInterpTo 平滑过渡（见 16.3.2 代码）
79

80
// ===== 陷阱 #7：Montage 的 Blend Out Time 设得太短 =====
81
// ✗ BlendOutTime = 0.0
82
//    → 攻击 Montage 被打断 → 手臂瞬间弹回 Idle 位置
83
//    → 看起来像"机器人"——极其不自然
84
// ✓ 设置 BlendOutTime ≥ 0.15s
85

86
// ===== 陷阱 #8：在 Construction Script 中访问 AnimInstance =====
87
// AnimInstance 在 BeginPlay 前可能未初始化
88
// 不要在构造函数或 Construction Script 中调用 GetAnimInstance()

1
Q: "AnimInstance 和 AnimBlueprint 的关系是什么？各自负责什么？"
2
A: AnimInstance（C++ 父类）负责数据——每帧计算 Speed、bIsInAir、Direction，
3
   供动画蓝图使用。AnimBlueprint（蓝图）负责表现——Event Graph 读取 C++ 变量，
4
   Anim Graph 通过状态机和 BlendSpace 选择最终骨骼姿态。
5
   一句话：C++ 管"现在是什么状态"，蓝图管"这个状态该播什么动画"。
6

7
Q: "Montage 的 Slot 机制是怎么实现上下半身分离的？"
8
A: 在 AnimBP 的 AnimGraph 中，骨骼链被分配到不同的 Slot 节点。
9
   DefaultSlot 管全身运动（Idle/Walk/Run），UpperBody Slot 管脊柱以上。
10
   换弹 Montage 分配到 UpperBody Slot 播放 → 覆盖上半身 → 下半身继续走路。
11
   本质上：Slot 节点在骨骼层级上做"后层覆盖前层"的混合。
12

13
Q: "Root Motion 和 Motion Warping 的区别？"
14
A: Root Motion 让动画中的根骨骼位移驱动角色移动（翻滚的位移来自动画数据）。
15
   Motion Warping 是 Root Motion 的增强——在运行时"扭曲"动画，
16
   让特定的关键帧精确匹配目标位置（不同高度的掩体用同一个翻越动画）。
17
   关系：Warping 修改动画的 Root Motion 数据，然后修改后的 Root Motion 再驱动角色。