Difference between revisions of "How to create mod for unity game"

From Nexus Mods Wiki
Jump to: navigation, search
m
 
(3 intermediate revisions by one other user not shown)
Line 1: Line 1:
 +
  
 
== Introduction ==
 
== Introduction ==
 +
 +
 
 +
<syntaxhighlight lang="Python">
 +
Check highlight plugin
 +
</syntaxhighlight>
  
 
To begin with, these mods are more focused on creating scripts than content. But still make a new game object or texture, you can. Unity works on the csharp language, so creating a mod may seem hardcore, but you do not need to be a super programmer, it is enough to know the basic knowledge of programming. It will be even more difficult to dig into the game code in search of the necessary game functions.
 
To begin with, these mods are more focused on creating scripts than content. But still make a new game object or texture, you can. Unity works on the csharp language, so creating a mod may seem hardcore, but you do not need to be a super programmer, it is enough to know the basic knowledge of programming. It will be even more difficult to dig into the game code in search of the necessary game functions.
Line 7: Line 13:
  
 
#Download and install Microsoft Visual Studio Community 2017 with C#  
 
#Download and install Microsoft Visual Studio Community 2017 with C#  
#Open the project creation and select 'Class Library (NET Framework)'. Change name to 'TestMod'. Open the project properties and target platform should be 'Net Framework 3.5' or 'Net Framework 4.0' for the newer Unity version.  
+
#Open the project creation and select 'Class Library (NET Framework)'. Change name to 'TestMod'. Open the project properties and target platform should be 'Net Framework 3.5' or 'Net Framework 4.0' for the newer Unity version.&nbsp;If&nbsp;game is made for .net&nbsp;3.5, UMM must be installed as Doorstop method.  
 
#You need to add references to game files 'Assembly-CSharp.dll', 'Assembly-CSharp-firstpass.dll', 'UnityEngine.dll', 'UnityEngine.UI.dll' which are located in 'Managed' folder and to UMM files 'UnityModManager.dll', '0Harmony.dll' which are located in 'Managed/UnityModManager' folder. If the unity version is 2017 or higher you need to add additional files 'UnityEngine.CoreModule.dll', 'UnityEngine.IMGUIModule.dll'. Now we can use the game and unity mod manager functions. ''Note: [https://www.nexusmods.com/site/mods/21/ Unity Mod Manager] should already be installed.''  
 
#You need to add references to game files 'Assembly-CSharp.dll', 'Assembly-CSharp-firstpass.dll', 'UnityEngine.dll', 'UnityEngine.UI.dll' which are located in 'Managed' folder and to UMM files 'UnityModManager.dll', '0Harmony.dll' which are located in 'Managed/UnityModManager' folder. If the unity version is 2017 or higher you need to add additional files 'UnityEngine.CoreModule.dll', 'UnityEngine.IMGUIModule.dll'. Now we can use the game and unity mod manager functions. ''Note: [https://www.nexusmods.com/site/mods/21/ Unity Mod Manager] should already be installed.''  
  
Line 39: Line 45:
  
 
The mod manager supports several variants of the Entry functions. Use only one.&nbsp;Let's call it <u>Load</u>.&nbsp;The name must be the same as in the ''EntryMethod''.
 
The mod manager supports several variants of the Entry functions. Use only one.&nbsp;Let's call it <u>Load</u>.&nbsp;The name must be the same as in the ''EntryMethod''.
<syntaxhighlight lang="C#">using UnityEngine;
+
<pre>using UnityEngine;
 
using UnityModManagerNet;
 
using UnityModManagerNet;
  
Line 46: Line 52:
 
     static class Main
 
     static class Main
 
     {
 
     {
         // Simply call.
+
         // Simply call. Compiled without dependencies on UnityModManagerNet
 
         static void Load()  
 
         static void Load()  
 
         {
 
         {
Line 65: Line 71:
 
         }
 
         }
 
     }
 
     }
}</syntaxhighlight>
+
}</pre>
  
 
----
 
----
  
You can add a function that will control on/off mode. This function is optional. If the function is missing, the mod may turn on, but it will turn off only after restarting the game.
+
You can add a function that will control on/off mode similar to&nbsp;hot-plug. This function is optional. If the function is missing, the mod may turn on, but it will turn off only after restarting the game.
 
<pre>using UnityEngine;
 
<pre>using UnityEngine;
 
using UnityModManagerNet;
 
using UnityModManagerNet;
Line 87: Line 93:
 
         // Called when the mod is turned to on/off.
 
         // Called when the mod is turned to on/off.
 
         // With this function you control an operation of the mod and inform users whether it is enabled or not.
 
         // With this function you control an operation of the mod and inform users whether it is enabled or not.
        static bool OnToggle(UnityModManager.ModEntry modEntry, bool value /* active or inactive */)
+
&nbsp; &nbsp; &nbsp; &nbsp; static bool OnToggle(UnityModManager.ModEntry modEntry, bool value /* active or inactive */)
        {
+
&nbsp; &nbsp; &nbsp; &nbsp; {
            SomeAction();
+
&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;if (value)
            enabled = value;
+
&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;{
            return true; // If true, the mod will switch the state. If not, the state will not change.
+
&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;Run(); // Perform all necessary steps to start mod.
        }
+
&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;}
 +
&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;else
 +
&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;{
 +
&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;Stop(); // Perform all necessary steps to stop mod.
 +
&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;}
 +
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;&nbsp;
 +
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; enabled = value;
 +
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; return true; // If true, the mod will switch the state. If not, the state will not change.
 +
&nbsp; &nbsp; &nbsp; &nbsp; }
 
     }
 
     }
 
}</pre>
 
}</pre>
Line 98: Line 112:
 
== Details of ModEntry ==
 
== Details of ModEntry ==
  
''Info ''- Contains all fields from the 'Info.json' file.<br/> ''Path ''- The path to the mod folder e.g. '\Steam\steamapps\common\YourGame\Mods\TestMod\'.<br/> ''Active ''- Active or inactive.<br/> ''Logger ''- Writes logs to the 'Log.txt' file.<br/> ''OnToggle ''- The presence of this function will let the mod manager know that the mod can be safely disabled during the game.<br/> ''OnGUI ''- Called to draw UI.<br/> ''OnSaveGUI ''- Called while saving.<br/> ''OnUpdate ''- Called by MonoBehaviour.Update.<br/> ''OnLateUpdate ''- Called by MonoBehaviour.LateUpdate.<br/> ''OnFixedUpdate ''- Called by MonoBehaviour.FixedUpdate.
+
''Info ''- Contains all fields from the 'Info.json' file.<br/> ''Path ''- The path to the mod folder e.g. '\Steam\steamapps\common\YourGame\Mods\TestMod\'.<br/> ''Active ''- Active or inactive.<br/> ''Logger ''- Writes logs to the 'Log.txt' file.<br/> ''OnToggle ''- The presence of this function will let the mod manager know that the mod can be safely disabled during the game.<br/> ''OnGUI ''- Called to draw UI.<br/> ''OnSaveGUI ''- Called while saving.<br/> ''OnUpdate ''- Called by MonoBehaviour.Update.<br/> ''OnLateUpdate ''- Called by MonoBehaviour.LateUpdate.<br/> ''OnFixedUpdate ''- Called by MonoBehaviour.FixedUpdate.<br/> ''OnShowGUI&nbsp;''- Called when opening mod GUI.<br/> ''OnHideGUI&nbsp;''- Called when closing mod GUI.
  
 
== Examples ==
 
== Examples ==
Line 176: Line 190:
 
     {
 
     {
 
         public static bool enabled;
 
         public static bool enabled;
 +
        public static ModEntry mod;
  
 
         static bool Load(UnityModManager.ModEntry modEntry)
 
         static bool Load(UnityModManager.ModEntry modEntry)
 
         {
 
         {
            modEntry.OnToggle = OnToggle;
 
 
 
             var harmony = HarmonyInstance.Create(modEntry.Info.Id);
 
             var harmony = HarmonyInstance.Create(modEntry.Info.Id);
 
             harmony.PatchAll(Assembly.GetExecutingAssembly());
 
             harmony.PatchAll(Assembly.GetExecutingAssembly());
 +
 +
            mod = modEntry;
 +
            modEntry.OnToggle = OnToggle;
  
 
             return true;
 
             return true;
Line 204: Line 220:
 
                 return;
 
                 return;
  
             __result = "New Level Name";
+
             try
 +
            {
 +
                __result = "New Level Name";
 +
            }
 +
            catch(Exception e)
 +
            {
 +
                mod.Logger.Error(e.ToString());
 +
            }
 
         }
 
         }
 
     }
 
     }
 
}</pre>
 
}</pre>
  
Now the function 'Application.loadedLevelName' will always return "New Level Name" string. Similarly, we can change any value in the game.
+
Now the function 'Application.loadedLevelName' will always return "New Level Name" string. Similarly, we can change any value in the game.<br/> Be sure to wrap the patch with a Try-Catch block so as not to interrupt an original function in case of errors. Errors can occur if a game code changes after updates.
  
 
== Finally ==
 
== Finally ==

Latest revision as of 06:15, 22 August 2019


Introduction

 

Check highlight plugin

To begin with, these mods are more focused on creating scripts than content. But still make a new game object or texture, you can. Unity works on the csharp language, so creating a mod may seem hardcore, but you do not need to be a super programmer, it is enough to know the basic knowledge of programming. It will be even more difficult to dig into the game code in search of the necessary game functions.

Project creation

  1. Download and install Microsoft Visual Studio Community 2017 with C#
  2. Open the project creation and select 'Class Library (NET Framework)'. Change name to 'TestMod'. Open the project properties and target platform should be 'Net Framework 3.5' or 'Net Framework 4.0' for the newer Unity version. If game is made for .net 3.5, UMM must be installed as Doorstop method.
  3. You need to add references to game files 'Assembly-CSharp.dll', 'Assembly-CSharp-firstpass.dll', 'UnityEngine.dll', 'UnityEngine.UI.dll' which are located in 'Managed' folder and to UMM files 'UnityModManager.dll', '0Harmony.dll' which are located in 'Managed/UnityModManager' folder. If the unity version is 2017 or higher you need to add additional files 'UnityEngine.CoreModule.dll', 'UnityEngine.IMGUIModule.dll'. Now we can use the game and unity mod manager functions. Note: Unity Mod Manager should already be installed.

 

Information file

Create an information file 'Info.json' so that the mod manager can read it and determine which files need to load when starting the game. The file is written in json and must be placed in the 'Mods' folder and one more folder e.g. '\Steam\steamapps\common\YourGame\Mods\TestMod\Info.json'.

{
  "Id": "TestMod",
  "DisplayName": "Test Mod",
  "Author": "username",
  "Version": "1.0.0",
  "ManagerVersion": "1.0.0",
  "GameVersion": "1.0.0",
  "Requirements": ["SomeMod-1.0.0", "AnotherMod"],
  "AssemblyName": "TestMod.dll",
  "EntryMethod": "TestMod.Main.Load"
}

OR short variant

{
  "Id": "TestMod",
  "Version": "1.0.0",
  "EntryMethod": "TestMod.Main.Load"
}

Id - Unique string. It is desirable to match the folder name. (Required)
DisplayName - Name or Title. (Optional)
Author - (Optional)
Version - Needs for dependent mods and to checking for updates (Format must be 'x.x.x'). (Required)
ManagerVersion - Minimum required version of the mod manager (Format must be 'x.x.x'). (Recommended)
GameVersion - Minimum required version of game. Works if game supports this option. (Format must be 'x.x.x') (Optional)
Requirements - Minimum required version of mods or just other required mod. (Optional)
AssemblyName - Filename we are creating. Default like 'Id' (e.g. TestMod.dll). (Optional)
EntryMethod - A function that will be called by the mod manager at load game. (Required)
HomePage - Web address. (Optional)
Repository - Web address to check for updates. (Optional)

Assembly file

The mod manager supports several variants of the Entry functions. Use only one. Let's call it Load. The name must be the same as in the EntryMethod.

using UnityEngine;
using UnityModManagerNet;

namespace TestMod
{
    static class Main
    {
        // Simply call. Compiled without dependencies on UnityModManagerNet
        static void Load() 
        {
            // Something
        }

        // Transfer a variable with data about the mod.
        static void Load(UnityModManager.ModEntry modEntry) 
        {
            // Something
        }

        // Send a response to the mod manager about the launch status, success or not.
        static bool Load(UnityModManager.ModEntry modEntry)
        {
            // Something
            return true; // If false the mod will show an error.
        }
    }
}

You can add a function that will control on/off mode similar to hot-plug. This function is optional. If the function is missing, the mod may turn on, but it will turn off only after restarting the game.

using UnityEngine;
using UnityModManagerNet;

namespace TestMod
{
    static class Main
    {
        public static bool enabled;

        static bool Load(UnityModManager.ModEntry modEntry)
        {
            modEntry.OnToggle = OnToggle;
            return true;
        }

        // Called when the mod is turned to on/off.
        // With this function you control an operation of the mod and inform users whether it is enabled or not.
        static bool OnToggle(UnityModManager.ModEntry modEntry, bool value /* active or inactive */)
        {
            if (value)
            {
                Run(); // Perform all necessary steps to start mod.
            }
            else
            {
                Stop(); // Perform all necessary steps to stop mod.
            }
            
            enabled = value;
            return true; // If true, the mod will switch the state. If not, the state will not change.
        }
    }
}

Details of ModEntry

Info - Contains all fields from the 'Info.json' file.
Path - The path to the mod folder e.g. '\Steam\steamapps\common\YourGame\Mods\TestMod\'.
Active - Active or inactive.
Logger - Writes logs to the 'Log.txt' file.
OnToggle - The presence of this function will let the mod manager know that the mod can be safely disabled during the game.
OnGUI - Called to draw UI.
OnSaveGUI - Called while saving.
OnUpdate - Called by MonoBehaviour.Update.
OnLateUpdate - Called by MonoBehaviour.LateUpdate.
OnFixedUpdate - Called by MonoBehaviour.FixedUpdate.
OnShowGUI - Called when opening mod GUI.
OnHideGUI - Called when closing mod GUI.

Examples

A simple example of how to bind any action to keys.

using UnityEngine;
using UnityModManagerNet;

namespace TestMod
{
    static class Main
    {
        public static bool enabled;

        static bool Load(UnityModManager.ModEntry modEntry)
        {
            modEntry.OnUpdate = OnUpdate;
            return true;
        }

        static void OnUpdate(UnityModManager.ModEntry modEntry, float dt)
        {
            if (Input.GetKeyDown(KeyCode.F1))
            {
                 Player.health = 9999f;
                 Player.weapon.ammo = 9999f;
            }
        }
    }
}

An example of how to draw a mod menu for a UMM UI. Some IMGUI documentation.

using UnityEngine;
using UnityModManagerNet;
using UnityEngine.UI;

namespace TestMod
{
    static class Main
    {
        public static bool enabled;
        public static string health;
        public static string ammo;

        static bool Load(UnityModManager.ModEntry modEntry)
        {
            modEntry.OnGUI = OnGUI;
            return true;
        }

        static void OnGUI(UnityModManager.ModEntry modEntry)
        {
            GUILayout.Label("God mode");
            health = GUILayout.TextField(health, GUILayout.Width(100f));
            ammo = GUILayout.TextField(ammo, GUILayout.Width(100f));
            if (GUILayout.Button("Apply") && int.TryParse(health, out var h) && int.TryParse(ammo, out var a))
            {
                 Player.health = h;
                 Player.weapon.ammo = a;
            }
        }
    }
}

Harmony

With harmony patches, you can completely take control of game functions. How to do this better to read the official Wiki. Here is an example.

using UnityEngine;
using Harmony;
using UnityModManagerNet;

namespace TestMod
{
    static class Main
    {
        public static bool enabled;
        public static ModEntry mod;

        static bool Load(UnityModManager.ModEntry modEntry)
        {
            var harmony = HarmonyInstance.Create(modEntry.Info.Id);
            harmony.PatchAll(Assembly.GetExecutingAssembly());

            mod = modEntry;
            modEntry.OnToggle = OnToggle;

            return true;
        }

        static bool OnToggle(UnityModManager.ModEntry modEntry, bool value) 
        {
            enabled = value;
            modEntry.Logger.Log(Application.loadedLevelName);

            return true;
        }
    }

    [HarmonyPatch(typeof(Application), "loadedLevelName", MethodType.Getter)]
    static class Application_loadedLevelName_Patch
    {
        static void Postfix(ref string __result)
        {
            if (!Main.enabled)
                return;

            try
            {
                __result = "New Level Name";
            }
            catch(Exception e)
            {
                mod.Logger.Error(e.ToString());
            }
        }
    }
}

Now the function 'Application.loadedLevelName' will always return "New Level Name" string. Similarly, we can change any value in the game.
Be sure to wrap the patch with a Try-Catch block so as not to interrupt an original function in case of errors. Errors can occur if a game code changes after updates.

Finally

Last, compile this code and copy the 'TestMod.dll' file to the 'Info.json' file. After starting the game, you will see messages in the 'Log.txt' file. Also detailed log can be found in 'YourGame\YourGame_Data\output_log.txt' or 'c:\Users%USERNAME%\AppData\LocalLow\YourGame\output_log.txt'.

Additionally

You can explore the game code using the dnspy tool. Also available source code of my mods.