diff --git "a/\344\275\277\347\224\250\346\225\231\347\250\213.md" "b/\344\275\277\347\224\250\346\225\231\347\250\213.md" new file mode 100644 index 0000000..3451b4d --- /dev/null +++ "b/\344\275\277\347\224\250\346\225\231\347\250\213.md" @@ -0,0 +1,833 @@ +# Behavior3Editor 详细使用教程 + +## 📚 目录 + +1. [项目简介](#项目简介) +2. [安装与运行](#安装与运行) +3. [工作区配置](#工作区配置) +4. [节点定义配置](#节点定义配置) +5. [创建行为树](#创建行为树) +6. [编辑器界面详解](#编辑器界面详解) +7. [节点类型详解](#节点类型详解) +8. [变量系统](#变量系统) +9. [批处理脚本](#批处理脚本) +10. [导入导出](#导入导出) +11. [调试功能](#调试功能) +12. [快捷键](#快捷键) +13. [常见问题](#常见问题) +14. [进阶技巧](#进阶技巧) + +--- + +## 📖 项目简介 + +Behavior3Editor 是一个直观、可视化、通用的行为树编辑器，专为游戏开发中的 AI 逻辑设计而生。它允许策划人员自行实现复杂的 AI 行为、技能系统、buff 逻辑等，大大减少开发沟通成本，提升开发效率。 + +### 核心特性 + +- **可视化编辑**：拖拽式节点编辑，直观易用 +- **通用格式**：使用 JSON 格式保存，便于跨平台使用 +- **节点扩展**：支持自定义节点类型和参数 +- **批处理**：支持批量处理行为树文件 +- **多语言支持**：内置国际化支持 +- **调试功能**：提供行为树调试和可视化功能 + +### 技术栈 + +- **前端**：React + TypeScript + Ant Design +- **图形引擎**：AntV G6 +- **桌面应用**：Electron +- **样式**：Tailwind CSS + Sass + +--- + +## 🚀 安装与运行 + +### 环境要求 + +- Node.js 18.0+ +- npm 或 yarn + +### 安装步骤 + +1. **克隆项目** +```bash +git clone https://github.com/zhandouxiaojiji/behavior3editor.git +cd behavior3editor +``` + +2. **安装依赖** +```bash +npm install +``` + +3. **开发模式运行** +```bash +npm run dev +``` + +4. **构建桌面应用** +```bash +npm run build +``` + +### 脚本说明 + +- `npm run dev` - 启动开发服务器 +- `npm run build` - 构建生产版本 +- `npm run preview` - 预览构建结果 +- `npm run test` - 运行测试 +- `npm run tsc-check` - TypeScript 类型检查 + +--- + +## 🔧 工作区配置 + +### 工作区文件结构 + +``` +项目目录/ +├── workspace.b3-workspace # 工作区配置文件 +├── node-config.b3-setting # 节点定义配置 +├── workdir/ # 行为树文件目录 +│ ├── hero.json # 英雄AI行为树 +│ ├── monster.json # 怪物AI行为树 +│ └── sub/ # 子树目录 +├── vars/ # 变量定义目录 +├── scripts/ # 批处理脚本目录 +└── icons/ # 图标资源目录 +``` + +### 工作区配置文件 (workspace.b3-workspace) + +```json +{ + "files": [ + { + "path": "workdir/hero.json", + "desc": "英雄测试AI" + }, + { + "path": "workdir/monster.json", + "desc": "怪物测试AI" + } + ], + "settings": { + "checkExpr": true, // 是否检查表达式语法 + "buildScript": "scripts/build.js" // 构建脚本路径 + } +} +``` + +### 创建新工作区 + +1. 启动编辑器 +2. 选择 **文件 > 新建工作区** +3. 选择项目目录 +4. 配置节点定义文件路径 +5. 设置工作区参数 + +--- + +## 🎯 节点定义配置 + +### 节点定义格式 + +节点定义使用 JSON 格式，定义了行为树中可用的所有节点类型： + +```typescript +interface NodeDef { + name: string; // 节点名称 + type: "Action" | "Decorator" | "Condition" | "Composite"; // 节点类型 + desc: string; // 节点描述 + icon?: string; // 图标 + color?: string; // 颜色 + input?: string[]; // 输入变量 + output?: string[]; // 输出变量 + args?: { // 参数定义 + name: string; + type: string; // 参数类型 + desc: string; + default?: unknown; + options?: { name: string; value: unknown }[]; + }[]; + children?: -1 | 0 | 1 | 3; // 允许的子节点数量 + doc?: string; // 文档说明(markdown格式) +} +``` + +### 参数类型 + +支持的参数类型包括： + +- **基础类型**：`boolean`, `int`, `float`, `string` +- **数组类型**：`boolean[]`, `int[]`, `float[]`, `string[]` +- **可选类型**：添加 `?` 后缀，如 `string?` +- **特殊类型**： + - `json` - JSON 对象 + - `expr` - 表达式 + - `code` - 代码片段 + +### 示例节点定义 + +```json +{ + "name": "Wait", + "type": "Action", + "desc": "等待指定时间", + "args": [ + { + "name": "time", + "type": "float", + "desc": "等待时间(秒)", + "default": 1.0 + } + ], + "children": 0, + "doc": "# 等待节点\n\n暂停执行指定的时间，然后返回成功。" +} +``` + +--- + +## 🌳 创建行为树 + +### 新建行为树 + +1. **通过菜单创建** + - 文件 > 新建 > 行为树 + - 输入文件名和描述 + - 选择保存位置 + +2. **通过资源管理器创建** + - 右键点击目录 + - 选择"新建行为树" + - 填写基本信息 + +### 行为树文件结构 + +```json +{ + "version": "1.8.0", // 版本号 + "name": "hero", // 行为树名称 + "desc": "英雄测试AI", // 描述 + "firstid": 1, // 起始ID + "export": true, // 是否导出 + "group": ["Client", "Server"], // 分组标签 + "import": [], // 导入的子树 + "vars": [], // 变量定义 + "root": { // 根节点 + "id": 1, + "name": "Selector", + "desc": "根选择器", + "children": [...] + } +} +``` + +### 行为树属性配置 + +- **名称**：行为树的唯一标识 +- **描述**：行为树功能说明 +- **分组**：用于分类管理（如 Client、Server） +- **导出**：是否在构建时导出 +- **变量**：行为树内部变量定义 + +--- + +## 🖥️ 编辑器界面详解 + +### 主界面布局 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 标题栏 (Title Bar) │ +├─────────────────────────────────────────────────────────────┤ +│ 菜单栏 (Menu Bar) │ +├──────────────┬──────────────────────────┬─────────────────────┤ +│ │ │ │ +│ 资源管理器 │ 画布区域 │ 属性面板 │ +│ (Explorer) │ (Canvas) │ (Inspector) │ +│ │ │ │ +│ │ │ │ +│ │ │ │ +│ │ │ │ +└──────────────┴──────────────────────────┴─────────────────────┘ +``` + +### 资源管理器 (Explorer) + +**功能**： +- 显示工作区中的所有文件 +- 支持文件夹展开/折叠 +- 提供文件操作菜单 + +**操作**： +- **双击**：打开文件 +- **右键**：显示上下文菜单 +- **拖拽**：移动文件位置 + +### 画布区域 (Canvas) + +**功能**： +- 可视化显示行为树结构 +- 支持节点拖拽和连接 +- 提供缩放和平移功能 + +**操作**： +- **鼠标滚轮**：缩放画布 +- **中键拖拽**：平移画布 +- **左键拖拽**：移动节点 +- **右键点击**：显示上下文菜单 + +### 属性面板 (Inspector) + +**功能**： +- 显示选中节点的属性 +- 编辑节点参数 +- 配置输入输出变量 + +**面板内容**： +- **基本信息**：ID、名称、描述 +- **参数配置**：节点特有参数 +- **变量绑定**：输入输出变量 +- **调试信息**：节点状态和调试数据 + +--- + +## 📝 节点类型详解 + +### 1. 组合节点 (Composite) + +#### Selector (选择器) +- **功能**：依次执行子节点，直到有一个成功 +- **返回**：第一个成功的子节点结果 +- **用途**：实现"或"逻辑，如多种攻击方式选择 + +```json +{ + "name": "Selector", + "children": [ + {"name": "Attack"}, // 优先攻击 + {"name": "Patrol"} // 攻击失败则巡逻 + ] +} +``` + +#### Sequence (序列器) +- **功能**：依次执行子节点，直到有一个失败 +- **返回**：第一个失败的子节点结果，全部成功则返回成功 +- **用途**：实现"且"逻辑，如攻击序列 + +```json +{ + "name": "Sequence", + "children": [ + {"name": "FindEnemy"}, // 先找敌人 + {"name": "Attack"}, // 再攻击 + {"name": "Wait"} // 最后等待 + ] +} +``` + +#### Parallel (并行器) +- **功能**：同时执行所有子节点 +- **配置**：可设置成功/失败条件 +- **用途**：同时执行多个动作 + +#### RandomSelector (随机选择器) +- **功能**：随机选择一个子节点执行 +- **用途**：增加AI的随机性 + +### 2. 装饰器节点 (Decorator) + +#### Inverter (反转器) +- **功能**：反转子节点的执行结果 +- **转换**：成功→失败，失败→成功 + +#### AlwaysSuccess (始终成功) +- **功能**：不管子节点结果如何，始终返回成功 + +#### AlwaysFail (始终失败) +- **功能**：不管子节点结果如何，始终返回失败 + +#### Repeat (重复器) +- **功能**：重复执行子节点指定次数 +- **参数**：重复次数 + +#### UntilSuccess (直到成功) +- **功能**：重复执行子节点直到成功 + +### 3. 条件节点 (Condition) + +#### Check (检查) +- **功能**：执行表达式判断，返回真/假 +- **参数**：布尔表达式 + +```json +{ + "name": "Check", + "args": { + "value": "hp > 50" // 血量大于50 + } +} +``` + +#### IsNull (空值判断) +- **功能**：判断变量是否为空 +- **输入**：要判断的变量名 + +### 4. 动作节点 (Action) + +#### Wait (等待) +- **功能**：等待指定时间 +- **参数**：等待时间（秒） + +#### Log (日志) +- **功能**：输出日志信息 +- **参数**：日志内容 + +#### Set (设置变量) +- **功能**：设置变量值 +- **参数**：变量名和值 + +#### Clear (清除变量) +- **功能**：清除指定变量 +- **输出**：被清除的变量名 + +--- + +## 🔄 变量系统 + +### 变量类型 + +1. **局部变量**：仅在当前行为树中有效 +2. **全局变量**：在所有行为树中共享 +3. **输入变量**：从父节点传入 +4. **输出变量**：传递给子节点 + +### 变量定义 + +在行为树文件中定义： + +```json +{ + "vars": [ + { + "name": "enemy", + "desc": "当前敌人目标" + }, + { + "name": "health", + "desc": "当前血量" + } + ] +} +``` + +### 变量使用 + +#### 输入变量 +节点可以声明需要的输入变量： + +```json +{ + "name": "Attack", + "input": ["enemy", "weapon"] // 需要敌人和武器变量 +} +``` + +#### 输出变量 +节点可以输出变量供其他节点使用： + +```json +{ + "name": "FindEnemy", + "output": ["enemy"] // 输出找到的敌人 +} +``` + +#### 参数中使用变量 +在节点参数中可以使用表达式引用变量： + +```json +{ + "name": "Wait", + "args": { + "time": "${attackSpeed}" // 使用变量 + } +} +``` + +### 表达式语法 + +支持丰富的表达式语法： + +- **算术运算**：`+`, `-`, `*`, `/`, `%` +- **比较运算**：`>`, `<`, `>=`, `<=`, `==`, `!=` +- **逻辑运算**：`&&`, `||`, `!` +- **变量引用**：`${varName}` +- **函数调用**：`min(a, b)`, `max(a, b)`, `abs(x)` + +--- + +## ⚙️ 批处理脚本 + +### 脚本功能 + +批处理脚本允许你在构建时自动处理行为树文件，实现： + +- 代码生成 +- 数据验证 +- 格式转换 +- 优化处理 + +### 脚本接口 + +```typescript +interface BatchScript { + onSetup?(env: Env): void; // 初始化 + onProcessTree?(tree: TreeModel, path: string): TreeModel | null; // 处理树 + onProcessNode?(node: NodeModel, tree: TreeModel): NodeModel | null; // 处理节点 + onWriteFile?(path: string, tree: TreeModel): void; // 写入文件 + onComplete?(status: "success" | "failure"): void; // 完成回调 +} +``` + +### 环境对象 (Env) + +```typescript +interface Env { + workdir: string; // 工作目录 + nodeDefs: Map; // 节点定义映射 + path: typeof import('path'); // 路径工具 + fs: typeof import('fs'); // 文件系统 +} +``` + +### 示例脚本 + +```javascript +// scripts/build.js +export const onSetup = (env) => { + console.log("构建开始", env.workdir); +}; + +export const onProcessTree = (tree) => { + // 为树添加版本信息 + tree.buildTime = new Date().toISOString(); + return tree; +}; + +export const onProcessNode = (node, tree) => { + // 验证节点配置 + if (node.name === "Attack" && !node.input?.includes("enemy")) { + console.warn(`${tree.name}: Attack节点缺少enemy输入`); + } + return node; +}; + +export const onComplete = (status) => { + console.log("构建完成:", status); +}; +``` + +### 运行批处理 + +1. **通过菜单**：工具 > 运行批处理脚本 +2. **通过命令**：在工作区设置中配置构建脚本 +3. **自动运行**：构建时自动执行 + +--- + +## 📤 导入导出 + +### 导出格式 + +支持多种导出格式： + +1. **JSON**：原生格式，保留完整信息 +2. **Lua**：适用于Lua游戏引擎 +3. **JavaScript/TypeScript**：适用于Web/Node.js +4. **XML**：通用标记语言格式 + +### 导出配置 + +在行为树文件中设置： + +```json +{ + "export": true, // 是否导出 + "group": ["Client"], // 导出分组 +} +``` + +### 子树导入 + +支持导入其他行为树作为子树： + +```json +{ + "import": [ + "sub/common_attack", // 导入公共攻击逻辑 + "sub/patrol_logic" // 导入巡逻逻辑 + ] +} +``` + +### 批量导出 + +1. 选择要导出的文件 +2. 工具 > 批量导出 +3. 选择导出格式和目录 +4. 点击开始导出 + +--- + +## 🐛 调试功能 + +### 调试模式 + +启用调试模式后，可以： + +- 实时查看节点执行状态 +- 设置断点 +- 单步执行 +- 查看变量值 + +### 调试信息显示 + +节点会显示不同的状态颜色： + +- **绿色**：执行成功 +- **红色**：执行失败 +- **黄色**：正在执行 +- **灰色**：未执行 + +### 日志输出 + +使用Log节点输出调试信息： + +```json +{ + "name": "Log", + "args": { + "text": "攻击敌人: ${enemy.name}" + } +} +``` + +### 断点设置 + +1. 右键点击节点 +2. 选择"设置断点" +3. 运行时会在此处暂停 + +--- + +## ⌨️ 快捷键 + +### 编辑快捷键 + +- `Ctrl + N` - 新建文件 +- `Ctrl + O` - 打开文件 +- `Ctrl + S` - 保存文件 +- `Ctrl + Z` - 撤销 +- `Ctrl + Y` - 重做 +- `Ctrl + C` - 复制节点 +- `Ctrl + V` - 粘贴节点 +- `Delete` - 删除节点 + +### 视图快捷键 + +- `Ctrl + +` - 放大画布 +- `Ctrl + -` - 缩小画布 +- `Ctrl + 0` - 重置缩放 +- `F` - 适应窗口 +- `Ctrl + F` - 查找节点 + +### 调试快捷键 + +- `F5` - 开始调试 +- `F9` - 设置断点 +- `F10` - 单步执行 +- `Shift + F5` - 停止调试 + +--- + +## ❓ 常见问题 + +### Q: 如何创建自定义节点？ + +A: +1. 编辑 `node-config.b3-setting` 文件 +2. 添加新的节点定义 +3. 重新加载工作区 + +示例： +```json +{ + "name": "CustomAction", + "type": "Action", + "desc": "自定义动作", + "args": [ + { + "name": "param1", + "type": "string", + "desc": "参数1" + } + ] +} +``` + +### Q: 如何在不同行为树间共享子树？ + +A: +1. 将共享逻辑提取为独立的行为树文件 +2. 在需要使用的地方通过 `import` 引入 +3. 使用 SubTree 节点调用 + +### Q: 表达式不生效怎么办？ + +A: +1. 检查变量名是否正确 +2. 确认表达式语法是否正确 +3. 在工作区设置中启用 `checkExpr` +4. 查看控制台错误信息 + +### Q: 如何提高大型行为树的编辑性能？ + +A: +1. 将复杂逻辑拆分为多个子树 +2. 使用分组功能组织节点 +3. 适当使用注释说明节点功能 +4. 定期清理未使用的节点 + +### Q: 导出的文件格式不正确？ + +A: +1. 检查批处理脚本是否正确 +2. 确认导出配置是否正确 +3. 查看构建日志中的错误信息 +4. 验证节点定义是否完整 + +--- + +## 🚀 进阶技巧 + +### 1. 节点模板 + +创建常用的节点组合模板： + +```json +{ + "name": "AttackSequence", + "template": { + "name": "Sequence", + "children": [ + {"name": "FindEnemy"}, + {"name": "MoveTo"}, + {"name": "Attack"}, + {"name": "Wait", "args": {"time": 1}} + ] + } +} +``` + +### 2. 条件表达式优化 + +使用复杂表达式减少节点数量： + +```javascript +// 替代多个Check节点 +"value": "hp > 50 && mp > 20 && !status.stunned" +``` + +### 3. 动态参数 + +使用变量让节点参数更灵活： + +```json +{ + "name": "Wait", + "args": { + "time": "${config.attackCooldown}" + } +} +``` + +### 4. 状态机集成 + +将行为树与状态机结合： + +```json +{ + "name": "CheckState", + "args": { + "value": "state == 'combat'" + } +} +``` + +### 5. 性能优化 + +- 避免深层嵌套 +- 合理使用并行节点 +- 减少不必要的条件检查 +- 使用缓存减少重复计算 + +### 6. 团队协作 + +- 制定节点命名规范 +- 使用统一的变量命名 +- 编写详细的节点文档 +- 定期代码审查 + +### 7. 版本管理 + +- 使用Git管理行为树文件 +- 为重要版本打标签 +- 记录重要修改的变更日志 +- 建立分支管理策略 + +--- + +## 📚 相关资源 + +### 官方资源 + +- **GitHub仓库**：https://github.com/zhandouxiaojiji/behavior3editor +- **问题反馈**：https://github.com/zhandouxiaojiji/behavior3editor/issues +- **QQ交流群**：644761605 + +### 示例项目 + +- **Lua版本**：[behavior3lua](https://github.com/zhandouxiaojiji/behavior3lua) +- **TypeScript版本**：[behavior3-ts](https://github.com/zhongfq/behavior3-ts) + +### 学习资料 + +- 行为树基础理论 +- 游戏AI设计模式 +- 状态机与行为树对比 +- 性能优化最佳实践 + +--- + +## 📝 更新日志 + +### v1.8.3 (最新版本) +- 优化编辑器性能 +- 新增批处理脚本功能 +- 改进变量系统 +- 修复已知问题 + +### 未来计划 +- 添加更多节点类型 +- 改进调试功能 +- 支持插件系统 +- 增强团队协作功能 + +--- + +*本教程将持续更新，如有疑问或建议，欢迎在GitHub上提出Issue或加入QQ群交流！* \ No newline at end of file