Up to date

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

Class reference primer

Cette page explique comment écrire la référence de la classe. Vous apprendrez où écrire de nouvelles descriptions pour les classes, les méthodes et les propriétés des types de nœuds intégrés de Godot.

Voir aussi

Pour apprendre à soumettre vos modifications au projet Godot en utilisant le système de contrôle de version Git, consultez Contribuer à la référence des classes.

La référence de chaque classe est contenue dans un fichier XML comme celui ci-dessous :

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

Cela commence par des descriptions brèves et longues. Dans la documentation générée, la description brève se trouve toujours en haut de la page, tandis que la description longue se trouve sous la liste des méthodes, des variables et des constantes. Vous pouvez trouver les méthodes, les variables membres, les constantes et les signaux dans des nœuds XML distincts.

Pour chacun, vous voulez apprendre comment ils fonctionnent dans le code source de Godot. Ensuite, remplissez leur documentation en complétant ou en améliorant le texte de ces balises :

<brief_description>
<description>
<constant>
<method> (dans sa balise <description> ; les types de retour et les arguments ne prennent pas de chaînes de documentation séparées)
<member>
<signal> (dans sa balise <description> ; les arguments ne prennent pas de chaînes de documentation séparées)
<constant>

Écrivez dans un langage clair et simple. Suivez toujours les directives d’écriture pour garder vos descriptions courtes et faciles à lire. Ne laissez pas de lignes vides dans les descriptions : chaque ligne du fichier XML entraînera un nouveau paragraphe, même s’il est vide.

Comment modifier la classe XML

Modifiez le fichier de la classe choisie dans doc/classes/ pour mettre à jour la référence de la classe. Le dossier contient un fichier XML pour chaque classe. Le XML liste les constantes et les méthodes que vous trouverez dans la référence de la classe. Godot génère et met à jour le XML automatiquement.

Note

Pour certains modules du code source du moteur, vous trouverez les fichiers XML dans le répertoire modules/<module_name>/doc_classes/ à la place.

Modifiez-le en utilisant votre éditeur de texte préféré. Si vous utilisez un éditeur de code, assurez-vous qu'il ne modifie pas le style d'indentation : vous devez utiliser des tabulations pour le XML et quatre espaces à l'intérieur des blocs de style BBCode. Plus d'informations à ce sujet ci-dessous.

Pour vérifier que les modifications que vous avez faites sont correctes dans la documentation générée, naviguez dans le dossier doc/ et exécutez la commande make rst. Cela convertira les fichiers XML au format de la documentation en ligne et affichera des erreurs si quelque chose ne va pas.

Alternativement, vous pouvez construire Godot et ouvrir la page modifiée dans la référence de code intégrée. Pour savoir comment compiler le moteur, lisez le guide de compilation.

Nous vous recommandons d'utiliser un éditeur de code prenant en charge les fichiers XML comme Vim, Atom, Visual Studio Code, Notepad++ ou autre pour éditer confortablement le fichier. Vous pouvez également utiliser leur fonction de recherche pour trouver rapidement les classes et les propriétés.

Astuce

Si vous utilisez Visual Studio Code, vous pouvez installer l'extension vscode-xml pour obtenir du linting pour les fichiers XML de références de classes.

Améliorez le formatage avec les balises de style BBcode

La référence de classe XML de Godot prend en charge les balises BBCode pour lier et formater le texte et le code. Dans les tableaux ci-dessous vous pouvez trouver les étiquettes disponibles, les exemples d'utilisation et les résultats après conversion en reStructuredText.

Lier

Chaque fois que vous créez un lien vers un membre d'une autre classe, vous devez spécifier le nom de la classe. Pour les liens vers la même classe, le nom de la classe est facultatif et peut être omis.

Étiquettes et Description	Exemple	Résultat
`[Class]` Lien vers une classe	`Déplacer le [Sprite2D].`	Déplacez le Sprite2D.
`[annotation Class.name]` Lien vers l'annotation	`Voir [annotation @GDScript.@rpc].`	Voir @GDScript.@rpc.
`[constant Class.name]` Lien vers une constante	`Voir [constant Color.RED].`	Voir Color.RED.
`[enum Class.name]` Lien vers l'énumération	`Voir [enum Mesh.ArrayType].`	Voir Mesh.ArrayType.
`[member Class.name]` Lier à un membre	`Obtenir [member Node2D.scale].`	Obtenir Node2D.scale.
`[method Class.name]` Lien vers une méthode	`Appelle [method Node3D.hide].`	Appelle Node3D.hide().
`[constructor Class.name]` Lien vers le constructeur intégré	`Utilise [constructor Color.Color].`	Utilise  Color.Color.
`[operator Class.name]` Lien vers un opérateur intégré	`Utilise [operator Color.operator *].`	Utilise  Color.operator *.
`[signal Class.name]` Lien vers un signal	`Émet [signal Node.renamed].`	Émet Node.renamed.
`[theme_item Class.name]` Lien vers un objet du thème	`Voir [theme_item Label.font].`	Voir Label.font.
`[param name]` Nom de paramètre (comme code)	`Prends [param size] pour la taille.`	Prends `size` pour la taille.

Note

Actuellement, seul @GDScript contient des annotations.

Formater du texte

Étiquettes et Description	Exemple	Résultat
`[br]` Saut de ligne	`Ligne 1.[br]` `Ligne 2.`	Ligne 1. Ligne 2.
`[lb]` `[rb]` `[` et `]` respectivement	`[lb]b[rb]texte[lb]/b[rb]`	[b]texte[/b]
`[b]` `[/b]` Gras	`[b]Ne pas[/b] appeler cette méthode.`	Ne pas appeler cette méthode.
`[i]` `[/i]` Italique	`Retourne la position [i]globale[/i].`	Retourne la position globale.
`[u]` `[/u]` Souligné	`[u]Toujours[/u] utiliser cette méthode.`	Always use this method.
`[s]` `[/s]` Barré	`[s]Information plus à jour.[/s]`	~~Outdated information.~~
`[url]` `[/url]` Lien web	`[url]https://example.com[/url]` `[url=https://example.com]site Web[/url]`	https://example.com `site Web<https://example.com>`_
`[center]` `[/center]` Centrage horizontal	`[center]2 + 2 = 4[/center]`	2 + 2 = 4
`[kbd]` `[/kbd]` Raccourci clavier/souris	`Appuyez sur [kbd]Ctrl + C[/kbd].`	Appuyez sur `Ctrl + C`.
`[code]` `[/code]` Fragment de code inline	`Renvoie [code]true[/code].`	Renvoie `true`.

Note

Certaines balises prises en charge telles que [color] et [font] ne sont pas listées ici car elles ne sont pas recommandées dans la documentation du moteur de jeu.
[kbd] désactive le BBCode jusqu'à ce que l'analyseur rencontre [/kbd].
[code] désactive le BBCode jusqu'à ce que l'analyseur rencontre [/code].

Formater des blocs de code

Il existe deux options pour formater les blocs de code :

Utiliser [codeblock] si vous voulez ajouter un exemple pour un langage spécifique.
Utilisez [codeblocks], [gdscript], et [csharp] si vous voulez ajouter le même exemple pour chacun des langages, GDScript and C#.

Par défaut, [codeblock] met en surbrillance la syntaxe GDScript. Vous pouvez la modifier à l'aide de l'attribut lang. Les options actuellement prises en charge sont :

[codeblock lang=text] désactive la coloration syntaxique ;
[codeblock lang=gdscript] met en évidence la syntaxe GDScript ;
[codeblock lang=csharp] met en évidence la syntaxe C# (uniquement dans la version .NET).

Note

[codeblock] désactive le BBCode jusqu'à ce que l'analyseur rencontre [/codeblock].

Avertissement

Utiliser [codeblock] pour des blocs de code préformatés. À l'intérieur de [codeblock], utiliser toujours quatre espaces pour l'indentation. L'analyseur supprimera les tabulations.

Par exemple :

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

S'affichera comme cela :

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

Si vous avez besoin d'avoir une version de code différente en GDScript et en C#, utilisez plutôt [codeblocks]. Si vous utilisez [codeblocks], vous devez aussi avoir au moins une des balises spécifiques au langage, [gdscript] et [csharp].

Commencez toujours par écrire des exemples de code GDScript ! Vous pouvez utiliser cet outil expérimental de traduction de code pour accélérer votre flux de travail.

[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]

Ce qui précède s'affichera comme suit :

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

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

Formatage des notes et des avertissements

Pour signaler des informations importantes, ajoutez un paragraphe commençant par "[b]Note :[/b]" à la fin de la description :

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

Pour indiquer les informations cruciales qui pourraient entraîner des problèmes de sécurité ou la perte de données si elles ne sont pas suivies attentivement, ajoutez un paragraphe commençant par "[b]Warning:[/b]" à la fin de la description :

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

Dans tous les paragraphes décrits ci-dessus, assurez-vous que la ponctuation fait partie des balises BBCode pour des raisons de cohérence.

Marque l'API comme expérimentale/Dépréciée

Pour marquer une API comme obsolète ou expérimentale, vous devez ajouter l'attribut XML correspondant. La valeur de l'attribut doit être un message expliquant pourquoi l'API n'est pas recommandée (le balisage BBCode est pris en charge) ou une chaîne vide (le message par défaut sera utilisé). Si un élément d'API est marqué comme obsolète/expérimental, il est alors considéré comme documenté même si la description est vide.

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