从 NativeActivity 迁移是 Android 游戏开发套件的一部分。

此页面介绍如何在 Android 游戏项目中从 NativeActivity 迁移到 GameActivity。

GameActivity 基于 Android 框架中的 NativeActivity，并进行了增强和添加了新功能

支持 Jetpack 中的 Fragment。
添加 TextInput 支持以方便软键盘集成。
在 GameActivity Java 类中处理触摸和按键事件，而不是在 NativeActivity onInputEvent 接口中处理。

在迁移之前，我们建议阅读入门指南，其中介绍了如何在项目中设置和集成 GameActivity。

Java 构建脚本更新

GameActivity 作为 Jetpack 库分发。请确保应用入门指南中描述的 Gradle 脚本更新步骤。

在项目的 gradle.properties 文件中启用 Jetpack 库
```
android.useAndroidX=true
```
可选地，在同一个 gradle.properties 文件中指定预制版本，例如
```
android.prefabVersion=2.0.0
```

在应用的 build.gradle 文件中启用预制功能

android {
    ... // other configurations
    buildFeatures.prefab true
}

将 GameActivity 依赖项添加到您的应用程序
1. 添加 core 和 games-activity 库。
2. 如果当前最低支持的 API 级别低于 16，请将其更新至至少 16。
3. 将已编译的 SDK 版本更新为 games-activity 库所需版本。Jetpack 通常在发布构建时需要最新的 SDK 版本。
更新后的 build.gradle 文件可能如下所示
```
android {
    compiledSdkVersion 33
    ... // other configurations.
    defaultConfig {
        minSdkVersion 16
    }
    ... // other configurations.

    buildFeatures.prefab true
}
dependencies {
    implementation 'androidx.core:core:1.9.0'
    implementation 'androidx.games:games-activity:1.2.2'
}
```

Kotlin 或 Java 代码更新

NativeActivity 可用作启动活动并创建全屏应用程序。目前，GameActivity *无法* 用作启动活动。应用必须从 GameActivity 派生一个类，并将其用作启动活动。您还必须进行其他配置更改才能创建全屏应用。

以下步骤假设您的应用程序使用 NativeActivity 作为启动活动。如果不是这种情况，您可以跳过其中的大部分步骤。

创建一个 Kotlin 或 Java 文件来托管新的启动活动。例如，以下代码创建 MainActivity 作为启动活动并加载应用程序的主要原生库 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");
      }
  }

在 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>

在 AndroidManifest.xml 文件中将主题应用于应用程序
```
<application  android:theme=”@style/Application.Fullscreen”>
     
</application>
```
有关全屏模式的详细说明，请参阅沉浸式指南和 games-samples 存储库中的示例实现。

本迁移指南不会更改原生库名称。如果确实更改了它，请确保以下三个位置中的原生库名称一致

Kotlin 或 Java 代码
```
System.loadLibrary(“AndroidGame”)
```

AndroidManifest.xml:

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

在 C/C++ 构建脚本文件中，例如 CMakeLists.txt
```
add_library(AndroidGame ...)
```

C/C++ 构建脚本更新

本节中的说明使用 cmake 作为示例。如果您的应用程序使用 ndk-build，则需要将其映射到 ndk-build 文档页面中描述的等效命令。

GameActivity 的 C/C++ 实现一直在提供源代码版本。对于 1.2.2 或更高版本，提供静态库版本。静态库是推荐的版本类型。

该版本与 prefab 实用程序一起打包在 AAR 中。原生代码包含 GameActivity 的 C/C++ 源代码和 native_app_glue 代码。需要将它们与应用程序的 C/C++ 代码一起构建。

NativeActivity 应用程序已经使用 NDK 中附带的 native_app_glue 代码。您必须将其替换为 GameActivity 的 native_app_glue 版本。除此之外，入门指南中记录的所有 cmake 步骤都适用

按如下方式将 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)
```

删除所有对 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)

解决 UnsatisfiedLinkError 问题

如果遇到 UnsatsifiedLinkError 函数 com.google.androidgamesdk.GameActivity.initializeNativeCode()，请将此代码添加到 CMakeLists.txt 文件中

set(CMAKE_SHARED_LINKER_FLAGS
    "${CMAKE_SHARED_LINKER_FLAGS} -u \
    Java_com_google_androidgamesdk_GameActivity_initializeNativeCode")

C/C++ 源代码更新

请按照以下步骤将应用程序中的 NativeActivity 引用替换为 GameActivity

使用与 GameActivity 一起发布的 native_app_glue。搜索并替换所有 android_native_app_glue.h 用法，替换为
```
#include <game-activity/native_app_glue/android_native_app_glue.h>
```

将运动事件过滤器和按键事件过滤器都设置为 NULL，以便您的应用可以接收来自所有输入设备的输入事件。通常在 android_main() 函数中执行此操作

void android_main(android_app* app) {
    ... // other init code.

    android_app_set_key_event_filter(app, NULL);
    android_app_set_motion_event_filter(app, NULL);

    ... // additional init code, and game loop code.
}

删除与 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];
           int32_t ptrIdx = 0;
           switch (event->action & AMOTION_EVENT_ACTION_MASK) {
               case AMOTION_EVENT_ACTION_POINTER_DOWN:
               case AMOTION_EVENT_ACTION_POINTER_UP:
                   // Retrieve the index for the starting and the ending of any secondary pointers
                   ptrIdx = (event->action & AMOTION_EVENT_ACTION_POINTER_INDEX_MASK) >>
                            AMOTION_EVENT_ACTION_POINTER_INDEX_SHIFT;
               case AMOTION_EVENT_ACTION_DOWN:
               case AMOTION_EVENT_ACTION_UP:
                   engine->state.x = GameActivityPointerAxes_getAxisValue(
                       &event->pointers[ptrIdx], AMOTION_EVENT_AXIS_X);
                   engine->state.y = GameActivityPointerAxes_getAxisValue(
                       &event->pointers[ptrIdx], AMOTION_EVENT_AXIS_Y);
                   break;
                case AMOTION_EVENT_ACTION_MOVE:
                // Process the move action: the new coordinates for all active touch pointers
                // are inside the event->pointers[]. Compare with our internally saved
                // coordinates to find out which pointers are actually moved. Note that there is
                // no index embedded inside event->action for AMOTION_EVENT_ACTION_MOVE (there
                // might be multiple pointers moved at the same time).
                    ...
                   break;
           }
       }
       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 具有您可能想要使用的其他功能。

文本输入.
游戏控制器.
片段.
在 NativeAppGlueAppCmd 中定义的新窗口 InSets 命令。

我们建议您探索这些功能，并根据您的游戏需要进行采用。

如果您对 GameActivity 或其他 AGDK 库有任何疑问或建议，请创建错误报告告知我们。

从 NativeActivity 迁移 是 Android 游戏开发套件 的一部分。