# 行为树使用指南 ![image](../image/bt-gui.png) 本指南将详细介绍如何使用 kunpocc-behaviortree 库和行为树编辑器。 ## 一、开发环境 - 引擎版本：Cocos Creator 3.8.6 - 编程语言：TypeScript - 支持引擎版本：Cocos Creator 3.7+ ## 二、安装 1. 安装 kunpocc-behaviortree ``` npm install kunpocc-behaviortree ``` 2. 下载扩展插件(bt-editor) 3. 项目脚本中引入库文件 ```typescript // 比如在项目代码目录下添加一个文件 header.ts // 写上如下代码 import * as BT from "kunpocc-behaviortree"; export { BT }; ``` 4. 重启creator 5. 启用插件 * 在 Cocos Creator 中选择 `扩展` -> `扩展管理器` -> `已安装扩展` * 找到 `bt-editor` 并启用 6. 打开扩展面板 * 在 Cocos Creator 顶部菜单栏中选择 `kunpo` -> `行为树编辑器` 7. 创建第一颗行为树 (见下方 `导出文件使用` 部分) ## 三、自定义节点 (扩展编辑器节点池) ### 节点装饰器 装饰器系统是连接自定义节点和编辑器的桥梁 只有通过装饰器装饰的节点，才能在编辑器中的节点池中显示 #### @ClassAction - 行为节点装饰器 用于装饰执行具体逻辑的叶子节点。 ```typescript @BT.ClassAction("NodeName", { name: "显示名称", group: "节点分组", desc: "节点描述" }) export class MyActionNode extends BT.LeafNode { public tick(): BT.Status { // 执行逻辑 return BT.Status.SUCCESS; } } ``` #### @ClassCondition - 条件节点装饰器 用于装饰判断条件的节点。 ```typescript @BT.ClassCondition("ConditionName", { name: "条件名称", group: "条件分组", desc: "节点描述" }) export class MyCondition extends BT.Condition { protected isEligible(): boolean { // 返回判断结果 return true; } } ``` #### @ClassComposite - 组合节点装饰器 用于装饰控制子节点执行流程的组合节点。 ```typescript @BT.ClassComposite("CompositeName", { name: "组合名称", group: "组合分组", desc: "节点描述" }) export class MyComposite extends BT.Composite { public tick(dt: number): BT.Status { // 控制子节点执行逻辑 for (const child of this.children) { const status = child._execute(dt); if (status !== BT.Status.SUCCESS) { return status; } } return BT.Status.SUCCESS; } } ``` #### @ClassDecorator - 装饰节点装饰器 用于装饰修改单个子节点行为的装饰节点。 ```typescript @BT.ClassDecorator("DecoratorName", { name: "装饰名称", group: "装饰分组", desc: "节点描述" }) export class MyDecorator extends BT.Decorator { public tick(dt: number): BT.Status { // 装饰逻辑，修改子节点行为 return this.children[0]._execute(dt); } } ``` ### 节点属性装饰器 (扩展节点参数) 为节点添加可在编辑器中配置的参数。 ```typescript @BT.ClassAction("NodeName", { name: "显示名称", group: "节点分组", desc: "节点描述" }) export class MyNode extends BT.LeafNode { // 基础类型参数 @BT.prop({ type: BT.ParamType.string, description: "动画名称", defaultValue: "idle" }) private animationName: string = "idle"; @BT.prop({ type: BT.ParamType.float, description: "速度", min: 0, max: 10, step: 0.1, defaultValue: 1.0 }) private speed: number = 1.0; @BT.prop({ type: BT.ParamType.bool, description: "是否循环" }) private loop: boolean = false; // 对象参数 @BT.prop({ type: BT.ParamType.object, description: "位置信息", properties: { x: { type: BT.ParamType.int, min: 0 }, y: { type: BT.ParamType.int, min: 0 } } }) private position: { x: number, y: number }; // 数组参数 @BT.prop({ type: BT.ParamType.array, description: "巡逻点列表", itemType: BT.ParamType.object, itemProperties: { x: { type: BT.ParamType.float }, y: { type: BT.ParamType.float }, name: { type: BT.ParamType.string } } }) private patrolPoints: Array<{ x: number, y: number, name: string }>; } ``` #### 参数类型详解 | 类型 | BT.ParamType | 描述 | 支持属性 | |------|--------------|------|----------| | 整数 | `int` | 整数类型 | `min`, `max`, `step`, `defaultValue` | | 浮点数 | `float` | 浮点数类型 | `min`, `max`, `step`, `defaultValue` | | 字符串 | `string` | 字符串类型 | `defaultValue` | | 布尔 | `bool` | 布尔类型 | `defaultValue` | | 对象 | `object` | 对象类型 | `properties` | | 数组 | `array` | 数组类型 | `itemType`, `itemProperties` | ## 四、编辑器介绍 #### 快捷键 - **打开编辑器**: `Ctrl+Shift+K` (Windows) / `Cmd+Shift+K` (Mac) - **导出配置**: `Ctrl+Shift+L` (Windows) / `Cmd+Shift+L` (Mac) #### 菜单访问 在 Cocos Creator 顶部菜单栏中选择 `kunpo` -> `行为树编辑器` ### 编辑器功能介绍 行为树编辑器提供了一个直观的可视化界面，让你可以轻松创建和管理复杂的行为树结构。 #### 核心功能 ##### 可视化节点编辑 - **拖拽创建**：从左侧节点库拖拽节点到画布中 - **分组管理**：节点按功能分组显示，便于查找 - **实时预览**：节点显示类型图标和描述信息 ##### 属性参数配置 - **智能表单**：根据`@prop`装饰器自动生成配置界面 - **类型校验**：支持数字、字符串、布尔值、对象、数组等类型 - **默认值**：自动填充装饰器中定义的默认值 - **约束验证**：支持最小值、最大值、步长等约束条件 ##### 连接线管理 - **可视连接**：通过拖拽连接点创建父子关系 - **自动布局**：连接线自动避让，保持界面整洁 - **连接验证**：防止创建非法的节点连接关系 ##### 画布操作 - **缩放平移**：鼠标滚轮缩放，拖拽平移画布 - **多选操作**：支持框选多个节点进行批量操作 ##### 节点管理 - **别名设置**：为节点设置有意义的别名，便于理解 - **复制粘贴**：快速复制节点及其子树结构 - **删除操作**：删除节点时自动清理相关连接 ##### 编辑器界面布局 ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ 顶部工具栏 │ │ [设置导出路径] [过滤行为树] [选择行为树▼] [导出配置] │ ├─────────────┬─────────────────────────────────────────────┬─────────────────┤ │ │ │ │ │ 节点库 │ │ 右侧面板 │ │ (左侧) │ │ │ │ │ ┌───────────────────────────────────────┐ │ ┌──────────────┐│ │ • 行为节点 │ │ 画布工具栏 │ │ │ 行为树名称 │ │ │ • 条件节点 │ │ [缩放] [重置] [清空] [复制] [粘贴] │ │ │ 行为树描述 │ │ │ • 组合节点 │ └─────────────────────────────────────────┘ │ └──────────────┘ │ │ • 装饰节点 │ │ │ │ • 内置节点 │ ┌─────────────────────────────────────────┐ │ ┌──────────────┐ │ │ │ │ │ │ │ │ │ │ │ │ 画布操作区 │ │ │ 节点参数区 │ │ │ │ │ │ │ │ │ │ │ │ │ ┌─────┐ │ │ │ • 节点名称 │ │ │ │ │ │根节点│ │ │ │ • 参数配置 │ │ │ │ │ └──┬──┘ │ │ │ • 描述信息 │ │ │ │ │ │ │ │ │ • 别名设置 │ │ │ │ │ ┌──▼──┐ ┌──────┐ │ │ │ │ │ │ │ │ │子节点│ │子节点│ │ │ └──────────────┘ │ │ │ │ └─────┘ └──────┘ │ │ │ │ │ │ │ │ ┌──────────────┐ │ │ │ │ │ │ │ [删除行为树] │ │ │ │ └────────────────────────────────────────┘ │ │ [创建新树] │ │ │ │ │ └──────────────┘ │ └────────────┴──────────────────────────────────────────────┴──────────────────┘ ``` ### 导出文件使用 #### 在项目中使用导出配置 ##### 1. 配置文件格式 ```json { "boss1": [ { "id": "1758206972710_bhxebhy7o", "className": "Sequence", "parameters": {}, "children": [ "1758090634327_mf36nwkdt" ] }, { "id": "1758090634327_mf36nwkdt", "className": "Selector", "parameters": {}, "children": [ "1758206988178_55b7kk5va" ] }, { "id": "1758206988178_55b7kk5va", "className": "BTAnimation", "parameters": { "_name": "", "_loop": false }, "children": [] } ] } ``` ##### 2. 配置文件放入项目资源目录 将从编辑器导出的JSON文件放入项目资源目录 自行加载配置数据 ``` assets/ ├── resources/ │ └── config/ │ ├── bt_config.json // 所有行为树的信息都在这个里边 ``` ##### 3. 创建行为树实例 * BT.createBehaviorTree(config["boss1"], entity); * 函数详解 ```typescript // 工厂函数签名 function createBehaviorTree(config: INodeConfig[], entity: T): BehaviorTree // 内部工作流程： // 1. 验证配置格式 // 2. 创建节点映射表 (id -> config) // 3. 递归创建节点树 // - 通过className查找构造函数 // - 根据节点类型选择创建方式 // - 设置节点参数 // - 建立父子关系 // 4. 返回行为树实例 ``` ## 五、更新声明 ## 0.0.1 (2025-09-23) - 首版本 ## 六、联系作者 * 邮箱: gong.xinhai@163.com * 微信: G0900901 * 扫码加微信: ## 七、版权声明 此插件源代码可商业使用 商业授权范围仅限于在您自行开发的游戏作品中使用 不得进行任何形式的转售、租赁、传播等 ## 八、购买须知 本产品为付费虚拟商品，一经购买成功概不退款，请在购买前谨慎确认购买内容。