unity3D 插件plugins

齐阳

2023-12-01

Unity中的插件机制

JUL 25TH, 2015 12:01 PM

1. 介绍

Unity有两类插件: Managed plugins和Native plugin。

Managed plugins是托管式.NET代码，因为只有.NET代码，也就是说不能使用.NET库不支持的功能。

Native plugins是平台专门的原生代码库，可以用来访问操作系统调用或者第三方的库。

在Unity5之前，通过插件存放的目录来区分支持的目标平台；然而Unity5可以把插件放在任何目录，通过Plugin Inspector设置相关属性就可以了，但为了兼容以前的版本，Unity5也会支持插件存放的目录，进行默认的插件设置。

规则如下:

文件夹	默认插件设置
Assets/**/Editor	只兼容Editor
Assets/**/Editor/(x86 or x86_64 or x64)	只兼容Editor，如果子文件夹存在，用于匹配目标CPU
Assets/Plugins/x86_64(or x64)	x64兼容
Assets/Plugins/x86	x86兼容
Assets/Plugins/Android/(x86 or armeabi or armeabi-v7a)	只跟Android兼容，如果子文件夹存在，用于匹配目标CPU
Assets/Plugins/iOS	只跟iOS兼容

2. 托管式插件

通常情况下，我们直接使用脚本实现相关功能，然后由Unity编译成目标可执行文件。但有时我们不能不在外部把脚本编译成DLL，然后放在Unity中使用。这个DLL就是这里所说的托管式插件，兼容.NET二进制。

2.1 创建一个DLL

如果制作的DLL依赖Unity本身的DLL(UnityEngine.dll和UnityEditor.dll),还需要使编译器能访问它们。 Mac系统，它们存放在/Applications/Unity/Unity.app/Contents/Frameworks/Managed/, Windows下，存放在C:\Program Files\Unity\Editor\Data\Managed

如果使用Mono C#编译器mcs编译，命令大体如下:

mcs -r:/Applications/Unity/Unity.app/Contents/Frameworks/Managed/UnityEngine.dll -target:library ClassesForDLL.cs

2.2 使用DLL

如同其它资源一样，直接拖放到Unity项目里。继承于MonoBehaviour的类可以直接拖到GameObject上，像普通脚本一样；非MonoBehaviour类可以在其它脚本中被直接使用。

2.3 为DLL设置调试功能

在MonoDevelop, 把生成的/bin/Debug/DLLTst.dll.mdb拷贝到Assets/Plugins文件夹下。在Visual Studio, 执行Program Files\Unity\Editor\Data\Mono\lib\mono\2.0\pdb2mdb.exe,按照提示传入\bin\Debug\DLLTest.pdb，然后把生成的mdb文件放到Assets/Plugins文件夹下。

接下来，确保Mono软调试器开启，Mac下是在MonoDevelop的MonoDevelop-Unity > Add-in Manager > Installed tab > Unity > select Mono Soft Debugger Support for Unity > Enable

然后就可以单步跟进DLL脚本里。

3. 原生插件

原生插件一般采用C,C++,Objective-C等等编写，Unity允许游戏代码来访问这些原生插件中的函数，允许Unity和一些中间件库或者已有的C/C++进行整合和。

3.1 实例

一个简单函数:

float FooPluginFunction () { return 5.0F; }

为了能再Unity中可以访问这简单函数，需要这么用:

using UnityEngine;
using System.Runtime.InteropServices;

class SomeScript : MonoBehaviour {

   #if UNITY_IPHONE || UNITY_XBOX360

   // On iOS and Xbox 360 plugins are statically linked into
   // the executable, so we have to use __Internal as the
   // library name.
   [DllImport ("__Internal")]

   #else

   // Other platforms load plugins dynamically, so pass the name
   // of the plugin's dynamic library.
   [DllImport ("PluginName")]

   #endif

   private static extern float FooPluginFunction ();

   void Awake () {
      // Calls the FooPluginFunction inside the plugin
      // And prints 5 to the console
      print (FooPluginFunction ());
   }
}

需要主要原生函数的name mangling问题，如果FooPluginFunction是用C++的代码，那么需要这样声明:

extern "C" {
    float FooPluginFunction ();
}

4. Android平台

4.1 C/C++插件

做法跟上面的3.1类似，只是在编译库的时候需要依赖Android NDK

4.2 Java插件

可以把预编译的Android库项目扔到Assets/Plugins/Android文件夹。预编译的意思是所有.java文件必须已被编译成java存放在bin/或者libs文件夹下，当项目编译的时候这些文件夹下的AndroidManifest.xml会被自动合并到主manifest文件。

Unity期望Java插件使用JDK v1.6编译。如果使用v1.7，需要在命令参数中包含-source 1.6 -target 1.6

4.3 原生代码访问Java插件

一旦你生成了.jar文件，你需要把它拷贝到Assets/Plugins/Android文件夹下。然后通过JNI访问。

为了能再原生端访问java代码，你需要先访问Java虚拟机，代码如下:

jint JNI_OnLoad(JavaVM* vm, void* reserved) {
  JNIEnv* jni_env = 0;
  vm->AttachCurrentThread(&jni_env, 0);
  return JNI_VERSION_1_6;
}

然后可以创建新的对象实例:

jobject createJavaObject(JNIEnv* jni_env) {
  jclass cls_JavaClass = jni_env->FindClass("com/your/java/Class");         // find class definition
  jmethodID mid_JavaClass = jni_env->GetMethodID (cls_JavaClass, "<init>", "()V");      // find constructor method
  jobject obj_JavaClass = jni_env->NewObject(cls_JavaClass, mid_JavaClass);     // create object instance
  return jni_env->NewGlobalRef(obj_JavaClass);                      // return object with a global reference
}

4.4 C#访问Java插件

Unity提供了API类AndroidJNIHelper和AndroidJNI简化JNI的访问，也提供了AndroidJavaObject、AndroidJavaClass和java.lang.Object、java.lang.class对应。

可以方便地:

调用方法
访问类成员变量
设置类成员变量

Call分成两类:

调用没有返回值(即返回void)的方法
调用有返回值的

例子如下:

//The comments describe what you would need to do if you were using raw JNI
AndroidJavaObject jo = new AndroidJavaObject("java.lang.String", "some_string"); 
// jni.FindClass("java.lang.String"); 
// jni.GetMethodID(classID, "<init>", "(Ljava/lang/String;)V"); 
// jni.NewStringUTF("some_string"); 
// jni.NewObject(classID, methodID, javaString); 
int hash = jo.Call<int>("hashCode"); 
// jni.GetMethodID(classID, "hashCode", "()I"); 
// jni.CallIntMethod(objectID, methodID);

不用额外插件，通过UnityPlayer获得当前应用的cache目录:

 AndroidJavaClass jc = new AndroidJavaClass("com.unity3d.player.UnityPlayer"); 
 // jni.FindClass("com.unity3d.player.UnityPlayer"); 
 AndroidJavaObject jo = jc.GetStatic<AndroidJavaObject>("currentActivity"); 
 // jni.GetStaticFieldID(classID, "Ljava/lang/Object;"); 
 // jni.GetStaticObjectField(classID, fieldID); 
 // jni.FindClass("java.lang.Object"); 

 Debug.Log(jo.Call<AndroidJavaObject>("getCacheDir").Call<string>("getCanonicalPath")); 
 // jni.GetMethodID(classID, "getCacheDir", "()Ljava/io/File;"); // or any baseclass thereof! 
 // jni.CallObjectMethod(objectID, methodID); 
 // jni.FindClass("java.io.File"); 
 // jni.GetMethodID(classID, "getCanonicalPath", "()Ljava/lang/String;"); 
 // jni.CallObjectMethod(objectID, methodID); 
 // jni.GetStringUTFChars(javaString);

上面代码只是举例说明，现在可以直接通过Application.temporaryCachePath和Application.persistentDataPath获得cache目录。

下面的例子演示使用UnitySendMessage从Java层把数据传递到C#:

using UnityEngine; 
public class NewBehaviourScript : MonoBehaviour { 

    void Start () { 
        AndroidJNIHelper.debug = true; 
        using (AndroidJavaClass jc = new AndroidJavaClass("com.unity3d.player.UnityPlayer")) { 
            jc.CallStatic("UnitySendMessage", "Main Camera", "JavaMessage", "whoowhoo"); 
        } 
    } 

    void JavaMessage(string message) { 
        Debug.Log("message from java: " + message); 
    }
}

4.5 扩展UnityPlayerActivity

可以创建一个新的Activity继承于UnityPlayerActivity(UnityPlayerActivity.java放在Mac的/Applications/Unity/Unity.app/Contents/PlaybackEngines/AndroidPlayer/com/unity3d/player或者Windows的C:\Program Files\Unity\Editor\Data\PlaybackEngines\AndroidPlayer\src\com\unity3d\player)。

首先，把classes.jar(Mac的/Applications/Unity/PlaybackEngines/AndroidPlayer/bin或者Windows下的C:\Program Files\Unity\Editor\Data)添加到classpath，用于编译新的Activity。生成.class打包成.jar文件，放到Assets/Plugins/Android文件夹；创建新的AndroidManifest.xml，指定启动的Activity,并把它放到Assets/Plugins/Android。

新的Acitivy，如下:

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) {

    // call UnityPlayerActivity.onCreate()
    super.onCreate(savedInstanceState);

    // print debug message to logcat
    Log.d("OverrideActivity", "onCreate called!");
  }

  public void onBackPressed()
  {
    // instead of calling UnityPlayerActivity.onBackPressed() we just ignore the back button event
    // 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=".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>

Gingerbread之后引入了UnityPlayerNativeActivity,相比于UnityPlayerActivity，它的输入延迟效果好。UnityPlayerNativeActivity的touch/motion事件都在原生代码中处理的，一般情况下Java视图不会接收到此类事件。Unity的重定向机制允许事件发往DalvikVM，如果使用这种机制，需要修改manifest:

<?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=".OverrideExampleNative"
             android:label="@string/app_name"
             android:configChanges="fontScale|keyboard|keyboardHidden|locale|mnc|mcc|navigation|orientation|screenLayout|screenSize|smallestScreenSize|uiMode|touchscreen">
  <meta-data android:name="android.app.lib_name" android:value="unity" />
  <meta-data android:name="unityplayer.ForwardNativeEventsToDalvik" android:value="true" />
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.LAUNCHER" />
        </intent-filter>
    </activity>
  </application>
</manifest>