Modding:Objects

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:

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

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:

Load video

YouTube

YouTube might collect personal data. Privacy Policy

ContinueDismiss

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.
<builder>
<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}".
<stat>
<property>
<intproperty>
<xtag>
<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.

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

Parts

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" />
</object>

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.

Miscellaneous

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

Detailed Topics

• Giving Creatures Inventory Items
• Ranged Weapons