<1> LimboAI Documentation
<2> <b>LimboAI</b> is an open-source C++ module for <b>Godot Engine 4</b> providing a combination of <b>Behavior Trees</b> and <b>State Machines</b> for crafting your game’s AI. It comes with a behavior tree editor, built-in documentation, visual debugger, and more! While it is implemented in C++, it fully supports GDScript for <l1>creating your own tasks</l> and states. The full list of features is available on the <l2>LimboAI GitHub</l> page.
<3> <b>Behavior Trees</b> are powerful hierarchical structures used to model and control the behavior of agents in a game (e.g., characters, enemies, entities). They are designed to make it easier to create complex and highly modular behaviors for your games. To learn more about behavior trees, check out <l1>Introduction to Behavior Trees</l>.
<4> <b>Hierarchical State Machines</b> are finite state machines that allow any state to host their own sub-state machine. This allows you to tackle your AI’s state and transition complexity by breaking down one big state machine into multiple smaller ones.
<5> Getting LimboAI
<6> LimboAI can be used as either a C++ module or as a GDExtension shared library. There are some differences between the two. In short, GDExtension version is more convenient to use but somewhat limited in features. The module version provides better editor experience and is slightly more performant, but it requires using custom engine builds including the export templates. Whichever you choose to use, your project will stay compatible with both and you can switch from one to the other any time.
<7> Choose the version you’d like to use. If you’re unsure, start with the GDExtension version. You can change your decision at any time - both versions are fully compatible.
<8> Get GDExtension version
<9> Precompiled builds are available on the official <l1>LimboAI GitHub</l> page, and in the Asset Library.
<10> GDExtension is the most convenient way of using the LimboAI plugin, but it comes with certain limitations:
<11> Documentation tooltips are not available.
<12> Handy <l1>BBParam</l> property editor is not available in the extension due to dependencies on the engine classes that are not available in the Godot API.
<13> <b>🛈 See also:</b> <l1>What is GDExtension?</l>
<14> Installation instructions:
<15> Make sure you’re using the latest stable version of the Godot editor.
<16> Create a new project for your experiments with LimboAI.
<17> In Godot, click AssetLib tab at the top of the screen and search for LimboAI. Download it. LimboAI plugin will be downloaded with the demo project files. Don’t mind the errors printed at this point, this is due to the extension library not being loaded just yet.
<18> Reload your project with Project -> Reload project. There shouldn’t be any errors printed now.
<19> In the project files, locate a scene file called showcase.tscn and run it. It’s the demo’s entry point.
<20> Get module version
<21> Precompiled builds are available on the official <l1>LimboAI GitHub</l> page.
<22> In <l1>GitHub releases</l>, download the latest pre-compiled release build for your platform.
<23> Download the demo project archive from the same release.
<24> Extract the pre-compiled editor and the demo project files.
<25> Launch the pre-compiled editor binary, import and open the demo project.
<26> Run the project.
<27> <b>Important</b>: To export your game using the module version of LimboAI, make sure to use the pre-compiled export templates included in the same GitHub release build.
<28> Using LimboAI with C#
<29> Here’s how you can use the module version with C# to write your tasks and states.
<30> Locate LimboAI NuGet package files.
<31> Each provided build comes with a GodotSharp folder, which has packages under “GodotSharp/Tools/nupkgs/”. Note down the directory path; you’ll need it in the next step.
<32> Add a local source for NuGet packages using the following command:
<33> Your C# project should be able to see LimboAI classes and compile.
<34> Regarding GDExtension, I can only confirm success with the module version and C#. Unfortunately, I haven’t had any luck with the GDExtension version yet. If you’ve had success with GDExtension, please let me know via Discord or email.
<35> Contributing
<36> We target the latest stable version of the Godot Engine for development until a third beta or a release candidate of an upcoming Godot release becomes available. If you want to contribute to the project, please ensure that you are using the corresponding Godot version.
<37> We follow the <l1>Godot code style guidelines</l>. Please use <2/> to maintain consistent styling. You can install <3/> hooks for Git using <4/> to automate this process.
<38> Please keep the minor versions backward-compatible when submitting pull requests.
<39> We support building LimboAI as a module for the Godot Engine and as a GDExtension library. Make sure your contribution is compatible with both. Our CI workflow will verify that your changes can be compiled in both configurations.
<40> Compiling as module of the Godot Engine
<41> Clone the Godot Engine repository.
<42> Switch to the latest stable tag.
<43> Clone the LimboAI repository into the <1/> directory.
<44> Consult the <l1>Godot Engine documentation</l> for detailed instructions on building the engine.
<45> <b>Unit tests</b> can be compiled using the <1/> build option. To execute them, run the compiled Godot binary with the <2/> command-line options.
<46> Building C# Packages
<47> If you want C# Support for LimboAI when building from source, follow Godot’s instructions for building from source with C# Support: <l1>Compiling with .NET</l>. LimboAI’s classes will be included in the output from that build process.
<48> Compiling as GDExtension library
<49> You’ll need the SCons build tool and a C++ compiler. See also <l1>Compiling</l>. Run <2/> to build the plugin library for your current platform.
<50> SCons will automatically clone the <1/> repository if it doesn’t already exist in the <2/> directory.
<51> By default, built targets are placed in the demo project: <1/>.
<52> Check <1/> for other options and targets.
<53> Contributing to the documentation
<54> Online documentation is created using <l1>Sphinx</l>. Source files are located in the <2/> directory in RST format and can be built locally with <3/>. See the <l4>Sphinx documentation</l> for more details.
<55> Class documentation resides in XML files within the <1/> directory. If you create a new class or modify an existing one, you can run the compiled Godot binary with the <2/> option in the root of the Godot source code to generate the missing XML files or sections within those files in the class documentation. After editing the XML files, please run the compiled editor binary with the <3/> option again to update and tidy up the XML files.
<56> Sphinx RST files for the class documentation are generated from XML files using the Godot script <1/> and stored in the <2/> directory. This process is performed using our own script <3/>. RST files in <4/> should not be edited manually.
<57> Introduction to Behavior Trees
<58> <b>🛈 Note:</b> Demo project includes a tutorial that provides an introduction to behavior trees through illustrative examples.
<59> <b>Behavior Trees (BT)</b> are hierarchical structures used to model and control the behavior of agents in a game (e.g., characters, enemies, entities). They are designed to make it easier to create complex and highly modular behaviors for your games.
<60> Behavior Trees are composed of tasks that represent specific actions or decision-making rules. Tasks can be broadly categorized into two main types: control tasks and leaf tasks. <b>Control tasks</b> determine the execution flow within the tree. They include <l1>Sequence</l>, <l2>Selector</l>, and <l3>Invert</l>. <b>Leaf tasks</b> represent specific actions to perform, like moving or attacking, or conditions that need to be checked. The <l4>BTTask</l> class provides the foundation for various building blocks of the Behavior Trees. Such tasks can <l5>share data using the Blackboard</l>.
<61> <b>🛈 Note:</b> To <l1>create your own actions</l>, extend the <l2>BTAction</l> class.
<62> A Behavior Tree is usually processed each frame. It is traversed from top to bottom, with the control tasks determining the control flow. Each task has a <l1>_tick</l> method, which performs the task’s work and returns a status indicating its progress: <2/>, <3/>, or <4/>. <5/> and <6/> indicate the outcome of finished work, while <7/> status is returned when a task requires more than one tick to complete its job. These statuses determine how the tree progresses, with the <8/> status usually meaning that the tree will continue execution during the next frame.
<63> There are <i>four types of tasks</i>:
<64> <b>Actions</b> are leaf tasks that perform the actual work.
<65> Examples: <l1>PlayAnimation</l>, <l2>Wait</l>.
<66> <b>Conditions</b> are leaf tasks that conduct various checks.
<67> Examples: <l1>CheckVar</l>, <l2>InRange</l>.
<68> <b>Composites</b> can have one or more child tasks, and dictate the execution flow of their children.
<69> Examples: <l1>Sequence</l>, <l2>Selector</l>, <l3>Parallel</l>.
<70> <b>Decorators</b> can only have a single child and they change how their child task operates.
<71> Examples: <l1>AlwaysSucceed</l>, <l2>Invert</l>, <l3>TimeLimit</l>.
<72> <l1>Sequence</l> is one of the core composite tasks. It executes its child tasks sequentially, from first to last, until one of them returns <2/>, or all of them result in <3/>. In other words, if any child task results in <4/>, the <l5>Sequence</l> execution will be aborted, and the <l6>Sequence</l> itself will return <7/>.
<73> <l1>Selector</l> is another essential composite task. It executes its child tasks sequentially, from first to last, until one of them returns <2/> or all of them result in <3/>. In other words, when a child task results in <4/>, it moves on to the next one until it finds the one that returns <5/>. Once a child task results in <6/>, the <l7>Selector</l> stops and also returns <8/>. The purpose of the <l9>Selector</l> is to find a child that succeeds.
<74> Behavior Trees handle conditional logic using <b>condition tasks</b>. These tasks check for specific conditions and return either <1/> or <2/> based on the state of the agent or its environment (e.g., “IsLowOnHealth”, “IsTargetInSight”). Conditions can be used together with <l3>Sequence</l> and <l4>Selector</l> to craft your decision-making logic.
<75> <b>🛈 Note:</b> To <l1>create your own conditions</l>, extend the <l2>BTCondition</l> class.
<76> Check out the <l1>BTTask</l> class documentation, which provides the foundation for various building blocks of Behavior Trees.
<77> Creating Behavior Trees
<78> This chapter describes how to create and debug behavior trees.
<79> Add a Behavior Tree to an agent
<80> Follow these steps to add a behavior tree to a new or existing agent:
<81> Make a scene file for your agent, or open an existing scene.
<82> Add a <l1>BTPlayer</l> node to your scene.
<83> Select <l1>BTPlayer</l>, and create a new behavior tree in the inspector.
<84> Optionally, you can save the behavior tree to a file using the property’s context menu.
<85> Click the behavior tree property to open it in the LimboAI editor.
<86> Debugging Behavior Trees
<87> In Godot Engine, follow to “Bottom Panel > Debugger > LimboAI” tab. With the LimboAI debugger, you can inspect any currently active behavior tree within the running project. The debugger can be detached from the main editor window, which can be particularly useful if you have a HiDPI or a secondary display.