从 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 文件中指定 Prefab 版本，例如
```
android.prefabVersion=2.0.0
```

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

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

将 GameActivity 依赖项添加到您的应用

添加 core 和 games-activity 库。
如果当前最低支持的 API 级别低于 16，请将其更新至至少 16。
将已编译的 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 prefab 模块中
```
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 游戏开发套件 的一部分。