Modding:Overview

For information on installing mods, see Modding:Installing a mod.

For information on installing mods, see Modding: Installing a mod.

Caves of Qud presents a broadly extensible engine. The game's core definition files reside in %game directory%\CoQ_Data\StreamingAssets\Base.

You can create mods for the game by creating a Mods folder in the same parent directory where your Saves are located, and then creating a sub-folder inside of the Mods folder for your new mod. New content can be created and existing content can be modified or replaced via data files and textures placed in this directory.

For the exact mod folder locations for your operating system, see file locations.

A (partial) checklist for getting ready to mod

• If your file manager (such as Windows Explorer) hides file extensions, tell it to show them instead. Being able to verify you're using the correct file extensions is vital when programming.
• Install a programming text editor, such as Visual Studio Code (all major platforms), Sublime Text (all major platforms), or Notepad++ (Windows only).
  • Visual Studio Code in particular, paired with Microsoft's C# extension for it, is very useful if you plan to write any script mods.
  • Word processors (such as LibreOffice Writer and Microsoft Word) are unsuitable for modding the game, because they deal primarily with formatted text, as opposed to plain text.
  • If you cannot install a programming text editor for whatever reason, Notepad is essentially useable, even though it's missing certain features usually considered desireable for programming, such as syntax highlighting and line numbering.
• If you plan to mod in your own tiles, familiarize yourself with a pixel editor, such as Piskel (all major platforms and web).
  • GIMP is essentially useable, but it isn't designed specifically for pixel art and may take more work to make game tiles with it than with a dedicated pixel editor.

Tutorials

If you're just getting started with modding, check out Modding:Tutorial - Snapjaw Mages. This tutorial is an end-to-end walkthrough of creating a new creature and some items, and then having them appear in-game. It also provides an introduction on browsing the game's data files, which you can then use to go on and mod in your own objects.

The Blue Ctesiphus tutorial is also an excellent starting point for new modders.

Data Mods, Script Mods

There are three "levels" of mod, with increasing capabilities:

• data/XML – Uses XML files to define new data of specific kinds. The base game itself uses this same mechanism! You can see the data for yourself at the “game data files” path.
• script/C# – Uses C# code to add new logic using interfaces the game provides. Even at this level, a mod can already do things like check the time and run other programs!
• Harmony – Inserts code at arbitrary places, unrestricted by any interfaces the game provides.

I want to add…	Could it be a data mod?	Notes
conversation	yes	There's very robust XML support, but if needed you can also define new behaviors in C#.
creature/NPC	yes	A large variety of properties can be defined with XML, but unique behaviors will generally require C#.
faction	yes	Most properties of interest can be defined with XML.
genotype/subtype	yes	Most properties of interest can be defined with XML, but unique behaviors will generally require C#.
item	yes	A large variety of properties can be defined with XML, but unique behaviors will generally require C#.
item mod	no	There's an XML interface but it covers only some properties.
liquid	no	There's no XML interface at all.
location/world	yes	There's very robust XML support, but if needed you can also define new behaviors in C#.
music/SFX	yes	These can be added to location and item data, respectively.
mutation	no	There's an XML interface but it covers only some properties.
quest	yes	It's possible to drive a quest entirely with conversations, but more complex logic can be done with C#.
skill	no	There's an XML interface but it covers only some properties.
status effect	no	There's no XML interface at all.
wish	no	There's no XML interface at all.

Possible Issues

I'm stuck and don't know what to do. Feel free to ask for help or guidance in #modding on the official Caves of Qud discord server! There are several modders there who use the channel to talk through and ask for feedback on their mods.

How do I troubleshoot my mod? A good place to start is by reading the following files that are updated every time the game runs:

• build_log.txt: Includes compiler errors if your mod code has errors that will not compile. These errors can prevent your mod from being loaded at all.
• Player.log: Includes XML errors and other miscellaneous errors that can prevent your mod from working as intended, even if it does load. Search the file for MODERROR statements, and review carefully for other output lines that mention your mod.

Where can I find build_log.txt and Player.log? See file locations.

My mod has been marked incompatible on Steam Workshop. What do I do? Update your mod to work with the latest stable or beta release of the game, then request that your mod be unmarked incompatible via either the official Caves of Qud Discord server's #modding channel, or the support email address, support@freeholdgames.com.

I keep getting an error when trying to save my game. Most likely, you have a list in your mod. Qud's default method of saving doesn't handle lists, so you need to handle it yourself. To see how, check out this article on how to override Qud's default saving/loading.

Examples

The sources for many mods are available online under various free/libre licenses. These can be a good resource for getting started with creating your own mods.

The following is an (incomplete) list of sources for different mods:

Repository	Corresponding mod(s)	Concepts used
gnarf37/qud-rhinoconaut	Rhinoconaut	Custom Preset, Custom player tile
DeSevilla/my-qud-mods/monsters	Terrors of the Depths	Creatures, Modding:Tiles
Armithaig/hearthpyre	Hearthpyre	Modding:C Sharp Scripting, Modding:Sounds, Modding:Tiles
AsheIsAmazing/QudMods	Various mods
HeladoDeBrownie/Caves-Of-Qud-Minimods	Various mods
Ilysen/Jademouth	Jademouth	Modding:Maps, Modding:Quests, Modding:Worlds
Ilysen/Tealeaves	Tealeaves	Modding:Conversations, Modding:Maps
kernelmethod/QudMods	Various mods
kernelmethod/QudMods/Pets/LimbBall	Pet: Marmus Mulegus, Chimeric Limb-Ball	Modding:Pets
librarianmage/FinderOfRuin	FinderOfRuin	Modding:Harmony, Modding:Options