Начало работы с 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.
Следуйте инструкциям на странице Jetpack Android Games, чтобы добавить зависимость библиотеки
GameActivityв файлbuild.gradleигры.Чтобы включить Prefab, выполните следующие действия с плагином Android версии 4.1 или более поздней:
- Добавьте в блок
androidфайлаbuild.gradleмодуля следующий код:
buildFeatures { prefab true }- Выберите версию Prefab и задайте ее для файла
gradle.properties:
android.prefabVersion=2.0.0Если вы используете более ранние версии AGP, следуйте инструкциям по настройке в документации по prefab.
- Добавьте в блок
Импортируйте статическую библиотеку C/C++ или исходный код C/C++ в проект, как описано ниже.
Статическая библиотека
В файле
CMakeLists.txtпроекта импортируйте статическую библиотекуgame-activityв модуль prefabgame-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. Примеры:
Название пакета и идентификатор приложения, которые позволяют однозначно идентифицировать вашу игру в Google Play.
Компоненты приложения, такие как действия, сервисы, широковещательные приемники и поставщики контента.
Разрешения на доступ к защищенным частям системы или другим приложениям.
Совместимость устройств. Укажите требования к аппаратному и программному обеспечению для вашей игры.
Название нативной библиотеки для
GameActivityиNativeActivity(по умолчанию – libmain.so).
Как реализовать GameActivity в игре
Создайте или найдите основной класс Java для объекта activity (указанный в элементе
activityв файлеAndroidManifest.xml). Измените этот класс, чтобы расширитьGameActivityиз пакетаcom.google.androidgamesdk:import com.google.androidgamesdk.GameActivity; public class YourGameActivity extends GameActivity { ... }Убедитесь, что нативная библиотека загружается в начале с помощью статического блока:
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"); } ... }Если у вашей нативной библиотеки не стандартное название (
libmain.so), добавьте ее вAndroidManifest.xml.<meta-data android:name="android.app.lib_name" android:value="android-game" />
Реализация android_main
Библиотека
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; }Обрабатывайте
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(); } } }Дополнительную информацию можно найти в примере реализации 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 соответственно.
Выполните итерацию и обработайте каждое событие в игровом цикле. В этом примере следующий код выполняет итерацию
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.После этого не забудьте очистить очередь событий, которые вы только что обработали:
android_app_clear_motion_events(mApp);
Дополнительные ресурсы
Дополнительную информацию о GameActivity можно найти в следующих статьях:
- Примечания к выпуску GameActivity и AGDK
- Используйте GameTextInput в GameActivity.
- руководстве по переходу с NativeActivity.
- Справочная документация по GameActivity
- Реализация GameActivity.
Чтобы сообщить об ошибке или запросить новую функцию для GameActivity, используйте систему отслеживания ошибок GameActivity.