SuperAPI AI 工具集

ue-statetree

编程与开发

查看项目

更新于 11-16 16:28

技能介绍

用途

ue-statetree 是一份面向 Unreal Engine 5.9 的技能文档,介绍如何把 StateTree 用作通用层级状态机,而不仅限于 AI。它针对挂载在 Actor 上的 UStateTreeComponent,用于实现游戏流程、屏幕/界面流转、过场动画排序、可交互对象等逻辑。文档中的示例来自一个 48 小时 UE 5.9 Game Jam 项目(2026-11),其完整游戏流程(标题、开场、三个章节、最终选择、两个结局)运行在同一个 UStateTreeComponent 上。AI 用法(AIController 上的 UStateTreeAIComponent)由另一份 ue-ai-and-navigation 技能覆盖。

适用场景

  • 在 Actor 上构建游戏流程、屏幕流程或过场动画排序的状态机。
  • 编写 C++ StateTree 任务或条件,包装自己的子系统。
  • 排查循环行为异常的状态树:任务被重复进入、控件被重建、开场动画被重放。
  • 通过编辑器 Python 编辑 StateTree 资产或 StateTreeComponent 引用。
  • 解决使用 StateTree 的模块在编辑器中可编译,但 Game / Shipping / Web 目标编译失败的问题。

核心心智模型

  • 节点是结构体,数据存放在实例数据中。任务结构体在运行时是 const 的,所有可变内容放在其 FInstanceDataType 结构体里,通过 Context.GetInstanceData(*this) 获取。运行时状态绝不能存放在节点结构体中。
  • Schema 决定树可以包含什么节点、获得什么上下文。UStateTreeComponentSchema(GameplayStateTree)提供 Actor 上下文;自定义 UStateTreeSchema 可以只允许自己的节点且不提供上下文。从 *CommonBase 系列结构体派生节点可同时适用于两种 Schema。
  • 子系统保存真实状态,状态树只负责编排。游戏状态放在子系统或组件里,节点读写并驱动它;这样树可以重启、从存档恢复或被替换而不丢失状态。
  • 完成状态即转场触发器。状态在其被纳入完成判断的任务全部完成时结束,随后 OnStateCompleted / OnStateSucceeded / OnStateFailed 转场触发。永不完成且被排除在完成判断之外的任务相当于在后台运行(例如控件、背景音乐)。
  • 已完成状态会被重建。在默认选择规则下,被转场再次选中的已完成状态是一个新状态,其任务会先收到 ExitState 再收到 EnterState(变化类型为 Changed)。bShouldStateChangeOnReselect = false 并不能阻止这一行为,它只覆盖 Sustained 情形。

环境配置

  • 插件:StateTree 和 GameplayStateTree(组件与组件 Schema);示例项目还启用了 PropertyBindingUtils。启用后需重启编辑器。
  • Build.cs:运行时模块 "StateTreeModule"、"GameplayStateTreeModule"(若通过标签发送或匹配事件还需 "GameplayTags")。"StateTreeEditorModule"(以及 "PropertyBindingUtils")仅用于编辑器目标,且仅在代码中构建或编译树(测试)时需要。
  • 运行时模块不启动线程,已在 Wasm(浏览器)构建中打包并运行。

C++ 模式摘要

文档给出了带参数与输出的任务示例、基于委托完成的任务示例、条件与求值器写法、自定义 Schema 写法,以及用 FStateTreeExecutionContext 直接运行(Start 与 Tick)的方式。要点包括:

  • 实例数据 UPROPERTY 的分类(Parameter、Input、Output、Context)构成绑定契约。
  • 在 5.9 中每个节点必须有实例数据类型,哪怕只是空的 USTRUCT(),否则编译报错。
  • bConsideredForCompletion 位于 WITH_EDITORONLY_DATA 下,不加保护会导致 Game、Shipping 和 Wasm 目标出现 C2065 编译错误。
  • 等待事件的任务应捕获 FStateTreeWeakExecutionContext,不能捕获上下文或实例数据引用;并在进入时先检查事件是否已发生,避免永久等待。
  • 一个动作可能触发多个委托,应让第一个完成任务的委托生效,忽略其余。

游戏流程的树形结构

文档给出示例结构:Flow 根状态下的 Start 根据存档状态路由到 Play、Ending 或 Intro;Intro 进入章节;Chapters 放置控件(父状态上的控件对全部子状态生效);Chapter1 与 Play 循环等待玩家操作,并根据条件转场;Ending 分为 Win 和 Lose 两个状态。关键建议:

  • 控件放在父状态,循环放在子状态。5.9 规则下循环子状态每次完成都会重建,若控件任务放在该状态上,会在每次玩家操作后被销毁重建。
  • 一次性内容必须幂等。示例中一个状态在测试里 6 个 tick 内进入了 31 次;应在子系统中记录“开场已播放”,使任务第二次成为空操作,并用“仅当待处理”限制进入开场状态的转场。
  • 在第一状态中处理恢复。转场不能回退,因此 Start 负责路由到正确状态。
  • 状态之间的移动通过子系统的公共 API 完成,让所有监听者都能感知每一步。

启动、暂停与替换状态树

  • 在 BeginPlay 之前调用 UStateTreeComponent::SetStartLogicAutomatically(false) 可将状态树挡在标题画面之后;之后调用 SetStartLogicAutomatically(true) 再调用 StartLogic()。
  • 逻辑运行期间 SetStateTree / SetStateTreeReference 会被忽略。
  • 5.9 中 StateTreeRef 为 protected 且没有公开 getter;如需检查放置的组件是否设置了树,可通过反射读取。
  • 事件:SendStateTreeEvent(FStateTreeEvent)(标签、可选负载、来源);GetStateTreeRunStatus() 与 OnStateTreeRunStatusChanged 用于获知结束状态。
  • 链接树:Linked 类型(同一资产中的子树)或 LinkedAsset 类型(另一资产),可用 AddLinkedStateTreeOverrides(Tag, Ref) 在运行时替换链接资产。

编辑器 Python 注意事项

  • 绝不要在蓝图组件模板上调用 StateTreeComponent.set_state_tree():编辑器会因 Null assigned to TNotNull 而崩溃。应改为写引用属性,示例使用了 import_text 并 set_editor_property("state_tree_ref", ref)。
  • 转场(FStateTreeTransition)没有脚本可调用的“添加转场”,C++ 的 AddTransition 不是 UFUNCTION。示例通过 StateTreeTransition.import_text 构造转场,再把新列表写回状态的 transitions 属性;写回数组这一步在文档中标注为未验证。
  • UStateTree::EditorData 是 WITH_EDITORONLY_DATA 下的裸 UPROPERTY(),get_editor_property("editor_data") 会失败;应使用 UStateTreeEditorData::GetEditorData(StateTree)。
  • Epic 的 StateTreeToolset(5.9,实验性)将编辑 API 包装为 AI 工具,可编译、读取编辑数据、根状态、全部状态、子节点、任务、转场,并可添加子状态、任务、进入条件、全局任务、求值器等;但它不能用 Schema 创建 StateTree 资产,也没有转场写入功能。

在代码中测试状态树

仅编辑器测试可用 UStateTreeEditorData 构建树,用 FStateTreeCompiler 编译,再用 FStateTreeExecutionContext 配合 EStateTreeRecordTransitions::Yes 运行,无需资产或世界。示例测试套件曾用这种方式在每个种子上完整运行游戏十次。

常见陷阱

  • 把运行状态放进节点结构体而不是实例数据:会被所有实例共享,而且节点在运行时本就是 const 的。
  • 等待一个已经发生的事件会永久等待;应在进入时检查。
  • 期望 bShouldStateChangeOnReselect = false 让循环状态保持存活:5.9 中已完成状态无论如何都会重建,持久任务应移到父状态。
  • 编辑器专用成员(bConsideredForCompletion)未加保护:编辑器可编译,游戏目标失败。
  • 运行时调用 SetStateTree:被忽略;应先暂停逻辑、设置、再启动。
  • 控件任务遇到缺失的类应记录日志并继续运行,缺失 UI 不能卡住流程。
  • 从 Python 对蓝图模板调用 set_state_tree():编辑器崩溃,应改用 import_text。

未验证内容

文档明确标注了若干未验证事项:上述转场数组写回与编译、仅用引擎 API 从 Python 添加转场条件、在普通脚本中调用 unreal.StateTreeEditorData.get_editor_data(tree)、以及 set_state_tree() 在编辑器世界中放置的(非模板)组件上是否同样致命。

参考资料

引擎源码(UE 5.9)中的 StateTreeTaskBase.h、StateTreeConditionBase.h、StateTreeEvaluatorBase.h、StateTreeNodeBase.h 等文件。