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

В связи с прекращением поддержки API Google Sign-In , мы удаляем SDK для игр версии 1 в 2026 году. После февраля 2025 года вы не сможете публиковать в Google Play игры, которые были интегрированы с SDK для игр версии 1. Мы рекомендуем использовать вместо него SDK для игр версии 2.
Хотя существующие игры с интеграцией предыдущих версий v1 будут продолжать работать еще пару лет, мы рекомендуем перейти на версию v2, начиная с июня 2025 года.
Данное руководство предназначено для использования SDK Play Games Services v1. SDK C++ для Play Games Services v2 пока недоступен.

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

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

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

Концепции

В общих чертах, использование SDK осуществляется следующим образом:

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

  3. После получения результата OnAuthActionFinished() вы можете использовать объект GameServices и его дочерние объекты Manager для выполнения вызовов сервисов 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 Games. Экземпляры GameServices создаются с помощью GameServices::Builder .

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

    // 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. Для управления объектом GameServices используйте классы Manager. Доступ к менеджерам осуществляется через экземпляр 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, перейдите к краткому руководству .

Дополнительная информация

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

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