Ir al contenido
Descargar
El libro de Grost

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.

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;
  • @nombre es 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.

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ónMuestra
@editableEl 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)
@multilineUn cuadro de texto grande
@no_alphaUn selector de color sin alfa
@file("*.json") / @dirUn 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
@easingUna curva de suavizado
@placeholder(...)Un campo de texto con una pista mientras está vacío
@storageNada: 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.

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_tree y _ready, y también sus conexiones on. 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 @tool empieza 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.

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)
}

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"
FormaOculta
Clase:propUna 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")).

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.

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ño

La guía de juegos en red lo explica con un ejemplo completo.

AnotaciónEnHace
@editable y familiaVariables mut, structsMuestra el valor en el inspector
@group, @subgroup, @categoryAntes de variables editablesLas agrupa
@buttonUna variable CallableUn botón en el inspector (solo @tool)
@toolEl scriptLo ejecuta también en el editor
@onreadyVariables, watchLo retrasa a cuando el actor está listo
@uneditableEl scriptOculta propiedades heredadas
@iconEl scriptSu icono en el editor
@persistentInterfaces globales, structsGuardar y cargar
@persistentUna variable @replicated/@ownerEl servidor la guarda para el jugador entre partidas
@replicatedVariablesEn red: la decide el servidor, la reciben todos
@ownerVariablesEn red: la decide el servidor, solo la recibe el dueño
@actionFuncionesEn red: se ejecuta en el servidor
@predictedUna @actionEn red: se ejecuta también al momento en el juego que la pide
@everyoneFuncionesEn red: se ejecuta en todos los juegos
@ownerFuncionesEn red: se ejecuta en el juego del dueño del objeto