Mod Folder Structure
This is a guide explaining the contents of mod folders and best practices for how they should be laid out for proper recognition by RimWorld as well as compatibility with other mods.
RimWorld Mod Folder
Your local Mods folder for manually installed mods as well as new local mods can be found in the following default installation locations:
| Operating System | Default Folder Location |
|---|---|
| Windows | C:\Program Files (x86)\Steam\steamapps\common\RimWorld\Mods
|
| Mac | ~/Library/Application Support/Steam/steamapps/common/RimWorld/RimWorldMac.app/Mods
|
| Linux (standalone) | ~/.steam/steam/steamapps/common/RimWorld/Mods
|
| Linux (GoG) | /home/<user>/GOG/Games/RimWorld/game/Mods/
|
Each mod should have its own subfolder within the main Mods folder. The name of individual mod folders does not matter and you can name them freely for your own personal organization; your mod's internal ID and title are defined in About.xml (see below). Unless specified otherwise, all specific files mentioned below must be capitalized and spelled correctly or RimWorld will not recognize them.
Example Mod Folder
The following is an example of a mod folder with all recognized subfolders:
Mods └ MyModFolder ├ About │ ├ About.xml │ └ Preview.png ├ Assemblies ├ Defs ├ Languages ├ Patches ├ Sounds └ Textures
About (Required)
The only folder required for all mods, the About folder contains information that identifies your mod to RimWorld and allows it to be loaded.
| Name | Description |
|---|---|
|
|
See: About.xml
|
|
|
A mod's Note: While PNG files are standard, RimWorld does not actually require a PNG file. It is possible to use JPG or even animated GIF files by simply renaming them "Preview.png", but the PNG extension must be used or RimWorld will not recognize it. |
|
|
You may see a |
Assemblies
The Assemblies folder can be used to add custom code to RimWorld in the form of compiled dynamic-link library or DLL files. Properly compiled assemblies will be automatically loaded by RimWorld.
Defs
See: Defs
XML Definitions or Defs are the primary content definition and configuration source for RimWorld. These Defs define everything from items and plants and animals to faction types and ideoligion options, and as a general rule any mod that adds additional content for RimWorld will likely be adding one or more Defs. Please see the Def guide for more detailed information.
Subfolders and even file names within the Defs does not matter as all XML files are read into memory from each individual mod and you can freely name them however you want for your own personal organization, however it is recommended that you follow vanilla conventions (SoundDefs in the /SoundDefs folder, ThingDefs in the various /ThingDef_*** folders) for readability. The one exception to this is if you are using versioned LoadFolders.xml entries: XML files with the same resolved path will overwrite each other, with the last one to be loaded taking precedence.
Languages
See: Localization
Localization is the process of creating and translating game and mod language content for different languages. This includes both translations for Defs and code-referenced text as well as word list for procedural name and content generation. Please see the localization guide for more information about the Languages folder and its subfolders.
Patches
See: PatchOperations
PatchOperations are a way of modifying Defs from the vanilla game, DLCs, or even other mods in a safe and interoperable manner. This can be used to rebalance or adjust vanilla content, remove or disable unwanted content, or provide optional changes or content for better mod compatibility. Please see the PatchOperations guide for more information.
Sounds
See: Sounds
The Sounds folder is used to hold custom sound files for mods. It is generally recommended to use Ogg files, though Unity can also recognize and use MP3 and WAV files. Please see the Sounds guide for more information.
Just like textures, sound files in RimWorld are identified by their path names; if a mod contains a sound file with the same path and file name as another mod or even the vanilla game or DLCs, then the last one to be loaded in your mod list will overwrite the others. This is sometimes done intentionally by mods that want to change vanilla or other mod's audio.
To avoid accidental collisions, it's recommended to prefix either your file names or use a namespace folder to reduce the chance that you have the exact same path as another mod:
Mods
└ MyModFolder
└ Sounds
└ MyNamespace
├ MyCustomSound.ogg
└ AnotherCustomSound.ogg
Textures
See: Textures
The Textures folder is used to hold custom texture files for mods. It is generally recommended to use PNG files. Please see the Textures guide for more information.
Just like sounds, texture files in RimWorld are identified by their path names; if a mod contains a texture file with the same path and file name as another mod or even the vanilla game or DLCs, then the last one to be loaded in your mod list will overwrite the others. This is sometimes done intentionally by re-texture mods that want to change textures from the vanilla game or other mods.
To avoid accidental collisions, it's recommended to prefix either your file names or use a namespace folder to reduce the chance that you have the exact same path as another mod:
Mods
└ MyModFolder
└ Textures
└ MyNamespace
├ MyCustomTexture.png
└ AnotherCustomTexture.png
Versioned Folders (Optional)
Note: It is strongly recommended that you do not declare support for versions of RimWorld that you do not personally test every release with, as RimWorld code and XML has changed in significant ways between every version.
Content for specific versions of RimWorld can be implemented by placing them in folders named after their minor version numbers:
Mods └ MyModFolder ├ 1.4 │ ├ Assemblies │ ├ Defs | ├ Languages │ ├ Sounds │ ├ Patches │ └ Textures ├ 1.3 │ └ ... ├ 1.2 │ └ ... ├ 1.1 │ └ ... │ ├ Common │ └ ... │ ├ About ├ Defs ├ Languages ├ Sounds ├ Patches └ Textures
- All versioned folders and the
Commonfolder can contain all normal root folders other than theAboutfolder. - For RimWorld 1.1 and later, the game will load the first versioned folder that is compatible with the version of the game. Thus, if you only had folders for
1.4and1.2, then RimWorld v1.4 would load the1.4folder, while RimWorld v1.3 and v1.2 would both load the1.2folder. All versions will also loadCommonand any direct root folders. - For RimWorld 1.0 only, the game does not recognize the
Commonfolder. RimWorld v1.0 is capable of recognizing a1.0folder, but if it is used then the game WILL NOT load from the root folder; for mods that support RimWorld v1.0, it is typically recommended that content be placed into root folders and override content for newer versions be placed into versioned folders. - Files with the same relative path will overwrite each other, with the most specific one taking precedence; this applies to XML files (both Def and Patch files), audio files, language files, and textures. Thus, if you have
Defs/MyFile.xml,Common/Defs/MyFile.xml, and1.4/Defs/MyFile.xml, only the last one will be read.
LoadFolders.xml (Optional)
Specific rules for which folders are loaded for which version of the game, as well as optional folders to be loaded for specific DLCs or mods can be specified by using a special file called LoadFolders.xml. This file should be placed in your root mod folder:
Mods └ MyModFolder └ LoadFolders.xml
LoadFolders.xml allows you to specify exactly which folders should be loaded for given versions of RimWorld. This supersedes the default versioned folder rules as specified above for all versions of RimWorld except v1.0, which means that you will need to specify the root or Common folders if you wish to use them. An example file is shown here:
<?xml version="1.0" encoding="utf-8" ?>
<loadFolders>
<v1.3>
<li>/</li>
<li>1.3</li>
<li IfModActive="Ludeon.RimWorld.Ideology">Ideology/1.3</li>
<li IfModActive="CETeam.CombatExtended">CombatExtended/1.3</li>
</v1.3>
<v1.4>
<li>/</li>
<li>1.4</li>
<li IfModActive="Ludeon.RimWorld.Ideology">Ideology/1.4</li>
<li IfModActive="CETeam.CombatExtended">CombatExtended/1.4</li>
</v1.4>
</loadFolders>
This example file specifies that the root folder and a versioned folder should be loaded for RimWorld v1.3 and v1.4, and optionally loads extra folders based on whether the Ideology DLC and/or Combat Extended mods are loaded. This might correspond to a mod folder structure as follows:
Mods └ MyModFolder ├ 1.4 │ ├ Assemblies │ ├ Defs │ └ Patches ├ 1.3 │ └ ... │ ├ Ideology │ ├ 1.4 │ │ └ ... │ └ 1.3 │ └ ... ├ CombatExtended │ ├ 1.4 │ │ └ ... │ └ 1.3 │ └ ... │ ├ About ├ Sounds ├ Textures └ LoadFolders.xml
- Folders that should be loaded if mods and DLCs are not loaded can also be specified using
IfModNotActive. Mods and DLCs specified usingIfModActiveorIfModNotActive - If you have files with the same relative path, then the last one specified by your load order will be used. Thus in the above example setup, if you had
Defs/MyFile.xml,1.4/Defs/MyFile.xml, andIdeology/1.4/Defs/MyFile.xml, then the Ideology version would be loaded. This applies to all XML files (both Defs and Patches), Sounds, Textures, and Language files. - If you have both a local version of the mod, as well as the steam version, you will need to qualify the steam version with
_steamfor requiring it to test out compatibility with the steam version. In the example above,IfModActive="CETeam.CombatExtended"would becomeIfModActive="CETeam.CombatExtended,CETeam.CombatExtended_steam"to support both a local mod version of Combat Extended as well as the steam version.
Miscellaneous
The Core game as well as all DLC folders are functionally identical to mod folders with the exception that official content textures and sound files are bundled into a Unity asset bundle rather than being saved directly to their respective folders. You can find these under the /Data folder inside your RimWorld directory.
Source Files
Some mods contain a Source folder containing the source code for their compiled assemblies. This is not read by RimWorld in any way but can be included if you wish to share the source code for your assemblies, but it is strongly recommended that you use a public code repository such as GitHub instead as it's easier to read at a glance and shows changes over time that can help diagnose issues and bugs.