How to create DLLs for Unity?

I guess the first question is Why? Why create DLLs?

DLLs can be used to Tidy Up Unity Code, speed up compile time (a bit)makes it easier to redistribute code and a bunch of other Pros (but also Cons), and reduce deployment clutter and you can literally put everything you need – textures, audio, whatever – inside one file.

Okay, so now, How? Unity actually has a pretty good tutorial on How, but it lacks pictures and fails to mention some quirks.

Let’s get started:

  1. Create a New Solution in MonoDevelop, select C# > Library.
  2. Specify its Name, Location and Solution Name. 
  3. Reference Unity DLLs, by going to Project > Edit References…
  4. Select .Net Assembly, and navigate to: /Applications/Unity/Unity.app/Contents/Frameworks/Managed/UnityEngine.dll, and click Add. 
  5. UnityEngine.dll will then be included in the References folder of the Solution.
  6. Add files by right clicking on the solution and Add > Add Files…
  7. Before building, make sure that Mono Soft Debugger Support for Unity is disabled. Go to MonoDevelop-Unity > Add-in Manager… Unity > Mono Soft Debugger Support for Unity, and click Disable.

    Remember to Enable Mono Soft Debugger Support for Unity again, after building.

  8. Also, make sure Target framework is set to .NET 2.0. Right click on the solution, go to Options > Build > General, and set Target framework.
  9. Click Build > Build All or Build > Build <Solution Name>.
  10. The DLL will be saved in the bin/Debug folder of the Solution.
  11. Copy the DLL file to Assets/Plugins and reference it like any normal script.

There will always be a few Quirks:

  1. Cyclic dependencies of DLL not allowed
  2. Can only reference other DLLs
  3. DLLs cannot be edited in Unity
  4. DLL with dependencies will log error, if dependency not included in Unity Project
  5. DLL scripts cannot be in separate folders (Editor scripts need to be in Editor folder -> build separate DLLs for Editor and normal scripts, use Unity Package to sort them into proper folders)
  6. Change #if UNITY_IPHONE script to if(Application.platform == RuntimePlatform.IPhonePlayer) and change #if UNITY_ANDROID script to if(Application.platform == RuntimePlatform.Android)
  7. Editor Scripts not working properly -> needs to create a proxy script to bind to Unity (http://forum.unity3d.com/threads/editor-script-dll-and-regular-script-dll-not-adding-custominspector-scripts.107720/)
  8. DLL with reference to AndroidJavaObject fails to build for iOS

Some quirks which I can’t seem to resolve and I’m hoping someone can help me:

Advertisements

How to Create Unity Android Plugins?

Disclaimer: This is based on FastEgg’s Tutorial http://fastegggames.com/blog/2013/3/30/tutorial-admob

Sometimes we need to create Plugins to easily use external frameworks such as Ad Networks in Unity.

Android

1. Create new Android Application Project

* Application Name, Project Name should refer to the specific plugin (admob for a plugin for AdMob)

2. Add Additional Libraries

  • right click on Project and select “Properties”
  • navigate to “Java Build Path”
  • select “Libraries” tab
  • click on “Add External JARs”
  • add Unity’s “classes.jar” (located at <UnityInstallPath>\Editor\Data\PlaybackEngines\AndroidPlayer\bin\classes.jar)
  • add other JARs that are required by the plugin (such as AdMob’s jar)

Unity’s classes.jar

  • it is found in the installation folder
  • C:\Program Files\Unity\Editor\Data\PlaybackEngines\AndroidPlayer\bin on Windows
  • /Applications/Unity/PlaybackEngines/AndroidPlayer/bin on Mac

  • select “Order and Export”
  • tick all external JARs to make sure that they will be exported together with the new JAR file

3. Code the Plugin

  • create new class with the same name as the project (such as AdMob.java)
  • make sure to give it the package name of your plugins package
  • create a Constructor
  • can refer to activity using UnityPlayer.currentActivity
package com.example.AdMob
public class AdMob
{ private Activity activity; //Store the android main activity

  //Constructor
  public AdMob()
  { activity =UnityPlayer.currentActivity;
  }
}

4. Export Plugin

  • right click on project and select “Export”
  • in the Export Window, select “Java/JAR file”
  • in Jar Export Window, make sure current project is ticked
  • set export location to our Unity Project’s “Assets\Plugins\Android folder”
  • name plugin (such as AdMob.jar)
  • the wizard will pack the jar file, making it available for Unity

* sometimes plugins require additional JARs to be included our Unity Project’s “Assets\Plugins\Android folder” (such as the AdMob SDK)

5. Call Plugin From Unity

  • create a new MonoBehaviour script in Unity, and name it closely to your plugin (such as AdMobController)
#pragma strict
public class AdMobController extends MonoBehaviour
{ function Awake()
  {
  }
}
  • to activate our new plugin, we need to create a new AndroidJavaObject, and by using our package name, we can have it cast to the type we created in our JAR file:
#pragma strict
public class AdMobController extends MonoBehaviour
{ private static var jo:AndroidJavaObject;
  function Awake()
  { 
   #if UNITY_ANDROID
   jo =newAndroidJavaObject("com.example.admob.AdMob");
   #endif
  }
}

6. Modifying the Manifest

  • Unity will usually create it’s own AndroidManifest.xml file when packaging your project, but also allows for you to override the one it creates with one you define inside of the Assets/Plugins/Android folder
  • you can either create one from scratch, or copy over the default one that Unity has created for your project
  • to get the default, make a build in Unity, and let it complete and save. Then look in your projects temp/stagingarea folder. There should be a AndroidManifest.xml file generated for you. Copy that to your projects Assets/Plugins/Android folder, and edit it using MonoDevelop
  • modify the Manifest file to include things required by your plugin (such as requires Internet): <uses-permission android:name=”android.permission.INTERNET” />
  • save changes

EDIT:

If you set your Android Application as Library, it’s Android Manifest will automatically be merged with any existing ones in your Unity project.

To set your project as Library, go to the project’s Properties > Android and tick Is Library, and click Apply.

It will add a project.properties file to your project, make sure to include that in your jar file.

Screen Shot 2015-01-09 at 4.57.34 PM

7. Testing

  • some Android related things (such as Ads) doesn’t show up in the Unity Editor, so you’d need to build and run on an Android device to test
  • you can use adb logcat in Terminal to debug while running on Android device
  • Ctrl+C stops logcat

That’s it!

Plugins love ❤

  • Firefox Personas (where I got my lovely Cath Kidston theme)
  • Fire.fm (for streaming music from Last.fm)
  • Facebook (for well checking Facebook notifications, changing statuses, etc.)
  • Tumblr (for well, duh)
  • WebMail Notifier (for checking multiple email accounts)
  • Echofon (for Twitter, which I basically use like chat)
  • ReminderFox (for reminders)