自动关联目录：AnimInstance 与动画蓝图

官方依据：Animation Blueprints（UE 5.8 Documentation，覆盖其 4 个条目）、Control Rig（3 个章节）。官方该页为概述页，EventGraph / 线程安全更新 / 属性访问 / 调试等内容按其指引以引擎模块为准书写。

1. 定位

Animation Blueprint（AnimBP）是一种特殊的 Blueprint，专门在运行时控制 Skeletal Mesh 的动画。它围绕 AnimBP Editor 里的各类 Graph 组织，用来混合动画、控制骨骼、逐帧定义最终姿势。

一句话定位：AnimBP 是"动画的状态机与混合逻辑"，AnimInstance 是它运行时的 C++ 载体。前者是资产，后者是类——理解这个区分，就知道逻辑该写在哪。

2. 结构

SkeletalMeshComponent
   └─ Anim Class = 某个 AnimBP（其 Parent Class 是 AnimInstance）
          ├─ EventGraph：更新变量（速度、朝向、状态）
          └─ AnimGraph：用这些变量混合出最终姿势

创建与组织

官方提到的三种组织手段：

大型角色推荐用 Linked Anim Graphs / Linked Anim Layers 拆分：一个总 AnimBP + 若干按部位（上半身/下半身）或按状态的子图，避免单张图变成蜘蛛网。

3. 更新管线

游戏线程                          工作线程
  ├─ 组件 Tick / 更新变量
  ├─ NativeUpdateAnimation        （游戏线程，可访问 UObject）
  ├─ NativeThreadSafeUpdateAnimation（工作线程，**不能访问 UObject**）
  ├─ BlueprintUpdateAnimation
  └─ BlueprintThreadSafeUpdateAnimation
        │
        ▼
   AnimGraph 求值（工作线程）→ 输出姿势

void UMyAnimInstance::NativeUpdateAnimation(float DeltaSeconds)
{
    Super::NativeUpdateAnimation(DeltaSeconds);
    if (APawn* Pawn = TryGetPawnOwner())
    {
        Speed = Pawn->GetVelocity().Size();       // 这里能碰 UObject
    }
}

void UMyAnimInstance::NativeThreadSafeUpdateAnimation(float DeltaSeconds)
{
    Super::NativeThreadSafeUpdateAnimation(DeltaSeconds);
    // 只能做纯计算：把 Speed 换算成 BlendSpace 坐标等
}

最常见的崩溃来源：在 NativeThreadSafeUpdateAnimation 里访问 UObject/Actor。它跑在工作线程上，UObject 归游戏线程与 GC 管，跨线程访问既是数据竞争也可能读到正在销毁的对象。

属性访问（Property Access）

AnimBP 里读变量要用 Property Access 节点（而不是直接 Cast 拿引用），因为：

• 它是线程安全的读取路径
• 支持自动缓存，避免每帧重复 Cast

直接拖一个 Actor 引用去 Cast，会让整个链退化到游戏线程，也就失去了多线程动画的收益。

4. 参数与设置

5. 代价与权衡

6. 踩坑与排查

7. 排查顺序

1. 完全没动画？→ 组件上的 Anim Class 是否设了；骨架是否匹配
2. 崩在工作线程？→ 线程安全函数里是否碰了 UObject
3. 慢？→ stat anim 看更新与求值；检查是否退化到游戏线程
4. 姿势不对？→ 看 AnimGraph 里变量的值（AnimBP 调试可实时看）
5. 状态跳变？→ 动画状态机的 transition 条件

8. 调试

参考

• Animation Blueprints
• IK 与重定向（Control Rig） · AnimGraph 与节点 · 动画性能
• GC 与对象生命周期（跨线程访问 UObject 的风险）