Hello!

In this step-by-step guide, we will go through the process of modding Caves of Qud. Modding Caves of Qud is relatively simple, and requires no previous experience modding or programming.

We will be going over several key concepts necessary to mod Caves of Qud:

• Enabling modding for Caves of Qud
  
• Creating a Mods folder in the right directory
  
• Modifying the game
  
• A "brief" overview of what this mod actually does

It's important to note that you do not need to read the entirety of this guide to understand how to mod Caves of Qud, or how to build your first mod. This is just a through step-by-step process for understanding most every aspect of modding Caves of Qud for the first time.

Modding Caves of Qud isn't difficult, but there's a lot you can do with it. As such, this guide goes over most of what you'll encounter your first time around and makes great effort to explain everything in clear and conscise, but explicit, detail.

So without any more preamble, let's get started!

Okay, before we begin, let's first make sure that your game has mods enabled.

To do that, let's start up Caves of Qud.



Now that the program is open, head on over to the Options tab in the Main Menu.



Once in the Options menu, scroll down and find the Modding tab and Enable Mods (you may also allow scripting mods, but for todays purposes this will not be required.)


Once you've enabled mods for Caves of Qud, go ahead and quit out of the game. Now we can actually begin modding our game!

For today's lesson, we're going to turn Ctesiphus, the ray cat found in Joppa, from a vibrant magenta to a cooler light blue.

Step 1: Setting up your Folders

The first thing we must do before we can change the hue on our glowing friend, is we must create a Mods folder in the right folder.

You must find and open your Freeholds Games folder, most likely found in your C: drive. For example, here is the address for my Freehold Games folder:

C:\Users\Your_Name\AppData\LocalLow\Freehold Games\CavesOfQud

Once there, you're going to create a new folder called "Mods"



Now go into your Mods folder and make a new folder. This is where we are going to build our first mod and change that kitty's color!

Feel free to name this folder whatever you like, but try and be descriptive. Something like "Ctesiphus_Recolor", "MyFirstMod", or "BlueCat". Naming the mod something vague or generic like "mod" or "asdf" will most likely confuse you later.

For the purposes of this guide, I will refer to this folder as "Ctesiphus_Recolor"



Now that we've created the folder to contain our mod, we can begin the process of acutally modifying Caves of Qud.

Step 2: Modifying your game files

Open up the "Ctesiphus_Recolor" folder you just created and create a new Text Document.



Now open up the Text Document you created with Notepad.

Very Important Note:

If you cannot use Notepad, then you may use any text editing software you prefer so long as that software lets you save this document as a .xml file. This is the step that will most likely cause you some problems if your text editor does not let you save the document correctly.

You should now be looking at an empty document.



Click on Notepad, and copy paste the following code into it:


This is what your document should now look like



Now we need to save this document. Make sure you follow the next few steps very closely.

Go to File and hit Save As.



In the File name text field enter "ObjectBlueprints.xml" exactly (without the quotation marks).



Then go to the drop down menu right below called Save as type and select All Files



Double check to make sure that your Save As screen should look the same as the following image, and then go ahead and click Save.



Congratulations! You just turned Ctesiphus blue. Go ahead and open up Caves of Qud and take a look! (You may need to start a new game for the color to take effect.)

Well lookit that! A blue ray cat. And you did it all by yourself, kinda.

Just in case you wanted to change Ctesiphus's color to something else, here's a handy table that you can pick a new color from:


And all you have to do to change the color is to go back to the ObjectBlueprints.xml file in your Mods folder and change this one character



Changing this to G should make Ctesiphus Bright Green



Feel free to mess around with the colors as much as you want. It's your mod, after all, you can do anything you feel like.

Make sure you keep a backup of your mod, just in case anything goes wrong.

Yeah, so, I didn't really explain any of the steps we just made in order to dye Ctesiphus's hair a different color.

Let's go over what each line means, then, shall we?

Note: this segment is more educational and useful if you plan on continuing your modding adventures. If you just wanted a blue or yellow or grey Ctesiphus, then feel free to stop reading here, though I do encourage you to continue as this is all really interesting stuff.

I honestly don't know exactly what this line does. It indicates that this is version 1.0 of XML and is encoded using utf-8. I don't know what any of this means necessarily, but it seems consistent throughout all of the .xml files in Caves of Qud.

Leave this as is and don't touch it unless you know what you're doing. Make sure to include it in all of your modifications (though you may not even need to, I'm honestly not sure.)




Okay, I kind of know what this line does. XML is a language that doesn't actually do anything. Well, that's unfair. XML does a lot, but isn't really capable of handling anything on its own.

XML is a language not dissimilar to JSON (for those of you who know what JSON is). In essence, XML is simply a language that stores data. XML does not know what to do with this data, it's simply a way for a modder (such as yourself) to store data for it to be used later.

Caves of Qud knows what to do with this data.

So unless you're going to mess around with scripting (which is not in the scope of this guide), then we really don't have to worry about how this data gets interpreted, just that we make sure we send it the right information.

So this <objects> segment simply informs Caves of Qud that there's going to be any number of <object>s inside this .xml file. The </objects> declares that this is the end of the <objects> segment.




Oh hey look, an <object> in the <objects> segment. What are the chances of that?

So, this <object> has two major attributes; Name and Load.

Let's take a look at Load first.

Load is super important in modding Caves of Qud. If you look under steamapps/common/Caves of Qud/CoQ_Data/StreamingAssets/Base (which we'll come back to later, don't worry) then you'll find in there a .xml file called ObjectBlueprints.

Weird. That's the same name as the file we just made. What's up with that?

Load="Merge" is what's up with that. Ctesiphus has a bunch of data in this XML file, like the fact Ctesiphus is a Ray Cat, what kind of tile Ctesiphus is using, if Ctesiphus wanders, what happens if you talk to Ctesiphus, etc. Because we don't want to remove all of that useful stuff, we use the command Load="Merge" to merge our ObjectBlueprints.xml file with the original, and only overwrite the parts of the Ctesiphus object that we've decided to overwrite; namely Ctesiphus's color.

So what's up with that Name segment, then? What's the point of that?

Name is, also, super important in modding Caves of Qud. Let's say, for instance, you made a typo; Name="Stesiphus". What would happen then? Well, because XML doesn't actually do anything, it just carries data, this <object> would be sent off and merged with the orignal ObjectBlueprints.xml and then try and find an <object> with the name "Stesiphus", which it would fail to find.

Now, I don't know for certain, but I don't believe it would write a new object called Stesiphus with these parameters passed, but I do know that this error would have no real impact on your game. The ray cat of Joppa would remain its vibrant magenta self.

Names are important, as they are what the game uses when creating a new character or wall or item or whatever. If you name an object incorrectly, then what you thought you were editing might be something different, or nothing at all.

So, make sure you name your objects correctly, and that you're merging the files, unless you want to overwrite them entirely.

And lastly...




Objects have parts. Parts have names. The name of a part can have an attribute. This part's name is called "Render" and it has an attribute "ColorString" that's set to "&amp;B".

Like we learned from the pervious line, Name is very important, except rather than referring to an <object> like Ctesiphus, we're referring to a <part> of Ctesiphus called "Render"

"Render", I assume, is the <part> of Ctesiphus that dictates who our favorite Ray Cat is being, well, rendered. Specifically, in this case we care about what color Ctesiphus is being rendered as. The ColorString attribute is assigned the value "&amp;B" which colorizes Ctesiphus as a bright blue kitty.

I have no clue why it's called "&amp;B" and not just "B". Sometimes program languages just like to be difficult for no reason. It comes with the territory.

Wow. That was a lot more than I expected to write.

Well, there we are. Your cat is now blue (or whatever color you decided on) and maybe you learned a thing or two about modding Caves of Qud and how XML works.

I hope you enjoyed this guide and found it useful. I know I had some trouble figuring things out the first time I tried modding this game, so I felt it would be useful to write up this guide.

Before I wrap all of this up, I'm going to leave you with some handy dandy resources on furthering your modding abilities:


Yeah, so, Notepad sucks. I'm sorry to have forced you through that, but I didn't want to complicate things by making you go download some third-party software just to make minor changes to a document.

However, if you plan on continuing to make changes to Caves of Qud, I cannot recommend enough that you go out and find a good XML text editor. Seriously, these things will help you out tremendously.

Visual Studio Code[code.visualstudio.com] is not only free, it's also a solid piece of software that comes recommended by the developers. This makes it the best choice if you plan on modifying any XML files for Caves of Qud.


If you plan on making bigger and better changes to your game, but you're not sure how to do that, then look no further than Freehold Games's own Technical Guidebook[freehold.atlassian.net]. This thing has just about everything you'd ever want and then some. Since you now know a bit more about modding, you should find this resource quite handy.

If you want to change Caves of Qud in any way, from changing tiles, to adding quests, to modifying sound effects or music, then the Technical Guidebook is for you.

Though it is less explanitory than this guide may be, it's still an excellent resource. You might make a few mistakes along the way, but that's okay. Mess up, get things wrong, and then keep trying. Eventually you'll get things to work the way you want, and you'll be better for it.


I referenced this earlier in the guide, and I'm briging it up here again where it'll be more useful.

In this guide we only changed the color of Ctesiphus by modifying the ObjectBlueprints.xml file, but there are plenty more to be changed to how you see fit.

All of the modifyable XML files for Caves of Qud can be found at

steamapps\common\Caves of Qud\CoQ_Data\StreamingAssets\Base

All of these files should be available for you to modify as you please. Just make sure you make your changes in the Mods folder and not directly to any of these files themselves.



Here's a twenty-seven minute long video Brian Bucklew made about three years ago on the topic of the "Data-Driven Engines of Qud and Sproggiwood." Somewhat of a mouthfull, but it's a good talk about how Qud's design works.

If you were ever curious as to why you were modifying .xml files before, this is a good video to watch as it does an excellent job as to explaining why some of the choices were made in Qud's design.


I've only recently gotten into modding Caves of Qud. It was literally just yesterday (the day before I wrote this whole guide) that I finally figured out how to start.

First, I made Ctesiphus blue. Then I turned Ctesiphus orange, renamed them to "Garfield", and then changed Garfield's description.

And then I gave him a gun.



If you have any questions or comments, or if you spot any glaring typos, then feel free to leave a message here and I'll try my best to respond.

Especially the typos. Steam Guides doesn't tell you if you mistyped something so I'm out here without any spell checking.

Happy modding everybody. I hope you have a wonderful day!