Ir al contenido
Descargar
El libro de Grost

Funciones

Una función le pone nombre a un trozo de código para usarlo cuantas veces quieras. En un juego escribirías una para recibir daño, para curarte, para sumar puntos: escribes el código una vez y lo llamas desde donde lo necesites.

Ya viste _ready(), que llama el motor; ahora vas a escribir las tuyas.

fn add(a: int, b: int) int {
return a + b
}
fn greet(who: String) void {
print($"Hello, {who}!")
}
  • fn nombre(parámetros) TipoDeRetorno { ... }. El tipo de retorno (el tipo de lo que devuelve la función) va justo después de los paréntesis, sin flecha.
  • Los parámetros son los valores que recibe la función. Cada parámetro lleva su tipo: a: int.
  • return devuelve el valor. Si la función no devuelve nada, su tipo es void.

Para llamar a una función, escribe su nombre y, entre paréntesis, los valores de sus parámetros (los argumentos):

print(add(2, 3)) # 5
greet("Gobu") # Hello, Gobu!
print(damage(10)) # 10.0
print(damage(10, 1.5)) # 15.0
print(damage(10, 1.5, true)) # 30.0
print(on_hit("spikes", 4)) # 4
print(percent(1, 4)) # 25.0
add_score(10)
print(score) # 10

Casi todos los golpes son normales; solo algunos son críticos. Un valor por defecto te ahorra escribir el caso habitual en cada llamada.

Un parámetro con = valor es opcional: si no lo pasas, toma ese valor.

fn damage(base: int, multiplier: float = 1.0, critical: bool = false) float {
return base * multiplier * (2.0 if critical else 1.0)
}

Los parámetros opcionales van al final. El valor por defecto se calcula en cada llamada, no una sola vez.

damage(10, 1.0, true) no dice qué es ese true. Un argumento puede ir con el nombre de su parámetro, nombre = valor: así puedes saltarte los opcionales que van antes, y la llamada dice qué es cada valor.

fn hits() void {
print(damage(10)) # 10.0
print(damage(10, critical = true)) # 20.0: multiplier keeps its 1.0
print(damage(multiplier = 1.5, base = 10))
}
  • Después de un argumento con nombre, los siguientes también lo llevan.
  • Un parámetro que te saltas toma su valor por defecto; uno sin valor por defecto no se puede saltar.
  • Funciona con tus funciones, los métodos de los structs y los métodos del motor (EffectManager.play(EffectManager.RING, position, color = Color.CYAN)). No con constructores (Vector2(...)) ni con funciones como print.

A veces una función tiene que recibir un parámetro que no necesita, por ejemplo porque otra parte del motor la llama así. Empieza su nombre con _ y el analizador no te avisa:

fn on_hit(_source: String, amount: int) int {
return amount
}

Lo mismo pasa con lo que devuelve una función: una llamada cuyo valor no usa nadie avisa, porque suele ser un descuido. Cuando de verdad no lo necesitas, dilo con _ =:

fn heal_all() void {
_ = on_hit("potion", 5) # the damage it returns isn't needed here
}

Es habitual con métodos del motor que devuelven algo que casi nunca quieres, como _ = body.move_and_slide() (si chocó). Una función que no devuelve nada (void) no se puede descartar: no hay valor.

Algunas funciones solo hacen un cálculo, como pasar una puntuación a porcentaje. Una función static no depende de ningún actor: solo trabaja con lo que recibe. No puede leer las variables del script que no sean también static.

static fn percent(part: int, total: int) float {
return part * 100.0 / total
}

El HUD tiene que mostrar la puntuación del jugador, así que necesita leerla del script del jugador. Lo que declaras en un script es privado: solo lo ve ese script. Con pub delante, otros scripts pueden leerlo (una variable) o llamarlo (una función). Para que otros puedan además escribir una variable, tiene que ser pub mut.

pub mut score : int = 0
pub fn add_score(points: int) void {
score += points
}

Cómo llega un script a otro lo verás en el capítulo 6.

A veces quieres pasarle una regla a otra función: cómo ordenar una lista, qué elementos quedarse. Una lambda es una función sin nombre que guardas en una variable. Se llama como cualquier función (double(3); double.call(3) también vale):

double := fn(x: int) int {
return x * 2
}
print(double(3)) # 6

Una lambda de bloque que devuelve algo necesita su tipo de retorno, como fn(x: int) int { ... }; sin él, el analizador avisa.

Cuando solo devuelve una expresión, escríbela después de =>: se devuelve su valor, y el tipo de retorno es el de la expresión (puedes escribirlo igual, fn(x: int) int => x * 3):

triple := fn(x: int) => x * 3 # returns x * 3, an int
print(triple(3)) # 9

Son útiles para pasar comportamiento a otra función. sort_custom ordena con la regla que le des; un parámetro de tipo Callable (un valor que guarda una función) se llama igual (f(x)):

mut values : []int = [3, 1, 2]
values.sort_custom(fn(a: int, b: int) => a > b)
print(values) # [3, 2, 1]

Una receta de fabricación cuesta lo que valen sus ingredientes; si un ingrediente no tiene precio, la receta entera tampoco. Una función que devuelve un Option (capítulo 1) puede pasar uno vacío: x? es el valor de dentro de x, y cuando x es none la función devuelve none ahí mismo.

fn price(item: String) Option[int] {
if item == "wood" {
return 3
}
if item == "stone" {
return 5
}
return none
}
fn total(a: String, b: String) Option[int] {
return price(a)? + price(b)?
}

Después de if x is none { return } (o break, continue), x es su valor hasta el final del bloque:

stock : Option[int] = price("wood")
if stock is none {
return
}
print(stock * 2) # 6: after the check, stock is an int

Cargar una partida, leer el número de nivel que alguien escribió, preguntar a un servidor: a veces no sale bien, y el código que lo pidió quiere saber por qué. Un Option solo dice “no hay nada”; un Result[T, E] tiene el valor (un T) o el error (un E, a menudo un String):

fn parse_level(text: String) Result[int, String] {
if not text.is_valid_int() {
return err("not a number: " + text)
}
level : int = text.to_int()
if level < 1 or level > 99 {
return err("out of range: " + text)
}
return ok(level)
}
  • ok(valor) es el valor (return level también vale); err(motivo) es el error.
  • Se lee como un Option: con match y sus dos casos, ok(...) y err(...) (los dos, o un _), con if r is ok(v) / if r is err(e), o con ?? valor.
  • También están r.is_ok(), r.is_err() y r.expect("por qué no puede fallar").

x? pasa el error hacia arriba: en una función que devuelve un Result con el mismo tipo de error, un error vuelve al que llamó en ese momento, y si no x? es el valor:

fn next_level(text: String) Result[int, String] {
level : int = parse_level(text)? # an error goes back to the caller as it is
return level + 1
}
match parse_level("12") {
ok(level): { print("level ", level) }
err(why): { print("can't load: ", why) }
}
if parse_level("abc") is err(why) {
print(why) # not a number: abc
}
print(parse_level("300") ?? 1) # 1
print(next_level("41") ?? 0) # 42

Crear un ok no cuesta nada: es el propio valor. Solo un error es un objeto aparte.

La vida nunca debería bajar de 0 ni pasar de su máximo. En lugar de comprobarlo en cada sitio que la cambia, puedes pegar la comprobación a la propia variable.

Una variable puede llevar código que se ejecuta al escribirla (el setter, set) o al leerla (el getter, get). Se declara con un bloque { } justo después del valor inicial; dentro, field es el valor guardado:

mut health : int = 100 {
set(value): field = clamp(value, 0, 100)
get(): return field
}

Cada parte también puede ser un bloque completo:

mut ammo : int = 30 {
set(value) {
field = max(value, 0)
}
get() {
return field
}
}

El setter se ejecuta solo cuando asignas con set delante:

set health = 250
print(health) # 100: the setter clamped it
set health = health - 30
print(health) # 70
health = 250
print(health) # 250: no `set`, no setter

Una asignación sin set escribe el valor directamente y se salta el setter. Así queda claro, al leer el código, qué asignaciones tienen efectos (hacen algo más que guardar el valor).

module Functions
fn add(a: int, b: int) int {
return a + b
}
fn greet(who: String) void {
print($"Hello, {who}!")
}
fn damage(base: int, multiplier: float = 1.0, critical: bool = false) float {
return base * multiplier * (2.0 if critical else 1.0)
}
fn hits() void {
print(damage(10)) # 10.0
print(damage(10, critical = true)) # 20.0: multiplier keeps its 1.0
print(damage(multiplier = 1.5, base = 10))
}
fn on_hit(_source: String, amount: int) int {
return amount
}
fn heal_all() void {
_ = on_hit("potion", 5) # the damage it returns isn't needed here
}
static fn percent(part: int, total: int) float {
return part * 100.0 / total
}
pub mut score : int = 0
pub fn add_score(points: int) void {
score += points
}
fn _ready() void {
print(add(2, 3)) # 5
greet("Gobu") # Hello, Gobu!
print(damage(10)) # 10.0
print(damage(10, 1.5)) # 15.0
print(damage(10, 1.5, true)) # 30.0
print(on_hit("spikes", 4)) # 4
print(percent(1, 4)) # 25.0
add_score(10)
print(score) # 10
}
module Properties
mut health : int = 100 {
set(value): field = clamp(value, 0, 100)
get(): return field
}
mut ammo : int = 30 {
set(value) {
field = max(value, 0)
}
get() {
return field
}
}
fn _ready() void {
set health = 250
print(health) # 100: the setter clamped it
set health = health - 30
print(health) # 70
health = 250
print(health) # 250: no `set`, no setter
set ammo = -5
print(ammo) # 0
}