Mod Folder Structure

From RimWorld Wiki
Jump to navigation Jump to search
?
Under Review
This tutorial or guide is currently undergoing review and should not be considered ready to use.

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
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.

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.

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

(Placeholder)

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.