Heavy Mod Manager

From Heavy Iron Modding

Heavy Mod Manager is a tool made by community member igorseabra4 using .NET 6. It is a mod manager intended to simplify the process of playing and managing mods for the GameCube version of the Heavy Iron Studios games on Dolphin. Please check the use guide below if you want to use the mod manager to play or create mods.

The mod manager is currently able to apply mods with file replacement, HIP/HOP merging, game ID change (for custom save files) and other patches. The program is still under development, some features are still planned.

Playing mods

What you'll need

  • Heavy Mod Manager
  • Latest release of Dolphin Emulator (make sure you get the latest development build, not 5.0 stable).
  • A copy of the GameCube or Wii ISO of the game(s) you want to play mods on.

Configure Dolphin path

When opening the Heavy Mod Manager for the first time, you will see the following screen.

You need to specify the paths for the Dolphin executable (Dolphin.exe) and the Dolphin user folder (usually located under Documents\Dolphin Emulator). Heavy Mod Manager will attempt to find these automatically for you; if it can, you will see them listed at the bottom of the window and you can skip to the next step. Otherwise, follow the steps below:

Click on Settings -> Choose Dolphin Path and a file selector window will open. Choose the location of your Dolphin executable (Dolphin.exe). Usually, you will find it on C:\Program Files\Dolphin-x64\, but this might vary depending on your Dolphin installation. If you have a shortcut on your desktop or elsewhere, you can select that as well.

Then, click on Settings -> Choose Dolphin User Folder Path and a folder selector window will open. Choose the location of your Dolphin user folder — it's usually located under Documents\Dolphin Emulator, but this might vary. It's the folder which contains folders such as Backup, Cache, Config, Dump:

Adding a game

To be able to play mods, the mod manager must first create an internal backup of the game. This process must be repeated for any games you wish to add to the mod manager:

  1. In Heavy Mod Manager, select the game you are adding from the "Choose Game" dropdown.
  2. Click on the "Create Backup" button. A file selector window will open. Navigate to your game's ISO file and select it.
  3. The mod manager will create an internal backup of the game's files. The window might be unresponsive for a few seconds, this is normal. After that, a message box will appear, notifying that the backup was successfully created.

You can start playing mods on this game now! If you want to test, click on "Apply Mods" and then on "Apply + Launch Game", even if you haven't added any mods added yet. Dolphin should launch with the selected game already running.

If you accidenally selected the wrong ISO file, don't worry, just click on "Create Backup" again and choose the correct ISO.

Adding and playing mods

To add a mod:

  1. Click on the "Add Mod" button and a file selector window will open. Select a mod's ZIP file (which you probably downloaded from the wiki or another place). This will add the mod.
  2. Click the checkbox next to the mod's name to enable it, as seen on the image below. You can enable and disable as many mods as you want to, as well as reorder them using the arrow buttons.
  3. Click on "Apply Mods" to apply the mods. The selected mods will be applied in order, from top to bottom. Note that not all mods are compatible with each other, meaning many mods (such as stage mods) will probably not work if multiple are enabled at the same time.
  4. Click on "Apply + Launch Game". This will apply the mods (if they haven't been applied already) and launch Dolphin with the modded instance of the game.

Note that, if you already had AR or Gecko codes active for the game on Dolphin, they will still be active when you launch the modded instance, even if you have active mods which change the game ID or add AR/Gecko codes.

Note that adding mods from ZIPs is only possible if the mod's creator made a ZIP file that is compatible with the mod manager. If you try to load an uncompatible ZIP, it will display an error. If you want to play a mod from an uncompatible ZIP, you must create a new mod and add the files to it manually. This is explained below.

Creating mods

Creating a new mod within the mod manager is necessary if you're a mod developer creating a new mod or if you just want to play a mod from a ZIP file that was not created by the mod manager. You will need to create a new mod from the mod manager, then add the mod's files to the mod's folder.

First, click on Manage -> Create Mod. This will open the Create New Mod window.

On this window, you should type in the mod's name, creator name and a short description. You can also set a date/time for when the mod was created and last updated.

The last field, Mod ID, is an ID that is generated automatically for the mod which should be unique among all mods, by all creators, for all games (adding a mod will overwrite a mod with that ID if it already exists). It's recommended not to change this from the default text, but you can if you believe another mod might already use this ID. You cannot change a mod's Mod ID after it is created.

Once you click on "Create Mod", a folder for the mod will be created and will be opened for you on a file browser window:

The "files" folder in the mod's folder should contain your mod's files. This "files" folder mimics the structure of the "files" folder in an extracted game. This means that you should put your mod's files in this folder as if it were the filesystem root. For example, if the mod has an INI file, it should go directly in the mod's "files" folder, and so should any subfolders, as shown below:

This mod will replace the "sb.ini" file in the filesystem root and files in the "db" folder. You can also add new files and folders to the mod.

Once the files have been placed, click on the "Refresh Mods" button. The new mod should run after enabling it by checking the checkbox and clicking on "Apply + Launch Game".

Editing a mod

Click on Manage -> Edit Mod to open a window where you can edit the mod's metadata. Note that you cannot change an existing mod's target game or Mod ID. You can also configure additional settings for you mod under "Patches and Replacements":

  • Game ID (Save File) - change the game ID for when your mod is applied. This allows your mod to have a unique save file. This is required if your mod has AR or Gecko codes.
  • INI Values - alter game INI entries without having to replace the entire INI.
  • Merge HIP Files - HIP/HOP files whose assets will be imported into the existing files instead of replacing the entire file.
  • Remove Files - files which will be deleted once the mod is applied. This is useful if you created a level with all assets in the HIP and need to delete the HOP.
  • DOL Patches - allows you to edit the binary of the game's executable.
  • AR and Gecko Codes - AR and Gecko codes to be applied when the mod is launched. It's recommended to set a custom game ID if you have AR or Gecko codes. If you don't set one yourself, it will use a custom one automatically.

For more information on each item, click on the "Info" buttons next to the text boxes.

If your mod has AR or Gecko codes, Heavy Mod Manager requires a custom game ID to be used so that it can create the proper Dolphin configuration file with the codes. If you don't set one yourself, it will use a custom one automatically. Note that, if the user already has active codes on Dolphin before applying the mod, the user's codes will also be active when launching the modded game.

Distributing mods

Once you've set up a new mod, you might want to share it in a mod manager compatible ZIP so others can play it. To do this, simply select the mod from the list and click on Manage -> Zip Mod. This will create a mod manager compatible ZIP with your mod, which you can share with others.

If you want to, feel free to create the ZIP yourself by zipping the contents of the mod folder (make sure the mod.json file and files folder are on the root).

Developer Mode

Under Settings -> Developer Mode, you can turn on developer mode. This mode is meant to be used not while playing mods, but by mod developers while working on mods.

To understand what developer mode does, here's a bit of insight on how the mod manager works: it keeps two copies of the game's files. One of them is a backup, clean copy and the other one is the running copy, which has the mods applied and is launched on Dolphin. Every time you add, remove or reorder mods, the running copy is invalidated, which means that, when you apply the mods (by clicking on "Apply Mods" or "Apply + Launch Game"), first the backup copy is restored and overwrites the running copy, then each mod's files are copied into the running copy, in order. But, if you click on "Apply + Launch Game" without changing the active mod list, no action is performed. The running copy already contains the active mods, so there's no need to reapply the same mods again. Dolphin is launched straight away.

However, when Developer Mode is on, the mod files of enabled mods are copied to the running instance every time you apply the mods. This means that you can edit your mod's HIP and HOP files (the ones in the mod's folder) with Industrial Park and, when you apply the mods, your edits will be copied to the running game, regardless of if you changed the active mods. This allows you to use the mod loader to quickly preview changes on your mods without needing a completely separate copy of the game just for a mod.

Note that, when developer mode is on, clicking on "Apply + Launch Game" will not restore the backup copy before applying the mods. This means that, if you deactivate a mod with developer mode on, the "Apply + Launch Game" button will not actually remove the deactivated mod's files from the running instance. To restore the backup copy with Developer Mode on, click on the "Apply Mods" button as that button will always restore the backup first.

Adding a game from extracted files

Aside from adding the game from the ISO, you can also add it from the game's extracted files. The steps are very similar to the Setting up Dolphin for modding guide, as you can add the game's main.dol file to create the mod manager's backup.

  1. Launch Dolphin and add your ISO to the game list.
  2. Right click the ISO on the game list and select Properties. Navigate to the Filesystem tab.
  3. Right click the root of the disc (first item on the file tree) and select Extract Entire Disc. Create a new folder and wait while the disc's files are extracted to it.
  4. In your new folder, there should be two folders: one named "files" and another named "sys".
  5. In Heavy Mod Manager, select the game you are adding from the "Choose Game" dropdown.
  6. Click on the "Create Backup" button. A file selector window will open. Navigate to the folder where you extracted your disc to. In the "sys" folder, select the "main.dol" file.
  7. The mod manager will create a backup of the game's files. The window might be unresponsive for a few seconds, this is normal.
  8. A message box will appear, notifying that the backup was successfully created. This means that now you can delete the "files" and "sys" folders which were extracted from Dolphin, as you do not need them anymore.
  9. The game's backup should have been created and you can start adding and playing mods to it now.

Planned features

  • Support for managing mods on other consoles

External Links

Retrieved from "https://heavyironmodding.org/wiki/Heavy_Mod_Manager?oldid=9529"