Attention: Here be dragons
This is the
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
get_node() to reference nodes from a script can sometimes be fragile.
If you move a button in a UI scene from one panel to another, the button's node
path changes, and if a script uses
get_node() with a hard-coded node path,
the script will not be able to find the button anymore.
In situations like this, the node can be turned into a scene unique node to avoid having to update the script every time the node's path is changed.
In the Scene tree dock, right-click on a node and select Access as Unique Name in the context menu.
After selecting the option, the node will now have a percent symbol (%) next to its name in the scene tree:
You can now use the node in your script. For example, you can reference it with
get_node() method call by typing the % symbol, followed by the node's
get_node("%RedButton").text = "Hello" %RedButton.text = "Hello" # Shorter syntax
GetNode<Button>("%RedButton").Text = "Hello";
A scene unique node can only be retrieved by a node inside the same scene. To demonstrate this limitation, consider this example Player scene that instances a Sword scene:
Here are the results of
get_node() calls inside the Player script:
get_node("%Eyes")returns the Eyes node.
These are the results of
get_node() calls inside the Sword script:
get_node("%Hilt")returns the Hilt node.
If a script has access to a node in another scene, it can call
that node to get scene unique nodes from that node's scene. This also works in a
node path, which avoids multiple
get_node() calls. Here are two ways to get
the Hilt node from the Player script using scene unique nodes:
get_node("Hand/Sword").get_node("%Hilt")returns the Hilt node.
get_node("Hand/Sword/%Hilt")also returns the Hilt node.
Scene unique names don't only work at the end of a node path. They can be used in the middle to navigate from one node to another. For example, the Sword node is marked as a scene unique node in the Player scene, so this is possible:
get_node("%Sword/%Hilt")returns the Hilt node.
Scene unique nodes are a useful tool to navigate a scene. However, there are some situations where other techniques may be better.
A Group allows locating a node (or a group of many nodes) from any other node, no matter what scene the two nodes are located in.
A Singleton (Autoload) is an always loaded node that can be accessed directly by any node regardless of the scene. These are useful when some data or functionality is shared globally.
Node.find_child() finds a node by name
without knowing its full path. This seems similar to a scene unique node, but
this method is able to find nodes in nested scenes, and doesn't require marking
the node in the scene editor in any way. However, this method is slow. Scene
unique nodes are cached by Godot and are fast to retrieve, but each time the
method is called,
find_child() needs to check every descendant (every child,
grandchild, and so on).