From Caves of Qud Wiki
Jump to navigation Jump to search
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.

Object Definitions

The game's object definitions live in the XML files in the %game directory%\CoQ_Data\StreamingAssets\Base\ObjectBlueprints directory.

These object definitions may be extended or replaced via an ObjectBlueprints.xml file placed in your mod's root directory, %appdata%\Caves of Qud\Mods\[your mod name]\ObjectBlueprints.xml.

If an object attribute Load="Merge" is supplied, the data will merge with any existing definition, otherwise the object definition will replace the named object entirely.

Example ObjectBlueprints.xml that merges a new color into Ctesiphus's blueprint:

    <object Name="Ctesiphus" Load="Merge">
        <part Name="Render" ColorString="&amp;B"></part>

Component System

Caves of Qud's codebase uses an entity component system architectural style, which makes it relatively easy for modders to create totally new objects with only a small XML snippet, simply by combining existing components from other game objects. Components are generally referred to as "parts" in Caves of Qud's XML files. For example, you might combine a LiquidVolume part with a MeleeWeapon part to create a weapon that holds liquid.

For a more thorough introduction to the component system used to define objects in Caves of Qud, check out this introductory presentation by CoQ developer Brian Bucklew from IRDC 2015:

Supported XML Tags and Functions

Each <object> in the ObjectBlueprints.xml file supports the following child XML tags:

XML Tag Description
<part> Indicates that this object should load the part with the specified name. A parts is any C# class that inherits IPart.
You don't need to know how to code to add a part though, there are a lot of useful parts already available in the base game that you can steal from other objects.
<mutation> If an existing mutation is redefined, the game merges the new attributes you define with existing attributes on the mutation, overwriting them if they already exist.
<skill> If an existing skill is redefined, the game merges the new attributes you define with existing attributes on the mutation, overwriting them if they already exist.
<inventoryobject> Adds an object to a creature's inventory. Number can be specified to say how many of the object the creature should have. In addition, a blueprint can be prefixed with @ to sample the inventory objects from a population table, e.g. Blueprint="@DynamicObjectsTable:EnergyCells:Tier{ownertier}".
<tag> The code includes a method to remove an existing tag, by redefining it with Value="*delete". However, this appears to currently be broken because it does not work in combination with Load="Merge" or on inherited tags.
<stag> Adds an object to a dynamic semantic table.
<mixin> Adds a "mixin" to an object. This can be used in place of (or in addition to) inheritance to automatically copy parts and tags to an object from another object. mixin supports the following attributes:
  • Name (string): blueprint used in mixin
  • Include (string): comma-delimited string of elements to include
  • Exclude (string): comma-delimited string of elements to exclude
  • Priority (int): mixin priority (lower comes earlier)
  • Fill (bool): whether to add the mixin before or after normal inheritance

The effects of most objects tags can be reverted using a remove* tag. For instance, <removepart Name="..." /> will remove a part from an object blueprint; <removemutation Name="..." /> can be used to remove a mutation from a creature[1].

Adding the object to encounters

Once you've created your item, check out this page for information on how to introduce it to dynamic encounters: Encounter and Population Modding


The game implements a wide variety of parts in XRL.World.Parts that can be applied to objects. These parts can be added to an object by adding a part tag to their definition in XML, supplying the name of the part and any other relevant attributes. For example:

<object Name="Snapjaw" Load="Merge">
  <part Name="Corpse" CorpseChance="90" CorpseBlueprint="Snapjaw Corpse" />

Parts can also be removed from an object through the use of the removepart XML tag, e.g. <removepart Name="Corpse" />.

Below is an (incomplete) list of some of the most common and important parts used by creatures and items in the game.

General parts

Name Attributes Description
Description Short Affects the description of an object when you look at it.
DeployWith Blueprint, PreferredDirection, SameCell, SolidOkay, SeepingOkay, Chance, CarryOverOwner Ensure that the object spawns alongside other objects. This is used, for example, by air wells to ensure that they spawn with catch basins.
Food Message, Satiation, Thirst, Healing Makes an object edible. This part also affects the message that pops up when you eat a given item, as well as its impact on your hitpoints (HP) and thirst.
Interesting Key, IfPartOperational, DisplayName, Preposition, Radius, EvenIfInvisible, TranslateToLocation, IconTile, IconRenderString, IconColorString, IconTileColor, IconDetailColor Whether or not an object is considered "interesting" in the current zone. Objects marked as interesting can be automatically moved to through the "move to point of interest" selector.
RandomColors DetailColor, TileColor Selects a random primary and detail color for an object's tile. The DetailColor and TileColor attributes should be comma-separated lists of colors.
RandomTile Tiles Changes the tile used by a creature to be a random tile from a comma-separated list given by the Tiles attribute.
Render DisplayName, RenderString, RenderLayer, RenderIfDark, DetailColor, ColorString Change the color and tile used to render an object, as well as the name of the object as it appears in-game.

Creature- and corpse-specific parts

Name Attributes Description
Body Anatomy The body type used by a creature.
Brain Hostile, Factions Used to specify a creature's default hostility state, as well as the factions that it belongs to.
Butcherable OnSuccessAmount, OnSuccess Can be applied to a creature's corpse to make it butcherable.
Consumer Chance, WeightThresholdPercentage, SuppressCorpseDrops, Message, FloatMessage Causes a creature to destroy objects and creatures in its path. This is used by salt krakens and star krakens (along with the SlowDangerousMovement and and AIWanderingJuggernaut parts).
ConversationScript ConversationID, Quest, PreQuestConversationID, InQuestConversationID, PostQuestConversationID, ClearLost, Filter Used to specify a creature's script for conversations, using an ID from Conversations.xml. Conversation scripts can be static, or can be dynamically selected conditional on what quests the player is currently undertaking.
Corpse CorpseBlueprint, CorpseRequiresBodyPart, BurntCorpseBlueprint, BurntCorpseRequiresBodyPart, VaporizedCorpseBlueprint, VaporizedCorpseRequiresBodyPart Specifies the corpse left by a creature.
Followers Table Generate followers for a creature from a given population table upon spawning.
GenerateName SpecialType, NamingContext Gives the creature a proper name upon spawning.
GivesRep repValue When given to a creature, allows the player to perform the water ritual with that creature.
MentalShield Gives a creature a mental shield.
SocialRoles Roles Add a list of "roles" that appear at the end of a creature's name. For instance, non-named creatures living in Yd Freehold are given the role "denizen of the Yd Freehold".
Titles Primary, Ordinary Add a title that appears after a creature's name. This is used, for example, by Oboroqoru, Ape God and Hamilcrab, cyclopean merchant.

Item- and furniture-specific parts

Name Attributes Description
Animated ChanceOneIn Makes an item animated with a probability given by the ChanceOneIn attribute.
BootSequence BootTime, VariableBootTime, ReadoutInName, ReadoutInDescription, AlwaysObvious, ObviousIfUnderstood, TextInDescription, VerbOnBootInitialized, VerbOnBootDone, VerbOnBootAborted, SoundOnBootInitialized, SoundOnBootDone, SoundOnBootAborted Forces an item to undergo a "boot sequence" before its effects are activated. Examples of items that use this part include thermo cask, ganglionic teleprojector, and telemetric visor.
Chat Says, ShowInShortDescription Adds writing to an object, which appears in the object's description when interacting with it. This is often used, for instance, by the signs outside of merchants' tents at the Six Day Stilt.
Commerce Value Controls the trade value of a given object.
CyberneticsBaseItem Slots, Cost, BehaviorDescription Makes an item an implantable cybernetic.
EnergyCellSocket SlotType, SlottedType, ChanceSlotted, ChanceFullCell, ChanceDestroyCellOnForcedUnequip Controls whether or not an item can be slotted with an energy cell, as well as whether or not it spawns with an energy cell by default.
Examiner Complexity, Difficulty, Unknown, Alternate, Understanding Determines the artifact examination difficulty for an item.
LiquidVolume InitialLiquid, MaxVolume, StartVolume, ManualSeal, LiquidVisibleWhenSealed Allows an item to hold liquid.
MutationOnEquip Level, ClassName, Constructor, Describe Grants a creature the mutation specified by the class name and constructor upon equipping the item (or increases the rank of the mutation if it's already present).

(Note: Constructor is typically used to differentiate between alternate versions of the same mutation; for instance, Stinger (Paralyzing Venom), Stinger (Confusing Venom), and Stinger (Poisoning Venom) all use the same class, but have different constructors.)

TinkerItem Bits, CanDisassemble, CanBuild, Ingredient, SubstituteBlueprint, RepairCost, RustedRepairCost Controls whether or not an item can be built and disassembled with tinkering skills, as well as what bits and special ingredients it may require.

Object materials and physical properties

Name Attributes Description
Interior Cell, WX, WY, X, Y, Z, FallDistance, CarriedWeight, Unique Gives an object an interior zone, which may be entered from outside.
Metal Controls whether or not an object is made of metal.
Physics Weight, Conductivity, FlameTemperature, VaporTemperature, FreezeTemperature, BrittleTemperature, Solid, IsReal, Owner, Takeable, Category Defines a variety of physical properties of objects, including their weight, the temperatures at which they are set on fire and freeze, how much they conduct electricity, and so on. Can also be used to indicate which faction owns an object.
Springy Factor Affects the "springiness" of an object. Objects with higher springiness have a higher kinetic absorption, which reduces knockback taken from explosions.

Armor- and weapon-specific parts

Name Attributes Description
Armor AV, DV, MA, Acid, Elec, Cold, Heat, Strength, Agility, Toughness, Intelligence, Ego, Willpower, ToHit, SpeedPenalty, SpeedBonus, CarryBonus, WornOn Used to specify different stat bonuses provided by an armor type upon being equipped, as well as the body part on which that armor can be equipped.
BioAmmoLoader MaxCapacity, Available, TurnsToGenerate, ReloadEnergy, ProjectileObject, TurnsToGenerateComputePowerFactor, TurnsGenerating Affects ammo capacity and ammo regeneration speed when applied to a missile weapon. BioAmmoLoader is typically used by natural missile weapons; for instance, slugsnouts use it to regenerate slugs, and svardym scrounges use it for their ranged "spit" attack.
CooldownAmmoLoader ProjectileObject, Cooldown, Readout Used by missile weapons that have a cooldown after shooting (e.g. spaser rifles). Can also be used to specify the projectile shot by those weapons.
EnergyAmmoLoader ProjectileObject, ChargeUse, IsPowerLoadSensitive Used by missile weapons that consume energy from energy cells. Can be used to specify the projectile shot by those weapons.
LiquidAmmoLoader ProjectileObject, Liquid, ShotsPerDram, ShowDamage Used by missile weapons that consume a liquid when firing, e.g. flamethrowers.
MagazineAmmoLoader ProjectileObject, AmmoPart, MaxAmmo Used to indicate that a missile weapon needs ammo to fire, and to specify the projectile shot by that weapon.
MeleeWeapon MaxStrengthBonus, BaseDamage, Skill, Stat, Slot Defines the amount of damage that can be dealt by a weapon, what body slot it can be equipped on, and what skill tree it falls under (e.g., Long Blade, Cudgel, etc.)
MissileWeapon AnimationDelay, ShotsPerAction, AmmoPerAction, ShotsPerAnimation, AimVarianceBonus, WeaponAccuracy, MaxRange, VariableMaxRange, AmmoChar, NoWildfire, bShowShotsPerAction, FiresManually, ProjectilePenetrationStat, SlotType, EnergyCost, RangeIncrement, Modifier, Skill Allows an item to be equipped as a missile weapon. Controls various aspects of missile weapon behavior, including projectile range and animations used.
Projectile BasePenetration, StrengthPenetration, PenetrateCreatures, PenetrateWalls, Quiet, BaseDamage, ColorString, Attributes, PassByVerb, RenderChar Used by projectiles shot by missile weapons. Defines the damage done by those weapons as well as other attributes of the projectiles that they shoot.


Name Attributes Description
Harvestable DestroyOnHarvest, OnSuccess, OnSuccessAmount, RipeColor, RipeTileColor, RipeDetailColor, UnripeColor, UnripeTileColor, UnripeDetailColor, StartRipeChance Allows an object to be harvested.

Detailed Topics


  1. XRL.World.Loaders.ObjectBlueprintLoader.RemovalNode