Modding:Overview

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

Much like playing it, the act of modding Caves of Qud is one of chiseling through a layer cake of history. Artifacts of great power have been left to us by the Eaters – or the developers in this case – and it's up to us to identify them and turn them to our own ends.

The purpose of this, the modding section of the Official Caves of Qud Wiki, is to provide a place where we may together demystify these gifts for the benefit of anyone looking to devise something new from them.

Do you know, or want to know, something that isn't mentioned on here? Edit away! Once you have an account, feel free to contribute your knowledge to the appropriate pages, or use the talk pages to ask questions. (Remember to sign your messages with ~~~~!)

Prerequisites

• First, make sure your file browser is configured to display file extensions; this is important especially when writing your own files because the file extension determines what the game does with the file.

• Before you even begin to write your mod, it's helpful to have a sense of how things work. You can learn a lot by browsing the game's files. Take a look around the location labeled "Game data files" before you start – there are lots of interesting things (including spoilers!) to find. In particular, ObjectBlueprints/Creatures.xml and ObjectBlueprints/Items.xml are likely to be a good place to start.
  • Also take note of the "Build log" and "Player log" locations, which you will need to look at when debugging.

• For the actual writing, at a minimum, you'll need a text editor. Notepad works, but we recommend Visual Studio Code (multi-platform), Sublime Text (multi-platform), Notepad++ (Windows only), or any other code editor with tabs and syntax highlighting for XML and C#. (Wordpad and Microsoft Word are not plain text editors and thus unsuitable.)

• If you plan to make your own tiles (sprites), a pixel editor such as Piskel (all major platforms + web) or Aseprite (all major platforms; both paid and free versions available) is useful. GIMP is essentially usable, but you may need to adjust settings to prevent automatic anti-aliasing, which is usually undesirable with low-resolution pixel art.

• It's also helpful to have someone you can ask for help. Beyond the wiki talk pages, there are also the Caves of Qud Discord's #modding channel and Kitfox Games's #caves-of-qud channel. Don't be afraid to ask questions!

File Structure

While working on your mod, it will exist as a folder in the "offline" mods location (see File locations). If you later upload it to the Steam Workshop and subscribe to it, make sure to move the working copy elsewhere to avoid conflicts.

These go directly inside the mod folder:

• Any .xml files – The file may be called anything as long as it ends in .xml. What kind of data it represents is determined by what the outermost tag is, e.g., <objects>…</objects>.
• Textures/* – This is where all images to be used as tiles go. Don't include the Textures/ when writing their file names.
• manifest.json and workshop.json – See Modding:Mod Configuration for more information.

This list is incomplete. See a tutorial or a topic-relevant article for more in-depth coverage.

Tutorials

If you're just getting started with modding, check out Modding:Tutorial - Snapjaw Mages. It walks through from the very basics, all the way to making a new creature and some items that appear in game. It also goes over the game's data files, which you can then use to go on and mod in your own objects.

Also check out the Blue Ctesiphus tutorial. It shows an older version of the game, but still gives relevant advice.

Debugging

If something isn't working right, the logs (see File locations) are a good first place to look for more information. There are, roughly speaking, two places where your mod can cause errors:

• At load time, when the game loads all the content from all enabled mods. You can find load errors and warnings in the build log. The mod manager, available from the main menu, will also note errors on each mod by clicking on it.

• At run time, pretty much any time after load time. You can find these in the player log. To see them immediately as they happen, enable "Show error popups" under the debug options. Note that there are some situations where this option can softlock your game.

Playing Nice

There are certain principles to be aware of if you want to avoid your mod conflicting with other mods or with future changes to the base game.

Prefix internal names. Pick a prefix that's likely to be unique to you, and add it to the front of any names that need to be unique, such as object blueprint IDs and part class names. E.g., if your name is Alice and you add a creature called a dog pig, you could use Alice_Dog Pig as its internal ID.

Specify only what you change. If you find yourself copying an entire block of XML from the base game, you probably don't need to be doing that! Most kinds of data file support merging either implicitly or by writing Load="Merge" in the opening tag, and then you only need to write the parts that differ from the base data. See Modding:Objects for more on how this applies to objects in particular.

What can a mod do?

The general answer is "just about anything". The difficulty of a task will depend in part on whether it's specifically supported by the game.

Mods can be divided into three "levels" that are, roughly speaking, progressively more powerful and more difficult to maintain.

Data mods use XML files to define new data that fall into specific kinds, such as objects, bodies, and conversations. The base game itself uses this same mechanism!

Script mods use C# code to add new logic. Turning off the "Allow scripting mods" option disables these.

Among script mods, Harmony mods are the most powerful and the most fickle. Harmony can insert code at arbitrary places unrestricted by any interfaces the game provides. This has the possibility of playing havoc with other mods and with future changes to the base game, so only use Harmony as a last resort!

I want to add…	Could it be a data mod?	Recommended Page	Notes
conversation	yes	Modding:Conversations	There's very robust XML support, but if needed you can also define new behaviors in C#.
creature/NPC	yes	Modding:Objects	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	Modding:Genotypes_and_Subtypes	Most properties of interest can be defined with XML, but unique behaviors will generally require C#.
item	yes	Modding:Objects	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	Modding:Liquids	There's no XML interface at all.
location/world	yes	Modding:Intro_-_Zones_and_Worlds	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	Modding:Mutations	There's an XML interface, but it covers only some properties.
preset character	yes	Modding:Tutorial_-_Custom_Player_Tiles	Most properties of interest can be defined with XML.
recipe	no		There's no XML interface at all, but one may be added in the future.
quest	yes	Modding:Quests	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	Modding:Wishes	There's no XML interface at all.

Example Mods

The code for many mods is available online under permissive licenses that allow others to reuse their code. This can be a good resource for getting started with creating your own mods.

Repository	Steam Workshop	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

My mod was marked incompatible

If you received a notice that your Steam Workshop mod was marked incompatible with the game:

1. Fix any errors it causes. (See #Debugging.)
2. Upload a new version to the Steam Workshop.
3. Request that your mod be unmarked as incompatible through either the support email or the Caves of Qud Discord's #modding channel.