Doc: Update doc pages and examples

doc/source/classes/class_btplayer.rst

@@ -19,7 +19,7 @@ Player of :ref:`BehaviorTree<class_BehaviorTree>` resources.
 Description
 -----------
 
-BTPlayer node is used for the instantiation and playback of :ref:`BehaviorTree<class_BehaviorTree>` resources at runtime. During instantiation, the behavior tree instance is initialized with a reference to the agent and the :ref:`blackboard<class_BTPlayer_property_blackboard>`. Agent is the owner of the BTPlayer node (see :ref:`Node.owner<class_Node_member_owner>`).
+**BTPlayer** node is used to instantiate and play :ref:`BehaviorTree<class_BehaviorTree>` resources at runtime. During initialization, the behavior tree instance is given references to the agent, the :ref:`blackboard<class_BTPlayer_property_blackboard>`, and the current scene root. The agent can be specified by the :ref:`agent_node<class_BTPlayer_property_agent_node>` property (defaults to the BTPlayer's parent node).
 
 For an introduction to behavior trees, see :ref:`BehaviorTree<class_BehaviorTree>`.
 

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<class_BehaviorTree>` instance. Usually, agent is the owner of the :ref:`BTPlayer<class_BTPlayer>` node containing the :ref:`BehaviorTree<class_BehaviorTree>` resource.
+The agent is the contextual object for the :ref:`BehaviorTree<class_BehaviorTree>` instance. This is usually the parent of the :ref:`BTPlayer<class_BTPlayer>` node that utilizes the :ref:`BehaviorTree<class_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<class_BTPlayer>` node). Can be uses to retrieve ``NodePath`` references.
 
 \ **Example:**\ 
 

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<class_BTTask>`.
 
-    **🛈 Note:** Agent is the owner of :ref:`BTPlayer<class_BTPlayer>` node.
+    **🛈 Note:** The root node of the agent's scene tree can be accessed with the
+    :ref:`scene_root<class_BTTask_property_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<editing_plan>` in the editor with the type ``NodePath``
-and point it to the proper node in the :ref:`BTPlayer<class_BTPlayer>` blackboard plan.
+and point it to the proper node in the :ref:`BTPlayer<class_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<class_BlackboardPlan_property_prefetch_nodepath_vars>`).
 
 .. code:: gdscript
 

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

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

doc_classes/BTPlayer.xml

@@ -4,7 +4,7 @@
 		Player of [BehaviorTree] resources.
 	</brief_description>
 	<description>
-		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].
 	</description>
 	<tutorials>

doc_classes/BTTask.xml

@@ -194,7 +194,7 @@
 	</methods>
 	<members>
 		<member name="agent" type="Node" setter="set_agent" getter="get_agent">
-			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.
 		</member>
 		<member name="blackboard" type="Blackboard" setter="" getter="get_blackboard">
 			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].
 		</member>
 		<member name="scene_root" type="Node" setter="" getter="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 [BTPlayer] node). Can be uses to retrieve [NodePath] references.
 			[b]Example:[/b]
 			[codeblock]
 			extends BTAction