Up to date

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

Einführung in die Klassenreferenz¶

Auf dieser Seite wird erklärt, wie man die Klassenreferenz schreibt. Sie erfahren, wo Sie neue Beschreibungen für die Klassen, Methoden und Propertys für Godots Built-in-Node-Typen schreiben können.

Siehe auch

Wie Sie Ihre Änderungen mit dem Git-Versionskontrollsystem an das Godot-Projekt übermitteln können, erfahren Sie unter Beitragen zur Klassenreferenz.

Die Referenz für jede Klasse ist in einer XML-Datei wie der folgenden enthalten:

<class name="Node2D" inherits="CanvasItem" version="4.0">
    <brief_description>
        A 2D game object, inherited by all 2D-related nodes. Has a position, rotation, scale, and Z index.
    </brief_description>
    <description>
        A 2D game object, with a transform (position, rotation, and scale). All 2D nodes, including physics objects and sprites, inherit from Node2D. Use Node2D as a parent node to move, scale and rotate children in a 2D project. Also gives control of the node's render order.
    </description>
    <tutorials>
        <link title="Custom drawing in 2D">https://docs.godotengine.org/en/latest/tutorials/2d/custom_drawing_in_2d.html</link>
        <link title="All 2D Demos">https://github.com/godotengine/godot-demo-projects/tree/master/2d</link>
    </tutorials>
    <methods>
        <method name="apply_scale">
            <return type="void">
            </return>
            <argument index="0" name="ratio" type="Vector2">
            </argument>
            <description>
                Multiplies the current scale by the [code]ratio[/code] vector.
            </description>
        </method>
        [...]
        <method name="translate">
            <return type="void">
            </return>
            <argument index="0" name="offset" type="Vector2">
            </argument>
            <description>
                Translates the node by the given [code]offset[/code] in local coordinates.
            </description>
        </method>
    </methods>
    <members>
        <member name="global_position" type="Vector2" setter="set_global_position" getter="get_global_position">
            Global position.
        </member>
        [...]
        <member name="z_index" type="int" setter="set_z_index" getter="get_z_index" default="0">
            Z index. Controls the order in which the nodes render. A node with a higher Z index will display in front of others.
        </member>
    </members>
    <constants>
    </constants>
</class>

Es beginnt mit kurzen und langen Beschreibungen. In den generierten Dokumenten steht die Kurzbeschreibung immer oben auf der Seite, während die Langbeschreibung unterhalb der Liste der Methoden, Variablen und Konstanten steht. Methoden, Membervariablen, Konstanten und Signale finden Sie in separaten XML-Nodes.

Für jedes dieser Elemente müssen Sie herausfinden, wie es im Quellcode von Godot funktioniert. Füllen Sie dann ihre Dokumentation aus, indem Sie den Text in diesen Tags vervollständigen oder verbessern:

<brief_description>
<description>
<constant>
<method> (in ihrem <description>-Tag; Rückgabetypen und Argumente benötigen keine separaten Dokumentationsstrings)
<member>
<signal> (in seinem <description>-Tag); Argumente benötigen keine separaten Dokumentationsstrings)
<constant>

Schreiben Sie in einer klaren und einfachen Sprache. Befolgen Sie immer die Schreibrichtlinien, um Ihre Beschreibungen kurz und leicht lesbar zu halten. Lassen Sie keine Leerzeilen in den Beschreibungen: Jede Zeile in der XML-Datei ergibt einen neuen Absatz, auch wenn sie leer ist.

Wie man Klassen-XMLs bearbeitet¶

Bearbeiten Sie die Datei für die von Ihnen gewählte Klasse in doc/classes/, um die Klassenreferenz zu aktualisieren. Der Ordner enthält eine XML-Datei für jede Klasse. In der XML-Datei sind die Konstanten und Methoden aufgeführt, die Sie in der Klassenreferenz finden. Godot generiert und aktualisiert die XML-Datei automatisch.

Bemerkung

Für einige Module im Quellcode der Engine finden Sie die XML-Dateien stattdessen im Verzeichnis modules/<module_name>/doc_classes/.

Bearbeiten Sie sie mit Ihrem bevorzugten Texteditor. Wenn Sie einen Code-Editor verwenden, stellen Sie sicher, dass dieser den Einrückungsstil nicht ändert: Sie sollten Tabulatoren für die XML und vier Leerzeichen innerhalb von Blöcken im BBCode-Stil verwenden. Mehr dazu weiter unten.

Um zu überprüfen, ob die von Ihnen vorgenommenen Änderungen in der generierten Dokumentation korrekt sind, navigieren Sie zum Ordner doc/ und führen Sie den Befehl make rst aus. Dies wird die XML-Dateien in das Format der Online-Dokumentation konvertieren und Fehler ausgeben, falls etwas nicht stimmt.

Alternativ dazu können Sie Godot kompilieren und die geänderte Seite in der eingebauten Code-Referenz öffnen. Um zu erfahren, wie man die Engine kompiliert, lesen Sie den Kompilier-Anleitung.

Wir empfehlen die Verwendung eines Code-Editors, der XML-Dateien unterstützt, wie Vim, Atom, Visual Studio Code, Notepad++ oder andere, um die Datei bequem zu bearbeiten. Sie können auch deren Suchfunktion verwenden, um Klassen und Propertys schnell zu finden.

Tipp

Wenn Sie Visual Studio Code verwenden, können Sie die vscode-xml-Erweiterung installieren, um Linting für Klassenreferenz-XML-Dateien zu erhalten.

Verbessern Sie die Formatierung mit BBCode-Tags¶

Die XML-Klassenreferenz von Godot unterstützt BBCode-ähnliche Tags für die Verknüpfung sowie die Formatierung von Text und Code. In den folgenden Tabellen finden Sie die verfügbaren Tags, Verwendungsbeispiele und die Ergebnisse nach der Konvertierung in reStructuredText.

Links¶

Wenn Sie auf einen Member einer anderen Klasse verweisen, müssen Sie den Klassennamen angeben. Bei Verweisen auf dieselbe Klasse ist der Klassenname optional und kann weggelassen werden.

Tag und Beschreibung	Beispiel	Ergebnis
`[Class]` Link zur Klasse	`Move the [Sprite2D].`	Move the Sprite2D.
`[annotation Class.name]` Link zur Annotation	`See [annotation @GDScript.@export].`	See @GDScript.@export.
`[constant Class.name]` Link zur Konstante	`See [constant @GlobalScope.KEY_F1].`	See @GlobalScope.KEY_F1.
`[enum Class.name]` Link zum Enum	`See [enum Mesh.ArrayType].`	See Mesh.ArrayType.
`[method Class.name]` Link zur Methode	`Call [method Node3D.hide].`	Call Node3D.hide().
`[member Class.name]` Link zum Member	`Get [member Node2D.scale].`	Get Node2D.scale.
`[signal Class.name]` Link zum Signal	`Emit [signal Node.renamed].`	Emit Node.renamed.
`[theme_item Class.name]` Link zum Theme-Element	`See [theme_item Label.font].`	See Label.font.

Bemerkung

Aktuell verfügt nur @GDScript über Annotationen.

Textformatierung¶

Tag und Beschreibung	Beispiel	Ergebnis
`[param name]` Formatiert einen Parameter-Namen (als Code)	`Takes [param size] for the size.`	Takes `size` for the size.
`[br]` Zeilenumbruch	`Line 1.[br]` `Line 2.`	Line 1. Line 2.
`[b]` `[/b]` Fett	`Some [b]bold[/b] text.`	Some bold text.
`[i]` `[/i]` Kursiv	`Some [i]italic[/i] text.`	Some italic text.
`[kbd]` `[/kbd]` Tasten/Maus-Kürzel	`Some [kbd]Ctrl + C[/kbd] key.`	Some `Ctrl + C` key.

Codeformatierung¶

Tag und Beschreibung	Beispiel	Ergebnis
`[code]` `[/code]` Monospace	`Some [code]monospace[/code] text.`	Some `monospace` text.
`[codeblock]` `[/codeblock]` Mehrzeiliger vorformatierter Block	Siehe unten	Siehe unten
`[codeblocks]` `[/codeblocks]` Codeblock für mehrere Sprachen	Siehe unten	Siehe unten
`[gdscript]` `[/gdscript]` GDScript Codeblock-tab in Codeblöcken	Siehe unten	Siehe unten
`[csharp]` `[/csharp]` C# Codeblock-tab in Codeblöcken	Siehe unten	Siehe unten

Bemerkung

[code] deaktiviert BBCode, bis der Parser auf [/code] trifft.
[codeblock] deaktiviert BBCode, bis der Parser auf [/codeblock] trifft.

Warnung

Verwenden Sie [codeblock] für vorformatierte Codeblöcke. Verwenden Sie innerhalb von [codeblock] immer vier Leerzeichen für die Einrückung. Der Parser wird Tabs löschen.

Zum Beispiel:

[codeblock]
func _ready():
    var sprite = get_node("Sprite2D")
    print(sprite.get_pos())
[/codeblock]

Wird angezeigt als:

func _ready():
    var sprite = get_node("Sprite2D")
    print(sprite.get_pos())

Wenn Sie unterschiedliche Codeversionen in GDScript und C# benötigen, verwenden Sie stattdessen [codeblocks]. Wenn Sie [codeblocks] verwenden, müssen Sie auch mindestens eines der sprachspezifischen Tags [gdscript] und [csharp] haben.

Schreiben Sie immer zuerst GDScript-Codebeispiele! Sie können dieses experimentelle Code-Übersetzungs-Tool verwenden, um Ihren Workflow zu beschleunigen.

[codeblocks]
[gdscript]
func _ready():
    var sprite = get_node("Sprite2D")
    print(sprite.get_pos())
[/gdscript]
[csharp]
public override void _Ready()
{
    var sprite = GetNode("Sprite2D");
    GD.Print(sprite.GetPos());
}
[/csharp]
[/codeblocks]

Der obige Code wird wie folgt angezeigt:

func _ready():
    var sprite = get_node("Sprite2D")
    print(sprite.get_pos())

public override void _Ready()
{
    var sprite = GetNode("Sprite2D");
    GD.Print(sprite.GetPos());
}

Um wichtige Informationen zu kennzeichnen, fügen Sie am Ende der Beschreibung einen Absatz hinzu, der mit "[b]Note:[/b]" beginnt:

[b]Note:[/b] Only available when using the Vulkan renderer.

Um wichtige Informationen zu kennzeichnen, die zu Sicherheitsproblemen oder Datenverlust führen können, wenn sie nicht sorgfältig beachtet werden, fügen Sie am Ende der Beschreibung einen Absatz hinzu, der mit "[b]Warning:[/b]" beginnt:

[b]Warning:[/b] If this property is set to [code]true[/code], it allows clients to execute arbitrary code on the server.

Fügen Sie für veraltete Propertys einen Absatz hinzu, der mit "[i]Deprecated.[/i]" beginnt. Beachten Sie die Verwendung von Kursivschrift anstelle von Fettdruck:

[i]Deprecated.[/i] This property has been replaced by [member other_property].

Stellen Sie in allen oben beschriebenen Abschnitten sicher, dass die Interpunktion aus Gründen der Konsistenz Teil der BBCode-Tags ist.