From 487c008f5c47d4cfd6c8dd4aa9816bd6af72b727 Mon Sep 17 00:00:00 2001
From: Serhii Snitsaruk <limbonaut@pm.me>
Date: Sat, 17 Feb 2024 23:54:38 +0100
Subject: [PATCH] Doc: Add accessing-nodes page

---
 .../getting-started/accessing-nodes.rst       | 39 +++++++++++++++++++
 .../getting-started/using-blackboard.rst      |  2 +
 doc/source/index.rst                          |  1 +
 3 files changed, 42 insertions(+)
 create mode 100644 doc/source/getting-started/accessing-nodes.rst

diff --git a/doc/source/getting-started/accessing-nodes.rst b/doc/source/getting-started/accessing-nodes.rst
new file mode 100644
index 0000000..fa6bf72
--- /dev/null
+++ b/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``.
diff --git a/doc/source/getting-started/using-blackboard.rst b/doc/source/getting-started/using-blackboard.rst
index 2e7ae65..1f8c5c1 100644
--- a/doc/source/getting-started/using-blackboard.rst
+++ b/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
 ---------------------------
 
diff --git a/doc/source/index.rst b/doc/source/index.rst
index fdc34cf..da40b9e 100644
--- a/doc/source/index.rst
+++ b/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::