Version: 2020.3
JAR 插件
适用于 Android 的原生 (C++) 插件

扩展 UnityPlayerActivity Java 代码

本页面包含以下部分:

扩展 UnityPlayerActivity 文件

在开发 Unity Android 应用程序时,可使用插件来扩展标准的 UnityPlayerActivity 类(这是 Android 上的 Unity Player 的主 Java 类,类似于 Unity iOS 上的 AppController.mm)。应用程序可以覆盖 Android 操作系统和 Unity Android 应用程序之间的所有基本交互。

要覆盖默认活动,请执行以下操作:

  • 新建一个从 UnityPlayerActivity 派生的 Activity(请参阅 Android 文档中有关活动 (Activity) 的部分);
  • 修改 Android 清单以将新 Activity 作为应用程序的入口点。

为实现此目的,最简单的方法是从 Unity 导出项目,然后在 Android Studio 中对 UnityPlayerActivity 类进行必要的修改。或者,您可以创建一个新类,对其进行扩展,修改 unityLibrary 项目中的 AndroidManifest.xml,然后将 UnityPlayerActivity 替换为您的类。

要用新 Activity 创建插件并将其添加到项目,必须执行以下步骤: 1. 扩展 UnityPlayerActivity 文件。这最好在从 Unity 导出项目后在 Android Studio 中完成。有几个选项: * 可将包含您的 activity 类的 .java 或 .kt 文件放入 Unity 项目 * 创建包含您的类的 Java 库,进行编译并将生成的 .jar 文件放入 Unity 项目 * 创建包含您的类的 Android 库;这个库可以源代码的形式放入 Unity 项目中(通过命名文件夹,使其具有 .androidlib “扩展”),或者可以进行编译并将生成的 .aar 放入 Unity 项目中

要用新 Activity 创建插件并将其添加到项目,请执行以下步骤:

  1. 扩展 UnityPlayerActivity 文件。这最好在从 Unity 导出项目后在 Android Studio 中完成。然后您有以下选项:

    • 将包含您的 activity 类的 .java 或 .kt 文件直接放入 Unity 项目。默认情况下,该文件位于:

    macOS:

    /Applications/Unity/Unity.app/Contents/PlaybackEngines/AndroidPlayer/src/com/unity3d/player

    Windows:

    C:\Program Files\Unity\Editor\Data\PlaybackEngines\AndroidPlayer\src\com\unity3d\player

    • 创建包含您的类的 Java 库,进行编译并将生成的 .jar 文件放入 Unity 项目
    • 创建一个包含您的类的 Android 库。然后,您可以将此库放入源代码中的 Unity 项目中。为此,请为您的文件夹命名并使用 .androidlib 扩展名,或者可以对其进行编译并将生成的 .aar 文件放入您的 Unity 项目中
  2. 创建一个新的 Android 清单以将新的 Activity 设置为应用程序的入口点,然后将 AndroidManifest.xml 文件放在项目的 Assets/Plugins/Android 文件夹中。

从自定义 UnityPlayerActivity 文件指定 Unity 启动参数

扩展 UnityPlayerActivity 时,可覆盖 String UnityPlayerActivity.updateUnityCommandLineArguments(String cmdLine) 以将启动参数传递给 Unity。

UnityPlayerActivity 会在启动期间调用此方法。它接受当前的命令行参数(这些参数可为 null 或为空),并返回新的命令行参数字符串以传递给 Unity。

有关 Unity 命令行界面的一般概述,请参阅命令行参数

下面的示例演示了如何使用该文件根据当前设备选择图形 API:

package com.company.product;
import com.unity3d.player.UnityPlayerActivity;
import android.os.Bundle;
import android.os.Build;

public class OverrideExample extends UnityPlayerActivity {
    private boolean preferVulkan() {
        // 在 Google Pixel 设备上使用 Vulkan
        if (Build.MANUFACTURER.equals("Google") && Build.MODEL.startsWith("Pixel"))
            return true;
        else
            return false;
    }

    private boolean preferES2() {
        // 在运行 Android 5.1 或更早版本的设备上使用 OpenGL ES 2.0
        if (Build.VERSION.SDK_INT <= Build.VERSION_CODES.LOLLIPOP_MR1)
            return true;
        else
            return false;
    }

    private String appendCommandLineArgument(String cmdLine, String arg) {
        if (arg == null || arg.isEmpty())
            return cmdLine;
        else if (cmdLine == null || cmdLine.isEmpty())
            return arg;
        else
            return cmdLine + " " + arg; 
    } 

    @Override protected String updateUnityCommandLineArguments(String cmdLine)
    {
        if (preferVulkan())
            return appendCommandLineArgument(cmdLine, "-force-vulkan");
        else if (preferES2())
            return appendCommandLineArgument(cmdLine, "-force-gles20");
        else
            return cmdLine; // 让 Unity 根据 PlayerSettings 选择图形 API
    }

    @Override protected void onCreate(Bundle savedInstanceState)
    {
        super.onCreate(savedInstanceState);
    }
}

UnityPlayerActivity 示例文件

以下是 UnityPlayerActivity 文件的示例:

OverrideExample.java:
package com.company.product;
import com.unity3d.player.UnityPlayerActivity;
import android.os.Bundle;
import android.util.Log;

public class OverrideExample extends UnityPlayerActivity {
  protected void onCreate(Bundle savedInstanceState) {
    // 调用 UnityPlayerActivity.onCreate()
    super.onCreate(savedInstanceState);
    // 将调试消息打印至 logcat
    Log.d("OverrideActivity", "onCreate called!");
  }
  public void onBackPressed()
  {
    // 不调用 UnityPlayerActivity.onBackPressed(),而是直接忽略 Back 按钮事件
    // super.onBackPressed();
  }
}

相应的 AndroidManifest.xml 可能如下所示:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.company.product">
  <application android:icon="@drawable/app_icon" android:label="@string/app_name">
    <activity android:name="com.YourPackage.name.OverrideExample"
             android:label="@string/app_name"
             android:configChanges="fontScale|keyboard|keyboardHidden|locale|mnc|mcc|navigation|orientation|screenLayout|screenSize|smallestScreenSize|uiMode|touchscreen">
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.LAUNCHER" />
        </intent-filter>
    </activity>
  </application>
</manifest>

要用新 Activity 创建插件并将其添加到项目,必须执行以下步骤:

  1. 扩展 UnityPlayerActivity 文件。这最好在从 Unity 导出项目后在 Android Studio 中完成。有几个选项:
    • 可将包含您的 activity 类的 .java 或 .kt 文件放入 Unity 项目。
    • 创建包含您的类的 Java 库,进行编译并将生成的 .jar 文件放入 Unity 项目。
    • 创建包含您的类的 Android 库;这个库可以源代码的形式放入 Unity 项目中(通过命名文件夹,使其具有 .androidlib “扩展”),或者可以进行编译并将生成的 .aar 放入 Unity 项目中。
  2. 创建一个新的 Android 清单以将新的 Activity 设置为应用程序的入口点,然后将 AndroidManifest.xml 文件放在项目的 Assets/Plugins/Android 文件夹中。

  • 在 2019.2 中添加了新代码示例。
  • 针对 Unity 2019.3 或更高版本更新了 AndroidManifest 示例
JAR 插件
适用于 Android 的原生 (C++) 插件