View source for Creating Mods/Mod Configuration

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">
<!--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>
</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">
<!--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>
</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}}