From e5d04b9eda7b6988a7fe8c8fce2a5d990ca1592d Mon Sep 17 00:00:00 2001 From: Serhii Snitsaruk Date: Thu, 2 May 2024 19:35:42 +0200 Subject: [PATCH] Doc: Update doc pages and examples --- doc/source/classes/class_btplayer.rst | 2 +- doc/source/classes/class_bttask.rst | 4 ++-- doc/source/getting-started/accessing-nodes.rst | 13 ++++++++----- doc/source/getting-started/custom-tasks.rst | 2 +- doc/source/getting-started/using-blackboard.rst | 2 +- doc_classes/BTPlayer.xml | 2 +- doc_classes/BTTask.xml | 4 ++-- 7 files changed, 16 insertions(+), 13 deletions(-) diff --git a/doc/source/classes/class_btplayer.rst b/doc/source/classes/class_btplayer.rst index 067940e..790fa0f 100644 --- a/doc/source/classes/class_btplayer.rst +++ b/doc/source/classes/class_btplayer.rst @@ -19,7 +19,7 @@ Player of :ref:`BehaviorTree` resources. Description ----------- -BTPlayer node is used for the instantiation and playback of :ref:`BehaviorTree` resources at runtime. During instantiation, the behavior tree instance is initialized with a reference to the agent and the :ref:`blackboard`. Agent is the owner of the BTPlayer node (see :ref:`Node.owner`). +**BTPlayer** node is used to instantiate and play :ref:`BehaviorTree` resources at runtime. During initialization, the behavior tree instance is given references to the agent, the :ref:`blackboard`, and the current scene root. The agent can be specified by the :ref:`agent_node` property (defaults to the BTPlayer's parent node). For an introduction to behavior trees, see :ref:`BehaviorTree`. diff --git a/doc/source/classes/class_bttask.rst b/doc/source/classes/class_bttask.rst index cc9b4ea..999cd32 100644 --- a/doc/source/classes/class_bttask.rst +++ b/doc/source/classes/class_bttask.rst @@ -133,7 +133,7 @@ Node **agent** - void **set_agent** **(** Node value **)** - Node **get_agent** **(** **)** -The agent is a contextual object for the task's :ref:`BehaviorTree` instance. Usually, agent is the owner of the :ref:`BTPlayer` node containing the :ref:`BehaviorTree` resource. +The agent is the contextual object for the :ref:`BehaviorTree` instance. This is usually the parent of the :ref:`BTPlayer` node that utilizes the :ref:`BehaviorTree` resource. .. rst-class:: classref-item-separator @@ -202,7 +202,7 @@ Node **scene_root** - Node **get_scene_root** **(** **)** -Root node of the scene the behavior tree is used in (e.g., the owner of the node that contains the behavior tree). Can be uses to retrieve ``NodePath`` references. +Root node of the scene the behavior tree is used in (e.g., the owner of the :ref:`BTPlayer` node). Can be uses to retrieve ``NodePath`` references. \ **Example:**\ diff --git a/doc/source/getting-started/accessing-nodes.rst b/doc/source/getting-started/accessing-nodes.rst index 11d8f00..882564e 100644 --- a/doc/source/getting-started/accessing-nodes.rst +++ b/doc/source/getting-started/accessing-nodes.rst @@ -3,9 +3,10 @@ Accessing nodes in the scene tree ================================= -There are several ways to access nodes in the agent's scene tree. +There are several ways to access nodes in the agent's scene tree from a :ref:`BTTask`. - **🛈 Note:** Agent is the owner of :ref:`BTPlayer` node. + **🛈 Note:** The root node of the agent's scene tree can be accessed with the + :ref:`scene_root` property. With ``BBNode`` property @@ -16,7 +17,7 @@ With ``BBNode`` property @export var cast_param: BBNode func _tick(delta) -> Status: - var node: ShapeCast3D = cast_param.get_value(agent, blackboard) + var node: ShapeCast3D = cast_param.get_value(scene_root, blackboard) With ``NodePath`` property @@ -27,14 +28,16 @@ With ``NodePath`` property @export var cast_path: NodePath func _tick(delta) -> Status: - var node: ShapeCast3D = agent.get_node(cast_path) + var node: ShapeCast3D = scene_root.get_node(cast_path) Using blackboard plan --------------------- You can :ref:`create a blackboard variable` in the editor with the type ``NodePath`` -and point it to the proper node in the :ref:`BTPlayer` blackboard plan. +and point it to the proper node in the :ref:`BTPlayer` blackboard plan. By default, +any ``NodePath`` variable will be replaced with the node instance when the blackboard is instantiated +at runtime (see :ref:`BlackboardPlan.prefetch_nodepath_vars`). .. code:: gdscript diff --git a/doc/source/getting-started/custom-tasks.rst b/doc/source/getting-started/custom-tasks.rst index 4cbc7c8..f1da51f 100644 --- a/doc/source/getting-started/custom-tasks.rst +++ b/doc/source/getting-started/custom-tasks.rst @@ -92,7 +92,7 @@ Example 1: A simple action # Called each time this task is ticked (aka executed). func _tick(p_delta: float) -> Status: - var n: CanvasItem = agent.get_node_or_null(node_path) + var n: CanvasItem = scene_root.get_node_or_null(node_path) if is_instance_valid(n): n.visible = visible return SUCCESS diff --git a/doc/source/getting-started/using-blackboard.rst b/doc/source/getting-started/using-blackboard.rst index 445ea6d..f957dbf 100644 --- a/doc/source/getting-started/using-blackboard.rst +++ b/doc/source/getting-started/using-blackboard.rst @@ -91,7 +91,7 @@ Usage example: @export var speed: BBFloat func _tick(delta: float) -> Status: - var current_speed: float = speed.get_value(agent, blackboard, 0.0) + var current_speed: float = speed.get_value(scene_root, blackboard, 0.0) ... Advanced topic: Blackboard scopes diff --git a/doc_classes/BTPlayer.xml b/doc_classes/BTPlayer.xml index 2829e5a..060a2f7 100644 --- a/doc_classes/BTPlayer.xml +++ b/doc_classes/BTPlayer.xml @@ -4,7 +4,7 @@ Player of [BehaviorTree] resources. - BTPlayer node is used for the instantiation and playback of [BehaviorTree] resources at runtime. During instantiation, the behavior tree instance is initialized with a reference to the agent and the [member blackboard]. Agent is the owner of the BTPlayer node (see [member Node.owner]). + [BTPlayer] node is used to instantiate and play [BehaviorTree] resources at runtime. During initialization, the behavior tree instance is given references to the agent, the [member blackboard], and the current scene root. The agent can be specified by the [member agent_node] property (defaults to the BTPlayer's parent node). For an introduction to behavior trees, see [BehaviorTree]. diff --git a/doc_classes/BTTask.xml b/doc_classes/BTTask.xml index 0c6720b..1c922ee 100644 --- a/doc_classes/BTTask.xml +++ b/doc_classes/BTTask.xml @@ -194,7 +194,7 @@ - The agent is a contextual object for the task's [BehaviorTree] instance. Usually, agent is the owner of the [BTPlayer] node containing the [BehaviorTree] resource. + The agent is the contextual object for the [BehaviorTree] instance. This is usually the parent of the [BTPlayer] node that utilizes the [BehaviorTree] resource. Provides access to the [Blackboard]. Blackboard is used to share data among tasks of the associated [BehaviorTree]. @@ -208,7 +208,7 @@ Returns [code]0[/code] when task is not [code]RUNNING[/code]. - Root node of the scene the behavior tree is used in (e.g., the owner of the node that contains the behavior tree). Can be uses to retrieve [NodePath] references. + Root node of the scene the behavior tree is used in (e.g., the owner of the [BTPlayer] node). Can be uses to retrieve [NodePath] references. [b]Example:[/b] [codeblock] extends BTAction