Up to date

This page is up to date for Godot 4.2. 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

If you use Visual Studio Code, you can install the vscode-xml extension to get linting for class reference XML files.

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

Godot's XML class reference supports BBCode-like tags for linking as well as formatting text and code. In the tables below you can find the available tags, usage examples and the results after conversion to reStructuredText.

Linking¶

Whenever you link to a member of another class, you need to specify the class name. For links to the same class, the class name is optional and can be omitted.

Tag and Description	Exemple	Résultat
`[Class]` Link to class	`Move the [Sprite2D].`	Move the Sprite2D.
`[annotation Class.name]` Link to annotation	`See [annotation @GDScript.@export].`	See @GDScript.@export.
`[constant Class.name]` Link to constant	`See [constant @GlobalScope.KEY_F1].`	See @GlobalScope.KEY_F1.
`[enum Class.name]` Link to enum	`See [enum Mesh.ArrayType].`	See Mesh.ArrayType.
`[method Class.name]` Link to method	`Call [method Node3D.hide].`	Call Node3D.hide().
`[member Class.name]` Link to member	`Get [member Node2D.scale].`	Get Node2D.scale.
`[signal Class.name]` Link to signal	`Emit [signal Node.renamed].`	Emit Node.renamed.
`[theme_item Class.name]` Link to theme item	`See [theme_item Label.font].`	See Label.font.

Note

Currently only @GDScript has annotations.

Formatting text¶

Tag and Description	Exemple	Résultat
`[param name]` Formats a parameter name (as code)	`Takes [param size] for the size.`	Takes `size` for the size.
`[br]` Line break	`Line 1.[br]` `Line 2.`	Line 1. Line 2.
`[b]` `[/b]` Gras	`Some [b]bold[/b] text.`	Du texte en gras.
`[i]` `[/i]` Italique	`Some [i]italic[/i] text.`	Du texte italique.
`[kbd]` `[/kbd]` Raccourci clavier/souris	`Some [kbd]Ctrl + C[/kbd] key.`	Des touches `Ctrl + C`.

Formatting code¶

Tag and Description	Exemple	Résultat
`[code]` `[/code]` Monospace	`Some [code]monospace[/code] text.`	Du texte `monospace`.
`[codeblock]` `[/codeblock]` Bloc multiligne préformaté	Voir ci-dessous.	Voir ci-dessous.
`[codeblocks]` `[/codeblocks]` Codeblock for multiple languages	Voir ci-dessous.	Voir ci-dessous.
`[gdscript]` `[/gdscript]` Onglet GDScript codeblock dans codeblocks	Voir ci-dessous.	Voir ci-dessous.
`[csharp]` `[/csharp]` C# codeblock tab dans codeblocks	Voir ci-dessous.	Voir ci-dessous.

Note

[code] disables BBCode until the parser encounters [/code].
[codeblock] disables BBCode until the parser encounters [/codeblock].

Avertissement

Use [codeblock] for pre-formatted code blocks. Inside [codeblock], always use four spaces for indentation. The parser will delete tabs.

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

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.

Pour les propriétés obsolètes, ajoutez un paragraphe commençant par "[i]Deprecated.[/i]". Notez l'utilisation de l'italique au lieu du gras :

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

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