Unity 将 Gradle 用于所有 Android 构建。可以在 Unity 中构建输出包(.apk、.aab),也可以从 Unity 导出 Gradle 项目,然后通过外部工具(如 Android Studio)进行构建。
什么是Gradle?
- 一款优秀的自动化构建系统工具。
- DSL(特定领域语言)基于Groovy。语法和Java相接近。
Unity的Gradle层次结构
为了清楚的理解Unity中的Android Gradle结构,我们首先可以导出Unity生成的Unity Gradle层次结构。
- 最简单的方式就是我们Build 下我们的Apk,然后在Temp/gradleOut获取我们的 Gradle层次结构。
- 或者Build出Android Gradle项目。
launcher:
- 启动器部分,其中包含应用程序的名称及其图标。
- 默认是可启动 Unity 的简单 Android 应用程序。可以将此模块替换为自己的应用程序。
src:
- 启动器模块的代码和资源。
build.gradle
- 描述如何构建启动器模块,并包含要在构建中包含的依赖项列表。
- 依赖于unityLibrary模块,当构建启动器模块时,unityLibrary必须包含在最终结果中。
- 对应自定义Gradle的Custom Launcher Gradle Template文件。
unityLibrary:
- 我们的Unity模块,包含 Unity 运行时和播放器数据。
- 可以集成到其他任何 Gradle 项目中,注意集成时如下注意:详情
- 仅支持全屏渲染,不支持在部分屏幕中渲染。
- 不能加载或集成多个 Unity 运行时实例。
- IUnityPlayerLifecycleEvents 提供一种与 Unity Player 生命周期事件进行交互方式。
- 通过 settings.gradle 文件将生成的 Android Gradle 项目的 unityLibrary 模块包含在您的 Android Unity 项目中。
libs:
- 用于存放unityLibrary模块的Android Archive (.aar)和Java Archive (.jar)插件。
- 导出的Unity项目,它包含了unity-classes.jar文件。
- 这个目录不包含 Android Library Projects 自定义模块。Unity将这些作为独立的子模块复制到Gradle项目中。
- unity-classes.jar包含了Unity引擎使用的java代码。
src:
- 包含unityLibrary模块的源代码和资源。Unity将源代码和资源放在次目录中。
build.gradle:
- 描述了如何构建unityLibrary模块,并包含了构建中要包含的依赖项列表。
- unityLibrary模块依赖于Unity项目中的所有插件。
- 对应自定义Gradle的Custom Main Gradle Template文件。
proguard-unity.txt
- Unity压缩,混肴的ProGuard配置配置文件。
- Minification 启动时,将配置unity-classes.jar文件将如何进行压缩混淆。
proguard-user.txt
- 包含项目的java代码和第三方java插件的ProGuard配置。
- Minification 启动时,将配置项目的java代码和第三方java插件将如何进行压缩混淆。
- 对应自定义Gradle的Custom Proguard File文件。
build.gradle
- 整体项目的构建逻辑,负责引入所需的全部子项目Gradle并触发每个构建命令。
- 文件位于项目的根目录下,用于定义适用于项目中所有模块的依赖项。
- 会影响所有模块的配置。
- 可包含用于清理 build 目录的代码。
- 用于指定Android Gradle Plugin版本。
- 对应自定义Gradle的Custom Base Gradle Template文件。
gradle.properties
- 配置了Gradle和JVM的属性
- 配置守护进程并管理构建过程中启动JVM的方式。
- 当使用网络代理,辅助Gradle通信。
- Unity默认添加了数据流文件资源目录中的资源类型unityStreamingAssets=.unity3d,告诉Gradle不应该压缩它们。多个文件用","进行分割。
- 对应自定义Gradle的Custom Gradle Properties Template文件。
- 此文件更多信息详情
local.properties
- 用于配置本地环境属性,如Android SDK或者AndoridNDK。
settings.gradle
- 用于多项目构建或者具有子项目的项目中的定义文件。
- Unity中通常包含launcher和unityLibrary。
- 如果使用Play Asset Delivery,由于所有的资源包都是单独的模块,所以将会列出每个资源模块。
- 如果要自定这个文件,需要复制你Unity安装目录的PlaybackEngines/AndroidPlayer/Tools/GradleTemplates/settingsTemplate.gradle文件到你项目的Assets/Plugins/Android文件夹中。
自定义Gradle模板
自定义Gradle模板变量:
变量: | 描述: |
---|---|
DEPS | 项目依赖项(即,项目使用的库)的列表。 |
APIVERSION | 构建针对的 API 版本(例如 25)。 |
MINSDKVERSION | 最低 API 版本(例如,25)。 |
BUILDTOOLS | 使用的 SDK 构建工具(例如 25.0.1)。 |
TARGETSDKVERSION | 目标 API 版本(例如,25)。 |
APPLICATIONID | Android 应用程序 ID(例如,com.mycompany.myapp)。 |
MINIFY_DEBUG | 允许为调试版本缩小(true 或 false)。 |
PROGUARD_DEBUG | 在调试版本中,使用 proguard 进行缩小(true 或 false)。 |
MINIFY_RELEASE | 允许为发布版本缩小(true 或 false)。 |
PROGUARD_RELEASE | 在发布版本中,使用 proguard 进行缩小(true 或 false)。 |
USER_PROGUARD | 自定义用户 proguard 文件(例如 proguard-user.txt )。 |
SIGN | 完成 signingConfigs 部分(如果该构建已签名)。 |
SIGNCONFIG | 设置为 signingConfig signingConfig.release (如果该构建已签名)。 |
DIR_GRADLEPROJECT | Unity 创建 Gradle 项目的目录。 |
DIR_UNITYPROJECT | Unity 项目的目录。 |
ARTIFACTORYREPOSITORY | artifactory仓库配置 |
BUILD_SCRIPT_DEPS | 构建脚本的项目依赖项(即,构建脚本使用的库)的列表 |
JVM_HEAP_SIZE | 分配给JVM守护进程的内存大小 |
MINIFY_WITH_R_EIGHT | 是否启用R8代码混淆(true 或 false)。 |
STREAMING_ASSETS | 数据流文件资源列表 |
ABIFILTERS | ABI过滤器,保留列表 |
ADDITIONAL_PROPERTIES | 额外配置属性 |
VERSIONCODE | 版本号,是数值类型 |
VERSIONNAME | 版本名,是字符串类型,如1.2.1 |
PACKAGING_OPTIONS | packagingOptions配置项 |
SPLITS | splits配置项 文档 |
BUILT_APK_LOCATION | 构建apk的位置 |
SPLITS_VERSION_CODE | 生成的splits的构建版本代码 |
LAUNCHER_SOURCE_BUILD_SETUP | 启动模块的源代码构建设置项 |
APPLY_PLUGINS | 应用的插件列表项 |
REPOSITORIES | repositories 配置项 |
IL_CPP_BUILD_SETUP | IL2CPP构建设置项 |
SOURCE_BUILD_SETUP | 源代码构建设置项 |
EXTERNAL_SOURCES | 外部源代码列表项 |
Custom Main Gradle Template
此文件包含有关如何将Unity的 Android 应用程序构建为库的配置信息。
对应Gradle结构的"unityLibrary/build.gradle"文件。
- Unity会把我们的Unity内容导出为 unityLibrary库然后通过launcher依赖构建。
- 这里Build出来的并不是一个App而是一个Library模块。
输出后的文件说明:
- 依赖项配置文档dependencies配置项 : 依赖项配置文档
- Lint选项配置:Lint选项配置文档
- aaptOptions配置:Android Asset Packaging Tool配置文档
- Packaging选项:Packaging选项文档
//表述这个工程的工程类型,一般包含3种:
//App类型工程:apply plugin: 'com.android.application'
//库类型工程:apply plugin: 'com.android.library'
//Test工程类型:apply plugin: 'com.android.test'
apply plugin: 'com.android.library'
//指构建工程所依赖的所有依赖项
dependencies {
//一般来说有3种依赖类型
//对于本地模块的依赖:implementation project(':mylibrary') [mylibrary此名称必须与在您的 settings.gradle 文件中使用 include: 定义的库名称相符)]
//本地文件依赖项:implementation fileTree(dir: 'libs', include: ['*.jar'])[对项目的libs目录中 JAR 文件的依赖关系,Gradle会读取build.gradle文件的相对路径]
//也可以按如下方式指定各个文件:implementation files('libs/foo.jar', 'libs/bar.jar')
//远程文件依赖项:implementation 'com.example.android:app-magic:12.3'[实际是implementation group: 'com.example.android', name: 'app-magic', version: '12.3'的简写]
implementation fileTree(dir: 'libs', include: ['*.jar'])
}
//针对Android选项的配置块
android {
//编译依赖的SDK版本
compileSdkVersion 29
//构建工具版本
buildToolsVersion '30.0.2'
//编译选项
compileOptions {
//这里配置的是Java 语言的的源码版本
sourceCompatibility JavaVersion.VERSION_1_8
//这里配置的是Java生成的字节码版本
targetCompatibility JavaVersion.VERSION_1_8
}
//默认的配置
defaultConfig {
//最小兼容的Android平台版本,如果低于此版本将会阻止用户安装。
minSdkVersion 19
//指定我们基于哪个版本开发。
targetSdkVersion 29
ndk {
//ABI 是 Application Binary Interface 的缩写。帮助适配不同的CPU架构。
//把除了v7a以外的兼容包都过滤掉
abiFilters 'armeabi-v7a'
}
//版本码,是一个递增的整数
versionCode 1
//版本名
versionName '1.0.2'
//Proguard的配置文件,这里面有两个文件一个是unity自身的配置还有一个是我们自己配置的Proguard配置文件
consumerProguardFiles 'proguard-unity.txt', 'proguard-user.txt'
}
//Lint选项配置
lintOptions {
//当发生错误不终止构建
//更多lint配置:https://developer.android.google.cn/reference/tools/gradle-api/4.1/com/android/build/api/dsl/LintOptions?hl=cn
abortOnError false
}
//aapt全称为Android Asset Packaging Tool,为Android资源打包工具。
//https://developer.android.google.cn/reference/tools/gradle-api/4.1/com/android/build/api/dsl/AaptOptions?hl=en
aaptOptions {
//这里表示这些文件类型不会被压缩存储在APK中。
//unityStreamingAssets.tokenize 这里获取的是gradle.properties文件中unityStreamingAssets的配置。
noCompress = ['.ress', '.resource', '.obb'] + unityStreamingAssets.tokenize(', ')
//需要忽略的资源类型
ignoreAssetsPattern = "!.svn:!.git:!.ds_store:!*.scc:.*:!CVS:!thumbs.db:!picasa.ini:!*~"
}
//Packaging选项
//https://developer.android.google.cn/reference/tools/gradle-api/7.4/com/android/build/api/dsl/PackagingOptions?hl=en
packagingOptions {
//设置armeabi-v7a相关文件不会被剥离优化压缩
doNotStrip '*/armeabi-v7a/*.so'
}
}
Custom Launcher Gradle Template
此文件包含有关如何构建 Android 应用主模块的配置。
对应Gradle结构的"unityLibrary/launcher.gradle"文件。
- 这里才是作为一个App来构建的模块。
- 这个模块必须有unityLibrary模块的支持。
输出后的文件说明:
- bundle用于改进的应用程序打包方式,能大幅度减少应用体积。 bundle文件说明文档
//此模块为App应用
apply plugin: 'com.android.application'
dependencies {
//依赖于unityLibrary本地模块
implementation project(':unityLibrary')
}
android {
compileSdkVersion 29
buildToolsVersion '30.0.2'
compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
defaultConfig {
minSdkVersion 19
targetSdkVersion 29
//设置applicationId,appi要与包名一致,这里Unity会帮我们通过playersetting设置
applicationId 'com.DefaultCompany.com.unity.template.mobile2D'
ndk {
abiFilters 'armeabi-v7a'
}
versionCode 1
versionName '1.0.2'
}
aaptOptions {
noCompress = ['.ress', '.resource', '.obb'] + unityStreamingAssets.tokenize(', ')
ignoreAssetsPattern = "!.svn:!.git:!.ds_store:!*.scc:.*:!CVS:!thumbs.db:!picasa.ini:!*~"
}
lintOptions {
abortOnError false
}
//这里用于配置我们不同的构建类型
buildTypes {
debug {
//是否启用混淆,启用之后增加反编译成本
minifyEnabled false
//设置混淆文件规则
//getDefaultProguardFile('proguard-android.txt')从Android SDK tools/proguard/文件夹获取默认的 ProGuard规则文件,为我们提供的默认混淆规则文件。
//proguardFiles getDefaultProguardFile('proguard-android.txt'),'proguard-rules.pro' 可以设置自定义混淆规则文件。
//proguard-rules.pro用于添加自定义位于模块根目录。
proguardFiles getDefaultProguardFile('proguard-android.txt')
//签名配置
signingConfig signingConfigs.debug
//是否激活NDK调试
jniDebuggable true
}
release {
minifyEnabled false
proguardFiles getDefaultProguardFile('proguard-android.txt')
signingConfig signingConfigs.debug
}
}
packagingOptions {
doNotStrip '*/armeabi-v7a/*.so'
}
//改进的应用程序打包方式,能大幅度减少应用体积。
//默认情况下,构建器会自动根据CPU架构对屏幕分辨率、语言等维度将app 分拆,如果希望自由控制分拆维度,可以在此控制。
//android 5.0以下不支持bundle
bundle {
//对语言进行拆分
language {
enableSplit = false
}
//对屏幕密度进行拆分
density {
enableSplit = false
}
//对不同CPU架构进行拆分
abi {
enableSplit = true
}
}
}
可配置项
- SignConfig【签名配置】
android {
signingConfigs {
release{
storeFile file('release.keystore')
storePassword '000000'
keyAlias 'kt'
keyPassword '000000'
}
debug{
storeFile file('debug.keystore')
storePassword '000000'
keyAlias 'kt'
keyPassword '000000'
}
}
buildTypes {
debug {
//...
signingConfig signingConfigs.debug
}
release {
//...
signingConfig signingConfigs.release
}
}
1.如果使用Gradle配置签名,请取消Custom Keystore的勾选。
2.如果keystore文件使用相对路径,应从Temp\gradleOut\launcher\ 开始。
如果user.keystore在Assets同目录下的KS文件夹中应该设置如下:
storeFile file('../../../KS/release.keystore')
Custom Base Gradle Template
自定义顶层项目build.gradle配置项,允许你对所有模块进行依赖项配置和远程仓配置。
对应Gradle结构的"build.gradle"文件。
- 在这里指定所有模块的依赖项和远程仓。
- 当只有单个模块需要的依赖项应该放在对应的模块级的build.gradle文件中。
输出后的文件说明:
- JCenter和Google本质就是个Maven仓库
//在这里指定所有模块的依赖项和远程仓
//当只有单个模块需要的依赖项应该放在对应的模块级的build.gradle文件中。
allprojects {
//gradle脚本执行所需的依赖项和远程仓
buildscript {
//使用JCenter和Google作为远程仓,本质就是个Maven仓库
repositories {
google()
jcenter()
}
//配置依赖关系
dependencies {
classpath 'com.android.tools.build:gradle:3.6.0'
}
}
//当前项目所需的依赖项和远程仓
//使用JCenter和Google作为远程仓
repositories {
google()
jcenter()
//设置源类型目录位置
//这里设置我们的unityLibrary模块的libs文件夹
flatDir {
dirs "${project(':unityLibrary').projectDir}/libs"
}
}
}
//定义了一个任务,用于删除项目中build文件夹下的内容
task clean(type: Delete) {
delete rootProject.buildDir
}
Custom Gradle Properties Template
此文件包含 Gradle 构建环境的配置设置。
对应Gradle结构的"gradle.properties"文件。
- 可以对JVM(Java 虚拟机)内存配置。
- 允许 Gradle 使用多个 JVM 进行构建的属性。
- 用于选择工具进行缩小的属性。
- 用于在构建应用程序包时不压缩原生资源的属性。
输出后的文件说明:
- R8 宗旨在与现有的 ProGuard 规则配合使用。
//分配给守护进程,JVM内存的大小,分配较高的值对提高构建性能特别有用。
org.gradle.jvmargs=-Xmx4096M
//多个构建任务进行并行执行
org.gradle.parallel=true
//Android Gradle插件3.4.0或更高版本时可用,R8和Proguard 相比,R8 可以更快地缩减代码,同时改善输出大小。
android.enableR8=false
//不对.unity3d在构建应用时进行压缩
unityStreamingAssets=.unity3d
Custom Proguard File
此文件包含 Gradle 混淆的配置。
对应Gradle结构的"unityLibrary/proguard-user.txt"文件。
- Andorid 混淆处理文档
- Android Studio 3.4 或 Android Gradle 插件 3.4.0 及更高版本时,R8 是默认编译器,用于将项目的 Java 字节码转换为在 Android 平台上运行的 DEX 格式。
- 当应用通过 Java 原生接口 (JNI) 调用方法时,需要我们自定义保留代码。
- 当应用在运行时查询代码时(如使用反射),需要我们自定义保留代码。
- 可以通过生成的代码报告查看我们保留或移除的代码,需要开启R8。
- 在Unity中一般用于第三方SDK的相关api自定义保留代码。
- 这里指的是java代码不是C#代码。
//保持com.unity3d.player下的所有类
-keep class com.unity3d.player.* { *; }
//忽略警告
-ignorewarnings
IPostGenerateGradleAndroidProject【构建Gradle工程完成接口】
生成 Android Gradle 项目后,实现该接口以接收回调。继承自 UnityEditor.Build.IOrderedCallback。
OnPostGenerateGradleAndroidProject
在 Android Gradle 项目生成之后且构建开始之前,实现该函数以接收回调,执行内部构建时不会进行调用。