В связи с прекращением поддержки API входа Google мы удалим SDK для игр v1 в 2026 году. После февраля 2025 года вы не сможете публиковать в Google Play игры, недавно интегрированные с SDK для игр v1. Вместо этого мы рекомендуем использовать SDK для игр v2.
Хотя существующие игры с интеграцией предыдущих игр v1 продолжат функционировать еще пару лет, вам рекомендуется перейти на v2, начиная с июня 2025 года.
Это руководство по использованию Play Games Services v1 SDK. C++ SDK для Play Games Services v2 пока недоступен.
В этом руководстве показано, как сохранять и загружать данные о прогрессе игрока с помощью сервиса «Сохранённые игры» в приложении на C++. Этот сервис позволяет автоматически загружать и сохранять данные о прогрессе игрока в любой момент игры. Этот сервис также позволяет игрокам запускать пользовательский интерфейс для обновления или восстановления существующего сохранения или создания нового.
Прежде чем начать
Если вы еще этого не сделали, возможно, вам будет полезно ознакомиться с концепциями игры «Сохраненные игры» .
Прежде чем начать писать код с использованием API сохраненных игр:
- Установите C++ Play Games SDK .
- Настройте среду разработки C++ .
- Загрузите и просмотрите пример кода C++ .
- Включите службу «Сохраненные игры» в консоли Google Play .
Форматы данных и кроссплатформенная совместимость
Данные сохранённых игр, сохраняемые на серверах Google, должны быть в формате std::vector<uint8_t> . Служба сохранённых игр кодирует ваши данные для кроссплатформенной совместимости; приложения Android могут считывать эти данные как массив байтов без каких-либо проблем с кроссплатформенной совместимостью.
При выборе формата данных для сохранённых игр не используйте форматы, специфичные для конкретной платформы. Мы настоятельно рекомендуем использовать формат данных, например XML или JSON, который имеет надёжную поддержку библиотек на нескольких платформах.
Включить службу сохраненных игр
Прежде чем использовать службу сохранённых игр, необходимо включить к ней доступ. Для этого вызовите EnableSnapshots() при создании службы с помощью gpg::GameServices::Builder . Это включит дополнительные области авторизации, необходимые для сохранённых игр, при следующем событии авторизации.
Показать сохраненные игры
В своей игре вы можете предоставить игрокам возможность сохранять или восстанавливать сохранённые игры. При выборе этой опции игра должна отобразить экран с существующими слотами сохранения и предоставить игрокам возможность сохранить игру в один из этих слотов, загрузить её из него или создать новую сохранённую игру. Для этого используйте следующий метод:
SnapshotManager::ShowSelectUIOperation(...)
Пользовательский интерфейс выбора сохраненных игр позволяет игрокам создавать новые сохраненные игры, просматривать сведения о существующих сохраненных играх и загружать предыдущие сохраненные игры.
SnapshotManager::SnapshotSelectUIResponse response;
if (IsSuccess(response.status)) {
if (response.data.Valid()) {
LogI("Description: %s", response.data.Description().c_str());
LogI("FileName %s", response.data.FileName().c_str());
//Opening the snapshot data
…
} else {
LogI("Creating new snapshot");
…
}
} else {
LogI("ShowSelectUIOperation returns an error %d", response.status);
}
В следующем примере показано, как вызвать пользовательский интерфейс сохраненных игр по умолчанию и обработать выбор пользовательского интерфейса игрока:
service_->Snapshots().ShowSelectUIOperation(
ALLOW_CREATE_SNAPSHOT,
ALLOW_DELETE_SNAPSHOT,
MAX_SNAPSHOTS,
SNAPSHOT_UI_TITLE,
[this](gpg::SnapshotManager::SnapshotSelectUIResponse const & response) {
…
}
Если в приведенном выше примере ALLOW_CREATE_SNAPSHOT имеет значение true , а MAX_SNAPSHOTS превышает фактическое количество снимков, созданных пользователем в данный момент, то пользовательский интерфейс снимков по умолчанию предоставляет игрокам кнопку для создания новой сохраненной игры вместо выбора существующей. (При отображении кнопка находится в нижней части пользовательского интерфейса.) Когда игрок нажимает на эту кнопку, ответ SnapshotSelectUIResponse действителен, но не содержит данных.
Открывать и читать сохраненные игры
Чтобы получить доступ к сохранённой игре и прочитать или изменить её содержимое, сначала откройте объект SnapshotMetadata , представляющий эту сохранённую игру. Затем вызовите метод SnapshotManager::Read*() .
В следующем примере показано, как открыть сохраненную игру:
LogI("Opening file");
service_->Snapshots()
.Open(current_snapshot_.FileName(),
gpg::SnapshotConflictPolicy::BASE_WINS,
[this](gpg::SnapshotManager::OpenResponse const & response) {
LogI("Reading file");
gpg::SnapshotManager::ReadResponse responseRead =
service_->Snapshots().ReadBlocking(response.data);
…
}
Обнаружение и разрешение конфликтов данных
При открытии объекта SnapshotMetadata служба Saved Games определяет наличие конфликтующей сохранённой игры. Конфликты данных могут возникать, если сохранённая игра на локальном устройстве игрока не синхронизирована с удалённой версией, хранящейся на серверах Google.
Политика разрешения конфликтов, указанная вами при открытии сохранённой игры, указывает службе сохранённых игр, как автоматически разрешать конфликты данных. Политика может быть одной из следующих:
| Политика разрешения конфликтов | Описание |
|---|---|
SnapshotConflictPolicy::MANUAL | Указывает, что служба сохранённых игр не должна выполнять никаких действий по разрешению. Вместо этого игра выполнит пользовательское слияние . |
SnapshotConflictPolicy::LONGEST_PLAYTIME | Указывает, что служба сохраненных игр должна выбрать сохраненную игру с наибольшим значением времени игры. |
SnapshotConflictPolicy::BASE_WINS | Указывает, что служба сохраненных игр должна выбрать базовую сохраненную игру. |
SnapshotConflictPolicy::REMOTE_WINS | Указывает, что служба сохранённых игр должна выбрать удалённую сохранённую игру. Удалённая версия — это версия сохранённой игры, обнаруженная на одном из устройств игрока и имеющая более позднюю временную метку, чем базовая версия. |
Если вы указали политику конфликтов, отличную от GPGSnapshotConflictPolicyManual , служба сохранённых игр объединит сохранённую игру и вернёт обновлённую версию через результирующее значение SnapshotManager::OpenResponse . Ваша игра может открыть сохранённую игру, записать в неё данные, а затем вызвать метод SnapshotManager::Commit(...) для публикации сохранённой игры на серверах Google.
Выполнить пользовательское слияние
Если вы указали SnapshotConflictPolicy::MANUAL в качестве политики разрешения конфликтов, ваша игра должна разрешить любой обнаруженный конфликт данных, прежде чем выполнять дальнейшие операции чтения или записи в сохраненной игре.
В этом случае при обнаружении конфликта данных служба возвращает следующие параметры через SnapshotManager::OpenResponse :
-
conflict_idдля уникальной идентификации данного конфликта (это значение будет использовано при сохранении финальной версии игры); - Конфликтующая базовая версия сохраненной игры; и,
- Конфликтующая удаленная версия сохраненной игры.
Ваша игра должна решить, какие данные сохранять, а затем вызвать метод SnapshotManager::ResolveConflictBlocking() для фиксации/разрешения финальной версии на серверах Google.
//Resolve conflict
gpg::SnapshotManager::OpenResponse resolveResponse =
manager.ResolveConflictBlocking(openResponse.conflict_base, metadata_change,
openResponse.conflict_id);
Записать сохраненные игры
Чтобы записать сохраненную игру, сначала откройте объект SnapshotMetadata , представляющий эту сохраненную игру, разрешите все обнаруженные конфликты данных, затем вызовите метод SnapshotManager::Commit() чтобы зафиксировать изменения в сохраненной игре.
В следующем примере показано, как можно создать изменение и зафиксировать сохраненную игру.
Сначала откройте снимок, который вы хотите отредактировать, и убедитесь, что все конфликты разрешены, выбрав базу.
service_->Snapshots().Open( file_name, gpg::SnapshotConflictPolicy::BASE_WINS, [this](gpg::SnapshotManager::OpenResponse const &response) { if (IsSuccess(response.status)) { // metadata : gpg::SnapshotMetadata metadata = response.data; } else { // Handle snapshot open error here } });Затем создайте сохраненное изменение игры, которое включает данные изображения, используемые для обложки:
gpg::SnapshotMetadataChange::Builder builder; gpg::SnapshotMetadataChange metadata_change = builder.SetDescription("CollectAllTheStar savedata") .SetCoverImageFromPngData(pngData).Create();Наконец, сохраните изменения в игре.
gpg::SnapshotManager::CommitResponse commitResponse = service_->Snapshots().CommitBlocking(metadata, metadata_change, SetupSnapshotData());Параметр data содержит все данные сохраненных игр. Изменение также содержит дополнительные метаданные сохраненной игры, такие как время игры и описание сохраненной игры.
Если операция фиксации выполнена успешно, игроки смогут увидеть сохраненную игру в интерфейсе выбора сохраненных игр.