Jump to content

Creating Mods/Creating a DLL Mod

From SA Docs

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. Prerequisites

In order to build DLL files, you will need Visual Studio Community with C++ capabilities. You can download the Visual Studio Installer here.

Open the installer, choose Visual Studio Community, then "Desktop Development with C++" and wait until the installation is finished.

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

2. Creating a DLL project

Now that Visual Studio is installed, we need to make a C++ DLL project.

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 (DLL) template

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

Navigate to the location you've chosen for the project. Visual Studio has created several project files.

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

The .cpp files are files containing C or C++ code, they will be compiled into machine code inside the DLL. The .h files are header files, they contain information that cpp files can use.

3. Add the Mod Loader headers

We already have enough to build a DLL, but we do not have modding capabilities yet. For that, we need to add the Mod Loader headers.

1. Go on the GitHub page of the SADX Mod Loader or the SA2 Mod Loader.

2. Download the repository by clicking on the green "< > Code" button then "Download ZIP".

3. Move the content of SADXModLoader/include (or SA2ModLoader/include) into your project folder.

These files provide modding capabilities to your project, we will learn how to actually use them later on.

4. Creating a source file

Now we need a space to start coding, we will create a new source (.cpp) file where we will put our own code.

1. In Visual Studio, right click "Source Files" then click Add -> New Item...

2. Name it however you want, for example mod.cpp

3. Now we have our own space where we can start coding.

The first line should be:

#include "pch.h"

If you're new to C++ development, you will learn what this is used for later. After that, we need to include the Mod Loader headers with the following line:

#include "SADXModLoader.h"

OR

#include "SA2ModLoader.h"

5. Adding the entry points

Now we need to add entry points to our DLL for the Mod Loader. In order for the Mod Loader to see our entry points, we need to use DLL exports. A DLL export allows other programs to use things from our DLL.

First we add the ModInfo export, this tells the Mod Loader that our DLL is a valid mod.

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

OR

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

Now we can add the most important entry point, the Init function:

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

And a bunch of other optional exports:

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

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

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

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

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

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

extern "C" __declspec(dllexport) void __cdecl OnRenderSceneEnd()
{
	// Executed when the game finishes rendering the scene
}

extern "C" __declspec(dllexport) void __cdecl OnExit()
{
	// Executed when the game is about to terminate
}

Here is what your source file should more or less look like:

6. Building the DLL

Our project is ready, we can now build the mod.

First, make sure you are building for the x86 (32bit) architecture, you can select it at the top.

Currently, it is building in the "Debug" configuration. This mode is useful for debugging and should only be used while testing your mod. Once you want to release it to the world, you should change it to the "Release" configuration and rebuild.

Now press Ctrl+B or click "Build" in the top panel -> "Build Solution".

The DLL should now build. If you get errors, make sure you haven't missed a step and try to understand their meaning. If you are stuck, you should come on our Discord server for help.

7. Testing the mod

Our DLL was generated in the solution folder, inside a "Debug" or "Release" folder.

1. Copy the DLL into your mod folder.

2. If you have not already, you need to edit the mod in the Mod Manager to add the name of your dll.

3. Now you can launch the game, make sure the mod is enabled.

If nothing happens, it's probably working! If an error shows up, try to understand it or ask us for directions on Discord.

8. Doing something

The problem is that our DLL does nothing for now.

This is where you should start experimenting:

  • If you are new to C++ development, see General Programming Guide.
  • Open the Mod Loader headers to see what they contain, specifically the Variables and Functions ones.
  • If you are already experimented, take a look at the community driven disassembly.
  • Take a look at open source SADX/SA2 mods on GitHub to learn from them.

If you want to quickly check if it's working, try to add Rings = 999; in the OnFrame entry point, this is the ingame ring counter.

If you have enabled the Debug Console in the Mod Manager options, you can print to it with:

PrintDebug("text\n");

After any modification, you need to rebuild the DLL, and move it to the mod folder again.

Once you are familiar enough with the process, you can make your life easier with debugging.

Retrieved from "https://sadocs.unreliable.network/index.php?title=Creating_Mods/Creating_a_DLL_Mod&oldid=370"