Сериализация JSON

Для сохранения более сложных структур данных вы можете сериализовать их в JSON и хранить в системе сохранения.

CSL может сериализовать определённые структуры данных в JSON для вас. Это особенно полезно, когда вы хотите сохранить «пакет» связанных полей (например, прогресс игрока, улучшения, разблокировки и т.д.) без управления множеством отдельных ключей сохранения.

Под капотом это использует JSON API системы Save:

• Save.set_json(player, key, value)

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

Сохранение/загрузка в JSON является для каждого игрока (оно принимает игрока). Сохранение на уровне всей игры в настоящее время поддерживает только строки и целые числа.

Что сохраняется?

Только поля, помеченные @ao_serialize включаются в JSON.

Player_Progress :: class {
    version: s64 @ao_serialize;

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

    unlocked_skins: [..]string @ao_serialize;
}

Сохранение в JSON

Сохраните всю структуру под одним ключом:

// Примечание: Записываются только поля с @ao_serialize
Save.set_json(player, "progress", ref progress);

Загрузка из JSON (с значениями по умолчанию)

Save.try_get_json возвращает false если ключ отсутствует или строка JSON испорчена. Если ключ существует, но структура изменилась (добавлены новые поля, удалены старые), оно возвращает true с отсутствующими полями, заполненными нулями.

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

    if !Save.try_get_json(player, "progress", ref progress) {
        // Новый игрок (или старый JSON больше не соответствует) → значения по умолчанию
        progress.version = 1;
        progress.xp = 0;
        progress.level = 1;
        progress.unlocked_skins = .{};
    }

    return progress;
}

Если вы переименуете/удалите сериализованные поля, старый JSON может не распарситься и вы попадёте в путь с значениями по умолчанию. Планируйте миграции заранее (см. ниже).

Версионирование и миграции

Если вы ожидаете, что схема JSON будет меняться, включите поле version в структуру и выполняйте миграцию после загрузки.

Лучшие практики для сохранения совместимости:

• Предпочитайте добавление новых полей (старый JSON часто всё ещё парсится; заполните значения по умолчанию после загрузки)

• Избегайте переименования/удаления полей (может вызвать ошибки парсинга)

• Если вам нужен жёсткий разрыв, рассмотрите сохранение под новым ключом (например, "progress_v2") и сохранение загрузчика с резервным вариантом

Пример миграции:

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 = .{};
    }

    // Миграция вперёд
    if progress.version < 2 {
        progress.version = 2;
        // Пример: v2 ввёл unlocked_skins (инициализируйте его)
        progress.unlocked_skins = .{};
    }

    // Запишите обратно мигрированную версию
    Save.set_json(player, "progress", ref progress);
    return progress;
}

Когда использовать JSON vs простые ключи

• Используйте простые ключи (Save.set_int, Save.set_string, и т.д.) для нескольких значений, которые вы часто читаете/пишите.

• Используйте JSON когда вы хотите хранить связную структуру (прогресс, наборы, разблокировки) и держать логику сохранения централизованной.

Автономный JSON API

Вы также можете сериализовать/десериализовать JSON независимо от системы Save (например, для логирования, сетевого взаимодействия или кастомного хранилища):

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