Create a DLL Mod - X-Hax/SADXModdingGuide GitHub Wiki

If you want to have more control over the game, you can compile a c++ DLL to modify or call the game's own code easily. This tutorial will go through the most basic method to get a DLL running.

Note that if you just want to replace assets or change level geometry for example, you do not need a DLL.

1. Prerequisite

You will need Visual Studio Community, you can get it here. In the install configuration, choose "Desktop Development with c++" and continue the installation.

Note: You only need the toolkit (the latest is v142), the SDK and the debugger.

2. Set up the DLL Project

Now we need to create an empty dll.

1. Click on "Create a new project" on the starting page. If there's no starting page, click on "File" then "New project".

2. Select the Dynamic Link Library template

3. Choose a name and a location for your project.

Navigate to the location you've chose for the project.

• The folder where the .sln file is is called the solution folder.
• The subfolder containing the .vcxproj files is called the project folder.

3. Set up the mod loader includes

The Mod Loader includes contain the location of a lot of SADX functions and variables.

1. Download the programming folder here.
2. Copy and extract the files into your project folder Note that only the files in the screenshots are necessary, the rest is optional.

3. In Visual Studio, open pch.h or stdafx.h depending on your environment, and add #include "SADXModLoader.h" below the existing include.
4. Build the solution ("Build" in the top panel -> "Build Solution") to check if it works.

If compilation fails be sure that:

• You are compiling in x86 mode (top panel)
• That #include "SADXModLoader.h" is under the windows include in pch.h or stdafx.h.
• That in the properties of your project ("Project" -> "Properties") you are using an existing SDK and toolset.

If it still doesn't work, please tell us on Discord.

4. Create the Entry Points

You have everything needed for the dll, now we just need to provide the entry points. In Visual Studio, add a new cpp file in the "Source Files" filter.

Name it whatever you want, and then put the code below.

#include "pch.h"
// or #include "stdafx.h" for previous Visual Studio versions

extern "C"
{
	__declspec(dllexport) void __cdecl Init(const char *path, const HelperFunctions &helperFunctions)
	{
		// Executed at startup, contains helperFunctions and the path to your mod (useful for getting the config file.)
		// This is where we override functions, replace static data, etc.
	}

	__declspec(dllexport) void __cdecl OnInitEnd()
	{
		// Executed after every mod has been initialized, mainly used to check if a specific mod is also enabled.
	}

	__declspec(dllexport) void __cdecl OnFrame()
	{
		// Executed every running frame of SADX
	}

	__declspec(dllexport) void __cdecl OnInput()
	{
		// Executed before the game processes input
	}

	__declspec(dllexport) void __cdecl OnControl()
	{
		// Executed when the game processes input
	}

	__declspec(dllexport) void __cdecl OnRenderDeviceReset()
	{
		// Executed when the window size changes
	}

	__declspec(dllexport) void __cdecl OnRenderDeviceLost()
	{
		// Executed when the game fails to render the scene
	}

	__declspec(dllexport) void __cdecl OnRenderSceneStart()
	{
		// Executed before the game starts rendering the scene
	}

	__declspec(dllexport) void __cdecl OnRenderSceneEnd()
	{
		// Executed when the game finishes rendering the scene
	}
	
	__declspec(dllexport) void __cdecl OnExit()
	{
		// Executed when the game is about to terminate
	}

	__declspec(dllexport) ModInfo SADXModInfo = { ModLoaderVer }; // This is needed for the Mod Loader to recognize the DLL.
}

And it is done, you can now build the solution again and it will output a valid DLL.

To test if it works, you can add Rings = 999; in the "OnFrame" function and it will, every frame, set the number of Rings to 999.

Screenshot of the result.

5. Add our DLL to the mod folder

Now the last thing you need to do is add DLLFile=DLLNAME.dll to your mod.ini, and move the DLL into your mod folder. The DLL will be located in the Debug/Release folder at the root of your project folder. Don't forget to enable the mod in the Mod Manager!

Important: If you want to release your mod online, be sure to set the build mode (top panel) to Release!