从 NativeActivity 迁移到 GameActivity Android Game Development Kit 的一部分。

GameActivity 基于 Android 框架中的 NativeActivity,但包含一些新功能和增强功能:

  • 支持 Jetpack 中的 Fragment
  • 添加了 TextInput 支持,以便集成软键盘。
  • GameActivity Java 类(而非 NativeActivity onInputEvent 接口)中处理触摸和按键事件。

NativeActivity 迁移到 GameActivity 的过程相当简单,需要进行以下应用更改:

  1. 更新您的 Java 和 C/C++ build 脚本。
  2. 集成新的 Java 类和 C/C++ 源代码。

本指南的其余部分将详细介绍必要的步骤。在迁移之前,您最好先阅读入门指南,大致了解 GameActivity 的运作方式。

Java build 脚本更新

GameActivity 以 Jetpack 库的形式分发;请务必遵循入门指南中所述的 Gradle 脚本更新步骤:

  1. 在项目的 gradle.properties 文件中启用 Jetpack 库:

    android.useAndroidX=true
    
  2. (可选)在同一个 gradle.properties 文件中指定 Prefab 版本,例如:

    android.prefabVersion=2.0.0
    
  3. 在应用的 build.gradle 文件中启用 Prefab 功能:

    android {
        ... // other configurations
        buildFeatures.prefab true
    }
    
  4. GameActivity 依赖项添加到您的应用:

    1. 添加 coregames-activity 库。
    2. 如果当前支持的最低 API 级别低于 16,请至少将其更新为 16。
    3. 将已编译的 SDK 版本更新为 games-activity 库所需的版本。Jetpack 通常要求在构建发布 build 时使用最新的 SDK 版本。

    更新后的 build.gradle 文件可能如下所示:

    android {
        compiledSdkVersion 31
        ... // other configurations.
        defaultConfig {
            minSdkVersion 16
        }
        ... // other configurations.
    
        buildFeatures.prefab true
    }
    dependencies {
        implementation 'androidx.core:core:1.4.2'
        implementation 'androidx.games:games-activity:1.1.0'
    }
    

Kotlin 或 Java 代码更新

NativeActivity 可用作启动 activity 并创建全屏应用。目前,GameActivity 不能用作启动 activity。应用必须从 GameActivity 派生一个类,并将其用作启动 activity。您还必须进行其他配置更改,才能创建全屏应用。

以下步骤假定您的应用使用 NativeActivity 作为启动 activity。如果不是这样,您可以跳过其中的大多数步骤。

  1. 创建 Kotlin 或 Java 文件以托管新的启动 activity。例如,以下代码会将 MainActivity 创建为启动 activity 并加载应用的主原生库 libAndroidGame.so

    Kotlin

    class MainActivity : GameActivity() {
       override fun onResume() {
           super.onResume()
           // Use the function recommended from the following page:
           // https://d.android.com/training/system-ui/immersive
           hideSystemBars()
       }
       companion object {
           init {
               System.loadLibrary("AndroidGame")
           }
       }
    }
    

    Java

      public class MainActivity extends GameActivity {
          protected void onResume() {
              super.onResume();
              // Use the function recommended from
              // https://d.android.com/training/system-ui/immersive
              hideSystemBars();
          }
          static {
              System.loadLibrary("AndroidGame");
          }
      }
    
  2. res\values\themes.xml 文件中创建全屏应用主题:

    <resources xmlns:tools="http://schemas.android.com/tools">
        <!-- Base application theme. -->
        <style name="Application.Fullscreen" parent="Theme.AppCompat.Light.NoActionBar">
            <item name="android:windowFullscreen">true</item>
            <item name="android:windowContentOverlay">@null</item>"
        </style>
    </resources>
    
  3. AndroidManifest.xml 文件中将该主题应用到应用:

    <application  android:theme=”@style/Application.Fullscreen”>
         <!-- other configurations not listed here. -->
    </application>
    

本迁移指南不会更改原生库的名称。如果您更改了它,请确保在以下三个位置,原生库名称保持一致:

  • Kotlin 或 Java 代码:

    System.loadLibrary(“AndroidGame”)
    
  • AndroidManifest.xml

    <meta-data android:name="android.app.lib_name"
            android:value="AndroidGame" />
    
  • 在 C/C++ build 脚本文件内,例如 CMakeLists.txt

    add_library(AndroidGame ...)
    

C/C++ build 脚本更新

这一部分中的说明以 cmake 为例。如果您的应用使用 ndk-build,您需要将其映射到 ndk-build 文档页面中介绍的等效命令。

目前,GameActivity 的 C/C++ 实现只有源代码版本,和 prefab 实用程序一起封装在 AAR 中。原生代码包含 GameActivity 的 C/C++ 源代码和 native_app_glue 代码。它们需要与应用的 C/C++ 代码一起构建。

NativeActivity 应用已使用 NDK 中提供的 native_app_glue 代码。您必须将其替换为 GameActivity 的 native_app_glue 版本。除此之外,入门指南中所述的所有 cmake 步骤都适用:

  • game-activity 添加到应用的 C/C++ 模块依赖项:

    find_package(game-activity REQUIRED CONFIG)
        ...
    target_link_libraries(AndroidGame game-activity::game-activity)
    
  • 移除对 NDK 的 native_app_glue 代码的所有引用,例如:

    ${ANDROID_NDK}/sources/android/native_app_glue/android_native_app_glue.c
        ...
    set(CMAKE_SHARED_LINKER_FLAGS
        "${CMAKE_SHARED_LINKER_FLAGS} -u ANativeActivity_onCreate")
    
  • 添加 GameActivity 源代码文件:

    get_target_property(game-activity-include
                        game-activity::game-activity
                        INTERFACE_INCLUDE_DIRECTORIES)
    add_library(${PROJECT_NAME} SHARED
        main.cpp
        ${game-activity-include}/game-activity/native_app_glue/android_native_app_glue.c
        ${game-activity-include}/game-activity/GameActivity.cpp
        ${game-activity-include}/game-text-input/gametextinput.cpp)
    

C/C++ 源代码更新

您可以按照以下步骤将应用中的 NativeActivity 引用替换为 GameActivity

  • 使用通过 GameActivity 发布的 native_app_glue。搜索使用的所有 android_native_app_glue.h 并将其替换为:

    #include <game-activity/native_app_glue/android_native_app_glue.h>
    
  • 移除 AInputEvent 相关代码,并将其替换为 GameActivity 的 InputBuffer 实现:

    while (true) {
        // Read all pending events.
        int events;
        struct android_poll_source* source;
    
        // If not animating, block forever waiting for events.
        // If animating, loop until all events are read, then continue
        // to draw the next frame of animation.
        while ((ALooper_pollAll(engine.animating ? 0 : -1, nullptr, &events,
                                (void**)&source)) >= 0) {
           // Process this app cycle or inset change event.
           if (source) {
               source->process(source->app, source);
           }
    
              ... // Other processing.
    
           // Check if app is exiting.
           if (state->destroyRequested) {
               engine_term_display(&engine);
               return;
           }
        }
        // Process input events if there are any.
        engine_handle_input(state);
    
       if (engine.animating) {
           // Draw a game frame.
       }
    }
    
    // Implement input event handling function.
    static int32_t engine_handle_input(struct android_app* app) {
       auto* engine = (struct engine*)app->userData;
       auto ib = android_app_swap_input_buffers(app);
       if (ib && ib->motionEventsCount) {
           for (int i = 0; i < ib->motionEventsCount; i++) {
               auto event = & ib->motionEvents[i];
               auto action = event->action & AMOTION_EVENT_ACTION_MASK;
               if (action  == AMOTION_EVENT_ACTION_UP ||
                   action  == AMOTION_EVENT_ACTION_POINTER_UP) {
                   int32_t ptrIdx = ((event->action & AMOTION_EVENT_ACTION_POINTER_INDEX_MASK)
                                   >> AMOTION_EVENT_ACTION_POINTER_INDEX_SHIFT);
                   engine->state.x = GameActivityPointerAxes_getAxisValue(
                                     &event->pointers[ptrIdx],
                                     AMOTION_EVENT_AXIS_X);
                   engine->state.y = GameActivityPointerAxes_getAxisValue(
                                     &event->pointers[ptrIdx],
                                     AMOTION_EVENT_AXIS_Y);
               }
           }
           android_app_clear_motion_events(ib);
       }
    
       // Process the KeyEvent in a similar way.
           ...
    
       return 0;
    }
    
  • 查看并更新附加到 NativeActivity 的 AInputEvent 的逻辑。如上一步所示,GameActivity 的 InputBuffer 是在 ALooper_pollAll() 循环之外处理的。

  • 将使用的 android_app::activity->clazz 替换为 android_app:: activity->javaGameActivity。GameActivity 会重命名 Java GameActivity 实例。

其他步骤

前面的步骤涵盖了 NativeActivity 的功能,但 GameActivity 还包含您可能想要使用的其他功能:

我们建议您了解这些功能,并在适当情况下为您的游戏采用这些功能。

如果您对 GameActivity 或其他 AGDK 库有任何疑问或建议,请创建 bug 告诉我们。