Organização da cena

This article covers topics related to the effective organization of scene content. Which nodes should you use? Where should you place them? How should they interact?

Como construir relações de forma eficaz

Quando os usuários do Godot começam a criar suas próprias cenas, eles geralmente se deparam com o seguinte problema:

Eles criam sua primeira cena e a preenchem com conteúdo apenas para, eventualmente, acabar salvando ramos de sua cena em cenas separadas, à medida que a sensação incômoda de que devem dividir as coisas começa a se acumular. No entanto, eles percebem que as referências concretas nas quais podiam confiar antes não são mais possíveis. Reutilizar a cena em vários lugares cria problemas porque os caminhos dos nós não encontram seus alvos e as conexões de sinal estabelecidas na quebra do editor.

To fix these problems, you must instantiate the sub-scenes without them requiring details about their environment. You need to be able to trust that the sub-scene will create itself without being picky about how it's used.

Uma das maiores coisas a considerar no POO é manter as classes focadas e de propósito único, com acoplamento fraco para outras partes da base do código. Isto mantém o tamanho dos objetos pequenos (para manutenção) e melhora a sua reusabilidade.

Essas melhores práticas de POO têm várias implicações para as melhores práticas na estrutura da cena e uso de script.

If at all possible, you should design scenes to have no dependencies. That is, you should create scenes that keep everything they need within themselves.

Se uma cena deve interagir com um contexto externo, desenvolvedores experientes recomendam o uso de Injeção de Dependência. Esta técnica envolve ter uma API de alto nível que fornece as dependências da API de baixo nível. Por que fazer isto? Porque classes que dependem de seu ambiente externo podem inadvertidamente acionar bugs e comportamentos inesperados.

To do this, you must expose data and then rely on a parent context to initialize it:

Connect to a signal. Extremely safe, but should be used only to "respond" to behavior, not start it. By convention, signal names are usually past-tense verbs like "entered", "skill_activated", or "item_collected".

# Parent
$Child.signal_name.connect(method_on_the_object)

# Child
signal_name.emit() # Triggers parent-specified behavior.

// Parent
GetNode("Child").Connect("SignalName", Callable.From(ObjectWithMethod.MethodOnTheObject));

// Child
EmitSignal("SignalName"); // Triggers parent-specified behavior.

// Parent
Node *node = get_node<Node>("Child");
if (node != nullptr) {
    // Note that get_node may return a nullptr, which would make calling the connect method crash the engine if "Child" does not exist!
    // So unless you are 1000% sure get_node will never return a nullptr, it's a good idea to always do a nullptr check.
    node->connect("signal_name", callable_mp(this, &ObjectWithMethod::method_on_the_object));
}

// Child
emit_signal("signal_name"); // Triggers parent-specified behavior.

Chame um método. Usado para iniciar o comportamento.

# Parent
$Child.method_name = "do"

# Child, assuming it has String property 'method_name' and method 'do'.
call(method_name) # Call parent-specified method (which child must own).

// Parent
GetNode("Child").Set("MethodName", "Do");

// Child
Call(MethodName); // Call parent-specified method (which child must own).

// Parent
Node *node = get_node<Node>("Child");
if (node != nullptr) {
    node->set("method_name", "do");
}

// Child
call(method_name); // Call parent-specified method (which child must own).

Inicialize uma propriedade Callable. Mais seguro do que um método, pois a propriedade do método é desnecessária. Utilizado para iniciar o comportamento.

# Parent
$Child.func_property = object_with_method.method_on_the_object

# Child
func_property.call() # Call parent-specified method (can come from anywhere).

// Parent
GetNode("Child").Set("FuncProperty", Callable.From(ObjectWithMethod.MethodOnTheObject));

// Child
FuncProperty.Call(); // Call parent-specified method (can come from anywhere).

// Parent
Node *node = get_node<Node>("Child");
if (node != nullptr) {
    node->set("func_property", Callable(&ObjectWithMethod::method_on_the_object));
}

// Child
func_property.call(); // Call parent-specified method (can come from anywhere).

Inicialize um Nó ou outra referência de Objeto.

# Parent
$Child.target = self

# Child
print(target) # Use parent-specified node.

// Parent
GetNode("Child").Set("Target", this);

// Child
GD.Print(Target); // Use parent-specified node.

// Parent
Node *node = get_node<Node>("Child");
if (node != nullptr) {
    node->set("target", this);
}

// Child
UtilityFunctions::print(target);

Inicialize um NodePath.

# Parent
$Child.target_path = ".."

# Child
get_node(target_path) # Use parent-specified NodePath.

// Parent
GetNode("Child").Set("TargetPath", NodePath(".."));

// Child
GetNode(TargetPath); // Use parent-specified NodePath.

// Parent
Node *node = get_node<Node>("Child");
if (node != nullptr) {
    node->set("target_path", NodePath(".."));
}

// Child
get_node<Node>(target_path); // Use parent-specified NodePath.

These options hide the points of access from the child node. This in turn keeps the child loosely coupled to its environment. You can reuse it in another context without any extra changes to its API.

Nota

Although the examples above illustrate parent-child relationships, the same principles apply towards all object relations. Nodes which are siblings should only be aware of their own hierarchies while an ancestor mediates their communications and references.

# Parent
$Left.target = $Right.get_node("Receiver")

# Left
var target: Node
func execute():
    # Do something with 'target'.

# Right
func _init():
    var receiver = Receiver.new()
    add_child(receiver)

// Parent
GetNode<Left>("Left").Target = GetNode("Right/Receiver");

public partial class Left : Node
{
    public Node Target = null;

    public void Execute()
    {
        // Do something with 'Target'.
    }
}

public partial class Right : Node
{
    public Node Receiver = null;

    public Right()
    {
        Receiver = ResourceLoader.Load<Script>("Receiver.cs").New();
        AddChild(Receiver);
    }
}

// Parent
get_node<Left>("Left")->target = get_node<Node>("Right/Receiver");

class Left : public Node {
    GDCLASS(Left, Node)

    protected:
        static void _bind_methods() {}

    public:
        Node *target = nullptr;

        Left() {}

        void execute() {
            // Do something with 'target'.
        }
};

class Right : public Node {
    GDCLASS(Right, Node)

    protected:
        static void _bind_methods() {}

    public:
        Node *receiver = nullptr;

        Right() {
            receiver = memnew(Node);
            add_child(receiver);
        }
};

The same principles also apply to non-Node objects that maintain dependencies on other objects. Whichever object owns the other objects should manage the relationships between them.

Aviso

You should favor keeping data in-house (internal to a scene), though, as placing a dependency on an external context, even a loosely coupled one, still means that the node will expect something in its environment to be true. The project's design philosophies should prevent this from happening. If not, the code's inherent liabilities will force developers to use documentation to keep track of object relations on a microscopic scale; this is otherwise known as development hell. Writing code that relies on external documentation to use it safely is error-prone by default.

To avoid creating and maintaining such documentation, you convert the dependent node ("child" above) into a tool script that implements _get_configuration_warnings(). Returning a non-empty PackedStringArray from it will make the Scene dock generate a warning icon with the string(s) as a tooltip by the node. This is the same icon that appears for nodes such as the Area2D node when it has no child CollisionShape2D nodes defined. The editor then self-documents the scene through the script code. No content duplication via documentation is necessary.

Uma GUI como essa pode informar melhor os usuários do projeto sobre informações críticas sobre um Nó.Ele possui dependências externas? Essas dependências foram satisfeitas? Outros programadores, e especialmente designers e escritores, precisarão de instruções claras nas mensagens dizendo-lhes o que fazer para configurá-lo.

So, why does all this complex switcheroo work? Well, because scenes operate best when they operate alone. If unable to work alone, then working with others anonymously (with minimal hard dependencies, i.e. loose coupling) is the next best thing. Inevitably, changes may need to be made to a class, and if these changes cause it to interact with other scenes in unforeseen ways, then things will start to break down. The whole point of all this indirection is to avoid ending up in a situation where changing one class results in adversely affecting other classes dependent on it.

Scripts e cenas, como extensões de classes do motor, devem obedecer a todos os princípios de POO. Exemplos incluem...

Escolhendo uma estrutura de árvore de nós

You might start to work on a game but get overwhelmed by the vast possibilities before you. You might know what you want to do, what systems you want to have, but where do you put them all? How you go about making your game is always up to you. You can construct node trees in countless ways. If you are unsure, this guide can give you a sample of a decent structure to start with.

A game should always have an "entry point"; somewhere you can definitively track where things begin so that you can follow the logic as it continues elsewhere. It also serves as a bird's eye view of all other data and logic in the program. For traditional applications, this is normally a "main" function. In Godot, it's a Main node.

Nó "Main" (main.gd)

The main.gd script will serve as the primary controller of your game.

Then you have an in-game "World" (a 2D or 3D one). This can be a child of Main. In addition, you will need a primary GUI for your game that manages the various menus and widgets the project needs.

Nó "Main" (main.gd)

Node2D/Node3D "World" (game_world.gd)

Control "GUI" (gui.gd)

When changing levels, you can then swap out the children of the "World" node. Changing scenes manually gives you full control over how your game world transitions.

The next step is to consider what gameplay systems your project requires. If you have a system that...

rastreia todos os seus dados internamente
deve ser globalmente acessível
deve existir isoladamente

... then you should create an autoload 'singleton' node.

Nota

Para jogos menores, uma alternativa mais simples com menos controle seria ter um singleton "Game" que simplesmente chama o método SceneTree.change_scene_to_file() para trocar o conteúdo da cena principal. Esta estrutura mantém mais ou menos o "Mundo" como o nó principal do jogo.

Any GUI would also need to be either a singleton, a transitory part of the "World", or manually added as a direct child of the root. Otherwise, the GUI nodes would also delete themselves during scene transitions.

If you have systems that modify other systems' data, you should define those as their own scripts or scenes, rather than autoloads. For more information, see Autoloads versus regular nodes.

Each subsystem within your game should have its own section within the SceneTree. You should use parent-child relationships only in cases where nodes are effectively elements of their parents. Does removing the parent reasonably mean that the children should also be removed? If not, then it should have its own place in the hierarchy as a sibling or some other relation.

Nota

In some cases, you need these separated nodes to also position themselves relative to each other. You can use the RemoteTransform / RemoteTransform2D nodes for this purpose. They will allow a target node to conditionally inherit selected transform elements from the Remote* node. To assign the target NodePath, use one of the following:

Um terceiro confiável, provavelmente um nó pai, para mediar a atribuição.
A group, to pull a reference to the desired node (assuming there will only ever be one of the targets).

When you should do this is subjective. The dilemma arises when you must micro-manage when a node must move around the SceneTree to preserve itself. For example...

Adicionar um nó "jogador" a uma "sala".
Need to change rooms, so you must delete the current room.
Before the room can be deleted, you must preserve and/or move the player.

Se a memória não for uma preocupação, você pode...
- Create the new room.
- Move the player to the new room.
- Delete the old room.
If memory is a concern, instead you will need to...
- Mover o jogador para outro lugar na árvore.
- Deletar a sala.
- Instanciar e adicionar a nova sala.
- Re-add the player to the new room.

The issue is that the player here is a "special case" where the developers must know that they need to handle the player this way for the project. The only way to reliably share this information as a team is to document it. Keeping implementation details in documentation is dangerous. It's a maintenance burden, strains code readability, and unnecessarily bloats the intellectual content of a project.

In a more complex game with larger assets, it can be a better idea to keep the player somewhere else in the SceneTree entirely. This results in:

Mais consistência.
Nenhum "caso especial" que deva ser documentado e mantido em algum lugar.
Nenhuma oportunidade para erros ocorrerem porque estes detalhes não são levados em consideração.

In contrast, if you ever need a child node that does not inherit the transform of its parent, you have the following options:

The declarative solution: place a Node in between them. Since it doesn't have a transform, they won't pass this information to its children.
The imperative solution: Use the top_level property for the CanvasItem or Node3D node. This will make the node ignore its inherited transform.

Nota

If building a networked game, keep in mind which nodes and gameplay systems are relevant to all players versus those just pertinent to the authoritative server. For example, users do not all need to have a copy of every players' "PlayerController" logic - they only need their own. Keeping them in a separate branch from the "world" can help simplify the management of game connections and the like.

A chave para a organização da cena é considerar a SceneTree em termos relacionais, em vez de termos espaciais. Os nós são dependentes da existência de seus pais? Do contrário, eles podem prosperar sozinhos em outro lugar. Se forem dependentes, é lógico que devam ser filhos desse pai (e provavelmente parte da cena desse pai, se ainda não o forem).

Does this mean nodes themselves are components? Not at all. Godot's node trees form an aggregation relationship, not one of composition. But while you still have the flexibility to move nodes around, it is still best when such moves are unnecessary by default.