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

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

Система Save — это простое хранилище ключ-значение. Вы даёте ему строковый ключ (например "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-blob.

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

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

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

load_progress :: proc(player: Player) -> Player_Progress {
    progress := new(Player_Progress);
    if !Save.try_get_json(player, "progress", ref progress) {
        // Отсутствующий ключ (или сбой разбора) уже имеет значения класса по умолчанию.
    }
    return progress;
}

Save.try_get_json возвращает false если ключ не существует или строка JSON повреждена. Выделяйте данные класса перед загрузкой, потому что ветка 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", "nobody yet");

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

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

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

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

Сохраняйте булевы значения как 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));
}

ordered_get и ordered_get_all асинхронны и выполняются на сервере. Вызывайте их из обычного общего игрового пути; не добавляйте Game.is_server() проверку.

Массивы callback действуют только во время callback, поэтому копируйте все записи, которые нужно сохранить:

Ranking_State :: class : Component {
    entries: [..]Ordered_Save_Entry;

    refresh :: method() {
        Save.ordered_get_all(
            "weekly_score",
            0,
            100,
            this,
            proc(results: []Ordered_Save_Entry, userdata: Object) {
                state := userdata.(Ranking_State);
                state.entries.clear();
                for result: results {
                    state.entries.append(result);
                }
            }
        );
    }
}

Каждый завершённый ordered_get запрос вызывает свой callback один раз. Отсутствующая запись или сбой запроса возвращает переданное значение по умолчанию. Каждый завершённый ordered_get_all запрос также вызывает свой callback один раз; пустой результат или сбой запроса возвращают пустой массив. Сбои запросов записываются в журнал.