Sistema de guardado

El sistema de guardado ofrece un sistema de almacenamiento de datos clave-valor para conservar el progreso y las preferencias del jugador entre sesiones.

El sistema de guardado es un simple almacén de pares clave-valor. Le das una clave de cadena (como "xp"), y almacena un valor que seguirá ahí la próxima vez que el jugador se conecte.

Hay dos tipos de datos de guardado:

• Guardado del jugador: datos personales de un jugador (XP, mejoras, ajustes, inventario, etc.)
• Guardado global del juego: compartido por todos en el juego (récords del mundo, ajustes del servidor, contadores globales, etc.)

No uses el sistema de guardado para almacenar compras que los jugadores hicieron con chispas. Usa el API de compras/productos en su lugar.

Inicio rápido (guardar + cargar una estadística)

El patrón más común es:

• Carga los valores guardados en ao_start
• Guarda de nuevo cada vez que cambie el valor

Player :: class : Player_Base {
    xp: s64;
    level: s64;

    ao_start :: method() {
        // Los valores predeterminados se usan para jugadores nuevos
        xp    = Save.get_int(this, "xp", 0);
        level = Save.get_int(this, "level", 1);
    }
}

add_xp :: proc(player: Player, amount: s64) {
    player.xp += amount;

    // ... tu lógica de subida de nivel aquí ...

    // Guarda inmediatamente cuando cambie
    Save.set_int(player, "xp", player.xp);
    Save.set_int(player, "level", player.level);
}

Guardado del jugador (datos por jugador)

El guardado del jugador está limitado a un solo jugador. Cada jugador tiene sus propios datos aislados de clave/valor.

Tipos compatibles:

• Cadena: Save.set_string / Save.get_string
• Entero (s64): Save.set_int / Save.get_int (nota: actualmente los valores se truncan internamente a 32 bits)
• Flotante (f64): Save.set_f64 / Save.get_f64
• JSON (avanzado): Save.set_json / Save.try_get_json

// Preferencias
Save.set_string(player, "selected_skin", "knight");
music_volume := Save.get_f64(player, "music_volume", 0.8);

// Eliminar una clave (útil al migrar/eliminar datos antiguos)
Save.delete_key(player, "old_key_name");

Proporciona siempre un valor predeterminado sensato al leer. Los jugadores nuevos aún no tendrán claves, y get_* devolverá tu valor predeterminado.

Guardar datos “más grandes” (JSON)

Si tienes un pequeño conjunto de campos (como progreso + elementos desbloqueados), a menudo es mejor guardarlo como un único bloque JSON.

Solo los campos marcados con @ao_serialize se guardan.

Player_Progress :: class {
    version: s64 = 1 @ao_serialize;
    max_health: s64 = 100 @ao_serialize;
    unlocked_skins: [..]string @ao_serialize;
}

save_progress :: proc(player: Player, progress: Player_Progress) {
    Save.set_json(player, "progress", ref progress);
}

load_progress :: proc(player: Player) -> Player_Progress {
    progress := new(Player_Progress);
    if !Save.try_get_json(player, "progress", ref progress) {
        // La clave faltante (o el análisis fallido) ya tiene los valores predeterminados de la clase.
    }
    return progress;
}

Save.try_get_json devuelve false si la clave no existe o la cadena JSON está mal formada. Asigna memoria para los datos de la clase antes de cargar, porque la ruta falsa no la asigna. Los campos faltantes conservan los valores predeterminados de su clase, y los campos desconocidos se ignoran.

Versionado del guardado (migrar datos antiguos de forma segura)

Si alguna vez cambias el formato de guardado, conserva una versión clave y migra los guardados antiguos hacia adelante.

Player :: class : Player_Base {
    hp: f64;

    ao_start :: method() {
        save_version := Save.get_int(this, "version", 0);

        if save_version < 6 {
            // Ejemplo de migración: hp antes era un entero, ahora es un flotante
            save_version = 6;
            old_hp := Save.get_int(this, "hp", 100);
            Save.delete_key(this, "hp");
            Save.set_f64(this, "hp", old_hp.(f64));
        }

        Save.set_int(this, "version", save_version);

        // Carga el formato actual
        hp = Save.get_f64(this, "hp", 100);
    }
}

Guardado global del juego (compartido por todos)

El guardado global del juego se comparte en todo el juego, no por jugador.

// Titular del récord global
Save.set_game_string("world_record_holder", player.get_username());
holder := Save.get_game_string("world_record_holder", "nadie todavía");

// Contadores globales (incremento atómico, seguro cuando muchos jugadores lo actualizan)
Save.increment_game_int("total_games_played", 1);
total := Save.get_game_int("total_games_played", 0);

Usa Save.increment_game_int para contadores que varios jugadores podrían actualizar al mismo tiempo (bajas, uniones, rondas jugadas, etc.). Su optimistic_update parámetro tiene el valor predeterminado de true, así que el valor local en caché cambia inmediatamente.

Patrones comunes

Booleanos

Guarda los booleanos como 0/1:

// Guardar
Save.set_int(player, "tutorial_complete", tutorial_complete ? 1 : 0);

// Cargar
tutorial_complete = Save.get_int(player, "tutorial_complete", 0) != 0;

Nomenclatura de claves

Las claves son solo cadenas, así que elige nombres que no entren en conflicto más adelante:

• "xp", "level", "selected_skin"
• "tycoon.cash", "tycoon.upgrades.mouth_level"

Si tienes varios juegos conectados mediante game parenting (hub + minijuegos), consulta Productos/datos entre juegos para ver cómo se pueden compartir los datos guardados.

APIs adicionales

Save :: struct {
    // Eliminar claves
    delete_key      :: proc(player: Player, key: string);
    delete_all_keys :: proc(player: Player);

    // Enumerar claves
    get_all_keys :: proc(player: Player) -> []string;

    // Enumeración global
    get_all_game_strings :: proc() -> []Save_Game_String;
    get_all_game_ints    :: proc() -> []Save_Game_Int;
    get_all_game_keys    :: proc() -> []Save_Game_Key;

    // Datos ordenados/clasificados (tablas de clasificación)
    ordered_set     :: proc(document: string, key: string, value: f64);
    ordered_get     :: proc(document: string, key: string, default: f64,
                            userdata: Object,
                            callback: proc(entry: Ordered_Save_Entry, userdata: Object));
    ordered_get_all :: proc(document: string, offset: s64, limit: s64,
                            userdata: Object,
                            callback: proc(entries: []Ordered_Save_Entry, userdata: Object));
}

ordered_get y ordered_get_all son asíncronos y se ejecutan en el servidor. Llámalos desde la ruta normal compartida del juego; no añadas una Game.is_server() protección.

Los arreglos de devolución de llamada solo son válidos durante la devolución de llamada, así que copia cualquier entrada que necesites conservar:

Ranking_State :: class : Component {
    entries: [..]Ordered_Save_Entry;

    refresh :: method() {
        Save.ordered_get_all(
            "weekly_score",
            0,
            100,
            this,
            proc(results: []Ordered_Save_Entry, userdata: Object) {
                state := userdata.(Ranking_State);
                state.entries.clear();
                for result: results {
                    state.entries.append(result);
                }
            }
        );
    }
}

Cada solicitud completada ordered_get invoca su devolución de llamada una vez. Una entrada faltante o un fallo de la solicitud devuelve el valor predeterminado proporcionado. Cada solicitud completada ordered_get_all también invoca su devolución de llamada una vez; un resultado vacío o un fallo de la solicitud proporciona un arreglo vacío. Los fallos de la solicitud se registran.