Перейти к содержимому
klyogames

Твоя игра

Как сохранить прогресс игрока в игре на HTML5

Добавь библиотеку klyo в index.html. Даже без кода сохранения игра не потеряет прогресс: библиотека сама переносит в облако её localStorage и файлы движка. Если хочешь сам решать, что считать прогрессом, вызывай klyo.save.get при запуске и klyo.save.set после важных изменений. Игроку, вошедшему в аккаунт, прогресс доступен на любом устройстве.

  • 4 мин чтения
  • Шаги: 5
На этой странице

Прежде чем начать

  • Браузерная игра (чистый JavaScript, Godot, Unity, GameMaker или другой движок с экспортом в браузер) и доступ к её файлу index.html.
  • Состояние игры в виде объекта размером до 64 КБ, например уровень, монеты и настройки.
  • С твоей стороны не нужны ни сервер, ни база данных: остальное сделают библиотека и страница klyo.

Шаг за шагом

  1. Подключи библиотеку

    Вставь эту строку в index.html перед своим скриптом: <script src="https://games.klyo.pl/sdk/klyo-gry-sdk.js"></script>. Движок с экспортом в браузер вызывает те же функции своим способом обращения к JavaScript: в Godot это JavaScriptBridge, в Unity плагин .jslib.

  2. Загрузи прогресс при запуске

    Вызови klyo.save.get(callback) один раз при запуске игры. Если z.ok истинно, а в z.data есть данные, восстанови игру из z.data. z.cloud истинно, когда ответил сервер klyo, а z.reason объясняет, почему данные взяты только из браузера.

  3. Сохраняй после важных изменений

    Вызывай klyo.save.set(state, callback) после прохождения уровня, покупки или смены настроек. Библиотека хранит копию в браузере и объединяет в одно сохранения, которые идут чаще раза в 2 секунды, так что свой таймер не нужен.

  4. Проверь в предпросмотре в студии

    Загрузи архив с игрой и сыграй в окне предпросмотра. Сохранение уходит в облако предпросмотра, которое видишь только ты, а в ответе o.cloud и o.preview истинны. Вызови klyo.save.get ещё раз или снова открой предпросмотр: те же данные вернутся с z.source, равным "chmura".

  5. Опубликуй игру

    После публикации у каждого игрока своё место для сохранений: у вошедшего в аккаунт прогресс есть на любом устройстве, у гостя только в этом браузере. Твоё сохранение из предпросмотра исчезает вместе с предпросмотром.

Если что-то не работает

В ответе сказано, что данные локальные

z.reason объясняет причину. bez-strony: игра запущена вне klyo (прямо из файла или на другом сайте), поэтому прогресс остаётся в браузере. bez-serwera: не было соединения, библиотека отправит копию позже. pusto-w-chmurze: в облаке ещё ничего не было, поэтому игра получила копию из браузера, а библиотека отправила её в облако.

Мой код ждёт, а потом сдаётся

Ответ приходит всегда, не позже чем через 8 секунд, а на klyo сразу. Убери свой более короткий тайм-аут и запускай игру из копии в браузере, не дожидаясь ответа облака.

Сохранение слишком большое

В ответе reason равно rozmiar: закодированное состояние больше 64 КБ. Сохраняй только то, что нужно для восстановления игры, а не всю сцену.

Проверка качества в предпросмотре предупреждает, что прогресс не перейдёт на другие устройства

Библиотека klyo подключена не первым скриптом на странице игры, поэтому копия хранилища приходит, когда игра уже его прочитала. Перенеси строку библиотеки выше всех остальных скриптов или сохраняй прогресс через klyo.save.

Нужен ли игроку аккаунт, чтобы сохранять прогресс?

Нет. Без регистрации прогресс привязан к этому браузеру. С аккаунтом он доступен игроку на любом устройстве, а копия, сохранённая в этом браузере до входа, переносится в аккаунт.

Что будет, если два устройства сохраняют одновременно?

Действует последнее сохранение в облаке. Копия из браузера, которую сервер ещё не подтвердил, уходит в облако, только если за это время не сохранялось другое устройство, поэтому старая копия никогда не перезапишет более новый прогресс.

Увидят ли игроки мои тестовые сохранения из предпросмотра?

Нет. У предпросмотра своё отдельное место, доступ к которому есть только у тебя и модераторов klyo, и оно удаляется вместе с предпросмотром.

Хватит ли localStorage для сохранений в браузерной игре?

На klyo да. Библиотека сама копирует localStorage игры в облако и записывает его на другом устройстве игрока до запуска игры, так что прогресс переходит с телефона на компьютер без единой строки кода. Вне klyo сохранение в localStorage остаётся в одном браузере и пропадает, когда игрок очищает данные сайта.

Работают ли сохранения из Godot или Unity совсем без кода?

Да. Файлы сохранений движка (Godot, Unity и других движков с экспортом в браузер) лежат в базе данных браузера, а библиотека копирует их в облако и записывает на новом устройстве, прежде чем движок их прочитает. Библиотека должна быть первым скриптом на странице игры; если в архиве её нет, мы добавляем её туда сами.

Что, если у игрока разный прогресс на двух устройствах?

Выбирает игрок. Над игрой появляется панель с сообщением, что прогресс на этом устройстве отличается от прогресса в аккаунте, и кнопками Загрузить из аккаунта и Оставить этот. Ничего не перезаписывается молча.

Какого размера может быть хранилище игры?

До 120 КБ localStorage и 120 КБ файлов движка на игрока и игру. Отдельная запись больше 100 КБ, например изображение или кэш, а также самые крупные записи сверх этого лимита остаются только на устройстве. Когда сохранение через klyo.save работает (сервер его подтвердил), библиотека перестаёт делать эту копию: одно сохранение, один источник правды.

Останется ли сохранение после выхода новой версии игры?

Да. Сохранение привязано к адресу игры и аккаунту игрока, а не к файлам в архиве, поэтому новая версия получает то же сохранение. Перед выпуском можешь проверить это в предпросмотре новой версии.

Как сохранить прогресс в браузерной игре на Godot?

Через мост движка к JavaScript: игра получает объект библиотеки klyo, а функция обратного вызова принимает ответ. Полный пример кода есть в документации библиотеки.

Как вызвать сохранение из Unity WebGL?

Из плагина на JavaScript в проекте: функция плагина вызывает набор klyo, а код на C# объявляет эту функцию и вызывает её как любой другой метод.