Go to file
Serhii Snitsaruk a92fb9da8e
Merge pull request #201 from limbonaut/fix-undo-redo
Fix editor undo polluting scene history if `BehaviorTree` is not saved to a file
2024-08-21 20:57:51 +02:00
.github GHA: Build Android .NET templates 2024-08-20 22:13:07 +02:00
blackboard Don't warn of mismatch between Object & NodePath 2024-08-16 00:44:37 +02:00
bt Clean up unused string names 2024-08-21 20:04:35 +02:00
demo Fix demo API calls 2024-08-03 11:40:56 +02:00
doc Doc: Update using-blackboard.rst 2024-08-16 10:53:59 +02:00
doc_classes Clarify add_event_handler in docs 2024-08-10 15:01:43 +02:00
editor Clean up unused string names 2024-08-21 20:04:35 +02:00
gdextension Fix icon *.import files on scons build 2024-08-10 10:32:35 +02:00
hsm Clean up unused string names 2024-08-21 20:04:35 +02:00
icons Editor: Tab button to inspect blackboard plan 2024-05-28 11:16:37 +02:00
tests Add tests for change_active_state() 2024-07-21 14:07:56 +02:00
util Clean up unused string names 2024-08-21 20:04:35 +02:00
.clang-format Initial commit 2022-08-28 12:54:16 +02:00
.gitignore update SConstruct to be used from repo root and add --project option 2024-08-07 15:01:50 +02:00
.pre-commit-config.yaml Add pre-commit configuration 2024-05-03 00:21:51 +02:00
LICENSE.md Demo: Add LICENSE_ASSETS.md 2024-02-14 21:09:16 +01:00
LOGO_LICENSE.md README: Add LimboAI logo 2023-11-05 15:19:13 +01:00
README.md Clone godot-cpp if not found during scons build 2024-08-09 14:21:40 +02:00
SConstruct Fix icon *.import files on scons build 2024-08-10 10:32:35 +02:00
SCsub Files reformatted by pre-commit 2024-05-31 11:46:16 +02:00
config.py Update class docs 2024-08-03 13:14:31 +02:00
limboai_version.py Bump version to 1.2-rc 2024-08-15 16:30:42 +02:00
register_types.cpp Implement BTInstance - runtime instance of BehaviorTree 2024-08-03 11:07:06 +02:00
register_types.h Update file headers and fix whitespace 2024-03-21 21:38:57 +01:00

README.md

LimboAI logo

LimboAI - Behavior Trees & State Machines for Godot 4

🔗 All builds 🔎 Unit Tests Documentation Status GitHub License Discord Mastodon Follow

🛈 Supported Godot Engine: 4.2 (latest release) | 4.3-rc (master branch)

LimboAI is an open-source C++ plugin for Godot Engine 4 providing a combination of Behavior Trees and State 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 for creating your own tasks and states.

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

ko-fi

Textured screenshot

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 out Introduction to Behavior Trees and our demo project, which includes a tutorial.

Demonstration

Charger from Demo

🛈 Demo project lives in the demo folder and is available separately in Releases. Run demo/scenes/showcase.tscn to get started. It also includes a tutorial that introduces behavior trees through illustrative examples.

Videos

🛈 YouTube videos produced by various creators

Features

  • Behavior Trees (BT):

    • Easily create, edit, and save BehaviorTree resources in the editor.
    • Execute BehaviorTree resources using the BTPlayer 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, and BTComposite.
    • Built-in class documentation.
    • Blackboard system: Share data seamlessly between tasks using the Blackboard.
      • 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 like sharing 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 exported StringName properties ending with "_var").
    • Use the BTSubtree 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 using BehaviorTreeView node (for custom in-game tools).
    • Monitor tree performance with custom performance monitors.
  • Hierarchical State Machines (HSM):

    • Extend the LimboState class to implement state logic.
    • LimboHSM node serves as a state machine that manages LimboState instances and transitions.
    • LimboHSM is a state itself and can be nested within other LimboHSM 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 using BTState for advanced reactive AI.
    • Delegation Option: Using the vanilla LimboState, 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 be used 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.

First steps

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

Getting LimboAI

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. See Using GDExtension.

Precompiled builds

  • For the most recent builds, navigate to ActionsAll Builds, select a build from the list, and scroll down until you find the Artifacts section.
  • For release builds, check Releases.

Compiling from source

  • Download the Godot Engine source code and put this module source into the modules/limboai directory.
  • Consult the Godot Engine documentation for instructions on how 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 with tests=yes and run it with --test --tc="*[LimboAI]*".

For GDExtension

  • You'll need SCons build tool and a C++ compiler. See also Compiling.
  • Run scons 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 the limboai/godot-cpp directory.
    • By default, built targets are placed in the demo project: demo/addons/limboai/bin/
  • Check scons -h for other options and targets.

Using the plugin

Contributing

Contributions are welcome! Please open issues for bug reports, feature requests, or code changes. Keep the minor versions backward-compatible when submitting pull requests.

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.

Social

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

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

License

Use of this source code is governed by an MIT-style license that can be found in the LICENSE file or at https://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 at https://creativecommons.org/licenses/by/4.0/