Modding:Objects

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:

<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.
<removepart>	Removes a part that is defined on or inherited by the object
<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>
<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>

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.
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.
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.
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.
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.

Item- and furniture-specific parts

Name	Attributes	Description
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.
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
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.

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.
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