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 负责两侧互调。标准流程:
- 写 Java 桥接类(含
native声明) - UPL 把它注入工程、加权限、加依赖
- C++ 侧实现 native 方法,回调时切回游戏线程
调试
| 手段 | 说明 |
|---|---|
| 查看生成的中间工程 | Intermediate/Android/... 里的 Gradle 工程 |
| 打包日志 | UPL 执行失败会在 UAT 日志里报 XML/语法错误 |
| 手动 gradle 编译 | 直接验证注入结果 |
| adb logcat | 看运行时 Java 侧日志 |
最有用的技巧是去看生成的中间工程——UPL 到底改了什么,一眼就能确认。
常见坑
| 坑 | 说明 |
|---|---|
XML 里用了 < > 没转义 | 解析失败,用 CDATA 包裹代码块 |
忘了在 .Build.cs 里声明 | 脚本根本没执行,且不报错 |
| 权限/AAR 加了但没生效 | 平台判断写错,或节点放错位置 |
| 直接在模板工程里改 | 被覆盖;必须走 UPL |
| 注入的代码引用了不存在的类 | 打包期不报,运行时崩溃 |
| 混淆把桥接类去掉 | proguard 里 keep |
许可协议:CC BY
作者:Davids
本文链接:https://hustjjd.github.io/64c729ef.html
更新于:2026年11月16日