935 字

5 分钟

UE5 StateTree状态树完全指南

深入解析Unreal Engine 5的StateTree状态树系统，涵盖状态机基础、节点类型、实战用法，帮你快速掌握AI行为逻辑开发

2026-03-15

Unreal

StateTree

状态机 +1

前言#

StateTree是UE5引入的全新AI行为逻辑框架，旨在替代传统的Behavior Tree。它结合了有限状态机（FSM）和行为树的优点，提供更直观、更模块化的AI逻辑设计方式。

本文系统讲解StateTree的用法，帮你快速上手这一强大的AI工具。

为什么用StateTree？#

特性	Behavior Tree	StateTree
状态切换	需要自定义逻辑	内置状态转换
模块化	有限	高度模块化
并行任务	支持但复杂	原生支持
学习曲线	较陡	平缓

核心概念#

State（状态）#

1
// State是StateTree的基本单元
2
// 每个State包含：Enter、Tick、Exit三个阶段

Transition（转换）#

1
// 状态之间的转换条件
2
// 支持事件触发和条件判断

Event（事件）#

1
// 事件驱动状态切换
2
// 可在代码或蓝图中发送事件

节点类型#

1. State Nodes（状态节点）#

节点	说明
State	普通状态，执行子节点
Linked State	链接到另一个StateTree
Operator State	并行执行多个任务

2. Task Nodes（任务节点）#

1
// 执行具体行为
2
// 如：移动、攻击、等待

3. Condition Nodes（条件节点）#

1
// 判断是否满足某个条件
2
// 用于Transition中

4. Event Nodes（事件节点）#

1
// 等待特定事件触发
2
// 收到事件后切换状态

创建StateTree#

1. 创建Asset#

内容浏览器右键
AI → StateTree
命名如 STT_EnemyAI

2. 基本结构#

1
Root
2
├── Idle State
3
│   └── Tasks: Wait, LookAround
4
├── Chase State
5
│   └── Tasks: MoveToTarget, FollowPath
6
└── Attack State
7
    └── Tasks: FaceTarget, ExecuteAttack

3. 配置Transition#

1
Idle → Chase
2
├── Condition: TargetDetected == true
3
└── Event: OnTargetFound
4

5
Chase → Attack
6
├── Condition: DistanceToTarget < MeleeRange
7
└── Event: OnInRange
8

9
Attack → Chase
10
├── Condition: DistanceToTarget > MeleeRange
11
└── Event: OnOutOfRange

代码集成#

发送事件#

1
// 从代码发送StateTree事件
2
UStateTreeComponent* StateTree = Player->FindComponentByClass<UStateTreeComponent>();
3
if (StateTree)
4
{
5
    FStateTreeEvent Event;
6
    Event.Tag = FGameplayTag::RequestGameplayTag("Event.EnemyAlert");
7
    Event.Payload.SetValue<FVector>(TargetLocation);
8
    StateTree->SendEvent(FStateTreeEvent("Alert", Event));
9
}

绑定数据#

1
// StateTree需要的数据定义在Schema中
2
USTRUCT()
3
struct FEnemyStateTreeContext : public FStateTreeOwnerContext
4
{
5
    GENERATED_BODY()
6

7
    UPROPERTY()
8
    TObjectPtr<AAIController> Controller;
9

10
    UPROPERTY()
11
    TObjectPtr<UAIPerceptionComponent> Perception;
12
};

实战：敌人AI#

需求分析#

1
Idle（待机）
2
  ↓ 发现目标
3
Chase（追击）
4
  ↓ 进入攻击范围
5
Attack（攻击）
6
  ↓ 目标逃离
7
Chase（追击）

创建Tasks#

MoveToTarget Task#

1
USTRUCT()
2
struct FMoveToTargetTask : public FStateTreeTask
3
{
4
    GENERATED_BODY()
5

6
    virtual EStateTreeRunStatus EnterState(FStateTreeExecutionContext& Context, const FStateTreeTransition& Transition) const override
7
    {
8
        // 获取Context中的数据
9
        FEnemyStateTreeContext EnemyContext;
10
        if (!Context.GetContext(EnemyContext)) return EStateTreeRunStatus::Failed;
11

12
        AAIController* Controller = EnemyContext.Controller;
13
        if (!Controller) return EStateTreeRunStatus::Failed;
14

15
        // 执行移动
16
        Controller->MoveToActor(EnemyContext.TargetActor);
17
        return EStateTreeRunStatus::Running;
18
    }
19

20
    virtual EStateTreeRunStatus Tick(FStateTreeExecutionContext& Context, const float DeltaTime) const override
21
    {
22
        // 检查是否到达
23
        AAIController* Controller = EnemyContext.Controller;
24
        if (Controller->GetMoveStatus() == EPathFollowingStatus::Type::AtGoal)
25
        {
26
            return EStateTreeRunStatus::Succeeded;
27
        }
28
        return EStateTreeRunStatus::Running;
29
    }
30
};

Attack Task#

1
USTRUCT()
2
struct FAttackTask : public FStateTreeTask
3
{
4
    GENERATED_BODY()
5

6
    float AttackCooldown = 1.0f;
7
    float LastAttackTime = 0.f;
8

9
    virtual EStateTreeRunStatus EnterState(FStateTreeExecutionContext& Context, const FStateTreeTransition& Transition) const override
10
    {
11
        FEnemyStateTreeContext EnemyContext;
12
        if (!Context.GetContext(EnemyContext)) return EStateTreeRunStatus::Failed;
13

14
        // 执行攻击
15
        if (GetWorld()->TimeSeconds - LastAttackTime > AttackCooldown)
16
        {
17
            Attack(EnemyContext.Controller);
18
            LastAttackTime = GetWorld()->TimeSeconds;
19
        }
20

21
        return EStateTreeRunStatus::Succeeded;
22
    }
23
};

调试StateTree#

编辑器内调试#

在StateTree编辑器中打开Debug面板
Play In Editor
观察状态高亮和变量值

日志输出#

1
UE_VLOG_UELOG(StateTreeComponent->GetOwner(), LogStateTree, Log, TEXT("Entering State: %s"), *StateName);

可视化工具#

StateTree Debugger — 查看当前状态和转换
AI Perception Visualizer — 查看AI感知范围
Behavior Tree Visualizer — 配合使用

常见问题#

Q: StateTree和Behavior Tree哪个好？#

A: 新项目推荐StateTree，更易维护。Behavior Tree适合复杂行为树已有项目。

Q: 如何处理并发状态？#

A: 使用 Operator State 节点，可以同时执行多个任务。

Q: 可以和Behavior Tree混用吗？#

A: 可以。通过 Linked State 节点引用Behavior Tree。

Q: 性能如何？#

A: 比传统Behavior Tree略优，尤其在高频状态切换场景。

总结#

StateTree核心要点：

模块化 — 状态和任务独立，可复用
事件驱动 — 灵活的状态切换
并行执行 — Operator State支持
易调试 — 内置调试工具
代码集成 — 可扩展Task和Condition

StateTree是UE5 AI开发的首选框架。

参考资源#

🎉 恭喜！ 现在你掌握了UE5 StateTree的用法！

UE5 StateTree状态树完全指南

https://gzhblog.cn/posts/2026-03/2026-03-15-ue5-state-tree/

作者

384400

发布于

2026-03-15

许可协议

CC BY-NC-SA 4.0

这篇文章是否对你有帮助？

联系赞助

OpenClaw 部署完整指南

游戏开发常用设计模式完全指南

写作概览

20 篇

文章

2.9万

总字数

2.5h

阅读时长

1,464

均字数

年度发文

2026