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

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

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

• Вещественное (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", 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 больше не соответствует вашей структуре. Рассматривайте это как «начать заново с значениями по умолчанию».

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

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

Player :: class : Player_Base {
    hp: f64;

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

        if save_version < 6 {
            // Пример миграции: hp раньше было целым, теперь это float
            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"

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