SA Docs - User contributions [en]

Creating Mods

2025-10-09T19:57:43Z

Kell: Fix link

There are many ways to modify Sonic Adventure DX and Sonic Adventure 2: Battle on PC using the Mod Loaders, from basic file editing to powerful code injection.

The first step is to create your mod using the [[Mod Managers|Mod Manager]]. This will create a folder in which you will be able to put your modifications without affecting the original game files or executable.

From there, you will be able to do:

* [[File Replacement]]
* [[Texture Replacement]]
* [[Cheat Codes]]
* [[Creating a DLL Mod|Code Injection (DLL Mod)]]
* [[Mod Updates|Automatic Updates]]
* [[Mod Configuration]]

= Creating a mod =
To create a mod you need the SA Mod Manager with Sonic Adventure DX and/or Sonic Adventure 2: Battle set up.

First open SA Mod Manager with the game of your choice and click on the "Add Mod" button in the Mods tab.
[[File:Add-mod-button.png|none|509x509px]]
Then select "New Mod (For Developers)"
[[File:Add-mod-prompt.png|none|500x500px]]
This opens the mod creation form.

=== Mod Information ===
[[File:New-mod-form-info.png|none|600x600px]]
Here are the information requested (* is mandatory):

* '''Name*''': the name of the mod
* '''Author''': your nickname, it is acceptable to add co-authors separated with commas
* '''Description''': short description of the mod, it appears below the mod list
* '''Version''': a version number, preferably numbers and dots. A common way to represent version is "major.minor".
* '''DLL''': for code injection, this is the name of the DLL with the extension (e.g. "my-mod.dll")
* '''Category''': one of the categories listed or none
* '''Mod ID*''': a unique name for your mod that should not change, preferably without spaces (e.g. "game.author.modname")
* '''Include Directories''': this is used for codeless mod configuration
* '''Author URL''': link to a page of your choice, ideally showcasing your mods (GameBanana or GitHub profile for example)
* '''Source Code URL''': for code injection, link to the source code (GitHub repository for example)

This should have created a folder with a system folder (for SADX) or a gd_PC folder (for SA2B), you can use these for [[file replacement]].

=== Update information ===
[[File:New-mod-form-update.png|none|600x600px]]
This tab is for [[Mod Updates|automatic updates]], it is generally filled out later.

For GitHub:

* Author and repo is the right part of the repository URL (e.g. myself/my-mod)
* Release Asset is the name of the zip file in the release (e.g. my-mod.7z)

For GameBanana:

* Mod ID is the number in the mod's page URL (e.g. 123456)
* Mod Type shouldn't be changed (legacy)

For self hosted:

* Update URL: path to mod folder root on a remote http server
* Changelog URL: path to changelog file (plain text)

=== Cheat codes ===
[[File:New-mod-form-cheat.png|none|600x600px]]
This tab is for [[Cheat Codes|cheat codes]].

=== Dependencies ===
[[File:New-mod-form-dependencies.png|none|600x600px]]
This tab is for mod dependencies. If your mod absolutely relies on another mod to function properly, you should add it here. The mod manager will warn users if they lack a dependency.

Mod Updates

2025-10-09T19:56:20Z

Kell: Initial draft

The [[SA Mod Manager|Mod Manager]] allows you to set up automatic updates for your mod.

There are currently 3 supported services:

* Self-Hosted
* GitHub
* GameBanana

== Configuring automatic updates ==
To configure automatic updates, open the Mod Manager, right click your mod and select "Edit Mod" (or select the mod and press Ctrl+E)
[[File:Samm-edit-mode-context-menu.png|none|302x302px]]
In the edit mode window, click on the "Update Info" tab.
[[File:Samm-editmod-updateinfo.png|none|428x428px]]
Now choose the service of your choice.

=== GitHub ===
If the code of your mod is open source, you can release updates on your repository page.

* Author and repo is the right part of the repository URL (e.g. myself/my-mod)
* Release Asset is the name of the zip file in the release (e.g. my-mod.7z)

=== GameBanana ===
If you have your mod on GameBanana, you can release updates there.

* Mod ID is the number in the mod's page URL (e.g. 123456)
* Mod Type shouldn't be changed (legacy)

=== Self-Hosted ===
If none of the above, you can host the mod yourself on an HTTP server.

* Update URL: path to mod folder root on a remote http server
* Changelog URL: path to changelog file (plain text)

== Releasing an update ==
Before releasing an update, you need to '''update the manifest'''.

The manifest tells the Mod Manager which files need to be changed.

For the first time, you need to enable the developer options of the Mod Manager. Go to the "Manager Config" tab and check the "Enable Developer Options" checkbox.

1. Right click your mod, then select "Developer" >"Generate Manifest"
[[File:Samm-modcontext-generatemanifest.png|none|500x500px]]
2. If you have modified something, the Manifest Generator window will pop up showing what's changed.
[[File:Samm-manifest-generator.png|none|400x400px]]
(If some of these files won't be in the released zip, uncheck them. By default the Mod Manager automatically ignores config.ini)

3. Click "OK", you may now release the update.

{{Note|text=If you have already released your mod and are adding automatic updates now, it won't work until users update it manually once.|type=warn}}

File:Samm-manifest-generator.png

2025-10-09T19:47:51Z

Kell:

File:Samm-modcontext-generatemanifest.png

2025-10-09T19:45:51Z

Kell:

File:Samm-editmod-updateinfo.png

2025-10-09T19:24:07Z

Kell:

Creating Mods/Creating a DLL Mod

2025-10-08T22:06:24Z

Kell: Discord links

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 [https://visualstudio.microsoft.com/fr/downloads/ 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.''
[[File:Visual-studio-installer.gif|none|646x646px]]

== 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".
[[File:Visual-studio-launcher.png|none|600x600px]]
2. Select the Dynamic Link Library (DLL) template
[[File:Visual-studio-launcher-template.png|none|600x600px]]
3. Choose a name and a location for your project.
[[File:Visual-studio-launcher-createproject.png|none|600x600px]]
Navigate to the location you've chosen for the project. Visual Studio has created several project files.

* The folder where the <code>.sln</code> file is located is called the '''solution''' folder.
* The subfolder containing the <code>.vcxproj</code> and <code>.cpp</code> files is called the '''project''' folder.
The <code>.cpp</code> files are files containing C or C++ code, they will be compiled into machine code inside the DLL. The <code>.h</code> 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 [https://github.com/X-Hax/sadx-mod-loader SADX Mod Loader] or the [https://github.com/X-Hax/sa2-mod-loader SA2 Mod Loader].

2. Download the repository by clicking on the green "< > Code" button then "Download ZIP".
[[File:Github-download-repo.png|none|296x296px]]
3. Move the content of SADXModLoader/include (or SA2ModLoader/include) into your '''project''' folder.
[[File:Dll-mod-project-folder-example-sadx.png|none|502x502px]]
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...
[[File:Visual-studio-add-new-item.png|none|450x450px]]
2. Name it however you want, for example mod.cpp
[[File:Visual-studio-add-new-item-form-cpp.png|none|450x450px]]
3. Now we have our own space where we can start coding.

The first line should be:<syntaxhighlight lang="c++">
#include "pch.h"
</syntaxhighlight>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:<syntaxhighlight lang="c++">
#include "SADXModLoader.h"
</syntaxhighlight>OR<syntaxhighlight lang="c++">
#include "SA2ModLoader.h"
</syntaxhighlight>

== 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.<syntaxhighlight lang="c++">extern "C" __declspec(dllexport) ModInfo SADXModInfo = { ModLoaderVer };</syntaxhighlight>OR<syntaxhighlight lang="c++">
extern "C" __declspec(dllexport) ModInfo SA2ModInfo = { ModLoaderVer };
</syntaxhighlight>Now we can add the most important entry point, the Init function:<syntaxhighlight lang="c++">
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.
}
</syntaxhighlight>And a bunch of other optional exports:<syntaxhighlight lang="c++">
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
}
</syntaxhighlight>Here is what your source file should more or less look like:
[[File:Mod-example-dllexports.png|none|604x604px]]

== 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.
[[File:Vs-build-mode.png|none|360x360px]]
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 [https://discord.gg/gqJCF47 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.
[[File:Samm-edit-mode-context-menu.png|none|302x302px]]
[[File:Samm-edit-mod-dllname.png|none|600x600px]]
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 [https://discord.gg/gqJCF47 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 [[Working with the Disassembly|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 <code>Rings = 999;</code> 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:<syntaxhighlight lang="c++">
PrintDebug("text\n");
</syntaxhighlight>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]].

Creating Mods/Creating a DLL Mod

2025-10-08T21:52:21Z

Kell: Typos

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 [https://visualstudio.microsoft.com/fr/downloads/ 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.''
[[File:Visual-studio-installer.gif|none|646x646px]]

== 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".
[[File:Visual-studio-launcher.png|none|600x600px]]
2. Select the Dynamic Link Library (DLL) template
[[File:Visual-studio-launcher-template.png|none|600x600px]]
3. Choose a name and a location for your project.
[[File:Visual-studio-launcher-createproject.png|none|600x600px]]
Navigate to the location you've chosen for the project. Visual Studio has created several project files.

* The folder where the <code>.sln</code> file is located is called the '''solution''' folder.
* The subfolder containing the <code>.vcxproj</code> and <code>.cpp</code> files is called the '''project''' folder.
The <code>.cpp</code> files are files containing C or C++ code, they will be compiled into machine code inside the DLL. The <code>.h</code> 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 [https://github.com/X-Hax/sadx-mod-loader SADX Mod Loader] or the [https://github.com/X-Hax/sa2-mod-loader SA2 Mod Loader].

2. Download the repository by clicking on the green "< > Code" button then "Download ZIP".
[[File:Github-download-repo.png|none|296x296px]]
3. Move the content of SADXModLoader/include (or SA2ModLoader/include) into your '''project''' folder.
[[File:Dll-mod-project-folder-example-sadx.png|none|502x502px]]
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...
[[File:Visual-studio-add-new-item.png|none|450x450px]]
2. Name it however you want, for example mod.cpp
[[File:Visual-studio-add-new-item-form-cpp.png|none|450x450px]]
3. Now we have our own space where we can start coding.

The first line should be:<syntaxhighlight lang="c++">
#include "pch.h"
</syntaxhighlight>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:<syntaxhighlight lang="c++">
#include "SADXModLoader.h"
</syntaxhighlight>OR<syntaxhighlight lang="c++">
#include "SA2ModLoader.h"
</syntaxhighlight>

== 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.<syntaxhighlight lang="c++">extern "C" __declspec(dllexport) ModInfo SADXModInfo = { ModLoaderVer };</syntaxhighlight>OR<syntaxhighlight lang="c++">
extern "C" __declspec(dllexport) ModInfo SA2ModInfo = { ModLoaderVer };
</syntaxhighlight>Now we can add the most important entry point, the Init function:<syntaxhighlight lang="c++">
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.
}
</syntaxhighlight>And a bunch of other optional exports:<syntaxhighlight lang="c++">
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
}
</syntaxhighlight>Here is what your source file should more or less look like:
[[File:Mod-example-dllexports.png|none|604x604px]]

== 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.
[[File:Vs-build-mode.png|none|360x360px]]
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.
[[File:Samm-edit-mode-context-menu.png|none|302x302px]]
[[File:Samm-edit-mod-dllname.png|none|600x600px]]
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 [[Working with the Disassembly|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 <code>Rings = 999;</code> 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:<syntaxhighlight lang="c++">
PrintDebug("text\n");
</syntaxhighlight>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]].

Creating Mods

2025-10-08T21:50:11Z

Kell: Edit links

There are many ways to modify Sonic Adventure DX and Sonic Adventure 2: Battle on PC using the Mod Loaders, from basic file editing to powerful code injection.

The first step is to create your mod using the [[Mod Managers|Mod Manager]]. This will create a folder in which you will be able to put your modifications without affecting the original game files or executable.

From there, you will be able to do:

* [[File Replacement]]
* [[Texture Replacement]]
* [[Cheat Codes]]
* [[Creating a DLL Mod|Code Injection (DLL Mod)]]
* [[Mod Updates|Automatic Updates]]
* [[Mod Configuration]]

= Creating a mod =
To create a mod you need the SA Mod Manager with Sonic Adventure DX and/or Sonic Adventure 2: Battle set up.

First open SA Mod Manager with the game of your choice and click on the "Add Mod" button in the Mods tab.
[[File:Add-mod-button.png|none|509x509px]]
Then select "New Mod (For Developers)"
[[File:Add-mod-prompt.png|none|500x500px]]
This opens the mod creation form.

=== Mod Information ===
[[File:New-mod-form-info.png|none|600x600px]]
Here are the information requested (* is mandatory):

* '''Name*''': the name of the mod
* '''Author''': your nickname, it is acceptable to add co-authors separated with commas
* '''Description''': short description of the mod, it appears below the mod list
* '''Version''': a version number, preferably numbers and dots. A common way to represent version is "major.minor".
* '''DLL''': for code injection, this is the name of the DLL with the extension (e.g. "my-mod.dll")
* '''Category''': one of the categories listed or none
* '''Mod ID*''': a unique name for your mod that should not change, preferably without spaces (e.g. "game.author.modname")
* '''Include Directories''': this is used for codeless mod configuration
* '''Author URL''': link to a page of your choice, ideally showcasing your mods (GameBanana or GitHub profile for example)
* '''Source Code URL''': for code injection, link to the source code (GitHub repository for example)

This should have created a folder with a system folder (for SADX) or a gd_PC folder (for SA2B), you can use these for [[file replacement]].

=== Update information ===
[[File:New-mod-form-update.png|none|600x600px]]
This tab is for [[Creating mods/Automatic updates|automatic updates]], it is generally filled out later.

For GitHub:

* Author and repo is the right part of the repository URL (e.g. myself/my-mod)
* Release Asset is the name of the zip file in the release (e.g. my-mod.7z)

For GameBanana:

* Mod ID is the number in the mod's page URL (e.g. 123456)
* Mod Type shouldn't be changed (legacy)

For self hosted:

* Update URL: path to mod folder root on a remote http server
* Changelog URL: path to changelog file (plain text)

=== Cheat codes ===
[[File:New-mod-form-cheat.png|none|600x600px]]
This tab is for [[Cheat Codes|cheat codes]].

=== Dependencies ===
[[File:New-mod-form-dependencies.png|none|600x600px]]
This tab is for mod dependencies. If your mod absolutely relies on another mod to function properly, you should add it here. The mod manager will warn users if they lack a dependency.

Creating Mods/Creating a DLL Mod

2025-10-08T21:47:57Z

Kell: Initial draft

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 downloader the Visual Studio installer [https://visualstudio.microsoft.com/fr/downloads/ 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.''
[[File:Visual-studio-installer.gif|none|646x646px]]

== 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".
[[File:Visual-studio-launcher.png|none|600x600px]]
2. Select the Dynamic Link Library (DLL) template
[[File:Visual-studio-launcher-template.png|none|600x600px]]
3. Choose a name and a location for your project.
[[File:Visual-studio-launcher-createproject.png|none|600x600px]]
Navigate to the location you've chosen for the project. Visual Studio has created several project files.

* The folder where the <code>.sln</code> file is located is called the '''solution''' folder.
* The subfolder containing the <code>.vcxproj</code> and <code>.cpp</code> files is called the '''project''' folder.
The <code>.cpp</code> files are files containing C or C++ code, they will be compiled into machine code inside the DLL. The <code>.h</code> 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 [https://github.com/X-Hax/sadx-mod-loader SADX Mod Loader] or the [https://github.com/X-Hax/sa2-mod-loader SA2 Mod Loader].

2. Download the repository by clicking on the green "< > Code" button then "Download ZIP".
[[File:Github-download-repo.png|none|296x296px]]
3. Move the content of SADXModLoader/include (or SA2ModLoader/include) into your '''project''' folder.
[[File:Dll-mod-project-folder-example-sadx.png|none|502x502px]]
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...
[[File:Visual-studio-add-new-item.png|none|450x450px]]
2. Name it however you want, for example mod.cpp
[[File:Visual-studio-add-new-item-form-cpp.png|none|450x450px]]
3. Now we have our own space where we can start coding.

The first line should be:<syntaxhighlight lang="c++">
#include "pch.h"
</syntaxhighlight>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:<syntaxhighlight lang="c++">
#include "SADXModLoader.h"
</syntaxhighlight>OR<syntaxhighlight lang="c++">
#include "SA2ModLoader.h"
</syntaxhighlight>

== 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.<syntaxhighlight lang="c++">extern "C" __declspec(dllexport) ModInfo SADXModInfo = { ModLoaderVer };</syntaxhighlight>OR<syntaxhighlight lang="c++">
extern "C" __declspec(dllexport) ModInfo SA2ModInfo = { ModLoaderVer };
</syntaxhighlight>Now we can add the most important entry point, the Init function:<syntaxhighlight lang="c++">
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.
}
</syntaxhighlight>And a bunch of other optional exports:<syntaxhighlight lang="c++">
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
}
</syntaxhighlight>Here is what your source file should more or less look like:
[[File:Mod-example-dllexports.png|none|604x604px]]

== 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.
[[File:Vs-build-mode.png|none|360x360px]]
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.
[[File:Samm-edit-mode-context-menu.png|none|302x302px]]
[[File:Samm-edit-mod-dllname.png|none|600x600px]]
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 [[Working with the Disassembly|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 <code>Rings = 999;</code> 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:<syntaxhighlight lang="c++">
PrintDebug("text\n");
</syntaxhighlight>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]].

File:Samm-edit-mod-dllname.png

2025-10-08T21:26:58Z

Kell:

File:Samm-edit-mode-context-menu.png

2025-10-08T21:26:12Z

Kell:

File:Vs-build-mode.png

2025-10-08T21:18:57Z

Kell:

File:Mod-example-dllexports.png

2025-10-08T21:16:13Z

Kell:

File:Visual-studio-add-new-item-form-cpp.png

2025-10-08T20:16:45Z

Kell:

File:Visual-studio-add-new-item.png

2025-10-08T20:12:08Z

Kell:

File:Dll-mod-project-folder-example-sadx.png

2025-10-08T20:04:12Z

Kell:

File:Github-download-repo.png

2025-10-08T19:52:14Z

Kell:

File:Visual-studio-launcher-createproject.png

2025-10-08T19:04:54Z

Kell:

File:Visual-studio-launcher-template.png

2025-10-08T18:57:34Z

Kell:

File:Visual-studio-launcher.png

2025-10-08T18:53:08Z

Kell:

File:Visual-studio-installer.gif

2025-10-08T18:24:42Z

Kell:

Katana SDK

2025-10-08T00:10:41Z

Kell: Start chunk model

== Dreamcast SDK ==
Katana SDK (Dreamcast SDK for SEGA Library) was the official SEGA development kit that came with Dreamcast development units. The Dreamcast SDK had a number of libraries and APIs that many developers used in their games. The SDK evolved together with the console, and earlier versions of the SDK had fewer features or targeted different hardware. Updates to the SDK continued after the Dreamcast's release, and some releases were as late as 2001.

The Dreamcast SDK consisted of several subsystems:

* The '''Shinobi''' library set interfaced with the CPU, cache and memory.
* The '''Kamui''' API (low level) and the '''Ninja''' library (high level) provided access to graphics.
* The '''Manatee''' and '''Audio64''' subsystems interfaced with sound hardware.

Over the years there have been multiple SDK leaks, including parts of source code for older revisions. For modding purposes, we should focus on the Ninja library, which is used by the Sonic Adventure games.

== Common Types ==
The following types are used in Shinobi and Ninja headers:
{| class="wikitable"
!Ninja type
!C type
!Size
!Description
|-
|Sint8
|char
|1
|Signed 8-bit integer
|-
|Uint8
|unsigned char
|1
|Unsigned 8-bit integer
|-
|Sint16
|__int16
|2
|Signed 16-bit integer
|-
|Uint16
|unsigned __int16
|2
|Unsigned 16-bit integer
|-
|Sint32
|int
|4
|Signed 32-bit integer
|-
|Uint32
|unsigned int
|4
|Unsigned 32-bit integer
|-
|Bool
|unsigned int
|4
|Unsigned 32-bit integer that is either TRUE (1) or FALSE (0)
|-
|Float and Float32
|float
|4
|32-bit floating point
|-
|Float64
|double
|8
|64-bit floating point
|-
|Void
|void
|
|Pointer
|}

== Ninja Model Formats ==
The Ninja library can use two model formats, the Basic model and the Chunk model. Basic models were introduced early on, while Chunk models were added later as a format that is optimized for better performance on Dreamcast hardware. The Basic format is easier to read as text.

=== Ninja Basic Model ===
The Basic model consists of the following structs:

==== Material struct (<code>NJS_MATERIAL</code>) and Material Array ====
The material affects how the model's surface looks. It defines which texture to use, whether to use environment mapping etc.
{| class="wikitable"
!Field
!Offset
!Type
!Size
!Description
!Notes
|-
|diffuse
|0
|NJS_COLOR
|4
|Diffuse color.
|In SA1 with palette lighting, only alpha is used.
|-
|specular
|0x4
|NJS_COLOR
|4
|Specular color.
|In SA1 with palette lighting, only alpha is used. The alpha value of 0 is treated as the "ignore specular" flag.
|-
|exponent
|0x8
|Float
|4
|Specular color strength.
|
|-
|attr_texId
|0xC
|Uint32
|4
|Texture ID.
|
|-
|attrflags
|0x10
|Uint32
|4
|Material flags.
|Bits 31-29 and 28-26 are used for source and destination alpha blending instructions respectively.
|}
Size: 20 bytes (0x14).

<code>NJS_COLOR</code> is a union that can be either <code>NJS_BGRA</code>, <code>NJS_TEX</code> or <code>Uint32</code> (4 bytes).

<code>NJS_BGRA</code>is a 4-byte struct that consists of blue, green, red and alpha values ranging from 0 to 255. For example, the color <code>A255 R178 G178 B178</code> would be <code>0xFFB2B2B2</code>.

<code>NJS_TEX</code> (4 bytes) is a struct commonly used in UVs. It consists of two <code>Sint16</code> values: one for U (horizontal) and one for V (vertical). UVs used in SA1 range from 0 to 255.

The following flags can be used in <code>attrflags</code>:
{| class="wikitable"
!Flag name
!Flag bit
!Description
!Comments
|-
|NJD_FLAG_IGNORE_LIGHT
|BIT_25
|Ignore lighting.
|
|-
|NJD_FLAG_USE_FLAT
|BIT_24
|Flat lighting.
|Has no effect when palette-based lighting in SA1 is used.
|-
|NJD_FLAG_DOUBLE_SIDE
|BIT_23
|Double-sided mesh.
|May be used for collision.
|-
|NJD_FLAG_USE_ENV
|BIT_22
|Enable environment mapping.
|
|-
|NJD_FLAG_USE_TEXTURE
|BIT_21
|Enable texture.
|
|-
|NJD_FLAG_USE_ALPHA
|BIT_20
|Enable transparency.
|
|-
|NJD_FLAG_IGNORE_SPECULAR
|BIT_19
|Disable specular lighting.
|Used for specular palette selection in palette-based lighting in SA1.
|-
|NJD_FLAG_FLIP_U
|BIT_18
|Flip Us.
|
|-
|NJD_FLAG_FLIP_V
|BIT_17
|Flip Vs.
|
|-
|NJD_FLAG_CLAMP_U
|BIT_16
|Clamp Us.
|
|-
|NJD_FLAG_CLAMP_V
|BIT_15
|Clamp Vs.
|
|-
|NJD_FLAG_USE_ANISOTROPIC
|BIT_12
|Enable anisotropic filtering,
|Unused.
|-
|NJD_FLAG_PICK
|BIT_7
|"Pick status"
|Unused.
|}
Alpha modes can be as follows:
{| class="wikitable"
!Source alpha
{| class="wikitable"
!Name
!Value
!Description
|-
|NJD_SA_ZERO
|0
|Zero.
|-
|NJD_SA_ONE
|BIT_29
|One.
|-
|NJD_SA_OTHER
|BIT_30
|Other color.
|-
|NJD_SA_INV_OTHER
|<nowiki>BIT_30 | BIT_29</nowiki>
|Inverse other color.
|-
|NJD_SA_SRC
|BIT_31
|Source alpha.
|-
|NJD_SA_INV_SRC
|<nowiki>BIT_31 | BIT_29</nowiki>
|Inverse source alpha.
|-
|NJD_SA_DST
|<nowiki>BIT_31 | BIT_30</nowiki>
|Destination alpha.
|-
|NJD_SA_INV_DST
|<nowiki>BIT_31 | BIT_30 | BIT_29</nowiki>
|Inverse destination alpha.
|}
!Destination alpha
{| class="wikitable"
!Name
!Value
!Description
|-
|NJD_DA_ZERO
|0
|Zero.
|-
|NJD_DA_ONE
|BIT_26
|One.
|-
|NJD_DA_OTHER
|BIT_27
|Other color.
|-
|NJD_DA_INV_OTHER
|<nowiki>BIT_27 | BIT_26</nowiki>
|Inverse other color.
|-
|NJD_DA_SRC
|BIT_28
|Source alpha.
|-
|NJD_DA_INV_SRC
|<nowiki>BIT_28 | BIT_26</nowiki>
|Inverse source alpha.
|-
|NJD_DA_DST
|<nowiki>BIT_28 | BIT_27</nowiki>
|Destination alpha.
|-
|NJD_DA_INV_DST
|<nowiki>BIT_28| BIT_27 |BIT_26</nowiki>
|Inverse destination alpha.
|}
|}
Basic models' materials are stored in arrays of <code>NJS_MATERIAL</code>.<syntaxhighlight lang="cpp">
NJS_MATERIAL matlist_004451A8[] = {
{ { 0xFFFFFFFF }, { 0xFFFFFFFF }, 11, 14, NJD_D_100 | NJD_FILTER_BILINEAR | NJD_FLAG_CLAMP_V | NJD_FLAG_CLAMP_U | NJD_FLAG_IGNORE_SPECULAR | NJD_FLAG_USE_TEXTURE | NJD_DA_INV_SRC | NJD_SA_SRC },
{ { 0xFFB2B2B2 }, { 0xFFFFFFFF }, 11, 13, NJD_D_100 | NJD_FILTER_BILINEAR | NJD_FLAG_CLAMP_V | NJD_FLAG_CLAMP_U | NJD_FLAG_IGNORE_SPECULAR | NJD_FLAG_USE_ALPHA | NJD_FLAG_USE_TEXTURE | NJD_DA_INV_SRC | NJD_SA_SRC },
{ { 0xFFB2B2B2 }, { 0xFFFFFFFF }, 11, 15, NJD_D_100 | NJD_FILTER_BILINEAR | NJD_FLAG_CLAMP_V | NJD_FLAG_CLAMP_U | NJD_FLAG_IGNORE_SPECULAR | NJD_FLAG_USE_TEXTURE | NJD_DA_INV_SRC | NJD_SA_SRC }
};
</syntaxhighlight>

==== Poly Array ====
The poly array in an array of <code>Sint16</code> that lists the model's primitives (polygons). It is commonly formatted with the number of vertices (points) followed by vertex indices. The indices are used to pick the specific vertices from the model's vertices array.

Here is an example of a polys array. The <code>4</code> in each new line indicates the number of vertices in the surface, and the following four values are vertex indices.<syntaxhighlight lang="cpp">
Sint16 poly_0000002C[] = {
4, 13, 12, 5, 4,
4, 9, 8, 1, 0,
4, 11, 10, 3, 2,
4, 15, 14, 7, 6
};
</syntaxhighlight>The number of vertices can be ORd with <code>0x8000</code>, which indicates a flipped surface. TODO: Confirm this.

==== UV Array ====
The UV array is an array of <code>NJS_TEX</code>. UVs determine how the texture is applied to the model's surface. For exampled, bigger UV values will make the texture "zoomed in", adding values to U will make the texture offset horizontally etc. UVs are per-polygon.<syntaxhighlight lang="cpp">
NJS_TEX uv_000003A4[] = {
{ 130, 145 },
{ 212, 225 },
{ 124, 230 },
// And so on...
};
</syntaxhighlight>

==== Vertex Color Array ====
This is an array of <code>NJS_COLOR</code> that determines the colors of the model's vertices. Vertex colors are used per-polygon, not per-vertex.<syntaxhighlight lang="cpp">
NJS_COLOR vcolor_0000003C[] = {
{ 0xFFFFFFDF },
{ 0xFFFFFFFF },
{ 0xFFFFDFBF },
{ 0xFFFFFFFF },
{ 0xFFFFDFBF },
// And so on...
};
</syntaxhighlight>

==== Polynormal Array ====
Normals determine the model's lighting and environment mapping distortion. Normals can be specified per-vertex or por-polygon. Almost no models in SA1 use per-poly normals (polynormals), with the exception of Tails' tails and Sonic's stretchy shoes. When polynormals are used, this is the array they are expected to be in.

Normals and polynormals are defined as arrays of <code>NJS_VECTOR</code>. <code>NJS_VECTOR</code> consists of three floats for X, Y and Z.<syntaxhighlight lang="cpp">
NJS_VECTOR polynormal_007383D8[] = {
{ 0 },
{ 0 },
{ 0 },
{ 0 },
{ 0 },
{ 0 }
};
</syntaxhighlight>

==== Polygon Attribute Array ====
This is an array of <code>Uint32</code> containing polygon-specific attributes. It is not used in Sonic Adventure games.

==== Meshset Struct (<code>NJS_MESHSET</code>) and Meshset Array ====
Multiple connected polygons form meshes. The <code>NJS_MESHSET</code> struct defines a single mesh.
{| class="wikitable"
!Field
!Offset
!Type
!Size
!Description
!Notes
|-
|type_matId
|0
|Uint16
|2
|Diffuse color.
|Bits 0-13 are material id (0-4095) in the material array.
Bits 14-15 are meshset type bits (see below).
|-
|nbMesh
|0x2
|Uint16
|2
|Number of meshes.
|
|-
|*meshes
|0x4
|Sint16*
|4
|Pointer to the poly array.
|
|-
|*attrs
|0x8
|Uint32*
|4
|Pointer to the poly attribute array.
|Unused in SA games.
|-
|*normals
|0xC
|NJS_VECTOR*
|4
|Pointer to the polynormal array.
|Almost never used.
|-
|*vertcolor
|0x10
|NJS_COLOR*
|4
|Pointer to the vertex color array.
|Unused in SA1 DC, used in SADX.
|-
|*vertuv
|0x14
|NJS_TEX*
|4
|Pointer to the UV array.
|
|-
|buffer
|0x18
|void
|4
|Pointer to the Direct3D mesh buffer.
|Always null.
SADX PC 2004, SADX X360 and SADX PS3 only.
|}
In the 2004 PC port of SADX this struct contains an extra field for the mesh buffer (<code>buffer</code>). This version of the struct is used in the PC, X360 and PS3 versions.

SA2 and Gamecube versions of SADX use the original struct without the extra field.

In [[Mod Loaders|SADX Mod Loader]] headers the original Ninja version is <code>NJS_MESHSET</code>, and the one with the extra field is <code>NJS_MESHSET_SADX</code>.

In the [[SADX X360 Prototype with Symbols|SADX X360 prototype with symbols]], the one with the extra field is <code>NJS_MESHSET</code>, and the original Ninja version is <code>NJS_MESHSET_OLD</code>.

The size of the original <code>NJS_MESHSET</code> is 24 (<code>0x18</code>) bytes, and the size of <code>NJS_MESHSET_SADX</code> is 28 (<code>0x1C</code>) bytes.

Meshset type bits are as follows:
{| class="wikitable"
!Meshset type
!Value
!Description
|-
|NJD_MESHSET_3
|0x0000
|Default mesh type (three vertices). Technically identical to <code>NJD_MESHSET_TRIMESH</code>.
|-
|NJD_MESHSET_4
|0x4000
|Quad (four vertices).
|-
|NJD_MESHSET_N
|0x8000
|N-Gon (custom number of vertices).
|-
|NJD_MESHSET_TRIMESH
|0xC000
|Trimesh, the most common meshset type.
|-
|NJS_MESHSET_MASK
|0xC000
|Meshset type mask.
|}
To get the material ID from the <code>type_matId</code> field in your code, use <code>type_matId & ~NJD_MESHSET_MASK</code>. To get the mesh type, use <code>type_matId >> 0xE</code>.

Meshes in Basic models are stored in arrays of NJS_MESHSET:<syntaxhighlight lang="cpp">
NJS_MESHSET_SADX meshlist_00000294[] = {
{ NJD_MESHSET_TRIMESH | 0, 9, poly_00000044, NULL, NULL, NULL, uv_00000128, NULL },
{ NJD_MESHSET_TRIMESH | 1, 10, poly_000000A4, NULL, NULL, NULL, uv_000001C4, NULL },
{ NJD_MESHSET_TRIMESH | 2, 3, poly_00000108, NULL, NULL, NULL, uv_00000264, NULL }
};

</syntaxhighlight>

==== Vertex Array ====
The model's vertices are in an array of <code>NJS_POINT3</code> (<code>NJS_VECTOR</code> in Mod Loader headers).<syntaxhighlight lang="cpp">NJS_VECTOR vertex_00000ADC[] = {
{ 0, 26.04398f, 0 },
{ 3.602116f, 18.50802f, 0 },
{ 1.801057f, 18.50802f, -3.119523f },
{ -1.801059f, 18.50802f, -3.119523f },
// And so on...
};</syntaxhighlight>

==== Normal Array ====
The model's normals are in an array of <code>NJS_VECTOR</code>.<syntaxhighlight lang="cpp">
NJS_VECTOR normal_00000D28[] = {
{ 0, 1, 0 },
{ 0.902229f, 0.431257f, 0 },
{ 0.451115f, 0.431256f, -0.781354f },
{ -0.451115f, 0.431256f, -0.781354f },
// And so on...
}

</syntaxhighlight>

==== Model Struct (<code>NJS_MODEL</code>) ====
The Model struct combines all the things mentioned above and adds model center coordinates and radius.
{| class="wikitable"
!Field
!Offset
!Type
!Size
!Description
!Notes
|-
|*points
|0
|NJS_POINT3*
|4
|Pointer to the vertex array.
|
|-
|*normals
|0x4
|NJS_VECTOR*
|4
|Pointer to the normal array.
|
|-
|nbPoint
|0x8
|Sint32
|4
|Number of vertices.
|
|-
|*meshsets
|0xC
|NJS_MESHSET*
|4
|Pointer to the meshset array.
|
|-
|*mats
|0x10
|NJS_MATERIAL*
|4
|Pointer to the material array.
|
|-
|nbMeshset
|0x14
|Uint16
|2
|Number of meshsets.
|
|-
|nbMat
|0x16
|Uint16
|2
|Number of materials.
|
|-
|center
|0x18
|NJS_POINT3
|12
|Model center.
|
|-
|r
|0x24
|Float
|4
|Model radius.
|
|-
|*buffer
|0x28
|void
|4
|Pointer to the Direct3D mesh buffer.
|Always null.
SADX PC 2004, SADX X360 and SADX PS3 only.
|}
In the 2004 PC port of SADX this struct contains an extra field for the mesh buffer (<code>buffer</code>). This version of the struct is used in the PC, X360 and PS3 versions.

SA2 and Gamecube versions of SADX use the original struct without the extra field.

In [[Mod Loaders|SADX Mod Loader]] headers the original Ninja version is <code>NJS_MODEL</code>, and the one with the extra field is <code>NJS_MODEL_SADX</code>.

In the [[SADX X360 Prototype with Symbols|SADX X360 prototype with symbols]], the one with the extra field is <code>NJS_MODEL</code>, and the original Ninja version is <code>NJS_MODEL_OLD</code>.

The size of the original <code>NJS_MODEL</code> is 40 (<code>0x28</code>) bytes, and the size of <code>NJS_MODEL_SADX</code> is 44 (<code>0x2C</code>) bytes.

In old modding terminology, the Model struct was referred to as the "attach" struct. You can still see this label in SA Tools' C exports.

==== Object Struct (<code>NJS_OBJECT</code>) ====
Ninja models use a node-like hierarchy, and the Object struct represents a single node. The size of NJS_OBJECT is 52 (<code>0x34</code>) bytes.
{| class="wikitable"
!Field
!Offset
!Type
!Size
!Description
!Notes
|-
|evalflags
|0
|Uint32
|4
|Model evaluation flags (see below).
|
|-
|*model
|0x4
|NJS_MODEL*
|4
|Pointer to the <code>NJS_MODEL</code>.
|
|-
|pos
|0x8
|Float[3]
|12
|Model position (X, Y, Z).
|
|-
|ang
|0x14
|Angle[3]
|12
|Model rotation (X, Y, Z).
|Angle is the same as Sint32.
|-
|scl
|0x20
|Float[3]
|12
|Model scale (X, Y, Z).
|
|-
|*child
|0x2C
|NJS_OBJECT*
|4
|Pointer to the child model in the hierarchy.
|
|-
|*sibling
|0x30
|NJS_OBJECT*
|4
|Pointer to the sibling model in the hierarchy.
|
|}
The following evaluation flags can be used:
{| class="wikitable"
!Name
!Flag bits
!Description
|-
|NJD_EVAL_UNIT_POS
|BIT_0
|Ignore the model's position.
|-
|NJD_EVAL_UNIT_ANG
|BIT_1
|Ignore the model's rotation.
|-
|NJD_EVAL_UNIT_SCL
|BIT_2
|Ignore the model's scale.
|-
|NJD_EVAL_HIDE
|BIT_3
|Do not render the model.
|-
|NJD_EVAL_BREAK
|BIT_4
|Node is the end of the hierarchy (do not check children).
|-
|NJD_EVAL_ZXY_ANG
|BIT_5
|Inverted order of rotation.
|-
|NJD_EVAL_SKIP
|BIT_6
|Do not animate (ignore) this node.
|-
|NJD_EVAL_SHAPE_SKIP
|BIT_7
|Do not animate (ignore) this node in shape animations.
|-
|NJD_EVAL_CLIP
|BIT_8
|If this node is clipped, do not clip child nodes.
|-
|NJD_EVAL_MODIFIER
|BIT_9
|The node has a modifier volume.
|}

=== Ninja Chunk Model ===
The chunk model format is a sequence of instructions called chunks. A chunk can modify the rendering context or supply vertex and strip data. This is more efficient as vertex data is preformatted and the rendering context is less often modified. However, it is a bit more involving to parse.

==== Chunk Model Structure ====
{| class="wikitable"
!Field
!Offset
!Type
!Size
!Description
!Notes
|-
|vlist
|0
|Sint32*
|4
|"Vertex" chunk list
|Only for vertex chunks, separate for 32bit access + easier preprocessing
|-
|plist
|4
|Sint16*
|4
|"Polygon" chunk list
|Remaining chunk types
|-
|center
|8
|NJS_VECTOR
|12
|Model center
|
|-
|r
|20
|Float
|4
|Model radius
|
|}
The chunk lists shall be parsed continuously until the "end" chunk (255) is reached.

==== Vertex chunk list ====
The library first parses the vertex chunk list. A vertex chunk contains a list of vertices. Each vertex will be placed in an intermediate vertex buffer that will be used for strip indices.

A vertex chunk is composed of a header, followed by data:
{| class="wikitable"
! colspan="2" |Header (32 bits)
! colspan="2" |Vertex data information (32 bits)
! rowspan="2" |Data
|-
!Type (0-15)
!Next chunk (16-31)
!Vertex count (0-15)
!Index offset (16-31)
|-
|Vertex type
|Chunk size - 1
|Number of vertices
|Start position in intermediate vbuffer
|Depends on type
|}
The data depends on the vertex chunk type:
{| class="wikitable"
!Vertex chunk
!Components
!Vertex stream
!Comment
|-
|NJD_CV_SH
|Position
|x, y, z,1.0f, ...
|SH4 optimized (aligned)
|-
|NJD_CV_VN_SH
|Position + Normal
|x, y, z,1.0f, nx, ny, ny, 0.0f, ...
|SH4 optimized (aligned)
|-
|NJD_CV
|Position
|x, y, z, ...
|
|-
|NJD_CV_D8
|Position + Diffuse
|x, y, z, D8888, ...
|
|-
|NJD_CV_UF
|Position + UserFlag
|x, y, z, UF32
|
|-
|NJD_CV_NF
|Position + NinjaFlag
|x, y, z, NF32
|Used for weights
|-
|NJD_CV_S5
|Position + Diffuse + Specular
|x, y, z, D565, S565, ...
|
|-
|NJD_CV_S4
|Position + Diffuse + Specular
|x, y, z, D4444, S565, ...
|
|-
|NJD_CV_IN
|Position + Diffuse + Specular
|x, y, z, D16, S16, ...
|
|-
|NJD_CV_VN
|Position + Normal
|x, y, z, nx, ny, nz, ...
|
|-
|NJD_CV_VN_D8
|Position + Normal + Diffuse
|x, y, z, nx, ny, nz, D8888, ...
|
|-
|NJD_CV_VN_UF
|Position + Normal + Diffuse + UserFlag
|x, y, z, nx, ny, nz, D8888, UF32, ...
|
|-
|NJD_CV_VN_NF
|Position + Normal + Diffuse + NinjaFlag
|x, y, z, nx, ny, nz, D8888, NF32, ...
|Used for weights
|-
|NJD_CV_VN_S5
|Position + Normal + Diffuse + Specular
|x, y, z, nx, ny, nz, D565, S565, ...
|
|-
|NJD_CV_VN_S4
|Position + Normal + Diffuse + Specular
|x, y, z, nx, ny, nz, D4444, S565, ...
|
|-
|NJD_CV_VN_IN
|Position + Normal + Diffuse + Specular
|x, y, z, nx, ny, nz, D16, S16, ...
|
|-
|NJD_CV_VNX
|Position + Normal
|x, y, z, nx10, ny10, nz(10), pad, ...
|
|-
|NJD_CV_VNX_D8
|Position + Normal + Diffuse
|x, y, z, nx10, ny10, nz(10), pad, D8888, ...
|
|-
|NJD_CV_VNX_UF
|Position + Normal + UserFlag
|x, y, z, nx10, ny10, nz(10), pad, UF32, ...
|
|}
Note that the library only supports '''one chunk type per model'''.

The data is continuous until the end chunk is reached (255).

==== Polygon chunk list ====
The library then processes the polygon chunk list, which consists of chunks that specify how to render the vertices.

These chunks follow the following structure:
{| class="wikitable"
! colspan="2" |Header (16 bits)
! rowspan="2" |''Next chunk, optional''
! rowspan="2" |''Data, optional''
|-
!Type (0-7)
!Headbits (8-15)
|-
|Vertex type
|Depends on type
|''Chunk size - 2''
|''Depends on type''
|}
Chunks are continuous until the end chunk is reached (255).

There are 5 categories of polygon chunks:

* '''Bits''' chunk (fixed 16 bit size) : some rendering attributes
* '''Tiny''' chunks (fixed 32 bit size) : texture ID
* '''Material''' chunks : diffuse color, ambient color, specular color, blending flags
* '''Volume''' chunks : collision/modifier volumes
* '''Strip''' chunks : strip data

===== Bits chunks =====
{| class="wikitable"
! colspan="2" |Header (16 bits)
|-
!Type (0-7)
!Headbits (8-15)
|}
The next chunk is directly after.

...

===== Tiny chunks =====
{| class="wikitable"
! colspan="2" |Header (16 bits)
! rowspan="2" |Data (16 bits)
|-
!Type (0-7)
!Headbits (8-15)
|}
The next chunk is directly after.

...

===== Material chunks =====
{| class="wikitable"
! colspan="2" |Header (16 bits)
! rowspan="2" |Next chunk
! rowspan="2" |Data
|-
!Type (0-7)
!Headbits (8-15)
|}
...

===== Volume chunks =====
...

===== Strip chunks =====
A strip chunk renders a triangle strip using vertices from the intermediate buffer generated by the vertex chunk list.

It can contain additional information, such as UV coordinates, vertex color or user data.

The chunk structure is as follows:
{| class="wikitable"
! colspan="2" |Header (16 bits)
! rowspan="2" |Next chunk
! colspan="2" |Strip data information
! rowspan="2" |Data, optional
|-
!Type (0-7)
!Headbits (8-15)
!Strip count (0-13)
!User area size (14-15)
|-
|Strip type
|Rendering flags
|Chunk size - 2
|Number of strips
|NJD_UFO_0 = 0 bits
NJD_UFO_1 = 16 bits
NJD_UFO_2 = 32 bits
|Depends on type
|}
The data itself follows this structure:
{| class="wikitable"
! colspan="2" |Strip header
! colspan="7" |Strip stream
|-
|Length (0-14)
|Winding flag (15)
! colspan="2" |First element
! colspan="2" |Second element
! colspan="3" |Element N ....
|-
|Number of vertices
|If set, reverse order
|Index
|Data
|Index
|Data
|Index
|Data
|''User area (optional)''
|}
<nowiki>*</nowiki> The user area is per-triangle, so it only starts at the third element, from there every other vertex is another triangle.

The data stream depends on the strip type:
{| class="wikitable"
!Strip chunk
!Components
!Data stream
|-
|NJD_CS
|None
|index
|-
|NJD_CS_UVN
|UV (255 = 1.0)
|index, u, v
|-
|NJD_CS_UVH
|UV (1023 = 1.0)
|index, u, v
|-
|NJD_CS_VN
|Normal
|index, nx, ny, nz
|-
|NJD_CS_UVN_VN
|UV (255), normal
|index, u, v, nx, ny, nz
|-
|NJD_CS_UVH_VN
|UV (1023), normal
|index, u, v, nx, ny, nz
|-
|NJD_CS_D8
|Diffuse
|index, ar, gb
|-
|NJD_CS_UVN_D8
|UV (255), diffuse
|index, u, v, ar, gb
|-
|NJD_CS_UVH_D8
|UV (1023), diffuse
|index, u, v, ar, gb
|-
|NJD_CS_2
|None
|index
|-
|NJD_CS_UVN2
|UV (255)
|index, u, v
|-
|NJD_CS_UVH2
|UV (1023)
|index, u, v
|}

=== Ninja Motions and Actions ===

== Ports of Ninja to Other Platforms ==

Creating Mods/Cheat Codes

2025-10-05T20:32:31Z

Kell: Add section links and fix minor mistake

The Sonic Adventure DX and Sonic Adventure 2: Battle Mod Loaders allow you to edit the game's code and memory without resorting to a DLL mod. The syntax is similar to cheat code for consoles, such as Action Replay code. This is useful for simple modifications where a DLL would be overkill.

== Creating a cheat code ==

=== Using the SA Mod Manager ===
First edit your mod by right clicking it and clicking on Edit mod, or by selecting it and pressing Ctrl + E.
[[File:Samm-editmod-context.png|none|508x508px]]
Then go in the "Codes" tab and click on "New code".
[[File:Samm-editmode-codestab.png|none|502x502px]]
You are now in the cheat code editor :
[[File:Samm-editmode-codeeditor.png|none|500x500px]]
Fields are:

* '''Name*''': short name for the cheat code.
* '''Author''': author(s) of the cheat code.
* '''Type*''': "Code" will make your cheat code run every frame, "Patch" will make it run once at start up.
* '''Is Required''': if checked, the cheat code will be forced on and won't appear in the Mod Manager "Codes" tab.
* '''Description''': description of the cheat code.

To write the code, see [[Creating mods/Cheat Codes#Writing a cheat code|Writing a cheat code]].

When finished, save the cheat code, enable the mod and click "Save" to compile the cheat codes.

=== Using notepad or another editor ===
In your mod folder, create an empty text file, preferably called "Codes.lst".

Then open your mod.ini to add the following line:
Codes=Codes.lst
Save your mod.ini, then open Codes.lst with the editor of your choice.

Here is the structure of a cheat code:
[Type] [Name] (Required)
[Code]
Author [Author]
Category [Category]
Description [Description]
Fields are:

* '''Type*''': "Code" will make your cheat code run every frame, "Patch" will make it run once at start up.
* '''Name*''': short name for the cheat code.
* '''Required''': the cheat code will be forced on and won't appear in the Mod Manager "Codes" tab.
* '''Code''': the actual code, see [[Creating mods/Cheat Codes#Writing a cheat code|Writing a cheat code]].
* '''Author''', '''Category''' and '''Description''' are optional.

Once finished, save the Codes.lst file, open the Mod Manager, enable the mod if not already and click "Save" to compile the cheat codes.

== Writing a cheat code ==
See the full [https://github.com/X-Hax/sadx-mod-loader/blob/master/doc/codes.md documentation].

=== Memory operations ===
Each line follows the following format:
[opcode] [address] [value] (repeat count)
The memory operations you can use are:
{| class="wikitable"
|+
!Operation
!Opcodes
!Description
!C equivalent
|-
|Write
|write8
write16
write32
writefloat
|Write value at address
|*address = value;
|-
|Add
|add8
add16
add32
addfloat
|Add value at address
|*address += value;
|-
|Subtract
|sub8
sub16
sub32
subfloat
|Subtract value at address
|*address -= value;
|-
|Multiply
|mulu8
mulu16
mulu32
muls8
muls16
muls32
mulfloat
|Multiply value at address
|*address *= value;
|-
|Divide
|divu8
divu16
divu32
divs8
divs16
divs32
divfloat
|Divide value at address
|*address /= value;
|}

=== Bitwise operations ===
These are more advanced operations as they operate on the bit level.
[opcode] [address] [value] (repeat count)
{| class="wikitable"
!Operation
!Opcodes
!Description
!C equivalent
|-
|Shift left
|shl8
shl16
shl32
|Shift bits at address to the left
|*address <<= value;
|-
|Shift right
|shrs8
shrs16
shrs32
shru8
shru16
shru32
|Shift bits at address to the right
|*address >>= value;
|-
|AND
|and8
and16
and32
|AND bits at address
Often used to remove flags
|*address &= value;
|-
|OR
|or8
or16
or32
|OR bits at address
Often used to add flags
|<nowiki>*address |= value;</nowiki>
|-
|XOR
|xor8
xor16
xor32
|XOR bits at address
|*address ^= value;
|-
|Rotate left
|rol8
rol16
rol32
|Rotate bits left
|
|-
|Rotate right
|ror8
ror16
ror32
|Rotate bits right
|
|}

=== Special operations ===
[opcode] [address] [value]
{| class="wikitable"
!Operation
!Opcodes
!Description
!C equivalent
|-
|Write NOP
|writenop
|Write NOP opcode at address N times
Often used to remove a call (writenop address 5)
|WriteData<value>((void*)address, 0x90);
|-
|Write JUMP
|writejump
|Write a JUMP opcode at address followed by rel jump address
Often used to redirect a function to another
|WriteJump((void*)address, (void*)value);
|-
|Write CALL
|writecall
|Write a CALL opcode at address followed by rel call address
Often used to replace a call to a function with another
|WriteCall((void*)address, (void*)value);
|}

=== Conditions ===
The cheat code system supports conditions and branching.
[condition opcode] [address] [compared value] (repeat count)
...
''else
...''
endif
Here are the conditions available:
{| class="wikitable"
!Operation
!Opcodes
!Description
!C equivalent
|-
|If equal
|ifeq8
ifeq16
ifeq32
ifeqfloat
|Check if value at address is equal
|if (*address == value)
|-
|If not equal
|ifne8
ifne16
ifne32
ifnefloat
|Check if value at address is different
|if (*address != value)
|-
|If lower
|ifltu8
ifltu16
ifltu32
iflts8
iflts16
iflts32
ifltfloat
|Check if value at address is lower
|if (*address < value)
|-
|If lower or equal
|ifltequ8
ifltequ16
ifltequ32
iflteqs8
iflteqs16
iflteqs32
iflteqfloat
|Check if value at address is lower or equal
|if (*address <= value)
|-
|If greater
|ifgtu8
ifgtu16
ifgtu32
ifgts8
ifgts16
ifgts32
ifgtfloat
|Check if value at address is greater
|if (*address > value)
|-
|If greater or equal
|ifgtequ8
ifgtequ16
ifgtequ32
ifgteqs8
ifgteqs16
ifgteqs32
ifgteqfloat
|Check if value at address is greater or equal
|if (*address >= value)
|-
|If mask
|ifmask8
ifmask16
ifmask32
|Check if value at address has specific bits
Often used to check flags
|if ((*address & value) == value)
|-
|If key pressed
|ifkbkey [keycode]
|Check if keyboard key is pressed
See Windows [https://learn.microsoft.com/fr-fr/windows/win32/inputdev/virtual-key-codes virtual key codes].
|if (GetAsyncKeyState(value))
|}

=== Registers ===
The cheat code system has 16 registers available, you can use them as variables.

Most opcodes have a register equivalent, simply add "reg" before the type (writereg8, divregu8, ifmaskreg8...)
[opcode] [address] [value] (repeat count)
{| class="wikitable"
!Operation
!Opcodes
!Description
!C equivalent
|-
|Read
|readreg8
readreg16
readreg32
|Read value at address into register
|reg[value] = *address;
|}

=== Values format ===
Values can be in decimal, hexadecimal, or float format.
{| class="wikitable"
!Type
!Example
|-
|Decimal
|10
|-
|Hexadecimal
|0xA
|-
|Float
|10.0
|}
Repeat count should be preceded with x.

Addresses can be in hexadecimal or pointer chain format.
{| class="wikitable"
!Type
!Example
|-
|Hexadecimal
|03B0F0FC
|-
|Pointer chain
|<nowiki>p03B42E30|20|C0|6</nowiki>
|}

== Examples ==
These examples use Sonic Adventure DX (2004) addresses.

=== Write to memory ===
write16 03B0F0E4 999
This forces the ring count to 999 every frame.

* <code>write16</code> means that it will write to 2 bytes. This is because the Rings variable in SADX is a 2 bytes (a "short" or "Sint16" in c++).
* <code>03B0F0E4</code> is the hexadecimal address of the Rings variable
* <code>999</code> is the 2-byte values that is going to be written at the provided address.

writefloat 03B0F0FC 1.0
This forces the gravity to be upside down.

* <code>writefloat</code> means that the edited value is a (single precision) floating point value.
* <code>03B0F0FC</code> is the hexadecimal address of the up gravity direction.
* <code>1.0</code> is a float value that we will be writing, 1.0 for up gravity means upward.

=== Conditions ===
ifltu32 03B0F14C 9999
add32 03B0F14C 1
endif
This increased the score counter every frame until it reaches 9999.

* <code>ifltu32</code> means "if value is inferior to3 (9999 here)
* <code>03B0F14C</code> is the level score.

ifmask32 03B0E9D0 0x10
mulfloat 03B0F0FC 1.05
endif
This increases the gravity when you press d-pad up.

* <code>ifmask32</code> means we are checking if the value at address has specific bits
* <code>03B0E9D0</code> is the hexadecimal address of the pressed buttons variable, each bit corresponds to a button.
* <code>0x10</code> is the bit mask for d-pad up.

=== More examples ===
Check the [https://github.com/X-Hax/sadx-mod-loader/blob/master/data/Codes.lst SADX Mod Loader cheat codes] and [https://github.com/X-Hax/sa2-mod-loader/blob/master/data/Codes.lst SA2 Mod Loader cheat codes] for more examples.

== Resources ==
To get addresses:

* Check the RAM editing pages on sonicretro ([https://info.sonicretro.org/SCHG:Sonic_Adventure_DX:_PC/RAM_Editing SADX]/[https://info.sonicretro.org/SCHG:Sonic_Adventure_2_(PC)/RAM_Editing SA2PC])
* Start disassembling the game with IDA Pro or Ghidra
* Ask us for help on Discord

Creating Mods/Cheat Codes

2025-10-05T20:27:43Z

Kell: Initial draft

The Sonic Adventure DX and Sonic Adventure 2: Battle Mod Loaders allow you to edit the game's code and memory without resorting to a DLL mod. The syntax is similar to cheat code for consoles, such as Action Replay code. This is useful for simple modifications where a DLL would be overkill.

== Creating a cheat code ==

=== Using the SA Mod Manager ===
First edit your mod by right clicking it and clicking on Edit mod, or by selecting it and pressing Ctrl + E.
[[File:Samm-editmod-context.png|none|508x508px]]
Then go in the "Codes" tab and click on "New code".
[[File:Samm-editmode-codestab.png|none|502x502px]]
You are now in the cheat code editor :
[[File:Samm-editmode-codeeditor.png|none|500x500px]]
Fields are:

* '''Name*''': short name for the cheat code.
* '''Author''': author(s) of the cheat code.
* '''Type*''': "Code" will make your cheat code run every frame, "Patch" will make it run once at start up.
* '''Is Required''': if checked, the cheat code will be forced on and won't appear in the Mod Manager "Codes" tab.
* '''Description''': description of the cheat code.

To write the code, see Writing a cheat code.

When finished, save the cheat code, enable the mod and click "Save" to compile the cheat codes.

=== Using notepad or another editor ===
In your mod folder, create an empty text file, preferably called "Codes.lst".

Then open your mod.ini to add the following line:
Codes=Codes.lst
Save your mod.ini, then open Codes.lst with the editor of your choice.

Here is the structure of a cheat code:
[Type] [Name] (Required)
[Code]
Author [Author]
Category [Category]
Description [Description]
Fields are:

* '''Type*''': "Code" will make your cheat code run every frame, "Patch" will make it run once at start up.
* '''Name*''': short name for the cheat code.
* '''Required''': the cheat code will be forced on and won't appear in the Mod Manager "Codes" tab.
* '''Code''': the actual code, see Writing a cheat code.
* '''Author''', '''Category''' and '''Description''' are optional.

Once finished, save the Codes.lst file, open the Mod Manager, enable the mod if not already and click "Save" to compile the cheat codes.

== Writing a cheat code ==
See the full [https://github.com/X-Hax/sadx-mod-loader/blob/master/doc/codes.md documentation].

=== Memory operations ===
Each line follows the following format:
[opcode] [address] [value] (repeat count)
The memory operations you can use are:
{| class="wikitable"
|+
!Operation
!Opcodes
!Description
!C equivalent
|-
|Write
|write8
write16
write32
writefloat
|Write value at address
|*address = value;
|-
|Add
|add8
add16
add32
addfloat
|Add value at address
|*address += value;
|-
|Subtract
|sub8
sub16
sub32
subfloat
|Subtract value at address
|*address -= value;
|-
|Multiply
|mulu8
mulu16
mulu32
muls8
muls16
muls32
mulfloat
|Multiply value at address
|*address *= value;
|-
|Divide
|divu8
divu16
divu32
divs8
divs16
divs32
divfloat
|Divide value at address
|*address /= value;
|}

=== Bitwise operations ===
These are more advanced operations as they operate on the bit level.
[opcode] [address] [value] (repeat count)
{| class="wikitable"
!Operation
!Opcodes
!Description
!C equivalent
|-
|Shift left
|shl8
shl16
shl32
|Shift bits at address to the left
|*address <<= value;
|-
|Shift right
|shrs8
shrs16
shrs32
shru8
shru16
shru32
|Shift bits at address to the right
|*address >>= value;
|-
|AND
|and8
and16
and32
|AND bits at address
Often used to remove flags
|*address &= value;
|-
|OR
|or8
or16
or32
|OR bits at address
Often used to add flags
|<nowiki>*address |= value;</nowiki>
|-
|XOR
|xor8
xor16
xor32
|XOR bits at address
|*address ^= value;
|-
|Rotate left
|rol8
rol16
rol32
|Rotate bits left
|
|-
|Rotate right
|ror8
ror16
ror32
|Rotate bits right
|
|}

=== Special operations ===
[opcode] [address] [value] (repeat count)
{| class="wikitable"
!Operation
!Opcodes
!Description
!C equivalent
|-
|Write NOP
|writenop
|Write NOP opcode at address N times
Often used to remove a call (writenop address 5)
|WriteData<value>((void*)address, 0x90);
|-
|Write JUMP
|writejump
|Write a JUMP opcode at address followed by rel jump address
Often used to redirect a function to another
|WriteJump((void*)address, (void*)value);
|-
|Write CALL
|writecall
|Write a CALL opcode at address followed by rel call address
Often used to replace a call to a function with another
|WriteCall((void*)address, (void*)value);
|}

=== Conditions ===
The cheat code system supports conditions and branching.
[condition opcode] [address] [compared value] (repeat count)
...
''else
...''
endif
Here are the conditions available:
{| class="wikitable"
!Operation
!Opcodes
!Description
!C equivalent
|-
|If equal
|ifeq8
ifeq16
ifeq32
ifeqfloat
|Check if value at address is equal
|if (*address == value)
|-
|If not equal
|ifne8
ifne16
ifne32
ifnefloat
|Check if value at address is different
|if (*address != value)
|-
|If lower
|ifltu8
ifltu16
ifltu32
iflts8
iflts16
iflts32
ifltfloat
|Check if value at address is lower
|if (*address < value)
|-
|If lower or equal
|ifltequ8
ifltequ16
ifltequ32
iflteqs8
iflteqs16
iflteqs32
iflteqfloat
|Check if value at address is lower or equal
|if (*address <= value)
|-
|If greater
|ifgtu8
ifgtu16
ifgtu32
ifgts8
ifgts16
ifgts32
ifgtfloat
|Check if value at address is greater
|if (*address > value)
|-
|If greater or equal
|ifgtequ8
ifgtequ16
ifgtequ32
ifgteqs8
ifgteqs16
ifgteqs32
ifgteqfloat
|Check if value at address is greater or equal
|if (*address >= value)
|-
|If mask
|ifmask8
ifmask16
ifmask32
|Check if value at address has specific bits
Often used to check flags
|if ((*address & value) == value)
|-
|If key pressed
|ifkbkey [keycode]
|Check if keyboard key is pressed
See Windows [https://learn.microsoft.com/fr-fr/windows/win32/inputdev/virtual-key-codes virtual key codes].
|if (GetAsyncKeyState(value))
|}

=== Registers ===
The cheat code system has 16 registers available, you can use them as variables.

Most opcodes have a register equivalent, simply add "reg" before the type (writereg8, divregu8, ifmaskreg8...)
[opcode] [address] [value] (repeat count)
{| class="wikitable"
!Operation
!Opcodes
!Description
!C equivalent
|-
|Read
|readreg8
readreg16
readreg32
|Read value at address into register
|reg[value] = *address;
|}

=== Values format ===
Values can be in decimal, hexadecimal, or float format.
{| class="wikitable"
!Type
!Example
|-
|Decimal
|10
|-
|Hexadecimal
|0xA
|-
|Float
|10.0
|}
Repeat count should be preceded with x.

Addresses can be in hexadecimal or pointer chain format.
{| class="wikitable"
!Type
!Example
|-
|Hexadecimal
|03B0F0FC
|-
|Pointer chain
|<nowiki>p03B42E30|20|C0|6</nowiki>
|}

== Examples ==
These examples use Sonic Adventure DX (2004) addresses.

=== Write to memory ===
write16 03B0F0E4 999
This forces the ring count to 999 every frame.

* <code>write16</code> means that it will write to 2 bytes. This is because the Rings variable in SADX is a 2 bytes (a "short" or "Sint16" in c++).
* <code>03B0F0E4</code> is the hexadecimal address of the Rings variable
* <code>999</code> is the 2-byte values that is going to be written at the provided address.

writefloat 03B0F0FC 1.0
This forces the gravity to be upside down.

* <code>writefloat</code> means that the edited value is a (single precision) floating point value.
* <code>03B0F0FC</code> is the hexadecimal address of the up gravity direction.
* <code>1.0</code> is a float value that we will be writing, 1.0 for up gravity means upward.

=== Conditions ===
ifltu32 03B0F14C 9999
add32 03B0F14C 1
endif
This increased the score counter every frame until it reaches 9999.

* <code>ifltu32</code> means "if value is inferior to3 (9999 here)
* <code>03B0F14C</code> is the level score.

ifmask32 03B0E9D0 0x10
mulfloat 03B0F0FC 1.05
endif
This increases the gravity when you press d-pad up.

* <code>ifmask32</code> means we are checking if the value at address has specific bits
* <code>03B0E9D0</code> is the hexadecimal address of the pressed buttons variable, each bit corresponds to a button.
* <code>0x10</code> is the bit mask for d-pad up.

=== More examples ===
Check the [https://github.com/X-Hax/sadx-mod-loader/blob/master/data/Codes.lst SADX Mod Loader cheat codes] and [https://github.com/X-Hax/sa2-mod-loader/blob/master/data/Codes.lst SA2 Mod Loader cheat codes] for more examples.

== Resources ==
To get addresses:

* Check the RAM editing pages on sonicretro ([https://info.sonicretro.org/SCHG:Sonic_Adventure_DX:_PC/RAM_Editing SADX]/[https://info.sonicretro.org/SCHG:Sonic_Adventure_2_(PC)/RAM_Editing SA2PC])
* Start disassembling the game with IDA Pro or Ghidra
* Ask us for help on Discord

File:Samm-editmode-codeeditor.png

2025-10-05T11:06:10Z

Kell:

File:Samm-editmode-codestab.png

2025-10-05T11:04:47Z

Kell:

File:Samm-editmod-context.png

2025-10-05T11:01:46Z

Kell:

Creating Mods

2025-10-04T22:45:49Z

Kell:

There are many ways to modify Sonic Adventure DX and Sonic Adventure 2: Battle on PC using the Mod Loaders, from basic file editing to powerful code injection.

The first step is to create your mod using the [[Mod Managers|Mod Manager]]. This will create a folder in which you will be able to put your modifications without affecting the original game files or executable.

From there, you will be able to do:

* [[Creating mods/File replacement|File replacement]]
* [[Creating mods/Texture replacement|Texture replacement]]
* [[Creating mods/Cheat Codes|Cheat codes]]
* [[Creating mods/Code injection|Code injection]] (DLL mod)
* [[Creating mods/Automatic updates|Automatic updates]]
* [[Creating mods/Mod configuration|Mod configuration]]

= Creating a mod =
To create a mod you need the SA Mod Manager with Sonic Adventure DX and/or Sonic Adventure 2: Battle set up.

First open SA Mod Manager with the game of your choice and click on the "Add Mod" button in the Mods tab.
[[File:Add-mod-button.png|none|509x509px]]
Then select "New Mod (For Developers)"
[[File:Add-mod-prompt.png|none|500x500px]]
This opens the mod creation form.

=== Mod Information ===
[[File:New-mod-form-info.png|none|600x600px]]
Here are the information requested (* is mandatory):

* '''Name*''': the name of the mod
* '''Author''': your nickname, it is acceptable to add co-authors separated with commas
* '''Description''': short description of the mod, it appears below the mod list
* '''Version''': a version number, preferably numbers and dots. A common way to represent version is "major.minor".
* '''DLL''': for code injection, this is the name of the DLL with the extension (e.g. "my-mod.dll")
* '''Category''': one of the categories listed or none
* '''Mod ID*''': a unique name for your mod that should not change, preferably without spaces (e.g. "game.author.modname")
* '''Include Directories''': this is used for codeless mod configuration
* '''Author URL''': link to a page of your choice, ideally showcasing your mods (GameBanana or GitHub profile for example)
* '''Source Code URL''': for code injection, link to the source code (GitHub repository for example)

This should have created a folder with a system folder (for SADX) or a gd_PC folder (for SA2B), you can use these for [[file replacement]].

=== Update information ===
[[File:New-mod-form-update.png|none|600x600px]]
This tab is for [[Creating mods/Automatic updates|automatic updates]], it is generally filled out later.

For GitHub:

* Author and repo is the right part of the repository URL (e.g. myself/my-mod)
* Release Asset is the name of the zip file in the release (e.g. my-mod.7z)

For GameBanana:

* Mod ID is the number in the mod's page URL (e.g. 123456)
* Mod Type shouldn't be changed (legacy)

For self hosted:

* Update URL: path to mod folder root on a remote http server
* Changelog URL: path to changelog file (plain text)

=== Cheat codes ===
[[File:New-mod-form-cheat.png|none|600x600px]]
This tab is for [[Creating mods/Cheat Codes|cheat codes]].

=== Dependencies ===
[[File:New-mod-form-dependencies.png|none|600x600px]]
This tab is for mod dependencies. If your mod absolutely relies on another mod to function properly, you should add it here. The mod manager will warn users if they lack a dependency.

File:New-mod-form-dependencies.png

2025-10-04T22:35:43Z

Kell:

File:New-mod-form-cheat.png

2025-10-04T22:34:19Z

Kell:

File:New-mod-form-update.png

2025-10-04T22:22:35Z

Kell:

Creating Mods

2025-10-04T17:22:13Z

Kell: First draft

File:New-mod-form-info.png

2025-10-04T16:49:30Z

Kell:

File:Add-mod-prompt.png

2025-10-04T16:46:26Z

Kell:

File:Add-mod-button.png

2025-10-04T16:45:19Z

Kell: