Merge pull request #45 from limbonaut/docs

Update documentation
This commit is contained in:
Serhii Snitsaruk 2024-02-17 23:55:34 +01:00 committed by GitHub
commit 27327cf18e
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
6 changed files with 94 additions and 14 deletions

View File

@ -0,0 +1,39 @@
.. _accessing_nodes:
Accessing nodes in the scene tree
=================================
There are several ways to access nodes in the agent's scene tree (agent is the owner of :ref:`BTPlayer<class_BTPlayer>` node):
1. You can export a :ref:`BBNode<class_BBNode>` variable:
.. code:: gdscript
@export var cast: BBNode
func _tick(delta) -> Status:
var node: ShapeCast3D = cast.get_value(agent, blackboard)
2. You can export a ``NodePath``
.. code:: gdscript
@export var cast_path: NodePath
var _shape_cast: ShapeCast3D
func _setup() -> void:
_shape_cast = agent.get_node(cast_path)
3. You can :ref:`create a blackboard variable<editing_plan>` in the editor with the type ``NodePath``
and point it to the proper node in the :ref:`BTPlayer<class_BTPlayer>` blackboard plan.
.. code:: gdscript
extends BTCondition
@export var shape_var: String = "shape_cast"
func _tick(delta) -> Status:
var shape_cast: ShapeCast3D = blackboard.get_var(shape_var)
The property :ref:`BTPlayer.prefetch_nodepath_vars<class_BTPlayer_property_prefetch_nodepath_vars>` should be set to ``true``.

View File

@ -93,6 +93,8 @@ Example 1: A simple action
return FAILURE
.. _example_in_range:
Example 2: InRange condition
----------------------------

View File

@ -1,3 +1,5 @@
.. _featured_classes:
Important classes
=================

View File

@ -3,6 +3,7 @@
Introduction to Behavior Trees
==============================
**🛈 Note:** Demo project includes a tutorial that provides an introduction to behavior trees through illustrative examples.
**Behavior Trees (BT)** are hierarchical structures used to model and
control the behavior of agents in a game (e.g., characters, enemies,
@ -11,34 +12,67 @@ 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
types: control tasks and leaf tasks. **Control tasks** determine the
execution flow within the tree. They include :ref:`Sequence<class_BTSequence>`,
:ref:`Selector<class_BTSelector>`, and
:ref:`Invert<class_BTInvert>`. Leaf tasks represent specific actions
:ref:`Invert<class_BTInvert>`. **Leaf tasks** represent specific actions
to perform, like moving or attacking, or conditions that need to be
checked. The :ref:`BTTask<class_BTTask>` class provides the foundation for various
building blocks of the Behavior Trees. BT tasks can share data with the
help of the :ref:`Blackboard<class_Blackboard>`.
building blocks of the Behavior Trees. Such tasks can :ref:`share data using the Blackboard<blackboard>`.
**🛈 Note:** To create your own actions, extend the :ref:`BTAction<class_BTAction>`
**🛈 Note:** To :ref:`create your own actions<custom_tasks>`, extend the :ref:`BTAction<class_BTAction>`
class.
The Behavior Tree 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
:ref:`BT.Status <enum_BT_Status>`.
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 :ref:`_tick<class_BTTask_private_method__tick>`
method, which performs the task's work and returns a status indicating its progress:
``SUCCESS``, ``FAILURE``, or ``RUNNING``. ``SUCCESS`` and ``FAILURE`` indicate the
outcome of finished work, while ``RUNNING`` status is returned when a task requires
more than one tick to complete its job. These statuses determine how the tree
progresses, with the ``RUNNING`` status usually meaning that the tree will
continue execution during the next frame.
Behavior Trees handle conditional logic using condition tasks. These
There are *four types of tasks*:
* **Actions** are leaf tasks that perform the actual work.
* Examples: :ref:`PlayAnimation<class_BTPlayAnimation>`, :ref:`Wait<class_BTWait>`.
* **Conditions** are leaf tasks that conduct various checks.
* Examples: :ref:`CheckVar<class_BTCheckVar>`, :ref:`InRange<example_in_range>`.
* **Composites** can have one or more child tasks, and dictate the execution flow of their children.
* Examples: :ref:`Sequence<class_BTSequence>`, :ref:`Selector<class_BTSelector>`, :ref:`Parallel<class_BTParallel>`.
* **Decorators** can only have a single child and they change how their child task operates.
* Examples: :ref:`AlwaysSucceed<class_BTAlwaysSucceed>`, :ref:`Invert<class_BTInvert>`, :ref:`TimeLimit<class_BTTimeLimit>`.
:ref:`Sequence<class_BTSequence>` is one of the core composite tasks.
It executes its child tasks sequentially, from first to last, until one of them
returns ``FAILURE``, or all of them result in ``SUCCESS``. In other words,
if any child task results in ``FAILURE``, the :ref:`Sequence<class_BTSequence>`
execution will be aborted, and the :ref:`Sequence<class_BTSequence>` itself will
return ``FAILURE``.
:ref:`Selector<class_BTSelector>` is another essential composite task.
It executes its child tasks sequentially, from first to last, until one of them
returns ``SUCCESS`` or all of them result in ``FAILURE``. In other words, when
a child task results in ``FAILURE``, it moves on to the next one until it
finds the one that returns ``SUCCESS``. Once a child task results in ``SUCCESS``,
the :ref:`Selector<class_BTSelector>` stops and also returns ``SUCCESS``.
The purpose of the :ref:`Selector<class_BTSelector>` is to find a child that succeeds.
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 :ref:`Sequence<class_BTSequence>` and :ref:`Selector<class_BTSelector>`
to craft your decision-making logic.
**🛈 Note:** To create your own conditions, extend the :ref:`BTCondition<class_BTCondition>`
**🛈 Note:** To :ref:`create your own conditions<custom_tasks>`, extend the :ref:`BTCondition<class_BTCondition>`
class.
Check out the :ref:`BTTask<class_BTTask>` class documentation, which

View File

@ -35,6 +35,8 @@ Here's an example of how you can interact with the :ref:`Blackboard<class_Blackb
**🛈 Note:** The variable doesn't need to exist when you set it.
.. _editing_plan:
Editing the Blackboard Plan
---------------------------

View File

@ -44,6 +44,7 @@ the other any time. For more information on this topic, see :ref:`gdextension`.
getting-started/using-blackboard
getting-started/gdextension
getting-started/c-sharp
getting-started/accessing-nodes
getting-started/featured-classes
.. toctree::