Marble It Up! Ultra Mod Loader

A very simple mod loader for Marble It Up! Ultra, utilizing Unity Doorstop. In theory, this will probably work with lots of other Unity games due to its simplicity.

DISCLAIMER: Marble It Up! Ultra is a competitive game with a highly competitive scene. I DO NOT CONDONE the use of mods to cheat or gain an unfair advantage in the game. Currently, the Referees in the Marble It Up! Discord are chill with mods, provided they aren't used for (e.g.) "pirating, ruining the leaderboards or play experience for others, or anything illegal". Using mods for fun to tweak/enhance the game (such as using custom skins) or to change the game in ways that don't affect the leaderboard are fine. Anything more is not. Do not ruin this.

Wtih all that said, play fair and enjoy :)

Installation

To install the mod loader:

1. Download the mod loader for your platform from the Releases page
2. Navigate to your Marble It Up! Ultra installation directory
   • In Steam, you can find this directory by right clicking on Marble It Up! Ultra in the library and navigating to "Manage" -> "Browse local files"
   • On Windows, this will probably be something along the lines of C:\Program Files (x86)\Steam\steamapps\common\Marble It Up!
3. Extract the zip file into this directory
4. Put any mods you want to use in your Mods directory
5. Linux/MacOS only: In Steam, right click on Marble It Up! Ultra in the library, open Properties..., and in the launch options text field, enter the following:
   • ./run.sh %command%
6. Start the game and you should be good to go!

Creating Mods

To create your own mod, the only thing you need is to define a class named PatchEntryPoint which has a public static method named Start. The compiled .dll should go inside a subfolder of the Mods folder, and have the same filename as the subfolder (with the .dll extension).

Here is an example:

using UnityEngine;
using UnityEngine.SceneManagement;

namespace HelloWorld
{
	public static class PatchEntryPoint
	{
		private static bool IsPatched;

		public static void Start()
		{
			SceneManager.sceneLoaded += BeginPatch;
		}

		private static void BeginPatch(Scene scene, LoadSceneMode mode)
		{
			if (!IsPatched)
			{
				Debug.Log("Hello, World!");
				IsPatched = true;
				SceneManager.sceneLoaded -= BeginPatch;
			}
		}
	}
}

When the dll file is built, it should be placed in: <MIUU location>/Mods/HelloWorld/HelloWorld.dll

Here are some examples. Take a look to use the .csproj as a template or otherwise learn from:

• Custom Cosmetic Loader
• Diamond Time Viewer
• Console Unlocker

Build

If you just want to use the mod loader, refer to the Usage section above. These instructions are if you want to compile the mod loader itself.

1. Clone the git repository
2. Download Harmony (v2.4.2 as of writing) and extract 0Harmony.dll for net48 into the directory <miuu install>/Mods/ModLoader.
3. Copy UserProperties.xml.template into UserProperties.xml and edit it:
   • Edit GameDir to point to the directory of your MIUU installation.
   • Linux only: Edit GameDataDir to $(GameDir)/MarbleItUp_Data
4. Open the project, e.g. open ModLoader.sln in Visual Studio or open the repository in vscode with the C# extension
5. Build the project, e.g. click Build -> Build Solution in Visual Studio, or run dotnet build --configuration Release. It will build directly into the Mods/ModLoader directory.
6. Download Unity Doorstop (v4.5.0 as of writing) for your platform and extract the x64 version (universal for MacOS) into your MIUU install directory.
7. Edit doorstop_config.ini (Windows) or run.sh (Linux/MacOS):
   • Change target_assembly to Mods/ModLoader/ModLoader.dll
   • Change dll_search_path_override to Mods/ModLoader
   • Optional but recommended (Windows only): Change redirect_output to true
8. Linux/MacOS only: In Steam, right click on Marble It Up! Ultra in the library, open Properties..., and in the launch options text field, enter the following:
   • ./run.sh %command%
9. You should now be able to launch Marble It Up! Ultra with the mod loader.