mirror of
https://github.com/godotengine/godot-docs.git
synced 2025-12-31 17:49:03 +03:00
406 lines
16 KiB
ReStructuredText
406 lines
16 KiB
ReStructuredText
:github_url: hide
|
|
|
|
.. DO NOT EDIT THIS FILE!!!
|
|
.. Generated automatically from Godot engine sources.
|
|
.. Generator: https://github.com/godotengine/godot/tree/4.0/doc/tools/make_rst.py.
|
|
.. XML source: https://github.com/godotengine/godot/tree/4.0/doc/classes/NodePath.xml.
|
|
|
|
.. _class_NodePath:
|
|
|
|
NodePath
|
|
========
|
|
|
|
A pre-parsed scene tree path.
|
|
|
|
.. rst-class:: classref-introduction-group
|
|
|
|
Description
|
|
-----------
|
|
|
|
A pre-parsed relative or absolute path in a scene tree, for use with :ref:`Node.get_node<class_Node_method_get_node>` and similar functions. It can reference a node, a resource within a node, or a property of a node or resource. For example, ``"Path2D/PathFollow2D/Sprite2D:texture:size"`` would refer to the ``size`` property of the ``texture`` resource on the node named ``"Sprite2D"`` which is a child of the other named nodes in the path.
|
|
|
|
You will usually just pass a string to :ref:`Node.get_node<class_Node_method_get_node>` and it will be automatically converted, but you may occasionally want to parse a path ahead of time with **NodePath** or the literal syntax ``^"path"``. Exporting a **NodePath** variable will give you a node selection widget in the properties panel of the editor, which can often be useful.
|
|
|
|
A **NodePath** is composed of a list of slash-separated node names (like a filesystem path) and an optional colon-separated list of "subnames" which can be resources or properties.
|
|
|
|
Some examples of NodePaths include the following:
|
|
|
|
::
|
|
|
|
# No leading slash means it is relative to the current node.
|
|
^"A" # Immediate child A
|
|
^"A/B" # A's child B
|
|
^"." # The current node.
|
|
^".." # The parent node.
|
|
^"../C" # A sibling node C.
|
|
# A leading slash means it is absolute from the SceneTree.
|
|
^"/root" # Equivalent to get_tree().get_root().
|
|
^"/root/Main" # If your main scene's root node were named "Main".
|
|
^"/root/MyAutoload" # If you have an autoloaded node or scene.
|
|
|
|
See also :ref:`StringName<class_StringName>`, which is a similar concept for general-purpose string interning.
|
|
|
|
\ **Note:** In the editor, **NodePath** properties are automatically updated when moving, renaming or deleting a node in the scene tree, but they are never updated at runtime.
|
|
|
|
\ **Note:** In a boolean context, a **NodePath** will evaluate to ``false`` if it is empty (``NodePath("")``). Otherwise, a **NodePath** will always evaluate to ``true``.
|
|
|
|
.. rst-class:: classref-introduction-group
|
|
|
|
Tutorials
|
|
---------
|
|
|
|
- `2D Role Playing Game Demo <https://godotengine.org/asset-library/asset/520>`__
|
|
|
|
.. rst-class:: classref-reftable-group
|
|
|
|
Constructors
|
|
------------
|
|
|
|
.. table::
|
|
:widths: auto
|
|
|
|
+---------------------------------+-------------------------------------------------------------------------------------------------------+
|
|
| :ref:`NodePath<class_NodePath>` | :ref:`NodePath<class_NodePath_constructor_NodePath>` **(** **)** |
|
|
+---------------------------------+-------------------------------------------------------------------------------------------------------+
|
|
| :ref:`NodePath<class_NodePath>` | :ref:`NodePath<class_NodePath_constructor_NodePath>` **(** :ref:`NodePath<class_NodePath>` from **)** |
|
|
+---------------------------------+-------------------------------------------------------------------------------------------------------+
|
|
| :ref:`NodePath<class_NodePath>` | :ref:`NodePath<class_NodePath_constructor_NodePath>` **(** :ref:`String<class_String>` from **)** |
|
|
+---------------------------------+-------------------------------------------------------------------------------------------------------+
|
|
|
|
.. rst-class:: classref-reftable-group
|
|
|
|
Methods
|
|
-------
|
|
|
|
.. table::
|
|
:widths: auto
|
|
|
|
+-------------------------------------+-------------------------------------------------------------------------------------------------------+
|
|
| :ref:`NodePath<class_NodePath>` | :ref:`get_as_property_path<class_NodePath_method_get_as_property_path>` **(** **)** |const| |
|
|
+-------------------------------------+-------------------------------------------------------------------------------------------------------+
|
|
| :ref:`StringName<class_StringName>` | :ref:`get_concatenated_names<class_NodePath_method_get_concatenated_names>` **(** **)** |const| |
|
|
+-------------------------------------+-------------------------------------------------------------------------------------------------------+
|
|
| :ref:`StringName<class_StringName>` | :ref:`get_concatenated_subnames<class_NodePath_method_get_concatenated_subnames>` **(** **)** |const| |
|
|
+-------------------------------------+-------------------------------------------------------------------------------------------------------+
|
|
| :ref:`StringName<class_StringName>` | :ref:`get_name<class_NodePath_method_get_name>` **(** :ref:`int<class_int>` idx **)** |const| |
|
|
+-------------------------------------+-------------------------------------------------------------------------------------------------------+
|
|
| :ref:`int<class_int>` | :ref:`get_name_count<class_NodePath_method_get_name_count>` **(** **)** |const| |
|
|
+-------------------------------------+-------------------------------------------------------------------------------------------------------+
|
|
| :ref:`StringName<class_StringName>` | :ref:`get_subname<class_NodePath_method_get_subname>` **(** :ref:`int<class_int>` idx **)** |const| |
|
|
+-------------------------------------+-------------------------------------------------------------------------------------------------------+
|
|
| :ref:`int<class_int>` | :ref:`get_subname_count<class_NodePath_method_get_subname_count>` **(** **)** |const| |
|
|
+-------------------------------------+-------------------------------------------------------------------------------------------------------+
|
|
| :ref:`int<class_int>` | :ref:`hash<class_NodePath_method_hash>` **(** **)** |const| |
|
|
+-------------------------------------+-------------------------------------------------------------------------------------------------------+
|
|
| :ref:`bool<class_bool>` | :ref:`is_absolute<class_NodePath_method_is_absolute>` **(** **)** |const| |
|
|
+-------------------------------------+-------------------------------------------------------------------------------------------------------+
|
|
| :ref:`bool<class_bool>` | :ref:`is_empty<class_NodePath_method_is_empty>` **(** **)** |const| |
|
|
+-------------------------------------+-------------------------------------------------------------------------------------------------------+
|
|
|
|
.. rst-class:: classref-reftable-group
|
|
|
|
Operators
|
|
---------
|
|
|
|
.. table::
|
|
:widths: auto
|
|
|
|
+-------------------------+------------------------------------------------------------------------------------------------------------+
|
|
| :ref:`bool<class_bool>` | :ref:`operator !=<class_NodePath_operator_neq_NodePath>` **(** :ref:`NodePath<class_NodePath>` right **)** |
|
|
+-------------------------+------------------------------------------------------------------------------------------------------------+
|
|
| :ref:`bool<class_bool>` | :ref:`operator ==<class_NodePath_operator_eq_NodePath>` **(** :ref:`NodePath<class_NodePath>` right **)** |
|
|
+-------------------------+------------------------------------------------------------------------------------------------------------+
|
|
|
|
.. rst-class:: classref-section-separator
|
|
|
|
----
|
|
|
|
.. rst-class:: classref-descriptions-group
|
|
|
|
Constructor Descriptions
|
|
------------------------
|
|
|
|
.. _class_NodePath_constructor_NodePath:
|
|
|
|
.. rst-class:: classref-constructor
|
|
|
|
:ref:`NodePath<class_NodePath>` **NodePath** **(** **)**
|
|
|
|
Constructs an empty **NodePath**.
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. rst-class:: classref-constructor
|
|
|
|
:ref:`NodePath<class_NodePath>` **NodePath** **(** :ref:`NodePath<class_NodePath>` from **)**
|
|
|
|
Constructs a **NodePath** as a copy of the given **NodePath**. ``NodePath("example")`` is equivalent to ``^"example"``.
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. rst-class:: classref-constructor
|
|
|
|
:ref:`NodePath<class_NodePath>` **NodePath** **(** :ref:`String<class_String>` from **)**
|
|
|
|
Creates a NodePath from a string, e.g. ``"Path2D/PathFollow2D/Sprite2D:texture:size"``. A path is absolute if it starts with a slash. Absolute paths are only valid in the global scene tree, not within individual scenes. In a relative path, ``"."`` and ``".."`` indicate the current node and its parent.
|
|
|
|
The "subnames" optionally included after the path to the target node can point to resources or properties, and can also be nested.
|
|
|
|
Examples of valid NodePaths (assuming that those nodes exist and have the referenced resources or properties):
|
|
|
|
::
|
|
|
|
# Points to the Sprite2D node.
|
|
"Path2D/PathFollow2D/Sprite2D"
|
|
# Points to the Sprite2D node and its "texture" resource.
|
|
# get_node() would retrieve "Sprite2D", while get_node_and_resource()
|
|
# would retrieve both the Sprite2D node and the "texture" resource.
|
|
"Path2D/PathFollow2D/Sprite2D:texture"
|
|
# Points to the Sprite2D node and its "position" property.
|
|
"Path2D/PathFollow2D/Sprite2D:position"
|
|
# Points to the Sprite2D node and the "x" component of its "position" property.
|
|
"Path2D/PathFollow2D/Sprite2D:position:x"
|
|
# Absolute path (from "root")
|
|
"/root/Level/Path2D"
|
|
|
|
.. rst-class:: classref-section-separator
|
|
|
|
----
|
|
|
|
.. rst-class:: classref-descriptions-group
|
|
|
|
Method Descriptions
|
|
-------------------
|
|
|
|
.. _class_NodePath_method_get_as_property_path:
|
|
|
|
.. rst-class:: classref-method
|
|
|
|
:ref:`NodePath<class_NodePath>` **get_as_property_path** **(** **)** |const|
|
|
|
|
Returns a node path with a colon character (``:``) prepended, transforming it to a pure property path with no node name (defaults to resolving from the current node).
|
|
|
|
|
|
.. tabs::
|
|
|
|
.. code-tab:: gdscript
|
|
|
|
# This will be parsed as a node path to the "x" property in the "position" node.
|
|
var node_path = NodePath("position:x")
|
|
# This will be parsed as a node path to the "x" component of the "position" property in the current node.
|
|
var property_path = node_path.get_as_property_path()
|
|
print(property_path) # :position:x
|
|
|
|
.. code-tab:: csharp
|
|
|
|
// This will be parsed as a node path to the "x" property in the "position" node.
|
|
var nodePath = new NodePath("position:x");
|
|
// This will be parsed as a node path to the "x" component of the "position" property in the current node.
|
|
NodePath propertyPath = nodePath.GetAsPropertyPath();
|
|
GD.Print(propertyPath); // :position:x
|
|
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_NodePath_method_get_concatenated_names:
|
|
|
|
.. rst-class:: classref-method
|
|
|
|
:ref:`StringName<class_StringName>` **get_concatenated_names** **(** **)** |const|
|
|
|
|
Returns all paths concatenated with a slash character (``/``) as separator without subnames.
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_NodePath_method_get_concatenated_subnames:
|
|
|
|
.. rst-class:: classref-method
|
|
|
|
:ref:`StringName<class_StringName>` **get_concatenated_subnames** **(** **)** |const|
|
|
|
|
Returns all subnames concatenated with a colon character (``:``) as separator, i.e. the right side of the first colon in a node path.
|
|
|
|
|
|
.. tabs::
|
|
|
|
.. code-tab:: gdscript
|
|
|
|
var nodepath = NodePath("Path2D/PathFollow2D/Sprite2D:texture:load_path")
|
|
print(nodepath.get_concatenated_subnames()) # texture:load_path
|
|
|
|
.. code-tab:: csharp
|
|
|
|
var nodepath = new NodePath("Path2D/PathFollow2D/Sprite2D:texture:load_path");
|
|
GD.Print(nodepath.GetConcatenatedSubnames()); // texture:load_path
|
|
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_NodePath_method_get_name:
|
|
|
|
.. rst-class:: classref-method
|
|
|
|
:ref:`StringName<class_StringName>` **get_name** **(** :ref:`int<class_int>` idx **)** |const|
|
|
|
|
Gets the node name indicated by ``idx`` (0 to :ref:`get_name_count<class_NodePath_method_get_name_count>` - 1).
|
|
|
|
|
|
.. tabs::
|
|
|
|
.. code-tab:: gdscript
|
|
|
|
var node_path = NodePath("Path2D/PathFollow2D/Sprite2D")
|
|
print(node_path.get_name(0)) # Path2D
|
|
print(node_path.get_name(1)) # PathFollow2D
|
|
print(node_path.get_name(2)) # Sprite
|
|
|
|
.. code-tab:: csharp
|
|
|
|
var nodePath = new NodePath("Path2D/PathFollow2D/Sprite2D");
|
|
GD.Print(nodePath.GetName(0)); // Path2D
|
|
GD.Print(nodePath.GetName(1)); // PathFollow2D
|
|
GD.Print(nodePath.GetName(2)); // Sprite
|
|
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_NodePath_method_get_name_count:
|
|
|
|
.. rst-class:: classref-method
|
|
|
|
:ref:`int<class_int>` **get_name_count** **(** **)** |const|
|
|
|
|
Gets the number of node names which make up the path. Subnames (see :ref:`get_subname_count<class_NodePath_method_get_subname_count>`) are not included.
|
|
|
|
For example, ``"Path2D/PathFollow2D/Sprite2D"`` has 3 names.
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_NodePath_method_get_subname:
|
|
|
|
.. rst-class:: classref-method
|
|
|
|
:ref:`StringName<class_StringName>` **get_subname** **(** :ref:`int<class_int>` idx **)** |const|
|
|
|
|
Gets the resource or property name indicated by ``idx`` (0 to :ref:`get_subname_count<class_NodePath_method_get_subname_count>` - 1).
|
|
|
|
|
|
.. tabs::
|
|
|
|
.. code-tab:: gdscript
|
|
|
|
var node_path = NodePath("Path2D/PathFollow2D/Sprite2D:texture:load_path")
|
|
print(node_path.get_subname(0)) # texture
|
|
print(node_path.get_subname(1)) # load_path
|
|
|
|
.. code-tab:: csharp
|
|
|
|
var nodePath = new NodePath("Path2D/PathFollow2D/Sprite2D:texture:load_path");
|
|
GD.Print(nodePath.GetSubname(0)); // texture
|
|
GD.Print(nodePath.GetSubname(1)); // load_path
|
|
|
|
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_NodePath_method_get_subname_count:
|
|
|
|
.. rst-class:: classref-method
|
|
|
|
:ref:`int<class_int>` **get_subname_count** **(** **)** |const|
|
|
|
|
Gets the number of resource or property names ("subnames") in the path. Each subname is listed after a colon character (``:``) in the node path.
|
|
|
|
For example, ``"Path2D/PathFollow2D/Sprite2D:texture:load_path"`` has 2 subnames.
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_NodePath_method_hash:
|
|
|
|
.. rst-class:: classref-method
|
|
|
|
:ref:`int<class_int>` **hash** **(** **)** |const|
|
|
|
|
Returns the 32-bit hash value representing the **NodePath**'s contents.
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_NodePath_method_is_absolute:
|
|
|
|
.. rst-class:: classref-method
|
|
|
|
:ref:`bool<class_bool>` **is_absolute** **(** **)** |const|
|
|
|
|
Returns ``true`` if the node path is absolute (as opposed to relative), which means that it starts with a slash character (``/``). Absolute node paths can be used to access the root node (``"/root"``) or autoloads (e.g. ``"/global"`` if a "global" autoload was registered).
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_NodePath_method_is_empty:
|
|
|
|
.. rst-class:: classref-method
|
|
|
|
:ref:`bool<class_bool>` **is_empty** **(** **)** |const|
|
|
|
|
Returns ``true`` if the node path is empty.
|
|
|
|
.. rst-class:: classref-section-separator
|
|
|
|
----
|
|
|
|
.. rst-class:: classref-descriptions-group
|
|
|
|
Operator Descriptions
|
|
---------------------
|
|
|
|
.. _class_NodePath_operator_neq_NodePath:
|
|
|
|
.. rst-class:: classref-operator
|
|
|
|
:ref:`bool<class_bool>` **operator !=** **(** :ref:`NodePath<class_NodePath>` right **)**
|
|
|
|
Returns ``true`` if two node paths are not equal.
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_NodePath_operator_eq_NodePath:
|
|
|
|
.. rst-class:: classref-operator
|
|
|
|
:ref:`bool<class_bool>` **operator ==** **(** :ref:`NodePath<class_NodePath>` right **)**
|
|
|
|
Returns ``true`` if two node paths are equal, i.e. all node names in the path are the same and in the same order.
|
|
|
|
.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
|
|
.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`
|
|
.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`
|
|
.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)`
|
|
.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)`
|
|
.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)`
|