# How mods work

## Turning mods on and off

A change to your mod list takes effect when you restart the game, as in RimWorld and Factorio. A
mod you subscribe to on the Workshop starts turned off. Tick it in the Mods menu and press Apply
and restart. Turning a mod on also turns on the mods it needs, if you have them.

Workshop updates download when the game starts. An update that arrives while you play waits for
the next start, so nothing changes in the middle of a run.

## Load order

The game sorts your mods every time it starts. A mod that needs another mod loads after it. Mods
also fall into layers, which load in this order.

1. Raid Haven itself.
2. Libraries that other mods build on.
3. Content mods, with new things, balance changes and compatibility patches.
4. Languages.
5. Looks and sound, so a reskin covers base and mod content alike.

You can move a mod up or down inside its layer. If a move would break a requirement, the game
refuses it and says why. For example, "Ironclad Arms needs Core Library, so it has to load after
it." Auto-sort puts everything back in the default order, and History keeps the last 10 orders
in case you want one back.

## When two mods change the same thing

If two mods change the same value, the one that loads later wins. The Mods menu tells you which
values overlap and whose are used.

> Better Balance and Ironclad Arms both change 7 values, such as Iron Longsword damage. Better
> Balance's values are used because it loads later.

Mods that say they can't run together are never on at the same time. If one mod turns off
something another mod uses, only that part is dropped, and the warning names both mods. For
example, "No Archers turns off Archer, so Sea Raiders' Tide raid spawns without it."

## When a mod is broken

A broken mod never crashes the game or stops it from starting. If one item in a mod has a
mistake, that item is skipped and the rest of the mod loads. Only a broken `mod.json`, the file
that names the mod, keeps a whole mod off.

Problems are listed in the Problems tab of the Mods menu, each in a plain sentence and with a
fix button where one exists. For mod makers, a problem also names the file, line and field. A
missing comma in Frost Blade gives a message much like this one.

```text wrap
ERROR: Frost Blade was not loaded
File: My First Mod / prototypes/weapons/frost_blade.lua, line 5
Problem: A comma is missing at the end of line 4, right before "damage".
Fix: Add a comma (,) at the end of line 4.
What happened: Frost Blade is not in the game until you fix this. The rest of My First Mod loaded normally.
```

## Errors during a run

A mod's script can still fail while you play. When one does, the game catches the error and
carries on. A small notice in the bottom right corner of the screen names the mod. Expand it to
see the file, the line and the stack trace. The notice can be turned off in the settings.

Every error also goes into `mods.log`. Copy report in the Mods menu puts a plain-text report on
your clipboard, ready to paste into a bug report. [Get help](/raid-haven/help/) has more on
both.

## Mods aren't throttled

Mods are not throttled. Scripts get no time budget, and a slow mod isn't paused or cut off.
RimWorld and Factorio work the same way.

Keeping a mod fast is up to its maker. A slow script slows the whole game, so test with big
raids. Wave 99 with a 3× Raiders multiplier and Brutal wave growth puts about 300 raiders on the
map.

## Saves

A save remembers which mods it used. If you load a save that uses content from a mod you don't
have on, the game asks first. It lists each missing mod and what the save uses from it, such as
"3 items, 1 building". Then it offers to turn the mods on, get them from the Workshop, or
continue without them.

If you continue without a mod, its content is kept but does nothing. Its items become stand-ins,
its buildings are put away and its raids play as Siege. When the mod comes back, its content
comes back with it. The first time mods change a save, the game keeps a copy of the save as it
was.

A save that uses nothing from a missing mod loads without asking.

## Achievements, Renown and Records

Gameplay mods turn off Steam achievements for that run. Cosmetic mods, such as text, reskins,
music and name packs, keep them. Renown and the Glossary keep working in modded runs, and
Records puts modded runs on their own Modded board.

Before a gameplay mod joins an unmodded save, the game warns you that the save will become a
Modded game with no Steam achievements.