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
(If anyone wants to go through and add more links, that would be lovely. I'm intending to do up a proper reaction class/material reaction product tutorial to add to this, so the last bit is vague.)
Line 1: Line 1:
−
{{av}}
+
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.
−
{{Quality|Exceptional}}
 
−
'''Reactions''' are moddable crafting formulas. They can be tweaked and added onto to allow smelting of new metals, alloys, and many other products. They must be assigned to specific [[Entities]]; if not explicitly added to an entity's definition, they will not be able to produce that reaction. For examples of various forms of reaction, see {{l|Reaction Examples}}.
 
  
−
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 to be determined.
+
== Reaction differences between modes ==
 +
In [[Fortress mode]], reactions are linked to specific buildings, and must be added to a civilizations [[Entities|entity file]] to be useable 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 - meaning that if you give your custom civilization a reaction to produce star metal or some other custom material, only they will be 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 stored within a backpack or quiver.  As of .10, there are several bugs with Adventure mode reactions, chief of which is the fact that the [HAS_MATERIAL_REACTION_PRODUCT] token is completely ignored, leading to dragon eye tissue tanned hides, among other things.
−
[REACTION:<REACTION_IDENTIFIER>]
 
−
[NAME:<REACTION_NAME>]
 
−
<... [[#Buildings]] One or more building references ...>
 
−
  <... [[#Reagents]] Zero or more reagent declarations ...>
 
−
<... [[#Products]] Zero or more product declarations ...>
 
−
<... [[#Reaction Modifiers]] Zero or more reaction modifiers ...>
 
−
  <... [[#Skills]] Zero or more skill references ...>
 
  
−
'''<REACTION_IDENTIFIER>''' - Refers to a unique identifier for the reaction (Used in Entity Raws to allow an Entity 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 to be determined.
  
−
'''<REACTION_NAME>''' - String displayed in the building for the reaction.
+
==Anatomy of a reaction==
  
−
==Entity Use==
+
Reactions are found within reaction_x files (such as reaction_smelter or reaction_other).  Generally speaking they adhere to the following structure:
−
In order for an entity to use the reaction a [PERMITTED_REACTION:] tag must be added.  It works by using the '''<REACTION_IDENTIFIER>''' after the colon.
 
−
[PERMITTED_REACTION:<REACTION_IDENTIFIER>]
 
  
−
==Buildings==
+
  [REACTION:<REACTION IDENTIFIER>]
−
Each reaction requires a building to be declared for it to be used at.
+
      [NAME:<REACTION NAME>]
 +
      [BUILDING:<BUILDING NAME>:<BUILDING KEY>]
 +
            The building that the reaction uses, and the relevant
 +
            keyboard shortcut.
 +
      [REAGENT:A:150:BAR:NONE:POTASH:NONE]
 +
            The ingredients required for the reaction.
 +
      [PRODUCT:100:1:BAR:NONE:PEARLASH:NONE][PRODUCT_DIMENSION:150]
 +
            The exact item produced by the reaction.
 +
      [FUEL]
 +
            Whether or not the reaction requires charcoal, coke or
 +
            a magma-powered workshop.
 +
      [#SKILL:<SKILL TOKEN>]
 +
            The skill required and trained by the reaction.
 +
      [AUTOMATIC]
  
−
[BUILDING:<BUILDING_IDENTIFIER>:<BUILDING_KEY>]
+
The <REACTION IDENTIFIER> may be anything, so long as it is unique within the raws - a good habit to get into is to append a short term to the end of 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.
  
−
'''<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}}
+
The <REACTION NAME> 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.
  
−
'''<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 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.
  
−
==Reagents==
+
=== Reagents ===
−
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.
+
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 so long as they all have unique names.
  
−
===Reagent Types===
+
    [REAGENT:<name>:<quantity>:<item token>:<item subtype>:<material token>:<material subtype>]
−
[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.
+
The name field is just a small string used to refer to the reagent within the reaction; 'A' or 'B' work, as do words like 'toolstone' or 'flux' - remember not to use apostrophes, though.
  
−
Type 2: Is used for when only a material type is needed, such as METAL_ORE for smelter reactions.
+
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.  For example, 10 thread is one extremely tiny unit of thread, but 10 toy is ten unique, solid toy items.
  
−
<Identifier> - Used to refer to this reagent in the reaction Product.
+
The item token is the type of item you require - WEAPON, TOY or SKIN_TANNED, for example.
  
−
<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).
+
The item subtype is the exact item that you require - ITEM_WEAPON_SPEAR or ITEM_TOY_PUZZLEBOX, as examples. 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 can leave this blank.
  
−
<ITEM_TOKEN> - Refers to the hard coded {{l|Item tokens|item token}} that the reagent must be.
+
The material token and material subtype are frequently related.  The first indicates the category of material you want, such as INORGANIC.  The second indicates the specific subtype of material you want, such as OBSIDIAN or STEEL.
  
−
<ITEM_SUBTYPE> - Refers to a specific item subtype, defined in the raws, of a specific ITEM_TOKEN, such as TOY:ITEM_TOY_MINIFORGE.
+
Reagents may also have extra tokens added on afterwards.  A list of them follows:
  
−
<MATGLOSS_TOKEN> - Refers to the hard coded material type {{l|Matgloss token| token}} of the reagent, such as PLANT_MAT, METAL_ORE, etc.
+
{| {{prettytable}}
 +
|- bgcolor="#dddddd"
 +
! Token
 +
! Meaning
 +
|-
 +
| [PRESERVE_REAGENT]
 +
| Reagent is not destroyed, which is the normal effect, at the completion of the reaction. Typically used for containers.
 +
|-
 +
| [REACTION_CLASS:X]
 +
| Detailed below the reaction anatomy section.
 +
|-
 +
| [HAS_MATERIAL_REACTION_PRODUCT:X]
 +
| Detailed below the reaction anatomy section.
 +
|-
 +
| [UNROTTEN]
 +
| Reagent must not be rotten, mainly for organic MATGLOSS types.
 +
|-
 +
| [BUILDMAT]
 +
| Reagent is able to be used to build structures (Stone, Wood, Blocks, Bars?).
 +
|-
 +
| [GLASS_MATERIAL]
 +
| Reagent has a one of the glass MATGLOSS types.
 +
|-
 +
| [WORTHLESS_STONE_ONLY]
 +
| The reagent respects allowed and forbidden economic stones from the Stone menu.
 +
|-
 +
| [FIRE_BUILD_SAFE]
 +
| Reagent must be considered fire safe - ie. not wood, and not coal.
 +
|-
 +
| [MAGMA_BUILD_SAFE]
 +
| Reagent must have a melting point greater than the temperature of Magma.
 +
|-
 +
| [CAN_USE_ARTIFACT]
 +
| Reagent can be an Artifact.  Using [PRESERVE_REAGENT] with this is strongly advised.
 +
|-
 +
| [ANY_PLANT_MATERIAL]
 +
| Reagent MATGLOSS must be of a plant subtype.
 +
|-
 +
| [ANY_SILK_MATERIAL]
 +
| Reagent MATGLOSS must be of a silk type.
 +
|-
 +
| [ANY_SOAP_MATERIAL]
 +
| Reagent MATGLOSS must be of a soap type.
 +
|-
 +
| [ANY_LEATHER_MATERIAL]
 +
| Reagent MATGLOSS must be of a leather type.
 +
|-
 +
| [ANY_BONE_MATERIAL]
 +
| Reagent MATGLOSS must be of a bone type.
 +
|-
 +
| [ANY_SHELL_MATERIAL]
 +
| Reagent MATGLOSS must be of a shell type.
 +
|-
 +
| [ANY_TOOTH_MATERIAL]
 +
| Reagent MATGLOSS must be of a tooth type.
 +
|-
 +
| [ANY_HORN_MATERIAL]
 +
| Reagent MATGLOSS must be of a horn type.
 +
|-
 +
| [ANY_PEARL_MATERIAL]
 +
| Reagent MATGLOSS must be of a pearl type (Excretion from sea creatures?)
 +
|-
 +
| [USE_BODY_COMPONENT]
 +
| Reagent MATGLOSS must come off a creature's body.
 +
|-
 +
| [METAL_ORE]
 +
| Reagent MATGLOSS must be a metal ore.
 +
|-
 +
| [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?).
 +
|-
 +
| [POTASHABLE]
 +
| The reagent must be able to be turned into pot ash.
 +
|-
 +
| [EMPTY]
 +
| If the reagent is a container, it must be empty.
 +
|-
 +
| [CONTAINS_LYE]
 +
| If the reagent is a container, it must contain LYE.
 +
|-
 +
| [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?).
 +
|-
 +
| [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.
 +
|}
  
−
<MATGLOSS_SUBTYPE> - Refers to a specific item {{l|Matgloss subtypes|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>.
+
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 matgloss fields as NONE:NONE, it will grab any available BOULDER-type item irrespective of matgloss.
  
−
''<PLANT_NAME>'' - Refers to the actual plant's name in the raw files.
+
===Products===
 +
Products are the end product of the reaction.  A reaction can have as many products as it likes.
  
−
''<PLANT_PART>'' - Refers to the plant 'part' you want, whether it's the PLANT, WOOD, LEAVES, SEED, etc.
+
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 also don't use tokens like USE_ANY_BONE_MATERIAL.
  
−
===Reagent Modifier===
+
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.
−
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.
+
===Other tokens===
 +
The [FUEL] token means that the reaction requires coke or charcoal to be performed, or theoretically magma, if we could build magma workshops.
  
−
'''[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 [SKILL:X] token determines what [[Skill tokens|skill]] the reaction requires and what skill it trains.  Multiple skills can be listed but only one will be used.
  
−
'''[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.
+
The [AUTOMATIC] token means that the reaction will be queued automatically if the reaction reagents are all present.
  
−
'''[UNROTTEN]''' - Reagent must not be rotten, mainly for organic MATGLOSS types.
+
==Material reaction products and reaction classes==
  
−
'''[BUILDMAT]''' - Reagent is able to be used to build structures (Stone, Wood, Blocks, Bars?).
+
You can get a certain measure of control over very specific materials using reaction classes and material reaction products - the tokens look like this:
  
−
'''[GLASS_MATERIAL]''' - Reagent has a one of the glass MATGLOSS types.
+
  [REACTION_CLASS:FAT]
 +
  [HAS_MATERIAL_REACTION_PRODUCT:RENDER_MAT]
  
−
'''[WORTHLESS_STONE_ONLY]''' - Only use objects allowed in the Stone Menu.
+
Reaction classes represent different classes of material - basically, the matgloss subtype of the reagent must have a REACTION_CLASS the same as the one in the reaction.
  
−
'''[FIRE_BUILD_SAFE]''' - Reagent must be considered fire safe (INORGANIC, excluding COAL types).
+
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.
  
−
'''[MAGMA_BUILD_SAFE]''' - Reagent must be considered magma safe (INORGANIC, with a melting point greater than the temperature of Magma.
+
In short, they require the material to have a token such as
 +
  [MATERIAL_REACTION_PRODUCT:X:Y:Z]
 +
...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), Y is the matgloss type of the desired product (such as INORGANIC or LOCAL_CREATURE_MAT) and Z is the specific material, like LEATHER or OBSIDIAN.
  
−
'''[CAN_USE_ARTIFACT]''' - Reagent can be an Artifact.
+
==Reactions and world generation==
  
−
'''[ANY_PLANT_MATERIAL]''' - Reagent MATGLOSS must be of a plant subtype.
+
There are several things to keep in mind when you're adding reactions to a game that already exists.
  
−
'''[ANY_SILK_MATERIAL]''' - Reagent MATGLOSS must be of a silk type.
+
- Most entity changes require a regen, but adding PERMITTED_REACTION tokens for reactions that existed at the time of world generation to a the entity file in the save directory do not.
−
 
+
- Adding reactions to the raws in a save directory requires you to regen the world.
−
'''[ANY_SOAP_MATERIAL]''' - Reagent MATGLOSS must be of a soap type.
+
- 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.
−
 
 
−
'''[ANY_LEATHER_MATERIAL]''' - Reagent MATGLOSS must be of a leather type.
 
−
 
 
−
'''[ANY_BONE_MATERIAL]''' - Reagent MATGLOSS must be of a bone type.
 
−
 
 
−
'''[ANY_SHELL_MATERIAL]''' - Reagent MATGLOSS must be of a shell type.
 
−
 
 
−
'''[ANY_TOOTH_MATERIAL]''' - Reagent MATGLOSS must be of a tooth type.
 
−
 
 
−
'''[ANY_HORN_MATERIAL]''' - Reagent MATGLOSS must be of a horn type.
 
−
 
 
−
'''[ANY_PEARL_MATERIAL]''' - Reagent MATGLOSS must be of a pearl type (Excretion from sea creatures?)
 
−
 
 
−
'''[USE_BODY_COMPONENT]''' - Reagent MATGLOSS must come off a creature's body.
 
−
 
 
−
'''[METAL_ORE]''' - Reagent MATGLOSS must be a metal ore.
 
−
 
 
−
'''[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?).
 
−
 
 
−
'''[POTASHABLE]''' - The reagent must be able to be turned into pot ash.
 
−
 
 
−
'''[EMPTY]''' - If the reagent is a container, it must be empty.
 
−
 
 
−
'''[CONTAINS_LYE]''' - If the reagent is a container, it must contain LYE.
 
−
 
 
−
'''[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?).
 
−
 
 
−
'''[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.
 
−
 
 
−
==Products==
 
−
These are the results of a given reaction. There may be any number of such results.
 
−
 
 
−
===Product Format===
 
−
[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.
 
−
 
 
−
'''<QUANTITY>''' - This is the number of the item to be created.
 
−
 
 
−
'''<ITEM_TOKEN>''' - This is the ITEM_TOKEN of the result.
 
−
 
 
−
'''<ITEM_SUBTYPE>''' - This is a ITEM_SUBTYPE listed in an actual Raw File.
 
−
 
 
−
'''<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.
 
−
 
 
−
'''<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.
 
−
 
 
−
Note that vermin can be created by using code similar to: [PRODUCT:100:1:VERMIN:NO_SUBTYPE:ROACH_LARGE:ROACH_LARGE]
 
−
 
 
−
===Product Modifiers===
 
−
Each product may have a zero, or more, modifiers following its declaration.
 
−
 
 
−
'''[PRODUCT_TO_CONTAINER:<IDENTIFIER>]''' - This states that the product should be put into a specific container listed in as a reagent.
 
−
 
 
−
''<IDENTIFIER>'' - Refers back to a reagent identifier.
 
−
 
 
−
'''[PRODUCT_DIMENSION:<DIMENSION>]''' - Used to specify the dimensions of the object, primarily for use with bars, threads, and cloth.
 
−
 
 
−
''<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}}
 
−
 
 
−
==Reaction Modifiers==
 
−
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.
 
−
 
 
−
'''[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. This tag will also work on reactions that do not have reagent requirements.
 
−
 
 
−
==Skills==
 
−
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.
 
−
 
 
−
[SKILL:<SKILL_TOKEN>]
 
−
 
 
−
'''<SKILL_TOKEN>''' - This is SKILL_TOKEN for the reaction.
 
−
 
 
−
{{Category|Modding}}
 

Revision as of 13:52, 14 July 2010

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

In Fortress mode, reactions are linked to specific buildings, and must be added to a civilizations entity file to be useable 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 - meaning that if you give your custom civilization a reaction to produce star metal or some other custom material, only they will be 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 stored within a backpack or quiver. As of .10, there are several bugs with Adventure mode reactions, chief of which is the fact that the [HAS_MATERIAL_REACTION_PRODUCT] token is completely ignored, leading to dragon eye tissue tanned hides, among other things.

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 to be determined.

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:<REACTION IDENTIFIER>]
     [NAME:<REACTION NAME>]
     [BUILDING:<BUILDING NAME>:<BUILDING KEY>] 
           The building that the reaction uses, and the relevant 
           keyboard shortcut.
     [REAGENT:A:150:BAR:NONE:POTASH:NONE] 
           The ingredients required for the reaction.
     [PRODUCT:100:1:BAR:NONE:PEARLASH:NONE][PRODUCT_DIMENSION:150] 
           The exact item produced by the reaction.
     [FUEL] 
           Whether or not the reaction requires charcoal, coke or 
           a magma-powered workshop.
     [#SKILL:<SKILL TOKEN>] 
           The skill required and trained by the reaction.
     [AUTOMATIC]

The <REACTION IDENTIFIER> may be anything, so long as it is unique within the raws - a good habit to get into is to append a short term to the end of 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.

The <REACTION NAME> 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.

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.

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 so long as they all have unique names. 

   [REAGENT:<name>:<quantity>:<item token>:<item subtype>:<material token>:<material subtype>]

The name field is just a small string used to refer to the reagent within the reaction; 'A' or 'B' work, as do words like 'toolstone' or 'flux' - remember not to use apostrophes, though.

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. For example, 10 thread is one extremely tiny unit of thread, but 10 toy is ten unique, solid toy items.

The item token is the type of item you require - WEAPON, TOY or SKIN_TANNED, for example.

The item subtype is the exact item that you require - ITEM_WEAPON_SPEAR or ITEM_TOY_PUZZLEBOX, as examples. 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 can leave this blank.

The material token and material subtype are frequently related. The first indicates the category of material you want, such as INORGANIC. The second indicates the specific subtype of material you want, such as OBSIDIAN or STEEL.

Reagents may also have extra tokens added on afterwards. A list of them follows:

Token Meaning
[PRESERVE_REAGENT] Reagent is not destroyed, which is the normal effect, at the completion of the reaction. Typically used for containers.
[REACTION_CLASS:X] Detailed below the reaction anatomy section.
[HAS_MATERIAL_REACTION_PRODUCT:X] Detailed below the reaction anatomy section.
[UNROTTEN] Reagent must not be rotten, mainly for organic MATGLOSS types.
[BUILDMAT] Reagent is able to be used to build structures (Stone, Wood, Blocks, Bars?).
[GLASS_MATERIAL] Reagent has a one of the glass MATGLOSS types.
[WORTHLESS_STONE_ONLY] The reagent respects allowed and forbidden economic stones from the Stone menu.
[FIRE_BUILD_SAFE] Reagent must be considered fire safe - ie. not wood, and not coal.
[MAGMA_BUILD_SAFE] Reagent must have a melting point greater than the temperature of Magma.
[CAN_USE_ARTIFACT] Reagent can be an Artifact. Using [PRESERVE_REAGENT] with this is strongly advised.
[ANY_PLANT_MATERIAL] Reagent MATGLOSS must be of a plant subtype.
[ANY_SILK_MATERIAL] Reagent MATGLOSS must be of a silk type.
[ANY_SOAP_MATERIAL] Reagent MATGLOSS must be of a soap type.
[ANY_LEATHER_MATERIAL] Reagent MATGLOSS must be of a leather type.
[ANY_BONE_MATERIAL] Reagent MATGLOSS must be of a bone type.
[ANY_SHELL_MATERIAL] Reagent MATGLOSS must be of a shell type.
[ANY_TOOTH_MATERIAL] Reagent MATGLOSS must be of a tooth type.
[ANY_HORN_MATERIAL] Reagent MATGLOSS must be of a horn type.
[ANY_PEARL_MATERIAL] Reagent MATGLOSS must be of a pearl type (Excretion from sea creatures?)
[USE_BODY_COMPONENT] Reagent MATGLOSS must come off a creature's body.
[METAL_ORE] Reagent MATGLOSS must be a metal ore.
[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?).
[POTASHABLE] The reagent must be able to be turned into pot ash.
[EMPTY] If the reagent is a container, it must be empty.
[CONTAINS_LYE] If the reagent is a container, it must contain LYE.
[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?).
[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.

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 matgloss fields as NONE:NONE, it will grab any available BOULDER-type item irrespective of matgloss.

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 also don't use tokens like USE_ANY_BONE_MATERIAL.

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.

Other tokens

The [FUEL] token means that the reaction requires coke or charcoal to be performed, or theoretically magma, if we could build magma workshops.

The [SKILL:X] token determines what skill the reaction requires and what skill it trains. Multiple skills can be listed but only one will be used.

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

Material reaction products and reaction classes

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 matgloss subtype 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:Z]

...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), Y is the matgloss type of the desired product (such as INORGANIC or LOCAL_CREATURE_MAT) and Z is the specific material, like LEATHER or OBSIDIAN.

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

Retrieved from "https://dwarffortresswiki.org/index.php?title=v0.31:Reactions&oldid=121498"