From e7f1d3a424e451fadbe399ccc7eb8417093bac7a Mon Sep 17 00:00:00 2001 From: Serhii Snitsaruk Date: Sat, 17 Feb 2024 23:25:45 +0100 Subject: [PATCH] Doc: Update introduction to behavior trees --- doc/source/getting-started/custom-tasks.rst | 2 + .../getting-started/featured-classes.rst | 2 + doc/source/getting-started/introduction.rst | 62 ++++++++++++++----- 3 files changed, 52 insertions(+), 14 deletions(-) diff --git a/doc/source/getting-started/custom-tasks.rst b/doc/source/getting-started/custom-tasks.rst index 0c7d6b3..77b3fb1 100644 --- a/doc/source/getting-started/custom-tasks.rst +++ b/doc/source/getting-started/custom-tasks.rst @@ -93,6 +93,8 @@ Example 1: A simple action return FAILURE +.. _example_in_range: + Example 2: InRange condition ---------------------------- diff --git a/doc/source/getting-started/featured-classes.rst b/doc/source/getting-started/featured-classes.rst index f2a51eb..5f7a7c9 100644 --- a/doc/source/getting-started/featured-classes.rst +++ b/doc/source/getting-started/featured-classes.rst @@ -1,3 +1,5 @@ +.. _featured_classes: + Important classes ================= diff --git a/doc/source/getting-started/introduction.rst b/doc/source/getting-started/introduction.rst index b4bb155..40d7890 100644 --- a/doc/source/getting-started/introduction.rst +++ b/doc/source/getting-started/introduction.rst @@ -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`, :ref:`Selector`, and -:ref:`Invert`. Leaf tasks represent specific actions +:ref:`Invert`. **Leaf tasks** represent specific actions to perform, like moving or attacking, or conditions that need to be checked. The :ref:`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`. +building blocks of the Behavior Trees. Such tasks can :ref:`share data using the Blackboard`. - **🛈 Note:** To create your own actions, extend the :ref:`BTAction` + **🛈 Note:** To :ref:`create your own actions`, extend the :ref:`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 `. +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` +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`, :ref:`Wait`. + +* **Conditions** are leaf tasks that conduct various checks. + + * Examples: :ref:`CheckVar`, :ref:`InRange`. + +* **Composites** can have one or more child tasks, and dictate the execution flow of their children. + + * Examples: :ref:`Sequence`, :ref:`Selector`, :ref:`Parallel`. + +* **Decorators** can only have a single child and they change how their child task operates. + + * Examples: :ref:`AlwaysSucceed`, :ref:`Invert`, :ref:`TimeLimit`. + +:ref:`Sequence` 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` +execution will be aborted, and the :ref:`Sequence` itself will +return ``FAILURE``. + +:ref:`Selector` 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` stops and also returns ``SUCCESS``. +The purpose of the :ref:`Selector` 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` and :ref:`Selector` to craft your decision-making logic. - **🛈 Note:** To create your own conditions, extend the :ref:`BTCondition` + **🛈 Note:** To :ref:`create your own conditions`, extend the :ref:`BTCondition` class. Check out the :ref:`BTTask` class documentation, which