Mod Folder Structure

< Modding Tutorials

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
About.xml (Required)	See: About.xml About.xml is used to identify a mod to RimWorld so it can be loaded, and can also be used to specify dependencies and load order helpers for mod compatibility. Please see the full guide for more information.
Preview.png (Required)	A mod's Preview.png is used as the preview image for that mod in both the in-game mod manager as well as Steam Workshop. It is strongly recommended to use a 640x360 PNG file as this is the default size and aspect ratio (16/9) configured for RimWorld and using other sizes may result in blurring or letterboxing. You can also opt to use 1280x720 for higher resolution artwork, but preview files must remain under 1MB or Steam Workshop will reject your upload. If you get a "limit exceeded" error, then double-check the size of your Preview.png. 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.
ModIcon.png (Optional)	New in RimWorld 1.5, a mod's ModIcon.png is shown during game loading screens and in the Options UI if your mod has mod settings. It should be either a 32x32 or 64x64 PNG file, and too much detail or color should be avoided; Unity texture compression will make overcomplicated icons very crunchy.
Manifest.xml (Obsolete)	You may see a Manifest.xml file in some older mods. This was a file used by Fluffy's Mod Manager as well as some external mod managers for dependency and versioning information in older versions of RimWorld. This is generally considered obsolete as the most important benefits of having a manifest file have largely been mainlined into About.xml; you do not need this file unless you want specific additional features provided by Mod Manager.

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 Common folder can contain all normal root folders other than the About folder.
• 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.4 and 1.2, then RimWorld v1.4 would load the 1.4 folder, while RimWorld v1.3 and v1.2 would both load the 1.2 folder. All versions will also load Common and any direct root folders.
• For RimWorld 1.0 only, the game does not recognize the Common folder. RimWorld v1.0 is capable of recognizing a 1.0 folder, 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, and 1.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 using IfModActive or IfModNotActive
• 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, and Ideology/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 _steam for requiring it to test out compatibility with the steam version. In the example above, IfModActive="CETeam.CombatExtended" would become IfModActive="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.