Update README with new links to docs and more
This commit is contained in:
Serhii Snitsaruk
parent
f9219fd509
commit
5245f19fa8
39
README.md
39
README.md
|
|
@ -5,23 +5,21 @@
|
|||
</p>
|
||||
|
||||
[](https://github.com/limbonaut/limboai/actions/workflows/test_builds.yml)
|
||||
[](https://limboai.readthedocs.io/en/latest/?badge=latest)
|
||||
|
||||
**LimboAI** is a C++ module for **Godot Engine 4** that provides an implementation of Behavior Trees and State Machines, which can be used together to create complex AI behaviors.
|
||||
**LimboAI** is an open-source C++ module 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.
|
||||
|
||||
>**🛈 Supported Godot Engine: 4.2**
|
||||
|
||||
>**🛈 Previously supported:** [godot-4.1](https://github.com/limbonaut/limboai/tree/godot-4.1)
|
||||
|
||||
>**🛈 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.
|
||||
|
||||
A Behavior Tree (BT) is a powerful hierarchical structure used to model and control the behavior of agents in a game. It comprises tasks that represent specific actions or decision-making rules. When executed, the Behavior Tree starts from the root task and traverses down to the leaf tasks, which correspond to the actual actions or behaviors that the agent should perform. For detailed information on how various BT tasks function, please refer to the class documentation. The BehaviorTree class serves as a good starting point.
|
||||
|
||||
> 🛈 See also: [Introduction to Behavior Trees](./doc/getting-started.md).
|
||||
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).
|
||||
|
||||
|
||||
|
||||
<!--  -->
|
||||
|
||||
## Features
|
||||
|
||||
- **Behavior Trees (BT):**
|
||||
|
|
@ -29,7 +27,7 @@ A Behavior Tree (BT) is a powerful hierarchical structure used to model and cont
|
|||
- 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](./doc/getting-started.md#creating-custom-tasks-in-gdscript) by extending core classes: `BTAction`, `BTCondition`, `BTDecorator`, and `BTComposite`.
|
||||
- [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.
|
||||
- Share data seamlessly between tasks using the `Blackboard`.
|
||||
- Blackboard scopes isolate variable namespaces and enable advanced techniques like sharing data between agents in a group.
|
||||
|
|
@ -48,8 +46,12 @@ A Behavior Tree (BT) is a powerful hierarchical structure used to model and cont
|
|||
|
||||
- **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.
|
||||
|
||||
## 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](https://limboai.readthedocs.io/en/latest/getting-started/gdextension.html).
|
||||
|
||||
### Precompiled builds
|
||||
|
||||
- For the most recent builds, navigate to **Actions** → [**All Builds**](https://github.com/limbonaut/limboai/actions/workflows/all_builds.yml), select a build from the list, and scroll down until you find the **Artifacts** section.
|
||||
|
|
@ -62,21 +64,24 @@ A Behavior Tree (BT) is a powerful hierarchical structure used to model and cont
|
|||
- 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]*"`.
|
||||
|
||||
## Using the module
|
||||
## Using the plugin
|
||||
|
||||
<!-- - [Getting Started](./doc/getting-started.md#getting-started) -->
|
||||
- [Introduction to Behavior Trees](./doc/getting-started.md#introduction-to-behavior-trees)
|
||||
- [Creating custom tasks in GDScript](./doc/getting-started.md#creating-custom-tasks-in-gdscript)
|
||||
- [Task anatomy](./doc/getting-started.md#task-anatomy)
|
||||
- [Custom task example](./doc/getting-started.md#custom-task-example)
|
||||
- [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)
|
||||
- [Using GDExtension](https://limboai.readthedocs.io/en/latest/getting-started/gdextension.html)
|
||||
- [Class reference](https://limboai.readthedocs.io/en/latest/getting-started/featured-classes.html)
|
||||
|
||||
## Contributing
|
||||
|
||||
All contributions are welcome! Feel free to open issues with bug reports and feature requests, and submit PRs.
|
||||
|
||||
Got an idea for a behavior tree task that you think would be useful on a variety of projects?
|
||||
Feel free to open an issue and describe your concept.
|
||||
|
||||
## Social
|
||||
|
||||
We have a Discord server: https://discord.gg/N5MGC95GpP
|
||||
We have a fresh new Discord server: https://discord.gg/N5MGC95GpP
|
||||
|
||||
I also write about LimboAI development on the Mastodon: https://mastodon.gamedev.place/@limbo.
|
||||
|
||||
|
|
@ -90,4 +95,4 @@ Features and improvements that may be implemented in the future:
|
|||
- 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.
|
||||
- Supporting GDExtension in the future, once it matures.
|
||||
~~- Supporting GDExtension in the future, once it matures.~~ 🗸
|
||||
|
|
|
|||
|
|
@ -1,118 +0,0 @@
|
|||
# Getting Started
|
||||
|
||||
> **🛈 See also:** [**How to get LimboAI**](../README.md#getting-limboai).
|
||||
|
||||
- [Getting Started](#getting-started)
|
||||
- [TL;DR](#tldr)
|
||||
- [Introduction to Behavior Trees](#introduction-to-behavior-trees)
|
||||
- [Creating custom tasks in GDScript](#creating-custom-tasks-in-gdscript)
|
||||
- [Task anatomy](#task-anatomy)
|
||||
- [Custom task example](#custom-task-example)
|
||||
|
||||
## TL;DR
|
||||
|
||||
- Next section gives a brief explanation of behavior trees.
|
||||
- To create your own actions, extend the `BTAction` class.
|
||||
- To create your own conditions, extend the `BTCondition` class.
|
||||
- In-editor class documentation is available. Try searching `BTTask` and `BehaviorTree`.
|
||||
- Add a script template with "Misc → Create script template".
|
||||
|
||||
|
||||
## Introduction to Behavior Trees
|
||||
|
||||
**Behavior Trees (BT)** 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.
|
||||
|
||||
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. Control tasks determine the execution flow within the tree. They include `BTSequence`, `BTSelector`, and `BTInvert`. Leaf tasks represent specific actions to perform, like moving or attacking, or conditions that need to be checked. The `BTTask` class provides the foundation for various building blocks of the Behavior Trees. BT tasks can share data with the help of `Blackboard`.
|
||||
|
||||
> **🛈 Note:** To create your own actions, extend the `BTAction` class.
|
||||
|
||||
The BehaviorTree is executed from the root task and follows the rules specified by the control tasks, all the way down to the leaf tasks, which represent the actual actions that the agent should perform or conditions that should be checked. Each task returns a status when it is executed. It can be `SUCCESS`, `RUNNING`, or `FAILURE`. These statuses determine how the tree progresses. They are defined in `BT.Status`.
|
||||
|
||||
Behavior Trees handle conditional logic using condition tasks. These tasks check for specific conditions and return either `SUCCESS` or `FAILURE` based on the state of the agent or its environment (e.g., "IsLowOnHealth", "IsTargetInSight"). Conditions can be used together with `BTSequence` and `BTSelector` to craft your decision-making logic.
|
||||
|
||||
>**🛈 Note:** To create your own conditions, extend the `BTCondition` class.
|
||||
|
||||
Check out the `BTTask` class documentation in the editor, which provides the foundation for various building blocks of Behavior Trees.
|
||||
|
||||
## Creating custom tasks in GDScript
|
||||
|
||||
By default, user tasks should be placed in the `res://ai/tasks` folder. You can set an alternative location for user tasks in the `Project Settings → Limbo AI` (To see those options, `Advanced Settings` should be enabled in the Project Settings). Each subfolder within the user tasks folder is treated as a category. Therefore, if you create a subfolder named "motion_and_physics," your custom tasks in that folder will automatically be categorized under "Motion And Physics."
|
||||
|
||||
>**🛈 Note:** You can add a script template to your project with "Misc → Create script template" menu option.
|
||||
|
||||
### Task anatomy
|
||||
```gdscript
|
||||
@tool
|
||||
extends BTAction
|
||||
|
||||
# Task parameters.
|
||||
@export var parameter1: float
|
||||
@export var parameter2: Vector2
|
||||
|
||||
## Note: Each method declaration is optional.
|
||||
## At minimum, you only need to define the "_tick" method.
|
||||
|
||||
# Called to generate a display name for the task (requires @tool).
|
||||
func _generate_name() -> String:
|
||||
return "MyTask"
|
||||
|
||||
# Called to initialize the task.
|
||||
func _setup() -> void:
|
||||
pass
|
||||
|
||||
# Called when the task is entered.
|
||||
func _enter() -> void:
|
||||
pass
|
||||
|
||||
# Called when the task is exited.
|
||||
func _exit() -> void:
|
||||
pass
|
||||
|
||||
# Called each time this task is ticked (aka executed).
|
||||
func _tick(delta: float) -> Status:
|
||||
return SUCCESS
|
||||
```
|
||||
|
||||
### Custom task example
|
||||
|
||||
```gdscript
|
||||
@tool
|
||||
extends BTCondition
|
||||
|
||||
## InRange condition checks if the agent is within a range of target, defined by
|
||||
## distance_min and distance_max.
|
||||
## Returns SUCCESS if agent is within the defined range;
|
||||
## otherwise, returns FAILURE.
|
||||
|
||||
@export var distance_min: float
|
||||
@export var distance_max: float
|
||||
@export var target_var := "target"
|
||||
|
||||
var _min_distance_squared: float
|
||||
var _max_distance_squared: float
|
||||
|
||||
|
||||
# Called to generate a display name for the task.
|
||||
func _generate_name() -> String:
|
||||
return "InRange (%d, %d) of %s" % [distance_min, distance_max,
|
||||
LimboUtility.decorate_var(target_var)]
|
||||
|
||||
|
||||
# Called to initialize the task.
|
||||
func _setup() -> void:
|
||||
_min_distance_squared = distance_min * distance_min
|
||||
_max_distance_squared = distance_max * distance_max
|
||||
|
||||
|
||||
# Called when the task is executed.
|
||||
func _tick(_delta: float) -> Status:
|
||||
var target: Node2D = blackboard.get_var(target_var, null)
|
||||
if not is_instance_valid(target):
|
||||
return FAILURE
|
||||
|
||||
var dist_sq: float = agent.global_position.distance_squared_to(target.global_position)
|
||||
if dist_sq >= _min_distance_squared and dist_sq <= _max_distance_squared:
|
||||
return SUCCESS
|
||||
else:
|
||||
return FAILURE
|
||||
```
|
||||
|
|
@ -7,7 +7,7 @@
|
|||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
|
||||
|
||||
project = 'LimboAI'
|
||||
copyright = 'Copyright 2021-present Serhii Snitsaruk and the LimboAI contributors'
|
||||
copyright = '2021-present Serhii Snitsaruk and the LimboAI contributors'
|
||||
author = 'Serhii Snitsaruk'
|
||||
release = '1.0'
|
||||
|
||||
|
|
@ -19,7 +19,6 @@ extensions = ['myst_parser', 'sphinx_markdown_builder', 'sphinx_rtd_dark_mode']
|
|||
templates_path = ['_templates']
|
||||
exclude_patterns = ['_build']
|
||||
|
||||
|
||||
# -- Markdown configuration (sphinx_markdown_builder).
|
||||
# markdown_anchor_sections = True
|
||||
# markdown_anchor_signatures = True
|
||||
|
|
@ -27,6 +26,7 @@ exclude_patterns = ['_build']
|
|||
# markdown_http_base = "https://your-domain.com/docs"
|
||||
# markdown_uri_doc_suffix = ".html"
|
||||
|
||||
# -- Dark-mode configuration.
|
||||
default_dark_mode = False
|
||||
|
||||
# -- Options for HTML output -------------------------------------------------
|
||||
|
|
|
|||
|
|
@ -54,6 +54,6 @@ future releases of Godot!
|
|||
|
||||
**Other GDExtension limitations**
|
||||
|
||||
* In-editor documentation is not available. The plugin will open online documentation instead when requested.
|
||||
* Built-in documentation is not available. The plugin will open online documentation instead when requested.
|
||||
* Documentation tooltips are not available.
|
||||
* Handy :ref:`class_BBParam` property editor is not available in the extension due to dependencies on the engine classes that are not available in the Godot API.
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ LimboAI Documentation
|
|||
About
|
||||
-----
|
||||
|
||||
**LimboAI** is an open-source C++ module for Godot Engine 4 providing a combination of
|
||||
**LimboAI** is an open-source C++ module for **Godot Engine 4** providing a combination of
|
||||
**Behavior Trees** and **State Machines** 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 :ref:`creating your own tasks <custom_tasks>`
|
||||
|
|
@ -13,7 +13,7 @@ and states. The full list of features is available on the
|
|||
|
||||
.. SCREENSHOT
|
||||
|
||||
**Behavior Trees** are hierarchical structures used to model and control the behavior
|
||||
**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 :ref:`introduction`.
|
||||
|
|
|
|||
Loading…
Reference in New Issue