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 en JSON por ti. Esto es más útil cuando quieres guardar un “paquete” de campos relacionados (como el progreso del jugador, mejoras, desbloqueos, etc.) sin gestionar muchas claves de guardado separadas.

Debajo del capó, esto usa las API 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 a nivel de juego actualmente soporta solo cadenas y enteros.

¿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 con @ao_serialize
Save.set_json(player, "progress", ref progress);

Cargando JSON (con valores por defecto)

Save.try_get_json devuelve false si falta la clave o el JSON guardado no se puede analizar en tu estructura actual.

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 por defecto
        progress.version = 1;
        progress.xp = 0;
        progress.level = 1;
        progress.unlocked_skins = .{};
    }

    return progress;
}

Si renombras/eliminás campos serializados, el JSON antiguo puede fallar al analizarse y caerás en la ruta de valores por defecto. Planifica migraciones con antelación (ver más abajo).

Versionado y migraciones

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

Mejores prácticas para mantener compatibilidad:

• Prefiere agregar nuevos campos (el JSON antiguo a menudo aún se puede analizar; completa los valores por defecto después de cargar)

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

• Si necesitas una ruptura drástica, considera guardar bajo una nueva clave (p. ej. "progress_v2") y mantener un cargador de reserva

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 (inicializarlo)
        progress.unlocked_skins = .{};
    }

    // Volver a escribir 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 un puñado de valores que lees/escribes con frecuencia.

• Usa JSON cuando quieres almacenar una estructura cohesionada (progreso, equipamientos, desbloqueos) y mantener tu lógica de guardado centralizada.