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.@rpc].`	See @GDScript.@rpc.
`[constant Class.name]` Link zur Konstante	`See [Konstante Color.RED].`	Siehe Color.RED.
`[enum Class.name]` Link zum Enum	`See [enum Mesh.ArrayType].`	See Mesh.ArrayType.
`[member Class.name]` Link zum Member	`Get [member Node2D.scale].`	Get Node2D.scale.
`[method Class.name]` Link zur Methode	`Call [method Node3D.hide].`	Call Node3D.hide().
`[constructor Class.name]` Link zum Built-in-Konstruktor	`Verwenden Sie [constructor Color.Color].`	Verwenden Sie Color.Color.
`[operator Class.name]` Link zum Built-in-Operator	`Verwenden Sie [operator Color.operator *].`	Verwenden Sie Color.operator *.
`[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.
`[param name]` Parameter-Name (als Code)	`Takes [param size] for the size.`	Takes `size` for the size.

Bemerkung

Aktuell verfügt nur @GDScript über Annotationen.

Textformatierung

Tag und Beschreibung	Beispiel	Ergebnis
`[br]` Zeilenumbruch	`Line 1.[br]` `Line 2.`	Line 1. Line 2.
`[lb]` `[rb]` `[` bzw. `]`	`[lb]b[rb]text[lb]/b[rb]`	[b]text[/b]
`[b]` `[/b]` Fett	`Do [b]not[/b] call this method.`	Rufen Sie diese Methode nicht auf.
`[i]` `[/i]` Kursiv	`Gibt die [i]globale[/i] Position zurück.`	Gibt die globale Position zurück.
`[u]` `[/u]` Unterstreichen	`Verwenden Sie [u]immer[/u] diese Methode.`	Always use this method.
`[s]` `[/s]` Durchgestrichen	`[s]Veraltete Informationen.[/s]`	~~Outdated information.~~
`[url]` `[/url]` Hyperlink	`[url]https://example.com[/url]` `[url=https://example.com]Website[/url]`	https://example.com Website
`[center]` `[/center]` Horizontale Zentrierung	`[center]2 + 2 = 4[/center]`	2 + 2 = 4
`[kbd]` `[/kbd]` Tasten/Maus-Kürzel	`Press [kbd]Ctrl + C[/kbd].`	Drücken Sie `Strg + C`.
`[code]` `[/code]` Inline-Code-Fragment	`Returns [code]true[/code].`	Gibt `true` zurück.

Bemerkung

Einige unterstützte Tags wie [color] und [font] sind hier nicht aufgeführt, da sie in der Dokumentation der Engine nicht empfohlen werden.
[kbd] deaktiviert BBCode, bis der Parser auf [/kbd] trifft.
[code] deaktiviert BBCode, bis der Parser auf [/code] trifft.

Formatierung von Codeblöcken

Für die Formatierung von Codeblöcken gibt es zwei Möglichkeiten:

Verwenden Sie [codeblock], wenn Sie ein Beispiel für eine bestimmte Sprache hinzufügen möchten.
Verwenden Sie [codeblocks], [gdscript] und [csharp], wenn Sie das gleiche Beispiel für beide Sprachen, GDScript und C#, hinzufügen möchten.

Standardmäßig verwendet [codeblock] das GDScript-Syntax-Highlighting. Sie können dies mit dem Attribut lang ändern. Derzeit unterstützte Optionen sind:

[codeblock lang=text] deaktiviert das Syntax-Highlighting;
[codeblock lang=text] verwendet GDScript-Syntax-Highlighting;
[codeblock lang=csharp] verwendet C#-Syntax-Highlighting (nur in der .NET-Version).

Bemerkung

[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());
}

Formatierungshinweise und Warnungen

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.

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

Kennzeichnung der API als veraltet/experimentell

Um eine API als veraltet oder experimentell zu kennzeichnen, müssen Sie das entsprechende XML-Attribut hinzufügen. Der Wert des Attributs muss eine Nachricht sein, die erklärt, warum die API nicht empfohlen wird (BBCode-Markup wird unterstützt), oder ein leerer String (die Standardnachricht wird verwendet). Wenn ein API-Element als veraltet/experimentell gekennzeichnet ist, gilt es als dokumentiert, auch wenn die Beschreibung leer ist.

<class name="Parallax2D" inherits="Node2D" experimental="This node is meant to replace [ParallaxBackground] and [ParallaxLayer]. The implementation may change in the future." xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
    [...]
</class>

<constant name="RESPONSE_USE_PROXY" value="305" enum="ResponseCode" deprecated="Many clients ignore this response code for security reasons. It is also deprecated by the HTTP standard.">
    HTTP status code [code]305 Use Proxy[/code].
</constant>

<member name="auto_translate" type="bool" setter="set_auto_translate" getter="is_auto_translating" deprecated="Use [member Node.auto_translate_mode] instead.">
    Toggles if any text should automatically change to its translated version depending on the current locale.
</member>

<method name="get_method_call_mode" qualifiers="const" deprecated="Use [member AnimationMixer.callback_mode_method] instead.">
    <return type="int" enum="AnimationPlayer.AnimationMethodCallMode" />
    <description>
        Returns the call mode used for "Call Method" tracks.
    </description>
</method>