Anotaciones
Una anotación es una palabra que empieza por @ y va delante de una declaración. No cambia
lo que hace el código. Le dice algo al editor o al motor: “muestra esto en el inspector”,
“asigna esto cuando el actor esté listo”, “guarda esto”.
Ya viste dos: @onready en un watch (capítulo 8) y @persistent
(capítulo 12). Este capítulo las reúne todas.
Varias a la vez: @(...)
Sección titulada «Varias a la vez: @(...)»Una declaración puede llevar varias anotaciones. Puedes escribirlas una detrás de otra, o
ponerlas en un solo @(...), como escribe Odin sus atributos:
- cada una va sin su
@, con sus argumentos si los tiene; - la lista puede ocupar varias líneas si es larga;
@nombrees lo mismo que@(nombre), así que las dos formas se mezclan sin problema.
module Lenador
@(range(0, 100), replicated, persistent) pub mut vida : int = 100@editable @replicated pub mut nivel : int = 1 # lo mismo que @(editable, replicated)
@( action, predicted,) pub fn talar(desde: Vector2) void { }
fn _ready() void { print(vida, " ", nivel)}Lo que describe el script entero (@tool, @icon, @uneditable) va detrás del nombre del
módulo, en su línea: module Island @tool, o varias a la vez con
module Island @(tool, icon("res://icons/island.svg")). Los grupos del inspector
(@group…) van solos.
@editable: valores en el inspector
Sección titulada «@editable: valores en el inspector»Quien diseña los niveles quiere un enemigo más rápido aquí y otro más lento allí, sin abrir el
código. Una variable marcada @editable aparece en el inspector (el panel que muestra las
propiedades del actor seleccionado). Su valor en el código es el de por defecto; cada instancia
del prefab o de la escena puede cambiarlo sin tocar el código.
@editable mut speed : float = 5.0@range(0, 100, 1) mut volume : int = 50@options("Easy", "Normal", "Hard") mut difficulty : int = 1@multiline mut description : String = ""@no_alpha mut tint : Color = Color.WHITE@file("*.json") mut data_file : String = ""La variable tiene que ser mut: el inspector la escribe. El tipo decide el control (lo que
usas para editarla): un campo numérico, una casilla, un selector de color, una ranura de
recurso… Las variantes añaden una pista:
| Anotación | Muestra |
|---|---|
@editable | El control por defecto del tipo |
@range(min, max, paso) | Un deslizador (añade "or_greater" / "or_less" para permitir pasarse) |
@options("A", "B", ...) | Un desplegable; el valor es el índice (int) |
@multiline | Un cuadro de texto grande |
@no_alpha | Un selector de color sin alfa |
@file("*.json") / @dir | Un selector de archivo / carpeta (el valor es una ruta) |
@node_path(...) | Un selector de nodo, opcionalmente limitado a algunas clases |
@flags(...) | Casillas combinadas como bits |
@easing | Una curva de suavizado |
@placeholder(...) | Un campo de texto con una pista mientras está vacío |
@storage | Nada: se guarda con el documento pero no se muestra |
Un enum tuyo (capítulo 5) como tipo también da un desplegable. Y un
struct entero puede ser editable: @editable Projectile :: struct { ... } muestra sus campos.
Cuando un nodo tiene muchos valores editables, el inspector se convierte en una lista larga.
Agrúpalos: todo lo que va después de @group entra en ese grupo, y lo que va después de
@subgroup, en un subgrupo dentro de él:
@group("Movement")@editable mut jump_force : float = 8.0@subgroup("Air")@editable mut air_control : float = 0.3@category("Nombre") empieza una categoría, un nivel por encima de los grupos.
@tool y botones de herramienta
Sección titulada «@tool y botones de herramienta»Los scripts normalmente solo corren en el juego. @tool, detrás del nombre del módulo
(module Spawner @tool), hace que el script corra también dentro del editor. Así se hacen
herramientas que funcionan mientras editas: un generador, una vista previa, un botón en el
inspector.
Para construir algo a partir de sus valores @editable mientras editas (un generador, una
valla), basta con on construct y no hace falta @tool (capítulo 7): en el
editor solo corre esa parte.
Usa @tool con cuidado: en el editor, el código actúa sobre el documento que estás editando.
Poner o quitar @tool surte efecto al guardar el código del documento; no hace falta volver a
abrir el documento ni el editor:
- Al ponerlo, el código arranca como si el documento se acabara de abrir: corren
_enter_treey_ready, y también sus conexioneson. Pasa en el documento y en sus instancias de otros documentos abiertos. - Al quitarlo, el código se para y conserva los valores que pusiste en el Inspector.
- Una variable que añadas a un script
@toolempieza con su valor inicial. Si ese valor sale de una llamada, empieza con el cero de su tipo.
El uso más conocido es un botón en el inspector, que solo existe en scripts @tool:
@button("Print settings") mut print_button : Callable = print_settings
fn print_settings() void { print($"speed {speed}, volume {volume}, difficulty {difficulty}")}La variable es un Callable (un valor que guarda una función), y su valor es la función que
llama el botón. Sin @tool, @button es un error de compilación.
@onready
Sección titulada «@onready»El valor inicial de una variable miembro se calcula cuando arranca el script, antes de que el
nodo esté en la escena. A veces eso es demasiado pronto: el valor necesita que la escena ya
esté ahí. @onready lo retrasa hasta que el nodo está listo, justo antes de _ready:
@onready mut started_at : int = Time.get_ticks_msec()También acepta un inicializador con await, que espera a que algo exista:
@onready target : Actor = await GetWorld.Spawned("player")Y en un watch, hace que el bloque corra una vez al empezar con el valor actual, no solo en
el primer cambio:
live health : int = 100
@onready watch health(value: int) { print("health -> ", value)}@uneditable: ocultar propiedades heredadas
Sección titulada «@uneditable: ocultar propiedades heredadas»El nodo raíz de un documento tiene las propiedades de su clase (process_mode, la
interpolación de física…). En un prefab, algunas no las debería tocar quien lo usa.
@uneditable las oculta en el inspector. Desde código siguen funcionando.
@uneditable Actor:process_mode Actor>"Physics Interpolation"| Forma | Oculta |
|---|---|
Clase:prop | Una propiedad |
Clase>"Grupo" | Un grupo entero del inspector |
Clase:* | Todas las propiedades de esa clase |
La clase tiene que ser una base del nodo (Button:text en un Actor es un error), y la
propiedad tiene que existir.
@icon("res://..."), detrás del nombre del módulo, le da al script su propio icono en el
editor, para distinguir tus actores de un vistazo. Solo uno por script. Junto a @tool:
module Island @(tool, icon("res://icons/island.svg")).
@persistent
Sección titulada «@persistent»Encima de una interfaz global o de un struct, @persistent añade save y load. Está todo en
el capítulo 12. En una variable de un personaje online, junto a
@replicated u @owner, el servidor la guarda para ese jugador entre partidas.
Juegos en red: @replicated, @owner, @action
Sección titulada «Juegos en red: @replicated, @owner, @action»En un juego en red, varias copias del juego juegan juntas, y un servidor decide lo que pasa de verdad. En un prefab marcado Online (Inspector > Online > Mode), estas anotaciones dicen dónde se decide y dónde corre cada cosa. Como en Unreal, lo replicado lo decide el servidor y los jugadores lo piden:
@replicated pub mut nivel : int = 1 # lo decide el servidor; lo reciben todos@owner @persistent pub mut madera : int = 0 # solo lo recibe el dueño; se guarda entre partidas
@action pub fn talar() void { } # se ejecuta en el servidor@action @predicted pub fn golpear() void { } # en el servidor, y al momento en el juego que la pide@everyone pub fn explotar() void { } # en todos los juegos (un efecto, un sonido)@owner pub fn mostrar_mensaje(texto: String) void { } # se ejecuta en el juego del dueñoLa guía de juegos en red lo explica con un ejemplo completo.
Resumen
Sección titulada «Resumen»| Anotación | En | Hace |
|---|---|---|
@editable y familia | Variables mut, structs | Muestra el valor en el inspector |
@group, @subgroup, @category | Antes de variables editables | Las agrupa |
@button | Una variable Callable | Un botón en el inspector (solo @tool) |
@tool | El script | Lo ejecuta también en el editor |
@onready | Variables, watch | Lo retrasa a cuando el actor está listo |
@uneditable | El script | Oculta propiedades heredadas |
@icon | El script | Su icono en el editor |
@persistent | Interfaces globales, structs | Guardar y cargar |
@persistent | Una variable @replicated/@owner | El servidor la guarda para el jugador entre partidas |
@replicated | Variables | En red: la decide el servidor, la reciben todos |
@owner | Variables | En red: la decide el servidor, solo la recibe el dueño |
@action | Funciones | En red: se ejecuta en el servidor |
@predicted | Una @action | En red: se ejecuta también al momento en el juego que la pide |
@everyone | Funciones | En red: se ejecuta en todos los juegos |
@owner | Funciones | En red: se ejecuta en el juego del dueño del objeto |