Managed plug-ins

Managed plug-ins are managed .NET assemblies that you create with tools like Visual Studio. They contain only .NET code which means that they can’t access any features that .NET libraries do not support. However, the standard .NET tools that Unity uses to compile scriptsA piece of code that allows you to create your own Components, trigger game events, modify Component properties over time and respond to user input in any way you like. More info
See in Glossary can access the managed code. Therefore, there isn’t a lot of difference in usage between managed plug-inA set of code created outside of Unity that creates functionality in Unity. There are two kinds of plug-ins you can use in Unity: Managed plug-ins (managed .NET assemblies created with tools like Visual Studio) and Native plug-ins (platform-specific native code libraries). More info
See in Glossary code and Unity script code, except that plug-ins are compiled outside of Unity and so the source might not be available.

Usually, Unity keeps scripts in a Project as source files and compiles them whenever the source changes. However, you can use an external compiler to compile a script to a dynamically linked library (DLL). You can then add the .dll file to the Project and attach the classes it contains to GameObjectsThe fundamental object in Unity scenes, which can represent characters, props, scenery, cameras, waypoints, and more. A GameObject’s functionality is defined by the Components attached to it. More info
See in Glossary just like normal scripts. A compiled DLL is known as a managed plug-inA managed .NET assembly that is created with tools like Visual Studio for use in Unity. More info
See in Glossary in Unity.

It’s generally much easier to work with scripts than DLLs in Unity. However, you might want to use compilers in your code that Unity doesn’t support, or add third party Mono code in a .dll file, or you might want to supply Unity code without the source. Creating and adding a .dll file to your Unity Project is the easiest way to get around these limitations.

Creating a managed plug-in

To create a managed plug-in, you need to create a DLL, which you need a suitable compiler for. Not all compilers that produce .NET code are guaranteed to work with Unity, so you should 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 use the appropriate compiler options to compile it to a .dll file.

If you do want to use the Unity API then you need to make Unity’s own DLLs available to the compiler. On macOS, the DLLs are contained in the application bundle. To see them, find the Unity.app file on your computer (Applications/Unity/Hub/Editor/[Version Number]/Unity.app) and then right click on Unity.app and select Show Package Contents.

On macOS the path to the Unity DLLs are:

/Applications/Unity/Unity.app/Contents/Managed/UnityEngine

On Windows the path to the Unity DLLs are:

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

The UnityEngine folder contains the .dll files for a number of modules that you can reference to get to the specific namespace you require. Additionally, some namepsaces require a reference to a compiled library from a Unity Project (for instance, UnityEngine.UI), which is located in the project folder’s directory:

~\Library\ScriptAssemblies

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

__mcs__The Mono C# compiler file format. [More info](PlatformDependentCompilation.html)<span class="tooltipGlossaryLink">See in [Glossary](Glossary.html#mcs)</span> -r:/Applications/Unity/Unity.app/Contents/Managed/UnityEngine/UnityEngine.UIModule.dll -target:library ClassesForDLL.cs 

In this example,, the -r option specifies a path to a library to include in the build; in this case the UnityEngine.UIModule library. The -target option specifies which type of build is required; the word “library” is signifies a DLL build. Finally, the name of the source file to compile is ClassesForDLL.cs. The compiler assumes that this file is in the current working folder, but you can use a full path to specify the file if necessary. The resulting .dll file appears in the same folder as the source file.

Using the managed plug-in

Once you’ve compiled the DLL, you can drag the .dll file into the Unity Project like any other Asset. The managed plug-in has a foldout triangle which you can use to reveal the separate classes inside the library. You can drag classes that derive from MonoBehaviour onto Game Objects like ordinary scripts. You can use non-MonoBehaviour classes directly from other scripts in the usual way.

Step by step guide for Visual Studio

This section explains how to build and integrate a simple DLL example with Visual Studio, and also how to prepare a debugging session for the DLL.

Setting Up the Project

Open Visual Studio and create a new project. Select File > New > Project and then choose Visual C# > Class Library.

Complete the following information for the new library:

• Name is the namespace (for this example use DLLTest as the name).
• Location is the parent folder of the project.
• Solution name is the folder of the project.

Next, add references to the Unity DLLs. In Visual Studio, open the contextual menu for References in the Solution Explorer and select Add Reference. Then, select Browse > Select File.

At this stage, select the required .dll file, located in the UnityEngine folder.

Code

For this example, rename the class to MyUtilities in the Solution browser and replace its code with the following:

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);
        }
    }
}

With the code in place, build the project to generate the DLL file along with its debug symbols.

Using the DLL in Unity

Create a new Project in Unity and copy the built file <project folder>/bin/Debug/DLLTest.dll into the Assets folder. Then, create a C# script called Test in Assets, and replace its contents with the following code:

using UnityEngine;
using System.Collections;
using DLLTest;

public class Test : MonoBehaviour {

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

Attach this script to a GameObject in the SceneA Scene contains the environments and menus of your game. Think of each unique Scene file as a unique level. In each Scene, you place your environments, obstacles, and decorations, essentially designing and building your game in pieces. More info
See in Glossary and press Play, and Unity displays the output of the code from the DLL in the Console windowA Unity Editor window that shows errors, warnings and other messages generated by Unity, or your own scripts. More info
See in Glossary.

Setting up a debugging session for the DLL

To set up a debugging session you need to prepare the debug symbols for the DLL. In Visual Studio, execute in the command prompt and pass <project folder>\bin\Debug\DLLTest.pdb as a parameter:

Program Files\Unity\Editor\Data\Mono\lib\mono\2.0\pdb2mdb.exe

Copy the converted file <project folder>\bin\Debug\DLLTest.dll.mdb into Assets/Plugins.

With this setup completed, you can debug code that uses the DLL in Unity in the usual way. See the Scripting Tools section for further information about debugging.

Compiling ‘unsafe’ C# code

To enable support for compiling unsafe C# code go to Edit > Project SettingsA broad collection of settings which allow you to configure how Physics, Audio, Networking, Graphics, Input and many other areas of your Project behave. More info
See in Glossary > Player. Expand the Other Settings panel and enable the Allow Unsafe Code checkbox.