Начните работу с GameActivity , входящей в комплект разработки игр для Android .

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

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

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

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

См. выпуски GameActivity , чтобы получить дистрибутив.

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

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

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

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

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

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

  • Предлагает API C, аналогичный 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. Включите префаб, выполнив следующие действия с помощью Android Plugin Version (AGP) 4.1+ :

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

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

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

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

    В файле CMakeLists.txt вашего проекта импортируйте статическую библиотеку game-activity в сборный модуль 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, вызывая методы обратного вызова, соответствующие определенным этапам жизненного цикла действия. Чтобы Android мог запустить вашу активность и запустить игру, вам необходимо объявить свою активность с соответствующими атрибутами в манифесте Android. Для получения дополнительной информации см. Введение в действия .

Android-манифест

Каждый проект приложения должен иметь файл AndroidManifest.xml в корне исходного набора проекта. Файл манифеста содержит важную информацию о вашем приложении для инструментов сборки Android, операционной системы Android и Google Play. Это включает в себя:

Внедрите GameActivity в свою игру.

  1. Создайте или определите класс Java основного действия (тот, который указан в элементе 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. Добавьте свою собственную библиотеку в AndroidManifest.xml , если имя вашей библиотеки не является именем по умолчанию ( libmain.so ): 

    <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_pollAll(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. Для дальнейшего чтения изучите реализацию примера Endless Tunnel NDK. Основное различие будет заключаться в том, как обрабатывать события, как показано в следующем разделе.

Обработка событий

Чтобы события ввода могли достигать вашего приложения, создайте и зарегистрируйте фильтры событий с помощью 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);
}

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

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

    android_app_clear_motion_events(mApp);

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

Чтобы узнать больше о GameActivity , см. следующее:

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