What is a Mod

• Melody Mania can be extended with custom code that can be used to modify (mod) the game.
  • TIP: Browse mods and other user-generated content on Steam Workshop.
• A folder with such custom code is called a mod folder or short mod.

How to Install Mods

• Mod folders are searched in a specific folder called the mods root folder.
• The mods root folder can be found by executing the command mod.path in the game's console (open via F7).
• To install a mod folder, copy it to the mods root folder. An app restart may be required afterwards.

How to Develop Mods

• Mod development for Melody Mania means C# programming.
• This can be done with Visual Studio Code and the C# Dev Kit that provides IDE features such as code completion, error markers, parameter hints, go to definition, etc.

Mod Interfaces

• A mod needs to implement certain C# interfaces that are instantiated by the game.
• Available interfaces for mods can be found by executing mod.interfaces in the game's console.

Create a New Mod

• Press F7 to open the game's console
• Execute the command mod.create MyModName in the console.
  • This will create a new example mod with the given name.
• Open the created mod folder in Visual Studio Code. Install C# Dev Kit if not done already.
• Write C# code as needed.

The .csproj file

• The .csproj file holds information about the C# project structure of the mod.
• This file tells the IDE which C# libraries (DLL files) are available.
  • The file should point to the DLL files that are shipped with the game, plus the DLL files in the mod folder itself.
• This file is used only by the IDE, not by the game.

The modinfo.yml file

• Information about the mod such as its name, description, and version should be specified in the file modinfo.yml.
• The information from modinfo.yml can be accessed by the user in the game without enabling the mod.

The modsettings.json file

• Instances of IModSettings are saved and loaded from the file modsettings.json of their corresponding mod folder.
• There should only be a single IModSettings implementation per mod.

Loading Assemblies and Types

• Not all of the app domain (i.e. loaded libraries) is exposed to mods by default.

• To make all types from an assembly (e.g. Newtonsoft.Json) available to your mod, specify the assembly in requiredAssemblies of modinfo.yml.

• To make specific types in an already loaded assembly (e.g. System.Uri) available to your mod, specify the type in requiredTypes of modinfo.yml.

  • NOTE: Types from the standard library (for example System.Uri from the assembly mscorlib) must be loaded using this field because requiredAssemblies cannot be used to load the standard library a second time.

• You can find the assembly of a type using go to declaration of Visual Studio Code (see below video).

Mod Loading

• Mods are loaded in alphabetical order.
• Enabled mod are loaded when
  • the game starts
  • a mod becomes enabled
• Instances of classes from mods are created only after all enabled mods have been loaded

Script Loading Order

• First, DLL files in the mod folder are loaded in alphabetical order.
• Second, C# files in the mod folder are loaded in alphabetical order.
• Thus, you can change the load order of your scripts be naming them accordingly, e.g., with a letter prefix.
  • Example: a-MyCoolFile.cs would be loaded before b-MyAwesomeFile.cs

Evaluate Code in the Console

• The game's console can be used to evaluate C# code by using the mod.eval command.
  • Example: mod.eval (UnityEngine.Debug.Log("Hello world!"))
    • Note that the first pair of parentheses is needed to handle the console argument as a single argument when there is a space
• Using statements can be used as well
  • Example:
    • mod.eval (using UnityEngine)
    • mod.eval (Debug.Log("Hello world!"))
• Example to change style of a UI element:
  • mod.eval (using UnityEngine.UIElements)
  • mod.eval (GameObject.FindObjectOfType<UIDocument>().rootVisualElement.Q("logo").style.opacity = 0.1f))
• Loaded mods are not available in this code evaluation.

Troubleshooting Hints

• Disable other mods while working on a new mod.
• Make sure C# Dev Kit and the C# project are loaded correctly.
  • Try to write something that is known to fail, e.g., ThisIsWrong() and check that an error marker appears as expected.
• Make sure that there are no error markers in the IDE
  • Only a mod without errors will load properly in the game.
• Make sure the dependencies of your scripts match their load order.
  • Scripts of a mod are loaded in alphabetical order.
• Make sure modinfo.yml specifies all required assemblies in the requiredAssemblies field or specific types in the requiredTypes field.
• Use UnityEngine.Debug.Log to write information to the game's console.
• Try to restart the app and see if errors are still present.