Doc: Update doc pages and examples

This commit is contained in:
Serhii Snitsaruk 2024-05-02 19:35:42 +02:00
parent e36ea6d3e6
commit e5d04b9eda
No known key found for this signature in database
GPG Key ID: A965EF8799FFEC2D
7 changed files with 16 additions and 13 deletions

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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