Ir al contenido
Descargar
El libro de Grost

Structs y enums

Una bala tiene velocidad, número de impactos y si sigue viva. Podrías guardar cada dato en una variable suelta, pero es más claro agruparlos: eso es un struct.

Y cuando un valor solo puede ser uno de unos pocos casos (quieto, corriendo, saltando), lo describes con un enum.

Una bala, un objeto del inventario, una partida guardada: cada uno son varios valores que siempre van juntos. Un struct le pone nombre a ese grupo:

Projectile :: struct {
speed : float = 100
hits : int = 0
alive : bool = true
}
  • Nombre :: struct { ... } declara el tipo, a nivel de script (fuera de cualquier función).
  • Cada valor de dentro es un campo. Lleva su tipo y, opcionalmente, un valor por defecto.
  • Escribe un campo por línea.

Un literal es un valor escrito directamente en el código. Para un struct es el nombre del tipo seguido de { }:

mut a : Projectile = Projectile{}
b : Projectile = Projectile{ .speed = 250, .hits = 2 }
a.hits += 1
print(a.speed, " ", a.hits) # 100.0 1
print(b.speed, " ", b.hits) # 250.0 2
  • Projectile{} crea uno con todos los valores por defecto.
  • Projectile{ .speed = 250 } cambia solo los campos que nombras, con un punto delante.
  • Los campos se leen y escriben con .: a.hits += 1. Para escribirlos, la variable tiene que ser mut.
  • Declarado sin valor, mut p : Projectile también tiene todos los valores por defecto.

Algunos detalles de los literales:

  • Un literal X{ ... } necesita que X esté declarado antes en el archivo.
  • El struct de otro script se escribe con el módulo de ese script delante: Inventory.Item{ .name = "espada" }. Sus valores por defecto se calculan en su propio script, así que uno que llama a una función de ese módulo funciona igual desde cualquier sitio.
  • Justo antes de un bloque, un {} vacío se lee como el bloque (if x == Mode.ON {}). Ahí escribe el literal vacío entre paréntesis: if (Inventory.Item{}).count == 0 { ... }.

Asignar un struct a otra variable lo copia. Las dos copias son independientes, así que cambiar una nunca cambia la otra por sorpresa:

mut copy : Projectile = a
copy.speed = 5
print(a.speed) # 100.0, the original didn't change
print(copy.speed) # 5.0

Igual que los arrays y diccionarios del capítulo 2: todos son valores.

El código que trabaja con una bala se lee mejor junto a la propia bala. Un bloque impl le añade funciones a un struct:

impl Projectile {
fn new(s: float) Projectile {
return Projectile{ .speed = s }
}
fn get_speed(self) float {
return self.speed
}
fn boost(mut self, k: float) void {
self.speed += k
self.hits += 1
}
}
  • Una función sin self es asociada: se llama sobre el tipo, Projectile.new(10). Es la forma habitual de escribir un constructor, una función que crea un valor listo para usar.
  • Con self es un método: se llama sobre un valor y lee sus campos con self.campo. self es el valor sobre el que se llamó el método.
  • Con mut self el método puede cambiar el valor. Solo se puede llamar sobre una variable mut.
mut p : Projectile = Projectile.new(10)
p.boost(5)
print(p.get_speed()) # 15.0
print(p.hits) # 1
print(p.alive) # true
  • Solo a nivel de script, nunca dentro de una función.
  • No hay herencia: un struct no extiende a otro.
  • Un método no puede usar await (capítulo 10).
  • Un método no puede llamarse igual que un campo.

Una función puede recibir un struct como parámetro. Recibe una copia: puede leerla, y el struct de quien llama no cambia. Para que una función cambie el struct de quien llama, declara el parámetro con & y pasa el struct también con &:

Projectile :: struct {
speed : float = 100
hits : int = 0
}
# A copy: the function reads it and can't change the caller's.
fn damage_of(p : Projectile) int {
return int(p.speed) * (p.hits + 1)
}
# A reference ("&"): the function changes the caller's projectile.
fn hit(p : &Projectile, slow_down : float) void {
p.hits += 1
p.speed -= slow_down
}
mut shot : Projectile = Projectile{ .speed = 200 }
print(damage_of(shot)) # 200
hit(&shot, 50)
print(shot.hits, " ", shot.speed) # 1 150.0
mut volley : []Projectile = [Projectile{}, Projectile{}]
hit(&volley[1], 10)
print(volley[1].speed) # 90.0
  • p : Projectile recibe una copia.
  • p : &Projectile cambia el struct de quien llama, y la llamada lo dice: hit(&shot, 50). Puedes pasar una variable mut, un campo (&a.pos) o un elemento de un array de structs (&volley[1]).
  • Una función con un parámetro & no puede esperar (await, sleep), y una lambda no puede tener uno.
  • & es solo para parámetros: una variable, un campo o un valor devuelto siempre tienen su propio struct.

El motor tiene una especie de caja que puede guardar un valor de cualquier tipo, llamada Variant. Muchas funciones del motor reciben una, y también un Array o un Dictionary sin tipo.

Un struct es un valor simple, no un Variant. Por eso no puedes pasar un struct entero a una función del motor que acepta cualquier valor, ni meterlo en un Array o un Dictionary sin tipo: el analizador lo marca como error. Pasa sus campos.

print y str son la excepción: muestran el struct con sus campos.

Projectile :: struct {
speed : float = 100
hits : int = 0
alive : bool = true
}
fn _ready() void {
p : Projectile = Projectile{}
print(p) # Projectile(speed: 100.0, hits: 0, alive: true)
mut values : Array = []
# values.append(p) # error: un struct no es un valor dinámico
values.append(p.speed) # bien: pasa sus campos
}

Para pasar un struct a algo que necesita un valor dinámico, conviértelo (“Convertir a diccionarios y JSON”, más abajo).

Un inventario es una lista de objetos, y un libro de recetas es un conjunto de recetas por nombre. Un []Item o un Dictionary[String, Item] guarda structs, con sus tipos:

Item :: struct {
name : String = ""
count : int = 0
}
mut items : []Item = [
Item{ .name = "wood", .count = 3 },
Item{ .name = "stone", .count = 1 },
]

Cada elemento es una copia, como cualquier valor de un struct:

  • Leer uno (items[i], for item in items, items.get(i), recipes[key]) da una copia.
  • Cambiar un campo de un elemento (items[i].count += 1) cambia el que está dentro del array.
fn add(item_name: String, count: int) void {
for i : int in items.size() {
if items[i].name == item_name {
items[i].count += count # changes the item inside the array
return
}
}
items.append(Item{ .name = item_name, .count = count })
}
fn total() int {
mut sum : int = 0
for item : Item in items { # each item is a copy
sum += item.count
}
return sum
}
mut recipes : Dictionary[String, Item] = {
"plank": Item{ .name = "wood", .count = 2 },
}
fn cost_of(recipe: String) int {
if recipes.has(recipe) {
return recipes[recipe].count
}
return 0
}
  • append, insert, push_back, push_front, items[i] = item y recipes[key] = item guardan una copia. Asignar un []Item (o duplicate()) da otro array, independiente del primero.
  • recipes.get(key, Item{}) da el struct o el valor por defecto.
  • Un []Item guarda sus structs uno tras otro en memoria, así que items[i].count += 1 cambia el campo donde está, sin copiar el elemento. Sus métodos son size, is_empty, append, push_back, push_front, insert, set, get, fill, remove_at, clear, reverse, shuffle, duplicate, slice, append_array, assign, sort_custom, filter, any, all, map, reduce y find_custom. Las funciones que les das reciben el struct: items.sort_custom(fn(a : Item, b : Item) => a.count < b.count).
  • Un campo pos : [3]float (o [N]int, [N]u8…) también guarda sus valores dentro del struct, así que bodies[i].pos[k] += v cambia el valor donde está, sin crear nada más.

Algunas cosas son errores, y el mensaje dice por qué:

  • structs en un Array/Dictionary sin tipo (a : Array = [item]);
  • un []Item como condición (if items): escribe if not items.is_empty();
  • un struct como clave de un diccionario;
  • has(item) / find(item): cada elemento es su propia copia, así que ninguno es el mismo que item. Compara un campo;
  • pop_back(), front() o get(key) sin valor por defecto: darían un Option de un struct, que aún no existe. Mira antes size() o has(key).

Balas, enemigos, chispas: un juego crea y quita muchos cada segundo. Para seguir a uno necesitas algo que no cambie cuando se quitan otros. Un índice de un []Bullet sí cambia (quitar el elemento 2 mueve todos los de después), y un Dictionary[int, Bullet] sirve pero es lento.

Un Pool[Bullet] los guarda en un bloque, como un []Bullet, y da a cada uno un id:

Bullet :: struct {
x : float = 0
speed : float = 300
life : float = 2
}
mut bullets : Pool[Bullet]
fn shoot(from_x : float) int {
return bullets.add(Bullet{ .x = from_x }) # its id
}
fn _process(delta : float) void {
for id : int in bullets.ids() {
bullets[id].x += bullets[id].speed * delta
bullets[id].life -= delta
if bullets[id].life <= 0 {
_ = bullets.remove(id) # safe inside the loop
}
}
}
  • add(b) guarda una copia y da su id, un int. bullets[id].x += 1 cambia el campo donde está; bullets[id] = b lo reemplaza; get(id) da una copia.
  • remove(id) y has(id) dan un bool; size(), is_empty(), clear() e ids() (los ids de los que siguen vivos) son el resto.
  • for b in bullets recorre los vivos, una copia cada uno. Para cambiarlos, recorre bullets.ids() como arriba: quitar dentro de ese bucle es seguro.
  • &bullets[id] pasa uno a una función con un parámetro &Bullet.

Un id vale hasta que se quita su bala. Su hueco se reutiliza después con un id nuevo, así que un id viejo no encuentra la bala que ocupó su lugar:

first : int = shoot(0)
second : int = shoot(10)
_ = bullets.remove(first)
print(bullets.has(first), " ", bullets.size()) # false 1
third : int = shoot(20) # reuses first's slot, with a new id
print(bullets.has(first), " ", bullets[third].x) # false 20.0
print(bullets[second].x) # 10.0

Usar un id que se quitó para el juego con un error (compruébalo con has(id) si no estás seguro). Como un []Bullet, un pool se copia al asignarlo y no es una condición: if not bullets.is_empty().

Para guardar una partida, mandar datos a un servidor o leer un mod, necesitas tus structs como datos simples. JSON es un formato de texto para datos que lee casi cualquier programa.

Todo struct puede convertirse en Dictionary o en texto JSON y volver, sin escribir nada: el compilador genera to_dict, from_dict, to_json y from_json a partir de sus campos.

Stats :: struct {
hp : int = 100
speed : float = 1.5
}
Enemy :: struct {
name : String = "?"
pos : Vector2 = Vector2.ZERO
stats : Stats = Stats{}
}
fn _ready() void {
mut orc : Enemy = Enemy{ .name = "orc" }
orc.stats.hp = 250
text : String = orc.to_json()
print(text) # {"name":"orc","pos":{...},"stats":{"hp":250,"speed":1.5}}
copy : Enemy = Enemy.from_json(text)
print(copy.stats.hp) # 250
# JSON written by someone else: missing fields keep their defaults,
# fields the struct doesn't have are ignored.
bat : Enemy = Enemy.from_json("{\"name\": \"bat\", \"wings\": 2}")
print(bat.name, " ", bat.stats.hp) # bat 100
}
  • from_json nunca falla: un JSON inválido o campos que faltan dan los valores por defecto, y los campos que el struct no tiene se ignoran. Es la forma de leer JSON de un servidor, un archivo o un mod: declara el struct con los campos que necesitas, y listo.
  • Números, texto, bool, arrays y diccionarios se escriben como JSON normal, legible por cualquier otro programa. Vectores, colores y otros tipos del motor conservan su tipo al volver.
  • Los structs anidados (stats, aquí) también se convierten.

Con diccionarios es igual:

fn as_dictionary() void {
d : Dictionary = Stats{ .hp = 7 }.to_dict()
print(d) # { "hp": 7, "speed": 1.5 }
back : Stats = Stats.from_dict(d)
print(back.hp) # 7
}

Para guardarlos en disco, mira el capítulo 12.

Los dos guardan valores con nombre, así que es fácil usar un Dictionary por costumbre. La pregunta que lo decide: ¿sabes los nombres de los campos al escribir el código?

Si los sabes, es un struct:

# The fields are known when you write the code: a struct.
Player :: struct {
hp : int = 100
speed : float = 4.5
}

Si las claves son datos que decide el juego (ids de objetos, actores, nombres de jugadores), es un Dictionary con tipo, usado como mapa (lleva de una clave a su valor):

# The keys are data that the game decides (item ids): a typed Dictionary.
mut inventory : Dictionary[int, int] = {}
fn add_item(item_id: int, amount: int) void {
inventory[item_id] = (inventory[item_id] ?? 0) + amount
}

Un { hp = 100, speed = 4.5 } que siempre tiene los mismos campos es un struct sin nombre. Pierdes los tipos, el autocompletado y las comprobaciones del analizador antes de que el juego corra (d.hpp solo falla cuando el juego corre), y además es más lento.

Leer un campo 2 millones de veces (runner de scripts de los tests de Gobu, tres rondas):

CómoTiempo
struct: st.mana64–76 ms
Diccionario estilo Lua: d.mana208–232 ms
Diccionario estilo Lua: d["mana"]221–234 ms
Diccionario con comillas: d["mana"]215–237 ms

Un campo de struct es unas 3 veces más rápido, porque se lee directamente; un diccionario tiene que buscar la clave cada vez. Entre los dos estilos de diccionario ({ a = 1 } y { "a": 1 }) no hay diferencia real: usa el que se lea mejor.

Un JSON de un servidor, un archivo o un mod llega como texto con claves que no escribiste tú. Aun así sabes qué campos necesitas: declara un struct con ellos y usa from_json (arriba). El diccionario se queda dentro de la conversión, y el resto del juego trabaja con el struct.

SituaciónUsar
Campos fijos (hp, speed, armor) que se leen a menudostruct
Claves que decide el juego: ids, nombres, actoresDictionary[K, V]
JSON o datos de fueraun struct + from_json
Una función del motor que devuelve un DictionaryDictionary

Un enemigo está quieto, patrullando o persiguiendo; una puerta está abierta o cerrada. Cuando un valor solo puede ser uno de unos pocos casos, un enum le pone nombre a cada caso:

enum State { IDLE, RUN, JUMP = 10 }
mut state : State = State.IDLE
  • Cada caso es un entero: empiezan en 0 y suben de uno en uno, salvo que les des un valor (JUMP = 10).
  • Una variable de tipo enum debería tener un valor inicial.
  • Nombres como State.RUN se leen mucho mejor que un 1 suelto, y una errata es un error en vez de un fallo silencioso.

Con match (capítulo 4) decides qué hacer en cada caso:

fn describe(s: State) String {
match s {
State.IDLE: {
return "standing still"
}
State.RUN: {
return "running"
}
_: {
return "in the air"
}
}
}
print(describe(state)) # standing still
state = State.JUMP
print(describe(state)) # in the air
print(State.RUN) # 1
print(State.JUMP) # 10

A veces cada caso necesita sus propios valores: un círculo tiene un radio, un rectángulo un ancho y un alto. Los casos de un enum pueden llevar campos:

enum Shape {
Circle(radius : float),
Rect(w : float, h : float),
Empty,
}
  • Shape.Circle(2.0) crea uno; un caso sin campos es solo Shape.Empty.
  • Un enum así es un struct por dentro (sin heap): va en un []Shape, un Pool[Shape], un campo, un parámetro…
  • match da un nombre a cada campo del caso, y debe cubrir todos los casos (o tener un _). Un when puede usar esos nombres:
fn area(s : Shape) float {
match s {
Shape.Circle(r): { return 3.14 * r * r }
Shape.Rect(w, h) when w == h: { return w * w } # a square
Shape.Rect(w, h): { return w * h }
Shape.Empty: { return 0.0 }
}
}
  • s is Shape.Circle prueba el caso; if s is Shape.Rect(w, h) { } además nombra sus campos (_ para uno que no necesitas). print(s) muestra Shape.Circle(radius: 2.0).
shapes : []Shape = [Shape.Circle(1.0), Shape.Rect(2.0, 3.0), Shape.Empty]
for s : Shape in shapes {
print(s, " ", area(s)) # Shape.Circle(radius: 1.0) 3.14 ...
}
if shapes[1] is Shape.Rect(w, _) {
print("width ", w) # width 2.0
}
print(shapes[2] is Shape.Empty) # true

Declara el enum antes del código que usa sus casos (como con un literal de struct). Un enum con datos necesita un nombre, y sus casos se numeran en orden (sin = valor).

module Structs
Projectile :: struct {
speed : float = 100
hits : int = 0
alive : bool = true
}
impl Projectile {
fn new(s: float) Projectile {
return Projectile{ .speed = s }
}
fn get_speed(self) float {
return self.speed
}
fn boost(mut self, k: float) void {
self.speed += k
self.hits += 1
}
}
fn _ready() void {
mut a : Projectile = Projectile{}
b : Projectile = Projectile{ .speed = 250, .hits = 2 }
a.hits += 1
print(a.speed, " ", a.hits) # 100.0 1
print(b.speed, " ", b.hits) # 250.0 2
mut copy : Projectile = a
copy.speed = 5
print(a.speed) # 100.0, the original didn't change
print(copy.speed) # 5.0
mut p : Projectile = Projectile.new(10)
p.boost(5)
print(p.get_speed()) # 15.0
print(p.hits) # 1
print(p.alive) # true
}
module Enums
enum State { IDLE, RUN, JUMP = 10 }
mut state : State = State.IDLE
fn describe(s: State) String {
match s {
State.IDLE: {
return "standing still"
}
State.RUN: {
return "running"
}
_: {
return "in the air"
}
}
}
fn _ready() void {
print(describe(state)) # standing still
state = State.JUMP
print(describe(state)) # in the air
print(State.RUN) # 1
print(State.JUMP) # 10
}