This is the full developer documentation for Raid Haven # Modding Raid Haven > What a Raid Haven mod is, how to get mods, how to make them, and where to ask. Mods add weapons, armor, raiders, raid types and buildings to Raid Haven, change how the game looks and sounds, and translate it. This site has the guides and the reference for making them. ## What a mod is A mod is a folder of files. You describe content in Lua tables, which read a lot like JSON with comments. Art is PNG and sound is WAV or OGG. Most mods need no programming. The first tutorial makes Frost Blade, a blue copy of the Iron Longsword. You copy the sword, rename it, recolour its picture and change a number or two. Some things can’t be done with data alone, like a raider with its own AI or a raid type with its own rules. For those you write Lua scripts against the game’s mod API. Scripts run in a sandbox, so a mod from the Workshop can’t touch your files, the network or Steam. [What you can mod](/raid-haven/what-you-can-mod/) goes through each area of the game. ## Getting mods Mods come from the Steam Workshop. Subscribe to a mod, open Mods on the title screen, tick it and restart the game. The Mods menu also has a Workshop tab, so you can browse and subscribe without leaving the game. The game sorts your mods into a working load order. When something is wrong, the Mods menu says which mod it is, what happened and what to do about it. [How mods work](/raid-haven/how-mods-work/) has the details. Mods are for the full game. The demo doesn’t load them. ## Making mods Turn on Mod Author mode in the game’s settings to get the tools for making mods. * New mod sets up a folder from a starter, such as a weapon, a raider, a raid type or a translation. * F5 reloads your mod’s data while the game runs. Art, sound and text reload as soon as you save the file. * Test my mod opens the Mod Lab, a small test map with Dev Mode on. You can spawn any raider, start any raid type at any wave and give your pawns any item. Lab runs never touch your saves. * You publish and update your mod on the Workshop from inside the game. The free Mod Kit is in the `ModKit` folder next to the game. It has example mods and sprite templates with the grip, tip and feet points marked. It also has every base item as a file you can copy, and the game’s palette. The examples and templates are CC0, so you can use them in your own mods however you like. If you work with a coding agent such as Claude Code, [Using an AI agent](/raid-haven/ai-agents/) shows how to give it these docs. ## Help Questions go to the modding support channel on the [Raid Haven Discord](https://discord.gg/RtJT2BcXKU). [Get help](/raid-haven/help/) says what to include when something goes wrong. # What you can mod > The parts of Raid Haven that mods can add or change, what isn't moddable yet, and what stays fixed. Everything on this page can be made with data files. Lua scripts add raider AI, raid types, abilities and building behaviour on top. Things that aren’t moddable yet are listed near the end. ## Weapons * New weapons of the five existing types (melee, ranged, slow projectile, beam and area launcher) at any rarity. * Start from nothing, or copy a base weapon and list only what changes. Frost Blade starts as a copy of the Iron Longsword. * Your own sprite, projectile, and fire and impact sounds. How a pawn holds it is picked by name, such as sword, staff or bow. * Any existing ability, or a new area ability built from radius, damage, burn, slow, knockback and building damage. It can trigger on hit, on kill, or when aimed at a point. * Which of the Market, wave rewards, raider kits and Champion loot it turns up in. Raiders take their gear from the same weapons, so a mod weapon ends up in raiders’ hands unless you leave it out of raider kits. A mod Legendary in the kit pool shows up on high-level raiders. Lua scripts can give an ability its own logic. ## Armor and healing items New armor has protection, agility, an attack bonus for one skill line, and a rarity. Its art is one 96×48 PNG with three poses: facing you, facing away and facing right. Facing left is the right pose mirrored. New healing items work like the Bandage and Herbal Tonic. They heal a share of max HP, a flat amount or both, over a time you set. Each has a 20×20 icon and its own sounds. You also choose how often an item shows up on supply reward cards and where it sits in Quick Heal. A pawn can still use one item of each type per wave, and each mod item is its own type. ## Raiders * Name, description and map colour. * Health, speed and damage as a percentage of normal. Stats still follow the raider’s level, on the same curve as pawns. * Raid cost, how often it appears in normal raids, and the coins it drops. A spawn weight of 0 keeps a raider for your own raid types. * A fixed weapon and armor, one set per rarity, or a roll from the raider kit pool. * One of the game’s 26 bodies, or your own 96×48 body sheet. * What it goes for (pawns, walls or buildings), and a role such as healer or exploder. * An existing AI behaviour, from the ones that work outside their own raid type. Lua scripts can give a raider its own AI. It thinks a few times a second and gives orders like move, attack, hold or flee. ## Champions and Champion Traits New Champion kits pair a weapon with armor. New Champion abilities are built from the seven existing kinds: self burst, ground strike, leap, chain, rupture, gravity well and bulwark. Each gets its own numbers, effects and telegraph colours. A Champion attack always shows its telegraph for its wind-up plus the wave’s reaction window. The window shrinks from 2 seconds on wave 10 to 0.4 seconds on wave 100, and mod attacks can’t skip it. New Champion Traits use the existing stats: damage, attack speed, max HP and move speed. Each has a skill line, a value for every rarity from Common to Legendary, and an 18×16 icon. They join the trait offer after a Champion wave on the same terms as the base traits, and balance mods can edit the base traits. ## Raid types A raid type made from data has a name, a description and an 18×16 icon. It sets its signature raiders and a fill from the normal mix or its own list. Raiders come in from map edges you pick, or land on the beach. It can ask for a map with a coast or open ground, and bring world events. Mod raid types roll alongside the base ones, but together they get at most 25% of the roll, so the base raids keep their chances. By default a mod raid type is available from the start, with no Renown unlock or quest. The game only places raiders where they can walk to the camp. The guaranteed map-changing raid every five waves still picks a base raid type. With Lua you can script a whole raid type. That covers what it locks in during Prepare, its roster, and what happens when it starts, on each tick, and when raiders spawn or die. ## Map events A mod raid type can bring a world event that lasts the whole raid. Events are made from these parts. * An overlay, either a colour tint or a scrolling texture such as dust streaks or rain. * Darkness and a colour tint over the map. * Lower hit chance for ranged attacks, magic and defenses, on both sides. * Slower movement for raiders and pawns, never below half speed. * One of the built-in events as it is: the tsunami, volcano, snowstorm or sandstorm. A dust squall is a good example. Dust blows across the island, ranged attacks miss more often and everyone moves a little slower. ## Buildings and defenses Every mod building is one of the existing kinds: wall, thin wall, door, gate, floor, trap floor, furniture or defense. It draws its art in that kind’s layout. It sets its own costs, HP, build work, cover, light, animations, build menu category and Market unlock price. That covers walls like the Iron Wall, thin walls like the Sandbag, sprite floors like the Rug, and lanterns, braziers and war banners. Doors and gates use the game’s fixed layouts, and a trap floor reuses an existing trap’s behaviour with your own art and numbers. A defense gets its own profile. The profile picks how it fires (a lobbed shot, a rolling boulder, a bolt or a chain). It also sets damage, range, cooldown, firing arc, blast radius, the projectile and the sounds. Lua scripts can give a building its own behaviour. ## Looks, sound and text * Mod content shows in the build menu, inventory, Market, tooltips, raid forecast and Glossary, with a line saying which mod it came from. * Rarity colours, including colour-blind and high-contrast sets. * Replacement icons, effect sheets, controller glyphs, creature sheets and any of the game’s 306 sounds. * Sounds for your own content, and title screen music from WAV or OGG files. * Text in any of the game’s 31 languages, translations of other people’s mods, and fixes to the game’s own text. A line missing in the player’s language shows in English. * Loading screen tips, pawn name packs, and appearance packs with hair, bodies, and skin and hair colours. ## Rules and balance * House rule presets for Customise Game, covering crit, parry, cover, wave budget and growth, roster caps, Champion HP, starting pawns and more. * World presets for Start From, made from the existing land steps. * Balance changes. A mod can change any field of any base entry, like the Red Oak Bow’s cooldown. ## Not moddable yet These are planned for later updates. * Renown shops, unlocks, upgrade tracks and quests from mods. * New UI panels written in Lua, and theme packs with HUD colours, fonts and mouse cursors. * World events with their own scripted behaviour and timing. * Status effects such as poison or stun. * Traits with new kinds of effect, like the base game’s Champion Slayer and Thornhide. * New ambient sounds, and music during raids. Base raids stay without music, and the hook plays nothing unless a mod adds some. * Painted floors like the Wood Floor, and trap behaviour made from data. * Challenges, new ruins, biome looks, wildlife made from data, and Market prices. * Whole new languages. ## What stays fixed * Steam achievements. * The 100-wave run, the squad cap of 7, a Champion every 10th wave and the map-changing raid every five waves. * New resource types. The four materials are fixed. * Pawn jobs and work AI. * Map size and tile types. * Shaders and post-processing. * The first-run tutorial. It only runs without gameplay mods. The game’s design rules hold for mods too. Wildlife leaves during raids, and no mod can put floating text over units or places in the world. Every raider must be able to reach the camp, Champion telegraphs keep their reaction window, and camera shake follows the Screen Shake setting. # How mods work > Load order, conflicts, broken mods, errors, performance and saves. ## 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 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. # Using an AI agent > How to point a coding agent such as Claude Code, Codex or Cursor at these docs, and a prompt to start a mod with. You can use a coding agent such as Claude Code, Codex or Cursor to help with a mod. Give it the plain-text copies of this site. They have the same content as the pages without the menus around them. ## The text files | File | What it holds | | ------------------------------------------------------------------------------ | ------------------------------------------------ | | [llms.txt](https://modding.tabbingstudios.com/raid-haven/llms.txt) | A short index that points to the two files below | | [llms-full.txt](https://modding.tabbingstudios.com/raid-haven/llms-full.txt) | Every page in one Markdown file | | [llms-small.txt](https://modding.tabbingstudios.com/raid-haven/llms-small.txt) | The same, shortened for agents with less room | If your agent can fetch web pages, give it the address of `llms-full.txt`. If it can’t, save the file into your mod’s folder and tell the agent to read it. On a wide screen, most pages also have Copy page as Markdown under “On this page”, for pasting a single page into a chat. ## A prompt to start with Open your mod’s folder in the agent, paste this, then write your idea after the last line. Make a mod ``` I'm making a mod for Raid Haven, a game by Tabbing Studios. This folder is the mod. First read https://modding.tabbingstudios.com/raid-haven/llms-full.txt. It is the game's modding documentation in one Markdown file. Follow the docs exactly. Only use file names, folder layouts, field names and functions that the docs show, and copy their examples where you can. If my idea needs something the docs don't cover, stop and tell me instead of guessing. Before you write anything, tell me which parts of my idea are data and which need a Lua script, and which pages you are following. When you're done, list the files you made and tell me what to check in the Mod Lab. This is my idea. ``` ## The Mod Kit The Mod Kit in the `ModKit` folder next to the game has an `AGENTS.md`, a file written for coding agents. Copy it into your mod’s folder and most agents read it on their own. It also has the Lua annotation files that give autocomplete in VS Code, for content fields and for the scripting API. An agent can read those too. An agent follows the same rules you do, and it can still get things wrong. Load what it made in the Mod Lab and read the Problems tab before you publish it. # Get help > Where to ask about Raid Haven modding, and what to put in a problem report. Ask in the modding support channel on the [Raid Haven Discord](https://discord.gg/RtJT2BcXKU). It’s the one place for modding questions and problem reports. If something on this site is wrong or unclear, say so in the same channel. ## What to put in a report These make a problem much quicker to track down. * The Copy report text. Open Mods on the title screen, go to the Problems tab, press Copy report and paste the result into your message. During a run, the Mods panel in the pause menu has the same button. * What you did and what happened, such as “Started a Pirate Tide raid with Sea Raiders on, and the game froze when the ships landed.” * If the game crashed, the `mods.log` from that session. * If it’s your own mod, the file and line that the error names, or the whole mod folder. Copy report already holds the game version and your load order with each mod’s version. It also lists the mods that are off and why, the current problems and this session’s errors. You don’t need to type out your mod list. ## Where mods.log is The Problems tab has an Open log folder button and shows the full path. The game keeps the logs of the last 5 sessions. | System | Path | | ----------------------------- | --------------------------------------------------------------------------- | | Windows | `%APPDATA%\Godot\app_userdata\Raid Haven\logs\mods.log` | | macOS | `~/Library/Application Support/Godot/app_userdata/Raid Haven/logs/mods.log` | | Linux and Steam Deck (native) | `~/.local/share/godot/app_userdata/Raid Haven/logs/mods.log` | The log is in English whatever language the game is in, so anyone helping you can read it. Paths in it start with `~`, so a shared log doesn’t show your account name.