Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

NodePath

A pre-parsed scene tree path.

Description

The NodePath built-in Variant type represents a path to a node or property in a hierarchy of nodes. It is designed to be efficiently passed into many built-in methods (such as Node.get_node, Object.set_indexed, Tween.tween_property, etc.) without a hard dependence on the node or property they point to.

A node path is represented as a String composed of slash-separated (/) node names and colon-separated (:) property names (also called "subnames"). Similar to a filesystem path, ".." and "." are special node names. They refer to the parent node and the current node, respectively.

The following examples are paths relative to the current node:

^"A"     # Points to the direct child A.
^"A/B"   # Points to A's child B.
^"."     # Points to the current node.
^".."    # Points to the parent node.
^"../C"  # Points to the sibling node C.
^"../.." # Points to the grandparent node.

A leading slash means the path is absolute, and begins from the SceneTree:

^"/root"            # Points to the SceneTree's root Window.
^"/root/Title"      # May point to the main scene's root node named "Title".
^"/root/Global"     # May point to an autoloaded node or scene named "Global".

Despite their name, node paths may also point to a property:

^"position"            # Points to this object's position.
^"position:x"          # Points to this object's position in the x axis.
^"Camera3D:rotation:y" # Points to the child Camera3D and its y rotation.
^"/root:size:x"        # Points to the root Window and its width.

Node paths cannot check whether they are valid and may point to nodes or properties that do not exist. Their meaning depends entirely on the context in which they're used.

You usually do not have to worry about the NodePath type, as strings are automatically converted to the type when necessary. There are still times when defining node paths is useful. For example, exported NodePath properties allow you to easily select any node within the currently edited scene. They are also automatically updated when moving, renaming or deleting nodes in the scene tree editor. See also @GDScript.@export_node_path.

See also StringName, which is a similar type designed for optimised strings.

Note: In a boolean context, a NodePath will evaluate to false if it is empty (NodePath("")). Otherwise, a NodePath will always evaluate to true.

Note

There are notable differences when using this API with C#. See C# API differences to GDScript for more information.

Tutorials

Constructors

NodePath

NodePath()

NodePath

NodePath(from: NodePath)

NodePath

NodePath(from: String)

Methods

NodePath

get_as_property_path() const

StringName

get_concatenated_names() const

StringName

get_concatenated_subnames() const

StringName

get_name(idx: int) const

int

get_name_count() const

StringName

get_subname(idx: int) const

int

get_subname_count() const

int

hash() const

bool

is_absolute() const

bool

is_empty() const

NodePath

slice(begin: int, end: int = 2147483647) const

Operators

bool

operator !=(right: NodePath)

bool

operator ==(right: NodePath)


Constructor Descriptions

NodePath NodePath()

Constructs an empty NodePath.


NodePath NodePath(from: NodePath)

Constructs a NodePath as a copy of the given NodePath.


NodePath NodePath(from: