653 lines
20 KiB
Markdown
653 lines
20 KiB
Markdown
# Behavior Designer Pro — 行为树节点编写完全指南
|
||
|
||
> 版本: Behavior Designer Pro (基于 DOTS 混合架构)
|
||
> 适用项目: Cielonos (3D 第三人称动作游戏)
|
||
|
||
---
|
||
|
||
## 1. 架构总览
|
||
|
||
Behavior Designer Pro 采用 **DOTS 混合架构**：行为树的**遍历**始终由 ECS (Entity Component System) 驱动，但节点的**逻辑**可以选择 GameObject 工作流或纯 ECS 工作流。
|
||
|
||
### 1.1 两种工作流对比
|
||
|
||
| 维度 | GameObject 工作流 (推荐) | Entity (ECS) 工作流 |
|
||
|------|------------------------|-------------------|
|
||
| 基类 | `Action`, `Conditional`, `ActionNode`, `ConditionalNode`, `DecoratorNode`, `CompositeNode` | `ECSActionTask<TSystem, TComponent>` 等 |
|
||
| 编写难度 | 低，类似 MonoBehaviour | 高，需要定义 `IBufferElementData`, `ISystem`, `Flag` |
|
||
| 是否可引用对象 | ✅ 可以引用 `GameObject`, `Component` | ❌ 只能传值类型 |
|
||
| 是否支持 SharedVariable | ✅ | ❌ |
|
||
| 是否支持 Burst/Job | ❌ | ✅ |
|
||
| 适用场景 | < 50 个 AI Agent | 成千上万个 Agent |
|
||
|
||
**本项目 (Cielonos) 统一使用 GameObject 工作流。**
|
||
|
||
### 1.2 核心命名空间
|
||
|
||
```csharp
|
||
using Opsive.BehaviorDesigner.Runtime; // BehaviorTree 组件
|
||
using Opsive.BehaviorDesigner.Runtime.Tasks; // TaskStatus, Task 基类
|
||
using Opsive.BehaviorDesigner.Runtime.Tasks.Actions; // Action, ActionNode
|
||
using Opsive.BehaviorDesigner.Runtime.Tasks.Conditionals; // Conditional, ConditionalNode
|
||
using Opsive.BehaviorDesigner.Runtime.Tasks.Composites; // CompositeNode
|
||
using Opsive.BehaviorDesigner.Runtime.Tasks.Decorators; // DecoratorNode
|
||
using Opsive.BehaviorDesigner.Runtime.Tasks.Events; // EventNode (OnReceivedEvent等)
|
||
using Opsive.GraphDesigner.Runtime; // NodeIcon, Description 等特性
|
||
using Opsive.GraphDesigner.Runtime.Variables; // SharedVariable<T>
|
||
using Opsive.Shared.Utility; // Category, Description, MemberVisibility
|
||
using Opsive.Shared.Events; // EventHandler (事件系统)
|
||
```
|
||
|
||
---
|
||
|
||
## 2. TaskStatus 枚举
|
||
|
||
```csharp
|
||
public enum TaskStatus : byte
|
||
{
|
||
Inactive, // 未激活
|
||
Queued, // 下一帧将执行
|
||
Running, // 正在执行（持续多帧）
|
||
Success, // 执行成功
|
||
Failure, // 执行失败
|
||
}
|
||
```
|
||
|
||
**核心规则:**
|
||
- **Action 节点**: 可以返回 `Running`（多帧持续）, `Success`, `Failure`
|
||
- **Conditional 节点**: 应当仅返回 `Success` 或 `Failure`，不应返回 `Running`（单帧内完成判定）
|
||
|
||
---
|
||
|
||
## 3. Task 基类生命周期
|
||
|
||
`Task` 是所有 GameObject 工作流节点的终极基类，其生命周期方法如下：
|
||
|
||
```
|
||
BehaviorTree 初始化
|
||
└─ Initialize() [internal, 自动调用]
|
||
├─ 缓存 m_GameObject, m_Transform, m_BehaviorTree
|
||
├─ 注册物理回调（如果子类启用了对应的 Receive*Callback）
|
||
└─ OnAwake() ← 【初始化：缓存组件引用，仅调用一次】
|
||
|
||
BehaviorTree 启动
|
||
└─ OnBehaviorTreeStarted() ← 【树启动时回调】
|
||
|
||
每次节点被激活
|
||
└─ OnStart() ← 【节点开始执行，每次激活都会调用】
|
||
└─ OnUpdate() (每帧) ← 【核心逻辑，返回 TaskStatus】
|
||
└─ OnEnd() ← 【节点执行结束（Success/Failure 后）】
|
||
|
||
BehaviorTree 停止/暂停
|
||
└─ OnBehaviorTreeStopped(bool paused)
|
||
|
||
BehaviorTree 销毁
|
||
└─ OnDestroy() ← 【清理，取消事件注册】
|
||
```
|
||
|
||
### 3.1 关键属性/字段
|
||
|
||
| 成员 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `m_GameObject` / `gameObject` | `GameObject` | 行为树挂载的 GameObject |
|
||
| `m_Transform` / `transform` | `Transform` | 行为树的 Transform |
|
||
| `m_BehaviorTree` | `BehaviorTree` | 行为树组件引用 |
|
||
| `m_RuntimeIndex` | `ushort` | 节点运行时索引 |
|
||
|
||
---
|
||
|
||
## 4. 四种节点类型详解
|
||
|
||
### 4.1 Action (行为节点)
|
||
|
||
**用途**: 改变游戏状态（播放动画、移动、设置变量等）。
|
||
|
||
**两种基类选择**:
|
||
- `Action` — **可堆叠** (Stacked)：多个 Action 可放在同一个 StackedAction 节点中
|
||
- `ActionNode` — **不可堆叠** (Independent)：独立节点
|
||
|
||
**编写模板（最简）**:
|
||
|
||
```csharp
|
||
using Opsive.BehaviorDesigner.Runtime.Tasks;
|
||
using Opsive.BehaviorDesigner.Runtime.Tasks.Actions;
|
||
using Opsive.GraphDesigner.Runtime;
|
||
using Opsive.Shared.Utility;
|
||
using UnityEngine;
|
||
|
||
[Description("描述此节点的功能")]
|
||
[NodeIcon("Assets/路径/图标.png")]
|
||
[Category("Cielonos")]
|
||
public class MyAction : Action
|
||
{
|
||
[Tooltip("参数说明")]
|
||
[SerializeField] float m_Speed = 5f;
|
||
|
||
public override void OnAwake()
|
||
{
|
||
// 缓存组件 (仅一次)
|
||
}
|
||
|
||
public override void OnStart()
|
||
{
|
||
// 每次节点激活时的初始化
|
||
}
|
||
|
||
public override TaskStatus OnUpdate()
|
||
{
|
||
// 核心逻辑
|
||
// 返回 Running = 继续执行, Success = 完成, Failure = 失败
|
||
return TaskStatus.Success;
|
||
}
|
||
|
||
public override void OnEnd()
|
||
{
|
||
// 节点结束时的清理
|
||
}
|
||
|
||
public override void Reset()
|
||
{
|
||
// 编辑器重置默认值
|
||
m_Speed = 5f;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.2 Conditional (条件节点)
|
||
|
||
**用途**: 检查游戏状态（距离、血量、事件等），不改变游戏状态。
|
||
|
||
**两种基类选择**:
|
||
- `Conditional` — **可堆叠** + **支持 Conditional Abort 重评估**
|
||
- `ConditionalNode` — **不可堆叠** (Independent)
|
||
|
||
**关键方法**: `OnReevaluateUpdate()` — 在 Conditional Abort 重评估阶段调用，默认实现会调用 `OnUpdate()`。
|
||
|
||
**编写模板**:
|
||
|
||
```csharp
|
||
using Opsive.BehaviorDesigner.Runtime.Tasks;
|
||
using Opsive.BehaviorDesigner.Runtime.Tasks.Conditionals;
|
||
using Opsive.Shared.Utility;
|
||
using UnityEngine;
|
||
|
||
[Category("Cielonos")]
|
||
[Description("检查某个条件")]
|
||
public class MyConditional : Conditional
|
||
{
|
||
public override void OnAwake()
|
||
{
|
||
// 缓存组件
|
||
}
|
||
|
||
public override TaskStatus OnUpdate()
|
||
{
|
||
// 检查条件：Success = 条件满足, Failure = 不满足
|
||
return someCondition ? TaskStatus.Success : TaskStatus.Failure;
|
||
}
|
||
|
||
// 可选：Conditional Abort 重评估时走不同逻辑
|
||
public override TaskStatus OnReevaluateUpdate()
|
||
{
|
||
return OnUpdate(); // 默认行为
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.3 Composite (组合节点)
|
||
|
||
**常用内置 Composite**:
|
||
|
||
| 节点 | 行为 |
|
||
|------|------|
|
||
| `Sequence` | 顺序执行子节点，全部 Success 才返回 Success，任一 Failure 立即返回 Failure（AND 逻辑） |
|
||
| `Selector` | 顺序执行子节点，任一 Success 立即返回 Success，全部 Failure 才返回 Failure（OR 逻辑） |
|
||
| `Parallel` | 并行执行所有子节点 |
|
||
| `ParallelSelector` | 并行执行，任一 Success 立即停止 |
|
||
| `RandomSelector` | 随机顺序的 Selector |
|
||
| `RandomSequence` | 随机顺序的 Sequence |
|
||
| `PrioritySelector` | 按优先级排序的 Selector |
|
||
| `UtilitySelector` | 效用评分选择器 |
|
||
|
||
**自定义 Composite**: 继承 `CompositeNode`，不可堆叠。
|
||
|
||
### 4.4 Decorator (装饰节点)
|
||
|
||
**用途**: 修改子节点的返回状态或控制子节点的执行方式。只能有一个子节点。
|
||
|
||
**常用内置 Decorator**:
|
||
|
||
| 节点 | 行为 |
|
||
|------|------|
|
||
| `Inverter` | 反转子节点结果 (Success↔Failure) |
|
||
| `Repeater` | 重复执行子节点指定次数或无限次 |
|
||
| `ReturnSuccess` | 无论子节点结果如何，始终返回 Success |
|
||
| `ReturnFailure` | 无论子节点结果如何，始终返回 Failure |
|
||
| `UntilSuccess` | 重复执行直到子节点返回 Success |
|
||
| `UntilFailure` | 重复执行直到子节点返回 Failure |
|
||
| `Cooldown` | 子节点执行后进入冷却 |
|
||
| `ConditionalEvaluator` | 条件评估装饰器 |
|
||
| `Iterator` | 遍历列表 |
|
||
|
||
**自定义 Decorator**: 继承 `DecoratorNode`，不可堆叠。
|
||
|
||
---
|
||
|
||
## 5. Conditional Aborts (条件打断)
|
||
|
||
**核心机制**: 在行为树运行时，Conditional 节点可以被持续重评估。当条件状态变化时（Success→Failure 或 Failure→Success），触发打断。
|
||
|
||
### 5.1 四种打断类型 (`ConditionalAbortType`)
|
||
|
||
```csharp
|
||
public enum ConditionalAbortType : byte
|
||
{
|
||
None, // 不打断
|
||
LowerPriority, // 打断右侧（低优先级）分支
|
||
Self, // 打断当前分支内的任务
|
||
Both // LowerPriority + Self
|
||
}
|
||
```
|
||
|
||
设置在 **Composite 节点**（Sequence/Selector）上。
|
||
|
||
### 5.2 经典设计模式
|
||
|
||
```
|
||
Selector (根)
|
||
├── Sequence [AbortType=LowerPriority] ← 最高优先级
|
||
│ ├── HasTakenDamage (Conditional)
|
||
│ └── ReactToDamage (Action)
|
||
├── Sequence [AbortType=LowerPriority]
|
||
│ ├── CanSeeObject (Conditional)
|
||
│ └── ChaseAndAttack (子树)
|
||
├── Sequence [AbortType=LowerPriority]
|
||
│ ├── WithinDistance (Conditional)
|
||
│ └── Investigate (Action)
|
||
└── Patrol (Action) ← 最低优先级（兜底行为）
|
||
```
|
||
|
||
### 5.3 OnReevaluateUpdate 注意事项
|
||
|
||
- 默认 `Conditional.OnReevaluateUpdate()` 调用 `OnUpdate()`
|
||
- 如果需要在重评估时走特殊逻辑（如避免消费事件），应覆写此方法
|
||
- 项目中 `HasReceivedContextEvent` 就是一个好例子：`OnReevaluateUpdate()` 只检查不消费
|
||
|
||
---
|
||
|
||
## 6. SharedVariable (共享变量)
|
||
|
||
SharedVariable 是行为树节点间共享数据的机制。
|
||
|
||
### 6.1 基本用法
|
||
|
||
```csharp
|
||
using Opsive.GraphDesigner.Runtime.Variables;
|
||
|
||
// 声明
|
||
[SerializeField] SharedVariable<float> m_Speed = 5f; // 带默认值
|
||
[SerializeField] SharedVariable<GameObject> m_Target; // 引用类型
|
||
[SerializeField] SharedVariable<Vector3> m_Position;
|
||
[SerializeField] SharedVariable<string> m_EventName;
|
||
[SerializeField] SharedVariable<bool> m_IsEnabled;
|
||
|
||
// 读取
|
||
float speed = m_Speed.Value;
|
||
GameObject target = m_Target.Value;
|
||
|
||
// 设置
|
||
m_Speed.Value = 10f;
|
||
|
||
// 无类型 SharedVariable (用于泛型存储)
|
||
[RequireShared] [SerializeField] SharedVariable m_StoredValue1;
|
||
// 设置值
|
||
m_StoredValue1.SetValue(someObject);
|
||
// 检查是否已共享
|
||
if (m_StoredValue1 != null && m_StoredValue1.IsShared) { ... }
|
||
|
||
// 值变化回调
|
||
m_Speed.OnValueChange += OnSpeedChanged;
|
||
```
|
||
|
||
### 6.2 通过 BehaviorTree 组件访问
|
||
|
||
```csharp
|
||
// 获取变量
|
||
var variable = m_BehaviorTree.GetVariable("VariableName");
|
||
|
||
// 设置变量值
|
||
m_BehaviorTree.SetVariableValue("VariableName", newValue);
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 事件系统
|
||
|
||
### 7.1 Opsive.Shared.Events.EventHandler
|
||
|
||
BD Pro 内置事件系统，用于节点间和外部脚本通信。
|
||
|
||
```csharp
|
||
// 发送事件 (到特定 BehaviorTree)
|
||
EventHandler.ExecuteEvent(behaviorTree, "EventName");
|
||
EventHandler.ExecuteEvent<object>(behaviorTree, "EventName", arg1);
|
||
EventHandler.ExecuteEvent<object, object>(behaviorTree, "EventName", arg1, arg2);
|
||
|
||
// 注册事件
|
||
EventHandler.RegisterEvent(behaviorTree, "EventName", OnEventReceived);
|
||
EventHandler.RegisterEvent<object>(behaviorTree, "EventName", OnEventReceived);
|
||
|
||
// 注销事件
|
||
EventHandler.UnregisterEvent(behaviorTree, "EventName", OnEventReceived);
|
||
|
||
// 全局事件
|
||
EventHandler.RegisterEvent("GlobalEventName", OnGlobalEvent);
|
||
EventHandler.ExecuteEvent("GlobalEventName");
|
||
```
|
||
|
||
### 7.2 内置事件节点
|
||
|
||
- **`HasReceivedEvent`** (Conditional): 当收到指定事件时返回 Success（支持 Conditional Abort）
|
||
- **`OnReceivedEvent`** (EventNode): 收到事件时启动一个独立分支（类似中断）
|
||
- **`SendEvent`** (Action): 向自身或其他 BehaviorTree 发送事件
|
||
|
||
### 7.3 自定义事件系统 (Cielonos)
|
||
|
||
本项目使用 `BehaviorSubcontroller.EventMemory` 实现了带**有效窗口期**的上下文事件系统：
|
||
|
||
```csharp
|
||
// HasReceivedContextEvent 的核心逻辑:
|
||
// 1. 通过 behaviorSc.EventMemory 读取事件
|
||
// 2. 用 validWindow (秒) 判断事件是否在有效期内
|
||
// 3. OnUpdate 中消费事件 (Remove)
|
||
// 4. OnReevaluateUpdate 中只检查不消费
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 常用特性 (Attributes)
|
||
|
||
```csharp
|
||
// 节点分类（在创建节点菜单中的路径）
|
||
[Category("Cielonos")]
|
||
[Category("Cielonos/Events")]
|
||
[Category("Movement Pack")]
|
||
|
||
// 节点描述（选中节点后右下角显示）
|
||
[Description("此节点的功能描述")]
|
||
|
||
// 节点图标（自定义 PNG 或 GUID）
|
||
[NodeIcon("Assets/Sprites/Icon/Play.png")]
|
||
[NodeIcon("GUID_Light", "GUID_Dark")] // 明暗两套图标
|
||
|
||
// Tooltip（Inspector 中悬浮提示）
|
||
[Tooltip("参数说明")]
|
||
|
||
// 隐藏在过滤窗口中
|
||
[HideInFilterWindow]
|
||
|
||
// 强制要求 SharedVariable 必须为 Shared 模式
|
||
[RequireShared]
|
||
|
||
// 隐藏字段不显示在 Inspector
|
||
[HideInInspector]
|
||
|
||
// 允许同类型多实例
|
||
[AllowMultipleTypes]
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 本项目自定义基类
|
||
|
||
### 9.1 AutomataActionBase (Action 基类)
|
||
|
||
```csharp
|
||
[Category("Cielonos")]
|
||
public abstract class AutomataActionBase : Action
|
||
{
|
||
protected Automata self;
|
||
protected BehaviorSubcontroller behaviorSc;
|
||
protected BehaviorTree mainBehaviorTree;
|
||
|
||
public override void OnAwake()
|
||
{
|
||
self = gameObject.GetComponent<Automata>();
|
||
behaviorSc = self.behaviorSc;
|
||
mainBehaviorTree = behaviorSc.mainBehaviorTree;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 9.2 AutomataConditionalBase (Conditional 基类)
|
||
|
||
```csharp
|
||
[Category("Cielonos")]
|
||
public abstract class AutomataConditionalBase : Conditional
|
||
{
|
||
protected Automata self;
|
||
protected BehaviorSubcontroller behaviorSc;
|
||
protected BehaviorTree mainBehaviorTree;
|
||
|
||
public override void OnAwake()
|
||
{
|
||
self = gameObject.GetComponent<Automata>();
|
||
behaviorSc = self.behaviorSc;
|
||
mainBehaviorTree = behaviorSc.mainBehaviorTree;
|
||
}
|
||
}
|
||
```
|
||
|
||
**使用这些基类后，子类可直接访问 `self`, `behaviorSc`, `mainBehaviorTree`。**
|
||
|
||
---
|
||
|
||
## 10. 本项目已有自定义节点清单
|
||
|
||
### 10.1 Action 节点
|
||
|
||
| 节点名 | 基类 | 功能 |
|
||
|--------|------|------|
|
||
| `PlayFuncAnim` | `AutomataActionBase` | 播放功能动画，检测打断，支持循环动画/转向目标/根吸附 |
|
||
| `SetBreakthroughResistance` | `AutomataActionBase` | 设置可打断状态（白/橙/红光） |
|
||
| `SetRootMotionMultipliers` | `Action` | 设置根运动各方向的倍率，支持自动计算 |
|
||
| `GetPlayer` | `AutomataActionBase` | 获取玩家对象到 SharedVariable |
|
||
| `GetGlobalVariable` | `AutomataActionBase` | 获取全局属性值 |
|
||
| `ResetTimer` | `AutomataActionBase` | 重置计时器 |
|
||
|
||
### 10.2 Conditional 节点
|
||
|
||
| 节点名 | 基类 | 功能 |
|
||
|--------|------|------|
|
||
| `HasReceivedContextEvent` | `AutomataConditionalBase` | 检查上下文事件（带有效窗口期），完美支持 Conditional Abort |
|
||
| `CheckAttribute` | `Conditional` | 检查数值属性（大于/小于/等于） |
|
||
| `CheckStatus` | `Conditional` | 检查状态效果（单个/任意/全部） |
|
||
| `CheckTimer` | `AutomataConditionalBase` | 检查计时器是否完成 |
|
||
| `CheckString` | `Conditional` | 字符串检查（完全匹配/包含/正则） |
|
||
| `IsPlayingFuncAnim` | `AutomataConditionalBase` | 检查是否正在播放指定功能动画 |
|
||
|
||
### 10.3 自定义 Editor
|
||
|
||
| 编辑器类 | 目标 | 功能 |
|
||
|---------|------|------|
|
||
| `SetBreakthroughResistanceControl` | `SetBreakthroughResistance` | 条件显示高级设置列表 |
|
||
|
||
---
|
||
|
||
## 11. 自定义 Inspector 编辑器
|
||
|
||
在 BD Pro 中自定义节点的 Inspector 面板：
|
||
|
||
```csharp
|
||
using UnityEngine.UIElements;
|
||
using Opsive.Shared.Editor.UIElements;
|
||
using Opsive.Shared.Editor.UIElements.Controls;
|
||
using Opsive.Shared.Editor.UIElements.Controls.Types;
|
||
|
||
[ControlType(typeof(目标Task类型))]
|
||
public class MyTaskControl : TypeControlBase
|
||
{
|
||
public override bool UseLabel => false; // 不使用外层 Label
|
||
|
||
protected override VisualElement GetControl(TypeControlInput input)
|
||
{
|
||
var task = input.Value as MyTask;
|
||
var container = new VisualElement();
|
||
|
||
// 使用 FieldInspectorView.AddField 自动生成标准控件
|
||
FieldInspectorView.AddField(
|
||
input.UnityObject, // UnityObject 引用
|
||
task, // 目标实例
|
||
"fieldName", // 字段名
|
||
container, // 父容器
|
||
(object newValue) => // 值变更回调
|
||
{
|
||
task.fieldName = (FieldType)newValue;
|
||
input.OnChangeEvent(task); // 通知 BD 数据已修改
|
||
}
|
||
);
|
||
|
||
return container;
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 12. Movement Pack Add-On
|
||
|
||
用于 NavMesh 导航的 Action 节点，所有移动类节点继承自 `MovementBase`。
|
||
|
||
### 12.1 MovementBase 架构
|
||
|
||
```csharp
|
||
public abstract class MovementBase : Action
|
||
{
|
||
protected Pathfinder m_Pathfinder; // 寻路器抽象（默认 NavMeshAgentPathfinder）
|
||
|
||
// 核心方法
|
||
protected virtual bool SetDestination(Vector3 destination);
|
||
protected bool HasPath();
|
||
public bool HasArrived();
|
||
protected bool SamplePosition(ref Vector3 position);
|
||
|
||
// 生命周期
|
||
public override void OnAwake() → m_Pathfinder.Initialize(gameObject);
|
||
public override void OnStart() → m_Pathfinder.OnStart();
|
||
public override void OnEnd() → m_Pathfinder.Stop(); + OnEnd();
|
||
}
|
||
```
|
||
|
||
### 12.2 常用移动节点
|
||
|
||
| 节点 | 功能 |
|
||
|------|------|
|
||
| `Seek` | 移向目标 GameObject 或 Position，到达返回 Success |
|
||
| `Flee` | 远离目标 |
|
||
| `Pursue` | 追逐（预测目标位置） |
|
||
| `Patrol` | 巡逻路径 |
|
||
| `Wander` | 随机漫游 |
|
||
| `Follow` | 跟随目标 |
|
||
| `Evade` | 逃避 |
|
||
| `Cover` | 寻找掩体 |
|
||
| `RotateTowards` | 转向目标 |
|
||
| `MoveTowards` | 直线移向目标 |
|
||
|
||
---
|
||
|
||
## 13. Senses Pack Add-On
|
||
|
||
用于感知系统的节点。
|
||
|
||
### 13.1 感知传感器类型
|
||
- `Visibility` — 视觉检测
|
||
- `Distance` — 距离检测
|
||
- `Sound` — 声音检测
|
||
- `Luminance` — 光照检测
|
||
- `Temperature` — 温度检测
|
||
- `Surface` — 地面类型检测
|
||
- `Tracer` — 痕迹追踪
|
||
|
||
### 13.2 常用感知节点
|
||
- `CanDetectObject` — 检测是否能感知到物体
|
||
- `WithinRange` — 检测是否在范围内
|
||
- `GetSensorAmount` — 获取传感器数值
|
||
|
||
---
|
||
|
||
## 14. 最佳实践与性能避坑
|
||
|
||
### 14.1 OnAwake vs OnStart
|
||
|
||
| 方法 | 调用频率 | 用途 |
|
||
|------|---------|------|
|
||
| `OnAwake()` | 行为树初始化时**仅一次** | 缓存组件引用（`GetComponent`） |
|
||
| `OnStart()` | 节点**每次激活**时 | 初始化运行时状态 |
|
||
|
||
**严禁在 `OnUpdate()` 中调用 `GetComponent`！**
|
||
|
||
### 14.2 Conditional Abort 安全编写
|
||
|
||
```csharp
|
||
public class SafeConditional : AutomataConditionalBase
|
||
{
|
||
public override TaskStatus OnUpdate()
|
||
{
|
||
// 正常评估 + 消费事件/状态
|
||
if (CheckAndConsume()) return TaskStatus.Success;
|
||
return TaskStatus.Failure;
|
||
}
|
||
|
||
public override TaskStatus OnReevaluateUpdate()
|
||
{
|
||
// 仅检查，不消费！
|
||
if (CheckOnly()) return TaskStatus.Success;
|
||
return TaskStatus.Failure;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 14.3 节点命名规范
|
||
|
||
- Action 节点: 动词开头 (`PlayFuncAnim`, `SetBreakthroughResistance`, `GetPlayer`)
|
||
- Conditional 节点: `Is*`, `Has*`, `Check*`, `Can*` (`IsPlayingFuncAnim`, `HasReceivedContextEvent`, `CheckAttribute`)
|
||
|
||
### 14.4 物理回调
|
||
|
||
如需接收物理回调，必须覆写对应属性：
|
||
|
||
```csharp
|
||
protected override bool ReceiveTriggerEnterCallback => true;
|
||
|
||
protected override void OnTriggerEnter(Collider other)
|
||
{
|
||
// 处理触发器进入
|
||
}
|
||
```
|
||
|
||
### 14.5 协程支持
|
||
|
||
Task 支持在节点内启动协程：
|
||
|
||
```csharp
|
||
protected void StartCoroutine(string methodName);
|
||
protected Coroutine StartCoroutine(IEnumerator routine);
|
||
protected void StopCoroutine(string methodName);
|
||
protected void StopAllCoroutines();
|
||
```
|
||
|
||
---
|
||
|
||
## 15. 新节点编写 Checklist
|
||
|
||
- [ ] 选择正确的基类 (`Action`/`Conditional`/`AutomataActionBase`/`AutomataConditionalBase`)
|
||
- [ ] 添加 `[Category("Cielonos")]` 和 `[Description("...")]`
|
||
- [ ] 在 `OnAwake()` 中缓存所有组件引用
|
||
- [ ] 在 `OnStart()` 中初始化每次运行的状态
|
||
- [ ] `OnUpdate()` 返回正确的 `TaskStatus`
|
||
- [ ] 如果是 Conditional 且需要支持 Abort，考虑覆写 `OnReevaluateUpdate()`
|
||
- [ ] 使用 `SharedVariable<T>` 实现节点间数据共享
|
||
- [ ] 可选：实现 `Reset()` 提供编辑器默认值
|
||
- [ ] 可选：实现 `OnEnd()` 进行清理
|
||
- [ ] 确保引用了正确的 Assembly Definition (`Opsive.BehaviorDesigner.Runtime`)
|