Up to date

This page is up to date for Godot 4.0. If you still find outdated information, please open an issue.

Scene Unique Nodes

Introduction

Using 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.

Creation and usage

In the Scene tree dock, right-click on a node and select Access as Unique Name in the context menu.

../../_images/unique_name.webp

After selecting the option, the node will now have a percent symbol (%) next to its name in the scene tree:

../../_images/percent.webp

You can now use the node in your script. For example, you can reference it with a get_node() method call by typing the % symbol, followed by the node's name:

get_node("%RedButton").text = "Hello"
%RedButton.text = "Hello" # Shorter syntax

Same-scene limitation

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:

../../_images/unique_name_scene_instance_example.webp

Here are the results of get_node() calls inside the Player script:

  • get_node("%Eyes") returns the Eyes node.

  • get_node("%Hilt") returns null.

These are the results of get_node() calls inside the Blade script:

  • get_node("%Eyes") returns null.

  • get_node("%Hilt") returns the Hilt node.

If a script has access to a node in another scene, it can call get_node() on 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.