Attention: Here be dragons
This is the latest
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
Checking the stable version of the documentation...
Proprietà esportate in GDScript
In Godot, i membri di una classe possono essere esportati. Ciò significa che il loro valore è salvato insieme alla risorsa (ad esempio, scene) a cui sono associati, e trasferito quando si usano gli RPC. Saranno anche disponibili per la modifica nell'editor delle proprietà. L'esportazione avviene tramite l'annotazione @export.
@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. Inoltre, è possibile servirsi dei commenti di documentazione per avere descrizioni nei tooltip, visibili al passaggio del mouse.
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
Anche se lo script non è eseguito nell'editor, le proprietà esportate sono comunque modificabili. Tuttavia, i getter e setter saranno utilizzati solo se lo script è in modalità "strumento" (tool).
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. Usare @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
L'elenco delle proprietà è organizzato in base all'ereditarietà delle classi e l'aggiunta di nuove categorie non rispetta questa convenzione. Da usare con cautela, soprattutto quando si creano progetti per uso pubblico.
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
Stringhe come azioni di input
Stringa come azione di input definita nella mappa di input del progetto.
@export_custom(PROPERTY_HINT_INPUT_NAME) var my_input
Stringa come azione di input definita nella mappa di input del progetto, oltre ai valori predefiniti integrati come ui_accept e ui_cancel.
@export_custom(PROPERTY_HINT_INPUT_NAME, "show_builtin") var my_input
Stringa come azione di input definita nella mappa di input del progetto, più valori arbitrari che si possono inserire manualmente.
@export_custom(PROPERTY_HINT_INPUT_NAME, "loose_mode") var my_input
Stringa come azione di input definita nella mappa di input del progetto, oltre a valori predefiniti integrati come ui_accept e ui_cancel e valori arbitrari che si possono inserire manualmente.
@export_custom(PROPERTY_HINT_INPUT_NAME, "show_builtin,loose_mode") var my_input
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" serve 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. È 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" serve 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
D'altra parte, l'indicazione "prefer_slider" serve per mostrare la barra orizzontale sotto le proprietà int invece delle frecce su/giù:
@export_range(0, 100, 1, "prefer_slider") var with_slider: int
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.
Collegare assieme i valori dei vettori
È possibile collegare tra loro i valori vettoriali. Quando l'utente modifica una delle componenti del vettore, le altre componenti vengono automaticamente regolate proporzionalmente. Ad esempio, questo è utile per mantenere il rapporto d'aspetto di uno sprite 2D quando se ne regola la scala. È possibile disabilitare questa funzionalità temporaneamente dall'utente cliccando sull'icona di collegamento a destra della proprietà.
# Leave the hint string empty if you don't want to add a suffix.
@export_custom(PROPERTY_HINT_LINK, "suffix:px") var vector2_linked: Vector2 = Vector2(16, 16)
Risulta in:
Proprietà Vector2i collegata con il suffisso "px"
Questa indicazione funziona su Vector2, Vector2i, Vector3, Vector3i, Vector4 e Vector4i. È possibile usarlo allo stesso tempo del suffisso di proprietà, come mostrato nell'esempio precedente.
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
È possibile esportare i nodi 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.
Nota
L'uso delle variabili @export per gli oggetti Resource li rende una dipendenza dell'istanza, il che significa che tutte le risorse a cui fanno riferimento le variabili @export vengono caricate quando viene caricata la scena contenente lo script. Se si desidera fare riferimento a un oggetto Resource ma caricarlo manualmente quando ce ne bisogno (come spesso accade, ad esempio, per i PackedScene che contengono un intero livello), usare invece @export_file o @export_file_path.
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, si possono impostare 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 utilizzando 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 utilizzando 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.
Normalmente, 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 usare @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.
Leggere il valore di una variabile esportata all'inizio
Se si legge il valore di una variabile esportata in _init(), verrà restituito il valore predefinito specificato nell'annotazione di esportazione anziché il valore impostato nell'ispettore. Questo perché l'assegnazione dei valori dal file di scena/risorsa salvato avviene dopo l'inizializzazione dell'oggetto; fino a quel momento, viene utilizzato il valore predefinito.
Per ottenere il valore impostato nell'ispettore (e quindi salvato nel file di scena/risorsa), bisogna leggerlo dopo che l'oggetto è stato costruito, ad esempio in Node._ready(). È anche possibile leggere il valore in un setter definito sulla proprietà esportata, il che è utile nelle risorse personalizzate dove _ready() non è disponibile:
# Set this property to 3 in the inspector.
@export var exported_variable = 2:
set(value):
exported_variable = value
print("Inspector-set value: ", exported_variable)
func _init():
print("Initial value: ", exported_variable)
Risulta in:
Initial value: 2
Inspector-set value: 3
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, è 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.