Unreal Plugin Language

自动关联目录:Unreal Plugin Language

UPL 是一段在打包期执行的 XML 脚本,用来修改 Android/iOS 的中间工程:注入 Java/ObjC 代码、改 Gradle 配置、加权限、改 plist。

它解决的核心问题是:第三方 SDK 要求改 AndroidManifest/Gradle/plist,但那是引擎生成的,直接改会被覆盖。

工作方式

打包流程(Android)
  生成 Gradle 工程
    → 执行 UPL 脚本(对每个插件)
    → 合并 manifest、注入 Java、改 build.gradle
    → 编译

UPL 文件是 *_UPL.xml,在 .Build.cs 里声明:

if (Target.Platform == UnrealTargetPlatform.Android)
{
    AdditionalPropertiesForReceipt.Add(
        "AndroidPlugin", Path.Combine(ModuleDirectory, "My_UPL.xml"));
}

常用节点

节点作用
<gameActivityClassAdditions>往 GameActivity 里加 Java 代码
<gameActivityOnCreateAdditions>加到 onCreate 里
<gameActivityImportAdditions>加 import
<gameActivityReadMetadata>读取 manifest 元数据
<soLoadLibrary>加载 so
<prebuildCopies> / <resourceCopies>拷贝文件(jar、资源)
<gradleCopies>往 Gradle 工程拷贝/注入
<gradleProperties>加 Gradle 属性
<buildGradleAdditions>改 build.gradle
<androidManifestUpdates>改 AndroidManifest(权限、Activity)
<AARImports>引入 AAR
<mavenImports>Maven 依赖

iOS 侧对应 <iosPListUpdates>、<iosBuildGradleAdditions>( cocoaPods)等。

典型例子

<root xmlns:android="http://schemas.android.com/apk/res/android">
  <gameActivityImportAdditions>
    <insert>
      import com.example.sdk.SdkManager;
    </insert>
  </gameActivityImportAdditions>

  <gameActivityOnCreateAdditions>
    <insert>
      SdkManager.init(this);
    </insert>
  </gameActivityOnCreateAdditions>

  <androidManifestUpdates>
    <addPermission android:name="android.permission.INTERNET"/>
  </androidManifestUpdates>
</root>

与 JNI 的配合

UPL 负责把 Java 代码放进去,JNI 负责两侧互调。标准流程:

  1. 写 Java 桥接类(含 native 声明)
  2. UPL 把它注入工程、加权限、加依赖
  3. C++ 侧实现 native 方法,回调时切回游戏线程

调试

手段说明
查看生成的中间工程Intermediate/Android/... 里的 Gradle 工程
打包日志UPL 执行失败会在 UAT 日志里报 XML/语法错误
手动 gradle 编译直接验证注入结果
adb logcat看运行时 Java 侧日志

最有用的技巧是去看生成的中间工程——UPL 到底改了什么,一眼就能确认。

常见坑

坑说明
XML 里用了 < > 没转义解析失败,用 CDATA 包裹代码块
忘了在 .Build.cs 里声明脚本根本没执行,且不报错
权限/AAR 加了但没生效平台判断写错,或节点放错位置
直接在模板工程里改被覆盖;必须走 UPL
注入的代码引用了不存在的类打包期不报,运行时崩溃
混淆把桥接类去掉proguard 里 keep