Getting started with SADX modding

This page is an introduction to SADX modding for beginners.

Modding SADX is fun, and pretty easy. It’s also a great learning process that will help you understand a lot of things about game development and acquire new skills that may be useful in your other projects. Although it may seem difficult from a quick look, don’t be discouraged by the seeming complexity of the tools and the usage of Visual Studio. You only need to understand the things you want to change, and you don’t even have to be a programmer to make C++ mods. Case in point: I developed all my mods, including Dreamcast Conversion, with next to zero knowledge of C++.

So, let’s get scratchin’!

Things you’ll need

  1. The 2004 PC version of SADX + SADX Mod Loader. It isn’t easy to purchase the 2004 port these days, but if you own the Steam version it’s possible to convert it to the 2004 version using SADX Mod Installer, which also installs the latest version of SADX Mod Loader automatically.
    Note 1: You will need a clean (unmodified) sonic.exe from the US version. If you have the European version of the 2004 port, you can simply replace the exe with this one. Alternatively you can use the installer, which will add the correct version of sonic.exe.
    Note 2: It’s always a good idea to back up your SADX folder. Before messing with mods, copy your entire SADX folder to a safe place that you can go back to later in case something goes wrong and you want to start afresh.
  2. SA Tools. This is a must have tool package for developing SADX and SA2 mods. It includes level, model and texture editors, various converters and a set of “split” tools that unpack sonic.exe and other binaries to let you view and edit the levels/models.
  3. (Optional) PVMX tool. You can use this command line utility to compress custom texture packs into PVMX archives, which improve load times.
  4. 7Zip Archiver to package your mods.

Depending on the kind of changes you want to have in your mod the above may be enough. For example, if you simply want to change a few textures in the game, you don’t need anything else. However, to develop mods that add new assets or change the way the game works you may need to write custom code, in which case you’ll need to use the following:

  1. Microsoft Visual Studio, preferably 2015 or above. If you’re a student, you may be able to get the Community version for free through the Microsoft Imagine (formerly DreamSpark) program.
    Note 1: You don’t need to know any programming language to be able to make mods in Visual Studio. You only need to know some basic C++ syntax, and only if you write custom code. For basic level/model replacements the tools generate C++ code with the correct syntax automatically.
    Note 2: It’s a good idea to install the GitHub plugin (available from Visual Studio installer as well) for seamless integration with GitHub.
  2. IDA disassembler version 7.0 or above + MainMemory and SonicFreak94‘s sonic.exe disassembly. The disassembly is helpful when you want to look up certain things in the game (models, code for objects etc.) or when you want to understand what the game does at a specific moment.
    Note: Where and how to get IDA is up to you – if unsure, ask other modders.
  3. Cheat Engine. This is a useful tool to edit memory when the game is running. There are several pre-made cheat tables you can use with SADX, such as MainMemory‘s table or Codenamegamma’s table. Depending on your area of interest and modding skills eventually you may end up making your own cheat table with things that are important for your mods.
  4. PL Tool if you want to make custom lighting for SonicFreak94‘s Lantern Engine mod.

The following things are not required for making mods, but it’s a good idea to have them nevertheless:

  1. Some kind of screenshot/video capture software. For screenshots, you can use MSI Afterburner. For streaming and recording videos, OBS Studio would work. Fraps is an all-around alternative, but unlike the above two it isn’t free.
  2. An IRC client. If you need help with modding SADX, the #x-hax channel on BadnikNET is the best place to ask. A dedicated client (such as HexChat) is recommended because it saves chat history so you can go back to it later for reference.
    Use the following URL in your preferred IRC client:
    irc://irc.badnik.zone/x-hax
    Alternatively you can input the settings manually like this:
    Server: irc.badnik.net
    Port: 6667
    Channel: x-hax
    Note: If you absolutely can’t use an IRC client, you can still access the channel using the webchat.
  3. A GitHub account, which will let you create code repositories for your mods, make contributions and submit feedback for other people’s projects.

Congratulations! You are now ready to delve into the world of SADX modding.

Configuring SADX and the Mod Loader

After you’ve installed the Mod Loader you need to configure SADX and the Mod Loader for optimal settings. First of all, run SADXModManager.exe from the SADX folder and make sure the Mod Loader is enabled:

If it says “Install loader” like in the screenshot above, click the button to enable the Mod Loader. If it says “Uninstall loader”, you don’t need to click it.

Now click the “Config Editor” button at the bottom right and set the following settings:

Click OK, then go to the Mod Manager’s Graphics tab and configure the settings to your liking. For 1080p I use the following settings:

Note: For convenience’s sake, the settings used for mod development are usually different from the settings used for regular gameplay. For example, you’d want to play the game in the windowed mode and/or windowed fullscreen to be able to switch between SADX and the tools (such as Cheat Engine) easily. The above settings make the game run at the 1080p resolution, which is downscaled to a 1664×936 window. This way you get a window that is large enough for a 16:9 screen and a full 1080p resolution when you go to the fullscreen mode (Alt+Enter).

Finally, go to the Options tab and configure debug output and update checks. When debugging mods you may also want to turn debug console on.

Of course the above settings are not mandatory, and depending on your needs and preferences you could use something different. For example, you may prefer to run the game in a 1024×768 window to keep the original 4:3 aspect ratio, or in a 1280×720 window if your screen resolution is small.

Don’t forget to click “Save” when done!

Overview of the SA Tools

The folder structure for the tools is a bit convoluted, but it becomes easier to navigate once you understand how it works. First, here’s a list of all tools in the package that can work with SADX:

Texture-related tools

  • ArchiveTool – this is a command line program that packs and unpacks PVM archives. Unlike the other tools, it uses PVR textures as-is without any conversions. It can also compress and decompress PRS-packed PVMs. This tool is mostly useful when working with Dreamcast assets, for custom textures PVMX is a better choice.
  • CompilePVM – this command line tool converts a folder texture pack into a PVM archive. It’s now obsolete – use PVMX instead.
  • PVMEditSharp – a GUI PVM archive editor. It can also export PVM archives into folder texture packs, which is useful for custom textures.
  • PVM2TexPack – a command line version of the “Export texture pack” option in PVMEditSharp.

Note: Don’t use PVMs when making custom textures. PVM archives require the textures to be converted into the Dreamcast’s PVR format, which is lossy and has many limitations. To make custom textures for a level, first export the original game’s PVM as a texture pack using PVMEditSharp/PVM2TexPack, then edit the PNG images in the exported folder. Optionally you can create a PVMX archive from that folder to minimize load times.

Model and level editors

  • SADXLVL2 – level editor for SADX PC. It requires a project .ini file to work. The default toolset comes with SADXLVL2.ini that covers all levels in SADX PC.
  • SALVL – level editor for SA1, SADX PC and SA2. Unlike SADXLVL2 it can open .sa1lvl and sa2lvl files, as well as load levels from EXE/DLL/BIN files directly without a project file.
  • SAMDL – model viewer/editor. Works with models from SA1 and SADXPC with some support for chunk models (SADX and SA2).

Export tools

  • StructConverter – this tool exports various game data from sonic.exe as Mod Loader-compatible data or C++ code.
  • DLLModGenerator – this tool exports various game data from DLL files (ADV00MODELS, CHRMODELS etc.) as Mod Loader-compatible data or C++ code. Basically StructConverter for DLL files.

Other tools

  • LevelConverter – converts SA1 and SA2 landtables to SADX format.
  • Level Extractor – extracts landtables from SA1, SADX and SA2 directly from binaries.
  • SADXSndSharp – editor for SADXPC .dat soundbanks, which contain sound effects and some character voices.
  • SADXTweaker2 – a tool that provides a GUI for editing various files extracted by the split program.
  • SASave – a savegame editor for SA1 and various versions of SADX.
  • SETCodeGenerator – this tool generates C++ code from SET files. Such code is used in mods when SET files can’t be loaded – for example I used it to restore objects in Chao Race (which uses SET files in SA1 but not in SADX). This is a pretty niche tool that not so many people have to use.

The tools have separate folders for SA1, SA2 and SADX, which contain project files, tools and other data specific to each game.

Setting up the tools and split data

Unpack the SA Tools archive to an easily accessible folder. For example, I prefer the SA Tools folder to be in the root of the disk, like D:\SATools.

Note: Some tools may not like spaces or “exotic” characters in paths. If you use Windows in a language other than English, it’s better to keep simple paths like D:\SATools instead of your desktop or “My Documents”.

The game stores its assets (models, levels etc.) in several binaries, which need to be extracted (“split”) before you can edit them. The main binary is sonic.exe, which contains the majority of ingame assets. However, there are also several DLL files that also store various assets:

  • CHRMODELS.dll (CHRMODELS_orig.dll with the Mod Loader) has models used by playable characters.
  • ADV00MODELS.dll has landtables, models and texture lists used by Station Square.
  • ADV01MODELS.dll has landtables, models and texture lists used by Egg Carrier (outside).
  • ADV01CMODELS.dll has landtables, models and texture lists used by Egg Carrier (inside).
  • ADV02MODELS.dll has landtables, models and texture lists used by the Mystic Ruins.
  • ADV03MODELS.dll has landtables, models and texture lists used by Mystic Ruins Past.
  • BOSSCHAOS0MODELS.dll has landtables, models and texture lists used by the Chaos 0 boss fight.
  • CHAOSTGGARDEN02MR_DAYTIME.dll and its EVENING and NIGHT counterparts have landtables and models for the Mystic Ruins Chao garden at different times of day.

Note: Although the above structure can be used for general reference, the game doesn’t always use it consistently. For example, not all objects in Station Square have their models stored in ADV00MODELS, and some character models (such as Amy when captured by Zero) are stored in sonic.exe rather than CHRMODELS.

Copy all files from your SADX folder to the SADXPC folder in SA Tools so that it looks like this:

Note: to save space you can delete the “sounddata” folder folder in SADXPC\system.

Now you are ready to split the data from sonic.exe and DLL files. Find the splitall.bat file and run it. If you did everything right, a command prompt will show up informing you on the progress:

If the process completed without errors, you are now ready to use the tools.

Installing Visual Studio

Launch the Visual Studio Installer and check “Desktop development with C++”:

Then go to the “Individual components” tab and make sure “Windows XP support for C++” and “GitHub Extension for Visual Studio” are checked. Proceed to install Visual Studio. Once Visual Studio is installed you can create your first project.

Creating a C++ mod

Start with creating a new project in Visual Studio:

Select “Visual C++” and “Empty Project”:

Now you need to decide whether or not to use a GitHub repository. In the most basic terms, a repository (repo) is a place that hosts the source code of your mods. The majority of SADX mods have their source code available on GitHub. You can set up Visual Studio to synchronize changes between your local code and the GitHub repo. In addition, you get all other benefits of GitHub, such as the “Issues” page for feedback, and the “Releases” page for mod releases and updates. Here’s a list of cases when using GitHub is beneficial:

  • You want to make your mod open-source. While nobody is obliged to open source their mods, we all learn from each other’s code, so if your mod does something new and original it’s a good idea to offer the source code for others to look at and potentially contribute.
  • You want to have a feedback channel for your mod. GitHub repositories can have an “Issues” page (example), where you and anyone else can post feedback, report problems and set up TODO lists.
  • You want to offer mod updates through GitHub. This way you can configure your mod to be updated through the Mod Loader, which will pull the latest version from the mod’s Releases page (example) on GitHub. There are other ways to support updates, which we will discuss separately, but for relatively small mods GitHub is probably the best choice.

If your mod is for personal use only – for example, if you just want to mess around with SADX with no particular goal in mind – you may want to skip GitHub support.

Check “Create new Git repository” on the bottom right if you want your mod to use GitHub.

Note: If you plan to work on multiple mods it’s a good idea to have a dedicated “GitHub” folder, which will contain subfolders for each of your mods. I recommend setting the location in the above dialog to something like “D:\GitHub” for all mods. That way your test mod will be in D:\GitHub\sadx-test-mod.

Now you need to set up the project to make it build a DLL. Right click “sadx-test-mod” in Solution Explorer and select Properties:

In the Properties window, configure the settings as follows. Make sure Configuration Type is set to Dynamic Library (.dll) and the Character Set is Unicode. Setting the toolset to v141_xp will maximize your mod’s compatibility.

After the project has been set up, you need to add a few basic things to make it compatible with the Mod Loader. Start by going to the project’s folder – if you followed the above example, it should be D:\GitHub\sadx-test-mod\sadx-test-mod.

Note: The project’s folder is different from the solution’s folder. You need to go one level deeper to reach the project’s folder, so it should be D:\GitHub\sadx-test-mod\sadx-test-mod rather than D:\GitHub\sadx-test-mod.

Now copy all files from SADX Mod Loader’s programming folder (which you can find in your SADX folder) to your project folder so that it looks like this:

Now go back to Visual Studio, right click “Source Files” and add a new source file:

Name it something recognizable like mod.cpp and add it to the project:

You are now ready to write your first code.

Code structure of C++ mods

The code explained below is generated by StructConverter and DLLModGenerator automatically when exporting modified assets, so in most cases you don’t need to write it yourself. However, it’s a good idea to have a general understanding of what the code is and how it’s used by the Mod Loader. This section examines the basic structure of a C++ mod for SADX.

The first line of your mod will be:

#include "SADXModLoader.h"

#include adds a header file to be processed before compiling the source.

Headers (.h files) contain data such as structure definitions, data pointers or actual level/model data structures, while source files (.cpp files) contain functions used by your mod. In other words, headers contain data and source files contain code. You can have data in the .cpp file as well if you prefer, but following the above convention makes your mod source easier to read.

SADXModLoader.h is the main header for the Mod Loader, which contains the majority of data structure definitions, data pointers and other things necessary to compile DLL mods, so every DLL mod should #include this header.

To make the mod’s code accessible by the Mod Loader it needs to have the dllexport storage class attribute. In simple terms, your mod should have this line:

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

The above line makes your DLL recognizable by the Mod Loader.

Now you can write your code for the Mod Loader to execute. There are several functions that you can use to execute your code:

The Init function is executed once when the Mod Loader initializes the mods on startup. It’s defined like this:

extern "C" __declspec(dllexport) void __cdecl Init(const char* path, const HelperFunctions &helperFunctions)
{
//Your code here
}

The OnFrame function is executed every frame while the game is running (so 60 times a second at 60 FPS). It’s defined like this:

extern "C" __declspec(dllexport) void __cdecl OnFrame()
{
//Your code here
}

The OnInput function is executed every time the game polls input. It can be used to detect whether a button is pressed, for example. It’s defined like this:

extern "C" __declspec(dllexport) void __cdecl OnInput()
{
//Your code here
}

The OnExit function is executed once when the game is about to close. It’s defined like this:

extern "C" __declspec(dllexport) void __cdecl OnExit()
{
//Your code here
}

If you use several of these functions in your mod, you can make your code look cleaner by putting them under one “extern”:

extern "C"
{
    __declspec(dllexport) ModInfo SADXModInfo = { ModLoaderVer };
    __declspec(dllexport) void __cdecl Init(const char* path, const HelperFunctions &helperFunctions)
    {
        //Your code for the Init function
    }
    __declspec(dllexport) void __cdecl OnFrame()
    {
        //Your code for the OnFrame function
    }
    __declspec(dllexport) void __cdecl OnInput()
    {
        //Your code for the OnInput function
    }
}

Note: To make the code cleaner, you can make your own functions and call them from each of the above functions when necessary.

For examples of code that you can use in a C++ mod check out the tutorials in the top menu.

Compiling your C++ mod

To compile the mod, you need to make sure it’s set up for x86 release configuration:

Then all you need to do is select Build->Build Solution (F7) in the top menu. Your DLL will be in the solution’s release folder. If you followed the example setup, the DLL is in D:\GitHub\sadx-test-mod\Release.

Pushing the changes to GitHub

In the bottom right corner of Visual Studio you can see an icon that lets you review the changes:

The Changes section will list all files that you’ve added, changed or removed since the last time you synchronized local code with GitHub. You can click individual files to review the changes side by side against the original version. You can also right click them to undo changes. When you’re done reviewing, enter a brief message describing your changes, click on the arrow next to the Commit button and select “Commit all and push”:

Note: You could also split your changes between several commits by right clicking individual changes and selecting “Stage”. The staged changes will be added to the commit, while the unstaged changes will remain local.

Now you need to publish your GitHub repo to be able to push the changes. Sign in using your GitHub credentials in Team Explorer:

Then enter a brief description and click Publish:

Restart Visual Studio and you should be able to push your changes to the repository. You can review outgoing commits by clicking this icon on the bottom right:

Making a Mod Loader mod

Open SADX Mod Manager and click “New…”. Then fill in the information about your mod:

If you want your mod to be updated via GitHub, go to the Updates tab and fill in the name of the mod’s archive, the repo’s name and the user’s name. In the example below the user’s name is “user”, replace it with your GitHub account name.

Click OK, and the folder with you mod will open. Now you need to edit mod.ini to make it load your mod DLL. You can do it by adding a DLLFile line:

If needed, make a system folder in your mod’s folder and copy any files you need to replace. You can also create a textures folder for texture packs.

Now just copy your DLL to the mod’s folder, and your mod is ready! Package it up by putting your mod folder into a .7z archive like this:

Making a GitHub release for updates

To make GitHub mod updates work you need to upload a release. Go to your GitHub account in the browser and open your repository. Then click “0 releases” in the Code tab:

Select “Create a new release” and fill in the following information:

  • Version tag can be anything, it’s probably best to make it match the mod’s version, like 1.0
  • Release name, such as “First test”
  • Release description, which will appear in the update changelog in the Mod Manager
  • Attach the archive with the mod that you created earlier. The archive’s name must match the one you specified in the GitHubAsset field in your mod.ini.

Now click “Publish release”, and your mod will become available through the Mod Loader’s update system!

Now that you know the basics of mod creation, let’s move on to specific examples. Check the top menu for tutorials.