Serialización JSON

Para guardar estructuras de datos más avanzadas, puedes serializarlas a JSON y almacenarlas en el sistema de guardado.

CSL puede serializar ciertas estructuras de datos a JSON para ti. Esto es más útil cuando quieres guardar un “paquete” de campos relacionados (como progreso del jugador, mejoras, desbloqueos, etc.) sin tener que manejar muchas claves de guardado separadas.

Por debajo, esto usa las APIs JSON del sistema de guardado:

• Save.set_json(player, key, value)

• Save.try_get_json(player, key, out) -> bool

El guardado/carga en JSON es por jugador (toma un jugador). El guardado global del juego actualmente solo admite strings + ints.

¿Qué se guarda?

Solo los campos marcados con @ao_serialize se incluyen en el JSON.

Player_Progress :: class {
    version: s64 @ao_serialize;

    xp: s64 @ao_serialize;
    level: s64 @ao_serialize;

    unlocked_skins: [..]string @ao_serialize;
}

Guardando JSON

Guarda toda la estructura bajo una sola clave:

// Nota: Solo se escriben los campos @ao_serialize
Save.set_json(player, "progress", ref progress);

Cargando JSON (con valores predeterminados)

Save.try_get_json devuelve false si la clave falta o la cadena JSON está mal formada. Si la clave existe pero la estructura ha cambiado (se añadieron campos nuevos, se eliminaron campos antiguos), devuelve true con los campos faltantes rellenados con cero.

load_progress :: proc(player: Player) -> Player_Progress {
    progress: Player_Progress;

    if !Save.try_get_json(player, "progress", ref progress) {
        // Jugador nuevo (o el JSON antiguo ya no coincide) → valores predeterminados
        progress.version = 1;
        progress.xp = 0;
        progress.level = 1;
        progress.unlocked_skins = .{};
    }

    return progress;
}

Si renombras/eliminás campos serializados, el JSON antiguo puede dejar de analizarse y caerás en tu ruta de valores predeterminados. Planifica las migraciones con anticipación (ver abajo).

Control de versiones y migraciones

Si esperas que tu esquema JSON cambie, incluye un version campo en la estructura y migra después de cargar.

Buenas prácticas para mantener la compatibilidad:

• Prefiere añadir campos nuevos (el JSON antiguo muchas veces aún se analiza; completa los valores predeterminados después de cargar)

• Evita renombrar/eliminar campos (puede causar fallos de análisis)

• Si necesitas un cambio radical, considera guardar bajo una nueva clave (p. ej., "progress_v2") y mantener un cargador de respaldo

Ejemplo de migración:

load_progress_and_migrate :: proc(player: Player) -> Player_Progress {
    progress: Player_Progress;

    if !Save.try_get_json(player, "progress", ref progress) {
        progress.version = 1;
        progress.xp = 0;
        progress.level = 1;
        progress.unlocked_skins = .{};
    }

    // Migrar hacia adelante
    if progress.version < 2 {
        progress.version = 2;
        // Ejemplo: v2 introdujo unlocked_skins (inicialízalo)
        progress.unlocked_skins = .{};
    }

    // Escribe de vuelta la versión migrada
    Save.set_json(player, "progress", ref progress);
    return progress;
}

Cuándo usar JSON vs claves simples

• Usa claves simples (Save.set_int, Save.set_string, etc.) para unos pocos valores que lees/escribes con frecuencia.

• Usa JSON cuando quieras almacenar una estructura coherente (progreso, cargas, desbloqueos) y mantener centralizada la lógica de guardado.

API JSON independiente

También puedes serializar/deserializar JSON independientemente del sistema de guardado (por ejemplo, para registro, redes o almacenamiento personalizado):

JSON :: struct {
    serialize       :: proc(obj: ref $T) -> string;
    try_deserialize :: proc(json: string, out_value: ref $T) -> bool;
}