Repository files navigation

Supported Godot Engine:4.4 - 4.5(see below for older versions)

LimboAI is an open-source C++ plugin forGodot Engine 4 providing a combination ofBehavior Trees andState Machines, which can be used together to create complex AI behaviors.It comes with a behavior tree editor, built-in documentation, visual debugger, extensive demo project with a tutorial, and more!While it is implemented in C++, it fully supports GDScript forcreating your own tasks andstates.

If you enjoy using LimboAI, pleaseconsider supporting my efforts with a donation on Ko-fi 😊 Your contribution will help me continue developing and improving it.

Behavior Trees are powerful hierarchical structures used to model and control the behavior of agents in a game (e.g., characters, enemies). They are designed to make it easier to create rich and highly modular behaviors for your games. To learn more about behavior trees, check outIntroduction to Behavior Trees and our demo project, which includes a tutorial.

YouTube videos produced by various creators

• Behavior Trees (BT):

  • Easily create, edit, and saveBehaviorTree resources in the editor.
  • ExecuteBehaviorTree resources using theBTPlayer node.
  • Create complex behaviors by combining and nesting tasks in a hierarchy.
  • Control execution flow using composite, decorator, and condition tasks.
  • Create custom tasks by extending core classes:BTAction,BTCondition,BTDecorator, andBTComposite.
  • Built-in class documentation.
  • Blackboard system: Share data seamlessly between tasks using theBlackboard.
    • Blackboard plans: Define variables in the BehaviorTree resource and override their values in the BTPlayer node.
    • Plan editor: Manage variables, their data types and property hints.
    • Blackboard scopes: Prevent name conflicts and enable advanced techniques likesharing data between several agents.
    • Blackboard parameters:Export a BB parameter, for which user can provide a value or bind it to a blackboard variable (can be used in custom tasks).
    • Inspector support for specifying blackboard variables (custom editor for exportedStringName properties ending with "_var").
  • Use theBTSubtree task to execute a tree from a different resource file, promoting organization and reusability.
  • Visual Debugger: Inspect the execution of any BT in a running scene to identify and troubleshoot issues.
  • Visualize BT in-game usingBehaviorTreeView node (for custom in-game tools).
  • Monitor tree performance with custom performance monitors.

• Hierarchical State Machines (HSM):

  • Extend theLimboState class to implement state logic.
  • LimboHSM node serves as a state machine that managesLimboState instances and transitions.
  • LimboHSM is a state itself and can be nested within otherLimboHSM instances.
  • Event-based: Transitions are associated with events and are triggered by the state machine when the relevant event is dispatched, allowing for better decoupling of transitions from state logic.
  • Combine state machines with behavior trees usingBTState for advanced reactive AI.
  • Delegation Option: Using the vanillaLimboState,delegate the implementation to your callback functions, making it perfect for rapid prototyping and game jams.
  • Note: State machine setup and initialization require code; there is no GUI editor.

• Tested: Behavior tree tasks and HSM are covered by unit tests.

• GDExtension: LimboAI can beused as extension. Custom engine builds are not necessary.

• Demo + Tutorial: Check out our extensive demo project, which includes an introduction to behavior trees using examples.

Follow theGetting started guide to learn how to get started with LimboAI and the demo project.

LimboAI can be used as either a C++ module or as a GDExtension shared library. GDExtension version is more convenient to use but somewhat limited in features. Whichever you choose to use, your project will stay compatible with both and you can switch from one to the other any time. SeeUsing GDExtension.

• For the most recent builds, navigate toActions →All Builds, select a build from the list, and scroll down until you find theArtifacts section.
• For release builds, checkReleases.

• Download the Godot Engine source code and put this module source into themodules/limboai directory.
• Consult the Godot Engine documentation for instructions onhow to build from source code.
• If you plan to export a game utilizing the LimboAI module, you'll also need to build export templates.
• To execute unit tests, compile the engine withtests=yes and run it with--test --tc="*[LimboAI]*".

• You'll need SCons build tool and a C++ compiler. See alsoCompiling.
• Runscons target=editor to build the plugin library for your current platform.
  • SCons will automatically clone the godot-cpp/ repository if it doesn't already exist in thelimboai/godot-cpp directory.
  • By default, built targets are placed in the demo project:demo/addons/limboai/bin/
• Checkscons -h for other options and targets.

• Online Documentation:stable,latest
• Getting started
• Introduction to Behavior Trees
• Creating custom tasks in GDScript
• Sharing data using Blackboard
• Accessing nodes in the scene tree
• State machines
• Using GDExtension
• Using LimboAI with C#
• Class reference

Contributions are welcome! Please open issues for bug reports, feature requests, or code changes.For detailed guidelines on contributing to code or documentation, check out ourContributing page.

If you have an idea for a behavior tree task or a feature that could be useful in a variety of projects, open an issue to discuss it.

Need help? We have a Discord server:https://discord.gg/N5MGC95GpP

I write about LimboAI development on Mastodon:https://mastodon.gamedev.place/@limbo.

Use of this source code is governed by an MIT-style license that can be found in the LICENSE file or athttps://opensource.org/licenses/MIT

LimboAI logo and demo project art assets are licensed under the Creative Commons Attribution 4.0 International license that can be found athttps://creativecommons.org/licenses/by/4.0/