SA Docs - User contributions [en]

SADX Mod Loader

2026-08-24T00:29:27Z

ItsEasyActually: Updating page, adding Character Welds page link

You can view the [https://github.com/X-Hax/sadx-mod-loader/ source code] here.

On this page, you'll find documentation on the main API that the SADX Mod Loader exports to every code based mod created for SADX. There are additional features which are documented on other pages. You can follow the below links to find documentation on those features.

[[SADX Mod Loader/Character Welds|Character Welds]]
= HelperFunctions API =

== Struct ==
Below is the initialized version of the HelperFunctions struct. For the definition of the struct, you can find that in [https://github.com/X-Hax/sadx-mod-loader/blob/master/SADXModLoader/include/SADXModInfo.h SADXModInfo.h]
{{DocHeader|header=HelperFunctions|content=
<syntaxhighlight lang="cpp">
HelperFunctions helperFunctions =
{
ModLoaderVer,
&RegisterStartPosition,
&ClearStartPositionList,
&RegisterFieldStartPosition,
&ClearFieldStartPositionList,
&RegisterPathList,
&ClearPathListList,
&RegisterCharacterPVM,
&ClearCharacterPVMList,
&RegisterCommonObjectPVM,
&ClearCommonObjectPVMList,
&RegisterTrialLevel,
&ClearTrialLevelList,
&RegisterTrialSubgame,
&ClearTrialSubgameList,
&GetMainSavePath,
&GetChaoSavePath,
&GetReplaceablePath,
&_ReplaceFile,
&SetWindowTitle,
&RegisterSoundList,
&RegisterMusicFile,
&LoadEXEData,
&LoadDLLData,
&_ReplaceFileForce,
&PushScaleUI,
&PopScaleUI,
&SetScaleFillMode,
&GetScaleFillMode,
&ReplaceTexture,
&MipmapBlacklistGBIX,
&RegisterEnglishVoiceDuration,
&RegisterJapaneseVoiceDuration,
&RegisterCharacterWelds,
&loaderSettings,
&modList,
&weightFuncs,
&RegisterVoice,
&PushInterpolationFix,
&PopInterpolationFix,
&RegisterPermanentTexlist,
&ExpandPVMList,
&UnreplaceFile,
&PrintDebugUnicode,
&PrintDebugLocal,
&PrintDebugCodepage,
&GetFileModIndex,
&ReplaceFileAtIndex
};
</syntaxhighlight>
}}

{{Note|text=Please be aware that all examples on this page will be using <code>helperFunctions</code> which is how the variable is sent to a mod.|type=info}}
== Properties ==

=== Mod Loader Version ===
<syntaxhighlight lang="cpp">
int ModLoaderVer;
</syntaxhighlight>

This returns the version of the mod loader. This can be used to check if the user has an old version of the mod loader that may not have functionality your mod requires.
{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
if (helperFunctions.ModLoaderVer <= 10)
PrintDebug("This Mod Loader is way out of date.\n");
</syntaxhighlight>
}}

=== Mod Loader Settings ===
<syntaxhighlight lang="cpp">
LoaderSettings loaderSettings;
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Mod List ===
<syntaxhighlight lang="cpp">
std::vector<Mod> modlist;
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Weight Functions ===
<syntaxhighlight lang="cpp">
BasicWeightFuncs weightFuncs;
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}
== Functions ==

=== Register Start Position ===
<syntaxhighlight lang="cpp">
static void RegisterStartPosition(unsigned char character, const StartPosition& position)
</syntaxhighlight>

Registers a new Start Position for the specified character.
{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
StartPosition myStageStartPos = {
1, // Level ID
0, // Act ID
{ 100.0f, 200.0f, 100.0f }, // Position
0 // Y Rotation
};

// We pass our StagePosition variable as a pointer to this function
// and we have specified Sonic, so the level for this ID would now use
// our StartPosition instead of the original.
helperFunctions.RegisterStartPosition(Characters_Sonic, &myStageStartPos);
</syntaxhighlight>
}}

=== Clear Start Position List ===
<syntaxhighlight lang="cpp">
static void ClearStartPositionList(unsigned char character)
</syntaxhighlight>

Clears the Start Positions for the specified character.
{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// Running this inside of your mod's Init export would
// clear all of Sonic's Start Positions for his stages.
helperFunctions.ClearStartPositionList(Characters_Sonic);
</syntaxhighlight>
}}

=== Register Field Position ===
<syntaxhighlight lang="cpp">
static void RegisterFieldStartPosition(unsigned char character, const FieldStartPosition& position)
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Clear Field Start Position List ===
<syntaxhighlight lang="cpp">
static void ClearFieldStartPositionList(unsigned char character)
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Register Path List ===
<syntaxhighlight lang="cpp">
static void RegisterPathList(const PathDataPtr& paths)
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Clear Path List List ===
<syntaxhighlight lang="cpp">
static void ClearPathListList()
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Register Character PVM ===
<syntaxhighlight lang="cpp">
static void RegisterCharacterPVM(unsigned char character, const PVMEntry& pvm)
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Clear Character PVM List ===
<syntaxhighlight lang="cpp">
static void ClearCharacterPVMList(unsigned char character)
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Register Common Object PVM ===
<syntaxhighlight lang="cpp">
static void RegisterCommonObjectPVM(const PVMEntry& pvm)
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Clear Common Object PVM List ===
<syntaxhighlight lang="cpp">
static void ClearCommonObjectPVMList()
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Register Trial Level ===
<syntaxhighlight lang="cpp">
static void RegisterTrialLevel(unsigned char character, const TrialLevelListEntry& level)
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Clear Trial Level List ===
<syntaxhighlight lang="cpp">
static void ClearTrialLevelList(unsigned char character)
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Register Trial Subgame ===
<syntaxhighlight lang="cpp">
static void RegisterTrialSubgame(unsigned char character, const TrialLevelListEntry& level)
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Clear Trial Subgame List ===
<syntaxhighlight lang="cpp">
static void ClearTrialSubgameList(unsigned char character)
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Get Main Save Path ===
<syntaxhighlight lang="cpp">
static const char* GetMainSavePath()
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Get Chao Save Path ===
<syntaxhighlight lang="cpp">
static const char* GetChaoSavePath()
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Get Replaceable Path ===
<syntaxhighlight lang="cpp">
const char* __cdecl GetReplaceablePath(const char* path)
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Replace File ===
<syntaxhighlight lang="cpp">
void _ReplaceFile(const char* src, const char* dst)
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Set Window Title ===
<syntaxhighlight lang="cpp">
void SetWindowTitle(const char* title)
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Register Sound List ===
<syntaxhighlight lang="cpp">
int RegisterSoundList(const SoundList& list)
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Register Music File ===
<syntaxhighlight lang="cpp">
int RegisterMusicFile(const MusicInfo& track)
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Load EXE Data ===
<syntaxhighlight lang="cpp">
void LoadEXEData(const wchar_t* filename, const wchar_t* mod_dir)
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Load DLL Data ===
<syntaxhighlight lang="cpp">
void LoadDLLData(const wchar_t* filename, const wchar_t* mod_dir)
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Replace File Force ===
<syntaxhighlight lang="cpp">
void _ReplaceFileForce(const char* src, const char* dst)
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Push Scale UI ===
<syntaxhighlight lang="cpp">
void PushScaleUI(uiscale::Align align, bool is_background, float ratio_h, float ratio_v)
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Pop Scale UI ===
<syntaxhighlight lang="cpp">
void PopScaleUI()
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Set Scale Fill Mode ===
<syntaxhighlight lang="cpp">
void SetScaleFillMode(uiscale::FillMode mode)
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Get Scale Fill Mode ===
<syntaxhighlight lang="cpp">
uiscale::FillMode GetScaleFillMode()
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Replace Texture ===
<syntaxhighlight lang="cpp">
void ReplaceTexture(const char* pvm_name, const char* tex_name, const char* file_path, uint32_t gbix, uint32_t width, uint32_t height)
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Mipmap Blacklist GBIX ===
<syntaxhighlight lang="cpp">
void MipmapBlacklistGBIX(Uint32 index)
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Register English Voice Duration ===
<syntaxhighlight lang="cpp">
void RegisterEnglishVoiceDuration(const uint16_t voiceID, const uint16_t duration)
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Register Japanese Voice Duration ===
<syntaxhighlight lang="cpp">
void RegisterJapaneseVoiceDuration(const uint16_t voiceID, const uint16_t duration)
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Register Character Welds ===
<syntaxhighlight lang="cpp">
void RegisterCharacterWelds(const uint8_t character, const char* iniPath)
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Register Voice ===
<syntaxhighlight lang="cpp">
uint16_t RegisterVoice(const char* fileJP, const char* fileEN, uint16_t durationJP, uint16_t durationEN)
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Push Interpolation Fix ===
<syntaxhighlight lang="cpp">
void PushInterpolationFix()
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Pop Interpolation Fix ===
<syntaxhighlight lang="cpp">
void PopInterpolationFix()
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Register Permanent Texlist ===
<syntaxhighlight lang="cpp">
void RegisterPermanentTexlist(NJS_TEXLIST* texlist)
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Unreplace File ===
<syntaxhighlight lang="cpp">
void UnreplaceFile(const char* file)
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Expand PVM List ===
<syntaxhighlight lang="cpp">
TEX_PVMTABLE* ExpandPVMList(TEX_PVMTABLE* sourcepvmlist, const TEX_PVMTABLE &newpvmentry)
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Unreplace File ===
<syntaxhighlight lang="cpp">
void UnreplaceFile(const char* file)
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Print Debug Unicode ===
<syntaxhighlight lang="cpp">
void PrintDebugUnicode(char* utf8)
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Print Debug Local ===
<syntaxhighlight lang="cpp">
void PrintDebugLocal(char* buf)
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Print Debug Codepage ===
<syntaxhighlight lang="cpp">
void PrintDebugCodepage(char* buf, unsigned int source_cp)
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Get File Mod Index ===
<syntaxhighlight lang="cpp">
int GetFileModIndex(const char* path)
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

=== Replace File At Index ===
<syntaxhighlight lang="cpp">
void ReplaceFileAtIndex(const char* src, const char* dst, int modIndex)
</syntaxhighlight>

{{DocHeader|header=Example|content=
<syntaxhighlight lang="cpp">
// TODO: Write example.
</syntaxhighlight>
}}

Creating Mods/Mod Configuration

2026-08-21T02:54:38Z

ItsEasyActually: Adding images.

The Mod Manager is capable of creating configuration files, saved as <code>config.ini</code> in a mod folder, through a Mod Config system it has built in. This requires mods to supply a <code>configschema.xml</code> within their mod folders. This is what defines the Groups, Properties, and custom Enumerations that can be used for creating a configuration file for a mod to make use of.

If you're looking to create a codeless configuration system (it uses an in-built system in the mod loader for redirecting the system folders for loading), you can head over to the Codeless Configuration Setup section.

If you want a more advanced system for Configuration that requires code, please check out the Code Configuration Setup section.

== Config Schema ==
The Config Schema is an XML file that the Mod Manager will read from to generate the various elements used for a config file. Below is an example Config Schema followed by a break down on each element within a schema file.
<syntaxhighlight lang="xml">


<?xml version="1.0"?>
<ConfigSchema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.sonicretro.org">
<Groups>
<Group name="config" display="Configuration">
<Property name="speed" display="Speed Value" type="float" defaultvalue="10">
<HelpText>Sets the speed for a custom object.</HelpText>
</Property>
<Property name="object" display="Object Type" type="ObjectType" defaultvalue="cub">
<HelpText>Sets the object model that is used.</HelpText>
</Property>
</Group>
</Groups>
<Enums>
<Enum name = "ObjectType">
<EnumMember name="cub" display="Cube" />
<EnumMember name="sph" display="Sphere" />
<EnumMember name="cyl" display="Cylinder" />
</Enum>
</Enums>
</ConfigSchema>
</syntaxhighlight>

=== Groups ===
Groups are groupings of properties that will be saved to a configuration file. They are wrapped inside of a base <code>Groups</code> element. All <code>Group</code> elements must be placed inside of the <code>Groups</code> element, just like how it is displayed in the example above.

* <code>name</code>: This is the name that is written as the Group's name within the config file. '''This is required.'''
* <code>display</code>: Optional name that will overwrite the displayed name in the Editor within the Mod Manager which can make it easier for users to read.

==== Properties ====
Properties are the actual variables written to a config file. These will always be wrapped inside of a <code>Group</code> element.

* <code>name</code>: The name of the property that will be written to the config file. '''This is required.'''
* <code>display</code>: Optional name that will overwrite the name when displaying the property in the Mod Manager if it's included.
* <code>type</code>: The type of property this is. Below is a list of currently valid types supported by the Mod Manager and Mod Loaders. '''This is required.'''
** <code>bool</code>: A boolean value. Valid values are <code>true</code> or <code>false</code>.
** <code>int</code>: An integer value. Valid values are any integer value.
** <code>float</code>: A floating point value. Valid values are any floating point value.
** <code>string</code>: A text value. Valid values are a string.
** <code>"enum"</code>: Enum types need to match the name of the <code>Enum</code> they correspond to. These are also the only supported type for Codeless Configuration. Valid values are the list of members of the specified <code>Enum</code> type.
* <code>defaultvalue</code>: This is the default value used by the property. It must be a valid value type for the supplied type. '''It is required.'''
* <code>min</code>: Optional value setting the minimum value. This is only used for <code>int</code> and <code>float</code> types.
* <code>max</code>: Optional value setting the maximum value. This is only used for <code>int</code> and <code>float</code> types.
* <code>alwaysinclude</code>: Optional boolean that, when set to true, forces the Manager to always write the property to the config file regardless of if it matches the default value or not.

===== HelpText =====
The <code>HelpText</code> element is used by a <code>Property</code> to supply a description or "helper" text to the user within the Mod Manager's editor. These are handled by doing.
<syntaxhighlight lang="xml">
<HelpText>This is how the helper text should be written.</HelpText>
</syntaxhighlight>
Please see the full Config Schema example above to see how these should be written within a <code>Property</code>.

=== Enums ===
Just like with <code>Group</code> elements being wrapped in a <code>Groups</code> element, <code>Enum</code> elements are wrapped inside of an <code>Enums</code> element.

* <code>name</code>: This sets the reference name to the <code>Enum</code> within the Mod Manager's editor. This has no impact on the written config file, but '''it is still required.'''

==== EnumMembers ====
These are the entries, or options, within an <code>Enum</code> that are utilized in the editor and are what get written to the config file when the <code>Enum</code> type is used in a property. Despite being sharing a name with enums, these are actually more like preset lists of strings that can be used.

* <code>name</code>: This is what is written as the value for a <code>Property</code> making use of an <code>Enum</code> type. '''This is required.'''
* <code>display</code>: Optional name that will be displayed in the editor when supplied.

----
Note: While any text editor can be used for writing a Config Schema file, it's recommended to use one that supports writing XML, such as Notepad++ or VSCodium.

== Codeless Configuration Setup ==
Codeless Configuration is an option for mod developers that want to include customizable asset replacement without needing to use code. As such, these are limited to ''solely'' asset replacement and have specific formatting that needs to be followed for the Mod Loader to correctly handle the asset loading redirection. They '''can''' be used in tandem with code mods that include other configuration options without the mod needing to implement its own custom asset redirection however.

=== Getting Started ===
There are two ways to setup the prerequisites needed for Codeless Configuration; using the Mod Manager or editing <code>mod.ini</code> manually. Please follow the directions for the method you wish to use.

==== Using the Mod Manager ====
In the Mod Manager, either create a new mod, use the Edit Mod option on an existing mod. This will open the Edit Mod window. In this window, locate the Include Directories entry. This is where you create the initial defaults and create the fallback folder IDs that will be stored inside the mod's <code>mod.ini</code> file. You can create multiple options for modifying different assets at the same time by separating each entry with a comma.
[[File:Example 1 for Codeless Configuration.png|center]]
In this example, the <code>sonic_sword</code> option is for editing Sonic's model while the <code>altmusica</code> would be for editing music files.

==== Manually Adding Defaults ====
If you want to edit <code>mod.ini</code> manually so you can create the sub folders as you need them, simply open your mod's folder and open <code>mod.ini</code> in a text editor of your choice. You will then need to add a new Section named "Config." Under this Section, you can create as many "Include Directories" as you need. These are formatted as <code>IncludeDirX</code> where X is the ID number. These begin as index 0. You will also need to include an <code>IncludeDirCount</code> which is the total number of directories you have setup. In our example, the following is how <code>mod.ini</code> looks:

<syntaxhighlight lang="ini">
Name=Example Codeless Config
Author=ItsEasyActually
Version=0.1
ModID=sadx.ExampleCodelessConfig
[Config]
IncludeDir0=sonic_sword
IncludeDir1=altmusica
IncludeDirCount=2
</syntaxhighlight>

=== Folder Structure ===
In your mod's folder, the default folders you just added should now be visible in the mod folder unless you modified <code>mod.ini</code> manually. This example will continue with the expectation that you have folders matching those examples.
[[File:Codeless Config Example 2.png|center]]
These sub folders act like a base mod folder which means they can contain any of the same folders a mod can contain, including the following:
* <code>system</code> (SADX only)
* <code>gd_PC</code> (SA2 only)
* <code>textures</code>
* <code>replacetex</code>

They can also contain any of the exported INI files from the SA Tools, such as <code>sonic_data.ini</code> or <code>sonic2app_data.ini</code>.

The folders that were created are just the default folders as well. You can create additional folders to be used for these options which are how you get into having multiple options for asset replacement.

For Codeless Config mods, the base <code>system</code> (<code>gd_PC</code> in SA2), <code>textures</code>, and <code>replacetex</code> folders are always loaded first if they exist ('''They are not required, just generated by default when making a mod with the Mod Manager'''). The Mod Loader will then load from any of the alternative directories (if valid) second. This allows users the option of having an "invalid" folder name as their default to only load from their base folders.

==== Real World Example ====
The Sprite Rings mod for SADX is a good example of a real mod making use of this system. Below is a screenshot of that mod's folder:
[[File:Codeless Config Example 3.png|center]]
In this example, every folder (excluding <code>system</code> and <code>textures</code>) contains a variation of sprite assets inside their own <code>system</code> and <code>textures</code> folders.

The Sprite Rings mod for SADX also makes use of the "invalid" folder setup by labeling its default as <code>classic</code> but no folder with that name actually exists.

=== Creating the Config Schema ===
Creating a config schema to include the directory options is relatively straight forward. Properties can be stored inside of any <code>Group</code> within the Config Schema files as the Mod Loader will search through all <code>Groups</code> looking for a matching property to the expected <code>Property</code> name.

The expected <code>Property</code> names should match the variables setup in the mod's Config section of its <code>mod.ini</code> file, ie <code>IncludeDirX</code> where X is the corresponding index. In our example, <code>sonic_sword</code> is the default option for <code>IncludeDir0</code> while <code>altmusica</code> is the default option for <code>IncludeDir1</code>.

Making use of <code>Enums</code> is the best way to setup the <code>Property</code> types as it controls what the folder names are without the user needing to do anything further. The <code>name</code> field in an <code>EnumMember</code> needs to match the folder name to work properly.

<syntaxhighlight lang="xml">

<?xml version="1.0" encoding="utf-8"?>
<ConfigSchema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.sonicretro.org">
<Groups>
<Group name="options" display="Example Options">
<Property name="IncludeDir0" type="model" display="Sonic Outfit" defaultvalue="sonic_sword">
<HelpText>Select the outfit you want Sonic to use.</HelpText>
</Property>
<Property name="IncludeDir1" type="music" display="Sonic Theme" defaultvalue="altmusica">
<HelpText>Select the theme you want to be used for Sonic.</HelpText>
</Property>
</Group>
</Groups>
<Enums>
<Enum name="model">
<EnumMember name="sonic_sword" display="Sonic with Gauntlet (from SatBK)" />
<EnumMember name="sonic_ring" display="Sonic with Ring (from SatSR)" />
</Enum>

<Enum name="music">
<EnumMember name="altmusica" display="Knight of the Wind" />
<EnumMember name="altmusicb" display="Seven Rings in Hand" />
</Enum>
</Enums>
</ConfigSchema>
</syntaxhighlight>

In the end, this is how the overall folder looks after creating the Config Schema, adding the additional folder options, and removing the <code>system</code> folder as it was not needed:
[[File:Codeless Config Example 4.png|center]]

=== Best Practices ===
Default options inside the Config Schema should match the defaults within your mod's INI file. Failing to due so may result in unintended behavior where the Mod Loader will continue to load whatever the option set in the mod's INI is set to. This is because the Mod Loader checks for a <code>config.ini</code> file and loads info from there. If it is not located, it sets the default directory to load as the one found in <code>mod.ini</code> as that is the fallback.

----

== Code based Configuration Setup ==

{{Note|text=This section will be added at a later date|type=info}}

File:Codeless Config Example 4.png

2026-08-21T02:54:17Z

ItsEasyActually:

Example of the final folder setup for the example mod for Codeless Config once all of the work has been done to set it up.

File:Codeless Config Example 3.png

2026-08-21T02:53:25Z

ItsEasyActually:

Real World example of Codeless Config taken from the Sprite Rings mod for SADX.

File:Codeless Config Example 2.png

2026-08-21T02:52:30Z

ItsEasyActually:

Example of the mod folder immediately after creating it from the Mod Manager.

File:Example 1 for Codeless Configuration.png

2026-08-21T02:49:09Z

ItsEasyActually:

Displays the Mod Manager Mod Editor window with Include Directories.

Creating Mods/Mod Configuration

2026-08-21T02:46:49Z

ItsEasyActually: Initial publishing of this page.

The Mod Manager is capable of creating configuration files, saved as <code>config.ini</code> in a mod folder, through a Mod Config system it has built in. This requires mods to supply a <code>configschema.xml</code> within their mod folders. This is what defines the Groups, Properties, and custom Enumerations that can be used for creating a configuration file for a mod to make use of.

If you're looking to create a codeless configuration system (it uses an in-built system in the mod loader for redirecting the system folders for loading), you can head over to the Codeless Configuration Setup section.

If you want a more advanced system for Configuration that requires code, please check out the Code Configuration Setup section.

== Config Schema ==
The Config Schema is an XML file that the Mod Manager will read from to generate the various elements used for a config file. Below is an example Config Schema followed by a break down on each element within a schema file.
<syntaxhighlight lang="xml">


<?xml version="1.0"?>
<ConfigSchema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.sonicretro.org">
<Groups>
<Group name="config" display="Configuration">
<Property name="speed" display="Speed Value" type="float" defaultvalue="10">
<HelpText>Sets the speed for a custom object.</HelpText>
</Property>
<Property name="object" display="Object Type" type="ObjectType" defaultvalue="cub">
<HelpText>Sets the object model that is used.</HelpText>
</Property>
</Group>
</Groups>
<Enums>
<Enum name = "ObjectType">
<EnumMember name="cub" display="Cube" />
<EnumMember name="sph" display="Sphere" />
<EnumMember name="cyl" display="Cylinder" />
</Enum>
</Enums>
</ConfigSchema>
</syntaxhighlight>

=== Groups ===
Groups are groupings of properties that will be saved to a configuration file. They are wrapped inside of a base <code>Groups</code> element. All <code>Group</code> elements must be placed inside of the <code>Groups</code> element, just like how it is displayed in the example above.

* <code>name</code>: This is the name that is written as the Group's name within the config file. '''This is required.'''
* <code>display</code>: Optional name that will overwrite the displayed name in the Editor within the Mod Manager which can make it easier for users to read.

==== Properties ====
Properties are the actual variables written to a config file. These will always be wrapped inside of a <code>Group</code> element.

* <code>name</code>: The name of the property that will be written to the config file. '''This is required.'''
* <code>display</code>: Optional name that will overwrite the name when displaying the property in the Mod Manager if it's included.
* <code>type</code>: The type of property this is. Below is a list of currently valid types supported by the Mod Manager and Mod Loaders. '''This is required.'''
** <code>bool</code>: A boolean value. Valid values are <code>true</code> or <code>false</code>.
** <code>int</code>: An integer value. Valid values are any integer value.
** <code>float</code>: A floating point value. Valid values are any floating point value.
** <code>string</code>: A text value. Valid values are a string.
** <code>"enum"</code>: Enum types need to match the name of the <code>Enum</code> they correspond to. These are also the only supported type for Codeless Configuration. Valid values are the list of members of the specified <code>Enum</code> type.
* <code>defaultvalue</code>: This is the default value used by the property. It must be a valid value type for the supplied type. '''It is required.'''
* <code>min</code>: Optional value setting the minimum value. This is only used for <code>int</code> and <code>float</code> types.
* <code>max</code>: Optional value setting the maximum value. This is only used for <code>int</code> and <code>float</code> types.
* <code>alwaysinclude</code>: Optional boolean that, when set to true, forces the Manager to always write the property to the config file regardless of if it matches the default value or not.

===== HelpText =====
The <code>HelpText</code> element is used by a <code>Property</code> to supply a description or "helper" text to the user within the Mod Manager's editor. These are handled by doing.
<syntaxhighlight lang="xml">
<HelpText>This is how the helper text should be written.</HelpText>
</syntaxhighlight>
Please see the full Config Schema example above to see how these should be written within a <code>Property</code>.

=== Enums ===
Just like with <code>Group</code> elements being wrapped in a <code>Groups</code> element, <code>Enum</code> elements are wrapped inside of an <code>Enums</code> element.

* <code>name</code>: This sets the reference name to the <code>Enum</code> within the Mod Manager's editor. This has no impact on the written config file, but '''it is still required.'''

==== EnumMembers ====
These are the entries, or options, within an <code>Enum</code> that are utilized in the editor and are what get written to the config file when the <code>Enum</code> type is used in a property. Despite being sharing a name with enums, these are actually more like preset lists of strings that can be used.

* <code>name</code>: This is what is written as the value for a <code>Property</code> making use of an <code>Enum</code> type. '''This is required.'''
* <code>display</code>: Optional name that will be displayed in the editor when supplied.

----
Note: While any text editor can be used for writing a Config Schema file, it's recommended to use one that supports writing XML, such as Notepad++ or VSCodium.

== Codeless Configuration Setup ==
Codeless Configuration is an option for mod developers that want to include customizable asset replacement without needing to use code. As such, these are limited to ''solely'' asset replacement and have specific formatting that needs to be followed for the Mod Loader to correctly handle the asset loading redirection. They '''can''' be used in tandem with code mods that include other configuration options without the mod needing to implement its own custom asset redirection however.

=== Getting Started ===
There are two ways to setup the prerequisites needed for Codeless Configuration; using the Mod Manager or editing <code>mod.ini</code> manually. Please follow the directions for the method you wish to use.

==== Using the Mod Manager ====
In the Mod Manager, either create a new mod, use the Edit Mod option on an existing mod. This will open the Edit Mod window. In this window, locate the Include Directories entry. This is where you create the initial defaults and create the fallback folder IDs that will be stored inside the mod's <code>mod.ini</code> file. You can create multiple options for modifying different assets at the same time by separating each entry with a comma.

''PICTURE''

In this example, the <code>sonic_sword</code> option is for editing Sonic's model while the <code>altmusica</code> would be for editing music files.

==== Manually Adding Defaults ====
If you want to edit <code>mod.ini</code> manually so you can create the sub folders as you need them, simply open your mod's folder and open <code>mod.ini</code> in a text editor of your choice. You will then need to add a new Section named "Config." Under this Section, you can create as many "Include Directories" as you need. These are formatted as <code>IncludeDirX</code> where X is the ID number. These begin as index 0. You will also need to include an <code>IncludeDirCount</code> which is the total number of directories you have setup. In our example, the following is how <code>mod.ini</code> looks:

<syntaxhighlight lang="ini">
Name=Example Codeless Config
Author=ItsEasyActually
Version=0.1
ModID=sadx.ExampleCodelessConfig
[Config]
IncludeDir0=sonic_sword
IncludeDir1=altmusica
IncludeDirCount=2
</syntaxhighlight>

=== Folder Structure ===
In your mod's folder, the default folders you just added should now be visible in the mod folder unless you modified <code>mod.ini</code> manually. This example will continue with the expectation that you have folders matching those examples.

''PICTURE''

These sub folders act like a base mod folder which means they can contain any of the same folders a mod can contain, including the following:
* <code>system</code> (SADX only)
* <code>gd_PC</code> (SA2 only)
* <code>textures</code>
* <code>replacetex</code>

They can also contain any of the exported INI files from the SA Tools, such as <code>sonic_data.ini</code> or <code>sonic2app_data.ini</code>.

The folders that were created are just the default folders as well. You can create additional folders to be used for these options which are how you get into having multiple options for asset replacement.

For Codeless Config mods, the base <code>system</code> (<code>gd_PC</code> in SA2), <code>textures</code>, and <code>replacetex</code> folders are always loaded first if they exist ('''They are not required, just generated by default when making a mod with the Mod Manager'''). The Mod Loader will then load from any of the alternative directories (if valid) second. This allows users the option of having an "invalid" folder name as their default to only load from their base folders.

==== Real World Example ====
The Sprite Rings mod for SADX is a good example of a real mod making use of this system. Below is a screenshot of that mod's folder:

''PICTURE''

In this example, every folder (excluding <code>system</code> and <code>textures</code>) contains a variation of sprite assets inside their own <code>system</code> and <code>textures</code> folders.

The Sprite Rings mod for SADX also makes use of the "invalid" folder setup by labeling its default as <code>classic</code> but no folder with that name actually exists.

=== Creating the Config Schema ===
Creating a config schema to include the directory options is relatively straight forward. Properties can be stored inside of any <code>Group</code> within the Config Schema files as the Mod Loader will search through all <code>Groups</code> looking for a matching property to the expected <code>Property</code> name.

The expected <code>Property</code> names should match the variables setup in the mod's Config section of its <code>mod.ini</code> file, ie <code>IncludeDirX</code> where X is the corresponding index. In our example, <code>sonic_sword</code> is the default option for <code>IncludeDir0</code> while <code>altmusica</code> is the default option for <code>IncludeDir1</code>.

Making use of <code>Enums</code> is the best way to setup the <code>Property</code> types as it controls what the folder names are without the user needing to do anything further. The <code>name</code> field in an <code>EnumMember</code> needs to match the folder name to work properly.

<syntaxhighlight lang="xml">

<?xml version="1.0" encoding="utf-8"?>
<ConfigSchema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.sonicretro.org">
<Groups>
<Group name="options" display="Example Options">
<Property name="IncludeDir0" type="model" display="Sonic Outfit" defaultvalue="sonic_sword">
<HelpText>Select the outfit you want Sonic to use.</HelpText>
</Property>
<Property name="IncludeDir1" type="music" display="Sonic Theme" defaultvalue="altmusica">
<HelpText>Select the theme you want to be used for Sonic.</HelpText>
</Property>
</Group>
</Groups>
<Enums>
<Enum name="model">
<EnumMember name="sonic_sword" display="Sonic with Gauntlet (from SatBK)" />
<EnumMember name="sonic_ring" display="Sonic with Ring (from SatSR)" />
</Enum>

<Enum name="music">
<EnumMember name="altmusica" display="Knight of the Wind" />
<EnumMember name="altmusicb" display="Seven Rings in Hand" />
</Enum>
</Enums>
</ConfigSchema>
</syntaxhighlight>

In the end, this is how the overall folder looks after creating the Config Schema, adding the additional folder options, and removing the <code>system</code> folder as it was not needed:

''PICTURE''

=== Best Practices ===
Default options inside the Config Schema should match the defaults within your mod's INI file. Failing to due so may result in unintended behavior where the Mod Loader will continue to load whatever the option set in the mod's INI is set to. This is because the Mod Loader checks for a <code>config.ini</code> file and loads info from there. If it is not located, it sets the default directory to load as the one found in <code>mod.ini</code> as that is the fallback.

----

== Code based Configuration Setup ==

{{Note|text=This section will be added at a later date|type=info}}