Dwarf Fortress Wiki - User contributions [en]

Game folders and files

2025-07-27T19:32:33Z

Tekkud:

{{av}}
Dwarf Fortress's default '''game folder''' location depends on the game version, platform or operating system. It is possible that users will change the install drive or directory, thus these locations may vary.

Non-portable (AppData) game folders were added in version 52.01.



==Game folder==
The game's installation folder is where all the game's content is stored. You might want to go to this folder to browse [[raw file]]s or to check logs.

* '''Dwarf Fortress Classic''' is [[Installation|distributed]] in a zip archive. Depending on the operating system the game folder is either <code>df_##_##_win</code> (with the version number, or the name chosen for the folder during extraction), <code>df_osx</code> or <code>df_linux</code> and will be located where you choose to [[installation|extract it]]. Essentially its where you run the game from. For example: <code>C:\Games\Dwarf Fortress\</code>
* '''Steam''': The default locations are listed below. You can also find it through the app by right-click Dwarf Fortress in the Steam library and choose Properties, then go to the Local files tab and click Browse local files. If you install the game to a custom Steam library, it will end up there instead.
** '''Windows''': <code>C:\Program Files (x86)\Steam\steamapps\common\Dwarf Fortress\</code>
** '''Linux''': <code>~/.steam/debian-installation/steamapps/common/Dwarf Fortress</code>
* '''Itch.io''': The default location is <code>%APPDATA%\itch\apps\Dwarf Fortress\</code> {{Verify}}

Note: On Windows, <code>%APPDATA%</code> is an environment variable that points to <code>C:\Users\(Username)\AppData\Roaming</code>. You can use winkey+R and type '%appdata%' to quickly jump there.

== Savegame folder ==
:''Further information: [[Saved game folder]]''
The savegame folder contains the saved games, and backup saves from the game. The location of this depends on the settings, defaulting to non-portable{{v|52.01}}. Adding ``portable.txt`` to ``\(gamefolder)\prefs\`` (or setting the corresponding option in-game) makes the game save files to the installation directory.

* '''Non-Portable''':
**Windows: <code>C:\Users\(Your username)\AppData\Roaming\Bay 12 Games\Dwarf Fortress\save</code>
**Linux: <code>/home/(Your username)/.local/share/Bay 12 Games/Dwarf Fortress/save</code>.
* '''Portable''':
**The folder is located within the Dwarf Fortress gamefolder <code>(gamefolder)\save\</code>.

== Mod folder ==
:''Further information: [[Modding]]''
The mod folders are where mods are stored. It is in the same game directory as the saves folder.

* '''Non-portable''' ''(Windows)'':
**<code>C:\Users\(Your username)\AppData\Roaming\Bay 12 Games\Dwarf Fortress\mods</code>
**<code>C:\Users\(Your username)\AppData\Roaming\Bay 12 Games\Dwarf Fortress\data\installed_mods</code>
* '''Non-portable''' ''(Linux)'':
**<code>~/.local/share/Bay 12 Games/Dwarf Fortress/mods</code>
**<code>~/.local/share/Bay 12 Games/Dwarf Fortress/data/installed_mods</code>
* '''Portable''':
**<code>(gamefolder)\mods\</code>
**<code>(gamefolder)\data\installed_mods\</code>

== Key ==
{|
| [[File:Folder-orange.svg|20px|link=]] Dwarf Fortress
| : Game folder
|-
| &emsp;● [[File:Folder.svg|20px|link=]] data
| : Contains game content.
|-
| &emsp;&emsp;&emsp;● [[File:Folder.svg|20px|link=]] art
| : Any images not loaded from vanilla graphics modules, primarily for the main menu.
|-
| &emsp;&emsp;&emsp;● [[File:Folder.svg|20px|link=]] init
| : Default versions of the settings.
|-
| &emsp;&emsp;&emsp;● [[File:Folder.svg|20px|link=]] installed_mods
| : Folder of mod copies used when loading a world.
|-
| &emsp;&emsp;&emsp;● [[File:Folder.svg|20px|link=]] sound
| : Contains all audio and music files used in the game.
|-
| &emsp;&emsp;&emsp;● [[File:Folder.svg|20px|link=]] vanilla
| : Contains all the vanilla modules and raw files.
|-
| &emsp;● [[File:Folder.svg|20px|link=]] mods
| : Folder for mods before being loaded.
|-
| &emsp;&emsp;&emsp;● [[File:Folder.svg|20px|link=]] mod_upload
| : Folder for uploading mods to Steam.
|-
| &emsp;● [[File:Folder.svg|20px|link=]] prefs
| : Contains all game setting files.
|-
| &emsp;● [[File:Folder.svg|20px|link=]] save
| : Contains all save game files.
|}

{{files}}
[[ru:Game folders and files]]

Material definition token

2025-04-13T03:30:17Z

Tekkud: /* Material properties */

{{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_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 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_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}}
|
*<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 a latching and tearing bite. 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 a latching and tearing bite. 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 a latching and tearing bite. 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 with a blunt attack (certain generated creatures can do this). 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 with a blunt attack (certain generated creatures can do this). 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 with a blunt attack (certain generated creatures can do this). 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.

|-
| {{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|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|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>
| 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 [[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 ([[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}}
|
| 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}}
|
| 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}}
|
| 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. Does not appear to work.
|}

==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]]

Plant token

2025-03-23T17:32:31Z

Tekkud: /* Growth tokens */

{{Quality|Fine}}
{{av}}
{{Modding}}
The <code>[OBJECT:PLANT]</code> [[token]] begins the definition of a [[plant]] [[raw file]]. Following this, each new plant definition begins with the <code>[PLANT:plant_ID]</code> token, where plant_ID is a unique identifier for the plant, and that plant's properties are then defined using the tokens listed below.

__TOC__
{{clear}}

==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 plant's name as seen in-game.

|-
| {{text anchor|NAME_PLURAL}}
|
*name
| The plural form of the plant's 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. Must be followed with [[material definition token]]s defining the material's properties.

|-
| {{text anchor|USE_MATERIAL}}
|
*material_name
*local_material
| Starts defining a new local plant material with the given name and using the properties of another local plant material. May be followed with material definition tokens to further define its properties or change the properties imported from the local plant material.

|-
| {{text anchor|USE_MATERIAL_TEMPLATE}}
|
*material_name
*template_name
| Starts defining a new local plant material with the name ''material_name'' and using the properties of the specified MATERIAL_TEMPLATE with the name ''template_name''. May be followed with material definition tokens to further define its properties or change the properties imported from the template material.

|-

| {{text anchor|SELECT_MATERIAL}}{{version|50.13}}
|
*material_name
| Selects a previously defined local plant material for subsequent modification. Unlike with [[creature token]]s, "ALL" ''cannot'' be specified here.

|-
| {{text anchor|BASIC_MAT}}
|
* [[Material token|material]]
| Sets the basic material of the plant. This defines what is harvested when the plant itself, rather than a growth, is picked. 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. The only way to remove the plant's basic material entry (e.g. "soybean plant") from every stockpile category is to remove this token, but this will cause problems with farming the plant in a farm plot and harvesting the whole wild plant if that's possible.
|}

==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 are 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. Plants with valid [[biome token]]s and [FREQUENCY:0] will not grow in the wild, but will still be available for entity use and farm plots.

|-
| {{text anchor|WET}}
|
| Restricts the plant to growing near natural water features. A plant with [WET] may be very common or very rare in an area, depending on how many water features that area has. Note that they will not grow next to dwarf-filled channels, since it explicitly checks the tile type (e.g. "River", "River Source", "Brook", "Murky Pool", and variants thereof). Combining this with [DRY] causes it to be ignored.

|-
| {{text anchor|DRY}}
|
| Restricts the plant to growing away from natural water features. Combining this with [WET] causes it to be ignored.

|-
| {{text anchor|BIOME}}
|
*biome
| What [[biome token|biome]] this plant appears in.

|}

==Growth tokens==
These tokens are used for all plants, and specify growths growing on a plant. Edible or otherwise usable growths should have [STOCKPILE_PLANT_GROWTH] in their [[material definition token|material definitions]] for proper stockpiling. This also lets them be collected from plant gathering and farming jobs.

{| {{prettytable}}
|- style='background-color:#ddd'
! width="20%" | Token
! width="20%" | Arguments
! width="60%" | Description

|-
| {{text anchor|GROWTH}}
|
*name
| Defines a plant growth, taking the below tokens as arguments.

|-
| {{text anchor|SELECT_GROWTH}}{{version|50.13}}
|
*name
| Selects a previously-defined plant growth. Any tokens which follow this will further modify the selected growth.

|-
| {{text anchor|GROWTH_NAME}}
|
*singular
*plural (STP for standard plural)
| The name of a plant growth.

|-
| {{text anchor|GROWTH_ITEM}}
|
* [[item token]]
* [[material token]]
| Specifies what item this growth is and what it is made of. Generally, the item type should be PLANT_GROWTH:NONE.

If multiple growths point to the same material with [STOCKPILE_PLANT_GROWTH] then only the first will appear correctly in the stockpile menu, with latter growths appearing as "Plant Growth (?)"

|-
| {{text anchor|GROWTH_HOST_TILE}}
|
*plant part
| Specifies on which part of the plant or tree the growth appears, usually for multi-tile [[tree]]s. Valid tokens are:
*TWIGS
*BRANCHES_AND_TWIGS / LIGHT_BRANCHES_AND_TWIGS
*BRANCHES / LIGHT_BRANCHES
*ALL_BRANCHES_AND_TWIGS
*HEAVY_BRANCHES / DIRECTED_BRANCHES
*HEAVY_BRANCHES_AND_TRUNK / DIRECTED_BRANCHES_AND_TRUNK
*TRUNK
*ROOTS
*CAP
*SAPLING

|-
| {{text anchor|GROWTH_TRUNK_HEIGHT_PERC}}
|
*start percent (0-100+)
*end percent (0-100+)
| Controls the height on the trunk between which the growth begins to appear. The first value is the percent of the trunk height where the growth begins appearing: 0 will cause growths to appear starting above the first tile; 100 will cause growths to appear only at the topmost trunk tile. Can be larger than 100 for trees that have growths on branches extending higher than the trunk.

A value of -1 for the second number appears to make the growths extend all the way to the top of the trunk.

|-
| {{text anchor|GROWTH_DENSITY}}
|
*integer
| Currently has no effect.

|-
| {{text anchor|GROWTH_TIMING}}
|
*[[time]] start:end (0-403200)
| Specifies at which part of the year the growth appears. Default is all year round.

A single growth can only have one GROWTH_TIMING tag. If multiple are declared, the last one will be used. To make a growth appear multiple times during the year, you need to create a different growth for every GROWTH_TIMING interval. By using the same material for all of the duplicate growths, all of them will be stockpiled together and be eligible for the same reactions. Edible/brewable growths will have separate entries in the kitchen menu, though.

There is no known way to declare a growth timing that lasts from winter into spring. Including numbers below 0 or above 403200 in the range will make the growth available at all times, as though you hadn't defined a growth timing at all. So will including a range for which the start time is later than the end time.

This has no effect on farmed growths; all eligible growths that have [STOCKPILE_PLANT_GROWTH] in their materials will be harvested, regardless of if they are currently within their growth timing or not.

|-
| {{text anchor|GROWTH_PRINT}}
|
*overworld tile
*item tile
*color
*time (0-403200) start:end, ALL, or NONE
*priority
| Specifies the appearance of the growth. Can be specified more than once, for example for autumn leaves. Transitions between different timing periods will happen gradually over the course of 2000 ticks.

Priority seems to control what to display when there would be multiple symbols on a tile in ASCII mode. A higher number takes priority over a lower number. Example: if a LEAVES growth has a priority of 1 and a FRUIT growth has a priority of 3, the fruit growth will be the symbol shown when it is present.

The GROWTH_PRINT tile will only be displayed when the growth in question is actually present, even if its timing parameter is ALL.

In graphics mode, any growth being displayed will cause the SHRUB graphic to be used, and no growths available will display the SHRUB_PICKED graphic.

|-
| {{text anchor|GROWTH_HAS_SEED}}
|
| The growth drops a seed if eaten raw.

|-
| {{text anchor|GROWTH_DROPS_OFF}}
|
| Growths drop from the plant, producing a cloud of items which fall on the ground, which [[herbalist]]s can collect.
|-
| {{text anchor|GROWTH_DROPS_OFF_NO_CLOUD}}
|
| Growths drop collectable items from the plant without producing item clouds.

|}

==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]] or NONE
| Makes the plant into a [[tree]]. Cutting down the tree will yield logs made of this material. Setting the material to NONE will give no wood from this tree.

|-
| {{text anchor|TRUNK_NAME}}
|
*name
| What the trunk of the tree is named.

|-
| {{text anchor|MAX_TRUNK_HEIGHT}}
|
*1-8
| The maximum z-level height of a mature tree's trunk, starting from about two z-levels above ground and going up.

|-
| {{text anchor|MAX_TRUNK_DIAMETER}}
|
*1-3
| Upper limit of trunk thickness, in tiles. Counted separately for all branching trunks. Has a geometric effect on log yield.

|-
| {{text anchor|TRUNK_PERIOD}}
|
*integer
| The number of years the trunk takes to grow one Z-level upward.{{verify}}

|-
| {{text anchor|TRUNK_WIDTH_PERIOD}}
|
*integer
| The number of years the trunk takes to grow another tile wider.

|-
| {{text anchor|LIGHT_BRANCHES_NAME}}
|
*name
| What thin branches of the tree are named.

|-
| {{text anchor|BRANCH_DENSITY}} / {{text anchor|LIGHT_BRANCHES_DENSITY}}
|
*integer
| How dense the branches grow on this tree.

|-
| {{text anchor|BRANCH_RADIUS}} / {{text anchor|LIGHT_BRANCH_RADIUS}}
|
*integer
| The radius to which branches can reach. Appears to never reach further than seven tiles from the centre. Does not depend on the trunk branching amount or where trunks are. The values used in the game go from 0-3. Higher values than that can cause crashes. {{bug|10419}}

|-
| {{text anchor|HEAVY_BRANCHES_NAME}} / {{text anchor|DIRECTED_BRANCHES_NAME}}
|
*name
| What thick branches of the tree are named.

|-
| {{text anchor|HEAVY_BRANCH_DENSITY}} / {{text anchor|DIRECTED_BRANCH_DENSITY}}
|
*integer
| Similar to [[Plant_token#BRANCH_DENSITY|BRANCH_DENSITY]] for thick branches.

|-
| {{text anchor|HEAVY_BRANCH_RADIUS}} / {{text anchor|DIRECTED_BRANCH_RADIUS}}
|
*integer
| Similar as [[Plant_token#BRANCH_RADIUS|BRANCH_DENSITY]] for thick branches. Values outside 0-3 can cause crashes. {{bug|10419}}

|-
| {{text anchor|TRUNK_BRANCHING}}
|
*integer
| How much the trunk branches out. 0 makes the trunk straight.

|-
| {{text anchor|ROOT_NAME}} / {{text anchor|ROOTS_NAME}}
|
*name
| What the roots of the tree are named.

|-
| {{text anchor|ROOT_DENSITY}}
|
*integer
| Density of the root growth.

|-
| {{text anchor|ROOT_RADIUS}}
|
*integer
| How wide the roots reach out.

|-
| {{text anchor|TWIGS_NAME}}
|
*name
| What the twigs of the tree are named.

|-
| {{text anchor|TWIGS_SIDE_BRANCHES}}
|
*boolean (0 or 1)
| Twigs appear on the side of branches. Defaults to 1.

|-
| {{text anchor|TWIGS_ABOVE_BRANCHES}}
|
*boolean (0 or 1)
| Twigs appear above branches. Defaults to 1.

|-
| {{text anchor|TWIGS_BELOW_BRANCHES}}
|
*boolean (0 or 1)
| Twigs appear below branches. Defaults to 0.

|-
| {{text anchor|TWIGS_SIDE_HEAVY_BRANCHES}}
|
*boolean (0 or 1)
| Twigs appear on the side of heavy branches. Defaults to 0.

|-
| {{text anchor|TWIGS_ABOVE_HEAVY_BRANCHES}}
|
*boolean (0 or 1)
| Twigs appear above heavy branches. Defaults to 0.

|-
| {{text anchor|TWIGS_BELOW_HEAVY_BRANCHES}}
|
*boolean (0 or 1)
| Twigs appear below heavy branches. Defaults to 0.

|-
| {{text anchor|TWIGS_SIDE_TRUNK}}
|
*boolean (0 or 1)
| Twigs appear on the side of the trunk. Defaults to 0.

|-
| {{text anchor|TWIGS_ABOVE_TRUNK}}
|
*boolean (0 or 1)
| Twigs appear above the trunk. Defaults to 0.

|-
| {{text anchor|TWIGS_BELOW_TRUNK}}
|
*boolean (0 or 1)
| Twigs appear below the trunk. Defaults to 0.

|-
| {{text anchor|TREE_HAS_MUSHROOM_CAP}}
|
| The tree has a rounded cap-hood like a giant mushroom. This severely stunts a tree's maximum height. {{bug|7313}}

|-
| {{text anchor|CAP_NAME}}
|
*name
| What this mushroom-cap is called. Only makes sense with TREE_HAS_MUSHROOM_CAP.

|-
| {{text anchor|CAP_PERIOD}}
|
*integer
| Similar to the other PERIOD tags, influences the rate of the mushroom cap growth. Only makes sense with TREE_HAS_MUSHROOM_CAP.

|-
| {{text anchor|CAP_RADIUS}}
|
*integer
| The radius of a mushroom cap. Only makes sense with TREE_HAS_MUSHROOM_CAP.

|-
| {{text anchor|STANDARD_TILE_NAMES}}
|
| Uses the standard names for the tree components (roots, trunk, branches, etc.)

|-
| {{text anchor|TREE_TILE}}
|
*tile
| The tile used for trees of this type on the world map. Defaults to 24 (↑).

|-
| {{text anchor|DEAD_TREE_TILE}}
|
*tile
| The tile used for (un)dead trees and deciduous trees (generally in winter) 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 sapling of this tree will drown once the water on its tile reaches this level. 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]".

|}

==Shrub tokens==
These tokens are used for non-grass, non-tree plants.

{| {{prettytable}}
|- style='background-color:#ddd'
! width="20%" | Token
! width="20%" | Arguments
! width="60%" | Description

|-
| {{text anchor|SPRING}}, {{text anchor|SUMMER}}, {{text anchor|AUTUMN}}, {{text anchor|WINTER}}
|
| Allows the plant to grow in farm plots during the given season.

If the plant is a surface plant, allows it to grow in the wild during this season; wild surface plants without this token will disappear at the beginning of the season. Underground plants grow wild in all seasons, regardless of their season tokens.

|-
| {{text anchor|GROWDUR}}
|
*time
| How long the plant takes to grow to harvest in a farm plot. Unit hundreds of ticks, See [[Time]]. There are 1008 GROWDUR units in a season. Defaults to 300.

|-
| {{text anchor|VALUE}}
|
*value
| Has no known effect. Previously set the value of the harvested plant.

|-
| {{text anchor|PICKED_TILE}}
|
*tile
| The tile used when the plant is harvested whole, or is ready to be picked from a farm plot. May either be a cp437 tile number, or a character between single quotes. See [[Main:character table|character table]]. Defaults to 231 (τ).

|-
| {{text anchor|DEAD_PICKED_TILE}}
|
*tile
| The tile used when a plant harvested whole has wilted. Defaults to 169 (⌐).

|-
| {{text anchor|SHRUB_TILE}}
|
*tile
| The tile used to represent this plant when it is wild, alive, and has no growths. Defaults to 34 (").

|-
| {{text anchor|DEAD_SHRUB_TILE}}
|
*tile
| The tile used to represent this plant when it is dead in the wild. Defaults to 34 (").

|-
| {{text anchor|CLUSTERSIZE}}
|
*size
| The maximum stack size collected when gathered via herbalism (but ''not'' farm plots). Defaults to 5. CLUSTERSIZE must be greater than or equal to 1+ the number of instances of [STOCKPILE_PLANT_GROWTH] in the plant's raws. For plants like vanilla cabbage, clustersize of 1, which is less than 1+[one instance]=2, will prevent citizens from gathering the plant. Best to set all cluster sizes to 2 or higher for safety.

|-
| {{text anchor|PICKED_COLOR}}
|
*foreground
*background
*bright
| The color of the plant when it has been picked whole, or when it is ready for harvest in a farm plot. Defaults to 2:0:0 (dark green).

|-
| {{text anchor|DEAD_PICKED_COLOR}}
|
*foreground
*background
*bright
| The [[color]] of the plant when it has been picked whole, but has wilted. Defaults to 0:0:1 (dark gray).

|-
| {{text anchor|SHRUB_COLOR}}
|
*foreground
*background
*bright
| The [[color]] of the plant when it is alive, wild, and has no growths. Defaults to 2:0:0 (dark green).

|-
| {{text anchor|DEAD_SHRUB_COLOR}}
|
*foreground
*background
*bright
|The [[color]] of the plant when it is dead in the wild. Defaults to 6:0:0 (brown).

|-
| {{text anchor|SHRUB_DROWN_LEVEL}}
|
*depth
| The shrub will drown once the water on its tile reaches this level. Defaults to 4.

|-
| {{text anchor|DRINK}}
|
* [[Material token|material]]
| Names a [[alcohol|drink]] made from the plant, allowing it to be used in entity resources. Previously also permitted brewing the plant into [[alcohol]] made of this material. Now, a MATERIAL_REACTION_PRODUCT of type DRINK_MAT should be used on the proper plant material.

|-
| {{text anchor|MILL}}
|
* [[Material token|material]]
| Permits milling the plant at a [[quern]] or [[millstone]] into a powder made of this material and allows its use in entity resources. Said material should have [POWDER_MISC_PLANT] to permit proper stockpiling. This token makes the whole plant harvestable regardless of which material is designated for milling. For plants with millable ''growths'', use only MATERIAL_REACTION_PRODUCT or ITEM_REACTION_PRODUCT tokens to define the milling products.

|-
| {{text anchor|THREAD}}
|
* [[Material token|material]]
| Permits processing the plant at a [[farmer's workshop]] to yield threads made of this material and allows its use in entity resources. 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|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. This allows animals to graze on it, and prevents it and its growths from being picked by herbalists. (Grass growths can still be picked in adventure mode, however.)

|-
| {{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}}
[[ru:Plant token]]

Plant token

2025-03-23T17:31:49Z

Tekkud: /* Growth tokens */

{{Quality|Fine}}
{{av}}
{{Modding}}
The <code>[OBJECT:PLANT]</code> [[token]] begins the definition of a [[plant]] [[raw file]]. Following this, each new plant definition begins with the <code>[PLANT:plant_ID]</code> token, where plant_ID is a unique identifier for the plant, and that plant's properties are then defined using the tokens listed below.

__TOC__
{{clear}}

==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 plant's name as seen in-game.

|-
| {{text anchor|NAME_PLURAL}}
|
*name
| The plural form of the plant's 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. Must be followed with [[material definition token]]s defining the material's properties.

|-
| {{text anchor|USE_MATERIAL}}
|
*material_name
*local_material
| Starts defining a new local plant material with the given name and using the properties of another local plant material. May be followed with material definition tokens to further define its properties or change the properties imported from the local plant material.

|-
| {{text anchor|USE_MATERIAL_TEMPLATE}}
|
*material_name
*template_name
| Starts defining a new local plant material with the name ''material_name'' and using the properties of the specified MATERIAL_TEMPLATE with the name ''template_name''. May be followed with material definition tokens to further define its properties or change the properties imported from the template material.

|-

| {{text anchor|SELECT_MATERIAL}}{{version|50.13}}
|
*material_name
| Selects a previously defined local plant material for subsequent modification. Unlike with [[creature token]]s, "ALL" ''cannot'' be specified here.

|-
| {{text anchor|BASIC_MAT}}
|
* [[Material token|material]]
| Sets the basic material of the plant. This defines what is harvested when the plant itself, rather than a growth, is picked. 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. The only way to remove the plant's basic material entry (e.g. "soybean plant") from every stockpile category is to remove this token, but this will cause problems with farming the plant in a farm plot and harvesting the whole wild plant if that's possible.
|}

==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 are 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. Plants with valid [[biome token]]s and [FREQUENCY:0] will not grow in the wild, but will still be available for entity use and farm plots.

|-
| {{text anchor|WET}}
|
| Restricts the plant to growing near natural water features. A plant with [WET] may be very common or very rare in an area, depending on how many water features that area has. Note that they will not grow next to dwarf-filled channels, since it explicitly checks the tile type (e.g. "River", "River Source", "Brook", "Murky Pool", and variants thereof). Combining this with [DRY] causes it to be ignored.

|-
| {{text anchor|DRY}}
|
| Restricts the plant to growing away from natural water features. Combining this with [WET] causes it to be ignored.

|-
| {{text anchor|BIOME}}
|
*biome
| What [[biome token|biome]] this plant appears in.

|}

==Growth tokens==
These tokens are used for all plants, and specify growths growing on a plant. Edible or otherwise usable growths should have [STOCKPILE_PLANT_GROWTH] in their [[material definition token|material definitions]] for proper stockpiling. This also lets them be collected from plant gathering and farming jobs.

{| {{prettytable}}
|- style='background-color:#ddd'
! width="20%" | Token
! width="20%" | Arguments
! width="60%" | Description

|-
| {{text anchor|GROWTH}}
|
*name
| Defines a plant growth, taking the below tokens as arguments.

|-
| {{text anchor|SELECT_GROWTH}}{{version|50.13}}
|
*name
| Selects a previously-defined plant growth. Any tokens which follow this will further modify the selected growth.

|-
| {{text anchor|GROWTH_NAME}}
|
*singular
*plural (STP for standard plural)
| The name of a plant growth.

|-
| {{text anchor|GROWTH_ITEM}}
|
* [[item token]]
* [[material token]]
| Specifies what item this growth is and what it is made of. Generally, the item type should be PLANT_GROWTH:NONE.
|
| If multiple growths point to the same material with [STOCKPILE_PLANT_GROWTH] then only the first will appear correctly in the stockpile menu, with latter growths appearing as "Plant Growth (?)"

|-
| {{text anchor|GROWTH_HOST_TILE}}
|
*plant part
| Specifies on which part of the plant or tree the growth appears, usually for multi-tile [[tree]]s. Valid tokens are:
*TWIGS
*BRANCHES_AND_TWIGS / LIGHT_BRANCHES_AND_TWIGS
*BRANCHES / LIGHT_BRANCHES
*ALL_BRANCHES_AND_TWIGS
*HEAVY_BRANCHES / DIRECTED_BRANCHES
*HEAVY_BRANCHES_AND_TRUNK / DIRECTED_BRANCHES_AND_TRUNK
*TRUNK
*ROOTS
*CAP
*SAPLING

|-
| {{text anchor|GROWTH_TRUNK_HEIGHT_PERC}}
|
*start percent (0-100+)
*end percent (0-100+)
| Controls the height on the trunk between which the growth begins to appear. The first value is the percent of the trunk height where the growth begins appearing: 0 will cause growths to appear starting above the first tile; 100 will cause growths to appear only at the topmost trunk tile. Can be larger than 100 for trees that have growths on branches extending higher than the trunk.

A value of -1 for the second number appears to make the growths extend all the way to the top of the trunk.

|-
| {{text anchor|GROWTH_DENSITY}}
|
*integer
| Currently has no effect.

|-
| {{text anchor|GROWTH_TIMING}}
|
*[[time]] start:end (0-403200)
| Specifies at which part of the year the growth appears. Default is all year round.

A single growth can only have one GROWTH_TIMING tag. If multiple are declared, the last one will be used. To make a growth appear multiple times during the year, you need to create a different growth for every GROWTH_TIMING interval. By using the same material for all of the duplicate growths, all of them will be stockpiled together and be eligible for the same reactions. Edible/brewable growths will have separate entries in the kitchen menu, though.

There is no known way to declare a growth timing that lasts from winter into spring. Including numbers below 0 or above 403200 in the range will make the growth available at all times, as though you hadn't defined a growth timing at all. So will including a range for which the start time is later than the end time.

This has no effect on farmed growths; all eligible growths that have [STOCKPILE_PLANT_GROWTH] in their materials will be harvested, regardless of if they are currently within their growth timing or not.

|-
| {{text anchor|GROWTH_PRINT}}
|
*overworld tile
*item tile
*color
*time (0-403200) start:end, ALL, or NONE
*priority
| Specifies the appearance of the growth. Can be specified more than once, for example for autumn leaves. Transitions between different timing periods will happen gradually over the course of 2000 ticks.

Priority seems to control what to display when there would be multiple symbols on a tile in ASCII mode. A higher number takes priority over a lower number. Example: if a LEAVES growth has a priority of 1 and a FRUIT growth has a priority of 3, the fruit growth will be the symbol shown when it is present.

The GROWTH_PRINT tile will only be displayed when the growth in question is actually present, even if its timing parameter is ALL.

In graphics mode, any growth being displayed will cause the SHRUB graphic to be used, and no growths available will display the SHRUB_PICKED graphic.

|-
| {{text anchor|GROWTH_HAS_SEED}}
|
| The growth drops a seed if eaten raw.

|-
| {{text anchor|GROWTH_DROPS_OFF}}
|
| Growths drop from the plant, producing a cloud of items which fall on the ground, which [[herbalist]]s can collect.
|-
| {{text anchor|GROWTH_DROPS_OFF_NO_CLOUD}}
|
| Growths drop collectable items from the plant without producing item clouds.

|}

==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]] or NONE
| Makes the plant into a [[tree]]. Cutting down the tree will yield logs made of this material. Setting the material to NONE will give no wood from this tree.

|-
| {{text anchor|TRUNK_NAME}}
|
*name
| What the trunk of the tree is named.

|-
| {{text anchor|MAX_TRUNK_HEIGHT}}
|
*1-8
| The maximum z-level height of a mature tree's trunk, starting from about two z-levels above ground and going up.

|-
| {{text anchor|MAX_TRUNK_DIAMETER}}
|
*1-3
| Upper limit of trunk thickness, in tiles. Counted separately for all branching trunks. Has a geometric effect on log yield.

|-
| {{text anchor|TRUNK_PERIOD}}
|
*integer
| The number of years the trunk takes to grow one Z-level upward.{{verify}}

|-
| {{text anchor|TRUNK_WIDTH_PERIOD}}
|
*integer
| The number of years the trunk takes to grow another tile wider.

|-
| {{text anchor|LIGHT_BRANCHES_NAME}}
|
*name
| What thin branches of the tree are named.

|-
| {{text anchor|BRANCH_DENSITY}} / {{text anchor|LIGHT_BRANCHES_DENSITY}}
|
*integer
| How dense the branches grow on this tree.

|-
| {{text anchor|BRANCH_RADIUS}} / {{text anchor|LIGHT_BRANCH_RADIUS}}
|
*integer
| The radius to which branches can reach. Appears to never reach further than seven tiles from the centre. Does not depend on the trunk branching amount or where trunks are. The values used in the game go from 0-3. Higher values than that can cause crashes. {{bug|10419}}

|-
| {{text anchor|HEAVY_BRANCHES_NAME}} / {{text anchor|DIRECTED_BRANCHES_NAME}}
|
*name
| What thick branches of the tree are named.

|-
| {{text anchor|HEAVY_BRANCH_DENSITY}} / {{text anchor|DIRECTED_BRANCH_DENSITY}}
|
*integer
| Similar to [[Plant_token#BRANCH_DENSITY|BRANCH_DENSITY]] for thick branches.

|-
| {{text anchor|HEAVY_BRANCH_RADIUS}} / {{text anchor|DIRECTED_BRANCH_RADIUS}}
|
*integer
| Similar as [[Plant_token#BRANCH_RADIUS|BRANCH_DENSITY]] for thick branches. Values outside 0-3 can cause crashes. {{bug|10419}}

|-
| {{text anchor|TRUNK_BRANCHING}}
|
*integer
| How much the trunk branches out. 0 makes the trunk straight.

|-
| {{text anchor|ROOT_NAME}} / {{text anchor|ROOTS_NAME}}
|
*name
| What the roots of the tree are named.

|-
| {{text anchor|ROOT_DENSITY}}
|
*integer
| Density of the root growth.

|-
| {{text anchor|ROOT_RADIUS}}
|
*integer
| How wide the roots reach out.

|-
| {{text anchor|TWIGS_NAME}}
|
*name
| What the twigs of the tree are named.

|-
| {{text anchor|TWIGS_SIDE_BRANCHES}}
|
*boolean (0 or 1)
| Twigs appear on the side of branches. Defaults to 1.

|-
| {{text anchor|TWIGS_ABOVE_BRANCHES}}
|
*boolean (0 or 1)
| Twigs appear above branches. Defaults to 1.

|-
| {{text anchor|TWIGS_BELOW_BRANCHES}}
|
*boolean (0 or 1)
| Twigs appear below branches. Defaults to 0.

|-
| {{text anchor|TWIGS_SIDE_HEAVY_BRANCHES}}
|
*boolean (0 or 1)
| Twigs appear on the side of heavy branches. Defaults to 0.

|-
| {{text anchor|TWIGS_ABOVE_HEAVY_BRANCHES}}
|
*boolean (0 or 1)
| Twigs appear above heavy branches. Defaults to 0.

|-
| {{text anchor|TWIGS_BELOW_HEAVY_BRANCHES}}
|
*boolean (0 or 1)
| Twigs appear below heavy branches. Defaults to 0.

|-
| {{text anchor|TWIGS_SIDE_TRUNK}}
|
*boolean (0 or 1)
| Twigs appear on the side of the trunk. Defaults to 0.

|-
| {{text anchor|TWIGS_ABOVE_TRUNK}}
|
*boolean (0 or 1)
| Twigs appear above the trunk. Defaults to 0.

|-
| {{text anchor|TWIGS_BELOW_TRUNK}}
|
*boolean (0 or 1)
| Twigs appear below the trunk. Defaults to 0.

|-
| {{text anchor|TREE_HAS_MUSHROOM_CAP}}
|
| The tree has a rounded cap-hood like a giant mushroom. This severely stunts a tree's maximum height. {{bug|7313}}

|-
| {{text anchor|CAP_NAME}}
|
*name
| What this mushroom-cap is called. Only makes sense with TREE_HAS_MUSHROOM_CAP.

|-
| {{text anchor|CAP_PERIOD}}
|
*integer
| Similar to the other PERIOD tags, influences the rate of the mushroom cap growth. Only makes sense with TREE_HAS_MUSHROOM_CAP.

|-
| {{text anchor|CAP_RADIUS}}
|
*integer
| The radius of a mushroom cap. Only makes sense with TREE_HAS_MUSHROOM_CAP.

|-
| {{text anchor|STANDARD_TILE_NAMES}}
|
| Uses the standard names for the tree components (roots, trunk, branches, etc.)

|-
| {{text anchor|TREE_TILE}}
|
*tile
| The tile used for trees of this type on the world map. Defaults to 24 (↑).

|-
| {{text anchor|DEAD_TREE_TILE}}
|
*tile
| The tile used for (un)dead trees and deciduous trees (generally in winter) 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 sapling of this tree will drown once the water on its tile reaches this level. 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]".

|}

==Shrub tokens==
These tokens are used for non-grass, non-tree plants.

{| {{prettytable}}
|- style='background-color:#ddd'
! width="20%" | Token
! width="20%" | Arguments
! width="60%" | Description

|-
| {{text anchor|SPRING}}, {{text anchor|SUMMER}}, {{text anchor|AUTUMN}}, {{text anchor|WINTER}}
|
| Allows the plant to grow in farm plots during the given season.

If the plant is a surface plant, allows it to grow in the wild during this season; wild surface plants without this token will disappear at the beginning of the season. Underground plants grow wild in all seasons, regardless of their season tokens.

|-
| {{text anchor|GROWDUR}}
|
*time
| How long the plant takes to grow to harvest in a farm plot. Unit hundreds of ticks, See [[Time]]. There are 1008 GROWDUR units in a season. Defaults to 300.

|-
| {{text anchor|VALUE}}
|
*value
| Has no known effect. Previously set the value of the harvested plant.

|-
| {{text anchor|PICKED_TILE}}
|
*tile
| The tile used when the plant is harvested whole, or is ready to be picked from a farm plot. May either be a cp437 tile number, or a character between single quotes. See [[Main:character table|character table]]. Defaults to 231 (τ).

|-
| {{text anchor|DEAD_PICKED_TILE}}
|
*tile
| The tile used when a plant harvested whole has wilted. Defaults to 169 (⌐).

|-
| {{text anchor|SHRUB_TILE}}
|
*tile
| The tile used to represent this plant when it is wild, alive, and has no growths. Defaults to 34 (").

|-
| {{text anchor|DEAD_SHRUB_TILE}}
|
*tile
| The tile used to represent this plant when it is dead in the wild. Defaults to 34 (").

|-
| {{text anchor|CLUSTERSIZE}}
|
*size
| The maximum stack size collected when gathered via herbalism (but ''not'' farm plots). Defaults to 5. CLUSTERSIZE must be greater than or equal to 1+ the number of instances of [STOCKPILE_PLANT_GROWTH] in the plant's raws. For plants like vanilla cabbage, clustersize of 1, which is less than 1+[one instance]=2, will prevent citizens from gathering the plant. Best to set all cluster sizes to 2 or higher for safety.

|-
| {{text anchor|PICKED_COLOR}}
|
*foreground
*background
*bright
| The color of the plant when it has been picked whole, or when it is ready for harvest in a farm plot. Defaults to 2:0:0 (dark green).

|-
| {{text anchor|DEAD_PICKED_COLOR}}
|
*foreground
*background
*bright
| The [[color]] of the plant when it has been picked whole, but has wilted. Defaults to 0:0:1 (dark gray).

|-
| {{text anchor|SHRUB_COLOR}}
|
*foreground
*background
*bright
| The [[color]] of the plant when it is alive, wild, and has no growths. Defaults to 2:0:0 (dark green).

|-
| {{text anchor|DEAD_SHRUB_COLOR}}
|
*foreground
*background
*bright
|The [[color]] of the plant when it is dead in the wild. Defaults to 6:0:0 (brown).

|-
| {{text anchor|SHRUB_DROWN_LEVEL}}
|
*depth
| The shrub will drown once the water on its tile reaches this level. Defaults to 4.

|-
| {{text anchor|DRINK}}
|
* [[Material token|material]]
| Names a [[alcohol|drink]] made from the plant, allowing it to be used in entity resources. Previously also permitted brewing the plant into [[alcohol]] made of this material. Now, a MATERIAL_REACTION_PRODUCT of type DRINK_MAT should be used on the proper plant material.

|-
| {{text anchor|MILL}}
|
* [[Material token|material]]
| Permits milling the plant at a [[quern]] or [[millstone]] into a powder made of this material and allows its use in entity resources. Said material should have [POWDER_MISC_PLANT] to permit proper stockpiling. This token makes the whole plant harvestable regardless of which material is designated for milling. For plants with millable ''growths'', use only MATERIAL_REACTION_PRODUCT or ITEM_REACTION_PRODUCT tokens to define the milling products.

|-
| {{text anchor|THREAD}}
|
* [[Material token|material]]
| Permits processing the plant at a [[farmer's workshop]] to yield threads made of this material and allows its use in entity resources. 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|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. This allows animals to graze on it, and prevents it and its growths from being picked by herbalists. (Grass growths can still be picked in adventure mode, however.)

|-
| {{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}}
[[ru:Plant token]]

Modding pitfalls

2025-03-22T19:20:14Z

Tekkud: /* Reactions */

{{Quality|Tattered}}
{{av}}
{{For/see|a guide to getting started with modding|[[Modding]]}}
{{Modding}}
When making a mod, there's a ''lot'' of things that can go wrong. Here's a bunch of common pitfalls that people might fall into.

== Errorlog ==
The error log is in a file called ``errorlog.txt``, located in the root directory of the game (the same folder as Dwarf Fortress's executable). Check that before you read on; your problem may in fact be in there.

== My mod won't load ==
Make sure you have an [[info.txt file]] and that your mod is in the root directory of the ``mods`` folder (``Dwarf Fortress/mods``), '''not''' in the ``mod_upload`` folder. ''Dwarf Fortress'' doesn't read ``mod_upload`` for using mods, but only to [[Mod#Publishing mods|publish]] them to the Steam Workshop.

Make sure you have '''every [[Mod info token#Tokens|required token in your info.txt!]]''' Also, make sure that the mod has a {{token|NUMERIC_VERSION|modinfo}} which is an integer, and greater than or equal to {{token|EARLIEST_COMPATIBLE_NUMERIC_VERSION|modinfo}}.

So, this is acceptable:

{{code|
[NUMERIC_VERSION:1]
[EARLIEST_COMPATIBLE_NUMERIC_VERSION:1]
}}
But this isn't:
{{code|
[NUMERIC_VERSION:1.05]
[EARLIEST_COMPATIBLE_NUMERIC_VERSION:1.0]
}}
Nor is this:
{{code|
[NUMERIC_VERSION:1]
[EARLIEST_COMPATIBLE_NUMERIC_VERSION:5005]
}}

== My mod loads, but my creature/plant/entity won't ==
Make sure the file has the correct name, and starts with the following lines:

# A filename that refers to the type of objects contained therein. '''Creature files must start with ``creature_``, entity files must start with ``entity_``, and so on.'''
# The filename on the first line of the file.
# ``[OBJECT:type]``, where "type" is replaced with the relevant object type, ``[OBJECT:CREATURE]`` etc

If your edit meets all of the above criteria, and still won't load, you can ask, or look for, specific advice from these [[Modding#Resource Overview|modding resources]].

== My mod won't update ==

''Dwarf Fortress'' only reads from ``installed_mods`` (``Dwarf Fortress/data/installed_mods``) when loading a world. If you have made changes to your mod since installing it, you will need to propagate your edits from ``mods`` to ``installed_mods`` to see them in-game. For quick testing, the easiest way to do so is by deleting the old copy in ``installed_mods``. You can also increase {{token|NUMERIC_VERSION|modinfo}} and {{token|EARLIEST_COMPATIBLE_NUMERIC_VERSION|modinfo}} to create a new copy.

Although you can edit currently-installed mods directly from the ``installed_mods`` folder , this often leads to confusion over where/how errors or bugs are occurring, as well as increasing the risk of accidentally overwriting edits made there. Applying newly-edited raws by working from the ``mods`` folder and loading them in from the in-game menu can avoid many oversights in troubleshooting.

== My mod causes glitches in world generation/won't work with '(other mod)' ==
If you are editing an object already present in the vanilla [[Raw file|raws]], you will cause [[Duplicated_raws|duplication errors]] if you don't use the [[Modding#Modifying_the_vanilla_objects|CUT or SELECT]] functions to modify that object. The modding page [[Modding#Selecting_and_Cutting|lists which objects]] can be edited using these functions.

If your mod cuts an object and is loaded after another mod that edits the same object, your mod will completely replace that mod's edit. Generally speaking, if you are merely adding tags/tokens to an object, you can achieve the same results with SELECT, which effectively appends those edits to an already existing vanilla object rather than replacing it. At the moment, only creature objects can have tags removed without the use of the CUT function, by making use of the more advanced [[Creature_variation_token|creature variation tokens]].

== Creatures ==

=== My civilization lives in "Nothing hamlets", "Nothing fortresses" or similar ===
You forgot to add a {{token|NAME}}. These use {{token|NAME}} rather than {{token|CASTE_NAME}}, so if you have a {{token|CASTE_NAME}} but no {{token|NAME}}, you'll see the individuals having a correct species name but their sites not having one.

=== Creature edits not working or duplicate creatures/creature materials appearing in-game ===
You might have added a [[Duplicated_raws|duplicate]] creature entry by forgetting to either [[Modding#Selecting_and_Cutting|SELECT or CUT]] the pre-existing vanilla creature entry.

== Reactions ==

=== My custom reaction isn't appearing in the game ===

Make sure you have added the corresponding tokens to the relevant civilization entity object ({{token|PERMITTED_BUILDING|e}}/{{token|PERMITTED_REACTION|e}}).

=== My custom armor/clothing reaction won't let the user choose the size ===

Currently, only the internal make armor/clothing tasks can set the product size via the Details screen; custom reactions cannot do this. If you want to be able to size things when ordering them to be made, they have to be included in the entity using the [[Entity_token#Available_resources|ARMOR]] token. The size selection menu only displays if armor/clothing made from cloth, leather, or weapons-grade metal is being produced.

=== Workers are not using items from barrels even though they're using them otherwise ===

When defining reagents, not including an item type (e.g. PLANT:NONE, PLANT_GROWTH:NONE) will cause workers to be unable to find otherwise eligible reagents when they're stored in barrels.

[[Category: Modding]]

Reaction

2025-03-22T19:17:03Z

Tekkud: /* Item token */

{{Quality|Superior}}
{{av}}
{{Modding}}

'''Reactions''' are modular, editable formulas that take specific ingredients, or reagents, and use them to produce a desired item. A lot of reactions are hardcoded—building beds or creating glass, for example—but a few are freely editable, and it's (sometimes) quite simple to add additional ones. There is a separate page with custom [[reaction examples]].

== Reaction differences between modes ==

In [[fortress mode]], reactions are linked to specific buildings, and must be added to a civilization's [[entity token|entity file]] to be usable by that civilization. This has the useful effect of limiting new items and materials (such as special [[wood]] or [[metal]]) to civilizations that have the requisite reaction — so that if you give your custom civilization a reaction to produce "star metal" or some other custom material, only they will be able to produce it. Exclusive non-{{token|SPECIAL|inorganic}} metals, such as [[steel]], may appear on [[bandit]]s and other entities with access to all materials.

In [[adventure mode]], reactions are freely available in the {{Adv menu icon|x}} create menu, and any adventurer character can make free use of them. Reagents may be held in the hands or dropped on the ground, but cannot be used within a backpack or quiver. There are several bugs with adventure mode reactions, chief of which is the fact that you cannot select liquid reagents.{{verify}} 

== Anatomy of a reaction ==
Reactions are found within reaction_x files (such as reaction_smelter or reaction_other). All reaction files must begin with the file name, followed by the <code>[OBJECT:REACTION]</code> token that tells the game that the file contains reaction definitions.

The reactions themselves generally adhere to the following structure:

[REACTION:<identifier>]
[NAME:<name>]
[BUILDING:<BUILDING NAME>:<BUILDING KEY>]
[REAGENT:A:150:BAR:NONE:POTASH:NONE]
[PRODUCT:100:1:BAR:NONE:PEARLASH:NONE][PRODUCT_DIMENSION:150]
[FUEL]
[SKILL:<SKILL TOKEN>]
[MAX_MULTIPLIER:<multiplier>]
[AUTOMATIC]
[ADVENTURE_MODE_ENABLED]
[DESCRIPTION:<description>]

* ''[[#Reaction identifier|identifier]]'': The internal ID of the reaction.
* ''[[#Reaction name|name]]'': The name of the reaction, visible to the player in the Fortress mode or Adventure mode menus.
* ''[[#Building|building]]'': The building ID that the reaction uses, and the relevant keyboard shortcut.
* ''[[#Reagents|...reagents...]]'': Zero or more reagents (ingredients) that are required to be in stock for the reaction to be possible.
* ''[[#Products|...products...]]'': Zero or more products that are created from the reaction.
* ''[[#Fuel|fuel]]'': (optional) If present, the reaction requires charcoal, coke or a magma-powered workshop.
* ''[[#Skill|skill]]'': (optional) The skill required and trained by the reaction.
* ''[[#Max multiplier|multiplier]]'': (optional) If present, the reaction will only be done the specified number of times per job; used to limit the output of reactions that accept stacks of items as reagents.
* ''[[#Automatic|automatic]]'': (optional) If present, the reaction will automatically be enqueued whenever it can possibly be performed.
* ''[[#Adventure mode enabled|adventure mode enabled]]'': (optional) If present, the reaction can be used by the player in Adventure mode.
* ''[[#Description|description]]'': (optional) If present, shows pop-up description when the reaction is selected in workshop (not working in v50).

=== Reaction identifier ===
The REACTION token assigns a unique ID to your reaction.
[REACTION:<reaction identifier>]

The ''reaction identifier'' may be anything, so long as it is unique within the raw data files. A good habit to get into is to append a short prefix or suffix to each name related to the name of your mod, to ensure nobody else is going to make an identical reaction and thereby mess up the game if their mod is run alongside yours. This is referenced in an entity definition via [[Entity_token#PERMITTED_REACTION|PERMITTED_REACTION]] to allow that entity to use the reaction.

=== Reaction name ===
The REACTION_NAME token assigns a descriptive name to your reaction in-game.
[REACTION_NAME:<name>]

==== Name ====
This can be anything at all, and is how the reaction will appear in the job list of the building it is assigned to, and so should describe the reaction. '''Tan a hide''', for example, is the name of the default leather-producing reaction. Generally this should be written as a small descriptive verb phrase, with the first letter capitalized, for consistency with the existing reactions.

=== Building ===
The BUILDING token assigns the reaction to a building. Adding multiple BUILDING tokens will cause the reaction to be available at all of the specified buildings. Omitting the BUILDING token entirely will make the reaction unusable in Fortress mode (often used to restrict certain reactions to [[Reaction#Adventure_Mode_enabled|Adventure mode]]).

[BUILDING:<building name>:<building key>]
* [[#Building name|''building name:'']] The ID of the building the reaction appears in.
* [[#Building key|''building key:'']] The hotkey to queue up the reaction in the specified building.

==== Building name ====
This is the ID of the building where the reaction will be carried out. Valid building names are as follows:

* ASHERY - [[Ashery]]
* BOWYER - [[Bowyer's workshop]]
* CARPENTER - [[Carpenter's workshop]]
* CLOTHES - [[Clothier's shop]]
* CRAFTSMAN - [[Craftsdwarf's workshop]]
* FARMER - [[Farmer's workshop]]
* GLASS - [[Glass furnace]]
* KILN - [[Kiln]] and [[Magma kiln]]
* KITCHEN - [[Kitchen]]
* LEATHER - [[Leather works]]
* MASON - [[Stoneworker's workshop]]
* METALSMITH - [[Metalsmith's forge]]
* MILLSTONE - [[Millstone]]
* QUERN - [[Quern]]
* SIEGE - [[Siege workshop]]
* SMELTER - [[Smelter]] and [[Magma smelter]]
* STILL - [[Still]]
* TANNER - [[Tanner's shop]]
* WOOD - [[Wood furnace]]
* Any custom (raw-defined) building, such as:
** SOAP_MAKER - [[Soap maker's workshop]]
** SCREW_PRESS - [[Screw press]]

==== Building key ====
This used to define the shortcut key(s) used to queue up the reaction in a workshop during gameplay. Doesn't do anything in the current version. {{version|50.01}}

=== Category ===

Categories are custom submenus for buildings' reaction menus. A reaction doesn't require a category, but if you have a lot of reactions, categories can be invaluable for organizing and presenting those reactions to players.

Categories can be nested indefinitely—you can have a category within a category within a category within a category within a category within... but as a practical matter, nesting categories more than 2 deep is not recommended.

Categories will be displayed in alphabetical order, first off the file name and then off the category name.

Categories currently have no effect on adventure mode reactions.

==== Defining a category ====

Each category needs to be defined within a reaction, usually one which should appear within its menu. Categories only need to be defined once.

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Arguments
! Description
|-
| style="vertical-align: top"| CATEGORY || style="vertical-align: top"| Category ID || The category ID is a unique identifier for the category. It is only used in the raws, and will not appear in the game.

If you're defining multiple categories within the same reaction - for example, if you intend the reaction to be nested two deep, and haven't yet defined the super-category - the ''last'' CATEGORY token within the reaction definition is the one that the reaction will appear in.
|-
| style="vertical-align: top"| CATEGORY_NAME || style="vertical-align: top"| String || The name of the category as displayed in-game.
|-
| style="vertical-align: top"| CATEGORY_DESCRIPTION || style="vertical-align: top"| String || Optional. If present, when the category is highlighted in a building menu, this string will be displayed in the Helpful Hint box.
|-
| style="vertical-align: top"| CATEGORY_PARENT || style="vertical-align: top"| Category ID || Optional. If present, this category will be a submenu of the indicated category, rather than a submenu of the reaction's building.
|-
| style="vertical-align: top"| CATEGORY_KEY || style="vertical-align: top"| Hotkey token || Optional. If present, this category can be selected from its parent menu (whether a building or a parent category) using the given hotkey. Uses the same format as the BUILDING KEY described above.
|}

==== Adding reactions to an existing category ====

Just include the tag [CATEGORY:<category_id>] within your reaction definition, and if the category exists, your reaction will be added to its menu. You can only add reactions to custom categories.

Each reaction can belong to only one category.

=== Reagents ===

REAGENTs are a little bit complicated. They are the ingredients that the reaction will use. You can define as many as you like within a reaction.

[REAGENT:<name>:<quantity>:<item token>:<material token>][...modifiers...]
* ''[[#Reagent name|name]]'': The name of the reagent, local to the reaction.
* ''[[#Quantity|quantity]]'': The amount of the item that will be used in the reaction.
* ''[[#Item_token|item token]]'': The type (and subtype) of the item you require.
* ''[[#Material_token|material token]]'': The material the item should be made of.
* ''[[#Modifiers|...modifiers...]]'': Zero or more tokens which further clarify the acceptable types when the item type and material types are insufficient to distinguish them.

==== Name ====

The name field is a small string used to identify the reagent within the reaction. The name is not visible to the player. It is local to the reaction and does not need to be unique across all of the reactions, so you can reuse the same names over and over, although each reagent within the same individual reaction must have a different name.

Most reagents are simply named '''A''', '''B''', and so forth in default reactions, although names such as '''TOOLSTONE''', '''FLUX''', or '''seeds''' will also work equally well. The PRODUCT may make reference to this name – for instance, if a container '''B''' is specified as a reagent, PRODUCT_TO_CONTAINER:B specifies that container.

==== Quantity ====

How many or how much of this reagent the reaction requires. For most item types this is just the number of them required. However, some other item types─specifically bars, cloth, thread, globs, liquids, powder, and sheets of paper or parchment─instead use numbers representing the size of the material within one (or more) of these items. For example, while REAGENT:A:'''''10''''':'''''TOY''''':NONE:NONE:NONE is ten unique, solid toy items, REAGENT:A:'''''10''''':'''''THREAD''''':NONE:NONE:NONE is an extremely tiny portion of a random spool of thread. One can see which items have what size quantities in the description of the [[Reaction#PRODUCT_DIMENSION|PRODUCT_DIMENSION]] token.

If one of the reagents is in a stack, or the reaction is only using a fraction of the amount of a sized item, the reaction will consume the entire stack, or as much of the sized item as possible, and multiply the product accordingly. This behaviour can be controlled using the [[Reaction#MAX_MULTIPLIER|MAX_MULTIPLIER]] token.

==== Item token ====

[[Item token]]s are of the form ITEM_TYPE:ITEM_SUBTYPE.

The ITEM_TYPE is the category of item you require; WEAPON, TOY or SKIN_TANNED, for example.

The ITEM_SUBTYPE is name of the exact item that you require. Examples are ITEM_WEAPON_SPEAR or ITEM_TOY_PUZZLEBOX. Some items, like quivers or backpacks, or chunks of stone or metal, have no subtype and only require the item token to be filled in; so if you're asking for those you should set the subtype to NONE. Subtypes are defined within the local raw data files and their exact names can be referenced by looking at the corresponding file.

For reagents, the item token can also be set to ANY_RAW_MATERIAL:NONE (to permit BAR, BOULDER, POWDER_MISC, or GLOB) or ANY_CRAFT:NONE (to permit FIGURINE, AMULET, SCEPTER, CROWN, RING, EARRING, or BRACELET). Internally, these special values are both converted to NONE:NONE and merely set special modifiers (similar to [BUILDMAT])—they cannot be used in any other context.

For backwards compatibility, reagents can also accept "METAL_ORE:metal_id" in place of both the item and material tokens—this is equivalent to using the reagent BOULDER:NONE:NONE:NONE with the modifier [METAL_ORE:metal_id] (see below).

When no item type is specified (as in NONE:NONE), workers will not be able to find otherwise eligible items if they are inside of barrels (at least when reagents are PLANT or PLANT_GROWTH type). This is likely a bug.

==== Material token ====

[[Material token]]s come in several forms. For most reagents, this will typically be INORGANIC:MATERIAL_ID or NONE:NONE (to allow multiple materials using other modifier tokens).

Some reactions will allow the player to select specific materials after creating the job (or in [[Reaction#material_token_2|some cases]], armor size from the product), by clicking on the magnifying glass icon next to the job in the workshop queue. To permit this behaviour in your reaction, the reagent materials must be specified as follows:
{| {{prettytable}}
|- bgcolor="#dddddd"
! Item Type
! Material
! Notes
|-
| style="vertical-align: top"| BAR BLOCKS BOULDER ROUGH SMALLGEM || style="vertical-align: top"| INORGANIC:NONE || style="vertical-align: top"| These all appear as "stone" in the material selection menu, and list all inorganic materials regardless of any material modifier tokens, eg. [ITEMS_METAL]. BAR and BLOCKS made of organic materials, and BOULDER made of clay, are excluded.
|-
| style="vertical-align: top"| SKIN_TANNED or WOOD || style="vertical-align: top"| NONE:NONE ||
|-
| style="vertical-align: top"| Other Item Types || style="vertical-align: top"| NONE:NONE || style="vertical-align: top"| These will appear if a material modifier token other than [ANY_LEATHER_MATERIAL] is included.
|}

==== Modifiers ====

Reagents may also have extra tokens added on, following the REAGENT token, in order to modify their behaviour.

Generally speaking, if you set a field in a reagent to NONE, the reaction won't discriminate when it comes to that particular field. For example, if you require a BOULDER reagent but leave the material as NONE:NONE, it will grab any available BOULDER-type item regardless of material. Modifiers can then be used to restrict this to only certain broad classes of materials.

The following is a list of all known reagent modifiers:

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Arguments
! Description
|-
| style="vertical-align: top"| ANY_BONE_MATERIAL
|
| Reagent material must have the [BONE] token.
|-
| style="vertical-align: top"| ANY_GEM_MATERIAL
|
| Reagent material must have the [IS_GEM] token.
|-
| style="vertical-align: top"| ANY_HORN_MATERIAL
|
| Reagent material must have the [HORN] token.
|-
| style="vertical-align: top"| ANY_LEATHER_MATERIAL
|
| Reagent material must have the [LEATHER] token.
|-
| style="vertical-align: top"| ANY_PEARL_MATERIAL
|
| Reagent material must have the [PEARL] token.
|-
| style="vertical-align: top"| ANY_PLANT_MATERIAL
|
| Reagent material must be subordinate to a PLANT object.
|-
| style="vertical-align: top"| ANY_SHELL_MATERIAL
|
| Reagent material must have the [SHELL] token.
|-
| style="vertical-align: top"| ANY_SILK_MATERIAL
|
| Reagent material must have the [SILK] token.
|-
| style="vertical-align: top"| ANY_SOAP_MATERIAL
|
| Reagent material must have the [SOAP] token.
|-
| style="vertical-align: top"| ANY_STONE_MATERIAL
|
| Reagent material must have the [IS_STONE] token.
|-
| style="vertical-align: top"| ANY_STRAND_TISSUE
|
| Reagent is made of a tissue having TISSUE_SHAPE:STRANDS, intended for matching hair and wool. Must be used with USE_BODY_COMPONENT.
|-
| style="vertical-align: top"| ANY_TOOTH_MATERIAL
|
| Reagent material must have the [TOOTH] token.
|-
| style="vertical-align: top"| ANY_WOOD_MATERIAL
|
| Reagent material must have the [WOOD] token.
|-
| style="vertical-align: top"| ANY_YARN_MATERIAL
|
| Reagent material must have the [YARN] token.
|-
| style="vertical-align: top"| BUILDMAT
|
| Reagent must be a general [[building material]] - BAR, BLOCKS, BOULDER, or WOOD.
|-
| style="vertical-align: top"| CAN_USE_ARTIFACT
|
| Reagent can be an Artifact. Using [PRESERVE_REAGENT] with this is strongly advised.
|-
| style="vertical-align: top"| CONTAINS
| style="vertical-align: top"|
* [[#Reagent name|Reagent name]]
| Reagent is a container that holds the specified reagent (where ''Reagent name'' is the locally-defined name of the reagent).
|-
| style="vertical-align: top"| CONTAINS_LYE
|
| Reagent must be a BARREL or TOOL which contains at least one item of type LIQUID_MISC made of LYE. Use of this token is discouraged, as it does not work with buckets (instead, use [CONTAINS:lye] — note the colon — and a corresponding lye reagent [REAGENT:lye:150:LIQUID_MISC:NONE:LYE]).
|-
| style="vertical-align: top"| DOES_NOT_ABSORB
|
| Reagent material must have ABSORPTION:0
|-
| style="vertical-align: top"| DOES_NOT_DETERMINE_PRODUCT_AMOUNT
|
| Reagent quantity is ignored for the purposes of producing extra outputs. Typically used for containers so that [[stack]]s of reagents will correctly produce additional outputs.
|-
| style="vertical-align: top"| EMPTY
|
| If the reagent is a container, it must be empty.
|-
| style="vertical-align: top"| FIRE_BUILD_SAFE
|
| Reagent material must be solid and stable at temperatures approaching 11000. Only works with items of type BAR, BLOCKS, BOULDER, WOOD, and ANVIL - all others are considered unsafe.
|-
| style="vertical-align: top"| FOOD_STORAGE_CONTAINER
|
| Reagent is either a BARREL or a TOOL with the FOOD_STORAGE use.
|-
| style="vertical-align: top"| GLASS_MATERIAL
|
| Reagent material must have the IS_GLASS token. All 3 types of [[glass]] have this token hardcoded.
|-
| style="vertical-align: top"| HARD_ITEM_MATERIAL
|
| Reagent material must have the [ITEMS_HARD] token.
|-
| style="vertical-align: top"| HAS_EDGE
|
| Reagent must have an edge.
|-
| style="vertical-align: top"| HAS_ITEM_REACTION_PRODUCT
| style="vertical-align: top"|
* PRODUCT_ID
| Reagent material must have the item reaction product specified by PRODUCT_ID - [[Reaction#Item_reaction_products|see below]] for more details. This can be used interchangeably with HAS_MATERIAL_REACTION_PRODUCT.
|-
| style="vertical-align: top"| HAS_MATERIAL_REACTION_PRODUCT
| style="vertical-align: top"|
* PRODUCT_ID
| Reagent material must have the material reaction product specified by PRODUCT_ID - [[Reaction#Material_reaction_products|see below]] for more details.
|-
| style="vertical-align: top"| HAS_TOOL_USE
| style="vertical-align: top"|
* [[Tool token#TOOL_USE|TOOL_USE]] value
| Reagent must be a [[tool]] with the specific TOOL_USE value. The reagent's item type must be TOOL:NONE for this to make any sense.
|-
| style="vertical-align: top"| IS_CRAFTED_ARTIFACT{{verify}}
|
| Reagent item must be an artifact.
|-
| style="vertical-align: top"| IS_DIVINE_MATERIAL
|
| Reagent material must have the [DIVINE] token.
|-
| style="vertical-align: top"| IS_SAND_MATERIAL
|
| Reagent material must have the [SOIL_SAND] token.
|-
| style="vertical-align: top"| MAGMA_BUILD_SAFE
|
| Reagent material must be solid and stable at temperatures approaching 12000. Only works with items of type BAR, BLOCKS, BOULDER, WOOD, and ANVIL - all others are considered unsafe.
|-
| style="vertical-align: top"| METAL_ITEM_MATERIAL
|
| Reagent material must have the [ITEMS_METAL] token.
|-
| style="vertical-align: top"| METAL_ORE
| style="vertical-align: top"|
* Metal ID
| Reagent material must be an ore of the specified metal.
|-
| style="vertical-align: top"| MIN_DIMENSION
| style="vertical-align: top"|
* Integer
| Reagent's item size must be at least as large as ''Integer''. The reagent's item type must be BAR, POWDER_MISC, LIQUID_MISC, DRINK, THREAD, CLOTH, or GLOB for this to work. See [[Reaction#PRODUCT_DIMENSION|PRODUCT_DIMENSION]] below.
|-
| style="vertical-align: top"| NO_EDGE_ALLOWED
|
| Reagent must not have an edge, so must be blunt. Sharp stones (produced using knapping) and most types of weapon/ammo can not be used with this token.
|-
| style="vertical-align: top"| NOT_ARTIFACT{{verify}}
|
| Reagent item must not be an artifact.
|-
| style="vertical-align: top"| NOT_CONTAIN_BARREL_ITEM
|
| If the reagent is a container, it must not contain [[lye]] or [[milk]]. Not necessary if specifying [EMPTY].
|-
| style="vertical-align: top"| NOT_ENGRAVED
|
| Reagent can not be engraved. For example, a memorial slab can not be engraved.
|-
| style="vertical-align: top"| NOT_IMPROVED
|
| Reagent has not been decorated.
|-
| style="vertical-align: top"| NOT_PRESSED
|
| Reagent must not be in the SOLID_PRESSED state.
|-
| style="vertical-align: top"| NOT_WEB
|
| Reagent must be collected (to distinguish silk thread from webs). Only makes sense for items of type THREAD.
|-
| style="vertical-align: top"| ON_GROUND
|
| Reagent must be on the ground. Grabs from stockpiles. Does not grab from inventories (workshops, wagon) and causes infinite gathering for reactions in workshop.
|-
| style="vertical-align: top"| POTASHABLE (Deprecated)
|
| Alias for [CONTAINS_LYE].
|-
| style="vertical-align: top"| PRESERVE_REAGENT
|
| Reagent is not destroyed, which is the normal effect, at the completion of the reaction. Typically used for containers.
|-
| style="vertical-align: top"| REACTION_CLASS
| style="vertical-align: top"|
* CLASS_ID
| Reagent material must have the reaction class specified by CLASS_ID - [[Reaction#Reaction_classes|see below]] for more details.
|-
| style="vertical-align: top"| UNROTTEN
|
| Reagent must not be rotten, mainly for organic materials.
|-
| style="vertical-align: top"| USE_BODY_COMPONENT
|
| Reagent must be a body part (CORPSE or CORPSEPIECE). Must be used even if your reagent item type is CORPSE or CORPSEPIECE, otherwise it will match any item.
|-
| style="vertical-align: top"| WEB_ONLY
|
| Reagent must be undisturbed (to distinguish silk thread from webs). Only makes sense for items of type THREAD.
|-
| style="vertical-align: top"| WORTHLESS_STONE_ONLY
|
| Reagent material must be non-[[economic]].
|-
| style="vertical-align: top"| WOVEN_ITEM
|
| Reagent must be a clothing item made of a woven material, ie. plant, silk, or yarn cloth.
|}

=== Products ===

Products are the end product of the reaction. A reaction can have as many products as it likes.

Products are almost identical to reagents, except that they do not need to be named, can't have fields undefined, and don't use the quantity field to determine the product size. Instead, the token [PRODUCT_DIMENSION:X] is tacked on after the PRODUCT token, determining the size of the product.

Products can be produced directly to a container using the [PRODUCT_TO_CONTAINER:''name''] token, where the ''name'' is the [[#Reagent name|name]] of a reagent. This requires the reagent to have the [PRESERVE_REAGENT] token.

Restating this in the above style, we have:
[PRODUCT:<probability>:<quantity>:<item token>:<material token>][...modifiers...]

==== Probability ====

The percentage chance the product will be produced when the reaction is completed. Must be an integer.

==== Quantity ====

Determines how many of the product will be produced. For the item types AMMO, REMAINS, MEAT, FISH, FISH_RAW, PLANT, PLANT_GROWTH, DRINK, CHEESE, LIQUID_MISC, COIN, and EGG, the resulting items will be created as a single [[stack]], while all other item types will produce multiple individual items.

If a reaction can take stacks of input items, then it will attempt to perform the reaction enough times to consume as many full sets of reagents as it can—for example, if a reaction "1 piece of meat + 2 pieces of fish -> 3 pieces of cheese" is given a stack of 5 meat and 5 fish, it will produce 6 pieces of cheese and leave 3 meat and 1 fish behind. Using the token DOES_NOT_DETERMINE_PRODUCT_AMOUNT allows a reagent to be excluded from this calculation - for example, with the reaction "1 plant + 1 barrel -> 5 alcohol (into barrel)", using this on the barrel allows the reaction to be performed as "5 plant + 1 barrel -> 25 alcohol" instead of "5 plant + 5 barrel -> 25 alcohol".

==== Item token ====

The [[item token]] and subtype of the item you produce.

If your item has an [[Reaction#Item reaction products|item reaction product]] and you want the item type and material to be derived from one of the reagents, you can use GET_ITEM_DATA_FROM_REAGENT:reagent:REACTION_PRODUCT_ID in place of both the item token ''and'' the material token (see next section). You can also specify GET_ITEM_DATA_FROM_REAGENT:reagent:NONE in order to make a direct copy of the source item, though this will not work for complex items such as corpses or prepared meals.

For products, this can also be set to CRAFTS:NONE to produce up to three random [[craft]] items. This value cannot be used in any other context.

==== Material token ====

A [[material token]] describing what the product will be made of.

If you want the product's material to be derived from one of the reagents, you can use GET_MATERIAL_FROM_REAGENT:reagent:NONE in place of the material token in order to directly use the reagent's own material; if the reagent has a [[Reaction#Material_reaction_products|material reaction product]] defined, you can use GET_MATERIAL_FROM_REAGENT:reagent:REACTION_PRODUCT_ID to use that.

Similarly to choosing material types for a reagent, if the item product is armor/clothing, and has the appropriate [[Entity_token#Available_resources|armor token]] in the entity file, you will be able to choose the armor/clothing size for different creatures by clicking the magnifying glass of the workshop task. However, this will only work if the product material is [[Modding pitfalls#My_custom_armor.2Fclothing_reaction_won.27t_let_user_choose_size|cloth leather or certain metals]], and the item is also recognized by the related vanilla workshop reaction{{verify}}.

==== Product modifiers ====

Zero or more tokens which further set the properties or disposition of the resulting product item.

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Arguments
! Description
|-
| style="vertical-align: top"| FORCE_EDGE
|
| Product is given a sharp edge. Used for knapping.
|-
| style="vertical-align: top"| PRODUCT_PASTE
|
| Product is created in the SOLID_PASTE state.
|-
| style="vertical-align: top"| PRODUCT_PRESSED
|
| Product is created in the SOLID_PRESSED state.
|-
| style="vertical-align: top"| PRODUCT_DIMENSION
| style="vertical-align: top"|
* Integer
| Specifies the dimension of the product for those items that use dimensions. For items of type BAR, DRINK, GLOB, LIQUID_MISC, and POWDER_MISC, one item is dimension 150; one item of CLOTH or SHEET is dimension 10000; and one item of THREAD is dimension 15000. Has no effect on any other item types. Note: this is not the actual [[storage]] volume of the product, which is hard-coded by the item token.
|-
| style="vertical-align: top"| PRODUCT_TO_CONTAINER
| style="vertical-align: top"|
* [[#Reagent name|Name]]
| Places the product in a container; ''Name'' must be the name of a reagent with the [PRESERVE_REAGENT] token and a container item type.
|-
| style="vertical-align: top"| PRODUCT_TOKEN
| style="vertical-align: top"|
* [[#Reagent name|Name]]
| Allows the product to be referred to by the given name for the purpose of being passed down as and argument in other tokens, in the same fashion as reagent names.
|-
| style="vertical-align: top"| TRANSFER_ARTIFACT_STATUS
|
| style="vertical-align: top"| Transfers artifact status from the reagent to the product.
|}

=== Improvements ===

Improvements are applied to existing reagents. A reaction can have as many improvements as it likes.

Restating this in the above style, we have:
[IMPROVEMENT:<probability>:<reagent name>:<improvement type>:<material token>]

==== Probability ====
The percentage chance the improvement will be applied to the reagent when the reaction is completed.

==== Reagent name ====
The [[#Reagent name|name]] of the reagent that will be improved. In order to be meaningful, this reagent must have [PRESERVE_REAGENT].

==== Improvement type ====
The following improvement types can be used:

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Description
|-
| COVERED
| Item is encrusted/studded/decorated with <material>.
|-
| GLAZED
| Item is glazed with <material>.
|-
| RINGS_HANGING
| Item is adorned with hanging rings of <material>.
|-
| BANDS
| Item is encircled with bands of <material>.
|-
| SPIKES
| Item menaces with spikes of <material>.
|-
| PAGES
| Adds pages to a [[book]].
|-
| SPECIFIC
| With subtype ROLLERS, adds rollers of <material> to a [[scroll]]; with subtype HANDLE, adds a handle of <material> to an item; with subtype TRACTION_BENCH_CHAIN or TRACTION_BENCH_ROPE adds a chain or rope of <material> to an item.
|}

All other item improvement tokens (ART_IMAGE, ITEMSPECIFIC, THREAD, CLOTH, SEWN_IMAGE, and ILLUSTRATION) are ignored.

==== Material token ====

A [[material token]] describing what the decoration will be made of.

If you want the product's material to be derived from one of the reagents, and the reagent has a [[Reaction#Material_reaction_products|material reaction product]] defined, you can use GET_MATERIAL_FROM_REAGENT:reagent:REACTION_PRODUCT_ID in place of the material token. You can also specify GET_MATERIAL_FROM_REAGENT:reagent:NONE in order to directly use the reagent's own material.

=== Other tokens ===

==== Fuel ====

The FUEL token means that the reaction requires coke or charcoal to be performed. Fuel is not needed when the reaction is performed at a magma workshop (a [[magma kiln]], [[magma smelter]], or any custom building having [NEEDS_MAGMA]).

==== Skill ====

The [[Skill token|skill tokens]] determine what skill the reaction requires and trains; also how quickly skill is gained, how quickly those skill gains raise attributes, and how skill level affects the quality of the reaction product.

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Arguments
! Description
|-
| style="vertical-align: top"| SKILL
| style="vertical-align: top"|
* [[Skill token]]
| (Optional) This identifies the skill required to carry out the reaction and is trained when the reaction is performed. Only one skill may be specified; if multiple skill tokens are defined only the last will be used. A reaction with no product will yield no experience gain. A reaction with no SKILL token will complete in a default amount of time.
|-
| style="vertical-align: top"| SKILL_IP
| style="vertical-align: top"|
* Integer
| (Optional, requires SKILL token) This adjusts the amount of skill gained each time the reaction is carried out. The default value is 30; higher values increase the amount of skill gain.
|-
| style="vertical-align: top"| ATTRIBUTE_IP
| style="vertical-align: top"|
* Integer
| (Optional, requires SKILL token) This adjusts the amount of [[Attribute|attribute]] gain that skill gain from this reaction results in. The default value is 10; higher values increase the amount of attribute gain.
|-
| style="vertical-align: top"| SKILL_ROLL_RANGE
| style="vertical-align: top"|
* Range
* Multiplier
| (Optional, requires SKILL token) This changes how much skill level affects the quality of the reaction product. The default is [SKILL_ROLL_RANGE:11:5]. The ''range'' is the base "die roll" and the ''multiplier'' determines how much the dwarf's skill can affect the reaction; the skill roll is random(range) + random((skill level * multipler)/2 + 1) + random((skill level * multipler)/2 + 1), where random(x) gives a random number from 0 to x-1, inclusive (which also means that the minimum for the range is 1). The higher result on the roll, the better. Both numbers can be lowered to make the skill check harder. For example, with the default values a dwarf who is proficient in a skill has a skill level of 5; their roll will be random(11)+random(13)+random(13), meaning this dwarf can roll anywhere from 0 to 34; similarly, unskilled dwarves can roll 0 to 10 while legendary+0 (skill 15) dwarves can roll 0 to 84. If this is changed to [SKILL_ROLL_RANGE:1:8], then instead a proficient dwarf will have random(1)+random(21)+random(21), giving a roll of 0 to 40, with unskilled dwarves always rolling 0 and legendary dwarves going all the way up to 120.

As a consequence, increasing the multiplier will always make legendary dwarves more effective, even if base roll is reduced to its minimum of 1, with the default going up to 84 for default and 90 for [SKILL_ROLL_RANGE:1:6].
|}

==== Max multiplier ====

The [MAX_MULTIPLIER:<#>] token specifies how many times to do the reaction. This can be used to limit stacked reagent use to the specified quantity instead of the whole stack.

==== Automatic ====

The AUTOMATIC token means that the reaction will be queued automatically if the reaction reagents are all present.

This token only works with jobs performed at a [[kiln]], [[smelter]], [[tanner's shop]], [[kitchen]], or custom workshop, and [[standing orders]] allow you to limit which ones trigger; custom reactions performed at a [[quern]], [[millstone]]{{verify}}, [[still]]{{verify}} or [[craftsdwarf's workshop]]{{verify}} cannot be made automatic.

==== Adventure mode enabled ====

The ADVENTURE_MODE_ENABLED token means that this version of the reaction can be used by the wanderers of Adventure Mode without needing to also give the dwarves at home in a fortress access to it. When using this token, it will be allowed for adventurers of any race, without editing entity files. This token does not prevent Fortress Mode usage assuming the reaction also has a usable building assigned and is a {{token|PERMITTED_REACTION|entity}} within the entity file.

==== Description ====

This feature is exclusive to Classic Mode, as no description window pops up when mousing over reactions in workshops in Premium.

The [DESCRIPTION:<string>] token provides a text description of the reaction when it is highlighted in the building UI. Multiple DESCRIPTION tokens can be defined in a reaction, and each will appear on a new line. The pop-up box that contains the description is limited to 325 characters total. Alternatively, this token can reference a DESCRIPTION token in an existing tool definition by replacing ''string'' with USE_TOOL:<ITEM_SUBTYPE>; or an existing instrument definition with USE_INSTRUMENT:<ITEM_SUBTYPE>.

== Reaction classes and products ==

When you're doing things like tanning hides or brewing alcohol, having separate reactions for every single possible raw material is unwieldy and terrible. However, you can let the reaction itself ask the material for details and process them all with the same reaction. There are three types of tags to dictate this behavior.

=== Reaction classes ===

The simplest token is the reaction class. If it is tacked on a material, a reaction can limit reagents to only those materials that have the specified arbitrary [REACTION_CLASS:whatever] identifier.

We want a reaction that smelts iron and flux into pig iron. However, there are a half-dozen different stones that count as flux. Instead of clogging up the smelter job menu with six nearly identical reactions that all take in either dolomite or limestone or marble for the same result, we use a reaction class.

[REACTION:PIG_IRON_MAKING]
[NAME:make pig iron bars]
[BUILDING:SMELTER:NONE]
[REAGENT:A:150:BAR:NO_SUBTYPE:METAL:IRON]
[REAGENT:B:1:BOULDER:NO_SUBTYPE:NONE:NONE]'''[REACTION_CLASS:FLUX]'''
[REAGENT:C:150:BAR:NO_SUBTYPE:COAL:NO_MATGLOSS]
[PRODUCT:100:1:BAR:NO_SUBTYPE:METAL:PIG_IRON][PRODUCT_DIMENSION:150]
[FUEL]
[SKILL:SMELT]

Note how reagent B asks for "NONE:NONE" as its material. This means "boulders of any kind as long as they have the reaction class named FLUX". Stuff like calcite, here:

[INORGANIC:CALCITE]
[USE_MATERIAL_TEMPLATE:STONE_TEMPLATE]
[STATE_NAME_ADJ:ALL_SOLID:calcite][DISPLAY_COLOR:7:7:1][TILE:'"']
'''[REACTION_CLASS:FLUX]'''
[ENVIRONMENT_SPEC:LIMESTONE:CLUSTER_SMALL:100]
[ENVIRONMENT_SPEC:MARBLE:CLUSTER_SMALL:100]
[MATERIAL_VALUE:2]
[IS_STONE]
[MELTING_POINT:12902]
[SOLID_DENSITY:2930]

The label itself can be absolutely anything. It's only used to find a match between the material and the reaction. Note that some reaction classes have special meanings to the game itself—notably, the [[site finder]] knows that "FLUX" should be connected to the "Flux stone" filter.

=== Material reaction products ===

But what if it's not all the same what materials the members of the reaction class put out? If a tanner starts working on a bear pelt, a horse hide, some dragon scales and a section of human skin, surely they all can't produce generic boot leather! No, the reaction must get the chance to ask the "reaction class" what the reagent should turn out as. We will declare a material reaction product.

[REACTION:TAN_A_HIDE]
[NAME:tan a hide]
[BUILDING:TANNER:CUSTOM_T]
[REAGENT:flaps of skin:1:NONE:NONE:NONE:NONE][USE_BODY_COMPONENT][UNROTTEN]
'''[HAS_MATERIAL_REACTION_PRODUCT:TAN_MAT]'''
[PRODUCT:100:1:SKIN_TANNED:NONE:'''GET_MATERIAL_FROM_REAGENT:flaps of skin:TAN_MAT''']
[SKILL:TANNER]
[AUTOMATIC]

Where you'd usually have some fresh bodypart with the TAN_MAT reaction class produce some generic SKIN_TANNED, this goes further. Instead of declaring a material, the spool of pattern-ready tailoring leather (SKIN_TANNED) now comes out as whatever the skin flaps' material reaction product (named TAN_MAT) says in the material's definition (GET_MATERIAL_FROM_REAGENT). And what does it say?

[MATERIAL_TEMPLATE:SKIN_TEMPLATE]
[STATE_COLOR:ALL_SOLID:GRAY]
[STATE_NAME:ALL_SOLID:skin]
[STATE_ADJ:ALL_SOLID:skin]
...
[ABSORPTION:100]
'''[MATERIAL_REACTION_PRODUCT:TAN_MAT:LOCAL_CREATURE_MAT:LEATHER]'''
[IMPLIES_ANIMAL_KILL]
[ROTS]

It says that the caller of the TAN_MAT hook always comes out as the LEATHER of whatever creature the skin has been peeled off of (LOCAL_CREATURE_MAT). For example, skin taken from a butchered dog would be turned into dog leather. Change the SKIN_TEMPLATE MATERIAL_REACTION_PRODUCT to TAN_MAT:INORGANIC:GOLD instead and your tanner turns into Midas. Use your imagination.

If the item you're creating should be made of the ''same'' material as the raw material you're using (e.g. if you're carving a log into a training spear), you can specify "NONE" instead of the MATERIAL_REACTION_PRODUCT code:

[REACTION:MAKE WOODEN TRAINING SPEAR]
[NAME:make wooden training spear]
[BUILDING:CARPENTER:NONE]
[REAGENT:log:1:WOOD:NONE:NONE:NONE][ANY_PLANT_MATERIAL]
[PRODUCT:100:1:WEAPON:ITEM_WEAPON_SPEAR_TRAINING:'''GET_MATERIAL_FROM_REAGENT:log:NONE''']
[SKILL:CARPENTRY]

As with reaction classes, some MATERIAL_REACTION_PRODUCT identifiers have special meanings to the game itself - notably, the [[site finder]] knows that "FIRED_MAT" should be connected to the "Clay" filter, and "CHEESE_MAT" is used when making [[cheese]] from [[milk]].

=== Item reaction products ===

Item reaction products are an even more powerful form of the above. Where material reaction products can only affect what type of stuff the predestined end product is made of, item reaction products can decide the entire end result ahead of time. Item AND material.

Let's assume for a moment that we're completely tired of leather earrings and hair crowns. We want a crafting reaction that takes cloth and only produces things that make sense.

[REACTION:TAILOR_THE_BEST_THING]
[NAME:weave something that makes sense]
[BUILDING:CRAFTSMAN]
[REAGENT:woven fabric:1:CLOTH:NONE:NONE:NONE]
'''[HAS_ITEM_REACTION_PRODUCT:BEST_OPTION]'''
[PRODUCT:100:1:'''GET_ITEM_DATA_FROM_REAGENT:woven fabric:BEST_OPTION''']
[SKILL:CLOTHIER]

Now we need to come up with the counterpart tags in the materials. Hmmm... cotton is thin and soft, so it makes pretty good undergarments. An undershirt, maybe?

[PLANT:COTTON] Gossypium hirsutum / sp.
[NAME:cotton plant][NAME_PLURAL:cotton plants][ADJ:cotton plant]
[USE_MATERIAL_TEMPLATE:STRUCTURAL:STRUCTURAL_PLANT_TEMPLATE]
[BASIC_MAT:LOCAL_PLANT_MAT:STRUCTURAL]
[DRY][BIOME:ANY_TROPICAL]
[VALUE:2]
...
[USE_MATERIAL_TEMPLATE:THREAD:THREAD_PLANT_TEMPLATE]
[MATERIAL_VALUE:2]
'''[ITEM_REACTION_PRODUCT:BEST_OPTION:ARMOR:ITEM_ARMOR_TUNIC:LOCAL_PLANT_MAT:THREAD]'''
...

Then jute fabric. Isn't that burlap? And what's about the only thing they make from burlap?

[PLANT:JUTE] Corchorus capsularis / Corchorus olitorius
[NAME:jute plant][NAME_PLURAL:jute plants][ADJ:jute plant]
[USE_MATERIAL_TEMPLATE:STRUCTURAL:STRUCTURAL_PLANT_TEMPLATE]
[BASIC_MAT:LOCAL_PLANT_MAT:STRUCTURAL]
[DRY][BIOME:ANY_TROPICAL]
[VALUE:2]
...
[USE_MATERIAL_TEMPLATE:THREAD:THREAD_PLANT_TEMPLATE]
[MATERIAL_VALUE:2]
'''[ITEM_REACTION_PRODUCT:BEST_OPTION:BAG:NONE:LOCAL_PLANT_MAT:THREAD]'''
...

Sacks, of course! Wait, how about silk?

[CREATURE:SPIDER_CAVE]
[DESCRIPTION:A tiny underground bug, sought after for its thread.]
[NAME:cave spider:cave spiders:cave spider]
...
[USE_MATERIAL_TEMPLATE:SILK:SILK_TEMPLATE]
'''[ITEM_REACTION_PRODUCT:BEST_OPTION:PANTS:ITEM_PANTS_THONG:LOCAL_CREATURE_MAT:SILK]'''
...

This goes on for as long as you let it. The ITEM_REACTION_PRODUCT declares the identifier and then the item and material with subtypes, just like a normal reaction's product line would.

Do note that MATERIAL_REACTION_PRODUCT and ITEM_REACTION_PRODUCT use the same IDs, so you cannot have both a material and item reaction product of the same name. Also, though you cannot use GET_ITEM_DATA_FROM_REAGENT with a MATERIAL_REACTION_PRODUCT (there'd be no item type information), you ''can'' use GET_MATERIAL_FROM_REAGENT on an ITEM_REACTION_PRODUCT (in case you want to force your own item type).

== Reactions and world generation ==

There are several things to keep in mind when you're adding reactions to a game that already exists.

* Most entity changes require a regen, but adding PERMITTED_REACTION tokens for reactions that existed at the time of world generation to the entity file in the save directory do not.
* Adding reactions to the raws in a save directory requires you to regen the world.
* You can alter an existing reaction in any way you like without regenning the world, so long as you don't alter the reaction identifier.

== Full token list ==

For the sake of convenience and readability, this is a complete compilation of the previously listed reaction tokens in alphabetical order:

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

|-
| style="vertical-align: top"| {{text anchor|ADVENTURE_MODE_ENABLED}}
|
|
| style="vertical-align: top"| This version of the reaction can be used by the wanderers of Adventure Mode without needing to also give the dwarves at home in a fortress access to it. When using this token, it will be allowed for adventurers of any race, without editing entity files. This token does not prevent Fortress Mode usage if assigned to a workshop and the civilization has access.

|-
| style="vertical-align: top"| {{text anchor|FORTRESS_MODE_ENABLED}}{{version|Lua beta}}
|
|
| style="vertical-align: top"| This reaction can be accessed when playing as any civilization in [[Fortress mode]], regardless of {{token|PERMITTED_REACTION|e}}. Particularly useful for compatibility or [[Lua scripting]].

|-
| style="vertical-align: top"| {{text anchor|WORLDGEN_ENABLED}}{{version|Lua beta}}
|
|
| style="vertical-align: top"| Adds the materials provided by the reaction to all civilizations, regardless of {{token|PERMITTED_REACTION|e}}.

|-
| style="vertical-align: top"| {{text anchor|ANY_BONE_MATERIAL}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent material must have the [BONE] token.

|-
| style="vertical-align: top"| {{text anchor|ANY_GEM_MATERIAL}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent material must have the [IS_GEM] token.

|-
| style="vertical-align: top"| {{text anchor|ANY_HORN_MATERIAL}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent material must have the [HORN] token.

|-
| style="vertical-align: top"| {{text anchor|ANY_LEATHER_MATERIAL}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent material must have the [LEATHER] token.

|-
| style="vertical-align: top"| {{text anchor|ANY_PEARL_MATERIAL}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent material must have the [PEARL] token.

|-
| style="vertical-align: top"| {{text anchor|ANY_PLANT_MATERIAL}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent material must be subordinate to a PLANT object.

|-
| style="vertical-align: top"| {{text anchor|ANY_SHELL_MATERIAL}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent material must have the [SHELL] token.

|-
| style="vertical-align: top"| {{text anchor|ANY_SILK_MATERIAL}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent material must have the [SILK] token.

|-
| style="vertical-align: top"| {{text anchor|ANY_SOAP_MATERIAL}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent material must have the [SOAP] token.

|-
| style="vertical-align: top"| {{text anchor|ANY_STONE_MATERIAL}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent material must have the [IS_STONE] token.

|-
| style="vertical-align: top"| {{text anchor|ANY_STRAND_TISSUE}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent is made of a tissue having [TISSUE_SHAPE:STRANDS], intended for matching hair and wool. Must be used with [USE_BODY_COMPONENT].

|-
| style="vertical-align: top"| {{text anchor|ANY_TOOTH_MATERIAL}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent material must have the [TOOTH] token.

|-
| style="vertical-align: top"| {{text anchor|ANY_WOOD_MATERIAL}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent material must have the [WOOD] token.

|-
| style="vertical-align: top"| {{text anchor|ANY_YARN_MATERIAL}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent material must have the [YARN] token.

|-
| style="vertical-align: top"| {{text anchor|ATTRIBUTE_IP}}
| style="vertical-align: top"|
* Integer
| style="vertical-align: top"| Skill modifier
| style="vertical-align: top"| Amount of attribute gain given per skill improvement. Default is 10.

|-
| style="vertical-align: top"| {{text anchor|AUTOMATIC}}
|
|
| style="vertical-align: top"| The reaction will be queued automatically if the reaction reagents are all present.

|-
| style="vertical-align: top"| {{text anchor|BAG}} (Deprecated)
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent has to be a bag. Intended to be used with an item type of BOX, to prevent chests, coffers, and other containers from being used instead. Deprecated as of Version 0.50.01 in favor of BAG:NONE [[item token]].

|-
| style="vertical-align: top"| {{text anchor|BUILDING}}
| style="vertical-align: top"|
* [[#building name|Building name]]
* [[#building key|In-building reaction hotkey]]
|
| style="vertical-align: top"| Sets the building that the reaction will be performed in, and the button used to queue the reaction once that building's menu is accessed in-game.

|-
| style="vertical-align: top"| {{text anchor|BUILDMAT}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent is able to be used to build structures (Boulders, Wood, Blocks, Bars).

|-
| style="vertical-align: top"| {{text anchor|CAN_USE_ARTIFACT}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent can be an Artifact. Using [PRESERVE_REAGENT] with this is strongly advised.

|-
| style="vertical-align: top"| {{text anchor|CAN_USE_HOSPITAL_RESERVED}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Allows the reagent to be an item that is otherwise reserved for use by a [[healthcare|hospital]].

|-
| style="vertical-align: top"| {{text anchor|CAN_USE_LOCATION_RESERVED}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Allows the reagent to be an item that is otherwise reserved for use by a [[locations|location]].

|-
| style="vertical-align: top"| {{text anchor|CATEGORY}}
| style="vertical-align: top"|
* Category ID
|
| style="vertical-align: top"| Puts the reaction in a category. Categories are custom submenus for reaction menus. The category ID is a unique identifier for the category. It is only used in the raws, and will not appear in the game.

If you're defining multiple categories within the same reaction - for example, if you intend the reaction to be nested two deep, and haven't yet defined the super-category - the ''last'' CATEGORY token within the reaction definition is the one that the reaction will appear in.

|-
| style="vertical-align: top"| {{text anchor|CATEGORY_NAME}}
| style="vertical-align: top"|
* String
| style="vertical-align: top"| Category
| style="vertical-align: top"| The name of the category as displayed in-game.

|-
| style="vertical-align: top"| {{text anchor|CATEGORY_DESCRIPTION}}
| style="vertical-align: top"|
* String
| style="vertical-align: top"| Category
| style="vertical-align: top"| If present, when the category is highlighted in a building menu, this string will be displayed in the Helpful Hint box.

|-
| style="vertical-align: top"| {{text anchor|CATEGORY_PARENT}}
| style="vertical-align: top"|
* Category ID
| style="vertical-align: top"| Category
| style="vertical-align: top"| If present, this category will be a submenu of the indicated category, rather than a submenu of the reaction's building.

|-
| style="vertical-align: top"| {{text anchor|CATEGORY_KEY}}
| style="vertical-align: top"|
* Hotkey
| style="vertical-align: top"| Category
| style="vertical-align: top"| If present, this category can be selected from its parent menu (whether a building or a parent category) using the given hotkey while playing in Classic mode.

|-
| style="vertical-align: top"| {{text anchor|CONTAINS}}
| style="vertical-align: top"|
* [[#Reagent name|Reagent name]]
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent is a container that holds the specified reagent.

|-
| style="vertical-align: top"| {{text anchor|CONTAINS_LYE}} (Deprecated)
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| If the reagent is a container, it must contain LYE. No longer used - instead, use one reagent for the LYE itself and another reagent with [CONTAINS:lye_reagent].

|-
| style="vertical-align: top"| {{text anchor|DESCRIPTION}}
| style="vertical-align: top"|
* String
|
| style="vertical-align: top"| A description of the reaction that appears when it is highlighted in the building UI. ''String'' can also be replaced with a reference to existing DESCRIPTION tokens in tools (using USE_TOOL:<tool_id>) or musical instruments (using USE_TOOL:<instrument_id>).

|-
| style="vertical-align: top"| {{text anchor|DOES_NOT_ABSORB}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent material must have [ABSORPTION:0].

|-
| style="vertical-align: top"| {{text anchor|DOES_NOT_DETERMINE_PRODUCT_AMOUNT}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Performing a reaction with large [[stack]]s of inputs can allow multiple sets of outputs to be produced. Setting this flag causes the reagent to be ignored in this process - for example, with the reaction "1 plant + 1 barrel -> 5 alcohol (into barrel)", using this on the barrel allows the reaction to be performed as "5 plant + 1 barrel -> 25 alcohol" instead of "5 plant + 5 barrel -> 25 alcohol".

|-
| style="vertical-align: top"| {{text anchor|EMPTY}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| If the reagent is a container, it must be empty.

|-
| style="vertical-align: top"| {{text anchor|FIRE_BUILD_SAFE}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent must be considered [[fire-safe]] (stable [[temperature]] below {{ct|11000}}) - i.e. not wood, and not coal.

|-
| style="vertical-align: top"| {{text anchor|FORCE_EDGE}}
|
| style="vertical-align: top"| Product modifier
| style="vertical-align: top"| Product is given a sharp edge. Used for knapping.

|-
| style="vertical-align: top"| {{text anchor|FOOD_STORAGE_CONTAINER}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent must be a barrel or any non-absorbing tool with [TOOL_USE:FOOD_STORAGE].

|-
| style="vertical-align: top"| {{text anchor|FUEL}}
|
|
| style="vertical-align: top"| Requires that the reaction either use up a unit of coal or charcoal or else be performed at a magma workshop.

|-
| style="vertical-align: top"| {{text anchor|GLASS_MATERIAL}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent material has [IS_GLASS].

|-
| style="vertical-align: top"| {{text anchor|HAS_EDGE}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent must be sharpened (used for carving).

|-
| style="vertical-align: top"| {{text anchor|HAS_ITEM_REACTION_PRODUCT}}
| style="vertical-align: top"|
* PRODUCT_ID (custom)
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Similar to HAS_MATERIAL_REACTION_PRODUCT, but requires the reagents material to have a matching ITEM_REACTION_PRODUCT entry.

|-
| style="vertical-align: top"| {{text anchor|HAS_MATERIAL_REACTION_PRODUCT}}
| style="vertical-align: top"|
* PRODUCT_ID (custom)
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Similar to REACTION_CLASS, but requires the reagents material to have a matching [[Material definition token|MATERIAL_REACTION_PRODUCT]] entry. Intended for reactions which transform one class of material into another, such as skin->leather and fat->tallow.

|-
| style="vertical-align: top"| {{text anchor|HAS_TOOL_USE}}
| style="vertical-align: top"|
* [[Tool token#TOOL_USE|TOOL_USE value]]
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent must be a [[tool]] with the specific TOOL_USE value. The reagents item type must be TOOL:NONE for this to make any sense.

|-
| style="vertical-align: top"| {{text anchor|HAS_WRITING_IMPROVEMENT}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent must contain writing.

|-
| style="vertical-align: top"| {{text anchor|IMPROVEMENT}}
| style="vertical-align: top"|
* Probability
* [[#Reagent name|Reagent name]]
* Improvement type
* Material Token
|
| style="vertical-align: top"| Applies an improvement to the named reagent. Only meaningful if said reagent has [PRESERVE_REAGENT]. Improvement types include BANDS, COVERED, GLAZED, PAGES, RINGS_HANGING, and SPIKES

|-
| style="vertical-align: top"| {{text anchor|IS_CRAFTED_ARTIFACT}}{{verify}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent item must be an artifact.

|-
| style="vertical-align: top"| {{text anchor|IS_DIVINE_MATERIAL}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent material must have the [DIVINE] token.

|-
| style="vertical-align: top"| {{text anchor|MAGMA_BUILD_SAFE}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Currently broken - Reagent must be considered [[magma-safe]] (stable [[temperature]] below {{ct|12000}}).

|-
| style="vertical-align: top"| {{text anchor|MAX_MULTIPLIER}}
| style="vertical-align: top"|
* Integer
|
| style="vertical-align: top"| Sets the maximum number of times a reaction is allowed to run when using stacked reagents. This can be used to ensure that the reaction doesn't repeat until the entire stack is depleted.

|-
| style="vertical-align: top"| {{text anchor|METAL_ORE}}
| style="vertical-align: top"|
* Inorganic material
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent material must be an ore of the specified metal.

|-
| style="vertical-align: top"| {{text anchor|MIN_DIMENSION}}
| style="vertical-align: top"|
* Integer
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Requires that the reagent have a size of at least ''integer''. Only effective with BAR, POWDER_MISC, LIQUID_MISC, DRINK, THREAD, CLOTH, and GLOB items.

|-
| style="vertical-align: top"| {{text anchor|NAME}}
| style="vertical-align: top"|
* [[#name|Name]]
|
| style="vertical-align: top"| Defines the name used by the reaction in-game.

|-
| style="vertical-align: top"| {{text anchor|NO_EDGE_ALLOWED}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent must not have an edge, so must be blunt. Sharp stones (produced using knapping) and most types of weapon/ammo can not be used with this token.

|-
| style="vertical-align: top"| {{text anchor|NOT_ARTIFACT}}{{verify}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent item must not be an artifact.

|-
| style="vertical-align: top"| {{text anchor|NOT_CONTAIN_BARREL_ITEM}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| If the reagent is a Barrel, it must not contain an item that has to reside in a barrel. Barrel items appear to be lye and milk. Alcohol appears to be covered as part of [EMPTY]. A reaction which places an item in a barrel should probably have both tags.

|-
| style="vertical-align: top"| {{text anchor|NOT_ENGRAVED}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent has not been engraved i.e. a blank memorial slab.
|-
| style="vertical-align: top"| {{text anchor|NOT_IMPROVED}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent has not been decorated.

|-
| style="vertical-align: top"| {{text anchor|NOT_PRESSED}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent must not be in the SOLID_PRESSED state.

|-
| style="vertical-align: top"| {{text anchor|NOT_WEB}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent must be "collected" - used with THREAD:NONE to exclude webs.

|-
| style="vertical-align: top"| {{text anchor|ON_GROUND}}
|
| style="vertical-align: top"| Reagent modifier
| Reagent must be on the ground. Grabs from stockpiles. Does not grab from bins in stockpiles, nor inventories (workshops, wagon). Causes infinite collection of items if reaction is in workshop, as reagents are no longer on ground when brought to workshop. Untested in adventure mode; possibly more useful for adv. mode reactions.

|-
| style="vertical-align: top"| {{text anchor|POTASHABLE}} (Deprecated)
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Alias for [CONTAINS_LYE].

|-
| style="vertical-align: top"| {{text anchor|PRESERVE_REAGENT}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent is not destroyed, which is the normal effect, at the completion of the reaction. Typically used for containers.

|-
| style="vertical-align: top"| {{text anchor|PRODUCT}}
| style="vertical-align: top"|
*Probability of success (%)
*Quantity
*Item token:subtype
*Material token:subtype
|
| style="vertical-align: top"| Defines a thing that comes out of the reaction. GET_MATERIAL_FROM_REAGENT and GET_ITEM_DATA_FROM_REAGENT can be used to defer the choice of material and/or item to the appropriate tag in a given reagent's material - the former comes in place of the material token, the latter replaces both the item and material tokens. See above for detailed information on how the hooks work.

|-
| style="vertical-align: top"| {{text anchor|PRODUCT_DIMENSION}}
| style="vertical-align: top"|
* Size
| style="vertical-align: top"| Product modifier
| style="vertical-align: top"| Specifies the amount of the product for those items that use dimension. For items of type BAR, DRINK, GLOB, LIQUID_MISC, and POWDER_MISC, one item is dimension 150; one item of CLOTH or SHEET is dimension 10000; and one item of THREAD is dimension 15000. Has no effect on any other item types. Note: this is not the actual [[storage]] volume of the product, which is hard-coded by the item token.

|-
| style="vertical-align: top"| {{text anchor|PRODUCT_PASTE}}
|
| style="vertical-align: top"| Product modifier
| style="vertical-align: top"| Product is created in the SOLID_PASTE state.

|-
| style="vertical-align: top"| {{text anchor|PRODUCT_PRESSED}}
|
| style="vertical-align: top"| Product modifier
| style="vertical-align: top"| Product is created in the SOLID_PRESSED state.

|-
| style="vertical-align: top"| {{text anchor|PRODUCT_TO_CONTAINER}}
| style="vertical-align: top"|
* [[#Reagent name|Reagent name]]
| style="vertical-align: top"| Product modifier
| style="vertical-align: top"| Places the product in a container; reagent name must be the name of a reagent with the [PRESERVE_REAGENT] token and a container item type.

|-
| style="vertical-align: top"| {{text anchor|PRODUCT_TOKEN}}
| style="vertical-align: top"|
* Name
| style="vertical-align: top"| Product modifier
| style="vertical-align: top"| Allows the product to be referred to by the given name, for the purpose of being passed down as argument in other tokens in the same fashion as reagent names.

|-
| style="vertical-align: top"| {{text anchor|REACTION}}
| style="vertical-align: top"|
* Identifier
|
| style="vertical-align: top"| Defines a new reaction.

|-
| style="vertical-align: top"| {{text anchor|REACTION_CLASS}}
| style="vertical-align: top"|
* CLASS_ID (custom)
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Requires the reagent's material to have a matching [[Material definition token|REACTION_CLASS]] entry. Intended for reactions which accept a variety of materials but where the input material does not determine the output material, such as FLUX (for making pig iron and steel) and GYPSUM (for producing plaster powder).

|-
| style="vertical-align: top"| {{text anchor|REAGENT}}
| style="vertical-align: top"|
* [[#Reagent name|Reagent name]]
* [[#quantity|Quantity]]
* [[Item token]]
* [[Material token]]
|
| style="vertical-align: top"| Specifies a given reagent as an input for a reaction.

|-
| style="vertical-align: top"| {{text anchor|SKILL}}
| style="vertical-align: top"|
* [[Skill token]]
|
| style="vertical-align: top"| Skill used by the reaction.

|-
| style="vertical-align: top"| {{text anchor|SKILL_IP}}
| style="vertical-align: top"|
* Integer
| style="vertical-align: top"| Skill modifier
| style="vertical-align: top"| Amount of skill given per product made. Default is 30.

|-
| style="vertical-align: top"| {{text anchor|SKILL_ROLL_RANGE}}
| style="vertical-align: top"|
* Range
* Multiplier
| style="vertical-align: top"| Skill modifier
| style="vertical-align: top"| Determines how [[skill]] level affects [[quality]] of the reaction product. The skill roll is random(range) + random((skill level * multipler)/2 + 1) + random((skill level * multipler)/2 + 1). random(x) returns a number between 0 and x-1, so range is always 1 or more. The default is 11. The default multiplier is 5. Higher skill rolls give better results.

|-
| style="vertical-align: top"| {{text anchor|TRANSFER_ARTIFACT_STATUS}}
|
| style="vertical-align: top"| Product modifier
| style="vertical-align: top"| Transfers artifact status from the reagent to the product.

|-
| style="vertical-align: top"| {{text anchor|UNROTTEN}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent must not be rotten, mainly for organic materials.

|-
| style="vertical-align: top"| {{text anchor|USE_BODY_COMPONENT}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent material must come off a creature's body.

|-
| style="vertical-align: top"| {{text anchor|WEB_ONLY}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent must be "undisturbed" - used with THREAD:NONE to gather webs.

|-
| style="vertical-align: top"| {{text anchor|WORTHLESS_STONE_ONLY}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent is not made of an economic stone.

|-
| style="vertical-align: top"| {{text anchor|WOVEN_ITEM}}
|
| style="vertical-align: top"| Reagent modifier
| style="vertical-align: top"| Reagent material must be a woven material, eg. plant cloth, silk, yarn. This ''excludes'' CLOTH or THREAD items.

|}

== Examples ==
:''Main articles: [[Reaction examples]]''

{{Category|Modding}}
{{Category|Tokens}}
[[ru:Reaction]]

Plant token

2023-08-20T22:51:30Z

Tekkud: Minor addition to prior BASIC_MAT edit.

{{Quality|Unrated}}
{{av}}
{{Modding}}
The <code>[OBJECT:PLANT]</code> [[token]] begins the definition of a [[plant]] [[raw file]]. Following this, each new plant definition begins with the <code>[PLANT:plant_ID]</code> token, where plant_ID is a unique identifier for the plant, and that plant's properties are then defined using the tokens listed below.

__TOC__
{{clear}}

==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 plant's name as seen in-game.

|-
| {{text anchor|NAME_PLURAL}}
|
*name
| The plural form of the plant's 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. Must be followed with [[material definition token]]s defining the material's properties.

|-
| {{text anchor|USE_MATERIAL}}
|
*material_name
*local_material
| Starts defining a new local plant material with the given name and using the properties of another local plant material. May be followed with material definition tokens to further define its properties or change the properties imported from the local plant material.

|-
| {{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. May be followed with material definition tokens to further define its properties or change the properties imported from the template material.

|-
| {{text anchor|BASIC_MAT}}
|
* [[Material token|material]]
| Sets the basic material of the plant. This defines what is harvested when the plant itself, rather than a growth, is picked. 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. The only way to remove the plant's basic material entry (e.g. "soybean plant") from every stockpile category is to remove this token, but this will cause problems with farming the plant in a farm plot and harvesting the whole wild plant if that's possible.
|}

==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 are 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. Plants with valid [[biome token]]s and [FREQUENCY:0] will not grow in the wild, but will still be available for entity use and farm plots.

|-
| {{text anchor|WET}}
|
| Restricts the plant to grow near natural water features. A plant with [WET] may be very common or very rare in an area, depending on how many water features that area has. Note that they will not grow next to dwarf-filled channels, since it explicitly checks if the tile type is "River", "River Slope", "River Source", "Waterfall" (used back in 40d for underground rivers), "Brook", "Murky Pool", or "Murky Pool Slope".

|-
| {{text anchor|DRY}}
|
| Allows the plant to grow away from water features.

|-
| {{text anchor|BIOME}}
|
*biome
| What [[biome token|biome]] this plant appears in.

|}

==Growth tokens==
These tokens are used for all plants and specify growths growing on a plant.

Edible or otherwise usable growths should have [STOCKPILE_PLANT_GROWTH] in their [[material definition token|material definitions]] for proper stockpiling. This also lets them be collected from plant gathering and farming jobs.

{| {{prettytable}}
|- style='background-color:#ddd'
! width="20%" | Token
! width="20%" | Arguments
! width="60%" | Description

|-
| {{text anchor|GROWTH}}
|
*name
| Defines a plant growth. Takes the below tokens as arguments.

|-
| {{text anchor|GROWTH_NAME}}
|
*singular
*plural (STP for standard plural)
| The name of a plant growth.

|-
| {{text anchor|GROWTH_ITEM}}
|
* [[item token]]
* [[material token]]
| Specifies what item this growth is and what it is made of. Generally, the item type should be PLANT_GROWTH:NONE.

|-
| {{text anchor|GROWTH_HOST_TILE}}
|
*plant part
| Specifies on which part of the plant or tree the growth appears, usually for multi-tile [[tree]]s. Valid tokens are:
*TWIGS
*BRANCHES_AND_TWIGS / LIGHT_BRANCHES_AND_TWIGS
*BRANCHES / LIGHT_BRANCHES
*ALL_BRANCHES_AND_TWIGS
*HEAVY_BRANCHES / DIRECTED_BRANCHES
*HEAVY_BRANCHES_AND_TRUNK / DIRECTED_BRANCHES_AND_TRUNK
*TRUNK
*ROOTS
*CAP
*SAPLING

|-
| {{text anchor|GROWTH_TRUNK_HEIGHT_PERC}}
|
*percent (0-100+)
*integer
| Controls the height on the trunk above which the growth begins to appear. The first value is the percent of the trunk height where the growth begins appearing: 0 will cause growths to appear along the entire trunk above the first tile; 100 will cause growths to appear only at the topmost trunk tile. Can be larger than 100 for trees that have growths on branches extending higher than the trunk.

The second integer currently ''must'' be -1, but might be intended to control whether it counts height starting from the bottom or top.

|-
| {{text anchor|GROWTH_DENSITY}}
|
*integer
| Currently has no effect.

|-
| {{text anchor|GROWTH_TIMING}}
|
*[[time]] start:end (0-403200)
| Specifies at which part of the year the growth appears. Default is all year round.

A single growth can only have one GROWTH_TIMING tag. If multiple are declared, the last one will be used. To make a growth appear multiple times during the year, you need to create a different growth for every GROWTH_TIMING interval. By using the same material for all of the duplicate growths, all of them will be stockpiled together and be eligible for the same reactions. Edible/brewable growths will have separate entries in the kitchen menu, though.

There is no known way to declare a growth timing that lasts from winter into spring. Including numbers below 0 or above 403200 in the range will make the growth available at all times, as though you hadn't defined a growth timing at all. So will including a range for which the start time is later than the end time.

This has no effect on farmed growths; all eligible growths that have [STOCKPILE_PLANT_GROWTH] in their materials will be harvested, regardless of if they are currently within their growth timing or not.

|-
| {{text anchor|GROWTH_PRINT}}
|
*overworld tile
*item tile
*color
*time (0-403200) start:end, ALL, or NONE
*priority
| Specifies the appearance of the growth. Can be specified more than once, for example for autumn leaves. Transitions between different timing periods will happen gradually over the course of 2000 ticks. Priority seems to control what to display when there would be multiple symbols on a tile.{{verify}}

The GROWTH_PRINT tile will only be displayed when the growth in question is actually present, even if its timing parameter is ALL.

|-
| {{text anchor|GROWTH_HAS_SEED}}
|
| The growth drops a seed if eaten raw.

|-
| {{text anchor|GROWTH_DROPS_OFF}}
|
| Growths drop from the plant, producing a cloud of items which fall on the ground, which [[herbalist]]s can collect.
|-
| {{text anchor|GROWTH_DROPS_OFF_NO_CLOUD}}
|
| Growths drop collectable items from the plant without producing item clouds.

|}

==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]] or NONE
| Makes the plant into a [[tree]]. Cutting down the tree will yield logs made of this material. Setting the material to NONE will give no wood from this tree.

|-
| {{text anchor|TRUNK_NAME}}
|
*name
| What the trunk of the tree is named.

|-
| {{text anchor|MAX_TRUNK_HEIGHT}}
|
*1-8
| The maximum z-level height of a mature tree's trunk, starting from about two z-levels above ground and going up.

|-
| {{text anchor|MAX_TRUNK_DIAMETER}}
|
*1-3
| Upper limit of trunk thickness, in tiles. Counted separately for all branching trunks. Has a geometric effect on log yield.

|-
| {{text anchor|TRUNK_PERIOD}}
|
*integer
| The number of years the trunk takes to grow one Z-level upward.

|-
| {{text anchor|TRUNK_WIDTH_PERIOD}}
|
*integer
| The number of years the trunk takes to grow another tile wider.

|-
| {{text anchor|LIGHT_BRANCHES_NAME}}
|
*name
| What thin branches of the tree are named.

|-
| {{text anchor|BRANCH_DENSITY}} / {{text anchor|LIGHT_BRANCHES_DENSITY}}
|
*integer
| How dense the branches grow on this tree.

|-
| {{text anchor|BRANCH_RADIUS}} / {{text anchor|LIGHT_BRANCH_RADIUS}}
|
*integer
| The radius to which branches can reach. Appears to never reach further than seven tiles from the centre. Does not depend on the trunk branching amount or where trunks are. The values used in the game go from 0-3. Higher values than that can cause crashes. {{bug|10419}}

|-
| {{text anchor|HEAVY_BRANCHES_NAME}} / {{text anchor|DIRECTED_BRANCHES_NAME}}
|
*name
| What thick branches of the tree are named.

|-
| {{text anchor|HEAVY_BRANCH_DENSITY}} / {{text anchor|DIRECTED_BRANCH_DENSITY}}
|
*integer
| Similar to [[Plant_token#BRANCH_DENSITY|BRANCH_DENSITY]] for thick branches.

|-
| {{text anchor|HEAVY_BRANCH_RADIUS}} / {{text anchor|DIRECTED_BRANCH_RADIUS}}
|
*integer
| Similar as [[Plant_token#BRANCH_RADIUS|BRANCH_DENSITY]] for thick branches. Values outside 0-3 can cause crashes. {{bug|10419}}

|-
| {{text anchor|TRUNK_BRANCHING}}
|
*integer
| How much the trunk branches out. 0 makes the trunk straight.

|-
| {{text anchor|ROOT_NAME}} / {{text anchor|ROOTS_NAME}}
|
*name
| What the roots of the tree are named.

|-
| {{text anchor|ROOT_DENSITY}}
|
*integer
| Density of the root growth.

|-
| {{text anchor|ROOT_RADIUS}}
|
*integer
| How wide the roots reach out.

|-
| {{text anchor|TWIGS_NAME}}
|
*name
| What the twigs of the tree are named.

|-
| {{text anchor|TWIGS_SIDE_BRANCHES}}
|
*boolean (0 or 1)
| Twigs appear on the side of branches. Defaults to 1.

|-
| {{text anchor|TWIGS_ABOVE_BRANCHES}}
|
*boolean (0 or 1)
| Twigs appear above branches. Defaults to 1.

|-
| {{text anchor|TWIGS_BELOW_BRANCHES}}
|
*boolean (0 or 1)
| Twigs appear below branches. Defaults to 0.

|-
| {{text anchor|TWIGS_SIDE_HEAVY_BRANCHES}}
|
*boolean (0 or 1)
| Twigs appear on the side of heavy branches. Defaults to 0.

|-
| {{text anchor|TWIGS_ABOVE_HEAVY_BRANCHES}}
|
*boolean (0 or 1)
| Twigs appear above heavy branches. Defaults to 0.

|-
| {{text anchor|TWIGS_BELOW_HEAVY_BRANCHES}}
|
*boolean (0 or 1)
| Twigs appear below heavy branches. Defaults to 0.

|-
| {{text anchor|TWIGS_SIDE_TRUNK}}
|
*boolean (0 or 1)
| Twigs appear on the side of the trunk. Defaults to 0.

|-
| {{text anchor|TWIGS_ABOVE_TRUNK}}
|
*boolean (0 or 1)
| Twigs appear above the trunk. Defaults to 0.

|-
| {{text anchor|TWIGS_BELOW_TRUNK}}
|
*boolean (0 or 1)
| Twigs appear below the trunk. Defaults to 0.

|-
| {{text anchor|TREE_HAS_MUSHROOM_CAP}}
|
| The tree has a rounded cap-hood like a giant mushroom. This severely stunts a tree's maximum height - see the [https://dwarffortress.mantishub.io/view.php?id=7313#c26413 bug report.]

|-
| {{text anchor|CAP_NAME}}
|
*name
| What this mushroom-cap is called. Only makes sense with TREE_HAS_MUSHROOM_CAP.

|-
| {{text anchor|CAP_PERIOD}}
|
*integer
| Similar to the other PERIOD tags, influences the rate of the mushroom cap growth. Only makes sense with TREE_HAS_MUSHROOM_CAP.

|-
| {{text anchor|CAP_RADIUS}}
|
*integer
| The radius of a mushroom cap. Only makes sense with TREE_HAS_MUSHROOM_CAP.

|-
| {{text anchor|STANDARD_TILE_NAMES}}
|
| Uses the standard names for the tree components (roots, trunk, branches, etc.)

|-
| {{text anchor|TREE_TILE}}
|
*tile
| The tile used for trees of this type on the world map. Defaults to 24 (↑).

|-
| {{text anchor|DEAD_TREE_TILE}}
|
*tile
| The tile used for (un)dead trees and deciduous trees (generally in winter) 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 sapling of this tree will drown once the water on its tile reaches this level. 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]".

|}

==Shrub tokens==
These tokens are used for non-grass, non-tree plants.

{| {{prettytable}}
|- style='background-color:#ddd'
! width="20%" | Token
! width="20%" | Arguments
! width="60%" | Description

|-
| {{text anchor|SPRING}}, {{text anchor|SUMMER}}, {{text anchor|AUTUMN}}, {{text anchor|WINTER}}
|
| Allows the plant to grow in farm plots during the given season.

If the plant is a surface plant, allows it to grow in the wild during this season; wild surface plants without this token will disappear at the beginning of the season. Underground plants grow wild in all seasons, regardless of their season tokens.

|-
| {{text anchor|GROWDUR}}
|
*time
| How long the plant takes to grow to harvest in a farm plot. Unit hundreds of ticks, See [[Time]]. There are 1008 GROWDUR units in a season. Defaults to 300.

|-
| {{text anchor|VALUE}}
|
*value
| Has no known effect. Previously set the value of the harvested plant.

|-
| {{text anchor|PICKED_TILE}}
|
*tile
| The tile used when the plant is harvested whole, or is ready to be picked from a farm plot. May either be a cp437 tile number, or a character between single quotes. See [[Main:character table|character table]]. Defaults to 231 (τ).

|-
| {{text anchor|DEAD_PICKED_TILE}}
|
*tile
| The tile used when a plant harvested whole has wilted. Defaults to 169 (⌐).

|-
| {{text anchor|SHRUB_TILE}}
|
*tile
| The tile used to represent this plant when it is wild, alive, and has no growths. Defaults to 34 (").

|-
| {{text anchor|DEAD_SHRUB_TILE}}
|
*tile
| The tile used to represent this plant when it is dead in the wild. Defaults to 34 (").

|-
| {{text anchor|CLUSTERSIZE}}
|
*size
| The maximum stack size collected when gathered via herbalism (possibly also from farm plots?). Defaults to 5.

|-
| {{text anchor|PICKED_COLOR}}
|
*foreground
*background
*bright
| The color of the plant when it has been picked whole, or when it is ready for harvest in a farm plot. Defaults to 2:0:0 (dark green).

|-
| {{text anchor|DEAD_PICKED_COLOR}}
|
*foreground
*background
*bright
| The [[color]] of the plant when it has been picked whole, but has wilted. Defaults to 0:0:1 (dark gray).

|-
| {{text anchor|SHRUB_COLOR}}
|
*foreground
*background
*bright
| The [[color]] of the plant when it is alive, wild, and has no growths. Defaults to 2:0:0 (dark green).

|-
| {{text anchor|DEAD_SHRUB_COLOR}}
|
*foreground
*background
*bright
|The [[color]] of the plant when it is dead in the wild. Defaults to 6:0:0 (brown).

|-
| {{text anchor|SHRUB_DROWN_LEVEL}}
|
*depth
| The shrub will drown once the water on its tile reaches this level. Defaults to 4.

|-
| {{text anchor|DRINK}}
|
* [[Material token|material]]
| Names a [[alcohol|drink]] made from the plant, allowing it to be used in entity resources. Previously also permitted brewing the plant into [[alcohol]] made of this material. Now, a MATERIAL_REACTION_PRODUCT of type DRINK_MAT should be used on the proper plant material.

|-
| {{text anchor|MILL}}
|
* [[Material token|material]]
| Permits milling the plant at a [[quern]] or [[millstone]] into a powder made of this material and allows its use in entity resources. Said material should have [POWDER_MISC_PLANT] to permit proper stockpiling. This token makes the whole plant harvestable regardless of which material is designated for milling. For plants with millable ''growths'', use only MATERIAL_REACTION_PRODUCT or ITEM_REACTION_PRODUCT tokens to define the milling products.

|-
| {{text anchor|THREAD}}
|
* [[Material token|material]]
| Permits processing the plant at a [[farmer's workshop]] to yield threads made of this material and allows its use in entity resources. 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|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. This allows animals to graze on it, and prevents it and its growths from being picked by herbalists. (Grass growths can still be picked in adventure mode, however.)

|-
| {{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}}
[[ru:Plant token]]

Plant token

2023-08-20T22:49:05Z

Tekkud: Added information to BASIC_MAT and MILL tokens.

{{Quality|Unrated}}
{{av}}
{{Modding}}
The <code>[OBJECT:PLANT]</code> [[token]] begins the definition of a [[plant]] [[raw file]]. Following this, each new plant definition begins with the <code>[PLANT:plant_ID]</code> token, where plant_ID is a unique identifier for the plant, and that plant's properties are then defined using the tokens listed below.

__TOC__
{{clear}}

==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 plant's name as seen in-game.

|-
| {{text anchor|NAME_PLURAL}}
|
*name
| The plural form of the plant's 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. Must be followed with [[material definition token]]s defining the material's properties.

|-
| {{text anchor|USE_MATERIAL}}
|
*material_name
*local_material
| Starts defining a new local plant material with the given name and using the properties of another local plant material. May be followed with material definition tokens to further define its properties or change the properties imported from the local plant material.

|-
| {{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. May be followed with material definition tokens to further define its properties or change the properties imported from the template material.

|-
| {{text anchor|BASIC_MAT}}
|
* [[Material token|material]]
| Sets the basic material of the plant. This defines what is harvested when the plant itself, rather than a growth, is picked. 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. The only way to remove the plant's basic material entry (e.g. "soybean plant") from every stockpile category is to remove this token, but this will cause problems with farming the plant in a farm plot.
|}

==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 are 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. Plants with valid [[biome token]]s and [FREQUENCY:0] will not grow in the wild, but will still be available for entity use and farm plots.

|-
| {{text anchor|WET}}
|
| Restricts the plant to grow near natural water features. A plant with [WET] may be very common or very rare in an area, depending on how many water features that area has. Note that they will not grow next to dwarf-filled channels, since it explicitly checks if the tile type is "River", "River Slope", "River Source", "Waterfall" (used back in 40d for underground rivers), "Brook", "Murky Pool", or "Murky Pool Slope".

|-
| {{text anchor|DRY}}
|
| Allows the plant to grow away from water features.

|-
| {{text anchor|BIOME}}
|
*biome
| What [[biome token|biome]] this plant appears in.

|}

==Growth tokens==
These tokens are used for all plants and specify growths growing on a plant.

Edible or otherwise usable growths should have [STOCKPILE_PLANT_GROWTH] in their [[material definition token|material definitions]] for proper stockpiling. This also lets them be collected from plant gathering and farming jobs.

{| {{prettytable}}
|- style='background-color:#ddd'
! width="20%" | Token
! width="20%" | Arguments
! width="60%" | Description

|-
| {{text anchor|GROWTH}}
|
*name
| Defines a plant growth. Takes the below tokens as arguments.

|-
| {{text anchor|GROWTH_NAME}}
|
*singular
*plural (STP for standard plural)
| The name of a plant growth.

|-
| {{text anchor|GROWTH_ITEM}}
|
* [[item token]]
* [[material token]]
| Specifies what item this growth is and what it is made of. Generally, the item type should be PLANT_GROWTH:NONE.

|-
| {{text anchor|GROWTH_HOST_TILE}}
|
*plant part
| Specifies on which part of the plant or tree the growth appears, usually for multi-tile [[tree]]s. Valid tokens are:
*TWIGS
*BRANCHES_AND_TWIGS / LIGHT_BRANCHES_AND_TWIGS
*BRANCHES / LIGHT_BRANCHES
*ALL_BRANCHES_AND_TWIGS
*HEAVY_BRANCHES / DIRECTED_BRANCHES
*HEAVY_BRANCHES_AND_TRUNK / DIRECTED_BRANCHES_AND_TRUNK
*TRUNK
*ROOTS
*CAP
*SAPLING

|-
| {{text anchor|GROWTH_TRUNK_HEIGHT_PERC}}
|
*percent (0-100+)
*integer
| Controls the height on the trunk above which the growth begins to appear. The first value is the percent of the trunk height where the growth begins appearing: 0 will cause growths to appear along the entire trunk above the first tile; 100 will cause growths to appear only at the topmost trunk tile. Can be larger than 100 for trees that have growths on branches extending higher than the trunk.

The second integer currently ''must'' be -1, but might be intended to control whether it counts height starting from the bottom or top.

|-
| {{text anchor|GROWTH_DENSITY}}
|
*integer
| Currently has no effect.

|-
| {{text anchor|GROWTH_TIMING}}
|
*[[time]] start:end (0-403200)
| Specifies at which part of the year the growth appears. Default is all year round.

A single growth can only have one GROWTH_TIMING tag. If multiple are declared, the last one will be used. To make a growth appear multiple times during the year, you need to create a different growth for every GROWTH_TIMING interval. By using the same material for all of the duplicate growths, all of them will be stockpiled together and be eligible for the same reactions. Edible/brewable growths will have separate entries in the kitchen menu, though.

There is no known way to declare a growth timing that lasts from winter into spring. Including numbers below 0 or above 403200 in the range will make the growth available at all times, as though you hadn't defined a growth timing at all. So will including a range for which the start time is later than the end time.

This has no effect on farmed growths; all eligible growths that have [STOCKPILE_PLANT_GROWTH] in their materials will be harvested, regardless of if they are currently within their growth timing or not.

|-
| {{text anchor|GROWTH_PRINT}}
|
*overworld tile
*item tile
*color
*time (0-403200) start:end, ALL, or NONE
*priority
| Specifies the appearance of the growth. Can be specified more than once, for example for autumn leaves. Transitions between different timing periods will happen gradually over the course of 2000 ticks. Priority seems to control what to display when there would be multiple symbols on a tile.{{verify}}

The GROWTH_PRINT tile will only be displayed when the growth in question is actually present, even if its timing parameter is ALL.

|-
| {{text anchor|GROWTH_HAS_SEED}}
|
| The growth drops a seed if eaten raw.

|-
| {{text anchor|GROWTH_DROPS_OFF}}
|
| Growths drop from the plant, producing a cloud of items which fall on the ground, which [[herbalist]]s can collect.
|-
| {{text anchor|GROWTH_DROPS_OFF_NO_CLOUD}}
|
| Growths drop collectable items from the plant without producing item clouds.

|}

==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]] or NONE
| Makes the plant into a [[tree]]. Cutting down the tree will yield logs made of this material. Setting the material to NONE will give no wood from this tree.

|-
| {{text anchor|TRUNK_NAME}}
|
*name
| What the trunk of the tree is named.

|-
| {{text anchor|MAX_TRUNK_HEIGHT}}
|
*1-8
| The maximum z-level height of a mature tree's trunk, starting from about two z-levels above ground and going up.

|-
| {{text anchor|MAX_TRUNK_DIAMETER}}
|
*1-3
| Upper limit of trunk thickness, in tiles. Counted separately for all branching trunks. Has a geometric effect on log yield.

|-
| {{text anchor|TRUNK_PERIOD}}
|
*integer
| The number of years the trunk takes to grow one Z-level upward.

|-
| {{text anchor|TRUNK_WIDTH_PERIOD}}
|
*integer
| The number of years the trunk takes to grow another tile wider.

|-
| {{text anchor|LIGHT_BRANCHES_NAME}}
|
*name
| What thin branches of the tree are named.

|-
| {{text anchor|BRANCH_DENSITY}} / {{text anchor|LIGHT_BRANCHES_DENSITY}}
|
*integer
| How dense the branches grow on this tree.

|-
| {{text anchor|BRANCH_RADIUS}} / {{text anchor|LIGHT_BRANCH_RADIUS}}
|
*integer
| The radius to which branches can reach. Appears to never reach further than seven tiles from the centre. Does not depend on the trunk branching amount or where trunks are. The values used in the game go from 0-3. Higher values than that can cause crashes. {{bug|10419}}

|-
| {{text anchor|HEAVY_BRANCHES_NAME}} / {{text anchor|DIRECTED_BRANCHES_NAME}}
|
*name
| What thick branches of the tree are named.

|-
| {{text anchor|HEAVY_BRANCH_DENSITY}} / {{text anchor|DIRECTED_BRANCH_DENSITY}}
|
*integer
| Similar to [[Plant_token#BRANCH_DENSITY|BRANCH_DENSITY]] for thick branches.

|-
| {{text anchor|HEAVY_BRANCH_RADIUS}} / {{text anchor|DIRECTED_BRANCH_RADIUS}}
|
*integer
| Similar as [[Plant_token#BRANCH_RADIUS|BRANCH_DENSITY]] for thick branches. Values outside 0-3 can cause crashes. {{bug|10419}}

|-
| {{text anchor|TRUNK_BRANCHING}}
|
*integer
| How much the trunk branches out. 0 makes the trunk straight.

|-
| {{text anchor|ROOT_NAME}} / {{text anchor|ROOTS_NAME}}
|
*name
| What the roots of the tree are named.

|-
| {{text anchor|ROOT_DENSITY}}
|
*integer
| Density of the root growth.

|-
| {{text anchor|ROOT_RADIUS}}
|
*integer
| How wide the roots reach out.

|-
| {{text anchor|TWIGS_NAME}}
|
*name
| What the twigs of the tree are named.

|-
| {{text anchor|TWIGS_SIDE_BRANCHES}}
|
*boolean (0 or 1)
| Twigs appear on the side of branches. Defaults to 1.

|-
| {{text anchor|TWIGS_ABOVE_BRANCHES}}
|
*boolean (0 or 1)
| Twigs appear above branches. Defaults to 1.

|-
| {{text anchor|TWIGS_BELOW_BRANCHES}}
|
*boolean (0 or 1)
| Twigs appear below branches. Defaults to 0.

|-
| {{text anchor|TWIGS_SIDE_HEAVY_BRANCHES}}
|
*boolean (0 or 1)
| Twigs appear on the side of heavy branches. Defaults to 0.

|-
| {{text anchor|TWIGS_ABOVE_HEAVY_BRANCHES}}
|
*boolean (0 or 1)
| Twigs appear above heavy branches. Defaults to 0.

|-
| {{text anchor|TWIGS_BELOW_HEAVY_BRANCHES}}
|
*boolean (0 or 1)
| Twigs appear below heavy branches. Defaults to 0.

|-
| {{text anchor|TWIGS_SIDE_TRUNK}}
|
*boolean (0 or 1)
| Twigs appear on the side of the trunk. Defaults to 0.

|-
| {{text anchor|TWIGS_ABOVE_TRUNK}}
|
*boolean (0 or 1)
| Twigs appear above the trunk. Defaults to 0.

|-
| {{text anchor|TWIGS_BELOW_TRUNK}}
|
*boolean (0 or 1)
| Twigs appear below the trunk. Defaults to 0.

|-
| {{text anchor|TREE_HAS_MUSHROOM_CAP}}
|
| The tree has a rounded cap-hood like a giant mushroom. This severely stunts a tree's maximum height - see the [https://dwarffortress.mantishub.io/view.php?id=7313#c26413 bug report.]

|-
| {{text anchor|CAP_NAME}}
|
*name
| What this mushroom-cap is called. Only makes sense with TREE_HAS_MUSHROOM_CAP.

|-
| {{text anchor|CAP_PERIOD}}
|
*integer
| Similar to the other PERIOD tags, influences the rate of the mushroom cap growth. Only makes sense with TREE_HAS_MUSHROOM_CAP.

|-
| {{text anchor|CAP_RADIUS}}
|
*integer
| The radius of a mushroom cap. Only makes sense with TREE_HAS_MUSHROOM_CAP.

|-
| {{text anchor|STANDARD_TILE_NAMES}}
|
| Uses the standard names for the tree components (roots, trunk, branches, etc.)

|-
| {{text anchor|TREE_TILE}}
|
*tile
| The tile used for trees of this type on the world map. Defaults to 24 (↑).

|-
| {{text anchor|DEAD_TREE_TILE}}
|
*tile
| The tile used for (un)dead trees and deciduous trees (generally in winter) 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 sapling of this tree will drown once the water on its tile reaches this level. 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]".

|}

==Shrub tokens==
These tokens are used for non-grass, non-tree plants.

{| {{prettytable}}
|- style='background-color:#ddd'
! width="20%" | Token
! width="20%" | Arguments
! width="60%" | Description

|-
| {{text anchor|SPRING}}, {{text anchor|SUMMER}}, {{text anchor|AUTUMN}}, {{text anchor|WINTER}}
|
| Allows the plant to grow in farm plots during the given season.

If the plant is a surface plant, allows it to grow in the wild during this season; wild surface plants without this token will disappear at the beginning of the season. Underground plants grow wild in all seasons, regardless of their season tokens.

|-
| {{text anchor|GROWDUR}}
|
*time
| How long the plant takes to grow to harvest in a farm plot. Unit hundreds of ticks, See [[Time]]. There are 1008 GROWDUR units in a season. Defaults to 300.

|-
| {{text anchor|VALUE}}
|
*value
| Has no known effect. Previously set the value of the harvested plant.

|-
| {{text anchor|PICKED_TILE}}
|
*tile
| The tile used when the plant is harvested whole, or is ready to be picked from a farm plot. May either be a cp437 tile number, or a character between single quotes. See [[Main:character table|character table]]. Defaults to 231 (τ).

|-
| {{text anchor|DEAD_PICKED_TILE}}
|
*tile
| The tile used when a plant harvested whole has wilted. Defaults to 169 (⌐).

|-
| {{text anchor|SHRUB_TILE}}
|
*tile
| The tile used to represent this plant when it is wild, alive, and has no growths. Defaults to 34 (").

|-
| {{text anchor|DEAD_SHRUB_TILE}}
|
*tile
| The tile used to represent this plant when it is dead in the wild. Defaults to 34 (").

|-
| {{text anchor|CLUSTERSIZE}}
|
*size
| The maximum stack size collected when gathered via herbalism (possibly also from farm plots?). Defaults to 5.

|-
| {{text anchor|PICKED_COLOR}}
|
*foreground
*background
*bright
| The color of the plant when it has been picked whole, or when it is ready for harvest in a farm plot. Defaults to 2:0:0 (dark green).

|-
| {{text anchor|DEAD_PICKED_COLOR}}
|
*foreground
*background
*bright
| The [[color]] of the plant when it has been picked whole, but has wilted. Defaults to 0:0:1 (dark gray).

|-
| {{text anchor|SHRUB_COLOR}}
|
*foreground
*background
*bright
| The [[color]] of the plant when it is alive, wild, and has no growths. Defaults to 2:0:0 (dark green).

|-
| {{text anchor|DEAD_SHRUB_COLOR}}
|
*foreground
*background
*bright
|The [[color]] of the plant when it is dead in the wild. Defaults to 6:0:0 (brown).

|-
| {{text anchor|SHRUB_DROWN_LEVEL}}
|
*depth
| The shrub will drown once the water on its tile reaches this level. Defaults to 4.

|-
| {{text anchor|DRINK}}
|
* [[Material token|material]]
| Names a [[alcohol|drink]] made from the plant, allowing it to be used in entity resources. Previously also permitted brewing the plant into [[alcohol]] made of this material. Now, a MATERIAL_REACTION_PRODUCT of type DRINK_MAT should be used on the proper plant material.

|-
| {{text anchor|MILL}}
|
* [[Material token|material]]
| Permits milling the plant at a [[quern]] or [[millstone]] into a powder made of this material and allows its use in entity resources. Said material should have [POWDER_MISC_PLANT] to permit proper stockpiling. This token makes the whole plant harvestable regardless of which material is designated for milling. For plants with millable ''growths'', use only MATERIAL_REACTION_PRODUCT or ITEM_REACTION_PRODUCT tokens to define the milling products.

|-
| {{text anchor|THREAD}}
|
* [[Material token|material]]
| Permits processing the plant at a [[farmer's workshop]] to yield threads made of this material and allows its use in entity resources. 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|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. This allows animals to graze on it, and prevents it and its growths from being picked by herbalists. (Grass growths can still be picked in adventure mode, however.)

|-
| {{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}}
[[ru:Plant token]]

Bolt

2023-03-25T03:59:47Z

Tekkud: Corrected formatting

{{Quality|Unrated}}{{av}}{{buggy}}
[[File:crossbow_bolts.jpg|thumb|Medieval crossbow bolts.]]

'''Bolts''' are a type of [[ammunition]] used by [[crossbow]]s. They can be made from either [[wood]], [[bone]], or weapons-grade [[metal]]s. As with all non-siege ammo, hunting and military dwarves must be equipped with [[quiver]]s to be able to carry bolts around for shooting.

Wooden and bone bolts are produced in a [[craftsdwarf's workshop]] by a [[wood crafter]] or a [[bone carver]], respectively. Each job will produce a stack of 25 wooden bolts from a single log, or a stack of 5 bone bolts taking a single bone from a stack. Metal bolts are a weapon, not a craft, so require [[Weaponsmith|Weapon''smithing'']] (not Metal''crafting'') and a [[Metalsmith's forge]] or [[Magma forge]], creating a stack of 25 bolts from a single metal bar.

When fired, bolts have a chance of shattering on impact or bouncing off onto the ground as free-laying items. However, depending on [[standing orders]], they may be immediately [[forbidden]] after being fired (to prevent <s>suicidal</s> hauling dwarves from running into active battlefields), and have to be [[reclaim]]ed by the player, either directly or from the [[stocks]] screen.

Given that crossbows have a maximum velocity and maximum force, the weight of bolts is generally irrelevant. Weight does not influence their effectiveness beyond 1333, which is the maximum density above which all bolts have the same inertia. Shear strength is the primary property that matters for bolts; even masterwork wooden bolts bounce harmlessly off copper armor because wood is very, very weak in shear compared to copper, while iron bolts pierce without any issue due to their reasonable strength. Bone bolts are significantly better than wood, but metal bolts are still recommended for military use [http://www.bay12forums.com/smf/index.php?topic=116151.0]. [[Adamantine]] bolts are effective despite their low density - it is offset by their greatly superior sharpness and shear properties, (see [[Weapon#Material|weapon materials]]), which allows adamantine bolts to tear through all metal armors, with the notable exception of adamantine armor itself. When pitted against itself, low-density adamantine bolts deflect 99.99% of the time. As comparison, bolts made out of non-adamantine metals fired at armor of equal or superior strength do not deflect and simply deal converted blunt damage instead of edge damage.

==Masterwork bolts==
As with other items, high-skill dwarves can make masterwork-[[Item quality|quality]] bolts. While they don't care if the bolts are fired and shatter on impact, they do get [[thought|upset]] if a bolt gets carried off the map - say, by a retreating enemy with the bolt stuck in them.

The simplest remedy for this is to simply '''make more bolts''' - a dwarf who has produced hundreds of masterwork bolts will be more annoyed by [[fly|flies]] than the loss of a masterwork. This is because the stress penalty for the loss of a masterwork is divided by the number of remaining masterwork items made by that dwarf (see [[thought]]s for more information).

==Weapon traps==
Bone bolts are not advisable for [[weapon trap]]s as only a stack of 5 will be stored per crossbow, making frequent restocking necessary.

==Bugs==
*If bolts claimed by a squad are forbidden then the squad may not claim new bolts. Instead they become stuck waiting for those bolts, indicated by a yellow bolt icon in the 'equip' menu. In this case, assigning a uniform again (even the same exact uniform that's currently assigned) will force them to find new, available bolts.
*If bolts claimed by a squad are forbidden ''and then made unreachable'', the squad will be unable to select new bolts. In this case, the bolt icon remains red in the 'equip' menu. The player will need to either allow them to acquire the bolts they have claimed or create a new squad.
*Masterwork bolts cause unhappy thoughts when they get carried off the map or melted down{{bug|3169}}. The solution to this is to make more bolts, since the unhappy thought caused by "art defacement" becomes less significant the more masterpieces a dwarf has produced.
*Bolts are not stored in a barracks, despite the tooltip for the 'story squad equipment' icon. Bolts will get dropped wherever the dwarf drops their quiver and promptly hauled to any stockpile where they are allowed.

{{Translation
| dwarven = alåth
| elvish = ene
| goblin = okom
| human = thora
}}

{{gamedata|{{raw|DF2014:item_ammo.txt|ITEM_AMMO|ITEM_AMMO_BOLTS}}}}
{{Weapons}}

{{Category|Ammo}}

Bolt

2023-03-25T03:54:38Z

Tekkud: Edited bugs to bring them up to date with current behaviours. Bin bug was resolved with 50.x, but new equipment bugs were introduced.

{{Quality|Unrated}}{{av}}{{buggy}}
[[File:crossbow_bolts.jpg|thumb|Medieval crossbow bolts.]]

'''Bolts''' are a type of [[ammunition]] used by [[crossbow]]s. They can be made from either [[wood]], [[bone]], or weapons-grade [[metal]]s. As with all non-siege ammo, hunting and military dwarves must be equipped with [[quiver]]s to be able to carry bolts around for shooting.

Wooden and bone bolts are produced in a [[craftsdwarf's workshop]] by a [[wood crafter]] or a [[bone carver]], respectively. Each job will produce a stack of 25 wooden bolts from a single log, or a stack of 5 bone bolts taking a single bone from a stack. Metal bolts are a weapon, not a craft, so require [[Weaponsmith|Weapon''smithing'']] (not Metal''crafting'') and a [[Metalsmith's forge]] or [[Magma forge]], creating a stack of 25 bolts from a single metal bar.

When fired, bolts have a chance of shattering on impact or bouncing off onto the ground as free-laying items. However, depending on [[standing orders]], they may be immediately [[forbidden]] after being fired (to prevent <s>suicidal</s> hauling dwarves from running into active battlefields), and have to be [[reclaim]]ed by the player, either directly or from the [[stocks]] screen.

Given that crossbows have a maximum velocity and maximum force, the weight of bolts is generally irrelevant. Weight does not influence their effectiveness beyond 1333, which is the maximum density above which all bolts have the same inertia. Shear strength is the primary property that matters for bolts; even masterwork wooden bolts bounce harmlessly off copper armor because wood is very, very weak in shear compared to copper, while iron bolts pierce without any issue due to their reasonable strength. Bone bolts are significantly better than wood, but metal bolts are still recommended for military use [http://www.bay12forums.com/smf/index.php?topic=116151.0]. [[Adamantine]] bolts are effective despite their low density - it is offset by their greatly superior sharpness and shear properties, (see [[Weapon#Material|weapon materials]]), which allows adamantine bolts to tear through all metal armors, with the notable exception of adamantine armor itself. When pitted against itself, low-density adamantine bolts deflect 99.99% of the time. As comparison, bolts made out of non-adamantine metals fired at armor of equal or superior strength do not deflect and simply deal converted blunt damage instead of edge damage.

==Masterwork bolts==
As with other items, high-skill dwarves can make masterwork-[[Item quality|quality]] bolts. While they don't care if the bolts are fired and shatter on impact, they do get [[thought|upset]] if a bolt gets carried off the map - say, by a retreating enemy with the bolt stuck in them.

The simplest remedy for this is to simply '''make more bolts''' - a dwarf who has produced hundreds of masterwork bolts will be more annoyed by [[fly|flies]] than the loss of a masterwork. This is because the stress penalty for the loss of a masterwork is divided by the number of remaining masterwork items made by that dwarf (see [[thought]]s for more information).

==Weapon traps==
Bone bolts are not advisable for [[weapon trap]]s as only a stack of 5 will be stored per crossbow, making frequent restocking necessary.

==Bugs==
*If bolts claimed by a squad are forbidden then the squad may not claim new bolts. Instead they become stuck waiting for those bolts, indicated by a yellow bolt icon in the 'equip' menu. In this case, assigning a uniform again (even the same exact uniform that's currently assigned) will force them to find new, available bolts.
*If bolts claimed by a squad are forbidden *and then made unreachable*, the squad will be unable to select new bolts. In this case, the bolt icon remains red in the 'equip' menu. The player will need to either allow them to acquire the bolts they have claimed or create a new squad.
*Masterwork bolts cause unhappy thoughts when they get carried off the map or melted down{{bug|3169}}. The solution to this is to make more bolts, since the unhappy thought caused by "art defacement" becomes less significant the more masterpieces a dwarf has produced.
*Bolts are not stored in a barracks, despite the tooltip for the 'story squad equipment' icon. Bolts will get dropped wherever the dwarf drops their quiver and promptly hauled to any stockpile where they are allowed.

{{Translation
| dwarven = alåth
| elvish = ene
| goblin = okom
| human = thora
}}

{{gamedata|{{raw|DF2014:item_ammo.txt|ITEM_AMMO|ITEM_AMMO_BOLTS}}}}
{{Weapons}}

{{Category|Ammo}}