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.
Declarar un struct
Sección titulada «Declarar un struct»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.
Crear valores
Sección titulada «Crear valores»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 += 1print(a.speed, " ", a.hits) # 100.0 1print(b.speed, " ", b.hits) # 250.0 2Projectile{}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 sermut. - Declarado sin valor,
mut p : Projectiletambién tiene todos los valores por defecto.
Algunos detalles de los literales:
- Un literal
X{ ... }necesita queXesté 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 { ... }.
Los structs son valores
Sección titulada «Los structs son valores»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 = acopy.speed = 5print(a.speed) # 100.0, the original didn't changeprint(copy.speed) # 5.0Igual que los arrays y diccionarios del capítulo 2: todos son valores.
Funciones y métodos con impl
Sección titulada «Funciones y métodos con impl»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
selfes 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
selfes un método: se llama sobre un valor y lee sus campos conself.campo.selfes el valor sobre el que se llamó el método. - Con
mut selfel método puede cambiar el valor. Solo se puede llamar sobre una variablemut.
mut p : Projectile = Projectile.new(10)p.boost(5)print(p.get_speed()) # 15.0print(p.hits) # 1print(p.alive) # trueLímites de impl
Sección titulada «Límites de impl»- 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.
Pasar structs a funciones
Sección titulada «Pasar structs a funciones»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)) # 200hit(&shot, 50)print(shot.hits, " ", shot.speed) # 1 150.0mut volley : []Projectile = [Projectile{}, Projectile{}]hit(&volley[1], 10)print(volley[1].speed) # 90.0p : Projectilerecibe una copia.p : &Projectilecambia el struct de quien llama, y la llamada lo dice:hit(&shot, 50). Puedes pasar una variablemut, 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.
Los structs no son valores del motor
Sección titulada «Los structs no son valores del motor»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).
Structs en arrays y diccionarios
Sección titulada «Structs en arrays y diccionarios»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] = itemyrecipes[key] = itemguardan una copia. Asignar un[]Item(oduplicate()) da otro array, independiente del primero.recipes.get(key, Item{})da el struct o el valor por defecto.- Un
[]Itemguarda sus structs uno tras otro en memoria, así queitems[i].count += 1cambia el campo donde está, sin copiar el elemento. Sus métodos sonsize,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,reduceyfind_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í quebodies[i].pos[k] += vcambia el valor donde está, sin crear nada más.
Algunas cosas son errores, y el mensaje dice por qué:
- structs en un
Array/Dictionarysin tipo (a : Array = [item]); - un
[]Itemcomo condición (if items): escribeif 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 queitem. Compara un campo;pop_back(),front()oget(key)sin valor por defecto: darían un Option de un struct, que aún no existe. Mira antessize()ohas(key).
Pools: structs que van y vienen
Sección titulada «Pools: structs que van y vienen»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, unint.bullets[id].x += 1cambia el campo donde está;bullets[id] = blo reemplaza;get(id)da una copia.remove(id)yhas(id)dan unbool;size(),is_empty(),clear()eids()(los ids de los que siguen vivos) son el resto.for b in bulletsrecorre los vivos, una copia cada uno. Para cambiarlos, recorrebullets.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 1third : int = shoot(20) # reuses first's slot, with a new idprint(bullets.has(first), " ", bullets[third].x) # false 20.0print(bullets[second].x) # 10.0Usar 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().
Convertir a diccionarios y JSON
Sección titulada «Convertir a diccionarios y JSON»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_jsonnunca 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.
¿Struct o Dictionary?
Sección titulada «¿Struct o Dictionary?»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.
Cuánto más lento
Sección titulada «Cuánto más lento»Leer un campo 2 millones de veces (runner de scripts de los tests de Gobu, tres rondas):
| Cómo | Tiempo |
|---|---|
struct: st.mana | 64–76 ms |
Diccionario estilo Lua: d.mana | 208–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.
Datos de fuera
Sección titulada «Datos de fuera»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ón | Usar |
|---|---|
| Campos fijos (hp, speed, armor) que se leen a menudo | struct |
| Claves que decide el juego: ids, nombres, actores | Dictionary[K, V] |
| JSON o datos de fuera | un struct + from_json |
Una función del motor que devuelve un Dictionary | Dictionary |
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
0y 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.RUNse leen mucho mejor que un1suelto, 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 stillstate = State.JUMPprint(describe(state)) # in the airprint(State.RUN) # 1print(State.JUMP) # 10Enums con datos
Sección titulada «Enums con datos»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 soloShape.Empty.- Un enum así es un struct por dentro (sin heap): va en un
[]Shape, unPool[Shape], un campo, un parámetro… matchda un nombre a cada campo del caso, y debe cubrir todos los casos (o tener un_). Unwhenpuede 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.Circleprueba el caso;if s is Shape.Rect(w, h) { }además nombra sus campos (_para uno que no necesitas).print(s)muestraShape.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) # trueDeclara 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).
Los ejemplos completos
Sección titulada «Los ejemplos completos»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}