@export e annotazioni in Godot 4

Introduzione: dalle keyword alle annotazioni

Godot 4 ha sostituito diverse keyword GDScript con annotazioni con prefisso @. Faceva parte di un più ampio sforzo per rendere la sintassi GDScript più pulita e coerente. Le tre modifiche più importanti sono:

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

Le annotazioni si collocano nella riga prima (o nella stessa riga) della dichiarazione che modificano. Godot 4 ha inoltre introdotto molte nuove varianti di annotazione come @export_range, @export_group e @export_category che non esistevano in Godot 3. Questa guida le tratta tutte.

@export di base

L'annotazione @export rende una variabile visibile nell'Inspector di Godot, permettendoti di configurare i valori senza modificare il codice. Godot sceglie automaticamente il widget dell'editor più adatto in base al tipo della variabile.

@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

Suggerimento: Aggiungi sempre le annotazioni di tipo alle variabili esportate. Così l'Inspector mostra il widget corretto (ad es. un selettore di colore per Color, uno slot di risorsa per Texture2D).

@export_range — Slider numerici

@export_range limita un valore numerico a un minimo e un massimo, mostrando uno slider nell'Inspector. Puoi anche specificare una dimensione dello step e suggerimenti come "or_greater" o "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

Il suggerimento "or_greater" consente di digitare valori superiori al massimo mantenendo focalizzato l'intervallo dello slider. Analogamente, "or_less" consente valori inferiori al minimo.

@export_enum — Menu a tendina

@export_enum crea un menu a tendina nell'Inspector. Usato con String, viene memorizzato il nome dell'opzione selezionata. Usato con int, puoi assegnare valori espliciti.

# 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 e @export_dir — Percorsi di file/cartelle

@export_file mostra una finestra di dialogo per i file nell'Inspector. Puoi filtrare per estensione. @export_dir mostra una finestra di selezione delle cartelle.

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

La stringa di filtro usa pattern glob. Più filtri possono essere separati da virgole: "*.png,*.jpg".

@export_multiline e @export_placeholder

@export_multiline fornisce un'ampia area di testo per stringhe su più righe (ideale per dialoghi o descrizioni). @export_placeholder mostra un testo di suggerimento all'interno del campo quando è vuoto.

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

@export_group e @export_subgroup — Organizzare le proprietà dell'Inspector

@export_group crea un'intestazione di gruppo comprimibile nell'Inspector. Tutte le variabili @export che seguono appartengono a quel gruppo, fino al gruppo o alla categoria successiva. @export_subgroup si annida all'interno del gruppo corrente.

@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

Gruppi e sottogruppi sono puramente organizzativi — non influiscono sull'accesso alle variabili nel codice, ma solo su come le proprietà appaiono nell'Inspector.

@export_category — Intestazioni di categoria in grassetto

@export_category crea un'intestazione di categoria di primo livello in grassetto nell'Inspector. A differenza dei gruppi, le categorie non possono essere compresse e fungono da forte separatore visivo tra insiemi di proprietà non correlati.

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

@export con riferimenti a Node

Puoi esportare un NodePath per consentire ai designer di scegliere un node dall'albero della scena. In Godot 4.2+ puoi esportare direttamente un riferimento a un node tipizzato — nessun NodePath necessario.

# 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

Gli export di node tipizzati sono l'approccio consigliato nel Godot 4 moderno. L'Inspector mostra un selettore di node filtrato sul tipo specificato e ottieni l'autocompletamento completo nell'editor degli script.

@export_flags — Checkbox bitmask

@export_flags crea un insieme di checkbox in cui ogni opzione corrisponde a un bit di un intero. Godot fornisce anche export di flag integrati per i layer di fisica e di rendering.

# 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 — Inizializzazione differita

@onready ritarda l'inizializzazione di una variabile fino a quando il node entra nell'albero della scena (equivalente all'assegnazione in _ready()). È indispensabile quando si referenziano node figli con $, perché i figli non sono disponibili al momento del parsing.

# 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

Best practice: Tipizza sempre le tue variabili @onready. Questo abilita l'autocompletamento e intercetta gli errori di tipo al momento del parsing invece che a runtime.

@tool — Eseguire gli script nell'editor

@tool fa eseguire uno script all'interno dell'editor di Godot (non solo a runtime). È potente per creare anteprime personalizzate, gizmo e proprietà aggiornate in tempo reale. Posizionalo in cima allo script, prima di 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)

Attenzione: Fai attenzione con gli script @tool. Il codice in _process() e _physics_process() verrà eseguito nell'editor. Usa Engine.is_editor_hint() per proteggere la logica riservata al gioco.

Altre annotazioni

@icon

Imposta un'icona personalizzata per il tipo di node dello script nel dock Scena e nella finestra "Crea Node".

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

@warning_ignore

Sopprime avvisi GDScript specifici per l'istruzione successiva. Utile quando fai deliberatamente shadowing di una variabile o hai un parametro inutilizzato.

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

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

@static_unload

Contrassegna uno script affinché Godot possa scaricarlo dalla memoria quando non esistono istanze. Questo può ridurre l'uso di memoria per gli script utilizzati solo temporaneamente. Lo script non deve avere variabili o dati statici che devono persistere.

@static_unload
extends RefCounted

# This script can be safely unloaded when not in use

Best practice per la tipizzazione statica

Pur non essendo annotazioni, i type hint statici sono strettamente correlati e fortemente consigliati in Godot 4. Migliorano l'autocompletamento, abilitano il controllo degli errori in fase di compilazione e possono migliorare le prestazioni.

# 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

Nota: Fai attenzione con := nei cicli for quando iteri su array non tipizzati. Usa invece annotazioni di tipo esplicite: for item: String in array.

Cheat sheet di migrazione: da Godot 3 a 4

Riferimento rapido per convertire la sintassi di export di Godot 3 nelle annotazioni di Godot 4: