diff --git a/README.md b/README.md index 661760f..988adc0 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,37 @@ -# LimboAI - Behavior Trees and State Machines for Godot 4 -

LimboAI logo

+# LimboAI - Behavior Trees & State Machines for Godot 4 + [![🔗 All builds](https://github.com/limbonaut/limboai/actions/workflows/all_builds.yml/badge.svg)](https://github.com/limbonaut/limboai/actions/workflows/all_builds.yml) [![🔎 Unit Tests](https://github.com/limbonaut/limboai/actions/workflows/test_builds.yml/badge.svg)](https://github.com/limbonaut/limboai/actions/workflows/test_builds.yml) [![Documentation Status](https://readthedocs.org/projects/limboai/badge/?version=latest)](https://limboai.readthedocs.io/en/latest/?badge=latest) ![GitHub License](https://img.shields.io/github/license/limbonaut/limboai) + ![Discord](https://img.shields.io/discord/1185664967379267774?logo=discord&link=https%3A%2F%2Fdiscord.gg%2FN5MGC95GpP) +![Support this project](https://img.shields.io/badge/Support%20this%20project-red?logo=kofi&logoColor=white&link=https%3A%2F%2Fko-fi.com%2Flimbonaut) ![Mastodon Follow](https://img.shields.io/mastodon/follow/109346796150895359?domain=https%3A%2F%2Fmastodon.gamedev.place) + **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, and more! -While it is implemented in C++, it fully supports GDScript for [creating your own tasks](https://limboai.readthedocs.io/en/latest/getting-started/custom-tasks.html) and states. +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](https://limboai.readthedocs.io/en/latest/getting-started/custom-tasks.html) and [states](https://limboai.readthedocs.io/en/latest/getting-started/hsm.html). >**🛈 Supported Godot Engine: 4.2** ->**🛈 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. - -Behavior Trees 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 [Introduction to Behavior Trees](https://limboai.readthedocs.io/en/latest/getting-started/introduction.html). - ![Textured screenshot](doc/images/behavior-tree-editor-debugger.png) +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](https://limboai.readthedocs.io/en/latest/getting-started/introduction.html) and our demo project, which includes a tutorial. + +## Demonstration + +[![Demonstration](https://img.youtube.com/vi/NWaMArUg7mY/0.jpg)](https://www.youtube.com/watch?v=NWaMArUg7mY) + +>**🛈 Demo project** lives in the `demo` folder and is available separately in [**Releases**](https://github.com/limbonaut/limboai/releases). +> It includes a tutorial providing an introduction to behavior trees with examples. + ## Features - **Behavior Trees (BT):** @@ -32,11 +40,11 @@ Behavior Trees are powerful hierarchical structures used to model and control th - Create complex behaviors by combining and nesting tasks in a hierarchy. - Control execution flow using composite, decorator, and condition tasks. - [Create custom tasks](https://limboai.readthedocs.io/en/latest/getting-started/custom-tasks.html) by extending core classes: `BTAction`, `BTCondition`, `BTDecorator`, and `BTComposite`. - - Built-in class documentation. Check out the `BehaviorTree` class documentation to get started. + - Built-in class documentation. - Blackboard: Share data seamlessly between tasks using the `Blackboard`. - Blackboard plans: Define variables in the BehaviorTree resource and override their values in the BTPlayer node. - - Blackboard scopes: Isolate variable namespaces and enable advanced techniques like sharing data between several agents in a group. - - 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). + - Blackboard scopes: Prevent name conflicts and enable advanced techniques like [sharing data between several agents](https://limboai.readthedocs.io/en/latest/getting-started/using-blackboard.html#sharing-data-between-several-agents). + - Blackboard parameters: [Export a BB parameter](https://limboai.readthedocs.io/en/latest/getting-started/using-blackboard.html#task-parameters), for which user can provide a value or bind it to a blackboard variable (can be used in custom tasks). - Editor support: Blackboard plan editor, and inspector property editor for exported string 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. @@ -47,16 +55,16 @@ Behavior Trees are powerful hierarchical structures used to model and control th - Extend the `LimboState` class to implement state logic. - The `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. + - [Event-based](https://limboai.readthedocs.io/en/latest/getting-started/hsm.html#events-and-transitions): 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. + - Delegation Option: Using the vanilla `LimboState`, [delegate the implementation](https://limboai.readthedocs.io/en/latest/getting-started/hsm.html#single-file-state-machine-setup) 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](https://limboai.readthedocs.io/en/latest/getting-started/gdextension.html). Custom engine builds are not necessary. -- **Demo Project:** Check out our extensive demo project with a tutorial (an introduction to behavior trees with examples)! +- **Demo + Tutorial:** Check out our extensive demo project, which includes a tutorial providing an introduction to behavior trees with examples. ## Getting LimboAI @@ -81,7 +89,11 @@ LimboAI can be used as either a C++ module or as a GDExtension shared library. G - [Online Documentation](https://limboai.readthedocs.io/en/latest/index.html) - [Introduction to Behavior Trees](https://limboai.readthedocs.io/en/latest/getting-started/introduction.html) - [Creating custom tasks in GDScript](https://limboai.readthedocs.io/en/latest/getting-started/custom-tasks.html) +- [Sharing data using Blackboard](https://limboai.readthedocs.io/en/latest/getting-started/using-blackboard.html) +- [Accessing nodes in the scene tree](https://limboai.readthedocs.io/en/latest/getting-started/accessing-nodes.html) +- [State machines](https://limboai.readthedocs.io/en/latest/getting-started/hsm.html) - [Using GDExtension](https://limboai.readthedocs.io/en/latest/getting-started/gdextension.html) +- [Using LimboAI with C#](https://limboai.readthedocs.io/en/latest/getting-started/c-sharp.html) - [Class reference](https://limboai.readthedocs.io/en/latest/getting-started/featured-classes.html) ## Contributing @@ -103,8 +115,12 @@ Features and improvements that may be implemented in the future: - ~~Providing precompiled builds for download.~~ 🗸 - ~~Tests and CI.~~ 🗸 - ~~GDExtension support.~~ 🗸 -- ~~Non-trivial demo project.~~ 🗸 +- ~~Extensive demo project.~~ 🗸 - Expanding the library of commonly useful tasks. - Exploring the execution history of behavior trees in the visual debugger. - Per-project ignore list for tasks that users may want to hide in the task palette. - GUI editor for state machines. + +## 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.