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

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

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

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

• 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 нельзя разобрать в вашу текущую структуру.

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, а когда простые ключи

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

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