Ir al contenido
Descargar
El libro de Grost

Señales

Una señal es un mensaje que un script envía cuando pasa algo: “me golpearon”, “morí”, “se pulsó el botón”. Quien esté interesado reacciona; el que envía no necesita saber quién escucha.

Por qué importa en un juego: cuando el jugador recoge una moneda, sube la puntuación, suena un sonido y cambia el HUD. Con una señal, la moneda solo dice “me recogieron”, y cada una de esas partes reacciona por su cuenta. Puedes añadir o quitar una sin tocar la moneda.

Primero el script declara sus señales (dice qué mensajes puede enviar). Luego las emite (las envía) cuando llega el momento:

signal died
signal hit(amount: int)
mut hp : int = 30
mut alive_time : float = 0.0
fn take_damage(amount: int) void {
emit hit(amount)
if hp <= 0 {
died.emit()
}
}
  • signal died declara una señal sin datos; signal hit(amount: int) una con parámetros, los datos que viajan con el mensaje.
  • emit hit(amount) la envía. died.emit() es lo mismo escrito como método.

Para reaccionar a una señal, le conectas un bloque de código con on. El bloque se ejecuta cada vez que se envía la señal:

on self.hit(amount: int) {
hp -= amount
print($"hit for {amount}, hp: {hp}")
}
on self.died() {
print("dead")
}

on <objetivo>.<señal>(parámetros) { } conecta un bloque a una señal. El objetivo es quien envía la señal:

  • self: las señales de este mismo script;
  • un actor importado con use actor:: (capítulo 6);
  • uno de los singletons del motor, los objetos globales que siempre están ahí (Online, GameMode…).

Un botón de la escena, por ejemplo:

use actor::start as start_button : Button
on start_button.pressed() {
SceneManager.load("level1")
}

Y un singleton:

on Online.player_joined(id: int) {
print("entró el jugador ", id)
}
  • Los manejadores (los bloques on) no tienen tipo de retorno ni parámetros por defecto.
  • El objetivo no puede ser una variable miembro (on enemy.died() con mut enemy): es un error. Usa un alias de use actor::.
  • Para un actor que aparece más tarde (un prefab creado en juego), espéralo por etiqueta con on await:
on await player.died() {
print("el jugador ya no está")
}

Aquí player es una etiqueta (el nombre de module del jugador): la conexión se hace en cuanto GetWorld.Spawned("player") lo encuentra.

once conecta un bloque igual que on, pero el bloque solo se ejecuta la primera vez que llega la señal (una vez por cada actor que tiene el código):

signal hit(damage: int)
once self.hit(damage: int) {
print("first hit: ", damage)
}
  • Un on y un once pueden escuchar la misma señal.
  • Dos emisiones en el mismo frame no lo ejecutan dos veces: una moneda que tocan dos cuerpos a la vez cuenta una sola.
  • once fn hace lo mismo con una función: solo se ejecuta su primera llamada.

El motor llama a algunas funciones de tu script en momentos fijos: cuando el actor está listo, en cada frame, cuando sale de la escena. Son las funciones del ciclo de vida (_ready, _process, _exit_tree), y tienen una forma más corta:

on ready {
take_damage(10)
}
on update(delta: float) {
alive_time += delta
}
on destroy {
print("bye")
}
EventoEquivale a
on ready { }fn _ready()
on update(delta: float) { }fn _process(delta: float)
on destroy { }fn _exit_tree()
on construct { }fn _construct()

Usa una forma o la otra para cada función, no las dos.

Imagina una valla con un número @editable de postes: cambias el número en el Inspector y quieres ver los postes al momento, sin ejecutar el juego. Para eso está on construct { }.

Construye el actor a partir de sus valores @editable, como el construction script de Unreal. Corre también en el editor, sin @tool:

  • al abrir el documento;
  • cada vez que cambias uno de sus valores @editable en el Inspector, una vez por frame aunque cambies varios;
  • al guardar su código.

En el juego corre una vez, justo antes de @onready y _ready.

on construct {
# Built again on each change: start from nothing, so the result is always the same.
post_positions.clear()
for i : int in range(posts) {
post_positions.append(Vector2(float(i) * spacing, 0.0))
}
}

En el editor es el único código del script que corre: _ready, _process, la entrada, _notification y las conexiones on esperan al juego (con @tool corre todo). Las variables miembro sí toman su valor inicial, y los setters corren cuando cambia un valor. Mover el actor no lo vuelve a ejecutar.

Escríbelo para que ejecutarlo otra vez dé lo mismo:

  • Borra lo que hizo la vez anterior antes de volver a hacerlo.
  • Lo que cambia se guarda con el documento, así que calcula a partir de los valores @editable.
  • No cambies recursos por copias ahí (gen.graph = gen.graph.duplicate()): al guardar se quedaría la copia en vez del archivo. Para dar a un generador sus propios valores, usa gen.set_parameter(...).

A veces no quieres reaccionar cada vez, sino detenerte aquí hasta que llegue una señal: mostrar un mensaje, esperar a que se abra la puerta y seguir. Eso es await, y una función que lo usa tiene que declararse async fn:

async fn wait_for_door() void {
print("waiting for the door...")
await door_opened
print("the door is open")
}

await sobre una señal con parámetros te da su valor. El tipo no se infiere, así que escríbelo:

async fn wait_for_points() void {
points : int = await scored
print($"scored {points}")
}

Una async fn no se puede llamar como una función normal. spawn la arranca y sigue adelante sin esperar:

fn _ready() void {
spawn wait_for_door()
spawn wait_for_points()
emit door_opened()
emit scored(100)
}

El capítulo 10 trata async fn, spawn y todo lo que las rodea.