Reaction

Реакции — модульные, редактируемые формулы (рецепты), расходующие конкретные ингредиенты, или реагенты, и использующие их для получения желаемого предмета. Многие реакции жёстко закодированы — строительство кроватей или создание стекла, например, — но некоторые из них свободно редактируются, и очень просто добавить дополнительные реакции.

Данная статья помечена как не оконченная. Вы можете прочитать эту статью на английском или помочь проекту её переводом.

Различия реакций между режимами

В Режиме Крепости, реакции всегда задаются для конкретных строений, а так же обязательно должны быть упомянуты в entity-файле описания Цивилизации, для того, чтобы они могли быть использованы данной цивилизацией. Это полезно иметь ввиду, если вы захотите ограничить использование новых предметов и/или материалов (разрешить использовать только древесину, металлы и т.п.) какими-либо цивилизациями -- вы сможете, например, дать возможность вашей новой цивилизации производить звездный металл и тому подобное, что будет доступно только ей.

В Режиме Приключения, реакции свободно доступны к применению для любого героя через комбинацию X - Create. Реагенты для реакции должны находиться в руках или лежать под ногами, но не могут быть использованы, если находятся в рюкзаке или колчане. В версии .10 у реакций в Режиме Приключения существует несколько ошибок, главная из которых заключается в том, что вы не можете использовать жидкие реагенты.

До версии 31.10 результатом реакции мог стать предмет с базовым уровнем качества. Однако, уже в .10 версии у предметов созданных в результате реакций обнаружены модификаторы качества. На определение качества предмета влияет стандартный механизм уровня используемого навыка точно таким же образом, как и для обычных предметов ^v0.31.21.

Анатомия реакции

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.

Идентификатор реакции

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 can be anything at all, and is usually used to describe the reaction. Tan a hide, for example, is the name of the default leather-producing reaction. Generally this should be written as a small descriptive verb phrase, with the first letter capitalised, for consistency with the existing reactions.

Постройка

   [BUILDING:<BUILDING NAME>:<BUILDING KEY>]

• name: The ID of the building where this reaction will appear in the tasks menu.
• key: The keyboard shortcut used to queue up the reaction.

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

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

Реагенты

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

Название

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

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

Количество

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

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

Токен предмета

Item tokens are of the form ITEM_TYPE:ITEM_SUBTYPE.

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

For reagents, the item token can also be set to ANY_RAW_MATERIAL:NONE (to permit POWDER_MISC, BAR, BOULDER, or GLOB^{Требует проверки}) or ANY_CRAFT:NONE (to permit FIGURINE, AMULET, SCEPTER, CROWN, RING, EARRING, or BRACELET). These special values cannot be used in any other context.

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

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

Токен материала

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

Модификаторы

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

A list of them follows:

Token	Meaning
[REACTION_CLASS:X]	Detailed below the reaction anatomy section.
[HAS_MATERIAL_REACTION_PRODUCT:X]	Detailed below the reaction anatomy section.
[CONTAINS:X]	Reagent is a container that holds the specified reagent.
[UNROTTEN]	Reagent must not be rotten, mainly for organic materials.
[CONTAINS_LYE]	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].
[POTASHABLE]	Alias for [CONTAINS_LYE].
[NOT_WEB]	States that the reagent must have been collected (to distinguish silk thread from webs).
[WEB_ONLY]	States that the reagent must be undisturbed (to distinguish silk thread from webs).
[EMPTY]	If the reagent is a container, it must be empty.
[NOT_CONTAIN_BARREL_ITEM]	If the reagent is a Barrel, it must not contain an item that has to reside in a barrel. Barrel items appear to be lye and milk. Alcohol appears to be covered as part of [EMPTY]. A reaction which places an item in a barrel should probably have both tags.
[BAG]	Reagent has to be a bag — that is, made of cloth or leather. Intended to be used with an item type of BOX:NONE, to prevent chests, coffers, and other containers from being used instead.
[GLASS_MATERIAL]	Reagent material must have the [IS_GLASS] token. All 3 types of glass have this token hardcoded.
[BUILDMAT]	Reagent must be a building material (Stone, Wood, Blocks, Bars?).
[FIRE_BUILD_SAFE]	Reagent material's IGNITE_POINT must be set to "NONE".
[MAGMA_BUILD_SAFE]	Reagent must be magma-safe. Currently broken — behaves exactly the same as [FIRE_BUILD_SAFE].
[CAN_USE_ARTIFACT]	Reagent can be an Artifact. Using [PRESERVE_REAGENT] with this is strongly advised.
[WORTHLESS_STONE_ONLY]	Reagent material must be non-economic.
[ANY_PLANT_MATERIAL]	Reagent material must be subordinate to a PLANT object.
[ANY_SILK_MATERIAL]	Reagent material must have the [SILK] token.
[ANY_YARN_MATERIAL]	Reagent material must have the [YARN] token.
[ANY_SOAP_MATERIAL]	Reagent material must have the [SOAP] token.
[ANY_LEATHER_MATERIAL]	Reagent material must have the [LEATHER] token.
[ANY_BONE_MATERIAL]	Reagent material must have the [BONE] token.
[ANY_STRAND_TISSUE]	Reagent is made of a tissue having [TISSUE_SHAPE:STRANDS], intended for matching hair and wool. Must be used with [USE_BODY_COMPONENT].
[ANY_SHELL_MATERIAL]	Reagent material must have the [SHELL] token.
[ANY_TOOTH_MATERIAL]	Reagent material must have the [TOOTH] token.
[ANY_HORN_MATERIAL]	Reagent material must have the [HORN] token.
[ANY_PEARL_MATERIAL]	Reagent material must have the [PEARL] token.
[USE_BODY_COMPONENT]	Reagent must be a body part.
[NO_EDGE_ALLOWED]	Reagent must not be sharpened (used for knapping).
[NOT_ENGRAVED]	? (May be used for memorial slabs?)
[NOT_IMPROVED]	Reagent has not been decorated.
[DOES_NOT_ABSORB]	Reagent material must have [ABSORPTION:0]
[FOOD_STORAGE_CONTAINER]	Reagent is either a BARREL or a TOOL with the FOOD_STORAGE use.
[HARD_ITEM_MATERIAL]	Material has the [ITEMS_HARD] token.Требует проверки
[NOT_PRESSED]	Reagent must not be in the SOLID_PRESSED state.
[METAL_ORE:X]	Reagent material must be an ore of the specified metal.
[MIN_DIMENSION:X]	?
[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]	This will make the reagent mass not modify the product amount (useful for metal bars -> other objects)

Generally speaking, if you set a field in a reagent to NONE, the reaction won't discriminate when it comes to that particular field. For example, if you require a BOULDER reagent but leave the material as NONE:NONE, it will grab any available BOULDER-type item regardless of material.

Продукты

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

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

Products can be produced directly to a container using the [PRODUCT_TO_CONTAINER:<IDENTIFIER>] token, where the IDENTIFIER is the name of a reagent. This requires the reagent to have the PRESERVE_REAGENT token.

Restating this in the above style, we have:

  [PRODUCT:<probability>:<quantity>:<item token>:<material token>][...modifiers...][PRODUCT_DIMENSION:X][PRODUCT_TO_CONTAINER:<IDENTIFIER>]

Вероятность

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

Количество

Determines how many of the product will be produced.

Токен предмета

The item token and subtype of the item you produce.

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

Токен материала

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

Модификаторы продукта

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

Token	Meaning
[FORCE_EDGE]	Product is given a sharp edge. Used for knapping.
[PRODUCT_PASTE]	Product is created in the SOLID_PASTE state.
[PRODUCT_PRESSED]	Product is created in the SOLID_PRESSED state.
[PRODUCT_DIMENSION:<size>]	Specifies the size of the product. A size of 150 is typical for BAR, POWDER_MISC, LIQUID_MISC, and DRINK. A size of 15000 is typical for THREAD, and a size of 10000 is typical for CLOTH.
[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 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>]

Вероятность

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

Название реагента

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

Тип улучшения

The following improvement types can be used:

Token	Meaning
COVERED	Item is encrusted/studded/decorated with <material>.
GLAZED	Item is glazed with <material>.
RINGS_HANGING	Item is adorned with hanging rings of <material>.
BANDS	Item is encircled with bands of <material>.
SPIKES	Item menaces with spikes of <material>.

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

Токен материала

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

Другие токены

fuel

The FUEL token means that the reaction requires coke or charcoal to be performed. If the reaction is performed at a Kiln or a Smelter, it can also be performed at a Magma Kiln or Magma Smelter without requiring fuel.

skill

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

automatic

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

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.

Материал продуктов реакции и классы реакций

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

  [REACTION_CLASS:FAT]
  [HAS_MATERIAL_REACTION_PRODUCT:RENDER_MAT]

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

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

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

  [MATERIAL_REACTION_PRODUCT:X:Y]

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

Реакции и генерация мира

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.

Полный список токенов

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

Token	Arguments	Description
ADVENTURE_MODE_ENABLED		this version of the reaction is not used by dwarves at home in a fortress, but rather the wanderers of Adventure Mode. When using this token, it will be allowed for adventurers of any race, without editing Entity files
ANY_BONE_MATERIAL		Reagent material must have the [BONE] token.
ANY_HORN_MATERIAL		Reagent material must have the [HORN] token.
ANY_LEATHER_MATERIAL		Reagent material must have the [LEATHER] token.
ANY_PEARL_MATERIAL		Reagent material must have the [PEARL] token.
ANY_PLANT_MATERIAL		Reagent material must be subordinate to a PLANT object.
ANY_SHELL_MATERIAL		Reagent material must have the [SHELL] token.
ANY_SILK_MATERIAL		Reagent material must have the [SILK] token.
ANY_SOAP_MATERIAL		Reagent material must have the [SOAP] token.
ANY_STRAND_TISSUE		Reagent is made of a tissue having [TISSUE_SHAPE:STRANDS], intended for matching hair and wool. Must be used with [USE_BODY_COMPONENT].
ANY_TOOTH_MATERIAL		Reagent material must have the [TOOTH] token.
ANY_YARN_MATERIAL		Reagent material must have the [YARN] token.
AUTOMATIC		the reaction will be queued automatically if the reaction reagents are all present.
BAG		Reagent has to be a bag. Intended to be used with an item type of BOX, to prevent chests, coffers, and other containers from being used instead.
BUILDING	Building name in-building reaction hotkey	Sets the building that the reaction will be performed in, and the button used to queue the reaction once that building's menu is accessed in-game
BUILDMAT		Reagent is able to be used to build structures (Stone, Wood, Blocks, Bars?).
CAN_USE_ARTIFACT		Reagent can be an Artifact. Using [PRESERVE_REAGENT] with this is strongly advised.
CONTAINS	required content	Reagent is a container that holds the specified reagent.
CONTAINS_LYE		If the reagent is a container, it must contain LYE. No longer used — instead, use one reagent for the LYE itself and another reagent with [CONTAINS:lye_reagent].
DOES_NOT_ABSORB		Reagent material must have [ABSORPTION:0]
DOES_NOT_DETERMINE_PRODUCT_AMOUNT		Setting this dis-allows the quantity of a reagent (probably first in the list) to determine the output quantity. Used where the input is a stack, e.g. liquids in a barrel.
EMPTY		If the reagent is a container, it must be empty.
FIRE_BUILD_SAFE		Reagent must be considered fire safe — ie. not wood, and not coal.
FORCE_EDGE		Product is given a sharp edge. Used for knapping.
FUEL		Requires that the reaction either use up a unit of coal or charcoal or else be performed at a magma workshop
GLASS_MATERIAL		Reagent material has [IS_GLASS].
HAS_MATERIAL_REACTION_PRODUCT	required reaction product
HAS_TOOL_USE	Tool-use token	Reagent must be a tool with the specific TOOL_USE value. The reagent's item type must be TOOL:NONE for this to make any sense.
IMPROVEMENT	Probability Reagent Name Improvement type Material Token	Improvement types include BANDS, COVERED, GLAZED, RINGS_HANGING, and SPIKES
MAGMA_BUILD_SAFE		Currently broken — behaves exactly the same as FIRE_BUILD_SAFE.
METAL_ORE	Inorganic material	Reagent material must be an ore of the specified metal
MIN_DIMENSION		?
NAME	name	defines the name used by the reaction in-game
NO_EDGE_ALLOWED		Reagent must not be sharpened (used for knapping).
NOT_CONTAIN_BARREL_ITEM		If the reagent is a Barrel, it must not contain an item that has to reside in a barrel. Barrel items appear to be lye and milk. Alcohol appears to be covered as part of [EMPTY]. A reaction which places an item in a barrel should probably have both tags.
NOT_ENGRAVED		Reagent must not be engraved?
NOT_IMPROVED		Reagent has not been decorated.
NOT_PRESSED		Reagent must not be in the SOLID_PRESSED state.
NOT_WEB		Reagent must be "collected" — used with THREAD:NONE to exclude webs.
POTASHABLE		Alias for CONTAINS_LYE.
PRESERVE_REAGENT		Reagent is not destroyed, which is the normal effect, at the completion of the reaction. Typically used for containers.
PRODUCT	Probability Quantity Item Token Material Token	Defines one of the products to be outputted by the reaction
PRODUCT_DIMENSION	size	Specifies the size of the product. A size of 150 is typical for BAR, POWDER_MISC, LIQUID_MISC, and DRINK. A size of 15000 is typical for THREAD, and a size of 10000 is typical for CLOTH.
PRODUCT_PASTE		Product is created in the SOLID_PASTE state.
PRODUCT_PRESSED		Product is created in the SOLID_PRESSED state.
PRODUCT_TO_CONTAINER	Reagent ID	Places the product in a container; <id> must be the name of a reagent with the PRESERVE_REAGENT token and a container item type.
REACTION	Identifier	defines a new reaction
REACTION_CLASS
REAGENT	name/id quantity item token (and subtoken) material token (and subtoken)	Requires a given reagent as an input for a reaction
SKILL	Skill Token	Skill used by the reaction
UNROTTEN		Reagent must not be rotten, mainly for organic materials.
USE_BODY_COMPONENT		Reagent material must come off a creature's body.
WEB_ONLY		Reagent must be "undisturbed" — used with THREAD:NONE to gather webs.
WORTHLESS_STONE_ONLY		Reagent is not made of an economic stone.