Начало работы с GameActivity   Входит в Android Game Development Kit.

В этом руководстве описано, как настроить и интегрировать GameActivity и обрабатывать события в игре для Android.

GameActivity упрощает использование важных API, помогая вам перенести игру на C или C++ на Android. Ранее для игр рекомендовался класс NativeActivity. Вместо него рекомендуется использовать класс GameActivity, который обратно совместим с уровнем API 19.

Пример интеграции GameActivity можно найти в репозитории games-samples.

Подготовка

Дистрибутив можно скачать на странице GameActivity releases.

Настройте сборку

На Android Activity служит точкой входа в игру, а также предоставляет Window для рисования. Во многих играх этот класс Activity расширяется за счет собственного класса Java или Kotlin, чтобы обойти ограничения в NativeActivity и использовать код JNI для связи с кодом игры на C или C++.

GameActivity предлагает следующие возможности:

  • Наследует от AppCompatActivity, что позволяет использовать компоненты архитектуры Android Jetpack.

  • Преобразуется в SurfaceView, который позволяет взаимодействовать с любым другим элементом интерфейса Android.

  • Обрабатывает события действий Java. Это позволяет интегрировать в игру любой элемент пользовательского интерфейса Android (например, EditText, WebView или Ad) с помощью интерфейса C.

  • Предлагает C API, похожий на NativeActivity и библиотеку android_native_app_glue.

GameActivity распространяется в виде Android Archive (AAR). Этот AAR-файл содержит класс Java, который вы используете в AndroidManifest.xml, а также исходный код C и C++, который связывает Java-часть GameActivity с реализацией приложения на C/C++. Если вы используете GameActivity 1.2.2 или более поздней версии, вам также доступна статическая библиотека C/C++. Мы рекомендуем по возможности использовать статическую библиотеку, а не исходный код.

Включите эти исходные файлы или статическую библиотеку в процесс сборки с помощью Prefab, который предоставляет нативные библиотеки и исходный код вашему проекту CMake или сборке NDK.

  1. Следуйте инструкциям на странице Jetpack Android Games, чтобы добавить зависимость библиотеки GameActivity в файл build.gradle игры.

  2. Чтобы включить Prefab, выполните следующие действия с плагином Android версии 4.1 или более поздней:

    • Добавьте в блок android файла build.gradle модуля следующий код:
    buildFeatures {
        prefab true
    }
    
    • Выберите версию Prefab и задайте ее для файла gradle.properties:
    android.prefabVersion=2.0.0
    

    Если вы используете более ранние версии AGP, следуйте инструкциям по настройке в документации по prefab.

  3. Импортируйте статическую библиотеку C/C++ или исходный код C/C++ в проект, как описано ниже.

    Статическая библиотека

    В файле CMakeLists.txt проекта импортируйте статическую библиотеку game-activity в модуль prefab game-activity_static:

    find_package(game-activity REQUIRED CONFIG)
    target_link_libraries(${PROJECT_NAME} PUBLIC log android
    game-activity::game-activity_static)
    

    Исходный код

    В файле CMakeLists.txt проекта импортируйте пакет game-activity и добавьте его в целевой объект. Пакет game-activity требует libandroid.so, поэтому, если он отсутствует, его также необходимо импортировать.

    find_package(game-activity REQUIRED CONFIG)
    ...
    target_link_libraries(... android game-activity::game-activity)
    

    Также добавьте в файл CmakeLists.txt проекта следующие файлы: GameActivity.cpp, GameTextInput.cpp и android_native_app_glue.c.

Как Android запускает ваше действие

Система Android выполняет код в экземпляре Activity, вызывая методы обратного вызова, которые соответствуют определенным этапам жизненного цикла объекта activity. Чтобы Android мог запустить вашу активность и начать игру, вам нужно объявить активность с соответствующими атрибутами в манифесте Android. Подробнее о действиях…

Файл манифеста Android

В корневом каталоге каждого проекта приложения должен быть файл AndroidManifest.xml. В файле манифеста содержится важная информация о приложении, которая передается инструментам сборки Android, операционной системе Android и Google Play. Примеры:

Как реализовать GameActivity в игре

  1. Создайте или найдите основной класс Java для объекта activity (указанный в элементе activity в файле AndroidManifest.xml). Измените этот класс, чтобы расширить GameActivity из пакета com.google.androidgamesdk:

    import com.google.androidgamesdk.GameActivity;
    
    public class YourGameActivity extends GameActivity { ... }
    
  2. Убедитесь, что нативная библиотека загружается в начале с помощью статического блока:

    public class EndlessTunnelActivity extends GameActivity {
      static {
        // Load the native library.
        // The name "android-game" depends on your CMake configuration, must be
        // consistent here and inside AndroidManifect.xml
        System.loadLibrary("android-game");
      }
      ...
    }
    
  3. Если у вашей нативной библиотеки не стандартное название (libmain.so), добавьте ее в AndroidManifest.xml.

    <meta-data android:name="android.app.lib_name"
     android:value="android-game" />
    

Реализация android_main

  1. Библиотека android_native_app_glue – это библиотека исходного кода, которую ваша игра использует для управления событиями жизненного цикла GameActivity в отдельном потоке, чтобы предотвратить блокировку в основном потоке. При использовании библиотеки вы регистрируете обратный вызов для обработки событий жизненного цикла, например событий сенсорного ввода. Архив GameActivity содержит собственную версию библиотеки android_native_app_glue, поэтому вы не можете использовать версию, включенную в выпуски NDK. Если в ваших играх используется библиотека android_native_app_glue, которая входит в NDK, перейдите на версию GameActivity.

    После добавления исходного кода библиотеки android_native_app_glue в проект она взаимодействует с GameActivity. Реализуйте функцию android_main, которая вызывается библиотекой и используется в качестве точки входа для игры. Ему передается структура android_app. В вашей игре и движке это может быть реализовано иначе. Рассмотрим пример.

    #include <game-activity/native_app_glue/android_native_app_glue.h>
    
    extern "C" {
        void android_main(struct android_app* state);
    };
    
    void android_main(struct android_app* app) {
        NativeEngine *engine = new NativeEngine(app);
        engine->GameLoop();
        delete engine;
    }
    
  2. Обрабатывайте android_app в основном игровом цикле, например опрашивайте и обрабатывайте события цикла приложения, определенные в NativeAppGlueAppCmd. Например, следующий фрагмент кода регистрирует функцию _hand_cmd_proxy в качестве обработчика NativeAppGlueAppCmd, затем опрашивает события цикла приложения и отправляет их зарегистрированному обработчику (в android_app::onAppCmd) для обработки:

    void NativeEngine::GameLoop() {
      mApp->userData = this;
      mApp->onAppCmd = _handle_cmd_proxy;  // register your command handler.
      mApp->textInputState = 0;
    
      while (1) {
        int events;
        struct android_poll_source* source;
    
        // If not animating, block until we get an event;
        // If animating, don't block.
        while ((ALooper_pollOnce(IsAnimating() ? 0 : -1, NULL, &events,
          (void **) &source)) >= 0) {
            if (source != NULL) {
                // process events, native_app_glue internally sends the outstanding
                // application lifecycle events to mApp->onAppCmd.
                source->process(source->app, source);
            }
            if (mApp->destroyRequested) {
                return;
            }
        }
        if (IsAnimating()) {
            DoFrame();
        }
      }
    }
    
  3. Дополнительную информацию можно найти в примере реализации NDK Endless Tunnel. Основное различие заключается в том, как обрабатываются события, как показано в следующем разделе.

Как обрабатывать события

Чтобы события ввода доходили до приложения, создайте и зарегистрируйте фильтры событий с помощью android_app_set_motion_event_filter и android_app_set_key_event_filter. По умолчанию библиотека native_app_glue разрешает события движения только от ввода SOURCE_TOUCHSCREEN. Подробную информацию вы найдете в справочной документации и коде реализации android_native_app_glue.

Чтобы обрабатывать события ввода, получите ссылку на android_input_buffer с помощью android_app_swap_input_buffers() в игровом цикле. Они содержат события движения и ключевые события, произошедшие с момента последнего опроса. Количество событий хранится в motionEventsCount и keyEventsCount соответственно.

  1. Выполните итерацию и обработайте каждое событие в игровом цикле. В этом примере следующий код выполняет итерацию motionEvents и обрабатывает их с помощью handle_event:

    android_input_buffer* inputBuffer = android_app_swap_input_buffers(app);
    if (inputBuffer && inputBuffer->motionEventsCount) {
        for (uint64_t i = 0; i < inputBuffer->motionEventsCount; ++i) {
            GameActivityMotionEvent* motionEvent = &inputBuffer->motionEvents[i];
    
            if (motionEvent->pointerCount > 0) {
                const int action = motionEvent->action;
                const int actionMasked = action & AMOTION_EVENT_ACTION_MASK;
                // Initialize pointerIndex to the max size, we only cook an
                // event at the end of the function if pointerIndex is set to a valid index range
                uint32_t pointerIndex = GAMEACTIVITY_MAX_NUM_POINTERS_IN_MOTION_EVENT;
                struct CookedEvent ev;
                memset(&ev, 0, sizeof(ev));
                ev.motionIsOnScreen = motionEvent->source == AINPUT_SOURCE_TOUCHSCREEN;
                if (ev.motionIsOnScreen) {
                    // use screen size as the motion range
                    ev.motionMinX = 0.0f;
                    ev.motionMaxX = SceneManager::GetInstance()->GetScreenWidth();
                    ev.motionMinY = 0.0f;
                    ev.motionMaxY = SceneManager::GetInstance()->GetScreenHeight();
                }
    
                switch (actionMasked) {
                    case AMOTION_EVENT_ACTION_DOWN:
                        pointerIndex = 0;
                        ev.type = COOKED_EVENT_TYPE_POINTER_DOWN;
                        break;
                    case AMOTION_EVENT_ACTION_POINTER_DOWN:
                        pointerIndex = ((action & AMOTION_EVENT_ACTION_POINTER_INDEX_MASK)
                                       >> AMOTION_EVENT_ACTION_POINTER_INDEX_SHIFT);
                        ev.type = COOKED_EVENT_TYPE_POINTER_DOWN;
                        break;
                    case AMOTION_EVENT_ACTION_UP:
                        pointerIndex = 0;
                        ev.type = COOKED_EVENT_TYPE_POINTER_UP;
                        break;
                    case AMOTION_EVENT_ACTION_POINTER_UP:
                        pointerIndex = ((action & AMOTION_EVENT_ACTION_POINTER_INDEX_MASK)
                                       >> AMOTION_EVENT_ACTION_POINTER_INDEX_SHIFT);
                        ev.type = COOKED_EVENT_TYPE_POINTER_UP;
                        break;
                    case AMOTION_EVENT_ACTION_MOVE: {
                        // Move includes all active pointers, so loop and process them here,
                        // we do not set pointerIndex since we are cooking the events in
                        // this loop rather than at the bottom of the function
                        ev.type = COOKED_EVENT_TYPE_POINTER_MOVE;
                        for (uint32_t i = 0; i < motionEvent->pointerCount; ++i) {
                            _cookEventForPointerIndex(motionEvent, callback, ev, i);
                        }
                        break;
                    }
                    default:
                        break;
                }
    
                // Only cook an event if we set the pointerIndex to a valid range, note that
                // move events cook above in the switch statement.
                if (pointerIndex != GAMEACTIVITY_MAX_NUM_POINTERS_IN_MOTION_EVENT) {
                    _cookEventForPointerIndex(motionEvent, callback,
                                              ev, pointerIndex);
                }
            }
        }
        android_app_clear_motion_events(inputBuffer);
    }
    

    Пример реализации _cookEventForPointerIndex() и других связанных функций можно найти на GitHub.

  2. После этого не забудьте очистить очередь событий, которые вы только что обработали:

    android_app_clear_motion_events(mApp);
    

Дополнительные ресурсы

Дополнительную информацию о GameActivity можно найти в следующих статьях:

Чтобы сообщить об ошибке или запросить новую функцию для GameActivity, используйте систему отслеживания ошибок GameActivity.