Игровые сервисы Play для C++

В связи с прекращением поддержки 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 пока недоступен.

Пакет SDK C++ для игровых сервисов Google Play предоставляет API C++ для использования с игровыми сервисами Google Play и предназначен для разработчиков, у которых уже есть реализация игры на C++.

В настоящее время SDK реализует следующие сервисы:

  • Авторизация
  • Достижения
  • Таблицы лидеров
  • События
  • Сохраненные игры
  • Подключения поблизости (только для Android)
  • Статистика игрока

Концепции

На высоком уровне использование SDK осуществляется следующим образом:

  1. Настройте конфигурацию платформы для Android.
  2. Используйте GameServices::Builder для настройки и создания объекта GameServices . Объект GameServices автоматически пытается выполнить вход и возвращает результат через обратный вызов OnAuthActionFinished() . Обратите внимание на результат, возвращаемый обратным вызовом. Если попытка автоматического входа не удалась, вы можете отобразить кнопку, позволяющую пользователям войти в систему.

  3. После получения результата OnAuthActionFinished() вы можете использовать объект GameServices и его дочерние менеджеры для выполнения вызовов служб Play Games, включая:

    • Войти (после неудачной авторизации): StartAuthorizationUI()
    • Разблокировать достижения: Achievements().Unlock()
    • Показать достижения с помощью встроенного пользовательского интерфейса: Achievements().ShowAllUI()
    • Отправьте высокий результат: Leaderboards().SubmitScore()
    • Выйти: SignOut()

  4. После завершения использования объекта GameServices сбросьте или уничтожьте его.

На более детальном уровне:

  1. Инициализация конфигурации платформы: это объект, содержащий информацию об инициализации, специфичную для платформы. В Android конфигурация платформы содержит виртуальную машину Java и указатель на текущую Activity :

    // In android_main(), create a platform configuration
// and bind the object activity.
// Alternately, attach the activity in JNI_Onload().
gpg::AndroidPlatformConfiguration platform_configuration;
platform_configuration.SetActivity(state->activity->clazz);

  2. Создайте объект GameServices : этот объект является основной точкой входа для функциональности игровых сервисов Google Play. Экземпляры GameServices создаются с помощью GameServices::Builder .

    В большинстве реализаций заданный объект GameServices будет сохраняться до тех пор, пока существует ваша среда C; вам не нужно повторно инициализировать его, когда ваша Android Activity приостанавливается и возобновляется.

    // Creates a GameServices object that has lambda callbacks.
game_services_ = gpg::GameServices::Builder()
        .SetDefaultOnLog(gpg::LogLevel::VERBOSE)
        .SetOnAuthActionStarted([started_callback](gpg::AuthOperation op) {
            is_auth_in_progress_ = true;
            started_callback(op);
        })
        .SetOnAuthActionFinished([finished_callback](gpg::AuthOperation op,
                                                     gpg::AuthStatus status) {
            LOGI("Sign in finished with a result of %d", status);
            is_auth_in_progress_ = false;
            finished_callback(op, status);
        })
        .Create(pc);

  3. Используйте классы Manager для управления объектом GameServices . Доступ к менеджерам осуществляется из экземпляра GameServices , и они группируют связанную функциональность. Примерами таких классов являются менеджеры достижений и рейтингов. Они сами по себе не содержат видимого пользователю состояния. Менеджеры возвращаются по ссылке, а содержащий их экземпляр GameServices управляет их жизненным циклом. Клиент никогда не должен хранить ссылку на Manager. Вместо этого клиент должен хранить экземпляр GameServices .

    Менеджеры возвращают данные через неизменяемые объекты типа значения. Эти значения отражают согласованное представление базовых данных на момент выполнения запроса.

    // Submit a high score
game_services_->Leaderboards().SubmitScore(leaderboard_id, score);

// Show the default Achievements UI
game_services_->Achievements().ShowAllUI();

  4. После завершения использования объекта GameServices выполните очистку, вызвав reset() для unique_ptr , которому он принадлежит, или позволив unique_ptr автоматически уничтожить его при выходе из области действия.

Модель резьбы

Если не указано иное, все методы GameServices и Manager имеют потокобезопасные асинхронные реализации. Их можно вызывать в любом потоке без внешней блокировки, и они будут выполняться в порядке, соответствующем порядку их вызова.

Методы доступа (те, которые считывают состояние) существуют в двух основных вариантах. Первый тип метода (с названиями вроде FetchProperty() ) асинхронно передает свои результаты предоставленному обратному вызову; второй (с названиями вроде FetchPropertyBlocking() ) синхронно возвращает свои результаты вызывающему потоку.

// Blocking callback
gpg::AchievementManager::FetchAllResponse fetchResponse =
        game_services_->Achievements().FetchAllBlocking(std::chrono::milliseconds(1000));

// Non-blocking callback
game_services_->Achievements().FetchAll(gpg::DataSource::CACHE_OR_NETWORK,
    [] (gpg::AchievementManager::FetchAllResponse response) {
    LogI("Achievement response status: %d", response.status);});

Все пользовательские обратные вызовы вызываются в выделенном потоке обратного вызова. Этот поток потенциально отличается от любой концепции платформы «основного потока» или «потока пользовательского интерфейса». Также следует постараться обеспечить быстрое выполнение пользовательских обратных вызовов; остановившийся поток обратного вызова может привести к заметным для пользователя проблемам (например, к задержке выполнения запроса на выход).

Информация, специфичная для платформы

Чтобы приступить к использованию Play Games C++ SDK на Android, перейдите к краткому руководству .

Дальнейшее чтение

Обязательно прочтите документацию по классам, входящую в состав Google Play Game services C++ SDK, для получения более подробной информации, а также ознакомьтесь с примерами , демонстрирующими использование SDK.

Если ваша игра использует внутренний сервер, см. раздел Включение доступа к игровым сервисам Google Play со стороны сервера .