Ir al contenido
Descargar
El libro de Grost

Guardar partida

Monedas recogidas, niveles desbloqueados, el volumen de la música: el jugador espera encontrarlos la próxima vez que juegue. Conservar datos cuando el juego se cierra se llama persistencia.

En Grost no escribes archivos a mano. Marcas los datos con @persistent y aprenden a guardarse y cargarse solos.

Cada partida guardada va en una ranura (slot): un nombre como "slot1" o "settings". Un juego con tres partidas guardadas usa tres nombres de ranura. Cada ranura es un archivo aparte.

El progreso del jugador (monedas, mejor puntuación, niveles desbloqueados) lo leen muchas partes del juego: el jugador suma monedas, el HUD las muestra, el menú de niveles mira cuáles están abiertos. Por eso casi siempre vive ya en una interfaz global (capítulo 9): un bloque de datos con una sola copia que puede usar cualquier script.

Para guardarla, pon @persistent encima de la interfaz:

progress.iface.gro
@persistent
interface progress global {
live coins : int = 0
mut best_score : int = 0
mut unlocked_levels : Array = [1]
}

La interfaz gana dos funciones, save(slot) y load(slot). Las llamas desde cualquier script que la use:

use interface::progress as progress
fn _ready() void {
if not progress.load("slot1") {
print("new game")
}
}
fn level_done() void {
progress.coins += 10
if not progress.save("slot1") {
print("could not save")
}
}
  • Las dos devuelven un bool (true o false). load da false cuando todavía no hay partida guardada: es una partida nueva. save da false cuando no se pudo escribir el archivo.
  • Después de load, los campos live avisan de su cambio como siempre: corren todos sus watch. Así el HUD muestra las monedas cargadas sin código extra.
  • Solo las interfaces globales pueden ser @persistent. Una interfaz por instancia (una copia por cada actor que la tiene) es un error de compilación: la partida no sabría qué copia restaurar.
  • Algunos campos no se guardan, porque no son estado: los campos sin mut (no pueden cambiar), los static y los derivados (=>, que se calculan a partir de otros campos).

No todos los datos pertenecen a una interfaz. El menú de opciones, una repetición o un editor de niveles tienen sus propios datos. Para ellos, pon @persistent en un struct (capítulo 5), un grupo de campos con nombre:

@persistent
AudioSettings :: struct {
music : float = 0.8
effects : float = 1.0
}
@persistent
Settings :: struct {
fullscreen : bool = true
language : String = "en"
audio : AudioSettings = AudioSettings{}
}

Un struct @persistent dentro de otro (audio, aquí) se guarda junto con él.

El struct recibe dos funciones. save(slot) va en un valor (s.save(...)) y load(slot) va en el tipo (Settings.load(...)):

fn apply_volume(volume: float) void {
mut s : Settings = Settings.load("settings") # defaults if there is no save
s.audio.music = volume
if not s.save("settings") {
print("could not save the settings")
}
}
  • Settings.load("settings") siempre da un Settings: el guardado, o uno con los valores por defecto si no hay partida guardada.
  • s.save("settings") devuelve un bool, como el de la interfaz.

Como todo struct (capítulo 5), un struct @persistent se puede convertir en un Dictionary (pares de nombre y valor) y volver. También se convierte en texto JSON con to_json / from_json. @persistent solo añade save y load:

fn show_settings() void {
s : Settings = Settings.load("settings")
d : Dictionary = s.to_dict()
print(d)
old : Dictionary = { "fullscreen": false, "removed_field": 3 }
from_old : Settings = Settings.from_dict(old)
print($"{from_old.fullscreen} {from_old.language} {from_old.audio.music}")
}
  • to_dict() da los campos por nombre. Los structs anidados también pasan a ser diccionarios.
  • from_dict(d) construye un struct a partir de un diccionario. Sigue las mismas reglas que load, que vienen ahora.

Una partida guarda datos simples: números, texto, listas y cosas así. Un campo de otro tipo es un error de compilación: te enteras mientras escribes el código, no mientras juegas.

Se guardaNo se guarda (error de compilación)
int, float, bool, StringNodos
Vectores, Color, transformacionesRecursos
Array, Dictionary, arrays empaquetadosCallable
Otros structs @persistent

Un nodo o una textura no son datos: guarda lo que los identifica (un nombre, un número de nivel).

Vas a seguir actualizando tu juego cuando ya haya gente con partidas guardadas. Las reglas lo hacen seguro:

  • Un campo que falta en la partida conserva su valor por defecto. Añade campos sin miedo: las partidas viejas siguen cargando y el campo nuevo empieza en su valor por defecto.
  • Un campo de la partida que el struct ya no tiene se ignora. Quita campos sin miedo.
  • Lo que no funciona es renombrar. Para la partida, un campo renombrado es un campo quitado y otro nuevo, así que vuelve a su valor por defecto.

Los datos de cada jugador en un juego en red

Sección titulada «Los datos de cada jugador en un juego en red»

En un juego en red, lo que conserva un jugador (su inventario, su nivel) lo guarda el servidor, el programa que mueve la partida compartida, no la copia del juego de ese jugador. Marca la variable del personaje con @persistent, junto a @replicated u @owner:

# El prefab del personaje (Online > Mode: Player)
@owner @persistent pub mut madera : int = 0
@replicated @persistent pub mut nivel : int = 1
  • El servidor la carga cuando el jugador entra, guarda lo que cambió cada pocos segundos y la vuelve a guardar cuando se va. No hay que llamar a nada.
  • Vive en un archivo SQLite (una pequeña base de datos) en el servidor.
  • Sin red, el juego la guarda igual.

Más en la guía de juegos en red.

En un objeto del mundo colocado en el nivel (Online > Mode: Shared), guarda el estado del mundo entre partidas: un árbol cortado o un cofre abierto siguen así la próxima vez.

Los datos de los jugadores se guardan por el nombre de cada variable:

  • Añade variables nuevas cuando quieras: empiezan con su valor por defecto.
  • Una variable que quitas (o que deja de ser @persistent) pierde lo que los jugadores guardaron en ella.
  • Una variable cuyo tipo cambia de forma que su valor ya no encaja (String a int) vuelve a su valor por defecto. int a float sí encaja.

Para que no pase sin querer, cada exportación escribe sus variables @persistent en config/online_persistent.json (guarda ese archivo con el proyecto), y la siguiente exportación compara con él:

  • Desde Project > Export, si un cambio pierde datos guardados, el editor lo lista y pregunta antes de exportar (Export Anyway o Cancel).
  • Desde la línea de comandos (--export-release, --export-pack…), la exportación avisa en su registro y termina “con avisos”.

El mismo nombre de variable en dos personajes es un solo valor guardado: si sus tipos son distintos, también se avisa.

Debajo de las dos formas está Persist, un singleton (un objeto que el motor crea una sola vez y al que cualquier script llega por su nombre). Guarda un Dictionary en una ranura. Un menú de partidas lo usa para ver qué ranuras están ocupadas o para borrar una:

fn save_note(slot: String, text: String) void {
if not Persist.save(slot, { "note": text }) {
print("could not save ", slot)
}
}
fn read_note(slot: String) String {
if not Persist.has(slot) {
return ""
}
data : Dictionary = Persist.load(slot)
return (data["note"] as String) ?? ""
}
fn erase(slot: String) void {
if not Persist.remove(slot) {
print("nothing to remove in ", slot)
}
}
FunciónQué hace
Persist.save(slot, data)Guarda el diccionario; bool
Persist.load(slot)El diccionario guardado, o uno vacío si no hay
Persist.has(slot)Si la ranura tiene partida guardada
Persist.remove(slot)La borra; bool
  • Cada ranura es un archivo user://saves/<slot>.save.
  • Una ranura es un nombre simple ("slot1", "settings"), no una ruta.

Usa Persist para listar o borrar ranuras desde un menú. Para los datos en sí, mejor @persistent.