Merge pull request #45 from limbonaut/docs

Update documentation

doc/source/getting-started/accessing-nodes.rst

@@ -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``.

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
 ----------------------------
 

doc/source/getting-started/featured-classes.rst

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

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<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
+building blocks of the Behavior Trees. Such tasks can :ref:`share data using the Blackboard<blackboard>`.
-help of the :ref:`Blackboard<class_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
+A Behavior Tree is usually processed each frame. It is traversed from top to bottom,
-specified by the control tasks, all the way down to the leaf tasks,
+with the control tasks determining the control flow. Each task has a :ref:`_tick<class_BTTask_private_method__tick>`
-which represent the actual actions that the agent should perform or
+method, which performs the task's work and returns a status indicating its progress:
-conditions that should be checked. Each task returns a status when it is
+``SUCCESS``, ``FAILURE``, or ``RUNNING``. ``SUCCESS`` and ``FAILURE`` indicate the
-executed. It can be ``SUCCESS``, ``RUNNING``, or ``FAILURE``. These
+outcome of finished work, while ``RUNNING`` status is returned when a task requires
-statuses determine how the tree progresses. They are defined in
+more than one tick to complete its job. These statuses determine how the tree
-:ref:`BT.Status <enum_BT_Status>`.
+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

doc/source/getting-started/using-blackboard.rst

@@ -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
 ---------------------------
 

doc/source/index.rst

@@ -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::