Modding:Tutorial - Custom Player Tiles

This is a step-by-step guide on how to use your own choice of tile for your character. It's intended to be followable by anyone who plays Caves of Qud, regardless of modding knowledge. We will be adding the tile by using a preset, which is selectable during character creation.

Besides a copy of the game itself, you will need:

• A tile. This is an image in a specific format that we'll go over in a moment.
• A build code. It will be the default when selecting your preset, but you can still choose a different build during character creation.
• A text editor. You don't need to know how to program, but you'll need to edit a text file. Notepad is fine, Microsoft Word isn't.

Tile Format

The gunslinger tile as seen in an image viewer.

The gunslinger tile as rendered in-game, using y as the foreground color, K as detail, and k as background.

Your tile should be a .png file with pixel dimensions 16×24. For colors, it should use:

• black (hex code #000000) – The game will replace this with the foreground color. This is generally the main color of your tile, the one there is the most of.
• white (hex code #ffffff) – This will be replaced with the detail color. This is used as an additional color to contrast with the foreground color.
• transparent (any color with an opacity/alpha of 0) – This will be the background color. This is almost always k (see below).

(It's possible to use other colors as well, but it's out of the scope of this guide. See here for more details.)

For reference, here are the colors the game can render your tile with:

Code	Name	Hex
r	dark red / crimson	#a64a2e	█
R	red / scarlet	#d74200	█
o	dark orange	#f15f22	█
O	orange	#e99f10	█
w	brown	#98875f	█
W	gold / yellow	#cfc041	█
g	dark green	#009403	█
G	green	#00c420	█
b	dark blue	#0048bd	█
B	blue / azure	#0096ff	█
c	dark cyan / teal	#40a4b9	█
C	cyan	#77bfcf	█
m	dark magenta / purple	#b154cf	█
M	magenta	#da5bd6	█
k		#0f3b3a	█
K	dark grey / black	#155352	█
y	grey	#b1c9c3	█
Y	white	#ffffff	█

Build Code

To get a build code for your character:

1. Launch the game and select “New Game”.
2. Go through character creation, selecting your genotype, calling/caste, attributes, and mutations/cybernetics. (Optionally, you can enter a name as well.)
3. While on the build summary step, select “Export Code to Clipboard”.
4. Paste the code somewhere you'll be able to find it later.

Making the Mod

Now you're going make a mod that puts everything together!

1. Locate your Mods folder, listed as “‘offline’ mods” on the file locations page.
2. Create a directory inside that folder that will contain your mod data. Name it something distinctive, such as [Your Name]'s Custom Preset. This name will appear in the in-game mod manager.
3. Inside your new mod folder, make a folder called Textures and put your tile in it.
4. Also inside the mod folder, make a file called EmbarkModules.xml. (The .xml file extension is mandatory; it can't be .txt. If necessary, disable hiding of file extensions in your file manager.) Add this text to it:

<embarkmodules>
    <module Class="XRL.CharacterBuilds.Qud.QudPregenModule">
        <pregens>
            <pregen Name="TODO" Genotype="TODO" Tile="TODO" Foreground="TODO" Detail="TODO" Background="k">
                <code>TODO</code>
                <description>
TODO
                </description>
            </pregen>
        </pregens>
    </module>
</embarkmodules>

Now you need to go through and replace all the TODOs.

• Inside the quotes next to Name, write whatever you want the preset to be called on the character creation menu.
• Next to Genotype, write either Mutated Human or True Kin, or the appropriate modded genotype if you're using one.
• Next to Tile, write the file name of your tile. For instance, if you put a file called My Tile.png into the Textures folder, write My Tile.png.
• Next to Foreground, write the single-letter color code for the foreground color you want from the table in the #Tile Format section (the one that will replace black). Usually, you won't see this color unless you disable the “Color player's @ based on HP level.” option. However, even with that option on, you can see it when you vacate your body or get cloned.
• Next to Detail, likewise but for the detail color (the one that will replace white).
• In between <code> and </code>, paste the build code that you generated earlier.
• In between <description> and </description>, write whatever descriptive text you want to appear for the preset on the character creation menu.

Here is a working example that you can paste into your EmbarkModules.xml to try it out:

<embarkmodules>
    <module Class="XRL.CharacterBuilds.Qud.QudPregenModule">
        <pregens>
            <pregen Name="Monad Nomad" Genotype="Mutated Human" Tile="Creatures/sw_monad.bmp" Foreground="Y" Detail="m" Background="k">
                <code>H4sIAAAAAAAAA81WXWvbMBR9768QZo9uSLtsjEEeMm/sqy1pk3WF0QfZvthismSkq44s5L/vSkmNY7fLOkhJILZzztXRyf0QXh4xFhW8gjswVmgVvWXR6WA4OB2+HryMYs+mTsi8RZ8QPVxTlc6dBEvoD/rJ2DJcG2K+qMGvuLk6GyQlNzxDMO+8nB1cutx/P4LSSGHnYUHMJtZClcrFcTKjBXXMrtcbjxtTMUucRGdgrMCh4TJmU5dKkX2FxVz/BDVWTsrgL1jJOXIycW+NkBf4VF/vSaPnrdmCJO/Dveq5Q46Qs0+u4qod1MvhhlqF+yr+zxTOXHqIGdyytTOBm2iveaErnj9D3kKdSNceWuY6xnbmrqpJcNgCLEjIgkIzmevPsvXMNp26yWxSigoMb+mGkEQ7hcSfdPBrbgQPzLDD3K2ZCzpTvG7UYlfxv3n5pizyVALzY0Uyj3h69Zye5lqJjE2kBFMs9pul5vl2/0MwQTQidQgHNwVdZzvHYKqFQjt1Jiu5hXxrR3/CoAFVYEn4m3YxokkhpMBFD59rV5QKrO0xnxWClKIAlUGP/C6krPUvMD3mQ6EJGzVQq/UiXs9qCJ1yPBpt4VdQcaGEKjpDntKfnPjJ34rfU5skzqKuxG9o+ENrl8cc7mwbtR5B76GF1oB9kAqeh7p2g41WdALMHlqzr4KUWluYITdIrXGms3BQHVxR/uJy9ytBZ5nf64uua/6EdwO63h6t/gCn9Rzp5QoAAA==</code>
                <description>
I'm a monad :)
                </description>
            </pregen>
        </pregens>
    </module>
</embarkmodules>

Now, assuming everything has gone to plan, you should be able to boot the game and enjoy your new preset with its custom tile! After selecting New Game and choosing a game mode, select Presets then whichever genotype you categorized your preset under. You should see it in the list.

Using a Different Build

As mentioned earlier, you don't have to stick with the build you picked for your preset. To use a different one:

1. Select the preset as normal during character creation.
2. Go back to a previous step by using the back arrow or one of the step icons at the top. For example, if your preset's default build is a Nomad, then there will be an icon at the top that says “Nomad”. Click that to go to the beginning of creating your character. Don't reselect a preset or else it will reset any changes you've made.
3. Now you can go through character creation as normal.

Adding Even More Presets

You can add more than one preset in the same mod. To do so, add more pregen sections just like the first one. Here's an example:

<embarkmodules>
    <module Class="XRL.CharacterBuilds.Qud.QudPregenModule">
        <pregens>
            <pregen Name="Monad Nomad" Genotype="Mutated Human" Tile="Creatures/sw_monad.bmp" Foreground="Y" Detail="m" Background="k">
                <code>H4sIAAAAAAAAA81WXWvbMBR9768QZo9uSLtsjEEeMm/sqy1pk3WF0QfZvthismSkq44s5L/vSkmNY7fLOkhJILZzztXRyf0QXh4xFhW8gjswVmgVvWXR6WA4OB2+HryMYs+mTsi8RZ8QPVxTlc6dBEvoD/rJ2DJcG2K+qMGvuLk6GyQlNzxDMO+8nB1cutx/P4LSSGHnYUHMJtZClcrFcTKjBXXMrtcbjxtTMUucRGdgrMCh4TJmU5dKkX2FxVz/BDVWTsrgL1jJOXIycW+NkBf4VF/vSaPnrdmCJO/Dveq5Q46Qs0+u4qod1MvhhlqF+yr+zxTOXHqIGdyytTOBm2iveaErnj9D3kKdSNceWuY6xnbmrqpJcNgCLEjIgkIzmevPsvXMNp26yWxSigoMb+mGkEQ7hcSfdPBrbgQPzLDD3K2ZCzpTvG7UYlfxv3n5pizyVALzY0Uyj3h69Zye5lqJjE2kBFMs9pul5vl2/0MwQTQidQgHNwVdZzvHYKqFQjt1Jiu5hXxrR3/CoAFVYEn4m3YxokkhpMBFD59rV5QKrO0xnxWClKIAlUGP/C6krPUvMD3mQ6EJGzVQq/UiXs9qCJ1yPBpt4VdQcaGEKjpDntKfnPjJ34rfU5skzqKuxG9o+ENrl8cc7mwbtR5B76GF1oB9kAqeh7p2g41WdALMHlqzr4KUWluYITdIrXGms3BQHVxR/uJy9ytBZ5nf64uua/6EdwO63h6t/gCn9Rzp5QoAAA==</code>
                <description>
I'm a monad :)
                </description>
            </pregen>
            <pregen Name="Copy of Monad Nomad" Genotype="Mutated Human" Tile="Creatures/sw_monad.bmp" Foreground="M" Detail="m" Background="k">
                <code>H4sIAAAAAAAAA81WXWvbMBR9768QZo9uSLtsjEEeMm/sqy1pk3WF0QfZvthismSkq44s5L/vSkmNY7fLOkhJILZzztXRyf0QXh4xFhW8gjswVmgVvWXR6WA4OB2+HryMYs+mTsi8RZ8QPVxTlc6dBEvoD/rJ2DJcG2K+qMGvuLk6GyQlNzxDMO+8nB1cutx/P4LSSGHnYUHMJtZClcrFcTKjBXXMrtcbjxtTMUucRGdgrMCh4TJmU5dKkX2FxVz/BDVWTsrgL1jJOXIycW+NkBf4VF/vSaPnrdmCJO/Dveq5Q46Qs0+u4qod1MvhhlqF+yr+zxTOXHqIGdyytTOBm2iveaErnj9D3kKdSNceWuY6xnbmrqpJcNgCLEjIgkIzmevPsvXMNp26yWxSigoMb+mGkEQ7hcSfdPBrbgQPzLDD3K2ZCzpTvG7UYlfxv3n5pizyVALzY0Uyj3h69Zye5lqJjE2kBFMs9pul5vl2/0MwQTQidQgHNwVdZzvHYKqFQjt1Jiu5hXxrR3/CoAFVYEn4m3YxokkhpMBFD59rV5QKrO0xnxWClKIAlUGP/C6krPUvMD3mQ6EJGzVQq/UiXs9qCJ1yPBpt4VdQcaGEKjpDntKfnPjJ34rfU5skzqKuxG9o+ENrl8cc7mwbtR5B76GF1oB9kAqeh7p2g41WdALMHlqzr4KUWluYITdIrXGms3BQHVxR/uJy9ytBZ5nf64uua/6EdwO63h6t/gCn9Rzp5QoAAA==</code>
                <description>
I'm also a monad :)
                </description>
            </pregen>
        </pregens>
    </module>
</embarkmodules>

Other methods for customizing player tiles

The Choose Your Fighter mod provides a different means of customizing player tiles through its expansion support; see the mod's GitHub page for more information. You may find this helpful if you want to add custom tiles to the game that aren't tied to specific build codes.