GuideToTroubleshootingRimWorldMods.md

sumghai's Guide to Troubleshooting RimWorld Mods

So you're minding your own business running your colony, when you suddenly get an error message or see bizarre behaviour like patients not getting off MedPods, machine gun turrets not firing at targets, or lolita ratgirls suddenly vomiting uncontrollably after eating Replimat meals.

Running mods in RimWorld is like adding new accessories to a sports car while it is rolling down the highway - the more parts/mods you have, the more complex the interactions between them, and the more likely something will go wrong.

To complicate matters, most parts/mods are made by different authors, who cannot realistically design their mods to work with every other mod or every possible play style.

Finally, many modders have professional careers, families and other real-life commitments. To them, RimWorld is just a hobby, and they often have very little time each day/week/month to decipher gigabytes of log files or chase down transient bugs.

Therefore, it is very important that you do some basic diagnosing of the problem yourself, and provide clear, exact and concise information in bug reports, so that mod authors can get to work fixing the bug as quickly as possible.

The following guide describes best practices for mod troubleshooting and bug reporting.

Contents

• Step 1: Make sure to run the latest stable version of the game/mods
• Step 2: Clear your configs
• Step 3: Sort your modlist
• Step 4: Check for known incompatible mods
• Step 5: Verify that the mod works on its own
• Step 6: Conduct a Binary search
• Step 7: Submit a bug report
• Step 8: Following up

Step 1: Make sure to run the latest stable version of the game/mods

Ludeon Studios updates the base RimWorld game on a semi-regular basis, adding new features, changing internal code or fixing old bugs. Many modders often take advantage of these major updates to also update their mods accordingly.

Because many base game updates and fixes are not backwards-compatible with old or existing savegames, most modders cannot guarrantee that they can continue to support older versions of their mods.

Therefore, please make sure:

• You are running the latest stable version of RimWorld

  • Check the version number on the upper right corner of the main menu screen, and make sure it matches the latest version number announced by Ludeon Studios on their Steam Workshop RimWorld news page
  • Avoid running unstable builds, as they often contain experimental code that might not actually go into the next stable update.
  • If you are running RimWorld through Steam, be sure to verify your game files; in your Steam client, go to the Library section, right-click on RimWorld and select Properties, then in the Local files tab, click Verify integrity of game cache... and wait for the game files to be verified

• You are running the latest stable version of every mod

  • Most modders will include a version number or release date in their mod's About.xml file, ModSync or Mod Manager Manifests
  • Check that this version number matches the latest version number announced on the mod's Steam Workshop page, Ludeon Forums thread, Discord server post etc.

If you consciously choose to run an older copy of RimWorld (e.g. you have a bootleg copy, or your savegame is dependent on an outdated mod), please be aware that modders reserve the right to not provide support for outdated game/mod versions.

Step 2: Clear your configs

Mods often store configuration files containing player-customisable settings.

Over time, these config files may contain settings, parameters and other data no longer needed by newer versions of the mods, and are not automatically removed when mods are uninstalled.

Because these outdated settings and/or obsolete config files often cause errors, the best thing to do is to nuke them all from orbit, just to be sure clear them out regularly when diagnosing mod problems, which will reset most mods back to their default settings.

1. Go to %appdata%\..\LocalLow\Ludeon Studios\RimWorld by Ludeon Studios\Config

2. Delete everything inside the folder, except ModsConfig.xml

You will need to keep your active mod load order for later troubleshooting steps.

Step 3: Sort your modlist

Many mods need to be loaded by RimWorld in a specific order to work properly. Ways of sorting your modlist include:

• In the mods dialog window, click Auto-sort mods; this is the crudest method, and is entirely dependent on how each modder has tagged their mods' dependencies and compatibility
• Using RimPy Mod Manager's automatic sorting feature, combines both the base game's Auto-sort mods feature and community-curated mod load order rules; You will need both the RimPy application itself and the mod sorting database
• Trisscar's Mod Order Guide
• Manually dragging and sorting your modlist, based on the following list of mod categories:

- Harmony
- Core and DLCs (e.g. Royalty, Ideology)
- Function/framework library mods (e.g. JecsTools, Hugslib)
- Humanoid Alien Races framework
- EdB Prepare Carefully
- Other "Core" mods, aside from the sssentials.
- Mods affecting map/planet generation (including new biomes and rock types)
- Faction mods (excluding those that add new pawn types)
- Trait/Name mods
- Medical mods, such as those that add new diseases, surgeries, prosthetics etc.
- "Ornery" mods, or those prone to conflicts (e.g. Hospitality)
- Game/pawn behavior/mechanics/UI-altering mods
- Storyteller mods
- Apparel, hairstyle, building, vegetation, crafted item mods
- Pawn type / animal / alien race mods
- Mods affecting pawn rendering
- Childhood and pregnancy mods
- Combat Extended
- Any compatibility patches, translation packs etc.
- Performance mods (e.g. RimThreaded)

Step 4: Check for known incompatible mods

Sometimes mods by different authors step on each other's toes while both are trying to change the same parts of the base game, or are simply not designed to be used together.

Regardless of the reason, you should check the following places for the names/IDs of other mods that will conflict with your mod in question:

• The mod's Steam Workshop description. Look for keywords like "Compatibility" or "Incompatible Mods".

• The mod's About.xml file. RimWorld's mod menu should highlight (in red) if you are running two or more mods that are conflicting with each other.

Disable all incompatible and conflicting mods, restart the game, and reload your savegame to see if the problem persists.

Step 5: Verify that the mod works on its own

So you suspect one particular mod to be causing problems, but before you jump to conclusions, it's best to make sure:

1. Enable Development mode, by going into Options > Gameplay and ticking the Development mode checkbox

2. Disable all your other mods, except for the mod you're diagnosing

3. Enable any dependencies that the mod you're diagnosing needs

4. Start a new, temporary savegame with this cut-down modlist

   • Depending on the issue, you can save loading time by generating the smallest world with the fewest factions and smallest map size

5. Enable God mode from the Development menu at the top of the screen

   • This allows you to quickly build buildings and furniture, without waiting to finish research or gather construction resources

6. Try to reproduce the bug by using the various Development mode tools to quickly recreate the situation where you first experienced the bug in your regular savegame

   • This might include spawning or destroying pawns/items/structures, adding/removing hediffs, changing the terrain/weather, etc.

If you manage to recreate the bug: Go straight to submitting a bug report.

If you cannot recreate the bug: It's probably a mod conflict, so it's time to narrow things down further.

Step 6: Conduct a Binary search

So let's say the mod works fine on its own, but apparently not with other mods.

To narrow down which other mods are conflicting with the mod in question, we need to go through a process of elimination. The fastest way to do so is to conduct a Binary Search or search-by-halves:

1. Make sure you're in Development mode (Options > Gameplay, tick the Development mode checkbox)

2. Make a list of all your mods (on paper, a Microsoft Excel spreadsheet, etc.)

3. Make sure you are running the mod being diagnosed (and all its dependencies) for all subsequent steps

4. Disable half of your existing list of mods

5. Start a new, temporary savegame with this cut-down modlist

6. Try to recreate the bug using God mode and other Development mode tools

7. a) If the bug occurs, the conflicting mod is in your current sublist of mods

   • Cross out the other mods on your list, as those are safe/compatible mods
   • Go to Step 4

   b) If the bug doesn't occur, the conflicting mod is in the other (disabled) sublist of mods

   • Cross out your current list of mods, as these are safe/compatible mods
   • Swap your current modlist with the mods you haven't marked as safe/compatible yet
   • Go to Step 5

By repeating this process several times, you can quickly narrow down a large modlist; for example, it would only take 8~9 search iterations to identify mod conflicts between 400 mods.

Step 7: Submit a bug report

Now that you've figured out which mods are conflicting to cause errors, you're tempted to dump your entire log file at the mod author and call it a day. Job done, right?

Not so fast, bucko.

The essence of a good bug report is one that provides all the essential information for the modder to precisely and reliably recreate the bug on their own development environment - no more, no less.

Generally, a bug report should consist of the following (examples included):

• A simple, short sentence summary of the bug as the issue title
• A detailed description of the bug
• What you expect should normally happen
• Steps to reproduce the bug (in a brand-new temporary savegame)
  • Clear, simple and obvious
  • Numbered list
  • Use the present imperative mood and start with a verb, like an instruction or order (e.g. "Build a Replimat Terminal", "Toggle off the Wear Hood gizmo on the pawn")
  • The steps must recreate the bug 100% of the time; if the bug only occurs sometimes, go back and check if you've forgotten a step
• Additional information
  • Screenshots
  • Relevant Debug log / HugsLib log messages
  • If you happen to know the exact underlying XML/C# code that needs to be fixed, you can also describe them here; mod authors will love you for it
• Operating System (e.g. Microsoft Windows 10 (64-bit))
• Physical RAM (e.g. 16.0 GB)
• RimWorld base game version (e.g. 1.3.3200, not just 1.3 or "the latest")
• RimWorld DLCs loaded (e.g. none, Royalty, Ideology)
• Relevant mods and version numbers / release dates (e.g. Replimat 1.2.14, Vanilla Expanded Framework 17/01/22 snapshot)
  • Don't list your entire modlist; mod authors ain't got time for that

Shameless example of a good bug report

Different mod authors may accept bug reports at various locations, and some may require you to fill out a report according to a fixed template. Follow each modder's bug reporting procedures exactly as they instruct you, as each author knows that their particular reporting format will give them the exact information they need.

Step 8: Following up

Once you've submitted your bug report, sit tight and wait patiently.

• If the mod author asks for more information, it is most likely because they aren't able to reproduce your problem with the information you initially gave them; do your best to give what they ask for

• If the mod author marks your issue as a duplicate and closes it, don't get offended; they're probably aware of the issue from other reports and are working on it

• If the mod author asks you to test a WIP dev build of the mod, please do so ASAP; being tardy with feedback really annoys mod authors, and if nobody confirms their fixes are working, they'll be less motivated to fix future bugs

• If the mod author explains that an issue can't be fixed at all, don't take it personally; some modders have limited abilities, some issues are too rare to be reliably reproduceable, and some mod conflicts are just too difficult to fix

• If the mod author hasn't got back to you in a very long time, don't pester them by reposting or bumping your issue/comment "for visibility"; either they are already quietly working on a fix, or real-life responsibilities and commitments mean they're no longer around to maintain their mods

• If the mod author is repeatedly closing certain bug reports, it is because they have addressed the issue many times already and do not feel it is worthwhile revisiting it. They are not sweeping problems under the rug, and they are not censoring you, either.