Dokumentation

Nach mehrfacher Nachfrage habe ich die Spendenseite eingerichtet: Jetzt hier spenden und die Entwicklung der ModAPI unterstützen

Inhaltsangabe

  • [relativeurl='index.php/documentation/#neededKnowledge']Benötigte Kenntnisse[/relativeurl]
  • [relativeurl='index.php/documentation/#prerequisites']Vorbereitungen[/relativeurl]
  • [relativeurl='index.php/documentation/#createMod']Einen neuen Mod erstellen[/relativeurl]
    • [relativeurl='index.php/documentation/#modConfiguration']Modkonfiguration[/relativeurl]
    • [relativeurl='index.php/documentation/#writeMod']Mod schreiben[/relativeurl]
      • [relativeurl='index.php/documentation/#injectCode']Neuen Code in bestehende Methoden hinzufügen[/relativeurl]
      • [relativeurl='index.php/documentation/#chaining']Chaining[/relativeurl]
      • [relativeurl='index.php/documentation/#addMethods']Hinzufügen von Methoden, Feldern und Klassen[/relativeurl]
    • [relativeurl='index.php/documentation/#modTools']Mod Tools[/relativeurl]
      • [relativeurl='index.php/documentation/#console']Konsole[/relativeurl]
      • [relativeurl='index.php/documentation/#logging']Logging[/relativeurl]
      • [relativeurl='index.php/documentation/#input']Eingaben[/relativeurl]
  • [relativeurl='index.php/documentation/#createModFile'].Mod Datei erstellen[/relativeurl]
  • [relativeurl='index.php/documentation/#errorReporting']Fehler berichten[/relativeurl]

Benötigte Kenntnisse

  • Fortgeschrittene Kenntnisse in C#
  • Grundkenntnisse in Unity3D
  • Grundkenntnisse in einem beliebigen C# Reflector

Vorbereitungen

screen_createmodlib_de.png
Um mit dem Modding zu beginnen, sollte der Quellcode des Spiels betrachtet und studiert werden. Hierzu eigenen sich verschiedene Werkzeuge:
  • Kostenlos:
    • ILDASM: Dieses Tool wird beim Microsoft.NET Framework mitgeliefert und ermöglicht es, den MSIL-Code jeder Managed-Code Assembly zu betrachten.
    • IL-Spy: Dieses Tool ermöglicht die bequeme Betrachtung des MSIL-Codes einer Managed-Code Assembly. Das Programm kann hier heruntergeladen werden.
    • Jetbrains dotPeek: Dieses Tool ermöglicht es, den Quellcode einer Managed-Code Assembly zu dekompilieren. Das Programm kann hier heruntergeladen werden.
  • Kostenpflichtig:
    • .NET Reflector: Dieses Tool ermöglicht es, den Quellcode einer Managed-Code Assembly zu dekompilieren: Das Programm kann hier gekauft werden.

Nachdem der Code studiert wurde, kann das eigentliche Modding losgehen. Zuerst sollte sicher gegangen werden, dass die aktuelle ModLib auch wirklich aktuell ist. Hierfür drückst Du einfach auf den "Modlib erstellen" Knopf in der ModAPI.

Sollte es zu einem Fehler kommen, beachte das Kapitel "Fehler berichten".

Einen neuen Mod erstellen

Am einfachsten ist es, die Funktion "Modprojekt erstellen" in der GUI zu verwenden. Das Projekt wird im Unterordner "ModProjects" erstellt. Hier drunter befindet sich ein Ordner mit dem Namen, der beim "Modprojekt erstellen" angegeben wurde.

Das Projekt verfügt bereits über alle nötigen Verweise und liefert bereits eine leere ModInfo.xml mit.

Modkonfiguration

Die Konfiguration für die Mod muss sich in den Resourcen des Projekts befinden. Wenn das Projekt über die Funktion "Modprojekt erstellen" angelegt wurde, ist dies bereits richtig eingestellt.

Das Rootelement der XML Datei benötigt das Attribut "ID". Hier wird die ID des Mods angegeben.

XML-Quellcode

  1. <mod id="YourModID">

Die Version wird im Tag "Version" angegeben. Die Version darf maximal aus 4 durch einen Punkt getrennte Werte bestehen. Jede Zahl darf einen Wert von 0-99 haben. Außerdem kann an jede Zahl ein Buchstabe von a-z angehangen werden.

XML-Quellcode

  1. <version>0.0.2a.1</version>

Der angezeigte Name wird im Tag "name" angegeben. Innerhalb des Tag "name" können verschiedene Sprachen angegeben werden. Die Ländercodes richten sich nach <a href="http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes">ISO 639-1</a>.

XML-Quellcode

  1. <name>
  2. <EN>English modname</EN>
  3. <DE>Deutscher Modname</DE>
  4. </name>

Die Beschreibung kommt in den Tag "description". Die Unterelemente werden wie beim Tag "name" gestaltet.

XML-Quellcode

  1. <description>
  2. <EN><![CDATA[English description]]></EN>
  3. <DE><![CDATA[Deutsche Beschreibung]]></DE>
  4. </description>

Der Tag "Button" fügt eine neue zuweisbare Taste hinzu. Im Attribut standard befindet sich die Standardtaste. Innerhalb des Tags befindet sich der Tag ID und Name. Der Wert in ID, ist der Wert, mit dem auf die Taste zugegriffen werden kann. Im Tag Name wird der angezeigte Name wie beim Modnamen mit Ländercodes angegeben.

XML-Quellcode

  1. <button standard="M">
  2. <id>Map</id>
  3. <name>
  4. <EN><![CDATA[Open map]]></EN>
  5. <DE><![CDATA[Karte öffnen]]></DE>
  6. </name>
  7. </button>

Die vollständige Konfiguration könnte folgendermaßen aussehen:

XML-Quellcode

  1. <mod id="YourModID">
  2. <version>0.0.2a.1</version>
  3. <name>
  4. <EN>English modname</EN>
  5. <DE>Deutscher Modname</DE>
  6. </name>
  7. <description>
  8. <EN><![CDATA[English description]]></EN>
  9. <DE><![CDATA[Deutsche Beschreibung]]></DE>
  10. </description>
  11. <button standard="M">
  12. <id>Map</id>
  13. <name>
  14. <EN><![CDATA[Open map]]></EN>
  15. <DE><![CDATA[Karte öffnen]]></DE>
  16. </name>
  17. </button>
  18. </mod>
Alles anzeigen

Mod schreiben

Um einen Mod zu schreiben, ist es empfehlenswert einen .NET Reflector zu verwenden. Ein kostenloses Tool dafür ist z.B. ILSpy.
Alternativ kann auch der dekompilierte Code mit dem kostenlosen Tool JetBrains dotPeek angezeigt werden.

Neuen Code in bestehende Methoden hinzufügen

Um neuen Code in bereits vorhandenen Methoden hinzuzufügen, reicht es, wenn die eigene Klasse von der Klasse erbt, in der man die Methode ersetzen möchte. Als Beispiel nehmen wir die TheForestAtmosphere Klasse.

Quellcode

  1. class MyModClass : TheForestAtmosphere
  2. {
  3. }

Um nun die Methode zu erweitern, überschreiben wir die originale Methode. Dies ist auch mit privaten Methoden möglich, da die ModLib alle Methoden, die private sind, auf protected umgeschrieben hat:

Quellcode

  1. override protected void Update()
  2. {
  3. //Code
  4. }

Dieser Ansatz überschreibt die Methode gänzlich. Damit der originale Code weiterhin aufgerufen wird, bedarf es einen Aufruf der base.Update() Methode. Dadurch entsteht eine Chain. Die vollständige Klasse könnte so aussehen:

Quellcode

  1. class MyModClass : TheForestAtmosphere
  2. {
  3. override protected void Update()
  4. {
  5. //Code vor dem Originalcode
  6. base.Update();
  7. //Code nach dem Originalcode
  8. }
  9. }

Chaining

Da es vorkommen kann, dass mehrere Mods die gleiche Methode überschreiben möchten, benutzt die ModAPI das Konzept des "Chaining". Das heißt, dass jede Überschreibung einer Mod nacheinander ausgeführt wird.

In der fertigen Assembly könnte der Code folgendermaßen aussehen:

Quellcode

  1. public class TheForestAtmosphere : MonoBehaviour
  2. {
  3. private void Update()
  4. {
  5. try
  6. {
  7. // Code von Mod 1
  8. }
  9. catch (Exception e)
  10. {
  11. this.Update_1();
  12. }
  13. }
  14. private void Update_1()
  15. {
  16. try
  17. {
  18. // Code von Mod 2
  19. }
  20. catch (Exception e)
  21. {
  22. this.Update_Original();
  23. }
  24. }
  25. private void Update_Original()
  26. {
  27. // Originaler Code
  28. }
  29. }
Alles anzeigen

Um die Priorität der eigenen Methode zu ändern, gibt es das Attribut "ModAPI.Priority". Desto höher der Wert, desto früher wird die eigene Methode aufgerufen:

Quellcode

  1. class MyModClass : TheForestAtmosphere
  2. {
  3. [ModAPI.Priority(100)]
  4. override protected void Update()
  5. {
  6. // Code
  7. }
  8. }

Hinzufügen von Methoden, Feldern und Klassen

Neben der Möglichkeit der Überschreibung einzelner Methoden, können auch neue Felder, Methoden und Klassen hinzugefügt werden. Zu beachten gibt es hierbei, dass die Felder in der jeweiligen Klasse noch nicht existieren dürfen. Das überschreiben von Feldern oder ihrer Standardwerter ist derzeit nicht möglich. Eine Alternativlösung hierfür, kann die Methode Start() darstellen, die von Unity beim Erstellen des MonoBehaviour Objekts aufgerufen wird.

Mod Tools

Die ModAPI wird mit einigen Tools ausgeliefert, die das Entwickeln und Debuggen vereinfachen sollen.

Konsole

Die Konsole kann im Spiel über das Drücken der Zirkumflex-Taste (Taste über "Tab") geöffnet werden. Mods können Befehle für die Konsole anmelden:

Quellcode

  1. ModAPI.Console.RegisterCommand("doSomething", callbackMethod);

Die Callback Methode muss folgendermaßen aussehen:

Quellcode

  1. public void callbackMethod(string params)
  2. {
  3. // Code
  4. }

Seit der 0.1.7 werden auch komplexe Kommandos unterstützt.

Parametisierte Kommandos können folgendermaßen hinzugefügt werden:

Quellcode

  1. ModAPI.Console.RegisterCommand("doSomething", callbackMethod, new ModAPI.ParameterType[]{
  2. ModAPI.ParameterType.TEXT,
  3. ModAPI.ParameterType.OBJECT,
  4. ModAPI.ParameterType.ENTITY,
  5. ModAPI.ParameterType.OBJECT | ModAPI.ParameterType.ITEM
  6. });

Die Callback Methode sieht hier jedoch etwas anders aus:

Quellcode

  1. public void callbackMethod(string[] param)
  2. {
  3. // Code
  4. }

Es ist auch möglich selbst definierte Parameter Typen zu erstellen. Derzeit werden nur String Listen oder Arrays unterstützt:

Quellcode

  1. ModAPI.Console.RegisterCommand("doSomething", callbackMethod, new ModAPI.CustomParameter[]{
  2. new ModAPI.CustomParameter(ModAPI.ParameterType.TEXT),
  3. new ModAPI.CustomParameter(new string[]
  4. {
  5. "option1", "option2", "option3"
  6. })
  7. });

Die Callback Methode sieht so aus, wie sie bei parametisierten Kommandos aussieht.

Logging

Jede Mod erhält eine eigene Logdatei. Die Logdateien befinden sich unter "Mods/Logs/". Um etwas zu loggen, reicht folgender Aufruf:

Quellcode

  1. ModAPI.Log.Write("Log Message");

Eingaben

Die in der Konfiguration angegebenen Buttons, können über folgende Methoden abgefragt werden:

Quellcode

  1. if (ModAPI.Input.GetButton("ButtonID"))
  2. {
  3. }
  4. if (ModAPI.Input.GetButtonDown("ButtonID"))
  5. {
  6. }
  7. if (ModAPI.Input.GetButtonUp("ButtonID"))
  8. {
  9. }

.Mod Datei erstellen

Um eine .mod Datei zu erstellen, muss das Projekt kompiliert werden. Anschließend kann einfach und bequem eine .mod Datei über die GUI erstellt werden. Hierfür müssen Sie die Schaltfläche "Mod erstellen" betätigen. Anschließend kann die Mod aus einer Liste ausgewählt werden und anschließend erstellt werden. Nach wenigen Sekunden taucht die neue Mod in der Modliste des Modloaders auf und kann anschließend getestet werden.

Die Mod Datei kann im Ordner "Mods" gefunden werden. Um die Mod weiterzugeben, reicht das übermitteln der entsprechenden .mod-Datei. (Namensformat: ID_Version.mod)

Fehler berichten

Um einen Fehler zu berichten, schaue bitte im Forum vorbei.