Creating Mods/Mod Configuration

The Mod Manager is capable of creating configuration files, saved as config.ini in a mod folder, through a Mod Config system it has built in. This requires mods to supply a configschema.xml 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.

<!--Example Config Schema File-->

<?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>

Groups

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

name: This is the name that is written as the Group's name within the config file. This is required.
display: 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 Group element.

name: The name of the property that will be written to the config file. This is required.
display: Optional name that will overwrite the name when displaying the property in the Mod Manager if it's included.
type: 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.
- bool: A boolean value. Valid values are true or false.
- int: An integer value. Valid values are any integer value.
- float: A floating point value. Valid values are any floating point value.
- string: A text value. Valid values are a string.
- "enum": Enum types need to match the name of the Enum they correspond to. These are also the only supported type for Codeless Configuration. Valid values are the list of members of the specified Enum type.
defaultvalue: This is the default value used by the property. It must be a valid value type for the supplied type. It is required.
min: Optional value setting the minimum value. This is only used for int and float types.
max: Optional value setting the maximum value. This is only used for int and float types.
alwaysinclude: 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 HelpText element is used by a Property to supply a description or "helper" text to the user within the Mod Manager's editor. These are handled by doing.

<HelpText>This is how the helper text should be written.</HelpText>

Please see the full Config Schema example above to see how these should be written within a Property.

Enums

Just like with Group elements being wrapped in a Groups element, Enum elements are wrapped inside of an Enums element.

name: This sets the reference name to the Enum 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 Enum that are utilized in the editor and are what get written to the config file when the Enum 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.

name: This is what is written as the value for a Property making use of an Enum type. This is required.
display: 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 mod.ini 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 mod.ini 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 sonic_sword option is for editing Sonic's model while the altmusica would be for editing music files.

Manually Adding Defaults

If you want to edit mod.ini manually so you can create the sub folders as you need them, simply open your mod's folder and open mod.ini 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 IncludeDirX where X is the ID number. These begin as index 0. You will also need to include an IncludeDirCount which is the total number of directories you have setup. In our example, the following is how mod.ini looks:

Name=Example Codeless Config
Author=ItsEasyActually
Version=0.1
ModID=sadx.ExampleCodelessConfig
[Config]
IncludeDir0=sonic_sword
IncludeDir1=altmusica
IncludeDirCount=2

Folder Structure

In your mod's folder, the default folders you just added should now be visible in the mod folder unless you modified mod.ini 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:

system (SADX only)
gd_PC (SA2 only)
textures
replacetex

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

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 system (gd_PC in SA2), textures, and replacetex 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 system and textures) contains a variation of sprite assets inside their own system and textures folders.

The Sprite Rings mod for SADX also makes use of the "invalid" folder setup by labeling its default as classic 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 Group within the Config Schema files as the Mod Loader will search through all Groups looking for a matching property to the expected Property name.

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

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

<!--Example Config Schema-->
<?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>

In the end, this is how the overall folder looks after creating the Config Schema, adding the additional folder options, and removing the system 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 config.ini file and loads info from there. If it is not located, it sets the default directory to load as the one found in mod.ini as that is the fallback.

Code based Configuration Setup

  This section will be added at a later date