Heroes Mod Loader

From Sonic Retro

Sonic Heroes Mod Loader.png
Heroes Mod Loader
Category: Universal Mod Loader
Version: Prototype "v0.8"
Status: Deprecated
System: Microsoft Windows
Supported Games: Various Games
Credits: Sewer56lol
Exclamation.svg This article/program is deprecated and should not be used. Please instead make use of Reloaded Mod Loader

Heroes Mod Loader is a mod loader and mod management system combination written in C#.

Originally designed to load user mods for Sonic Heroes, the loader was entirely written and researched from scratch and is an experimental prototype of a universal mod loader which can also support various games out of the box without modification.

A public prototype was released at the Sonic Hacking Contest as part of Sonic Heroes' first ever Sonic Hacking Contest entry on the 20th of November 2017. Following release, the mod loader was under heavy reworking until it was eventually cancelled and replaced with the Reloaded Mod Loader, a mod loader not only for Sonic Heroes, but also for numerous other titles.


  • Windows 7 or newer.
  • .NET Framework 4.5 Runtime (as of 12th of December 2017)
  • .NET Framework 4.7 Runtime (prior to 12th of December 2017)
  • DirectInput Compatible Input Device (Keyboard, Joystick).
  • Correct Executable for Each Game (Generally an Anti-disc crack or the latest version of Steam (if a game uses Steam client)).

Due to heavy reliance on Platform Invocation (P/Invoke) within the loader, it is unlikely to run under Wine.

Installation and Usage

Basic use and configuration may be performed as follows:

  • To install, download the archive storing the mod loader and extract the 7z contents in any location.
  • Run the configuration utility, HeroesModLoader-Configurator and follow the on-screen instructions.
  • In the Main Menu, select any mod you would like to use and then either "Save & Exit" or "Launch & Exit".
  • To start, run HeroesModLoader.exe as Administrator, launching the stock game executable will have no effect on the game.

When running the loader, it is not recommended to close the console window at the current time.

Controller Configuration:

  • You may at first require to configure your own controller.
  • To configure, select the second tab labelled "Mod Loader: Input Stack" and set up the buttons for your controller.
  • Selecting a controller from the dropdown will generate a new config file if it doesn't already exist.
  • It is recommended that controls for each device are set regardless of whether it'll be used or not.

Additionally, the following points may also be considered:

  • "Exit" button may be used discard any non-controller configuration changes.
  • "Controller I/II Buttons" is an alternative for the Sonic Heroes' launcher controller configuration and changes the game's own configuration.
  • Controller configurations can be changed on a per-mod basis by copying controller configurations to a mod's directory alongside main.dll.
  • Controllers follow an internal port priority/order, some mods may expect/only read controller port 1.

Port priority may be changed by manually modifying the Controller_ID field of each controller configuration under Mod-Loader-Config, all controllers are sorted by the Controller_ID field with lowest number taking the highest priority. Changing port order via the GUI is unsupported at the current time.

File Structure

  • Mod-Loader-Backup: Stores game files which have been replaced for this session. Restored when the game is exited/on each loader startup.
  • Mod-Loader-Config: Currently under reconstruction. Stores controller configurations, fonts & mod loader configuration files.
  • Mod-Loader-Libraries: Stores external libraries used by the loader & configurator. Non-statically compiled mods will also look in here.
  • Mod-Loader-Mods: Stores individual mods for the Mod-Loader. Currently all mods occupy a subdirectory of this directory.

There is no mechanism to switch between games at the current moment, to switch you should reset the paths. Remove the Setup Flag by deleting Mod-Loader-Config/Setup_Complete and re-run the configurator to set new game paths.

Feature List

This list has been shortened down to a tl;dr format, the total feature set is more exhaustive but constantly changes:

  • Memory Reading/Writing: This one should have been obvious.
  • File Replacement/Addition: Also obvious.
  • Game Function Hooking: Including hooking in own ASM code, redirection to own C# code/methods. Support for Multi-Level hooking.
  • D2D Overlays: Currently based off of an external overlay. Limited to Windowed/Borderless, requires Windows Aero. Supports any API.
  • Direct Controller Input Reading: Supports DirectInput keyboards and controllers. Fully rebindable, supports hotplugging.
  • Assembler Integration: Generate assembly code on the fly during runtime.
  • C# Based Mods: Lowering the entry gap, convenience of .NET Framework.

Planned Changes/Features

  • Game Manager: Switch games without manually resetting paths. Per-game mod management/filtering.
  • XInput Support: Vibrate a few controllers, separate axis for 360 controller triggers.
  • Internal D3D9/D3D11 Overlay: Internal D3D9 & D3D11 Hooking as an option planned for future.
  • File Replacement: Soon moving onto Hardlinks to prevent redundant storage writes.

Development of these features is expected post internal rework & code cleanup.

Sonic Heroes specific features are planned to be moved out of the configurator onto an external mod for the loader.

Supported Games

The Heroes Mod Loader is known to have been used/tested with the following games/configurations:

The loader has not been tested with any x64 games/processes.

At the moment it may not function with games using Address Space Layout Randomization (a rarity) and games which terminate themselves and/or are forced to launch from a launcher (rare).

Sonic Riders requires a patch to remove the launcher requirement. The author created one which allows this as well as launching multiple Riders instances (for Netplay testing).


There is no "Stable" version as this mod loader never left the prototyping phase, but its replacement, Reloaded Mod Loader, has a few stable releases and is being actively worked on.

File layouts, mod templates, mod layouts, system requirements and other different factors are continuously changed.

Download.svg Download Heroes Mod Loader
File: Heroes-Mod-Loader-NET45.7z (35.91 MB) (info)
Current version: 8th December 2017

For the purposes of archival, the first ever public release can be found on the Sonic Hacking Contest 2017 website: Heroes Mod Loader & Tweakbox β (Tech Demo).