Mod Loaders

The Mod Loaders are Dynamic Link Libraries (DLL) files that inject themselves into the Sonic Adventure titles by replacing existing DLL files from the game. This is what allows mods to exist external to editing the existing files within the game as well as inject their own code into the game.

Below you'll find links to documentation pertaining to each mod loader respectively. These include in-depth looks at each one's specific APIs.

• SADX Mod Loader

• SA2B Mod Loader

Mod Loader Export References

Below is an overview of the general exports that are available in the mod loaders. An example of a complete export can be seen below.

Variable Exports

ModInfo

ModInfo is a required export from any code based mod. Without it, the mod loader will not load the mod and will throw an error alerting the user that a mod is not a valid mod. <--->

// Example of exporting the ModInfo for SADX.
__declspec(dllexport) ModInfo SADXModInfo = { ModLoaderVer };

// Example of exporting the ModInfo for SA2B.
__declspec(dllexport) ModInfo SA2ModInfo = { ModLoaderVer };

Function Exports

The mod loaders support loading various function exports from a mod. While these are all optional, many mods make use of at least one of these exports as their entry point. This is most commonly the Init export.

Init

The Init (short for Initialize) export is used for initializing information within your mod and passing some variables from the mod loader into the mod itself. The include the mod's path (local path to the mod folder from the game's root), HelperFunctions (see each respective page for each mod loader for more information on this struct), and the mod's index in the list.

This is fired for all enabled mods first. It's fired in the order in which mods are loaded (top to bottom).

__declspec(dllexport) void Init(const char* path, HelperFunctions& helperFunctions, const unsigned int index)
{
    
}

OnInitEnd

This is run after all mods have finished running their Init, but before the game has completely loaded. This is useful for any mods making APIs for other mods to utilize.

NOTE: This is only available in the SADX Mod Loader at this time.

__declspec(dllexport) void OnInitEnd()
{
    
}

OnFrame

This export will run every frame. This can be useful if you need to check something within the game constantly. Users who utilize this should consider cautionary measures to prevent running large amounts of logic every frame if it can be avoided for performance reasons.

__declspec(dllexport) void OnFrame()
{
    
}

OnInput

This export will run when the game processes input. More specifically, it will run just prior to the game actually processing that input.

__declspec(dllexport) void OnInput()
{
    
}

OnControl

This export will run while the game is actively processing input.

__declspec(dllexport) void OnControl()
{
    
}

OnRenderSceneStart

This export will run just before a game scene is rendered.

__declspec(dllexport) void OnRenderSceneStart()
{
    
}

OnRenderSceneEnd

This export will run just after a game scene has finished rendering.

__declspec(dllexport) void OnRenderSceneEnd()
{
    
}

OnRenderDeviceReset

This export will run whenever the render device for the game is reset. For example, resizing the game window will cause the render device to be reset.

__declspec(dllexport) void OnRenderDeviceReset()
{
    
}

OnRenderDeviceLost

This export will run whenever a game scene fails to render.

__declspec(dllexport) void OnRenderDeviceLost()
{
    
}

OnExit

This export runs just prior to the game completely closing.

__declspec(dllexport) void OnExit()
{
    
}

Exportable Lists

The mod loaders also have support for exporting different types of lists. These are all optional exports.

Patch List

A PatchList is comprised of an array of PatchInfo entries. The mod loader will generate these using WriteData.

// TODO: Insert example.

Jumps, Calls, and Pointer Lists

These three exportable lists are all comprised of an array of PointerInfo entries. On the mod loader's side, these arrays are handled like so:

• Jumps are generated using WriteJump.
• Calls are generated using WriteCall.
• Pointers are generated using WriteData.

// TODO: Insert examples.

Example

// Inside of your mod's "main" cpp file (or whichever one houses your exports).
#include "pch.h"

HelperFunctions globalHelperFunctions;
const char* globalPath;

extern "C"
{
    __declspec(dllexport) SADXModInfo = { ModLoaderVer };


    __declspec(dllexport) Init(const char* path, HelperFunctions &helperFunctions, const unsigned int index)
    {
        // This passes the Mod Loader's HelperFunctions struct to your mod's.
        // This is necessary so the API related functions can work properly.
        globalHelperFunctions = helperFunctions;

        // This passes the mod's local folder path to the mod itself.
        // This is helpful for loading custom files.
        globalPath = path;
    }
}