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

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

    • Для обычного CSL float (f32) значений, Save.set_float / Save.get_float являются удобными псевдонимами, которые используют то же хранилище f64 и приводят тип на границе API.

  • Ссылка на предмет инвентаря: Save.save_item_reference / Save.get_item_reference

  • JSON (дополнительно): Save.set_json / Save.try_get_json

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

Сохранение экипированного предмета

Используйте ссылку на предмет, чтобы запомнить выбор из любого из постоянных инвентарей игрока, не копируя владение предметом или его свойства в Save:

Save.save_item_reference принимает предметы из автоматически сохраняемого default_inventory или любого инвентаря, созданного с помощью Items.create_player_inventory. Именованные инвентари подходят даже когда авто-сохранение инвентаря по умолчанию отключено. Ссылки сохраняются при перестановке слотов внутри этого инвентаря и при повторном входе. Удаление, выбрасывание, уничтожение или перенос предмета в любой другой инвентарь делает его старые ссылки недействительными, даже для того же игрока или если предмет позже вернётся. Сохраните его снова, чтобы выбрать его в новом инвентаре. Стек, полностью поглощённый при объединении, также становится null; ссылки на оставшийся стек остаются действительными.

Создавайте все именованные инвентари в Player.ao_start до разрешения сохранённых ссылок или JSON-записей. Инвентарь, который ещё не создан, пока не может разрешить свои предметы; геттеры возвращают null без его создания. Существующие сохранённые ссылки остаются доступными для чтения.

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

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

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

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

Item_Instance поля (включая производные типы предметов) используют те же ссылки на инвентарь, что и Save.save_item_reference. Каждый ненулевой предмет должен принадлежать одному из постоянных инвентарей этого игрока. Перенос его в любой другой инвентарь делает ссылку недействительной, даже для того же игрока. Отсутствующий или ставший недействительным предмет, либо предмет, который больше не соответствует производному типу поля, становится null. Создавайте именованные инвентари до загрузки записи. Инвентарь остаётся главным источником истины для владения и данных предмета.

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

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

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

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

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

Save.delete_game_key ставит удаления в очередь и дедуплицирует их при обычной выгрузке сохранения игры. Позднее set_game_string для того же ключа отменяет поставленное в очередь удаление. Позднее increment_game_int сохраняет удаление, сбрасывает сохранённый счётчик до нуля, а затем применяет увеличение.

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

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

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

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

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

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

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

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

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

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

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

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

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