v50 Steam/Premium information for editors
  • v50 information can now be added to pages in the main namespace. v0.47 information can still be found in the DF2014 namespace. See here for more details on the new versioning policy.
  • Use this page to report any issues related to the migration.
This notice may be cached—the current version can be found here.

Difference between revisions of "v0.31:Reactions"

From Dwarf Fortress Wiki
Jump to navigation Jump to search
 
(107 intermediate revisions by 35 users not shown)
Line 1: Line 1:
 +
{{quality|Fine|09:41, 6 October 2010 (UTC)}}
 
{{av}}
 
{{av}}
  
−
'''Reactions''' are moddable crafting formulas. They can be tweaked and added onto to allow smelting of new metals, alloys, and many other products. They can be assigned to specific [[Entities]] to allow only certain entities to have access to it.
+
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 quite simple to add additional ones.
  
−
Currently, a reaction can only result in an object of base quality.
+
== Reaction differences between modes ==
 +
In [[Fortress mode]], reactions are linked to specific buildings, and must be added to a civilization's [[Entities|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 use it.
  
−
==Reaction Makeup==
+
In [[Adventure mode]], reactions are freely available via x > create, 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.  As of .10, there are several bugs with Adventure mode reactions, chief of which is the fact that you cannot select liquid reagents. <!-- reaction product tag works now, liquids and improvement quality dont -->
−
[REACTION:<REACTION_IDENTIFIER>]
 
−
[NAME:<REACTION_NAME>]
 
−
<... [[#Buildings]] One or more reagent declarations ...>
 
−
  <... [[#Reagents]] Zero or more reagent declarations...>
 
−
<... [[#Products]] Zero or more reagent declarations ...>
 
−
  <... [[#Reaction Modifiers]] Zero or more reagent declarations ...>
 
−
<... [[#Skills]] Zero or more skill declarations ...>
 
  
−
'''<REACTION_IDENTIFER>''' - Refers to a unique identifier for the reaction (Used in Entity Raws to allow an Enitity to make use of the reaction.
+
Prior to version 31.10, a reaction could only result in an object of base [[quality]].  However, in .10 items produced via reactions have been observed to have quality modifiers.  The way skill factors into them has yet is the same as for normal items{{version|0.31.21}}.
  
−
'''<REACTION_NAME>''' - String displayed in the building for the reaction.
+
==Anatomy of a reaction==
  
−
==Buildings==
+
Reactions are found within reaction_x files (such as reaction_smelter or reaction_other).  Generally speaking they adhere to the following structure:
−
Each reaction requires a building to be declared for it to be used at.
 
  
−
[BUILDING:<BUILDING_IDENTIFIER>:<BUILDING_KEY>]
+
  [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>]
 +
      [AUTOMATIC]
 +
      [ADVENTURE_MODE_ENABLED]
 +
* ''[[#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.
 +
* ''[[#automatic|automatic]]'': (optional) If present, the reaction will automatically be enqueued whenever it can possibly be performed.
 +
* ''[[#adventure mode|adventure mode]]'': (optional) If present, the reaction is used by the player in Adventure mode instead.
  
−
'''<BUILDING_IDENTIFIER''' - The building at which this reaction can be used. NOTE: SMELTER, KILN, KITCHEN and TANNER seem to be the only non-custom buildings allowed to be specified at this point.{{verify}}
+
=== Reaction identifier ===
  
−
'''<BUILDING_KEY>''' - The key that is pressed at the building (Such as 'b' for bed at a Carpenter or a block at a Mason's). If two reactions have the same key, then one of them will be assigned a different key, the first alphabetically available at the building.
+
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.
  
−
==Reagents==
+
=== Reaction name ===
−
A reagent is some object that is required to produce whatever the intended object is. This is typically something like needing the ore of a metal to smelt bars of it.
 
  
−
===Reagent Types===
+
This can be anything at all, and is usually used to 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.
−
  [REAGENT:<Identifier>:<Quantity>:<ITEM_TOKEN>:<ITEM_SUBTYPE>:<MATGLOSS_TOKEN>:<MATGLOSS_SUBTYPE>]
 
−
  or
 
−
[REAGENT:<Identifier>:<Quantity>:<MATGLOSS_TOKEN>:<MATGLOSS_SUBTYPE>]
 
  
−
Type 1: Is used for reactions where a specific type of object is required, such as a BUCKET, SWORD, etc.
+
=== Building ===
  
−
Type 2: Is used for when only a material type is needed, such as METAL_ORE for smelter reactions.
+
    [BUILDING:<BUILDING NAME>:<BUILDING KEY>]
 +
* ''name'': The ID of the building where this reaction will appear in the tasks menu.
 +
* ''key'': The keyboard shortcut used to queue up the reaction.
  
−
<Identifier> - Used to refer to this reagent in the reaction Product.
+
The BUILDING NAME is the name of the building that will house this reaction, and the building key is the keyboard shortcut that will queue up the reaction.  If two reactions have the same key, then one of them will be assigned a different key, the first alphabetically available at the building.
  
−
<Quantity> - Used to refer to the number of individual units of the reagent needed for the reaction. NOTE: If a bar, thread, or cloth is used as the <ITEM_TOKEN>, then this value refers to the PRODUCT_DENSITY of the object (150, 15000, 10000 respectively).
+
Valid buildings are KILN, SMELTER, TANNER, KITCHEN, QUERN, MILLSTONE, STILL, CRAFTSMAN, and any custom buildings.
  
−
<ITEM_TOKEN> - Refers to the hard coded ITEM_TOKEN that the reagent must be.
+
Specifying multiple BUILDING tokens will cause the reaction to be available at all of the specified buildings.
  
−
<ITEM_SUBTYPE> - Refers to a specific item subtype, defined in the raws, of a specific ITEM_TOKEN, such as TOY:ITEM_TOY_MINIFORGE.
+
=== 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.
  
−
<MATGLOSS_TOKEN> - Refers to the hardcoded material type of the reagent, such as PLANT_MAT, METAL_ORE, etc.
+
    [REAGENT:<name>:<quantity>:<item token>:<material token>][...modifiers...]
 +
* ''[[#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.
  
−
<MATGLOSS_SUBTYPE> - Refers to a specific item subtype, defined in the raws, of a specific MATGLOSS_TOKEN, such as INORGANIC:MICA. In the case of a plant type the syntax is slightly different, the MATGLOSS_SUBTYPE is actually <PLANT_NAME>:<PLANT_PART>.
+
==== 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.
  
−
''<PLANT_NAME>'' - Refers to the actual plant's name in the raw files.
+
Most reactions are simply named '''A''', '''B''', and so forth in default reactions, although names such as '''TOOLSTONE''' or '''FLUX''' will also work equally well.  The PRODUCT may make reference to this name &mdash; for instance, if a container '''B''' is specified as a reagent, PRODUCT_TO_CONTAINER:B specifies that container.
  
−
''<PLANT_PART>'' - Refers to the plant 'part' you want, whether it's the PLANT, WOOD, LEAVES, SEED, etc.
+
==== quantity ====
 +
The quantity differs between item types.  Generally speaking, cloth, thread, powder and globs use numbers representing the size of material within one item, and everything else uses a static quantity.  While REAGENT:A:'''''10''''':'''''THREAD''''':NONE:NONE:NONE thread is an extremely tiny portion of a random spool of thread, REAGENT:A:'''''10''''':'''''TOY''''':NONE:NONE:NONE is ten unique, solid toy items.
  
−
===Reagent Modifier===
+
Sometimes the quantity of product is directly connected with the quantity of reagent; it seems to be 150 / REAGENT <quantity> (rounding down) so that Reagent <quantity> of 3 gives 50 product and a <quantity> of 4 gives 37. (150/4=37.5) [List of item types this applies to? Bars, for instance.]
−
A reagent can be modified by attaching one, or more, of the following. The modification is used to narrow the available items that can be used for the reaction.
 
  
−
'''[PRESERVE_REAGENT]''' - Reagent is not destroyed, which is the normal effect, at the completion of the reaction. Typically used for containers.
+
==== item token ====
 +
Item tokens are of the form ITEM_TYPE:ITEM_SUBTYPE.
  
−
'''[REACTION_CLASS:X]''' - Reagent's MATGLOSS_SUBTYPE must have a REACTION_CLASS of type X attached to it. Such as the various forms of Gypsum having [REACTION_CLASS:GYPSUM] in them.  Reaction classes are not hard-coded and you may freely insert REACTION_CLASS tags with custom "X" types into object definitions that will be used as reagents.
+
The item type is the sort of item you require; WEAPON, TOY or SKIN_TANNED, for example.  A [[item token|full list]] is available.
  
−
'''[HAS_MATERIAL_REACTION_PRODUCT:X]''' - Reagent's MATGLOSS_SUBTYPE must have a MATERIAL_REACTION_PRODUCT tag. This is used primarily on items that come from a dead, or butchered, animal such as skins or fat for tanning and rendering.
+
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.
  
−
'''[UNROTTEN]''' - Reagent must not be rotten, mainly for organic MATGLOSS types.
+
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, 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.
  
−
'''[BUILDMAT]''' - Reagent is able to be used to build structures (Stone, Wood, Blocks, Bars?).
+
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).
  
−
'''[GLASS_MATERIAL]''' - Reagent has a one of the glass MATGLOSS types.
+
==== material token ====
 +
Material tokens come in several forms - see [[material token|here]] for a full list. For reagents, this will typically be INORGANIC:MATERIAL_ID, whereas products will typically use GET_MATERIAL_FROM_REAGENT:REAGENT_ID:REACTION_PRODUCT_ID.
  
−
'''[WORTHLESS_STONE_ONLY]''' - Only use objects allowed in the Stone Menu.
+
==== Modifiers ====
 +
Reagents may also have extra tokens added on afterwards, placed just after the REAGENT tag.
  
−
'''[FIRE_BUILD_SAFE]''' - Reagent must be considered fire safe (INORGANIC, excluding COAL types).
+
A list of them follows:
  
−
'''[MAGMA_BUILD_SAFE]''' - Reagent must be considered magma safe (INORGANIC, with a melting point greater than the temperature of Magma.
+
{| {{prettytable}}
 +
|- bgcolor="#dddddd"
 +
! Token
 +
! Meaning
 +
|-
 +
| [REACTION_CLASS:X]
 +
| Detailed below the reaction anatomy section.
 +
|-
 +
| [HAS_MATERIAL_REACTION_PRODUCT:X]
 +
| Detailed below the reaction anatomy section.
 +
|-
 +
| [CONTAINS:X]
 +
| Reagent is a container that holds the specified reagent.
 +
|-
 +
| [UNROTTEN]
 +
| Reagent must not be rotten, mainly for organic materials.
 +
|-
 +
| [CONTAINS_LYE]
 +
| Reagent must be a BARREL or TOOL which contains at least one item of type LIQUID_MISC made of LYE.
 +
|-
 +
| [POTASHABLE]
 +
| Alias for [CONTAINS_LYE].
 +
|-
 +
| [NOT_WEB]
 +
| Reagent must be collected (to distinguish silk thread from webs). Only makes sense for items of type THREAD.
 +
|-
 +
| [WEB_ONLY]
 +
| Reagent must be undisturbed (to distinguish silk thread from webs). Only makes sense for items of type THREAD.
 +
|-
 +
| [EMPTY]
 +
| If the reagent is a container, it must be empty.
 +
|-
 +
| [NOT_CONTAIN_BARREL_ITEM]
 +
| If the reagent is a container, it must not contain [[lye]] or [[milk]]. Not necessary if specifying [EMPTY].
 +
|-
 +
| [BAG]
 +
| Reagent must be a bag - that is, a BOX made of plant fiber, silk, yarn, or leather.
 +
|-
 +
| [GLASS_MATERIAL]
 +
| Reagent material must have the [IS_GLASS] token. All 3 types of [[glass]] have this token hardcoded.
 +
|-
 +
| [BUILDMAT]
 +
| Reagent must be a general [[building material]] - BAR, BLOCKS, BOULDER, or WOOD.
 +
|-
 +
| [FIRE_BUILD_SAFE]
 +
| Reagent material must be stable at temperatures below 11000. Currently broken - requires material's IGNITE_POINT to be set to "NONE". Only works with items of type BAR, BLOCKS, BOULDER, WOOD, and ANVIL - all others are considered unsafe.
 +
|-
 +
| [MAGMA_BUILD_SAFE]
 +
| Reagent material must be stable at temperatures below 12000. Currently broken - requires material's IGNITE_POINT to be set to "NONE". Only works with items of type BAR, BLOCKS, BOULDER, WOOD, and ANVIL - all others are considered unsafe.
 +
|-
 +
| [CAN_USE_ARTIFACT]
 +
| Reagent can be an Artifact.  Using [PRESERVE_REAGENT] with this is strongly advised.
 +
|-
 +
| [WORTHLESS_STONE_ONLY]
 +
| Reagent material must be non-[[economic]].
 +
|-
 +
| [ANY_PLANT_MATERIAL]
 +
| Reagent material must be subordinate to a PLANT object.
 +
|-
 +
| [ANY_SILK_MATERIAL]
 +
| Reagent material must have the [SILK] token.
 +
|-
 +
| [ANY_YARN_MATERIAL]
 +
| Reagent material must have the [YARN] token.
 +
|-
 +
| [ANY_SOAP_MATERIAL]
 +
| Reagent material must have the [SOAP] token.
 +
|-
 +
| [ANY_LEATHER_MATERIAL]
 +
| Reagent material must have the [LEATHER] token.
 +
|-
 +
| [ANY_BONE_MATERIAL]
 +
| Reagent material must have the [BONE] token.
 +
|-
 +
| [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].
 +
|-
 +
| [ANY_SHELL_MATERIAL]
 +
| Reagent material must have the [SHELL] token.
 +
|-
 +
| [ANY_TOOTH_MATERIAL]
 +
| Reagent material must have the [TOOTH] token.
 +
|-
 +
| [ANY_HORN_MATERIAL]
 +
| Reagent material must have the [HORN] token.
 +
|-
 +
| [ANY_PEARL_MATERIAL]
 +
| Reagent material must have the [PEARL] token.
 +
|-
 +
| [USE_BODY_COMPONENT]
 +
| Reagent must be a body part (CORPSE or CORPSEPIECE).
 +
|-
 +
| [NO_EDGE_ALLOWED]
 +
| Reagent must not have an edge - excludes sharp stones (produced using knapping) and most types of weapon/ammo.
 +
|-
 +
| [NOT_ENGRAVED]
 +
| Reagent has not been engraved (excludes memorial slabs).
 +
|-
 +
| [NOT_IMPROVED]
 +
| Reagent has not been decorated.
 +
|-
 +
| [DOES_NOT_ABSORB]
 +
| Reagent material must have [ABSORPTION:0]
 +
|-
 +
| [FOOD_STORAGE_CONTAINER]
 +
| Reagent is either a BARREL or a TOOL with the FOOD_STORAGE use.
 +
|-
 +
| [HARD_ITEM_MATERIAL]
 +
| Material has the [ITEMS_HARD] token.
 +
|-
 +
| [NOT_PRESSED]
 +
| Reagent must not be in the SOLID_PRESSED state.
 +
|-
 +
| [METAL_ORE:X]
 +
| Reagent material must be an ore of the specified metal.
 +
|-
 +
| [MIN_DIMENSION:X]
 +
| Reagent's item dimension must be at least this large. The reagent's item type must be BAR, POWDER_MISC, LIQUID_MISC, DRINK, THREAD, or CLOTH for this to work.
 +
|-
 +
| [HAS_TOOL_USE:X]
 +
| 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.
 +
|-
 +
| [PRESERVE_REAGENT]
 +
| Reagent is not destroyed, which is the normal effect, at the completion of the reaction. Typically used for containers.
 +
|-
 +
| [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.
 +
|}
  
−
'''[CAN_USE_ARTIFACT]''' - Reagent can be an Artifact.
+
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.
  
−
'''[ANY_PLANT_MATERIAL]''' - Reagent MATGLOSS must be of a plant subtype.
+
===Products===
 +
Products are the end product of the reaction.  A reaction can have as many products as it likes.
  
−
'''[ANY_SILK_MATERIAL]''' - Reagent MATGLOSS must be of a silk type.
+
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.
  
−
'''[ANY_SOAP_MATERIAL]''' - Reagent MATGLOSS must be of a soap type.
+
Products can be produced directly to a container using the [PRODUCT_TO_CONTAINER:<IDENTIFIER>] token, where the IDENTIFIER is the name of a reagent.  This requires the reagent to have the PRESERVE_REAGENT token.
  
−
'''[ANY_LEATHER_MATERIAL]''' - Reagent MATGLOSS must be of a leather type.
+
Restating this in the above style, we have:
 +
  [PRODUCT:<probability>:<quantity>:<item token>:<material token>][...modifiers...][PRODUCT_DIMENSION:X][PRODUCT_TO_CONTAINER:<IDENTIFIER>]
  
−
'''[ANY_BONE_MATERIAL]''' - Reagent MATGLOSS must be of a bone type.
+
====probability====
 +
The percentage chance the product will be produced when the reaction is completed.
  
−
'''[ANY_SHELL_MATERIAL]''' - Reagent MATGLOSS must be of a shell type.
+
====quantity====
 +
Determines how many of the product will be produced.
  
−
'''[ANY_TOOTH_MATERIAL]''' - Reagent MATGLOSS must be of a tooth type.
+
====item token====
 +
The [[item token]] and subtype of the item you produce.
  
−
'''[ANY_HORN_MATERIAL]''' - Reagent MATGLOSS must be of a horn type.
+
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.
  
−
'''[ANY_PEARL_MATERIAL]''' - Reagent MATGLOSS must be of a pearl type (Excretion from sea creatures?)
+
====material token====
 +
A [[material token]] describing what the product will be made of.
  
−
'''[USE_BODY_COMPONENT]''' - Reagent MATGLOSS must come off a creature's body.
+
====Product modifiers====
 +
Zero or more tokens which further clarify the acceptable types when the item type and material types are insufficient to distinguish them.
  
−
'''[METAL_ORE]''' - Reagent MATGLOSS must be a metal ore.
+
{| {{prettytable}}
 +
|- bgcolor="#dddddd"
 +
! Token
 +
! Meaning
 +
|-
 +
| [FORCE_EDGE]
 +
| Product is given a sharp edge. Used for knapping.
 +
|-
 +
| [PRODUCT_PASTE]
 +
| Product is created in the SOLID_PASTE state.
 +
|-
 +
| [PRODUCT_PRESSED]
 +
| Product is created in the SOLID_PRESSED state.
 +
|-
 +
| [PRODUCT_DIMENSION:<size>]
 +
| Specifies the size of the product. A size of 150 is typical for BAR, POWDER_MISC, LIQUID_MISC, and DRINK. A size of 15000 is typical for THREAD, and a size of 10000 is typical for CLOTH. Has no effect on any other item types.
 +
|-
 +
| [PRODUCT_TO_CONTAINER:<id>]
 +
| Places the product in a container; <id> must be the name of a reagent with the PRESERVE_REAGENT token and a container item type.
  
−
'''[NOT_WEB]''' - States that the material cannot be web (For making only plant/adamantine thread?).
+
|}
  
−
'''[WEB_ONLY]''' - States that the material has to be web (For making only silk thread?).
+
===Improvements===
 +
Improvements are applied to existing reagents. A reaction can have as many improvements as it likes.
  
−
'''[POTASHABLE]''' - The reagent must be able to be turned into pot ash.
+
Restating this in the above style, we have:
 +
  [IMPROVEMENT:<probability>:<reagent name>:<improvement type>:<material token>]
  
−
'''[EMPTY]''' - If the reagent is a container, it must be empty.
+
====probability====
 +
The percentage chance the improvement will be applied to the reagent when the reaction is completed.
  
−
'''[CONTAINS_LYE]''' - If the reagent is a container, it must contain LYE.
+
====reagent name====
 +
The name of the reagent that will be improved. In order to be meaningful, this reagent must have [PRESERVE_REAGENT].
  
−
'''[NOT_CONTAIN_BARREL_ITEM]''' - If the reagent is a Barrel, it must not contain an item that has to reside in a barrel (Such as alcohol?).
+
====improvement type====
 +
The following improvement types can be used:
 +
{| {{prettytable}}
 +
|- bgcolor="#dddddd"
 +
! Token
 +
! Meaning
 +
|-
 +
| 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>.
 +
|}
  
−
'''[BAG]''' - 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.
+
All other item improvement tokens (ART_IMAGE, ITEMSPECIFIC, THREAD, CLOTH, and SEWN_IMAGE) are ignored.
  
−
==Products==
+
====material token====
−
These are the results of a given reaction. There may be any number of such results.
+
A [[material token]] describing what the decoration will be made of.
  
−
===Product Format===
+
===Other tokens===
−
[PRODUCT:<CHANCE>:<QUANTITY>:<ITEM_TOKEN>:<ITEM_SUBTYPE>:<MATGLOSS>:<MATGLOSS_SUBTYPE>]
 
  
−
'''<CHANCE>''' - This is the chance (As a percent) that the <QUANTITY> number of items will be created after this reaction completes.
+
==== 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]).
  
−
'''<QUANTITY>''' - This is the number of the item to be created.
+
==== skill ====
 +
The SKILL token determines what [[Skill token|skill]] the reaction requires and what skill it trains.  Only one skill may be specified.
  
−
'''<ITEM_TOKEN>''' - This is the ITEM_TOKEN of the result.
+
==== automatic ====
 +
The AUTOMATIC token means that the reaction will be queued automatically if the reaction reagents are all present.
  
−
'''<ITEM_SUBTYPE>''' - This is a ITEM_SUBTYPE listed in an actual Raw File.
+
==== adventure mode enabled ====
 +
The ADVENTURE_MODE_ENABLED token means that this version of the reaction is not used by dwarves at home in a fortress, but rather the wanderers of Adventure Mode.  When using this token, it will be allowed for adventurers of any race, without editing Entity files.
  
−
'''<MATGLOSS>''' - This is the MATGLOSS of the item. If you want to use the MATGLOSS information of a Reagent, then this is GET_MATERIAL_FROM_REAGENT:IDENTIFIER, where IDENTIFIER is the reagent's identifier in the reaction.
+
==Material reaction products and reaction classes==
  
−
'''<MATGLOSS_SUBTYPE>''' - Refers to a specific item subtype, defined in the raws, of a specific MATGLOSS_TOKEN, such as PLANT_MAT:MUSHROOM_HELMET_PLUMP. If GET_MATERIAL_FROM_REAGENT was used in the MATGLOSS, you can specify a type, or you can state NONE, to recieve the MATGLOSS_SUBTYPE of the reagent.
+
You can get a certain measure of control over very specific materials using reaction classes and material reaction products - the tokens look like this:
  
−
===Product Modifiers===
+
  [REACTION_CLASS:FAT]
−
Each product may have a zero, or more, modifiers following its declaration.
+
  [HAS_MATERIAL_REACTION_PRODUCT:RENDER_MAT]
  
−
'''[PRODUCT_TO_CONTAINER:<IDENTIFIER>]''' - This states that the product should be put into a specific container listed in as a reagent.
+
Reaction classes represent different classes of material - basically, the material of the reagent must have a REACTION_CLASS the same as the one in the reaction.
  
−
''<IDENTIFIER>'' - Refers back to a reagent identifier.
+
Material reaction products are similar, but are generally used more for things like different kinds of creature materials than universal materials like stone.  This token is how skin can be tanned into leather, which are two separate materials - the skin material has leather as a MATERIAL_REACTION_PRODUCT.
  
−
'''[PRODUCT_DIMENSIONS:<DIMENSION>]''' - Used to specify the dimensions of the object, primarily for use with bars, threads, and cloth.
+
In short, they require the material to have a token such as
 +
  [MATERIAL_REACTION_PRODUCT:X:Y]
 +
...where X is the name of the reaction product that will be referred to in the reaction (RENDER_MAT, in the reaction class example, or TAN_MAT for leather) and Y is a [[material token]] indicating the material of the desired product (such as LOCAL_CREATURE_MAT:LEATHER]).
  
−
''<DIMENSION>'' - The 'size' of the object, for use in reactions that require a certain amount of bars, threads and cloth. 'Normal' size is bars = 150, threads = 15000 and cloth = 10000.{{verify}}
+
==Reactions and world generation==
  
−
==Reaction Modifiers==
+
There are several things to keep in mind when you're adding reactions to a game that already exists.
−
Reactions can be further modified by the adding zero or more of the following.
 
  
−
'''[FUEL]''' - Which states that it must take some form of COAL (COKE or CHARCOAL) to fuel it. If the building requires magma, it's assumed that this tag is ignored.
+
* 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.
  
−
'''[AUTOMATIC]''' - Meaning that if the reagents are present, this reaction is automatically added to the work list of the building, such as 'Butcher Animal' at a Butcher's or 'Gather Web' at a Loom.
+
==Full Token List==
 +
For the sake of convenience and readability this is a complete compilation of the previously listed reaction tokens in alphabetical order
  
−
==Skills==
+
{| {{prettytable}}
−
Skills have to be associated with a reaction. This dictates what skill receives the experience and who can do the job. More than one skill can be associated with the reaction, but only the last SKILL on the list, that a dwarf can perform, receives experience.
+
|- bgcolor="#dddddd"
 +
! Token
 +
! Arguments
 +
! Description
  
−
  [SKILL:<SKILL_TOKEN>]
+
|-
 +
| ADVENTURE_MODE_ENABLED
 +
|
 +
| this version of the reaction is not used by dwarves at home in a fortress, but rather the wanderers of Adventure Mode. When using this token, it will be allowed for adventurers of any race, without editing Entity files
  
−
'''<IDENTIFIER>''' - This is SKILL_TOKEN for the reaction.
+
|-
 +
| ANY_BONE_MATERIAL
 +
|
 +
| Reagent material must have the [BONE] token.
  
−
[[Category:Modding]]
+
|-
 +
| ANY_HORN_MATERIAL
 +
|
 +
| Reagent material must have the [HORN] token.
 +
 
 +
|-
 +
| ANY_LEATHER_MATERIAL
 +
|
 +
| Reagent material must have the [LEATHER] token.
 +
 
 +
|-
 +
| ANY_PEARL_MATERIAL
 +
|
 +
| Reagent material must have the [PEARL] token.
 +
 
 +
|-
 +
| ANY_PLANT_MATERIAL
 +
|
 +
| Reagent material must be subordinate to a PLANT object.
 +
 
 +
|-
 +
| ANY_SHELL_MATERIAL
 +
|
 +
| Reagent material must have the [SHELL] token.
 +
 
 +
|-
 +
| ANY_SILK_MATERIAL
 +
|
 +
| Reagent material must have the [SILK] token.
 +
 
 +
|-
 +
| ANY_SOAP_MATERIAL
 +
|
 +
| Reagent material must have the [SOAP] token.
 +
 
 +
|-
 +
| 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].
 +
 
 +
|-
 +
| ANY_TOOTH_MATERIAL
 +
|
 +
| Reagent material must have the [TOOTH] token.
 +
 
 +
|-
 +
| ANY_YARN_MATERIAL
 +
|
 +
| Reagent material must have the [YARN] token.
 +
 
 +
|-
 +
| AUTOMATIC
 +
|
 +
| the reaction will be queued automatically if the reaction reagents are all present.
 +
 
 +
|-
 +
| BAG
 +
|
 +
| 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.
 +
 
 +
|-
 +
| BUILDING
 +
|
 +
* Building name
 +
* in-building reaction hotkey
 +
| 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
 +
 
 +
|-
 +
| BUILDMAT
 +
|
 +
| Reagent is able to be used to build structures (Stone, Wood, Blocks, Bars?).
 +
 
 +
|-
 +
| CAN_USE_ARTIFACT
 +
|
 +
| Reagent can be an Artifact.  Using [PRESERVE_REAGENT] with this is strongly advised.
 +
 
 +
|-
 +
| CONTAINS
 +
| required content
 +
| Reagent is a container that holds the specified reagent.
 +
 
 +
|-
 +
| CONTAINS_LYE
 +
|
 +
| 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].
 +
 
 +
|-
 +
| DOES_NOT_ABSORB
 +
|
 +
| Reagent material must have [ABSORPTION:0]
 +
 
 +
|-
 +
| DOES_NOT_DETERMINE_PRODUCT_AMOUNT
 +
|
 +
| 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".
 +
 
 +
|-
 +
| EMPTY
 +
|
 +
| If the reagent is a container, it must be empty.
 +
 
 +
|-
 +
| FIRE_BUILD_SAFE
 +
|
 +
| Reagent must be considered fire safe - ie. not wood, and not coal.
 +
 
 +
|-
 +
| FORCE_EDGE
 +
|
 +
| Product is given a sharp edge. Used for knapping.
 +
 
 +
|-
 +
| FUEL
 +
|
 +
| Requires that the reaction either use up a unit of coal or charcoal or else be performed at a magma workshop
 +
 
 +
|-
 +
| GLASS_MATERIAL
 +
|
 +
| Reagent material has [IS_GLASS].
 +
 
 +
|-
 +
| HAS_MATERIAL_REACTION_PRODUCT
 +
| required reaction product
 +
|
 +
 
 +
|-
 +
| HAS_TOOL_USE
 +
| Tool-use token
 +
| 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.
 +
 
 +
|-
 +
| IMPROVEMENT
 +
|
 +
* Probability
 +
* Reagent Name
 +
* Improvement type
 +
* Material Token
 +
| Improvement types include BANDS, COVERED, GLAZED, RINGS_HANGING, and SPIKES
 +
 
 +
|-
 +
| MAGMA_BUILD_SAFE
 +
|
 +
| Currently broken - behaves exactly the same as FIRE_BUILD_SAFE.
 +
 
 +
|-
 +
| METAL_ORE
 +
|
 +
* Inorganic material
 +
| Reagent material must be an ore of the specified metal
 +
 
 +
|-
 +
| MIN_DIMENSION
 +
|
 +
* size
 +
| Requires that the reagent have a dimension of at least this value. Only effective with BAR, POWDER_MISC, LIQUID_MISC, DRINK, THREAD, and CLOTH items.
 +
 
 +
|-
 +
| NAME
 +
| name
 +
| defines the name used by the reaction in-game
 +
 
 +
|-
 +
| NO_EDGE_ALLOWED
 +
|
 +
| Reagent must not be sharpened (used for knapping).
 +
 
 +
|-
 +
| NOT_CONTAIN_BARREL_ITEM
 +
|
 +
| 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.
 +
 
 +
|-
 +
| NOT_ENGRAVED
 +
|
 +
| Reagent must not be engraved?
 +
 
 +
|-
 +
| NOT_IMPROVED
 +
|
 +
| Reagent has not been decorated.
 +
 
 +
|-
 +
| NOT_PRESSED
 +
|
 +
| Reagent must not be in the SOLID_PRESSED state.
 +
 
 +
|-
 +
| NOT_WEB
 +
|
 +
| Reagent must be "collected" - used with THREAD:NONE to exclude webs.
 +
 
 +
|-
 +
| POTASHABLE
 +
|
 +
| Alias for CONTAINS_LYE.
 +
 
 +
|-
 +
| PRESERVE_REAGENT
 +
|
 +
| Reagent is not destroyed, which is the normal effect, at the completion of the reaction. Typically used for containers.
 +
 
 +
|-
 +
| PRODUCT
 +
|
 +
*Probability
 +
*Quantity
 +
*Item Token
 +
*Material Token
 +
| Defines one of the products to be outputted by the reaction
 +
 
 +
|-
 +
| PRODUCT_DIMENSION
 +
| size
 +
| Specifies the size of the product. A size of 150 is typical for BAR, POWDER_MISC, LIQUID_MISC, and DRINK.  A size of 15000 is typical for THREAD, and a size of 10000 is typical for CLOTH.
 +
 
 +
|-
 +
| PRODUCT_PASTE
 +
|
 +
| Product is created in the SOLID_PASTE state.
 +
 
 +
|-
 +
| PRODUCT_PRESSED
 +
|
 +
| Product is created in the SOLID_PRESSED state.
 +
 
 +
|-
 +
| PRODUCT_TO_CONTAINER
 +
| Reagent ID
 +
| Places the product in a container; <id> must be the name of a reagent with the PRESERVE_REAGENT token and a container item type.
 +
 
 +
|-
 +
| REACTION
 +
| Identifier
 +
| defines a new reaction
 +
 
 +
|-
 +
| REACTION_CLASS
 +
|
 +
|
 +
 
 +
|-
 +
|REAGENT
 +
|
 +
* name/id
 +
* quantity
 +
* [[item token]]
 +
* [[material token]]
 +
| Requires a given reagent as an input for a reaction
 +
 
 +
|-
 +
| SKILL
 +
| Skill Token
 +
| Skill used by the reaction
 +
 
 +
|-
 +
| UNROTTEN
 +
|
 +
| Reagent must not be rotten, mainly for organic materials.
 +
 
 +
|-
 +
| USE_BODY_COMPONENT
 +
|
 +
| Reagent material must come off a creature's body.
 +
 
 +
|-
 +
| WEB_ONLY
 +
|
 +
| Reagent must be "undisturbed" - used with THREAD:NONE to gather webs.
 +
 
 +
|-
 +
| WORTHLESS_STONE_ONLY
 +
|
 +
| Reagent is not made of an economic stone.
 +
 
 +
|}
 +
 
 +
{{Category|Modding}}

Latest revision as of 15:55, 25 July 2012

xTATTEREDx  · +FINE+  · *SUPERIOR*  · ≡EXCEPTIONAL≡  · ☼MASTERWORK☼
v50.14 · v0.47 · v0.34 · v0.31.25 · v0.28 · v0.23
This article is about an older version of DF.

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 quite simple to add additional ones.

Reaction differences between modes[edit]

In Fortress mode, reactions are linked to specific buildings, and must be added to a civilization's 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 use it.

In Adventure mode, reactions are freely available via x > create, 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. As of .10, there are several bugs with Adventure mode reactions, chief of which is the fact that you cannot select liquid reagents.

Prior to version 31.10, a reaction could only result in an object of base quality. However, in .10 items produced via reactions have been observed to have quality modifiers. The way skill factors into them has yet is the same as for normal itemsv0.31.21.

Anatomy of a reaction[edit]

Reactions are found within reaction_x files (such as reaction_smelter or reaction_other). Generally speaking they 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>]
     [AUTOMATIC]
     [ADVENTURE_MODE_ENABLED]
  • identifier: The internal ID of the reaction.
  • name: The name of the reaction, visible to the player in the Fortress mode or Adventure mode menus.
  • building: The building ID that the reaction uses, and the relevant keyboard shortcut.
  • ...reagents...: Zero or more reagents (ingredients) that are required to be in stock for the reaction to be possible.
  • ...products...: Zero or more products that are created from the reaction.
  • fuel: (optional) If present, the reaction requires charcoal, coke or a magma-powered workshop.
  • skill: (optional) The skill required and trained by the reaction.
  • automatic: (optional) If present, the reaction will automatically be enqueued whenever it can possibly be performed.
  • adventure mode: (optional) If present, the reaction is used by the player in Adventure mode instead.

Reaction identifier[edit]

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.

Reaction name[edit]

This can be anything at all, and is usually used to 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[edit]

   [BUILDING:<BUILDING NAME>:<BUILDING KEY>]
  • name: The ID of the building where this reaction will appear in the tasks menu.
  • key: The keyboard shortcut used to queue up the reaction.

The BUILDING NAME is the name of the building that will house this reaction, and the building key is the keyboard shortcut that will queue up the reaction. If two reactions have the same key, then one of them will be assigned a different key, the first alphabetically available at the building.

Valid buildings are KILN, SMELTER, TANNER, KITCHEN, QUERN, MILLSTONE, STILL, CRAFTSMAN, and any custom buildings.

Specifying multiple BUILDING tokens will cause the reaction to be available at all of the specified buildings.

Reagents[edit]

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...]
  • name: The name of the reagent, local to the reaction.
  • quantity: The amount of the item that will be used in the reaction.
  • item token: The type (and subtype) of the item you require.
  • material token: The material the item should be made of.
  • ...modifiers...: Zero or more tokens which further clarify the acceptable types when the item type and material types are insufficient to distinguish them.

name[edit]

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 reactions are simply named A, B, and so forth in default reactions, although names such as TOOLSTONE or FLUX 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[edit]

The quantity differs between item types. Generally speaking, cloth, thread, powder and globs use numbers representing the size of material within one item, and everything else uses a static quantity. While REAGENT:A:10:THREAD:NONE:NONE:NONE thread is an extremely tiny portion of a random spool of thread, REAGENT:A:10:TOY:NONE:NONE:NONE is ten unique, solid toy items.

Sometimes the quantity of product is directly connected with the quantity of reagent; it seems to be 150 / REAGENT <quantity> (rounding down) so that Reagent <quantity> of 3 gives 50 product and a <quantity> of 4 gives 37. (150/4=37.5) [List of item types this applies to? Bars, for instance.]

item token[edit]

Item tokens are of the form ITEM_TYPE:ITEM_SUBTYPE.

The item type is the sort of item you require; WEAPON, TOY or SKIN_TANNED, for example. A full list is available.

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.

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

material token[edit]

Material tokens come in several forms - see here for a full list. For reagents, this will typically be INORGANIC:MATERIAL_ID, whereas products will typically use GET_MATERIAL_FROM_REAGENT:REAGENT_ID:REACTION_PRODUCT_ID.

Modifiers[edit]

Reagents may also have extra tokens added on afterwards, placed just after the REAGENT tag.

A list of them follows:

Token Meaning
[REACTION_CLASS:X] Detailed below the reaction anatomy section.
[HAS_MATERIAL_REACTION_PRODUCT:X] Detailed below the reaction anatomy section.
[CONTAINS:X] Reagent is a container that holds the specified reagent.
[UNROTTEN] Reagent must not be rotten, mainly for organic materials.
[CONTAINS_LYE] Reagent must be a BARREL or TOOL which contains at least one item of type LIQUID_MISC made of LYE.
[POTASHABLE] Alias for [CONTAINS_LYE].
[NOT_WEB] Reagent must be collected (to distinguish silk thread from webs). Only makes sense for items of type THREAD.
[WEB_ONLY] Reagent must be undisturbed (to distinguish silk thread from webs). Only makes sense for items of type THREAD.
[EMPTY] If the reagent is a container, it must be empty.
[NOT_CONTAIN_BARREL_ITEM] If the reagent is a container, it must not contain lye or milk. Not necessary if specifying [EMPTY].
[BAG] Reagent must be a bag - that is, a BOX made of plant fiber, silk, yarn, or leather.
[GLASS_MATERIAL] Reagent material must have the [IS_GLASS] token. All 3 types of glass have this token hardcoded.
[BUILDMAT] Reagent must be a general building material - BAR, BLOCKS, BOULDER, or WOOD.
[FIRE_BUILD_SAFE] Reagent material must be stable at temperatures below 11000. Currently broken - requires material's IGNITE_POINT to be set to "NONE". Only works with items of type BAR, BLOCKS, BOULDER, WOOD, and ANVIL - all others are considered unsafe.
[MAGMA_BUILD_SAFE] Reagent material must be stable at temperatures below 12000. Currently broken - requires material's IGNITE_POINT to be set to "NONE". Only works with items of type BAR, BLOCKS, BOULDER, WOOD, and ANVIL - all others are considered unsafe.
[CAN_USE_ARTIFACT] Reagent can be an Artifact. Using [PRESERVE_REAGENT] with this is strongly advised.
[WORTHLESS_STONE_ONLY] Reagent material must be non-economic.
[ANY_PLANT_MATERIAL] Reagent material must be subordinate to a PLANT object.
[ANY_SILK_MATERIAL] Reagent material must have the [SILK] token.
[ANY_YARN_MATERIAL] Reagent material must have the [YARN] token.
[ANY_SOAP_MATERIAL] Reagent material must have the [SOAP] token.
[ANY_LEATHER_MATERIAL] Reagent material must have the [LEATHER] token.
[ANY_BONE_MATERIAL] Reagent material must have the [BONE] token.
[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].
[ANY_SHELL_MATERIAL] Reagent material must have the [SHELL] token.
[ANY_TOOTH_MATERIAL] Reagent material must have the [TOOTH] token.
[ANY_HORN_MATERIAL] Reagent material must have the [HORN] token.
[ANY_PEARL_MATERIAL] Reagent material must have the [PEARL] token.
[USE_BODY_COMPONENT] Reagent must be a body part (CORPSE or CORPSEPIECE).
[NO_EDGE_ALLOWED] Reagent must not have an edge - excludes sharp stones (produced using knapping) and most types of weapon/ammo.
[NOT_ENGRAVED] Reagent has not been engraved (excludes memorial slabs).
[NOT_IMPROVED] Reagent has not been decorated.
[DOES_NOT_ABSORB] Reagent material must have [ABSORPTION:0]
[FOOD_STORAGE_CONTAINER] Reagent is either a BARREL or a TOOL with the FOOD_STORAGE use.
[HARD_ITEM_MATERIAL] Material has the [ITEMS_HARD] token.
[NOT_PRESSED] Reagent must not be in the SOLID_PRESSED state.
[METAL_ORE:X] Reagent material must be an ore of the specified metal.
[MIN_DIMENSION:X] Reagent's item dimension must be at least this large. The reagent's item type must be BAR, POWDER_MISC, LIQUID_MISC, DRINK, THREAD, or CLOTH for this to work.
[HAS_TOOL_USE:X] 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.
[PRESERVE_REAGENT] Reagent is not destroyed, which is the normal effect, at the completion of the reaction. Typically used for containers.
[DOES_NOT_DETERMINE_PRODUCT_AMOUNT] Reagent quantity is ignored for the purposes of producing extra outputs. Typically used for containers so that stacks of reagents will correctly produce additional outputs.

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.

Products[edit]

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:<IDENTIFIER>] token, where the IDENTIFIER is the 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...][PRODUCT_DIMENSION:X][PRODUCT_TO_CONTAINER:<IDENTIFIER>]

probability[edit]

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

quantity[edit]

Determines how many of the product will be produced.

item token[edit]

The item token and subtype of the item you produce.

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[edit]

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

Product modifiers[edit]

Zero or more tokens which further clarify the acceptable types when the item type and material types are insufficient to distinguish them.

Token Meaning
[FORCE_EDGE] Product is given a sharp edge. Used for knapping.
[PRODUCT_PASTE] Product is created in the SOLID_PASTE state.
[PRODUCT_PRESSED] Product is created in the SOLID_PRESSED state.
[PRODUCT_DIMENSION:<size>] Specifies the size of the product. A size of 150 is typical for BAR, POWDER_MISC, LIQUID_MISC, and DRINK. A size of 15000 is typical for THREAD, and a size of 10000 is typical for CLOTH. Has no effect on any other item types.
[PRODUCT_TO_CONTAINER:<id>] Places the product in a container; <id> must be the name of a reagent with the PRESERVE_REAGENT token and a container item type.

Improvements[edit]

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[edit]

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

reagent name[edit]

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

improvement type[edit]

The following improvement types can be used:

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

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

material token[edit]

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

Other tokens[edit]

fuel[edit]

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[edit]

The SKILL token determines what skill the reaction requires and what skill it trains. Only one skill may be specified.

automatic[edit]

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

adventure mode enabled[edit]

The ADVENTURE_MODE_ENABLED token means that this version of the reaction is not used by dwarves at home in a fortress, but rather the wanderers of Adventure Mode. When using this token, it will be allowed for adventurers of any race, without editing Entity files.

Material reaction products and reaction classes[edit]

You can get a certain measure of control over very specific materials using reaction classes and material reaction products - the tokens look like this: 

  [REACTION_CLASS:FAT]
  [HAS_MATERIAL_REACTION_PRODUCT:RENDER_MAT]

Reaction classes represent different classes of material - basically, the material of the reagent must have a REACTION_CLASS the same as the one in the reaction.

Material reaction products are similar, but are generally used more for things like different kinds of creature materials than universal materials like stone. This token is how skin can be tanned into leather, which are two separate materials - the skin material has leather as a MATERIAL_REACTION_PRODUCT.

In short, they require the material to have a token such as 

  [MATERIAL_REACTION_PRODUCT:X:Y]

...where X is the name of the reaction product that will be referred to in the reaction (RENDER_MAT, in the reaction class example, or TAN_MAT for leather) and Y is a material token indicating the material of the desired product (such as LOCAL_CREATURE_MAT:LEATHER]).

Reactions and world generation[edit]

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[edit]

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

Token Arguments Description
ADVENTURE_MODE_ENABLED this version of the reaction is not used by dwarves at home in a fortress, but rather the wanderers of Adventure Mode. When using this token, it will be allowed for adventurers of any race, without editing Entity files
ANY_BONE_MATERIAL Reagent material must have the [BONE] token.
ANY_HORN_MATERIAL Reagent material must have the [HORN] token.
ANY_LEATHER_MATERIAL Reagent material must have the [LEATHER] token.
ANY_PEARL_MATERIAL Reagent material must have the [PEARL] token.
ANY_PLANT_MATERIAL Reagent material must be subordinate to a PLANT object.
ANY_SHELL_MATERIAL Reagent material must have the [SHELL] token.
ANY_SILK_MATERIAL Reagent material must have the [SILK] token.
ANY_SOAP_MATERIAL Reagent material must have the [SOAP] token.
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].
ANY_TOOTH_MATERIAL Reagent material must have the [TOOTH] token.
ANY_YARN_MATERIAL Reagent material must have the [YARN] token.
AUTOMATIC the reaction will be queued automatically if the reaction reagents are all present.
BAG 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.
BUILDING
  • Building name
  • in-building reaction hotkey
 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
BUILDMAT Reagent is able to be used to build structures (Stone, Wood, Blocks, Bars?).
CAN_USE_ARTIFACT Reagent can be an Artifact. Using [PRESERVE_REAGENT] with this is strongly advised.
CONTAINS required content Reagent is a container that holds the specified reagent.
CONTAINS_LYE 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].
DOES_NOT_ABSORB Reagent material must have [ABSORPTION:0]
DOES_NOT_DETERMINE_PRODUCT_AMOUNT Performing a reaction with large stacks 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".
EMPTY If the reagent is a container, it must be empty.
FIRE_BUILD_SAFE Reagent must be considered fire safe - ie. not wood, and not coal.
FORCE_EDGE Product is given a sharp edge. Used for knapping.
FUEL Requires that the reaction either use up a unit of coal or charcoal or else be performed at a magma workshop
GLASS_MATERIAL Reagent material has [IS_GLASS].
HAS_MATERIAL_REACTION_PRODUCT required reaction product
HAS_TOOL_USE Tool-use token 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.
IMPROVEMENT
  • Probability
  • Reagent Name
  • Improvement type
  • Material Token
 Improvement types include BANDS, COVERED, GLAZED, RINGS_HANGING, and SPIKES
MAGMA_BUILD_SAFE Currently broken - behaves exactly the same as FIRE_BUILD_SAFE.
METAL_ORE
  • Inorganic material
 Reagent material must be an ore of the specified metal
MIN_DIMENSION
  • size
 Requires that the reagent have a dimension of at least this value. Only effective with BAR, POWDER_MISC, LIQUID_MISC, DRINK, THREAD, and CLOTH items.
NAME name defines the name used by the reaction in-game
NO_EDGE_ALLOWED Reagent must not be sharpened (used for knapping).
NOT_CONTAIN_BARREL_ITEM 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.
NOT_ENGRAVED Reagent must not be engraved?
NOT_IMPROVED Reagent has not been decorated.
NOT_PRESSED Reagent must not be in the SOLID_PRESSED state.
NOT_WEB Reagent must be "collected" - used with THREAD:NONE to exclude webs.
POTASHABLE Alias for CONTAINS_LYE.
PRESERVE_REAGENT Reagent is not destroyed, which is the normal effect, at the completion of the reaction. Typically used for containers.
PRODUCT
  • Probability
  • Quantity
  • Item Token
  • Material Token
 Defines one of the products to be outputted by the reaction
PRODUCT_DIMENSION size Specifies the size of the product. A size of 150 is typical for BAR, POWDER_MISC, LIQUID_MISC, and DRINK. A size of 15000 is typical for THREAD, and a size of 10000 is typical for CLOTH.
PRODUCT_PASTE Product is created in the SOLID_PASTE state.
PRODUCT_PRESSED Product is created in the SOLID_PRESSED state.
PRODUCT_TO_CONTAINER Reagent ID Places the product in a container; <id> must be the name of a reagent with the PRESERVE_REAGENT token and a container item type.
REACTION Identifier defines a new reaction
REACTION_CLASS
REAGENT Requires a given reagent as an input for a reaction
SKILL Skill Token Skill used by the reaction
UNROTTEN Reagent must not be rotten, mainly for organic materials.
USE_BODY_COMPONENT Reagent material must come off a creature's body.
WEB_ONLY Reagent must be "undisturbed" - used with THREAD:NONE to gather webs.
WORTHLESS_STONE_ONLY Reagent is not made of an economic stone.
Retrieved from "https://dwarffortresswiki.org/index.php?title=v0.31:Reactions&oldid=175825"