Legacy Documentation: Version 4.3
Unity Manual>Advanced>Using Mono DLLs in a Unity Project
Previous
Next

Using Mono DLLs in a Unity Project

Usually, scripts are kept in a project as source files and compiled by Unity whenever the source changes. However, it is also possible to compile a script to a dynamically linked library (DLL) using an external compiler. The resulting DLL can then be added to the project and the classes it contains can be attached to objects just like normal scripts.

It is generally much easier to work with scripts than DLLs in Unity. However, you may have access to third party Mono code which is supplied in the form of a DLL. When developing your own code, you may be able to use compilers not supported by Unity (F#, for example) by compiling the code to a DLL and adding it to your Unity project. Also, you may want to supply Unity code without the source (for an Asset Store product, say) and a DLL is an easy way to do this.

Creating a DLL

To create a DLL, you will first need a suitable compiler. Not all compilers that produce .NET code are guaranteed to work with Unity, so it may be wise to test the compiler with some available code before doing significant work with it. If the DLL contains no code that depends on the Unity API then you can simply compile it to a DLL using the appropriate compiler options. If you do want to use the Unity API then you will need to make Unity's own DLLs available to the compiler. On a Mac, these are contained in the application bundle (you can see the internal structure of the bundle by using the Show Package Contents command from the contextual menu; right click or ctrl-click the Unity application):-

The path to the Unity DLLs will typically be 

	/Applications/Unity/Unity.app/Contents/Frameworks/Managed/

...and the two DLLs are called UnityEngine.dll and UnityEditor.dll.

On Windows, the DLLs can be found in the folders that accompany the Unity application. The path will typically be 

	C:\Program Files\Unity\Editor\Data\Managed

...while the names of the DLLs are the same as for Mac OS.

The exact options for compiling the DLL will vary depending on the compiler used. As an example, the command line for the Mono C# compiler, mcs, might look like this on Mac OS:- 

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

Here, the -r option specifies a path to a library to be included in the build, in this case the UnityEngine library. The -target option specifies which type of build is required; the word "library" is used to select a DLL build. Finally, the name of the source file to compile is ClassesForDLL.cs (it is assumed that this file is in the current working folder, but you could specify the file using a full path if necessary). Assuming all goes well, the resulting DLL file will appear shortly in the same folder as the source file.

Using the DLL

Once compiled, the DLL file can simply be dragged into the Unity project like any other asset. The DLL asset has a foldout triangle which can be used to reveal the separate classes inside the library. Classes that derive from MonoBehaviour can be dragged onto Game Objects like ordinary scripts. Non-MonoBehaviour classes can be used directly from other scripts in the usual way.


A folded-out DLL with the classes visible

Step by Step Guide for MonoDevelop and Visual Studio

In this section you will learn how to build and integrate a simple DLL example with MonoDevelop and Visual Studio, which are the most popular IDEs to generate .NET libraries. This section will also explain how to prepare the debugging session for the DLL.

Writing and Building the DLL

  1. Open MonoDevelop or Visual Studio.
  2. Create a new project from the application's menu:
    • MonoDevelop:
      1. Open the menu File > New > Solution
      2. Choose C# > Library
    • Visual Studio:
      1. Open the menu File > New > Project
      2. Choose Visual C# > Class Library
  3. Fill out the information for the new library:
    • Name is the namespace, for this example use "DLLTest".
    • Location is the parent folder of the project.
    • Solution name is the folder of the project.
  4. Add references to the Unity API:
    • MonoDevelop:
      1. In the Solution browser open the contextual menu of References (right-click) and choose Edit references
      2. Choose the option .Net Assembly tab > File System > select file
    • Visual Studio:
      1. In the Solution Explorer open the contextual menu of References (right-click) and choose Add Reference
      2. Choose the option Browse > Browse > select file
  5. Select the required Unity API file:
    • MacOS:
      • <Applications>/Unity.app/Contents/Frameworks/Managed/UnityEngine.dll
    • Windows:
      • <Program Files>\Unity\Editor\Data\Managed\UnityEngine.dll
  6. For this example, in the Solution browser rename the class into "MyUtilities" and replace its code with this:

    C#

     using System;	
 using UnityEngine;

 namespace DLLTest {

	public class MyUtilities {

		public int c;

		public void AddValues(int a, int b) {
			c = a + b;	
		}

		public static int GenerateRandom(int min, int max) {
			System.Random rand = new System.Random();
			return rand.Next(min, max);
		}
	}
 }
  7. Finally build the project to generate the DLL file and its debug symbols.

Using the newly created DLL in Unity

  1. Open Unity and create a new project.
  2. Copy the built file <project folder>/bin/Debug/DLLTest.dll into Assets or a subfolder (e.g. Plugins)
  3. For this example, create a C# script called "Test" in Assets, and replace its contents with the following code:

    C#

     using UnityEngine;
 using System.Collections;
 using DLLTest;

 void Start () {
	MyUtilities utils = new MyUtilities();
	utils.AddValues(2, 3);
	print("2 + 3 = " + utils.c);
 }

 void Update () {
	print(MyUtilities.GenerateRandom(0, 100));
 }
  4. Finally assign the script to an object in the scene (ie. Main Camera) and run the scene. You will see the output in the Console window.

Setup the debugging session for the DLL

  1. Prepare the debug symbols of the DLL:
    • MonoDevelop:
      • Copy built file <project folder>/bin/Debug/DLLTest.dll.mdb into Assets (ie. Assets/Plugins/)
    • Visual Studio:
      1. Execute <Program Files>\Unity\Editor\Data\Mono\lib\mono\2.0\pdb2mdb.exe in the command prompt, pass <project folder>\bin\Debug\DLLTest.pdb as parameter
      2. Copy converted file <project folder>\bin\Debug\DLLTest.dll.mdb into Assets (ie. Assets\Plugins\)
  2. Open "Test" script in MonoDevelop, and make sure to enable the debugger for Unity from the Tools menu (Windows) or MonoDevelop-Unity menu (MacOS):
    • Add-in Manager > Installed tab > Unity > select Mono Soft Debugger Support for Unity > Enable

See the Debugger page for further information.

Page last updated: 2013-07-08

Previous
Next