Mod Dependencies - X-Hax/SADXModdingGuide GitHub Wiki

Mod Dependencies

Sometimes when making a mod, you may find yourself relying on something provided by another for yours to properly function. This becomes an issue in a lot of cases when users don't happen to have the necessary mod(s) installed. Through the Mod Dependency system, it's now possible to alert users to missing mods, or if a mod needed isn't being loaded in the appropriate order.

General Formatting

Within mod.ini you can create a list of Mod Dependencies by simply writing them out in a list.

The format for a Mod Dependency is pretty straight forward. A fully formatted dependency is shown below followed by a break down of each section:
Dependency1=ModID|ModFolder|ModName|ModLink

  • Dependency is the identifier used to mark a Dependency in mod.ini.
    • This is formatted like a list, so all items would end with an index. ie:
      • Dependency1=
      • Dependency2=
  • ModID is a unique ID supplied by the mod.ini for a specific mod. This may not exist in older mods as this system was only recently implemented.
  • ModFolder is the folder in which the Dependency is installed. This can vary depending on the installation method (or be renamed manually by end users), so this is only here as a fallback. The ideal is for mods to include unique ModIDs.
  • ModName is the name of the Dependency. This is only used in the pop ups informing the user of what mod is missing or needs to be moved priority wise.
  • ModLink is a link to download the Dependency if it's not found for the user. If it's supplied, it'll open a link for users when prompted to download the mod.

The way the system works is it will check the ModID, which may or may not be supplied by an existing mod as most mods were built prior to this system existing. That's why it's ideal to supply a mod folder. It will fallback and check to see if the mod exists by way of its folder.

NOTE: Not all items need to exist in the list, but all separators do need to exist.

For instance, if you have a mod that does not have a ModID at the time you include it as a Dependency, you would format your Dependency as Dependency1=|ModFolder|ModName|ModLink. Another possibility is that the ModID or ModFolder are the same as the ModName, in which case you could have Dependency1=ModID|||ModLink. Basically, you need to have three | characters within any Dependency listing otherwise there will be issues with getting the correct data from a Dependency.

Tips

  • ModIDs can be written in almost any way you'd like. The Mod Manager will now generate ModIDs when creating new mods, but you can still modify it however you like. A recommended format is sadx.author.name (or any variants), but generally any way you write it will work as long as it does not contain any | characters. Below are some additional examples of ways you could write your own unique mod ID:
    • myname.mycoolmod
    • mycoolmod.myname.sadx
    • DC19971016
  • You should never update the ModID after your mod has gone public as it may lead to issues in dependency referencing. It's why we have the fallback on folders, but that is not something to rely on to always work. There are a few instances where you may want to update it to reflect the situation, but these are not part of the norm. For example, if you submit to the Sonic Hacking Contest where mod updates are intended to be disabled, you may want to add an shc somewhere in the ModID. This would be an indication that it's for SHC specifically.
  • GameBanana uploaded mods have one additional feature and another thing you should be aware of.
    • Regarding the ModLink, you can include the one click install links rather than the link to the mod on GameBanana if you desire. If the user has installed the URL handler, it will simply offer the automatic download instead of needing to open a web page.
    • Due to how one click installs are downloaded and installed, it's highly recommended that the ModName supplied is the same as what is displayed on GameBanana. There's an additional check to see if the ModName is actually a mod folder. This is not an end-all-be-all solution, so please do not rely on it to always work. You still need to supply at least a ModID or a ModFolder for this fallback to run.

Please do not abuse this system! This system has been implemented due to the amount of prerequisites that have been popping up over the years for mods relying on other mods to simply function as intended. Do not add Dependencies just because you think a mod is cool or that you want people to play specifically with that mod when using yours. Only use this when another mod is necessary for yours to function properly.