For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

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

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

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

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

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

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

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

  • Загружайте сохранённые значения в 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

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

Сохранение «больших» данных (JSON)

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

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

Save.try_get_json возвращает false если ключ не существует или строка JSON повреждена. Выделяйте данные класса перед загрузкой, потому что ветка false их не выделяет. Отсутствующие поля сохраняют значения класса по умолчанию, а неизвестные поля игнорируются.

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

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

Глобальное сохранение (общее для всех)

Глобальное сохранение общее для всей игры, а не для каждого игрока отдельно.

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

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

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

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

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

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

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

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

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

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

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

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

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

Последнее обновление