Система сохранений

Система сохранений предоставляет систему хранения данных в формате ключ-значение для сохранения прогресса и настроек игрока между сессиями.

Система сохранения — это простой хранилище ключ-значение. Вы задаёте ему строковый ключ (например "xp"), и он сохраняет значение, которое останется там и в следующий раз, когда игрок зайдёт в игру.

Есть два вида данных сохранения:

• Сохранение игрока: личные данные одного игрока (XP, улучшения, настройки, инвентарь и т. д.)

• Сохранение для всей игры: общее для всех в игре (мировые рекорды, настройки сервера, глобальные счётчики и т. д.)

Не используйте систему сохранения для хранения покупок, которые игроки сделали за sparks. Используйте API покупок/продуктов вместо этого.

Быстрый старт (сохранить + загрузить стат)

Самый распространённый шаблон:

• Загружайте сохранённые значения в ao_start

• Сохраняйте снова всякий раз, когда значение меняется

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

    ao_start :: method() {
        // Для новых игроков используются значения по умолчанию
        xp    = Save.get_int(this, "xp", 0);
        level = Save.get_int(this, "level", 1);
    }
}

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

    // ... здесь ваша логика повышения уровня ...

    // Сохраняйте сразу, когда значение меняется
    Save.set_int(player, "xp", player.xp);
    Save.set_int(player, "level", player.level);
}

Сохранение игрока (данные по игроку)

Сохранение игрока привязано к одному игроку. У каждого игрока есть свои изолированные данные ключ/значение.

Поддерживаемые типы:

• Строка: Save.set_string / Save.get_string

• Целое (s64): Save.set_int / Save.get_int (примечание: в настоящее время значения внутренне усекаются до 32 бит)

• Число с плавающей точкой (f64): Save.set_f64 / Save.get_f64

• JSON (расширенно): Save.set_json / Save.try_get_json

// Настройки
Save.set_string(player, "selected_skin", "knight");
music_volume := Save.get_f64(player, "music_volume", 0.8);

// Удаление ключа (полезно при миграции/удалении старых данных)
Save.delete_key(player, "old_key_name");

Всегда указывайте разумное значение по умолчанию при чтении. У новых игроков ещё не будет ключей, и get_* вернёт ваше значение по умолчанию.

Сохранение «более крупных» данных (JSON)

Если у вас есть небольшой набор полей (например, прогресс + разблокированные вещи), часто удобнее сохранить его как один JSON-блок.

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

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

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

load_progress :: proc(player: Player, out: ref Player_Progress) {
    if !Save.try_get_json(player, "progress", out) {
        // Ключ отсутствует (или разбор не удался) → заполнить значениями по умолчанию
        out.version = 1;
        out.max_health = 100;
        out.unlocked_skins = .{};
    }
}

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

Версионирование сохранений (безопасная миграция старых данных)

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

Player :: class : Player_Base {
    hp: f64;

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

        if save_version < 6 {
            // Пример миграции: раньше hp был целым числом, теперь это число с плавающей точкой
            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);

        // Загрузить текущий формат
        hp = Save.get_f64(this, "hp", 100);
    }
}

Сохранение для всей игры (общее для всех)

Сохранение для всей игры общее для всей игры, а не по игрокам.

// Глобальный обладатель рекорда
Save.set_game_string("world_record_holder", player->get_username());
holder := Save.get_game_string("world_record_holder", "пока никого нет");

// Глобальные счётчики (атомарное увеличение, безопасно, когда много игроков обновляют его)
Save.increment_game_int("total_games_played", 1);
total := Save.get_game_int("total_games_played", 0);

Используйте Save.increment_game_int для счётчиков, которые могут одновременно обновлять несколько игроков (убийства, заходы, сыгранные раунды и т. д.).

Распространённые шаблоны

Булевы значения

Сохраняйте булевы значения как 0/1:

// Сохранить
Save.set_int(player, "tutorial_complete", tutorial_complete ? 1 : 0);

// Загрузить
tutorial_complete = Save.get_int(player, "tutorial_complete", 0) != 0;

Именование ключей

Ключи — это просто строки, так что выбирайте названия, которые потом не будут конфликтовать:

• "xp", "level", "selected_skin"

• "tycoon.cash", "tycoon.upgrades.mouth_level"

Если у вас несколько игр, связанных через родительство игр (хаб + мини-игры), см. Кросс-игровые продукты/данные о том, как можно делиться данными сохранения.

Дополнительные API

Save :: struct {
    // Удаление ключей
    delete_key      :: proc(player: Player, key: string);
    delete_all_keys :: proc(player: Player);

    // Перечисление ключей
    get_all_keys :: proc(player: Player) -> []string;

    // Перечисление для всей игры
    get_all_game_strings :: proc() -> []Save_Game_String;
    get_all_game_ints    :: proc() -> []Save_Game_Int;
    get_all_game_keys    :: proc() -> []Save_Game_Key;

    // Упорядоченные/ранжированные данные (таблицы лидеров)
    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));
}