Overview
first of a series of modding tutorials on creating stuff for Qud!
setup
official modding guidebook:
Caves of Qud – Technical Guidebook[freehold.atlassian.net]
and a step-by-step guide to get a mod running:
getting started guide by 0xDB
qud uses XML for databases, which I edit in notepad++, and C# for the code, which I edit using atom.
lastly, for any serious modding you’ll need dotPeek (or some other decompiler) to read Quds source code. Once you’ve got it, open up this file:
this tutorial begins with the assumption you’ve followed the step-by-step guide above, and have a basic mod set up to start editing.
quick object overview
Qud is made up of many, many objects. If you navigate to
you’ll find a file called ObjectBlueprints.xml. It contains 22k (and counting) lines of code detailing all the objects in the game, starting with the most basic of all:
if you imagine the objects as a tree, that generic Object object is the trunk. A little further along, we’ve got:
which would be the first few branches. Since they are inheriting from “Object”, they have all the same properties it does, plus any extra ones you add.
to see this in action, take a peek at an item from the game:
<object Name=”Knollworm Skull” Inherits=”BaseHelmet”>
it inherits the properties of BaseHelmet.. which inherits from Armor, from Item, from InorganicObject, from PhysicalObject, from – finally – Object.
this means the Knollworm Skull has the properties of every object up it’s family tree. This inheritance scheme is very useful, because you can (for example) specify BaseHelmet uses the head slot — and then any object that inherits from it will already be set to use that slot as well. Neat!
(or you could add <part Name=”LightSource” Lit=”true” Radius=”6″ /> to the generic Armor object. Nearly every piece of armor in the game inherits from it, so they’d all have a 6 tile light radius!)
making an object of our own
in your mods own ObjectBlueprint.xml, lets start creating an item, examining the pieces as we go.
here’s what we’ll start with:
(it’s good form to prefix things in your mod with a unique id (ie COOLMOD_SpikeyBoots) — helps with debugging & avoids naming conflicts)
our new cloak inherits all the properties from BaseCloak, adding two parts: Render and Description. (note: BaseCloak already has Render, but specifying it again lets us modify its variables)
but what are parts? basically, they’re little chunks of code you can tack on to objects. To examine them, open up dotpeek (or decompiler of choice), and search for the part’s name:
there might be a bunch of stuff that pops up with the same name, but the parts we’re using here will appear under XRL.World.Parts
the Render part handles the drawing of objects in the game world. View it in dotpeek, and you’ll see all the variables it has: whether the object has a tile, what color the tile is, what layer to draw it on, if it blocks line of sight, whether to render it in the dark, etc.
any of these public variables can be modified in our xml, for instance:
<part Name=”Render” DisplayName=”glowcloak” /> would just change the name
<part Name=”Render” DisplayName=”glowcloak” Occluding=”True” /> would both change the name, and set the Occluding boolean to true, making our cloak block line of sight (maybe it’s a really big cloak??)
the ColorString and DetailColor variables control the main and secondary color of the sprite. & is the xml way of writing an ampersand (&), and an ampersand followed by a letter is a color code. y is a light grey and and c light blue (note: DetailColor doesn’t need the ampersand).
what else can we do to our item? Well, anything, really. Since it’s supposedly a glowing cloak, lets add a part which gives it a weak light radius, and we’ll throw in a Commerce part to make it valuable:
oh, and the DisplayName string in Render changed a bit as well. &Y is the colorstring to make the following text display bright white!
strings with lots of colors can get confusing to type, so try out this color generator I coaxed my buddy into making:
qud text colorgen[qud-colorgen.herokuapp.com]
we could continue adding parts to our item, but first lets spawn it in-game to make sure it’s working.
the wish menu
to spawn our item for testing, we’ll need to access the wish menu, one of the testing/debugging tools.
in-game, press ESC > Key Mapping and scroll to the very bottom of the list. One of the commands under Debug is Wish. Bind it to something convenient, and try it out. A text prompt will open, where you can type various commands, listed here:
[link]
to spawn something, type it’s object name from ObjectBlueprints.xml:
(you don’t have to be exact, by the way. Just typing ‘glowcloak’ was enough for the parser to figure it out)
if nothing went wrong, our item should have spawned! wow!
since we inherited from BaseCloak, and didn’t overwrite it’s Tile variable in the Render part, we use the tile it supplies. The colors are rather boring though, let’s change them:
<part Name=”Render” DisplayName=”&Yglowcloak” ColorString=”&O” DetailColor=”M” />
handily, we can make edits to the xml without restarting the game: save ObjectBlueprints.xml with our changes, open the wish menu again, and enter the word reload. If it works, you’ll see ‘Configuration Hotloaded…’ in the text log.
the cloak we already spawned wont change, but if we spawn a new one:
garish!
onward
the same steps we took to create our item can be used to create anything else in the game. A creature, for example:
in addition to parts, our critter has xml modifying its stats, adding a mutation, and starting it with another object in its inventory.
the best way to learn is just poking around the objects that already exist, and seeing what you can make!
—
paste of the mods ObjectBlueprints.xml file:
[link]