DLLs für Unity: Wie man eine .NET Klassenbibliothek für die Unity Engine als DLL mit Visual Studio erstellt und in Unity verwendet (Teil 1)

Möchte man Code in vielen Unity Projekten oder Paketen wiederverwenden, kann es sinnvoll sein, diesen in Form einer Klassenbibliothek als DLL zur Verfügung zu stellen. Wir zeigen wie.

Einleitung

Oft kommt man in einem Projekt an den Punkt, an dem man genau den Code benötigt, den man doch im letzten Projekt schon mühsam geschrieben hat. So auch beim Entwickeln eines Spiels mit Unity.

In dieser Schritt-für-Schritt-Anleitung zeigen wir, wie man Code als DLL in eine Klassenbibliothek auslagert und dann in Unity-Projekten verwenden kann.

Klassenbibliothek erstellen

Projekt in Visual Studio erstellen

Zuerst öffnet man Visual Studio und erstellt ein neues Projekt.

Name ist der Namespace.
Speicherort (Location) ist der Überordner des Projekts.
Projektmappenname (Solution name) ist der Name der Projektmappe und des Ordners dafür.

Unity Referenzen hinzufügen

Als nächstes müssen wir der Projektmappe die Verweise zu den Unity DLLs hinzufügen, welche wir in unserer Klassenbibliothek benötigen und die in folgendem Ordner zu finden sind:

In unserem Beispiel sieht der Pfad so aus:

Für unser Beispiel benötigen wir die UnityEngine.dll.

Dazu öffnen wir im Projektmappen-Explorer (Solution explorer) für Verweise (References) das Kontextmenü und wählen Verweis hinzufügen.

Im Verweis-Manager klicken wir auf Durchsuchen, um die DLLs auszuwählen.

Im Dateiauswahl-Fenster navigieren wir zu unserer lokalen Unity-Installation. Die DLLs findet man im Unterordner Editor/Data/Managed.
Weitere DLLs, z.B. UnityEngine.UI findet man im Unterordner UnityEngine.

Wir wollen in unserem Beispiel einige Unity-Klassen verwenden, die sich in der UnityEngine.dll befinden, z.B. Component, MonoBehaviour und weitere.
Wir wählen die DLL und drücken auf Hinzufügen.

Die DLL ist nun als Verweis (Reference) in unser Projekt eingebunden.

Klasse erstellen

Als Beispiel möchten wir ein Singleton-Klasse für Unity Components erstellen, welche wir in allen Projekten wiederverwenden wollen.

Dazu benennen wir die von Visual Studio automatisch erstellte Klassen-Datei um oder erstellen eine neue mit dem Namen „PersistentSingleton.cs“. Dort benötigen wir die zu vor als Verweis angelegte „UnityEngine“, weil wir die Unity-Klassen MonoBehavier, Component und weitere benötigen.

public class PersistentSingleton<T> : MonoBehaviour	where T : Component
{
	protected static T _instance;
	protected bool _enabled;

	/// 
<summary>
	/// Singleton design pattern
	/// </summary>

	/// <value>The instance.</value>
	public static T Instance
	{
		get
		{
			if (_instance == null)
			{
				_instance = FindObjectOfType<T> ();
				if (_instance == null)
				{
					GameObject obj = new GameObject ();
					_instance = obj.AddComponent<T> ();
				}
			}
			return _instance;
		}
	}

	/// 
<summary>
	/// On awake, we check if there's already a copy of the object in the scene. If there's one, we destroy it.
	/// </summary>

	protected virtual void Awake ()
	{
		if (!Application.isPlaying)
		{
			return;
		}

		if (_instance == null)
		{
			//If I am the first instance, make me the Singleton
			_instance = this as T;
			DontDestroyOnLoad (transform.gameObject);
			_enabled = true;
		}
		else
		{
			//If a Singleton already exists and you find
			//another reference in scene, destroy it!
			if(this != _instance)
			{
				Destroy(this.gameObject);
			}
		}
	}
}

DLL bauen

Jetzt können wir die DLL bauen. Dazu erstellen wir einfach die Projektmappe.

Die kompilierte DLL findet man im Projekt-Ordner unter bin/Debug bzw. bin/Release.

DLL in Unity Projekt verwenden

Für dieses Beispiel erstellen wir ein neues Unity-Projekt. Die folgenden Schritte lassen sich aber natürlich auch in vorhandenen Projekten durchführen.

DLL importieren

Wir können die DLL einfach in Unity importieren, in dem wir sie im Projektfenster in den Ordner Assets hineinziehen. Oder in einen Unterordner.

Die Klassen der Bibliothek stehen jetzt in unserem Unity-Projekt zur Verfügung und können im Code verwendet werden.
Als nächstes wollen wir die PersitentSingleton-Klasse in unserem Projekt verwenden, damit GameObjects über Szenen hinweg erhalten bleiben.

Verwenden im Code

Dazu erstellen wir im Ordner Scripts eine neue Komponenten-Klasse mit Namen GameManager.cs.

Mittels using können wir dort über den Namespace unsere Bibliothek einbinden und die PersistentSingleton-Klasse verwenden.
Von dieser leiten wir unsere Component-Klasse ab.

Um später zu sehen, ob die Komponente über Szenen hinweg erhalten bleibt und ihre Daten hält (also nur ein mal existiert), fügen wir ein Feld testSetting hinzu, dem wir später im Inspektor Werte geben.

Component verwenden

Jetzt können wir die Komponente verwenden. Dazu öffnen wir die automatisch erstellte SampleScene oder erstellen eine neue Szenen.

In der Szene erstellen wir zunächst ein UI-Panel, damit wir optisch etwas sehen und einen Button darstellen können, der zur nächsten Szene wechselt.
Dann erstellen wir ein leeres GameObject, das wir GameManager nennen.

Diesem GameObject fügen wir im Inspektor als Komponente unsere GameManager-Klasse hinzu und befüllen den Wert für unser Feld.

Wenn wir jetzt das Spiel im Editor starten, müssten wir im Hierarchie-Fenster erkennen können, dass unser GameManager GameObject unter DontDestroyOnLoad gelistet ist.

Unsere Komponente wird also als Singleton behandelt. Genauer prüfen werden wir das später.
Zunächst wollen wir unser Projekt als Stand-Alone-Anwendung bauen, um zu sehen, ob unsere DLL nicht nur im Editor funktioniert.

Projekt bauen

Um das Projekt zu bauen klicken wir im Menü auf File -> Build Settings. Dort fügen wir unsere SampleScene zu den Scenes In Build hinzu und drücken auf Build.
Dort geben wir einen Ordner an und los geht es.

Nach erfolgreichem Build öffnet der Explorer den Build-Ordner. Alles hat geklappt.

In den Unterordnern finden wir auch die DLL unserer eingebundenen Bibliothek.

Offensichtlich hat alles funktioniert. Ganz einfach.
Jetzt können wir die EXE ausführen, um zu schauen, ob unser „Spiel“ fehlerfrei startet.

Tut es!

Ausblick

Im nächsten Teil der Anleitung schauen wir, ob unser Singleton die Daten auch über den Szenenwechsel behält und wir schauen, wie man Projekte, die die DLL eingebunden haben als Unity-Packages exportiert und in einer weiteren Anwendung zusammen verwendet.

Zum nächsten Artikel: DLLs für Unity: Wie man ein GameObject als Singleton erstellt und über den Szenenwechsel behält (Teil 2)

Bis dahin hoffe ich, diese erstbeste Anleitung war hilfreich.

Quellen:

• Unity Documentation: Managed plug-ins