Editing Modding Tutorials/Mod Folder Structure

{{DISPLAYTITLE:Mod Folder Structure}}

{{BackToTutorials}}

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 <code>Mods</code> folder for manually installed mods as well as new local mods can be found in the following default installation locations:

{| class="wikitable" style="margin-right:auto"
|-
! Operating System !! Default Folder Location
|-
| Windows || <code>C:\Program Files (x86)\Steam\steamapps\common\RimWorld\Mods</code>
|-
| Mac || <code>~/Library/Application Support/Steam/steamapps/common/RimWorld/RimWorldMac.app/Mods</code>
|-
| Linux (standalone) || <code>~/.steam/steam/steamapps/common/RimWorld/Mods</code>
|-
| Linux (GoG) || <code>/home/<user>/GOG/Games/RimWorld/game/Mods/</code>
|}

Each mod should have its own subfolder within the main <code>Mods</code> 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 [[Modding_Tutorials/About.xml|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:

<source>
Mods
└ MyModFolder
  ├ About
  │ ├ About.xml
  │ └ Preview.png
  ├ Assemblies
  ├ Defs
  ├ Languages
  ├ Patches
  ├ Sounds
  └ Textures
</source>

== <code>About</code> (Required) ==

The only folder required for all mods, the <code>About</code> folder contains information that identifies your mod to RimWorld and allows it to be loaded.

<div class="TutorialTableWrapper">
{| class="TutorialCodeTable"
! Name !! Description
|-
| class="TutorialCodeTable-description" |
<code>About.xml</code>
'''(Required)'''
| class="TutorialCodeTable-description" |
''See: [[Modding_Tutorials/About.xml|About.xml]]''

<code>About.xml</code> 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 [[Modding_Tutorials/About.xml|full guide]] for more information.
|-
| class="TutorialCodeTable-description" |
<code>Preview.png</code>
'''(Required)'''
| class="TutorialCodeTable-description" |
A mod's <code>Preview.png</code> 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 <code>Preview.png</code>.

'''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.
|-
| class="TutorialCodeTable-description" |
<code>ModIcon.png</code>
''(Optional)''
| class="TutorialCodeTable-description" |
New in RimWorld 1.5, a mod's <code>ModIcon.png</code> is shown during game loading screens and in the Options UI if your mod has [[Modding_Tutorials/ModSettings|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.
|-
| class="TutorialCodeTable-description" |
<code>Manifest.xml</code>
''(Obsolete)''
| class="TutorialCodeTable-description" |
You may see a <code>Manifest.xml</code> file in some older mods. This was a file used by [https://steamcommunity.com/sharedfiles/filedetails/?id=1507748539 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 <code>About.xml</code>; you do not need this file unless you want specific additional features provided by Mod Manager.
|-
|}
</div>

== <code>Assemblies</code> ==

The <code>Assemblies</code> folder can be used to add custom code to RimWorld in the form of compiled [https://en.wikipedia.org/wiki/Dynamic-link_library dynamic-link library] or DLL files. Properly compiled assemblies will be automatically loaded by RimWorld.

== <code>Defs</code> ==

''See: [[Modding_Tutorials/Defs|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 [[Modding_Tutorials/Defs|Def guide]] for more detailed information.

Subfolders and even file names within the <code>Defs</code> 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 (<code>SoundDef</code>s in the <code>/SoundDefs</code> folder, <code>ThingDef</code>s in the various <code>/ThingDef_***</code> folders) for readability. The one exception to this is if you are using versioned <code>LoadFolders.xml</code> entries: XML files with the same resolved path will overwrite each other, with the last one to be loaded taking precedence.

== <code>Languages</code> ==

''See: [[Modding_Tutorials/Localization|Localization]]''

'''[https://en.wikipedia.org/wiki/Internationalization_and_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 [[Modding_Tutorials/Localization|localization guide]] for more information about the <code>Languages</code> folder and its subfolders.

== <code>Patches</code> ==

''See: [[Modding_Tutorials/PatchOperations|PatchOperations]]''

'''<code>PatchOperations</code>''' 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 [[Modding_Tutorials/PatchOperations|PatchOperations guide]] for more information.

== <code>Sounds</code> ==

''See: [[Modding_Tutorials/Sounds|Sounds]]''

The <code>Sounds</code> folder is used to hold custom sound files for mods. It is generally recommended to use [https://en.wikipedia.org/wiki/Ogg Ogg files], though Unity can also recognize and use MP3 and WAV files. Please see the [[Modding_Tutorials/Sounds|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:

<source>
Mods
└ MyModFolder
  └ Sounds
    └ MyNamespace
      ├ MyCustomSound.ogg
      └ AnotherCustomSound.ogg
</source>

== <code>Textures</code> ==

''See: [[Modding_Tutorials/Textures|Textures]]''

The <code>Textures</code> folder is used to hold custom texture files for mods. It is generally recommended to use [https://en.wikipedia.org/wiki/PNG PNG files]. Please see the [[Modding_Tutorials/Textures|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:

<source>
Mods
└ MyModFolder
  └ Textures
    └ MyNamespace
      ├ MyCustomTexture.png
      └ AnotherCustomTexture.png
</source>

== 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:

<source>
Mods
└ MyModFolder
  ├ 1.4
  │ ├ Assemblies
  │ ├ Defs
  | ├ Languages
  │ ├ Sounds
  │ ├ Patches
  │ └ Textures
  ├ 1.3
  │ └ ...
  ├ 1.2
  │ └ ...
  ├ 1.1
  │ └ ...
  │
  ├ Common
  │ └ ...
  │
  ├ About
  ├ Defs
  ├ Languages
  ├ Sounds
  ├ Patches
  └ Textures
</source>

* All versioned folders and the <code>Common</code> folder can contain all normal root folders other than the <code>About</code> 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 <code>1.4</code> and <code>1.2</code>, then RimWorld v1.4 would load the <code>1.4</code> folder, while RimWorld v1.3 and v1.2 would both load the <code>1.2</code> folder. All versions will also load <code>Common</code> and any direct root folders.
* '''For RimWorld 1.0 only''', the game does not recognize the <code>Common</code> folder. RimWorld v1.0 is capable of recognizing a <code>1.0</code> 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 <code>Defs/MyFile.xml</code>, <code>Common/Defs/MyFile.xml</code>, and <code>1.4/Defs/MyFile.xml</code>, only the last one will be read.

== <code>LoadFolders.xml</code> (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 <code>LoadFolders.xml</code>. This file should be placed in your root mod folder:

<source>
Mods
└ MyModFolder
  └ LoadFolders.xml
</source>

<code>LoadFolders.xml</code> 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 <code>Common</code> folders if you wish to use them. An example file is shown here:

<source lang="xml">
<?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>
</source>

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:

<source>
Mods
└ MyModFolder
  ├ 1.4
  │ ├ Assemblies
  │ ├ Defs
  │ └ Patches
  ├ 1.3
  │ └ ...
  │
  ├ Ideology
  │ ├ 1.4
  │ │ └ ...
  │ └ 1.3
  │   └ ...
  ├ CombatExtended
  │ ├ 1.4
  │ │ └ ...
  │ └ 1.3
  │   └ ...
  │
  ├ About
  ├ Sounds
  ├ Textures
  └ LoadFolders.xml
</source>

* Folders that should be loaded if mods and DLCs are ''not'' loaded can also be specified using <code>IfModNotActive</code>. Mods and DLCs specified using <code>IfModActive</code> or <code>IfModNotActive</code>
* 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 <code>Defs/MyFile.xml</code>, <code>1.4/Defs/MyFile.xml</code>, and <code>Ideology/1.4/Defs/MyFile.xml</code>, 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 <code>_steam</code> for requiring it to test out compatibility with the steam version. In the example above, <code>IfModActive="CETeam.CombatExtended"</code> would become <code>IfModActive="CETeam.CombatExtended,CETeam.CombatExtended_steam"</code> to support both a local mod version of Combat Extended as well as the steam version.

== Miscellaneous ==

The <code>Core</code> 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 <code>/Data</code> folder inside your RimWorld directory.

=== <code>Source</code> Files ===

Some mods contain a <code>Source</code> folder containing the source code for their compiled assemblies. This is not read by RimWorld in any way and is generally not recommended as the vast majority of players will not need to see or use your source code, and including it will cause unnecessary bloat in downloads for your mod. If you wish to share your source code, it is strongly recommended that you use a public code repository such as [https://github.com/ GitHub].

[[Category:Modding]]
[[Category:Modding tutorials]]