@export et annotations dans Godot 4

Introduction : des mots-clés aux annotations

Godot 4 a remplacé plusieurs mots-clés GDScript par des annotations préfixées par @. Cela faisait partie d'un effort plus large visant à rendre la syntaxe GDScript plus propre et plus cohérente. Les trois changements les plus importants sont :

• export → @export
• onready → @onready
• tool → @tool

Les annotations se placent sur la ligne précédant (ou sur la même ligne que) la déclaration qu'elles modifient. Godot 4 a également introduit de nombreuses nouvelles variantes d'annotations comme @export_range, @export_group et @export_category, qui n'existaient pas dans Godot 3. Ce guide les couvre toutes.

@export de base

L'annotation @export rend une variable visible dans l'inspecteur de Godot et te permet de configurer des valeurs sans modifier le code. Godot choisit automatiquement le widget d'éditeur approprié en fonction du type de la variable.

@export var speed: float = 300.0
@export var player_name: String = "Player"
@export var health: int = 100
@export var color: Color = Color.WHITE
@export var texture: Texture2D
@export var scene: PackedScene

Astuce : ajoute toujours des annotations de type aux variables exportées. Ainsi l'inspecteur affiche le bon widget (par exemple un sélecteur de couleur pour Color, un emplacement de ressource pour Texture2D).

@export_range — Curseurs numériques

@export_range limite une valeur numérique à un minimum et un maximum et affiche un curseur dans l'inspecteur. Tu peux aussi indiquer un pas ainsi que des indications comme "or_greater" ou "or_less".

@export_range(0, 100) var health: int = 100
@export_range(0.0, 1.0, 0.01) var volume: float = 0.8
@export_range(0, 1000, 1, "or_greater") var damage: int = 10

L'indication "or_greater" autorise la saisie de valeurs au-dessus du maximum, tout en gardant la plage du curseur en évidence. De la même façon, "or_less" autorise des valeurs en dessous du minimum.

@export_enum — Menus déroulants

@export_enum crée un menu déroulant dans l'inspecteur. Utilisé avec String, il enregistre le nom de l'option sélectionnée. Utilisé avec int, tu peux assigner des valeurs explicites.

# Stores the string name: "Warrior", "Mage", or "Rogue"
@export_enum("Warrior", "Mage", "Rogue") var character_class: String

# Stores the integer value: 0, 1, or 2
@export_enum("Easy:0", "Normal:1", "Hard:2") var difficulty: int = 1

@export_file et @export_dir — Chemins de fichiers/répertoires

@export_file affiche une boîte de dialogue de fichier dans l'inspecteur. Tu peux filtrer par extension de fichier. @export_dir affiche une boîte de dialogue de sélection de répertoire.

@export_file("*.tscn") var next_level: String
@export_dir var save_directory: String

La chaîne de filtre utilise des motifs glob. Plusieurs filtres peuvent être séparés par des virgules : "*.png,*.jpg".

@export_multiline et @export_placeholder

@export_multiline fournit une grande zone de texte pour les chaînes multilignes (idéal pour les dialogues ou les descriptions). @export_placeholder affiche un texte indicatif dans le champ lorsqu'il est vide.

@export_multiline var description: String
@export_placeholder("Enter name...") var player_name: String

@export_group et @export_subgroup — Organiser les propriétés de l'inspecteur

@export_group crée un en-tête de groupe repliable dans l'inspecteur. Toutes les variables @export qui suivent appartiennent à ce groupe, jusqu'au groupe ou à la catégorie suivante. @export_subgroup s'imbrique à l'intérieur du groupe courant.

@export_group("Movement")
@export var speed: float = 300.0
@export var jump_force: float = 400.0

@export_group("Combat")
@export var attack_damage: int = 10
@export var defense: int = 5

@export_subgroup("Ranged")
@export var projectile_speed: float = 500.0

Les groupes et sous-groupes servent uniquement à l'organisation — ils n'affectent pas l'accès aux variables dans le code, seulement la façon dont les propriétés apparaissent dans l'inspecteur.

@export_category — En-têtes de catégorie en gras

@export_category crée un en-tête de catégorie de premier niveau en gras dans l'inspecteur. Contrairement aux groupes, les catégories ne peuvent pas être repliées et agissent comme une forte séparation visuelle entre des ensembles de propriétés sans lien.

@export_category("Player Stats")
@export var level: int = 1
@export var experience: int = 0

@export avec des références de nœuds

Tu peux exporter un NodePath afin que les concepteurs puissent sélectionner un nœud dans l'arbre de scène. Dans Godot 4.2+, tu peux exporter directement une référence de nœud typée — aucun NodePath n'est nécessaire.

# Classic NodePath export
@export var target_path: NodePath

# Godot 4.2+: typed node export (direct reference, no NodePath needed)
@export var sprite: Sprite2D
@export var collision: CollisionShape2D

Les exports de nœuds typés sont l'approche recommandée dans le Godot 4 moderne. L'inspecteur affiche un sélecteur de nœud filtré sur le type indiqué, et tu bénéficies de l'autocomplétion complète dans l'éditeur de scripts.

@export_flags — Cases à cocher de masque de bits

@export_flags crée un ensemble de cases à cocher où chaque option correspond à un bit dans un entier. Godot propose aussi des exports de drapeaux intégrés pour les couches de physique et de rendu.

# Custom flags: Fire=1, Water=2, Earth=4, Wind=8
@export_flags("Fire", "Water", "Earth", "Wind") var elements: int

# Built-in physics layer flags
@export_flags_2d_physics var collision_layers: int
@export_flags_2d_render var render_layers: int
@export_flags_3d_physics var collision_layers_3d: int

@onready — Initialisation différée

@onready diffère l'initialisation d'une variable jusqu'à ce que le nœud entre dans l'arbre de scène (équivalent à l'affectation dans _ready()). C'est indispensable lorsque tu référencies des nœuds enfants avec $, car les enfants ne sont pas encore disponibles au moment de l'analyse.

# Godot 3 (old syntax):
# onready var sprite = $Sprite2D

# Godot 4:
@onready var sprite: Sprite2D = $Sprite2D
@onready var anim: AnimationPlayer = $AnimationPlayer
@onready var label: Label = $UI/ScoreLabel

Bonne pratique : typise toujours tes variables @onready. Cela active l'autocomplétion et intercepte les erreurs de type au moment de l'analyse plutôt qu'à l'exécution.

@tool — Exécuter des scripts dans l'éditeur

@tool permet à un script de s'exécuter au sein de l'éditeur Godot (pas seulement à l'exécution). C'est puissant pour créer des aperçus personnalisés, des gizmos et des propriétés mises à jour en direct. Place-le tout en haut du script, avant extends.

@tool
extends Node2D

@export var radius: float = 100.0:
    set(value):
        radius = value
        queue_redraw()  # Redraw in editor when value changes

func _draw() -> void:
    draw_circle(Vector2.ZERO, radius, Color.WHITE)

Attention : sois prudent avec les scripts @tool. Le code dans _process() et _physics_process() s'exécute dans l'éditeur. Utilise Engine.is_editor_hint() pour protéger la logique purement liée au jeu.

Autres annotations

@icon

Définit une icône personnalisée pour le type de nœud du script dans le dock de scène et dans la boîte de dialogue « Créer un nœud ».

@icon("res://icons/enemy.svg")
extends CharacterBody2D

@warning_ignore

Supprime certains avertissements GDScript pour l'instruction suivante. Utile lorsque tu masques intentionnellement une variable ou que tu as un paramètre inutilisé.

@warning_ignore("unused_parameter")
func _on_body_entered(body: Node2D) -> void:
    queue_free()

@warning_ignore("shadowed_variable")
var size: int = 10

@static_unload

Marque un script pour que Godot puisse le décharger de la mémoire lorsqu'aucune instance n'existe. Cela peut réduire la consommation mémoire des scripts qui ne sont utilisés que temporairement. Le script ne doit pas comporter de variables ou de données statiques qui doivent être conservées.

@static_unload
extends RefCounted

# This script can be safely unloaded when not in use

Bonnes pratiques de typage statique

Bien qu'il ne s'agisse pas d'annotations, les indications de type statique y sont étroitement liées et sont vivement recommandées dans Godot 4. Elles améliorent l'autocomplétion, permettent la vérification des erreurs à la compilation et peuvent améliorer les performances.

# Variable type annotations
var speed: float = 300.0
var player: CharacterBody2D = null
var items: Array[String] = []
var scores: Dictionary = {}

# Function return types and parameter types
func get_damage() -> int:
    return attack - defense

func apply_force(direction: Vector2, strength: float) -> void:
    velocity += direction * strength

# Type inference with :=
var pos := Vector2(100, 200)  # Inferred as Vector2

Remarque : sois prudent avec := dans les boucles for lorsque tu itères sur des tableaux non typés. Utilise plutôt des annotations de type explicites : for item: String in array.

Aide-mémoire de migration : Godot 3 vers 4

Référence rapide pour convertir la syntaxe d'export de Godot 3 en annotations de Godot 4 :