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.

Checking the stable version of the documentation...

Nós únicos da cena

Introdução

Usar get_node() para referenciar nós a partir de um script às vezes pode ser frágil. Se você mover um botão em uma cena de UI de um painel para outro, o caminho do nó do botão muda, e se um script usar get_node() com um caminho de nó fixo (hard-coded), o script não será mais capaz de encontrar o botão.

Em situações como essa, o nó pode ser transformado em um nó único de cena (scene unique node) para evitar ter que atualizar o script toda vez que o caminho do nó for alterado.

Criação e uso

Existem duas maneiras de criar um nó exclusivo da cena.

Na doca da árvore de Cena, clique com o botão direito em um nó e selecione Access as Unique Name (Acessar como Nome Único) no menu de contexto.

Após selecionar a opção, o nó agora terá um símbolo de porcentagem (%) ao lado de seu nome na árvore de cena:

Você também pode fazer isso ao renomear o nó adicionando "%" no início do nome. Assim que você confirmar, o símbolo de porcentagem aparecerá ao lado de seu nome.

Você pode agora usar o nó em seu script. Por exemplo, você pode referenciá-lo com uma chamada do método get_node() digitando o símbolo %, seguido pelo nome do nó:

GDScriptC#

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

Limitação de mesma cena

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 instantiates a Sword scene:

Aqui estão os resultados das chamadas de get_node() dentro do script do Player:

• get_node("%Eyes") retorna o nó Eyes.

• get_node("%Hilt") retorna null.

Estes são os resultados das chamadas de get_node() dentro do script da Sword:

• get_node("%Eyes") retorna null.

• get_node("%Hilt") retorna o nó Hilt.

Se um script tiver acesso a um nó em outra cena, ele pode chamar get_node() naquele nó para obter nós únicos de cena da cena daquele nó. Isso também funciona em um caminho de nó, o que evita múltiplas chamadas de get_node(). Aqui estão duas maneiras de obter o nó Hilt a partir do script do Player usando nós únicos de cena:

• get_node("Hand/Sword").get_node("%Hilt") retorna o nó Hilt.

• get_node("Hand/Sword/%Hilt") também retorna o nó Hilt.

Nomes únicos de cena não funcionam apenas no final de um caminho de nó. Eles podem ser usados no meio para navegar de um nó para outro. Por exemplo, o nó Sword está marcado como um nó único de cena na cena Player, então isto é possível:

• get_node("%Sword/%Hilt") retorna o nó Hilt.

Alternativas

Nós únicos de cena são uma ferramenta útil para navegar em uma cena. No entanto, existem algumas situações onde outras técnicas podem ser melhores.

Um Group (Grupo) permite localizar um nó (ou um grupo de muitos nós) a partir de qualquer outro nó, não importa em qual cena os dois nós estejam localizados.

Um Singleton (Autoload) é um nó sempre carregado que pode ser acessado diretamente por qualquer nó, independentemente da cena. Estes são úteis quando alguns dados ou funcionalidades são compartilhados globalmente.

Node.find_child() encontra um nó por nome sem saber seu caminho completo. Isso parece semelhante a um nó único de cena, mas este método é capaz de encontrar nós em cenas aninhadas e não exige marcar o nó no editor de cena de nenhuma forma. No entanto, este método é lento. Nós únicos de cena são armazenados em cache pelo Godot e são rápidos de recuperar, mas toda vez que o método é chamado, o find_child() precisa verificar cada descendente (cada filho, neto e assim por diante).