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.
Una interfaz global
Sección titulada «Una interfaz global»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:
@persistentinterface 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(trueofalse).loaddafalsecuando todavía no hay partida guardada: es una partida nueva.savedafalsecuando no se pudo escribir el archivo. - Después de
load, los camposliveavisan de su cambio como siempre: corren todos suswatch. 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), losstaticy los derivados (=>, que se calculan a partir de otros campos).
Un struct
Sección titulada «Un struct»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:
@persistentAudioSettings :: struct { music : float = 0.8 effects : float = 1.0}
@persistentSettings :: 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 unSettings: el guardado, o uno con los valores por defecto si no hay partida guardada.s.save("settings")devuelve unbool, como el de la interfaz.
to_dict y from_dict
Sección titulada «to_dict y from_dict»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 queload, que vienen ahora.
Qué se puede guardar
Sección titulada «Qué se puede guardar»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 guarda | No se guarda (error de compilación) |
|---|---|
int, float, bool, String | Nodos |
Vectores, Color, transformaciones | Recursos |
Array, Dictionary, arrays empaquetados | Callable |
Otros structs @persistent |
Un nodo o una textura no son datos: guarda lo que los identifica (un nombre, un número de nivel).
Cambiar tus datos más adelante
Sección titulada «Cambiar tus datos más adelante»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.
Al exportar una versión nueva
Sección titulada «Al exportar una versión nueva»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 (
Stringaint) vuelve a su valor por defecto.intafloatsí 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.
Persist: ranuras a mano
Sección titulada «Persist: ranuras a mano»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ón | Qué 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.