Dwarf Fortress Wiki - User contributions [en]

Soil

2026-04-09T02:52:50Z

Quietust: fix grammar

{{migrated article}}
{{av}}
{{Quality|Fine}}
[[File:soil_preview.png|thumb|270px|right|Probably not enough for 80 dwarves.]]'''Soil''' is the name for the various kinds of ground that can be [[farming|planted]] on (both above and below ground) without [[irrigation]] using [[water]]. In ''Dwarf Fortress'', the category of "Soil" includes all types of sand, [[clay]], ooze and any "non-stone" layer equally, even if you or I generally don't associate that substance with "growing plants".

{{Translation
| dwarven = adur
| elvish = avi
| goblin = snustrok
| human = ocul
}}
{| class="wikitable" cellspacing="0" border="1" cellpadding="5"
! Topsoil
! Tile
|-
|[[Loam]]||{{Raw Tile|░|6:7:0}}{{Raw Tile|.|6:0}} {{Raw Tile|≈|3:1:1}}
|-
|[[Loamy sand]]||{{Raw Tile|▒|6:6:1}}{{Raw Tile|.|6:1}} {{Raw Tile|≈|3:1:1}}
|-
|[[Peat]]||{{Raw Tile|░|0:6:1}}{{Raw Tile|.|0:1}} {{Raw Tile|≈|3:1:1}}
|-
|[[Sandy clay loam]]||{{Raw Tile|░|4:6:0}}{{Raw Tile|.|4:0}} {{Raw Tile|≈|3:1:1}}
|-
|[[Sandy loam]]||{{Raw Tile|░|6:6:1}}{{Raw Tile|.|6:1}} {{Raw Tile|≈|3:1:1}}
|-
|[[Silt]]||{{Raw Tile|▓|6:7:0}}{{Raw Tile|.|6:0}} {{Raw Tile|≈|3:1:1}}
|-
|[[Silty clay loam]]||{{Raw Tile|░|4:7:0}}{{Raw Tile|.|4:0}} {{Raw Tile|≈|3:1:1}}
|-
|[[Silt loam]]||{{Raw Tile|▒|6:7:0}}{{Raw Tile|.|6:0}} {{Raw Tile|≈|3:1:1}}
|-
! Ocean Floor
! Tile
|-
|[[Pelagic clay]]||{{Raw Tile|░|4:6:0}}{{Raw Tile|.|4:0}} {{Raw Tile|≈|3:1:1}}
|-
|[[Siliceous ooze]]||{{Raw Tile|▒|4:7:0}}{{Raw Tile|.|4:0}} {{Raw Tile|≈|3:1:1}}
|-
|[[Calcareous ooze]]||{{Raw Tile|▒|4:7:0}}{{Raw Tile|.|4:0}} {{Raw Tile|≈|3:1:1}}
|-
! [[Sand]]
! Tile
|-
|[[Sand (tan)]]||{{Raw Tile|░|6:4:1}}{{Raw Tile|≈|6:1}} {{Raw Tile|≈|3:1:1}}
|-
|[[Black sand]]||{{Raw Tile|▓|0:6:1}}{{Raw Tile|≈|0:1}} {{Raw Tile|≈|3:1:1}}
|-
|[[Red sand]]||{{Raw Tile|░|4:4:1}}{{Raw Tile|≈|4:1}} {{Raw Tile|≈|3:1:1}}
|-
|[[White sand]]||{{Raw Tile|▓|7:6:1}}{{Raw Tile|≈|7:1}} {{Raw Tile|≈|3:1:1}}
|-
|[[Yellow sand]]||{{Raw Tile|▓|6:6:1}}{{Raw Tile|≈|6:1}} {{Raw Tile|≈|3:1:1}}
|-
! Clay
! Tile
|-
|[[Clay]]||{{Raw Tile|▓|4:6:0}}{{Raw Tile|.|4:0}}
|-
|[[Clay loam]]||{{Raw Tile|▒|4:7:0}}{{Raw Tile|.|4:0}}
|-
|[[Sandy clay]]||{{Raw Tile|▒|4:6:0}}{{Raw Tile|.|4:0}}
|-
|[[Silty clay]]||{{Raw Tile|▓|4:7:0}}{{Raw Tile|.|4:0}}
|-
|[[Fire clay]]||{{Raw Tile|▓|4:6:0}}{{Raw Tile|.|4:0}}
|}
'''Notes:'''
* The "topsoil" types "Loamy sand", "Sandy clay loam", and "Sandy loam" do '''not''' count as [[sand]] for [[glass]]making, even if their names include the word "sand" - only those in the "Sand" section are usable for this purpose.
* The 3 "ocean floor" layers are only found under deep [[ocean]] tiles, usually far out from any embarkable site. Thus, they can rarely, if ever be encountered, in either [[fortress mode]] or [[adventurer mode]].
* Soil layers marked with {{Raw Tile|≈|3:1:1}} are capable of supporting an [[aquifer]].
* The [[clay]] types listed at the bottom can be used for making ceramic items. Fire clay produces [[stoneware]], while the other types produce [[earthenware]].

In previous versions, types and quantities of available soils were listed at the bottom right of the fortress location selection screen; in the current version, however, it will only indicate the presence of soil and whether it can be used as [[clay]].

Digging into soil does not generate any byproduct materials, unlike digging in [[stone|rock]], and also is a much faster process which makes it much easier to create storerooms and other large areas of empty space, and to train [[miner]]s.

Soil cannot be [[Smoothing|smooth]]ed, which makes it more difficult to make high-value rooms or pierce [[aquifer]]s, and impossible to carve [[fortification]]s, [[track]]s, or [[engraving]]s.

Building a [[farm plot]] or [[road]] or removing a [[construction]] on top of soil will cause it to become "furrowed", making it appear with the {{Tile|≈|6:0}} and {{Tile|~|6:0}} tiles. Furrowed soil — including furrowed subterranean soil — will gradually smooth itself out, at which point grass and other vegetation will begin to grow. Sand always appears as {{Tile|≈|6:0}} and {{Tile|~|6:0}} and cannot become furrowed - as such, sand roads do not last as long as those made on ordinary soil.

===Trees and Shrubs===
Once you discover any [[cavern]] layer, all subterranean [[grass]], [[shrub]]s, and [[tree]]s growing within that cavern will begin to grow on any subterranean soil. Any kind of vegetation implicitly has some soil under it, even if it grew on [[mud]]dy stone; clearing the growth (such as by building a [[road]]) will thus create a soil floor, even in a stone [[layer]]. It will typically correspond to the lowest soil layer in the local [[biome]]; if that happens to be useful clay or sand, an enterprising player can use [[irrigation]] and some patience to move their sand/clay collection [[zone]]s closer to the [[magma]].

{{materials}}
{{soil}}

{{Category|Soil Layers|*}}
[[Ru:Soil]]

v0.31:Inorganic material definition token

2026-04-04T01:18:11Z

Quietust:

{{quality|Exceptional|21:09, 30 March 2011 (UTC)}}{{av}}

The following tokens can be used in inorganic material definitions, generally those for stones, gems, and metals. They cannot be used with materials attached to plants or creatures.

{| {{prettytable}}
|- style='background-color:#ddd'
! Token
! Arguments
! Description
|-
| {{text anchor|WAFERS}}|| ||Used on metals, causes the metal to be made into wafers instead of [[bar]]s.
|-
| {{text anchor|DEEP_SPECIAL}}|| || Causes the stone to form hollow tubes leading to the [[Underworld]]. Used for [[raw adamantine]]. When mined, stone has a 100% yield. If no material with this token exists, hollow veins will instead be made of the first available inorganic, usually [[iron]].
|-
| {{text anchor|METAL_ORE}}|| metal:chance || Allows the ore to be [[smelter|smelted]] into metal in the smelter. Multiple tokens allow multiple types of metal to be smelted from a single ore.
|-
| {{text anchor|THREAD_METAL}}|| metal:chance ||Allows strands to be extracted from the metal at a [[craftsdwarf's workshop]].
|-
| {{text anchor|DEEP_SURFACE}}|| ||Causes the stone to line the landscape of the [[Underworld]]. Used for [[slade]]. When mined (if it's mineable), stone has a 100% yield. If no material with this token exists, other materials will be used in place of slade.
|-
| {{text anchor|AQUIFER}}|| ||Allows the stone to support an [[aquifer]].
|-
| {{text anchor|METAMORPHIC}}|| ||Causes the material to form [[metamorphic layer]]s.
|-
| {{text anchor|SEDIMENTARY}}|| ||Causes the material to form [[sedimentary layer]]s.
|-
| {{text anchor|SOIL}}|| ||Causes the material to form [[soil]] layers, allowing it to appear in (almost) any biome. Mining is faster and produces no stones.
|-
| {{text anchor|SOIL_OCEAN}}|| ||Causes the material to form [[soil|pelagic sediment]] layers beneath deep oceans. Mining is faster and produces no stones.
|-
| {{text anchor|SOIL_SAND}}|| ||Causes the material to form [[sand]] layers, allowing it to appear in [[sand desert]]s and shallow [[ocean]]s. Mining is faster and produces no stones. Sand layers can also be used for making [[glass]]. Can be combined with [SOIL].
|-
| {{text anchor|SEDIMENTARY_OCEAN_SHALLOW}}|| ||Permits an already [SEDIMENTARY] stone layer to appear underneath shallow ocean regions.
|-
| {{text anchor|SEDIMENTARY_OCEAN_DEEP}}|| ||Permits an already [SEDIMENTARY] stone layer to appear underneath deep ocean regions.
|-
| {{text anchor|IGNEOUS_INTRUSIVE}}|| || Causes the material to form [[igneous intrusive layer]]s.
|-
| {{text anchor|IGNEOUS_EXTRUSIVE}}|| || Causes the material to form [[igneous extrusive layer]]s.
|-
| {{text anchor|ENVIRONMENT}}|| class:type:freq ||Specifies what types of layers will contain this mineral. Multiple instances of the same token segment will cause the rock type to occur more frequently, but won't increase its abundance in the specified environment. See below.
|-
| {{text anchor|ENVIRONMENT_SPEC}}|| stone:type:freq ||Specifies which specific minerals will contain this mineral. See below.
|-
| {{text anchor|LAVA}}|| ||Specifies that the stone is created when combining [[water]] and [[magma]], also causing it to line the edges of [[magma]] pools and volcanoes. If multiple minerals are marked as lava stones, a different one will be used in each biome or geological region.
|}

==ENVIRONMENT and ENVIRONMENT_SPEC==

Format:
* [ENVIRONMENT:<class>:<inclusion type>:<frequency>]

Possible values for class:
{| {{prettytable}}
|- style='background-color:#ddd'
! Environment class token
! Description
|-
| {{text anchor|ALL_STONE}}||Will appear in every stone.
|-
| {{text anchor|IGNEOUS_ALL}}, {{text anchor|IGNEOUS_INTRUSIVE}}, {{text anchor|IGNEOUS_EXTRUSIVE}}||Will appear in igneous layers, either [[igneous intrusive]], [[igneous extrusive]], or both.
|-
| {{text anchor|SOIL}}, {{text anchor|SOIL_OCEAN}}, {{text anchor|SOIL_SAND}}||Will appear in soil. SOIL_OCEAN is oceans specifically and SOIL_SAND is sand specifically.
|-
| {{text anchor|METAMORPHIC}}||Will appear in [[metamorphic]] layers.
|-
| {{text anchor|SEDIMENTARY}}||Will appear in [[sedimentary]] layers.
|-
| {{text anchor|ALLUVIAL}}||Will appear in [[alluvial]] layers.
|}

Possible values for inclusion type:
{| {{prettytable}}
|- style='background-color:#ddd'
! Inclusion type token
! Description
|-
| {{text anchor|CLUSTER}}||Large ovoids that occupy their entire 48x48 embark tile. [[Microcline]] is an example. When mined, stone has a 25% yield (as with layer stones).
|-
| {{text anchor|CLUSTER_SMALL}}||Blobs of 3-9 tiles. Will always be successfully mined. [[Red pyrope]]s are an example. When mined, stone has a 100% yield.
|-
| {{text anchor|CLUSTER_ONE}}||Single tiles. Will always be successfully mined. [[Clear diamond]]s are an example. When mined, stone has a 100% yield.
|-
| {{text anchor|VEIN}}||Large streaks of stone. [[Native gold]] is an example. When mined, stone has a 33% yield instead of the usual 25%.
|}

An inclusion may be contained within a larger inclusion. For example, diamond small clusters are found within kimberlite veins.

The frequency number varies from 1 to 100 and determines the relative frequency at which the stone will be chosen to appear - if all frequency values are the same, then all stones will be equally likely to appear.

ENVIRONMENT_SPEC follows much the same format, but takes a specific stone material ID where ENVIRONMENT would take a class token. What you can use will depend on what inorganic raws are around.

Due to an error in the raw parsing logic, having multiple ENVIRONMENT_SPEC tokens will cause the inclusion type to be parsed in ''reverse'' order compared to the stone ID and frequency values - in the vanilla raws, this causes [[native platinum]] to appear as veins within [[chromite]] and as small clusters within [[olivine]].{{bug|1429}}

==See Also==
* [[Material definition token]]

{{Category|Modding}}
{{Category|Tokens}}

v0.34:Inorganic material definition token

2026-04-04T01:17:08Z

Quietust:

{{quality|Exceptional|21:09, 30 March 2011 (UTC)}}{{av}}

The following tokens can be used in inorganic material definitions, generally those for stones, gems, and metals. They cannot be used with materials attached to plants or creatures.

{| {{prettytable}}
|- style='background-color:#ddd'
! Token
! Arguments
! Description
|-
| {{text anchor|WAFERS}}|| ||Used on metals, causes the metal to be made into wafers instead of [[bar]]s.
|-
| {{text anchor|DEEP_SPECIAL}}|| || Causes the stone to form hollow tubes leading to the [[Underworld]]. Used for [[raw adamantine]]. When mined, stone has a 100% yield. If no material with this token exists, hollow veins will instead be made of the first available inorganic, usually [[iron]].
|-
| {{text anchor|METAL_ORE}}|| metal:chance || Allows the ore to be [[smelter|smelted]] into metal in the smelter. Multiple tokens allow multiple types of metal to be smelted from a single ore.
|-
| {{text anchor|THREAD_METAL}}|| metal:chance ||Allows strands to be extracted from the metal at a [[craftsdwarf's workshop]].
|-
| {{text anchor|DEEP_SURFACE}}|| ||Causes the stone to line the landscape of the [[Underworld]]. Used for [[slade]]. When mined (if it's mineable), stone has a 100% yield. If no material with this token exists, other materials will be used in place of slade.
|-
| {{text anchor|AQUIFER}}|| ||Allows the stone to support an [[aquifer]].
|-
| {{text anchor|METAMORPHIC}}|| ||Causes the material to form [[metamorphic layer]]s.
|-
| {{text anchor|SEDIMENTARY}}|| ||Causes the material to form [[sedimentary layer]]s.
|-
| {{text anchor|SOIL}}|| ||Causes the material to form [[soil]] layers, allowing it to appear in (almost) any biome. Mining is faster and produces no stones.
|-
| {{text anchor|SOIL_OCEAN}}|| ||Causes the material to form [[soil|pelagic sediment]] layers beneath deep oceans. Mining is faster and produces no stones.
|-
| {{text anchor|SOIL_SAND}}|| ||Causes the material to form [[sand]] layers, allowing it to appear in [[sand desert]]s and shallow [[ocean]]s. Mining is faster and produces no stones. Sand layers can also be used for making [[glass]]. Can be combined with [SOIL].
|-
| {{text anchor|SEDIMENTARY_OCEAN_SHALLOW}}|| ||Permits an already [SEDIMENTARY] stone layer to appear underneath shallow ocean regions.
|-
| {{text anchor|SEDIMENTARY_OCEAN_DEEP}}|| ||Permits an already [SEDIMENTARY] stone layer to appear underneath deep ocean regions.
|-
| {{text anchor|IGNEOUS_INTRUSIVE}}|| || Causes the material to form [[igneous intrusive layer]]s.
|-
| {{text anchor|IGNEOUS_EXTRUSIVE}}|| || Causes the material to form [[igneous extrusive layer]]s.
|-
| {{text anchor|ENVIRONMENT}}|| class:type:freq ||Specifies what types of layers will contain this mineral. Multiple instances of the same token segment will cause the rock type to occur more frequently, but won't increase its abundance in the specified environment. See below.
|-
| {{text anchor|ENVIRONMENT_SPEC}}|| stone:type:freq ||Specifies which specific minerals will contain this mineral. See below.
|-
| {{text anchor|LAVA}}|| ||Specifies that the stone is created when combining [[water]] and [[magma]], also causing it to line the edges of [[magma]] pools and volcanoes. If multiple minerals are marked as lava stones, a different one will be used in each biome or geological region.
|-
| {{text anchor|SPECIAL}}|| ||Prevents the material from showing up in certain places. AI-controlled entities won't use the material to make items and don't bring it in caravans, though the player can use it as normal. Also, inorganic generated creatures (forgotten beasts, titans, demons) will never be composed of this material. Explicitly set by all [[evil weather]] materials and implied by [DEEP_SURFACE] and [DEEP_SPECIAL].
|-
| {{text anchor|GENERATED}}|| ||Indicates that this is a generated material. Cannot be specified in user-defined raws.
|}

==ENVIRONMENT and ENVIRONMENT_SPEC==

Format:
* [ENVIRONMENT:<class>:<inclusion type>:<frequency>]

Possible values for class:
{| {{prettytable}}
|- style='background-color:#ddd'
! Environment class token
! Description
|-
| {{text anchor|ALL_STONE}}||Will appear in every stone.
|-
| {{text anchor|IGNEOUS_ALL}}, {{text anchor|IGNEOUS_INTRUSIVE}}, {{text anchor|IGNEOUS_EXTRUSIVE}}||Will appear in igneous layers, either [[igneous intrusive]], [[igneous extrusive]], or both.
|-
| {{text anchor|SOIL}}, {{text anchor|SOIL_OCEAN}}, {{text anchor|SOIL_SAND}}||Will appear in soil. SOIL_OCEAN is oceans specifically and SOIL_SAND is sand specifically.
|-
| {{text anchor|METAMORPHIC}}||Will appear in [[metamorphic]] layers.
|-
| {{text anchor|SEDIMENTARY}}||Will appear in [[sedimentary]] layers.
|-
| {{text anchor|ALLUVIAL}}||Will appear in [[alluvial]] layers.
|}

Possible values for inclusion type:
{| {{prettytable}}
|- style='background-color:#ddd'
! Inclusion type token
! Description
|-
| {{text anchor|CLUSTER}}||Large ovoids that occupy their entire 48x48 embark tile. [[Microcline]] is an example. When mined, stone has a 25% yield (as with layer stones).
|-
| {{text anchor|CLUSTER_SMALL}}||Blobs of 3-9 tiles. Will always be successfully mined. [[Red pyrope]]s are an example. When mined, stone has a 100% yield.
|-
| {{text anchor|CLUSTER_ONE}}||Single tiles. Will always be successfully mined. [[Clear diamond]]s are an example. When mined, stone has a 100% yield.
|-
| {{text anchor|VEIN}}||Large streaks of stone. [[Native gold]] is an example. When mined, stone has a 33% yield instead of the usual 25%.
|}

An inclusion may be contained within a larger inclusion. For example, diamond small clusters are found within kimberlite veins.

The frequency number varies from 1 to 100 and determines the relative frequency at which the stone will be chosen to appear - if all frequency values are the same, then all stones will be equally likely to appear.

ENVIRONMENT_SPEC follows much the same format, but takes a specific stone material ID where ENVIRONMENT would take a class token. What you can use will depend on what inorganic raws are around.

Due to an error in the raw parsing logic, having multiple ENVIRONMENT_SPEC tokens will cause the inclusion type to be parsed in ''reverse'' order compared to the stone ID and frequency values - in the vanilla raws, this causes [[native platinum]] to appear as veins within [[chromite]] and as small clusters within [[olivine]].{{bug|1429}}

==See Also==
* [[Material definition token]]

{{Category|Modding}}
{{Category|Tokens}}

Material definition token

2026-04-04T01:14:44Z

Quietust: remove inorganic tokens

{{Quality|Fine}}
{{av}}
{{Modding}}

The following [[token]]s can be used in creating new [[:Category:material template raw pages|material templates]], as well as in [[material]] definitions (whether for inorganics or those within plants and creatures).

Material templates are used to define broad classes of materials (eg. "stone", or "milk"), the properties of which can be imported into other more specific material definitions (eg. "granite", or "llama milk") using the <code>[USE_MATERIAL_TEMPLATE:template_name]</code> token. When creating material templates, the <code>[OBJECT:MATERIAL_TEMPLATE]</code> [[token]] begins the definition of a material template [[raw file]]. Following this, each new material template definition begins with the <code>[MATERIAL_TEMPLATE:template_name]</code> token, where <code>template_name</code> is a unique identifier for the template, and that material's properties are then defined using the tokens listed below.

{{Urist asks|q=Materials use specific, often bespoke, units. Are there any tools to help convert from real-world values?|a=
Here are some web-based [[utilities]] designed for raw authoring.

For [[material science|yield]] and [[strain at yield|elasticity]]: https://putnam3145.github.io/helper

For [[temperature]]: https://jose96xd.github.io/DF_Tools/Modules/TemperatureConverter.html
}}

__TOC__
{{clear}}

==Material properties==
{| {{prettytable}}
|- bgcolor="#C0C0C0"
! Token
! Arguments
! Description

|-
| {{text_anchor|USE_MATERIAL_TEMPLATE}}
|
* <template name>
| Resets all material tokens back to their default values, then imports the tokens of the specified preexisting material template (overriding any tokens defined prior to itself in the material). This means USE_MATERIAL_TEMPLATE should be the first token present in any material using it. It cannot be used inside of a [MATERIAL_TEMPLATE:X] which prevents the creation of nested material template structures.

|-
| {{text_anchor|PREFIX}}
|
* <prefix> or NONE
| Applies a prefix to all items made from the material. For PLANT and CREATURE materials, this defaults to the plant/creature name. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|STONE_NAME}}
|
* <name>
| Overrides the name of [[Item token#BOULDER|BOULDER]] items (i.e. mined-out stones) made of the material (used for native copper/silver/gold/platinum to make them be called "nuggets" instead of "boulders").

|-
| {{text_anchor|IS_GEM}}
|
* <name>
* <plural>
* OVERWRITE_SOLID (optional)
| Used to indicate that said material is a gemstone - when tiles are mined out, rough gems will be yielded instead of boulders. Plural can be "STP" to automatically append an "s" to the singular form, and OVERWRITE_SOLID will override the relevant STATE_NAME and STATE_ADJ values.

|-
| {{text_anchor|TEMP_DIET_INFO}}
|
* <type>
| Specifies what the material should be treated as when drinking water contaminated by it, for generating unhappy [[thought]]s. Valid values are BLOOD, SLIME, VOMIT, ICHOR, PUS, GOO, GRIME, and FILTH.

|-
| {{text_anchor|POWDER_DYE}}
|
*<[[Color#Color tokens|color token]]>
| Allows the material to be used as [[dye]], and defines color of dyed items.

|-
| {{text_anchor|TILE}}
|
*<[[Main:Character table|tile value or character]]>
| Specifies the tile that will be used to represent unmined tiles made of this material. Generally only used with stones. Defaults to 219 ('█').

|-
| {{text_anchor|ITEM_SYMBOL}}
|
*<[[Main:Character table|tile value or character]]>
| Specifies the tile that will be used to represent [[Item token#BOULDER|BOULDER]] items made of this material. Generally only used with stones. Defaults to 7 ('•').

|-
| {{text_anchor|DISPLAY_COLOR}}
|
*<[[Color#Color values|foreground color]]>
*<[[Color#Color values|background color]]>
*<[[Color#Color values|foreground brightness]]>
| The on-screen color of the material. Uses a standard 3-digit [[Color|color token]]. Equivalent to [TILE_COLOR:a:b:c], [BUILD_COLOR:b:a:X] (X = 1 if 'a' equals 'b', 0 otherwise), and [BASIC_COLOR:a:c]

|-
| {{text_anchor|BUILD_COLOR}}
|
*<[[Color#Color values|foreground color]]>
*<[[Color#Color values|background color]]>
*<[[Color#Color values|foreground brightness]]>
| The color of objects made of this material which use both the foreground and background color: [[door]]s, [[floodgate]]s, [[hatch cover]]s, [[bin]]s, [[barrel]]s, and [[cage]]s. Defaults to 7:7:1 (white).

|-
| {{text_anchor|TILE_COLOR}}
|
*<[[Color#Color values|foreground color]]>
*<[[Color#Color values|background color]]>
*<[[Color#Color values|foreground brightness]]>
| The color of unmined tiles containing this material (for stone and soil), as well as [[engraving]]s in this material. Defaults to 7:7:1 (white).

|-
| {{text_anchor|BASIC_COLOR}}
|
*<[[Color#Color values|foreground color]]>
*<[[Color#Color values|foreground brightness]]>
| The color of objects made of this material which use only the foreground color, including workshops, floors and boulders, and smoothed walls. Defaults to 7:1 (white).

|-
| {{text_anchor|STATE_COLOR}}
|
*<[[#Material states|material state]]>
*<[[Color#Color tokens|color token]]>
| Determines the color of the material at the specified state. Color comes from descriptor_color_standard.txt. The nearest color value is used to display contaminants and body parts made of this material in ASCII and to color items and constructions made from this material with graphics. Example:
[STATE_COLOR:ALL_SOLID:GRAY]

|-
| {{text_anchor|STATE_NAME}}
|
*<[[#Material states|material state]]>
*<name>
| Determines the name of the material at the specified state, as displayed in-game.
[STATE_NAME:ALL_SOLID:stone]

|-
| {{text_anchor|STATE_ADJ}}
|
*<[[#Material states|material state]]>
*<adjective>
| Like [[#STATE_NAME|STATE_NAME]], but used in different situations. Equipment made from the material uses the state adjective and not the state name.

|-
| {{text_anchor|STATE_NAME_ADJ}}
|
*<[[#Material states|material state]]>
*<name>
*<adjective>
| Sets both [[#STATE_NAME|STATE_NAME]] and [[#STATE_ADJ|STATE_ADJ]] at the same time.

|-
| {{text_anchor|ABSORPTION}}
|
*<value>
| The material's tendency to absorb liquids. Containers made of materials with nonzero absorption cannot hold liquids unless they have been [[glaze]]d. Defaults to 0.

|-
| {{text_anchor|IMPACT_YIELD}}
|
*<pressure>
| Specifies how hard of an impact (in kPa) the material can withstand before it will start deforming permanently. Used for blunt-force combat. Defaults to 10000.

|-
| {{text_anchor|IMPACT_FRACTURE}}
|
*<pressure>
| Specifies how hard of an impact the material can withstand before it will fail entirely. Used for blunt-force combat. Defaults to 10000.

|-
| {{text_anchor|IMPACT_STRAIN_AT_YIELD}} or {{text_anchor|IMPACT_ELASTICITY}}
|
*<[[Strain at yield|strain]]>
| Specifies how much the material will have given (in parts-per-100000) when the yield point is reached. Used for blunt-force combat. Defaults to 0. Apparently affects in combat whether the corresponding tissue is bruised (value >= 50000), torn (value between 25000 and 49999), or fractured (value <= 24999)

|-
| {{text_anchor|COMPRESSIVE_YIELD}}
|
*<pressure>
| Specifies how hard the material can be compressed before it will start deforming permanently. Determines a tissue's resistance to pinching and response to strangulation. Defaults to 10000.

|-
| {{text_anchor|COMPRESSIVE_FRACTURE}}
|
*<pressure>
| Specifies how hard the material can be compressed before it will fail entirely. Determines a tissue's resistance to pinching and response to strangulation. Defaults to 10000.

|-
| {{text_anchor|COMPRESSIVE_STRAIN_AT_YIELD}} or {{text_anchor|COMPRESSIVE_ELASTICITY}}
|
*<[[Strain at yield|strain]]>
| Specifies how much the material will have given when it has been compressed to its yield point. Determines a tissue's resistance to pinching and response to strangulation. Defaults to 0.

|-
| {{text_anchor|TENSILE_YIELD}}
|
*<pressure>
| Specifies how hard the material can be stretched before it will start deforming permanently. Determines a tissue's resistance to latching and shaking (50% chance, with torsion the other 50%). Defaults to 10000.

|-
| {{text_anchor|TENSILE_FRACTURE}}
|
*<pressure>
| Specifies how hard the material can be stretched before it will fail entirely. Determines a tissue's resistance to latching and shaking (50% chance). Defaults to 10000.

|-
| {{text_anchor|TENSILE_STRAIN_AT_YIELD}} or {{text_anchor|TENSILE_ELASTICITY}}
|
*<[[Strain at yield|strain]]>
| Specifies how much the material will have given when it is stretched to its yield point. Determines a tissue's resistance to to latching and shaking (50% chance). Defaults to 0.

|-
| {{text_anchor|TORSION_YIELD}}
|
*<pressure>
| Specifies how hard the material can be twisted before it will start deforming permanently. Used for latching and shaking (50% chance). Defaults to 10000.

|-
| {{text_anchor|TORSION_FRACTURE}}
|
*<pressure>
| Specifies how hard the material can be twisted before it will fail entirely. Used for latching and shaking (50% chance). Defaults to 10000.

|-
| {{text_anchor|TORSION_STRAIN_AT_YIELD}} or {{text_anchor|TORSION_ELASTICITY}}
|
*<[[Strain at yield|strain]]>
| Specifies how much the material will have given when it is twisted to its yield point. Used for latching and shaking (50% chance). Defaults to 0.

|-
| {{text_anchor|SHEAR_YIELD}}
|
*<pressure>
| Specifies how hard the material can be sheared before it will start deforming permanently. Used for cutting calculations. Defaults to 10000.

|-
| {{text_anchor|SHEAR_FRACTURE}}
|
*<pressure>
| Specifies how hard the material can be sheared before it will fail entirely. Used for cutting calculations. Defaults to 10000.

|-
| {{text_anchor|SHEAR_STRAIN_AT_YIELD}} or {{text_anchor|SHEAR_ELASTICITY}}
|
*<[[Strain at yield|strain]]>
| Specifies how much the material will have given when sheared to its yield point. Used for cutting calculations. Defaults to 0.

|-
| {{text_anchor|BENDING_YIELD}}
|
*<pressure>
| Specifies how hard the material can be bent before it will start deforming permanently. Determines a tissue's resistance to being mangled with a joint lock. Defaults to 10000.

|-
| {{text_anchor|BENDING_FRACTURE}}
|
*<pressure>
| Specifies how hard the material can be bent before it will fail entirely. Determines a tissue's resistance to being mangled with a joint lock. Defaults to 10000.

|-
| {{text_anchor|BENDING_STRAIN_AT_YIELD}} or {{text_anchor|BENDING_ELASTICITY}}
|
*<[[Strain at yield|strain]]>
| Specifies how much the material will have given when bent to its yield point. Determines a tissue's resistance to being mangled with a joint lock. Defaults to 0.

|-
| {{text_anchor|MAX_EDGE}}
|
*<value>
| How sharp the material is. Used in cutting calculations. Applying a value of at least 10000 to a stone will allow weapons to be made from that stone. Defaults to 10000.

|-
| {{text_anchor|MATERIAL_VALUE}}
|
*<[[item value]]>
| Value modifier for the material. Defaults to 1. This number can be made negative by placing a "-" in front, resulting in things that you are paid to buy and must pay to sell.

|-
| {{text_anchor|MULTIPLY_VALUE}}
|
*<[[item value]]>
| Multiplies the value of the material. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|SPEC_HEAT}}
|
*<specific heat capacity>
| Rate at which the material heats up or cools down (in J⋅kg−1⋅K−1.). If set to NONE, the temperature will be fixed at its initial value. See [[Temperature]] for more information. Defaults to NONE.

|-
| {{text_anchor|HEATDAM_POINT}}
|
*<[[temperature]]>
| Temperature above which the material takes damage from heat. May be set to NONE. If the material has an ignite point but no heatdam point, it will burn for a very long time (9 months and 16.8 days). Defaults to NONE.

|-
| {{text_anchor|COLDDAM_POINT}}
|
*<[[temperature]]>
| Temperature below which the material takes damage from cold. Defaults to NONE.

|-
| {{text_anchor|IGNITE_POINT}}
|
*<[[temperature]]>
| Temperature at which the material will catch fire. Defaults to NONE.

|-
| {{text_anchor|MELTING_POINT}}
|
*<[[temperature]]>
| Temperature at which the material melts. Defaults to NONE.

|-
| {{text_anchor|BOILING_POINT}}
|
*<[[temperature]]>
| Temperature at which the material boils. Defaults to NONE.

|-
| {{text_anchor|MAT_FIXED_TEMP}}
|
*<[[temperature]]>
| Items composed of this material will initially have this temperature. Used in conjunction with <code>[SPEC_HEAT:NONE]</code> to make material's temperature fixed at the specified value. Defaults to NONE.

|-
| {{text_anchor|IF_EXISTS_SET_HEATDAM_POINT}}
|
*<[[temperature]]>
| Changes a material's HEATDAM_POINT, but only if it was not set to NONE. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|IF_EXISTS_SET_COLDDAM_POINT}}
|
*<[[temperature]]>
| Changes a material's COLDDAM_POINT, but only if it was not set to NONE. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|IF_EXISTS_SET_IGNITE_POINT}}
|
*<[[temperature]]>
| Changes a material's IGNITE_POINT, but only if it was not set to NONE. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|IF_EXISTS_SET_MELTING_POINT}}
|
*<[[temperature]]>
| Changes a material's MELTING_POINT, but only if it was not set to NONE. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|IF_EXISTS_SET_BOILING_POINT}}
|
*<[[temperature]]>
| Changes a material's BOILING_POINT, but only if it was not set to NONE. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|IF_EXISTS_SET_MAT_FIXED_TEMP}}
|
*<[[temperature]]>
| Changes a material's MAT_FIXED_TEMP, but only if it was not set to NONE. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|SOLID_DENSITY}}
|
*<[[density]]>
| Specifies the density (in kg/m³) of the material when in solid form. Also affects combat calculations; affects blunt-force damage and ability of weak-in-impact-yield blunt attacks to pierce armor. Defaults to NONE.

|-
| {{text_anchor|LIQUID_DENSITY}}
|
*<[[density]]>
| Specifies the density of the material when in liquid form. Defaults to NONE. Also affects combat calculations; affects blunt force damage like SOLID_DENSITY, but only for attacks made by liquids (e.g. forgotten beasts made of water).

|-
| {{text_anchor|MOLAR_MASS}}
|
*<value>
| Specifies (in kg/mol) the molar mass of the material in gaseous form. Only affects combat calculations like the densities, and only for attacks made by gases (e.g. forgotten beasts made of steam).

|-
| {{text_anchor|EXTRACT_STORAGE}}
| * BARREL or FLASK
| Specifies the type of container used to store the material. Used in conjunction with the [EXTRACT_BARREL], [EXTRACT_VIAL], or [EXTRACT_STILL_VIAL] [[plant token]]s. Defaults to BARREL.

|-
| {{text_anchor|BUTCHER_SPECIAL}}
|
*<[[item token]]>
| Specifies the item type used for butchering results made of this material. Stock raws use GLOB:NONE for fat and MEAT:NONE for other meat materials.

|-
| {{text_anchor|MEAT_NAME}}
|
*<prefix>
*<name>
*<adjective>
| When a creature is butchered, meat yielded from organs made from this material will be named via this token. If this token is not specified, meat objects will be called "chops" instead.

|-
| {{text_anchor|BLOCK_NAME}}
|
*<singular>
*<plural>
| Specifies the name of [[block]]s made from this material.

|-
| {{text_anchor|MATERIAL_REACTION_PRODUCT}}
|
*<reaction reference>
*<[[material token]]>
| Used with reaction raws to associate a reagent material with a product material. The first argument is used by HAS_MATERIAL_REACTION_PRODUCT and GET_MATERIAL_FROM_REAGENT in reaction raws. The remainder is a material reference, generally LOCAL_CREATURE_MAT:SUBTYPE or LOCAL_PLANT_MAT:SUBTYPE or INORGANIC:STONETYPE.
[MATERIAL_REACTION_PRODUCT:TAN_MAT:LOCAL_CREATURE_MAT:LEATHER]

|-
| {{text_anchor|ITEM_REACTION_PRODUCT}}
|
*<item reference>
*<[[item token]]>
*<[[material token]]>
| Used with reaction raws to associate a reagent material with a complete item. The first argument is used by HAS_ITEM_REACTION_PRODUCT and GET_ITEM_DATA_FROM_REAGENT in reaction raws. The rest refers to the type of item, then its material.
[ITEM_REACTION_PRODUCT:BAG_ITEM:PLANT_GROWTH:LEAVES:LOCAL_PLANT_MAT:LEAF]

|-
| {{text_anchor|REACTION_CLASS}}
|
*<reaction class name>
| Used to classify all items made of the material, so that reactions can use them as generic reagents.
In default raws, the following are used:
* FAT, TALLOW, SOAP, PARCHMENT, PAPER_PLANT, PAPER_SLURRY, MILK, CHEESE, WAX
* CAN_GLAZE - items made from this material can be glazed.
* FLUX - can be used as [[flux]] in pig iron and steel making.
* GYPSUM - can be processed into [[gypsum plaster]].
* CALCIUM_CARBONATE - can be used in production of [[quicklime]].

The TALLOW reaction class also flags the material to be stored in "rendered fat" containers. Other default reaction classes might affect storage, too, but testing is needed.

|-
| {{text_anchor|HARDENS_WITH_WATER}}
|
* <[[material token]]>
| Allows the material to be used to make [[healthcare|casts]].

|-
| {{text_anchor|SOAP_LEVEL}}
|
*<value>
| Determines effectiveness of soap - if the amount of grime on a body part is more than 3-SOAP_LEVEL, it sets it to 3-SOAP_LEVEL; as such setting it above 3 is bad. [[Soap]] has [SOAP_LEVEL:2]. Defaults to 0.

|-
| {{text_anchor|SYNDROME}}
|
| Begins defining a [[syndrome]] applied by the material. Multiple syndromes can be specified. See [[Syndrome token]].

|-
| {{text_anchor|ANTLER}}
|
| Found in the raws of several antler-wielding animals. It is used to show an antler as bodypart.
|

|-
| {{text_anchor|HAIR}}
|
| Probably used in graphics.
|

|-
| {{text_anchor|FEATHER}}
|
| Probably used in graphics.
|

|-
| {{text_anchor|SCALE}}
|
| Probably used in graphics.
|

|-
| {{text_anchor|HOOF}}
|
| Probably used in graphics.
|

|-
| {{text_anchor|CHITIN}}
|
| Probably used in graphics.
|

|-
| {{text_anchor|CARTILAGE}}
|
| Probably used in graphics.
|

|-
| {{text_anchor|NERVOUS_TISSUE}}
|
| Probably used in graphics.
|

|-
| {{text_anchor|MEAT_CATEGORY}}
| category
| Probably used in graphics. The following values for "category" are used in the vanilla raws: STANDARD, EYE, LUNG, HEART, INTESTINES, LIVER, STOMACH, PANCREAS, SPLEEN, KIDNEY, BRAIN, GIZZARD.
|}

===Material states===

The following is a list of valid material states:

{| {{prettytable}}
|-
|'''SOLID'''
|-
|'''LIQUID'''
|-
|'''GAS'''
|-
|'''POWDER''' (or '''SOLID_POWDER''')
|-
|'''PASTE''' (or '''SOLID_PASTE''')
|-
|'''PRESSED''' (or '''SOLID_PRESSED''')
|}

The following can be specified within tokens such as [[#STATE_NAME|STATE_NAME]], [[#STATE_NAME_ADJ|STATE_NAME_ADJ]] and [[#STATE_ADJ|STATE_ADJ]] to make them apply to several of the above material states simultaneously:

{| {{prettytable}}
|- bgcolor="#C0C0C0"
!Value
!Description
|-
|'''ALL'''
|Denotes all possible material states.
|-
|'''ALL_SOLID'''
|Denotes 'SOLID', 'POWDER', 'PASTE' and 'PRESSED'.
|}

==Material usage tokens==
{| {{prettytable}}
|- bgcolor="#C0C0C0"
! Token
! Arguments
! Description

|-
| {{text_anchor|IMPLIES_ANIMAL_KILL}}
|
| Lets the game know that an animal was likely killed in the production of this item. Entities opposed to killing animals ([[elf|Elves]] in vanilla) will refuse to accept these items in trade.

|-
| {{text_anchor|ALCOHOL_PLANT}}
|
| Classifies the material as plant-based alcohol, allowing its storage in food stockpiles under "Drink (Plant)".

|-
| {{text_anchor|ALCOHOL_CREATURE}}
|
| Classifies the material as animal-based alcohol, allowing its storage in food stockpiles under "Drink (Animal)".

|-
| {{text_anchor|ALCOHOL}}
|
| Classifies the material as generic alcohol. Implied by both ALCOHOL_PLANT and ALCOHOL_CREATURE. Exact behavior unknown, possibly vestigial.

|-
| {{text_anchor|CHEESE_PLANT}}
|
| Classifies the material as plant-based cheese, allowing its storage in food stockpiles under "Cheese (Plant)".

|-
| {{text_anchor|CHEESE_CREATURE}}
|
| Classifies the material as animal-based cheese, allowing its storage in food stockpiles under "Cheese (Animal)".

|-
| {{text_anchor|CHEESE}}
|
| Classifies the material as generic cheese. Implied by both CHEESE_PLANT and CHEESE_CREATURE. Exact behavior unknown, possibly vestigial.

|-
| {{text_anchor|POWDER_MISC_PLANT}}
|
| Classifies the material as plant powder, allowing its storage in food stockpiles under "Milled Plant".

|-
| {{text_anchor|POWDER_MISC_CREATURE}}
|
| Classifies the material as creature powder, allowing its storage in food stockpiles under "Bone Meal". Unlike milled plants, such as sugar and flour, "Bone Meal" barrels or pots may not contain bags. Custom reactions using this product better use buckets or jugs instead.

|-
| {{text_anchor|POWDER_MISC}}
|
| Classifies the material as generic powder. Implied by both POWDER_MISC_PLANT and POWDER_MISC_CREATURE. Exact behavior unknown, possibly vestigial.

|-
| {{text_anchor|STOCKPILE_GLOB}} or {{text_anchor|STOCKPILE_GLOB_SOLID}}
|
| Permits globs of the material in solid form to be stored in food stockpiles under "Fat" - without it, dwarves will come by and "clean" the items, destroying them (unless [DO_NOT_CLEAN_GLOB] is also included).

|-
| {{text_anchor|STOCKPILE_GLOB_PASTE}}
|
| Classifies the material as milled paste, allowing its storage in food stockpiles under "Paste".

|-
| {{text_anchor|STOCKPILE_GLOB_PRESSED}}
|
| Classifies the material as pressed goods, allowing its storage in food stockpiles under "Pressed Material".

|-
| {{text_anchor|STOCKPILE_PLANT_GROWTH}}
|
| Classifies the material as a plant growth (e.g. fruits, leaves), allowing its storage in food stockpiles under Plant Growth/Fruit.

|-
| {{text_anchor|LIQUID_MISC_PLANT}}
|
| Classifies the material as a plant extract, allowing its storage in food stockpiles under "Extract (Plant)".

|-
| {{text_anchor|LIQUID_MISC_CREATURE}}
|
| Classifies the material as a creature extract, allowing its storage in food stockpiles under "Extract (Animal)".

|-
| {{text_anchor|LIQUID_MISC_OTHER}}
|
| Classifies the material as a miscellaneous liquid, allowing its storage in food stockpiles under "Misc. Liquid" along with [[lye]].

|-
| {{text_anchor|LIQUID_MISC}}
|
| Classifies the material as a generic liquid. Implied by LIQUID_MISC_PLANT, LIQUID_MISC_CREATURE, and LIQUID_MISC_OTHER. Exact behavior unknown, possibly vestigial.

|-
| {{text_anchor|STRUCTURAL_PLANT_MAT}}
|
| Classifies the material as a plant, allowing its storage in food stockpiles under "Plants".

|-
| {{text_anchor|SEED_MAT}}
|
| Classifies the material as a plant seed, allowing its storage in food stockpiles under "Seeds".

|-
| {{text_anchor|BONE}}
|
| Classifies the material as bone, allowing its use for bone carvers and restriction from stockpiles by material.

|-
| {{text_anchor|WOOD}}
|
| Classifies the material as wood, allowing its use for carpenters and storage in wood stockpiles. Entities opposed to killing plants (i.e. [[Elf|Elves]]) will refuse to accept these items in trade.

|-
| {{text_anchor|THREAD_PLANT}}
|
| Classifies the material as plant fiber, allowing its use for clothiers and storage in cloth stockpiles under "Thread (Plant)" and "Cloth (Plant)".

|-
| {{text_anchor|TOOTH}}
|
| Classifies the material as tooth, allowing its use for bone carvers and restriction from stockpiles by material.

|-
| {{text_anchor|HORN}}
|
| Classifies the material as horn, allowing its use for bone carvers and restriction from stockpiles by material.

|-
| {{text_anchor|HAIR}}
|
| Classifies the material as hair, allowing for its use for spinners and restriction from refuse stockpiles by material.

|-
| {{text_anchor|PEARL}}
|
| Classifies the material as pearl, allowing its use for bone carvers and restriction from stockpiles by material.

|-
| {{text_anchor|SHELL}}
|
| Classifies the material as shell, allowing its use for bone carvers and restriction from stockpiles by material.

|-
| {{text_anchor|LEATHER}}
|
| Classifies the material as leather, allowing its use for leatherworkers and storage in leather stockpiles.

|-
| {{text_anchor|SILK}}
|
| Classifies the material as silk, allowing its use for clothiers and storage in cloth stockpiles under "Thread (Silk)" and "Cloth (Silk)".

|-
| {{text_anchor|SOAP}}
|
| Classifies the material as soap, allowing it to be used as a bath detergent and stored in bar/block stockpiles under "Bars: Other Materials".{{verify}}

|-
| {{text_anchor|GENERATES_MIASMA}}
|
| Material generates miasma when it rots.

|-
| {{text_anchor|MEAT}}
|
| Classifies the material as edible meat.{{verify}}

|-
| {{text_anchor|ROTS}}
|
| Material will rot if not stockpiled appropriately. Currently only affects [[food]] and [[refuse]], other items made of this material will not rot.

|-
| {{text_anchor|NERVOUS_TISSUE}}
|
| In most living creatures, it controls many bodily functions and movements by sending signals around the body. See: [[Nervous tissue]]

|-
| {{text_anchor|BLOOD_MAP_DESCRIPTOR}}
|
| Tells the game to classify contaminants of this material as being "blood" in Adventurer mode tile descriptions ("Here we have a Dwarf in a slurry of blood.").

|-
| {{text_anchor|ICHOR_MAP_DESCRIPTOR}}
|
| Tells the game to classify contaminants of this material as being "ichor".

|-
| {{text_anchor|GOO_MAP_DESCRIPTOR}}
|
| Tells the game to classify contaminants of this material as being "goo".

|-
| {{text_anchor|SLIME_MAP_DESCRIPTOR}}
|
| Tells the game to classify contaminants of this material as being "slime".

|-
| {{text_anchor|PUS_MAP_DESCRIPTOR}}
|
| Tells the game to classify contaminants of this material as being "pus".

|-
| {{text_anchor|SWEAT_MAP_DESCRIPTOR}}
|
| Tells the game to classify contaminants of this material as being "sweat".

|-
| {{text_anchor|TEARS_MAP_DESCRIPTOR}}
|
| Tells the game to classify contaminants of this material as being "tears".

|-
| {{text_anchor|SPIT_MAP_DESCRIPTOR}}
|
| Tells the game to classify contaminants of this material as being "spit".

|-
| {{text_anchor|EVAPORATES}}
|
| Contaminants composed of this material evaporate over time, slowly disappearing from the map. Used internally by water.

|-
| {{text_anchor|ENTERS_BLOOD}}
|
| Used for materials which cause [[syndrome]]s, causes it to enter the creature's blood instead of simply spattering on the surface.

|-
| {{text_anchor|EDIBLE_VERMIN}}
|
| Can be eaten by vermin.

|-
| {{text_anchor|EDIBLE_RAW}}
|
| Can be eaten raw.

|-
| {{text_anchor|EDIBLE_COOKED}}
|
| Can be cooked and then eaten.

|-
| {{text_anchor|DO_NOT_CLEAN_GLOB}}
|
| Prevents globs made of this material from being cleaned up and destroyed.

|-
| {{text_anchor|NO_STONE_STOCKPILE}}
|
| Prevents the material from showing up in Stone stockpile settings.

|-
| {{text_anchor|ITEMS_METAL}}
|
| The material can be made into minecarts, wheelbarrows, and stepladders at the metalsmith's forge.

|-
| {{text_anchor|ITEMS_BARRED}}
|
| Theoretically allows the item to be made into {{token|BARRED|ar}} armor, but doesn't actually work (game checks for {{token|BONE|md}} instead). Given to [[bone]].

|-
| {{text_anchor|ITEMS_SCALED}}
|
| Theoretically allows the item to be made into {{token|SCALED|ar}} armor, but doesn't actually work (game checks for {{token|SHELL|md}} instead). Given to [[shell]].

|-
| {{text_anchor|ITEMS_LEATHER}}
|
| Theoretically allows the item to be made into {{token|LEATHER|ar}} armor, but doesn't actually work (game checks for {{token|LEATHER|md}} instead). Given to [[leather]].

|-
| {{text_anchor|ITEMS_SOFT}}
|
| The material can be made into clothing, amulets, bracelets, earrings, backpacks, and quivers, contingent on which workshops accept the material. Given to [[plant fiber]], [[silk]] and [[wool]].

|-
| {{text_anchor|ITEMS_HARD}}
|
| The material can be made into furniture, crafts, mechanisms, and blocks, contingent on which workshops accept the material. Random [[finished goods|crafts]] made from this material include all seven items. Given to [[stone]], [[wood]], [[bone]], [[shell]], [[chitin]], [[nail|claws]], [[tooth|teeth]], [[horn|horns]], [[horn|hooves]] and [[wax|beeswax]]. [[Hair]], [[pearl|pearls]] and eggshells also have the tag.

|-
| {{text_anchor|IS_STONE}}
|
| Used to define that the material is a stone. Allows its usage in [[masonry]] and [[stonecrafting]] and storage in stone stockpiles, among other effects.

|-
| {{text_anchor|UNDIGGABLE}}
|
| Used for a stone that cannot be dug into.

|-
| {{text_anchor|DISPLAY_UNGLAZED}}
|
| Causes containers made of this material to be prefixed with "unglazed" if they have not yet been [[glaze]]d.

|-
| {{text_anchor|YARN}}
|
| Classifies the material as yarn, allowing its use for clothiers and its storage in cloth stockpiles under "Thread (Yarn)" and "Cloth (Yarn)".

|-
| {{text_anchor|STOCKPILE_THREAD_METAL}}
|
| Classifies the material as metal thread, permitting thread and cloth to be stored in cloth stockpiles under "Thread (Metal)" and "Cloth (Metal)".

|-
| {{text_anchor|IS_METAL}}
|
| Defines the material as being metal, allowing it to be used at forges.

|-
| {{text_anchor|IS_GLASS}}
|
| Used internally by green glass, clear glass, and crystal glass. Appears to only affect the [[Reaction#GLASS_MATERIAL|[GLASS_MATERIAL]]] reaction token. Does not cause the game to treat the material like glass, i.e being referred to as "raw" instead of "rough" in its raw form or being displayed in the "glass" trade/embark category.

|-
| {{text_anchor|IS_CERAMIC}}
|
| Defines the material as a ceramic. Examples include CERAMIC_EARTHENWARE, CERAMIC_STONEWARE and CERAMIC_PORCELAIN.

|-
| {{text_anchor|CRYSTAL_GLASSABLE}}
|
| Can be used in the production of crystal glass.

|-
| {{text_anchor|ITEMS_WEAPON}}
|
| Melee [[Weapon#Manufactured weapons|weapons]] can be made out of this material.

|-
| {{text_anchor|ITEMS_WEAPON_RANGED}}
|
| Ranged weapons can be made out of this material.

|-
| {{text_anchor|ITEMS_ANVIL}}
|
| [[Anvil]]s can be made out of this material.

|-
| {{text_anchor|ITEMS_AMMO}}
|
| [[Weapon#Ammunition|Ammunition]] can be made out of this material.

|-
| {{text_anchor|ITEMS_DIGGER}}
|
| [[Weapon#Dwarf-manufactured weapons|Picks]] can be made out of this material.

|-
| {{text_anchor|ITEMS_ARMOR}}
|
| [[Armor]] can be made out of this material.

|-
| {{text_anchor|ITEMS_DELICATE}}
|
| Used internally by amber and coral. Functionally equivalent to ITEMS_HARD.

|-
| {{text_anchor|ITEMS_SIEGE_ENGINE}}
|
| Theoretically, siege engine parts can be made out of this material. Does not appear to work (game checks for {{token|WOOD|md}} or {{token|IS_METAL|md}}+{{token|ITEMS_SOFT|md}} instead).

|-
| {{text_anchor|ITEMS_QUERN}}
|
| Theoretically, querns and millstones can be made out of this material. Does not appear to work (game checks for {{token|ITEMS_HARD|md}} instead).
|}

==Syndrome tokens==
Below is a table with some of the tokens you can use when declaring a [SYNDROME] token. For all the tokens you can use, see the [[Syndrome token]] page.

{| {{prettytable}}
|- bgcolor="#C0C0C0"
! Token
! Arguments
! Description

|-
| {{text_anchor|SYN_NAME
|
* text
| Defines the name of the syndrome

|-
| {{text_anchor|SYN_INJECTED}}
|
| Syndrome can be contracted by injection (by a creature)

|-
| {{text_anchor|SYN_CONTACT}}
|
| Syndrome can be contracted on contact (e.g. poison dust or liquid)

|-
| {{text_anchor|SYN_INHALED}}
|
| Syndrome can be contracted by inhalation (e.g. poison vapor or gas)

|-
| {{text_anchor|SYN_INGESTED}}
|
| Syndrome can be contracted by ingestion (when the material is eaten in solid or liquid form)

|-
| {{text_anchor|SYN_AFFECTED_CLASS}}
|
* creature class name
| Adds a class of creatures to those affected, such as CREATURE_CLASS:GENERAL_POISON

|-
| {{text_anchor|SYN_IMMUNE_CLASS}}
|
* creature class name
| Makes the class of creatures immune to the syndrome

|-
| {{text_anchor|SYN_AFFECTED_CREATURE}}
|
* creature name
* caste name or ALL
| Adds a specific creature to those affected.

|-
| {{text_anchor|SYN_IMMUNE_CREATURE}}
|
* creature name
* caste name or ALL
| Makes the creature immune to the syndrome

|-
| CE_PAIN CE_SWELLING CE_OOZING CE_BRUISING CE_BLISTERS CE_NUMBNESS CE_PARALYSIS CE_FEVER CE_BLEEDING CE_COUGH_BLOOD CE_VOMIT_BLOOD CE_NAUSEA CE_UNCONSCIOUSNESS CE_NECROSIS CE_IMPAIR_FUNCTION CE_DROWSINESS CE_DIZZINESS
|
*SEV:<value> (severity, higher is worse)
*PROB:<value(1-100)> (probability)
*RESISTABLE (optional) allows resistance
*SIZE_DILUTES (optional) lessens effect based on size
Place affected:
*LOCALIZED (optional)
*VASCULAR_ONLY (optional)
*MUSCULAR_ONLY (optional)
*BP:BY_CATEGORY:category:tissue (optional)
*BP:BY_TYPE:type:tissue (optional)
*BP:BY_TOKEN:token:tissue (optional)
Timeline:
*Start:effect start time
*Peak:effect peak time
*End:effect end time
| Specifies the way that a syndrome affects a creature -- more detail can be found on the [[Syndrome#Creature effect tokens|Syndromes page]]

|}

==See also==
* [[Inorganic material definition token]]
* [[Syndrome]]
* [[Hardcoded material]]

{{Category|Modding}}
{{Category|Tokens}}
[[ru:Material definition token]]

DF2014:Material definition token

2026-04-04T01:14:13Z

Quietust: remove inorganic-specific tokens

{{Quality|Fine|11:11, 18 May 2015 (UTC)}}
{{av}}
{{Modding}}

The following [[token]]s can be used in [[material]] definitions (whether for inorganics or those within plants and creatures) as well as in [[material templates]].

__TOC__
{{clear}}

==Material properties==
{| {{prettytable}}
|- bgcolor="#C0C0C0"
! Token
! Arguments
! Description

|-
| {{text_anchor|USE_MATERIAL_TEMPLATE}}
|
* <template name>
| Imports the properties of the specified preexisting material template.

|-
| {{text_anchor|PREFIX}}
|
* <prefix> or NONE
| Applies a prefix to all items made from the material. For PLANT and CREATURE materials, this defaults to the plant/creature name. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|STONE_NAME}}
|
* <name>
| Overrides the name of [[Item_token#BOULDER|BOULDER]] items (i.e. mined-out stones) made of the material (used for native copper/silver/gold/platinum to make them be called "nuggets" instead of "boulders").

|-
| {{text_anchor|IS_GEM}}
|
* <name>
* <plural>
* OVERWRITE_SOLID (optional)
| Used to indicate that said material is a gemstone - when tiles are mined out, rough gems will be yielded instead of boulders. Plural can be "STP" to automatically append an "s" to the singular form, and OVERWRITE_SOLID will override the relevant STATE_NAME and STATE_ADJ values.

|-
| {{text_anchor|TEMP_DIET_INFO}}
|
* <type>
| Specifies what the material should be treated as when drinking water contaminated by it, for generating unhappy [[thought]]s. Valid values are BLOOD, SLIME, VOMIT, ICHOR, PUS, GOO, GRIME, and FILTH.

|-
| {{text_anchor|POWDER_DYE}}
|
*<[[Color#Color_tokens|color token]]>
| Allows the material to be used as [[dye]], and defines color of dyed items.

|-
| {{text_anchor|TILE}}
|
*<[[Main:Character table|tile value or character]]>
| Specifies the tile that will be used to represent unmined tiles made of this material. Generally only used with stones. Defaults to 219 ('█').

|-
| {{text_anchor|ITEM_SYMBOL}}
|
*<[[Main:Character table|tile value or character]]>
| Specifies the tile that will be used to represent [[Item_token#BOULDER|BOULDER]] items made of this material. Generally only used with stones. Defaults to 7 ('•').

|-
| {{text_anchor|DISPLAY_COLOR}}
|
*<[[Color#Color_values|foreground color]]>
*<[[Color#Color_values|background color]]>
*<[[Color#Color_values|foreground brightness]]>
| The on-screen color of the material. Uses a standard 3-digit [[Color|color token]]. Equivalent to [TILE_COLOR:a:b:c], [BUILD_COLOR:b:a:X] (X = 1 if 'a' equals 'b', 0 otherwise), and [BASIC_COLOR:a:c]

|-
| {{text_anchor|BUILD_COLOR}}
|
*<[[Color#Color_values|foreground color]]>
*<[[Color#Color_values|background color]]>
*<[[Color#Color_values|foreground brightness]]>
| The color of objects made of this material which use both the foreground and background color: [[door]]s, [[floodgate]]s, [[hatch cover]]s, [[bin]]s, [[barrel]]s, and [[cage]]s. Defaults to 7:7:1 (white).

|-
| {{text_anchor|TILE_COLOR}}
|
*<[[Color#Color_values|foreground color]]>
*<[[Color#Color_values|background color]]>
*<[[Color#Color_values|foreground brightness]]>
| The color of unmined tiles containing this material (for stone and soil), as well as [[engraving]]s in this material. Defaults to 7:7:1 (white).

|-
| {{text_anchor|BASIC_COLOR}}
|
*<[[Color#Color_values|foreground color]]>
*<[[Color#Color_values|foreground brightness]]>
| The color of objects made of this material which use only the foreground color, including workshops, floors and boulders, and smoothed walls. Defaults to 7:1 (white).

|-
| {{text_anchor|STATE_COLOR}}
|
*<[[Material_definition_token#Material States|material state]]>
*<[[Color#Color_tokens|color token]]>
| Determines the color of the material at the specified state. See [[Material_definition_token#Material states|below]] for a list of valid material states. Color comes from descriptor_color_standard.txt. The nearest color value is used to display contaminants and body parts made of this material. Example:
[STATE_COLOR:ALL_SOLID:GRAY]

|-
| {{text_anchor|STATE_NAME}}
|
*<[[Material_definition_token#Material States|material state]]>
*<name>
| Determines the name of the material at the specified state, as displayed in-game.
[STATE_NAME:ALL_SOLID:stone]

|-
| {{text_anchor|STATE_ADJ}}
|
*<[[Material_definition_token#Material States|material state]]>
*<adjective>
| Like [[Material_definition_token#STATE_NAME|STATE_NAME]], but used in different situations. Equipment made from the material uses the state adjective and not the state name.

|-
| {{text_anchor|STATE_NAME_ADJ}}
|
*<[[Material_definition_token#Material States|material state]]>
*<name>
*<adjective>
| Sets both [[Material_definition_token#STATE_NAME|STATE_NAME]] and [[Material_definition_token#STATE_ADJ|STATE_ADJ]] at the same time.

|-
| {{text_anchor|ABSORPTION}}
|
*<value>
| The material's tendency to absorb liquids. Containers made of materials with nonzero absorption cannot hold liquids unless they have been [[glaze]]d. Defaults to 0.

|-
| {{text_anchor|IMPACT_YIELD}}
|
*<value>
| Specifies how hard of an impact (in kilopascals) the material can withstand before it will start deforming permanently. Used for blunt-force combat. Defaults to 10000.

|-
| {{text_anchor|IMPACT_FRACTURE}}
|
*<value>
| Specifies how hard of an impact the material can withstand before it will fail entirely. Used for blunt-force combat. Defaults to 10000.

|-
| {{text_anchor|IMPACT_STRAIN_AT_YIELD}} or {{text_anchor|IMPACT_ELASTICITY}}
|
*<value>
| Specifies how much the material will have given (in parts-per-100000) when the yield point is reached. Used for blunt-force combat. Defaults to 0. Apparently affects in combat whether the corresponding tissue is bruised (value >= 50000), torn (value between 25000 and 49999), or fractured (value <= 24999)

|-
| {{text_anchor|COMPRESSIVE_YIELD}}
|
*<value>
| Specifies how hard the material can be compressed before it will start deforming permanently. Determines a tissue's resistance to pinching and response to strangulation. Defaults to 10000.

|-
| {{text_anchor|COMPRESSIVE_FRACTURE}}
|
*<value>
| Specifies how hard the material can be compressed before it will fail entirely. Determines a tissue's resistance to pinching and response to strangulation. Defaults to 10000.

|-
| {{text_anchor|COMPRESSIVE_STRAIN_AT_YIELD}} or {{text_anchor|COMPRESSIVE_ELASTICITY}}
|
*<value>
| Specifies how much the material will have given when it has been compressed to its yield point. Determines a tissue's resistance to pinching and response to strangulation. Defaults to 0.

|-
| {{text_anchor|TENSILE_YIELD}}
|
*<value>
| Specifies how hard the material can be stretched before it will start deforming permanently. Determines a tissue's resistance to a latching and tearing bite. Defaults to 10000.

|-
| {{text_anchor|TENSILE_FRACTURE}}
|
*<value>
| Specifies how hard the material can be stretched before it will fail entirely. Determines a tissue's resistance to a latching and tearing bite. Defaults to 10000.

|-
| {{text_anchor|TENSILE_STRAIN_AT_YIELD}} or {{text_anchor|TENSILE_ELASTICITY}}
|
*<value>
| Specifies how much the material will have given when it is stretched to its yield point. Determines a tissue's resistance to a latching and tearing bite. Defaults to 0.

|-
| {{text_anchor|TORSION_YIELD}}
|
*<value>
| Specifies how hard the material can be twisted before it will start deforming permanently. Used for latching and shaking with a blunt attack (no default creature has such an attack, but they can be modded in). Defaults to 10000.

|-
| {{text_anchor|TORSION_FRACTURE}}
|
*<value>
| Specifies how hard the material can be twisted before it will fail entirely. Used for latching and shaking with a blunt attack (no default creature has such an attack, but they can be modded in). Defaults to 10000.

|-
| {{text_anchor|TORSION_STRAIN_AT_YIELD}} or {{text_anchor|TORSION_ELASTICITY}}
|
*<value>
| Specifies how much the material will have given when it is twisted to its yield point. Used for latching and shaking with a blunt attack (no default creature has such an attack, but they can be modded in). Defaults to 0.

|-
| {{text_anchor|SHEAR_YIELD}}
|
*<value>
| Specifies how hard the material can be sheared before it will start deforming permanently. Used for cutting calculations. Defaults to 10000.

|-
| {{text_anchor|SHEAR_FRACTURE}}
|
*<value>
| Specifies how hard the material can be sheared before it will fail entirely. Used for cutting calculations. Defaults to 10000.

|-
| {{text_anchor|SHEAR_STRAIN_AT_YIELD}} or {{text_anchor|SHEAR_ELASTICITY}}
|
*<value>
| Specifies how much the material will have given when sheared to its yield point. Used for cutting calculations. Defaults to 0.

|-
| {{text_anchor|BENDING_YIELD}}
|
*<value>
| Specifies how hard the material can be bent before it will start deforming permanently. Determines a tissue's resistance to being mangled with a joint lock. Defaults to 10000.

|-
| {{text_anchor|BENDING_FRACTURE}}
|
*<value>
| Specifies how hard the material can be bent before it will fail entirely. Determines a tissue's resistance to being mangled with a joint lock. Defaults to 10000.

|-
| {{text_anchor|BENDING_STRAIN_AT_YIELD}} or {{text_anchor|BENDING_ELASTICITY}}
|
*<value>
| Specifies how much the material will have given when bent to its yield point. Determines a tissue's resistance to being mangled with a joint lock. Defaults to 0.

|-
| {{text_anchor|MAX_EDGE}}
|
*<value>
| How sharp the material is. Used in cutting calculations. Does not allow an inferior metal to penetrate superior armor. Applying a value of at least 10000 to a stone will allow weapons to be made from that stone. Defaults to 10000.

|-
| {{text_anchor|MATERIAL_VALUE}}
|
*<value>
| Value modifier for the material. Defaults to 1. This number can be made negative by placing a "-" in front, resulting in things that you are paid to buy and must pay to sell.

|-
| {{text_anchor|MULTIPLY_VALUE}}
|
*<value>
| Multiplies the value of the material. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|SPEC_HEAT}}
|
*<specific heat capacity>
| Rate at which the material heats up or cools down (in joules/kilogram-kelvin). If set to NONE, the temperature will be fixed at its initial value. See [[Temperature]] for more information. Defaults to NONE.

|-
| {{text_anchor|HEATDAM_POINT}}
|
*<temperature>
| Temperature above which the material takes damage from heat. May be set to NONE. If the material has an ignite point but no heatdam point, it will burn for a very long time (9 months and 16.8 days). Defaults to NONE.

|-
| {{text_anchor|COLDDAM_POINT}}
|
*<temperature>
| Temperature below which the material takes damage from cold. Defaults to NONE.

|-
| {{text_anchor|IGNITE_POINT}}
|
*<temperature>
| Temperature at which the material will catch fire. Defaults to NONE.

|-
| {{text_anchor|MELTING_POINT}}
|
*<temperature>
| Temperature at which the material melts. Defaults to NONE.

|-
| {{text_anchor|BOILING_POINT}}
|
*<temperature>
| Temperature at which the material boils. Defaults to NONE.

|-
| {{text_anchor|MAT_FIXED_TEMP}}
|
*<temperature>
| Items composed of this material will initially have this temperature. Used in conjunction with <code>[SPEC_HEAT:NONE]</code> to make material's temperature fixed at the specified value. Defaults to NONE.

|-
| {{text_anchor|IF_EXISTS_SET_HEATDAM_POINT}}
|
*<temperature>
| Changes a material's HEATDAM_POINT, but only if it was not set to NONE. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|IF_EXISTS_SET_COLDDAM_POINT}}
|
*<temperature>
| Changes a material's COLDDAM_POINT, but only if it was not set to NONE. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|IF_EXISTS_SET_IGNITE_POINT}}
|
*<temperature>
| Changes a material's IGNITE_POINT, but only if it was not set to NONE. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|IF_EXISTS_SET_MELTING_POINT}}
|
*<temperature>
| Changes a material's MELTING_POINT, but only if it was not set to NONE. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|IF_EXISTS_SET_BOILING_POINT}}
|
*<temperature>
| Changes a material's BOILING_POINT, but only if it was not set to NONE. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|IF_EXISTS_SET_MAT_FIXED_TEMP}}
|
*<temperature>
| Changes a material's MAT_FIXED_TEMP, but only if it was not set to NONE. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|SOLID_DENSITY}}
|
*<density>
| Specifies the density (in kilograms per cubic meter) of the material when in solid form. Also affects combat calculations; affects blunt-force damage and ability of edged weapons to pierce tissue layers{{verify}}. Defaults to NONE.

|-
| {{text_anchor|LIQUID_DENSITY}}
|
*<density>
| Specifies the density of the material when in liquid form. Defaults to NONE.

|-
| {{text_anchor|MOLAR_MASS}}
|
*<value>
| Supposedly not used{{verify}}. Theoretically, should determine density (at given pressure) in gas state, on which in turn would depend (together with weight of vaporized material) on the volume covered by spreading vapors. Defaults to NONE.

|-
| {{text_anchor|EXTRACT_STORAGE}}
| * BARREL or FLASK
| Specifies the type of container used to store the material. Used in conjunction with the [EXTRACT_BARREL], [EXTRACT_VIAL], or [EXTRACT_STILL_VIAL] [[plant token]]s. Defaults to BARREL.

|-
| {{text_anchor|BUTCHER_SPECIAL}}
|
*<[[item token]]>
| Specifies the item type used for butchering results made of this material. Stock raws use GLOB:NONE for fat and MEAT:NONE for other meat materials.

|-
| {{text_anchor|MEAT_NAME}}
|
*<prefix>
*<name>
*<adjective>
| When a creature is butchered, meat yielded from organs made from this material will be named via this token. If this token is not specified, meat objects will be called "chops" instead.

|-
| {{text_anchor|BLOCK_NAME}}
|
*<singular>
*<plural>
| Specifies the name of [[block]]s made from this material.

|-
| {{text_anchor|MATERIAL_REACTION_PRODUCT}}
|
*<reaction reference>
*<[[material token]]>
| Used with reaction raws to associate a reagent material with a product material. The first argument is used by HAS_MATERIAL_REACTION_PRODUCT and GET_MATERIAL_FROM_REAGENT in reaction raws. The remainder is a material reference, generally LOCAL_CREATURE_MAT:SUBTYPE or LOCAL_PLANT_MAT:SUBTYPE or INORGANIC:STONETYPE.
[MATERIAL_REACTION_PRODUCT:TAN_MAT:LOCAL_CREATURE_MAT:LEATHER]

|-
| {{text_anchor|ITEM_REACTION_PRODUCT}}
|
*<item reference>
*<[[item token]]>
*<[[material token]]>
| Used with reaction raws to associate a reagent material with a complete item. The first argument is used by HAS_ITEM_REACTION_PRODUCT and GET_ITEM_DATA_FROM_REAGENT in reaction raws. The rest refers to the type of item, then its material.
[ITEM_REACTION_PRODUCT:BAG_ITEM:PLANT_GROWTH:LEAVES:LOCAL_PLANT_MAT:LEAF]

|-
| {{text_anchor|REACTION_CLASS}}
|
*<reaction class name>
| Used to classify all items made of the material, so that reactions can use them as generic reagents.
In default raws, the following are used:
* FAT, TALLOW, SOAP, PARCHMENT, PAPER_PLANT, PAPER_SLURRY, MILK, CHEESE, WAX
* CAN_GLAZE - items made from this material can be glazed.
* FLUX - can be used as [[flux]] in pig iron and steel making.
* GYPSUM - can be processed into [[gypsum plaster]].
* CALCIUM_CARBONATE - can be used in production of [[quicklime]].{{version|0.42.01}}

|-
| {{text_anchor|HARDENS_WITH_WATER}}
|
* <[[material token]]>
| Allows the material to be used to make [[healthcare|casts]].

|-
| {{text_anchor|SOAP_LEVEL}}
|
*<value>
| [[Soap]] has [SOAP_LEVEL:2]. Effects unknown. Defaults to 0.

|-
| {{text_anchor|SYNDROME}}
|
| Begins defining a [[syndrome]] applied by the material. Multiple syndromes can be specified. See [[Syndrome token]].
|}

===Material states===

The following is a list of valid material states:

{| {{prettytable}}
|-
|'''SOLID'''
|-
|'''LIQUID'''
|-
|'''GAS'''
|-
|'''POWDER''' (or '''SOLID_POWDER''')
|-
|'''PASTE''' (or '''SOLID_PASTE''')
|-
|'''PRESSED''' (or '''SOLID_PRESSED''')
|}

The following can be specified within tokens such as [[Material_definition_token#STATE_NAME|STATE_NAME]], [[Material_definition_token#STATE_NAME_ADJ|STATE_NAME_ADJ]] and [[Material_definition_token#STATE_ADJ|STATE_ADJ]] to make them apply to several of the above material states simultaneously:

{| {{prettytable}}
|- bgcolor="#C0C0C0"
!Value
!Description
|-
|'''ALL'''
|Denotes all possible material states.
|-
|'''ALL_SOLID'''
|Denotes 'SOLID', 'POWDER', 'PASTE' and 'PRESSED'.
|}

==Material usage tokens==
{| {{prettytable}}
|- bgcolor="#C0C0C0"
! Token
! Arguments
! Description

|-
| {{text_anchor|IMPLIES_ANIMAL_KILL}}
|
| Lets the game know that an animal was likely killed in the production of this item. Entities opposed to killing animals (which currently does '''not''' include [[elf|Elves]]) will refuse to accept these items in trade.

|-
| {{text_anchor|ALCOHOL_PLANT}}
|
| Classifies the material as plant-based alcohol, allowing its storage in food stockpiles under "Drink (Plant)".

|-
| {{text_anchor|ALCOHOL_CREATURE}}
|
| Classifies the material as animal-based alcohol, allowing its storage in food stockpiles under "Drink (Animal)".

|-
| {{text_anchor|ALCOHOL}}
|
| Classifies the material as generic alcohol. Implied by both ALCOHOL_PLANT and ALCOHOL_CREATURE. Exact behavior unknown, possibly vestigial.

|-
| {{text_anchor|CHEESE_PLANT}}
|
| Classifies the material as plant-based cheese, allowing its storage in food stockpiles under "Cheese (Plant)".

|-
| {{text_anchor|CHEESE_CREATURE}}
|
| Classifies the material as animal-based cheese, allowing its storage in food stockpiles under "Cheese (Animal)".

|-
| {{text_anchor|CHEESE}}
|
| Classifies the material as generic cheese. Implied by both CHEESE_PLANT and CHEESE_CREATURE. Exact behavior unknown, possibly vestigial.

|-
| {{text_anchor|POWDER_MISC_PLANT}}
|
| Classifies the material as plant powder, allowing its storage in food stockpiles under "Milled Plant".

|-
| {{text_anchor|POWDER_MISC_CREATURE}}
|
| Classifies the material as creature powder, allowing its storage in food stockpiles under "Bone Meal". Unlike milled plants, such as sugar and flour, "Bone Meal" barrels or pots may not contain bags. Custom reactions using this product better use buckets or jugs instead.

|-
| {{text_anchor|POWDER_MISC}}
|
| Classifies the material as generic powder. Implied by both POWDER_MISC_PLANT and POWDER_MISC_CREATURE. Exact behavior unknown, possibly vestigial.

|-
| {{text_anchor|STOCKPILE_GLOB}} or {{text_anchor|STOCKPILE_GLOB_SOLID}}
|
| Permits globs of the material in solid form to be stored in food stockpiles under "Fat" - without it, dwarves will come by and "clean" the items, destroying them (unless [DO_NOT_CLEAN_GLOB] is also included).

|-
| {{text_anchor|STOCKPILE_GLOB_PASTE}}
|
| Classifies the material as milled paste, allowing its storage in food stockpiles under "Paste".

|-
| {{text_anchor|STOCKPILE_GLOB_PRESSED}}
|
| Classifies the material as pressed goods, allowing its storage in food stockpiles under "Pressed Material".

|-
| {{text_anchor|STOCKPILE_PLANT_GROWTH}}
|
| Classifies the material as a plant growth (e.g. fruits, leaves), allowing its storage in food stockpiles under Plant Growth/Fruit.

|-
| {{text_anchor|LIQUID_MISC_PLANT}}
|
| Classifies the material as a plant extract, allowing its storage in food stockpiles under "Extract (Plant)".

|-
| {{text_anchor|LIQUID_MISC_CREATURE}}
|
| Classifies the material as a creature extract, allowing its storage in food stockpiles under "Extract (Animal)".

|-
| {{text_anchor|LIQUID_MISC_OTHER}}
|
| Classifies the material as a miscellaneous liquid, allowing its storage in food stockpiles under "Misc. Liquid" along with lye.

|-
| {{text_anchor|LIQUID_MISC}}
|
| Classifies the material as a generic liquid. Implied by LIQUID_MISC_PLANT, LIQUID_MISC_CREATURE, and LIQUID_MISC_OTHER. Exact behavior unknown, possibly vestigial.

|-
| {{text_anchor|STRUCTURAL_PLANT_MAT}}
|
| Classifies the material as a plant, allowing its storage in food stockpiles under "Plants".

|-
| {{text_anchor|SEED_MAT}}
|
| Classifies the material as a plant seed, allowing its storage in food stockpiles under "Seeds".

|-
| {{text_anchor|BONE}}
|
| Classifies the material as bone, allowing its use for bone carvers and restriction from stockpiles by material.

|-
| {{text_anchor|WOOD}}
|
| Classifies the material as wood, allowing its use for carpenters and storage in wood stockpiles. Entities opposed to killing plants (i.e. [[Elf|Elves]]) will refuse to accept these items in trade.

|-
| {{text_anchor|THREAD_PLANT}}
|
| Classifies the material as plant fiber, allowing its use for clothiers and storage in cloth stockpiles under "Thread (Plant)" and "Cloth (Plant)".

|-
| {{text_anchor|TOOTH}}
|
| Classifies the material as tooth, allowing its use for bone carvers and restriction from stockpiles by material.

|-
| {{text_anchor|HORN}}
|
| Classifies the material as horn, allowing its use for bone carvers and restriction from stockpiles by material.

|-
| {{text_anchor|PEARL}}
|
| Classifies the material as pearl, allowing its use for bone carvers and restriction from stockpiles by material.

|-
| {{text_anchor|SHELL}}
|
| Classifies the material as shell, allowing its use for bone carvers and restriction from stockpiles by material.

|-
| {{text_anchor|LEATHER}}
|
| Classifies the material as leather, allowing its use for leatherworkers and storage in leather stockpiles.

|-
| {{text_anchor|SILK}}
|
| Classifies the material as silk, allowing its use for clothiers and storage in cloth stockpiles under "Thread (Silk)" and "Cloth (Silk)".

|-
| {{text_anchor|SOAP}}
|
| Classifies the material as soap, allowing it to be used as a bath detergent and stored in bar/block stockpiles under "Bars: Other Materials".{{verify}}

|-
| {{text_anchor|GENERATES_MIASMA}}
|
| Material generates miasma when it rots.

|-
| {{text_anchor|MEAT}}
|
| Classifies the material as edible meat.{{verify}}

|-
| {{text_anchor|ROTS}}
|
| Material will rot if not stockpiled appropriately. Currently only affects [[food]] and [[refuse]], other items made of this material will not rot.

|-
| {{text_anchor|BLOOD_MAP_DESCRIPTOR}}
|
| Tells the game to classify contaminants of this material as being "blood" in Adventurer mode tile descriptions ("Here we have a Dwarf in a slurry of blood.").

|-
| {{text_anchor|ICHOR_MAP_DESCRIPTOR}}
|
| Tells the game to classify contaminants of this material as being "ichor".

|-
| {{text_anchor|GOO_MAP_DESCRIPTOR}}
|
| Tells the game to classify contaminants of this material as being "goo".

|-
| {{text_anchor|SLIME_MAP_DESCRIPTOR}}
|
| Tells the game to classify contaminants of this material as being "slime".

|-
| {{text_anchor|PUS_MAP_DESCRIPTOR}}
|
| Tells the game to classify contaminants of this material as being "pus".

|-
| {{text_anchor|SWEAT_MAP_DESCRIPTOR}}
|
| Tells the game to classify contaminants of this material as being "sweat".

|-
| {{text_anchor|TEARS_MAP_DESCRIPTOR}}
|
| Tells the game to classify contaminants of this material as being "tears".

|-
| {{text_anchor|SPIT_MAP_DESCRIPTOR}}
|
| Tells the game to classify contaminants of this material as being "spit".

|-
| {{text_anchor|EVAPORATES}}
|
| Contaminants composed of this material evaporate over time, slowly disappearing from the map. Used internally by water.

|-
| {{text_anchor|ENTERS_BLOOD}}
|
| Used for materials which cause [[syndrome]]s, causes it to enter the creature's blood instead of simply spattering on the surface.

|-
| {{text_anchor|EDIBLE_VERMIN}}
|
| Can be eaten by vermin.

|-
| {{text_anchor|EDIBLE_RAW}}
|
| Can be eaten raw.

|-
| {{text_anchor|EDIBLE_COOKED}}
|
| Can be cooked and then eaten.

|-
| {{text_anchor|DO_NOT_CLEAN_GLOB}}
|
| Prevents globs made of this material from being cleaned up and destroyed.

|-
| {{text_anchor|NO_STONE_STOCKPILE}}
|
| Prevents the material from showing up in Stone stockpile settings.

|-
| {{text_anchor|ITEMS_METAL}}
|
| Allows the creation of metal furniture at the metalsmith's forge.

|-
| {{text_anchor|ITEMS_BARRED}}
|
| Equivalent to ITEMS_HARD. Given to [[bone]].

|-
| {{text_anchor|ITEMS_SCALED}}
|
| Equivalent to ITEMS_HARD. Given to [[shell]].

|-
| {{text_anchor|ITEMS_LEATHER}}
|
| Equivalent to ITEMS_SOFT. Given to [[leather]].

|-
| {{text_anchor|ITEMS_SOFT}}
|
| Random [[finished goods|crafts]] made from this material cannot be made into rings, crowns, scepters or figurines. Given to [[plant fiber]], [[silk]] and [[wool]].

|-
| {{text_anchor|ITEMS_HARD}}
|
| Random [[finished goods|crafts]] made from this material include all seven items. Given to [[stone]], [[wood]], [[bone]], [[shell]], [[chitin]], [[nail|claws]], [[tooth|teeth]], [[horn|horns]], [[horn|hooves]] and [[wax|beeswax]]. [[Hair]], [[pearl|pearls]] and eggshells also have the tag.

|-
| {{text_anchor|IS_STONE}}
|
| Used to define that the material is a stone. Allows its usage in [[masonry]] and [[stonecrafting]] and storage in stone stockpiles, among other effects.

|-
| {{text_anchor|UNDIGGABLE}}
|
| Used for a stone that cannot be dug into.

|-
| {{text_anchor|DISPLAY_UNGLAZED}}
|
| Causes containers made of this material to be prefixed with "unglazed" if they have not yet been [[glaze]]d.

|-
| {{text_anchor|YARN}}
|
| Classifies the material as yarn, allowing its use for clothiers and its storage in cloth stockpiles under "Thread (Yarn)" and "Cloth (Yarn)".

|-
| {{text_anchor|STOCKPILE_THREAD_METAL}}
|
| Classifies the material as metal thread, permitting thread and cloth to be stored in cloth stockpiles under "Thread (Metal)" and "Cloth (Metal)".

|-
| {{text_anchor|IS_METAL}}
|
| Defines the material as being metal, allowing it to be used at forges.

|-
| {{text_anchor|IS_GLASS}}
|
| Used internally by green glass, clear glass, and crystal glass.

|-
| {{text_anchor|CRYSTAL_GLASSABLE}}
|
| Can be used in the production of crystal glass.

|-
| {{text_anchor|ITEMS_WEAPON}}
|
| Melee [[Weapon#Manufactured weapons|weapons]] can be made out of this material.

|-
| {{text_anchor|ITEMS_WEAPON_RANGED}}
|
| Ranged weapons can be made out of this material.

|-
| {{text_anchor|ITEMS_ANVIL}}
|
| [[Anvil]]s can be made out of this material.

|-
| {{text_anchor|ITEMS_AMMO}}
|
| [[Weapon#Ammunition|Ammunition]] can be made out of this material.

|-
| {{text_anchor|ITEMS_DIGGER}}
|
| [[Weapon#Dwarf-manufactured weapons|Picks]] can be made out of this material.

|-
| {{text_anchor|ITEMS_ARMOR}}
|
| [[Armor]] can be made out of this material.

|-
| {{text_anchor|ITEMS_DELICATE}}
|
| Used internally by amber and coral. Functionally equivalent to ITEMS_HARD.

|-
| {{text_anchor|ITEMS_SIEGE_ENGINE}}
|
| Siege engine parts can be made out of this material. Does not appear to work.

|-
| {{text_anchor|ITEMS_QUERN}}
|
| Querns and millstones can be made out of this material.{{verify}}
|}

==Syndrome tokens==
Below is a table with some of the tokens you can use when declaring a [SYNDROME] token. For all the tokens you can use, see the [[Syndrome token]] page.

{| {{prettytable}}
|- bgcolor="#C0C0C0"
! Token
! Arguments
! Description

|-
| {{text_anchor|SYN_NAME
|
* text
| Defines the name of the syndrome

|-
| {{text_anchor|SYN_INJECTED}}
|
| Syndrome can be contracted by injection (by a creature)

|-
| {{text_anchor|SYN_CONTACT}}
|
| Syndrome can be contracted on contact (e.g. poison dust or liquid)

|-
| {{text_anchor|SYN_INHALED}}
|
| Syndrome can be contracted by inhalation (e.g. poison vapor or gas)

|-
| {{text_anchor|SYN_INGESTED}}
|
| Syndrome can be contracted by ingestion (when the material is eaten in solid or liquid form)

|-
| {{text_anchor|SYN_AFFECTED_CLASS}}
|
* creature class name
| Adds a class of creatures to those affected, such as CREATURE_CLASS:GENERAL_POISON

|-
| {{text_anchor|SYN_IMMUNE_CLASS}}
|
* creature class name
| Makes the class of creatures immune to the syndrome

|-
| {{text_anchor|SYN_AFFECTED_CREATURE}}
|
* creature name
* caste name or ALL
| Adds a specific creature to those affected.

|-
| {{text_anchor|SYN_IMMUNE_CREATURE}}
|
* creature name
* caste name or ALL
| Makes the creature immune to the syndrome

|-
| CE_PAIN CE_SWELLING CE_OOZING CE_BRUISING CE_BLISTERS CE_NUMBNESS CE_PARALYSIS CE_FEVER CE_BLEEDING CE_COUGH_BLOOD CE_VOMIT_BLOOD CE_NAUSEA CE_UNCONSCIOUSNESS CE_NECROSIS CE_IMPAIR_FUNCTION CE_DROWSINESS CE_DIZZINESS
|
*SEV:<value> (severity, higher is worse)
*PROB:<value(1-100)> (probability)
*RESISTABLE (optional) allows resistance
*SIZE_DILUTES (optional) lessens effect based on size
Place affected:
*LOCALIZED (optional)
*VASCULAR_ONLY (optional)
*MUSCULAR_ONLY (optional)
*BP:BY_CATEGORY:category:tissue (optional)
*BP:BY_TYPE:type:tissue (optional)
*BP:BY_TOKEN:token:tissue (optional)
Timeline:
*Start:effect start time
*Peak:effect peak time
*End:effect end time
| Specifies the way that a syndrome affects a creature -- more detail can be found on the [[Syndrome#Creature effect tokens|Syndromes page]]

|}

==See also==
* [[Inorganic material definition token]]
* [[Syndrome]]
* [[Hardcoded material]]

{{Category|Modding}}
{{Category|Tokens}}
[[ru:Material definition token]]

v0.34:Material definition token

2026-04-04T01:13:51Z

Quietust: remove INORGANIC-specific tokens

{{quality|Exceptional|18:11, 28 April 2011 (UTC)}}{{av}}

The following tokens can be used in material definitions (whether for inorganics or those within plants and creatures) as well as in material templates.

==Material properties==
{| {{prettytable}}
|- bgcolor="#C0C0C0"
! Token
! Arguments
! Description

|-
| {{text_anchor|USE_MATERIAL_TEMPLATE}}
|
* <template name>
| Imports the properties of the specified preexisting material template.

|-
| {{text_anchor|PREFIX}}
|
* <prefix> or NONE
| Applies a prefix to all items made from the material. For PLANT and CREATURE materials, this defaults to the plant/creature name. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|STONE_NAME}}
|
* <name>
| Overrides the name of [[Item_token#BOULDER|BOULDER]] items (i.e. mined-out stones) made of the material (used for native copper/silver/gold/platinum to make them be called "nuggets" instead of "boulders").

|-
| {{text_anchor|IS_GEM}}
|
* <name>
* <plural>
* OVERWRITE_SOLID (optional)
| Used to indicate that said material is a gemstone - when tiles are mined out, rough gems will be yielded instead of boulders. Plural can be "STP" to automatically append an "s" to the singular form, and OVERWRITE_SOLID will override the relevant STATE_NAME and STATE_ADJ values.

|-
| {{text_anchor|TEMP_DIET_INFO}}
|
* <type>
| Specifies what the material should be treated as when drinking water contaminated by it, for generating unhappy [[thought]]s. Valid values are BLOOD, SLIME, VOMIT, ICHOR, PUS, GOO, GRIME, and FILTH.

|-
| {{text_anchor|POWDER_DYE}}
|
*<[[Color#Color_tokens|color token]]>
| Allows the material to be used as [[dye]], and defines color of dyed items.

|-
| {{text_anchor|TILE}}
|
*<[[Main:Character table|tile value or character]]>
| Specifies the tile that will be used to represent unmined tiles made of this material. Generally only used with stones. Defaults to 219 ('█').

|-
| {{text_anchor|ITEM_SYMBOL}}
|
*<[[Main:Character table|tile value or character]]>
| Specifies the tile that will be used to represent [[Item_token#BOULDER|BOULDER]] items made of this material. Generally only used with stones. Defaults to 7 ('•').

|-
| {{text_anchor|DISPLAY_COLOR}}
|
*<[[Color#Color_values|foreground color]]>
*<[[Color#Color_values|background color]]>
*<[[Color#Color_values|foreground brightness]]>
| The on-screen color of the material. Uses a standard 3-digit [[Color|color token]]. Equivalent to [TILE_COLOR:a:b:c], [BUILD_COLOR:b:a:X] (X = 1 if 'a' equals 'b', 0 otherwise), and [BASIC_COLOR:a:c]

|-
| {{text_anchor|BUILD_COLOR}}
|
*<[[Color#Color_values|foreground color]]>
*<[[Color#Color_values|background color]]>
*<[[Color#Color_values|foreground brightness]]>
| The color of objects made of this material which use both the foreground and background color: [[door]]s, [[floodgate]]s, [[hatch cover]]s, [[bin]]s, [[barrel]]s, and [[cage]]s. Defaults to 7:7:1 (white).

|-
| {{text_anchor|TILE_COLOR}}
|
*<[[Color#Color_values|foreground color]]>
*<[[Color#Color_values|background color]]>
*<[[Color#Color_values|foreground brightness]]>
| The color of unmined tiles containing this material (for stone and soil), as well as [[engraving]]s in this material. Defaults to 7:7:1 (white).

|-
| {{text_anchor|BASIC_COLOR}}
|
*<[[Color#Color_values|foreground color]]>
*<[[Color#Color_values|foreground brightness]]>
| The color of objects made of this material which use only the foreground color, including workshops, floors and boulders, and smoothed walls. Defaults to 7:1 (white).

|-
| {{text_anchor|STATE_COLOR}}
|
*<[[Material_definition_token#Material States|material state]]>
*<[[Color#Color_tokens|color token]]>
| Determines the color of the material at the specified state. See [[Material_definition_token#Material states|below]] for a list of valid material states. Color comes from descriptor_color_standard.txt. The nearest color value is used to display contaminants and body parts made of this material. Example:
[STATE_COLOR:ALL_SOLID:GRAY]

|-
| {{text_anchor|STATE_NAME}}
|
*<[[Material_definition_token#Material States|material state]]>
*<name>
| Determines the name of the material at the specified state, as displayed in-game.
[STATE_NAME:ALL_SOLID:stone]

|-
| {{text_anchor|STATE_ADJ}}
|
*<[[Material_definition_token#Material States|material state]]>
*<adjective>
| Like [[Material_definition_token#STATE_NAME|STATE_NAME]], but used in different situations. Equipment made from the material uses the state adjective and not the state name.

|-
| {{text_anchor|STATE_NAME_ADJ}}
|
*<[[Material_definition_token#Material States|material state]]>
*<name>
*<adjective>
| Sets both [[Material_definition_token#STATE_NAME|STATE_NAME]] and [[Material_definition_token#STATE_ADJ|STATE_ADJ]] at the same time.

|-
| {{text_anchor|ABSORPTION}}
|
*<value>
| The material's tendency to absorb liquids. Containers made of materials with nonzero absorption cannot hold liquids unless they have been [[glaze]]d. Defaults to 0.

|-
| {{text_anchor|IMPACT_YIELD}}
|
*<value>
| Specifies how hard of an impact (in kilopascals) the material can withstand before it will start deforming permanently. Used for blunt-force combat. Defaults to 10000.

|-
| {{text_anchor|IMPACT_FRACTURE}}
|
*<value>
| Specifies how hard of an impact the material can withstand before it will fail entirely. Used for blunt-force combat. Defaults to 10000.

|-
| {{text_anchor|IMPACT_STRAIN_AT_YIELD}} or {{text_anchor|IMPACT_ELASTICITY}}
|
*<value>
| Specifies how much the material will have given (in parts-per-100000) when the yield point is reached. Used for blunt-force combat. Defaults to 0. Apparently affects in combat whether the corresponding tissue is bruised (value >= 50000), torn (value between 25000 and 49999), or fractured (value <= 24999)

|-
| {{text_anchor|COMPRESSIVE_YIELD}}
|
*<value>
| Specifies how hard the material can be compressed before it will start deforming permanently. Determines a tissue's resistance to pinching and response to strangulation. Defaults to 10000.

|-
| {{text_anchor|COMPRESSIVE_FRACTURE}}
|
*<value>
| Specifies how hard the material can be compressed before it will fail entirely. Determines a tissue's resistance to pinching and response to strangulation. Defaults to 10000.

|-
| {{text_anchor|COMPRESSIVE_STRAIN_AT_YIELD}} or {{text_anchor|COMPRESSIVE_ELASTICITY}}
|
*<value>
| Specifies how much the material will have given when it has been compressed to its yield point. Determines a tissue's resistance to pinching and response to strangulation. Defaults to 0.

|-
| {{text_anchor|TENSILE_YIELD}}
|
*<value>
| Specifies how hard the material can be stretched before it will start deforming permanently. Determines a tissue's resistance to a latching and tearing bite. Defaults to 10000.

|-
| {{text_anchor|TENSILE_FRACTURE}}
|
*<value>
| Specifies how hard the material can be stretched before it will fail entirely. Determines a tissue's resistance to a latching and tearing bite. Defaults to 10000.

|-
| {{text_anchor|TENSILE_STRAIN_AT_YIELD}} or {{text_anchor|TENSILE_ELASTICITY}}
|
*<value>
| Specifies how much the material will have given when it is stretched to its yield point. Determines a tissue's resistance to a latching and tearing bite. Defaults to 0.

|-
| {{text_anchor|TORSION_YIELD}}
|
*<value>
| Specifies how hard the material can be twisted before it will start deforming permanently. Used for latching and shaking with a blunt attack (no default creature has such an attack, but they can be modded in). Defaults to 10000.

|-
| {{text_anchor|TORSION_FRACTURE}}
|
*<value>
| Specifies how hard the material can be twisted before it will fail entirely. Used for latching and shaking with a blunt attack (no default creature has such an attack, but they can be modded in). Defaults to 10000.

|-
| {{text_anchor|TORSION_STRAIN_AT_YIELD}} or {{text_anchor|TORSION_ELASTICITY}}
|
*<value>
| Specifies how much the material will have given when it is twisted to its yield point. Used for latching and shaking with a blunt attack (no default creature has such an attack, but they can be modded in). Defaults to 0.

|-
| {{text_anchor|SHEAR_YIELD}}
|
*<value>
| Specifies how hard the material can be sheared before it will start deforming permanently. Used for cutting calculations. Defaults to 10000.

|-
| {{text_anchor|SHEAR_FRACTURE}}
|
*<value>
| Specifies how hard the material can be sheared before it will fail entirely. Used for cutting calculations. Defaults to 10000.

|-
| {{text_anchor|SHEAR_STRAIN_AT_YIELD}} or {{text_anchor|SHEAR_ELASTICITY}}
|
*<value>
| Specifies how much the material will have given when sheared to its yield point. Used for cutting calculations. Defaults to 0.

|-
| {{text_anchor|BENDING_YIELD}}
|
*<value>
| Specifies how hard the material can be bent before it will start deforming permanently. Determines a tissue's resistance to being mangled with a joint lock. Defaults to 10000.

|-
| {{text_anchor|BENDING_FRACTURE}}
|
*<value>
| Specifies how hard the material can be bent before it will fail entirely. Determines a tissue's resistance to being mangled with a joint lock. Defaults to 10000.

|-
| {{text_anchor|BENDING_STRAIN_AT_YIELD}} or {{text_anchor|BENDING_ELASTICITY}}
|
*<value>
| Specifies how much the material will have given when bent to its yield point. Determines a tissue's resistance to being mangled with a joint lock. Defaults to 0.

|-
| {{text_anchor|MAX_EDGE}}
|
*<value>
| How sharp the material is. Used in cutting calculations. Does not allow an inferior metal to penetrate superior armor. Applying a value of at least 10000 to a stone will allow weapons to be made from that stone. Defaults to 10000.

|-
| {{text_anchor|MATERIAL_VALUE}}
|
*<value>
| Value modifier for the material. Defaults to 1. This number can be made negative by placing a "-" in front, resulting in things that you are paid to buy and must pay to sell.

|-
| {{text_anchor|MULTIPLY_VALUE}}
|
*<value>
| Multiplies the value of the material. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|SPEC_HEAT}}
|
*<specific heat capacity>
| Rate at which the material heats up or cools down (in joules/kilogram-kelvin). If set to NONE, the temperature will be fixed at its initial value. See [[Temperature]] for more information. Defaults to NONE.

|-
| {{text_anchor|HEATDAM_POINT}}
|
*<temperature>
| Temperature above which the material takes damage from heat. May be set to NONE. If the material has an ignite point but no heatdam point, it will burn for a very long time (9 months and 16.8 days). Defaults to NONE.

|-
| {{text_anchor|COLDDAM_POINT}}
|
*<temperature>
| Temperature below which the material takes damage from cold. Defaults to NONE.

|-
| {{text_anchor|IGNITE_POINT}}
|
*<temperature>
| Temperature at which the material will catch fire. Defaults to NONE.

|-
| {{text_anchor|MELTING_POINT}}
|
*<temperature>
| Temperature at which the material melts. Defaults to NONE.

|-
| {{text_anchor|BOILING_POINT}}
|
*<temperature>
| Temperature at which the material boils. Defaults to NONE.

|-
| {{text_anchor|MAT_FIXED_TEMP}}
|
*<temperature>
| Items composed of this material will initially have this temperature. Used in conjunction with <code>[SPEC_HEAT:NONE]</code> to make material's temperature fixed at the specified value. Defaults to NONE.

|-
| {{text_anchor|IF_EXISTS_SET_HEATDAM_POINT}}
|
*<temperature>
| Changes a material's HEATDAM_POINT, but only if it was not set to NONE. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|IF_EXISTS_SET_COLDDAM_POINT}}
|
*<temperature>
| Changes a material's COLDDAM_POINT, but only if it was not set to NONE. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|IF_EXISTS_SET_IGNITE_POINT}}
|
*<temperature>
| Changes a material's IGNITE_POINT, but only if it was not set to NONE. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|IF_EXISTS_SET_MELTING_POINT}}
|
*<temperature>
| Changes a material's MELTING_POINT, but only if it was not set to NONE. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|IF_EXISTS_SET_BOILING_POINT}}
|
*<temperature>
| Changes a material's BOILING_POINT, but only if it was not set to NONE. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|IF_EXISTS_SET_MAT_FIXED_TEMP}}
|
*<temperature>
| Changes a material's MAT_FIXED_TEMP, but only if it was not set to NONE. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|SOLID_DENSITY}}
|
*<density>
| Specifies the density (in kilograms per cubic meter) of the material when in solid form. Also affects combat calculations; affects blunt-force damage and ability of edged weapons to pierce tissue layers{{verify}}. Defaults to NONE.

|-
| {{text_anchor|LIQUID_DENSITY}}
|
*<density>
| Specifies the density of the material when in liquid form. Defaults to NONE.

|-
| {{text_anchor|MOLAR_MASS}}
|
*<value>
| Supposedly not used{{verify}}. Theoretically, should determine density (at given pressure) in gas state, on which in turn would depend (together with weight of vaporized material) on the volume covered by spreading vapors. Defaults to NONE.

|-
| {{text_anchor|EXTRACT_STORAGE}}
| * BARREL or FLASK
| Specifies the type of container used to store the material. Used in conjunction with the [EXTRACT_BARREL], [EXTRACT_VIAL], or [EXTRACT_STILL_VIAL] [[plant token]]s. Defaults to BARREL.

|-
| {{text_anchor|BUTCHER_SPECIAL}}
|
*<[[item token]]>
| Specifies the item type used for butchering results made of this material. Stock raws use GLOB:NONE for fat and MEAT:NONE for other meat materials.

|-
| {{text_anchor|MEAT_NAME}}
|
*<prefix>
*<name>
*<adjective>
| When a creature is butchered, meat yielded from organs made from this material will be named via this token. If this token is not specified, meat objects will be called "chops" instead.

|-
| {{text_anchor|BLOCK_NAME}}
|
*<singular>
*<plural>
| Specifies the name of [[block]]s made from this material.

|-
| {{text_anchor|MATERIAL_REACTION_PRODUCT}}
|
*<reaction reference>
*<[[material token]]>
| Used with reaction raws to associate a reagent material with a product material. The first argument is used by HAS_MATERIAL_REACTION_PRODUCT and GET_MATERIAL_FROM_REAGENT in reaction raws. The remainder is a material reference, generally LOCAL_CREATURE_MAT:SUBTYPE or LOCAL_PLANT_MAT:SUBTYPE or INORGANIC:STONETYPE.
[MATERIAL_REACTION_PRODUCT:TAN_MAT:LOCAL_CREATURE_MAT:LEATHER]

|-
| {{text_anchor|REACTION_CLASS}}
|
*<reaction class name>
| Used to classify all items made of the material, so that reactions can use them as generic reagents.
In default raws, the following are used:
* FAT, TALLOW, SOAP, MILK, CHEESE, WAX
* CAN_GLAZE - items made from this material can be glazed.
* FLUX - can be used as [[flux]] in pig iron and steel making.
* GYPSUM - can be processed into [[gypsum plaster]].

|-
| {{text_anchor|HARDENS_WITH_WATER}}
|
* <[[material token]]>
| Allows the material to be used to make [[healthcare|casts]].

|-
| {{text_anchor|SOAP_LEVEL}}
|
*<value>
| [[Soap]] has [SOAP_LEVEL:2]. Effects unknown. Defaults to 0.

|-
| {{text_anchor|SYNDROME}}
|
| Begins defining a [[syndrome]] applied by the material. Multiple syndromes can be specified. See [[Syndrome token]].
|}

===Material states===

The following is a list of valid material states:

{| {{prettytable}}
|-
|'''SOLID'''
|-
|'''LIQUID'''
|-
|'''GAS'''
|-
|'''POWDER''' (or '''SOLID_POWDER''')
|-
|'''PASTE''' (or '''SOLID_PASTE''')
|-
|'''PRESSED''' (or '''SOLID_PRESSED''')
|}

The following can be specified within tokens such as [[Material_definition_token#STATE_NAME|STATE_NAME]], [[Material_definition_token#STATE_NAME_ADJ|STATE_NAME_ADJ]] and [[Material_definition_token#STATE_ADJ|STATE_ADJ]] to make them apply to several of the above material states simultaneously:

{| {{prettytable}}
|- bgcolor="#C0C0C0"
!Value
!Description
|-
|'''ALL'''
|Denotes all possible material states.
|-
|'''ALL_SOLID'''
|Denotes 'SOLID', 'POWDER', 'PASTE' and 'PRESSED'.
|}

==Material usage tokens==
{| {{prettytable}}
|- bgcolor="#C0C0C0"
! Token
! Arguments
! Description

|-
| {{text_anchor|IMPLIES_ANIMAL_KILL}}
|
| Lets the game know that an animal was likely killed in the production of this item. Entities opposed to killing animals (which currently does '''not''' include [[elf|Elves]]) will refuse to accept these items in trade.

|-
| {{text_anchor|ALCOHOL_PLANT}}
|
| Classifies the material as plant-based alcohol, allowing its storage in food stockpiles under "Drink (Plant)".

|-
| {{text_anchor|ALCOHOL_CREATURE}}
|
| Classifies the material as animal-based alcohol, allowing its storage in food stockpiles under "Drink (Animal)".

|-
| {{text_anchor|ALCOHOL}}
|
| Classifies the material as generic alcohol. Implied by both ALCOHOL_PLANT and ALCOHOL_CREATURE. Exact behavior unknown, possibly vestigial.

|-
| {{text_anchor|CHEESE_PLANT}}
|
| Classifies the material as plant-based cheese, allowing its storage in food stockpiles under "Cheese (Plant)".

|-
| {{text_anchor|CHEESE_CREATURE}}
|
| Classifies the material as animal-based cheese, allowing its storage in food stockpiles under "Cheese (Animal)".

|-
| {{text_anchor|CHEESE}}
|
| Classifies the material as generic cheese. Implied by both CHEESE_PLANT and CHEESE_CREATURE. Exact behavior unknown, possibly vestigial.

|-
| {{text_anchor|POWDER_MISC_PLANT}}
|
| Classifies the material as plant powder, allowing its storage in food stockpiles under "Milled Plant".

|-
| {{text_anchor|POWDER_MISC_CREATURE}}
|
| Classifies the material as creature powder, allowing its storage in food stockpiles under "Bone Meal". Unlike milled plants, such as sugar and flour, "Bone Meal" barrels or pots may not contain bags. Custom reactions using this product better use buckets or jugs instead.

|-
| {{text_anchor|POWDER_MISC}}
|
| Classifies the material as generic powder. Implied by both POWDER_MISC_PLANT and POWDER_MISC_CREATURE. Exact behavior unknown, possibly vestigial.

|-
| {{text_anchor|STOCKPILE_GLOB}} or {{text_anchor|STOCKPILE_GLOB_SOLID}}
|
| Permits globs of the material in solid form to be stored in food stockpiles under "Fat" - without it, dwarves will come by and "clean" the items, destroying them (unless [DO_NOT_CLEAN_GLOB] is also included).

|-
| {{text_anchor|STOCKPILE_GLOB_PASTE}}
|
| Classifies the material as milled paste, allowing its storage in food stockpiles under "Paste".

|-
| {{text_anchor|STOCKPILE_GLOB_PRESSED}}
|
| Classifies the material as pressed goods, allowing its storage in food stockpiles under "Pressed Material".

|-
| {{text_anchor|LIQUID_MISC_PLANT}}
|
| Classifies the material as a plant extract, allowing its storage in food stockpiles under "Extract (Plant)".

|-
| {{text_anchor|LIQUID_MISC_CREATURE}}
|
| Classifies the material as a creature extract, allowing its storage in food stockpiles under "Extract (Animal)".

|-
| {{text_anchor|LIQUID_MISC_OTHER}}
|
| Classifies the material as a miscellaneous liquid, allowing its storage in food stockpiles under "Misc. Liquid" along with lye.

|-
| {{text_anchor|LIQUID_MISC}}
|
| Classifies the material as a generic liquid. Implied by LIQUID_MISC_PLANT, LIQUID_MISC_CREATURE, and LIQUID_MISC_OTHER. Exact behavior unknown, possibly vestigial.

|-
| {{text_anchor|STRUCTURAL_PLANT_MAT}}
|
| Classifies the material as a plant, allowing its storage in food stockpiles under "Plants".

|-
| {{text_anchor|SEED_MAT}}
|
| Classifies the material as a plant seed, allowing its storage in food stockpiles under "Seeds".

|-
| {{text_anchor|LEAF_MAT}}
|
| Classifies the material as plant leaf, allowing its storage in food stockpiles under "Leaves".

|-
| {{text_anchor|BONE}}
|
| Classifies the material as bone, allowing its use for bone carvers and restriction from stockpiles by material.

|-
| {{text_anchor|WOOD}}
|
| Classifies the material as wood, allowing its use for carpenters and storage in wood stockpiles. Entities opposed to killing plants (i.e. [[Elf|Elves]]) will refuse to accept these items in trade.

|-
| {{text_anchor|THREAD_PLANT}}
|
| Classifies the material as plant fiber, allowing its use for clothiers and storage in cloth stockpiles under "Thread (Plant)" and "Cloth (Plant)".

|-
| {{text_anchor|TOOTH}}
|
| Classifies the material as tooth, allowing its use for bone carvers and restriction from stockpiles by material.

|-
| {{text_anchor|HORN}}
|
| Classifies the material as horn, allowing its use for bone carvers and restriction from stockpiles by material.

|-
| {{text_anchor|PEARL}}
|
| Classifies the material as pearl, allowing its use for bone carvers and restriction from stockpiles by material.

|-
| {{text_anchor|SHELL}}
|
| Classifies the material as shell, allowing its use for bone carvers and restriction from stockpiles by material.

|-
| {{text_anchor|LEATHER}}
|
| Classifies the material as leather, allowing its use for leatherworkers and storage in leather stockpiles.

|-
| {{text_anchor|SILK}}
|
| Classifies the material as silk, allowing its use for clothiers and storage in cloth stockpiles under "Thread (Silk)" and "Cloth (Silk)".

|-
| {{text_anchor|SOAP}}
|
| Classifies the material as soap, allowing it to be used as a bath detergent and stored in bar/block stockpiles under "Bars: Other Materials".{{verify}}

|-
| {{text_anchor|GENERATES_MIASMA}}
|
| Material generates miasma when it rots.

|-
| {{text_anchor|MEAT}}
|
| Classifies the material as edible meat.{{verify}}

|-
| {{text_anchor|ROTS}}
|
| Material will rot if not stockpiled appropriately. Currently only affects [[food]] and [[refuse]], other items made of this material will not rot.

|-
| {{text_anchor|BLOOD_MAP_DESCRIPTOR}}
|
| Tells the game to classify contaminants of this material as being "blood" in Adventurer mode tile descriptions ("Here we have a Dwarf in a slurry of blood.").

|-
| {{text_anchor|ICHOR_MAP_DESCRIPTOR}}
|
| Tells the game to classify contaminants of this material as being "ichor".

|-
| {{text_anchor|GOO_MAP_DESCRIPTOR}}
|
| Tells the game to classify contaminants of this material as being "goo".

|-
| {{text_anchor|SLIME_MAP_DESCRIPTOR}}
|
| Tells the game to classify contaminants of this material as being "slime".

|-
| {{text_anchor|PUS_MAP_DESCRIPTOR}}
|
| Tells the game to classify contaminants of this material as being "pus".

|-
| {{text_anchor|ENTERS_BLOOD}}
|
| Used for materials which cause [[syndrome]]s, causes it to enter the creature's blood instead of simply spattering on the surface.

|-
| {{text_anchor|EDIBLE_VERMIN}}
|
| Can be eaten by vermin.

|-
| {{text_anchor|EDIBLE_RAW}}
|
| Can be eaten raw.

|-
| {{text_anchor|EDIBLE_COOKED}}
|
| Can be cooked and then eaten.

|-
| {{text_anchor|DO_NOT_CLEAN_GLOB}}
|
| Prevents globs made of this material from being cleaned up and destroyed.

|-
| {{text_anchor|NO_STONE_STOCKPILE}}
|
| Prevents the material from showing up in Stone stockpile settings.

|-
| {{text_anchor|ITEMS_METAL}}
|
| Allows the creation of metal furniture at the metalsmith's forge.

|-
| {{text_anchor|ITEMS_BARRED}}
|
| Equivalent to ITEMS_HARD. Given to [[bone]].

|-
| {{text_anchor|ITEMS_SCALED}}
|
| Equivalent to ITEMS_HARD. Given to [[shell]].

|-
| {{text_anchor|ITEMS_LEATHER}}
|
| Equivalent to ITEMS_SOFT. Given to [[leather]].

|-
| {{text_anchor|ITEMS_SOFT}}
|
| Random [[finished goods|crafts]] made from this material cannot be made into rings, crowns, scepters or figurines. Given to [[plant fiber]], [[silk]] and [[wool]].

|-
| {{text_anchor|ITEMS_HARD}}
|
| Random [[finished goods|crafts]] made from this material include all seven items. Given to [[stone]], [[wood]], [[bone]], [[shell]], [[chitin]], [[nail|claws]], [[tooth|teeth]], [[horn|horns]], [[horn|hooves]] and [[wax|beeswax]]. [[Hair]], [[pearl|pearls]] and eggshells also have the tag.

|-
| {{text_anchor|IS_STONE}}
|
| Used to define that the material is a stone. Allows its usage in [[masonry]] and [[stonecrafting]] and storage in stone stockpiles, among other effects.

|-
| {{text_anchor|UNDIGGABLE}}
|
| Used for a stone that cannot be dug into.

|-
| {{text_anchor|DISPLAY_UNGLAZED}}
|
| Causes containers made of this material to be prefixed with "unglazed" if they have not yet been [[glaze]]d.

|-
| {{text_anchor|YARN}}
|
| Classifies the material as yarn, allowing its use for clothiers and its storage in cloth stockpiles under "Thread (Yarn)" and "Cloth (Yarn)".

|-
| {{text_anchor|STOCKPILE_THREAD_METAL}}
|
| Classifies the material as metal thread, permitting thread and cloth to be stored in cloth stockpiles under "Thread (Metal)" and "Cloth (Metal)".

|-
| {{text_anchor|IS_METAL}}
|
| Defines the material as being metal, allowing it to be used at forges.

|-
| {{text_anchor|IS_GLASS}}
|
| Used internally by green glass, clear glass, and crystal glass.

|-
| {{text_anchor|CRYSTAL_GLASSABLE}}
|
| Can be used in the production of crystal glass.

|-
| {{text_anchor|ITEMS_WEAPON}}
|
| Melee [[Weapon#Manufactured weapons|weapons]] can be made out of this material.

|-
| {{text_anchor|ITEMS_WEAPON_RANGED}}
|
| Ranged weapons can be made out of this material.

|-
| {{text_anchor|ITEMS_ANVIL}}
|
| [[Anvil]]s can be made out of this material.

|-
| {{text_anchor|ITEMS_AMMO}}
|
| [[Weapon#Ammunition|Ammunition]] can be made out of this material.

|-
| {{text_anchor|ITEMS_DIGGER}}
|
| [[Weapon#Dwarf-manufactured weapons|Picks]] can be made out of this material.

|-
| {{text_anchor|ITEMS_ARMOR}}
|
| [[Armor]] can be made out of this material.

|-
| {{text_anchor|ITEMS_DELICATE}}
|
| Used internally by amber and coral. Functionally equivalent to ITEMS_HARD.

|-
| {{text_anchor|ITEMS_SIEGE_ENGINE}}
|
| Siege engine parts can be made out of this material. Does not appear to work.

|-
| {{text_anchor|ITEMS_QUERN}}
|
| Querns and millstones can be made out of this material.{{verify}}
|}

==Syndrome tokens==
Below is a table with some of the tokens you can use when declaring a [SYNDROME] token. For all the tokens you can use, see the [[Syndrome token]] page.

{| {{prettytable}}
|- bgcolor="#C0C0C0"
! Token
! Arguments
! Description

|-
| {{text_anchor|SYN_NAME
|
* text
| Defines the name of the syndrome

|-
| {{text_anchor|SYN_INJECTED}}
|
| Syndrome can be contracted by injection (by a creature)

|-
| {{text_anchor|SYN_CONTACT}}
|
| Syndrome can be contracted on contact (e.g. poison dust or liquid)

|-
| {{text_anchor|SYN_INHALED}}
|
| Syndrome can be contracted by inhalation (e.g. poison vapor or gas)

|-
| {{text_anchor|SYN_AFFECTED_CLASS}}
|
* creature class name
| Adds a class of creatures to those affected, such as CREATURE_CLASS:GENERAL_POISON

|-
| {{text_anchor|SYN_IMMUNE_CLASS}}
|
* creature class name
| Makes the class of creatures immune to the syndrome

|-
| {{text_anchor|SYN_AFFECTED_CREATURE}}
|
* creature name
* caste name or ALL
| Adds a specific creature to those affected.

|-
| {{text_anchor|SYN_IMMUNE_CREATURE}}
|
* creature name
* caste name or ALL
| Makes the creature immune to the syndrome

|-
| CE_PAIN CE_SWELLING CE_OOZING CE_BRUISING CE_BLISTERS CE_NUMBNESS CE_PARALYSIS CE_FEVER CE_BLEEDING CE_COUGH_BLOOD CE_VOMIT_BLOOD CE_NAUSEA CE_UNCONSCIOUSNESS CE_NECROSIS CE_IMPAIR_FUNCTION CE_DROWSINESS CE_DIZZINESS
|
*SEV:<value> (severity, higher is worse)
*PROB:<value(1-100)> (probability)
*RESISTABLE (optional) allows resistance
*SIZE_DILUTES (optional) lessens effect based on size
Place affected:
*LOCALIZED (optional)
*VASCULAR_ONLY (optional)
*MUSCULAR_ONLY (optional)
*BP:BY_CATEGORY:category:tissue (optional)
*BP:BY_TYPE:type:tissue (optional)
*BP:BY_TOKEN:token:tissue (optional)
Timeline:
*Start:effect start time
*Peak:effect peak time
*End:effect end time
| Specifies the way that a syndrome affects a creature -- more detail can be found on the [[Syndrome#Creature effect tokens|Syndromes page]]

|}

==See Also==
* [[Inorganic material definition token]]
* [[Syndrome]]

{{Category|Modding}}
{{Category|Tokens}}

v0.31:Material definition token

2026-04-04T01:13:33Z

Quietust:

{{quality|Exceptional|18:11, 28 April 2011 (UTC)}}{{av}}

The following tokens can be used in material definitions (whether for inorganics or those within plants and creatures) as well as in material templates.

==Material properties==
{| {{prettytable}}
|- bgcolor="#C0C0C0"
! Token
! Arguments
! Description

|-
| {{text_anchor|USE_MATERIAL_TEMPLATE}}
|
* <template name>
| Imports the properties of the specified preexisting material template.

|-
| {{text_anchor|PREFIX}}
|
* <prefix> or NONE
| Applies a prefix to all items made from the material. For PLANT and CREATURE materials, this defaults to the plant/creature name. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|STONE_NAME}}
|
* <name>
| Overrides the name of [[Item_token#BOULDER|BOULDER]] items (i.e. mined-out stones) made of the material (used for native copper/silver/gold/platinum to make them be called "nuggets" instead of "boulders").

|-
| {{text_anchor|IS_GEM}}
|
* <name>
* <plural>
* OVERWRITE_SOLID (optional)
| Used to indicate that said material is a gemstone - when tiles are mined out, rough gems will be yielded instead of boulders. Plural can be "STP" to automatically append an "s" to the singular form, and OVERWRITE_SOLID will override the relevant STATE_NAME and STATE_ADJ values.

|-
| {{text_anchor|TEMP_DIET_INFO}}
|
* <type>
| Specifies what the material should be treated as when drinking water contaminated by it, for generating unhappy [[thought]]s. Valid values are BLOOD, SLIME, VOMIT, ICHOR, PUS, GOO, GRIME, and FILTH.

|-
| {{text_anchor|POWDER_DYE}}
|
*<[[Color#Color_tokens|color token]]>
| Allows the material to be used as [[dye]], and defines color of dyed items.

|-
| {{text_anchor|TILE}}
|
*<[[Main:Character table|tile value or character]]>
| Specifies the tile that will be used to represent unmined tiles made of this material. Generally only used with stones. Defaults to 219 ('█').

|-
| {{text_anchor|ITEM_SYMBOL}}
|
*<[[Main:Character table|tile value or character]]>
| Specifies the tile that will be used to represent [[Item_token#BOULDER|BOULDER]] items made of this material. Generally only used with stones. Defaults to 7 ('•').

|-
| {{text_anchor|DISPLAY_COLOR}}
|
*<[[Color#Color_values|foreground color]]>
*<[[Color#Color_values|background color]]>
*<[[Color#Color_values|foreground brightness]]>
| The on-screen color of the material. Uses a standard 3-digit [[Color|color token]]. Equivalent to [TILE_COLOR:a:b:c], [BUILD_COLOR:b:a:X] (X = 1 if 'a' equals 'b', 0 otherwise), and [BASIC_COLOR:a:c]

|-
| {{text_anchor|BUILD_COLOR}}
|
*<[[Color#Color_values|foreground color]]>
*<[[Color#Color_values|background color]]>
*<[[Color#Color_values|foreground brightness]]>
| The color of objects made of this material which use both the foreground and background color: [[door]]s, [[floodgate]]s, [[hatch cover]]s, [[bin]]s, [[barrel]]s, and [[cage]]s. Defaults to 7:7:1 (white).

|-
| {{text_anchor|TILE_COLOR}}
|
*<[[Color#Color_values|foreground color]]>
*<[[Color#Color_values|background color]]>
*<[[Color#Color_values|foreground brightness]]>
| The color of unmined tiles containing this material (for stone and soil), as well as [[engraving]]s in this material. Defaults to 7:7:1 (white).

|-
| {{text_anchor|BASIC_COLOR}}
|
*<[[Color#Color_values|foreground color]]>
*<[[Color#Color_values|foreground brightness]]>
| The color of objects made of this material which use only the foreground color, including workshops, floors and boulders, and smoothed walls. Defaults to 7:1 (white).

|-
| {{text_anchor|STATE_COLOR}}
|
*<[[Material_definition_token#Material States|material state]]>
*<[[Color#Color_tokens|color token]]>
| Determines the color of the material at the specified state. See [[Material_definition_token#Material states|below]] for a list of valid material states. Color comes from descriptor_color_standard.txt. The nearest color value is used to display contaminants and body parts made of this material. Example:
[STATE_COLOR:ALL_SOLID:GRAY]

|-
| {{text_anchor|STATE_NAME}}
|
*<[[Material_definition_token#Material States|material state]]>
*<name>
| Determines the name of the material at the specified state, as displayed in-game.
[STATE_NAME:ALL_SOLID:stone]

|-
| {{text_anchor|STATE_ADJ}}
|
*<[[Material_definition_token#Material States|material state]]>
*<adjective>
| Like [[Material_definition_token#STATE_NAME|STATE_NAME]], but used in different situations. Equipment made from the material uses the state adjective and not the state name.

|-
| {{text_anchor|STATE_NAME_ADJ}}
|
*<[[Material_definition_token#Material States|material state]]>
*<name>
*<adjective>
| Sets both [[Material_definition_token#STATE_NAME|STATE_NAME]] and [[Material_definition_token#STATE_ADJ|STATE_ADJ]] at the same time.

|-
| {{text_anchor|ABSORPTION}}
|
*<value>
| The material's tendency to absorb liquids. Containers made of materials with nonzero absorption cannot hold liquids unless they have been [[glaze]]d. Defaults to 0.

|-
| {{text_anchor|IMPACT_YIELD}}
|
*<value>
| Specifies how hard of an impact (in kilopascals) the material can withstand before it will start deforming permanently. Used for blunt-force combat. Defaults to 10000.

|-
| {{text_anchor|IMPACT_FRACTURE}}
|
*<value>
| Specifies how hard of an impact the material can withstand before it will fail entirely. Used for blunt-force combat. Defaults to 10000.

|-
| {{text_anchor|IMPACT_STRAIN_AT_YIELD}} or {{text_anchor|IMPACT_ELASTICITY}}
|
*<value>
| Specifies how much the material will have given (in parts-per-100000) when the yield point is reached. Used for blunt-force combat. Defaults to 0. Apparently affects in combat whether the corresponding tissue is bruised (value >= 50000), torn (value between 25000 and 49999), or fractured (value <= 24999)

|-
| {{text_anchor|COMPRESSIVE_YIELD}}
|
*<value>
| Specifies how hard the material can be compressed before it will start deforming permanently. Determines a tissue's resistance to pinching and response to strangulation. Defaults to 10000.

|-
| {{text_anchor|COMPRESSIVE_FRACTURE}}
|
*<value>
| Specifies how hard the material can be compressed before it will fail entirely. Determines a tissue's resistance to pinching and response to strangulation. Defaults to 10000.

|-
| {{text_anchor|COMPRESSIVE_STRAIN_AT_YIELD}} or {{text_anchor|COMPRESSIVE_ELASTICITY}}
|
*<value>
| Specifies how much the material will have given when it has been compressed to its yield point. Determines a tissue's resistance to pinching and response to strangulation. Defaults to 0.

|-
| {{text_anchor|TENSILE_YIELD}}
|
*<value>
| Specifies how hard the material can be stretched before it will start deforming permanently. Determines a tissue's resistance to a latching and tearing bite. Defaults to 10000.

|-
| {{text_anchor|TENSILE_FRACTURE}}
|
*<value>
| Specifies how hard the material can be stretched before it will fail entirely. Determines a tissue's resistance to a latching and tearing bite. Defaults to 10000.

|-
| {{text_anchor|TENSILE_STRAIN_AT_YIELD}} or {{text_anchor|TENSILE_ELASTICITY}}
|
*<value>
| Specifies how much the material will have given when it is stretched to its yield point. Determines a tissue's resistance to a latching and tearing bite. Defaults to 0.

|-
| {{text_anchor|TORSION_YIELD}}
|
*<value>
| Specifies how hard the material can be twisted before it will start deforming permanently. Used for latching and shaking with a blunt attack (no default creature has such an attack, but they can be modded in). Defaults to 10000.

|-
| {{text_anchor|TORSION_FRACTURE}}
|
*<value>
| Specifies how hard the material can be twisted before it will fail entirely. Used for latching and shaking with a blunt attack (no default creature has such an attack, but they can be modded in). Defaults to 10000.

|-
| {{text_anchor|TORSION_STRAIN_AT_YIELD}} or {{text_anchor|TORSION_ELASTICITY}}
|
*<value>
| Specifies how much the material will have given when it is twisted to its yield point. Used for latching and shaking with a blunt attack (no default creature has such an attack, but they can be modded in). Defaults to 0.

|-
| {{text_anchor|SHEAR_YIELD}}
|
*<value>
| Specifies how hard the material can be sheared before it will start deforming permanently. Used for cutting calculations. Defaults to 10000.

|-
| {{text_anchor|SHEAR_FRACTURE}}
|
*<value>
| Specifies how hard the material can be sheared before it will fail entirely. Used for cutting calculations. Defaults to 10000.

|-
| {{text_anchor|SHEAR_STRAIN_AT_YIELD}} or {{text_anchor|SHEAR_ELASTICITY}}
|
*<value>
| Specifies how much the material will have given when sheared to its yield point. Used for cutting calculations. Defaults to 0.

|-
| {{text_anchor|BENDING_YIELD}}
|
*<value>
| Specifies how hard the material can be bent before it will start deforming permanently. Determines a tissue's resistance to being mangled with a joint lock. Defaults to 10000.

|-
| {{text_anchor|BENDING_FRACTURE}}
|
*<value>
| Specifies how hard the material can be bent before it will fail entirely. Determines a tissue's resistance to being mangled with a joint lock. Defaults to 10000.

|-
| {{text_anchor|BENDING_STRAIN_AT_YIELD}} or {{text_anchor|BENDING_ELASTICITY}}
|
*<value>
| Specifies how much the material will have given when bent to its yield point. Determines a tissue's resistance to being mangled with a joint lock. Defaults to 0.

|-
| {{text_anchor|MAX_EDGE}}
|
*<value>
| How sharp the material is. Used in cutting calculations. Does not allow an inferior metal to penetrate superior armor. Applying a value of at least 10000 to a stone will allow weapons to be made from that stone. Defaults to 10000.

|-
| {{text_anchor|MATERIAL_VALUE}}
|
*<value>
| Value modifier for the material. Defaults to 1. This number can be made negative by placing a "-" in front, resulting in things that you are paid to buy and must pay to sell.

|-
| {{text_anchor|MULTIPLY_VALUE}}
|
*<value>
| Multiplies the value of the material. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|SPEC_HEAT}}
|
*<specific heat capacity>
| Rate at which the material heats up or cools down (in joules/kilogram-kelvin). If set to NONE, the temperature will be fixed at its initial value. See [[Temperature]] for more information. Defaults to NONE.

|-
| {{text_anchor|HEATDAM_POINT}}
|
*<temperature>
| Temperature above which the material takes damage from heat. May be set to NONE. If the material has an ignite point but no heatdam point, it will burn for a very long time (9 months and 16.8 days). Defaults to NONE.

|-
| {{text_anchor|COLDDAM_POINT}}
|
*<temperature>
| Temperature below which the material takes damage from cold. Defaults to NONE.

|-
| {{text_anchor|IGNITE_POINT}}
|
*<temperature>
| Temperature at which the material will catch fire. Defaults to NONE.

|-
| {{text_anchor|MELTING_POINT}}
|
*<temperature>
| Temperature at which the material melts. Defaults to NONE.

|-
| {{text_anchor|BOILING_POINT}}
|
*<temperature>
| Temperature at which the material boils. Defaults to NONE.

|-
| {{text_anchor|MAT_FIXED_TEMP}}
|
*<temperature>
| Items composed of this material will initially have this temperature. Used in conjunction with <code>[SPEC_HEAT:NONE]</code> to make material's temperature fixed at the specified value. Defaults to NONE.

|-
| {{text_anchor|IF_EXISTS_SET_HEATDAM_POINT}}
|
*<temperature>
| Changes a material's HEATDAM_POINT, but only if it was not set to NONE. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|IF_EXISTS_SET_COLDDAM_POINT}}
|
*<temperature>
| Changes a material's COLDDAM_POINT, but only if it was not set to NONE. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|IF_EXISTS_SET_IGNITE_POINT}}
|
*<temperature>
| Changes a material's IGNITE_POINT, but only if it was not set to NONE. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|IF_EXISTS_SET_MELTING_POINT}}
|
*<temperature>
| Changes a material's MELTING_POINT, but only if it was not set to NONE. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|IF_EXISTS_SET_BOILING_POINT}}
|
*<temperature>
| Changes a material's BOILING_POINT, but only if it was not set to NONE. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|IF_EXISTS_SET_MAT_FIXED_TEMP}}
|
*<temperature>
| Changes a material's MAT_FIXED_TEMP, but only if it was not set to NONE. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|SOLID_DENSITY}}
|
*<density>
| Specifies the density (in kilograms per cubic meter) of the material when in solid form. Also affects combat calculations; affects blunt-force damage and ability of edged weapons to pierce tissue layers{{verify}}. Defaults to NONE.

|-
| {{text_anchor|LIQUID_DENSITY}}
|
*<density>
| Specifies the density of the material when in liquid form. Defaults to NONE.

|-
| {{text_anchor|MOLAR_MASS}}
|
*<value>
| Supposedly not used{{verify}}. Theoretically, should determine density (at given pressure) in gas state, on which in turn would depend (together with weight of vaporized material) on the volume covered by spreading vapors. Defaults to NONE.

|-
| {{text_anchor|EXTRACT_STORAGE}}
| * BARREL or FLASK
| Specifies the type of container used to store the material. Used in conjunction with the [EXTRACT_BARREL], [EXTRACT_VIAL], or [EXTRACT_STILL_VIAL] [[plant token]]s. Defaults to BARREL.

|-
| {{text_anchor|BUTCHER_SPECIAL}}
|
*<[[item token]]>
| Specifies the item type used for butchering results made of this material. Stock raws use GLOB:NONE for fat and MEAT:NONE for other meat materials.

|-
| {{text_anchor|MEAT_NAME}}
|
*<prefix>
*<name>
*<adjective>
| When a creature is butchered, meat yielded from organs made from this material will be named via this token. If this token is not specified, meat objects will be called "chops" instead.

|-
| {{text_anchor|BLOCK_NAME}}
|
*<singular>
*<plural>
| Specifies the name of [[block]]s made from this material.

|-
| {{text_anchor|MATERIAL_REACTION_PRODUCT}}
|
*<reaction reference>
*<[[material token]]>
| Used with reaction raws to associate a reagent material with a product material. The first argument is used by HAS_MATERIAL_REACTION_PRODUCT and GET_MATERIAL_FROM_REAGENT in reaction raws. The remainder is a material reference, generally LOCAL_CREATURE_MAT:SUBTYPE or LOCAL_PLANT_MAT:SUBTYPE or INORGANIC:STONETYPE.
[MATERIAL_REACTION_PRODUCT:TAN_MAT:LOCAL_CREATURE_MAT:LEATHER]

|-
| {{text_anchor|REACTION_CLASS}}
|
*<reaction class name>
| Used to classify all items made of the material, so that reactions can use them as generic reagents.
In default raws, the following are used:
* FAT, TALLOW, SOAP, MILK, CHEESE, WAX
* CAN_GLAZE - items made from this material can be glazed.
* FLUX - can be used as [[flux]] in pig iron and steel making.
* GYPSUM - can be processed into [[gypsum plaster]].

|-
| {{text_anchor|HARDENS_WITH_WATER}}
|
* <[[material token]]>
| Allows the material to be used to make [[healthcare|casts]].

|-
| {{text_anchor|SOAP_LEVEL}}
|
*<value>
| [[Soap]] has [SOAP_LEVEL:2]. Effects unknown. Defaults to 0.

|-
| {{text_anchor|SYNDROME}}
|
| Begins defining a [[syndrome]] applied by the material. Multiple syndromes can be specified. See [[Syndrome token]].
|}

===Material states===

The following is a list of valid material states:

{| {{prettytable}}
|-
|'''SOLID'''
|-
|'''LIQUID'''
|-
|'''GAS'''
|-
|'''POWDER''' (or '''SOLID_POWDER''')
|-
|'''PASTE''' (or '''SOLID_PASTE''')
|-
|'''PRESSED''' (or '''SOLID_PRESSED''')
|}

The following can be specified within tokens such as [[Material_definition_token#STATE_NAME|STATE_NAME]], [[Material_definition_token#STATE_NAME_ADJ|STATE_NAME_ADJ]] and [[Material_definition_token#STATE_ADJ|STATE_ADJ]] to make them apply to several of the above material states simultaneously:

{| {{prettytable}}
|- bgcolor="#C0C0C0"
!Value
!Description
|-
|'''ALL'''
|Denotes all possible material states.
|-
|'''ALL_SOLID'''
|Denotes 'SOLID', 'POWDER', 'PASTE' and 'PRESSED'.
|}

==Material usage tokens==
{| {{prettytable}}
|- bgcolor="#C0C0C0"
! Token
! Arguments
! Description

|-
| {{text_anchor|IMPLIES_ANIMAL_KILL}}
|
| Lets the game know that an animal was likely killed in the production of this item. Entities opposed to killing animals (which currently does '''not''' include [[elf|Elves]]) will refuse to accept these items in trade.

|-
| {{text_anchor|ALCOHOL_PLANT}}
|
| Classifies the material as plant-based alcohol, allowing its storage in food stockpiles under "Drink (Plant)".

|-
| {{text_anchor|ALCOHOL_CREATURE}}
|
| Classifies the material as animal-based alcohol, allowing its storage in food stockpiles under "Drink (Animal)".

|-
| {{text_anchor|ALCOHOL}}
|
| Classifies the material as generic alcohol. Implied by both ALCOHOL_PLANT and ALCOHOL_CREATURE. Exact behavior unknown, possibly vestigial.

|-
| {{text_anchor|CHEESE_PLANT}}
|
| Classifies the material as plant-based cheese, allowing its storage in food stockpiles under "Cheese (Plant)".

|-
| {{text_anchor|CHEESE_CREATURE}}
|
| Classifies the material as animal-based cheese, allowing its storage in food stockpiles under "Cheese (Animal)".

|-
| {{text_anchor|CHEESE}}
|
| Classifies the material as generic cheese. Implied by both CHEESE_PLANT and CHEESE_CREATURE. Exact behavior unknown, possibly vestigial.

|-
| {{text_anchor|POWDER_MISC_PLANT}}
|
| Classifies the material as plant powder, allowing its storage in food stockpiles under "Milled Plant".

|-
| {{text_anchor|POWDER_MISC_CREATURE}}
|
| Classifies the material as creature powder, allowing its storage in food stockpiles under "Bone Meal". Unlike milled plants, such as sugar and flour, "Bone Meal" barrels or pots may not contain bags. Custom reactions using this product better use buckets or jugs instead.

|-
| {{text_anchor|POWDER_MISC}}
|
| Classifies the material as generic powder. Implied by both POWDER_MISC_PLANT and POWDER_MISC_CREATURE. Exact behavior unknown, possibly vestigial.

|-
| {{text_anchor|STOCKPILE_GLOB}} or {{text_anchor|STOCKPILE_GLOB_SOLID}}
|
| Permits globs of the material in solid form to be stored in food stockpiles under "Fat" - without it, dwarves will come by and "clean" the items, destroying them (unless [DO_NOT_CLEAN_GLOB] is also included).

|-
| {{text_anchor|STOCKPILE_GLOB_PASTE}}
|
| Classifies the material as milled paste, allowing its storage in food stockpiles under "Paste".

|-
| {{text_anchor|STOCKPILE_GLOB_PRESSED}}
|
| Classifies the material as pressed goods, allowing its storage in food stockpiles under "Pressed Material".

|-
| {{text_anchor|LIQUID_MISC_PLANT}}
|
| Classifies the material as a plant extract, allowing its storage in food stockpiles under "Extract (Plant)".

|-
| {{text_anchor|LIQUID_MISC_CREATURE}}
|
| Classifies the material as a creature extract, allowing its storage in food stockpiles under "Extract (Animal)".

|-
| {{text_anchor|LIQUID_MISC_OTHER}}
|
| Classifies the material as a miscellaneous liquid, allowing its storage in food stockpiles under "Misc. Liquid" along with lye.

|-
| {{text_anchor|LIQUID_MISC}}
|
| Classifies the material as a generic liquid. Implied by LIQUID_MISC_PLANT, LIQUID_MISC_CREATURE, and LIQUID_MISC_OTHER. Exact behavior unknown, possibly vestigial.

|-
| {{text_anchor|STRUCTURAL_PLANT_MAT}}
|
| Classifies the material as a plant, allowing its storage in food stockpiles under "Plants".

|-
| {{text_anchor|SEED_MAT}}
|
| Classifies the material as a plant seed, allowing its storage in food stockpiles under "Seeds".

|-
| {{text_anchor|LEAF_MAT}}
|
| Classifies the material as plant leaf, allowing its storage in food stockpiles under "Leaves".

|-
| {{text_anchor|BONE}}
|
| Classifies the material as bone, allowing its use for bone carvers and restriction from stockpiles by material.

|-
| {{text_anchor|WOOD}}
|
| Classifies the material as wood, allowing its use for carpenters and storage in wood stockpiles. Entities opposed to killing plants (i.e. [[Elf|Elves]]) will refuse to accept these items in trade.

|-
| {{text_anchor|THREAD_PLANT}}
|
| Classifies the material as plant fiber, allowing its use for clothiers and storage in cloth stockpiles under "Thread (Plant)" and "Cloth (Plant)".

|-
| {{text_anchor|TOOTH}}
|
| Classifies the material as tooth, allowing its use for bone carvers and restriction from stockpiles by material.

|-
| {{text_anchor|HORN}}
|
| Classifies the material as horn, allowing its use for bone carvers and restriction from stockpiles by material.

|-
| {{text_anchor|PEARL}}
|
| Classifies the material as pearl, allowing its use for bone carvers and restriction from stockpiles by material.

|-
| {{text_anchor|SHELL}}
|
| Classifies the material as shell, allowing its use for bone carvers and restriction from stockpiles by material.

|-
| {{text_anchor|LEATHER}}
|
| Classifies the material as leather, allowing its use for leatherworkers and storage in leather stockpiles.

|-
| {{text_anchor|SILK}}
|
| Classifies the material as silk, allowing its use for clothiers and storage in cloth stockpiles under "Thread (Silk)" and "Cloth (Silk)".

|-
| {{text_anchor|SOAP}}
|
| Classifies the material as soap, allowing it to be used as a bath detergent and stored in bar/block stockpiles under "Bars: Other Materials".{{verify}}

|-
| {{text_anchor|GENERATES_MIASMA}}
|
| Material generates miasma when it rots.

|-
| {{text_anchor|MEAT}}
|
| Classifies the material as edible meat.{{verify}}

|-
| {{text_anchor|ROTS}}
|
| Material will rot if not stockpiled appropriately. Currently only affects [[food]] and [[refuse]], other items made of this material will not rot.

|-
| {{text_anchor|BLOOD_MAP_DESCRIPTOR}}
|
| Tells the game to classify contaminants of this material as being "blood" in Adventurer mode tile descriptions ("Here we have a Dwarf in a slurry of blood.").

|-
| {{text_anchor|ICHOR_MAP_DESCRIPTOR}}
|
| Tells the game to classify contaminants of this material as being "ichor".

|-
| {{text_anchor|GOO_MAP_DESCRIPTOR}}
|
| Tells the game to classify contaminants of this material as being "goo".

|-
| {{text_anchor|SLIME_MAP_DESCRIPTOR}}
|
| Tells the game to classify contaminants of this material as being "slime".

|-
| {{text_anchor|PUS_MAP_DESCRIPTOR}}
|
| Tells the game to classify contaminants of this material as being "pus".

|-
| {{text_anchor|ENTERS_BLOOD}}
|
| Used for materials which cause [[syndrome]]s, causes it to enter the creature's blood instead of simply spattering on the surface.

|-
| {{text_anchor|EDIBLE_VERMIN}}
|
| Can be eaten by vermin.

|-
| {{text_anchor|EDIBLE_RAW}}
|
| Can be eaten raw.

|-
| {{text_anchor|EDIBLE_COOKED}}
|
| Can be cooked and then eaten.

|-
| {{text_anchor|DO_NOT_CLEAN_GLOB}}
|
| Prevents globs made of this material from being cleaned up and destroyed.

|-
| {{text_anchor|NO_STONE_STOCKPILE}}
|
| Prevents the material from showing up in Stone stockpile settings.

|-
| {{text_anchor|ITEMS_METAL}}
|
| Allows the creation of metal furniture at the metalsmith's forge.

|-
| {{text_anchor|ITEMS_BARRED}}
|
| Equivalent to ITEMS_HARD. Given to [[bone]].

|-
| {{text_anchor|ITEMS_SCALED}}
|
| Equivalent to ITEMS_HARD. Given to [[shell]].

|-
| {{text_anchor|ITEMS_LEATHER}}
|
| Equivalent to ITEMS_SOFT. Given to [[leather]].

|-
| {{text_anchor|ITEMS_SOFT}}
|
| Random [[finished goods|crafts]] made from this material cannot be made into rings, crowns, scepters or figurines. Given to [[plant fiber]], [[silk]] and [[wool]].

|-
| {{text_anchor|ITEMS_HARD}}
|
| Random [[finished goods|crafts]] made from this material include all seven items. Given to [[stone]], [[wood]], [[bone]], [[shell]], [[chitin]], [[nail|claws]], [[tooth|teeth]], [[horn|horns]], [[horn|hooves]] and [[wax|beeswax]]. [[Hair]], [[pearl|pearls]] and eggshells also have the tag.

|-
| {{text_anchor|IS_STONE}}
|
| Used to define that the material is a stone. Allows its usage in [[masonry]] and [[stonecrafting]] and storage in stone stockpiles, among other effects.

|-
| {{text_anchor|UNDIGGABLE}}
|
| Used for a stone that cannot be dug into.

|-
| {{text_anchor|DISPLAY_UNGLAZED}}
|
| Causes containers made of this material to be prefixed with "unglazed" if they have not yet been [[glaze]]d.

|-
| {{text_anchor|YARN}}
|
| Classifies the material as yarn, allowing its use for clothiers and its storage in cloth stockpiles under "Thread (Yarn)" and "Cloth (Yarn)".

|-
| {{text_anchor|STOCKPILE_THREAD_METAL}}
|
| Classifies the material as metal thread, permitting thread and cloth to be stored in cloth stockpiles under "Thread (Metal)" and "Cloth (Metal)".

|-
| {{text_anchor|IS_METAL}}
|
| Defines the material as being metal, allowing it to be used at forges.

|-
| {{text_anchor|IS_GLASS}}
|
| Used internally by green glass, clear glass, and crystal glass.

|-
| {{text_anchor|CRYSTAL_GLASSABLE}}
|
| Can be used in the production of crystal glass.

|-
| {{text_anchor|ITEMS_WEAPON}}
|
| Melee [[Weapon#Manufactured weapons|weapons]] can be made out of this material.

|-
| {{text_anchor|ITEMS_WEAPON_RANGED}}
|
| Ranged weapons can be made out of this material.

|-
| {{text_anchor|ITEMS_ANVIL}}
|
| [[Anvil]]s can be made out of this material.

|-
| {{text_anchor|ITEMS_AMMO}}
|
| [[Weapon#Ammunition|Ammunition]] can be made out of this material.

|-
| {{text_anchor|ITEMS_DIGGER}}
|
| [[Weapon#Dwarf-manufactured weapons|Picks]] can be made out of this material.

|-
| {{text_anchor|ITEMS_ARMOR}}
|
| [[Armor]] can be made out of this material.

|-
| {{text_anchor|ITEMS_DELICATE}}
|
| Used internally by amber and coral. Functionally equivalent to ITEMS_HARD.

|-
| {{text_anchor|ITEMS_SIEGE_ENGINE}}
|
| Siege engine parts can be made out of this material. Does not appear to work.

|-
| {{text_anchor|ITEMS_QUERN}}
|
| Querns and millstones can be made out of this material.{{verify}}
|}

==Syndrome tokens==
Below is a table with some of the tokens you can use when declaring a [SYNDROME] token. For all the tokens you can use, see the [[Syndrome token]] page.

{| {{prettytable}}
|- bgcolor="#C0C0C0"
! Token
! Arguments
! Description

|-
| {{text_anchor|SYN_NAME
|
* text
| Defines the name of the syndrome

|-
| {{text_anchor|SYN_INJECTED}}
|
| Syndrome can be contracted by injection (by a creature)

|-
| {{text_anchor|SYN_CONTACT}}
|
| Syndrome can be contracted on contact (e.g. poison dust or liquid)

|-
| {{text_anchor|SYN_INHALED}}
|
| Syndrome can be contracted by inhalation (e.g. poison vapor or gas)

|-
| {{text_anchor|SYN_AFFECTED_CLASS}}
|
* creature class name
| Adds a class of creatures to those affected, such as CREATURE_CLASS:GENERAL_POISON

|-
| {{text_anchor|SYN_IMMUNE_CLASS}}
|
* creature class name
| Makes the class of creatures immune to the syndrome

|-
| {{text_anchor|SYN_AFFECTED_CREATURE}}
|
* creature name
* caste name or ALL
| Adds a specific creature to those affected.

|-
| {{text_anchor|SYN_IMMUNE_CREATURE}}
|
* creature name
* caste name or ALL
| Makes the creature immune to the syndrome

|-
| CE_PAIN CE_SWELLING CE_OOZING CE_BRUISING CE_BLISTERS CE_NUMBNESS CE_PARALYSIS CE_FEVER CE_BLEEDING CE_COUGH_BLOOD CE_VOMIT_BLOOD CE_NAUSEA CE_UNCONSCIOUSNESS CE_NECROSIS CE_IMPAIR_FUNCTION CE_DROWSINESS CE_DIZZINESS
|
*SEV:<value> (severity, higher is worse)
*PROB:<value(1-100)> (probability)
*RESISTABLE (optional) allows resistance
*SIZE_DILUTES (optional) lessens effect based on size
Place affected:
*LOCALIZED (optional)
*VASCULAR_ONLY (optional)
*MUSCULAR_ONLY (optional)
*BP:BY_CATEGORY:category:tissue (optional)
*BP:BY_TYPE:type:tissue (optional)
*BP:BY_TOKEN:token:tissue (optional)
Timeline:
*Start:effect start time
*Peak:effect peak time
*End:effect end time
| Specifies the way that a syndrome affects a creature -- more detail can be found on the [[Syndrome#Creature effect tokens|Syndromes page]]

|}

==See Also==
* [[Inorganic material definition token]]
* [[Tissue definition token]]
* [[Syndrome]]

{{Category|Modding}}
{{Category|Tokens}}

v0.34:Material definition token

2026-04-04T01:10:22Z

Quietust:

{{quality|Exceptional|18:11, 28 April 2011 (UTC)}}{{av}}

The following tokens can be used in material definitions (whether for inorganics or those within plants and creatures) as well as in material templates.

==Material properties==
{| {{prettytable}}
|- bgcolor="#C0C0C0"
! Token
! Arguments
! Description

|-
| {{text_anchor|USE_MATERIAL_TEMPLATE}}
|
* <template name>
| Imports the properties of the specified preexisting material template.

|-
| {{text_anchor|PREFIX}}
|
* <prefix> or NONE
| Applies a prefix to all items made from the material. For PLANT and CREATURE materials, this defaults to the plant/creature name. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|STONE_NAME}}
|
* <name>
| Overrides the name of [[Item_token#BOULDER|BOULDER]] items (i.e. mined-out stones) made of the material (used for native copper/silver/gold/platinum to make them be called "nuggets" instead of "boulders").

|-
| {{text_anchor|IS_GEM}}
|
* <name>
* <plural>
* OVERWRITE_SOLID (optional)
| Used to indicate that said material is a gemstone - when tiles are mined out, rough gems will be yielded instead of boulders. Plural can be "STP" to automatically append an "s" to the singular form, and OVERWRITE_SOLID will override the relevant STATE_NAME and STATE_ADJ values.

|-
| {{text_anchor|TEMP_DIET_INFO}}
|
* <type>
| Specifies what the material should be treated as when drinking water contaminated by it, for generating unhappy [[thought]]s. Valid values are BLOOD, SLIME, VOMIT, ICHOR, PUS, GOO, GRIME, and FILTH.

|-
| {{text_anchor|POWDER_DYE}}
|
*<[[Color#Color_tokens|color token]]>
| Allows the material to be used as [[dye]], and defines color of dyed items.

|-
| {{text_anchor|TILE}}
|
*<[[Main:Character table|tile value or character]]>
| Specifies the tile that will be used to represent unmined tiles made of this material. Generally only used with stones. Defaults to 219 ('█').

|-
| {{text_anchor|ITEM_SYMBOL}}
|
*<[[Main:Character table|tile value or character]]>
| Specifies the tile that will be used to represent [[Item_token#BOULDER|BOULDER]] items made of this material. Generally only used with stones. Defaults to 7 ('•').

|-
| {{text_anchor|DISPLAY_COLOR}}
|
*<[[Color#Color_values|foreground color]]>
*<[[Color#Color_values|background color]]>
*<[[Color#Color_values|foreground brightness]]>
| The on-screen color of the material. Uses a standard 3-digit [[Color|color token]]. Equivalent to [TILE_COLOR:a:b:c], [BUILD_COLOR:b:a:X] (X = 1 if 'a' equals 'b', 0 otherwise), and [BASIC_COLOR:a:c]

|-
| {{text_anchor|BUILD_COLOR}}
|
*<[[Color#Color_values|foreground color]]>
*<[[Color#Color_values|background color]]>
*<[[Color#Color_values|foreground brightness]]>
| The color of objects made of this material which use both the foreground and background color: [[door]]s, [[floodgate]]s, [[hatch cover]]s, [[bin]]s, [[barrel]]s, and [[cage]]s. Defaults to 7:7:1 (white).

|-
| {{text_anchor|TILE_COLOR}}
|
*<[[Color#Color_values|foreground color]]>
*<[[Color#Color_values|background color]]>
*<[[Color#Color_values|foreground brightness]]>
| The color of unmined tiles containing this material (for stone and soil), as well as [[engraving]]s in this material. Defaults to 7:7:1 (white).

|-
| {{text_anchor|BASIC_COLOR}}
|
*<[[Color#Color_values|foreground color]]>
*<[[Color#Color_values|foreground brightness]]>
| The color of objects made of this material which use only the foreground color, including workshops, floors and boulders, and smoothed walls. Defaults to 7:1 (white).

|-
| {{text_anchor|STATE_COLOR}}
|
*<[[Material_definition_token#Material States|material state]]>
*<[[Color#Color_tokens|color token]]>
| Determines the color of the material at the specified state. See [[Material_definition_token#Material states|below]] for a list of valid material states. Color comes from descriptor_color_standard.txt. The nearest color value is used to display contaminants and body parts made of this material. Example:
[STATE_COLOR:ALL_SOLID:GRAY]

|-
| {{text_anchor|STATE_NAME}}
|
*<[[Material_definition_token#Material States|material state]]>
*<name>
| Determines the name of the material at the specified state, as displayed in-game.
[STATE_NAME:ALL_SOLID:stone]

|-
| {{text_anchor|STATE_ADJ}}
|
*<[[Material_definition_token#Material States|material state]]>
*<adjective>
| Like [[Material_definition_token#STATE_NAME|STATE_NAME]], but used in different situations. Equipment made from the material uses the state adjective and not the state name.

|-
| {{text_anchor|STATE_NAME_ADJ}}
|
*<[[Material_definition_token#Material States|material state]]>
*<name>
*<adjective>
| Sets both [[Material_definition_token#STATE_NAME|STATE_NAME]] and [[Material_definition_token#STATE_ADJ|STATE_ADJ]] at the same time.

|-
| {{text_anchor|ABSORPTION}}
|
*<value>
| The material's tendency to absorb liquids. Containers made of materials with nonzero absorption cannot hold liquids unless they have been [[glaze]]d. Defaults to 0.

|-
| {{text_anchor|IMPACT_YIELD}}
|
*<value>
| Specifies how hard of an impact (in kilopascals) the material can withstand before it will start deforming permanently. Used for blunt-force combat. Defaults to 10000.

|-
| {{text_anchor|IMPACT_FRACTURE}}
|
*<value>
| Specifies how hard of an impact the material can withstand before it will fail entirely. Used for blunt-force combat. Defaults to 10000.

|-
| {{text_anchor|IMPACT_STRAIN_AT_YIELD}} or {{text_anchor|IMPACT_ELASTICITY}}
|
*<value>
| Specifies how much the material will have given (in parts-per-100000) when the yield point is reached. Used for blunt-force combat. Defaults to 0. Apparently affects in combat whether the corresponding tissue is bruised (value >= 50000), torn (value between 25000 and 49999), or fractured (value <= 24999)

|-
| {{text_anchor|COMPRESSIVE_YIELD}}
|
*<value>
| Specifies how hard the material can be compressed before it will start deforming permanently. Determines a tissue's resistance to pinching and response to strangulation. Defaults to 10000.

|-
| {{text_anchor|COMPRESSIVE_FRACTURE}}
|
*<value>
| Specifies how hard the material can be compressed before it will fail entirely. Determines a tissue's resistance to pinching and response to strangulation. Defaults to 10000.

|-
| {{text_anchor|COMPRESSIVE_STRAIN_AT_YIELD}} or {{text_anchor|COMPRESSIVE_ELASTICITY}}
|
*<value>
| Specifies how much the material will have given when it has been compressed to its yield point. Determines a tissue's resistance to pinching and response to strangulation. Defaults to 0.

|-
| {{text_anchor|TENSILE_YIELD}}
|
*<value>
| Specifies how hard the material can be stretched before it will start deforming permanently. Determines a tissue's resistance to a latching and tearing bite. Defaults to 10000.

|-
| {{text_anchor|TENSILE_FRACTURE}}
|
*<value>
| Specifies how hard the material can be stretched before it will fail entirely. Determines a tissue's resistance to a latching and tearing bite. Defaults to 10000.

|-
| {{text_anchor|TENSILE_STRAIN_AT_YIELD}} or {{text_anchor|TENSILE_ELASTICITY}}
|
*<value>
| Specifies how much the material will have given when it is stretched to its yield point. Determines a tissue's resistance to a latching and tearing bite. Defaults to 0.

|-
| {{text_anchor|TORSION_YIELD}}
|
*<value>
| Specifies how hard the material can be twisted before it will start deforming permanently. Used for latching and shaking with a blunt attack (no default creature has such an attack, but they can be modded in). Defaults to 10000.

|-
| {{text_anchor|TORSION_FRACTURE}}
|
*<value>
| Specifies how hard the material can be twisted before it will fail entirely. Used for latching and shaking with a blunt attack (no default creature has such an attack, but they can be modded in). Defaults to 10000.

|-
| {{text_anchor|TORSION_STRAIN_AT_YIELD}} or {{text_anchor|TORSION_ELASTICITY}}
|
*<value>
| Specifies how much the material will have given when it is twisted to its yield point. Used for latching and shaking with a blunt attack (no default creature has such an attack, but they can be modded in). Defaults to 0.

|-
| {{text_anchor|SHEAR_YIELD}}
|
*<value>
| Specifies how hard the material can be sheared before it will start deforming permanently. Used for cutting calculations. Defaults to 10000.

|-
| {{text_anchor|SHEAR_FRACTURE}}
|
*<value>
| Specifies how hard the material can be sheared before it will fail entirely. Used for cutting calculations. Defaults to 10000.

|-
| {{text_anchor|SHEAR_STRAIN_AT_YIELD}} or {{text_anchor|SHEAR_ELASTICITY}}
|
*<value>
| Specifies how much the material will have given when sheared to its yield point. Used for cutting calculations. Defaults to 0.

|-
| {{text_anchor|BENDING_YIELD}}
|
*<value>
| Specifies how hard the material can be bent before it will start deforming permanently. Determines a tissue's resistance to being mangled with a joint lock. Defaults to 10000.

|-
| {{text_anchor|BENDING_FRACTURE}}
|
*<value>
| Specifies how hard the material can be bent before it will fail entirely. Determines a tissue's resistance to being mangled with a joint lock. Defaults to 10000.

|-
| {{text_anchor|BENDING_STRAIN_AT_YIELD}} or {{text_anchor|BENDING_ELASTICITY}}
|
*<value>
| Specifies how much the material will have given when bent to its yield point. Determines a tissue's resistance to being mangled with a joint lock. Defaults to 0.

|-
| {{text_anchor|MAX_EDGE}}
|
*<value>
| How sharp the material is. Used in cutting calculations. Does not allow an inferior metal to penetrate superior armor. Applying a value of at least 10000 to a stone will allow weapons to be made from that stone. Defaults to 10000.

|-
| {{text_anchor|MATERIAL_VALUE}}
|
*<value>
| Value modifier for the material. Defaults to 1. This number can be made negative by placing a "-" in front, resulting in things that you are paid to buy and must pay to sell.

|-
| {{text_anchor|MULTIPLY_VALUE}}
|
*<value>
| Multiplies the value of the material. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|SPEC_HEAT}}
|
*<specific heat capacity>
| Rate at which the material heats up or cools down (in joules/kilogram-kelvin). If set to NONE, the temperature will be fixed at its initial value. See [[Temperature]] for more information. Defaults to NONE.

|-
| {{text_anchor|HEATDAM_POINT}}
|
*<temperature>
| Temperature above which the material takes damage from heat. May be set to NONE. If the material has an ignite point but no heatdam point, it will burn for a very long time (9 months and 16.8 days). Defaults to NONE.

|-
| {{text_anchor|COLDDAM_POINT}}
|
*<temperature>
| Temperature below which the material takes damage from cold. Defaults to NONE.

|-
| {{text_anchor|IGNITE_POINT}}
|
*<temperature>
| Temperature at which the material will catch fire. Defaults to NONE.

|-
| {{text_anchor|MELTING_POINT}}
|
*<temperature>
| Temperature at which the material melts. Defaults to NONE.

|-
| {{text_anchor|BOILING_POINT}}
|
*<temperature>
| Temperature at which the material boils. Defaults to NONE.

|-
| {{text_anchor|MAT_FIXED_TEMP}}
|
*<temperature>
| Items composed of this material will initially have this temperature. Used in conjunction with <code>[SPEC_HEAT:NONE]</code> to make material's temperature fixed at the specified value. Defaults to NONE.

|-
| {{text_anchor|IF_EXISTS_SET_HEATDAM_POINT}}
|
*<temperature>
| Changes a material's HEATDAM_POINT, but only if it was not set to NONE. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|IF_EXISTS_SET_COLDDAM_POINT}}
|
*<temperature>
| Changes a material's COLDDAM_POINT, but only if it was not set to NONE. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|IF_EXISTS_SET_IGNITE_POINT}}
|
*<temperature>
| Changes a material's IGNITE_POINT, but only if it was not set to NONE. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|IF_EXISTS_SET_MELTING_POINT}}
|
*<temperature>
| Changes a material's MELTING_POINT, but only if it was not set to NONE. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|IF_EXISTS_SET_BOILING_POINT}}
|
*<temperature>
| Changes a material's BOILING_POINT, but only if it was not set to NONE. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|IF_EXISTS_SET_MAT_FIXED_TEMP}}
|
*<temperature>
| Changes a material's MAT_FIXED_TEMP, but only if it was not set to NONE. '''Not permitted in material template definitions.'''

|-
| {{text_anchor|SOLID_DENSITY}}
|
*<density>
| Specifies the density (in kilograms per cubic meter) of the material when in solid form. Also affects combat calculations; affects blunt-force damage and ability of edged weapons to pierce tissue layers{{verify}}. Defaults to NONE.

|-
| {{text_anchor|LIQUID_DENSITY}}
|
*<density>
| Specifies the density of the material when in liquid form. Defaults to NONE.

|-
| {{text_anchor|MOLAR_MASS}}
|
*<value>
| Supposedly not used{{verify}}. Theoretically, should determine density (at given pressure) in gas state, on which in turn would depend (together with weight of vaporized material) on the volume covered by spreading vapors. Defaults to NONE.

|-
| {{text_anchor|EXTRACT_STORAGE}}
| * BARREL or FLASK
| Specifies the type of container used to store the material. Used in conjunction with the [EXTRACT_BARREL], [EXTRACT_VIAL], or [EXTRACT_STILL_VIAL] [[plant token]]s. Defaults to BARREL.

|-
| {{text_anchor|BUTCHER_SPECIAL}}
|
*<[[item token]]>
| Specifies the item type used for butchering results made of this material. Stock raws use GLOB:NONE for fat and MEAT:NONE for other meat materials.

|-
| {{text_anchor|MEAT_NAME}}
|
*<prefix>
*<name>
*<adjective>
| When a creature is butchered, meat yielded from organs made from this material will be named via this token. If this token is not specified, meat objects will be called "chops" instead.

|-
| {{text_anchor|BLOCK_NAME}}
|
*<singular>
*<plural>
| Specifies the name of [[block]]s made from this material.

|-
| {{text_anchor|WAFERS}}
|
| The material forms "wafers" instead of "[[bar]]s".

|-
| {{text_anchor|MATERIAL_REACTION_PRODUCT}}
|
*<reaction reference>
*<[[material token]]>
| Used with reaction raws to associate a reagent material with a product material. The first argument is used by HAS_MATERIAL_REACTION_PRODUCT and GET_MATERIAL_FROM_REAGENT in reaction raws. The remainder is a material reference, generally LOCAL_CREATURE_MAT:SUBTYPE or LOCAL_PLANT_MAT:SUBTYPE or INORGANIC:STONETYPE.
[MATERIAL_REACTION_PRODUCT:TAN_MAT:LOCAL_CREATURE_MAT:LEATHER]

|-
| {{text_anchor|REACTION_CLASS}}
|
*<reaction class name>
| Used to classify all items made of the material, so that reactions can use them as generic reagents.
In default raws, the following are used:
* FAT, TALLOW, SOAP, MILK, CHEESE, WAX
* CAN_GLAZE - items made from this material can be glazed.
* FLUX - can be used as [[flux]] in pig iron and steel making.
* GYPSUM - can be processed into [[gypsum plaster]].

|-
| {{text_anchor|METAL_ORE}}
|
* <inorganic material name e.g. [[lead|LEAD]]>
* <value>
| Makes BOULDER acceptable as a [[Reactions#Reagents|reagent]] in reactions that require [[Item_token#Related_Tokens|"METAL_ORE:MATERIAL_NAME"]], as well as [[Smelter|smelting]] directly into metal [[bar]]s. Places the material under "Metal Ores" in Stone stockpiles. The specified value determines the probability for this product (see [[Tetrahedrite]] or [[Galena]] for details).

|-
| {{text_anchor|THREAD_METAL}}
|
* <inorganic material name e.g. [[Raw_adamantine|RAW_ADAMANTINE]]>
* <value>
| Makes BOULDER items made of the material acceptable for [[Strand extractor|strand extraction]] into threads; see also STOCKPILE_THREAD_METAL. Value presumably determines the probability of this product extracted.{{verify}}

|-
| {{text_anchor|HARDENS_WITH_WATER}}
|
* <[[material token]]>
| Allows the material to be used to make [[healthcare|casts]].

|-
| {{text_anchor|SOAP_LEVEL}}
|
*<value>
| [[Soap]] has [SOAP_LEVEL:2]. Effects unknown. Defaults to 0.

|-
| {{text_anchor|SYNDROME}}
|
| Begins defining a [[syndrome]] applied by the material. Multiple syndromes can be specified. See [[Syndrome token]].
|}

===Material states===

The following is a list of valid material states:

{| {{prettytable}}
|-
|'''SOLID'''
|-
|'''LIQUID'''
|-
|'''GAS'''
|-
|'''POWDER''' (or '''SOLID_POWDER''')
|-
|'''PASTE''' (or '''SOLID_PASTE''')
|-
|'''PRESSED''' (or '''SOLID_PRESSED''')
|}

The following can be specified within tokens such as [[Material_definition_token#STATE_NAME|STATE_NAME]], [[Material_definition_token#STATE_NAME_ADJ|STATE_NAME_ADJ]] and [[Material_definition_token#STATE_ADJ|STATE_ADJ]] to make them apply to several of the above material states simultaneously:

{| {{prettytable}}
|- bgcolor="#C0C0C0"
!Value
!Description
|-
|'''ALL'''
|Denotes all possible material states.
|-
|'''ALL_SOLID'''
|Denotes 'SOLID', 'POWDER', 'PASTE' and 'PRESSED'.
|}

==Material usage tokens==
{| {{prettytable}}
|- bgcolor="#C0C0C0"
! Token
! Arguments
! Description

|-
| {{text_anchor|IMPLIES_ANIMAL_KILL}}
|
| Lets the game know that an animal was likely killed in the production of this item. Entities opposed to killing animals (which currently does '''not''' include [[elf|Elves]]) will refuse to accept these items in trade.

|-
| {{text_anchor|ALCOHOL_PLANT}}
|
| Classifies the material as plant-based alcohol, allowing its storage in food stockpiles under "Drink (Plant)".

|-
| {{text_anchor|ALCOHOL_CREATURE}}
|
| Classifies the material as animal-based alcohol, allowing its storage in food stockpiles under "Drink (Animal)".

|-
| {{text_anchor|ALCOHOL}}
|
| Classifies the material as generic alcohol. Implied by both ALCOHOL_PLANT and ALCOHOL_CREATURE. Exact behavior unknown, possibly vestigial.

|-
| {{text_anchor|CHEESE_PLANT}}
|
| Classifies the material as plant-based cheese, allowing its storage in food stockpiles under "Cheese (Plant)".

|-
| {{text_anchor|CHEESE_CREATURE}}
|
| Classifies the material as animal-based cheese, allowing its storage in food stockpiles under "Cheese (Animal)".

|-
| {{text_anchor|CHEESE}}
|
| Classifies the material as generic cheese. Implied by both CHEESE_PLANT and CHEESE_CREATURE. Exact behavior unknown, possibly vestigial.

|-
| {{text_anchor|POWDER_MISC_PLANT}}
|
| Classifies the material as plant powder, allowing its storage in food stockpiles under "Milled Plant".

|-
| {{text_anchor|POWDER_MISC_CREATURE}}
|
| Classifies the material as creature powder, allowing its storage in food stockpiles under "Bone Meal". Unlike milled plants, such as sugar and flour, "Bone Meal" barrels or pots may not contain bags. Custom reactions using this product better use buckets or jugs instead.

|-
| {{text_anchor|POWDER_MISC}}
|
| Classifies the material as generic powder. Implied by both POWDER_MISC_PLANT and POWDER_MISC_CREATURE. Exact behavior unknown, possibly vestigial.

|-
| {{text_anchor|STOCKPILE_GLOB}} or {{text_anchor|STOCKPILE_GLOB_SOLID}}
|
| Permits globs of the material in solid form to be stored in food stockpiles under "Fat" - without it, dwarves will come by and "clean" the items, destroying them (unless [DO_NOT_CLEAN_GLOB] is also included).

|-
| {{text_anchor|STOCKPILE_GLOB_PASTE}}
|
| Classifies the material as milled paste, allowing its storage in food stockpiles under "Paste".

|-
| {{text_anchor|STOCKPILE_GLOB_PRESSED}}
|
| Classifies the material as pressed goods, allowing its storage in food stockpiles under "Pressed Material".

|-
| {{text_anchor|LIQUID_MISC_PLANT}}
|
| Classifies the material as a plant extract, allowing its storage in food stockpiles under "Extract (Plant)".

|-
| {{text_anchor|LIQUID_MISC_CREATURE}}
|
| Classifies the material as a creature extract, allowing its storage in food stockpiles under "Extract (Animal)".

|-
| {{text_anchor|LIQUID_MISC_OTHER}}
|
| Classifies the material as a miscellaneous liquid, allowing its storage in food stockpiles under "Misc. Liquid" along with lye.

|-
| {{text_anchor|LIQUID_MISC}}
|
| Classifies the material as a generic liquid. Implied by LIQUID_MISC_PLANT, LIQUID_MISC_CREATURE, and LIQUID_MISC_OTHER. Exact behavior unknown, possibly vestigial.

|-
| {{text_anchor|STRUCTURAL_PLANT_MAT}}
|
| Classifies the material as a plant, allowing its storage in food stockpiles under "Plants".

|-
| {{text_anchor|SEED_MAT}}
|
| Classifies the material as a plant seed, allowing its storage in food stockpiles under "Seeds".

|-
| {{text_anchor|LEAF_MAT}}
|
| Classifies the material as plant leaf, allowing its storage in food stockpiles under "Leaves".

|-
| {{text_anchor|BONE}}
|
| Classifies the material as bone, allowing its use for bone carvers and restriction from stockpiles by material.

|-
| {{text_anchor|WOOD}}
|
| Classifies the material as wood, allowing its use for carpenters and storage in wood stockpiles. Entities opposed to killing plants (i.e. [[Elf|Elves]]) will refuse to accept these items in trade.

|-
| {{text_anchor|THREAD_PLANT}}
|
| Classifies the material as plant fiber, allowing its use for clothiers and storage in cloth stockpiles under "Thread (Plant)" and "Cloth (Plant)".

|-
| {{text_anchor|TOOTH}}
|
| Classifies the material as tooth, allowing its use for bone carvers and restriction from stockpiles by material.

|-
| {{text_anchor|HORN}}
|
| Classifies the material as horn, allowing its use for bone carvers and restriction from stockpiles by material.

|-
| {{text_anchor|PEARL}}
|
| Classifies the material as pearl, allowing its use for bone carvers and restriction from stockpiles by material.

|-
| {{text_anchor|SHELL}}
|
| Classifies the material as shell, allowing its use for bone carvers and restriction from stockpiles by material.

|-
| {{text_anchor|LEATHER}}
|
| Classifies the material as leather, allowing its use for leatherworkers and storage in leather stockpiles.

|-
| {{text_anchor|SILK}}
|
| Classifies the material as silk, allowing its use for clothiers and storage in cloth stockpiles under "Thread (Silk)" and "Cloth (Silk)".

|-
| {{text_anchor|SOAP}}
|
| Classifies the material as soap, allowing it to be used as a bath detergent and stored in bar/block stockpiles under "Bars: Other Materials".{{verify}}

|-
| {{text_anchor|GENERATES_MIASMA}}
|
| Material generates miasma when it rots.

|-
| {{text_anchor|MEAT}}
|
| Classifies the material as edible meat.{{verify}}

|-
| {{text_anchor|ROTS}}
|
| Material will rot if not stockpiled appropriately. Currently only affects [[food]] and [[refuse]], other items made of this material will not rot.

|-
| {{text_anchor|BLOOD_MAP_DESCRIPTOR}}
|
| Tells the game to classify contaminants of this material as being "blood" in Adventurer mode tile descriptions ("Here we have a Dwarf in a slurry of blood.").

|-
| {{text_anchor|ICHOR_MAP_DESCRIPTOR}}
|
| Tells the game to classify contaminants of this material as being "ichor".

|-
| {{text_anchor|GOO_MAP_DESCRIPTOR}}
|
| Tells the game to classify contaminants of this material as being "goo".

|-
| {{text_anchor|SLIME_MAP_DESCRIPTOR}}
|
| Tells the game to classify contaminants of this material as being "slime".

|-
| {{text_anchor|PUS_MAP_DESCRIPTOR}}
|
| Tells the game to classify contaminants of this material as being "pus".

|-
| {{text_anchor|ENTERS_BLOOD}}
|
| Used for materials which cause [[syndrome]]s, causes it to enter the creature's blood instead of simply spattering on the surface.

|-
| {{text_anchor|EDIBLE_VERMIN}}
|
| Can be eaten by vermin.

|-
| {{text_anchor|EDIBLE_RAW}}
|
| Can be eaten raw.

|-
| {{text_anchor|EDIBLE_COOKED}}
|
| Can be cooked and then eaten.

|-
| {{text_anchor|DO_NOT_CLEAN_GLOB}}
|
| Prevents globs made of this material from being cleaned up and destroyed.

|-
| {{text_anchor|NO_STONE_STOCKPILE}}
|
| Prevents the material from showing up in Stone stockpile settings.

|-
| {{text_anchor|ITEMS_METAL}}
|
| Allows the creation of metal furniture at the metalsmith's forge.

|-
| {{text_anchor|ITEMS_BARRED}}
|
| Equivalent to ITEMS_HARD. Given to [[bone]].

|-
| {{text_anchor|ITEMS_SCALED}}
|
| Equivalent to ITEMS_HARD. Given to [[shell]].

|-
| {{text_anchor|ITEMS_LEATHER}}
|
| Equivalent to ITEMS_SOFT. Given to [[leather]].

|-
| {{text_anchor|ITEMS_SOFT}}
|
| Random [[finished goods|crafts]] made from this material cannot be made into rings, crowns, scepters or figurines. Given to [[plant fiber]], [[silk]] and [[wool]].

|-
| {{text_anchor|ITEMS_HARD}}
|
| Random [[finished goods|crafts]] made from this material include all seven items. Given to [[stone]], [[wood]], [[bone]], [[shell]], [[chitin]], [[nail|claws]], [[tooth|teeth]], [[horn|horns]], [[horn|hooves]] and [[wax|beeswax]]. [[Hair]], [[pearl|pearls]] and eggshells also have the tag.

|-
| {{text_anchor|IS_STONE}}
|
| Used to define that the material is a stone. Allows its usage in [[masonry]] and [[stonecrafting]] and storage in stone stockpiles, among other effects.

|-
| {{text_anchor|UNDIGGABLE}}
|
| Used for a stone that cannot be dug into.

|-
| {{text_anchor|DISPLAY_UNGLAZED}}
|
| Causes containers made of this material to be prefixed with "unglazed" if they have not yet been [[glaze]]d.

|-
| {{text_anchor|YARN}}
|
| Classifies the material as yarn, allowing its use for clothiers and its storage in cloth stockpiles under "Thread (Yarn)" and "Cloth (Yarn)".

|-
| {{text_anchor|STOCKPILE_THREAD_METAL}}
|
| Classifies the material as metal thread, permitting thread and cloth to be stored in cloth stockpiles under "Thread (Metal)" and "Cloth (Metal)".

|-
| {{text_anchor|IS_METAL}}
|
| Defines the material as being metal, allowing it to be used at forges.

|-
| {{text_anchor|IS_GLASS}}
|
| Used internally by green glass, clear glass, and crystal glass.

|-
| {{text_anchor|CRYSTAL_GLASSABLE}}
|
| Can be used in the production of crystal glass.

|-
| {{text_anchor|ITEMS_WEAPON}}
|
| Melee [[Weapon#Manufactured weapons|weapons]] can be made out of this material.

|-
| {{text_anchor|ITEMS_WEAPON_RANGED}}
|
| Ranged weapons can be made out of this material.

|-
| {{text_anchor|ITEMS_ANVIL}}
|
| [[Anvil]]s can be made out of this material.

|-
| {{text_anchor|ITEMS_AMMO}}
|
| [[Weapon#Ammunition|Ammunition]] can be made out of this material.

|-
| {{text_anchor|ITEMS_DIGGER}}
|
| [[Weapon#Dwarf-manufactured weapons|Picks]] can be made out of this material.

|-
| {{text_anchor|ITEMS_ARMOR}}
|
| [[Armor]] can be made out of this material.

|-
| {{text_anchor|ITEMS_DELICATE}}
|
| Used internally by amber and coral. Functionally equivalent to ITEMS_HARD.

|-
| {{text_anchor|ITEMS_SIEGE_ENGINE}}
|
| Siege engine parts can be made out of this material. Does not appear to work.

|-
| {{text_anchor|ITEMS_QUERN}}
|
| Querns and millstones can be made out of this material.{{verify}}
|}

==Syndrome tokens==
Below is a table with some of the tokens you can use when declaring a [SYNDROME] token. For all the tokens you can use, see the [[Syndrome token]] page.

{| {{prettytable}}
|- bgcolor="#C0C0C0"
! Token
! Arguments
! Description

|-
| {{text_anchor|SYN_NAME
|
* text
| Defines the name of the syndrome

|-
| {{text_anchor|SYN_INJECTED}}
|
| Syndrome can be contracted by injection (by a creature)

|-
| {{text_anchor|SYN_CONTACT}}
|
| Syndrome can be contracted on contact (e.g. poison dust or liquid)

|-
| {{text_anchor|SYN_INHALED}}
|
| Syndrome can be contracted by inhalation (e.g. poison vapor or gas)

|-
| {{text_anchor|SYN_AFFECTED_CLASS}}
|
* creature class name
| Adds a class of creatures to those affected, such as CREATURE_CLASS:GENERAL_POISON

|-
| {{text_anchor|SYN_IMMUNE_CLASS}}
|
* creature class name
| Makes the class of creatures immune to the syndrome

|-
| {{text_anchor|SYN_AFFECTED_CREATURE}}
|
* creature name
* caste name or ALL
| Adds a specific creature to those affected.

|-
| {{text_anchor|SYN_IMMUNE_CREATURE}}
|
* creature name
* caste name or ALL
| Makes the creature immune to the syndrome

|-
| CE_PAIN CE_SWELLING CE_OOZING CE_BRUISING CE_BLISTERS CE_NUMBNESS CE_PARALYSIS CE_FEVER CE_BLEEDING CE_COUGH_BLOOD CE_VOMIT_BLOOD CE_NAUSEA CE_UNCONSCIOUSNESS CE_NECROSIS CE_IMPAIR_FUNCTION CE_DROWSINESS CE_DIZZINESS
|
*SEV:<value> (severity, higher is worse)
*PROB:<value(1-100)> (probability)
*RESISTABLE (optional) allows resistance
*SIZE_DILUTES (optional) lessens effect based on size
Place affected:
*LOCALIZED (optional)
*VASCULAR_ONLY (optional)
*MUSCULAR_ONLY (optional)
*BP:BY_CATEGORY:category:tissue (optional)
*BP:BY_TYPE:type:tissue (optional)
*BP:BY_TOKEN:token:tissue (optional)
Timeline:
*Start:effect start time
*Peak:effect peak time
*End:effect end time
| Specifies the way that a syndrome affects a creature -- more detail can be found on the [[Syndrome#Creature effect tokens|Syndromes page]]

|}

==See Also==
* [[Inorganic material definition token]]
* [[Syndrome]]

{{Category|Modding}}
{{Category|Tokens}}

v0.31:Weapon token

2026-04-04T01:04:01Z

Quietust:

{{quality|Exceptional|19:42, 24 August 2010 (UTC)}}{{av}}

These tokens can only be placed within an ITEM_WEAPON object definition.
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|NAME}}
|
*singular
*plural
| Name of the weapon. Required.

|-
| {{text anchor|ADJECTIVE}}
|
*adjective
| Adjective of the weapon, e.g. the "large" in "large copper dagger".

|-
| {{text anchor|SIZE}} / {{text anchor|WEIGHT}}
|
*size
| Volume of weapon in mL or cubic cm. Defaults to 100.

|-
| {{text anchor|SHOOT_FORCE}}
|
*value
| The amount of force used when firing projectiles - velocity is presumably determined by the projectile's mass. Defaults to 0.

|-
| {{text anchor|SHOOT_MAXVEL}}
|
*value
| The maximum speed a fired projectile can have.

|-
| {{text anchor|SKILL}}
|
*[[Skill token]]
| The skill to determine effectiveness in melee with this weapon. Defaults to MACE. Skill of AXE will allow it to be used to chop down trees.

|-
| {{text anchor|RANGED}}
|
*[[Skill token]]
*Ammo class
| Makes this a ranged weapon that uses the specified ammo. The specified skill determines accuracy in ranged combat.

|-
| {{text anchor|TWO_HANDED}}
|
*size
| Creatures under this size (in cm^3) must use the weapon two-handed. Defaults to 50000.

|-
| {{text anchor|MINIMUM_SIZE}}
|
*size
| Minimum body size (in cm^3) to use the weapon at all (multigrasp required until TWO_HANDED value). Defaults to 40000.

|-
| {{text anchor|CAN_STONE}}
|
| Allows the weapon to be made at a [[craftsdwarf's workshop]] from a sharp ([MAX_EDGE:10000] or higher) stone (e.g. [[obsidian]]) plus a wood log.

|-
| {{text anchor|TRAINING}}
|
| Restricts this weapon to being made of wood.

|-
| {{text anchor|MATERIAL_SIZE}}
|
*value
| Number of bar units needed for forging. Due to a bug, this does not actually work properly. Required.

|-
| {{text anchor|ATTACK}}
|
*attacktype:BLUNT or EDGE
*contact_area:value
*penetration_size:value
*verb2nd:string
*verb3rd:string
*noun:string
*velocity_multiplier:value
| You can have many ATTACK tags and one will be randomly selected for each attack, with EDGE attacks 100 times more common than BLUNT attacks. Contact area is usually high for slashing and low for bludgeoning, piercing, and poking. Penetration value tends to be low for slashing and high for stabbing. Penetration is ignored if attack is BLUNT. Required.

|}

{{Category|Modding}}
{{Category|Tokens}}

v0.34:Weapon token

2026-04-04T01:02:56Z

Quietust: get rid of this

{{quality|Exceptional|19:42, 24 August 2010 (UTC)}}{{av}}

These tokens can only be placed within an ITEM_WEAPON object definition.
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|NAME}}
|
*singular
*plural
| Name of the weapon. Required.

|-
| {{text anchor|ADJECTIVE}}
|
*adjective
| Adjective of the weapon, e.g. the "large" in "large copper dagger".

|-
| {{text anchor|SIZE}} / {{text anchor|WEIGHT}}
|
*size
| Volume of weapon in mL or cubic cm. Defaults to 100.

|-
| {{text anchor|SHOOT_FORCE}}
|
*value
| The amount of force used when firing projectiles - velocity is presumably determined by the projectile's mass. Defaults to 0.

|-
| {{text anchor|SHOOT_MAXVEL}}
|
*value
| The maximum speed a fired projectile can have.

|-
| {{text anchor|SKILL}}
|
*[[Skill token]]
| The skill to determine effectiveness in melee with this weapon. Defaults to MACE. Skill of AXE will allow it to be used to chop down trees.

|-
| {{text anchor|RANGED}}
|
*[[Skill token]]
*Ammo class
| Makes this a ranged weapon that uses the specified ammo. The specified skill determines accuracy in ranged combat.

|-
| {{text anchor|TWO_HANDED}}
|
*size
| Creatures under this size (in cm^3) must use the weapon two-handed. Defaults to 50000.

|-
| {{text anchor|MINIMUM_SIZE}}
|
*size
| Minimum body size (in cm^3) to use the weapon at all (multigrasp required until TWO_HANDED value). Defaults to 40000.

|-
| {{text anchor|CAN_STONE}}
|
| Allows the weapon to be made at a [[craftsdwarf's workshop]] from a sharp ([MAX_EDGE:10000] or higher) stone (e.g. [[obsidian]]) plus a wood log.

|-
| {{text anchor|TRAINING}}
|
| Restricts this weapon to being made of wood.

|-
| {{text anchor|MATERIAL_SIZE}}
|
*value
| Number of bar units needed for forging, as well as the amount gained from melting. Required.

|-
| {{text anchor|ATTACK}}
|
*attacktype:BLUNT or EDGE
*contact_area:value
*penetration_size:value
*verb2nd:string
*verb3rd:string
*noun:string
*velocity_multiplier:value
| You can have many ATTACK tags and one will be randomly selected for each attack, with EDGE attacks 100 times more common than BLUNT attacks. Contact area is usually high for slashing and low for bludgeoning, piercing, and poking. Penetration value tends to be low for slashing and high for stabbing. Penetration is ignored if attack is BLUNT. Required.

|}

{{Category|Modding}}
{{Category|Tokens}}

v0.31:Trap component token

2026-04-04T01:02:17Z

Quietust:

{{quality|Exceptional|18:26, 28 April 2011 (UTC)}}{{av}}

For use on trap components.

{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|NAME}}
| singular:plural
| What this item will be called in-game.

|-
| {{text anchor|ADJECTIVE}}
| adjective
| Appears before the name of the weapon's material. E.g. "menacing steel spike"

|-
| {{text anchor|SIZE}} / {{text anchor|WEIGHT}}
| value
| How large the item is. Defaults to 100.

|-
| {{text anchor|HITS}}
| value
| Number of times it hits. Defaults to 1

|-
| {{text anchor|MATERIAL_SIZE}}
| value
| How much material is needed to make the item. Is most important with bars. The number of bars needed is the value divided by three. Required.

|-
| {{text anchor|IS_SCREW}}
|
| Weapon may be installed in a screw pump.

|-
| {{text anchor|IS_SPIKE}}
|
| Weapon may be installed in a spike trap.

|-
| {{text anchor|WOOD}}
|
| Weapon may be made out of wood.

|-
| {{text anchor|METAL}}
|
| Weapon may be made out of metal.

|-
| {{text anchor|ATTACK}}
|
* attacktype:EDGE (or BLUNT?)
* contact_area:value
* penetration_size:value
* verb2nd:string
* verb3rd:string
* noun:string
* velocity_multiplier:value
| Sets the attack characteristics of the weapon
|}

{{Category|Modding}}
{{Category|Tokens}}

v0.34:Trap component token

2026-04-04T01:02:01Z

Quietust:

v0.31:Tool token

2026-04-04T01:01:25Z

Quietust:

{{quality|Exceptional|21:46, 21 November 2010 (UTC)}}{{av}}

{| {{prettytable}}
|- bgcolor="#999999"
! Token
! Arguments
! Description

|-
| {{text anchor|NAME}}
|
*singular
*plural
| Name of the tool. Required.

|-
| {{text anchor|HARD_MAT}}
|
| Permits the tool to be made from anything with the [ITEMS_HARD] token, such as wood, stone or metal.

|-
| {{text anchor|METAL_MAT}}
|
| Permits the tool to be made from anything with the [IS_METAL] token.

|-
| {{text anchor|METAL_WEAPON_MAT}}
|
| Permits the tool to be made from any metal with the [ITEMS_WEAPON] token.

|-
| {{text anchor|UNIMPROVABLE}}
|
| Prevents the tool from being improved. Used on honeycombs.

|-
| {{text anchor|VALUE}}
|
*num
| Defines the item value of the tool. Required.

|-
| {{text anchor|TILE}}
|
*num
| Defines the tile used to represent the tool. Required.

|-
| {{text anchor|TOOL_USE}}
|
*tool use, see below
| Defines the task performed using the tool.

|-
| {{text anchor|ADJECTIVE}}
|
*adjective
| Adjective preceding the material name (e.g. "large copper dagger")

|-
| {{text anchor|SIZE}} // {{text anchor|WEIGHT}}
|
*size
| Volume of tool in mL or cubic centimeters. Required.

|-
| {{text anchor|CONTAINER_CAPACITY}}
|
*amount
| How much the item can contain. Defaults to 0.

|-
| {{text anchor|SHOOT_FORCE}}
|
*value
| Required for weapons.

|-
| {{text anchor|SHOOT_MAXVEL}}
|
*value
| Required for weapons.

|-
| {{text anchor|SKILL}}
|
*Skill token
| The skill to determine effectiveness in melee with this tool. Required for weapons.

|-
| {{text anchor|RANGED}}
|
*Skill token
*Ammo item token
| Makes this tool a ranged weapon that uses the specified ammo. The specified skill determines accuracy in ranged combat.

|-
| {{text anchor|TWO_HANDED}}
|
*size
| Creatures under this size (in cm^3) must use the tool two-handed. Required for weapons.

|-
| {{text anchor|MINIMUM_SIZE}}
|
*size
| Minimum body size (in cm^3) to use the tool at all (multigrasp required until TWO_HANDED value) Required for weapons.

|-
| {{text anchor|MATERIAL_SIZE}}
|
*value
| Intended to specify number of bar units needed for forging. Does '''not''' work due to a bug.

|-
| {{text anchor|ATTACK}}
|
*attacktype:BLUNT or EDGE
*contact_area:value
*penetration_size:value
*verb2nd:string
*verb3rd:string
*noun:string
*velocity_multiplier:value
| You can have many ATTACK tags and one will be randomly selected for each attack, with EDGE attacks 100 times more common than BLUNT attacks. Required for weapons.
|}

Valid tool uses (and the default tools used for these tasks) are as follows:
{| class="wikitable sortable"
|- bgcolor="#999999"
! ID
! Token
! Usage
|-
| 0 || LIQUID_COOKING || cauldron || adventure mode decoration / weapon
|-
| 1 || LIQUID_SCOOP || ladle || adventure mode decoration / weapon
|-
| 2 || GRIND_POWDER_RECEPTACLE || mortar || adventure mode decoration / weapon
|-
| 3 || GRIND_POWDER_GRINDER || pestle || adventure mode decoration / weapon
|-
| 4 || MEAT_CARVING || carving knife || adventure mode decoration / weapon
|-
| 5 || MEAT_BONING || boning knife || adventure mode decoration / weapon
|-
| 6 || MEAT_SLICING || slicing knife || adventure mode decoration / weapon
|-
| 7 || MEAT_CLEAVING || meat cleaver || adventure mode decoration / weapon
|-
| 8 || HOLD_MEAT_FOR_CARVING || carving fork || adventure mode decoration / weapon
|-
| 9 || MEAL_CONTAINER || bowl || adventure mode decoration / weapon
|-
| 10 || LIQUID_CONTAINER || [[jug]] || can store honey or oil
|-
| 11 || FOOD_STORAGE || [[large pot]] || can store beer
|-
| 12 || HIVE || [[hive]] || can make honey
|-
| 13 || NEST_BOX || [[nest box]] || for your birds to lay eggs
|}

{{Category|Modding}}
{{Category|Tokens}}

v0.34:Tool token

2026-04-04T00:59:07Z

Quietust:

{{quality|Exceptional|21:46, 21 November 2010 (UTC)}}{{av}}

{| {{prettytable}}
|- bgcolor="#999999"
! Token
! Arguments
! Description

|-
| {{text anchor|NAME}}
|
*singular
*plural
| Name of the tool. Required.

|-
| {{text anchor|HARD_MAT}}
|
| Permits the tool to be made from anything with the [ITEMS_HARD] token, such as wood, stone or metal.

|-
| {{text anchor|METAL_MAT}}
|
| Permits the tool to be made from anything with the [IS_METAL] token.

|-
| {{text anchor|METAL_WEAPON_MAT}}
|
| Permits the tool to be made from any metal with the [ITEMS_WEAPON] token.

|-
| {{text anchor|UNIMPROVABLE}}
|
| Prevents the tool from being improved. Used on honeycombs.

|-
| {{text anchor|VALUE}}
|
*num
| Defines the item value of the tool. Required.

|-
| {{text anchor|TILE}}
|
*num
| Defines the tile used to represent the tool. Required.

|-
| {{text anchor|INVERTED_TILE}}
|
| The background of the tile will be colored, instead of the foreground.

|-
| {{text anchor|TOOL_USE}}
|
*tool use, see below
| Defines the task performed using the tool.

|-
| {{text anchor|FURNITURE}}
|
| Allows item to be stored in a furniture stockpile.

|-
| {{text anchor|ADJECTIVE}}
|
*adjective
| Adjective preceding the material name (e.g. "large copper dagger")

|-
| {{text anchor|SIZE}}
|
*size
| Volume of tool in mL or cubic centimeters. Required.

|-
| {{text anchor|CONTAINER_CAPACITY}}
|
*amount
| How much the item can contain. Defaults to 0.

|-
| {{text anchor|SHOOT_FORCE}}
|
*value
| Required for weapons.

|-
| {{text anchor|SHOOT_MAXVEL}}
|
*value
| Required for weapons.

|-
| {{text anchor|SKILL}}
|
*Skill token
| The skill to determine effectiveness in melee with this tool. Required for weapons.

|-
| {{text anchor|RANGED}}
|
*Skill token
*Ammo item token
| Makes this tool a ranged weapon that uses the specified ammo. The specified skill determines accuracy in ranged combat.

|-
| {{text anchor|TWO_HANDED}}
|
*size
| Creatures under this size (in cm^3) must use the tool two-handed. Required for weapons.

|-
| {{text anchor|MINIMUM_SIZE}}
|
*size
| Minimum body size (in cm^3) to use the tool at all (multigrasp required until TWO_HANDED value) Required for weapons.

|-
| {{text anchor|MATERIAL_SIZE}}
|
*value
| Number of bar units needed for forging, as well as the amount gained from melting. Required for weapons.

|-
| {{text anchor|ATTACK}}
|
*attacktype:BLUNT or EDGE
*contact_area:value
*penetration_size:value
*verb2nd:string
*verb3rd:string
*noun:string
*velocity_multiplier:value
| You can have many ATTACK tags and one will be randomly selected for each attack, with EDGE attacks 100 times more common than BLUNT attacks. Required for weapons.
|}

Valid tool uses (and the default tools used for these tasks) are as follows:
{| class="wikitable sortable"
|- bgcolor="#999999"
! ID
! Token
! Usage
|-
| 0 || LIQUID_COOKING || cauldron || adventure mode decoration / weapon
|-
| 1 || LIQUID_SCOOP || ladle || adventure mode decoration / weapon
|-
| 2 || GRIND_POWDER_RECEPTACLE || mortar || adventure mode decoration / weapon
|-
| 3 || GRIND_POWDER_GRINDER || pestle || adventure mode decoration / weapon
|-
| 4 || MEAT_CARVING || carving knife || adventure mode decoration / weapon
|-
| 5 || MEAT_BONING || boning knife || adventure mode decoration / weapon
|-
| 6 || MEAT_SLICING || slicing knife || adventure mode decoration / weapon
|-
| 7 || MEAT_CLEAVING || meat cleaver || adventure mode decoration / weapon
|-
| 8 || HOLD_MEAT_FOR_CARVING || carving fork || adventure mode decoration / weapon
|-
| 9 || MEAL_CONTAINER || bowl || adventure mode decoration / weapon
|-
| 10 || LIQUID_CONTAINER || [[jug]] || can store honey or oil
|-
| 11 || FOOD_STORAGE || [[large pot]] || can store beer
|-
| 12 || HIVE || [[hive]] || can make honey
|-
| 13 || NEST_BOX || [[nest box]] || for your birds to lay eggs
|-
| 14 || SMALL_OBJECT_STORAGE || [[pouch]] || adventure mode coin purse
|-
| 15 || TRACK_CART || [[minecart]] || item hauling / weapon
|-
| 16 || HEAVY_OBJECT_HAULING || [[wheelbarrow]] || allows hauling items faster
|}

{{Category|Modding}}
{{Category|Tokens}}

v0.31:Armor token

2026-04-04T00:53:54Z

Quietust:

{{Quality|Exceptional|08:43, 9 June 2010 (UTC)}}{{av}}

The tokens for all types of [[armor]] on all slots, including [[shield]]s. Usage column gives information on what types of '''armor''' the token might be restricted to.

These tokens can only be placed within an ITEM_ARMOR, ITEM_GLOVES, ITEM_SHOES, ITEM_SHIELD, ITEM_HELM, or ITEM_PANTS object definition, most do not function in weapon objects.

==Tokens==
{| {{prettytable}}
|- bgcolor="#999999"
! Token
! Arguments
! Usage
! Description

|-
| {{text anchor|NAME}}
| singular:plural
| {{tc|red|Required}}
| What this item will be called ingame.

|-
| {{text anchor|PREPLURAL}}
| <phrase> of
| ITEM_ARMOR ITEM_PANTS
| Changes the plural form of this item to "<phrase of> item". Primarily pertains to the stock screens. Example, "suits of" platemail, "pairs of" trousers, etc.

|-
| {{text anchor|MATERIAL_PLACEHOLDER}}
| adjective
| ITEM_ARMOR ITEM_PANTS
| If the item has no material associated with it (e.g. stockpile menus and trade negotiations), this will be displayed in its place. Used for leather armor.

|-
| {{text anchor|VALUE}}
|
|
| Unused. Defaults to -1.

|-
| {{text anchor|ARMORLEVEL}}
|
0 - clothing 
1 - leather 
2 - chain 
3 - plate
| All garments and shields
| The garment's general purpose. Defaults to 1 for shields, 0 for everything else. Class 0 items are claimed and used by civilians as ordinary clothing and are subject to [[wear]].

|-
| {{text anchor|UPSTEP}}
| value, MAX
| ITEM_GLOVES ITEM_SHOES ITEM_SHIELD
| Length of gloves or footwear, counted in [LIMB] body parts towards the torso. A value of 1 lets gloves cover the lower arms, a value of 2 stretches a boot all the way over the upper leg and so on. Regardless of the value, none of these items can ever extend to cover the upper or lower body. Shields also have this token, but it only seems to affect weight.

|-
| {{text anchor|UBSTEP}}
| value, MAX
| ITEM_ARMOR
| Length of the sleeves, counted in [LIMB] body parts towards the hands. A value of 0 only protects both halves of the torso, 1 extends over the upper arms and so on. Regardless of the value, body armor can never extend to cover the hands or head.

Currently bugged{{bug|1821}}, high values of UBSTEP will result in the item protecting facial features, fingers, and toes, while leaving those parts that it can not protect unprotected (but still counting them as steps).

|-
| {{text anchor|LBSTEP}}
| value or MAX
| ITEM_ARMOR ITEM_PANTS
| Length of the legs/hem, counted in [LIMB] body parts towards the feet. A value of 0 only covers the lower body, 1 extends over the upper legs and so on. Regardless of the value, body armor or pants can never extend to cover the feet.

|-
| {{text anchor|METAL_ARMOR_LEVELS}}
|
| All garments
| Metal versions of this item count as one ARMORLEVEL higher and thus won't be worn by random peasants.

|-
| {{text anchor|BLOCKCHANCE}}
| value
| ITEM_SHIELD
| Affects the block chance of the shield. Defaults to 10.

|-
| {{text anchor|MATERIAL_SIZE}}
| value
| {{tc|red|Required}}
| How much material is needed to make the item. Most important with bars. The number of bars required to make the item is the value divided by three.

|-
| {{text anchor|SOFT}}
|
| All garments
| Clothiers can make this item from all kinds of cloth. If paired with [LEATHER], the item has an equal chance of being either in randomly generated outfits. Further uses of this tag are unknown.

|-
| {{text anchor|HARD}}
|
| All garments
| Default state in the absence of a [SOFT] token. Actual effects unknown.

|-
| {{text anchor|METAL}}
|
| All garments
| Item can be made from metal. Overrides [SOFT] and [LEATHER] in randomly generated outfits, if the ARMORLEVEL permits. Civilizations with [[Entity_token#WOOD_ARMOR|[WOOD_ARMOR]]] will make this item out of wood instead.

|-
| {{text anchor|BARRED}}
|
| All garments
| Craftsmen can make this item from bones. Randomly generated outfits don't include bone armor.

|-
| {{text anchor|SCALED}}
|
| All garments
| Craftsmen can make this item from shells. Randomly generated outfits don't include shell armor.

|-
| {{text anchor|LEATHER}}
|
| All garments
| Leatherworkers can make this item from leather. If paired with [SOFT], this item has an equal chance of being either in randomly generated outfits.

|-
| {{text anchor|SHAPED}}
|
| All garments
| Only one shaped piece of clothing can be worn on a single body slot at a time.

|-
| {{text anchor|CHAIN_METAL_TEXT}}
|
| All garments
| Metal versions of this item will have "chain" added between the material and item name.

|-
| {{text anchor|STRUCTURAL_ELASTICITY_WOVEN_THREAD}}
|
| All garments
| Reduces the armor material's SHEAR_YIELD to 20000, SHEAR_FRACTURE to 30000 and increases the *_STRAIN_AT_YIELD properties to 50000, but only if the garment is made from cloth. This makes the item very weak against edged attacks, even if the thread material is normally very strong.

|-
| {{text anchor|STRUCTURAL_ELASTICITY_CHAIN_METAL}}
|
| All garments
| Increases the *_STRAIN_AT_YIELD properties of the armor's material to 50000, but only if the garment is made from metal.

|-
| {{text anchor|STRUCTURAL_ELASTICITY_CHAIN_ALL}}
|
| All garments
| Increases the *_STRAIN_AT_YIELD properties of the armor's material to 50000, if lower. This makes the garment flex and give way instead of shattering under force. Strong materials that resist cutting will blunt edged attacks into bone-crushing hits instead.

|-
| {{text anchor|LAYER_SIZE}}
| value
| All garments
| The item's bulkiness when worn. Aside from the layer limitations, it's a big contributor to the thickness and weight (and therefore price) of the garment. See [[Armor]] for more on item sizes and layering. Defaults to 10.

|-
| {{text anchor|LAYER_PERMIT}}
| value
| All garments
| The maximum amount of crap that can fit underneath the garment. See [[Armor]] for more on item sizes and layering. Defaults to 10.

|-
| {{text anchor|LAYER}}
| UNDER OVER ARMOR COVER
| All garments
| Where the item goes in relation to other clothes. Socks cannot be worn on top of boots!
The LAYER_PERMIT of the highest layer is used on a given section of the body - you can fit a lot of shirts and other undergarments underneath a robe, but not if you wear a leather jerkin on top of it, and you can still wear a cloak over the whole ensemble. Defaults to UNDER.

|-
| {{text anchor|COVERAGE}}
| % value
| All garments
| How often the garment gets in the way of a contaminant or an attack. Armor with a 5% coverage value, for example, will be near useless because 95% of attacks will bypass it completely. Temperature effects and armor thickness are also influenced. Defaults to 100.

|}

{{Category|Modding}}
{{Category|Tokens}}

v0.31:Ammo token

2026-04-04T00:49:15Z

Quietust:

{{Quality|Superior|02:31, 18 April 2013 (UTC)}}{{av}}

{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|NAME}}
| singular:plural
| What this item will be called ingame.

|-
| {{text anchor|CLASS}}
| anything
| This ammo can be fired from a weapon that is set to fire the same ammo type as this. Defaults to BOLT.

|-
| {{text anchor|SIZE}} / {{text anchor|WEIGHT}}
| value
| How large the ammunition is. Required.

|-
| {{text anchor|ATTACK}}
|
*attacktype:BLUNT or EDGE
*contact_area:value
*penetration_size:value
*verb2nd:string
*verb3rd:string
*noun:string
*velocity_multiplier:value
| Specifies the attack characteristics of the ammunition.
|}

{{Category|Modding}}
{{Category|Tokens}}

v0.31:Descriptor pattern token

2026-04-04T00:48:06Z

Quietust: Created page with "{{Quality|Superior|18:45, 10 February 2022 (UTC)}}{{av}} Tokens used to define descriptor patterns, that may be used instead of descriptor colors. As a..."

{{Quality|Superior|18:45, 10 February 2022 (UTC)}}{{av}}

Tokens used to define descriptor patterns, that may be used instead of [[Color#Color_tokens|descriptor colors]]. As an example, the descriptor pattern STRIPES_ORANGE_BLACK is what gives tigers their stripes.
{{clear}}

==Tokens==
{| {{prettytable}}
|- bgcolor="#999999"
! Token
! Arguments
! Usage
! Description

|-
| {{text anchor|PATTERN}}
| SPOTS, STRIPES, MOTTLED, IRIS_EYE or PUPIL_EYE
| {{tc|red|Required}}
| The type of pattern, deciding the description.
* SPOTS: Causes a crash if no CP_COLOR is given{{bug|11806}}, otherwise takes any amount.
* STRIPES: Takes any amount of CP_COLOR tokens.
* IRIS_EYE: Only shows the third CP_COLOR given; technically takes any amount. Causes a crash if no CP_COLOR is given{{bug|11806}}. If only one or two CP_COLORs is given, the tissue is described as being "transparent".
* PUPIL_EYE: Only shows the second CP_COLOR given; technically takes any amount. Causes a crash if no CP_COLOR is given{{bug|11806}}. If only one CP_COLORs is given, the tissue is described as being "transparent".
An undefined pattern type causes the description to simply not show up.

|-
| {{text anchor|CP_COLOR}}
| [[Color#Color_tokens|color token]]
| {{tc|red|Required (mostly)}}
| A color to be used in the pattern. See [[Descriptor_pattern_token#PATTERN|PATTERN]] for how many CP_COLOR tokens are needed, and how they are used. [[descriptor color token|Modded color tokens]] may be used.
|}

{{Category|Modding}}
{{Category|Tokens}}
[[ru:Descriptor pattern token]]

v0.34:Descriptor pattern token

2026-04-04T00:47:59Z

Quietust:

{{Quality|Superior|18:45, 10 February 2022 (UTC)}}{{av}}

Tokens used to define descriptor patterns, that may be used instead of [[Color#Color_tokens|descriptor colors]]. As an example, the descriptor pattern STRIPES_ORANGE_BLACK is what gives tigers their stripes.
{{clear}}

==Tokens==
{| {{prettytable}}
|- bgcolor="#999999"
! Token
! Arguments
! Usage
! Description

|-
| {{text anchor|PATTERN}}
| SPOTS, STRIPES, MOTTLED, IRIS_EYE or PUPIL_EYE
| {{tc|red|Required}}
| The type of pattern, deciding the description.
* SPOTS: Causes a crash if no CP_COLOR is given{{bug|11806}}, otherwise takes any amount.
* STRIPES: Takes any amount of CP_COLOR tokens.
* MOTTLED: Takes any amount of CP_COLOR tokens.
* IRIS_EYE: Only shows the third CP_COLOR given; technically takes any amount. Causes a crash if no CP_COLOR is given{{bug|11806}}. If only one or two CP_COLORs is given, the tissue is described as being "transparent".
* PUPIL_EYE: Only shows the second CP_COLOR given; technically takes any amount. Causes a crash if no CP_COLOR is given{{bug|11806}}. If only one CP_COLORs is given, the tissue is described as being "transparent".
An undefined pattern type causes the description to simply not show up.

|-
| {{text anchor|CP_COLOR}}
| [[Color#Color_tokens|color token]]
| {{tc|red|Required (mostly)}}
| A color to be used in the pattern. See [[Descriptor_pattern_token#PATTERN|PATTERN]] for how many CP_COLOR tokens are needed, and how they are used. [[descriptor color token|Modded color tokens]] may be used.
|}

{{Category|Modding}}
{{Category|Tokens}}
[[ru:Descriptor pattern token]]

v0.34:Descriptor pattern token

2026-04-04T00:47:51Z

Quietust: Created page with "{{Quality|Superior|18:45, 10 February 2022 (UTC)}} {{av}} {{Modding}} Tokens used to define descriptor patterns, that may be used instead of Color#Color_tokens|descriptor co..."

{{Quality|Superior|18:45, 10 February 2022 (UTC)}}
{{av}}
{{Modding}}
Tokens used to define descriptor patterns, that may be used instead of [[Color#Color_tokens|descriptor colors]]. As an example, the descriptor pattern STRIPES_ORANGE_BLACK is what gives tigers their stripes.
{{clear}}

==Tokens==
{| {{prettytable}}
|- bgcolor="#999999"
! Token
! Arguments
! Usage
! Description

|-
| {{text anchor|PATTERN}}
| SPOTS, STRIPES, MOTTLED, IRIS_EYE or PUPIL_EYE
| {{tc|red|Required}}
| The type of pattern, deciding the description.
* SPOTS: Causes a crash if no CP_COLOR is given{{bug|11806}}, otherwise takes any amount.
* STRIPES: Takes any amount of CP_COLOR tokens.
* MOTTLED: Takes any amount of CP_COLOR tokens.
* IRIS_EYE: Only shows the third CP_COLOR given; technically takes any amount. Causes a crash if no CP_COLOR is given{{bug|11806}}. If only one or two CP_COLORs is given, the tissue is described as being "transparent".
* PUPIL_EYE: Only shows the second CP_COLOR given; technically takes any amount. Causes a crash if no CP_COLOR is given{{bug|11806}}. If only one CP_COLORs is given, the tissue is described as being "transparent".
An undefined pattern type causes the description to simply not show up.

|-
| {{text anchor|CP_COLOR}}
| [[Color#Color_tokens|color token]]
| {{tc|red|Required (mostly)}}
| A color to be used in the pattern. See [[Descriptor_pattern_token#PATTERN|PATTERN]] for how many CP_COLOR tokens are needed, and how they are used. [[descriptor color token|Modded color tokens]] may be used.
|}

{{Category|Modding}}
{{Category|Tokens}}
[[ru:Descriptor pattern token]]

v0.31:Creature variation token

2026-04-04T00:46:05Z

Quietust:

{{av}}
Creature variations are used to create creatures which are derived from another already-existing creature without having to duplicate every single token. They are defined as CREATURE_VARIATION objects, and the default variations are defined in c_variation_default.txt

{| {{prettytable}}
|- bgcolor="#999999"
! Token
! Arguments
! Description

|-
| {{text anchor|CV_NEW_TAG}}
|
*token (plus any additional parameters)
| Adds a new token to the creature's variant.

|-
| {{text anchor|CV_ADD_TAG}}
|
*token
| Alias for CV_NEW_TAG

|-
| {{text anchor|CV_REMOVE_TAG}}
|
*token
| Removes a token from the creature's variant.

|-
| {{text anchor|CV_CONVERT_TAG}}
|
| Begins altering tokens within the creature's variant using the CVCT_MASTER, CVCT_TARGET, and CVCT_REPLACEMENT tokens below. If a variation template contains multiple CV_CONVERT_TAG blocks for the same CVCT_MASTER, the replacements will be applied [http://bay12games.com/dwarves/mantisbt/view.php?id=6393#c24231 in reverse order].

|-
| {{text anchor|CVCT_MASTER}}
|
*token
| Specifies the token that will be modified.

|-
| {{text anchor|CVCT_TARGET}}
|
*value
| Locates the specified parameter within the token specified by CVCT_MASTER.

|-
| {{text anchor|CVCT_REPLACEMENT}}
|
*value
| Replaces the parameter specified by CVCT_TARGET within the token specified by CVCT_MASTER. If no replacement is specified, the target will simply be removed.
|}

{{Category|Modding}}
{{Category|Tokens}}

v0.31:Body detail plan token

2026-04-04T00:44:56Z

Quietust:

{{quality|Exceptional|17:58, 28 April 2011 (UTC)}}{{av}}

{| {{prettytable}}
|- bgcolor="#ddd"
! width="20%" | Token
! width="20%" | Arguments
! width="60%" | Description

|-
| {{text anchor|ADD_MATERIAL}}
|
* identifier
* material template
| Adds a new material to the creature based on the specified template and assigned to the specified identifier.

|-
| {{text anchor|ADD_TISSUE}}
|
* identifier
* tissue template
| Adds a new tissue to the creature based on the specified template and assigned to the specified identifier.

|-
| {{text anchor|BODY_DETAIL_PLAN}}
|
| Begins defining a body detail plan for use in creature raws

|-
| {{text anchor|BP_LAYERS}}
|
*BY_CATEGORY or BY_TYPE or BY_TOKEN
*body part
*tissue name or tissue ARG# for innermost tissue
*tissue thickness
*tissue name or tissue ARG# for second innermost tissue
*tissue thickness
*tissue name or tissue ARG# for third innermost tissue
*tissue thickness
etc...
| Defines a series of tissue layers. Alternatively to specifying a tissue, variable arguments can be entered (numbered arbitrarily to a max of 5) to be filled with tissues when the plan is called in the creature entry. The SELECT_TISSUE creature token with TL_RELATIVE_THICKNESS can change tissue thickness, but tissue ''layering'' is hard to do without a new detail plan.

|-
| {{text anchor|BP_LAYERS_OVER}}
|
| Works like BP_LAYERS, but defines layers over existing layers.

|-
| {{text anchor|BP_LAYERS_UNDER}}
|
| Works like BP_LAYERS, but defines layers under existing layers.

|-
| {{text anchor|BP_POSITION}}
|
*BY_CATEGORY or BY_TYPE or BY_TOKEN
*body part
*position token
| Defines a position for the specified body part (the nose is assigned the position FRONT, as it's on the front of the face). This has some effects on combat, attacks and the like. Valid position tokens are FRONT, BACK, SIDES, TOP and BOTTOM.

|-
| {{text anchor|BP_RELATION}}
|
*BY_CATEGORY or BY_TYPE or BY_TOKEN
*body part to be affected
*relation token
*BY_CATEGORY or BY_TYPE or BY_TOKEN
*parent body part
*coverage
| Defines a positional relationship between one body part and another (the right eyelid is AROUND the right eye with coverage 50, as it only partially covers the eye). This has some effects on combat, attacks and the like. Valid relation tokens are AROUND, SURROUNDED_BY, ABOVE, BELOW, IN_FRONT, BEHIND, CLEANS, and CLEANED_BY. The lattermost two tokens are used when specifying parts that clean each other (such as eyelids to eyes).

|-
| {{text anchor|BP_RELSIZE}}
|
*BY_CATEGORY (or, presumably, BY_TYPE or BY_TOKEN)
*body part
*relsize
| Defines a relsize for the selected body part for the current body detail plan
|}

{{Category|Modding}}
{{Category|Tokens}}

v0.34:Body detail plan token

2026-04-04T00:44:21Z

Quietust:

40d:Body token

2026-04-04T00:43:51Z

Quietust: /* Body Parts */

{{quality|Exceptional|21:17, 30 March 2011 (UTC)}}{{av}}
{{Category|Modding}}

'''Body tokens''' are one of the fundamental parts of creatures, and determine their bodily structure. There are two major types of body tokens: ''body templates'' (BODY) and ''body parts'' (BP).

A creature uses the [[creature token#B|BODY creature token]] to list all of the body templates it includes. Each part listed in each template is then included in the creature. In other words: a creature lists the ''body templates'' it is made of. Each ''body template'' contains a set of ''body parts''. Each ''body part'' specifies which other body part it is attached to.

Body parts can connect specifically to another body part, or generally to any body part of a certain category. These connections are handled by the CON and CONTYPE body part tokens respectively.

Body parts can be renamed with a ''[[bodygloss]]'', allowing someone to reuse an existing template instead of defining a similar template with only the names of the body parts changed.

== Convention ==

The convention in the unmodded raw object data in Dwarf Fortress is to make the centre of mass the core of the creature. All other body parts then attach to this central mass, or to those body parts that attach to this central mass. Creating chains of attachments in this fashion produces limbs. If a part is listed before a part that it is attached to is, this can create strange bugs, such as the creatures instantly suffocating.

While it is possible to use the CON token to connect to a specific body part ID even if it is in another template, it is convention within the default raw object data to use a CONTYPE if the connected part is in another template, for safety. Otherwise, a creature must have both templates within its BODY token to prevent unpredictable behaviour when the creature is used during world generation or simulated during gameplay.

==Basic Syntax==

filename

[OBJECT:BODY]

[BODY:TEMPLATE1]
[BP:CORE][UPPERBODY][...]
[BP:PART1][CONTYPE:UPPERBODY][...]
[BP:PART2][CON:CORE][...]

[BODYGLOSS:FOOBAR:foo:bar]

==Body==

{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| BODY
|
* id
| The name of the body template. Each BP token underneath a given Body Token BODY template is added to a creature when the Creature Token BODY specifies this ID.

|-
| BODYGLOSS
|
* id
* match
* replacement
| Replaces all occurrences of "match" in the creature's body parts with "replacement". E.g., the Body Token [BODYGLOSS:TENTACLE:leg:tentacle], used by the Creature Token [BODYGLOSS:TENTACLE], will cause any "right leg" to appear as "right tentacle". Testing required: would "brain legend" appear as "brain tentacleend"?{{verify}}

|-
|}

==Body Parts==

{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|BP}}
|
* id
* name
| The internal object ID of the body part. Unlike many other tokens in the game, the id of the BP does not need to be unique throughout all of the raw object files, though it does need to be unique within the BODY it is in, as well as within the set of body templates used by any given creature.

|-
| {{text anchor|UPPERBODY}}
|
| The body part is the "core" of the creature; when the upperbody body part is destroyed, the creature is blown apart.
A creature doesn't die until an UPPERBODY, HEAD, or LOWERBODY is destroyed, so a creature without one or all of these
can't be killed*. UPPERBODYs aren't redundant, once one is destroyed the creature dies. Body parts with [CONTYPE:UPPERBODY] will be connected to these.
*most creatures can also be killed indirectly by suffocation or blood loss. (or brain damage?).

|-
| {{text anchor|LOWERBODY}}
|
| The body part is another part of the "core" of the creature. When the lowerbody body part is destroyed, the creature is bisected. A creature doesn't die until an UPPERBODY, HEAD, or LOWERBODY is destroyed, so a creature without one or all of these can't be killed*. LOWERBODYs aren't redundant, once one is destroyed the creature dies. Body parts with [CONTYPE:LOWERBODY] will be connected to these.
*most creatures can also be killed indirectly by suffocation or blood loss. (or brain damage?).

|-
| {{text anchor|HEAD}}
|
| Vital bodypart. If severed, creature dies. A creature doesn't die until an UPPERBODY, HEAD, or LOWERBODY is destroyed, so a creature without one or all of these can't be killed*. HEADs aren't redundant, once one is destroyed the creature dies. Body parts with [CONTYPE:HEAD] will be connected to these.
*most creatures can also be killed indirectly by suffocation or blood loss. (or brain damage?).

|-
| {{text anchor|CON}}
|
* id
| The specific body part ''object ID'' to which this body part attaches. This tag is optional. Interesting effects can be created by leaving unconnected body parts. If an invalid ID is given, the body part is unconnected. This can lead to interesting bugs.

|-
| {{text anchor|CONTYPE}}
|
* type
| The body part ''token type'' to which this body part attaches - valid values are UPPERBODY, LOWERBODY, HEAD, GRASP, and STANCE. Note that if the creature has more than one body part with that token type each of them will get its own additional body part attached. For example, if a creature has two upper bodies (two torsos) and a lower body, the CONTYPE:UPPERBODY means that the two upper torsos are connected to the lower torso by default. This tag is optional. Interesting effects can be created by leaving unconnected body parts.

|-
| {{text anchor|LIMB}}
|
| The body part is usable for [[wrestling]] (i.e. can grab, lock, choke, etc.).

|-
| {{text anchor|THROAT}}
|
| Can be strangled with [[wrestling]] to cause winding, unconsciousness, and eventual death. Strangely, even creatures with the NOBREATHE token can be rendered unconscious (but not dead) by strangulation.

|-
| {{text anchor|JOINT}}
|
| Can be broken by [[wrestling]].

|-
| {{text anchor|SKELETON}}
|
| Prevents game code from removing this bodypart when the creature is converted to skeletal undead.

|-
| {{text anchor|THOUGHT}}
|
| Necessary for the creature to think. Without a working brain, the creature dies unless it has the NOTHOUGHT Creature Token. Also seems to apply the effects of NERVOUS.

|-
| {{text anchor|NERVOUS}}
|
| Causes pain when destroyed and appears to stop a part from healing over time. However, it will heal normally if creature is NOTHOUGHT. Other effects?

|-
| {{text anchor|GRASP}}
|
| The body part can be used to hold items (if the creature has the EQUIPS token) or [[wrestling|wrestle]]. Body parts with [CONTYPE:GRASP] will be connected to these.

|-
| {{text anchor|FLIER}}
|
| The body part is necessary for the creature to fly, and damage to the body part will ground the creature.

|-
| {{text anchor|STANCE}}
|
| The body part is used to keep the creature standing; injury to the body part will cause the creature to collapse. It also makes the body part act like a foot, and can be problematic as the body part can be armored by a boot. STANCE body parts that are unconnected to the root (have no CON tag) do not count towards keeping the creature standing (NOTE: if '''any''' [STANCE] body parts are unconnected to root, the creature may fall over. Further testing required). Body parts with [CONTYPE:STANCE] will be connected to these.

|-
| {{text anchor|SIGHT}}
|
| Allows creatures to see; creatures without this tag on any part of their bodies cannot see for the purposes of aiming missile weapons (though apparently can find and kill mad adventurers fairly well with melee attacks). May need more testing.

|-
| {{text anchor|HEAR}}
|
| Unknown effect. Presumably allows the creature to listen. Also makes earrings equippable.

|-
| {{text anchor|SMELL}}
|
| Unknown effect. Presumably allows creature to smell.

|-
| {{text anchor|EMBEDDED}}
|
| The body part is embedded into the body -- it is external and can be gouged out. This does not make a part invisible.

|-
| {{text anchor|APERTURE}}
|
| An opening in the body. Cannot be destroyed except by destroying the part is attached to.

|-
| {{text anchor|SMALL}}
|
| Unknown effect. Reduces chance to hit? Also will cloak body parts much like the [INTERNAL] or the [EMBEDDED] tags will. Allows body parts to be pinched. In 40d it appears that body parts are visible unless [SMALL], even if they are [INTERNAL] or [EMBEDDED]. If the root (first BP) of the creature is [SMALL], it will not be targeted until all other parts have been severed or torn off.

|-
| {{text anchor|INTERNAL}}
|
| The body part is an internal organ and is not visible until injured. In 40d, it appears that the [SMALL] tag is what actually makes organs invisible, and that non-SMALL internal organs are visible even before being damaged.

|-
| {{text anchor|BREATHE}}
|
| The body part is necessary to breathe. If the body part is destroyed, the creature can suffocate unless it has the NOBREATHE token. The NOBREATHE token also causes the part to heal normally.

|-
| {{text anchor|CIRCULATION}}
|
| If this body part is destroyed, the creature will bleed to death?

|-
| {{text anchor|GUTS}}
|
| To be thought of like intestines. Can be disemboweled, causing a slow painful death from heavy bleeding.

|-
| {{text anchor|RIGHT}}
|
| The body part is on the right side of the creature and is thus vulnerable to attacks from the right side.

|-
| {{text anchor|LEFT}}
|
| The body part is on the left side of the creature and is thus vulnerable to attacks from the left side.

|-
| {{text anchor|DIGIT}}
|
| Is a finger/toe. Unknown effect. DIGITs '''may''' only be damaged when their connected body part is damaged, they do not appear to be valid targets for damage otherwise.

|-
| {{text anchor|MOUTH}}
|
| Unknown effect. Does not allow creature to eat. Often tied to a creature's attacks, so this may be the primary use of the tag.
|}

==Body Part Types==

Legal token types for use with the Attack Token "BYTYPE" argument:

* APERTURE
* BREATHE
* CIRCULATION
* DIGIT
* FLIER
* GRASP
* GUTS
* HEAD
* HEAR
* JOINT
* LIMB
* LOWERBODY
* MOUTH
* NERVOUS
* SMELL
* STANCE
* THOUGHT
* UPPERBODY

==Example==

An [[elephant]] is composed of a large number of body parts, but only includes a small list of templates. When an elephant asks for the following 15 templates in its CREATURE:ELEPHANT token:
[BODY:QUADRUPED:TAIL:2EYES:2EARS:TRUNK:2LUNGS:HEART:GUTS:ORGANS:THROAT:NECK:SPINE:BRAIN:MOUTH:2TUSKS]

...it gets all of the following 35 body parts:

QUADRUPED:
- upper body
- lower body
- head
- right front leg
- left front leg
- right front foot
- left front foot
- right rear leg
- left rear leg
- right rear foot
- left rear foot
TAIL:
- tail
2EYES:
- right eye
- left eye
2EARS:
- right ear
- left ear
TRUNK:
- trunk
2LUNGS:
- right lung
- left lung
HEART:
- heart
GUTS:
- guts
ORGANS:
- liver
- stomach
- pancreas
- spleen
- right kidney
- left kidney
THROAT:
- throat
NECK:
- neck
SPINE:
- upper spine
- lower spine
BRAIN:
- brain
MOUTH:
- mouth
2TUSKS:
- right tusk
- left tusk

The body part tree of the elephant, after connections are made, is as follows:

+ upper body
- heart
- upper spine
- right lung
- left lung
+ head
- brain
- mouth
- trunk
- right tusk
- left tusk
- right eye
- left eye
- right ear
- left ear
- neck
- throat
+ right front leg
- right front foot
+ left front leg
- left front foot
+ lower body
- lower spine
- guts
- tail
- liver
- stomach
- pancreas
- spleen
- right kidney
- left kidney
+ right rear leg
- right rear foot
+ left rear leg
- left rear foot

To understand how the above connections are determined (for example, why "lower spine" knows that it goes in "lower body", why "heart" knows that it goes in "upper body", etc.) refer to the CONTYPE tag.

{{Category|Modding}}
{{Category|Tokens}}

v0.31:Body token

2026-04-04T00:42:30Z

Quietust:

{{quality|Fine|00:14, 23 November 2010 (UTC)}}{{av}}

'''Body tokens''' are one of the fundamental parts of creatures, and determine their bodily structure. There are two major types of body tokens: ''body templates'' (BODY) and ''body parts'' (BP).

A creature uses the [[creature token#B|BODY creature token]] to list all of the body templates it includes. Each part listed in each template is then included in the creature. In other words: a creature lists the ''body templates'' it is made of. Each ''body template'' contains a set of ''body parts''. Each ''body part'' specifies which other body part it is attached to.

Body parts can connect specifically to another body part, or generally to any body part of a certain category. These connections are handled by the CON and CONTYPE body part tokens respectively.

Body parts can be renamed with a bodygloss, allowing someone to reuse an existing template instead of defining a similar template with only the names of the body parts changed.

{| {{prettytable}}
|- bgcolor="#999999"
! Token
! Arguments
! Description

|-
| {{text anchor|BP}}
|
*ID
*name
*pluralized name
| "STP stands for "Standard Plural" and it just adds an 's' to the singular word to save some typing. If you don't add something in that slot, the body part won't even load." --Toady. Note that this can cause confusing issues when porting from 40d to 2010. Make sure you add your pluralizations!

|-
| {{text anchor|UPPERBODY}}
| None
| Flags the body part as being able to wear upper body clothing like coats, breastplates etc. If an upper body is chopped off, the creature dies. Multiple upperbody parts aren't redundant. All default creatures with bodies have the upperbody as the root of the body tree, making it impossible to chop off.

|-
| {{text anchor|LOWERBODY}}
| None
| Flags the body part as being able to wear lower body clothing like skirts, pants, etc. If a lower body is chopped off, the creature dies. Multiple lowerbody parts aren't redundant.

|-
| {{text anchor|HEAD}}
| None
| Flags the body part as being able to wear head clothing like hats, helms, etc. If all heads are chopped off, the creature dies. Multiple heads '''are''' redundant - for example, [[hydra]]s can survive with several missing heads.

|-
| {{text anchor|CON}}
|
*value
| Connects the body part to a specific other body part

|-
| {{text anchor|CON_CAT}}
|
*value
| Connects the body part to all other body parts having the specified CATEGORY

|-
| {{text anchor|CONTYPE}}
|
*value
| Connects the body part to all other body parts having the specified type token. Valid values are UPPERBODY, LOWERBODY, HEAD, GRASP, or STANCE.

|-
| {{text anchor|LIMB}}
| None
| Body part is a limb. It can be used to initiate certain types of wrestling moves. If it is located between an UPPERBODY part and a GRASP body part, it is eligible to be covered by certain types of armor (body armors and gauntlets). If it is located between a LOWERBODY part and a STANCE body part, it is eligible to be covered by other types of armor (Leg armors like pants, etc; trailing body armors like mail shirts and robes; and high boots).

|-
| {{text anchor|THROAT}}
|
| Body part can be strangled.

|-
| {{text anchor|JOINT}}
|
| Body part is a joint that may be broken by wrestling.

|-
| {{text anchor|SKELETON}}
|
| Body part is part of the creature's skeleton.

|-
| {{text anchor|THOUGHT}}
| None
| Most creatures die if all bodyparts with this tag have sustained damage to a FUNCTIONAL tissue or been outright destroyed (chopped off). Creatures will not die if they have NO_THOUGHT_CENTER_FOR_MOVEMENT (and/or NOTHOUGHT?)

|-
| {{text anchor|NERVOUS}}
|
| Body part is necessary for motor function. Damage will impair movement and also disallow creature from sparring in Fortress mode.

|-
| {{text anchor|GRASP}}
| None
| Creature can wield a picked-up weapon with body part, and can use the part to initiate a wider variety of wrestling moves. When creatures are spawned with a weapon and shield, one GRASP part will hold a weapon while '''all others''' will hold shields.

|-
| {{text anchor|FLIER}}
| None
| Flags the body part as being need for flight. Damage to a certain number of FLIER body parts will prevent the creature from flying. Note that a creature can only fly if the creature has the FLIER tag in its creature definition, and that a flying creature does not actually need any FLIER body parts. This tags only purpose is to identify body parts which will cause a creature to '''lose''' the ability to fly, if they are damaged.

|-
| {{text anchor|UNDER_PRESSURE}}
| None
| Makes the body part pop out of edge attack wounds. Used on guts. Body part shows up as "~" when spilled/popped out.

|-
| {{text anchor|TOTEMABLE}}
| None
| Makes the body part makeable into totems at a craftsdwarf's workshop.

|-
| {{text anchor|VERMIN_BUTCHER_ITEM}}
| None
| Allows the item to be obtained from butchered or rotted vermin.

|-
| {{text anchor|STANCE}}
|
| Allows the creature to stand. Damage or loss of these body parts will cause creature to fall over.

|-
| {{text anchor|SIGHT}}
| None
| Body part is used to see with. If the creature has no SIGHT body parts, or if all its sight body parts are damaged or destroyed, it can't see unless it has the EXTRAVISION tag in its creature def.

|-
| {{text anchor|HEAR}}
|
| Body part is used to hear. No known effects.

|-
| {{text anchor|SMELL}}
| None
| Body part is used to smell. No known function.

|-
| {{text anchor|EMBEDDED}}
| None
| Body part with this tag is on the surface of parent body part. ie: eye and mouth on head. It can be gouged.

|-
| {{text anchor|APERTURE}}
|
| Marks body part as an opening in the body. This body part cannot be destroyed except by destroying the part it is attached to.

|-
| {{text anchor|SMALL}}
| None
| "SMALL means that the part isn't displayed as part of the overall displayed body part lists. They can't be splinted. They are more often targeted for torture (although those situations might not occur anymore). They are removed in skeletons if they aren't specifically skeletons/joints/digits/apertures. They are more easily lost in world gen duels. They are the only gougable/pinchable parts. SMALL is an old tag, so it has accumulated some weird functions which'll get split off over time. " --Toady

|-
| {{text anchor|INTERNAL}}
|
| Marks the body part as inside the body. Needs [SMALL] tag as well to not be targetable by attacks.

|-
| {{text anchor|BREATHE}}
|
| Body part is used to breathe. If all body parts with [BREATHE] are damaged or destroyed, the creature will suffocate unless it has the NOBREATHE tag in its creature def.

|-
| {{text anchor|CIRCULATION}}
|
| Body part is responsible for blood circulation. Exact effects not known.

|-
| {{text anchor|GUTS}}
| None
| Body parts marked with this tag make the creature nauseous and vomit when hit.

|-
| {{text anchor|RIGHT}}
| None
| Marks body part as on the right side of the body and vulnerable to attacks from the right. Used in conjunction with tags in the b_detail_plan_default raw.

|-
| {{text anchor|LEFT}}
| None
| Marks body part as on the left side of the body and vulnerable to attacks from the left. Used in conjunction with tags in the b_detail_plan_default raw.

|-
| {{text anchor|DIGIT}}
|
|

|-
| {{text anchor|CONNECTOR}}
|
| Body part is used to connect other body parts together. Used for the neck and lower spine.

|-
| {{text anchor|SOCKET}}
|
| Allows the body part to be easily knocked out. Used on teeth.

|-
| {{text anchor|MOUTH}}
|
|

|-
| {{text anchor|CATEGORY}}
|
*ID
| Assigns the body part to a user-defined category. Used by CON_CAT to attach to other body parts.

|-
| {{text anchor|DEFAULT_RELSIZE}}
|
*Size
| This command establishes the relative size of body parts within a creature. The numbers have no absolute meaning or units.

|-
| {{text anchor|NUMBER}}
|
*value
| In theory, the number lets you stack identical body parts. These can be individually damaged by wounds, but you don't have to define them explicitly one by one. If you don't give them individual names (see teeth) they'll be preceded by ordinal numbers (first, second, etc).
HOWEVER, this tag appears to be non-functional.

|-
| {{text anchor|INDIVIDUAL_NAME}}
|
*name
*plural
| Adding individual names tells the game what to call each individual part in a NUMBERed bodypart. This command replaces "first upper front tooth" for example.

|}

{{Category|Modding}}
{{Category|Tokens}}

v0.31:Tissue definition token

2026-04-04T00:39:15Z

Quietust:

{{quality|Fine|21:41, 22 February 2011 (UTC)}}{{av}}

__TOC__

{| {{prettytable}}
|- bgcolor="#999999"
! Token
! Arguments
! Description

|-
| {{text anchor|TISSUE_NAME}}
|
*name
*plural
|plural can alternatively be NP (No Plural) or STP (Standard Plural, adds an 's' on the end).

|-
| {{text anchor|TISSUE_MATERIAL}}
|
* [[material token]]
| Defines the tissue material.

|-
| {{text anchor|RELATIVE_THICKNESS}}
|
*value
| The relative thickness of the tissue. A higher thickness is harder to penetrate, but raising a tissue's relative thickness decreases the thickness of all other tissues.

|-
| {{text anchor|HEALING_RATE}}
|
*value
| Lower is faster. Omitting the token will result in a tissue that never heals.

|-
| {{text anchor|VASCULAR}}
|
*value
| Related to how much said tissue bleeds. Higher = More bleeding (Which is why the heart has the highest value.)

|-
| {{text anchor|PAIN_RECEPTORS}}
|
*value
| Related to how much pain your character will suffer when said tissue is damaged. Higher = More pain when damaged (Which is why the bone tissue has a much higher value than other tissues. A broken bone hurts a lot more than a flesh cut.)

|-
| {{text anchor|THICKENS_ON_STRENGTH}}
|
| The thickness of the tissue increases when character strength increases.

|-
| {{text anchor|THICKENS_ON_ENERGY_STORAGE}}
|
| Thickness of said tissue increases when the character eats and doesn't exercise sufficiently.

|-
| {{text anchor|ARTERIES}}
|
| The tissue contains arteries. Edged attacks have the chance to break an artery, increasing blood loss.

|-
| {{text anchor|SCARS}}
|
| Simply, whether or not the tissue will be scarred once healed.

|-
| {{text anchor|STRUCTURAL}}
|
| Holds the body part together. A cut or a fracture disables the body part it's in.

|-
| {{text anchor|CONNECTIVE_TISSUE_ANCHOR}}
|
| Any ligaments or tendons are part of this tissue. Vulnerable to edged attacks, damage disables the limb.

|-
| {{text anchor|SETTABLE}}
|
| The tissue will not heal, or heals slower, until it is set by a bone doctor.

|-
| {{text anchor|SPLINTABLE}}
|
| The broken tissue can be fixed with a cast or a splint to restore function while it heals.

|-
| {{text anchor|FUNCTIONAL}}
|
| The tissue performs some sort of special function (e.g. sight, hearing, breathing, etc.) An organ with such a function will stop working if a sufficient amount of damage is sustained by its FUNCTIONAL tissues. If an organ has no FUNCTIONAL tissues, it will stop working only if it is severed or destroyed entirely by heat or cold.

|-
| {{text anchor|NERVOUS}}
|
| Nervous function - not used. This token is used in [[Body_token#NERVOUS|[OBJECT:BODY]]] tokens.

|-
| {{text anchor|THOUGHT}}
|
| If a creature has no functioning parts with the THOUGHT token, it will be unable to move or breathe. NO_THOUGHT_CENTER_FOR_MOVEMENT bypasses this limitation.

|-
| {{text anchor|MUSCULAR}}
|
| Seems to affect where sensory or motor nerves are located, and whether damage to this tissue will render a limb useless.

|-
| {{text anchor|SMELL}}
|
| Used to smell - not used. This token is used in [[Body_token#SMELL|[OBJECT:BODY]]] tokens.

|-
| {{text anchor|HEAR}}
|
| Used to hearing - not used. This token is used in [[Body_token#HEAR|[OBJECT:BODY]]] tokens.

|-
| {{text anchor|FLIGHT}}
|
| Unknown - not used. Most likely related to flying, see [[Body_token#FLIER|[FLIER] in [OBJECT:BODY]]].

|-
| {{text anchor|BREATHE}}
|
| Used to breathing - not used. This token is used in [[Body_token#BREATHE|[OBJECT:BODY]]] tokens.

|-
| {{text anchor|SIGHT}}
|
| Used to seeing - not used. This token is used in [[Body_token#SIGHT|[OBJECT:BODY]]] tokens.

|-
| {{text anchor|CONNECTS}}
|
| Holds body parts together. A body part will not be severed unless all of its component tissues with the CONNECTS tag are severed.

|-
| {{text anchor|MAJOR_ARTERIES}}
|
| Causes tissue to sometimes severely bleed when damaged. This is independent of its VASCULAR value.

|-
| {{text anchor|INSULATION}}
|
*value
| Tissue supplies the creature with heat insulation. Higher values result in more insulation.

|-
| {{text anchor|COSMETIC}}
|
| ?

|-
| {{text anchor|STYLEABLE}}
|
| The tissue can be styled as per a tissue style (defined in an [[Entity_token|entity]] entry)

|-
| {{text anchor|TISSUE_SHAPE}}
|
*value
| Value can be one of the following:
;LAYER
:Regular layer tissue.
;STRANDS
:Can be spun into thread at a farmer's workshop. Edge attacks will pass right through the tissue.
;FEATHERS
:Edge attacks will pass right through the tissue.
;SCALES
:?
;CUSTOM
:?

|-
| {{text anchor|SUBORDINATE_TO_TISSUE}}
|
*value
| Tissue is implicitly attached to another tissue and will fall off if that tissue layer is destroyed. Used for hair and feathers, which are subordinate to skin.

|-
| {{text anchor|TISSUE_MAT_STATE}}
|
*SOLID, SOLID_POWDER, LIQUID, or GAS 
(possibly others, as well. Needs testing.)
| Sets/forces a default material state for the selected tissue.

|-
| {{text anchor|TISSUE_LEAKS}}
|
| The selected tissue leaks out of the creature when the layers above it are pierced.
|}

== Tissue layer tokens ==

These are used in creature raws to override the above for whatever reason.

{| {{prettytable}}
|- bgcolor="#ddd"
! width="20%" | Token
! width="20%" | Arguments
! width="60%" | Description

|-
| {{text anchor|SET_LAYER_TISSUE}}
|
* tissue
| Sets a tissue layer to be made of a different tissue.

|-
| {{text anchor|TL_RELATIVE_THICKNESS}}
|
* value
| Sets a new relative thickness for selected tissue layers.

|-
| {{text anchor|TL_CONNECTS}}
|
| Gives the CONNECTS attribute to selected layers.

|-
| {{text anchor|TL_MAJOR_ARTERIES}}
|
| Gives Major Artery attribute to selected layers.

|-
| {{text anchor|TL_HEALING_RATE}}
|
* value
| Sets a new HEALING_RATE of the selected tissue layers.

|-
| {{text anchor|TL_VASCULAR}}
|
| Sets a new VASCULAR value (which modulates bleeding) for selected tissue layers.

|-
| {{text anchor|TL_PAIN_RECEPTORS}}
|
| Sets a new number of pain receptors for selected tissue layers.
|}

==Defaults==
Default values (as of 0.31.21):

{| {{prettytable}} style="margin: 1em 1em 1em 0; background: #f9f9f9; border: 1px #aaa solid; border-collapse: collapse; font-size: 70%;"
|- bgcolor="#999999"
! style="font-size: 150%;"| TISSUE_TEMPLATE !! TISSUE_NAME !! TISSUE_MATERIAL !! TISSUE_MAT_STATE !! RELATIVE_THICKNESS !! HEALING_RATE !! VASCULAR !! PAIN_RECEPTORS !! SUBORDINATE_TO_TISSUE !! INSULATION !! TISSUE_SHAPE
|-
| SKIN_TEMPLATE || skin:NP || LOCAL_CREATURE_MAT:SKIN || || 1 || 100 || 1 || 5 || || || LAYER
|-
| FAT_TEMPLATE || fat:NP || LOCAL_CREATURE_MAT:FAT || || 1 || 100 || 3 || 5 || || 100 || LAYER
|-
| MUSCLE_TEMPLATE || muscle:muscles || LOCAL_CREATURE_MAT:MUSCLE || || 3 || 100 || 5 || 5 || || || LAYER
|-
| BONE_TEMPLATE || bone:NP || LOCAL_CREATURE_MAT:BONE || || 2 || 1000 || 3 || 50 || || || LAYER
|-
| SHELL_TEMPLATE || shell:NP || LOCAL_CREATURE_MAT:SHELL || || 2 || 1000 || || || || || LAYER
|-
| HORN_TEMPLATE || horn:NP || LOCAL_CREATURE_MAT:HORN || || 2 || || || || || || LAYER
|-
| HOOF_TEMPLATE || hoof:NP || LOCAL_CREATURE_MAT:HOOF || || 2 || || || || || || LAYER
|-
| CARTILAGE_TEMPLATE || cartilage:NP || LOCAL_CREATURE_MAT:CARTILAGE || || 2 || || || || || || LAYER
|-
| HAIR_TEMPLATE || hair:NP || LOCAL_CREATURE_MAT:HAIR || || 1 || || || || SKIN || 100 || STRANDS
|-
| CHEEK_WHISKERS_TEMPLATE || cheek whisker:STP || LOCAL_CREATURE_MAT:HAIR || || 2 || || || || SKIN || || STRANDS
|-
| CHIN_WHISKERS_TEMPLATE || chin whisker:STP || LOCAL_CREATURE_MAT:HAIR || || 2 || || || || SKIN || || STRANDS
|-
| MOUSTACHE_TEMPLATE || moustache:NP || LOCAL_CREATURE_MAT:HAIR || || 2 || || || || SKIN || || STRANDS
|-
| SIDEBURNS_TEMPLATE || sideburns:NP || LOCAL_CREATURE_MAT:HAIR || || 2 || || || || SKIN || || STRANDS
|-
| EYEBROW_TEMPLATE || eyebrow:NP || LOCAL_CREATURE_MAT:HAIR || || 2 || || || || SKIN || || STRANDS
|-
| EYELASH_TEMPLATE || eyelash:eyelashes || LOCAL_CREATURE_MAT:HAIR || || 2 || || || || SKIN || || STRANDS
|-
| FEATHER_TEMPLATE || feather:STP || LOCAL_CREATURE_MAT:FEATHER || || 2 || || || || SKIN || 100 || FEATHERS
|-
| SCALE_TEMPLATE || scale:STP || LOCAL_CREATURE_MAT:SCALE || || 1 || 100 || 1 || 5 || || || SCALES
|-
| NAIL_TEMPLATE || nail:NP || LOCAL_CREATURE_MAT:NAIL || || 2 || || || || || || LAYER
|-
| CLAW_TEMPLATE || claw:NP || LOCAL_CREATURE_MAT:CLAW || || 2 || || || || || || LAYER
|-
| TALON_TEMPLATE || talon:NP || LOCAL_CREATURE_MAT:TALON || || 2 || || || || || || LAYER
|-
| TOOTH_TEMPLATE || tooth:NP || LOCAL_CREATURE_MAT:TOOTH || || 2 || || || || || || LAYER
|-
| IVORY_TEMPLATE || ivory:NP || LOCAL_CREATURE_MAT:IVORY || || 2 || || || || || || LAYER
|-
| EYE_TEMPLATE || eye tissue:NP || LOCAL_CREATURE_MAT:EYE || || 1 || 100 || 3 || 5 || || || LAYER
|-
| NERVE_TEMPLATE || nervous tissue:NP || LOCAL_CREATURE_MAT:NERVE || || 1 || || 3 || || || || LAYER
|-
| BRAIN_TEMPLATE || brain tissue:NP || LOCAL_CREATURE_MAT:BRAIN || || 1 || || 3 || || || || LAYER
|-
| LUNG_TEMPLATE || lung tissue:NP || LOCAL_CREATURE_MAT:LUNG || || 1 || 100 || 8 || 5 || || || LAYER
|-
| HEART_TEMPLATE || heart tissue:NP || LOCAL_CREATURE_MAT:HEART || || 1 || 100 || 10 || 5 || || || LAYER
|-
| LIVER_TEMPLATE || liver tissue:NP || LOCAL_CREATURE_MAT:LIVER || || 1 || 100 || 8 || 5 || || || LAYER
|-
| GUT_TEMPLATE || gut:NP || LOCAL_CREATURE_MAT:GUT || || 1 || 100 || 3 || 5 || || || LAYER
|-
| STOMACH_TEMPLATE || stomach tissue:NP || LOCAL_CREATURE_MAT:STOMACH || || 1 || 100 || 3 || 5 || || || LAYER
|-
| PANCREAS_TEMPLATE || pancreatic tissue:NP || LOCAL_CREATURE_MAT:PANCREAS || || 1 || 100 || 3 || 5 || || || LAYER
|-
| SPLEEN_TEMPLATE || spleen tissue:NP || LOCAL_CREATURE_MAT:SPLEEN || || 1 || 100 || 5 || 5 || || || LAYER
|-
| KIDNEY_TEMPLATE || kidney tissue:NP || LOCAL_CREATURE_MAT:KIDNEY || || 1 || 100 || 8 || 5 || || || LAYER
|-
| FLAME_TEMPLATE || flames:NP || LOCAL_CREATURE_MAT:FLAME || GAS || 1 || || || || || || LAYER
|-
| CHITIN_TEMPLATE || chitin:NP || LOCAL_CREATURE_MAT:CHITIN || || 1 || 100 || 1 || 5 || || || LAYER
|- bgcolor="#999999"
! style="font-size: 150%;"| TISSUE_TEMPLATE !! TISSUE_NAME !! TISSUE_MATERIAL !! TISSUE_MAT_STATE !! RELATIVE_THICKNESS !! HEALING_RATE !! VASCULAR !! PAIN_RECEPTORS !! SUBORDINATE_TO_TISSUE !! INSULATION !! TISSUE_SHAPE
|}

Default flags (as of 0.31.21):

{| {{prettytable}} style="margin: 1em 1em 1em 0; background: #f9f9f9; border: 1px #aaa solid; border-collapse: collapse; font-size: 70%;"
|- bgcolor="#999999" style="font-size: 70%;"
! style="font-size: 150%;"| TISSUE_TEMPLATE !! THICKENS_ON_ENERGY_STORAGE !! THICKENS_ON_STRENGTH !! ARTERIES !! SCARS !! MUSCULAR !! FUNCTIONAL !! STRUCTURAL !! CONNECTIVE_TISSUE_ANCHOR !! CONNECTS !! SETTABLE !! SPLINTABLE !! COSMETIC !! STYLEABLE
|-
| SKIN_TEMPLATE || || || || X || || || || || X || || || ||
|-
| FAT_TEMPLATE || X || || || X || || || || || X || || || ||
|-
| MUSCLE_TEMPLATE || || X || X || X || X || || || || X || || ||
|-
| BONE_TEMPLATE || || || || || || || X || X || X || X || X || ||
|-
| SHELL_TEMPLATE || || || || || || || X || || X || X || X || ||
|-
| HORN_TEMPLATE || || || || || || || X || || X || || || ||
|-
| HOOF_TEMPLATE || || || || || || || X || || X || || || ||
|-
| CARTILAGE_TEMPLATE || || || || || || || X || || X || || || ||
|-
| HAIR_TEMPLATE || || || || || || || || || || || || X || X
|-
| CHEEK_WHISKERS_TEMPLATE || || || || || || || || || || || || X || X
|-
| CHIN_WHISKERS_TEMPLATE || || || || || || || || || || || || X || X
|-
| MOUSTACHE_TEMPLATE || || || || || || || || || || || || X || X
|-
| SIDEBURNS_TEMPLATE || || || || || || || || || || || || X || X
|-
| EYEBROW_TEMPLATE || || || || || || || || || || || || X || X
|-
| EYELASH_TEMPLATE || || || || || || || || || || || || X || X
|-
| FEATHER_TEMPLATE || || || || || || || || || || || ||
|-
| SCALE_TEMPLATE || || || || X || || || || || X || || || ||
|-
| NAIL_TEMPLATE || || || || || || || X || || X || || || ||
|-
| CLAW_TEMPLATE || || || || || || || X || || X || || || ||
|-
| TALON_TEMPLATE || || || || || || || X || || X || || || ||
|-
| TOOTH_TEMPLATE || || || || || || || X || || X || || || ||
|-
| IVORY_TEMPLATE || || || || || || || X || || X || || || ||
|-
| EYE_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| NERVE_TEMPLATE || || || || X || || X || || || X || || || ||
|-
| BRAIN_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| LUNG_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| HEART_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| LIVER_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| GUT_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| STOMACH_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| PANCREAS_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| SPLEEN_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| KIDNEY_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| FLAME_TEMPLATE || || || || || X || X || X || || X || || || ||
|-
| CHITIN_TEMPLATE || || || || X || || || X || X || X || X || X || ||
|- bgcolor="#999999" style="font-size: 70%;"
! style="font-size: 150%;"| TISSUE_TEMPLATE !! THICKENS_ON_ENERGY_STORAGE !! THICKENS_ON_STRENGTH !! ARTERIES !! SCARS !! MUSCULAR !! FUNCTIONAL !! STRUCTURAL !! CONNECTIVE_TISSUE_ANCHOR !! CONNECTS !! SETTABLE !! SPLINTABLE !! COSMETIC !! STYLEABLE
|}

==See Also==
*[[Material definition token]]

{{Category|Modding}}
{{Category|Tokens}}

v0.34:Tissue definition token

2026-04-04T00:35:37Z

Quietust:

{{quality|Superior}}{{av}}

__TOC__

{| {{prettytable}}
|- bgcolor="#999999"
! Token
! Arguments
! Description

|-
| {{text anchor|TISSUE_NAME}}
|
*name
*plural
|plural can alternatively be NP (No Plural) or STP (Standard Plural, adds an 's' on the end).

|-
| {{text anchor|TISSUE_MATERIAL}}
|
* [[material token]]
| Defines the tissue material.

|-
| {{text anchor|RELATIVE_THICKNESS}}
|
*value
| The relative thickness of the tissue. A higher thickness is harder to penetrate, but raising a tissue's relative thickness decreases the thickness of all other tissues.

|-
| {{text anchor|HEALING_RATE}}
|
*value
| Lower is faster. Omitting the token will result in a tissue that never heals.

|-
| {{text anchor|VASCULAR}}
|
*value
| Related to how much said tissue bleeds. Higher = More bleeding (Which is why the heart has the highest value.)

|-
| {{text anchor|PAIN_RECEPTORS}}
|
*value
| Related to how much pain your character will suffer when said tissue is damaged. Higher = More pain when damaged (Which is why the bone tissue has a much higher value than other tissues. A broken bone hurts a lot more than a flesh cut.)

|-
| {{text anchor|THICKENS_ON_STRENGTH}}
|
| The thickness of the tissue increases when character strength increases.

|-
| {{text anchor|THICKENS_ON_ENERGY_STORAGE}}
|
| Thickness of said tissue increases when the character eats and doesn't exercise sufficiently.

|-
| {{text anchor|ARTERIES}}
|
| The tissue contains arteries. Edged attacks have the chance to break an artery, increasing blood loss.

|-
| {{text anchor|SCARS}}
|
| Simply, whether or not the tissue will be scarred once healed.

|-
| {{text anchor|STRUCTURAL}}
|
| Holds the body part together. A cut or a fracture disables the body part it's in.

|-
| {{text anchor|CONNECTIVE_TISSUE_ANCHOR}}
|
| Any ligaments or tendons are part of this tissue. Vulnerable to edged attacks, damage disables the limb.

|-
| {{text anchor|SETTABLE}}
|
| The tissue will not heal, or heals slower, until it is set by a bone doctor.

|-
| {{text anchor|SPLINTABLE}}
|
| The broken tissue can be fixed with a cast or a splint to restore function while it heals.

|-
| {{text anchor|FUNCTIONAL}}
|
| The tissue performs some sort of special function (e.g. sight, hearing, breathing, etc.) An organ with such a function will stop working if a sufficient amount of damage is sustained by its FUNCTIONAL tissues. If an organ has no FUNCTIONAL tissues, it will stop working only if it is severed or destroyed entirely by heat or cold.

|-
| {{text anchor|NERVOUS}}
|
| Nervous function - not used. This token is used in [[Body_token#NERVOUS|[OBJECT:BODY]]] tokens.

|-
| {{text anchor|THOUGHT}}
|
| If a creature has no functioning parts with the THOUGHT token, it will be unable to move or breathe. NO_THOUGHT_CENTER_FOR_MOVEMENT bypasses this limitation.

|-
| {{text anchor|MUSCULAR}}
|
| Seems to affect where sensory or motor nerves are located, and whether damage to this tissue will render a limb useless.

|-
| {{text anchor|SMELL}}
|
| Used to smell - not used. This token is used in [[Body_token#SMELL|[OBJECT:BODY]]] tokens.

|-
| {{text anchor|HEAR}}
|
| Used to hearing - not used. This token is used in [[Body_token#HEAR|[OBJECT:BODY]]] tokens.

|-
| {{text anchor|FLIGHT}}
|
| Unknown - not used. Most likely related to flying, see [[Body_token#FLIER|[FLIER] in [OBJECT:BODY]]].

|-
| {{text anchor|BREATHE}}
|
| Used to breathing - not used. This token is used in [[Body_token#BREATHE|[OBJECT:BODY]]] tokens.

|-
| {{text anchor|SIGHT}}
|
| Used to seeing - not used. This token is used in [[Body_token#SIGHT|[OBJECT:BODY]]] tokens.

|-
| {{text anchor|CONNECTS}}
|
| Holds body parts together. A body part will not be severed unless all of its component tissues with the CONNECTS tag are severed.

|-
| {{text anchor|MAJOR_ARTERIES}}
|
| Causes tissue to sometimes severely bleed when damaged. This is independent of its VASCULAR value.

|-
| {{text anchor|INSULATION}}
|
*value
| Tissue supplies the creature with heat insulation. Higher values result in more insulation.

|-
| {{text anchor|COSMETIC}}
|
| ?

|-
| {{text anchor|STYLEABLE}}
|
| The tissue can be styled as per a tissue style (defined in an [[Entity_token|entity]] entry)

|-
| {{text anchor|TISSUE_SHAPE}}
|
*value
| Value can be one of the following:
;LAYER
:Regular layer tissue.
;STRANDS
:Can be spun into thread at a farmer's workshop. Edge attacks will pass right through the tissue.
;FEATHERS
:Edge attacks will pass right through the tissue.
;SCALES
:?
;CUSTOM
:?

|-
| {{text anchor|SUBORDINATE_TO_TISSUE}}
|
*value
| Tissue is implicitly attached to another tissue and will fall off if that tissue layer is destroyed. Used for hair and feathers, which are subordinate to skin.

|-
| {{text anchor|TISSUE_MAT_STATE}}
|
*SOLID, SOLID_POWDER, LIQUID, or GAS 
(possibly others, as well. Needs testing.)
| Sets/forces a default material state for the selected tissue.

|-
| {{text anchor|TISSUE_LEAKS}}
|
| The selected tissue leaks out of the creature when the layers above it are pierced.
|}

== Tissue layer tokens ==

These are used in creature raws to override the above for whatever reason.

{| {{prettytable}}
|- bgcolor="#ddd"
! width="20%" | Token
! width="20%" | Arguments
! width="60%" | Description

|-
| {{text anchor|SET_LAYER_TISSUE}}
|
* tissue
| Sets a tissue layer to be made of a different tissue.

|-
| {{text anchor|TL_RELATIVE_THICKNESS}}
|
* value
| Sets a new relative thickness for selected tissue layers.

|-
| {{text anchor|TL_CONNECTS}}
|
| Gives the CONNECTS attribute to selected layers.

|-
| {{text anchor|TL_MAJOR_ARTERIES}}
|
| Gives Major Artery attribute to selected layers.

|-
| {{text anchor|TL_HEALING_RATE}}
|
* value
| Sets a new HEALING_RATE of the selected tissue layers.

|-
| {{text anchor|TL_VASCULAR}}
|
| Sets a new VASCULAR value (which modulates bleeding) for selected tissue layers.

|-
| {{text anchor|TL_PAIN_RECEPTORS}}
|
| Sets a new number of pain receptors for selected tissue layers.
|}

==Defaults==
Default values (as of 0.34.11):

{| {{prettytable}} style="margin: 1em 1em 1em 0; background: #f9f9f9; border: 1px #aaa solid; border-collapse: collapse; font-size: 70%;"
|- bgcolor="#999999"
! style="font-size: 150%;"| TISSUE_TEMPLATE !! TISSUE_NAME !! TISSUE_MATERIAL !! TISSUE_MAT_STATE !! RELATIVE_THICKNESS !! HEALING_RATE !! VASCULAR !! PAIN_RECEPTORS !! SUBORDINATE_TO_TISSUE !! INSULATION !! TISSUE_SHAPE
|-
| SKIN_TEMPLATE || skin:NP || LOCAL_CREATURE_MAT:SKIN || || 1 || 100 || 1 || 5 || || || LAYER
|-
| FAT_TEMPLATE || fat:NP || LOCAL_CREATURE_MAT:FAT || || 1 || 100 || 3 || 5 || || 100 || LAYER
|-
| MUSCLE_TEMPLATE || muscle:muscles || LOCAL_CREATURE_MAT:MUSCLE || || 3 || 100 || 5 || 5 || || || LAYER
|-
| BONE_TEMPLATE || bone:NP || LOCAL_CREATURE_MAT:BONE || || 2 || 1000 || 3 || 50 || || || LAYER
|-
| SHELL_TEMPLATE || shell:NP || LOCAL_CREATURE_MAT:SHELL || || 2 || 1000 || || || || || LAYER
|-
| HORN_TEMPLATE || horn:NP || LOCAL_CREATURE_MAT:HORN || || 2 || || || || || || LAYER
|-
| HOOF_TEMPLATE || hoof:NP || LOCAL_CREATURE_MAT:HOOF || || 2 || || || || || || LAYER
|-
| CARTILAGE_TEMPLATE || cartilage:NP || LOCAL_CREATURE_MAT:CARTILAGE || || 2 || || || || || || LAYER
|-
| HAIR_TEMPLATE || hair:NP || LOCAL_CREATURE_MAT:HAIR || || 1 || || || || SKIN || 100 || STRANDS
|-
| CHEEK_WHISKERS_TEMPLATE || cheek whisker:STP || LOCAL_CREATURE_MAT:HAIR || || 2 || || || || SKIN || || STRANDS
|-
| CHIN_WHISKERS_TEMPLATE || chin whisker:STP || LOCAL_CREATURE_MAT:HAIR || || 2 || || || || SKIN || || STRANDS
|-
| MOUSTACHE_TEMPLATE || moustache:NP || LOCAL_CREATURE_MAT:HAIR || || 2 || || || || SKIN || || STRANDS
|-
| SIDEBURNS_TEMPLATE || sideburns:NP || LOCAL_CREATURE_MAT:HAIR || || 2 || || || || SKIN || || STRANDS
|-
| EYEBROW_TEMPLATE || eyebrow:NP || LOCAL_CREATURE_MAT:HAIR || || 2 || || || || SKIN || || STRANDS
|-
| EYELASH_TEMPLATE || eyelash:eyelashes || LOCAL_CREATURE_MAT:HAIR || || 2 || || || || SKIN || || STRANDS
|-
| FEATHER_TEMPLATE || feather:STP || LOCAL_CREATURE_MAT:FEATHER || || 2 || || || || SKIN || 100 || FEATHERS
|-
| SCALE_TEMPLATE || scale:STP || LOCAL_CREATURE_MAT:SCALE || || 1 || 100 || 1 || 5 || || || SCALES
|-
| NAIL_TEMPLATE || nail:NP || LOCAL_CREATURE_MAT:NAIL || || 2 || || || || || || LAYER
|-
| CLAW_TEMPLATE || claw:NP || LOCAL_CREATURE_MAT:CLAW || || 2 || || || || || || LAYER
|-
| TALON_TEMPLATE || talon:NP || LOCAL_CREATURE_MAT:TALON || || 2 || || || || || || LAYER
|-
| TOOTH_TEMPLATE || tooth:NP || LOCAL_CREATURE_MAT:TOOTH || || 2 || || || || || || LAYER
|-
| IVORY_TEMPLATE || ivory:NP || LOCAL_CREATURE_MAT:IVORY || || 2 || || || || || || LAYER
|-
| EYE_TEMPLATE || eye tissue:NP || LOCAL_CREATURE_MAT:EYE || || 1 || 100 || 3 || 5 || || || LAYER
|-
| NERVE_TEMPLATE || nervous tissue:NP || LOCAL_CREATURE_MAT:NERVE || || 1 || || 3 || || || || LAYER
|-
| BRAIN_TEMPLATE || brain tissue:NP || LOCAL_CREATURE_MAT:BRAIN || || 1 || || 3 || || || || LAYER
|-
| LUNG_TEMPLATE || lung tissue:NP || LOCAL_CREATURE_MAT:LUNG || || 1 || 100 || 8 || 5 || || || LAYER
|-
| HEART_TEMPLATE || heart tissue:NP || LOCAL_CREATURE_MAT:HEART || || 1 || 100 || 10 || 5 || || || LAYER
|-
| LIVER_TEMPLATE || liver tissue:NP || LOCAL_CREATURE_MAT:LIVER || || 1 || 100 || 8 || 5 || || || LAYER
|-
| GUT_TEMPLATE || gut:NP || LOCAL_CREATURE_MAT:GUT || || 1 || 100 || 3 || 5 || || || LAYER
|-
| STOMACH_TEMPLATE || stomach tissue:NP || LOCAL_CREATURE_MAT:STOMACH || || 1 || 100 || 3 || 5 || || || LAYER
|-
| PANCREAS_TEMPLATE || pancreatic tissue:NP || LOCAL_CREATURE_MAT:PANCREAS || || 1 || 100 || 3 || 5 || || || LAYER
|-
| SPLEEN_TEMPLATE || spleen tissue:NP || LOCAL_CREATURE_MAT:SPLEEN || || 1 || 100 || 5 || 5 || || || LAYER
|-
| KIDNEY_TEMPLATE || kidney tissue:NP || LOCAL_CREATURE_MAT:KIDNEY || || 1 || 100 || 8 || 5 || || || LAYER
|-
| FLAME_TEMPLATE || flames:NP || LOCAL_CREATURE_MAT:FLAME || GAS || 1 || || || || || || LAYER
|-
| CHITIN_TEMPLATE || chitin:NP || LOCAL_CREATURE_MAT:CHITIN || || 1 || 100 || 1 || 5 || || || LAYER
|-
| SPINE_TEMPLATE || spine:NP || LOCAL_CREATURE_MAT:SPINE || || 2 || || || || || || LAYER
|-
| SPONGE_TEMPLATE || sponge:NP || LOCAL_CREATURE_MAT:SPONGE || || 1 || 100 || 3 || 5 || || 100 || LAYER
|- bgcolor="#999999"
! style="font-size: 150%;"| TISSUE_TEMPLATE !! TISSUE_NAME !! TISSUE_MATERIAL !! TISSUE_MAT_STATE !! RELATIVE_THICKNESS !! HEALING_RATE !! VASCULAR !! PAIN_RECEPTORS !! SUBORDINATE_TO_TISSUE !! INSULATION !! TISSUE_SHAPE
|}

Default flags (as of 0.34.11):

{| {{prettytable}} style="margin: 1em 1em 1em 0; background: #f9f9f9; border: 1px #aaa solid; border-collapse: collapse; font-size: 70%;"
|- bgcolor="#999999" style="font-size: 70%;"
! style="font-size: 150%;"| TISSUE_TEMPLATE !! THICKENS_ON_ENERGY_STORAGE !! THICKENS_ON_STRENGTH !! ARTERIES !! SCARS !! MUSCULAR !! FUNCTIONAL !! STRUCTURAL !! CONNECTIVE_TISSUE_ANCHOR !! CONNECTS !! SETTABLE !! SPLINTABLE !! COSMETIC !! STYLEABLE
|-
| SKIN_TEMPLATE || || || || X || || || || || X || || || ||
|-
| FAT_TEMPLATE || X || || || X || || || || || X || || || ||
|-
| MUSCLE_TEMPLATE || || X || X || X || X || || || || X || || ||
|-
| BONE_TEMPLATE || || || || || || || X || X || X || X || X || ||
|-
| SHELL_TEMPLATE || || || || || || || X || || X || X || X || ||
|-
| HORN_TEMPLATE || || || || || || || X || || X || || || ||
|-
| HOOF_TEMPLATE || || || || || || || X || || X || || || ||
|-
| CARTILAGE_TEMPLATE || || || || || || || X || || X || || || ||
|-
| HAIR_TEMPLATE || || || || || || || || || || || || X || X
|-
| CHEEK_WHISKERS_TEMPLATE || || || || || || || || || || || || X || X
|-
| CHIN_WHISKERS_TEMPLATE || || || || || || || || || || || || X || X
|-
| MOUSTACHE_TEMPLATE || || || || || || || || || || || || X || X
|-
| SIDEBURNS_TEMPLATE || || || || || || || || || || || || X || X
|-
| EYEBROW_TEMPLATE || || || || || || || || || || || || X || X
|-
| EYELASH_TEMPLATE || || || || || || || || || || || || X || X
|-
| FEATHER_TEMPLATE || || || || || || || || || || || ||
|-
| SCALE_TEMPLATE || || || || X || || || || || X || || || ||
|-
| NAIL_TEMPLATE || || || || || || || X || || X || || || ||
|-
| CLAW_TEMPLATE || || || || || || || X || || X || || || ||
|-
| TALON_TEMPLATE || || || || || || || X || || X || || || ||
|-
| TOOTH_TEMPLATE || || || || || || || X || || X || || || ||
|-
| IVORY_TEMPLATE || || || || || || || X || || X || || || ||
|-
| EYE_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| NERVE_TEMPLATE || || || || X || || X || || || X || || || ||
|-
| BRAIN_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| LUNG_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| HEART_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| LIVER_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| GUT_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| STOMACH_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| PANCREAS_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| SPLEEN_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| KIDNEY_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| FLAME_TEMPLATE || || || || || X || X || X || || X || || || ||
|-
| CHITIN_TEMPLATE || || || || X || || || X || X || X || X || X || ||
|-
| SPINE_TEMPLATE || || || || || || || X || || X || || || ||
|-
| SPONGE_TEMPLATE || || || || X || || || || || X || || || ||
|- bgcolor="#999999" style="font-size: 70%;"
! style="font-size: 150%;"| TISSUE_TEMPLATE !! THICKENS_ON_ENERGY_STORAGE !! THICKENS_ON_STRENGTH !! ARTERIES !! SCARS !! MUSCULAR !! FUNCTIONAL !! STRUCTURAL !! CONNECTIVE_TISSUE_ANCHOR !! CONNECTS !! SETTABLE !! SPLINTABLE !! COSMETIC !! STYLEABLE
|}

==See Also==
*[[Material definition token]]

{{Category|Modding}}
{{Category|Tokens}}

v0.31:Plant token

2026-04-04T00:33:05Z

Quietust:

{{quality|Exceptional|21:01, 30 March 2011 (UTC)}}{{av}}
The default plants are stored in the plant_standard.txt file, while grasses are stored in plant_grasses.txt.

==Basic Tokens==
These tokens are specified for all plants and define their most basic characteristics.

{| {{prettytable}}
|- style='background-color:#ddd'
! width="20%" | Token
! width="20%" | Arguments
! width="60%" | Description

|-
| {{text anchor|NAME}}
|
*name
| The singular form of the plants name as seen in game.

|-
| {{text anchor|NAME_PLURAL}}
|
*name
| The plural form of the plants name as seen in game.

|-
| {{text anchor|ADJ}}
|
*adjective
| The word or phrase used to describe items made from this plant.

|-
| {{text anchor|ALL_NAMES}}
|
*name
| Sets the NAME, NAME_PLURAL, and ADJ to the specified string.

|-
| {{text anchor|PREFSTRING}}
|
*reason
| What dwarves can like this object for (e.g. "Urist likes plump helmets for their rounded tops.")

|-
| {{text anchor|MATERIAL}}
|
*material_name
| Starts defining a new local plant material with the given name and '''no''' properties. A maximum of 200 materials can be defined on any given plant.

|-
| {{text anchor|USE_MATERIAL}}
|
*material_name
*old_material
| Starts defining a new local plant material with the given name and using the properties of another local plant material. A maximum of 200 materials can be defined on any given plant.

|-
| {{text anchor|USE_MATERIAL_TEMPLATE}}
|
*material_name
*template_name
| Starts defining a new local plant material with the given name and using the properties of the specified material template. A maximum of 200 materials can be defined on any given plant.

|-
| {{text anchor|BASIC_MAT}}
|
* [[Material token|material]]
| Sets the basic material of the plant. According to Toady, you can use other materials (for instance, iron) but the game may hiccup on plants that aren't structurally plants. For crops, said material should have [STRUCTURAL_PLANT_MAT] to permit proper stockpiling. Generally, this should be "LOCAL_PLANT_MAT:material_name", using a material defined using MATERIAL, USE_MATERIAL, or USE_MATERIAL_TEMPLATE.
|}

==Environment Tokens==
These tokens, also applicable to all plants, specify where the plants grow.

{| {{prettytable}}
|- style='background-color:#ddd'
! width="20%" | Token
! width="20%" | Arguments
! width="60%" | Description

|-
| {{text anchor|UNDERGROUND_DEPTH}}
|
*minimum
*maximum
| Designates the highest and lowest cavern levels that the plant can appear in if its [[biome token|biome]] is subterranean. Dwarven civilizations will only export (via the embark screen or caravans) things that available at depth 1. Defaults to 0:0 (surface only).

|-
| {{text anchor|GOOD}}
|
| Restricts the plant to growing in Good regions. Cannot be combined with [EVIL].

|-
| {{text anchor|EVIL}}
|
| Restricts the plant to growing in Evil regions. Cannot be combined with [GOOD].

|-
| {{text anchor|SAVAGE}}
|
| Restricts the plant to growing in Savage regions (regardless of alignment).

|-
| {{text anchor|FREQUENCY}}
|
*freq (0-100)
| How frequently this plant is generated in a particular area. Defaults to 50.

|-
| {{text anchor|WET}}
|
| Allows the plant to grow near water features.

|-
| {{text anchor|DRY}}
|
| Allows the plant to grow away from water features.

|-
| {{text anchor|BIOME}}
|
*biome
| What [[biome token|biome]] this plant appears in.

|}

==Tree Tokens==
These tokens are used only for trees.

{| {{prettytable}}
|- style='background-color:#ddd'
! width="20%" | Token
! width="20%" | Arguments
! width="60%" | Description

|-
| {{text anchor|TREE}}
|
* [[Material token|material]]
| Makes the plant into a [[tree]]. Cutting down the tree will yield logs made of this material.

|-
| {{text anchor|AUTUMNCOLOR}}
|
| Makes the tree turn yellow, orange, and red in Autumn, then lose its leaves in Winter.

|-
| {{text anchor|TREE_TILE}}
|
*tile
| The tile used for the tree on the map. May be a number or a character inside apostrophes. Defaults to 24 (↑).

|-
| {{text anchor|DEAD_TREE_TILE}}
|
*tile
| The tile used for (un)dead trees of this type. Defaults to 198 (╞).

|-
| {{text anchor|SAPLING_TILE}}
|
*tile
| The tile used for saplings of this tree. Defaults to 231 (τ).

|-
| {{text anchor|DEAD_SAPLING_TILE}}
|
*tile
| The tile used for dead saplings of this tree. Defaults to 231 (τ).

|-
| {{text anchor|TREE_COLOR}}
|
*foreground
*background
*bright
| The [[color]] of the tree on the map. Defaults to 2:0:0 (dark green).

|-
| {{text anchor|DEAD_TREE_COLOR}}
|
*foreground
*background
*bright
| The [[color]] of the tree on the map when (un)dead. Defaults to 0:0:1 (dark gray).

|-
| {{text anchor|SAPLING_COLOR}}
|
*foreground
*background
*bright
| The [[color]] of saplings of this tree. Defaults to 2:0:0 (dark green).

|-
| {{text anchor|DEAD_SAPLING_COLOR}}
|
*foreground
*background
*bright
| The [[color]] of dead saplings of this tree. Defaults to 0:0:1 (dark gray).

|-
| {{text anchor|SAPLING_DROWN_LEVEL}}
|
*depth
| The water depth at which saplings of this tree will drown. Exact behavior is unknown. Defaults to 4.

|-
| {{text anchor|TREE_DROWN_LEVEL}}
|
*depth
| The water depth at which this tree will drown. Exact behavior is unknown. Defaults to 7.

|-
| {{text anchor|SAPLING}}
|
| Makes young versions of the tree be called "[tree name] sapling"; otherwise, they are called "young [tree name]".

|}

==Crop Tokens==
These tokens are used only for plantable crops and harvestable shrubs.

{| {{prettytable}}
|- style='background-color:#ddd'
! width="20%" | Token
! width="20%" | Arguments
! width="60%" | Description

|-
| {{text anchor|SPRING}}
|
| Allows the plant to grow during spring.

|-
| {{text anchor|SUMMER}}
|
| Allows the plant to grow during summer.

|-
| {{text anchor|AUTUMN}}
|
| Allows the plant to grow during autumn.

|-
| {{text anchor|WINTER}}
|
| Allows the plant to grow during winter.

|-
| {{text anchor|GROWDUR}}
|
*time
| How long the plant takes to grow. Unit hundreds of ticks, See [[Time]]. There are 1008 GROWDUR units in a season. Defaults to 300.

|-
| {{text anchor|VALUE}}
|
*value
| Appears to have no effect.

|-
| {{text anchor|PICKED_TILE}}
|
*tile
| The tile used when harvested. May either be a number or letter within apostrophes(confirm?). See [[Main:character table|character table]]. Defaults to 231 (τ).

|-
| {{text anchor|DEAD_PICKED_TILE}}
|
*tile
| The tile used when a harvested plant has wilted. Defaults to 169 (⌐).

|-
| {{text anchor|SHRUB_TILE}}
|
*tile
| What tile is used for shrubs bearing this plant. Can be either a number or a character inside apostrophes. Defaults to 34 (").

|-
| {{text anchor|DEAD_SHRUB_TILE}}
|
*tile
| What tile is used for dead shrubs that once bore this plant. Can be either a number or a character inside apostrophes. Defaults to 34 (").

|-
| {{text anchor|CLUSTERSIZE}}
|
*size
| The maximum stack size collected when gathered via herbalism. Defaults to 5.

|-
| {{text anchor|PICKED_COLOR}}
|
*foreground
*background
*bright
| The [[color]] of the plant in farms. Defaults to 2:0:0 (dark green).

|-
| {{text anchor|DEAD_PICKED_COLOR}}
|
*foreground
*background
*bright
| The [[color]] of the plant when wilted. Defaults to 0:0:1 (dark gray).

|-
| {{text anchor|SHRUB_COLOR}}
|
*foreground
*background
*bright
| The [[color]] of shrubs bearing this plant. Defaults to 2:0:0 (dark green).

|-
| {{text anchor|DEAD_SHRUB_COLOR}}
|
*foreground
*background
*bright
|The [[color]] of dead shrubs that bore this plant. Defaults to 6:0:0 (brown).

|-
| {{text anchor|SHRUB_DROWN_LEVEL}}
|
*depth
| The water depth at which shrubs of this plant will drown. Exact behavior is unknown. Defaults to 4.

|-
| {{text anchor|DRINK}}
|
* [[Material token|material]]
| Permits brewing the plant into [[alcohol]] made of this material. Said material should have [ALCOHOL_PLANT] to permit proper stockpiling.

|-
| {{text anchor|MILL}}
|
* [[Material token|material]]
| Permits milling the plant at a [[quern]] or [[millstone]] into a powder made of this material. Said material should have [POWDER_MISC_PLANT] to permit proper stockpiling.

|-
| {{text anchor|THREAD}}
|
* [[Material token|material]]
| Permits processing the plant at a [[farmer's workshop]] to yield threads made of this material. Said material should have [THREAD_PLANT] to permit proper stockpiling.

|-
| {{text anchor|SEED}}
|
*name
*name_plural
*foreground
*background
*bright
*[[Material token|material]]
| Causes the plant to yield plantable seeds made of this material and having these properties. Said material should have [SEED_MAT] to permit proper stockpiling.

|-
| {{text anchor|LEAVES}}
|
*name
*name_plural
*tile
*foreground
*background
*bright
*wilt_foreground
*wilt_background
*wilt_bright
*[[Material token|material]]
| Permits processing the plant into a [[bag]] at a [[farmer's workshop]] to yield leaves made of this material and having these properties. Said material should have [LEAF_MAT] to permit proper stockpiling.

|-
| {{text anchor|EXTRACT_STILL_VIAL}}
|
* [[Material token|material]]
| Permits processing the plant into a [[vial]] at a [[still]] to yield extract made of this material. Said material should have [EXTRACT_STORAGE:FLASK].

|-
| {{text anchor|EXTRACT_VIAL}}
|
*[[Material token|material]]
| Permits processing the plant into a [[vial]] at a [[farmer's workshop]] to yield extract made of this material. Said material should have [EXTRACT_STORAGE:FLASK].

|-
| {{text anchor|EXTRACT_BARREL}}
|
* [[Material token|material]]
| Permits processing the plant into a [[barrel]] at a [[farmer's workshop]] to yield extract made of this material. Said material should have [EXTRACT_STORAGE:BARREL].

|}

==Grass Tokens==
These tokens are used only for [[grass]]es.

{| {{prettytable}}
|- style='background-color:#ddd'
! width="20%" | Token
! width="20%" | Arguments
! width="60%" | Description

|-
| {{text anchor|GRASS}}
|
| Makes the plant behave as a type of grass.

|-
| {{text anchor|GRASS_TILES}}
|
*tile
*tile
*tile
*tile
| Specifies the 4 tiles used to represent grass of this type. If VARIED_GROUND_TILES is disabled in d_init.txt, these are seemingly ignored. Defaults to 46:44:96:39 (.,`').

|-
| {{text anchor|ALT_PERIOD}}
|
*period
*offset
| How often the grass switches between its main tiles and alternate tiles. The "period" value determines how quickly (in frames) the grass animates, and the "offset" value specifies how much of that time is spent displaying the alternate tiles. If the "offset" value is greater than or equal to the "period" value, the grass will only display using the alternate tiles.{{verify}} Defaults to 0:0.

|-
| {{text anchor|ALT_GRASS_TILES}}
|
*tile
*tile
*tile
*tile
| When used with ALT_PERIOD, specifies the 4 alternate tiles used to represent grass of this type. Defaults to 46:44:96:39 (.,`'). Dead grass does not animate.

|-
| {{text anchor|GRASS_COLORS}}
|
*color 1 (fore:back:bright)
*color 2 (fore:back:bright)
*dry color (fore:back:bright)
*dead color (fore:back:bright)
| Specifies the color of this grass. Defaults to 2:0:1:2:0:0:6:0:1:6:0:0 (light green, dark green, yellow, brown).
|}

{{Category|Modding}}
{{Category|Tokens}}

v0.34:Plant token

2026-04-04T00:32:07Z

Quietust:

{{quality|Exceptional|21:01, 30 March 2011 (UTC)}}{{av}}
The default plants are stored in the plant_standard.txt file, while grasses are stored in plant_grasses.txt.

==Basic Tokens==
These tokens are specified for all plants and define their most basic characteristics.

{| {{prettytable}}
|- style='background-color:#ddd'
! width="20%" | Token
! width="20%" | Arguments
! width="60%" | Description

|-
| {{text anchor|NAME}}
|
*name
| The singular form of the plants name as seen in game.

|-
| {{text anchor|NAME_PLURAL}}
|
*name
| The plural form of the plants name as seen in game.

|-
| {{text anchor|ADJ}}
|
*adjective
| The word or phrase used to describe items made from this plant.

|-
| {{text anchor|ALL_NAMES}}
|
*name
| Sets the NAME, NAME_PLURAL, and ADJ to the specified string.

|-
| {{text anchor|PREFSTRING}}
|
*reason
| What dwarves can like this object for (e.g. "Urist likes plump helmets for their rounded tops.")

|-
| {{text anchor|MATERIAL}}
|
*material_name
| Starts defining a new local plant material with the given name and '''no''' properties. A maximum of 200 materials can be defined on any given plant.

|-
| {{text anchor|USE_MATERIAL}}
|
*material_name
*old_material
| Starts defining a new local plant material with the given name and using the properties of another local plant material. A maximum of 200 materials can be defined on any given plant.

|-
| {{text anchor|USE_MATERIAL_TEMPLATE}}
|
*material_name
*template_name
| Starts defining a new local plant material with the given name and using the properties of the specified material template. A maximum of 200 materials can be defined on any given plant.

|-
| {{text anchor|BASIC_MAT}}
|
* [[Material token|material]]
| Sets the basic material of the plant. According to Toady, you can use other materials (for instance, iron) but the game may hiccup on plants that aren't structurally plants. For crops, said material should have [STRUCTURAL_PLANT_MAT] to permit proper stockpiling. Generally, this should be "LOCAL_PLANT_MAT:material_name", using a material defined using MATERIAL, USE_MATERIAL, or USE_MATERIAL_TEMPLATE.
|}

==Environment Tokens==
These tokens, also applicable to all plants, specify where the plants grow.

{| {{prettytable}}
|- style='background-color:#ddd'
! width="20%" | Token
! width="20%" | Arguments
! width="60%" | Description

|-
| {{text anchor|UNDERGROUND_DEPTH}}
|
*minimum
*maximum
| Designates the highest and lowest cavern levels that the plant can appear in if its [[biome token|biome]] is subterranean. Dwarven civilizations will only export (via the embark screen or caravans) things that available at depth 1. Defaults to 0:0 (surface only).

|-
| {{text anchor|GOOD}}
|
| Restricts the plant to growing in Good regions. Cannot be combined with [EVIL].

|-
| {{text anchor|EVIL}}
|
| Restricts the plant to growing in Evil regions. Cannot be combined with [GOOD].

|-
| {{text anchor|SAVAGE}}
|
| Restricts the plant to growing in Savage regions (regardless of alignment).

|-
| {{text anchor|FREQUENCY}}
|
*freq (0-100)
| How frequently this plant is generated in a particular area. Defaults to 50.

|-
| {{text anchor|WET}}
|
| Allows the plant to grow near water features.

|-
| {{text anchor|DRY}}
|
| Allows the plant to grow away from water features.

|-
| {{text anchor|BIOME}}
|
*biome
| What [[biome token|biome]] this plant appears in.

|}

==Tree Tokens==
These tokens are used only for trees.

{| {{prettytable}}
|- style='background-color:#ddd'
! width="20%" | Token
! width="20%" | Arguments
! width="60%" | Description

|-
| {{text anchor|TREE}}
|
* [[Material token|material]]
| Makes the plant into a [[tree]]. Cutting down the tree will yield logs made of this material.

|-
| {{text anchor|AUTUMNCOLOR}}
|
| Makes the tree turn yellow, orange, and red in Autumn, then lose its leaves in Winter.

|-
| {{text anchor|TREE_TILE}}
|
*tile
| The tile used for the tree on the map. May be a number or a character inside apostrophes. Defaults to 24 (↑).

|-
| {{text anchor|DEAD_TREE_TILE}}
|
*tile
| The tile used for (un)dead trees of this type. Defaults to 198 (╞).

|-
| {{text anchor|SAPLING_TILE}}
|
*tile
| The tile used for saplings of this tree. Defaults to 231 (τ).

|-
| {{text anchor|DEAD_SAPLING_TILE}}
|
*tile
| The tile used for dead saplings of this tree. Defaults to 231 (τ).

|-
| {{text anchor|TREE_COLOR}}
|
*foreground
*background
*bright
| The [[color]] of the tree on the map. Defaults to 2:0:0 (dark green).

|-
| {{text anchor|DEAD_TREE_COLOR}}
|
*foreground
*background
*bright
| The [[color]] of the tree on the map when (un)dead. Defaults to 0:0:1 (dark gray).

|-
| {{text anchor|SAPLING_COLOR}}
|
*foreground
*background
*bright
| The [[color]] of saplings of this tree. Defaults to 2:0:0 (dark green).

|-
| {{text anchor|DEAD_SAPLING_COLOR}}
|
*foreground
*background
*bright
| The [[color]] of dead saplings of this tree. Defaults to 0:0:1 (dark gray).

|-
| {{text anchor|SAPLING_DROWN_LEVEL}}
|
*depth
| The water depth at which saplings of this tree will drown. Exact behavior is unknown. Defaults to 4.

|-
| {{text anchor|TREE_DROWN_LEVEL}}
|
*depth
| The water depth at which this tree will drown. Exact behavior is unknown. Defaults to 7.

|-
| {{text anchor|SAPLING}}
|
| Makes young versions of the tree be called "[tree name] sapling"; otherwise, they are called "young [tree name]".

|}

==Crop Tokens==
These tokens are used only for plantable crops and harvestable shrubs.

{| {{prettytable}}
|- style='background-color:#ddd'
! width="20%" | Token
! width="20%" | Arguments
! width="60%" | Description

|-
| {{text anchor|SPRING}}
|
| Allows the plant to grow during spring.

|-
| {{text anchor|SUMMER}}
|
| Allows the plant to grow during summer.

|-
| {{text anchor|AUTUMN}}
|
| Allows the plant to grow during autumn.

|-
| {{text anchor|WINTER}}
|
| Allows the plant to grow during winter.

|-
| {{text anchor|GROWDUR}}
|
*time
| How long the plant takes to grow. Unit hundreds of ticks, See [[Time]]. There are 1008 GROWDUR units in a season. Defaults to 300.

|-
| {{text anchor|VALUE}}
|
*value
| Has no effect as of version 0.34.11. Previously set the value of the harvested plant.

|-
| {{text anchor|PICKED_TILE}}
|
*tile
| The tile used when harvested. May either be a number or letter within apostrophes(confirm?). See [[Main:character table|character table]]. Defaults to 231 (τ).

|-
| {{text anchor|DEAD_PICKED_TILE}}
|
*tile
| The tile used when a harvested plant has wilted. Defaults to 169 (⌐).

|-
| {{text anchor|SHRUB_TILE}}
|
*tile
| What tile is used for shrubs bearing this plant. Can be either a number or a character inside apostrophes. Defaults to 34 (").

|-
| {{text anchor|DEAD_SHRUB_TILE}}
|
*tile
| What tile is used for dead shrubs that once bore this plant. Can be either a number or a character inside apostrophes. Defaults to 34 (").

|-
| {{text anchor|CLUSTERSIZE}}
|
*size
| The maximum stack size collected when gathered via herbalism. Defaults to 5.

|-
| {{text anchor|PICKED_COLOR}}
|
*foreground
*background
*bright
| The [[color]] of the plant in farms. Defaults to 2:0:0 (dark green).

|-
| {{text anchor|DEAD_PICKED_COLOR}}
|
*foreground
*background
*bright
| The [[color]] of the plant when wilted. Defaults to 0:0:1 (dark gray).

|-
| {{text anchor|SHRUB_COLOR}}
|
*foreground
*background
*bright
| The [[color]] of shrubs bearing this plant. Defaults to 2:0:0 (dark green).

|-
| {{text anchor|DEAD_SHRUB_COLOR}}
|
*foreground
*background
*bright
|The [[color]] of dead shrubs that bore this plant. Defaults to 6:0:0 (brown).

|-
| {{text anchor|SHRUB_DROWN_LEVEL}}
|
*depth
| The water depth at which shrubs of this plant will drown. Exact behavior is unknown. Defaults to 4.

|-
| {{text anchor|DRINK}}
|
* [[Material token|material]]
| Permits brewing the plant into [[alcohol]] made of this material. Said material should have [ALCOHOL_PLANT] to permit proper stockpiling.

|-
| {{text anchor|MILL}}
|
* [[Material token|material]]
| Permits milling the plant at a [[quern]] or [[millstone]] into a powder made of this material. Said material should have [POWDER_MISC_PLANT] to permit proper stockpiling.

|-
| {{text anchor|THREAD}}
|
* [[Material token|material]]
| Permits processing the plant at a [[farmer's workshop]] to yield threads made of this material. Said material should have [THREAD_PLANT] to permit proper stockpiling.

|-
| {{text anchor|SEED}}
|
*name
*name_plural
*foreground
*background
*bright
*[[Material token|material]]
| Causes the plant to yield plantable seeds made of this material and having these properties. Said material should have [SEED_MAT] to permit proper stockpiling.

|-
| {{text anchor|LEAVES}}
|
*name
*name_plural
*tile
*foreground
*background
*bright
*wilt_foreground
*wilt_background
*wilt_bright
*[[Material token|material]]
| Permits processing the plant into a [[bag]] at a [[farmer's workshop]] to yield leaves made of this material and having these properties. Said material should have [LEAF_MAT] to permit proper stockpiling.

|-
| {{text anchor|EXTRACT_STILL_VIAL}}
|
* [[Material token|material]]
| Permits processing the plant into a [[vial]] at a [[still]] to yield extract made of this material. Said material should have [EXTRACT_STORAGE:FLASK].

|-
| {{text anchor|EXTRACT_VIAL}}
|
*[[Material token|material]]
| Permits processing the plant into a [[vial]] at a [[farmer's workshop]] to yield extract made of this material. Said material should have [EXTRACT_STORAGE:FLASK].

|-
| {{text anchor|EXTRACT_BARREL}}
|
* [[Material token|material]]
| Permits processing the plant into a [[barrel]] at a [[farmer's workshop]] to yield extract made of this material. Said material should have [EXTRACT_STORAGE:BARREL].

|}

==Grass Tokens==
These tokens are used only for [[grass]]es.

{| {{prettytable}}
|- style='background-color:#ddd'
! width="20%" | Token
! width="20%" | Arguments
! width="60%" | Description

|-
| {{text anchor|GRASS}}
|
| Makes the plant behave as a type of grass.

|-
| {{text anchor|GRASS_TILES}}
|
*tile
*tile
*tile
*tile
| Specifies the 4 tiles used to represent grass of this type. If VARIED_GROUND_TILES is disabled in d_init.txt, these are seemingly ignored. Defaults to 46:44:96:39 (.,`').

|-
| {{text anchor|ALT_PERIOD}}
|
*period
*offset
| How often the grass switches between its main tiles and alternate tiles. The "period" value determines how quickly (in frames) the grass animates, and the "offset" value specifies how much of that time is spent displaying the alternate tiles. If the "offset" value is greater than or equal to the "period" value, the grass will only display using the alternate tiles.{{verify}} Defaults to 0:0.

|-
| {{text anchor|ALT_GRASS_TILES}}
|
*tile
*tile
*tile
*tile
| When used with ALT_PERIOD, specifies the 4 alternate tiles used to represent grass of this type. Defaults to 46:44:96:39 (.,`'). Dead grass does not animate.

|-
| {{text anchor|GRASS_COLORS}}
|
*color 1 (fore:back:bright)
*color 2 (fore:back:bright)
*dry color (fore:back:bright)
*dead color (fore:back:bright)
| Specifies the color of this grass. Defaults to 2:0:1:2:0:0:6:0:1:6:0:0 (light green, dark green, yellow, brown).
|}

{{Category|Modding}}
{{Category|Tokens}}

v0.31:Labor token

2026-04-04T00:29:05Z

Quietust:

{{quality|Exceptional|18:10, 28 April 2011 (UTC)}}{{av}}

A list of all labor tokens, mainly used in custom buildings.

{| {{prettytable}} class="sortable"
|- style='background-color:#ddd'
! # !! Token !! Labor
|-
| 0 || {{text anchor|MINE}} || [[Mining]]
|-
| 1 || {{text anchor|HAUL_STONE}} || [[Stone hauling]]
|-
| 2 || {{text anchor|HAUL_WOOD}} || [[Wood hauling]]
|-
| 3 || {{text anchor|HAUL_BODY}} || [[Burial]]
|-
| 4 || {{text anchor|HAUL_FOOD}} || [[Food hauling]]
|-
| 5 || {{text anchor|HAUL_REFUSE}} || [[Refuse hauling]]
|-
| 6 || {{text anchor|HAUL_ITEM}} || [[Item hauling]]
|-
| 7 || {{text anchor|HAUL_FURNITURE}} || [[Furniture hauling]]
|-
| 8 || {{text anchor|HAUL_ANIMALS}} || [[Animal hauling]]
|-
| 9 || {{text anchor|CLEAN}} || [[Cleaning]]
|-
| 10 || {{text anchor|CUTWOOD}} || [[Wood cutting]]
|-
| 11 || {{text anchor|CARPENTER}} || [[Carpentry]]
|-
| 12 || {{text anchor|DETAIL}} || [[Stone detailing]]
|-
| 13 || {{text anchor|MASON}} || [[Masonry]]
|-
| 14 || {{text anchor|ARCHITECT}} || [[Architecture]]
|-
| 15 || {{text anchor|ANIMALTRAIN}} || [[Animal training]]
|-
| 16 || {{text anchor|ANIMALCARE}} || [[Animal care]]
|-
| 17 || {{text anchor|DIAGNOSE}} || [[Diagnosis]]
|-
| 18 || {{text anchor|SURGERY}} || [[Surgery]]
|-
| 19 || {{text anchor|BONE_SETTING}} || [[Setting bones]]
|-
| 20 || {{text anchor|SUTURING}} || [[Suturing]]
|-
| 21 || {{text anchor|DRESSING_WOUNDS}} || [[Dressing wounds]]
|-
| 22 || {{text anchor|FEED_WATER_CIVILIANS}} || [[Feed patients/prisoners]]
|-
| 23 || {{text anchor|RECOVER_WOUNDED}} || [[Recovering wounded]]
|-
| 24 || {{text anchor|BUTCHER}} || [[Butchery]]
|-
| 25 || {{text anchor|TRAPPER}} || [[Trapper]]
|-
| 26 || {{text anchor|DISSECT_VERMIN}} || [[Small animal dissection]]
|-
| 27 || {{text anchor|LEATHER}} || [[Leatherworking]]
|-
| 28 || {{text anchor|TANNER}} || [[Tanning]]
|-
| 29 || {{text anchor|BREWER}} || [[Brewing]]
|-
| 30 || {{text anchor|ALCHEMIST}} || [[Alchemy]]
|-
| 31 || {{text anchor|SOAP_MAKER}} || [[Soap making]]
|-
| 32 || {{text anchor|WEAVER}} || [[Weaving]]
|-
| 33 || {{text anchor|CLOTHESMAKER}} || [[Clothesmaking]]
|-
| 34 || {{text anchor|MILLER}} || [[Milling]]
|-
| 35 || {{text anchor|PROCESS_PLANT}} || [[Plant processing]]
|-
| 36 || {{text anchor|MAKE_CHEESE}} || [[Cheese making]]
|-
| 37 || {{text anchor|MILK}} || [[Milking]]
|-
| 38 || {{text anchor|COOK}} || [[Cooking]]
|-
| 39 || {{text anchor|PLANT}} || [[Farming (fields)]]
|-
| 40 || {{text anchor|HERBALIST}} || [[Plant gathering]]
|-
| 41 || {{text anchor|FISH}} || [[Fishing]]
|-
| 42 || {{text anchor|CLEAN_FISH}} || [[Fish cleaning]]
|-
| 43 || {{text anchor|DISSECT_FISH}} || [[Fish dissection]]
|-
| 44 || {{text anchor|HUNT}} || [[Hunting]]
|-
| 45 || {{text anchor|SMELT}} || [[Furnace operating]]
|-
| 46 || {{text anchor|FORGE_WEAPON}} || [[Weaponsmithing]]
|-
| 47 || {{text anchor|FORGE_ARMOR}} || [[Armoring]]
|-
| 48 || {{text anchor|FORGE_FURNITURE}} || [[Blacksmithing]]
|-
| 49 || {{text anchor|METAL_CRAFT}} || [[Metalcrafting]]
|-
| 50 || {{text anchor|CUT_GEM}} || [[Gem cutting]]
|-
| 51 || {{text anchor|ENCRUST_GEM}} || [[Gem setting]]
|-
| 52 || {{text anchor|WOOD_CRAFT}} || [[Woodcrafting]]
|-
| 53 || {{text anchor|STONE_CRAFT}} || [[Stonecrafting]]
|-
| 54 || {{text anchor|BONE_CARVE}} || [[Bone carving]]
|-
| 55 || {{text anchor|GLASSMAKER}} || [[Glassmaking]]
|-
| 56 || {{text anchor|EXTRACT_STRAND}} || [[Strand extraction]]
|-
| 57 || {{text anchor|SIEGECRAFT}} || [[Siege engineering]]
|-
| 58 || {{text anchor|SIEGEOPERATE}} || [[Siege operating]]
|-
| 59 || {{text anchor|BOWYER}} || [[Crossbow-making]]
|-
| 60 || {{text anchor|MECHANIC}} || [[Mechanics]]
|-
| 61 || {{text anchor|POTASH_MAKING}} || [[Potash making]]
|-
| 62 || {{text anchor|LYE_MAKING}} || [[Lye making]]
|-
| 63 || {{text anchor|DYER}} || [[Dyeing]]
|-
| 64 || {{text anchor|BURN_WOOD}} || [[Wood burning]]
|-
| 65 || {{text anchor|OPERATE_PUMP}} || [[Pump operating]]
|-
| 66 || {{text anchor|SHEARER}} || [[Shearing]]
|-
| 67 || {{text anchor|SPINNER}} || [[Spinning]]
|-
| 68 || {{text anchor|POTTERY}} || [[Pottery]]
|-
| 69 || {{text anchor|GLAZING}} || [[Glazing]]
|-
| 70 || {{text anchor|PRESSING}} || [[Pressing]]
|-
| 71 || {{text anchor|BEEKEEPING}} || [[Beekeeping]]
|-
| 72 || {{text anchor|WAX_WORKING}} || [[Wax working]]
|}

{{Category|Modding}}{{Category|Tokens}}

v0.34:Labor token

2026-04-04T00:28:41Z

Quietust:

{{Quality|Superior|21:42, 17 May 2015 (UTC)}}
{{av}}

A list of all labor tokens, mainly used in custom buildings.

{| {{prettytable}} class="sortable"
|- style='background-color:#ddd'
! # !! Token !! Labor
|-
| 0 || {{text anchor|MINE}} || [[Mining]]
|-
| 1 || {{text anchor|HAUL_STONE}} || [[Stone hauling]]
|-
| 2 || {{text anchor|HAUL_WOOD}} || [[Wood hauling]]
|-
| 3 || {{text anchor|HAUL_BODY}} || [[Burial]]
|-
| 4 || {{text anchor|HAUL_FOOD}} || [[Food hauling]]
|-
| 5 || {{text anchor|HAUL_REFUSE}} || [[Refuse hauling]]
|-
| 6 || {{text anchor|HAUL_ITEM}} || [[Item hauling]]
|-
| 7 || {{text anchor|HAUL_FURNITURE}} || [[Furniture hauling]]
|-
| 8 || {{text anchor|HAUL_ANIMALS}} || [[Animal hauling]]
|-
| 9 || {{text anchor|CLEAN}} || [[Cleaning]]
|-
| 10 || {{text anchor|CUTWOOD}} || [[Wood cutting]]
|-
| 11 || {{text anchor|CARPENTER}} || [[Carpentry]]
|-
| 12 || {{text anchor|DETAIL}} || [[Stone detailing]]
|-
| 13 || {{text anchor|MASON}} || [[Masonry]]
|-
| 14 || {{text anchor|ARCHITECT}} || [[Architecture]]
|-
| 15 || {{text anchor|ANIMALTRAIN}} || [[Animal training]]
|-
| 16 || {{text anchor|ANIMALCARE}} || [[Animal care]]
|-
| 17 || {{text anchor|DIAGNOSE}} || [[Diagnosis]]
|-
| 18 || {{text anchor|SURGERY}} || [[Surgery]]
|-
| 19 || {{text anchor|BONE_SETTING}} || [[Setting bones]]
|-
| 20 || {{text anchor|SUTURING}} || [[Suturing]]
|-
| 21 || {{text anchor|DRESSING_WOUNDS}} || [[Dressing wounds]]
|-
| 22 || {{text anchor|FEED_WATER_CIVILIANS}} || [[Feed patients/prisoners]]
|-
| 23 || {{text anchor|RECOVER_WOUNDED}} || [[Recovering wounded]]
|-
| 24 || {{text anchor|BUTCHER}} || [[Butchery]]
|-
| 25 || {{text anchor|TRAPPER}} || [[Trapper]]
|-
| 26 || {{text anchor|DISSECT_VERMIN}} || [[Small animal dissection]]
|-
| 27 || {{text anchor|LEATHER}} || [[Leatherworking]]
|-
| 28 || {{text anchor|TANNER}} || [[Tanning]]
|-
| 29 || {{text anchor|BREWER}} || [[Brewing]]
|-
| 30 || {{text anchor|ALCHEMIST}} || [[Alchemy]]
|-
| 31 || {{text anchor|SOAP_MAKER}} || [[Soap making]]
|-
| 32 || {{text anchor|WEAVER}} || [[Weaving]]
|-
| 33 || {{text anchor|CLOTHESMAKER}} || [[Clothesmaking]]
|-
| 34 || {{text anchor|MILLER}} || [[Milling]]
|-
| 35 || {{text anchor|PROCESS_PLANT}} || [[Plant processing]]
|-
| 36 || {{text anchor|MAKE_CHEESE}} || [[Cheese making]]
|-
| 37 || {{text anchor|MILK}} || [[Milking]]
|-
| 38 || {{text anchor|COOK}} || [[Cooking]]
|-
| 39 || {{text anchor|PLANT}} || [[Farming (fields)]]
|-
| 40 || {{text anchor|HERBALIST}} || [[Plant gathering]]
|-
| 41 || {{text anchor|FISH}} || [[Fishing]]
|-
| 42 || {{text anchor|CLEAN_FISH}} || [[Fish cleaning]]
|-
| 43 || {{text anchor|DISSECT_FISH}} || [[Fish dissection]]
|-
| 44 || {{text anchor|HUNT}} || [[Hunting]]
|-
| 45 || {{text anchor|SMELT}} || [[Furnace operating]]
|-
| 46 || {{text anchor|FORGE_WEAPON}} || [[Weaponsmithing]]
|-
| 47 || {{text anchor|FORGE_ARMOR}} || [[Armoring]]
|-
| 48 || {{text anchor|FORGE_FURNITURE}} || [[Blacksmithing]]
|-
| 49 || {{text anchor|METAL_CRAFT}} || [[Metalcrafting]]
|-
| 50 || {{text anchor|CUT_GEM}} || [[Gem cutting]]
|-
| 51 || {{text anchor|ENCRUST_GEM}} || [[Gem setting]]
|-
| 52 || {{text anchor|WOOD_CRAFT}} || [[Woodcrafting]]
|-
| 53 || {{text anchor|STONE_CRAFT}} || [[Stonecrafting]]
|-
| 54 || {{text anchor|BONE_CARVE}} || [[Bone carving]]
|-
| 55 || {{text anchor|GLASSMAKER}} || [[Glassmaking]]
|-
| 56 || {{text anchor|EXTRACT_STRAND}} || [[Strand extraction]]
|-
| 57 || {{text anchor|SIEGECRAFT}} || [[Siege engineering]]
|-
| 58 || {{text anchor|SIEGEOPERATE}} || [[Siege operating]]
|-
| 59 || {{text anchor|BOWYER}} || [[Crossbow-making]]
|-
| 60 || {{text anchor|MECHANIC}} || [[Mechanics]]
|-
| 61 || {{text anchor|POTASH_MAKING}} || [[Potash making]]
|-
| 62 || {{text anchor|LYE_MAKING}} || [[Lye making]]
|-
| 63 || {{text anchor|DYER}} || [[Dyeing]]
|-
| 64 || {{text anchor|BURN_WOOD}} || [[Wood burning]]
|-
| 65 || {{text anchor|OPERATE_PUMP}} || [[Pump operating]]
|-
| 66 || {{text anchor|SHEARER}} || [[Shearing]]
|-
| 67 || {{text anchor|SPINNER}} || [[Spinning]]
|-
| 68 || {{text anchor|POTTERY}} || [[Pottery]]
|-
| 69 || {{text anchor|GLAZING}} || [[Glazing]]
|-
| 70 || {{text anchor|PRESSING}} || [[Pressing]]
|-
| 71 || {{text anchor|BEEKEEPING}} || [[Beekeeping]]
|-
| 72 || {{text anchor|WAX_WORKING}} || [[Wax working]]
|-
| 73 || {{text anchor|HANDLE_VEHICLES}} || [[Push/haul vehicles]]
|}

{{Category|Modding}}{{Category|Tokens}}

v0.34:Interaction token

2026-04-04T00:27:35Z

Quietust:

{{av}}

The following tokens can be used to define and use interactions.

==Interaction Definitions==
{| {{prettytable}}
|- bgcolor="#C0C0C0"
! Token
! Context
! Arguments
! Description

|-
| {{text anchor|I_SOURCE}}
| Global
| type
| Defines what things are capable of triggering this interaction. Can be specified multiple times. Valid values:
* REGION - The interaction takes place in particular types of regions in the world.
* UNDERGROUND_SPECIAL - The interaction takes place in [[Demonic fortress|curious underground structure]]s.
* SECRET - The interaction is a secret that can be learned by particular individuals.
* DISTURBANCE - The interaction is triggered when disturbing a [[tomb]].
* DEITY - The interaction is inflicted upon mortals by the gods.
* ATTACK - The interaction is triggered by an attack during combat.
* INGESTION - The interaction is triggered by eating or drinking something.
* CREATURE_ACTION - The interaction is triggered by an explicit action.

|-
| {{text anchor|IS_HIST_STRING_1}}
| Within I_SOURCE
| text
| Describes what the interaction did to a historical figure. Displayed after the name of the historical figure that performed the interaction.

[IS_HIST_STRING_1: cursed ]

|-
| {{text anchor|IS_HIST_STRING_2}}
| Within I_SOURCE
| text
| Describes what the interaction did to a historical figure. Displayed after the name of the historical figure that was targeted by the interaction.

[IS_HIST_STRING_2: to assume the form of a lizard-like monster every full moon]

|-
| {{text anchor|IS_FREQUENCY}}
| Within I_SOURCE
| Number
| Presumably, the probability of biome specified by [IS_REGION] to have this interaction.

|-
| {{text anchor|IS_NAME}}
| Within I_SOURCE
| string
| Generally used with secrets, describes what the secret is about.

|-
| {{text anchor|IS_REGION}}
| Within I_SOURCE:REGION
| Region type
| Indicates what types regions are capable of performing this interaction. Can be specified multiple times. Valid values:
* ANY
* ANY_TERRAIN
* NORMAL_ALLOWED
* EVIL_ALLOWED
* GOOD_ALLOWED
* SAVAGE_ALLOWED
* EVIL_ONLY
* GOOD_ONLY
* SAVAGE_ONLY
* Region type - SWAMP, DESERT, FOREST, MOUNTAINS, OCEAN, LAKE, GLACIER, TUNDRA, GRASSLAND, HILLS

|-
| {{text anchor|IS_SPHERE}}
| Within I_SOURCE:SECRET
| [[Sphere]]
| Indicates the sphere to which this secret pertains. Only one sphere can be defined for each [I_SOURCE:SECRET] token, thus several [I_SOURCE:SECRET] tokens required to create a valid custom secret, which belongs to several different spheres

|-
| {{text anchor|IS_SECRET_GOAL}}
| Within I_SOURCE:SECRET
| Secret Goal token
| Indicates why somebody would want to learn the secret. Valid values:
* IMMORTALITY

|-
| {{text anchor|IS_SECRET}}
| Within I_SOURCE:SECRET
| Secret Flag
| Indicates how the secret can be learned. Valid values:
* SUPERNATURAL_LEARNING_POSSIBLE - the secret can be learned by supernatural means
* MUNDANE_RESEARCH_POSSIBLE - the secret can be researched by mundane means
* MUNDANE_TEACHING_POSSIBLE - the secret can be taught to apprentices
* MUNDANE_RECORDING_POSSIBLE:objects/text/(book_title).txt:objects/text/(book_topic).txt - the secret can be written in books with the specified title. If this tag is present, a slab will be created upon learning the secret by supernatural means.
|-
| {{text anchor|IS_USAGE_HINT}}
| Within I_SOURCE:DEITY
| Usage Hint token
| Indicates why a deity would choose to perform this interaction. See CDI:USAGE_HINT below for valid values - in this context, MAJOR_CURSE is the only value that makes sense.

|-
| {{text anchor|I_TARGET}}
| Global
| id, type
| Specifies what things this interaction acts upon. Can be specified multiple times. Valid values:
* CORPSE - Also includes pieces of corpses
* CREATURE
* MATERIAL
* LOCATION

|-
| {{text anchor|IT_LOCATION}}
| Within I_TARGET
| Location
| Narrows down exactly what the interaction targets. Valid values:
* CONTEXT_REGION - Can only be used by IS_REGION interactions.
* CONTEXT_CREATURE
* CONTEXT_ITEM - Used when the target is a CORPSE.
* CONTEXT_BP - Use body part from CDI:BP_REQUIRED token (below).
* CONTEXT_LOCATION

|-
| {{text anchor|IT_MANUAL_INPUT}}
| Within I_TARGET
| text
| Tells the player what they should be selecting.

|-
| {{text anchor|IT_AFFECTED_CREATURE}}
| Within I_TARGET:CORPSE or I_TARGET:CREATURE
| CREATURE:CASTE
| Specifies specific creatures the interaction can target.

|-
| {{text anchor|IT_AFFECTED_CLASS}}
| Within I_TARGET:CORPSE or I_TARGET:CREATURE
| Creature class
| Specifies creature classes the interaction can target.

|-
| {{text anchor|IT_IMMUNE_CREATURE}}
| Within I_TARGET:CORPSE or I_TARGET:CREATURE
| CREATURE:CASTE
| Specifies specific creatures the interaction cannot target.

|-
| {{text anchor|IT_IMMUNE_CLASS}}
| Within I_TARGET:CORPSE or I_TARGET:CREATURE
| Creature class
| Specifies creature classes the interaction cannot target.

|-
| {{text anchor|IT_REQUIRES}}
| Within I_TARGET:CORPSE or I_TARGET:CREATURE
| Creature token or property
| Indicates that the target must have the specified property. Valid values:
* FIT_FOR_ANIMATION - Any corpse or body part that can become a zombie (heads, hands, etc.)
* FIT_FOR_RESURRECTION - The target corpse's UPPERBODY must be attached.
* HAS_BLOOD
* MORTAL
* NO_AGING
* STERILE
* Creature token: BLOODSUCKER, CAN_LEARN, CAN_SPEAK, CRAZED, EXTRAVISION, LIKES_FIGHTING (or LIKESFIGHTING), MISCHIEVOUS (or MISCHIEVIOUS), NO_CONNECTIONS_FOR_MOVEMENT, NO_DIZZINESS, NO_DRINK, NO_EAT, NO_FEVERS, NO_PHYS_ATT_GAIN, NO_PHYS_ATT_RUST, NO_SLEEP, NO_THOUGHT_CENTER_FOR_MOVEMENT, NOBREATHE, NOEMOTION, NOEXERT, NOFEAR, NONAUSEA, NOPAIN, NOSTUN, NOT_LIVING, NOTHOUGHT, OPPOSED_TO_LIFE, PARALYZEIMMUNE, SUPERNATURAL, TRANCES, UTTERANCES

|-
| {{text anchor|IT_FORBIDDEN}}
| Within I_TARGET:CORPSE or I_TARGET:CREATURE
| Creature token or property
| Indicates that the target must not have the specified property. Valid values are the same as for IT_REQUIRES.

|-
| {{text anchor|IT_CANNOT_TARGET_IF_ALREADY_AFFECTED}}
| Within I_TARGET:CORPSE or I_TARGET:CREATURE
|
| Prevents the interaction from targeting a creature that's already under the effect of the same interaction.

|-
| {{text anchor|IT_CANNOT_HAVE_SYNDROME_CLASS}}
| Within I_TARGET:CORPSE or I_TARGET:CREATURE
| [[Syndrome]] class
| Prevents the interaction from targeting a creature under the effects of a syndrome having the specified SYN_CLASS value.

|-
| {{text anchor|IT_MATERIAL}}
| Within I_TARGET:MATERIAL
| Type
| Specifies the type of material the interaction targets. Valid values:
* FLOW:Breath attack token - Specifies an attack not made of any material.
* MATERIAL:[[Material token]]:Breath attack token - Specifies an attack made of a specific material.
* CONTEXT_MATERIAL - Use material from CDI:MATERIAL token (below).

|-
| {{text anchor|I_EFFECT}}
| Global
| type
| Specifies what the interaction does to the targets. Can be specified multiple times. Valid values:
* ANIMATE - Raises the target corpse/bodypart as a zombie. The zombie will always be hostile to life and will retain no information about its original personality/loyalties. Syndromes can also be specified within this tag.
* RESURRECT - Returns the creature to life. This can be used on parts that are not FIT_FOR_RESURRECTION, but only the main part (with an UPPERBODY attached) will remain loyal to its original faction. Syndromes can also be specified within this tag.
* ADD_SYNDROME - Adds one or more syndromes. The actual syndrome is specified with the [SYNDROME] tag.
* CLEAN - Cleans off most liquids/dust covering the creature.
* HIDE - Allows the creature to hide even if another creature can see it.
* CONTACT - Causes the creatures to touch. The interaction's range must be TOUCHABLE.
* MATERIAL_EMISSION - Used within the MATERIAL_EMISSION interaction.

|-
| {{text anchor|IE_TARGET}}
| Within I_EFFECT
| ID
| Specifies which I_TARGET this effect will be applied to

|-
| {{text anchor|IE_INTERMITTENT}}
| Within I_EFFECT
| Frequency
| Indicates that the effect happens intermittently and specifies roughly how often. Valid values:
* WEEKLY

|-
| {{text anchor|IE_IMMEDIATE}}
| Within I_EFFECT
|
| Indicates that the effect happens immediately.

|-
| {{text anchor|IE_LOCATION}}
| Within I_EFFECT
| Location Hint
| Indicates where the effect can take place. Valid values:
* IN_WATER
* IN_MAGMA
* NO_WATER
* NO_MAGMA

|-
| {{text anchor|IE_ARENA_NAME}}
| Within I_EFFECT
| text
| Allows the interaction to be applied to newly spawned creatures in Arena mode.

|-
| {{text anchor|IE_GRIME_LEVEL}}
| Within I_EFFECT:CLEAN
| amount?
| [IE_GRIME_LEVEL:2] appears in the default cleaning interaction, and may indicate amount of grime cleaned.

|-
| {{text anchor|IE_SYNDROME_TAG}}
| Within I_EFFECT:CLEAN
| Syndrome flag
| Indicates that cleaning off materials will activate their syndromes if they have this flag.

|-
| {{text anchor|GENERATED}}
| Global
|
| Indicates that this is a generated interaction. Cannot be specified in user-defined raws.

|}

==Interaction Usage==
In order to actually use an interaction, add the [[creature token]] [CAN_DO_INTERACTION:NAME] followed by a series of [CDI:...] tokens. Interactions can also be granted through [[syndrome]]s using the token [CE_CAN_DO_INTERACTION] (plus the same series of CDI tokens).

The following CDI tokens can be specified:
{| {{prettytable}}
|- bgcolor="#C0C0C0"
! Token
! Arguments
! Description

|-
| {{text anchor|INTERACTION}}
| id
| Specifies which interaction can be performed. Only to be used with syndromes, since CE_CAN_DO_INTERACTION does not allow specifying the interaction ID directly.

|-
| {{text anchor|TARGET}}
| target ID, target types
| Specifies how the creature chooses what to . Target ID refers to an I_TARGET defined in the interaction itself. Multiple target types can be specified. If no target is specified, creature will target any available target within range, even through walls. Valid target types:
* LINE_OF_SIGHT - the source needs to be able to see the target
* TOUCHABLE - the source needs to be able to touch the target
* DISTURBER_ONLY - the target must be whoever disturbed the source
* SELF_ALLOWED - the target can be the source
* SELF_ONLY - the target '''must''' be the source

|-
| {{text anchor|TARGET_RANGE}}
| target ID, range
| Specifies how far away the target can be, in tiles.

|-
| {{text anchor|LOCATION_HINT}}
| Location Hint (see above)
| ?

|-
| {{text anchor|USAGE_HINT}}
| Usage hint token
| Indicates when and how CPU-controlled creatures will use the interaction. If no hint is specified, the interaction will be used whenever a valid target is available. Valid values:
* MAJOR_CURSE - Used in disturbance curses and deity curses. Targets the tomb disturber/temple defiler.
* GREETING - Creatures will target 'friendly' creatures, usually at random.
* CLEAN_SELF - Creature targets itself when covered in liquids or dust.
* CLEAN_FRIEND - Same, but targets other friendly units.
* ATTACK - Targets enemy creatures in combat. If the interaction specifies SELF_ONLY, CPU-controlled creatures will never use it.
* FLEEING - Used when fleeing an enemy. Creature will target itself.

|-
| {{text anchor|ADV_NAME}}
| text
| Specifies the interaction's name when used in Adventurer mode.

|-
| {{text anchor|MAX_TARGET_NUMBER}}
| ID, number
| Specifies the maximum number of things that can be selected for a particular I_TARGET.

|-
| {{text anchor|WAIT_PERIOD}}
| number
| Controls how often the interaction can be used.

|-
| {{text anchor|VERBAL}}
|
| Only creatures that can speak will be able to use the interaction. Might also be needed for VERBAL_SPEECH.

|-
| {{text anchor|VERBAL_SPEECH}}
| filename
| Specifies what the creature says when they perform the interaction. Filename path is relative to /data/speech.

|-
| {{text anchor|CAN_BE_MUTUAL}}
|
| Presumably, allows two creatures with this same interaction to use it on each other simultaneously, for example cats cleaning each other.

|-
| {{text anchor|FREE_ACTION}}
|
| Indicates that performing the interaction doesn't take any time.

|-
| {{text anchor|VERB}}
| self:other:mutual
| When a creature uses the interaction, a message will display, describing the source as doing this.

|-
| {{text anchor|VERB_REVERSE}}
| ?
| ?

|-
| {{text anchor|TARGET_VERB}}
| self:other
| When a creature uses the interaction, a message will display, describing the target as doing this.

|-
| {{text anchor|BP_REQUIRED}}
| Body part criteria
| Indicates that a particular body part must be present in order to perform the interaction. Criteria are BY_CATEGORY:category, BY_TYPE:type, or BY_TOKEN:token.

|-
| {{text anchor|FLOW}}
| [[Syndrome#Breath Attack Types|Breath attack token]]
| Causes the interaction to create an effect not made of any material. Only makes sense for FIREBALL, FIREJET, or DRAGONFIRE.

|-
| {{text anchor|MATERIAL}}
| [[Material token]]:Breath attack token
| Causes the interaction to create an effect made of a specific material. Doesn't make sense for FIREBALL, FIREJET, or DRAGONFIRE.

|}

==See Also==
* [[Syndrome]]

{{Category|Modding}}
{{Category|Tokens}}

40d:Ethic

2026-04-04T00:24:58Z

Quietust:

{{quality|Exceptional|21:18, 30 March 2011 (UTC)}}{{av}}
== List of acceptable ethics tags==

Ethics tags are used in the entity_default file to determine how races feel about various issues. Example usage: [ETHIC:ASSAULT:PUNISH_SERIOUS]

Entities will start [[war|wars]] with each other over ethical differences during [[World generation|world gen]]. Ongoing wars may influence fortress mode, causing early [[siege|sieges]].

== Ethics types ==
{| {{prettytable}}
|- bgcolor="#dddddd"
!Token
!Extra Information
|-
|{{text anchor|ASSAULT}}
| Determines punishments for the "Assault" and "Disorderly Conduct" [[justice|crime]]s.
|-
|{{text anchor|EAT_SAPIENT_KILL}}
| Civilizations that accept this type of cannibalism and civilizations that do not may go to war over "the devouring of the bodies of sapient beings" in world-gen. Members of civilizations that accept this type of cannibalism will devour the bodies of creatures they kill in world-gen.
|-
|{{text anchor|EAT_SAPIENT_OTHER}}
| Civilizations that accept this type of cannibalism and civilizations that do not may go to war over "the devouring of the bodies of sapient beings" in world-gen. Adds meat and other materials from creatures who can learn into trade.
|-
|{{text anchor|KILL_ANIMAL}}
| Civilizations that accept killing animals and civilizations that do not may go to war over "the treatment of animals."
|-
|{{text anchor|KILL_ENEMY}}
|
|-
|{{text anchor|KILL_ENTITY_MEMBER}}
| Determines punishments for the "Murder" [[justice|crime]]. Members of a civilization that accepts murder may kill other entity members in world-gen.
|-
|{{text anchor|KILL_NEUTRAL}}
|
|-
|{{text anchor|KILL_PLANT}}
| This includes a race's position towards wood - a response between MISGUIDED and UNTHINKABLE (see below) causes the entity to refuse wooden objects in trade and also prohibits them from bringing caravan [[wagon]]s.

Civilizations that accept killing plants and civilizations that do not may go to war in world-gen.
|-
|{{text anchor|LYING}}
| Civilizations that accept lying and civilizations that do not may go to war over "truthfulness" in world-gen.
|-
|{{text anchor|MAKE_TROPHY_ANIMAL}}
| Civilizations that accept making this type of trophy and civilizations that do not may go to war over "the display of war and hunting trophies" in world-gen.
|-
|{{text anchor|MAKE_TROPHY_SAME_RACE}}
| Civilizations that accept making this type of trophy and civilizations that do not may go to war over "the display of war and hunting trophies" in world-gen.
|-
|{{text anchor|MAKE_TROPHY_SAPIENT}}
| Civilizations that accept making this type of trophy and civilizations that do not may go to war over "the display of war and hunting trophies" in world-gen.
|-
|{{text anchor|OATH_BREAKING}}
| Civilizations that accept oath-breaking and civilizations that do not may go to war over "a formalized agreement" in world-gen.
|-
|{{text anchor|SLAVERY}}
| Civilizations that accept slavery will take the former population of sites they conquer as slaves in world-gen.
|-
|{{text anchor|THEFT}}
|
|-
|{{text anchor|TORTURE_ANIMALS}}
| Civilizations that accept this type of torture and civilizations that do not may go to war in world-gen.
|-
|{{text anchor|TORTURE_AS_EXAMPLE}}
|
|-
|{{text anchor|TORTURE_FOR_FUN}}
| Civilizations that accept this type of torture and civilizations that do not may go to war over "torture" in world-gen.
|-
|{{text anchor|TORTURE_FOR_INFORMATION}}
|
|-
|{{text anchor|TREASON}}
|
|-
|{{text anchor|TRESPASSING}}
|
|-
|{{text anchor|VANDALISM}}
|Determines punishments for the "Building Destruction" [[justice|crime]]s.
|}

==Ethic value numbers in relation to each other==
The following table describes how entities respond to other cultures, with the observer on the vertical axis and their target on the horizontal axis.
If an entity's accumulated animosity towards another passes a certain threshold (determined by the ruler's personality) then it will run a risk-assessment check. If passed, this will lead to a declaration of war.

In general, entities react much more strongly to actions that violate ''their'' taboos than to the outlawing of their customs in other civilisations.
For example, Civ A finds slavery Acceptable, but Civ B considers it a Capital Offence.
* Civ A will consider Civ B most unreasonable (−5) for executing people over such a non-issue.
* Civ B will be shocked and disgusted (−15) that Civ A engages in such a debased activity.
* The end result is mutual negativity. However, Civ B is 3× ''more'' offended, and much more likely to go to war over the issue — assuming, of course, they think they have a chance of winning.

{| {{prettytable}}
|- bgcolor="#dddddd"
! rowspan=2 colspan=2 |  
! colspan=16 | TARGET
|- bgcolor="#dddddd"
!width=6%| Accept. ||width=6%| Personal ||width=6%| Reperc. ||width=6%| Good ||width=6%| Extreme ||width=6%| Self-Def. ||width=6%| Sanct. ||width=6%| Misguid. ||width=6%| Shun ||width=6%| Appall. ||width=6%| Reprim. ||width=6%| Serious ||width=6%| Exile ||width=6%| Capital ||width=6%| Unthink.
|-
! rowspan=16 | {{rotate|OBSERVER}}     
! Acceptable || {{tc|blue|+1}} || {{tc|blue|+1}} || {{tc|blue|+1}} || 0 || 0 || 0 || 0 || {{tc|red|−1}} || {{tc|red|−2}} || {{tc|red|−2}} || {{tc|red|−2}} || {{tc|red|−3}} || {{tc|red|−5}} || {{tc|red|−5}} || {{tc|red|−2}}
|-
! Personal || {{tc|blue|+1}} || {{tc|blue|+1}} || {{tc|blue|+1}} || 0 || 0 || 0 || 0 || {{tc|red|−1}} || {{tc|red|−2}} || {{tc|red|−2}} || {{tc|red|−2}} || {{tc|red|−3}} || {{tc|red|−5}} || {{tc|red|−5}} || {{tc|red|−2}}
|-
! No Reperc. || {{tc|blue|+1}} || {{tc|blue|+1}} || {{tc|blue|+1}} || 0 || 0 || 0 || 0 || {{tc|red|−1}} || {{tc|red|−2}} || {{tc|red|−2}} || {{tc|red|−2}} || {{tc|red|−3}} || {{tc|red|−5}} || {{tc|red|−5}} || {{tc|red|−2}}
|-
! Good Reas. || 0 || 0 || 0 || {{tc|blue|+2}} || {{tc|blue|+1}} || 0 || 0 || 0 || {{tc|red|−1}} || {{tc|red|−1}} || {{tc|red|−1}} || {{tc|red|−1}} || {{tc|red|−1}} || {{tc|red|−1}} || {{tc|red|−1}}
|-
! Extreme Rs. || {{tc|red|−1}} || {{tc|red|−1}} || 0 || {{tc|blue|+1}} || {{tc|blue|+2}} || 0 || 0 || 0 || {{tc|red|−1}} || {{tc|red|−1}} || {{tc|red|−1}} || {{tc|red|−1}} || {{tc|red|−1}} || {{tc|red|−1}} || {{tc|red|−1}}
|-
! Self-Defence || {{tc|red|−2}} || {{tc|red|−2}} || {{tc|red|−1}} || 0 || {{tc|blue|+1}} || {{tc|blue|+2}} || 0 || 0 || 0 || {{tc|red|−1}} || {{tc|red|−1}} || {{tc|red|−1}} || {{tc|red|−1}} || {{tc|red|−1}} || {{tc|red|−1}}
|-
! Sanctioned || {{tc|red|−2}} || {{tc|red|−2}} || {{tc|red|−1}} || 0 || {{tc|blue|+1}} || 0 || {{tc|blue|+2}} || 0 || 0 || {{tc|red|−1}} || {{tc|red|−1}} || {{tc|red|−1}} || {{tc|red|−1}} || {{tc|red|−1}} || {{tc|red|−1}}
|-
! Misguided || {{tc|red|−1}} || {{tc|red|−1}} || 0 || 0 || 0 || 0 || 0 || {{tc|blue|+2}} || {{tc|blue|+1}} || {{tc|blue|+1}} || {{tc|blue|+1}} || 0 || 0 || {{tc|red|−1}} || {{tc|blue|+1}}
|-
! Shun || {{tc|red|−1}} || {{tc|red|−1}} || 0 || 0 || 0 || 0 || 0 || {{tc|blue|+1}} || {{tc|blue|+2}} || {{tc|blue|+1}} || {{tc|blue|+1}} || 0 || 0 || {{tc|red|−1}} || {{tc|blue|+1}}
|-
! Appalling || {{tc|red|−5}} || {{tc|red|−5}} || {{tc|red|−3}} || {{tc|red|−2}} || {{tc|red|−1}} || {{tc|red|−1}} || {{tc|red|−2}} || {{tc|blue|+1}} || {{tc|blue|+1}} || {{tc|blue|+2}} || {{tc|blue|+1}} || {{tc|blue|+1}} || {{tc|blue|+1}} || 0 || {{tc|blue|+1}}
|-
! Reprimand || {{tc|red|−5}} || {{tc|red|−5}} || {{tc|red|−3}} || {{tc|red|−2}} || {{tc|red|−1}} || {{tc|red|−1}} || {{tc|red|−2}} || {{tc|blue|+1}} || {{tc|blue|+1}} || {{tc|blue|+1}} || {{tc|blue|+2}} || {{tc|blue|+1}} || {{tc|blue|+1}} || 0 || {{tc|blue|+1}}
|-
! Serious || {{tc|red|−10}} || {{tc|red|−10}} || {{tc|red|−7}} || {{tc|red|−3}} || {{tc|red|−2}} || {{tc|red|−2}} || {{tc|red|−3}} || 0 || {{tc|blue|+1}} || {{tc|blue|+1}} || 0 || {{tc|blue|+2}} || {{tc|blue|+1}} || {{tc|blue|+1}} || {{tc|blue|+1}}
|-
! Exile || {{tc|red|−10}} || {{tc|red|−10}} || {{tc|red|−7}} || {{tc|red|−3}} || {{tc|red|−2}} || {{tc|red|−2}} || {{tc|red|−3}} || 0 || {{tc|blue|+1}} || {{tc|blue|+1}} || 0 || {{tc|blue|+1}} || {{tc|blue|+2}} || {{tc|blue|+1}} || {{tc|blue|+1}}
|-
! Capital || {{tc|red|−15}} || {{tc|red|−15}} || {{tc|red|−10}} || {{tc|red|−5}} || {{tc|red|−3}} || {{tc|red|−3}} || {{tc|red|−5}} || 0 || 0 || {{tc|blue|+1}} || 0 || {{tc|blue|+1}} || {{tc|blue|+1}} || {{tc|blue|+2}} || {{tc|blue|+1}}
|-
! Unthinkable || {{tc|red|−15}} || {{tc|red|−15}} || {{tc|red|−10}} || {{tc|red|−5}} || {{tc|red|−3}} || {{tc|red|−3}} || {{tc|red|−5}} || 0 || {{tc|blue|+1}} || {{tc|blue|+1}} || 0 || {{tc|blue|+1}} || {{tc|blue|+1}} || {{tc|blue|+1}} || {{tc|blue|+2}}
|}

All above info was collected and interpreted from the data given by Toady himself at [http://www.bay12forums.com/smf/index.php?topic=22151.msg239689] and confirmed against a disassembly.

v0.31:Ethic

2026-04-04T00:23:55Z

Quietust:

{{quality|Exceptional|18:03, 28 April 2011 (UTC)}}{{av}}
== List of acceptable ethics tags==

Ethics tags are used in the entity_default raw file to determine how races feel about various issues. Relationships between civs are based on their ethics value numbers in relation to each other; Some yield favourable positive numbers or unfavourable negative numbers that result in ethic/civ conflict. Civs with UNTHINKABLE in a specific ethic will happily go to war with a different civ that has ACCEPTABLE in that same ethic type.

Example usage: [ETHIC:ASSAULT:PUNISH_SERIOUS]

In un-modded DF, this corresponds to wars over eating sapients and elves declaring war on everybody for harming plants and hunting/displaying trophies.

== Ethics types ==
{| {{prettytable}}
|- bgcolor="#dddddd"
!Token
!Extra Information
|-
|{{text anchor|ASSAULT}}
|
|-
|{{text anchor|EAT_SAPIENT_KILL}}
| This determines if the race will sometimes devour dead enemy combatants.
|-
|{{text anchor|EAT_SAPIENT_OTHER}}
| This also determines whatever or not a race is willing to butcher other sapients.
|-
|{{text anchor|KILL_ANIMAL}}
|
|-
|{{text anchor|KILL_ENEMY}}
|
|-
|{{text anchor|KILL_ENTITY_MEMBER}}
|
|-
|{{text anchor|KILL_NEUTRAL}}
|
|-
|{{text anchor|KILL_PLANT}}
| This determines a race's position towards wood as well. Setting this ethic's response to MISGUIDED, SHUN, APPALLING, PUNISH_*, or UNTHINKABLE (see below) prohibits the entity from using [[wagon]]s in trade.
|-
|{{text anchor|LYING}}
|
|-
|{{text anchor|MAKE_TROPHY_ANIMAL}}
|
|-
|{{text anchor|MAKE_TROPHY_SAME_RACE}}
|
|-
|{{text anchor|MAKE_TROPHY_SAPIENT}}
|
|-
|{{text anchor|OATH_BREAKING}}
|
|-
|{{text anchor|SLAVERY}}
|
|-
|{{text anchor|THEFT}}
| This determines whether the race will try to steal goods.
|-
|{{text anchor|TORTURE_ANIMALS}}
|
|-
|{{text anchor|TORTURE_AS_EXAMPLE}}
|
|-
|{{text anchor|TORTURE_FOR_FUN}}
|
|-
|{{text anchor|TORTURE_FOR_INFORMATION}}
|
|-
|{{text anchor|TREASON}}
|
|-
|{{text anchor|TRESPASSING}}
|
|-
|{{text anchor|VANDALISM}}
|
|}

==Ethics values==
In order of acceptability:

{| {{prettytable}}
|- bgcolor="#dddddd"
!Token
|-
|{{text anchor|NOT_APPLICABLE}}
|-
|{{text anchor|ACCEPTABLE}}
|-
|{{text anchor|PERSONAL_MATTER}}
|-
|{{text anchor|JUSTIFIED_IF_NO_REPERCUSSIONS}}
|-
|{{text anchor|JUSTIFIED_IF_GOOD_REASON}}
|-
|{{text anchor|JUSTIFIED_IF_EXTREME_REASON}}
|-
|{{text anchor|JUSTIFIED_IF_SELF_DEFENSE}}
|-
|{{text anchor|ONLY_IF_SANCTIONED}}
|-
|{{text anchor|MISGUIDED}}
|-
|{{text anchor|SHUN}}
|-
|{{text anchor|APPALLING}}
|-
|{{text anchor|PUNISH_REPRIMAND}}
|-
|{{text anchor|PUNISH_SERIOUS}}
|-
|{{text anchor|PUNISH_EXILE}}
|-
|{{text anchor|PUNISH_CAPITAL}}
|-
|{{text anchor|UNTHINKABLE}}
|}

==Ethics value numbers in relation to each other==

Note: These were given by Toady himself [http://www.bay12forums.com/smf/index.php?topic=22151.msg239689]. Anything above listed value indicator is counted for same value difference.

{| {{prettytable}}
|- bgcolor="#dddddd"
!Token
|-
|JUSTIFIED_IF_GOOD_REASON
|<pre>JUSTIFIED_IF_GOOD_REASON +2
JUSTIFIED_IF_EXTREME_REASON +1
SHUN
APPALLING
PUNISH_REPRIMAND
PUNISH_SERIOUS
PUNISH_EXILE
PUNISH_CAPITAL
UNTHINKABLE
-1
</pre>
|-
|JUSTIFIED_IF_EXTREME_REASON
|<pre>JUSTIFIED_IF_GOOD_REASON +1
JUSTIFIED_IF_EXTREME_REASON +2
SHUN
APPALLING
PUNISH_REPRIMAND
PUNISH_SERIOUS
PUNISH_EXILE
PUNISH_CAPITAL
UNTHINKABLE
PERSONAL_MATTER
ACCEPTABLE
-1
</pre>
|-
|JUSTIFIED_IF_SELF_DEFENSE
|<pre>JUSTIFIED_IF_EXTREME_REASON +1
JUSTIFIED_IF_SELF_DEFENSE +2
APPALLING
PUNISH_REPRIMAND
PUNISH_SERIOUS
PUNISH_EXILE
PUNISH_CAPITAL
UNTHINKABLE
JUSTIFIED_IF_NO_REPERCUSSIONS
-1
PERSONAL_MATTER
ACCEPTABLE
-2
</pre>
|-
|ONLY_IF_SANCTIONED
|<pre>ONLY_IF_SANCTIONED +2
JUSTIFIED_IF_EXTREME_REASON +1
JUSTIFIED_IF_NO_REPERCUSSIONS
UNTHINKABLE
APPALLING
PUNISH_REPRIMAND
PUNISH_SERIOUS
PUNISH_EXILE
PUNISH_CAPITAL
-1
PERSONAL_MATTER
ACCEPTABLE
-2
</pre>
|-
|MISGUIDED
|<pre>MISGUIDED +2
SHUN
APPALLING
PUNISH_REPRIMAND
UNTHINKABLE
+1
PUNISH_CAPITAL
PERSONAL_MATTER
ACCEPTABLE
-1
</pre>
|-
|SHUN
|<pre>SHUN +2
MISGUIDED
APPALLING
PUNISH_REPRIMAND
UNTHINKABLE
+1
PUNISH_CAPITAL
PERSONAL_MATTER
ACCEPTABLE
-1
</pre>
|-
|APPALLING
|<pre>PERSONAL_MATTER
ACCEPTABLE
-5
JUSTIFIED_IF_NO_REPERCUSSIONS -3
JUSTIFIED_IF_GOOD_REASON
ONLY_IF_SANCTIONED
-2
JUSTIFIED_IF_EXTREME_REASON
JUSTIFIED_IF_SELF_DEFENSE
-1
SHUN
PUNISH_REPRIMAND
PUNISH_SERIOUS
MISGUIDED
PUNISH_EXILE
UNTHINKABLE
+1
APPALLING +2
</pre>
|-
|PUNISH_REPRIMAND
|<pre>PERSONAL_MATTER
ACCEPTABLE
-5
JUSTIFIED_IF_NO_REPERCUSSIONS -3
JUSTIFIED_IF_GOOD_REASON
ONLY_IF_SANCTIONED
-2
JUSTIFIED_IF_EXTREME_REASON
JUSTIFIED_IF_SELF_DEFENSE
-1
SHUN
PUNISH_SERIOUS
APPALLING
MISGUIDED
PUNISH_EXILE
UNTHINKABLE
+1
PUNISH_REPRIMAND +2
</pre>
|-
|PUNISH_SERIOUS
|<pre>PERSONAL_MATTER
ACCEPTABLE
-10
JUSTIFIED_IF_NO_REPERCUSSIONS
-7
JUSTIFIED_IF_GOOD_REASON
ONLY_IF_SANCTIONED
-3
JUSTIFIED_IF_EXTREME_REASON
JUSTIFIED_IF_SELF_DEFENSE
-2
SHUN
APPALLING
PUNISH_EXILE
UNTHINKABLE
PUNISH_CAPITAL
1
PUNISH_SERIOUS +2
</pre>
|-
|PUNISH_EXILE
|<pre>PERSONAL_MATTER
ACCEPTABLE
-10
JUSTIFIED_IF_NO_REPERCUSSIONS
-7
JUSTIFIED_IF_GOOD_REASON
ONLY_IF_SANCTIONED
-3
JUSTIFIED_IF_EXTREME_REASON
JUSTIFIED_IF_SELF_DEFENSE
-2
SHUN
APPALLING
PUNISH_SERIOUS
UNTHINKABLE
PUNISH_CAPITAL
+1
PUNISH_EXILE +2
</pre>
|-
|PUNISH_CAPITAL
|<pre>PERSONAL_MATTER
ACCEPTABLE
-15
JUSTIFIED_IF_NO_REPERCUSSIONS
-10
JUSTIFIED_IF_GOOD_REASON
ONLY_IF_SANCTIONED
-5
JUSTIFIED_IF_EXTREME_REASON
JUSTIFIED_IF_SELF_DEFENSE
-3
APPALLING
PUNISH_SERIOUS
UNTHINKABLE
PUNISH_EXILE
+1
PUNISH_CAPITAL +2
</pre>
|-
|UNTHINKABLE
|<pre>PERSONAL_MATTER
ACCEPTABLE
-15
JUSTIFIED_IF_NO_REPERCUSSIONS
-10
JUSTIFIED_IF_GOOD_REASON
ONLY_IF_SANCTIONED
-5
JUSTIFIED_IF_EXTREME_REASON
JUSTIFIED_IF_SELF_DEFENSE
-3
SHUN
APPALLING
PUNISH_SERIOUS
PUNISH_EXILE
PUNISH_CAPITAL
+1
UNTHINKABLE
+2
</pre>
|-
|JUSTIFIED_IF_NO_REPERCUSSIONS PERSONAL_MATTER ACCEPTABLE
|<pre>MISGUIDED -1
SHUN
APPALLING
PUNISH_REPRIMAND
UNTHINKABLE
-2
PUNISH_SERIOUS -3
PUNISH_EXILE
PUNISH_CAPITAL
-5
JUSTIFIED_IF_NO_REPERCUSSIONS
PERSONAL_MATTER
ACCEPTABLE
+1
</pre>
|}

{{Category|Modding}}
{{Category|Tokens}}

v0.31:Entity token

2026-04-04T00:22:23Z

Quietust:

{{quality|Exceptional|18:03, 28 April 2011 (UTC)}}{{av}}
These tokens define entities, or civilizations, in entity_*.txt files.

== Gameplay ==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|ADVENTURE_TIER}}
| order
| Allows adventure mode. Dwarves, Elves, and Humans take up tier 3, 2, and 1 respectively. It seems that the best way to use this is to put your entity in the same order as the other tiers. The tiers are in descending order. So you should put a new adventure entity above the Dwarves. Not at the end of the file.
[ADVENTURE_TIER:4]

|-
| {{text anchor|INDIV_CONTROLLABLE}}
|
| Allows the race to be played as an "outsider" in adventure mode. Not having this specified in one of the entities will cause the Adventure mode option to disappear.

|-
| {{text anchor|CIV_CONTROLLABLE}}
|
| Allows fortress mode. If multiple entities have the CIV_CONTROLLABLE token, than in embark mode the specific civs can be chosen by + or - on the civ list screen (by pressing tab), though it will not state what entity the civs belong to. To check which one, tab to the neighbors screen: the entity's race will be at the top. At least one civilization must have this token.

|-
| {{text anchor|CREATURE}}
| creature
|The type of creature that will inhabit the civilization. Multiple entries will be chosen from at random for each civilization.
[CREATURE:DWARF]

|}

== Placement ==

{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|BIOME_SUPPORT}}
|
* [[Biome token|biome]]
* frequency
| Frequency goes from 0 to 10. Higher numbers make the entity more likely to settle there.
[BIOME_SUPPORT:ANY_GRASSLAND:4]

|-
| {{text anchor|START_BIOME}}
| [[Biome token|biome]]
| Birth of the civilization can be performed on this biome.
[START_BIOME:MOUNTAIN]

|-
| {{text anchor|DEFAULT_SITE_TYPE}}
| site type
| Valid site types are DARK_FORTRESS (π), CAVE (•), CAVE_DETAILED (Ω), TREE_CITY (î), and CITY (#). Also recognizes PLAYER_FORTRESS and FORTRESS, though these likely will not work. Defaults to CITY. As of version 0.31.13, dark fortresses, detailed caves, and tree cities can no longer be visited in Adventurer mode.
[DEFAULT_SITE_TYPE:CAVE_DETAILED]

|-
| {{text anchor|LIKES_SITE}}
| site type
| Most residents will try to move to this site type, unless already at one.
[LIKES_SITE:CAVE_DETAILED]

|-
| {{text anchor|TOLERATES_SITE}}
| site type
| Some residents will try to move to this site type, unless already at one.
[TOLERATES_SITE:CITY]

|-
| {{text anchor|WORLD_CONSTRUCTION}}
| construction
| Controls which constructions the civ will build on the world map. Valid constructions are ROAD, TUNNEL, BRIDGE, and WALL.
[WORLD_CONSTRUCTION:BRIDGE]
[WORLD_CONSTRUCTION:ROAD]
[WORLD_CONSTRUCTION:TUNNEL]
[WORLD_CONSTRUCTION:WALL]

|}

== Population ==

{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|START_GROUP_NUMBER}}
| number
| Number of breeding couples to start with per entity. Helps give a boost to weaker civs by giving them more cannon fodder at the beginning of their histories, and better genetic diversity (if that's modeled for that particular creature). Note that single-gender (eg. [FEMALE], [MALE], [NO_GENDER]) creatures will not have breeding couples, so a civilization with only these creatures will not be very likely to survive. As of 40d, although many had problems getting such civilizations to survive, there are those who have demonstrably and repeatedly done so. Presumably if the civ-starting code can't place breeding couples, it doesn't start the civ. However, because the children never grow up, the civ is limited to its original individuals).
[START_GROUP_NUMBER:10]

|-
| {{text anchor|MAX_POP_NUMBER}}
| number
| Max population '''per entity'''. Multiply this by max starting civ to get the total population of the species. Defaults to 500.
[MAX_POP_NUMBER:500]

|-
| {{text anchor|MAX_SITE_POP_NUMBER}}
| number
| Max population per individual site. Generic site types will not hold any more than this number of entities - must be at least 80 for towns to be generated. In general, lower pop numbers mean more sprawl, and higher numbers mean more needing to crawl when entering town stores, which are not affected by this cap. Defaults to 50.
[MAX_SITE_POP_NUMBER:200]

|-
| {{text anchor|MAX_STARTING_CIV_NUMBER}}
| number
| Max number of entities to spawn at world generation. Worldgen picks civs in some sequential order from the raws. Once it reaches the end of the list, it will begin again at the top. Setting this number lower than 100, like say, 7, will cause worldgen to skip over this civ for placement if there are already 7 civs of this type. Note that if all civs are set to lower numbers, and the number of starting civs is set higher than the maximum possible amount of civs in total, it will gracefully stop placing civs and get down to the history aspect of worldgen. Defaults to 3.
[MAX_STARTING_CIV_NUMBER:3]

|}

== Flavor ==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|PERMITTED_BUILDING}}
| building name
| The named, custom building can be built by a civilization in Fortress Mode.
[PERMITTED_BUILDING:SOAP_MAKER]

|-
| {{text anchor|PERMITTED_JOB}}
| [[Unit type token|profession]]
| Allows this job type to be selected. This applies to worldgen creatures, in the embark screen, and in play.
[PERMITTED_JOB:MINER]

|-
| {{text anchor|PERMITTED_REACTION}}
| reaction name
| Allows this reaction to be used by a civilization. It is used primarily in Fortress Mode. When creating custom reactions, this token MUST be present or the player will not be able to use the reaction in Fortress Mode.
[PERMITTED_REACTION:TAN_A_HIDE]

|-
| {{text anchor|CURRENCY_BY_YEAR}}
|
| Causes the civ's currency to be numbered with the year it was minted.

|-
| {{text anchor|CURRENCY}}
|
* inorganic material
* value
| What kind of metals the civ uses for coin minting as well as the value of the coin. Only effective in Adventurer mode due to lack of [[dwarven economy]].
[CURRENCY:SILVER:5]

|-
| {{text anchor|ART_FACET_MODIFIER}}
|
* type
* number
| OWN_RACE, FANCIFUL, EVIL, GOOD
Number goes from 0 to 25600 where 256 is the default.
[ART_FACET_MODIFIER:OWN_RACE:512]

|-
| {{text anchor|ART_IMAGE_ELEMENT_MODIFIER}}
|
* type
* number
| CREATURE, PLANT, TREE, SHAPE, ITEM 0-25600

Determines the chance of each image occurring in that entity's artwork, such as engravings and on artifacts, for default (non-historical) artwork.

[ART_IMAGE_ELEMENT_MODIFIER:TREE:512]

|-
| {{text anchor|ITEM_IMPROVEMENT_MODIFIER}}
|
* type
* number
| ART_IMAGE, COVERED or GLAZED, RINGS_HANGING, BANDS, SPIKES, ITEMSPECIFIC, THREAD, CLOTH, SEWN_IMAGE 0-25600

Determines the chance of the entity using that particular artwork method, such as "encircled with bands" or "menaces with spikes".

[ITEM_IMPROVEMENT_MODIFIER:SPIKES:0]

This also seems to change the amount that the entity will pay for items that are improved in the ways in their tokens.

|-
| {{text anchor|TRANSLATION}}
| language
| What language raw the entity uses.
* If an entity lacks this tag, translations appear to be drawn randomly from all translation files{{verify}}.
[TRANSLATION:DWARF]

|-
| {{text anchor|SELECT_SYMBOL}}
|
* noun
* symbol
| ALL, REMAINING, CIV, SITE, VESSEL, RELIGION, MILITARY_UNIT, TEMPLE, WAR, BATTLE, SIEGE, ROAD, BRIDGE, TUNNEL, WALL
Causes the entity to more often use these symbols in the particular SYM set.
[SELECT_SYMBOL:ALL:PEACE]

|-
| {{text anchor|SUBSELECT_SYMBOL}}
|
* noun
* symbol
| Unknown.

|-
| {{text anchor|CULL_SYMBOL}}
|
* noun
* symbol
| Causes the entity to not use the words in these SYM sets.
[CULL_SYMBOL:ALL:UGLY]

|-
| {{text anchor|FRIENDLY_COLOR}}
| see [[color]]
|
The color of this entity's civilization settlements in the world gen and embark screens. Defaults to 7:0:1.
[FRIENDLY_COLOR:1:0:1]

|}

== Religion ==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|RELIGION}}
| type
|
* REGIONAL_FORCE: The creatures will worship a single force associated with their spheres. Currently hardcoded to only be associated with rivers and nature.
* PANTHEON: The creatures will worship a group of gods, each aligned with their spheres and other appropriate ones as well.

[RELIGION:PANTHEON]

|-
| {{text anchor|RELIGION_SPHERE}}
| sphere
| Can be any available [[Sphere]]. Multiple entries are possible. Choosing a religious sphere will automatically make its opposing sphere not possible for the species to have: adding WATER, for example, means the species will never get FIRE as a religious sphere.

[RELIGION_SPHERE:FORTRESSES]

|-
| {{text anchor|SPHERE_ALIGNMENT}}
|
* type
* number
|
This token forces an entity to favor or disfavor particular religious spheres, causing them to acquire those spheres more often when generating a pantheon.

[SPHERE_ALIGNMENT:TREES:512]

|}

== Leadership ==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|POSITION}}
| string
| Defines a leader/noble position for a civilization. These replace previous tags such as [MAYOR] and [CAN_HAVE_SITE_LEADER] and so on. To define a position further, see [[Position token]].

|-
| {{text anchor|LAND_HOLDER_TRIGGER}}
|
* land holder number
* population
* wealth exported
* created wealth
| Defines when a particular land-holding noble (baron, count, duke in vanilla) will arrive at a fortress.

|-
| {{text anchor|VARIABLE_POSITIONS}}
| Position responsibility or ALL
| Allows a responsibility to be taken up by a dynamically generated position (such as Law-maker).

|}

== Behavior ==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|ETHIC}}
|
*[[ethic]]
*response
| Sets the civ's view of certain behaviors, from capital punishment to completely acceptable. This also causes the civ to look upon opposing ethics with disfavor, if their reaction to it is opposing, and when at extremes (one ACCEPTABLE, another civ UNTHINKABLE for example) they will often go to war over it.
Ex: [ETHIC:EAT_SAPIENT_KILL:ACCEPTABLE]

|-
| {{text anchor|WILL_ACCEPT_TRIBUTE}}
|
| Makes the civ's traders accept offered goods.

|-
| {{text anchor|WANDERER}}, {{text anchor|BEAST_HUNTER}}, {{text anchor|SCOUT}}
|
| The civ will send out these sorts of adventurers in worldgen.

|-
| {{text anchor|ABUSE_BODIES}}
|
| The civilization will mutilate bodies when they are the victors in history-gen warfare, such as hanging bodies from trees, putting them on spikes, and so forth. Adventurers killed in Adventurer mode will sometimes be impaled on spikes wherever they died, with or without this token, and regardless of whether they actually antagonized the townspeople.

|-
| {{text anchor|ACTIVE_SEASON}}
| season
| the season when the civ is most active: when they will trade, interact with you via diplomats, and/or invade you. Civs can have multiple season entries. Note: If multiple caravans arrive at the same time, you are able to select which civ to trade with at the depot menu. ACTIVE_SEASON tags may be changed for a currently active fort.
[ACTIVE_SEASON:AUTUMN]

|-
| {{text anchor|AMBUSHER}}
|
| When invading sneaks around and shoots at straggling members of your society. They will spawn on the edge of the map and will only be visible when one of their party are spotted; this can be quite dangerous to undefended trade depots.

|-
| {{text anchor|AT_PEACE_WITH_WILDLIFE}}
|
| Will not attack wildlife, and will not be attacked by them, even if you have them in your party. This can be somewhat disconcerting when attacked by bears in the forest and your elven ally sits back and does nothing.

|-
| {{text anchor|BABYSNATCHER}}
|
| Sends thieves to steal babies. Also sends ambush parties to harass your civilization. Without this tag, enemy civs will only siege, and will siege as early as they would otherwise babysnatch. This can happen as early as the first year of the fort! In addition, babysnatcher civs will snatch children during worldgen, allowing them to become part of the civ if they do not escape.

Note: If the playable civ in Fortress Mode has this tag (ie. you add BABYSNATCHER to the Dwarf entity) then the roles will be reversed and elves and humans will siege and ambush and goblins will trade with you.

|-
| {{text anchor|BUILDS_OUTDOOR_FORTIFICATIONS}}
|
| Makes the civilization build castles.

|-
| {{text anchor|BANDITRY}}
| percentage
| Sets a percentage of the entity population to be used as bandits.

|-
| {{text anchor|DIPLOMAT_BODYGUARDS}}
|
| Intended to cause visiting diplomats to be accompanied by a pair of soldiers. Does not work due to a long-standing bug.

|-
| {{text anchor|INVADERS_IGNORE_NEUTRALS}}
|
|

|-
| {{text anchor|ITEM_THIEF}}
|
| Sends thieves to steal items. This will also occur in history generation, and thieves will have the "thief" profession. Items stolen in history gen will be scattered around that creature's home.

|-
| {{text anchor|LOCAL_BANDITRY}}
|
| Causes the entity to send out patrols that can ambush adventurers.

|-
| {{text anchor|MERCHANT_BODYGUARDS}}
|
| Causes merchants to be accompanied by soldiers.

|-
| {{text anchor|MERCHANT_NOBILITY}}
|
| No known effect.

|-
| {{text anchor|PROGRESS_TRIGGER_POPULATION}}
| level
| 0 to 5, civ will come to site once population at site has reached that level. If multiple progress triggers exist for a civ, it will come when any one of them is fulfilled instead of waiting for all of them to be reached. 0 means that no population requirement is needed for interaction, but only appears to apply to diplomacy and trade and is ignored by sieges. 1 corresponds to 20 dwarves, 2 to 50 dwarves, 3 to 80, 4 to 110, and 5 to 140. Progress triggers may be changed, added, or deleted for a currently active fort. Note: hostile civs require that the population trigger be fulfilled as well as at least one other trigger before attacking.

|-
| {{text anchor|PROGRESS_TRIGGER_PRODUCTION}}
| level
| 0 to 5, civ will come to site once created wealth has reached that level. If multiple progress triggers exist for a civ, it will come when any one of them is fulfilled instead of waiting for all of them to be reached. Progress triggers may be changed, added, or deleted for a currently active fort.

|-
| {{text anchor|PROGRESS_TRIGGER_TRADE}}
| level
| 0 to 5, civ will come to site once exported goods has reached that level. If multiple progress triggers exist for a civ, it will come when any one of them is fulfilled instead of waiting for all of them to be reached. Progress triggers may be changed, added, or deleted for a currently active fort.

|-
| {{text anchor|PROGRESS_TRIGGER_POP_SIEGE}}
| level
| 0 to 5, civ will begin to send sieges against the player civ when this level is reached if it is hostile.

If multiple progress triggers exist for a civ, it will come when any one of them is fulfilled instead of waiting for all of them to be reached. 0 corresponds to no population requirement capable of causing interaction; i.e. population changes do not cause sieges to come. 1 corresponds to 20 dwarves, 2 to 50 dwarves, 3 to 80, 4 to 110, and 5 to 140.

|-
| {{text anchor|PROGRESS_TRIGGER_PROD_SIEGE}}
| level
| 0 to 5, civ will begin to send sieges against the player civ when this level is reached if it is hostile.

|-
| {{text anchor|PROGRESS_TRIGGER_TRADE_SIEGE}}
| level
| 0 to 5, civ will begin to send sieges against the player civ when this level is reached if it is hostile.

|-
| {{text anchor|SIEGER}}
|
| Will start campfires and wait around at the edge of your map for a month or two before rushing in to attack.

|-
| {{text anchor|SKULKING}}
|
| This makes the severity of attacks depend on the extent of item/baby thievery rather than the passage of time.

|-
| {{text anchor|TREE_CAP_DIPLOMACY}}
|
| Makes the entity angry if you cut down too many trees. They will send a warning first.

|-
| {{text anchor|LAYER_LINKED}}
|
| Defines if a civilization is a hidden subterranean entity, such as batman civilizations.

|-
| {{text anchor|UNDEAD_CANDIDATE}}
|
| Unknown.

|}

== Items and Animals Used ==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|AMMO}}
| item token
|
[AMMO:ITEM_AMMO_BOLTS]

|-
| {{text anchor|ARMOR}}
|
* item token
* rarity
|Rarity is optional. Permitted rarity values are RARE, UNCOMMON, FORCED (anything else is treated as COMMON).
[ARMOR:ITEM_ARMOR_PLATEMAIL:COMMON]

|-
| {{text anchor|DIGGER}}
| item token
|
[DIGGER:ITEM_WEAPON_PICK]

|-
| {{text anchor|GLOVES}}
|
* item token
* rarity
| Rarity is optional. Permitted rarity values are RARE, UNCOMMON, FORCED (anything else is treated as COMMON).
[GLOVES:ITEM_GLOVES_GLOVES:COMMON]

|-
| {{text anchor|HELM}}
|
* item token
* rarity
| Rarity is optional. Permitted rarity values are RARE, UNCOMMON, FORCED (anything else is treated as COMMON).
[HELM:ITEM_HELM_HELM:COMMON]

|-
| {{text anchor|INSTRUMENT}}
| item token
|
[INSTRUMENT:ITEM_INSTRUMENT_FLUTE]

|-
| {{text anchor|PANTS}}
|
* item token
* rarity
| Rarity is optional. Permitted rarity values are RARE, UNCOMMON, FORCED (anything else is treated as COMMON).
[PANTS:ITEM_PANTS_PANTS:COMMON]

|-
| {{text anchor|SHIELD}}
| item token
|
[SHIELD:ITEM_SHIELD_SHIELD]

|-
| {{text anchor|SHOES}}
|
* item token
* rarity
| Rarity is optional. Permitted rarity values are RARE, UNCOMMON, FORCED (anything else is treated as COMMON).
[SHOES:ITEM_SHOES_SHOES:COMMON]

|-
| {{text anchor|SIEGEAMMO}}
| item token
|
[SIEGEAMMO:ITEM_SIEGEAMMO_BALLISTA]

|-
| {{text anchor|TOOL}}
| item token
|
[TOOL:ITEM_TOOL_NEST_BOX]

|-
| {{text anchor|TOY}}
| item token
|
[TOY:ITEM_TOY_PUZZLEBOX]

|-
| {{text anchor|TRAPCOMP}}
| item token
|
[TRAPCOMP:ITEM_TRAPCOMP_GIANTAXEBLADE]

|-
| {{text anchor|WEAPON}}
| item token
|
[WEAPON:ITEM_WEAPON_AXE_BATTLE]

|-
| {{text anchor|USE_ANIMAL_PRODUCTS}}
|
|

|-
| {{text anchor|USE_ANY_PET_RACE}}
|
| Assuming it passes other checks, any creature in their list of usables (from common domestic if they have that or from the surrounding 7x7 or so of squares and map features in those squares) which has PET or PET_EXOTIC will be available as a pet (next time, it'll let them use mounts/pullers/pack animals of any kind as well, but I'm not sure this matters in the stock raws). This notion of the initial usable creature list, which then gets pared down or otherwise considered, applies below as well. All common domestic and equipment creatures are also added to the initial list.

|-
| {{text anchor|USE_CAVE_ANIMALS}}
|
| If they don't have it, creatures with exclusively subterranean biomes are skipped.

|-
| {{text anchor|USE_EVIL_ANIMALS}}
|
| Don't have it -> EVIL creatures skipped.

|-
| {{text anchor|USE_EVIL_PLANTS}}
|
| As EVIL creatures for all uses of plants.

|-
| {{text anchor|USE_EVIL_WOOD}}
|
| As EVIL creatures for all uses of wood.

|-
| {{text anchor|USE_GOOD_ANIMALS}}
|
| Don't have it -> GOOD creatures skipped.

|-
| {{text anchor|USE_GOOD_PLANTS}}
|
| As GOOD creatures for all uses of plants.

|-
| {{text anchor|USE_GOOD_WOOD}}
|
| As GOOD creatures for all uses of wood.

|-
| {{text anchor|USE_MISC_PROCESSED_WOOD_PRODUCTS}}
|
| If wood is available locally, and the relevant professions are permitted, controls availability of lye, charcoal, potash and pearlash.

|-
| {{text anchor|COMMON_DOMESTIC_MOUNT}}
|
| If a creature has MOUNT and the relevant COMMON_DOMESTIC_x tag (or COMMON_DOMESTIC for pets), it will be allowed if it passes the other checks.

|-
| {{text anchor|COMMON_DOMESTIC_PACK}}
|
| If a creature has PACK_ANIMAL and the relevant COMMON_DOMESTIC_x tag (or COMMON_DOMESTIC for pets), it will be allowed if it passes the other checks. Also seems to be required currently for trading to occur.

|-
| {{text anchor|COMMON_DOMESTIC_PET}}
|
| If a creature has PET and the relevant COMMON_DOMESTIC_x tag (or COMMON_DOMESTIC for pets), it will be allowed if it passes the other checks. Also seems to be required to have any animals at all, including those used in trading.

|-
| {{text anchor|COMMON_DOMESTIC_PULL}}
|
| If a creature has WAGON_PULLER and the relevant COMMON_DOMESTIC_x tag (or COMMON_DOMESTIC for pets), it will be allowed if it passes the other checks.

|-
| {{text anchor|RIVER_PRODUCTS}}
|
| Allow civ to use river products in the goods it has available for trade.

|-
| {{text anchor|OCEAN_PRODUCTS}}
|
| Allow civ to use ocean products (including [[amber]] and [[coral]]) in the goods it has available for trade.

|-
| {{text anchor|INDOOR_FARMING}}
|
| Allow civ to use underground plant products in the goods it has available for trade.

|-
| {{text anchor|OUTDOOR_FARMING}}
|
| Allow civ to use outdoor plant products in the goods it has available for trade.

|-
| {{text anchor|CLOTHING}}
|
| Civ members will attempt to wear clothing.

|-
| {{text anchor|SUBTERRANEAN_CLOTHING}}
|
| Will wear things made of spider silk and other subterranean materials.

|-
| {{text anchor|EQUIPMENT_IMPROVEMENTS}}
|
| Adds decorations to equipment based on the level of the generated unit. Also improves item quality.

|-
| {{text anchor|IMPROVED_BOWS}}
|
| Adds decorations to weapons generated for bowman and master bowman. An elf hack.

|-
| {{text anchor|METAL_PREF}}
|
| Needs testing.

|-
| {{text anchor|STONE_PREF}}
|
| Enables creatures of this entity to bring stones in trade. Also seems to enable the use of metals smelted from ore, such as iron or copper.

|-
| {{text anchor|WOOD_WEAPONS}}
|
| Causes members to be able to use wooden weapons.

|-
| {{text anchor|WOOD_ARMOR}}
|
| Causes members to be able to use wooden armor.

|-
| {{text anchor|GEM_PREF}}
|
| Enables creatures of this entity to bring gems in trade.

|-
| {{text anchor|INDOOR_WOOD}}
|
| Allow civ to trade subterranean wood types, such as tower-cap and fungiwood logs.

|-
| {{text anchor|OUTDOOR_WOOD}}
|
| Allow civ to use outdoor wood types, such as mangrove and oak.

|}

== Tissue Styling Related Tokens ==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|TISSUE_STYLE}}
|
*tissue???
| Presumably selects tissue to set cultural style parameters for. Needs testing.

|-
| {{text anchor|TS_MAINTAIN_LENGTH}}
|
*length?
*???
| Presumably sets culturally preferred tissue length for selected tissue. Needs testing.

|-
| {{text anchor|TS_PREFERRED_SHAPING}}
| ???
| Presumably sets culturally preferred tissue shapings for selected tissue. Needs testing.

{{Category|Modding}}
{{Category|Tokens}}

v0.31:Building token

2026-04-04T00:16:02Z

Quietust:

{{quality|Fine|22:04, 2 March 2011 (UTC)}}{{av}}

'''Building tokens''' control the functionality of custom buildings.

All custom buildings are defined as objects of type BUILDING_WORKSHOP or BUILDING_FURNACE; workshops show up in the {{K|b}}-{{K|w}} menu, while furnaces show up in the {{K|b}}-{{K|e}} menu.

You also must add any new custom buildings to the [[Entity token|civilization]] that you want to use it.

Additionally, furnaces must be designed by an [[architect]] before being constructed (and will gain [[quality]] accordingly), though they will always use the labor(s) specified in the building definition rather than ones based on the materials being used.

{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|NAME}}
| name
| The name of the custom building.

|-
| {{text anchor|NAME_COLOR}}
| [[Color#Modding_color|fg:bg:bright]]
| The color of the building's name when {{K|q}}uerying it. Seemingly ignored for furnaces, which are hardcoded to 4:0:1.

|-
| {{text anchor|DIM}}
| width:height
| The size of the custom building, in number of tiles. Defaults to 3:3. Maximum possible size is 31x31.

|-
| {{text anchor|WORK_LOCATION}}
| x:y
| The tile (1:1 for upper-left) in which dwarves will stand when they are performing tasks. Defaults to 3:3 (bottom-right).

|-
| {{text anchor|BUILD_LABOR}}
| [[labor token]]
| The labor required to construct the custom building. If multiple BUILD_LABOR tokens are specified, then any of the indicated labors can be used to construct the building; if none are specified, then no labors are required. For furnaces, this labor does not come into play until after the workshop has been designed by an [[architect]].

|-
| {{text anchor|BUILD_KEY}}
| key token
| The shortcut key used in the Build menu for selecting the custom building.

|-
| {{text anchor|BLOCK}}
|
* row
* tiles...
| Specifies whether or not each workshop tile blocks movement. The first parameter is the row (1 = top), and each subsequent parameter is a 0 (nonblocking) or 1 (blocking) for each column, left to right.

|-
| {{text anchor|TILE}}
|
* stage
* row
* tiles...
| Specifies the characters used to represent the custom building. The first parameter is the building stage, varying from 0 (awaiting construction) to N (completed) where N is between 1 and 3, the 2nd parameter is the row number, and each subsequent parameter is a character number (or literal character enclosed in 'quotes').

|-
| {{text anchor|COLOR}}
|
* stage
* row
* colors...
| Specifies the colors in which the custom building's tiles will be displayed. The first parameter is the building stage, the 2nd parameter is the row number, and subsequent parameters are either sets of 3 numbers (foreground:background:brightness) or the token "MAT" to use the color of the primary building material. MAT may not be available on BUILDING_FURNACEs.{{verify}}

|-
| {{text anchor|BUILD_ITEM}}
|
* quantity
* [[item token]]
* [[material token]]
| Specifies one of the objects necessary to construct the custom building. Each BUILD_ITEM can be followed by zero or more modifiers.

|-
| {{text anchor|NEEDS_MAGMA}}
|
| Specifies that one of the building's tiles (other than the WORK_LOCATION) must be hanging over [[magma]] in order for the building to function. Buildings with this token also ignore the [FUEL] token in their reactions.
|}

==Item Modifiers==
Building items have many of the same modifiers as [[Reactions#Modifiers|reagents]] in custom reactions.

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| [{{text anchor|REACTION_CLASS}}:X]
| Item's material has a [REACTION_CLASS] token with the appropriate ID.
|-
| [{{text anchor|HAS_MATERIAL_REACTION_PRODUCT}}:X]
| Item's material has a [MATERIAL_REACTION_PRODUCT] token with the appropriate ID.
|-
| [{{text anchor|UNROTTEN}}]
| Item must not be rotten, mainly for organic materials.
|-
| [{{text anchor|CONTAINS_LYE}}]
| Item must be a BARREL or TOOL which contains at least one item of type LIQUID_MISC made of LYE.
|-
| [{{text anchor|POTASHABLE}}]
| Alias for [CONTAINS_LYE].
|-
| [{{text anchor|NOT_WEB}}]
| Item must be collected (to distinguish silk thread from webs). Only makes sense for items of type THREAD.
|-
| [{{text anchor|WEB_ONLY}}]
| Item must be undisturbed (to distinguish silk thread from webs). Only makes sense for items of type THREAD.
|-
| [{{text anchor|EMPTY}}]
| If the item is a container, it must be empty.
|-
| [{{text anchor|NOT_CONTAIN_BARREL_ITEM}}]
| If the item is a container, it must not contain [[lye]] or [[milk]]. Not necessary if specifying [EMPTY].
|-
| [{{text anchor|BAG}}]
| Item must be a bag - that is, a BOX made of plant fiber, silk, yarn, or leather.
|-
| [{{text anchor|GLASS_MATERIAL}}]
| Item material must have the [IS_GLASS] token. All 3 types of [[glass]] have this token hardcoded.
|-
| [{{text anchor|BUILDMAT}}]
| Item must be a general [[building material]] - BAR, BLOCKS, BOULDER, or WOOD.
|-
| [{{text anchor|FIRE_BUILD_SAFE}}]
| Item material must be [[fire-safe]]. Only works with building materials (see above) and anvils - all others are considered unsafe.
|-
| [{{text anchor|MAGMA_BUILD_SAFE}}]
| Item material must be [[magma-safe]]. Only works with building materials (see above) and anvils - all others are considered unsafe.
|-
| [{{text anchor|CAN_USE_ARTIFACT}}]
| Item can be an Artifact.
|-
| [{{text anchor|WORTHLESS_STONE_ONLY}}]
| Item material must be non-[[economic]].
|-
| [{{text anchor|ANY_PLANT_MATERIAL}}]
| Item material must be subordinate to a PLANT object.
|-
| [{{text anchor|ANY_SILK_MATERIAL}}]
| Item material must have the [SILK] token.
|-
| [{{text anchor|ANY_YARN_MATERIAL}}]
| Item material must have the [YARN] token.
|-
| [{{text anchor|ANY_SOAP_MATERIAL}}]
| Item material must have the [SOAP] token.
|-
| [{{text anchor|ANY_LEATHER_MATERIAL}}]
| Item material must have the [LEATHER] token.
|-
| [{{text anchor|ANY_BONE_MATERIAL}}]
| Item material must have the [BONE] token.
|-
| [{{text anchor|ANY_STRAND_TISSUE}}]
| Item is made of a tissue having [TISSUE_SHAPE:STRANDS], intended for matching hair and wool. Must be used with [USE_BODY_COMPONENT].
|-
| [{{text anchor|ANY_SHELL_MATERIAL}}]
| Item material must have the [SHELL] token.
|-
| [{{text anchor|ANY_TOOTH_MATERIAL}}]
| Item material must have the [TOOTH] token.
|-
| [{{text anchor|ANY_HORN_MATERIAL}}]
| Item material must have the [HORN] token.
|-
| [{{text anchor|ANY_PEARL_MATERIAL}}]
| Item material must have the [PEARL] token.
|-
| [{{text anchor|USE_BODY_COMPONENT}}]
| Item must be a body part (CORPSE or CORPSEPIECE).
|-
| [{{text anchor|NO_EDGE_ALLOWED}}]
| Item must not have an edge - excludes sharp stones (produced using knapping) and most types of weapon/ammo.
|-
| [{{text anchor|NOT_ENGRAVED}}]
| Item has not been engraved (excludes memorial slabs).
|-
| [{{text anchor|METAL_ORE}}:X]
| Item material must be an ore of the specified metal.
|-
| [{{text anchor|MIN_DIMENSION}}:X]
| Item's dimension must be at least this large. The item type must be BAR, POWDER_MISC, LIQUID_MISC, DRINK, THREAD, or CLOTH for this to work.
|-
| [{{text anchor|HAS_TOOL_USE}}:X]
| Item must be a [[tool]] with the specific TOOL_USE value. The item type must be TOOL:NONE for this to make any sense.
|}

{{Category|Modding}}
{{Category|Tokens}}

v0.34:Position token

2026-04-03T14:51:08Z

Quietust: /* Responsibilities */

{{quality|Exceptional|18:14, 28 April 2011 (UTC)}}{{av}}
These tokens define positions in entity_*.txt files. See [[Entity token]].
==Position Tokens==
These tokens belong in an entity definition. These tokens apply to a position (such as monarch) and should follow the [POSITION:POSITION_NAME] token.

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Arguments
! Description

|-
| {{text anchor|ACCOUNT_EXEMPT}}
|
| The position holder is not subjected to the economy. Less than relevant right now.

|-
| {{text anchor|ALLOWED_CLASS}}
| {{token|CREATURE_CLASS|creature}} Token
| Only creatures with the specified class token can be appointed to this position.

|-
| {{text anchor|ALLOWED_CREATURE}}
| CREATURE:CASTE
| Restricts the position to only the defined caste. Only works with a caste of the entity's current race (If the entity had multiple CREATURE: tokens)

|-
| {{text anchor|APPOINTED_BY}}
| position
| This position can only be chosen to the task from the nobles screen, and is available only if there is an *argument* present. For example, the GENERAL is [APPOINTED_BY:MONARCH]. Contrast [ELECTED]. Being appointed by a MONARCH seems to handle a lot of worldgen stuff and interferes with fort mode titles.

|-
| {{text anchor|BRAG_ON_KILL}}
|
| A creature that kills this position will be sure to talk about it a lot.

|-
| {{text anchor|CHAT_WORTHY}}
|
| In adventure mode, when referencing locations an NPC may mention this position holder living there or having done some deed there.

|-
| {{text anchor|COLOR}}
| color
| Creatures of this position will have this color, instead of their profession color. e.g. [COLOR:5:0:1]

|-
| {{text anchor|COMMANDER}}
| position:ALL
| This position will act as a commander of the specified position{{verify}}. E.g. GENERAL is [COMMANDER:LIEUTENANT:ALL]. Unknown if values other than ALL work.

|-
| {{text anchor|CONQUERED_SITE}}
|
| This position is the puppet ruler left behind at a conquered site.

|-
| {{text anchor|DEMAND_MAX}}
| number (0-100)
| How many [[demand]]s at one time the position can make of the population.

|-
| {{text anchor|DETERMINES_COIN_DESIGN}}
|
| Minted [[coin]]s will have images that reflect the personality of this position holder.

|-
| {{text anchor|DO_NOT_CULL}}
|
| The position won't be culled from Legends as "unimportant" during world generation.

|-
| {{text anchor|DUTY_BOUND}}
|
| Members of this position will never agree to 'join' your character during adventure mode.

|-
| {{text anchor|ELECTED}}
|
| The population will periodically select the most skill-eligible creature to fill this position. Contrast [APPOINTED_BY].

|-
| {{text anchor|EXECUTION_SKILL}}
| weapon skill
| A mandatory subtag of [RESPONSIBILITY:EXECUTIONS]. Determines the weapon chosen by the executioner for his work.

|-
| {{text anchor|EXPORTED_IN_LEGENDS}}
|
| The various members who have filled this role will be listed in the civilisation's history.

|-
| {{text anchor|FLASHES}}
|
| The creature holding this position will visibly flash, like legendary citizens. Represents a properly noble station by default.

|-
| {{text anchor|GENDER}}
| male/female
| The position can only be held by specified gender.

|-
| {{text anchor|KILL_QUEST}}
|
| The position can assign quests to adventurers.

|-
| {{text anchor|LAND_HOLDER}}
| importance tier (1-10)
| The position is a title bestowed by the King. The outpost liaison may offer to appoint a citizen to this position once the wealth requirements given in the LAND_HOLDER_TRIGGER in the entity definition has been met.

|-
| {{text anchor|LAND_NAME}}
| string
| The name the area takes on when under the control of a LAND_HOLDER. E.g. for the DUKE, [LAND_NAME:a duchy]

|-
| {{text anchor|MANDATE_MAX}}
| number (0-100)
| The maximum number of [[mandate]]s the position can make at once.

|-
| {{text anchor|MENIAL_WORK_EXEMPTION}}
|
| The position cannot be assigned labours, and will generally just lounge around like nobles do. Currently does not actually work. {{bug|3721}}

|-
| {{text anchor|MENIAL_WORK_EXEMPTION_SPOUSE}}
|
| The spouse of the position holder doesn't have to work, either. Also doesn't work either. {{bug|3721}}

|-
| {{text anchor|MILITARY_SCREEN_ONLY}}
|
| This position can not be appointed from the nobles screen. Intended for militia captains and other squad leaders to reduce clutter.

|-
| {{text anchor|NAME}}
| singular:plural
| The name of the position.

|-
| {{text anchor|NAME_MALE}}
| singular:plural
| If the creature holding the position is male, this is the position's name. E.g. for MONARCH, [NAME_MALE:king:kings]

|-
| {{text anchor|NAME_FEMALE}}
| singular:plural
| If the creature holding the position is female, this is the position's name. E.g. for MONARCH, [NAME_FEMALE:queen:queens]

|-
| {{text anchor|NUMBER}}
|
* number/AS_NEEDED
| How many of the position there should be. If the [SITE] token exists, this is per site, otherwise this is per civilisation.

|-
| {{text anchor|PRECEDENCE}}
| number (0-30000)
| How important the position is in society; a lower number is more important and displayed higher in the Nobles menu. For MONARCH it's 1, for MILITIA_CAPTAIN it's 200.

|-
| {{text anchor|PUNISHMENT_EXEMPTION}}
|
| The position holder will not be held accountable for his or her crimes. Does not appear to work. {{bug|4589}}

|-
| {{text anchor|QUEST_GIVER}}
|
| The position holder can give quests in Adventurer mode. Functionality in 0.31.13 and later is uncertain.

|-
| {{text anchor|REJECTED_CLASS}}
| {{token|CREATURE_CLASS|creature}} Token
| Creatures of the specified class cannot be appointed to this position.

|-
| {{text anchor|REJECTED_CREATURE}}
| CREATURE:CASTE
| Restricts position holders by CREATURE type.

|-
| {{text anchor|REPLACED_BY}}
| position
| This position is absorbed by another down the line. For example, expedition leader is [REPLACED_BY:MAYOR].

|-
| {{text anchor|REQUIRED_BEDROOM}}
| number (0-1000000)
| The position holder requires a bedroom with at least this value.

|-
| {{text anchor|REQUIRED_BOXES}}
| number (0-100)
| The position holder requires at least this many [[box]]es (i.e. chests or coffers).

|-
| {{text anchor|REQUIRED_CABINETS}}
| number (0-100)
| The position holder requires at least this many [[cabinet]]s.

|-
| {{text anchor|REQUIRED_DINING}}
| number (0-1000000)
| The position holder requires a dining room with at least this value.

|-
| {{text anchor|REQUIRED_OFFICE}}
| number (0-1000000)
| The position holder requires an office with at least this value.

|-
| {{text anchor|REQUIRED_RACKS}}
| number (0-100)
| The position holder requires at least this many [[weapon rack]]s.

|-
| {{text anchor|REQUIRED_STANDS}}
| number (0-100)
| The position holder requires at least this many [[armor stand]]s.

|-
| {{text anchor|REQUIRED_TOMB}}
| number (0-1000000)
| The position holder requires a tomb with at least this value.

|-
| {{text anchor|REQUIRES_POPULATION}}
| number
| The position requires the population to be at least this number before it becomes available or before the position holder will move in.

|-
| {{text anchor|RESPONSIBILITY}}
| responsibility
| The position holder does a thing. See the table below for suitable arguments.

|-
| {{text anchor|RULES_FROM_LOCATION}}
|
| The position holder is the main ruler of his site and tends to stay there. {{verify}} This token is also required for custom position to appear in fortresses and town keeps in adventure mode, like randomly generated lords/ladies.

|-
| {{text anchor|SITE}}
|
| The civilisation will attempt to have this position separate for each site.

|-
| {{text anchor|SLEEP_PRETENSION}}
|
| The position holder will get upset if someone with a higher PRECEDENCE holds quarters with a greater value than their own.

|-
| {{text anchor|SPECIAL_BURIAL}}
|
| The civilisation will inter the corpse of the position holder in a special grave, either in catacombs or in monuments. If that grave is disturbed, the position holder can return as a mummy. {{verify}}

|-
| {{text anchor|SPOUSE}}
| singular:plural
| The name of the position holder's spouse.

|-
| {{text anchor|SPOUSE_FEMALE}}
| singular:plural
| If the spouse of the creature holding the position is female, this is the spouse's position name.

|-
| {{text anchor|SPOUSE_MALE}}
| singular:plural
| If the spouse of the creature holding the position is male, this is the spouse's position name.

|-
| {{text anchor|SQUAD}}
| number:singular:plural
| The position holder is authorized to form a military squad, led by themselves. The number denotes the maximum headcount. The noun used to describe the subordinates (e.g. royal guard) may be a relic from the 40d era.{{verify}}

|-
| {{text anchor|SUCCESSION}}
|
* BY_HEIR / BY_POSITION:position
| How a new position holder is chosen. A single position can have multiple BY_POSITION tokens.

|}

== Responsibilities ==
{| {{prettytable}}
|- bgcolor="#dddddd"
! Argument
! Description

|-
| {{text anchor|ACCOUNTING}}
| Found on bookkeeper. Position will use Record Keeper skill to keep track of stocks.

|-
| {{text anchor|ATTACK_ENEMIES}}
| Found on elven ranger captain and human warrior. Effect unknown.{{verify}}

|-
| {{text anchor|BUILD_MORALE}}
| Found on [[champion]]. Citizens get a special thought for "talking to a pillar of society" when speaking to this noble.

|-
| {{text anchor|COLLECT_TAXES}}
| Found on tax collector. Position goes around and collects the tax money from the populace, under armed escort. Only functions if the dwarven [[economy]] is active, which never happens.

|-
| {{text anchor|EQUIPMENT_MANIFESTS}}
| Has no effect.

|-
| {{text anchor|ESCORT_TAX_COLLECTOR}}
| Found on hammerer. Position serves as one of the tax collector's bodyguards during his rounds. Only functions if the dwarven [[economy]] is active, which never happens.

|-
| {{text anchor|ESTABLISH_COLONY_TRADE_AGREEMENTS}}
| Found on outpost liaison. Position will live in the civilization capital and travels to make trade agreements with its colonies.

|-
| {{text anchor|EXECUTIONS}}
| Found on hammerer. Position executes death penalties with a weapon of the appropriate skill.

|-
| {{text anchor|HEALTH_MANAGEMENT}}
| Found on chief medical dwarf. Position will use Diagnostician skill enable the {{key|z}}-menu health screen.

|-
| {{text anchor|LAW_ENFORCEMENT}}
| Found on sheriff/captain of the guard. Position and its subordinates are in charge of punishing criminals.

|-
| {{text anchor|LAW_MAKING}}
| Found on monarch/landholders. Seems to allow position to receive elf and human diplomats.{{verify}}

|-
| {{text anchor|MAKE_INTRODUCTIONS}}
| Found on diplomat. Allows Elves to make "first contact".

|-
| {{text anchor|MAKE_PEACE_AGREEMENTS}}
| Found on diplomat. Position negotiates peace treaties in order to end wars.

|-
| {{text anchor|MAKE_TOPIC_AGREEMENTS}}
| Found on diplomat. Position negotiates special agreements such as tree cutting quotas.

|-
| {{text anchor|MANAGE_PRODUCTION}}
| Found on manager. Position enables the use of workshop profiles and uses the Organizer skill to process work orders entered in the job manager after the fortress population reaches 20.

|-
| {{text anchor|MEET_WORKERS}}
| Found on expedition leader/mayor. Position holds meetings with unhappy citizens and tries to pacify them with happy thoughts.

|-
| {{text anchor|MILITARY_GOALS}}
| Found on monarch/landholder/leaders. Effect unknown.{{verify}}

|-
| {{text anchor|MILITARY_STRATEGY}}
| Found on general/militia commander. During worldgen, position will go on expeditions to tame exotic creatures.{{verify}}

|-
| {{text anchor|PATROL_TERRITORY}}
| Found on elven ranger captain and human warrior. Effect unknown.{{verify}}

|-
| {{text anchor|RECEIVE_DIPLOMATS}}
| Found on monarch/landholder/leaders. Position will hold meetings with incoming diplomats and liaisons.

|-
| {{text anchor|RELIGION}}
| Found on elven druid. Position informs you about worship cults{{verify}}

|-
| {{text anchor|SORT_AMMUNITION}}
| Has no effect.

|-
| {{text anchor|TAME_EXOTICS}}
| Has no effect.

|-
| {{text anchor|TRADE}}
| Found on broker. Position will use Appraisal skill to display value estimates and trade at the depot when set to broker only. When applied to other civilizations, the position will arrive with the caravan to make trade agreements.

|-
| {{text anchor|UPGRADE_SQUAD_EQUIPMENT}}
| Has no effect.

|}

== Related Tokens ==
The following two ENTITY tokens are not actually position tokens, but bear mentioning on this page because they can modify the way that a civilization's positions behave:

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Arguments
! Description

|-
| {{text anchor|LAND_HOLDER_TRIGGER}}
|
* landholder tier
* population
* wealth exported
* created wealth
| Defines the requirements for the noble ruler promotions. The tier numbers determine which position is used.

|-
| {{text anchor|VARIABLE_POSITIONS}}
| Position responsibility or ALL
| Allows a responsibility to be taken up by a dynamically generated position (such as Law-maker).

|}

== Why Won't My Positions Appear? ==
The way DF determines what positions will actually ''appear'' in your fortress is somewhat counterintuitive and fairly limiting. This guide should help you understand what you can do to actually get your positions working properly.

There are five tokens governing which positions appear in your fortress - LAND_HOLDER, REQUIRES_POPULATION, APPOINTED_BY, ELECTED, and REPLACED_BY. The first two determine when your fortress is eligible for a new position, the next two determine how a new position for which your fortress is eligible can be added, and the fifth allows you to clear up obsolete positions. Unfortunately, they also interact in some strange ways that makes creating interesting position structures difficult.

When you start a new fortress, DF compiles a list of your initial positions. To do this, it looks at the requirements for each position - any position whose only requirement is less than seven dwarves (either because they have no requirement tokens, or because their only requirement tokens are [REQUIRES_POPULATION: =< 7] or [LAND_HOLDER:some trigger whose only requirement is some number of dwarves equal to or less than 7]). Most importantly, ''any'' position whose only requirement is a LAND_HOLDER requirement, regardless of what the trigger for that requirement is, will be added if another eligible starting position is REPLACED_BY it. '''A non-LAND_HOLDER position that is REPLACED_BY a LAND_HOLDER position will never appear.''' With this list compiled, the game culls all positions that are REPLACED_BY another eligible position, and then culls all positions that have the APPOINTED_BY token. '''You may not embark with any appointed positions.''' Any remaining positions are then filled by a dwarf chosen at random.

'''Positions do not automatically appear when you reach their requirements.''' For example, if you remove the ELECTED token from the Mayor, then the Mayor will never appear, even once you reach his required number of dwarves. '''For a position that does not appear at embark to appear in your fortress, it must be APPOINTED_BY another position or ELECTED.'''

Naturally, this is more complicated than it looks. '''APPOINTED_BY positions must be appointed by another position already in your fortress, or a civ-level position. Only LAND_HOLDER positions may be appointed by civ-level positions.''' LAND_HOLDER positions that are APPOINTED_BY civ-level positions are inherently tied to civ-level tokens with the ESTABLISH_COLONY_TRADE_AGREEMENTS responsibility. If a fortress meets the LAND_HOLDER_TRIGGER for a new LAND_HOLDER tier when a caravan leaves, then the next time the outpost liaison or equivalent arrives, he will offer to make you an official colony, which will allow you to select all positions for that LAND_HOLDER level. '''Each time he appears, the outpost liaison will only promote your fortress one tier up the LAND_HOLDER track.''' The biggest problem with this system is that you may set your LAND_HOLDER_TRIGGERS such that you are eligible for the first tier of LAND_HOLDER positions at embark. '''If you are eligible for the first tier of LAND_HOLDER positions at embark, then all first-tier positions will appear twice - once at embark, and again when the outpost liaison comes to appoint you to the first tier.'''

{{Category|Modding}}
{{Category|Tokens}}

v0.31:Position token

2026-04-03T14:49:47Z

Quietust:

{{quality|Exceptional|18:14, 28 April 2011 (UTC)}}{{av}}
These tokens define positions in entity_*.txt files. See [[Entity token]].
==Position Tokens==
These tokens belong in an entity definition. These tokens apply to a position (such as monarch, dungeon master, etc) and should follow the [POSITION:POSITION_NAME] token.

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Arguments
! Description

|-
| {{text anchor|ACCOUNT_EXEMPT}}
|
| The position holder is not subjected to the Dwarven Economy.

|-
| {{text anchor|ALLOWED_CLASS}}
| CREATURE_CLASS Token
| Only creatures with the specified class token can be appointed to this position in Fortress Mode. Has no effect on world generation.

|-
| {{text anchor|ALLOWED_CREATURE}}
| ???
| Unknown - may restrict position holders by CREATURE type.

|-
| {{text anchor|APPOINTED_BY}}
| position
| The position used as an argument selects creatures to fill the role in question. For example, the GENERAL is [APPOINTED_BY:MONARCH].

|-
| {{text anchor|BRAG_ON_KILL}}
|
| A creature that kills this position will be sure to talk about it a lot.

|-
| {{text anchor|CHAT_WORTHY}}
|
| In adventure mode, when referencing locations an NPC may mention this position holder living there or having done some deed there.

|-
| {{text anchor|COLOR}}
| color
| Creatures of this position will have this colour, instead of their profession colour. e.g. [COLOR:5:0:1]

|-
| {{text anchor|COMMANDER}}
| position:ALL
| This position will act as a commander of the specified position{{verify}}. E.g. GENERAL is [COMMANDER:LIEUTENANT:ALL]. Unknown if values other than ALL work.

|-
| {{text anchor|CONQUERED_SITE}}
|
| This position will be available to creatures when the site has been taken over by another civilisation.

|-
| {{text anchor|DEMAND_MAX}}
| number (0-100)
| How many demands at one time the position can make of the population.

|-
| {{text anchor|DETERMINES_COIN_DESIGN}}
|
| Coins minted will have images that reflect the personality of this position holder.

|-
| {{text anchor|DO_NOT_CULL}}
|
| The position won't be culled during world generation.{{verify}}

|-
| {{text anchor|DUTY_BOUND}}
|
| Members of this position will never agree to 'join' your character during adventure mode.

|-
| {{text anchor|ELECTED}}
|
| The population will periodically select the creature to fill this position.

|-
| {{text anchor|EXPORTED_IN_LEGENDS}}
|
| The various members who have filled this role will be listed in the civilisation's history.

|-
| {{text anchor|FLASHES}}
|
| The creature holding this position will flash on the display.

|-
| {{text anchor|GENDER}}
|
*MALE/FEMALE
| The position can only be held by specified gender.

|-
| {{text anchor|KILL_QUEST}}
|
| The position can assign quests to adventurers.

|-
| {{text anchor|LAND_HOLDER}}
| importance tier (1-10)
| The position will arrive when the LAND_HOLDER_TRIGGER in the entity definition has been met.

|-
| {{text anchor|LAND_NAME}}
| string
| The name the area takes on when under the control of a LAND_HOLDER. E.g. for the DUKE, [LAND_NAME:a duchy]

|-
| {{text anchor|MANDATE_MAX}}
| number (0-100)
| The maximum number of mandates the position can make at once.

|-
| {{text anchor|MENIAL_WORK_EXEMPTION}}
|
| The position cannot be assigned labors, and will generally just lounge around like nobles do. Currently does not actually work. {{bug|3721}}

|-
| {{text anchor|MENIAL_WORK_EXEMPTION_SPOUSE}}
|
| The spouse of the position holder doesn't have to work, either. Also doesn't work either. {{bug|3721}}

|-
| {{text anchor|MILITARY_SCREEN_ONLY}}
|
| The position only shows up in the Military screen.{{verify}}

|-
| {{text anchor|NAME}}
| singular:plural
| The name of the position.

|-
| {{text anchor|NAME_MALE}}
| singular:plural
| If the creature holding the position is male, this is the position's name. E.g. for MONARCH, [NAME_MALE:king:kings]

|-
| {{text anchor|NAME_FEMALE}}
| singular:plural
| If the creature holding the position is female, this is the position's name. E.g. for MONARCH, [NAME_FEMALE:queen:queens]

|-
| {{text anchor|NUMBER}}
|
* number/AS_NEEDED
| How many of the position there should be. If the [SITE] token exists, this is per site, otherwise this is per civilisation.

|-
| {{text anchor|PRECEDENCE}}
| number (0-30000)
| How important the position is in society; a lower number is more important. For MONARCH it's 1, for MILITIA_CAPTAIN it's 200.

|-
| {{text anchor|PUNISHMENT_EXEMPTION}}
|
| The position holder will not be held accountable for his or her crimes. Does not appear to work. {{bug|4589}}

|-
| {{text anchor|QUEST_GIVER}}
|
| The position holder can give quests in Adventurer mode. Functionality in 0.31.13 and later is uncertain.

|-
| {{text anchor|REJECTED_CLASS}}
| CREATURE_CLASS Token
| Creatures of the specified class cannot be appointed to this position in Fortress Mode. Has no effect on world generation.

|-
| {{text anchor|REJECTED_CREATURE}}
| ???
| Unknown - may restrict position holders by CREATURE type.

|-
| {{text anchor|REPLACED_BY}}
| position
| For when one position is a lesser form of another. For example, expedition leader is [REPLACED_BY:MAYOR].

|-
| {{text anchor|REQUIRED_BEDROOM}}
| number (0-1000000)
| The position holder requires a bedroom with at least this value.

|-
| {{text anchor|REQUIRED_BOXES}}
| number (0-100)
| The position holder requires at least this many boxes.

|-
| {{text anchor|REQUIRED_CABINETS}}
| number (0-100)
| The position holder requires at least this many cabinets.

|-
| {{text anchor|REQUIRED_DINING}}
| number (0-1000000)
| The position holder requires a dining room with at least this value.

|-
| {{text anchor|REQUIRED_OFFICE}}
| number (0-1000000)
| The position holder requires an office with at least this value.

|-
| {{text anchor|REQUIRED_RACKS}}
| number (0-100)
| The position holder requires at least this many weapon racks.

|-
| {{text anchor|REQUIRED_STANDS}}
| number (0-100)
| The position holder requires at least this many armor stands.

|-
| {{text anchor|REQUIRED_TOMB}}
| number (0-1000000)
| The position holder requires a tomb with at least this value.

|-
| {{text anchor|REQUIRES_POPULATION}}
| number
| The position requires the population to be at least this number before it becomes available or before the position holder will move in.

|-
| {{text anchor|RESPONSIBILITY}}
| responsibility
| See the table below for the available responsibility tokens. E.g. [RESPONSIBILITY:TAME_EXOTICS]

|-
| {{text anchor|RULES_FROM_LOCATION}}
|
| Unknown{{verify}}

|-
| {{text anchor|SITE}}
|
| The civilisation will attempt to have this position separate for each site.

|-
| {{text anchor|SLEEP_PRETENSION}}
|
| The position holder will get upset if someone with a higher precedence holds quarters with a greater value than their own.

|-
| {{text anchor|SPOUSE}}
| singular:plural
| The name of the position holder's spouse.

|-
| {{text anchor|SPOUSE_FEMALE}}
| singular:plural
| If the spouse of the creature holding the position is female, this is the spouse's position name.

|-
| {{text anchor|SPOUSE_MALE}}
| singular:plural
| If the spouse of the creature holding the position is male, this is the spouse's position name.

|-
| {{text anchor|SQUAD}}
| number:singular:plural
| The position holder will be accompanied by this many whatevers; e.g. for HAMMERER, [SQUAD:10:royal guard:royal guards]

|-
| {{text anchor|SUCCESSION}}
|
* BY_HEIR / BY_POSITION:position
| How a new position holder is chosen.

|}

== Responsibilities ==
{| {{prettytable}}
|- bgcolor="#dddddd"
! Argument
! Description

|-
| {{text anchor|ACCOUNTING}}
| Found on bookkeeper. Position will keep track of stockpiles.

|-
| {{text anchor|ATTACK_ENEMIES}}
| Found on elven ranger captain and human warrior. Effect unknown.

|-
| {{text anchor|BUILD_MORALE}}
| Found on [[champion]]. Citizens get a special thought for "talking to a pillar of society" when speaking to this noble.

|-
| {{text anchor|COLLECT_TAXES}}
| Found on tax collector. Will collect taxes if the economy is active (which never happens).

|-
| {{text anchor|EQUIPMENT_MANIFESTS}}
| Previously found on arsenal dwarf. Has no effect.

|-
| {{text anchor|ESCORT_TAX_COLLECTOR}}
| Found on hammerer. Position will accompany the COLLECT_TAXES position during tax collection.

|-
| {{text anchor|ESTABLISH_COLONY_TRADE_AGREEMENTS}}
| Found on outpost liaison. Position will make trade agreements with the civilization's colonies.

|-
| {{text anchor|EXECUTIONS}}
| Found on hammerer. Position will deliver hammerstrikes for great justice.

|-
| {{text anchor|HEALTH_MANAGEMENT}}
| Found on chief medical dwarf. Enables the {{key|z}} menu health screen, as well individual unit health status.

|-
| {{text anchor|LAW_ENFORCEMENT}}
| Found on sheriff/captain of the guard. Position is in charge of imprisoning criminals.

|-
| {{text anchor|LAW_MAKING}}
| Found on monarch/landholders. Effect unknown.

|-
| {{text anchor|MAKE_INTRODUCTIONS}}
| Found on diplomat. Allows civilizations with TREE_CAP_DIPLOMACY to make "first contact" once you have a land holder present at your fortress.

|-
| {{text anchor|MAKE_PEACE_AGREEMENTS}}
| Found on diplomat. Will request peace treaties in order to end wars.

|-
| {{text anchor|MAKE_TOPIC_AGREEMENTS}}
| Found on diplomat. Will make various types of agreements when visiting - tree cutting quotas (for Elves) or simply "such a nice place you've carved out for yourselves".

|-
| {{text anchor|MANAGE_PRODUCTION}}
| Found on manager. Position will verify work orders.

|-
| {{text anchor|MEET_WORKERS}}
| Found on expedition leader/mayor. Dwarves want one of these around to complain to.

|-
| {{text anchor|MILITARY_GOALS}}
| Found on monarch/landholder/leaders. Effect unknown.

|-
| {{text anchor|MILITARY_STRATEGY}}
| Found on general/militia commander. During worldgen, position will go on expeditions to tame exotic creatures. If you are sieged, the creature holding this position may lead a squad when attacking.

|-
| {{text anchor|PATROL_TERRITORY}}
| Found on elven ranger captain and human warrior. Effect unknown.

|-
| {{text anchor|RECEIVE_DIPLOMATS}}
| Found on monarch/landholder/leaders. Position will hold meetings with incoming diplomats/liaisons.

|-
| {{text anchor|RELIGION}}
| Found on elven druid. In Adventurer mode, positions with this token will wander around in Temples (if they exist).

|-
| {{text anchor|SORT_AMMUNITION}}
| Previously found on arsenal dwarf. Has no effect.

|-
| {{text anchor|TAME_EXOTICS}}
| Found on dungeon master. Position will tame creatures with the [PET_EXOTIC] token. Currently non-functional.

|-
| {{text anchor|TRADE}}
| Found on broker. Position will trade at the depot when set to broker only. When applied to other civilizations, the position will arrive with the caravan to make trade agreements.

|-
| {{text anchor|UPGRADE_SQUAD_EQUIPMENT}}
| Previously found on arsenal dwarf. Has no effect.

|}

== Related Tokens ==
The following two ENTITY tokens are not actually position tokens, but bear mentioning on this page because they can modify the way that a civilization's positions behave:

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Arguments
! Description

|-
| {{text anchor|LAND_HOLDER_TRIGGER}}
|
* land holder number
* population
* wealth exported
* created wealth
| Defines when a particular land-holding noble (baron, count, duke in vanilla) will arrive at a fortress.

|-
| {{text anchor|VARIABLE_POSITIONS}}
| Position responsibility or ALL
| Allows a responsibility to be taken up by a dynamically generated position (such as Law-maker).

|}

== Why Won't My Positions Appear? ==
The way DF determines what positions will actually ''appear'' in your fortress is somewhat counterintuitive and fairly limiting. This guide should help you understand what you can do to actually get your positions working properly.

There are five tokens governing which positions appear in your fortress - LAND_HOLDER, REQUIRES_POPULATION, APPOINTED_BY, ELECTED, and REPLACED_BY. The first two determine when your fortress is eligible for a new position, the next two determine how a new position for which your fortress is eligible can be added, and the fifth allows you to clear up obsolete positions. Unfortunately, they also interact in some strange ways that makes creating interesting position structures difficult.

When you start a new fortress, DF compiles a list of your initial positions. To do this, it looks at the requirements for each position - any position whose only requirement is less than seven dwarves (either because they have no requirement tokens, or because their only requirement tokens are [REQUIRES_POPULATION: =< 7] or [LAND_HOLDER:some trigger whose only requirement is some number of dwarves equal to or less than 7]). Most importantly, ''any'' position whose only requirement is a LAND_HOLDER requirement, regardless of what the trigger for that requirement is, will be added if another eligible starting position is REPLACED_BY it. '''A non-LAND_HOLDER position that is REPLACED_BY a LAND_HOLDER position will never appear.''' With this list compiled, the game culls all positions that are REPLACED_BY another eligible position, and then culls all positions that have the APPOINTED_BY token. '''You may not embark with any appointed positions.''' Any remaining positions are then filled by a dwarf chosen at random.

'''Positions do not automatically appear when you reach their requirements.''' For example, if you remove the ELECTED token from the Mayor, then the Mayor will never appear, even once you reach his required number of dwarves. '''For a position that does not appear at embark to appear in your fortress, it must be APPOINTED_BY another position or ELECTED.'''

Naturally, this is more complicated than it looks. '''APPOINTED_BY positions must be appointed by another position already in your fortress, or a civ-level position. Only LAND_HOLDER positions may be appointed by civ-level positions.''' LAND_HOLDER positions that are APPOINTED_BY civ-level positions are inherently tied to civ-level tokens with the ESTABLISH_COLONY_TRADE_AGREEMENTS responsibility. If a fortress meets the LAND_HOLDER_TRIGGER for a new LAND_HOLDER tier when a caravan leaves, then the next time the outpost liaison or equivalent arrives, he will offer to make you an official colony, which will allow you to select all positions for that LAND_HOLDER level. '''Each time he appears, the outpost liaison will only promote your fortress one tier up the LAND_HOLDER track.''' The biggest problem with this system is that you may set your LAND_HOLDER_TRIGGERS such that you are eligible for the first tier of LAND_HOLDER positions at embark. '''If you are eligible for the first tier of LAND_HOLDER positions at embark, then all first-tier positions will appear twice - once at embark, and again when the outpost liaison comes to appoint you to the first tier.'''

{{Category|Modding}}
{{Category|Tokens}}

v0.34:Position token

2026-04-03T14:44:44Z

Quietust:

{{quality|Exceptional|18:14, 28 April 2011 (UTC)}}{{av}}
These tokens define positions in entity_*.txt files. See [[Entity token]].
==Position Tokens==
These tokens belong in an entity definition. These tokens apply to a position (such as monarch) and should follow the [POSITION:POSITION_NAME] token.

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Arguments
! Description

|-
| {{text anchor|ACCOUNT_EXEMPT}}
|
| The position holder is not subjected to the economy. Less than relevant right now.

|-
| {{text anchor|ALLOWED_CLASS}}
| {{token|CREATURE_CLASS|creature}} Token
| Only creatures with the specified class token can be appointed to this position.

|-
| {{text anchor|ALLOWED_CREATURE}}
| CREATURE:CASTE
| Restricts the position to only the defined caste. Only works with a caste of the entity's current race (If the entity had multiple CREATURE: tokens)

|-
| {{text anchor|APPOINTED_BY}}
| position
| This position can only be chosen to the task from the nobles screen, and is available only if there is an *argument* present. For example, the GENERAL is [APPOINTED_BY:MONARCH]. Contrast [ELECTED]. Being appointed by a MONARCH seems to handle a lot of worldgen stuff and interferes with fort mode titles.

|-
| {{text anchor|BRAG_ON_KILL}}
|
| A creature that kills this position will be sure to talk about it a lot.

|-
| {{text anchor|CHAT_WORTHY}}
|
| In adventure mode, when referencing locations an NPC may mention this position holder living there or having done some deed there.

|-
| {{text anchor|COLOR}}
| color
| Creatures of this position will have this color, instead of their profession color. e.g. [COLOR:5:0:1]

|-
| {{text anchor|COMMANDER}}
| position:ALL
| This position will act as a commander of the specified position{{verify}}. E.g. GENERAL is [COMMANDER:LIEUTENANT:ALL]. Unknown if values other than ALL work.

|-
| {{text anchor|CONQUERED_SITE}}
|
| This position is the puppet ruler left behind at a conquered site.

|-
| {{text anchor|DEMAND_MAX}}
| number (0-100)
| How many [[demand]]s at one time the position can make of the population.

|-
| {{text anchor|DETERMINES_COIN_DESIGN}}
|
| Minted [[coin]]s will have images that reflect the personality of this position holder.

|-
| {{text anchor|DO_NOT_CULL}}
|
| The position won't be culled from Legends as "unimportant" during world generation.

|-
| {{text anchor|DUTY_BOUND}}
|
| Members of this position will never agree to 'join' your character during adventure mode.

|-
| {{text anchor|ELECTED}}
|
| The population will periodically select the most skill-eligible creature to fill this position. Contrast [APPOINTED_BY].

|-
| {{text anchor|EXECUTION_SKILL}}
| weapon skill
| A mandatory subtag of [RESPONSIBILITY:EXECUTIONS]. Determines the weapon chosen by the executioner for his work.

|-
| {{text anchor|EXPORTED_IN_LEGENDS}}
|
| The various members who have filled this role will be listed in the civilisation's history.

|-
| {{text anchor|FLASHES}}
|
| The creature holding this position will visibly flash, like legendary citizens. Represents a properly noble station by default.

|-
| {{text anchor|GENDER}}
| male/female
| The position can only be held by specified gender.

|-
| {{text anchor|KILL_QUEST}}
|
| The position can assign quests to adventurers.

|-
| {{text anchor|LAND_HOLDER}}
| importance tier (1-10)
| The position is a title bestowed by the King. The outpost liaison may offer to appoint a citizen to this position once the wealth requirements given in the LAND_HOLDER_TRIGGER in the entity definition has been met.

|-
| {{text anchor|LAND_NAME}}
| string
| The name the area takes on when under the control of a LAND_HOLDER. E.g. for the DUKE, [LAND_NAME:a duchy]

|-
| {{text anchor|MANDATE_MAX}}
| number (0-100)
| The maximum number of [[mandate]]s the position can make at once.

|-
| {{text anchor|MENIAL_WORK_EXEMPTION}}
|
| The position cannot be assigned labours, and will generally just lounge around like nobles do. Currently does not actually work. {{bug|3721}}

|-
| {{text anchor|MENIAL_WORK_EXEMPTION_SPOUSE}}
|
| The spouse of the position holder doesn't have to work, either. Also doesn't work either. {{bug|3721}}

|-
| {{text anchor|MILITARY_SCREEN_ONLY}}
|
| This position can not be appointed from the nobles screen. Intended for militia captains and other squad leaders to reduce clutter.

|-
| {{text anchor|NAME}}
| singular:plural
| The name of the position.

|-
| {{text anchor|NAME_MALE}}
| singular:plural
| If the creature holding the position is male, this is the position's name. E.g. for MONARCH, [NAME_MALE:king:kings]

|-
| {{text anchor|NAME_FEMALE}}
| singular:plural
| If the creature holding the position is female, this is the position's name. E.g. for MONARCH, [NAME_FEMALE:queen:queens]

|-
| {{text anchor|NUMBER}}
|
* number/AS_NEEDED
| How many of the position there should be. If the [SITE] token exists, this is per site, otherwise this is per civilisation.

|-
| {{text anchor|PRECEDENCE}}
| number (0-30000)
| How important the position is in society; a lower number is more important and displayed higher in the Nobles menu. For MONARCH it's 1, for MILITIA_CAPTAIN it's 200.

|-
| {{text anchor|PUNISHMENT_EXEMPTION}}
|
| The position holder will not be held accountable for his or her crimes. Does not appear to work. {{bug|4589}}

|-
| {{text anchor|QUEST_GIVER}}
|
| The position holder can give quests in Adventurer mode. Functionality in 0.31.13 and later is uncertain.

|-
| {{text anchor|REJECTED_CLASS}}
| {{token|CREATURE_CLASS|creature}} Token
| Creatures of the specified class cannot be appointed to this position.

|-
| {{text anchor|REJECTED_CREATURE}}
| CREATURE:CASTE
| Restricts position holders by CREATURE type.

|-
| {{text anchor|REPLACED_BY}}
| position
| This position is absorbed by another down the line. For example, expedition leader is [REPLACED_BY:MAYOR].

|-
| {{text anchor|REQUIRED_BEDROOM}}
| number (0-1000000)
| The position holder requires a bedroom with at least this value.

|-
| {{text anchor|REQUIRED_BOXES}}
| number (0-100)
| The position holder requires at least this many [[box]]es (i.e. chests or coffers).

|-
| {{text anchor|REQUIRED_CABINETS}}
| number (0-100)
| The position holder requires at least this many [[cabinet]]s.

|-
| {{text anchor|REQUIRED_DINING}}
| number (0-1000000)
| The position holder requires a dining room with at least this value.

|-
| {{text anchor|REQUIRED_OFFICE}}
| number (0-1000000)
| The position holder requires an office with at least this value.

|-
| {{text anchor|REQUIRED_RACKS}}
| number (0-100)
| The position holder requires at least this many [[weapon rack]]s.

|-
| {{text anchor|REQUIRED_STANDS}}
| number (0-100)
| The position holder requires at least this many [[armor stand]]s.

|-
| {{text anchor|REQUIRED_TOMB}}
| number (0-1000000)
| The position holder requires a tomb with at least this value.

|-
| {{text anchor|REQUIRES_POPULATION}}
| number
| The position requires the population to be at least this number before it becomes available or before the position holder will move in.

|-
| {{text anchor|RESPONSIBILITY}}
| responsibility
| The position holder does a thing. See the table below for suitable arguments.

|-
| {{text anchor|RULES_FROM_LOCATION}}
|
| The position holder is the main ruler of his site and tends to stay there. {{verify}} This token is also required for custom position to appear in fortresses and town keeps in adventure mode, like randomly generated lords/ladies.

|-
| {{text anchor|SITE}}
|
| The civilisation will attempt to have this position separate for each site.

|-
| {{text anchor|SLEEP_PRETENSION}}
|
| The position holder will get upset if someone with a higher PRECEDENCE holds quarters with a greater value than their own.

|-
| {{text anchor|SPECIAL_BURIAL}}
|
| The civilisation will inter the corpse of the position holder in a special grave, either in catacombs or in monuments. If that grave is disturbed, the position holder can return as a mummy. {{verify}}

|-
| {{text anchor|SPOUSE}}
| singular:plural
| The name of the position holder's spouse.

|-
| {{text anchor|SPOUSE_FEMALE}}
| singular:plural
| If the spouse of the creature holding the position is female, this is the spouse's position name.

|-
| {{text anchor|SPOUSE_MALE}}
| singular:plural
| If the spouse of the creature holding the position is male, this is the spouse's position name.

|-
| {{text anchor|SQUAD}}
| number:singular:plural
| The position holder is authorized to form a military squad, led by themselves. The number denotes the maximum headcount. The noun used to describe the subordinates (e.g. royal guard) may be a relic from the 40d era.{{verify}}

|-
| {{text anchor|SUCCESSION}}
|
* BY_HEIR / BY_POSITION:position
| How a new position holder is chosen. A single position can have multiple BY_POSITION tokens.

|}

== Responsibilities ==
{| {{prettytable}}
|- bgcolor="#dddddd"
! Argument
! Description
! Notes

|-
| {{text anchor|ACCOUNTING}}
| Found on bookkeeper. Position will use Record Keeper skill to keep track of stocks.

|-
| {{text anchor|ATTACK_ENEMIES}}
| Found on elven ranger captain and human warrior. Effect unknown.{{verify}}

|-
| {{text anchor|BUILD_MORALE}}
| Found on [[champion]]. Citizens get a special thought for "talking to a pillar of society" when speaking to this noble.

|-
| {{text anchor|COLLECT_TAXES}}
| Found on tax collector. Position goes around and collects the tax money from the populace, under armed escort.
| Only functions if the dwarven [[economy]] is active, which never happens.

|-
| {{text anchor|EQUIPMENT_MANIFESTS}}
| Originally found on arsenal dwarf. Position will keep track of assigned weapons and equipment.
| Has no effect.

|-
| {{text anchor|ESCORT_TAX_COLLECTOR}}
| Found on hammerer. Position serves as one of the tax collector's bodyguards during his rounds.
| Only functions if the dwarven [[economy]] is active, which never happens.

|-
| {{text anchor|ESTABLISH_COLONY_TRADE_AGREEMENTS}}
| Found on outpost liaison. Position will live in the civilization capital and travels to make trade agreements with its colonies.

|-
| {{text anchor|EXECUTIONS}}
| Found on hammerer. Position executes death penalties with a weapon of the appropriate skill.
|

|-
| {{text anchor|HEALTH_MANAGEMENT}}
| Found on chief medical dwarf. Position will use Diagnostician skill enable the {{key|z}}-menu health screen.
|

|-
| {{text anchor|LAW_ENFORCEMENT}}
| Found on sheriff/captain of the guard. Position and its subordinates are in charge of punishing criminals.

|-
| {{text anchor|LAW_MAKING}}
| Found on monarch/landholders. Seems to allow position to receive elf and human diplomats.{{verify}}

|-
| {{text anchor|MAKE_INTRODUCTIONS}}
| Found on diplomat. Allows Elves to make "first contact".

|-
| {{text anchor|MAKE_PEACE_AGREEMENTS}}
| Found on diplomat. Position negotiates peace treaties in order to end wars.

|-
| {{text anchor|MAKE_TOPIC_AGREEMENTS}}
| Found on diplomat. Position negotiates special agreements such as tree cutting quotas.

|-
| {{text anchor|MANAGE_PRODUCTION}}
| Found on manager. Position enables the use of workshop profiles and uses the Organizer skill to process work orders entered in the job manager after the fortress population reaches 20.

|-
| {{text anchor|MEET_WORKERS}}
| Found on expedition leader/mayor. Position holds meetings with unhappy citizens and tries to pacify them with happy thoughts.

|-
| {{text anchor|MILITARY_GOALS}}
| Found on monarch/landholder/leaders. Effect unknown.{{verify}}

|-
| {{text anchor|MILITARY_STRATEGY}}
| Found on general/militia commander. During worldgen, position will go on expeditions to tame exotic creatures.{{verify}}

|-
| {{text anchor|PATROL_TERRITORY}}
| Found on elven ranger captain and human warrior. Effect unknown.{{verify}}

|-
| {{text anchor|RECEIVE_DIPLOMATS}}
| Found on monarch/landholder/leaders. Position will hold meetings with incoming diplomats and liaisons.

|-
| {{text anchor|RELIGION}}
| Found on elven druid. Position informs you about worship cults{{verify}}

|-
| {{text anchor|SORT_AMMUNITION}}
| Originally found on arsenal dwarf. Position approves changes to ammunition settings in the military screen.
| Has current effect.

|-
| {{text anchor|TAME_EXOTICS}}
| Originally found on dungeon master. Position enables taming exotic creatures and does forge work.
| Removed with the animal training overhaul in 0.34.06. Has no current effect.

|-
| {{text anchor|TRADE}}
| Found on broker. Position will use Appraisal skill to display value estimates and trade at the depot when set to broker only. When applied to other civilizations, the position will arrive with the caravan to make trade agreements.

|-
| {{text anchor|UPGRADE_SQUAD_EQUIPMENT}}
| Originally found on arsenal dwarf. Position approves changes to assigned squad equipment in the military screen.
| Has current effect.

|}

== Related Tokens ==
The following two ENTITY tokens are not actually position tokens, but bear mentioning on this page because they can modify the way that a civilization's positions behave:

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Arguments
! Description

|-
| {{text anchor|LAND_HOLDER_TRIGGER}}
|
* landholder tier
* population
* wealth exported
* created wealth
| Defines the requirements for the noble ruler promotions. The tier numbers determine which position is used.

|-
| {{text anchor|VARIABLE_POSITIONS}}
| Position responsibility or ALL
| Allows a responsibility to be taken up by a dynamically generated position (such as Law-maker).

|}

== Why Won't My Positions Appear? ==
The way DF determines what positions will actually ''appear'' in your fortress is somewhat counterintuitive and fairly limiting. This guide should help you understand what you can do to actually get your positions working properly.

There are five tokens governing which positions appear in your fortress - LAND_HOLDER, REQUIRES_POPULATION, APPOINTED_BY, ELECTED, and REPLACED_BY. The first two determine when your fortress is eligible for a new position, the next two determine how a new position for which your fortress is eligible can be added, and the fifth allows you to clear up obsolete positions. Unfortunately, they also interact in some strange ways that makes creating interesting position structures difficult.

When you start a new fortress, DF compiles a list of your initial positions. To do this, it looks at the requirements for each position - any position whose only requirement is less than seven dwarves (either because they have no requirement tokens, or because their only requirement tokens are [REQUIRES_POPULATION: =< 7] or [LAND_HOLDER:some trigger whose only requirement is some number of dwarves equal to or less than 7]). Most importantly, ''any'' position whose only requirement is a LAND_HOLDER requirement, regardless of what the trigger for that requirement is, will be added if another eligible starting position is REPLACED_BY it. '''A non-LAND_HOLDER position that is REPLACED_BY a LAND_HOLDER position will never appear.''' With this list compiled, the game culls all positions that are REPLACED_BY another eligible position, and then culls all positions that have the APPOINTED_BY token. '''You may not embark with any appointed positions.''' Any remaining positions are then filled by a dwarf chosen at random.

'''Positions do not automatically appear when you reach their requirements.''' For example, if you remove the ELECTED token from the Mayor, then the Mayor will never appear, even once you reach his required number of dwarves. '''For a position that does not appear at embark to appear in your fortress, it must be APPOINTED_BY another position or ELECTED.'''

Naturally, this is more complicated than it looks. '''APPOINTED_BY positions must be appointed by another position already in your fortress, or a civ-level position. Only LAND_HOLDER positions may be appointed by civ-level positions.''' LAND_HOLDER positions that are APPOINTED_BY civ-level positions are inherently tied to civ-level tokens with the ESTABLISH_COLONY_TRADE_AGREEMENTS responsibility. If a fortress meets the LAND_HOLDER_TRIGGER for a new LAND_HOLDER tier when a caravan leaves, then the next time the outpost liaison or equivalent arrives, he will offer to make you an official colony, which will allow you to select all positions for that LAND_HOLDER level. '''Each time he appears, the outpost liaison will only promote your fortress one tier up the LAND_HOLDER track.''' The biggest problem with this system is that you may set your LAND_HOLDER_TRIGGERS such that you are eligible for the first tier of LAND_HOLDER positions at embark. '''If you are eligible for the first tier of LAND_HOLDER positions at embark, then all first-tier positions will appear twice - once at embark, and again when the outpost liaison comes to appoint you to the first tier.'''

{{Category|Modding}}
{{Category|Tokens}}

Bowyer's workshop

2026-04-03T13:53:46Z

Quietust: /* Notes */ it's not just crossbows, but ALL ranged weapons your civ knows how to make

{{Quality|Unrated}}
{{V50 workshop
|name=Bowyer's workshop
|icon=[[File:bowyers_workshop_icon.png]]
|key=b
|job=*[[Crossbow-making]]
|construction=
* [[Building material]] (non-[[economic]])
|construction_job=
*[[Crossbow-making]]
|use=
*[[Bone]]
*[[Wood]]
|production=
*[[Crossbow]]s
}}{{av}}
The '''bowyer's workshop''' is a [[Workshop#Tier 1 Workshops|Tier 1]] [[workshop]] used solely to make [[crossbow]]s (and any other modded ranged weapons) out of [[wood]] or [[bone]]; [[metal]] crossbows are made at a [[metalsmith's forge]] (or [[magma forge]]), and [[ammo]] is made elsewhere. It requires any [[building material]] to construct, and must be built by a [[dwarf]] with the [[bowyer|crossbow-making]] [[labor]] enabled.

Note that many fortresses will never build a bowyer's shop, or will do so only upon arrival and then tear it down again. While wooden or bone crossbows are identical to metal ones for purposes of ranged combat (same accuracy, same range, etc), if (read "when") a marksdwarf's target(s) rush up and force melee combat, a lightweight wooden/bone crossbow is ''significantly'' inferior to any metal crossbow. So, the only advantages of wood/bone crossbows are 1) that they are slightly lighter in weight, and 2) that a fortress doesn't need a [[metal industry]] up and running to produce them, just an [[axe]] and a tree to [[wood cutter|cut down]].

==Tasks==
*Make [[bone]] [[crossbow]]
*Make [[wood]]en [[crossbow]]

==Common Uses==
*Outfit an [[archer]], [[military]] [[squad]], or [[hunter]].

==Notes==
*The name of this workshop will change if your fortress's primary race provides a custom value for the {{token|PROFESSION_NAME|c|BOWYER}} token.
*Use of a [[crossbow]] also requires [[bolt]]s, which are made in a [[craftsdwarf's workshop]] or [[forge]], and a [[quiver]], made in a [[leather works]].
*If you're using a mod which allows dwarves to make and use [[bow]]s and/or [[blowgun]]s (or any other ranged weapons), they will automatically show up here.

==See also==
* [[Weapon]]
* [[Craftsdwarf's workshop]] for making bolts

{{Workshops}}

Bowyer's workshop

2026-04-03T13:46:36Z

Quietust: call out Metal crossbows too, and simplify Ammo mention (since bolts can be made in multiple locations too, depending on material)

{{Quality|Unrated}}
{{V50 workshop
|name=Bowyer's workshop
|icon=[[File:bowyers_workshop_icon.png]]
|key=b
|job=*[[Crossbow-making]]
|construction=
* [[Building material]] (non-[[economic]])
|construction_job=
*[[Crossbow-making]]
|use=
*[[Bone]]
*[[Wood]]
|production=
*[[Crossbow]]s
}}{{av}}
The '''bowyer's workshop''' is a [[Workshop#Tier 1 Workshops|Tier 1]] [[workshop]] used solely to make [[crossbow]]s (and any other modded ranged weapons) out of [[wood]] or [[bone]]; [[metal]] crossbows are made at a [[metalsmith's forge]] (or [[magma forge]]), and [[ammo]] is made elsewhere. It requires any [[building material]] to construct, and must be built by a [[dwarf]] with the [[bowyer|crossbow-making]] [[labor]] enabled.

Note that many fortresses will never build a bowyer's shop, or will do so only upon arrival and then tear it down again. While wooden or bone crossbows are identical to metal ones for purposes of ranged combat (same accuracy, same range, etc), if (read "when") a marksdwarf's target(s) rush up and force melee combat, a lightweight wooden/bone crossbow is ''significantly'' inferior to any metal crossbow. So, the only advantages of wood/bone crossbows are 1) that they are slightly lighter in weight, and 2) that a fortress doesn't need a [[metal industry]] up and running to produce them, just an [[axe]] and a tree to [[wood cutter|cut down]].

==Tasks==
*Make [[bone]] [[crossbow]]
*Make [[wood]]en [[crossbow]]

==Common Uses==
*Outfit an [[archer]], [[military]] [[squad]], or [[hunter]].

==Notes==
*The name of this workshop will change if your fortress's primary race provides a custom value for the {{token|PROFESSION_NAME|c|BOWYER}} token.
*Use of a [[crossbow]] also requires [[bolt]]s, which are made in a [[craftsdwarf's workshop]] or [[forge]], and a [[quiver]], made in a [[leather works]].

==See also==
* [[Weapon]]
* [[Craftsdwarf's workshop]] for making bolts

{{Workshops}}

40d:Ballista arrow

2026-03-30T12:57:03Z

Quietust:

{{av}}{{Quality|Fine|06:10, 16 June 2010 (UTC)}}
Ballista arrows are created at a [[siege workshop]] and used as ammunition by a [[ballista]]. Wooden ballista arrows are made using one log, and (presumably){{verify}} more powerful ones can be made using one log plus a metal [[ballista arrowhead]] from the [[forge]].

Ballista arrows, even mere [[wood]]en ones, are extremely deadly, able to turn a vast swathe of troops into flying [[corpse]]s. It usually takes a [[wall]] or other similar object to stop them, but even then they can still be reused by firing into a wall or raised [[bridge]] above a channel.

Additionally, ballista arrows can be destroyed by hitting too many targets in a row. Each arrow normally has a range of 200 tiles, but impacting a creature will subtract an amount from that range based on the {{token|DAMAGE_PERC|mt}} of the arrow's material: materials with 50% or less damage subtract 50 tiles per hit, materials with 150% or more damage subtract just 5 tiles per hit, and everything in between scales linearly (e.g. [[steel]] subtracts 12, [[iron]] subtracts 27, [[bronze]] subtracts 38, and [[copper]] subtracts 42).

'''See also:''' [[Siege engine]]

{{Category|Ammo}}

23a:Ballista arrow

2026-03-30T12:56:42Z

Quietust: remove redundant statement

{{av}}{{Quality|Fine|06:10, 16 June 2010 (UTC)}}
Ballista arrows are created at a [[siege workshop]] and used as ammunition by a [[ballista]]. Wooden ballista arrows are made using one log, and more powerful ones can be made using one log plus a metal [[ballista arrowhead]] from the [[forge]].

Ballista arrows, even mere [[wood]]en ones, are extremely deadly, able to turn a vast swathe of troops into flying [[corpse]]s. It usually takes a wall or other similar object to stop them.

Additionally, ballista arrows can be destroyed by hitting too many targets in a row. Each arrow normally has a range of 200 tiles, but impacting a creature will subtract an amount from that range based on its material:
* [[Wood]] - 50 tiles
* [[Copper]] - 35 tiles
* [[Bronze]] - 25 tiles
* [[Iron]] - 15 tiles
* [[Steel]] - 10 tiles
* [[Adamantine]] - 5 tiles

'''See also:''' [[Siege engine]]

{{Category|Ammo}}

DF2014:Siege engine

2026-03-30T04:03:31Z

Quietust:

{{Quality|Exceptional|01:09, 4 February 2015 (UTC)}}{{Building|name=Catapult|key=i|key2=c
|job=[[Siege operating]]
|construction=
3 catapult parts
|construction_job=
* [[Siege engineering]]
|purpose=
Stationary weapons platform
}}{{Building|name=Ballista|key=i|key2=b
|job=[[Siege operating]]
|construction=
3 ballista parts
|construction_job=
* [[Siege engineering]]
|purpose=
Stationary weapons platform
}}{{av}}{{buggy}}
A '''siege engine''' in ''Dwarf Fortress'' is half building, half heavy weapon, and includes both the '''catapult''' and the '''ballista'''. Both are capable of launching hazardous projectiles at a tremendous range (more than a screen-width, around 80 to 100 tiles for a catapult and between 130 and 200 tiles for a ballista). A [[ballista arrow]] can kill or injure each creature in its path indiscriminate of friend or foe, but a stone launched from a catapult cannot harm [[dwarf|dwarves]] or [[animal trainer|tamed animals]].

Unlike what the name may imply, siege engines are only deployed defensively, and no [[siege]] will use them against you (although the use of siege engines against your fort is [http://bay12games.com/dwarves/dev.html planned for future versions]).

Siege engines can be made to face in any of the four cardinal directions, but they cannot be moved after placement. They can, however, be rotated, or deconstructed back into their 3 parts (with {{k|q}}-{{k|x}}), to be moved elsewhere. Both the construction of siege equipment and the engine itself require a dwarf with the "[[Siege engineering]]" [[labor]] designated, which uses the "[[Siege engineer]]" [[skill]].

The player determines when (or if) each engine is actively firing or not; when active, a single engine is crewed by a single [[siege operator]].

Ballistae require specially-made [[ammo]] – [[ballista arrow]]s, made from [[wood]]en [[log]]s at the [[siege workshop]] (and optionally tipped with [[metal]] [[ballista arrowhead]]s that have been made at a [[forge]] by a [[weaponsmith]]). Catapults use simple [[stone]] as ammunition. Catapults respect [[economic stone]] restrictions and cannot fire [[clay]] at all.

[[File:siege-engines.jpg|thumb|230px|right|Three types of common siege engines.]]

==Building Siege Engines==
{{key|b}}-{{key|i}}

In order to build a siege engine, you first need to produce (at least) three catapult or ballista parts in the [[siege workshop]]; catapults are made from any 3 '''catapult parts''', and ballistae are made from any 3 '''ballista parts'''. All parts are made from any type of wood at the siege workshop. Beyond that, "parts" are generic - there are no particular "sub-types" of parts beyond the distinction between those for the two different engine types. The quality of the parts has no effect on the siege engine's operation, so there is no need to produce high quality parts except to augment your fortress's architecture value.

Once you have the parts, you may then build the respective siege engine like any other building, selecting the parts that you wish to construct that particular engine with. The assembled siege engine is, effectively, a 3x3 building. It cannot be moved about, other than by taking it down and re-assembling it at the new site. Siege engines do not impede movement, though, so you don't have to worry about building them in a corridor.

==Using Siege Engines (simple)==
{{key|o}} will let you change the orientation, whether the siege engine is pointing north / south / east / west. This takes effect immediately, it does not require a dwarf to come and turn the engine.

{{key|f}} toggles the current status between:
*Not In Use: Dwarves with the [[Siege operator]] [[job]] will reload unloaded engines and leave them unattended.
*Prepare to Fire: Siege operators will load the engine and remain stationed for further commands.
*Fire at Will: Siege operators will fire and load normally.

Once an engine is given orders to fire (or prepare to), a dwarf with the [[Siege operator|siege operating]] labor designated will respond and report to the engine. The dwarf(s) will (re-)load any siege engine that is not currently loaded; there's no way to prevent this short of disabling the labor on all dwarves or forbidding every piece of ammo (or otherwise blocking a [[path]] to it, perhaps by locking [[door]]s or using a [[burrow]].)

[[Ammo]] is destroyed upon landing, unless it falls a z-level, and then it falls harmlessly. (See [[#Catapults as stone movers|below]].)

<diagram>
########
CCC..._#
CCC..._#
CCC..._#
########
</diagram>

The [[channel]] at the end of this firing range preserves the stone. For catapults there is usually so much spare stone that this is not necessary, but it could be used for fast stone transport, or simply to set up a self-contained training area. A similar effect can sometimes be observed when firing a catapult over bumpy ground outside.

The design can be further improved by using a [[drawbridge]] rather than a wall, this way when the drawbridge is raised it acts like a wall deflecting the stone into the channel below. In the case of an attack on your [[fortress]] the drawbridge can be lowered allowing the catapult to fire.

<diagram>
#####################
CCC..._¦.............
CCC..._¦.............
CCC..._¦.............
#####################
</diagram>

Drawbridge raised deflecting stones into channel.

<diagram>
#####################
CCC...[].............
CCC...[].............
CCC...[].............
#####################
</diagram>

Drawbridge lowered allowing catapult to shoot down the corridor.

Since catapults will never hurt your dwarves, you can easily take the above designs and face the catapults towards each other with channels behind them.

<diagram>
######################
#_CCC............CCC_#
#_CCC............CCC_#
#_CCC............CCC_#
#########....#########
</diagram>

This is obviously only for training purposes, but the point is efficiency. As each catapult fires, it "gives" stones to the engine across from it. This is entirely self contained, as your operators will continuously recycle the same ammunition, practically playing "catch" with the stones they are training with. Stones will always be available directly behind each operator, however <s>dorfs</s> some dwarves are incredibly stupid. They will tend to pick the last MINED stone for loading (like masons and crafters), so its best to burrow them into the range. Even then, the idiots will sometimes cross the range and pick up stones from the far end.

==Special considerations==

* Both catapults and ballistas have narrow fields of fire – they will only shoot at creatures directly "in front" of them, and so cannot target anything off at an angle. They can be turned 90 degrees, but that often will not solve the problem. Unskilled operators have trouble aiming perfectly straight, and their shots will randomly veer off to either side, resulting in a field of fire roughly 19 degrees across. Highly skilled operators fire their shots perfectly straight, restricting their field of fire to a straight line facing directly north/south/east/west.
* Both catapults and ballistae aim and fire only along one z-level. While ammo from both may drop down z-levels, they do no damage to creatures there. This also means that no "head room" is necessary – ammo only flies out, never up.
* Catapults have a minimum range – at least 30 tiles.
* Catapults can and will fire over any creatures between them and their target.
* Ballistae fire over prone creatures without hitting them.
* Neither are affected by [[fortification]]s.
* [[Siege operator]]s are civilians and, as such, will run in fear if enemy units come too close to them. "Too close" varies somewhat, but may be as far as 10 tiles.
* Siege operators cannot "aim" sideways - they always try to fire perfectly straight, but if they're unskilled there's a chance that the shot will "go wild" and veer off to either side by a random amount. In the case of catapults, however, these "wild" shots will actually calculate their arc height based on whatever enemy units are present off to that side (rather than based on what would've been directly ahead).

As for the actual amount of variance, siege engines aim at a location exactly 60 tiles away and up to 10 tiles to either side (if the shot is "unskilled"), which works out to a 19 degree spread (9.5 degrees to each side). The game generates 3 random numbers from 0 to 14 and checks if any of them are less than the unit's effective Siege Operator skill level (where Dabbling is 0 and Legendary is 15, and status ailments such as Nausea/Winded/Stunned/Fever/etc. can each reduce the level by as much as 50%) to see if the sideways drift should be eliminated. This works out to the following probabilities:

Dabbling - 0%
Novice - 18.7%
Adequate - 34.9%
Competent - 48.8%
Skilled - 60.6%
Proficient - 70.4%
Talented - 78.4%
Adept - 84.8%
Expert - 89.8%
Professional - 93.6%
Accomplished - 96.3%
Great - 98.1%
Master - 99.2%
High Master - 99.76%
Grand Master - 99.97%
Legendary - 100%

===Safety Warning===

'''Ballistae can and will kill anything in their path!''' Ballista arrows may hit any units in any square that the head passes through. They are moderately dangerous weapons, and should never be used with friendlies anywhere in their cone of fire, including the space the ballista arrowhead occupies when loaded on the engine. Always designate a [[traffic|restricted traffic area]] for a lot of tiles along the firing arc and keep dwarves out of the area or, better, wall off anything in front of them with fortifications to prevent all friendly traffic, or both. Each [[ballista arrow]] will fly for up to 200 tiles, though each target pierced will reduce that range based on its [[weight]]. If the bolt passes through any part of a [[tree]], the tree will disappear, presumably reduced to toothpicks.{{cite rev|210835}}

Surprisingly, catapults are relatively safe. Catapult operators will target enemies (and wild [[animals]]) if there are any in their field of fire. If not, they will loose the shot in a high arc (not requiring additional [[z-level]]s, though) that misses everything until it lands. It is perfectly safe to operate a catapult in the cave: just point it at a nearby wall of solid rock. A nice side effect is that this will, in due time, clear the whole area of stone.

Using catapults to shoot into the open may provide some [[meat]]: as said above, the operators will target animals if there are any. However, [[elephant]]s don't take nicely if you slay some of them. You also have a slight risk of killing your own dwarves or [[caravan]] escorts if they happen to be hunting the selfsame animal (and hence are close to it).

'''"Fire at Will" does ''not'' mean there has to be anything to shoot at!''' The siege engine will simply continue to be loaded and fired, simply launching ammo (stone or arrows) downrange with no (visible) target if given this command. This can be good against unseen [[ambush]]es, or if you wish to move [[stone]] across a map, but not if you are worried about depleting an ammo stockpile.

==Using Siege Engines (advanced)==
===Placement===
Siege engines can almost only shoot at targets right in front of them on the same Z-level. The target may deviate only slightly, as the field of fire is about 10-20 degrees wide. Because of the huge blind spots, it is advisable to [[Security_design#Siege_Engines|prepare the position]] so that the enemy will be channeled through the field of fire.

Siege operators are civilians! They may cease firing and run if the enemy comes too close, which is around 20 tiles. You should therefore place the engines behind a [[moat]] or a wall of [[fortification]]s that will keep the enemy at a safe distance, or shield access to their location in some other fashion.

Siege engines can shoot through [[fortification]]s, just like any other projectile weapon. As fortifications appear to provide some protection against incoming [[bolt]]s and [[arrow]]s, it's usually a good idea to protect the siege engine in that way. The siege engine can shoot through any tile thickness of fortification. Fortifications further on in the path of the shot will not hinder it either.

===Skill and Quality===
The damage inflicted by a siege engine is based entirely on the material and quality of the ammunition used - the quality of the parts from which the siege engine is built has no effect whatsoever.

If you desire high-quality siege engine parts (e.g. to increase your fortress's architectural value), the only way to obtain them is to have them made by a trained engineer, and the only way to train an engineer is to make parts or ammunition. Assembling and disassembling siege engines does not train the [[siege engineer]] skill. Dwarves will occasionally produce masterpieces long before reaching [[Legendary]] skill level, but be prepared to waste hundreds of logs until you have three masterpiece parts. Bringing an engineer to [[Experience|Proficient]] level (the highest you could buy when starting a new fortress) will take about 120 logs. Becoming Legendary requires 600 logs.

The operator skill affects reload time and accuracy. It will take a whole month for an unskilled dwarf to load a catapult; a Legendary operator with nearby ammo will get several shots at a running enemy.

Operators are best trained by firing into a nearby pit (to conserve ammo and ensure that it remains near the engine). It is recommended to have multiple skilled operators for each engine, since, as civilians, they cannot be compelled into action if they've decided to take a rest. Dwarves that have increased their strength statistic load engines much more rapidly than others, making them good candidates for operator duty (experienced operators can be [[cross-training|cross-trained]] for strength). You should start training early: it can take one year for an operator to become Proficient, and two more years until he finally reaches Legendary level; by then he will have spent 300 rounds.

Loading ballista arrows seems to be much faster than loading catapults, probably due to the much lighter weight of the projectile.

An alternative approach is [[cross-training]] any highly skilled dwarves who aren't doing anything useful at the moment. With a couple levels each in strength and agility, a free siege engine, and an ample supply of ammunition nearby, a dwarf can become a Legendary siege operator within a few seasons at most, giving more flexibility in defense and several more levels for the fortunate dwarf. Rotating legendary [[miner]]s out to siege-operation and then to stone-hauling duties sets up an efficient cycle.

===In Battle===

Catapults are generally less effective in battle situations than ballistae. The launched rocks will often glance off mail armor, making them poorly suited for killing even [[goblin]]s; they are also very inaccurate. Their ammo is easily replenished, making them ideal for target practice and very cheap to make and use.

Ballista arrows tipped with softer materials (such as wood) can glance off ordinary clothes, making the choice of arrowhead significant. However, the arrows may hit multiple targets in a single launch. This makes ballistae many times more efficient than catapults, which fire in an arc that hits only a few tiles per shot and is nearly useless against anything larger than smaller, poorly-armored foes. Ballista arrows fired through too many successive targets will be lost or destroyed; the limit seems to be roughly 5-6 goblin-sized targets hit before the arrow is lost. Adding a channel to the end of the arrow's trajectory will allow expensive bolts to be recovered after the attackers are dealt with.

A siege engine you want to use for actual defense shouldn't be set to fire at will, as this likely means that it's not loaded and ready at the time you actually need it. You should train your operators on other pieces. You might train your operators on a set of catapults and defend your fortress with a set of ballistae.

When the time comes, switch off all training engines and set all of the ones you'll be using to prepare to fire so the operators will be on-station; if some of them are currently not loaded, designate them to be disassembled so to prevent your operators from loading the training weapons instead of firing the real ones. Alternatively, use [[Scheduling#Alert_Levels|civilian alert levels]] with burrow restrictions, and just make sure the training catapults are not within any allowed burrow.

Remember, operators are civilians. They do not care that the fortress is at stake: hunger, thirst, sleep and breaks will always come first. It's wise to train more operators than you have engines, and disable all other work for them in times of need. The most effective way to ensure that your operators won't run off is to lock them in with the siege engine during the moment of truth.

===Ballista battery===

If you place ballistae close enough together, you can completely cover a two or three tile wide corridor. Because siege engines are 3x3, they need to be staggered, so each one fires through the edge of the one ahead of it. This can be dangerous for your operators. To minimize risk, place [[fortification]]s to keep dwarves from wandering too far, and have only one entrance to the ballista room. There is still some risk that dwarves might wander into the line of fire, even with no reason to do so.

: '''Three tile-wide corridor''' (battery room 5 tiles wide)

<diagram>
╔═══
══════════════════════════╦══╦══╝▐▀\
Entrance++++++++++++▼ ╬ ╬▐▀\◄═« (~ammo~)
Entrance++++++++++++▼ ╬▐▀\◄═«▐▄/
Entrance++++++++++++▼ ╬◄═«▐▄/ (~ammo~)
══════════════════════════╣▐▄/ (~ammo~)
╚═════════
</diagram>

:*<tt>＋</tt> - floor
:*<tt>═</tt> - wall
:*<tt>▼</tt> - ramp (down)
:*<tt>·</tt> - channel (aka "empty space" on this level)
:*<tt>╬</tt> - fortification

Due to the rare wild shot, the staggering should always be from one side to the other, and not put one ballista far ahead of the one it overlaps, as this may increase friendly-fire accidents.

Ammo storage can be on the same level, or via [[stairs]] or [[ramp]]s on another [[z-level]]. Expand the room as desired for more storage. Also note that ballista arrows are stored in [[Stockpile#Furniture_Storage|furniture stockpiles]], not ammo stockpiles.

An alternate strategy could be to place a [[floodgate]] or retracting [[bridge]] in the center of the 3x3 hallway, and activate it during times of crisis so that the Goblins are forced to fight in two separate 1x1 corridors rather than a single 3x3 corridor. If the corridors are further lined with spike traps and weapon traps, this combined defense can assure your dwarves that any attempts to assault your base will be very, very bloody.

A drawbridge can be combined with the channeled area to provide a practice area, as discussed above. The channels would be accessible from the battery area via a staircase, keeping the dwarves below/behind the lines of fire at all times.

==Catapults as stone movers==
When a catapult throws a stone, that stone is destroyed upon landing, unless it falls a z-level, where it lands harmlessly. That means that if you can arrange it so ammo hits a wall (or door, or raised bridge), and there is empty space immediately under that, the stone arrives at that point. If the ammo reaches its maximum range, again, it falls harmlessly. Even with a single, no-quality catapult and an untrained crew, this is massively faster than hauling stone by hand. Ammo that hits [[stairs]] is destroyed, even if it can fall a z-level. Stones falling one z-level onto a floor with empty space under it will also be destroyed, make sure there is a wall under the tile where the ammo ultimately lands on.

The same idea can be used to clean up your fortress: If the landing zone cannot be accessed (else the stones will soon be taken from ''that'' pile), a single catapult crew will, over time, collect every stone in your fortress and deposit it near your [[mason]]ry, removing clutter even from the caverns.

==Gatling Catapults==
This involves a catapult, a garbage dump [[activity zone]], and a legendary siege operator. Set up your catapult where you'd like it to be used, then place a garbage dump zone in the middle of the catapult and dump a sufficient number of stones there. Reclaim the ammo using {{k|d}}-{{k|b}}-{{k|c}} (making sure that you don't have any stone [[stockpile]]s that permit the stone you used) and you're good to go. With a sufficiently strong/agile siege operator (and a lack of distractions), you can easily manage 2-3 stones flying at once per catapult.

==Bugs==
* Siege projectiles are surprisingly non-lethal{{bug|818}}
* Liaisons/children do not avoid standing in front of a firing ballista{{bug|4486}}

----

'''See Also:'''
:*[[Defense design]]
:*[[cross-training#Artillery proving ground (siege operator)|Army corps of engineers]]
{{buildings}}

{{Category|Buildings}}
{{Category|Fortress defense}}

v0.34:Siege engine

2026-03-30T04:03:23Z

Quietust:

{{quality|Superior}}{{Building|name=Catapult|key=i|key2=c
|job=[[Siege operating]]
|construction=
3 catapult parts
|construction_job=
* [[Siege engineering]]
|purpose=
Stationary weapons platform
}}{{Building|name=Ballista|key=i|key2=b
|job=[[Siege operating]]
|construction=
3 ballista parts
|construction_job=
* [[Siege engineering]]
|purpose=
Stationary weapons platform
}}{{av}}
A '''siege engine''' in Dwarf Fortress is half building and half heavy weapon, and includes both the '''catapult''' and the '''ballista'''. Both are capable of launching hazardous projectiles at a tremendous range ''(more than a screen-width, around 80 to 100 tiles for a catapult and between 130 and 200 tiles for a ballista).'' A [[ballista arrow]] can kill or injure each creature in its path indiscriminate of friend or foe, but a stone launched from a catapult cannot harm [[dwarf|dwarves]] or [[animal trainer|tamed animals]].

Unlike what the name may imply, siege engines are only deployed defensively, and no [[siege]] will use them against you (although the use of siege engines against your fort is [http://bay12games.com/dwarves/dev.html planned for future versions]).

Siege engines can be made to face in any of the four cardinal directions, but they cannot be moved after placement. They can, however, be rotated, or deconstructed back into their 3 parts (with {{k|q}}-{{k|x}}), to be moved elsewhere. Both the construction of siege equipment and the engine itself require a dwarf with the "[[Siege engineering]]" [[labor]] designated, which uses the "[[Siege engineer]]" [[skill]].

The player determines when (or if) each engine is actively firing or not; when active, a single engine is crewed by a single [[siege operator]].

Ballistae require specially made [[ammo]] — [[ballista arrow]]s, made from [[wood]]en [[log]]s at the [[siege workshop]] (and optionally tipped with [[metal]] [[ballista arrowhead]]s that have been made at a [[forge]] by a [[weaponsmith]]). Catapults use simple [[stone]] as ammunition. Catapults respect [[economic stone]] restrictions and cannot fire [[clay]] at all.

==Building Siege Engines==
{{key|b}}-{{key|i}}

In order to build a siege engine, you first need to produce (at least) three catapult or ballista parts in the [[siege workshop]]; catapults are made from any 3 '''catapult parts''', and ballistae are made from any 3 '''ballista parts'''. All parts are made from any type of wood at the siege workshop. Beyond that, "parts" are generic - there are no particular "sub-types" of parts beyond the distinction between those for the two different engine types. The quality of the parts has no effect on the siege engine's operation, so there is no need to produce high quality parts except to augment your fortress's architecture value.

Once you have the parts, you may then build the respective siege engine like any other building, selecting the parts that you wish to construct that particular engine with. The assembled siege engine is, effectively, a 3x3 building. It cannot be moved about other than by taking it down and re-assembling it at the new site. Siege engines do not impede movement, though, so you don't have to worry about building them in a corridor.

==Using Siege Engines (simple)==
{{key|o}} will let you change the orientation, whether the siege engine is pointing north / south / east / west. This takes effect immediately, it does not require a dwarf to come and turn the engine.

{{key|f}} toggles the current status between:
*Not In Use: Dwarves with the [[Siege operator]] [[job]] will reload unloaded engines and leave them unattended.
*Prepare to Fire: Siege Operators will load the engine and remain stationed for further commands.
*Fire at Will: Siege Operators will fire and load normally.

Once an engine is given orders to fire (or prepare to), a dwarf with the [[Siege operator|siege operating]] labor designated will respond and report to the engine. The dwarf(s) will (re-)load any siege engine that is not currently loaded; there's no way to prevent this short of disabling the labor on all dwarves or forbidding every piece of ammo (or otherwise blocking a [[path]] to it, perhaps by locking [[door]]s or using a [[burrow]].)

[[Ammo]] is destroyed upon landing, unless it falls a z-level, and then it falls harmlessly. (See [[#Catapults as stone movers|below]].)

########
CCC..._#
CCC..._#
CCC..._#
########

The [[channel]] at the end of this firing range preserves the stone. For catapults there is usually so much spare stone that this is not necessary, but it could be used for fast stone transport, or simply to set up a self-contained training area. A similar effect can sometimes be observed when firing a catapult over bumpy ground outside.

The design can be further improved by using a [[drawbridge]] rather than a wall, this way when the drawbridge is raised it acts like a wall deflecting the stone into the channel below. In the case of an attack on your [[fortress]] the drawbridge can be lowered allowing the catapult to fire.

#####################
CCC..._¦.............
CCC..._¦.............
CCC..._¦.............
#####################
Drawbridge raised deflecting stones into channel.

#####################
CCC...[].............
CCC...[].............
CCC...[].............
#####################
Drawbridge lowered allowing catapult to shoot down the corridor.

==Special considerations==

* Both catapults and ballistae have narrow fields of fire - they will only shoot at creatures directly "in front" of them, and so cannot target anything off at an angle. They can be turned 90 degrees, but that often will not solve the problem. Unskilled operators have trouble aiming perfectly straight, and their shots will randomly veer off to either side, resulting in a field of fire roughly 19 degrees across. Highly skilled operators are supposed to fire perfectly straight; due to a bug, however, this does not happen.
* Both catapults and ballistae aim and fire only along one z-level. While ammo from both may drop down z-levels, they do no damage to creatures there. This also means that no "head room" is necessary - ammo just flies out, never up.
* Catapults have a minimum range - at least 30 tiles.
* Catapults can and will fire over any creatures between them and their target.
* Neither are affected by [[fortification]]s.
* [[Siege operator]]s are "civilians", and as such they will run in fear if enemy units come too close to them. "Too close" varies somewhat, but may be as far as 10 tiles.

===Safety Warning===

'''Ballistae can and will kill anything in their path!''' Ballista arrows appear to hit any units in any square that the head passes through. They are devastatingly dangerous weapons, and should never be used with friendlies anywhere in their cone of fire, including the space the ballista arrowhead occupies when loaded on the engine. Always designate a [[traffic|restricted traffic area]] for a lot of tiles along the firing arc and keep dwarves out of the area or, better, wall off anything in front of them with fortifications to prevent all friendly traffic, or both. Each [[ballista arrow]] will fly for up to 200 tiles, though each target pierced will reduce that range based on its [[weight]]. If the bolt passes through a [[tree]], the tree will disappear, presumably reduced to toothpicks.

Surprisingly, catapults are relatively safe. Catapult operators will target enemies (and wild [[animals]]) if there are any in their field of fire. If not, they will loose the shot in a high arc (not requiring additional [[z-level]]s, though) that misses everything until it lands. It is perfectly safe to operate a catapult in the cave: just point it at a nearby wall of solid rock. A nice side effect is that this will, in due time, clear the whole area of stone.

Using catapults to shoot into the open may provide some [[meat]]: as said above, the operators will target animals if there are any. However, [[elephant]]s don't take nicely if you slay some of them. You also have a slight risk of killing your own dwarves or [[caravan]] escorts if they happen to be hunting the selfsame animal (and hence are close to it).

'''"Fire at Will" does ''not'' mean there has to be anything to shoot at!''' The siege engine will simply continue to be loaded and fired, simply launching ammo (stone or arrows) downrange with no (visible) target if given this command. This can be good against unseen [[ambush]]es, or if you wish to move [[stone]] across a map, but not if you are worried about depleting an ammo stockpile.

==Using Siege Engines (advanced)==
===Placement===
Siege engines can almost only shoot at targets right in front of them on the same Z-level. The target may deviate only slightly, as the field of fire is about 20-30 degrees wide. Because of the huge blind spots, it is advisable to [[Security_design#Siege_Engines|prepare the position]] so that the enemy will be channeled through the field of fire.

Siege operators are civilians! They will drop their work and run if the enemy comes too close, which is around 20 tiles. You should therefore place the engines behind a [[moat]] or a wall of [[fortification]]s that will keep the enemy at a safe distance, or shield access to their location in some other fashion.

Siege engines can shoot through [[fortification]]s, just like any other projectile weapon. As fortifications appear to provide some protection against incoming [[bolt]]s and [[arrow]]s, it's usually a good idea to protect the siege engine in that way. The siege engine only needs a one tile wide fortification to shoot out.

===Skill and Quality===
The damage inflicted by a siege engine is based entirely on the material and quality of the ammunition used - the quality of the parts from which the siege engine is built has no effect whatsoever.

If you desire high-quality siege engine parts (e.g. to increase your fortress's architectural value), the only way to obtain them is to have them made by a trained engineer, and the only way to train an engineer is to make parts or ammunition. Assembling and disassembling siege engines does not train the [[siege engineer]] skill. Dwarves will occasionally produce masterpieces long before reaching [[Legendary]] skill level, but be prepared to waste hundreds of logs until you have three masterpiece parts. Bringing an engineer to [[Experience|Proficient]] level (the highest you could buy when starting a new fortress) will take about 120 logs. Becoming Legendary requires the wood of 600 trees.

The operator skill certainly affects reload time. It will take a whole month for an unskilled dwarf to load a catapult; a Legendary operator with nearby ammo will get several shots at a running enemy. Operator skill is intended to improve accuracy as well, but does not.{{bug|6483}}

Operators are best trained on catapults, as these require nothing but cheap stone for ammo. It is recommended to have a number of dedicated operators that will follow no other line of work, and enough catapults for all of them to play with. As they're often going for a drink or sleep, you may get along with three catapults for four operators, and even two pieces would go a long way. Since the dwarf must hold the heavy stone in his inventory during the entire loading procedure, dwarves that have increased their strength statistic load catapults much more rapidly than others, making them good candidates for operator duty. You should start training early: it can take one year for an operator to become Proficient, and two more years until he finally reaches Legendary level; by then he will have spent 300 rounds.

Loading ballista arrows seems to be much faster than loading catapults, probably due to the much lighter weight of the projectile.

An alternative approach is cross-training any highly skilled dwarves who aren't doing anything useful at the moment. With a couple levels each in strength and agility, a decent-quality catapult, and an ample supply of ammunition nearby, a dwarf can become a Legendary siege operator within a few seasons at most, giving more flexibility in defense and several more levels for the fortunate dwarf. [[Cross-training|Rotating]] Legendary [[miner]]s out to siege-operation and then to stone-hauling duties sets up an efficient cycle.

===In Battle===

Catapults are generally less effective in battle situations than are ballistae. The launched rocks will often glance off mail armor, making them poorly suited for killing even [[goblin]]s; they are also very inaccurate. Their ammo is easily replenished, making them ideal for target practice and very cheap to make and use.

Ballista arrows tipped with softer materials (such as wood) can glance off ordinary clothes, making the choice of arrowhead significant. However, the arrows penetrate through any unit they strike, allowing them to hit many multiple targets in a single launch. This makes ballistae many times more efficient than catapults, which fire in an arc that hits only a few tiles per shot and is nearly useless against anything larger than smaller, poorly-armored foes. Ballista arrows fired through too many successive targets will be lost or destroyed; the limit seems to be roughly 5-6 goblin-sized targets hit before the arrow is lost. Adding a channel to the end of the arrow's trajectory will allow expensive bolts to be recovered after the attackers are dealt with.

A siege engine you want to use for actual defense shouldn't be set to fire at will, as this likely means that it's not loaded and ready at the time you actually need it. You should train your operators on other pieces. You might train your operators on a set of catapults and defend your fortress with a set of ballistae.

When the time comes, switch off all training engines and set all of the ones you'll be using to prepare to fire so the operators will be on-station; if some of them are currently not loaded, designate them to be disassembled so to prevent your operators from loading the training weapons instead of firing the real ones. Alternatively, use [[Scheduling#Alert_Levels|civilian alert levels]] with burrow restrictions, and just make sure the training catapults are not within any allowed burrow.

Remember, operators are civilians. They do not care that the fortress is at stake: hunger, thirst, sleep and breaks will always come first. It's wise to train more operators than you have engines, and disable all other work for them in times of need. The most effective way to ensure that your operators won't run off is to lock them in with the siege engine during the moment of truth.

===Ballista battery===

If you place ballistae close enough together, you can completely cover a two or three tile wide corridor. Because siege engines are 3x3, they need to be staggered, so each one fires through the edge of the one ahead of it. This can be dangerous for your operators. To minimize risk, place [[fortification]]s to keep dwarves from wandering too far, and have only one entrance to the ballista room. There is still some risk that dwarves might wander into the line of fire, even with no reason to do so.

: '''Three tile-wide corridor''' (battery room 5 tiles wide)

╔═══
══════════════════════════╦══╦══╝▐▀\
Entrance++++++++++++▼·····╬++╬▐▀\◄═« (~ammo~)
Entrance++++++++++++▼·····╬▐▀\◄═«▐▄/
Entrance++++++++++++▼·····╬◄═«▐▄/+(~ammo~)
══════════════════════════╣▐▄/+(~ammo~)
╚═════════
:*<tt>+</tt> - floor
:*<tt>═</tt> - wall
:*<tt>▼</tt> - ramp (down)
:*<tt>·</tt> - channel (aka "empty space" on this level)
:*<tt>╬</tt> - fortification

Due to the rare wild shot, the staggering should always be from one side to the other, and not put one ballista far ahead of the one it overlaps, as this may increase friendly-fire accidents.

Ammo storage can be on the same level, or via [[stair]]s or [[ramp]]s on another [[z-level]]. Expand the room as desired for more storage. Also note that ballista arrows are stored in [[Stockpile#Furniture_Storage|furniture stockpiles]], not ammo stockpiles.

An alternate strategy could be to place a [[floodgate]] or retracting [[bridge]] in the center of the 3x3 hallway, and activate it during times of crisis so that the Goblins are forced to fight in two separate 1x1 corridors rather than a single 3x3 corridor. If the corridors are further lined with spike traps and weapon traps, this combined defense can assure your dwarves that any attempts to assault your base will be very, very bloody.

A drawbridge can be combined with the channeled area to provide a practice area, as discussed above. The channels would be accessible from the battery area via a staircase, keeping the dwarves below/behind the lines of fire at all times.

==Catapults as stone movers==
When a catapult throws a stone, that stone is destroyed upon landing, unless it falls a z-level, where it lands harmlessly. That means that if you can arrange it so ammo hits a wall (or door, or raised bridge), and there is empty space immediately under that, the stones arrives at that point. If ammo reaches its maximum range, again, it falls harmlessly. Even with a single, no-quality catapult and an untrained crew, this is massively faster than hauling stone by hand. Ammo that hits [[stair]]s is destroyed, even if it can fall a z-level.

==Gatling Catapults==
This involves a catapult, a garbage dump [[activity zone]], and a legendary siege operator. Setup your catapult, as you wish to use, then place a garbage dump zone in the middle of the catapult and dump a sufficient number of stones there. Reclaim the ammo using {{k|d}}-{{k|b}}-{{k|c}} (making sure that you don't have any stone [[stockpile]]s that permit the stone you used) and you're good to go. With a sufficiently strong/agile siege operator (and a lack of distractions), you can easily manage 2-3 stones flying at once per catapult.

----

'''See Also:'''
:*[[Defense design]]
:*[[cross-training#Army corps of engineers|Army corps of engineers]]
{{buildings}}

{{Category|Buildings}}
{{Category|Fortress defense}}

v0.31:Siege engine

2026-03-30T04:03:14Z

Quietust:

{{quality|Masterwork}}{{Building|name=Catapult|key=i|key2=c
|job=[[Siege operating]]
|construction=
3 catapult parts
|construction_job=
* [[Siege engineering]]
|purpose=
Stationary weapons platform
}}{{Building|name=Ballista|key=i|key2=b
|job=[[Siege operating]]
|construction=
3 ballista parts
|construction_job=
* [[Siege engineering]]
|purpose=
Stationary weapons platform
}}{{av}}
A '''siege engine''' in Dwarf Fortress is half building/half heavy weapon, and includes both the '''catapult''' and the '''ballista'''. Both are capable of launching hazardous projectiles at a tremendous range ''(more than a screen-width, around 80 to 100 tiles for a catapult and between 130 and 200 tiles for a ballista).'' A [[ballista arrow]] can kill or injure each creature in its path indiscriminate of friend or foe, but a stone launched from a catapult cannot harm dwarves or tamed animals.

Siege engines can be made to face any cardinal direction, but they cannot be moved after placement. They can, however, be deconstructed back into their 3 parts, to be moved elsewhere (individually or together). Both the construction of siege equipment and the engine itself require a dwarf with the "Siege Engineering" [[labor]] designated, which uses the "[[Siege_engineer|Siege Engineer]]" [[skill]].

The player determines when/if each engine is actively firing or not; when active, a single engine is crewed by a single [[siege operator]]. Ballistae require specially made [[ammo]], [[ballista arrow]]s, made from wooden [[log]]s at the siege workshop (and optionally tipped with [[metal]] [[ballista arrowhead]]s that have been made at a [[forge]] by a [[weaponsmith]]). Catapults use simple [[stone]] as ammunition.

==Building Siege Engines==
{{key|b}}-{{key|i}}

In order to build a siege engine, you first need to produce (at least) three catapult or ballista parts in the [[siege workshop]]; catapults are made from any 3 '''catapult parts''', and ballistae are made from any 3 '''ballista parts'''. All parts are made from any type of wood at the siege workshop. Beyond that, "parts" are generic - there are no particular "sub-types" of parts beyond the distinction between those for the two different engine types. The quality of the parts has no effect on the siege engine's operation, so there is no need to produce high quality parts except to augment your fortress's architecture value.

Once you have the parts, you may then build the respective siege engine like any other building, selecting the parts that you wish to construct that particular engine with.

The assembled siege engine is, effectively, a 3x3 building. It cannot be moved about other than by taking it down and re-assembling it at the new site. Siege engines do not impede movement, though, so you don't have to worry about building them in a corridor.

==Using Siege Engines (simple)==
{{key|o}} will let you change the orientation, whether the siege engine is pointing north / south / east / west. This takes effect immediately, it does not require a dwarf to come and turn the engine.

{{key|f}} toggles the current status between:
*Not In Use: Dwarves with the [[Siege operator]] [[job]] will reload unloaded engines and leave them unattended.
*Prepare to Fire: Siege Operators will load the engine and remain stationed for further commands.
*Fire at Will: Siege Operators will fire and load normally.

Once an engine is given orders to fire (or prepare to), a dwarf with the [[Siege operator|siege operating]] labor designated will respond and report to the engine. The dwarf(s) will (re-)load any siege engine that is not currently loaded; there's no way to prevent this short of disabling the labor on all dwarves or forbidding every piece of ammo (or otherwise blocking a [[path]] to it, perhaps by locking [[door]]s or using a [[burrow]].)

[[Ammo]] is destroyed upon landing, unless it falls a z-level, and then it falls harmlessly. (See [[#Catapults as stone movers|below]].)

########
CCC..._#
CCC..._#
CCC..._#
########

The [[channel]] at the end of this firing range preserves the stone. For catapults there is usually so much spare stone that this is not necessary, but it could be used for fast stone transport, or simply to set up a self-contained training area. A similar effect can sometimes be observed when firing a catapult over bumpy ground outside.

The design can be further improved by using a [[drawbridge]] rather than a wall, this way when the drawbridge is raised it acts like a wall deflecting the stone into the channel below. In the case of an attack on your [[fortress]] the drawbridge can be lowered allowing the catapult to fire.

#####################
CCC..._¦.............
CCC..._¦.............
CCC..._¦.............
#####################

Drawbridge raised deflecting stones into channel.

#####################
CCC...[].............
CCC...[].............
CCC...[].............
#####################

Drawbridge lowered allowing catapult to shoot down the corridor.

==Special considerations==

* Both catapults and ballistae have narrow fields of fire - they will only shoot at creatures directly "in front" of them, and so cannot target anything off at an angle. They can be turned 90 degrees, but that often will not solve the problem. Unskilled operators have trouble aiming perfectly straight, and their shots will randomly veer off to either side, resulting in a field of fire roughly 19 degrees across. Highly skilled operators are supposed to fire perfectly straight; due to a bug, however, this does not happen.
* Both catapults and ballistae aim and fire only along one z-level. While ammo from both may drop down z-levels, they do no damage to creatures there. This also means that no "head room" is necessary - ammo just flies out, never up.
* Catapults have a minimum range - at least 30 tiles.
* Catapults can and will fire over any creatures between them and their target.
* Neither are affected by [[fortification]]s.
* [[Siege operator]]s are "civilians", and as such they will run in fear if enemy units come too close to them. "Too close" varies somewhat, but may be as far as 10 tiles.

===Safety Warning===

'''Ballistae can and will kill anything in their path!''' Ballista arrows appear to hit any units in any square that the head passes through. They are devastatingly dangerous weapons, and should never be used with friendlies anywhere in their cone of fire, including the space the ballista arrowhead occupies when loaded on the engine. Always designate a [[traffic|restricted traffic area]] for a lot of tiles along the firing arc and keep dwarves out of the area or, better, wall off anything in front of them with fortifications to prevent all friendly traffic, or both. Each [[ballista arrow]] will fly for up to 200 tiles, though each target pierced will reduce that range based on its [[weight]]. If the bolt passes through a [[tree]], the tree will disappear, presumably reduced to toothpicks.

Surprisingly, catapults are relatively safe. Catapult operators will target enemies (and wild [[animals]]) if there are any in their field of fire. If not, they will loose the shot in a high arc (not requiring additional [[z-level]]s, though) that misses everything until it lands. It is perfectly safe to operate a catapult in the cave: just point it at a nearby wall of solid rock. A nice side effect is that this will, in due time, clear the whole area of stone.

Using catapults to shoot into the open may provide some [[meat]]: as said above, the operators will target animals if there are any. However, [[elephant]]s don't take nicely if you slay some of them. You also have a slight risk of killing your own dwarves or [[caravan]] escorts if they happen to be hunting the selfsame animal (and hence are close to it).

'''"Fire at Will" does ''not'' mean there has to be anything to shoot at!''' The siege engine will simply continue to be loaded and fired, simply launching ammo (stone or arrows) downrange with no (visible) target if given this command. This can be good against unseen [[ambush]]es, or if you wish to move [[stone]] across a map, but not if you are worried about depleting an ammo stockpile.

==Using Siege Engines (advanced)==
===Placement===
Siege engines can almost only shoot at targets right in front of them on the same Z-level. The target may deviate only slightly, as the field of fire is about 20-30 degrees wide. Because of the huge blind spots, it is advisable to [[Security_design#Siege_Engines|prepare the position]] so that the enemy will be channeled through the field of fire.

Siege operators are civilians! They will drop their work and run if the enemy comes too close, which is around 20 tiles. You should therefore place the engines behind a [[moat]] or a wall of [[fortification]]s that will keep the enemy at a safe distance, or shield access to their location in some other fashion.

Siege engines can shoot through [[fortification]]s, just like any other projectile weapon. As fortifications appear to provide some protection against incoming [[bolt]]s and [[arrow]]s, it's usually a good idea to protect the siege engine in that way. The siege engine only needs a one tile wide fortification to shoot out.

===Skill and Quality===
The damage inflicted by a siege engine is based entirely on the material and quality of the ammunition used - the quality of the parts from which the siege engine is built has no effect whatsoever.

If you desire high-quality siege engine parts (e.g. to increase your fortress's architectural value), the only way to obtain them is to have them made by a trained engineer, and the only way to train an engineer is to make parts or ammunition. Assembling and disassembling siege engines does not train the [[siege engineer]] skill. Dwarves will occasionally produce masterpieces long before reaching [[Legendary]] skill level, but be prepared to waste hundreds of logs until you have three masterpiece parts. Bringing an engineer to [[Experience|Proficient]] level (the highest you could buy when starting a new fortress) will take about 120 logs. Becoming Legendary requires the wood of 600 trees.

The operator skill certainly affects reload time. It will take a whole month for an unskilled dwarf to load a catapult; a Legendary operator with nearby ammo will get several shots at a running enemy. Due to a bug, operator skill has no effect on accuracy.

Operators are best trained on catapults, as these require nothing but cheap stone for ammo. It is recommended to have a number of dedicated operators that will follow no other line of work, and enough catapults for all of them to play with. As they're often going for a drink or sleep, you may get along with three catapults for four operators, and even two pieces would go a long way. Since the dwarf must hold the heavy stone in his inventory during the entire loading procedure, dwarves that have increased their strength statistic load catapults much more rapidly than others, making them good candidates for operator duty. You should start training early: it can take one year for an operator to become Proficient, and two more years until he finally reaches Legendary level; by then he will have spent 300 rounds.

Loading ballista arrows seems to be much faster than loading catapults, probably due to the much lighter weight of the projectile.

An alternative approach is cross-training any highly-skilled dwarves who aren't doing anything useful at the moment. With a couple levels each in strength and agility, a decent-quality catapult, and an ample supply of ammunition nearby, a dwarf can become a Legendary siege operator within a few seasons at most, giving more flexibility in defense and several more levels for the fortunate dwarf. [[Cross-training|Rotating]] Legendary [[miner]]s out to siege-operation and then to stone-hauling duties sets up an efficient cycle.

===In Battle===

Catapults are generally less effective in battle situations than are ballistae (as of version 0.31.08). The launched rocks will often glance off mail armor, making them poorly suited for killing even [[goblin]]s. ''It is still faster to fire stones than carry them, at least.'' Catapults are very inaccurate, but they are less likely to harm friendly creatures, and their ammo is easily replenished, making them ideal for target practice.

Ballista arrows tipped with softer materials (such as wood) can glance off ordinary clothes, making the choice of arrowhead significant. However, the arrows penetrate through any unit they strike, allowing them to hit many multiple targets in a single launch. This makes ballistae many times more efficient than catapults, which fire in an arc that hits only a few tiles per shot and is nearly useless against anything larger than smaller, poorly-armored foes. Ballista arrows fired through too many successive targets will be lost or destroyed; the limit seems to be roughly 5-6 goblin-sized targets hit before the arrow is lost.

A siege engine you want to use for actual defense should be not set to fire at will, as this likely means that it's not loaded and ready at the time you actually need it. You should train your operators on other pieces.

When the time comes, switch off all training engines and set all of the ones you'll be using to prepare to fire so the operators will be on-station; if some of them are currently not loaded, designate them to be disassembled so to prevent your operators from loading the training weapons instead of firing the real ones.

Remember, operators are civilians. They do not care that the fortress is at stake: hunger, thirst, sleep and breaks will always come first. It's wise to train more operators than you have engines, and disable all other work for them in times of need. The most effective way to ensure that your operators won't run off is to lock them in with the siege engine during the moment of truth.

===Ballista battery===

If you place ballistae close enough together, you can completely cover a two or three tile wide corridor. Because siege engines are 3x3, they need to be staggered, so each one fires through the edge of the one ahead of it. This can be dangerous for your operators. To minimize risk, place [[fortification]]s to keep dwarves from wandering too far, and have only one entrance to the ballista room. There is still some risk that dwarves might wander into the line of fire, even with no reason to do so.

: '''Three tile-wide corridor''' (battery room 5 tiles wide)

╔═══
══════════════════════════╦══╦══╝▐▀\
Entrance++++++++++++▼·····╬++╬▐▀\◄═« (~ammo~)
Entrance++++++++++++▼·····╬▐▀\◄═«▐▄/
Entrance++++++++++++▼·····╬◄═«▐▄/+(~ammo~)
══════════════════════════╣▐▄/+(~ammo~)
╚═════════
:*<tt>+</tt> - floor
:*<tt>═</tt> - wall
:*<tt>▼</tt> - ramp (down)
:*<tt>·</tt> - channel (aka "empty space" on this level)
:*<tt>╬</tt> - fortification

Due to the rare wild shot, the staggering should always be from one side to the other, and not put one ballista far ahead of the one it overlaps, as this may increase friendly-fire accidents.

Ammo storage can be on the same level, or via [[stair]]s or [[ramp]]s on another [[z-level]]. Expand the room as desired for more storage. Also note that ballista arrows are stored in [[Stockpile#Furniture_Storage|furniture stockpiles]], not ammo stockpiles.

An alternate strategy could be to place a [[floodgate]] or retracting [[bridge]] in the center of the 3x3 hallway, and activate it during times of crisis so that the Goblins are forced to fight in two separate 1x1 corridors rather than a single 3x3 corridor. If the corridors are further lined with spike traps and weapon traps, this combined defense can assure your dwarves that any attempts to assault your base will be very, very bloody.

A drawbridge can be combined with the channeled area to provide a practice area, as discussed above. The channels would be accessible from the battery area via a staircase, keeping the dwarves below/behind the lines of fire at all times.

==Catapults as stone movers==
When a catapult throws a stone, that stone is destroyed upon landing, unless it falls a z-level, where it lands harmlessly. That means that if you can arrange it so ammo hits a wall (or door, or raised bridge), and there is empty space immediately under that, the stones arrives at that point. If ammo reaches its maximum range, again, it falls harmlessly. Even with a single, no-quality catapult and an untrained crew, this is massively faster than hauling stone by hand. Ammo that hits [[stair]]s is destroyed, even if it can fall a z-level.

==Gatling Catapults==
This involves a catapult, a garbage dump [[activity zone]], and a legendary siege operator. Setup your catapult, as you wish to use, then place a garbage dump zone in the middle of the catapult and dump a sufficient number of stones there. Reclaim the ammo using {{k|d}}-{{k|b}}-{{k|c}} (making sure that you don't have any stone [[stockpile]]s that permit the stone you used) and you're good to go. With a sufficiently strong/agile siege operator (and a lack of distractions), you can easily manage 2-3 stones flying at once per catapult.

----

'''See Also:'''
:*[[Defense design]]
:*[[cross-training#Army corps of engineers|Army corps of engineers]]
{{buildings}}

{{Category|Buildings}}
{{Category|Fortress defense}}

Ballista arrow

2026-03-30T04:02:06Z

Quietust:

{{Quality|Superior}}
{{av}}

[[File:ballista_arrow_preview.png|right]]'''Ballista arrows''' are, essentially, giant [[arrow]]s, created at a [[siege workshop]] and used as ammunition by a [[ballista]]. There are two types:
* Simple wooden ballista arrows, which are "assembled" from one unit of [[wood]] at the siege workshop by a [[siege engineer]],
* And much stronger metal ones, which first requires the creation of a ballista arrowhead at a [[metalsmith's forge]] from three units of [[metal]] bars by a [[weaponsmith]], and then final assembly with [[wood]] at the siege workshop by a [[siege engineer]].

For wooden arrows, the type of [[wood]] that is used impacts its strength, where heavier types of wood such as [[glumprong]] or [[blood thorn]] are better; for metal arrows, the type of wood used for the shaft is irrelevant because the game treats the entire arrow as being made of metal. Both ballista arrowheads and the completed ballista arrows are stored in the Siege ammo section of Furniture/Siege Ammo stockpiles.

For such a big, cumbersome, inaccurate weapon, wooden ballista arrows are surprisingly ineffective, dealing only comparatively minor amounts of blunt damage. Metal ballista arrows, on the other hand, are extremely lethal, and can kill two fully-grown [[elephant]]s standing in a line if the arrow hits squarely; any [[goblin]]s you hit will be smeared all over the space on which they stood.

Creating arrowheads is tedious and resource-consuming, and both [[catapult]]s and [[ballista]]s train the [[siege operator]] skill, at the same rate, when used. Since [[catapult]]s use [[stone]]s you can literally pick up off of the ground, they're a much better practice platform for your operator, whereas a ballista armed with ''metal'' arrows is a much stronger actual weapons platform. As such, there's never much reason to produce wooden ballista arrows.

Ballista arrows normally have a range of 200 tiles, but impacting a creature will subtract an amount from that range based on the [[weight]] of the arrow: arrows weighing 50Γ or less (i.e. [[adamantine]] and every type of [[wood]]) subtract 50 tiles per hit, arrows weighing 150Γ or more (i.e. every other vanilla weapons-grade [[metal]]) subtract just 5 tiles per hit, and everything in between would scale linearly.

{{Gamedata|{{raw|v50:item_siegeammo.txt|ITEM_SIEGEAMMO|ITEM_SIEGEAMMO_BALLISTA}}}}
{{Category|Ammo}}
[[Ru:Ballista arrow]]

DF2014:Ballista arrow

2026-03-30T04:01:58Z

Quietust:

{{Quality|Superior|01:09, 4 February 2015 (UTC)}}
{{av}}

'''Ballista arrows''' are, essentially, giant [[arrow]]s, created at a [[siege workshop]] and used as ammunition by a [[ballista]]. There are two types:
* Simple wooden ballista arrows, which are made from one unit of [[wood]] at the workshop,
* And much stronger metal ones, which first requires the creation of a ballista arrowhead at a [[metalsmith's forge]] from three units of [[metal]] bars and then final assembly with [[wood]] at the siege workshop.

The type of [[wood]] that is used for the arrow impacts its strength, where heavier types of wood such as [[glumprong]] or [[blood thorn]] are better. Both ballista arrowheads and the completed ballista arrows are stored in Furniture/Siege Ammo stockpiles.

For such a big, cumbersome, inaccurate weapon, wooden ballista arrows are surprisingly ineffective, dealing only comparatively minor amounts of blunt damage. Metal ballista arrows, on the other hand, are extremely lethal, and can kill two fully-grown [[elephant]]s standing in a line if the arrow hits squarely; any [[goblin]]s you hit will be smeared all over the space on which they stood.

Creating arrowheads is tedious and resource-consuming, and both [[catapult]]s and [[ballista]]s train the [[siege operator]] skill, at the same rate, when used. Since [[catapult]]s use [[stone]]s you can literally pick up off of the ground, they're a much better practice platform for your operator, whereas a ballista armed with ''metal'' arrows is a much stronger actual weapons platform. As such, there's never much reason to produce wooden ballista arrows.

Ballista arrows normally have a range of 200 tiles, but impacting a creature will subtract an amount from that range based on the [[weight]] of the arrow: arrows weighing 50Γ or less (i.e. [[adamantine]] and every type of [[wood]]) subtract 50 tiles per hit, arrows weighing 150Γ or more (i.e. every other vanilla weapons-grade [[metal]]) subtract just 5 tiles per hit, and everything in between would scale linearly.

{{Gamedata|{{raw|DF2014:item_siegeammo.txt|ITEM_SIEGEAMMO|ITEM_SIEGEAMMO_BALLISTA}}}}
{{Category|Ammo}}
[[Ru:Ballista arrow]]

v0.34:Ballista arrow

2026-03-30T04:01:29Z

Quietust:

{{Quality|Exceptional|03:58, 7 July 2013 (UTC)}}{{av}}

'''Ballista arrows''' are essentially giant [[arrow]]s, created at a [[siege workshop]] and used as ammunition by a [[ballista]]. There are two types: simple wooden ballista arrows, which are made by unit of [[wood]] at the workshop, and much stronger metal ones, which first requires the creation of a ballista arrowhead at a [[metalsmith's forge]] and then final assembly with wood at the siege workshop.

For such a big, cumbersome, inaccurate weapon, wooden ballista arrows are surprisingly ineffective, dealing only comparatively minor amounts of blunt damage. Metal ballista arrows, on the other hand, are extremely lethal and can kill two fully-grown [[elephant]]s standing in a line if the arrow hits squarely; any [[goblin]]s you hit will be smeared all over the space on which they stood.

Creating arrowheads is tedious and resource-consuming, and both [[catapult]]s and [[ballista]]s train the [[siege operator]] skill when used, at the same rate. Since [[catapult]]s use [[stone]]s you can literally pick up off of the ground, they're a much better practice platform for your operator, whereas a ballista armed with ''metal'' arrows is a much stronger actual weapons platform. As such there's never much reason to produce wooden ballista arrows.

Ballista arrows normally have a range of 200 tiles, but impacting a creature will subtract an amount from that range based on the [[weight]] of the arrow: arrows weighing 50Γ or less (i.e. [[adamantine]] and every type of [[wood]]) subtract 50 tiles per hit, arrows weighing 150Γ or more (i.e. every other vanilla weapons-grade [[metal]]) subtract just 5 tiles per hit, and everything in between would scale linearly.

{{Category|Ammo}}

v0.31:Ballista arrow

2026-03-30T04:00:18Z

Quietust:

{{Quality|Fine|19:40, 24 May 2010 (UTC)}}{{av}}

Ballista arrows are created at a [[siege workshop]] and used as ammunition by a [[ballista]]. Wooden ballista arrows are made using one log, and more powerful ones can be made using one log plus a metal [[ballista arrowhead]] from the [[forge]].

Wooden ballista arrows are generally ineffective, dealing only minor amounts of blunt damage, but metal ballista bolts can be surprisingly lethal.

Additionally, ballista arrows can be destroyed by hitting too many targets in a row. Each arrow normally has a range of 200 tiles, but impacting a creature will subtract an amount from that range based on the [[weight]] of the arrow: arrows weighing 50Γ or less (i.e. [[adamantine]] and every type of [[wood]]) subtract 50 tiles per hit, arrows weighing 150Γ or more (i.e. every other vanilla weapons-grade [[metal]]) subtract just 5 tiles per hit, and everything in between would scale linearly.

'''See also:''' [[Siege engine]]

{{Category|Ammo}}

40d:Ballista arrow

2026-03-30T03:58:07Z

Quietust:

{{av}}{{Quality|Fine|06:10, 16 June 2010 (UTC)}}
Ballista arrows are created at a [[siege workshop]] and used as ammunition by a [[ballista]]. Wooden ballista arrows are made using one log, and (presumably){{verify}} more powerful ones can be made using one log plus a metal [[ballista arrowhead]] from the [[forge]].

Ballista arrows, even mere [[wood]]en ones, are extremely deadly, able to turn a vast swathe of troops into flying [[corpse]]s. It usually takes a [[wall]] or other similar object to stop them, but even then they can still be reused by firing into a wall or raised [[bridge]] above a channel.

Additionally, ballista arrows can be destroyed by hitting too many targets in a row, with the limit being based on the material from which the arrow was made. Each arrow normally has a range of 200 tiles, but impacting a creature will subtract an amount from that range based on the {{token|DAMAGE_PERC|mt}} of the arrow's material: materials with 50% or less damage subtract 50 tiles per hit, materials with 150% or more damage subtract just 5 tiles per hit, and everything in between scales linearly (e.g. [[steel]] subtracts 12, [[iron]] subtracts 27, [[bronze]] subtracts 38, and [[copper]] subtracts 42).

'''See also:''' [[Siege engine]]

{{Category|Ammo}}