Unity与Android交互及SO库打包实战指南

技术文档

本文还有配套的精品资源，点击获取

简介：Unity是一个多平台游戏开发引擎，通过使用Java Native Interface（JNI），可以与Android设备的特定功能进行交互。本实例将详细说明Unity与Android的交互原理，指导如何打包SO库，并在Unity端进行集成。在进行交叉编译生成SO库后，开发者需要确保在Unity中正确加载和使用这些库，以及注意相关的兼容性和调试信息。实例附带了完整的APK文件和示例项目，供学习参考。
unity与android交互实例（打包so）

1. Unity游戏引擎与Android交互原理

Unity游戏引擎的强大之处在于其跨平台的兼容性和灵活性，而与Android平台的交互则进一步拓宽了其应用领域。通过Java Native Interface（JNI），Unity可以调用Android平台上的本地代码，实现更深层次的功能拓展和性能优化。本章，我们将深入探讨Unity与Android平台之间的交互机制，从它们之间的通信方式开始，逐步剖析数据交换的原理，为接下来章节中对JNI的细节探讨打下基础。通过本章内容，读者将能够理解Unity与Android交互的基本框架和实现原理，为后续章节中详细的开发和优化流程做好铺垫。

2. Java Native Interface（JNI）基础

2.1 JNI的定义与作用

2.1.1 JNI是什么？

Java Native Interface（JNI）是Java平台的一部分，提供了一种机制让Java代码与其他语言编写的代码进行交互，尤其是C和C++代码。通过JNI，Java应用程序可以调用本地应用程序接口（API）库中的函数，或者被这些库调用。JNI的使用让开发者可以在Java环境中利用已有的本地库，或者编写性能敏感部分的代码以本地代码形式运行，从而在保持跨平台优势的同时提升性能。

2.1.2 JNI在Unity与Android交互中的角色

在Unity开发的游戏或应用中，当涉及到Android特有的功能或者性能优化时，可能会用到JNI。Unity通过JNI与Android平台的本地代码进行交互，使得Unity应用能够利用Android平台提供的所有功能。例如，Unity可以通过JNI调用Android的Camera API，访问硬件传感器，或者使用Android提供的特定算法进行图形处理等。

2.2 JNI的数据类型与调用规范

2.2.1 Java与C/C++数据类型的映射关系

JNI定义了一套完整的类型映射机制，让Java和C/C++之间可以传递数据。基本数据类型（如int, float等）和引用类型（如Java对象，数组等）都有明确的映射规则。例如，Java中的int类型在C/C++中对应的是 jint 类型，而Java的boolean类型对应的是 jboolean 。这些映射关系让在Java和本地代码间传递数据变得简单明了。

// 示例：Java中int类型与JNI中jint类型的映射jint a = 10; // Java中的int变量a映射为C/C++中的jint类型

2.2.2 JNI函数命名规则与调用约定

JNI函数遵循特定的命名规则，这使得Java虚拟机（JVM）能够识别并正确地调用相应的本地方法。每个本地方法在C/C++中的实现都需要遵循特定的命名约定，这通常包含方法的返回类型、类名、方法名以及方法签名。

// 示例：本地方法命名规范JNIEXPORT void JNICALL Java_ClassName_MethodName(JNIEnv *env, jobject obj)

2.3 JNI的使用场景与优势

2.3.1 何时应该使用JNI

使用JNI通常是因为性能优化的需求，或者需要调用Java平台未提供的本地库的功能。比较常见的情景包括使用特定算法的加速实现，访问系统级功能（如传感器、网络接口等），以及利用已有的本地代码库。然而，应当谨慎使用JNI，因为引入本地代码会增加系统的复杂性，且可能导致平台依赖性增加。

2.3.2 JNI相较于其他方式的优势

与其他桥接技术相比，JNI的优势在于它提供了完整的类型映射机制和直接的内存访问能力。它允许Java应用直接调用本地代码，实现更高效的数据交互和更复杂的系统级操作。同时，JNI没有运行时开销，对于性能要求极高的应用场景来说，这一点尤为重要。

在选择使用JNI之前，开发者需要权衡其带来的复杂性和潜在的平台依赖性。对于性能要求不是特别高的场景，可能会优先考虑其他桥接技术，如Java Native Access（JNA）或Java的RMI（远程方法调用），这些技术在提供跨语言交互的同时，可能会带来更高的开发便利性和更低的平台依赖性。

3. SO库的打包流程和路径配置

3.1 SO库的打包流程详解

3.1.1 SO库是什么及重要性

SO库，也称为共享对象库，是一种在Linux系统中广泛使用的动态链接库。在Android开发中，SO库用于存放二进制代码，可以被多个应用程序共享使用，以减少内存占用并提升性能。SO库的扩展名为 .so ，它们是在Android NDK环境下通过C或C++代码编译而成。

在Unity与Android交互的过程中，SO库扮演着至关重要的角色。当Unity游戏需要调用Android平台的原生API时，或者需要利用特定的Android硬件特性，比如蓝牙、摄像头等，这时候通常需要借助SO库来实现。因为Unity本身是用C#编写的，而很多Android特有的功能是通过Java实现的。通过JNI桥接C#与Java，并且通过SO库将Java代码编译成可以直接被Unity调用的本地方法。

3.1.2 SO库的打包步骤与注意事项

打包SO库的步骤可以概括为以下几个主要阶段：

准备源代码 ：首先需要准备好所有需要编译为SO库的C/C++源代码文件。
编写Android.mk ：这是在Android NDK中用于描述源代码文件和编译选项的Makefile。
配置项目 ：在Android Studio或命令行中配置NDK路径、指定编译选项等。
编译构建 ：执行NDK编译命令，系统将根据Android.mk文件中的指令编译源代码成 .so 文件。
验证与测试 ：编译完成后，需要验证生成的SO库文件是否符合预期，并在Android设备上进行测试。

在打包SO库时需要注意以下事项：

确保源代码无编译错误，并且兼容Android平台。
使用的NDK版本需与目标Android设备的系统版本兼容。
针对不同CPU架构生成对应的SO库文件，如armeabi-v7a, arm64-v8a等，以提升应用的兼容性和性能。
在打包过程中，务必清晰记录每一步的日志，以便于后续的问题排查和优化。

接下来，将详细讨论SO库的路径配置与环境设置。

3.2 SO库的路径配置与环境设置

3.2.1 在Android项目中配置SO库路径

在Android项目中，SO库文件通常放置在 libs 目录下。根据不同的CPU架构，这个目录下可能包含多个子目录，例如 armeabi-v7a , arm64-v8a , x86 等，以便放置对应架构的SO库文件。

要配置SO库的路径，需在Android的 build.gradle 文件中声明所需的库。例如，如果有一个名为 libhello.so 的SO库文件，其路径配置代码如下：

android { ... sourceSets { main { jniLibs.srcDirs = [\'libs\'] } } ...}

这里 jniLibs.srcDirs 指定了JNI库的存放路径。

3.2.2 Unity项目中SO库的引用与配置

在Unity项目中，SO库文件需要被拷贝到Unity的Assets文件夹下的Plugins目录中，这样Unity在构建时才会把SO库文件打包到最终的APK中。

例如，有一个 armeabi-v7a 和 arm64-v8a 两个架构的SO库文件，需要分别放置在：

Assets/Plugins/armeabi-v7a/libhello.soAssets/Plugins/arm64-v8a/libhello.so

Unity支持多种平台，若要确保SO库只在Android平台上被加载，可以在SO库文件名前加上 android 前缀，如下所示：

Assets/Plugins/android-armeabi-v7a/libhello.so

然后，在Unity的C#脚本中通过 DllImport 属性来声明外部方法，例如：

[DllImport(\"libhello\")]private static extern int nativeFunction();

注意，这里的”libhello”是SO库的名称，不包含前缀和后缀。

以上就是SO库的打包流程详解和路径配置的详细步骤。配置好这些后，你就可以在Unity和Android交互开发中顺利使用SO库了。接下来，第四章将详细介绍Unity端集成SO库的步骤。

4. Unity端集成SO库的步骤

4.1 Unity项目设置与环境搭建

4.1.1 创建Unity新项目和基本设置

在开始集成SO库到Unity之前，需要有一个已经搭建好的Unity环境。首先，打开Unity Hub，点击“新建”，选择合适的Unity版本并创建一个新项目。项目创建后，接下来需要设置项目的基础配置，如分辨率设置、图形API选择等。通常对于Android平台，你可能需要选择使用Vulkan或OpenGL ES作为图形API。

4.1.2 Unity C#与C++代码的接口说明

Unity项目中，C#脚本是主要的编程语言。为了调用C++编写的SO库，需要使用 DllImport 属性来导入SO库中定义的C++函数。例如，如果你有一个C++函数 nativeFunction 在名为 library.so 的SO库中，可以在C#中这样声明：

[DllImport(\"library\", EntryPoint=\"nativeFunction\")]private static extern void NativeFunction();

这里的 library 是库的名称，不包含前缀 lib 和后缀 .so 。 EntryPoint 参数指向具体的C++函数名。之后就可以在C#脚本中调用 NativeFunction ，并且这个函数会调用对应SO库中的原生函数。

4.2 Unity中集成SO库的流程

4.2.1 从零开始集成SO库到Unity

将SO库集成到Unity项目中通常分为几个步骤。首先是将SO库文件放置到Unity项目的Assets文件夹下。由于Android平台对SO库架构有要求，你需要确保库文件是对应平台的架构编译的。接着，通过编写一个管理器脚本来动态加载这个库文件，示例代码如下：

using System;using System.Runtime.InteropServices;class LibraryLoader{ [DllImport(\"libdl.so\", EntryPoint = \"dlopen\")] private static extern IntPtr Dlopen(string path, int mode); [DllImport(\"libdl.so\", EntryPoint = \"dlsym\")] private static extern IntPtr Dlsym(IntPtr handle, string symbol); [DllImport(\"libdl.so\", EntryPoint = \"dlclose\")] private static extern int Dlclose(IntPtr handle); private const int RTLD_LAZY = 0x1; static LibraryLoader() { IntPtr handle = Dlopen(\"path/to/library.so\", RTLD_LAZY); if (handle == IntPtr.Zero) { throw new Exception($\"Unable to load library: {Marshal.GetLastWin32Error()}\"); } } public static T GetFunction(string functionName) { IntPtr symbolHandle = Dlsym(IntPtr.Zero, functionName); if (symbolHandle == IntPtr.Zero) { throw new Exception($\"Unable to load symbol \'{functionName}\': {Marshal.GetLastWin32Error()}\"); } return Marshal.GetDelegateForFunctionPointer(symbolHandle); }}

以上代码展示了如何加载SO库并获取其中的函数。其中 Dlopen 用于打开库， Dlsym 用于获取函数指针， Dlclose 用于关闭库。函数 GetFunction 是一个通用方法，它接受函数名，并返回对应函数的委托类型。

4.2.2 集成过程中的问题排查与解决方案

在集成过程中，可能会遇到各种问题，例如找不到库文件、符号解析失败等。以下是一些常见问题的排查和解决方案：

找不到库文件 ：确保SO库文件放置在正确的路径下，如果是在Assets之外的路径使用，需要使用 Application.streamingAssetsPath 等路径获取正确的文件路径。
符号解析失败 ：检查SO库是否与Unity项目的CPU架构兼容，或者函数的导出名称是否正确，使用 nm 工具检查符号。
运行时错误 ：运行时遇到的错误可能是由于库文件中出现的异常引起的，此时需要使用Android的日志工具（logcat）来查看具体的异常信息。

一旦上述步骤正确完成，你就可以在Unity项目中成功调用SO库中的本地函数，从而为游戏或应用提供更底层的功能支持。

5. Android Studio项目的创建和NDK配置

5.1 创建Android Studio项目的基本步骤

5.1.1 初始化项目与项目结构理解

当我们开始一个新的项目时，第一步通常是创建一个项目框架。在Android开发中，Android Studio提供了非常直观的方式来初始化项目，帮助开发者理解项目结构，这是理解和配置NDK集成的基础。

创建项目时，你可以选择一个模板。对于包含本地代码的项目，建议选择”Empty Activity”，因为这样可以保持项目的简洁性。打开Android Studio，点击”Start a new Android Studio project”，然后按照向导进行操作。在模板选择界面，选择”Empty Activity”，然后点击”Next”。

接下来，填写你的应用名称、保存位置、语言（Java/Kotlin）和最低支持的API等级。填完这些信息后，点击”Finish”。Android Studio会创建一个具有基本项目结构的新项目。

在项目创建完成后，我们通常会看到以下几个主要目录：

app/ ：包含应用程序代码和资源的目录。
libs/ ：存放第三方库的目录。
src/ ：源代码目录，其中 main/ 包含了Java、Kotlin源代码和资源文件。

理解这些目录是进行Android开发的关键。NDK集成后，我们还需要熟悉包含C/C++源代码的 cpp/ 目录和 CMakeLists.txt 文件。 CMakeLists.txt 是CMake构建脚本文件，用于定义和管理原生项目构建。

5.1.2 Android项目的Gradle配置与构建类型

Gradle是一个强大的构建自动化工具，而在Android项目中，它负责管理项目的依赖关系、插件配置、构建配置等。理解Gradle配置是配置NDK的关键步骤。

在Android项目中，每个模块都有自己的 build.gradle 文件。打开 app 目录下的 build.gradle 文件，你会看到如下重要部分：

android { ... defaultConfig { ... externalNativeBuild { cmake { cppFlags \"\" } } } buildTypes { release { minifyEnabled false proguardFiles getDefaultProguardFile(\'proguard-android-optimize.txt\'), \'proguard-rules.pro\' } } externalNativeBuild { cmake { path \"CMakeLists.txt\" } }}

上面的配置展示了如何定义构建类型以及如何配置原生构建。其中 externalNativeBuild 部分允许你指定CMake或ndk-build用于编译C/C++代码。 cppFlags 字段可以添加额外的C++编译器标志， path 属性指向了项目的CMake构建脚本。

Android Studio允许你通过点击 Build 菜单中的 Clean Project 和 Rebuild Project 来清理和重新构建项目。这些步骤对于确保编译环境的整洁和构建过程的正确性非常有帮助。

5.2 配置NDK与集成C++代码

5.2.1 NDK的安装与项目集成流程

为了在Android Studio项目中集成C++代码，你需要安装Android NDK。NDK（Native Development Kit）是一个工具包，它允许开发者使用C和C++编写性能密集型部分，并将其编译为.so文件，以便在Android项目中调用。

要安装NDK，按照以下步骤操作：

打开Android Studio，进入 File > Settings > Appearance & Behavior > System Settings > Android SDK 。
在SDK Tools标签页中，勾选NDK（Side by side），然后点击Apply。
等待下载和安装完成。

安装完成后，你需要在项目级别集成NDK。将NDK集成到项目中的步骤如下：

在项目的 build.gradle 文件中，指定NDK版本：

android { ... defaultConfig { ... externalNativeBuild { cmake { cppFlags \"\" } } } buildTypes { release { minifyEnabled false proguardFiles getDefaultProguardFile(\'proguard-android-optimize.txt\'), \'proguard-rules.pro\' } } externalNativeBuild { cmake { path \"CMakeLists.txt\" } }}

在项目根目录下创建 CMakeLists.txt 文件，用于定义C++源代码的编译方式：

cmake_minimum_required(VERSION 3.4.1)add_library( native-lib SHARED native-lib.cpp)find_library( log-lib log)target_link_libraries( native-lib ${log-lib})

确保你的C++代码文件与 CMakeLists.txt 中声明的一致，例如 native-lib.cpp 。
通过Gradle同步项目，检查是否有任何错误。然后，你可以构建项目并生成APK文件。

5.2.2 C++代码编写、编译与集成进Android项目

现在，我们将介绍如何编写C++代码，并将其集成到Android项目中。首先，你需要对C++有基础了解，以及对如何使用CMake进行原生代码构建有基本认识。

假设你已经有了一个C++函数，你想在你的Android应用中调用它。你可以创建一个 .cpp 文件，并在其中定义你的函数。例如：

#include extern \"C\"JNIEXPORT jstring JNICALLJava_com_example_myapp_MainActivity_stringFromJNI(JNIEnv *env, jobject /* this */) { std::string hello = \"Hello from C++\"; return env->NewStringUTF(hello.c_str());}

在上面的代码中，我们定义了一个名为 stringFromJNI 的原生方法，它返回一个字符串。注意 extern \"C\" ，这是为了避免C++的名称修饰。

接下来，你需要在 CMakeLists.txt 中添加这个新的源文件：

add_library( native-lib SHARED native-lib.cpp)find_library( log-lib log)target_link_libraries( native-lib ${log-lib})

确保包含了你的新 .cpp 文件，这样CMake才能找到它并将其编译进你的动态链接库（ .so 文件）。

集成C++代码的最后一步是通过JNI接口在Java或Kotlin代码中调用这个原生方法。在 MainActivity 类中，你可以这样调用它：

package com.example.myapp;import androidx.appcompat.app.AppCompatActivity;import android.os.Bundle;import android.widget.TextView;public class MainActivity extends AppCompatActivity { // 加载包含 native 方法的库 static { System.loadLibrary(\"native-lib\"); } @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); // 调用 native 方法并显示返回的字符串 TextView tv = findViewById(R.id.sample_text); tv.setText(stringFromJNI()); }}

在这段Java代码中， System.loadLibrary(\"native-lib\") 负责加载编译好的 .so 文件，而 stringFromJNI 是你在C++中定义的函数名称。

通过以上步骤，你就成功地在Android项目中集成和调用了C++代码。接下来，你可以利用这种方式集成更复杂的C++库，或者编写更多高性能的本地代码。

6. CPU架构与SO库的匹配问题

在移动设备上，CPU架构的多样性是开发中必须考虑的一个因素。不同的设备可能搭载不同的CPU架构，如ARMv7, ARMv8(AArch64), x86等。SO库，也就是共享对象库，需要与目标设备的CPU架构相匹配，才能正确加载和执行。本章将讨论CPU架构的基础知识，SO库的多架构生成与匹配，以及调试和错误信息查看的设置。

6.1 CPU架构基础与分类

6.1.1 理解不同CPU架构类型

在移动领域，最常见的CPU架构包括ARM和x86。ARM架构以其低功耗高效率在移动设备上广受欢迎，而x86架构则多见于个人电脑。ARM架构又分为多个版本，如ARMv7和ARMv8（也称为AArch64），其中后者支持64位计算，是近年来较新的发展。

6.1.2 CPU架构与SO库的关系

为了确保SO库能够在不同架构的设备上运行，开发者需要生成适用于这些架构的SO库。这意味着需要为每个目标架构编译相应的本地代码，并打包到最终的应用程序中。如果不进行适当处理，应用程序可能无法在具有不同CPU架构的设备上运行。

6.2 多架构SO库的生成与匹配

6.2.1 生成适用于多架构的SO库

生成多架构SO库通常需要在编译时指定目标架构。在使用NDK编译C/C++代码时，可以通过 -march 参数来指定架构。例如，生成ARMv7和ARMv8架构的SO库，可以在构建脚本中使用如下命令：

ndk-build APP_ABI=\"arm64-v8a armeabi-v7a\"

以上命令会生成对应于ARMv8架构（64位）和ARMv7架构（32位）的SO库。

6.2.2 配置应用以支持不同CPU架构

在Unity项目中配置多架构SO库涉及到将这些库放置到正确的目录中。例如，你可以按照如下目录结构来组织SO库：

Plugins └── armeabi-v7a └── libnative-lib.so └── arm64-v8a └── libnative-lib.so

每个目录代表一种架构，库文件必须与其架构相对应。Unity将根据运行应用的设备自动选择合适的SO库。

6.3 调试和错误信息的查看设置

6.3.1 设置调试环境与工具链

为了调试Unity与Android交互中的问题，需要设置合适的调试环境。在Android Studio中打开项目，可以通过”Run”菜单选择”Edit Configurations”来配置调试器。此外，选择合适的NDK版本和构建工具版本对于调试也至关重要，因为它们可能会影响库的兼容性和性能。

6.3.2 查看和解析错误信息

在遇到错误时，正确的错误信息至关重要。在Unity的控制台或者Android Studio的Logcat中，开发者可以查看到运行时的错误信息。为了解析这些信息，需要对Java, JNI以及底层C/C++代码有一定的了解。查看错误堆栈跟踪和相关的日志信息，可以帮助开发者定位问题的根源。

对于开发者来说，掌握CPU架构的基础知识，生成正确的多架构SO库，并正确配置调试环境，将为成功的跨平台应用开发打下坚实的基础。