LimboAI - 适用于 Godot 4 的行为树与状态机

支持的 Godot 引擎版本: 4.6 (较旧版本请见下方)

LimboAI 是一个开源的 C++ 插件，专为 Godot 引擎 4 设计，提供了 行为树 和 状态机 的组合，两者可以协同工作以创建复杂的 AI 行为。它自带行为树编辑器、内置文档、可视化调试器、包含教程的丰富示例项目等！尽管它是用 C++ 实现的，但它完全支持 GDScript，可用于 创建自定义任务 和 状态。

如果您喜欢使用 LimboAI，请考虑通过 Ko-fi 向我捐款以支持我的开发工作 😊 您的支持将帮助我继续改进和优化它。

行为树是一种强大的层次化结构，用于建模和控制游戏中智能体（如角色、敌人）的行为。它们旨在让开发者更轻松地为游戏创建丰富且高度模块化的行为逻辑。要深入了解行为树，请参阅 行为树简介 以及我们的示例项目，其中包含详细的教程。

展示

[!注意] 示例项目 位于 demo 文件夹中，并在 发布页面 中单独提供。 运行 demo/scenes/showcase.tscn 即可开始体验。 该项目还包含一个教程，通过生动的示例介绍行为树的概念。

视频

由不同创作者制作的 YouTube 视频

支持的 Godot 版本

插件版本	GDExtension/AssetLib	模块
1.7.x 版本	Godot 4.6 或更高	Godot 4.6
1.6.x 版本	Godot 4.4、4.5、4.6	Godot 4.6
1.5.x 版本	Godot 4.4、4.5	Godot 4.5
1.4.x 版本	Godot 4.4、4.5	Godot 4.4
1.2.0-1.3.x 版本	Godot 4.3	Godot 4.3
1.1.x 版本	Godot 4.2	Godot 4.2

功能特性

• 行为树（BT）：

  • 在编辑器中轻松创建、编辑和保存 BehaviorTree 资源。
  • 使用 BTPlayer 节点执行 BehaviorTree 资源。
  • 通过组合和嵌套任务构建复杂的层级行为。
  • 利用复合、装饰器和条件任务控制执行流程。
  • 通过扩展核心类 BTAction、BTCondition、BTDecorator 和 BTComposite，创建自定义任务。
  • 内置类文档。
  • 黑板系统：使用 Blackboard 在任务之间无缝共享数据。
    • 黑板计划：在 BehaviorTree 资源中定义变量，并在 BTPlayer 节点中覆盖其值。
    • 计划编辑器：管理变量、其数据类型和属性提示。
    • 黑板作用域：防止名称冲突，并支持高级技术，例如 在多个智能体之间共享数据。
    • 黑板参数：导出 BB 参数，用户可以为其提供值，或将其绑定到黑板变量（可在自定义任务中使用）。
    • 检查器支持指定黑板变量（为以 _var 结尾的导出 StringName 属性提供自定义编辑器）。
  • 使用 BTSubtree 任务从其他资源文件中执行子树，从而提高组织性和可重用性。
  • 可视化调试器：在运行场景中检查任意 BT 的执行情况，以便识别和排查问题。
  • 使用 BehaviorTreeView 节点在游戏中可视化 BT（用于自定义游戏内工具）。
  • 通过自定义性能监控器监测树的性能。

• 层次状态机（HSM）：

  • 扩展 LimboState 类以实现状态逻辑。
  • LimboHSM 节点作为状态机，管理 LimboState 实例及其转换。
  • LimboHSM 本身也是一个状态，可以嵌套在其他 LimboHSM 实例中。
  • 基于事件：转换与事件相关联，当相关事件被分发时由状态机触发，从而更好地解耦转换与状态逻辑。
  • 使用 BTState 将状态机与行为树结合，实现高级反应式 AI。
  • 委托选项：使用原生 LimboState，将实现委托给您的回调函数，非常适合快速原型设计和游戏开发马拉松。
  • 注意：状态机的设置和初始化需要编写代码；没有 GUI 编辑器。

• 已测试： 行为树任务和 HSM 均有单元测试覆盖。

• GDExtension： LimboAI 可以作为 扩展使用。无需自定义引擎构建。

• 示例 + 教程： 请查看我们的大型示例项目，其中包含使用示例介绍行为树的内容。

入门步骤

请按照 入门指南 学习如何开始使用 LimboAI 和示例项目。

获取 LimboAI

LimboAI 可以作为 C++ 模块或 GDExtension 共享库使用。GDExtension 版本使用起来更方便，但功能上有所限制。无论您选择哪种方式，您的项目都将同时兼容两者，并且可以随时切换。请参阅 使用 GDExtension。

预编译版本

• 对于最新版本，请前往 Actions → All Builds，从列表中选择一个构建，然后向下滚动至 Artifacts 部分。
• 对于发布版本，请查看 Releases。

从源码编译

• 下载 Godot 引擎源代码，并将本模块源代码放入 modules/limboai 目录。
• 请参考 Godot 引擎文档，了解 如何从源码编译。
• 如果您计划导出使用 LimboAI 模块的游戏，还需要构建导出模板。
• 要运行单元测试，需使用 tests=yes 编译引擎，并以 --test --tc="*[LimboAI]*" 运行。

对于 GDExtension

• 您需要 SCons 构建工具和 C++ 编译器。更多信息请参阅 编译指南。
• 运行 scons target=editor 以构建适用于您当前平台的插件库。
  • 如果 limboai/godot-cpp 目录中尚未存在 godot-cpp/ 仓库，SCons 会自动克隆该仓库。
  • 默认情况下，构建的目标文件会放置在示例项目中：demo/addons/limboai/bin/。
• 请查阅 scons -h 以获取其他选项和目标。

使用插件

• 在线文档：稳定版、最新版
• 入门指南
• 行为树简介
• 在 GDScript 中创建自定义任务
• 使用黑板共享数据
• 访问场景树中的节点
• 状态机
• 使用 GDExtension
• 使用 LimboAI 与 C#
• 类参考

贡献

我们欢迎任何贡献！请针对 bug 报告、功能请求或代码更改提交问题。 有关参与代码或文档贡献的详细指南，请参阅我们的 贡献页面。

如果您对行为树任务或可在多种项目中使用的功能有任何想法，请提交一个问题进行讨论。

社交

需要帮助吗？我们有一个 Discord 服务器：https://discord.gg/N5MGC95GpP

我在 Mastodon 上分享 LimboAI 的开发进展：https://mastodon.gamedev.place/@limbo。

许可证

本源代码的使用受 MIT 许可证约束，该许可证可在 LICENSE 文件中找到，或访问 https://opensource.org/licenses/MIT 查阅。

LimboAI 的 logo 和演示项目美术资源采用知识共享署名 4.0 国际许可协议授权，详情请参见 https://creativecommons.org/licenses/by/4.0/。

LimboAI 快速上手指南

LimboAI 是一款专为 Godot Engine 4 设计的开源 C++ 插件，集成了行为树 (Behavior Trees) 和 分层状态机 (Hierarchical State Machines)。它提供了可视化的行为树编辑器、内置文档、可视化调试器以及丰富的演示项目，支持使用 GDScript 编写自定义任务，是构建复杂游戏 AI 的强大工具。

环境准备

在开始之前，请确保满足以下要求：

• Godot Engine 版本：
  • 推荐使用 Godot 4.6（对应插件 1.7.x 版本）。
  • 若使用旧版本 Godot (4.2 - 4.5)，请参考 README 中的版本对照表选择对应的插件版本。
• 操作系统：Windows, macOS, 或 Linux。
• 前置依赖（仅源码编译需要）：
  • SCons：构建工具。
  • C++ 编译器：如 MSVC (Windows), Xcode Command Line Tools (macOS), 或 GCC/Clang (Linux)。
  • Git：用于克隆仓库。

注意：大多数用户推荐直接使用 GDExtension 预编译版本，无需安装 C++ 编译环境即可快速上手。

安装步骤

你可以通过下载预编译库或使用源码编译两种方式安装。

方法一：使用预编译版本（推荐）

这是最便捷的方式，适用于快速集成到现有项目中。

1. 下载插件：
   • 访问 Releases 页面 下载最新稳定版的压缩包。
   • 或者访问 Actions -> All Builds 获取最新的开发构建版（点击最近的构建记录，向下滚动找到 Artifacts 下载）。
2. 解压文件：
   • 将下载的压缩包解压。
   • 找到 addons 文件夹（通常包含 limboai 目录）。
3. 集成到项目：
   • 将整个 addons 文件夹复制到你 Godot 项目的根目录下。
   • 最终路径结构应为：你的项目/addons/limboai/。
4. 启用插件：
   • 打开 Godot 编辑器。
   • 进入菜单 项目 (Project) -> 项目设置 (Project Settings) -> 插件 (Plugins)。
   • 勾选 LimboAI 以启用它。

方法二：源码编译 (GDExtension)

如果你需要针对特定平台定制或贡献代码，可以选择此方式。

1. 克隆仓库：

   git clone https://github.com/limbonaut/limboai.git
   cd limboai
   

2. 执行编译： 运行 SCons 命令编译当前平台的编辑器库：

   scons target=editor
   

   • 系统会自动克隆 godot-cpp 依赖（如果不存在）。
   • 编译产物默认位于 demo/addons/limboai/bin/ 目录。
3. 部署： 将生成的 addons 目录复制到你的 Godot 项目中，并在编辑器中启用插件（同方法一步骤 4）。

基本使用

以下是一个创建简单行为树的最简示例。

1. 创建行为树资源

1. 在 Godot 编辑器的文件系统面板中，右键点击任意文件夹。
2. 选择 新建资源 (New Resource) -> 搜索并选择 BehaviorTree。
3. 保存该资源，例如命名为 enemy_ai.tres。
4. 双击打开该资源，将进入 LimboAI 行为树编辑器。

2. 构建简单的树结构

在编辑器中，通过右键菜单添加节点来构建逻辑。例如，创建一个“巡逻”逻辑：

1. 添加一个 Selector (选择器) 作为根节点（默认已有）。
2. 在 Selector 下添加一个 Sequence (序列) 节点。
3. 在 Sequence 下添加两个 Action (动作) 节点：
   • 第一个命名为 MoveToPatrolPoint。
   • 第二个命名为 Wait。
4. (可选) 选中 Action 节点，在检查器中关联具体的 GDScript 脚本以实现逻辑（详见下文）。

3. 在场景中运行行为树

1. 在你的场景中添加一个角色节点（如 CharacterBody2D 或 CharacterBody3D）。
2. 为该角色添加一个子节点：BTPlayer。
3. 选中 BTPlayer 节点，在检查器中找到 Behavior Tree 属性。
4. 将之前创建的 enemy_ai.tres 资源拖拽赋值给该属性。
5. 运行场景，BTPlayer 将自动开始执行行为树逻辑。

4. 编写自定义任务 (GDScript)

LimboAI 允许你用 GDScript 轻松创建自定义行为。创建一个新脚本并继承 BTAction：

class_name MoveToPatrolPoint
extends BTAction

@export var target_position: Vector2

func _tick(_delta: float) -> int:
    # 获取拥有该行为树的代理节点 (Agent)
    var agent = get_agent()
    
    if agent.global_position.distance_to(target_position) < 1.0:
        return SUCCESS # 任务成功
    
    # 执行移动逻辑 (伪代码)
    agent.move_toward(target_position, _delta)
    
    return RUNNING # 任务进行中，下一帧继续执行

• 返回值说明：
  • SUCCESS: 任务完成。
  • FAILURE: 任务失败。
  • RUNNING: 任务仍在执行中。

5. 调试

• 运行游戏时，点击编辑器底部的 LimboAI Debugger 标签页。
• 你可以实时查看行为树的执行流程、当前激活的节点以及黑板 (Blackboard) 中的数据变量，方便排查逻辑问题。

---

更多高级功能（如黑板数据共享、状态机组合、子树复用）请参阅官方文档或运行项目自带的 demo/scenes/showcase.tscn 示例场景。