Skip to content

Basic Mod File Structure

Jump to bottom Edit New page
Michael edited this page Feb 15, 2024 · 19 revisions

This page will describe some useful information on the mod format for Hedge Mod Manager.

Table of Contents


Mod file structure

Mods designed for Hedge Mod Manager need to come in the form of folders that contain the following:

  • A mod.ini file (a file that describes your mod, as well as all its various details).
  • A disk folder
    • A bb folder (for Sonic Generations)
      • All your modified files/folders from the root of Sonic Generations' bb.cpk in their raw form.
    • A bb2 folder (for Sonic Generations)
      • All your modified files/folders from the root of Sonic Generations' bb2.cpk in their raw form.
    • A bb3 folder (for Sonic Generations)
      • All your modified files/folders from the root of Sonic Generations' bb3.cpk in their raw form.
    • A sonic2013_patch_0 folder (for Sonic Lost World)
      • All your modified files/folders from the root of Sonic Lost World's sonic2013_0.cpk in their raw form.
    • A wars_patch folder (for Sonic Forces)
      • All your modified files/folders from the root of Sonic Forces' wars_0.cpk and wars_1.cpk in their raw form.
    • A musashi_0 folder (for Olympic Games Tokyo 2020)
      • All your modified files/folders from the root of Olympic Games Tokyo 2020's musashi_0.cpk in their raw form.
  • A raw folder (for Puyo Puyo Tetris 2, Sonic Origins, and Sonic Frontiers)
    • All your modified files/folders from the root of the raw folder in their raw form.
  • A Sonic1/2/3k/CDu folder (for Sonic Origins)
    • All your modified files/folders from the RSDK file of the respective game in their raw form.

So long as the structure of your mod remains in this format, virtually any file in the game can be modified and released as part of your mod.


For example, a basic Modern Sonic character mod for Sonic Generations would have a file/folder structure that goes like so:

📁ModFolder
├ 📁disk
│  ├ 📁bb3
│  │  ├ Sonic.ar.00
│  │  └ Sonic.arl
└ mod.ini

Alternatively, this is what that kind of mod would look like for Puyo Puyo Tetris 2:

📁ModFolder
├ 📁raw
│  ├ 📁ui
│  │  ├ 📁cutin
│  │  │  ├ ui_cutin_2p_son.pac
│  │  │  └ ui_cutin_4p_son.pac
└ mod.ini

Append Archive / Work Folder

Note: The work folder feature is currently exclusive to Sonic Generations. There are plans to add Sonic Lost World support in the future.

HE1ML includes support for append archives and a work folder - these can contain the files that you specifically modified.

  • The Work folder is intended to be utilized during mod development for loading raw files, eliminating the need for repacking.
  • An Append archive is intended to be utilized when releasing and publishing mods, they should contain only the files you added or modified. Adding a + before the file name signifies that it is an append archive.

Example work folder structure:

📁ModFolder
├ 📁work
│  ├ 📁Sonic
│  │  ├ chr_sonic_body01_dif_HD.dds
│  │  └ chr_sonic_eye_dif_HD.dds
└ mod.ini

Example folder structure for using append archives:

📁ModFolder
├ 📁disk
│  ├ 📁bb3
│  │  ├ +Sonic.ar.00
│  │  └ +Sonic.arl
└ mod.ini

mod.ini file

The mod.ini file is a mod configuration file that details all the information about your mod, as well as how HE1ML should load the mod.
The format used in the Hedge Mod Manager is a variation of the format used in SLWModLoader and SonicGMI, with some minor changes and additions.

Here's an example from a Sonic Generations mod by PTKay:

[Main]
UpdateServer="https://raw.githubusercontent.com/PTKay/ModUpdates/master/SonicGenerations/SonicUnleashedHUD/"
SaveFile=""
ID="ptkickass.sonicgenerations.unleashedhud"
IncludeDir0="."
IncludeDirCount=1
DependsCount=0
DLLFile="UnleashedHUD.dll"
CodeFile="UnleashedHUD.hmm"
ConfigSchemaFile="UnleashedHUD.json"

[Desc]
Author="PTKay, Skyth, brianuuu"
Title="Sonic Unleashed HUD"
Version="2.2.0"
AuthorURL="https://www.youtube.com/@PTKay_"
Date="2020/02/20"
Description="A Sonic Generations mod that partially ports the Sonic Unleashed HUD"

The following is a list of the most important values that can be used in a mod.ini file:

The "[Main]" section

Click here to expand...

UpdateServer - A URL to a directory on an HTTP or HTTPS server containing a mod_version.ini and mod_files.txt file using the SonicGMI update format.

Example:

UpdateServer="https://raw.githubusercontent.com/PTKickass/ModUpdates/master/SonicGenerations/SonicUnleashedHUD/"

SaveFile - A path to a save file or to where you want the file save to be located. This is recommended to be used if the mod needs a curtain progress or if the mod risks breaking save files.

ID - A unique identifier for your mod. If one doesn't exist, Hedge Mod Manager will generate one for you. This is used for identification with certain codes (via the HMM library) and for dependencies, so it's recommended to not change it once it has been set.

IncludeDir# - Specifies which folders the mod loader will load for your mod, where # is replaced with a numerical value. This uses zero-index numbering, so the first one is IncludeDir0 as opposed to IncludeDir1.

Note: This must point to the folder containing a disk folder. By default, this is typically the root of the mod folder, and as such it MUST USE "." as the value. (Example: IncludeDir0=".")
Getting this wrong will result in your mod NOT loading.

Example:

IncludeDir0="." ;Will match to "mods/<MOD NAME>/"
IncludeDirCount=1 ;Amount of includes, if unsure keep at 1

IncludeDirCount - Specifies how many folders will be included with your mod.

Depends# - Specifies a dependency required for the mod, where # is replaced with a numerical value. The required formatting is ID|Mod Name|Mod URL|Version. Version can be omitted if the mod doesn't require a specific version of a dependency, but it must use version formatting (ex. 1.2 or 1.2.3). This uses zero-index numbering, so the first one is Depends0 as opposed to Depends1.

Example:

Depends0="A979D4|Direct3D 9 Ex|https://gamebanana.com/mods/50770|" ;ID|Mod Name|Mod URL|Version
Depends1="FF125998|Better FxPipeline|https://gamebanana.com/mods/50765|"
DependsCount=2 ;Amount of dependencies, if unsure keep at 0

DependsCount - Specifies how many dependencies the mod requires.

DLLFile - A path to the mod's DLL file. You can use multiple by separating it with a comma. Only use this if the mod contains a dll file.

CodeFile - A path to the mod's HMM file. You can use multiple by separating it with a comma. Only use this if the mod contains a hmm file.

ConfigSchemaFile - A path to the mod's config schema file. This allows you to configure the mod straight from Hedge Mod Manager. Only use this if the mod has configuration support.

The "[Desc]" section

Click here to expand...

Title - The name of your mod as shown in the manager.

Description - A description of your mod that is shown in the description window in the manager. Typing "\n" in this value will indicate a new line within the manager, which should be done to keep your mods loadable!

Date - The date the mod was created as shown in the manager.

Author - The author(s) of the mod.

Note: You can include multiple authors in this value by separating them with " & " (without the quotes). They'll load as separate authors within the manager, allowing you to link to them separately.
Example: "Radfordhound & Gotta Play Fast"

AuthorURL - The URL(s) to the author(s) of the mod. (Such as websites, YouTube channels, and social media accounts.)

Note: You can include multiple URLs in this value by separating them with " & " (without the quotes). They'll load as separate URLs within the manager, automatically linking with the data contained in the "Author" value
Example: "https://www.youtube.com/user/Radfordhound & https://www.youtube.com/channel/UCZfOGBkXRKICFozWU5bE0Xg"

URL The URL of the mod (aka mod homepages/threads/release videos).

Many other values can be used in a mod.ini file, plenty of which are already being used in several mods. Keep an eye out for them in other released mods!

HMM Wiki

Clone this wiki locally