SA Docs - Recent changes [en]

User:ChanaMontgomery

ChanaMontgomery — Sat, 12 Sep 2026 08:33:11 GMT

User account ChanaMontgomery was created

User:RonaldDougharty

RonaldDougharty — Mon, 07 Sep 2026 16:33:39 GMT

User account RonaldDougharty was created

User:Celinda50C

Celinda50C — Mon, 07 Sep 2026 03:29:10 GMT

User account Celinda50C was created

User:MarcelinoJohnsto

MarcelinoJohnsto — Sat, 05 Sep 2026 19:47:54 GMT

User account MarcelinoJohnsto was created

Sonic Adventure/Voice List

TheAwesomeSonic — Wed, 02 Sep 2026 16:12:49 GMT

Show changes

User:TheAwesomeSonic

ItsEasyActually — Wed, 02 Sep 2026 14:11:46 GMT

ItsEasyActually changed group membership for TheAwesomeSonic: granted writer Requested to be added.

User:TheAwesomeSonic

TheAwesomeSonic — Mon, 31 Aug 2026 18:02:25 GMT

User account TheAwesomeSonic was created

SADX Mod Loader

ItsEasyActually — Mon, 24 Aug 2026 00:29:27 GMT

Updating page, adding Character Welds page link

← Older revision		Revision as of 00:29, 24 August 2026
Line 1:		Line 1:
	[https://github.com/X-Hax/sadx-mod-loader/ ~~Source Code~~]		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 =		= HelperFunctions API =

Sonic Adventure 2/Texture Files

End User — Sat, 22 Aug 2026 20:07:57 GMT

← Older revision		Revision as of 20:07, 22 August 2026
Line 5:		Line 5:
	For the GameCube version, the texture packages are stored in the root of the disc, but the textures are saved as GVR files within the PRS archives.		For the GameCube version, the texture packages are stored in the root of the disc, but the textures are saved as GVR files within the PRS archives.

	The PC version stores the textures in the <code>resource/gd_PC</code> path of the given installation directory. Some texture packs were converted to the PAK file system, which overrides the included GameCube texture packs when applicable. The PAK files are stored in either the <code>PRS</code> folder or the <code>SOC</code> folder within the Sonic Adventure 2 game files. Event textures that are using PAK files store those files in the <code>event/prs</code> folder path. The PAK files stored within the <code>SOC</code> folder can ~~only~~ be ~~extracted and rebuilt with PAKTool~~. ~~This program is included in SA Tools~~.		The PC version stores the textures in the <code>resource/gd_PC</code> path of the given installation directory. Some texture packs were converted to the PAK file system, which overrides the included GameCube texture packs when applicable. The PAK files are stored in either the <code>PRS</code> folder or the <code>SOC</code> folder within the Sonic Adventure 2 game files. Event textures that are using PAK files store those files in the <code>event/prs</code> folder path. The PAK files stored within the <code>SOC</code> folder can also be modified using Texture Editor, for the most part. As they can sometimes contain non-texture information, not everything within those files can be altered.

	{\| class="wikitable"		{\| class="wikitable"

Creating Mods/Mod Configuration

ItsEasyActually — Fri, 21 Aug 2026 02:54:38 GMT

Adding images.

← Older revision		Revision as of 02:54, 21 August 2026
Line 83:		Line 83:
	==== Using the Mod Manager ====		==== 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.		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]]
	~~''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.		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.

Line 104:		Line 102:
	=== Folder Structure ===		=== 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.		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]]
	~~''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:		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>system</code> (SADX only)
Line 121:		Line 117:
	==== Real World Example ====		==== 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:		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]]
	~~''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.		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.

Line 164:		Line 158:

	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:		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]]
	~~''PICTURE''~~

	=== Best Practices ===		=== Best Practices ===

File:Codeless Config Example 4.png

ItsEasyActually — Fri, 21 Aug 2026 02:54:17 GMT

ItsEasyActually uploaded File:Codeless Config Example 4.png

New page

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

ItsEasyActually — Fri, 21 Aug 2026 02:53:25 GMT

ItsEasyActually uploaded File:Codeless Config Example 3.png

New page

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

File:Codeless Config Example 2.png

ItsEasyActually — Fri, 21 Aug 2026 02:52:30 GMT

ItsEasyActually uploaded File:Codeless Config Example 2.png

New page

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

File:Example 1 for Codeless Configuration.png

ItsEasyActually — Fri, 21 Aug 2026 02:49:09 GMT

ItsEasyActually uploaded File:Example 1 for Codeless Configuration.png

New page

Displays the Mod Manager Mod Editor window with Include Directories.

Creating Mods/Mod Configuration

ItsEasyActually — Fri, 21 Aug 2026 02:46:49 GMT

Initial publishing of this page.

New 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}}