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

Szenenorganisation

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?

Wie man effektiv Beziehungen aufbaut

Wenn Godot-Anwender beginnen, ihre eigenen Szenen zu erstellen, stoßen sie häufig auf das folgende Problem:

Sie erstellen ihre erste Szene und füllen sie mit Inhalten, um dann irgendwann Teile ihrer Szene in separate Szenen zu speichern, da sich im Laufe der Zeit das Gefühl einstellt, dass sie die Dinge aufteilen sollten. Dann stellen sie jedoch fest, dass die direkten Verweise, auf die sie sich zuvor verlassen konnten, nicht mehr möglich sind. Die Wiederverwendung der Szene an mehreren Stellen führt zu Problemen, da die Node-Pfade nicht mehr ihre Ziele finden und Signalverbindungen, die im Editor erstellt wurde, abbrechen.

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.

One of the biggest things to consider in Object-Oriented Programming (OOP) is maintaining focused, singular-purpose classes with loose coupling to other parts of the codebase. This keeps the size of objects small (for maintainability) and improves their reusability.

Diese bewährten OOP-Praktiken haben mehrere Konsequenzen für bewährte Praktiken in der Szenenstruktur und der Skriptverwendung.

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.

Muss eine Szene mit einem externen Kontext interagieren, empfehlen erfahrene Entwickler die Verwendung von Dependency Injection. Dieses Verfahren beschreibt die Bereitstellung einer High-Level-API für die Abhängigkeiten der Low-Level-API. Warum das? Weil Klassen, die sich auf ihre externe Umgebung verlassen, ungewollt Bugs und unerwartetes Verhalten auslösen können.

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

Mit einem Signal verbinden. Äußerst sicher, sollte aber nur verwendet werden, um auf ein Verhalten zu "reagieren", nicht, um es einzuleiten. Signalnamen bestehen in der Regel aus Verben in der Vergangenheitsform, z.B. "entered", "skill_activated" oder "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.

Eine Methode aufrufen. Wird verwendet, um ein Verhalten einzuleiten.

# 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).

Initialisieren einer Callable-Property. Sicherer als eine Methode, da es nicht nötig ist, die Methode zu besitzen. Wird verwendet, um ein Verhalten einzuleiten.

# 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).

Initialisieren eines Nodes oder einer anderen Objektreferenz.

# 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);

Initialisieren eines 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.

Bemerkung

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.

Warnung

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.

A Graphical User Interface (GUI) like this can better inform project users of critical information about a Node. Does it have external dependencies? Have those dependencies been satisfied? Other programmers, and especially designers and writers, will need clear instructions in the messages telling them what to do to configure it.

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.

Skripte und Szenen als Erweiterungen von Engine-Klassen sollten allen OOP-Prinzipien folgen. Beispiele beinhalten...

Auswahl einer Node-Baum-Struktur

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.

Node "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.

Node "Main" (main.gd)

Node2D/Node3D "Welt" (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...

alle seine Daten intern trackt
global zugänglich sein sollte
isoliert existieren sollte

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

Bemerkung

Für kleinere Spiele wäre eine einfachere Alternative mit weniger Kontrolle ein Singleton namens "Game", das einfach die Methode SceneTree.change_scene_to_file() aufruft, um den Inhalt der Hauptszene auszutauschen. Diese Struktur behält mehr oder weniger "Welt" als Haupt-Spiel-Node.

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.

Bemerkung

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:

Ein zuverlässiger Dritter, wahrscheinlich ein Parent-Node, der die Zuweisung vermittelt.
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...

Fügen Sie einen "Spieler"-Node zu einem "Raum" hinzu.
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.

If memory is not a concern, you can...
- 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...
- Den Spieler an eine andere Stelle im Baum bewegen.
- Den Raum löschen.
- Den neuen Raum instanziieren und hinzufügen.
- 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:

Mehr Konsistenz.
Keine "Spezialfälle", die weder dokumentiert noch irgendwo gepflegt werden müssen.
Keine Möglichkeit für das Auftreten von Fehlern, da diese Details nicht berücksichtigt werden müssen.

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.
Die imperative Lösung: Verwenden Sie die Property top_level für den CanvasItem- oder Node3D-Node. Dies führt dazu, dass der Node seine geerbte Transformation ignoriert.

Bemerkung

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.

Der Schlüssel zur Organisation der Szene liegt darin, den Szenenbaum in relationalen Begriffen und nicht in räumlichen Begriffen zu betrachten. Sind die Nodes von der Existenz ihres Parent-Nodes abhängig? Wenn nicht, dann können sie ganz allein an anderer Stelle gedeihen. Wenn sie abhängig sind, dann ist es logisch, dass sie Child-Nodes dieses Parents sein sollten (und wahrscheinlich Teil der Szene dieses Parents, wenn sie es nicht schon sind).

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.