Proprietà esportate in GDScript
In Godot, class members can be exported. This means their value gets saved along
with the resource (such as the scene) they're
attached to, and get transferred over when using RPCs.
They will also be available for editing in the property editor. Exporting is done by using
the @export annotation.
@export var number: int = 5
In questo esempio il valore 5 sarà salvato e visibile nell'editor delle proprietà.
Una variabile esportata deve essere inizializzata a un'espressione costante o definire un suggerimento del tipo. Alcune annotazioni di esportazione hanno un tipo specifico e non richiedono che la variabile sia tipizzata (vedere la sezione Esempi di seguito).
Uno dei motivi fondamentali per esportare variabili membro è per renderle visibili e modificabili nell'editor. Facendo così, artisti e game designer possono modificare valori che poi influiranno sull'esecuzione del programma. A questo scopo, viene fornita una sintassi di esportazione specifica.
Nota
È possibile esportare le proprietà anche in altri linguaggi come C#. La sintassi varia a seconda del linguaggio. Consultare Proprietà esportate in C# per informazioni sulle esportazioni in C#.
Utilizzo di base
Se il valore esportato assegna una costante o un'espressione costante, il tipo sarà dedotto e utilizzato nell'editor.
@export var number = 5
Se non esiste un valore predefinito, si può aggiungere un tipo alla variabile.
@export var number: int
Le risorse e i nodi si possono esportare.
@export var resource: Resource
@export var node: Node
Raggruppare le esportazioni
È possibile raggruppare le proprietà esportate all'interno dell'Ispettore con l'annotazione @export_group. Ogni proprietà esportata dopo questa annotazione sarà aggiunta al gruppo. Creare un nuovo gruppo o utilizzare @export_group("") per uscirne.
@export_group("My Properties")
@export var number = 3
Il secondo argomento dell'annotazione può essere utilizzato per raggruppare solo le proprietà con il prefisso specificato.
I gruppi non si possono annidare. Utilizzare @export_subgroup per creare sottogruppi all'interno di un gruppo.
@export_subgroup("Extra Properties")
@export var string = ""
@export var flag = false
È anche possibile modificare il nome della categoria principale o creare categorie aggiuntive nell'elenco delle proprietà tramite l'annotazione @export_category.
@export_category("Main Category")
@export var number = 3
@export var string = ""
@export_category("Extra Category")
@export var flag = false
Nota
The list of properties is organized based on the class inheritance and new categories break that expectation. Use them carefully, especially when creating projects for public use.
Stringhe rappresentanti percorsi
Stringa rappresentante un percorso a un file. Consultare @export_file.
@export_file var f
Stringa rappresentante un percorso a una cartella. Consultare @export_dir.
@export_dir var f
Stringa rappresentante un percorso a un file, filtro personalizzato fornito come suggerimento. Consultare nuovamente @export_file.
@export_file("*.txt") var f
È possibile utilizzare anche i percorsi nel file system globale, ma solo negli script in modalità strumento (tool).
Stringa rappresentante un percorso per un file PNG nel file system globale. Consultare @export_global_file.
@export_global_file("*.png") var tool_image
Stringa rappresentante un percorso per una cartella nel file system globale. Consultare @export_global_dir.
@export_global_dir var tool_dir
L'annotazione multilinea indica all'editor di visualizzare un campo ampio di input per la digitare su più righe. Consultare @export_multiline.
@export_multiline var text
Limitare gli intervalli inseribili nell'editor
Consultare @export_range per quanto segue.
Permette valori interi da 0 a 20.
@export_range(0, 20) var i
Permette valori interi da -10 a 20.
@export_range(-10, 20) var j
Permette valori in virgola mobile da -10 a 20 e aggancia il valore a multipli di 0,2.
@export_range(-10, 20, 0.2) var k: float
È possibile impostare i limiti in modo che influiscano solo sullo slider aggiungendo le indicazioni "or_less" e/o "or_greater". Se si utilizza una di queste indicazioni, sarà possibile immettere qualsiasi valore o trascinarlo con il mouse quando non si utilizza lo slider, anche se al di fuori dell'intervallo specificato.
@export_range(0, 100, 1, "or_less", "or_greater") var l: int
L'indicazione "exp" può essere utilizzata per impostare un valore con uno slider esponenziale anziché lineare. Ciò significa che, trascinando lo slider verso destra, i cambiamenti diventeranno progressivamente più significativi trascinando il mouse. Ciò è utile per facilitare la modifica di valori molto piccoli o molto grandi, a costo di renderla meno intuitiva.
@export_range(0, 100000, 0.01, "exp") var exponential: float
Per i valori che dovrebbero rappresentare un fattore di easing, utilizzare invece Numeri in virgola mobile con indicazione di easing.
L'indicazione "hide_slider" può essere utilizzata per nascondere la barra orizzontale che appare sotto le proprietà float, o le frecce su/giù che appaiono accanto alle proprietà int:
@export_range(0, 1000, 0.01, "hide_slider") var no_slider: float
Aggiungere suffissi e gestire i gradi/radianti
È anche possibile definire un suffisso per rendere il valore più intuitivo nell'ispettore. Ad esempio, per definire un valore che si intende configurare in "metri" (m) dall'utente:
@export_range(0, 100, 1, "suffix:m") var m: int
Per gli angoli memorizzati in radianti ma visualizzati all'utente in gradi, utilizzare l'indicazione "radians_as_degrees":
@export_range(0, 360, 0.1, "radians_as_degrees") var angle: float
Ciò effettua una conversione automatica quando il valore viene visualizzato o modificato nell'ispettore e visualizza inoltre un suffisso per i gradi (°). Questo approccio è utilizzato dalle proprietà rotation di Godot in tutto l'editor.
Se invece l'angolo è memorizzato in gradi, utilizzare l'indicazione "degrees" per visualizzare il simbolo dei gradi e disabilitare la conversione automatica da gradi a radianti quando il valore viene modificato dall'ispettore.
Numeri in virgola mobile con indicazione di easing
Visualizza una rappresentazione visiva della funzione ease() in fase di modifica. Consultare @export_exp_easing.
@export_exp_easing var transition_speed
Colori
Colore regolare fornito come valore rosso-verde-blu-alfa.
@export var col: Color
Colore fornito come valore rosso-verde-blu (alfa sarà sempre 1). Consultare @export_color_no_alpha.
@export_color_no_alpha var col: Color
Nodi
A partire da Godot 4.0, i nodi possono essere esportati direttamente come proprietà in uno script senza dover utilizzare NodePath:
# Allows any node.
@export var node: Node
# Allows any node that inherits from BaseButton.
# Custom classes declared with `class_name` can also be used.
@export var some_button: BaseButton
È ancora possibile esportare i NodePath come in Godot 3.x, nel caso in cui sia necessario:
@export var node_path: NodePath
var node = get_node(node_path)
Se si desidera limitare i tipi di nodi per NodePath, è possibile utilizzare l'annotazione @export_node_path:
@export_node_path("Button", "TouchScreenButton") var some_button
Risorse
@export var resource: Resource
Nell'Ispettore, sarà quindi possibile trascinare e rilasciare un file di risorse dal pannello del FileSystem nello slot della variabile.
Tuttavia, se si apre il menu a discesa nell'ispettore potrebbe apparire un elenco estremamente lungo di classi disponibili da creare. Pertanto, se si specifica un'estensione di Resource come:
@export var resource: AnimationNode
Il menu a discesa sarà limitato ad AnimationNode e a tutte le sue classi derivate.
È importante notare che anche se lo script non viene eseguito nell'editor, le proprietà esportate sono comunque modificabili. Ciò può essere utilizzato in combinazione con uno script in modalità "strumento" (tool).
Esportare bit flag
Consultare @export_flags.
Gli interi utilizzati come bit flag possono memorizzare più valori true/false (booleani) in un'unica proprietà. Attraverso l'annotazione @export_flags, possono essere impostati dall'editor:
# Set any of the given flags from the editor.
@export_flags("Fire", "Water", "Earth", "Wind") var spell_elements = 0
È necessario fornire una stringa di descrizione per ogni flag. In questo esempio, Fire ha valore 1, Water ha valore 2, Earth ha valore 4 e Wind corrisponde al valore 8. Di solito, si dovrebbero definire costanti corrispondenti (ad esempio const ELEMENT_WIND = 8 e così via).
È possibile aggiungere valori espliciti tramite i due punti:
@export_flags("Self:4", "Allies:8", "Foes:16") var spell_targets = 0
Solo i valori che sono potenze di 2 sono validi come opzioni di bit flag. Il valore minimo consentito è 1, poiché 0 indica che nulla è selezionato. È anche possibile aggiungere opzioni che sono una combinazione di altri flag:
@export_flags("Self:4", "Allies:8", "Self and Allies:12", "Foes:16")
var spell_targets = 0
Sono inoltre fornite annotazioni di esportazione per gli strati di fisica, rendering e navigazione definiti nelle impostazioni del progetto:
@export_flags_2d_physics var layers_2d_physics
@export_flags_2d_render var layers_2d_render
@export_flags_2d_navigation var layers_2d_navigation
@export_flags_3d_physics var layers_3d_physics
@export_flags_3d_render var layers_3d_render
@export_flags_3d_navigation var layers_3d_navigation
L'utilizzo dei bit flag richiede una certa conoscenza delle operazioni bit a bit. In casi di dubbio, utilizzare invece variabili booleane.
Esportare enumerazioni
Consultare @export_enum.
Le proprietà possono essere esportate con un suggerimento di tipo che referenzia a un enumerazione per limitarne i valori ai valori dell'enumerazione. L'editor creerà un widget nell'Ispettore, enumerando quanto segue come "Thing 1", "Thing 2", "Another Thing". Il valore sarà memorizzato sotto forma di un intero.
enum NamedEnum {THING_1, THING_2, ANOTHER_THING = -1}
@export var x: NamedEnum
Le proprietà di tipo intero e stringa possono anche essere limitate a un elenco specifico di valori tramite l'annotazione @export_enum. L'editor creerà un widget nell'Ispettore, enumerando i seguenti valori come Warrior, Magician, Thief. Il valore sarà memorizzato sotto forma di un intero, corrispondente all'indice dell'opzione selezionata (ad esempio 0, 1 o 2).
@export_enum("Warrior", "Magician", "Thief") var character_class: int
È possibile aggiungere valori espliciti tramite i due punti:
@export_enum("Slow:30", "Average:60", "Very Fast:200") var character_speed: int
Se il tipo è String, il valore sarà memorizzato sotto forma di una stringa.
@export_enum("Rebecca", "Mary", "Leah") var character_name: String
Se si desidera impostare un valore iniziale, è necessario specificarlo esplicitamente:
@export_enum("Rebecca", "Mary", "Leah") var character_name: String = "Rebecca"
Esportare array
Gli array esportati possono essere inizializzati, ma devono essere inizializzati con espressioni costanti.
Se l'array esportato specifica un tipo che eredita da Resource, i valori dell'array si possono impostare nell'ispettore trascinando e rilasciando più file alla volta dal pannello FileSystem.
Il valore predefinito deve essere un'espressione costante.
@export var a = [1, 2, 3]
Gli array esportati possono specificare un tipo (utilizzando gli stessi suggerimenti di prima).
@export var ints: Array[int] = [1, 2, 3]
# Nested typed arrays such as `Array[Array[float]]` are not supported yet.
@export var two_dimensional: Array[Array] = [[1.0, 2.0], [3.0, 4.0]]
È possibile omettere il valore predefinito, ma sarà null se non viene assegnato.
@export var b: Array
@export var scenes: Array[PackedScene]
Gli array con tipi specificati che ereditano da Resource si possono impostare trascinando e rilasciando più file dal pannello FileSystem.
@export var textures: Array[Texture] = []
@export var scenes: Array[PackedScene] = []
Anche gli array impacchettati funzionano, ma solamente se inizializzati vuoti:
@export var vector3s = PackedVector3Array()
@export var strings = PackedStringArray()
È possibile utilizzare anche altre annotazioni di esportazione per esportare gli array:
@export_range(-360, 360, 0.001, "degrees") var laser_angles: Array[float] = []
@export_file("*.json") var skill_trees: Array[String] = []
@export_color_no_alpha var hair_colors = PackedColorArray()
@export_enum("Espresso", "Mocha", "Latte", "Capuccino") var barista_suggestions: Array[String] = []
@export_storage
Consultare @export_storage.
Come predefinito, l'esportazione di una proprietà ha due effetti:
memorizza la proprietà nel file di scena/risorsa (PROPERTY_USAGE_STORAGE);
aggiunge un campo all'Ispettore (PROPERTY_USAGE_EDITOR).
Tuttavia, a volte potrebbe essere necessario rendere una proprietà serializzabile, ma senza visualizzarla nell'editor, per evitare modifiche involontarie e l'ingombro dell'interfaccia.
A questo scopo, è possibile utilizzare @export_storage. Questo può essere utile per gli script strumento (@tool). Inoltre, il valore della proprietà verrà copiato quando la funzione Resource.duplicate() o Node.duplicate() viene chiamata, a differenza delle variabili non esportate.
var a # Not stored in the file, not displayed in the editor.
@export_storage var b # Stored in the file, not displayed in the editor.
@export var c: int # Stored in the file, displayed in the editor.
@export_custom
Se è necessario più controllo rispetto a quello offerto dalle annotazioni @export integrate, è possibile utilizzare @export_custom. Essa permette di definire qualsiasi indicazione di proprietà, stringa indicativa e flag di utilizzo, con una sintassi simile a quella utilizzata dall'editor per i nodi integrati.
Ad esempio, questo espone la proprietà altitude senza limiti di intervallo ma con un suffisso m (metro) definito:
@export_custom(PROPERTY_HINT_NONE, "suffix:m") var altitude: float
Quanto sopra non è normalmente realizzabile con la solita sintassi di @export_range, poiché essa richiede di definire un intervallo.
Consultare il riferimento alle classi per un elenco dei parametri e dei valori consentiti.
Avvertimento
Quando si utilizza @export_custom, GDScript non convalida la sintassi. Una sintassi non valida potrebbe avere un comportamento imprevisto nell'ispettore.
Impostare le variabili esportate da uno script strumento (tool)
Quando si modifica il valore di una variabile esportata da uno script in Modalità strumento (tool), il valore nell'ispettore non verrà aggiornato automaticamente. Per aggiornarlo, è necessario chiamare notify_property_list_changed() dopo aver impostato il valore della variabile esportata.
Esportazioni avanzate
Non sono forniti tutti i tipi di esportazione nel linguaggio stesso, per evitare inutili complessità di progettazione. Di seguito sono descritte alcune funzionalità di esportazione più o meno comuni che si possono implementare con un'API di basso livello.
Prima di proseguire la lettura, è opportuno acquisire familiarità con il modo in cui vengono gestite le proprietà e con il modo in cui si possono personalizzare con i metodi _set(), _get() e _get_property_list(), come descritto in Accedere ai dati o alla logica da un oggetto.
Vedi anche
Per vincolare le proprietà in C++ attraverso i metodi sopra indicati, consultare Vincolare proprietà tramite _set/_get/_get_property_list.
Avvertimento
Lo script deve operare in modalità @tool affinché i metodi sopra indicati possano funzionare dall'interno dell'editor.