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 "Reaction"

From Dwarf Fortress Wiki
Jump to navigation Jump to search
(→‎Full token list: Reformatted full token list, added "type" column.)
Line 598: Line 598:
 
! Token
 
! Token
 
! Arguments
 
! Arguments
 +
! Type
 
! Description
 
! Description
  
 
|-
 
|-
 
| {{text anchor|ADVENTURE_MODE_ENABLED}}
 
| {{text anchor|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.
 
| 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.
Line 608: Line 610:
 
| {{text anchor|ANY_BONE_MATERIAL}}
 
| {{text anchor|ANY_BONE_MATERIAL}}
 
|
 
|
 +
| Reagent modifier
 
| Reagent material must have the [BONE] token.
 
| Reagent material must have the [BONE] token.
  
Line 613: Line 616:
 
| {{text anchor|ANY_HORN_MATERIAL}}
 
| {{text anchor|ANY_HORN_MATERIAL}}
 
|
 
|
 +
| Reagent modifier
 
| Reagent material must have the [HORN] token.
 
| Reagent material must have the [HORN] token.
  
Line 618: Line 622:
 
| {{text anchor|ANY_LEATHER_MATERIAL}}
 
| {{text anchor|ANY_LEATHER_MATERIAL}}
 
|
 
|
 +
| Reagent modifier
 
| Reagent material must have the [LEATHER] token.
 
| Reagent material must have the [LEATHER] token.
  
Line 623: Line 628:
 
| {{text anchor|ANY_PEARL_MATERIAL}}
 
| {{text anchor|ANY_PEARL_MATERIAL}}
 
|
 
|
 +
| Reagent modifier
 
| Reagent material must have the [PEARL] token.
 
| Reagent material must have the [PEARL] token.
  
Line 628: Line 634:
 
| {{text anchor|ANY_PLANT_MATERIAL}}
 
| {{text anchor|ANY_PLANT_MATERIAL}}
 
|
 
|
 +
| Reagent modifier
 
| Reagent material must be subordinate to a PLANT object.
 
| Reagent material must be subordinate to a PLANT object.
  
Line 633: Line 640:
 
| {{text anchor|ANY_SHELL_MATERIAL}}
 
| {{text anchor|ANY_SHELL_MATERIAL}}
 
|
 
|
 +
| Reagent modifier
 
| Reagent material must have the [SHELL] token.
 
| Reagent material must have the [SHELL] token.
  
Line 638: Line 646:
 
| {{text anchor|ANY_SILK_MATERIAL}}
 
| {{text anchor|ANY_SILK_MATERIAL}}
 
|
 
|
 +
| Reagent modifier
 
| Reagent material must have the [SILK] token.
 
| Reagent material must have the [SILK] token.
  
Line 643: Line 652:
 
| {{text anchor|ANY_SOAP_MATERIAL}}
 
| {{text anchor|ANY_SOAP_MATERIAL}}
 
|
 
|
 +
| Reagent modifier
 
| Reagent material must have the [SOAP] token.
 
| Reagent material must have the [SOAP] token.
  
Line 648: Line 658:
 
| {{text anchor|ANY_STRAND_TISSUE}}
 
| {{text anchor|ANY_STRAND_TISSUE}}
 
|
 
|
 +
| Reagent modifier
 
| Reagent is made of a tissue having [TISSUE_SHAPE:STRANDS], intended for matching hair and wool. Must be used with [USE_BODY_COMPONENT].
 
| Reagent is made of a tissue having [TISSUE_SHAPE:STRANDS], intended for matching hair and wool. Must be used with [USE_BODY_COMPONENT].
  
Line 653: Line 664:
 
| {{text anchor|ANY_TOOTH_MATERIAL}}
 
| {{text anchor|ANY_TOOTH_MATERIAL}}
 
|
 
|
 +
| Reagent modifier
 
| Reagent material must have the [TOOTH] token.
 
| Reagent material must have the [TOOTH] token.
  
Line 658: Line 670:
 
| {{text anchor|ANY_YARN_MATERIAL}}
 
| {{text anchor|ANY_YARN_MATERIAL}}
 
|
 
|
 +
| Reagent modifier
 
| Reagent material must have the [YARN] token.
 
| Reagent material must have the [YARN] token.
  
 
|-
 
|-
 
| {{text anchor|ATTRIBUTE_IP}}{{version|0.47.01}}
 
| {{text anchor|ATTRIBUTE_IP}}{{version|0.47.01}}
−
| Integer
+
|
 +
* Integer
 +
| Skill modifier
 
| Amount of attribute gain given per skill improvement. Default is 10.
 
| Amount of attribute gain given per skill improvement. Default is 10.
  
 
|-
 
|-
 
| {{text anchor|AUTOMATIC}}
 
| {{text anchor|AUTOMATIC}}
 +
|
 
|
 
|
 
| The reaction will be queued automatically if the reaction reagents are all present.
 
| The reaction will be queued automatically if the reaction reagents are all present.
Line 673: Line 689:
 
| {{text anchor|BAG}}
 
| {{text anchor|BAG}}
 
|
 
|
 +
| Reagent modifier
 
| 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.
 
| 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.
  
Line 679: Line 696:
 
|  
 
|  
 
* Building name
 
* Building name
−
* In-building reaction hotkey  
+
* 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.
 
| 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.
  
Line 685: Line 703:
 
| {{text anchor|BUILDMAT}}
 
| {{text anchor|BUILDMAT}}
 
|
 
|
 +
| Reagent modifier
 
| Reagent is able to be used to build structures (Stone, Wood, Blocks, Bars?).
 
| Reagent is able to be used to build structures (Stone, Wood, Blocks, Bars?).
  
Line 690: Line 709:
 
| {{text anchor|CAN_USE_ARTIFACT}}
 
| {{text anchor|CAN_USE_ARTIFACT}}
 
|
 
|
 +
| Reagent modifier
 
| Reagent can be an Artifact.  Using [PRESERVE_REAGENT] with this is strongly advised.
 
| Reagent can be an Artifact.  Using [PRESERVE_REAGENT] with this is strongly advised.
  
Line 695: Line 715:
 
| {{text anchor|CAN_USE_HOSPITAL_RESERVED}}{{version|0.42.01}}
 
| {{text anchor|CAN_USE_HOSPITAL_RESERVED}}{{version|0.42.01}}
 
|  
 
|  
 +
| Reagent modifier
 
| Allows the reagent to be an item that is otherwise reserved for use by a [[healthcare|hospital]].
 
| Allows the reagent to be an item that is otherwise reserved for use by a [[healthcare|hospital]].
  
Line 700: Line 721:
 
| {{text anchor|CAN_USE_LOCATION_RESERVED}}{{version|0.42.01}}
 
| {{text anchor|CAN_USE_LOCATION_RESERVED}}{{version|0.42.01}}
 
|  
 
|  
 +
| Reagent modifier
 
| Allows the reagent to be an item that is otherwise reserved for use by a [[locations|location]].
 
| Allows the reagent to be an item that is otherwise reserved for use by a [[locations|location]].
  
 
|-
 
|-
 
| {{text anchor|CATEGORY}}{{version|0.42.01}}
 
| {{text anchor|CATEGORY}}{{version|0.42.01}}
−
| Category ID  
+
|
 +
* Category ID  
 +
|
 
| 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.
 
| 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.
  
Line 711: Line 735:
 
|-
 
|-
 
| {{text anchor|CATEGORY_NAME}}{{version|0.42.01}}
 
| {{text anchor|CATEGORY_NAME}}{{version|0.42.01}}
−
| String  
+
|
 +
* String  
 +
| Category
 
| The name of the category as displayed in-game.
 
| The name of the category as displayed in-game.
  
 
|-
 
|-
 
| {{text anchor|CATEGORY_DESCRIPTION}}{{version|0.42.01}}
 
| {{text anchor|CATEGORY_DESCRIPTION}}{{version|0.42.01}}
−
| String  
+
|
 +
* String  
 +
| Category
 
| If present, when the category is highlighted in a building menu, this string will be displayed in the Helpful Hint box.
 
| If present, when the category is highlighted in a building menu, this string will be displayed in the Helpful Hint box.
  
 
|-
 
|-
 
| {{text anchor|CATEGORY_PARENT}}{{version|0.42.01}}
 
| {{text anchor|CATEGORY_PARENT}}{{version|0.42.01}}
−
| Category ID  
+
|
 +
* Category ID  
 +
| Category
 
| If present, this category will be a submenu of the indicated category, rather than a submenu of the reaction's building.
 
| If present, this category will be a submenu of the indicated category, rather than a submenu of the reaction's building.
  
 
|-
 
|-
 
| {{text anchor|CATEGORY_KEY}}{{version|0.42.01}}
 
| {{text anchor|CATEGORY_KEY}}{{version|0.42.01}}
−
| [[interface.txt|Hotkey token]]
+
|
 +
* Hotkey
 +
| Category
 
| If present, this category can be selected from its parent menu (whether a building or a parent category) using the given hotkey.
 
| If present, this category can be selected from its parent menu (whether a building or a parent category) using the given hotkey.
  
 
|-
 
|-
 
| {{text anchor|CONTAINS}}
 
| {{text anchor|CONTAINS}}
−
| Reagent name
+
|
 +
* Reagent name
 +
| Reagent modifier
 
| Reagent is a container that holds the specified reagent.
 
| Reagent is a container that holds the specified reagent.
  
Line 737: Line 771:
 
| {{text anchor|CONTAINS_LYE}} (Deprecated)
 
| {{text anchor|CONTAINS_LYE}} (Deprecated)
 
|
 
|
 +
| Reagent modifier
 
| 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].
 
| 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].
  
 
|-
 
|-
 
| {{text anchor|DESCRIPTION}}
 
| {{text anchor|DESCRIPTION}}
−
| String
+
|
 +
* String
 +
|
 
| Description of the reaction.
 
| Description of the reaction.
  
Line 747: Line 784:
 
| {{text anchor|DOES_NOT_ABSORB}}
 
| {{text anchor|DOES_NOT_ABSORB}}
 
|
 
|
 +
| Reagent modifier
 
| Reagent material must have [ABSORPTION:0].
 
| Reagent material must have [ABSORPTION:0].
  
Line 752: Line 790:
 
| {{text anchor|DOES_NOT_DETERMINE_PRODUCT_AMOUNT}}
 
| {{text anchor|DOES_NOT_DETERMINE_PRODUCT_AMOUNT}}
 
|
 
|
 +
| Reagent modifier
 
| 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".
 
| 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".
  
Line 757: Line 796:
 
| {{text anchor|EMPTY}}
 
| {{text anchor|EMPTY}}
 
|
 
|
 +
| Reagent modifier
 
| If the reagent is a container, it must be empty.
 
| If the reagent is a container, it must be empty.
  
Line 762: Line 802:
 
| {{text anchor|FIRE_BUILD_SAFE}}
 
| {{text anchor|FIRE_BUILD_SAFE}}
 
|
 
|
 +
| Reagent modifier
 
| Reagent must be considered [[fire-safe]] (stable [[temperature]] below {{ct|11000}}) - i.e. not wood, and not coal.
 
| Reagent must be considered [[fire-safe]] (stable [[temperature]] below {{ct|11000}}) - i.e. not wood, and not coal.
  
Line 767: Line 808:
 
| {{text anchor|FORCE_EDGE}}
 
| {{text anchor|FORCE_EDGE}}
 
|
 
|
 +
| Product modifier
 
| Product is given a sharp edge. Used for knapping.
 
| Product is given a sharp edge. Used for knapping.
  
Line 772: Line 814:
 
| {{text anchor|FOOD_STORAGE_CONTAINER}}
 
| {{text anchor|FOOD_STORAGE_CONTAINER}}
 
|
 
|
 +
| Reagent modifier
 
| Reagent must be a barrel or any non-absorbing tool with [TOOL_USE:FOOD_STORAGE].
 
| Reagent must be a barrel or any non-absorbing tool with [TOOL_USE:FOOD_STORAGE].
  
 
|-
 
|-
 
| {{text anchor|FUEL}}
 
| {{text anchor|FUEL}}
 +
|
 
|
 
|
 
| Requires that the reaction either use up a unit of coal or charcoal or else be performed at a magma workshop.
 
| Requires that the reaction either use up a unit of coal or charcoal or else be performed at a magma workshop.
Line 782: Line 826:
 
| {{text anchor|GLASS_MATERIAL}}
 
| {{text anchor|GLASS_MATERIAL}}
 
|
 
|
 +
| Reagent modifier
 
| Reagent material has [IS_GLASS].
 
| Reagent material has [IS_GLASS].
  
Line 787: Line 832:
 
| {{text anchor|HAS_EDGE}}{{version|0.42.01}}
 
| {{text anchor|HAS_EDGE}}{{version|0.42.01}}
 
|
 
|
 +
| Reagent modifier
 
| Reagent must be sharpened (used for carving).
 
| Reagent must be sharpened (used for carving).
  
 
|-
 
|-
 
| {{text anchor|HAS_ITEM_REACTION_PRODUCT}}
 
| {{text anchor|HAS_ITEM_REACTION_PRODUCT}}
−
| PRODUCT_ID (custom)
+
|
 +
* PRODUCT_ID (custom)
 +
| Reagent modifier
 
| Similar to HAS_MATERIAL_REACTION_PRODUCT, but requires the reagents material to have a matching ITEM_REACTION_PRODUCT entry.
 
| Similar to HAS_MATERIAL_REACTION_PRODUCT, but requires the reagents material to have a matching ITEM_REACTION_PRODUCT entry.
  
 
|-
 
|-
 
| {{text anchor|HAS_MATERIAL_REACTION_PRODUCT}}
 
| {{text anchor|HAS_MATERIAL_REACTION_PRODUCT}}
−
| PRODUCT_ID (custom)
+
|
 +
* PRODUCT_ID (custom)
 +
| Reagent modifier
 
| 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.
 
| 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.
  
 
|-
 
|-
 
| {{text anchor|HAS_TOOL_USE}}
 
| {{text anchor|HAS_TOOL_USE}}
−
| Tool-use token
+
|
 +
* [[Tool token|Tool-use token]]
 +
| Reagent modifier
 
| 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.
 
| 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.
  
Line 807: Line 859:
 
| {{text anchor|HAS_WRITING_IMPROVEMENT}}{{version|0.42.01}}
 
| {{text anchor|HAS_WRITING_IMPROVEMENT}}{{version|0.42.01}}
 
|  
 
|  
 +
| Reagent modifier
 
| Reagent must contain writing.
 
| Reagent must contain writing.
  
Line 816: Line 869:
 
* Improvement type
 
* Improvement type
 
* Material Token
 
* Material Token
 +
|
 
| Improvement types include BANDS, COVERED, GLAZED, RINGS_HANGING, and SPIKES
 
| Improvement types include BANDS, COVERED, GLAZED, RINGS_HANGING, and SPIKES
  
Line 821: Line 875:
 
| {{text anchor|MAGMA_BUILD_SAFE}}
 
| {{text anchor|MAGMA_BUILD_SAFE}}
 
|
 
|
 +
| Reagent modifier
 
| Currently broken - Reagent must be considered [[magma-safe]] (stable [[temperature]] below {{ct|12000}}).
 
| Currently broken - Reagent must be considered [[magma-safe]] (stable [[temperature]] below {{ct|12000}}).
  
 
|-
 
|-
 
| {{text anchor|MAX_MULTIPLIER}}{{version|0.42.01}}
 
| {{text anchor|MAX_MULTIPLIER}}{{version|0.42.01}}
−
| Number
+
|
 +
* Integer
 +
|
 
| 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.
 
| 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.
  
 
|-
 
|-
 
| {{text anchor|METAL_ORE}}
 
| {{text anchor|METAL_ORE}}
−
| Inorganic material
+
|
 +
* Inorganic material
 +
| Reagent modifier
 
| Reagent material must be an ore of the specified metal.
 
| Reagent material must be an ore of the specified metal.
  
 
|-
 
|-
 
| {{text anchor|MIN_DIMENSION}}
 
| {{text anchor|MIN_DIMENSION}}
−
| Integer
+
|
 +
* Integer
 +
| Reagent modifier
 
| Requires that the reagent have a dimension of at least this value. Only effective with BAR, POWDER_MISC, LIQUID_MISC, DRINK, THREAD, CLOTH, and GLOB items.
 
| Requires that the reagent have a dimension of at least this value. Only effective with BAR, POWDER_MISC, LIQUID_MISC, DRINK, THREAD, CLOTH, and GLOB items.
  
 
|-
 
|-
 
| {{text anchor|NAME}}
 
| {{text anchor|NAME}}
−
| Name
+
|
 +
* Name
 +
|
 
| Defines the name used by the reaction in-game.
 
| Defines the name used by the reaction in-game.
  
Line 846: Line 909:
 
| {{text anchor|NO_EDGE_ALLOWED}}
 
| {{text anchor|NO_EDGE_ALLOWED}}
 
|
 
|
 +
| Reagent modifier
 
| 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.
 
| 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.
  
Line 851: Line 915:
 
| {{text anchor|NOT_CONTAIN_BARREL_ITEM}}
 
| {{text anchor|NOT_CONTAIN_BARREL_ITEM}}
 
|
 
|
 +
| Reagent modifier
 
| 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.
 
| 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.
  
Line 856: Line 921:
 
| {{text anchor|NOT_ENGRAVED}}
 
| {{text anchor|NOT_ENGRAVED}}
 
|
 
|
 +
| Reagent modifier
 
| Reagent can not be engraved. For example, a memorial slab can not be engraved.
 
| Reagent can not be engraved. For example, a memorial slab can not be engraved.
 
|-
 
|-
 
| {{text anchor|NOT_IMPROVED}}
 
| {{text anchor|NOT_IMPROVED}}
 
|
 
|
 +
| Reagent modifier
 
| Reagent has not been decorated.
 
| Reagent has not been decorated.
  
Line 865: Line 932:
 
| {{text anchor|NOT_PRESSED}}
 
| {{text anchor|NOT_PRESSED}}
 
|
 
|
 +
| Reagent modifier
 
| Reagent must not be in the SOLID_PRESSED state.
 
| Reagent must not be in the SOLID_PRESSED state.
  
Line 870: Line 938:
 
| {{text anchor|NOT_WEB}}
 
| {{text anchor|NOT_WEB}}
 
|
 
|
 +
| Reagent modifier
 
| Reagent must be "collected" - used with THREAD:NONE to exclude webs.
 
| Reagent must be "collected" - used with THREAD:NONE to exclude webs.
  
Line 875: Line 944:
 
| {{text anchor|POTASHABLE}} (Deprecated)
 
| {{text anchor|POTASHABLE}} (Deprecated)
 
|
 
|
 +
| Reagent modifier
 
| Alias for CONTAINS_LYE.
 
| Alias for CONTAINS_LYE.
  
Line 880: Line 950:
 
| {{text anchor|PRESERVE_REAGENT}}
 
| {{text anchor|PRESERVE_REAGENT}}
 
|
 
|
 +
| Reagent modifier
 
| Reagent is not destroyed, which is the normal effect, at the completion of the reaction. Typically used for containers.
 
| Reagent is not destroyed, which is the normal effect, at the completion of the reaction. Typically used for containers.
  
Line 889: Line 960:
 
*Item token:subtype
 
*Item token:subtype
 
*Material token:subtype
 
*Material token:subtype
 +
|
 
| 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.
 
| 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.
  
 
|-
 
|-
 
| {{text anchor|PRODUCT_DIMENSION}}
 
| {{text anchor|PRODUCT_DIMENSION}}
−
| Size
+
|
 +
* Size
 +
| Product modifier
 
| Specifies the size of the product. A size of 150 is typical for BAR, POWDER_MISC, LIQUID_MISC, DRINK, and GLOB.  A size of 15000 is typical for THREAD, and a size of 10000 is typical for CLOTH.
 
| Specifies the size of the product. A size of 150 is typical for BAR, POWDER_MISC, LIQUID_MISC, DRINK, and GLOB.  A size of 15000 is typical for THREAD, and a size of 10000 is typical for CLOTH.
  
Line 899: Line 973:
 
| {{text anchor|PRODUCT_PASTE}}
 
| {{text anchor|PRODUCT_PASTE}}
 
|
 
|
 +
| Product modifier
 
| Product is created in the SOLID_PASTE state.
 
| Product is created in the SOLID_PASTE state.
  
Line 904: Line 979:
 
| {{text anchor|PRODUCT_PRESSED}}
 
| {{text anchor|PRODUCT_PRESSED}}
 
|
 
|
 +
| Product modifier
 
| Product is created in the SOLID_PRESSED state.
 
| Product is created in the SOLID_PRESSED state.
  
 
|-
 
|-
 
| {{text anchor|PRODUCT_TO_CONTAINER}}
 
| {{text anchor|PRODUCT_TO_CONTAINER}}
−
| Reagent ID
+
|
 +
* Reagent ID
 +
| Product modifier
 
| Places the product in a container; <id> must be the name of a reagent with the PRESERVE_REAGENT token and a container item type.
 
| Places the product in a container; <id> must be the name of a reagent with the PRESERVE_REAGENT token and a container item type.
  
 
|-
 
|-
 
| {{text anchor|PRODUCT_TOKEN}}{{version|0.42.01}}
 
| {{text anchor|PRODUCT_TOKEN}}{{version|0.42.01}}
−
| Name
+
|
 +
* Name
 +
| Product modifier
 
| Allows the product to be referred to by the given name, for the purpose of being passed down as argument in other tokens.
 
| Allows the product to be referred to by the given name, for the purpose of being passed down as argument in other tokens.
  
 
|-
 
|-
 
| {{text anchor|REACTION}}
 
| {{text anchor|REACTION}}
−
| Identifier
+
|
 +
* Identifier
 +
|
 
| Defines a new reaction.
 
| Defines a new reaction.
  
 
|-
 
|-
 
| {{text anchor|REACTION_CLASS}}
 
| {{text anchor|REACTION_CLASS}}
−
| CLASS_ID (custom)
+
|
 +
* CLASS_ID (custom)
 +
| Reagent modifier
 
| 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).
 
| 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).
  
Line 933: Line 1,017:
 
* [[Item token]]
 
* [[Item token]]
 
* [[Material token]]
 
* [[Material token]]
 +
|
 
| Specifies a given reagent as an input for a reaction.
 
| Specifies a given reagent as an input for a reaction.
  
 
|-
 
|-
 
| {{text anchor|SKILL}}
 
| {{text anchor|SKILL}}
−
| [[Skill token]]
+
|
 +
* [[Skill token]]
 +
|
 
| Skill used by the reaction.
 
| Skill used by the reaction.
  
 
|-
 
|-
 
| {{text anchor|SKILL_IP}}{{version|0.47.01}}
 
| {{text anchor|SKILL_IP}}{{version|0.47.01}}
−
| Integer
+
|
 +
* Integer
 +
| Skill modifier
 
| Amount of skill given per product made. Default is 30.  
 
| Amount of skill given per product made. Default is 30.  
  
Line 950: Line 1,039:
 
* Range
 
* Range
 
* Multiplier
 
* Multiplier
 +
| Skill modifier
 
| 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.
 
| 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.
  
Line 955: Line 1,045:
 
| {{text anchor|TRANSFER_ARTIFACT_STATUS}}{{version|0.42.01}}
 
| {{text anchor|TRANSFER_ARTIFACT_STATUS}}{{version|0.42.01}}
 
|  
 
|  
 +
| Product modifier
 
| Transfers artifact status from the reagent to the product.
 
| Transfers artifact status from the reagent to the product.
  
Line 960: Line 1,051:
 
| {{text anchor|UNROTTEN}}
 
| {{text anchor|UNROTTEN}}
 
|
 
|
 +
| Reagent modifier
 
| Reagent must not be rotten, mainly for organic materials.
 
| Reagent must not be rotten, mainly for organic materials.
  
Line 965: Line 1,057:
 
| {{text anchor|USE_BODY_COMPONENT}}
 
| {{text anchor|USE_BODY_COMPONENT}}
 
|
 
|
 +
| Reagent modifier
 
| Reagent material must come off a creature's body.
 
| Reagent material must come off a creature's body.
  
Line 970: Line 1,063:
 
| {{text anchor|WEB_ONLY}}
 
| {{text anchor|WEB_ONLY}}
 
|
 
|
 +
| Reagent modifier
 
| Reagent must be "undisturbed" - used with THREAD:NONE to gather webs.
 
| Reagent must be "undisturbed" - used with THREAD:NONE to gather webs.
  
Line 975: Line 1,069:
 
| {{text anchor|WORTHLESS_STONE_ONLY}}
 
| {{text anchor|WORTHLESS_STONE_ONLY}}
 
|
 
|
 +
| Reagent modifier
 
| Reagent is not made of an economic stone.
 
| Reagent is not made of an economic stone.
  

Revision as of 05:43, 24 April 2022

xTATTEREDx  · +FINE+  · *SUPERIOR*  · ≡EXCEPTIONAL≡  · ☼MASTERWORK☼
v50.14 · v0.47.05
This article is about the current version of DF.
Note that some content may still need to be updated.

Modding
Tokens
Audio · Biome · Graphics · Interaction · Mod info · Plant · Speech · Sphere · Syndrome · World
Body tokens
Body · Body detail plan · Bodygloss · Tissue
Creature tokens
Creature · Creature mannerism · Personality · Creature variation · Procedural graphics layer
Descriptor tokens
Descriptor color · Color · Descriptor pattern · Descriptor shape
Entity tokens
Entity · Ethic · Language · Value · Position
Job tokens
Building · Labor · Reaction · Skill · Unit type
Item tokens
Item type · Item definition · Ammo · Armor · Instrument · Tool · Trap component · Weapon
Material tokens
Material type · Material definition · Inorganic material definition
v · t · e


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 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 in the x menu via the create option, 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). 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

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 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 Adventure mode). 

   [BUILDING:<building name>:<building key>]
  • building name: The ID of the building the reaction appears in.
  • 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:

building key

This defines the shortcut key(s) used to queue up the reaction in the workshop during gameplay. It can be NONE for no shortcut, or take the format of CUSTOM_X, where X can be: any uppercase letter, which shows as a lowercase letter in the building UI, eg. "CUSTOM_A" creates the shortcut "a"; or a valid modifier key (ALT, CTRL, or SHIFT) followed by an uppercase letter, eg. CUSTOM_SHIFT_A.

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

Token Arguments Description
CATEGORY 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.

CATEGORY_NAME String The name of the category as displayed in-game.
CATEGORY_DESCRIPTION String Optional. If present, when the category is highlighted in a building menu, this string will be displayed in the Helpful Hint box.
CATEGORY_PARENT Category ID Optional. If present, this category will be a submenu of the indicated category, rather than a submenu of the reaction's building.
CATEGORY_KEY 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...]
  • 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

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

The quantity differs between item types. Generally speaking, cloth, thread, powder, bars, liquids 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.

If one of the reagents is in a stack, the reaction will use the entire stack and multiply the product--for example, using only 1 BAR instead of 150 BAR will multiply the product quantity by 150. One can see which items have what quantities in the description of the Reaction#PRODUCT_DIMENSION token.

item token

Item tokens 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).

material token

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

Modifiers

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

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.

A list of them follows:

Token Description
[REACTION_CLASS:X] Reagent material must have the specified reaction class - see below for more details.
[HAS_MATERIAL_REACTION_PRODUCT:X] Reagent material must have the specified material reaction product - see below for more details.
[HAS_ITEM_REACTION_PRODUCT:X] Reagent material must have the specified item reaction product - see below for more details. This can be used interchangeably with HAS_MATERIAL_REACTION_PRODUCT.
[CONTAINS:X] Reagent is a container that holds the specified reagent (where X is the name of the 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. 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]).
[POTASHABLE] (Deprecated) 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 solid and stable at temperatures approaching 11000. Only works with items of type BAR, BLOCKS, BOULDER, WOOD, and ANVIL - all others are considered unsafe.
[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.
[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.
[IS_SAND_MATERIAL] Reagent material must have the [SOIL_SAND] token.
[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.
[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.
[HAS_EDGE]v0.42.01 Reagent must have an edge.
[NOT_ENGRAVED] Reagent can not be engraved. For example, a memorial slab can not be engraved.
[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] Reagent material must have [ITEMS_HARD].
[METAL_ITEM_MATERIAL] Reagent material must have [ITEMS_METAL].
[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, CLOTH, or GLOB 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.

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

probability

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

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

Product modifiers

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

Token Description
[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 dimensions of the product. A product of 150 is typical for BAR, POWDER_MISC, LIQUID_MISC, DRINK, and GLOB. 15000 is typical for THREAD, and a size of 10000 is typical for CLOTH. Has no effect on any other item types. Note: this is not the actual volume of the product, which is hard-coded by the item token.
[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

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

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.

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 decoration's material to be derived from one of the reagents, 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 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.

Token Arguments Description
SKILL 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 always complete instantly.
SKILL_IP 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.
ATTRIBUTE_IPv0.47.01 Integer (Optional, requires SKILL token) This adjusts the amount of attribute gain that skill gain from this reaction results in. The default value is 10; higher values increase the amount of attribute gain.
SKILL_ROLE_RANGEv0.47.01 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].

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

max multiplier

The [MAX_MULTIPLIER:<#>] 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.v0.42.01

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's half-dozen different stones that count as flux. Instead of clogging up the smelter job menu with half-dozen 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:BOOT_FABRIC]
        [PRODUCT:100:1:SKIN_TANNED:NONE:GET_MATERIAL_FROM_REAGENT:flaps of skin:BOOT_FABRIC]
     [SKILL:TANNER]
     [AUTOMATIC]

Where you'd usually have some fresh bodypart with the BOOT_FABRIC 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 BOOT_FABRIC) 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:BOOT_FABRIC:LOCAL_CREATURE_MAT:LEATHER]
        [IMPLIES_ANIMAL_KILL]
        [ROTS]

It says that the caller of the BOOT_FABRIC hook always comes out as the LEATHER of whatever creature the skin has been peeled off of (LOCAL_CREATURE_MAT). Make it BOOT_FABRIC:INORGANIC:GOLD instead and your tanner turns into Midas. Use your imagination.

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

The version 0.40 added 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:BOX: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:

Token Arguments Type 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 modifier Reagent material must have the [BONE] token.
ANY_HORN_MATERIAL Reagent modifier Reagent material must have the [HORN] token.
ANY_LEATHER_MATERIAL Reagent modifier Reagent material must have the [LEATHER] token.
ANY_PEARL_MATERIAL Reagent modifier Reagent material must have the [PEARL] token.
ANY_PLANT_MATERIAL Reagent modifier Reagent material must be subordinate to a PLANT object.
ANY_SHELL_MATERIAL Reagent modifier Reagent material must have the [SHELL] token.
ANY_SILK_MATERIAL Reagent modifier Reagent material must have the [SILK] token.
ANY_SOAP_MATERIAL Reagent modifier Reagent material must have the [SOAP] token.
ANY_STRAND_TISSUE Reagent modifier 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 modifier Reagent material must have the [TOOTH] token.
ANY_YARN_MATERIAL Reagent modifier Reagent material must have the [YARN] token.
ATTRIBUTE_IPv0.47.01
  • Integer
 Skill modifier Amount of attribute gain given per skill improvement. Default is 10.
AUTOMATIC The reaction will be queued automatically if the reaction reagents are all present.
BAG Reagent modifier 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 modifier Reagent is able to be used to build structures (Stone, Wood, Blocks, Bars?).
CAN_USE_ARTIFACT Reagent modifier Reagent can be an Artifact. Using [PRESERVE_REAGENT] with this is strongly advised.
CAN_USE_HOSPITAL_RESERVEDv0.42.01 Reagent modifier Allows the reagent to be an item that is otherwise reserved for use by a hospital.
CAN_USE_LOCATION_RESERVEDv0.42.01 Reagent modifier Allows the reagent to be an item that is otherwise reserved for use by a location.
CATEGORYv0.42.01
  • Category ID
 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.

CATEGORY_NAMEv0.42.01
  • String
 Category The name of the category as displayed in-game.
CATEGORY_DESCRIPTIONv0.42.01
  • String
 Category If present, when the category is highlighted in a building menu, this string will be displayed in the Helpful Hint box.
CATEGORY_PARENTv0.42.01
  • Category ID
 Category If present, this category will be a submenu of the indicated category, rather than a submenu of the reaction's building.
CATEGORY_KEYv0.42.01
  • Hotkey
 Category If present, this category can be selected from its parent menu (whether a building or a parent category) using the given hotkey.
CONTAINS
  • Reagent name
 Reagent modifier Reagent is a container that holds the specified reagent.
CONTAINS_LYE (Deprecated) Reagent modifier 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].
DESCRIPTION
  • String
 Description of the reaction.
DOES_NOT_ABSORB Reagent modifier Reagent material must have [ABSORPTION:0].
DOES_NOT_DETERMINE_PRODUCT_AMOUNT Reagent modifier 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 Reagent modifier If the reagent is a container, it must be empty.
FIRE_BUILD_SAFE Reagent modifier Reagent must be considered fire-safe (stable temperature below 11000 °U ) - i.e. not wood, and not coal.
FORCE_EDGE Product modifier Product is given a sharp edge. Used for knapping.
FOOD_STORAGE_CONTAINER Reagent modifier Reagent must be a barrel or any non-absorbing tool with [TOOL_USE:FOOD_STORAGE].
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 modifier Reagent material has [IS_GLASS].
HAS_EDGEv0.42.01 Reagent modifier Reagent must be sharpened (used for carving).
HAS_ITEM_REACTION_PRODUCT
  • PRODUCT_ID (custom)
 Reagent modifier Similar to HAS_MATERIAL_REACTION_PRODUCT, but requires the reagents material to have a matching ITEM_REACTION_PRODUCT entry.
HAS_MATERIAL_REACTION_PRODUCT
  • PRODUCT_ID (custom)
 Reagent modifier Similar to REACTION_CLASS, but requires the reagents material to have a matching MATERIAL_REACTION_PRODUCT entry. Intended for reactions which transform one class of material into another, such as skin->leather and fat->tallow.
HAS_TOOL_USE Reagent modifier 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.
HAS_WRITING_IMPROVEMENTv0.42.01 Reagent modifier Reagent must contain writing.
IMPROVEMENT
  • Probability
  • Reagent Name
  • Improvement type
  • Material Token
 Improvement types include BANDS, COVERED, GLAZED, RINGS_HANGING, and SPIKES
MAGMA_BUILD_SAFE Reagent modifier Currently broken - Reagent must be considered magma-safe (stable temperature below 12000 °U ).
MAX_MULTIPLIERv0.42.01
  • Integer
 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.
METAL_ORE
  • Inorganic material
 Reagent modifier Reagent material must be an ore of the specified metal.
MIN_DIMENSION
  • Integer
 Reagent modifier Requires that the reagent have a dimension of at least this value. Only effective with BAR, POWDER_MISC, LIQUID_MISC, DRINK, THREAD, CLOTH, and GLOB items.
NAME
  • Name
 Defines the name used by the reaction in-game.
NO_EDGE_ALLOWED Reagent modifier 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.
NOT_CONTAIN_BARREL_ITEM Reagent modifier 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 modifier Reagent can not be engraved. For example, a memorial slab can not be engraved.
NOT_IMPROVED Reagent modifier Reagent has not been decorated.
NOT_PRESSED Reagent modifier Reagent must not be in the SOLID_PRESSED state.
NOT_WEB Reagent modifier Reagent must be "collected" - used with THREAD:NONE to exclude webs.
POTASHABLE (Deprecated) Reagent modifier Alias for CONTAINS_LYE.
PRESERVE_REAGENT Reagent modifier Reagent is not destroyed, which is the normal effect, at the completion of the reaction. Typically used for containers.
PRODUCT
  • Probability of success (%)
  • Quantity
  • Item token:subtype
  • Material token:subtype
 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.
PRODUCT_DIMENSION
  • Size
 Product modifier Specifies the size of the product. A size of 150 is typical for BAR, POWDER_MISC, LIQUID_MISC, DRINK, and GLOB. A size of 15000 is typical for THREAD, and a size of 10000 is typical for CLOTH.
PRODUCT_PASTE Product modifier Product is created in the SOLID_PASTE state.
PRODUCT_PRESSED Product modifier Product is created in the SOLID_PRESSED state.
PRODUCT_TO_CONTAINER
  • Reagent ID
 Product modifier Places the product in a container; <id> must be the name of a reagent with the PRESERVE_REAGENT token and a container item type.
PRODUCT_TOKENv0.42.01
  • Name
 Product modifier Allows the product to be referred to by the given name, for the purpose of being passed down as argument in other tokens.
REACTION
  • Identifier
 Defines a new reaction.
REACTION_CLASS
  • CLASS_ID (custom)
 Reagent modifier Requires the reagent's material to have a matching 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).
REAGENT Specifies a given reagent as an input for a reaction.
SKILL Skill used by the reaction.
SKILL_IPv0.47.01
  • Integer
 Skill modifier Amount of skill given per product made. Default is 30.
SKILL_ROLL_RANGEv0.47.01
  • Range
  • Multiplier
 Skill modifier 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.
TRANSFER_ARTIFACT_STATUSv0.42.01 Product modifier Transfers artifact status from the reagent to the product.
UNROTTEN Reagent modifier Reagent must not be rotten, mainly for organic materials.
USE_BODY_COMPONENT Reagent modifier Reagent material must come off a creature's body.
WEB_ONLY Reagent modifier Reagent must be "undisturbed" - used with THREAD:NONE to gather webs.
WORTHLESS_STONE_ONLY Reagent modifier Reagent is not made of an economic stone.
Retrieved from "https://dwarffortresswiki.org/index.php?title=Reaction&oldid=263744"