Modding:Mod Configuration

This page is about modding. See the modding overview for an abstract on modding.

This page is about modding. See the modding overview for an abstract on modding.

There are a number of configuration files that can be associated with a mod. They are all placed in the root folder of the mod and are all optional.

By convention, all JSON keys will be referred to using the casing used in the game's code. However, the configuration file keys are case-insensitive.

manifest.json

Mod Manager mock

The manifest.json file is primarily used for display in the game's Mod Manager, but can also control how the mod is loaded.

Structure

Field	Description	Properties
ID	Primary identifier of the mod, this is used as the mod's key in the mod manager and to resolve it as a dependency of another mod. Try to restrict the ID to alphanumeric characters, as it is also used as a symbol for preprocessor directives when compiling.	Falls back to config.json's ID field.
LoadOrder	Whole number indicating the mod's load priority in ascending order: smaller values load before larger ones. E.g. a mod with a loadorder of -1 loads before one with 1. Obsolete in favor of Dependencies with build 210.	Falls back to config.json's's LoadOrder field.
Title	Title of the mod, displayed in the mod manager.	Accepts color shaders. Falls back to workshop.json's Title field.
Description	Short description of the mod, displayed in the mod manager.	Accepts color shaders.
Tags	Comma-delimited list of tags, only for display in the mod manager and has no effect on tags used in the workshop.	Falls back to workshop.json's Tags field.
Version	Mod's version, displayed in the mod manager.
Author	Creator(s) of the mod.	Accepts color shaders.
PreviewImage	Relative path to an image used as an icon for the mod in the manager, recommended size 512x512. The largest Caves of Qud displays on default scale is 128x128, but if also used as the steam workshop preview image, that can display at up to 435x435 on the "Most Popular Items" front page.	Falls back to workshop.json's ImagePath field.
Dependencies	ID-Version pair collection of mods that are required to load before this one. New in build 210.	Accepts version ranges.
Dependency	Shorthand to declare a single mod dependency of any version, mutually exclusive with Dependencies field. New in build 210.
LoadBefore	A single or array of mod IDs that this mod should attempt to load earlier than. New in build 210.
LoadAfter	A single or array of mod IDs that this mod should attempt to load later than. New in build 210.
Directories	Array of directory objects that can be loaded conditionally depending on game version or other mods in the load order. Refer to directory structure for directory properties. New in build 210.	Falls back to loading the root directory if undefined.

Directory Structure

Each entry in the Directories array will be evaluated and loaded if optional conditions such as version and dependency match.
If no conditions are specified the directory and its paths will always be loaded.
Directories can be used to include separate content/scripts for different game versions, or optional addons to other mods.
If none are explicitly defined the mod's root directory will be loaded.

Field	Description	Properties
Paths	Array of paths to load, relative to the mod's root directory. Any leading or trailing separators are optional. Each path is deduplicated and only loaded once, even if a parent or sub directory is defined at any point. Be mindful of the fact that paths are case-sensitive on some operating systems.	Prohibited from escaping the mod directory. Recursive.
Path	Shorthand to declare a single path, mutually exclusive with Paths field.
Version	A version range that is required to match the game's XRLGame.MarketingVersion. This is the bright number in the bottom right of the main menu.	Accepts version ranges. Defaults to *.
Build	A version range that is required to match the game's XRLGame.CoreVersion. This is the dark number prefixed with 'build' in the bottom right of the main menu.	Accepts version ranges. Defaults to *.
Dependencies	ID-Version pair collection of mods that are required for this directory to be loaded. These are treated as optional dependencies and do influence the load order, but won't prevent the mod from loading overall.	Accepts version ranges.
Dependency	Shorthand to declare a single mod dependency of any version, mutually exclusive with Dependencies field.
Options	A single or array of options Requires strings that must be true. Note that the XML file containing the referenced options is required to have Option somewhere in its file name. This is a quirk caused by populating the option defaults prior to directory initialization.

Version Ranges

To match a game or mod's version you'll define a range of acceptable values using a simple and familiar syntax.
Any number left undefined will behave as if substituted with *.

• *: Matches any version number and will thus always proceed.
• 1.0.*: Matches a version greater or equal to 1.0.0, but less than 1.1.0.
• 2.0.208 - 3.0.0: Matches a version greater or equal to 2.0.208, and less or equal to 3.0.0 (i.e. an inclusive closed interval).
• 2.0.209.52 - *: Matches a version greater or equal to 2.0.209.52.
• >3.5: Matches a version greater or equal to 3.6.0.
• >=2 <5: Matches a version greater or equal to 2.0.0, but less than 5.0.0.
• ^0.5.2 || 7.2.1: Matches a version greater or equal to 0.5.2, but less than 0.6.0. Or a version equal to 7.2.1.

Example manifest.json

An example manifest.json, taken from the snapjaw mages tutorial and modified to demonstrate more of the file's options.

{
    "ID": "Pyovya_SnapjawMage",
    "LoadOrder": 1,
    "Title": "{{R|Snapjaw}} {{C|Mages}}!",
    "Description": "Adds the new {{Y|snapjaw}} {{R|fire}} {{Y|mage}} and {{Y|snapjaw}} {{C|ice}} {{Y|mage}} creatures to Caves of Qud.",
    "Version": "0.1.0",
    "Author": "{{M|Pyovya}}",
    "Tags": "Creature",
    "PreviewImage": "preview.png",
    "LoadBefore": "SightlessFray",
    "LoadAfter": [ "Tamago_PlatypusCommune", "ChromeGarlands" ],
    "Dependencies": {
        "Pyovya_SaltOrphan": "1.0.0 - *"
    },
    "Directories": [
        {
            "Paths": [ "/Common/", "/Assets/Textures/" ]
        },
        {
            "Path": "/Old/",
            "Build": "<2.0.209.43"
        },
        {
            "Paths": [ "/NewCS/", "/NewXML/" ],
            "Build": ">=2.0.209.43"
        },
        {
            "Path": "/GooeyAddon/",
            "Version": ">=1.0.0",
            "Options": [ "OptionSnapjawMage_AddGooeyIck == Yes", "OptionSound != No" ],
            "Dependencies": {
                "Momo_CyberneticGenders": "^2.*",
                "IckySounds": ">=999.7.1.X"
            }
        },
        {
            "Path": "/SaltAddon/",
            "Option": "OptionSnapjawMage_AddRiotSalt == Yes",
            "Dependency": "Yarif_RiotCooking"
        }
    ]
}

workshop.json

The workshop.json file configures a mod's upload to the Caves of Qud Steam Workshop. It is usually manipulated through the game's Workshop Uploader.

Structure

Field	Description	Properties
WorkshopId	The mod's unique ID on the workshop.
Title	Title of the mod, displayed on the workshop.
Description	Description of the mod, displayed on the workshop.	Accepts formatting tags.
Tags	Comma-delimited list of tags, displayed on the workshop.	Pre-defined tags can be filtered on.
Visibility	Stringed integer, detailing the mod's visibility on the workshop. "0": The mod is private (visible only to the mod's creator). "1": The mod is visible to friends only. "2": The mod is public.
ImagePath	Relative path to an image used as an icon for the mod in the workshop, recommended size 512x512.

Example workshop.json

An example workshop.json for the snapjaw mages tutorial mod.

{
  "WorkshopId": 708258860,
  "Title": "Snapjaw Mages",
  "Description": "[h1]Snapjaw Mages[/h1]\n\nThis mod adds the new [b]Snapjaw Mage[/b] creature to Caves of Qud.",
  "Tags": "Creatures",
  "Visibility": "2",
  "ImagePath": "Preview.png"
}

modconfig.json

The modconfig.json file configures a mod's properties for all textures located within the mod's folder.

Structure

Field	Description	Properties
ShaderMode	An integer representing the mod's textures' shader mode. 0: The default texture shader. 1: The true color texture shader. Note: This currently only works for textures rendered in the world. Most UI elements do not support this mode.
TextureWidth	The width of the mod's textures, in pixels.
TextureHeight	The height of the mod's textures, in pixels.

Example modconfig.json

An example modconfig.json.

{
  "shaderMode": 0,
  "textureWidth": 16,
  "textureHeight": 24
}

config.json

The config.json file was obsoleted in version 2.0.201.44 and was subsumed by the manifest.json file.