Heavy Mod Manager

From Heavy Iron Modding
Revision as of 02:18, 2 September 2023 by Igorseabra4 (talk | contribs)

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 and Wii 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 file replacement mods only. The program is still under development, so many 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.

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. This will enable Heavy Mod Manager to launch Dolphin.

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 don't have any mods installed yet. Dolphin should launch with the selected game already running.

Installing and playing mods

To install a mod:

  1. Click on the "Install 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 install 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 installing 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 an optional short description. You can also set an optional 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 (installing 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.

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.

Removing files

It is possible to exclude files from a mod, meaning they will be deleted from the game's filesystem once the mod is turned on. You can do this when creating or editing a mod.

Enter the files or folders which you want to remove, one per line. Note that you must enter the full path to the file, including folder names. In the example shown, the file "boot.hip", all the contents of the "hb" folder and the files "db01.HIP" and "db01.HOP" from the "db" folder will be deleted.

This is probably not necessary on most mods, as any files which are not referenced ingame will be simply ignored.

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.

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. 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. But, if you apply the mods 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. Clicking on "Apply Mods" actually does nothing and clicking on "Apply + Launch Game" will simply launch the running copy of the game.

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 Mods" will not restore the backup copy before applying the mods. This means that, if you deactivate a mod with developer mode on, applying the mods will not actually remove the deactivated mod's files from the running instance. To restore the backup copy, click on "Apply Mods" with developer mode off.

Developer mode also forces any running Dolphin instances to close when you click on "Apply + Launch Game". This means you do not need to close your running Dolphin instance before running the game, as the mod manager will do it automatically for you.

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

Features planned for Heavy Mod Manager's future:

  • DOL patching
  • Save file redirection
  • Automatically enabling per-mod AR or Gecko codes
  • Automatically editing the game's INI configuration
  • Support for Xbox and PS2 versions of the games

External Links

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