Struct NodePath

pub struct NodePath { /* private fields */ }

Expand description

A pre-parsed scene tree path.

§Null bytes

Note that Godot ignores any bytes after a null-byte. This means that for instance "hello, world!" and "hello, world!\0 ignored by Godot" will be treated as the same string if converted to a NodePath.

§All string types

Intended use case	String type
General purpose	`GString`
Interned names	`StringName`
Scene-node paths	`NodePath`

§Godot docs

NodePath (stable)

Implementations§

§

impl NodePath

pub fn get_name(&self, index: usize) -> StringName

Returns the node name at position index.

If you want to get a property name instead, check out get_subname().

§Example

let path = NodePath::from("../RigidBody2D/Sprite2D");
godot_print!("{}", path.get_name(0)); // ".."
godot_print!("{}", path.get_name(1)); // "RigidBody2D"
godot_print!("{}", path.get_name(2)); // "Sprite"

§Panics (safeguards-balanced)

If index is out of bounds. In safeguards-disengaged level, a Godot error is generated and the result is unspecified (but safe).

pub fn get_subname(&self, index: usize) -> StringName

Returns the node subname (property) at position index.

If you want to get a node name instead, check out get_name().

§Example

let path = NodePath::from("Sprite2D:texture:resource_name");
godot_print!("{}", path.get_subname(0)); // "texture"
godot_print!("{}", path.get_subname(1)); // "resource_name"

§Panics (safeguards-balanced)

If index is out of bounds. In safeguards-disengaged level, a Godot error is generated and the result is unspecified (but safe).

pub fn get_name_count(&self) -> usize

Returns the number of node names in the path. Property subnames are not included.

pub fn get_subname_count(&self) -> usize

Returns the number of property names (“subnames”) in the path. Each subname in the node path is listed after a colon character (:).

pub fn get_total_count(&self) -> usize

Returns the total number of names + subnames.

This method does not exist in Godot and is provided in Rust for convenience.

pub fn hash_u32(&self) -> u32

Returns a 32-bit integer hash value representing the node path.

pub fn subpath(&self, range: impl SignedRange) -> NodePath

Available on since_api=4.3 only.

Returns the range begin..exclusive_end as a new NodePath.

The absolute value of begin and exclusive_end will be clamped to get_total_count().

§Usage

For negative indices, use wrapped().

let path = NodePath::from("path/to/Node:with:props");

// If upper bound is not defined, `exclusive_end` will span to the end of the `NodePath`.
let sub = path.subpath(2..);
assert_eq!(sub, ":props".into());

// If either `begin` or `exclusive_end` are negative, they will be relative to the end of the `NodePath`.
let total_count = path.get_total_count();
let wrapped_sub = path.subpath(wrapped(0..-2));
let normal_sub = path.subpath(0..total_count - 2);
// Both are equal to "path/to/Node".
assert_eq!(wrapped_sub, normal_sub);

Godot equivalent: slice

§Compatibility

The slice() behavior for Godot <= 4.3 is unintuitive, see #100954. Godot-rust automatically changes this to the fixed version for Godot 4.4+, even when used in older versions. So, the behavior is always the same.

§

impl NodePath

pub fn is_absolute(&self) -> bool

Returns true if the node path is absolute. Unlike a relative path, an absolute path is represented by a leading slash character (/) and always begins from the SceneTree. It can be used to reliably access nodes from the root node (e.g. "/root/Global" if an autoload named “Global” exists).

pub fn get_concatenated_names(&self) -> StringName

Returns all node names concatenated with a slash character (/) as a single StringName.

pub fn get_concatenated_subnames(&self) -> StringName

Returns all property subnames concatenated with a colon character (:) as a single StringName.

var node_path = ^"Sprite2D:texture:resource_name"
print(node_path.get_concatenated_subnames()) # Prints "texture:resource_name"

pub fn get_as_property_path(&self) -> NodePath

Returns a copy of this node path with a colon character (:) prefixed, transforming it to a pure property path with no node names (relative to the current node).

# node_path points to the "x" property of the child node named "position".
var node_path = ^"position:x"

# property_path points to the "position" in the "x" axis of this node.
var property_path = node_path.get_as_property_path()
print(property_path) # Prints ":position:x"