Dwarf Fortress Wiki - User contributions [en]

Utilities

2022-01-03T16:37:25Z

Ralpha: Added DF RAW Language server

{{Quality|Masterwork|13:28, 28 September 2013 (UTC)}}
{{av}}

A collection of third-party '''Utilities''' that are useful for ''[[Dwarf Fortress]]'' players and [[modding|modders]] alike, and this page serves as a list of them. ''Dwarf Fortress'' is a difficult game to play, and any help that can be had in the task is welcome help. If you would like to add an article on a ''specific'' game utility to the wiki, please do so under the [http://dwarffortresswiki.org/index.php?title=Special%3AAllPages&from=&to=&namespace=102 Utility] namespace. Not included on this page: [[Main:Tileset repository|tileset repositories]] and [[Main:Graphics set repository|graphics set repositories]], due to having been given their own, separate pages. [[Modding|Mods]] have also been listed under their own [http://dwarffortresswiki.org/index.php?title=Special%3AAllPages&from=&to=&namespace=104 Modification] namespace. To avoid namespace clutter, websites ''are'' considered utilities, though they really aren't, and have been included.

A [http://www.bay12forums.com/smf/index.php?board=29.0 subsection of the Bay12 forums] is devoted to such third-party programs, and contains development threads for most of them.

The [[Utilities#Lazy Newb Pack|Lazy Newb Pack]] is an effort to make ''Dwarf Fortress'' more accessible for new players by bundling and configuring utilities, graphics and tilesets, and extras such as reference material or more intuitive controls.

==Launchers==

=== [[Utility:Lazy_Newb_Pack|Lazy Newb Pack]] ===
<gallery widths=90px heights=150px>
File:Lnp-gui1.png|The original LNP launcher, options tab
File:Lnp-gui2.png|The graphics tab
File:Lnp-gui3.png|The utilities tab
File:Lnp-gui5.png|The advanced tab
File:lnp-dfhack.png|The DFHack tab
</gallery>
A commonly-used software bundle with a nice launcher. Allows you to start playing DF really quickly on a new machine - no need to download and integrate [[Graphics set repository|tilesets]] and tools like Dwarf Therapist, SoundSense, etc. - or even know what you need to get. The newer packs also include many third-party fixes for common bugs, which work automatically, and a large number of significant user interface improvements. The launcher makes changing settings or graphics options much easier (press button, instead of editing files) and can even remember to launch selected utilities whenever you open a game of ''Dwarf Fortress''. See the [[Utility:Lazy_Newb_Pack|Lazy Newb Pack]] page for more information, or the forum thread for your platform.

*[http://www.bay12forums.com/smf/index.php?topic=126076 PeridexisErrant's Starter Pack] (Windows)
*[http://www.bay12forums.com/smf/index.php?topic=128960 MacNewbie Pack] (OS X)
*[http://www.bay12forums.com/smf/index.php?topic=156011 Unofficial Linux LNP] (Linux)

===[http://www.bay12forums.com/smf/index.php?topic=140808 PyLNP] ===
A cross-platform LNP port, written in Python. The launcher and configuration interface for all of the Lazy Newb Packs. PyLNP is under active development for bugfixes, addition of features pioneered by other launchers, and creation of entirely new features - such as rebuilding the raws of modded saves to change graphics packs.

===[http://www.bay12forums.com/smf/index.php?topic=102316 Manila Launcher] ===
A Java interface that allows easy option toggling, update and devlog checking, and tileset, mod and color scheme switching. Designed for players who prefer vanilla DF to a bundle like the above.

== 3D Visualizers ==
=== [[Utility:Stonesense|Stonesense]] ===
[[File:stonesense_prev.jpg|left|frameless|200px|none]]
Stonesense is a third party visualizer, implemented as a [[Utility:DFHack|DFHack]] plugin, that lets you view your fortress in a classic isometric perspective. It runs alongside ''Dwarf Fortress'', and can follow the main game's view, updating in real-time. It is included in DFHack, and can be opened by typing <code>stonesense</code> or <code>ssense</code> into the console window.

* Links: [[Utility:Stonesense]]
{{Clear}}

=== Fortress Overseer ===
[[File:fortress_viewer.jpg|left|frameless|200px|none]]
Fortress Overseer is the only 3D visualizer supporting v0.31. It has been completely rewritten and is currently updated to support v0.34.11 and v0.31.25. Overseer works indirectly, by using [[Utility:DFHack|DFHack]]'s <code>mapexport</code> to export a file which can then be rendered in 3D. DirectX 9 must be installed, though this requirement is not documented. Has not been tested for 0.40.13.

* Links: [http://www.bay12forums.com/smf/index.php?topic=63484 Bay12forums Thread]
{{Clear}}

=== Armok Vision ===
[[File:armok_vision.png|left|frameless|200px|none]]
Armok Vision is a 3D real-time visualizer using Unity for version 0.40.24. It works as a separate program communicating with the game through fast network interfaces.

* Links: [http://www.bay12forums.com/smf/index.php?topic=146473.0 Bay12forums Thread]
{{Clear}}

=== Isoworld ===
[[File:isoworld_prev.png|left|frameless|200px|none]]
Isoworld is an isometric world map viewer, which can display each of the detailed maps exported from [[Legends mode]]. It also has a pictographic view which makes finding waterfalls easy.

Isoworld can link with [[Utility:DFHack|DFHack]] to display a game view at full spatial resolution in wider context, including tracking the player's view. This is particularly useful for adventure mode.

* Links: [http://www.bay12forums.com/smf/index.php?topic=70700.0 Bay12forums Thread]
{{Clear}}

=== Voxel Fortress ===
[[File:voxel_prev.png|left|frameless|200px|none]]
Voxel Fortress is a converter from DF worlds to a voxel format. It takes an export of one of the two elevation maps (for the voxels coordinates), and any other one (for the colors).
The map is saved in .xraw format. An additional utility (e.g. [https://ephtracy.github.io/index.html?page=mv_renderer MagicaVoxel Viewer]) is required to see the voxel representation of the map.

* Link: [http://www.bay12forums.com/smf/index.php?topic=159578.0 Bay12forums Thread]
{{Clear}}

== Music and Sounds ==
=== [[Utility:SoundSense|SoundSense]] ===
[[File:soundsense_prev.png|left|frameless|100px]]
SoundSense is a sound engine that parses game logs and reacts to game events with sound effects, incidental music and dwarfy comments. You can look it up on the [http://www.bay12forums.com/smf/index.php?topic=60287 forum thread], or directly download it at [http://df.zweistein.cz/soundsense/ the SoundSense homepage]. Due to it being written in Java, Soundsense is portable to all platforms.

Due to development having slowed down, a [https://github.com/calmhorizons/soundsense fork] was released that most notably disables the broken auto-updater and adds the option to minimize Soundsense to the system tray.

Note that older Soundsense users may have different default seasonal soundtracks, which were removed and replaced in early 2011. These are available [http://www.krauselabs.net/dump/music.zip here].
{{Clear}}

=== SoundCenSe ===
[[File:soundCenSe_prev.png|left|frameless|100px|]]
A C# port of SoundSense, it uses the existing sound pack files and XML's present in SoundSense, but with some added enhancements. More information regarding what specific type of enhancements and how to install SoundCenSe can be gathered at the [http://www.bay12forums.com/smf/index.php?topic=159567.0 official forum thread]. If problems emerge while trying to get SoundSense to work with the latest versions of Java, this port may prove to be a useful alternative.

* links: [http://www.bay12forums.com/smf/index.php?topic=159567.0 Bay12forums Thread]. Downloads for the windows and linux binaries are available [https://github.com/Algorithman/SoundCenSe/releases here], while code releases can be obtained from the [https://github.com/Algorithman/SoundCenSe GitHub site].
{{Clear}}

== Game manipulation tools ==
===[[Utility:DFHack|DFHack]]===
[[File:dfhack_cmd.png|thumb|right|250px|DFHack's console.]]
DFHack is an advanced ''Dwarf Fortress'' memory access library and a set of tools and scripts using this library, providing direct object-oriented access to Dwarf Fortress's internals as if it were compiled into the game itself. Runs on Windows, Linux, and OS X. The standard configuration enables a variety of included bugfixes and interface upgrades, and provides many useful tools such as "clean all". See [[Utility:DFHack]] for summary of features and common use in.

* Links: [https://docs.dfhack.org/en/stable/# DFHack's Documentation] site offers all relevant information on how download, install, and use the utility. Including an up-to-date list of all available and optional Plugins. [http://www.bay12forums.com/smf/index.php?topic=164123 Official Bay12 forum thread].

==== Unit Management Plugins ====
[[File:Klokerscreen0.png|thumb|right|250px|Kloker's main screen]]
Kloker, A DFhack in-game UI for inspecting and managing units, with colorful summaries and accessible features including automatic labor assignment.

* Links: [http://www.bay12forums.com/smf/index.php?topic=169329 Bay12Forum Thread]

==== Feature plugins ====
These plugins add features to the game.
* [http://www.bay12forums.com/smf/index.php?topic=128487 Rendermax], a plugin that implements a lighting system at the graphics level.
* [http://www.bay12forums.com/smf/index.php?topic=136155 Dwarven Emigration], a script that allows unhappy dwarves to emigrate with their families.

==== Interaction plugins ====
[http://www.bay12forums.com/smf/index.php?topic=135597 DFHack scripts designed for modders to use as "spells"] (not in standard package)

==== Miscellaneous plugins ====
[http://www.bay12forums.com/smf/index.php?topic=135506 DFHack script collection] (not in standard package)

=== remotefortressreader ===

A critical internal DFHack plugin, [https://github.com/DFHack/dfhack/tree/develop/plugins/remotefortressreader developed within the same repository]. It provides a protobuf-based (currently v2.4.1) RPC connection to the game, enabling remote clients like Armok Vision. The service listens on <code>127.0.0.1:5000</code> (configurable within <code>dfhack-config/remote-server.json</code>).

Currently there are no change-based or change-driven notifications, so remote fortress clients must perform the expensive operation of polling the desired volume every frame (via e.g. <code>GetBlockList</code>). Additionally, the sidebar menu state is shared with the native view, to avoid reimplementing construction material dependencies.

==Dwarf Therapist==
===Dwarf Therapist===
[[File:dwarf_therapist.png|frameless|right|250px|]]
Dwarf Therapist gives you an advanced GUI to manage and check dwarf job allocations, military assignments, statistics (such as attributes, personality traits and happiness), sort dwarves by various criteria (e.g. profession, migration wave, happiness, number of assigned jobs etc.) and generally manage the Dwarven Resources of your fortress in a very convenient way. This version contains the "labor optimizer" semi-automatic labor management system.

Splinterz' fork of Dwarf Therapist is the currently updated version, and available for Windows, Mac and GNU + Linux.

* Links: See the [http://www.bay12forums.com/smf/index.php?topic=168411.0 forum thread] for current downloads. Besides the Bay12 forum thread, there's more information on the [https://github.com/Dwarf-Therapist/Dwarf-Therapist GitHub project page].

====[[Utility:Dwarf Therapist/Addons Repository|Dwarf Therapist Addons Repository]]====

A collection of customizations for Dwarf Therapist submitted by the community.

Addons include:

* custom professions
* custom roles
* optimization plans
* filter scripts
* new grid views

== Fortress layout tools ==
=== [https://github.com/joelpt/quickfort Quickfort] ===
Quickfort is a utility for ''Dwarf Fortress'' that helps you build fortresses from "blueprint" .CSV files (comma separated values). These files are easily created and edited in an app like Excel. Most building-oriented DF commands are supported through the use of multiple .CSV files to describe the different phases of DF construction (designation, building, stockpiles, and making adjustments. Recent versions of Quickfort work by converting the blueprint into a native macro for ''Dwarf Fortress'', then executing the macro. This allows for enormously faster playback compared to early versions or DF Designator.

====[https://www.mediafire.com/folder/u38qsqr1bq6wu/Community_Quickfort_Blueprints_v2 Quickfort Community Blueprints]====

A large collection of blueprints, published to remove the last hint of hassle in creating a fortress. You can download the lot without a paid account [http://www.mediafire.com/download/n6im1ok6z02n8nc/Community_Quickfort_Blueprints_v2.zip here].

===[http://www.bay12forums.com/smf/index.php?topic=55025 ChromaFort]===
Chromafort is a tool designed to complement [[Utilities#Quickfort|Quickfort]], by converting images into quickfort-compatible .csv files. It works with 24-bit bitmap (.bmp) files. There are a number of known issues that can affect any image that is not square, and the size must be an exponent of two (8, 16, 32, 64...); other images may show nonexistent colours and/or come out highly distorted.

===[http://www.bay12forums.com/smf/index.php?topic=138590 Picturefort]===
Picturefort is an attempt to make "Chromafort, but ''better''" - it performs the same function of converting an image to a [[Utilities#Quickfort|Quickfort]]-compatible .csv file. Unlike Chromafort, Picturefort can handle a large number of image formats (though .bmp or .png are recommended); images can be of any shape and within reason size; and while as of May 2014 it is only available on Windows, there are plans for a Linux version.

===[http://www.bay12forums.com/smf/index.php?topic=154849.0 Symmetricity]===
A fortress planner with a focus on multiple planes of symmetry. It can output csv for quickfort. It's early in development so it's probably not suitable for serious use cases.

== Modding tools ==
===[http://www.bay12forums.com/smf/index.php?topic=140853.0 Rubble]===

A useful plugin-based modding tool that generates raws and supports easy installation of reactions, tilesets, macros, modding fixes and DFHack scripts. It is a fork of the now abandoned [http://www.bay12forums.com/smf/index.php?topic=125997.0 Blast]. Binaries are available for Linux 32-bits, OS X 32-bits and Windows 64-bits, as well as the source (written in Go with building instructions). As of 4.0, a GUI is available for Windows.

=== [http://www.bay12forums.com/smf/index.php?topic=150857.0 PyDwarf] ===

For players, PyDwarf is an easy way to manage and configure preferred mods in a way that avoids almost entirely the problems of outdated mods or incompatible groups of mods. For modders, PyDwarf's mod manager exposes a powerful Python API for interacting with raws and other data files.

=== [http://www.bay12forums.com/smf/index.php?topic=103360 Raw Explorer] ===
A tree-based raw files browser, editor and manager.

=== [http://www.bay12forums.com/smf/index.php?topic=174431.0 Dwarf_RAW] ===
A GUI for editing raw files, updated 2019.

=== [http://www.bay12forums.com/smf/index.php?topic=140645.0 Dwarf Fortress real-life material helper] ===
A Python script that generates raws based on custom real-life material values.

=== [http://www.bay12forums.com/smf/index.php?topic=140688.0 Roses' Random Creature Script] ===
A Python script that generates random creature raws.

=== [http://www.bay12forums.com/smf/index.php?topic=175695.0 DF Diagnosipack] ===
A collection of modding tools, with a focus on diagnosing problems and getting statistics on what is found within the raws.
It includes:
* DF Duplisearch - checks your raws folder for duplicated objects, and counts the number of objects of each type (creature, entity, reaction, etc.).
* DF Creatureclasser - tells you what [[cv:Creature_token#CREATURE_CLASS|creature classes]] are in your raws, and what they are used for.
* DF CVunpack - unpacks creature variations, so you can see how the raws for e.g. wolf men really look (spoiler: they have 7 fingers).
* DF Creaturescale - calculates creature weights, and the proportions of each body part and tissue.
* DF Biomeviewer - shows what creature/plants can be found in which biomes.

=== [https://gitlab.com/df-modding-tools/df-raw-language-server DF RAW Language server] ===
Modding support for DF RAW files in IDE/Code/Text editors.
Checks syntax of files, detects errors and syntax highlighting.

Current extensions:
* [https://marketplace.visualstudio.com/items?itemName=df-modding-tools.dwarf-fortress-raw-vscode VS Code]
* [https://gitlab.com/df-modding-tools/df-raw-language-server#supported-editors-and-ides (more are coming)]

<gallery widths=200px>
File:DF_RAW_Language_server_Logo.png|DF RAW Language server Logo
File:DF_RAW_Language_server_VSCode_screenshot_1.png|DF RAW Language server in VSCode
File:DF_RAW_Language_server_VSCode_screenshot_2.png|DF RAW Language server in VSCode
</gallery>

The [[wikipedia:Language_Server_Protocol|Language server]] is a shared component that can be used to easily add support for more IDE's.

== World Map / World Gen tools ==
=== [http://dffd.wimbli.com/file.php?id=2354 Perfect World DF] ===
Requires an additional (tiny) download to be functional for current versions (40.#): [http://dffd.wimbli.com/file.php?id=8756 WorldGen.xml] . Easy access to world settings for quick modification to allow highly customized world generation far easier and faster than DF's ingame advanced map maker. [http://www.bay12forums.com/smf/index.php?topic=57428.0 forum thread]

=== [http://pastebin.com/jdVKPzpt Fortress World Generator] ===
A bash script for automating world generation of large numbers of worlds on GNU/Linux.

=== [http://www.bay12forums.com/smf/index.php?topic=73095 Dwarf Map Maker] ===
A Photoshop action script which turns legends mode exported maps into a much prettier fantasy map. There is also a version available [http://www.bay12forums.com/smf/index.php?topic=73095.msg2261106#msg2261106 for GIMP].

=== [http://www.bay12forums.com/smf/index.php?topic=137076.msg5085575#msg5085575 Satellite Map Maker] ===
A GIMP script based on the Dwarf Map Maker that creates a satellite image of ''Dwarf Fortress'' world maps.

==Legends tools==

=== [http://www.bay12forums.com/smf/index.php?topic=72702 Legends Viewer] ===
<gallery widths=200px>
File:legends_prev.png|Historical Figures view
File:legends_prev2.png|Infrastructure view
File:legends_prev3.png|Other/Eras view
</gallery>
[http://www.bay12forums.com/smf/index.php?topic=154617 Unofficial Branch for 0.47.XX version of DF]

Legends Viewer loads up the legends you can export in a much more usable format than the [[Legends mode]] of DF itself. Legends Viewer can open pages in new tabs, filter information on a wide range of criteria, and display information on the map as well. Binaries are only available for Windows, as well as the source (written in C#).

It takes four files as input: the legends XML file, the sites and pops text, world history text, and a map image. It can load these separately, but it is recommended to load them as a single compressed archive (folder) - the XML can be multiple GB uncompressed for long histories, and reduce to less than 5% of its size.

If you have played a fortress and then exported legends, you may get an error about unreadable HEX characters. This is caused by Workflow, which saves its settings as unreadable historical figures. There are several ways to fix this:
* Clear the workflow settings in fortress mode before exporting legends
* Edit the XML by hand, [http://www.bay12forums.com/smf/index.php?topic=72702.msg4629392#msg4629392 as described here] (any platform)
* Use the [http://www.bay12forums.com/smf/index.php?topic=131307 Legends Processing script] (windows only), which fixes the XML and also creates a compressed folder as described above

=== [http://www.bay12forums.com/smf/index.php?topic=128932.0 World Viewer] ===
[[File:world_viewer_prev.png|thumb|200px|none|"Race" tab view]]
An alternative to Legends Viewer that most specifically features a timeline of historical events. Binaries are only available for Windows, as well as the source (written in C#).

=== [http://www.uristmaps.org Uristmaps] ===
[[File:uristmaps_prev.png|thumb|200px|none|Zoomed-in area of a map view.]]
A web-based interface that displays worlds in the way of an interactive map complete with features and structures.

=== [http://www.bay12forums.com/smf/index.php?topic=155307.0 Legends Browser] ===
[[File:legendsbrowser.png|thumb|200px|none|Civilizations view]]
A web-based multi-platform (Win, Linux, OSX) Viewer. It displays an interactive map and legends information (using legends_plus.xml generated via DFHack).

=== [https://dfstoryteller.com/ DF Storyteller] ===
<gallery widths=200px>
File:DF_Storyteller_Logo.svg|DF Storyteller Logo
File:DF_Storyteller_explain_workings.png|Explains how DF Storyteller works
File:The_Bard_historical_figure_screenshot.png|Screenshot of Historical Figure in The Bard visualizer
</gallery>
Dwarf Fortress Storyteller (DF Storyteller, DF ST) is an application that parses ''Dwarf Fortress'' legends files, stores them internally and makes them queryable using API's. (Cross platform: Windows, Linux, macOS)
This utility can be used to easily create new visualizers to view the legends data. A list of visualizers can be found [https://gitlab.com/df_storyteller/df-storyteller/-/blob/master/docs/paintings.md here].
An example of a visualizer is [https://gitlab.com/df_storyteller/the-bard The Bard] created in DF ST.

== Remote playing tools ==

=== [[Utility:Dfterm3|Dfterm3]]===

[[Utility:Dfterm3|Dfterm3]] is a remote ''Dwarf Fortress''-playing software for multiple users through a web interface. DFterm3 enables play through a web interface, and games can also be viewed on mobile - or even played if a bluetooth keyboard is attached. The web interface should work with Chrome or Firefox browsers, but there are known problems using Internet Explorer. DFTerm3 functions via a DFHack plugin, and is thus dependent on each version of DFHack.

It is a successor to [[Utility:dfterm2|dfterm2]], which functions similarly using telnet instead of a web browser. This utility only works with version 0.34.11 or earlier.

=== [http://www.bay12forums.com/smf/index.php?topic=139167.0 Webfort] ===
[[File:webfortress.png|thumb|200px|none|Playable in Mac browser.]]
A newer alternative to dfterm3 that functions similarly, but players must wait in a queue before assuming control for a given period of time. It also functions via a DFHack plugin. Binaries are available for Windows, as well as the source (written in C++). ''(Note: [https://github.com/mifki/df-webfort main repo] unmaintained. [https://github.com/Ankoku/df-webfort New repo] last updated 5/22/2015.)''

=== [http://www.bay12forums.com/smf/index.php?topic=140892.0 DorfServer] ===
[[File:dorfserver.png|thumb|200px|none|Like Twitch, without Twitch.]]
A remote SSH-based ''Dwarf Fortress'' host software. ([http://www.bay12forums.com/smf/index.php?topic=140892.0 repo])

=== [http://www.bay12forums.com/smf/index.php?topic=139975.0 DFEverywhere] ===

A utility that connects a locally-run ''Dwarf Fortress'' instance to a proprietary remote website, allowing remote browser-based play. ''(Note: Main website no longer available. [https://github.com/tpainter/df_everywhere Client source here.])''

=== [http://mifki.com/df Dwarf Fortress Remote] ===

iOS app (paid) that allows one to play ''Dwarf Fortress'' remotely with native UI. A server can be set up at home, or on DigitalOcean, AWS or other hosting service.

=== [http://www.bay12forums.com/smf/index.php?topic=176070.msg DFPlex ] ===

DFPlex is a plugin for DFHack which introduces simultaneous, real-time online co-op to fortress mode: each player has their own independent view, cursor, menus, etc. so nobody has to wrestle for control. It's a fork of webfort, so players join just by connecting from their web browser.

==Language tools==

===[http://www.bay12forums.com/smf/index.php?topic=47332.0 DFLang]===
A language creating tool.

===[http://www.bay12forums.com/smf/index.php?topic=136098.0 Toadese Language Utility]===
A language editing and translating tool.

===[http://www.bay12forums.com/smf/index.php?topic=140432.0 DFlangOpt]===
A little tool meant to prevent redundancy when importing or updating language files.

===[http://dffd.wimbli.com/file.php?id=8288 Python language extraction and injection script]===
This simple script will extract words from language files and put them a word per line, for easy automatic translation or treatment. It can also read that list and put the translated words back in their place.

==Announcement tools==

===[http://www.bay12forums.com/smf/index.php?topic=130590 DFMon] ===

An announcement monitoring/filtering program, useful to hide some types of job cancellation spam or other more advanced filtering. Note that you can set the game to announce no job cancellations ''without'' any utilities or mods from the {{k|o}}rders menu, with {{k|x}}.

===[http://www.bay12forums.com/smf/index.php?topic=130030 DF Announcement Filter]===

An alternative to DFMon written in Java (and thus portable to Linux and OS X).

===[http://www.bay12forums.com/smf/index.php?topic=153777 Announcement Window+]===

Announcement Window+ is a Python application that interfaces with ''Dwarf Fortress'' to print announcements and combat reports to a separate window. It was written to fix some annoying bugs that are present in DF Announcement Filter, which is no longer being updated.

[[File:announce+_prev.png|thumb|300px|none|One less game-pausing hotkey.]]

==Filesharing websites==

=== [http://dffd.wimbli.com/ Dwarf Fortress File Depot] ===
The Dwarf Fortress File Upload Service - an excellent place to store mods, community games, tilesets and other files. Courtesy of [[User:Janus|Janus]]; for files related to Dwarf Fortress only.

=== [http://mkv25.net/dfma/ Dwarf Fortress Map Archive] ===
{{main|Utility:Dwarf Fortress Map Archive}}

The Dwarf Fortress Map Archive is a large collection of user-submitted maps and videos and a nice flash viewer for perusing them. Maps are uploaded, stored, and downloaded in a special compressed format created by the DF Map Compressor; videos are stored in a compressed version of Toady One's own video-recording format.

Read more about the [[User:Markavian/DF_Map_Archive|DF Map Archive]] on Markavian's User page.

== Other/miscellaneous ==

=== [http://shadowlord13.googlepages.com/dfmap-index.html DF Map Compressor] ===
[[File:dfmapcomp.png|thumb|200px|none|Main program window.]]
The DF Map Compressor encodes multiple bitmaps exported from ''Dwarf Fortress'' into a single, very compressed, .fdf-map file. The fdf-map file can then be shared with your friends by uploading to the DF Map Archive.

=== [http://www.mindwerks.net/projects/exita/ Exita] ===
Exita is a Python program that takes your DF world map exports and dump them into several different text outputs.

===[http://www.bay12forums.com/smf/index.php?topic=132153.0 DwarfFamily]===
A tool that lets you import your legends XML file and converts all dwarf entries to a .GED file, which you can use in Family Tree programs like MyHeritage to display a family tree for the dwarves.

===[https://www.dropbox.com/s/dea50wrs557w283/kobold.py Kobold name generator]===
A Python script that generates random names in the way of kobold utterances

===[https://play.google.com/store/apps/details?id=dae.dfnews Dwarf Fortress News - Android App]===
Watches the ''Dwarf Fortress'' devblog. Receives Push Notifications on new updates.

{{Category|Modding}}
{{Category|Community}}
[[ru:Utilities]]

File:DF RAW Language server Logo.png

2022-01-03T16:31:15Z

Ralpha: Logo of the [https://gitlab.com/df-modding-tools/df-raw-language-server DF Language server]

== Summary ==
Logo of the [https://gitlab.com/df-modding-tools/df-raw-language-server DF Language server]
== Licensing ==
{{cc-by-3.0}}

File:DF RAW Language server VSCode screenshot 2.png

2022-01-03T16:25:12Z

Ralpha: Wrong argument number, to many. Image of VSCode using the [https://gitlab.com/df-modding-tools/df-raw-language-server DF Language server]

== Summary ==
Wrong argument number, to many.
Image of VSCode using the [https://gitlab.com/df-modding-tools/df-raw-language-server DF Language server]
== Licensing ==
{{cc-by-sa-3.0}}

File:DF RAW Language server VSCode screenshot 1.png

2022-01-03T16:08:41Z

Ralpha: Image of VSCode using the [https://gitlab.com/df-modding-tools/df-raw-language-server DF Language server]

== Summary ==
Image of VSCode using the [https://gitlab.com/df-modding-tools/df-raw-language-server DF Language server]
== Licensing ==
{{cc-by-sa-3.0}}

Reaction

2021-05-29T15:19:13Z

Ralpha: Update fire and magma safe

{{Quality|Superior|19:56, 28 August 2013 (UTC)}}
{{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 (sometimes) quite simple to add additional ones. There is a separate page with custom [[reaction examples]].

== Reaction differences between modes ==

In [[fortress mode]], reactions are linked to specific buildings, and must be added to a civilization's [[entity token|entity file]] to be usable by that civilization. This has the useful effect of limiting new items and materials (such as special [[wood]] or [[metal]]) to civilizations that have the requisite reaction — so that if you give your custom civilization a reaction to produce "star metal" or some other custom material, only they will be able to use it.

In [[adventure mode]], reactions are freely available in the {{k|x}} menu via the {{DFtext|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]
* ''[[#Reaction identifier|identifier]]'': The internal ID of the reaction.
* ''[[#Reaction name|name]]'': The name of the reaction, visible to the player in the Fortress mode or Adventure mode menus.
* ''[[#Building|building]]'': The building ID that the reaction uses, and the relevant keyboard shortcut.
* ''[[#Reagents|...reagents...]]'': Zero or more reagents (ingredients) that are required to be in stock for the reaction to be possible.
* ''[[#Products|...products...]]'': Zero or more products that are created from the reaction.
* ''[[#fuel|fuel]]'': (optional) If present, the reaction requires charcoal, coke or a magma-powered workshop.
* ''[[#skill|skill]]'': (optional) The skill required and trained by the reaction.
* ''[[#automatic|automatic]]'': (optional) If present, the reaction will automatically be enqueued whenever it can possibly be performed.
* ''[[#adventure mode|adventure mode]]'': (optional) If present, the reaction is used by the player in Adventure mode instead.

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

=== Reaction name ===

This can be anything at all, and is usually used to describe the reaction. '''Tan a hide''', for example, is the name of the default leather-producing reaction. Generally this should be written as a small descriptive verb phrase, with the first letter capitalized, for consistency with the existing reactions.

=== Building ===

[BUILDING:<BUILDING NAME>:<BUILDING KEY>]
* ''name'': The ID (that is the internal TOKEN each building can be referred to into reactions) 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 TOKENS are as follows:
* KILN - [[Kiln]] and [[Magma kiln]]
* SMELTER - [[Smelter]] and [[Magma smelter]]
* TANNER - [[Tanner's shop]]
* KITCHEN - [[Kitchen]]
* QUERN - [[Quern]]
* MILLSTONE - [[Millstone]]
* STILL - [[Still]]
* FARMER - [[Farmer's workshop]]
* CRAFTSMAN - [[Craftsdwarf's workshop]]
* GLASS{{version|0.42.01}} - [[Glass furnace]]
* WOOD{{version|0.42.01}} - [[Wood furnace]]
* MASON{{version|0.42.01}} - [[Mason's workshop]]
* ASHERY{{version|0.42.01}} - [[Ashery]]
* LEATHER{{version|0.42.01}} - [[Leather works]]
* BOWYER{{version|0.42.01}} - [[Bowyer's workshop]]
* SIEGE{{version|0.42.01}} - [[Siege workshop]]
* CLOTHES{{version|0.42.01}} - [[Clothier's shop]]
* METALSMITH{{version|0.42.01}} - [[Metalsmith's forge]]
* CARPENTER{{version|0.42.01}} - [[Carpenter's workshop]]
* Any custom (raw-defined) building type, such as:
** SOAP_MAKER - [[Soap maker's workshop]]
** SCREW_PRESS - [[Screw press]]

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

=== Category ===

{{new in v0.42}}

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.

{| {{prettytable}}
|- bgcolor="#dddddd"
! 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 || [[interface.txt|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.
|}

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

==== name ====

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

Most reagents are simply named '''A''', '''B''', and so forth in default reactions, although names such as '''TOOLSTONE''' 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 token]]s 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 [[item token|full list]] is available.

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

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

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

==== material token ====

[[Material token]]s come in several forms. For most reagents, this will typically be INORGANIC:MATERIAL_ID or NONE:NONE (to allow multiple materials using other 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:

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| [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|name]] of the reagent).
|-
| [UNROTTEN]
| Reagent must not be rotten, mainly for organic materials.
|-
| style="vertical-align: top"| [CONTAINS_LYE]
| Reagent must be a BARREL or TOOL which contains at least one item of type LIQUID_MISC made of LYE. Use of this token is discouraged, as it does not work with buckets (instead, use [CONTAINS:lye] — note the colon — and a corresponding lye reagent [REAGENT:lye:150:LIQUID_MISC:NONE:LYE]).
|-
| [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]{{version|0.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 [[stack]]s 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.

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| [FORCE_EDGE]
| Product is given a sharp edge. Used for knapping.
|-
| [PRODUCT_PASTE]
| Product is created in the SOLID_PASTE state.
|-
| [PRODUCT_PRESSED]
| Product is created in the SOLID_PRESSED state.
|-
| [PRODUCT_DIMENSION:<size>]
| Specifies the 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:

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| COVERED
| Item is encrusted/studded/decorated with <material>.
|-
| GLAZED
| Item is glazed with <material>.
|-
| RINGS_HANGING
| Item is adorned with hanging rings of <material>.
|-
| BANDS
| Item is encircled with bands of <material>.
|-
| SPIKES
| Item menaces with spikes of <material>.
|-
| 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 token|SKILL token]] determines what skill the reaction requires and what skill it trains. Only one skill may be specified. For custom reactions, the amount of experience gained is linearly correlated with the amount of product created; a reaction with no product will yield no experience for the performing dwarf. A reaction with no skill associated will always be instant.

One may also adjust how much skill is gained using the [SKILL_IP:<integer>] token. The default is 30; more will increase the amount of skill gain. Attribute gain from the skill gain can also be adjusted with [ATTRIBUTE_IP:<integer>], with the default being 10.{{version|0.47.01}}

It's also possible to change how much skill affects the outcome (i.e. quality) of the reaction using the [SKILL_ROLL_RANGE:<basic range>:<multiplier>] token.{{version|0.47.01}} The default is [SKILL_ROLL_RANGE:11:5]. The first number is the base roll and the second number is how much the dwarf's skill can affect the reaction; the skill roll is random(basic 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 basic range is 1). The higher result on the roll, the better. Both numbers can be lowered to the skill harder. For example, 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 have 0 to 10 while legendary+0 (skill 15) dwarves can have 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 range from 0 to 40 for proficient dwarves, with unskilled dwarves always having 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.{{version|0.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:

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

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

|-
| {{text anchor|ANY_BONE_MATERIAL}}
|
| Reagent material must have the [BONE] token.

|-
| {{text anchor|ANY_HORN_MATERIAL}}
|
| Reagent material must have the [HORN] token.

|-
| {{text anchor|ANY_LEATHER_MATERIAL}}
|
| Reagent material must have the [LEATHER] token.

|-
| {{text anchor|ANY_PEARL_MATERIAL}}
|
| Reagent material must have the [PEARL] token.

|-
| {{text anchor|ANY_PLANT_MATERIAL}}
|
| Reagent material must be subordinate to a PLANT object.

|-
| {{text anchor|ANY_SHELL_MATERIAL}}
|
| Reagent material must have the [SHELL] token.

|-
| {{text anchor|ANY_SILK_MATERIAL}}
|
| Reagent material must have the [SILK] token.

|-
| {{text anchor|ANY_SOAP_MATERIAL}}
|
| Reagent material must have the [SOAP] token.

|-
| {{text anchor|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].

|-
| {{text anchor|ANY_TOOTH_MATERIAL}}
|
| Reagent material must have the [TOOTH] token.

|-
| {{text anchor|ANY_YARN_MATERIAL}}
|
| Reagent material must have the [YARN] token.

|-
| {{text anchor|ATTRIBUTE_IP}}{{version|0.47.01}}
| integer
| Amount of attributes given per skill improvement. Default is 10.

|-
| {{text anchor|AUTOMATIC}}
|
| the reaction will be queued automatically if the reaction reagents are all present.

|-
| {{text anchor|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.

|-
| {{text anchor|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

|-
| {{text anchor|BUILDMAT}}
|
| Reagent is able to be used to build structures (Stone, Wood, Blocks, Bars?).

|-
| {{text anchor|CAN_USE_ARTIFACT}}
|
| Reagent can be an Artifact. Using [PRESERVE_REAGENT] with this is strongly advised.

|-
| {{text anchor|CAN_USE_HOSPITAL_RESERVED}}{{version|0.42.01}}
|
| Allows the reagent to be an item that is otherwise reserved for use by a [[healthcare|hospital]].

|-
| {{text anchor|CAN_USE_LOCATION_RESERVED}}{{version|0.42.01}}
|
| Allows the reagent to be an item that is otherwise reserved for use by a [[locations|location]].

|-
| {{text anchor|CATEGORY}}{{version|0.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.

|-
| {{text anchor|CATEGORY_NAME}}{{version|0.42.01}}
| String
| The name of the category as displayed in-game.

|-
| {{text anchor|CATEGORY_DESCRIPTION}}{{version|0.42.01}}
| String
| 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}}
| Category ID
| 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}}
| [[interface.txt|Hotkey token]]
| 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}}
| required content
| Reagent is a container that holds the specified reagent.

|-
| {{text anchor|CONTAINS_LYE}} (Deprecated)
|
| 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}}
| String
| Description of the reaction

|-
| {{text anchor|DOES_NOT_ABSORB}}
|
| Reagent material must have [ABSORPTION:0]

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

|-
| {{text anchor|EMPTY}}
|
| If the reagent is a container, it must be empty.

|-
| {{text anchor|FIRE_BUILD_SAFE}}
|
| Reagent must be considered [[fire-safe]] (stable [[temperature]] below {{ct|11000}}) - i.e. not wood, and not coal.

|-
| {{text anchor|FORCE_EDGE}}
|
| Product is given a sharp edge. Used for knapping.

|-
| {{text anchor|FOOD_STORAGE_CONTAINER}}
|
| Reagent must be a barrel or any non-absorbing tool with [TOOL_USE:FOOD_STORAGE]

|-
| {{text anchor|FUEL}}
|
| Requires that the reaction either use up a unit of coal or charcoal or else be performed at a magma workshop

|-
| {{text anchor|GLASS_MATERIAL}}
|
| Reagent material has [IS_GLASS].

|-
| {{text anchor|HAS_EDGE}}{{version|0.42.01}}
|
| Reagent must be sharpened (used for carving).

|-
| {{text anchor|HAS_ITEM_REACTION_PRODUCT}}
| PRODUCT_ID (custom)
| 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}}
| PRODUCT_ID (custom)
| 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}}
| Tool-use token
| 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.

|-
| {{text anchor|HAS_WRITING_IMPROVEMENT}}{{version|0.42.01}}
|
| Reagent must contain writing.

|-
| {{text anchor|IMPROVEMENT}}
|
* Probability
* Reagent Name
* Improvement type
* Material Token
| Improvement types include BANDS, COVERED, GLAZED, RINGS_HANGING, and SPIKES

|-
| {{text anchor|MAGMA_BUILD_SAFE}}
|
| Currently broken - Reagent must be considered [[magma-safe]] (stable [[temperature]] below {{ct|12000}}).

|-
| {{text anchor|MAX_MULTIPLIER}}{{version|0.42.01}}
| number
| 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}}
|
* Inorganic material
| Reagent material must be an ore of the specified metal

|-
| {{text anchor|MIN_DIMENSION}}
|
* size
| Requires that the reagent have a dimension of at least this value. Only effective with BAR, POWDER_MISC, LIQUID_MISC, DRINK, THREAD, CLOTH, and GLOB items.

|-
| {{text anchor|NAME}}
| name
| defines the name used by the reaction in-game

|-
| {{text anchor|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.

|-
| {{text anchor|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.

|-
| {{text anchor|NOT_ENGRAVED}}
|
| Reagent can not be engraved. For example, a memorial slab can not be engraved.
|-
| {{text anchor|NOT_IMPROVED}}
|
| Reagent has not been decorated.

|-
| {{text anchor|NOT_PRESSED}}
|
| Reagent must not be in the SOLID_PRESSED state.

|-
| {{text anchor|NOT_WEB}}
|
| Reagent must be "collected" - used with THREAD:NONE to exclude webs.

|-
| {{text anchor|POTASHABLE}} (Deprecated)
|
| Alias for CONTAINS_LYE.

|-
| {{text anchor|PRESERVE_REAGENT}}
|
| Reagent is not destroyed, which is the normal effect, at the completion of the reaction. Typically used for containers.

|-
| {{text anchor|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.

|-
| {{text anchor|PRODUCT_DIMENSION}}
| size
| 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.

|-
| {{text anchor|PRODUCT_PASTE}}
|
| Product is created in the SOLID_PASTE state.

|-
| {{text anchor|PRODUCT_PRESSED}}
|
| Product is created in the SOLID_PRESSED state.

|-
| {{text anchor|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.

|-
| {{text anchor|PRODUCT_TOKEN}}{{version|0.42.01}}
| name
| 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}}
| Identifier
| defines a new reaction

|-
| {{text anchor|REACTION_CLASS}}
| CLASS_ID (custom)
| 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).

|-
| {{text anchor|REAGENT}}
|
* name/id
* quantity
* [[item token]]
* [[material token]]
| Requires a given reagent as an input for a reaction

|-
| {{text anchor|SKILL}}
| Skill Token
| Skill used by the reaction

|-
| {{text anchor|SKILL_IP}}{{version|0.47.01}}
| integer
| Amount of skill given per product made. Default is 30.

|-
| {{text anchor|SKILL_ROLL_RANGE}}{{version|0.47.01}}
|
* basic range
* multiplier
| The skill roll is random(basic range) + random((skill level * multipler)/2 + 1) + random((skill level * multipler)/2 + 1). random(x) returns a number between 0 and x-1, so basic range is always 1 or more. The default is 11. The default multiplier is 5. Higher skill rolls give better results.

|-
| {{text anchor|TRANSFER_ARTIFACT_STATUS}}{{version|0.42.01}}
|
| Transfers artifact status from the reagent to the product.

|-
| {{text anchor|UNROTTEN}}
|
| Reagent must not be rotten, mainly for organic materials.

|-
| {{text anchor|USE_BODY_COMPONENT}}
|
| Reagent material must come off a creature's body.

|-
| {{text anchor|WEB_ONLY}}
|
| Reagent must be "undisturbed" - used with THREAD:NONE to gather webs.

|-
| {{text anchor|WORTHLESS_STONE_ONLY}}
|
| Reagent is not made of an economic stone.

|}

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

Reaction

2021-05-22T16:27:27Z

Ralpha: Clarify description

{{Quality|Superior|19:56, 28 August 2013 (UTC)}}
{{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 (sometimes) quite simple to add additional ones. There is a separate page with custom [[reaction examples]].

== Reaction differences between modes ==

In [[fortress mode]], reactions are linked to specific buildings, and must be added to a civilization's [[entity token|entity file]] to be usable by that civilization. This has the useful effect of limiting new items and materials (such as special [[wood]] or [[metal]]) to civilizations that have the requisite reaction — so that if you give your custom civilization a reaction to produce "star metal" or some other custom material, only they will be able to use it.

In [[adventure mode]], reactions are freely available in the {{k|x}} menu via the {{DFtext|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]
* ''[[#Reaction identifier|identifier]]'': The internal ID of the reaction.
* ''[[#Reaction name|name]]'': The name of the reaction, visible to the player in the Fortress mode or Adventure mode menus.
* ''[[#Building|building]]'': The building ID that the reaction uses, and the relevant keyboard shortcut.
* ''[[#Reagents|...reagents...]]'': Zero or more reagents (ingredients) that are required to be in stock for the reaction to be possible.
* ''[[#Products|...products...]]'': Zero or more products that are created from the reaction.
* ''[[#fuel|fuel]]'': (optional) If present, the reaction requires charcoal, coke or a magma-powered workshop.
* ''[[#skill|skill]]'': (optional) The skill required and trained by the reaction.
* ''[[#automatic|automatic]]'': (optional) If present, the reaction will automatically be enqueued whenever it can possibly be performed.
* ''[[#adventure mode|adventure mode]]'': (optional) If present, the reaction is used by the player in Adventure mode instead.

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

=== Reaction name ===

This can be anything at all, and is usually used to describe the reaction. '''Tan a hide''', for example, is the name of the default leather-producing reaction. Generally this should be written as a small descriptive verb phrase, with the first letter capitalized, for consistency with the existing reactions.

=== Building ===

[BUILDING:<BUILDING NAME>:<BUILDING KEY>]
* ''name'': The ID (that is the internal TOKEN each building can be referred to into reactions) 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 TOKENS are as follows:
* KILN - [[Kiln]] and [[Magma kiln]]
* SMELTER - [[Smelter]] and [[Magma smelter]]
* TANNER - [[Tanner's shop]]
* KITCHEN - [[Kitchen]]
* QUERN - [[Quern]]
* MILLSTONE - [[Millstone]]
* STILL - [[Still]]
* FARMER - [[Farmer's workshop]]
* CRAFTSMAN - [[Craftsdwarf's workshop]]
* GLASS{{version|0.42.01}} - [[Glass furnace]]
* WOOD{{version|0.42.01}} - [[Wood furnace]]
* MASON{{version|0.42.01}} - [[Mason's workshop]]
* ASHERY{{version|0.42.01}} - [[Ashery]]
* LEATHER{{version|0.42.01}} - [[Leather works]]
* BOWYER{{version|0.42.01}} - [[Bowyer's workshop]]
* SIEGE{{version|0.42.01}} - [[Siege workshop]]
* CLOTHES{{version|0.42.01}} - [[Clothier's shop]]
* METALSMITH{{version|0.42.01}} - [[Metalsmith's forge]]
* CARPENTER{{version|0.42.01}} - [[Carpenter's workshop]]
* Any custom (raw-defined) building type, such as:
** SOAP_MAKER - [[Soap maker's workshop]]
** SCREW_PRESS - [[Screw press]]

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

=== Category ===

{{new in v0.42}}

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.

{| {{prettytable}}
|- bgcolor="#dddddd"
! 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 || [[interface.txt|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.
|}

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

==== name ====

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

Most reagents are simply named '''A''', '''B''', and so forth in default reactions, although names such as '''TOOLSTONE''' 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 token]]s 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 [[item token|full list]] is available.

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

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

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

==== material token ====

[[Material token]]s come in several forms. For most reagents, this will typically be INORGANIC:MATERIAL_ID or NONE:NONE (to allow multiple materials using other 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:

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| [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|name]] of the reagent).
|-
| [UNROTTEN]
| Reagent must not be rotten, mainly for organic materials.
|-
| style="vertical-align: top"| [CONTAINS_LYE]
| Reagent must be a BARREL or TOOL which contains at least one item of type LIQUID_MISC made of LYE. Use of this token is discouraged, as it does not work with buckets (instead, use [CONTAINS:lye] — note the colon — and a corresponding lye reagent [REAGENT:lye:150:LIQUID_MISC:NONE:LYE]).
|-
| [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]{{version|0.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 [[stack]]s 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.

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| [FORCE_EDGE]
| Product is given a sharp edge. Used for knapping.
|-
| [PRODUCT_PASTE]
| Product is created in the SOLID_PASTE state.
|-
| [PRODUCT_PRESSED]
| Product is created in the SOLID_PRESSED state.
|-
| [PRODUCT_DIMENSION:<size>]
| Specifies the 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:

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| COVERED
| Item is encrusted/studded/decorated with <material>.
|-
| GLAZED
| Item is glazed with <material>.
|-
| RINGS_HANGING
| Item is adorned with hanging rings of <material>.
|-
| BANDS
| Item is encircled with bands of <material>.
|-
| SPIKES
| Item menaces with spikes of <material>.
|-
| 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 token|SKILL token]] determines what skill the reaction requires and what skill it trains. Only one skill may be specified. For custom reactions, the amount of experience gained is linearly correlated with the amount of product created; a reaction with no product will yield no experience for the performing dwarf. A reaction with no skill associated will always be instant.

One may also adjust how much skill is gained using the [SKILL_IP:<integer>] token. The default is 30; more will increase the amount of skill gain. Attribute gain from the skill gain can also be adjusted with [ATTRIBUTE_IP:<integer>], with the default being 10.{{version|0.47.01}}

It's also possible to change how much skill affects the outcome (i.e. quality) of the reaction using the [SKILL_ROLL_RANGE:<basic range>:<multiplier>] token.{{version|0.47.01}} The default is [SKILL_ROLL_RANGE:11:5]. The first number is the base roll and the second number is how much the dwarf's skill can affect the reaction; the skill roll is random(basic 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 basic range is 1). The higher result on the roll, the better. Both numbers can be lowered to the skill harder. For example, 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 have 0 to 10 while legendary+0 (skill 15) dwarves can have 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 range from 0 to 40 for proficient dwarves, with unskilled dwarves always having 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.{{version|0.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:

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

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

|-
| {{text anchor|ANY_BONE_MATERIAL}}
|
| Reagent material must have the [BONE] token.

|-
| {{text anchor|ANY_HORN_MATERIAL}}
|
| Reagent material must have the [HORN] token.

|-
| {{text anchor|ANY_LEATHER_MATERIAL}}
|
| Reagent material must have the [LEATHER] token.

|-
| {{text anchor|ANY_PEARL_MATERIAL}}
|
| Reagent material must have the [PEARL] token.

|-
| {{text anchor|ANY_PLANT_MATERIAL}}
|
| Reagent material must be subordinate to a PLANT object.

|-
| {{text anchor|ANY_SHELL_MATERIAL}}
|
| Reagent material must have the [SHELL] token.

|-
| {{text anchor|ANY_SILK_MATERIAL}}
|
| Reagent material must have the [SILK] token.

|-
| {{text anchor|ANY_SOAP_MATERIAL}}
|
| Reagent material must have the [SOAP] token.

|-
| {{text anchor|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].

|-
| {{text anchor|ANY_TOOTH_MATERIAL}}
|
| Reagent material must have the [TOOTH] token.

|-
| {{text anchor|ANY_YARN_MATERIAL}}
|
| Reagent material must have the [YARN] token.

|-
| {{text anchor|ATTRIBUTE_IP}}{{version|0.47.01}}
| integer
| Amount of attributes given per skill improvement. Default is 10.

|-
| {{text anchor|AUTOMATIC}}
|
| the reaction will be queued automatically if the reaction reagents are all present.

|-
| {{text anchor|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.

|-
| {{text anchor|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

|-
| {{text anchor|BUILDMAT}}
|
| Reagent is able to be used to build structures (Stone, Wood, Blocks, Bars?).

|-
| {{text anchor|CAN_USE_ARTIFACT}}
|
| Reagent can be an Artifact. Using [PRESERVE_REAGENT] with this is strongly advised.

|-
| {{text anchor|CAN_USE_HOSPITAL_RESERVED}}{{version|0.42.01}}
|
| Allows the reagent to be an item that is otherwise reserved for use by a [[healthcare|hospital]].

|-
| {{text anchor|CAN_USE_LOCATION_RESERVED}}{{version|0.42.01}}
|
| Allows the reagent to be an item that is otherwise reserved for use by a [[locations|location]].

|-
| {{text anchor|CATEGORY}}{{version|0.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.

|-
| {{text anchor|CATEGORY_NAME}}{{version|0.42.01}}
| String
| The name of the category as displayed in-game.

|-
| {{text anchor|CATEGORY_DESCRIPTION}}{{version|0.42.01}}
| String
| 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}}
| Category ID
| 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}}
| [[interface.txt|Hotkey token]]
| 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}}
| required content
| Reagent is a container that holds the specified reagent.

|-
| {{text anchor|CONTAINS_LYE}} (Deprecated)
|
| 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}}
| String
| Description of the reaction

|-
| {{text anchor|DOES_NOT_ABSORB}}
|
| Reagent material must have [ABSORPTION:0]

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

|-
| {{text anchor|EMPTY}}
|
| If the reagent is a container, it must be empty.

|-
| {{text anchor|FIRE_BUILD_SAFE}}
|
| Reagent must be considered fire safe - i.e. not wood, and not coal.

|-
| {{text anchor|FORCE_EDGE}}
|
| Product is given a sharp edge. Used for knapping.

|-
| {{text anchor|FOOD_STORAGE_CONTAINER}}
|
| Reagent must be a barrel or any non-absorbing tool with [TOOL_USE:FOOD_STORAGE]

|-
| {{text anchor|FUEL}}
|
| Requires that the reaction either use up a unit of coal or charcoal or else be performed at a magma workshop

|-
| {{text anchor|GLASS_MATERIAL}}
|
| Reagent material has [IS_GLASS].

|-
| {{text anchor|HAS_EDGE}}{{version|0.42.01}}
|
| Reagent must be sharpened (used for carving).

|-
| {{text anchor|HAS_ITEM_REACTION_PRODUCT}}
| PRODUCT_ID (custom)
| 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}}
| PRODUCT_ID (custom)
| 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}}
| Tool-use token
| 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.

|-
| {{text anchor|HAS_WRITING_IMPROVEMENT}}{{version|0.42.01}}
|
| Reagent must contain writing.

|-
| {{text anchor|IMPROVEMENT}}
|
* Probability
* Reagent Name
* Improvement type
* Material Token
| Improvement types include BANDS, COVERED, GLAZED, RINGS_HANGING, and SPIKES

|-
| {{text anchor|MAGMA_BUILD_SAFE}}
|
| Currently broken - behaves exactly the same as FIRE_BUILD_SAFE.

|-
| {{text anchor|MAX_MULTIPLIER}}{{version|0.42.01}}
| number
| 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}}
|
* Inorganic material
| Reagent material must be an ore of the specified metal

|-
| {{text anchor|MIN_DIMENSION}}
|
* size
| Requires that the reagent have a dimension of at least this value. Only effective with BAR, POWDER_MISC, LIQUID_MISC, DRINK, THREAD, CLOTH, and GLOB items.

|-
| {{text anchor|NAME}}
| name
| defines the name used by the reaction in-game

|-
| {{text anchor|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.

|-
| {{text anchor|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.

|-
| {{text anchor|NOT_ENGRAVED}}
|
| Reagent can not be engraved. For example, a memorial slab can not be engraved.
|-
| {{text anchor|NOT_IMPROVED}}
|
| Reagent has not been decorated.

|-
| {{text anchor|NOT_PRESSED}}
|
| Reagent must not be in the SOLID_PRESSED state.

|-
| {{text anchor|NOT_WEB}}
|
| Reagent must be "collected" - used with THREAD:NONE to exclude webs.

|-
| {{text anchor|POTASHABLE}} (Deprecated)
|
| Alias for CONTAINS_LYE.

|-
| {{text anchor|PRESERVE_REAGENT}}
|
| Reagent is not destroyed, which is the normal effect, at the completion of the reaction. Typically used for containers.

|-
| {{text anchor|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.

|-
| {{text anchor|PRODUCT_DIMENSION}}
| size
| 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.

|-
| {{text anchor|PRODUCT_PASTE}}
|
| Product is created in the SOLID_PASTE state.

|-
| {{text anchor|PRODUCT_PRESSED}}
|
| Product is created in the SOLID_PRESSED state.

|-
| {{text anchor|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.

|-
| {{text anchor|PRODUCT_TOKEN}}{{version|0.42.01}}
| name
| 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}}
| Identifier
| defines a new reaction

|-
| {{text anchor|REACTION_CLASS}}
| CLASS_ID (custom)
| 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).

|-
| {{text anchor|REAGENT}}
|
* name/id
* quantity
* [[item token]]
* [[material token]]
| Requires a given reagent as an input for a reaction

|-
| {{text anchor|SKILL}}
| Skill Token
| Skill used by the reaction

|-
| {{text anchor|SKILL_IP}}{{version|0.47.01}}
| integer
| Amount of skill given per product made. Default is 30.

|-
| {{text anchor|SKILL_ROLL_RANGE}}{{version|0.47.01}}
|
* basic range
* multiplier
| The skill roll is random(basic range) + random((skill level * multipler)/2 + 1) + random((skill level * multipler)/2 + 1). random(x) returns a number between 0 and x-1, so basic range is always 1 or more. The default is 11. The default multiplier is 5. Higher skill rolls give better results.

|-
| {{text anchor|TRANSFER_ARTIFACT_STATUS}}{{version|0.42.01}}
|
| Transfers artifact status from the reagent to the product.

|-
| {{text anchor|UNROTTEN}}
|
| Reagent must not be rotten, mainly for organic materials.

|-
| {{text anchor|USE_BODY_COMPONENT}}
|
| Reagent material must come off a creature's body.

|-
| {{text anchor|WEB_ONLY}}
|
| Reagent must be "undisturbed" - used with THREAD:NONE to gather webs.

|-
| {{text anchor|WORTHLESS_STONE_ONLY}}
|
| Reagent is not made of an economic stone.

|}

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

Reaction

2021-05-22T16:26:42Z

Ralpha: Clarify description

{{Quality|Superior|19:56, 28 August 2013 (UTC)}}
{{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 (sometimes) quite simple to add additional ones. There is a separate page with custom [[reaction examples]].

== Reaction differences between modes ==

In [[fortress mode]], reactions are linked to specific buildings, and must be added to a civilization's [[entity token|entity file]] to be usable by that civilization. This has the useful effect of limiting new items and materials (such as special [[wood]] or [[metal]]) to civilizations that have the requisite reaction — so that if you give your custom civilization a reaction to produce "star metal" or some other custom material, only they will be able to use it.

In [[adventure mode]], reactions are freely available in the {{k|x}} menu via the {{DFtext|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]
* ''[[#Reaction identifier|identifier]]'': The internal ID of the reaction.
* ''[[#Reaction name|name]]'': The name of the reaction, visible to the player in the Fortress mode or Adventure mode menus.
* ''[[#Building|building]]'': The building ID that the reaction uses, and the relevant keyboard shortcut.
* ''[[#Reagents|...reagents...]]'': Zero or more reagents (ingredients) that are required to be in stock for the reaction to be possible.
* ''[[#Products|...products...]]'': Zero or more products that are created from the reaction.
* ''[[#fuel|fuel]]'': (optional) If present, the reaction requires charcoal, coke or a magma-powered workshop.
* ''[[#skill|skill]]'': (optional) The skill required and trained by the reaction.
* ''[[#automatic|automatic]]'': (optional) If present, the reaction will automatically be enqueued whenever it can possibly be performed.
* ''[[#adventure mode|adventure mode]]'': (optional) If present, the reaction is used by the player in Adventure mode instead.

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

=== Reaction name ===

This can be anything at all, and is usually used to describe the reaction. '''Tan a hide''', for example, is the name of the default leather-producing reaction. Generally this should be written as a small descriptive verb phrase, with the first letter capitalized, for consistency with the existing reactions.

=== Building ===

[BUILDING:<BUILDING NAME>:<BUILDING KEY>]
* ''name'': The ID (that is the internal TOKEN each building can be referred to into reactions) 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 TOKENS are as follows:
* KILN - [[Kiln]] and [[Magma kiln]]
* SMELTER - [[Smelter]] and [[Magma smelter]]
* TANNER - [[Tanner's shop]]
* KITCHEN - [[Kitchen]]
* QUERN - [[Quern]]
* MILLSTONE - [[Millstone]]
* STILL - [[Still]]
* FARMER - [[Farmer's workshop]]
* CRAFTSMAN - [[Craftsdwarf's workshop]]
* GLASS{{version|0.42.01}} - [[Glass furnace]]
* WOOD{{version|0.42.01}} - [[Wood furnace]]
* MASON{{version|0.42.01}} - [[Mason's workshop]]
* ASHERY{{version|0.42.01}} - [[Ashery]]
* LEATHER{{version|0.42.01}} - [[Leather works]]
* BOWYER{{version|0.42.01}} - [[Bowyer's workshop]]
* SIEGE{{version|0.42.01}} - [[Siege workshop]]
* CLOTHES{{version|0.42.01}} - [[Clothier's shop]]
* METALSMITH{{version|0.42.01}} - [[Metalsmith's forge]]
* CARPENTER{{version|0.42.01}} - [[Carpenter's workshop]]
* Any custom (raw-defined) building type, such as:
** SOAP_MAKER - [[Soap maker's workshop]]
** SCREW_PRESS - [[Screw press]]

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

=== Category ===

{{new in v0.42}}

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.

{| {{prettytable}}
|- bgcolor="#dddddd"
! 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 || [[interface.txt|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.
|}

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

==== name ====

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

Most reagents are simply named '''A''', '''B''', and so forth in default reactions, although names such as '''TOOLSTONE''' 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 token]]s 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 [[item token|full list]] is available.

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

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

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

==== material token ====

[[Material token]]s come in several forms. For most reagents, this will typically be INORGANIC:MATERIAL_ID or NONE:NONE (to allow multiple materials using other 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:

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| [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|name]] of the reagent).
|-
| [UNROTTEN]
| Reagent must not be rotten, mainly for organic materials.
|-
| style="vertical-align: top"| [CONTAINS_LYE]
| Reagent must be a BARREL or TOOL which contains at least one item of type LIQUID_MISC made of LYE. Use of this token is discouraged, as it does not work with buckets (instead, use [CONTAINS:lye] — note the colon — and a corresponding lye reagent [REAGENT:lye:150:LIQUID_MISC:NONE:LYE]).
|-
| [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]{{version|0.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 [[stack]]s 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.

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| [FORCE_EDGE]
| Product is given a sharp edge. Used for knapping.
|-
| [PRODUCT_PASTE]
| Product is created in the SOLID_PASTE state.
|-
| [PRODUCT_PRESSED]
| Product is created in the SOLID_PRESSED state.
|-
| [PRODUCT_DIMENSION:<size>]
| Specifies the 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:

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| COVERED
| Item is encrusted/studded/decorated with <material>.
|-
| GLAZED
| Item is glazed with <material>.
|-
| RINGS_HANGING
| Item is adorned with hanging rings of <material>.
|-
| BANDS
| Item is encircled with bands of <material>.
|-
| SPIKES
| Item menaces with spikes of <material>.
|-
| 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 token|SKILL token]] determines what skill the reaction requires and what skill it trains. Only one skill may be specified. For custom reactions, the amount of experience gained is linearly correlated with the amount of product created; a reaction with no product will yield no experience for the performing dwarf. A reaction with no skill associated will always be instant.

One may also adjust how much skill is gained using the [SKILL_IP:<integer>] token. The default is 30; more will increase the amount of skill gain. Attribute gain from the skill gain can also be adjusted with [ATTRIBUTE_IP:<integer>], with the default being 10.{{version|0.47.01}}

It's also possible to change how much skill affects the outcome (i.e. quality) of the reaction using the [SKILL_ROLL_RANGE:<basic range>:<multiplier>] token.{{version|0.47.01}} The default is [SKILL_ROLL_RANGE:11:5]. The first number is the base roll and the second number is how much the dwarf's skill can affect the reaction; the skill roll is random(basic 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 basic range is 1). The higher result on the roll, the better. Both numbers can be lowered to the skill harder. For example, 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 have 0 to 10 while legendary+0 (skill 15) dwarves can have 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 range from 0 to 40 for proficient dwarves, with unskilled dwarves always having 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.{{version|0.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:

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

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

|-
| {{text anchor|ANY_BONE_MATERIAL}}
|
| Reagent material must have the [BONE] token.

|-
| {{text anchor|ANY_HORN_MATERIAL}}
|
| Reagent material must have the [HORN] token.

|-
| {{text anchor|ANY_LEATHER_MATERIAL}}
|
| Reagent material must have the [LEATHER] token.

|-
| {{text anchor|ANY_PEARL_MATERIAL}}
|
| Reagent material must have the [PEARL] token.

|-
| {{text anchor|ANY_PLANT_MATERIAL}}
|
| Reagent material must be subordinate to a PLANT object.

|-
| {{text anchor|ANY_SHELL_MATERIAL}}
|
| Reagent material must have the [SHELL] token.

|-
| {{text anchor|ANY_SILK_MATERIAL}}
|
| Reagent material must have the [SILK] token.

|-
| {{text anchor|ANY_SOAP_MATERIAL}}
|
| Reagent material must have the [SOAP] token.

|-
| {{text anchor|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].

|-
| {{text anchor|ANY_TOOTH_MATERIAL}}
|
| Reagent material must have the [TOOTH] token.

|-
| {{text anchor|ANY_YARN_MATERIAL}}
|
| Reagent material must have the [YARN] token.

|-
| {{text anchor|ATTRIBUTE_IP}}{{version|0.47.01}}
| integer
| Amount of attributes given per skill improvement. Default is 10.

|-
| {{text anchor|AUTOMATIC}}
|
| the reaction will be queued automatically if the reaction reagents are all present.

|-
| {{text anchor|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.

|-
| {{text anchor|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

|-
| {{text anchor|BUILDMAT}}
|
| Reagent is able to be used to build structures (Stone, Wood, Blocks, Bars?).

|-
| {{text anchor|CAN_USE_ARTIFACT}}
|
| Reagent can be an Artifact. Using [PRESERVE_REAGENT] with this is strongly advised.

|-
| {{text anchor|CAN_USE_HOSPITAL_RESERVED}}{{version|0.42.01}}
|
| Allows the reagent to be an item that is otherwise reserved for use by a [[healthcare|hospital]].

|-
| {{text anchor|CAN_USE_LOCATION_RESERVED}}{{version|0.42.01}}
|
| Allows the reagent to be an item that is otherwise reserved for use by a [[locations|location]].

|-
| {{text anchor|CATEGORY}}{{version|0.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.

|-
| {{text anchor|CATEGORY_NAME}}{{version|0.42.01}}
| String
| The name of the category as displayed in-game.

|-
| {{text anchor|CATEGORY_DESCRIPTION}}{{version|0.42.01}}
| String
| 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}}
| Category ID
| 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}}
| [[interface.txt|Hotkey token]]
| 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}}
| required content
| Reagent is a container that holds the specified reagent.

|-
| {{text anchor|CONTAINS_LYE}} (Deprecated)
|
| 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}}
| String
| Description of the reaction

|-
| {{text anchor|DOES_NOT_ABSORB}}
|
| Reagent material must have [ABSORPTION:0]

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

|-
| {{text anchor|EMPTY}}
|
| If the reagent is a container, it must be empty.

|-
| {{text anchor|FIRE_BUILD_SAFE}}
|
| Reagent must be considered fire safe - i.e. not wood, and not coal.

|-
| {{text anchor|FORCE_EDGE}}
|
| Product is given a sharp edge. Used for knapping.

|-
| {{text anchor|FOOD_STORAGE_CONTAINER}}
|
| Reagent must be a barrel or any non-absorbing tool with [TOOL_USE:FOOD_STORAGE]

|-
| {{text anchor|FUEL}}
|
| Requires that the reaction either use up a unit of coal or charcoal or else be performed at a magma workshop

|-
| {{text anchor|GLASS_MATERIAL}}
|
| Reagent material has [IS_GLASS].

|-
| {{text anchor|HAS_EDGE}}{{version|0.42.01}}
|
| Reagent must be sharpened (used for carving).

|-
| {{text anchor|HAS_ITEM_REACTION_PRODUCT}}
| PRODUCT_ID (custom)
| 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}}
| PRODUCT_ID (custom)
| 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}}
| Tool-use token
| 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.

|-
| {{text anchor|HAS_WRITING_IMPROVEMENT}}{{version|0.42.01}}
|
| Reagent must contain writing.

|-
| {{text anchor|IMPROVEMENT}}
|
* Probability
* Reagent Name
* Improvement type
* Material Token
| Improvement types include BANDS, COVERED, GLAZED, RINGS_HANGING, and SPIKES

|-
| {{text anchor|MAGMA_BUILD_SAFE}}
|
| Currently broken - behaves exactly the same as FIRE_BUILD_SAFE.

|-
| {{text anchor|MAX_MULTIPLIER}}{{version|0.42.01}}
| number
| 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}}
|
* Inorganic material
| Reagent material must be an ore of the specified metal

|-
| {{text anchor|MIN_DIMENSION}}
|
* size
| Requires that the reagent have a dimension of at least this value. Only effective with BAR, POWDER_MISC, LIQUID_MISC, DRINK, THREAD, CLOTH, and GLOB items.

|-
| {{text anchor|NAME}}
| name
| defines the name used by the reaction in-game

|-
| {{text anchor|NO_EDGE_ALLOWED}}
|
| Reagent must not be sharpened (used for knapping).

|-
| {{text anchor|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.

|-
| {{text anchor|NOT_ENGRAVED}}
|
| Reagent can not be engraved. For example, a memorial slab can not be engraved.
|-
| {{text anchor|NOT_IMPROVED}}
|
| Reagent has not been decorated.

|-
| {{text anchor|NOT_PRESSED}}
|
| Reagent must not be in the SOLID_PRESSED state.

|-
| {{text anchor|NOT_WEB}}
|
| Reagent must be "collected" - used with THREAD:NONE to exclude webs.

|-
| {{text anchor|POTASHABLE}} (Deprecated)
|
| Alias for CONTAINS_LYE.

|-
| {{text anchor|PRESERVE_REAGENT}}
|
| Reagent is not destroyed, which is the normal effect, at the completion of the reaction. Typically used for containers.

|-
| {{text anchor|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.

|-
| {{text anchor|PRODUCT_DIMENSION}}
| size
| 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.

|-
| {{text anchor|PRODUCT_PASTE}}
|
| Product is created in the SOLID_PASTE state.

|-
| {{text anchor|PRODUCT_PRESSED}}
|
| Product is created in the SOLID_PRESSED state.

|-
| {{text anchor|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.

|-
| {{text anchor|PRODUCT_TOKEN}}{{version|0.42.01}}
| name
| 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}}
| Identifier
| defines a new reaction

|-
| {{text anchor|REACTION_CLASS}}
| CLASS_ID (custom)
| 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).

|-
| {{text anchor|REAGENT}}
|
* name/id
* quantity
* [[item token]]
* [[material token]]
| Requires a given reagent as an input for a reaction

|-
| {{text anchor|SKILL}}
| Skill Token
| Skill used by the reaction

|-
| {{text anchor|SKILL_IP}}{{version|0.47.01}}
| integer
| Amount of skill given per product made. Default is 30.

|-
| {{text anchor|SKILL_ROLL_RANGE}}{{version|0.47.01}}
|
* basic range
* multiplier
| The skill roll is random(basic range) + random((skill level * multipler)/2 + 1) + random((skill level * multipler)/2 + 1). random(x) returns a number between 0 and x-1, so basic range is always 1 or more. The default is 11. The default multiplier is 5. Higher skill rolls give better results.

|-
| {{text anchor|TRANSFER_ARTIFACT_STATUS}}{{version|0.42.01}}
|
| Transfers artifact status from the reagent to the product.

|-
| {{text anchor|UNROTTEN}}
|
| Reagent must not be rotten, mainly for organic materials.

|-
| {{text anchor|USE_BODY_COMPONENT}}
|
| Reagent material must come off a creature's body.

|-
| {{text anchor|WEB_ONLY}}
|
| Reagent must be "undisturbed" - used with THREAD:NONE to gather webs.

|-
| {{text anchor|WORTHLESS_STONE_ONLY}}
|
| Reagent is not made of an economic stone.

|}

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

Building token

2021-05-22T16:26:01Z

Ralpha: Clarify description

{{Quality|Superior|21:42, 20 September 2016 (UTC)}}
{{av}}

'''Building tokens''' control the functionality of custom buildings.

All custom buildings are defined as objects of type BUILDING_WORKSHOP or BUILDING_FURNACE; workshops show up in the {{K|b}}-{{K|w}} menu, while furnaces show up in the {{K|b}}-{{K|e}} menu.

You also must add any new custom buildings to the [[Entity token|civilization]] that you want to use it.

Additionally, furnaces must be designed by an [[architect]] before being constructed (and will gain [[quality]] accordingly), though they will always use the labor(s) specified in the building definition, rather than ones based on the materials being used.

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

|-
| {{text anchor|NAME}}
| name
| The name of the custom building.

|-
| {{text anchor|NAME_COLOR}}
| [[Color#Modding_color|fg:bg:bright]]
| The color of the building's name when {{K|q}}uerying it. Seemingly ignored for furnaces, which are hardcoded to 4:0:1.

|-
| {{text anchor|DIM}}
| width:height
| The size of the custom building, in number of tiles. Defaults to 3:3. Maximum possible size is 31x31.

|-
| {{text anchor|WORK_LOCATION}}
| x:y
| The tile (1:1 for upper-left) in which dwarves will stand when they are performing tasks. Defaults to 3:3 (bottom-right).

|-
| {{text anchor|BUILD_LABOR}}
| [[labor token]]
| The labor required to construct the custom building. If multiple BUILD_LABOR tokens are specified, then any of the indicated labors can be used to construct the building; if none are specified, then no labors are required. For furnaces, this labor does not come into play until after the workshop has been designed by an [[architect]].

|-
| {{text anchor|BUILD_KEY}}
| [[Interface.txt#Key_bindings|key bind]]
| The shortcut key used in the Build menu for selecting the custom building. For example: "CUSTOM_SHIFT_S"

|-
| {{text anchor|BLOCK}}
|
* row
* tiles...
| Specifies whether or not each workshop tile blocks movement. The first parameter is the row (1 = top), and each subsequent parameter is a 0 (nonblocking) or 1 (blocking) for each column, left to right.

|-
| {{text anchor|TILE}}
|
* stage
* row
* tiles...
| Specifies the characters used to represent the custom building. The first parameter is the building stage, varying from 0 (awaiting construction) to N (completed) where N is between 1 and 3, the 2nd parameter is the row number, and each subsequent parameter is a character number (or literal character enclosed in 'quotes').

|-
| {{text anchor|COLOR}}
|
* stage
* row
* colors...
| Specifies the colors in which the custom building's tiles will be displayed. The first parameter is the building stage, the 2nd parameter is the row number, and subsequent parameters are either sets of 3 numbers (foreground:background:brightness) or the token "MAT" to use the color of the primary building material. MAT may not be available on BUILDING_FURNACEs.{{verify}}

|-
| {{text anchor|BUILD_ITEM}}
|
* quantity
* [[item token]]
* [[material token]]
| Specifies one of the objects necessary to construct the custom building. Each BUILD_ITEM can be followed by zero or more modifiers.

|-
| {{text anchor|NEEDS_MAGMA}}
|
| Specifies that one of the building's tiles (other than the WORK_LOCATION) must be hanging over [[magma]] in order for the building to function. Buildings with this token also ignore the [FUEL] token in their reactions.
|}

==Item Modifiers==
Building items have many of the same modifiers as [[Reactions#Modifiers|reagents]] in custom reactions.

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| [{{text anchor|ANY_BONE_MATERIAL}}]
| Item material must have the [BONE] token.
|-
| [{{text anchor|ANY_HORN_MATERIAL}}]
| Item material must have the [HORN] token.
|-
| [{{text anchor|ANY_LEATHER_MATERIAL}}]
| Item material must have the [LEATHER] token.
|-
| [{{text anchor|ANY_PEARL_MATERIAL}}]
| Item material must have the [PEARL] token.
|-
| [{{text anchor|ANY_PLANT_MATERIAL}}]
| Item material must be subordinate to a PLANT object.
|-
| [{{text anchor|ANY_SHELL_MATERIAL}}]
| Item material must have the [SHELL] token.
|-
| [{{text anchor|ANY_SILK_MATERIAL}}]
| Item material must have the [SILK] token.
|-
| [{{text anchor|ANY_SOAP_MATERIAL}}]
| Item material must have the [SOAP] token.
|-
| [{{text anchor|ANY_STRAND_TISSUE}}]
| Item is made of a tissue having [TISSUE_SHAPE:STRANDS], intended for matching hair and wool. Must be used with [USE_BODY_COMPONENT].
|-
| [{{text anchor|ANY_TOOTH_MATERIAL}}]
| Item material must have the [TOOTH] token.
|-
| [{{text anchor|ANY_YARN_MATERIAL}}]
| Item material must have the [YARN] token.
|-
| [{{text anchor|BAG}}]
| Item must be a bag - that is, a BOX made of plant fiber, silk, yarn, or leather.
|-
| [{{text anchor|BUILDMAT}}]
| Item must be a general [[building material]] - BAR, BLOCKS, BOULDER, or WOOD.
|-
| [{{text anchor|CAN_USE_ARTIFACT}}]
| Item can be an Artifact.
|-
| [{{text anchor|CONTAINS_LYE}}]
| Item must be a BARREL or TOOL which contains at least one item of type LIQUID_MISC made of LYE.
|-
| [{{text anchor|EMPTY}}]
| If the item is a container, it must be empty.
|-
| [{{text anchor|FIRE_BUILD_SAFE}}]
| Item material must be stable at temperatures below 11000. Only works with items of type BAR, BLOCKS, BOULDER, WOOD, and ANVIL - all others are considered unsafe.
|-
| [{{text anchor|GLASS_MATERIAL}}]
| Item material must have the [IS_GLASS] token. All 3 types of [[glass]] have this token hardcoded.
|-
| [{{text anchor|HAS_MATERIAL_REACTION_PRODUCT}}:X]
| Item's material has a [MATERIAL_REACTION_PRODUCT] token with the appropriate ID.
|-
| [{{text anchor|HAS_TOOL_USE}}:X]
| Item must be a [[tool]] with the specific TOOL_USE value. The item type must be TOOL:NONE for this to make any sense.
|-
| [{{text anchor|MAGMA_BUILD_SAFE}}]
| Item material must be stable at temperatures below 12000. Only works with items of type BAR, BLOCKS, BOULDER, WOOD, and ANVIL - all others are considered unsafe.
|-
| [{{text anchor|METAL_ORE}}:X]
| Item material must be an ore of the specified metal.
|-
| [{{text anchor|MIN_DIMENSION}}:X]
| Item's dimension must be at least this large. The item type must be BAR, POWDER_MISC, LIQUID_MISC, DRINK, THREAD, or CLOTH for this to work.
|-
| [{{text anchor|NO_EDGE_ALLOWED}}]
| Item 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.
|-
| [{{text anchor|NOT_CONTAIN_BARREL_ITEM}}]
| If the item is a container, it must not contain [[lye]] or [[milk]]. Not necessary if specifying [EMPTY].
|-
| [{{text anchor|NOT_ENGRAVED}}]
| Item can not be engraved. For example, a memorial slab can not be engraved.
|-
| [{{text anchor|NOT_WEB}}]
| Item must be collected (to distinguish silk thread from webs). Only makes sense for items of type THREAD.
|-
| [{{text anchor|POTASHABLE}}] (Deprecated)
| Alias for [CONTAINS_LYE].
|-
| [{{text anchor|REACTION_CLASS}}:X]
| Item's material has a [REACTION_CLASS] token with the appropriate ID.
|-
| [{{text anchor|UNROTTEN}}]
| Item must not be rotten, mainly for organic materials.
|-
| [{{text anchor|USE_BODY_COMPONENT}}]
| Item must be a body part (CORPSE or CORPSEPIECE).
|-
| [{{text anchor|WEB_ONLY}}]
| Item must be undisturbed (to distinguish silk thread from webs). Only makes sense for items of type THREAD.
|-
| [{{text anchor|WORTHLESS_STONE_ONLY}}]
| Item material must be non-[[economic]].
|}

{{Category|Modding}}
{{Category|Tokens}}
[[ru:Building token]]

Reaction

2021-05-22T16:17:10Z

Ralpha: Clarify description

{{Quality|Superior|19:56, 28 August 2013 (UTC)}}
{{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 (sometimes) quite simple to add additional ones. There is a separate page with custom [[reaction examples]].

== Reaction differences between modes ==

In [[fortress mode]], reactions are linked to specific buildings, and must be added to a civilization's [[entity token|entity file]] to be usable by that civilization. This has the useful effect of limiting new items and materials (such as special [[wood]] or [[metal]]) to civilizations that have the requisite reaction — so that if you give your custom civilization a reaction to produce "star metal" or some other custom material, only they will be able to use it.

In [[adventure mode]], reactions are freely available in the {{k|x}} menu via the {{DFtext|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]
* ''[[#Reaction identifier|identifier]]'': The internal ID of the reaction.
* ''[[#Reaction name|name]]'': The name of the reaction, visible to the player in the Fortress mode or Adventure mode menus.
* ''[[#Building|building]]'': The building ID that the reaction uses, and the relevant keyboard shortcut.
* ''[[#Reagents|...reagents...]]'': Zero or more reagents (ingredients) that are required to be in stock for the reaction to be possible.
* ''[[#Products|...products...]]'': Zero or more products that are created from the reaction.
* ''[[#fuel|fuel]]'': (optional) If present, the reaction requires charcoal, coke or a magma-powered workshop.
* ''[[#skill|skill]]'': (optional) The skill required and trained by the reaction.
* ''[[#automatic|automatic]]'': (optional) If present, the reaction will automatically be enqueued whenever it can possibly be performed.
* ''[[#adventure mode|adventure mode]]'': (optional) If present, the reaction is used by the player in Adventure mode instead.

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

=== Reaction name ===

This can be anything at all, and is usually used to describe the reaction. '''Tan a hide''', for example, is the name of the default leather-producing reaction. Generally this should be written as a small descriptive verb phrase, with the first letter capitalized, for consistency with the existing reactions.

=== Building ===

[BUILDING:<BUILDING NAME>:<BUILDING KEY>]
* ''name'': The ID (that is the internal TOKEN each building can be referred to into reactions) 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 TOKENS are as follows:
* KILN - [[Kiln]] and [[Magma kiln]]
* SMELTER - [[Smelter]] and [[Magma smelter]]
* TANNER - [[Tanner's shop]]
* KITCHEN - [[Kitchen]]
* QUERN - [[Quern]]
* MILLSTONE - [[Millstone]]
* STILL - [[Still]]
* FARMER - [[Farmer's workshop]]
* CRAFTSMAN - [[Craftsdwarf's workshop]]
* GLASS{{version|0.42.01}} - [[Glass furnace]]
* WOOD{{version|0.42.01}} - [[Wood furnace]]
* MASON{{version|0.42.01}} - [[Mason's workshop]]
* ASHERY{{version|0.42.01}} - [[Ashery]]
* LEATHER{{version|0.42.01}} - [[Leather works]]
* BOWYER{{version|0.42.01}} - [[Bowyer's workshop]]
* SIEGE{{version|0.42.01}} - [[Siege workshop]]
* CLOTHES{{version|0.42.01}} - [[Clothier's shop]]
* METALSMITH{{version|0.42.01}} - [[Metalsmith's forge]]
* CARPENTER{{version|0.42.01}} - [[Carpenter's workshop]]
* Any custom (raw-defined) building type, such as:
** SOAP_MAKER - [[Soap maker's workshop]]
** SCREW_PRESS - [[Screw press]]

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

=== Category ===

{{new in v0.42}}

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.

{| {{prettytable}}
|- bgcolor="#dddddd"
! 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 || [[interface.txt|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.
|}

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

==== name ====

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

Most reagents are simply named '''A''', '''B''', and so forth in default reactions, although names such as '''TOOLSTONE''' 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 token]]s 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 [[item token|full list]] is available.

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

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

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

==== material token ====

[[Material token]]s come in several forms. For most reagents, this will typically be INORGANIC:MATERIAL_ID or NONE:NONE (to allow multiple materials using other 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:

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| [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|name]] of the reagent).
|-
| [UNROTTEN]
| Reagent must not be rotten, mainly for organic materials.
|-
| style="vertical-align: top"| [CONTAINS_LYE]
| Reagent must be a BARREL or TOOL which contains at least one item of type LIQUID_MISC made of LYE. Use of this token is discouraged, as it does not work with buckets (instead, use [CONTAINS:lye] — note the colon — and a corresponding lye reagent [REAGENT:lye:150:LIQUID_MISC:NONE:LYE]).
|-
| [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 - excludes sharp stones (produced using knapping) and most types of weapon/ammo.
|-
| [HAS_EDGE]{{version|0.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 [[stack]]s 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.

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| [FORCE_EDGE]
| Product is given a sharp edge. Used for knapping.
|-
| [PRODUCT_PASTE]
| Product is created in the SOLID_PASTE state.
|-
| [PRODUCT_PRESSED]
| Product is created in the SOLID_PRESSED state.
|-
| [PRODUCT_DIMENSION:<size>]
| Specifies the 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:

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| COVERED
| Item is encrusted/studded/decorated with <material>.
|-
| GLAZED
| Item is glazed with <material>.
|-
| RINGS_HANGING
| Item is adorned with hanging rings of <material>.
|-
| BANDS
| Item is encircled with bands of <material>.
|-
| SPIKES
| Item menaces with spikes of <material>.
|-
| 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 token|SKILL token]] determines what skill the reaction requires and what skill it trains. Only one skill may be specified. For custom reactions, the amount of experience gained is linearly correlated with the amount of product created; a reaction with no product will yield no experience for the performing dwarf. A reaction with no skill associated will always be instant.

One may also adjust how much skill is gained using the [SKILL_IP:<integer>] token. The default is 30; more will increase the amount of skill gain. Attribute gain from the skill gain can also be adjusted with [ATTRIBUTE_IP:<integer>], with the default being 10.{{version|0.47.01}}

It's also possible to change how much skill affects the outcome (i.e. quality) of the reaction using the [SKILL_ROLL_RANGE:<basic range>:<multiplier>] token.{{version|0.47.01}} The default is [SKILL_ROLL_RANGE:11:5]. The first number is the base roll and the second number is how much the dwarf's skill can affect the reaction; the skill roll is random(basic 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 basic range is 1). The higher result on the roll, the better. Both numbers can be lowered to the skill harder. For example, 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 have 0 to 10 while legendary+0 (skill 15) dwarves can have 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 range from 0 to 40 for proficient dwarves, with unskilled dwarves always having 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.{{version|0.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:

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

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

|-
| {{text anchor|ANY_BONE_MATERIAL}}
|
| Reagent material must have the [BONE] token.

|-
| {{text anchor|ANY_HORN_MATERIAL}}
|
| Reagent material must have the [HORN] token.

|-
| {{text anchor|ANY_LEATHER_MATERIAL}}
|
| Reagent material must have the [LEATHER] token.

|-
| {{text anchor|ANY_PEARL_MATERIAL}}
|
| Reagent material must have the [PEARL] token.

|-
| {{text anchor|ANY_PLANT_MATERIAL}}
|
| Reagent material must be subordinate to a PLANT object.

|-
| {{text anchor|ANY_SHELL_MATERIAL}}
|
| Reagent material must have the [SHELL] token.

|-
| {{text anchor|ANY_SILK_MATERIAL}}
|
| Reagent material must have the [SILK] token.

|-
| {{text anchor|ANY_SOAP_MATERIAL}}
|
| Reagent material must have the [SOAP] token.

|-
| {{text anchor|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].

|-
| {{text anchor|ANY_TOOTH_MATERIAL}}
|
| Reagent material must have the [TOOTH] token.

|-
| {{text anchor|ANY_YARN_MATERIAL}}
|
| Reagent material must have the [YARN] token.

|-
| {{text anchor|ATTRIBUTE_IP}}{{version|0.47.01}}
| integer
| Amount of attributes given per skill improvement. Default is 10.

|-
| {{text anchor|AUTOMATIC}}
|
| the reaction will be queued automatically if the reaction reagents are all present.

|-
| {{text anchor|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.

|-
| {{text anchor|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

|-
| {{text anchor|BUILDMAT}}
|
| Reagent is able to be used to build structures (Stone, Wood, Blocks, Bars?).

|-
| {{text anchor|CAN_USE_ARTIFACT}}
|
| Reagent can be an Artifact. Using [PRESERVE_REAGENT] with this is strongly advised.

|-
| {{text anchor|CAN_USE_HOSPITAL_RESERVED}}{{version|0.42.01}}
|
| Allows the reagent to be an item that is otherwise reserved for use by a [[healthcare|hospital]].

|-
| {{text anchor|CAN_USE_LOCATION_RESERVED}}{{version|0.42.01}}
|
| Allows the reagent to be an item that is otherwise reserved for use by a [[locations|location]].

|-
| {{text anchor|CATEGORY}}{{version|0.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.

|-
| {{text anchor|CATEGORY_NAME}}{{version|0.42.01}}
| String
| The name of the category as displayed in-game.

|-
| {{text anchor|CATEGORY_DESCRIPTION}}{{version|0.42.01}}
| String
| 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}}
| Category ID
| 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}}
| [[interface.txt|Hotkey token]]
| 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}}
| required content
| Reagent is a container that holds the specified reagent.

|-
| {{text anchor|CONTAINS_LYE}} (Deprecated)
|
| 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}}
| String
| Description of the reaction

|-
| {{text anchor|DOES_NOT_ABSORB}}
|
| Reagent material must have [ABSORPTION:0]

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

|-
| {{text anchor|EMPTY}}
|
| If the reagent is a container, it must be empty.

|-
| {{text anchor|FIRE_BUILD_SAFE}}
|
| Reagent must be considered fire safe - i.e. not wood, and not coal.

|-
| {{text anchor|FORCE_EDGE}}
|
| Product is given a sharp edge. Used for knapping.

|-
| {{text anchor|FOOD_STORAGE_CONTAINER}}
|
| Reagent must be a barrel or any non-absorbing tool with [TOOL_USE:FOOD_STORAGE]

|-
| {{text anchor|FUEL}}
|
| Requires that the reaction either use up a unit of coal or charcoal or else be performed at a magma workshop

|-
| {{text anchor|GLASS_MATERIAL}}
|
| Reagent material has [IS_GLASS].

|-
| {{text anchor|HAS_EDGE}}{{version|0.42.01}}
|
| Reagent must be sharpened (used for carving).

|-
| {{text anchor|HAS_ITEM_REACTION_PRODUCT}}
| PRODUCT_ID (custom)
| 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}}
| PRODUCT_ID (custom)
| 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}}
| Tool-use token
| 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.

|-
| {{text anchor|HAS_WRITING_IMPROVEMENT}}{{version|0.42.01}}
|
| Reagent must contain writing.

|-
| {{text anchor|IMPROVEMENT}}
|
* Probability
* Reagent Name
* Improvement type
* Material Token
| Improvement types include BANDS, COVERED, GLAZED, RINGS_HANGING, and SPIKES

|-
| {{text anchor|MAGMA_BUILD_SAFE}}
|
| Currently broken - behaves exactly the same as FIRE_BUILD_SAFE.

|-
| {{text anchor|MAX_MULTIPLIER}}{{version|0.42.01}}
| number
| 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}}
|
* Inorganic material
| Reagent material must be an ore of the specified metal

|-
| {{text anchor|MIN_DIMENSION}}
|
* size
| Requires that the reagent have a dimension of at least this value. Only effective with BAR, POWDER_MISC, LIQUID_MISC, DRINK, THREAD, CLOTH, and GLOB items.

|-
| {{text anchor|NAME}}
| name
| defines the name used by the reaction in-game

|-
| {{text anchor|NO_EDGE_ALLOWED}}
|
| Reagent must not be sharpened (used for knapping).

|-
| {{text anchor|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.

|-
| {{text anchor|NOT_ENGRAVED}}
|
| Reagent can not be engraved. For example, a memorial slab can not be engraved.
|-
| {{text anchor|NOT_IMPROVED}}
|
| Reagent has not been decorated.

|-
| {{text anchor|NOT_PRESSED}}
|
| Reagent must not be in the SOLID_PRESSED state.

|-
| {{text anchor|NOT_WEB}}
|
| Reagent must be "collected" - used with THREAD:NONE to exclude webs.

|-
| {{text anchor|POTASHABLE}} (Deprecated)
|
| Alias for CONTAINS_LYE.

|-
| {{text anchor|PRESERVE_REAGENT}}
|
| Reagent is not destroyed, which is the normal effect, at the completion of the reaction. Typically used for containers.

|-
| {{text anchor|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.

|-
| {{text anchor|PRODUCT_DIMENSION}}
| size
| 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.

|-
| {{text anchor|PRODUCT_PASTE}}
|
| Product is created in the SOLID_PASTE state.

|-
| {{text anchor|PRODUCT_PRESSED}}
|
| Product is created in the SOLID_PRESSED state.

|-
| {{text anchor|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.

|-
| {{text anchor|PRODUCT_TOKEN}}{{version|0.42.01}}
| name
| 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}}
| Identifier
| defines a new reaction

|-
| {{text anchor|REACTION_CLASS}}
| CLASS_ID (custom)
| 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).

|-
| {{text anchor|REAGENT}}
|
* name/id
* quantity
* [[item token]]
* [[material token]]
| Requires a given reagent as an input for a reaction

|-
| {{text anchor|SKILL}}
| Skill Token
| Skill used by the reaction

|-
| {{text anchor|SKILL_IP}}{{version|0.47.01}}
| integer
| Amount of skill given per product made. Default is 30.

|-
| {{text anchor|SKILL_ROLL_RANGE}}{{version|0.47.01}}
|
* basic range
* multiplier
| The skill roll is random(basic range) + random((skill level * multipler)/2 + 1) + random((skill level * multipler)/2 + 1). random(x) returns a number between 0 and x-1, so basic range is always 1 or more. The default is 11. The default multiplier is 5. Higher skill rolls give better results.

|-
| {{text anchor|TRANSFER_ARTIFACT_STATUS}}{{version|0.42.01}}
|
| Transfers artifact status from the reagent to the product.

|-
| {{text anchor|UNROTTEN}}
|
| Reagent must not be rotten, mainly for organic materials.

|-
| {{text anchor|USE_BODY_COMPONENT}}
|
| Reagent material must come off a creature's body.

|-
| {{text anchor|WEB_ONLY}}
|
| Reagent must be "undisturbed" - used with THREAD:NONE to gather webs.

|-
| {{text anchor|WORTHLESS_STONE_ONLY}}
|
| Reagent is not made of an economic stone.

|}

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

Reaction

2021-05-22T16:16:33Z

Ralpha: Clarify description

{{Quality|Superior|19:56, 28 August 2013 (UTC)}}
{{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 (sometimes) quite simple to add additional ones. There is a separate page with custom [[reaction examples]].

== Reaction differences between modes ==

In [[fortress mode]], reactions are linked to specific buildings, and must be added to a civilization's [[entity token|entity file]] to be usable by that civilization. This has the useful effect of limiting new items and materials (such as special [[wood]] or [[metal]]) to civilizations that have the requisite reaction — so that if you give your custom civilization a reaction to produce "star metal" or some other custom material, only they will be able to use it.

In [[adventure mode]], reactions are freely available in the {{k|x}} menu via the {{DFtext|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]
* ''[[#Reaction identifier|identifier]]'': The internal ID of the reaction.
* ''[[#Reaction name|name]]'': The name of the reaction, visible to the player in the Fortress mode or Adventure mode menus.
* ''[[#Building|building]]'': The building ID that the reaction uses, and the relevant keyboard shortcut.
* ''[[#Reagents|...reagents...]]'': Zero or more reagents (ingredients) that are required to be in stock for the reaction to be possible.
* ''[[#Products|...products...]]'': Zero or more products that are created from the reaction.
* ''[[#fuel|fuel]]'': (optional) If present, the reaction requires charcoal, coke or a magma-powered workshop.
* ''[[#skill|skill]]'': (optional) The skill required and trained by the reaction.
* ''[[#automatic|automatic]]'': (optional) If present, the reaction will automatically be enqueued whenever it can possibly be performed.
* ''[[#adventure mode|adventure mode]]'': (optional) If present, the reaction is used by the player in Adventure mode instead.

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

=== Reaction name ===

This can be anything at all, and is usually used to describe the reaction. '''Tan a hide''', for example, is the name of the default leather-producing reaction. Generally this should be written as a small descriptive verb phrase, with the first letter capitalized, for consistency with the existing reactions.

=== Building ===

[BUILDING:<BUILDING NAME>:<BUILDING KEY>]
* ''name'': The ID (that is the internal TOKEN each building can be referred to into reactions) 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 TOKENS are as follows:
* KILN - [[Kiln]] and [[Magma kiln]]
* SMELTER - [[Smelter]] and [[Magma smelter]]
* TANNER - [[Tanner's shop]]
* KITCHEN - [[Kitchen]]
* QUERN - [[Quern]]
* MILLSTONE - [[Millstone]]
* STILL - [[Still]]
* FARMER - [[Farmer's workshop]]
* CRAFTSMAN - [[Craftsdwarf's workshop]]
* GLASS{{version|0.42.01}} - [[Glass furnace]]
* WOOD{{version|0.42.01}} - [[Wood furnace]]
* MASON{{version|0.42.01}} - [[Mason's workshop]]
* ASHERY{{version|0.42.01}} - [[Ashery]]
* LEATHER{{version|0.42.01}} - [[Leather works]]
* BOWYER{{version|0.42.01}} - [[Bowyer's workshop]]
* SIEGE{{version|0.42.01}} - [[Siege workshop]]
* CLOTHES{{version|0.42.01}} - [[Clothier's shop]]
* METALSMITH{{version|0.42.01}} - [[Metalsmith's forge]]
* CARPENTER{{version|0.42.01}} - [[Carpenter's workshop]]
* Any custom (raw-defined) building type, such as:
** SOAP_MAKER - [[Soap maker's workshop]]
** SCREW_PRESS - [[Screw press]]

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

=== Category ===

{{new in v0.42}}

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.

{| {{prettytable}}
|- bgcolor="#dddddd"
! 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 || [[interface.txt|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.
|}

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

==== name ====

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

Most reagents are simply named '''A''', '''B''', and so forth in default reactions, although names such as '''TOOLSTONE''' 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 token]]s 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 [[item token|full list]] is available.

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

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

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

==== material token ====

[[Material token]]s come in several forms. For most reagents, this will typically be INORGANIC:MATERIAL_ID or NONE:NONE (to allow multiple materials using other 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:

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| [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|name]] of the reagent).
|-
| [UNROTTEN]
| Reagent must not be rotten, mainly for organic materials.
|-
| style="vertical-align: top"| [CONTAINS_LYE]
| Reagent must be a BARREL or TOOL which contains at least one item of type LIQUID_MISC made of LYE. Use of this token is discouraged, as it does not work with buckets (instead, use [CONTAINS:lye] — note the colon — and a corresponding lye reagent [REAGENT:lye:150:LIQUID_MISC:NONE:LYE]).
|-
| [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 - excludes sharp stones (produced using knapping) and most types of weapon/ammo.
|-
| [HAS_EDGE]{{version|0.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 [[stack]]s 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.

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| [FORCE_EDGE]
| Product is given a sharp edge. Used for knapping.
|-
| [PRODUCT_PASTE]
| Product is created in the SOLID_PASTE state.
|-
| [PRODUCT_PRESSED]
| Product is created in the SOLID_PRESSED state.
|-
| [PRODUCT_DIMENSION:<size>]
| Specifies the 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:

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| COVERED
| Item is encrusted/studded/decorated with <material>.
|-
| GLAZED
| Item is glazed with <material>.
|-
| RINGS_HANGING
| Item is adorned with hanging rings of <material>.
|-
| BANDS
| Item is encircled with bands of <material>.
|-
| SPIKES
| Item menaces with spikes of <material>.
|-
| 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 token|SKILL token]] determines what skill the reaction requires and what skill it trains. Only one skill may be specified. For custom reactions, the amount of experience gained is linearly correlated with the amount of product created; a reaction with no product will yield no experience for the performing dwarf. A reaction with no skill associated will always be instant.

One may also adjust how much skill is gained using the [SKILL_IP:<integer>] token. The default is 30; more will increase the amount of skill gain. Attribute gain from the skill gain can also be adjusted with [ATTRIBUTE_IP:<integer>], with the default being 10.{{version|0.47.01}}

It's also possible to change how much skill affects the outcome (i.e. quality) of the reaction using the [SKILL_ROLL_RANGE:<basic range>:<multiplier>] token.{{version|0.47.01}} The default is [SKILL_ROLL_RANGE:11:5]. The first number is the base roll and the second number is how much the dwarf's skill can affect the reaction; the skill roll is random(basic 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 basic range is 1). The higher result on the roll, the better. Both numbers can be lowered to the skill harder. For example, 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 have 0 to 10 while legendary+0 (skill 15) dwarves can have 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 range from 0 to 40 for proficient dwarves, with unskilled dwarves always having 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.{{version|0.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:

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

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

|-
| {{text anchor|ANY_BONE_MATERIAL}}
|
| Reagent material must have the [BONE] token.

|-
| {{text anchor|ANY_HORN_MATERIAL}}
|
| Reagent material must have the [HORN] token.

|-
| {{text anchor|ANY_LEATHER_MATERIAL}}
|
| Reagent material must have the [LEATHER] token.

|-
| {{text anchor|ANY_PEARL_MATERIAL}}
|
| Reagent material must have the [PEARL] token.

|-
| {{text anchor|ANY_PLANT_MATERIAL}}
|
| Reagent material must be subordinate to a PLANT object.

|-
| {{text anchor|ANY_SHELL_MATERIAL}}
|
| Reagent material must have the [SHELL] token.

|-
| {{text anchor|ANY_SILK_MATERIAL}}
|
| Reagent material must have the [SILK] token.

|-
| {{text anchor|ANY_SOAP_MATERIAL}}
|
| Reagent material must have the [SOAP] token.

|-
| {{text anchor|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].

|-
| {{text anchor|ANY_TOOTH_MATERIAL}}
|
| Reagent material must have the [TOOTH] token.

|-
| {{text anchor|ANY_YARN_MATERIAL}}
|
| Reagent material must have the [YARN] token.

|-
| {{text anchor|ATTRIBUTE_IP}}{{version|0.47.01}}
| integer
| Amount of attributes given per skill improvement. Default is 10.

|-
| {{text anchor|AUTOMATIC}}
|
| the reaction will be queued automatically if the reaction reagents are all present.

|-
| {{text anchor|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.

|-
| {{text anchor|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

|-
| {{text anchor|BUILDMAT}}
|
| Reagent is able to be used to build structures (Stone, Wood, Blocks, Bars?).

|-
| {{text anchor|CAN_USE_ARTIFACT}}
|
| Reagent can be an Artifact. Using [PRESERVE_REAGENT] with this is strongly advised.

|-
| {{text anchor|CAN_USE_HOSPITAL_RESERVED}}{{version|0.42.01}}
|
| Allows the reagent to be an item that is otherwise reserved for use by a [[healthcare|hospital]].

|-
| {{text anchor|CAN_USE_LOCATION_RESERVED}}{{version|0.42.01}}
|
| Allows the reagent to be an item that is otherwise reserved for use by a [[locations|location]].

|-
| {{text anchor|CATEGORY}}{{version|0.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.

|-
| {{text anchor|CATEGORY_NAME}}{{version|0.42.01}}
| String
| The name of the category as displayed in-game.

|-
| {{text anchor|CATEGORY_DESCRIPTION}}{{version|0.42.01}}
| String
| 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}}
| Category ID
| 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}}
| [[interface.txt|Hotkey token]]
| 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}}
| required content
| Reagent is a container that holds the specified reagent.

|-
| {{text anchor|CONTAINS_LYE}} (Deprecated)
|
| 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}}
| String
| Description of the reaction

|-
| {{text anchor|DOES_NOT_ABSORB}}
|
| Reagent material must have [ABSORPTION:0]

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

|-
| {{text anchor|EMPTY}}
|
| If the reagent is a container, it must be empty.

|-
| {{text anchor|FIRE_BUILD_SAFE}}
|
| Reagent must be considered fire safe - i.e. not wood, and not coal.

|-
| {{text anchor|FORCE_EDGE}}
|
| Product is given a sharp edge. Used for knapping.

|-
| {{text anchor|FOOD_STORAGE_CONTAINER}}
|
| Reagent must be a barrel or any non-absorbing tool with [TOOL_USE:FOOD_STORAGE]

|-
| {{text anchor|FUEL}}
|
| Requires that the reaction either use up a unit of coal or charcoal or else be performed at a magma workshop

|-
| {{text anchor|GLASS_MATERIAL}}
|
| Reagent material has [IS_GLASS].

|-
| {{text anchor|HAS_EDGE}}{{version|0.42.01}}
|
| Reagent must be sharpened (used for carving).

|-
| {{text anchor|HAS_ITEM_REACTION_PRODUCT}}
| PRODUCT_ID (custom)
| 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}}
| PRODUCT_ID (custom)
| 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}}
| Tool-use token
| 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.

|-
| {{text anchor|HAS_WRITING_IMPROVEMENT}}{{version|0.42.01}}
|
| Reagent must contain writing.

|-
| {{text anchor|IMPROVEMENT}}
|
* Probability
* Reagent Name
* Improvement type
* Material Token
| Improvement types include BANDS, COVERED, GLAZED, RINGS_HANGING, and SPIKES

|-
| {{text anchor|MAGMA_BUILD_SAFE}}
|
| Currently broken - behaves exactly the same as FIRE_BUILD_SAFE.

|-
| {{text anchor|MAX_MULTIPLIER}}{{version|0.42.01}}
| number
| 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}}
|
* Inorganic material
| Reagent material must be an ore of the specified metal

|-
| {{text anchor|MIN_DIMENSION}}
|
* size
| Requires that the reagent have a dimension of at least this value. Only effective with BAR, POWDER_MISC, LIQUID_MISC, DRINK, THREAD, CLOTH, and GLOB items.

|-
| {{text anchor|NAME}}
| name
| defines the name used by the reaction in-game

|-
| {{text anchor|NO_EDGE_ALLOWED}}
|
| Reagent must not be sharpened (used for knapping).

|-
| {{text anchor|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.

|-
| {{text anchor|NOT_ENGRAVED}}
|
| Reagent must not be an engraved memorial slab.
|-
| {{text anchor|NOT_IMPROVED}}
|
| Reagent has not been decorated.

|-
| {{text anchor|NOT_PRESSED}}
|
| Reagent must not be in the SOLID_PRESSED state.

|-
| {{text anchor|NOT_WEB}}
|
| Reagent must be "collected" - used with THREAD:NONE to exclude webs.

|-
| {{text anchor|POTASHABLE}} (Deprecated)
|
| Alias for CONTAINS_LYE.

|-
| {{text anchor|PRESERVE_REAGENT}}
|
| Reagent is not destroyed, which is the normal effect, at the completion of the reaction. Typically used for containers.

|-
| {{text anchor|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.

|-
| {{text anchor|PRODUCT_DIMENSION}}
| size
| 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.

|-
| {{text anchor|PRODUCT_PASTE}}
|
| Product is created in the SOLID_PASTE state.

|-
| {{text anchor|PRODUCT_PRESSED}}
|
| Product is created in the SOLID_PRESSED state.

|-
| {{text anchor|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.

|-
| {{text anchor|PRODUCT_TOKEN}}{{version|0.42.01}}
| name
| 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}}
| Identifier
| defines a new reaction

|-
| {{text anchor|REACTION_CLASS}}
| CLASS_ID (custom)
| 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).

|-
| {{text anchor|REAGENT}}
|
* name/id
* quantity
* [[item token]]
* [[material token]]
| Requires a given reagent as an input for a reaction

|-
| {{text anchor|SKILL}}
| Skill Token
| Skill used by the reaction

|-
| {{text anchor|SKILL_IP}}{{version|0.47.01}}
| integer
| Amount of skill given per product made. Default is 30.

|-
| {{text anchor|SKILL_ROLL_RANGE}}{{version|0.47.01}}
|
* basic range
* multiplier
| The skill roll is random(basic range) + random((skill level * multipler)/2 + 1) + random((skill level * multipler)/2 + 1). random(x) returns a number between 0 and x-1, so basic range is always 1 or more. The default is 11. The default multiplier is 5. Higher skill rolls give better results.

|-
| {{text anchor|TRANSFER_ARTIFACT_STATUS}}{{version|0.42.01}}
|
| Transfers artifact status from the reagent to the product.

|-
| {{text anchor|UNROTTEN}}
|
| Reagent must not be rotten, mainly for organic materials.

|-
| {{text anchor|USE_BODY_COMPONENT}}
|
| Reagent material must come off a creature's body.

|-
| {{text anchor|WEB_ONLY}}
|
| Reagent must be "undisturbed" - used with THREAD:NONE to gather webs.

|-
| {{text anchor|WORTHLESS_STONE_ONLY}}
|
| Reagent is not made of an economic stone.

|}

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

Building token

2021-05-22T16:15:44Z

Ralpha: Clarify description

{{Quality|Superior|21:42, 20 September 2016 (UTC)}}
{{av}}

'''Building tokens''' control the functionality of custom buildings.

All custom buildings are defined as objects of type BUILDING_WORKSHOP or BUILDING_FURNACE; workshops show up in the {{K|b}}-{{K|w}} menu, while furnaces show up in the {{K|b}}-{{K|e}} menu.

You also must add any new custom buildings to the [[Entity token|civilization]] that you want to use it.

Additionally, furnaces must be designed by an [[architect]] before being constructed (and will gain [[quality]] accordingly), though they will always use the labor(s) specified in the building definition, rather than ones based on the materials being used.

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

|-
| {{text anchor|NAME}}
| name
| The name of the custom building.

|-
| {{text anchor|NAME_COLOR}}
| [[Color#Modding_color|fg:bg:bright]]
| The color of the building's name when {{K|q}}uerying it. Seemingly ignored for furnaces, which are hardcoded to 4:0:1.

|-
| {{text anchor|DIM}}
| width:height
| The size of the custom building, in number of tiles. Defaults to 3:3. Maximum possible size is 31x31.

|-
| {{text anchor|WORK_LOCATION}}
| x:y
| The tile (1:1 for upper-left) in which dwarves will stand when they are performing tasks. Defaults to 3:3 (bottom-right).

|-
| {{text anchor|BUILD_LABOR}}
| [[labor token]]
| The labor required to construct the custom building. If multiple BUILD_LABOR tokens are specified, then any of the indicated labors can be used to construct the building; if none are specified, then no labors are required. For furnaces, this labor does not come into play until after the workshop has been designed by an [[architect]].

|-
| {{text anchor|BUILD_KEY}}
| [[Interface.txt#Key_bindings|key bind]]
| The shortcut key used in the Build menu for selecting the custom building. For example: "CUSTOM_SHIFT_S"

|-
| {{text anchor|BLOCK}}
|
* row
* tiles...
| Specifies whether or not each workshop tile blocks movement. The first parameter is the row (1 = top), and each subsequent parameter is a 0 (nonblocking) or 1 (blocking) for each column, left to right.

|-
| {{text anchor|TILE}}
|
* stage
* row
* tiles...
| Specifies the characters used to represent the custom building. The first parameter is the building stage, varying from 0 (awaiting construction) to N (completed) where N is between 1 and 3, the 2nd parameter is the row number, and each subsequent parameter is a character number (or literal character enclosed in 'quotes').

|-
| {{text anchor|COLOR}}
|
* stage
* row
* colors...
| Specifies the colors in which the custom building's tiles will be displayed. The first parameter is the building stage, the 2nd parameter is the row number, and subsequent parameters are either sets of 3 numbers (foreground:background:brightness) or the token "MAT" to use the color of the primary building material. MAT may not be available on BUILDING_FURNACEs.{{verify}}

|-
| {{text anchor|BUILD_ITEM}}
|
* quantity
* [[item token]]
* [[material token]]
| Specifies one of the objects necessary to construct the custom building. Each BUILD_ITEM can be followed by zero or more modifiers.

|-
| {{text anchor|NEEDS_MAGMA}}
|
| Specifies that one of the building's tiles (other than the WORK_LOCATION) must be hanging over [[magma]] in order for the building to function. Buildings with this token also ignore the [FUEL] token in their reactions.
|}

==Item Modifiers==
Building items have many of the same modifiers as [[Reactions#Modifiers|reagents]] in custom reactions.

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| [{{text anchor|ANY_BONE_MATERIAL}}]
| Item material must have the [BONE] token.
|-
| [{{text anchor|ANY_HORN_MATERIAL}}]
| Item material must have the [HORN] token.
|-
| [{{text anchor|ANY_LEATHER_MATERIAL}}]
| Item material must have the [LEATHER] token.
|-
| [{{text anchor|ANY_PEARL_MATERIAL}}]
| Item material must have the [PEARL] token.
|-
| [{{text anchor|ANY_PLANT_MATERIAL}}]
| Item material must be subordinate to a PLANT object.
|-
| [{{text anchor|ANY_SHELL_MATERIAL}}]
| Item material must have the [SHELL] token.
|-
| [{{text anchor|ANY_SILK_MATERIAL}}]
| Item material must have the [SILK] token.
|-
| [{{text anchor|ANY_SOAP_MATERIAL}}]
| Item material must have the [SOAP] token.
|-
| [{{text anchor|ANY_STRAND_TISSUE}}]
| Item is made of a tissue having [TISSUE_SHAPE:STRANDS], intended for matching hair and wool. Must be used with [USE_BODY_COMPONENT].
|-
| [{{text anchor|ANY_TOOTH_MATERIAL}}]
| Item material must have the [TOOTH] token.
|-
| [{{text anchor|ANY_YARN_MATERIAL}}]
| Item material must have the [YARN] token.
|-
| [{{text anchor|BAG}}]
| Item must be a bag - that is, a BOX made of plant fiber, silk, yarn, or leather.
|-
| [{{text anchor|BUILDMAT}}]
| Item must be a general [[building material]] - BAR, BLOCKS, BOULDER, or WOOD.
|-
| [{{text anchor|CAN_USE_ARTIFACT}}]
| Item can be an Artifact.
|-
| [{{text anchor|CONTAINS_LYE}}]
| Item must be a BARREL or TOOL which contains at least one item of type LIQUID_MISC made of LYE.
|-
| [{{text anchor|EMPTY}}]
| If the item is a container, it must be empty.
|-
| [{{text anchor|FIRE_BUILD_SAFE}}]
| Item material must be stable at temperatures below 11000. Only works with items of type BAR, BLOCKS, BOULDER, WOOD, and ANVIL - all others are considered unsafe.
|-
| [{{text anchor|GLASS_MATERIAL}}]
| Item material must have the [IS_GLASS] token. All 3 types of [[glass]] have this token hardcoded.
|-
| [{{text anchor|HAS_MATERIAL_REACTION_PRODUCT}}:X]
| Item's material has a [MATERIAL_REACTION_PRODUCT] token with the appropriate ID.
|-
| [{{text anchor|HAS_TOOL_USE}}:X]
| Item must be a [[tool]] with the specific TOOL_USE value. The item type must be TOOL:NONE for this to make any sense.
|-
| [{{text anchor|MAGMA_BUILD_SAFE}}]
| Item material must be stable at temperatures below 12000. Only works with items of type BAR, BLOCKS, BOULDER, WOOD, and ANVIL - all others are considered unsafe.
|-
| [{{text anchor|METAL_ORE}}:X]
| Item material must be an ore of the specified metal.
|-
| [{{text anchor|MIN_DIMENSION}}:X]
| Item's dimension must be at least this large. The item type must be BAR, POWDER_MISC, LIQUID_MISC, DRINK, THREAD, or CLOTH for this to work.
|-
| [{{text anchor|NO_EDGE_ALLOWED}}]
| Item must not have an edge - excludes sharp stones (produced using knapping) and most types of weapon/ammo.
|-
| [{{text anchor|NOT_CONTAIN_BARREL_ITEM}}]
| If the item is a container, it must not contain [[lye]] or [[milk]]. Not necessary if specifying [EMPTY].
|-
| [{{text anchor|NOT_ENGRAVED}}]
| Item can not be engraved. For example, a memorial slab can not be engraved.
|-
| [{{text anchor|NOT_WEB}}]
| Item must be collected (to distinguish silk thread from webs). Only makes sense for items of type THREAD.
|-
| [{{text anchor|POTASHABLE}}] (Deprecated)
| Alias for [CONTAINS_LYE].
|-
| [{{text anchor|REACTION_CLASS}}:X]
| Item's material has a [REACTION_CLASS] token with the appropriate ID.
|-
| [{{text anchor|UNROTTEN}}]
| Item must not be rotten, mainly for organic materials.
|-
| [{{text anchor|USE_BODY_COMPONENT}}]
| Item must be a body part (CORPSE or CORPSEPIECE).
|-
| [{{text anchor|WEB_ONLY}}]
| Item must be undisturbed (to distinguish silk thread from webs). Only makes sense for items of type THREAD.
|-
| [{{text anchor|WORTHLESS_STONE_ONLY}}]
| Item material must be non-[[economic]].
|}

{{Category|Modding}}
{{Category|Tokens}}
[[ru:Building token]]

Reaction

2021-05-22T16:09:04Z

Ralpha: Marked `POTASHABLE` as Deprecated

{{Quality|Superior|19:56, 28 August 2013 (UTC)}}
{{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 (sometimes) quite simple to add additional ones. There is a separate page with custom [[reaction examples]].

== Reaction differences between modes ==

In [[fortress mode]], reactions are linked to specific buildings, and must be added to a civilization's [[entity token|entity file]] to be usable by that civilization. This has the useful effect of limiting new items and materials (such as special [[wood]] or [[metal]]) to civilizations that have the requisite reaction — so that if you give your custom civilization a reaction to produce "star metal" or some other custom material, only they will be able to use it.

In [[adventure mode]], reactions are freely available in the {{k|x}} menu via the {{DFtext|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]
* ''[[#Reaction identifier|identifier]]'': The internal ID of the reaction.
* ''[[#Reaction name|name]]'': The name of the reaction, visible to the player in the Fortress mode or Adventure mode menus.
* ''[[#Building|building]]'': The building ID that the reaction uses, and the relevant keyboard shortcut.
* ''[[#Reagents|...reagents...]]'': Zero or more reagents (ingredients) that are required to be in stock for the reaction to be possible.
* ''[[#Products|...products...]]'': Zero or more products that are created from the reaction.
* ''[[#fuel|fuel]]'': (optional) If present, the reaction requires charcoal, coke or a magma-powered workshop.
* ''[[#skill|skill]]'': (optional) The skill required and trained by the reaction.
* ''[[#automatic|automatic]]'': (optional) If present, the reaction will automatically be enqueued whenever it can possibly be performed.
* ''[[#adventure mode|adventure mode]]'': (optional) If present, the reaction is used by the player in Adventure mode instead.

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

=== Reaction name ===

This can be anything at all, and is usually used to describe the reaction. '''Tan a hide''', for example, is the name of the default leather-producing reaction. Generally this should be written as a small descriptive verb phrase, with the first letter capitalized, for consistency with the existing reactions.

=== Building ===

[BUILDING:<BUILDING NAME>:<BUILDING KEY>]
* ''name'': The ID (that is the internal TOKEN each building can be referred to into reactions) 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 TOKENS are as follows:
* KILN - [[Kiln]] and [[Magma kiln]]
* SMELTER - [[Smelter]] and [[Magma smelter]]
* TANNER - [[Tanner's shop]]
* KITCHEN - [[Kitchen]]
* QUERN - [[Quern]]
* MILLSTONE - [[Millstone]]
* STILL - [[Still]]
* FARMER - [[Farmer's workshop]]
* CRAFTSMAN - [[Craftsdwarf's workshop]]
* GLASS{{version|0.42.01}} - [[Glass furnace]]
* WOOD{{version|0.42.01}} - [[Wood furnace]]
* MASON{{version|0.42.01}} - [[Mason's workshop]]
* ASHERY{{version|0.42.01}} - [[Ashery]]
* LEATHER{{version|0.42.01}} - [[Leather works]]
* BOWYER{{version|0.42.01}} - [[Bowyer's workshop]]
* SIEGE{{version|0.42.01}} - [[Siege workshop]]
* CLOTHES{{version|0.42.01}} - [[Clothier's shop]]
* METALSMITH{{version|0.42.01}} - [[Metalsmith's forge]]
* CARPENTER{{version|0.42.01}} - [[Carpenter's workshop]]
* Any custom (raw-defined) building type, such as:
** SOAP_MAKER - [[Soap maker's workshop]]
** SCREW_PRESS - [[Screw press]]

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

=== Category ===

{{new in v0.42}}

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.

{| {{prettytable}}
|- bgcolor="#dddddd"
! 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 || [[interface.txt|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.
|}

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

==== name ====

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

Most reagents are simply named '''A''', '''B''', and so forth in default reactions, although names such as '''TOOLSTONE''' 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 token]]s 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 [[item token|full list]] is available.

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

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

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

==== material token ====

[[Material token]]s come in several forms. For most reagents, this will typically be INORGANIC:MATERIAL_ID or NONE:NONE (to allow multiple materials using other 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:

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| [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|name]] of the reagent).
|-
| [UNROTTEN]
| Reagent must not be rotten, mainly for organic materials.
|-
| style="vertical-align: top"| [CONTAINS_LYE]
| Reagent must be a BARREL or TOOL which contains at least one item of type LIQUID_MISC made of LYE. Use of this token is discouraged, as it does not work with buckets (instead, use [CONTAINS:lye] — note the colon — and a corresponding lye reagent [REAGENT:lye:150:LIQUID_MISC:NONE:LYE]).
|-
| [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 - excludes sharp stones (produced using knapping) and most types of weapon/ammo.
|-
| [HAS_EDGE]{{version|0.42.01}}
| Reagent must have an edge.
|-
| [NOT_ENGRAVED]
| Reagent has not been engraved (excludes memorial slabs).
|-
| [NOT_IMPROVED]
| Reagent has not been decorated.
|-
| [DOES_NOT_ABSORB]
| Reagent material must have [ABSORPTION:0]
|-
| [FOOD_STORAGE_CONTAINER]
| Reagent is either a BARREL or a TOOL with the FOOD_STORAGE use.
|-
| [HARD_ITEM_MATERIAL]
| 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 [[stack]]s 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.

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| [FORCE_EDGE]
| Product is given a sharp edge. Used for knapping.
|-
| [PRODUCT_PASTE]
| Product is created in the SOLID_PASTE state.
|-
| [PRODUCT_PRESSED]
| Product is created in the SOLID_PRESSED state.
|-
| [PRODUCT_DIMENSION:<size>]
| Specifies the 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:

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| COVERED
| Item is encrusted/studded/decorated with <material>.
|-
| GLAZED
| Item is glazed with <material>.
|-
| RINGS_HANGING
| Item is adorned with hanging rings of <material>.
|-
| BANDS
| Item is encircled with bands of <material>.
|-
| SPIKES
| Item menaces with spikes of <material>.
|-
| 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 token|SKILL token]] determines what skill the reaction requires and what skill it trains. Only one skill may be specified. For custom reactions, the amount of experience gained is linearly correlated with the amount of product created; a reaction with no product will yield no experience for the performing dwarf. A reaction with no skill associated will always be instant.

One may also adjust how much skill is gained using the [SKILL_IP:<integer>] token. The default is 30; more will increase the amount of skill gain. Attribute gain from the skill gain can also be adjusted with [ATTRIBUTE_IP:<integer>], with the default being 10.{{version|0.47.01}}

It's also possible to change how much skill affects the outcome (i.e. quality) of the reaction using the [SKILL_ROLL_RANGE:<basic range>:<multiplier>] token.{{version|0.47.01}} The default is [SKILL_ROLL_RANGE:11:5]. The first number is the base roll and the second number is how much the dwarf's skill can affect the reaction; the skill roll is random(basic 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 basic range is 1). The higher result on the roll, the better. Both numbers can be lowered to the skill harder. For example, 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 have 0 to 10 while legendary+0 (skill 15) dwarves can have 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 range from 0 to 40 for proficient dwarves, with unskilled dwarves always having 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.{{version|0.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:

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

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

|-
| {{text anchor|ANY_BONE_MATERIAL}}
|
| Reagent material must have the [BONE] token.

|-
| {{text anchor|ANY_HORN_MATERIAL}}
|
| Reagent material must have the [HORN] token.

|-
| {{text anchor|ANY_LEATHER_MATERIAL}}
|
| Reagent material must have the [LEATHER] token.

|-
| {{text anchor|ANY_PEARL_MATERIAL}}
|
| Reagent material must have the [PEARL] token.

|-
| {{text anchor|ANY_PLANT_MATERIAL}}
|
| Reagent material must be subordinate to a PLANT object.

|-
| {{text anchor|ANY_SHELL_MATERIAL}}
|
| Reagent material must have the [SHELL] token.

|-
| {{text anchor|ANY_SILK_MATERIAL}}
|
| Reagent material must have the [SILK] token.

|-
| {{text anchor|ANY_SOAP_MATERIAL}}
|
| Reagent material must have the [SOAP] token.

|-
| {{text anchor|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].

|-
| {{text anchor|ANY_TOOTH_MATERIAL}}
|
| Reagent material must have the [TOOTH] token.

|-
| {{text anchor|ANY_YARN_MATERIAL}}
|
| Reagent material must have the [YARN] token.

|-
| {{text anchor|ATTRIBUTE_IP}}{{version|0.47.01}}
| integer
| Amount of attributes given per skill improvement. Default is 10.

|-
| {{text anchor|AUTOMATIC}}
|
| the reaction will be queued automatically if the reaction reagents are all present.

|-
| {{text anchor|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.

|-
| {{text anchor|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

|-
| {{text anchor|BUILDMAT}}
|
| Reagent is able to be used to build structures (Stone, Wood, Blocks, Bars?).

|-
| {{text anchor|CAN_USE_ARTIFACT}}
|
| Reagent can be an Artifact. Using [PRESERVE_REAGENT] with this is strongly advised.

|-
| {{text anchor|CAN_USE_HOSPITAL_RESERVED}}{{version|0.42.01}}
|
| Allows the reagent to be an item that is otherwise reserved for use by a [[healthcare|hospital]].

|-
| {{text anchor|CAN_USE_LOCATION_RESERVED}}{{version|0.42.01}}
|
| Allows the reagent to be an item that is otherwise reserved for use by a [[locations|location]].

|-
| {{text anchor|CATEGORY}}{{version|0.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.

|-
| {{text anchor|CATEGORY_NAME}}{{version|0.42.01}}
| String
| The name of the category as displayed in-game.

|-
| {{text anchor|CATEGORY_DESCRIPTION}}{{version|0.42.01}}
| String
| 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}}
| Category ID
| 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}}
| [[interface.txt|Hotkey token]]
| 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}}
| required content
| Reagent is a container that holds the specified reagent.

|-
| {{text anchor|CONTAINS_LYE}} (Deprecated)
|
| 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}}
| String
| Description of the reaction

|-
| {{text anchor|DOES_NOT_ABSORB}}
|
| Reagent material must have [ABSORPTION:0]

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

|-
| {{text anchor|EMPTY}}
|
| If the reagent is a container, it must be empty.

|-
| {{text anchor|FIRE_BUILD_SAFE}}
|
| Reagent must be considered fire safe - i.e. not wood, and not coal.

|-
| {{text anchor|FORCE_EDGE}}
|
| Product is given a sharp edge. Used for knapping.

|-
| {{text anchor|FOOD_STORAGE_CONTAINER}}
|
| Reagent must be a barrel or any non-absorbing tool with [TOOL_USE:FOOD_STORAGE]

|-
| {{text anchor|FUEL}}
|
| Requires that the reaction either use up a unit of coal or charcoal or else be performed at a magma workshop

|-
| {{text anchor|GLASS_MATERIAL}}
|
| Reagent material has [IS_GLASS].

|-
| {{text anchor|HAS_EDGE}}{{version|0.42.01}}
|
| Reagent must be sharpened (used for carving).

|-
| {{text anchor|HAS_ITEM_REACTION_PRODUCT}}
| PRODUCT_ID (custom)
| 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}}
| PRODUCT_ID (custom)
| 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}}
| Tool-use token
| 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.

|-
| {{text anchor|HAS_WRITING_IMPROVEMENT}}{{version|0.42.01}}
|
| Reagent must contain writing.

|-
| {{text anchor|IMPROVEMENT}}
|
* Probability
* Reagent Name
* Improvement type
* Material Token
| Improvement types include BANDS, COVERED, GLAZED, RINGS_HANGING, and SPIKES

|-
| {{text anchor|MAGMA_BUILD_SAFE}}
|
| Currently broken - behaves exactly the same as FIRE_BUILD_SAFE.

|-
| {{text anchor|MAX_MULTIPLIER}}{{version|0.42.01}}
| number
| 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}}
|
* Inorganic material
| Reagent material must be an ore of the specified metal

|-
| {{text anchor|MIN_DIMENSION}}
|
* size
| Requires that the reagent have a dimension of at least this value. Only effective with BAR, POWDER_MISC, LIQUID_MISC, DRINK, THREAD, CLOTH, and GLOB items.

|-
| {{text anchor|NAME}}
| name
| defines the name used by the reaction in-game

|-
| {{text anchor|NO_EDGE_ALLOWED}}
|
| Reagent must not be sharpened (used for knapping).

|-
| {{text anchor|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.

|-
| {{text anchor|NOT_ENGRAVED}}
|
| Reagent must not be an engraved memorial slab.
|-
| {{text anchor|NOT_IMPROVED}}
|
| Reagent has not been decorated.

|-
| {{text anchor|NOT_PRESSED}}
|
| Reagent must not be in the SOLID_PRESSED state.

|-
| {{text anchor|NOT_WEB}}
|
| Reagent must be "collected" - used with THREAD:NONE to exclude webs.

|-
| {{text anchor|POTASHABLE}} (Deprecated)
|
| Alias for CONTAINS_LYE.

|-
| {{text anchor|PRESERVE_REAGENT}}
|
| Reagent is not destroyed, which is the normal effect, at the completion of the reaction. Typically used for containers.

|-
| {{text anchor|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.

|-
| {{text anchor|PRODUCT_DIMENSION}}
| size
| 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.

|-
| {{text anchor|PRODUCT_PASTE}}
|
| Product is created in the SOLID_PASTE state.

|-
| {{text anchor|PRODUCT_PRESSED}}
|
| Product is created in the SOLID_PRESSED state.

|-
| {{text anchor|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.

|-
| {{text anchor|PRODUCT_TOKEN}}{{version|0.42.01}}
| name
| 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}}
| Identifier
| defines a new reaction

|-
| {{text anchor|REACTION_CLASS}}
| CLASS_ID (custom)
| 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).

|-
| {{text anchor|REAGENT}}
|
* name/id
* quantity
* [[item token]]
* [[material token]]
| Requires a given reagent as an input for a reaction

|-
| {{text anchor|SKILL}}
| Skill Token
| Skill used by the reaction

|-
| {{text anchor|SKILL_IP}}{{version|0.47.01}}
| integer
| Amount of skill given per product made. Default is 30.

|-
| {{text anchor|SKILL_ROLL_RANGE}}{{version|0.47.01}}
|
* basic range
* multiplier
| The skill roll is random(basic range) + random((skill level * multipler)/2 + 1) + random((skill level * multipler)/2 + 1). random(x) returns a number between 0 and x-1, so basic range is always 1 or more. The default is 11. The default multiplier is 5. Higher skill rolls give better results.

|-
| {{text anchor|TRANSFER_ARTIFACT_STATUS}}{{version|0.42.01}}
|
| Transfers artifact status from the reagent to the product.

|-
| {{text anchor|UNROTTEN}}
|
| Reagent must not be rotten, mainly for organic materials.

|-
| {{text anchor|USE_BODY_COMPONENT}}
|
| Reagent material must come off a creature's body.

|-
| {{text anchor|WEB_ONLY}}
|
| Reagent must be "undisturbed" - used with THREAD:NONE to gather webs.

|-
| {{text anchor|WORTHLESS_STONE_ONLY}}
|
| Reagent is not made of an economic stone.

|}

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

Building token

2021-05-22T16:08:14Z

Ralpha: Marked `POTASHABLE` as Deprecated

{{Quality|Superior|21:42, 20 September 2016 (UTC)}}
{{av}}

'''Building tokens''' control the functionality of custom buildings.

All custom buildings are defined as objects of type BUILDING_WORKSHOP or BUILDING_FURNACE; workshops show up in the {{K|b}}-{{K|w}} menu, while furnaces show up in the {{K|b}}-{{K|e}} menu.

You also must add any new custom buildings to the [[Entity token|civilization]] that you want to use it.

Additionally, furnaces must be designed by an [[architect]] before being constructed (and will gain [[quality]] accordingly), though they will always use the labor(s) specified in the building definition, rather than ones based on the materials being used.

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

|-
| {{text anchor|NAME}}
| name
| The name of the custom building.

|-
| {{text anchor|NAME_COLOR}}
| [[Color#Modding_color|fg:bg:bright]]
| The color of the building's name when {{K|q}}uerying it. Seemingly ignored for furnaces, which are hardcoded to 4:0:1.

|-
| {{text anchor|DIM}}
| width:height
| The size of the custom building, in number of tiles. Defaults to 3:3. Maximum possible size is 31x31.

|-
| {{text anchor|WORK_LOCATION}}
| x:y
| The tile (1:1 for upper-left) in which dwarves will stand when they are performing tasks. Defaults to 3:3 (bottom-right).

|-
| {{text anchor|BUILD_LABOR}}
| [[labor token]]
| The labor required to construct the custom building. If multiple BUILD_LABOR tokens are specified, then any of the indicated labors can be used to construct the building; if none are specified, then no labors are required. For furnaces, this labor does not come into play until after the workshop has been designed by an [[architect]].

|-
| {{text anchor|BUILD_KEY}}
| [[Interface.txt#Key_bindings|key bind]]
| The shortcut key used in the Build menu for selecting the custom building. For example: "CUSTOM_SHIFT_S"

|-
| {{text anchor|BLOCK}}
|
* row
* tiles...
| Specifies whether or not each workshop tile blocks movement. The first parameter is the row (1 = top), and each subsequent parameter is a 0 (nonblocking) or 1 (blocking) for each column, left to right.

|-
| {{text anchor|TILE}}
|
* stage
* row
* tiles...
| Specifies the characters used to represent the custom building. The first parameter is the building stage, varying from 0 (awaiting construction) to N (completed) where N is between 1 and 3, the 2nd parameter is the row number, and each subsequent parameter is a character number (or literal character enclosed in 'quotes').

|-
| {{text anchor|COLOR}}
|
* stage
* row
* colors...
| Specifies the colors in which the custom building's tiles will be displayed. The first parameter is the building stage, the 2nd parameter is the row number, and subsequent parameters are either sets of 3 numbers (foreground:background:brightness) or the token "MAT" to use the color of the primary building material. MAT may not be available on BUILDING_FURNACEs.{{verify}}

|-
| {{text anchor|BUILD_ITEM}}
|
* quantity
* [[item token]]
* [[material token]]
| Specifies one of the objects necessary to construct the custom building. Each BUILD_ITEM can be followed by zero or more modifiers.

|-
| {{text anchor|NEEDS_MAGMA}}
|
| Specifies that one of the building's tiles (other than the WORK_LOCATION) must be hanging over [[magma]] in order for the building to function. Buildings with this token also ignore the [FUEL] token in their reactions.
|}

==Item Modifiers==
Building items have many of the same modifiers as [[Reactions#Modifiers|reagents]] in custom reactions.

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| [{{text anchor|ANY_BONE_MATERIAL}}]
| Item material must have the [BONE] token.
|-
| [{{text anchor|ANY_HORN_MATERIAL}}]
| Item material must have the [HORN] token.
|-
| [{{text anchor|ANY_LEATHER_MATERIAL}}]
| Item material must have the [LEATHER] token.
|-
| [{{text anchor|ANY_PEARL_MATERIAL}}]
| Item material must have the [PEARL] token.
|-
| [{{text anchor|ANY_PLANT_MATERIAL}}]
| Item material must be subordinate to a PLANT object.
|-
| [{{text anchor|ANY_SHELL_MATERIAL}}]
| Item material must have the [SHELL] token.
|-
| [{{text anchor|ANY_SILK_MATERIAL}}]
| Item material must have the [SILK] token.
|-
| [{{text anchor|ANY_SOAP_MATERIAL}}]
| Item material must have the [SOAP] token.
|-
| [{{text anchor|ANY_STRAND_TISSUE}}]
| Item is made of a tissue having [TISSUE_SHAPE:STRANDS], intended for matching hair and wool. Must be used with [USE_BODY_COMPONENT].
|-
| [{{text anchor|ANY_TOOTH_MATERIAL}}]
| Item material must have the [TOOTH] token.
|-
| [{{text anchor|ANY_YARN_MATERIAL}}]
| Item material must have the [YARN] token.
|-
| [{{text anchor|BAG}}]
| Item must be a bag - that is, a BOX made of plant fiber, silk, yarn, or leather.
|-
| [{{text anchor|BUILDMAT}}]
| Item must be a general [[building material]] - BAR, BLOCKS, BOULDER, or WOOD.
|-
| [{{text anchor|CAN_USE_ARTIFACT}}]
| Item can be an Artifact.
|-
| [{{text anchor|CONTAINS_LYE}}]
| Item must be a BARREL or TOOL which contains at least one item of type LIQUID_MISC made of LYE.
|-
| [{{text anchor|EMPTY}}]
| If the item is a container, it must be empty.
|-
| [{{text anchor|FIRE_BUILD_SAFE}}]
| Item material must be stable at temperatures below 11000. Only works with items of type BAR, BLOCKS, BOULDER, WOOD, and ANVIL - all others are considered unsafe.
|-
| [{{text anchor|GLASS_MATERIAL}}]
| Item material must have the [IS_GLASS] token. All 3 types of [[glass]] have this token hardcoded.
|-
| [{{text anchor|HAS_MATERIAL_REACTION_PRODUCT}}:X]
| Item's material has a [MATERIAL_REACTION_PRODUCT] token with the appropriate ID.
|-
| [{{text anchor|HAS_TOOL_USE}}:X]
| Item must be a [[tool]] with the specific TOOL_USE value. The item type must be TOOL:NONE for this to make any sense.
|-
| [{{text anchor|MAGMA_BUILD_SAFE}}]
| Item material must be stable at temperatures below 12000. Only works with items of type BAR, BLOCKS, BOULDER, WOOD, and ANVIL - all others are considered unsafe.
|-
| [{{text anchor|METAL_ORE}}:X]
| Item material must be an ore of the specified metal.
|-
| [{{text anchor|MIN_DIMENSION}}:X]
| Item's dimension must be at least this large. The item type must be BAR, POWDER_MISC, LIQUID_MISC, DRINK, THREAD, or CLOTH for this to work.
|-
| [{{text anchor|NO_EDGE_ALLOWED}}]
| Item must not have an edge - excludes sharp stones (produced using knapping) and most types of weapon/ammo.
|-
| [{{text anchor|NOT_CONTAIN_BARREL_ITEM}}]
| If the item is a container, it must not contain [[lye]] or [[milk]]. Not necessary if specifying [EMPTY].
|-
| [{{text anchor|NOT_ENGRAVED}}]
| Item has not been engraved (excludes memorial slabs).
|-
| [{{text anchor|NOT_WEB}}]
| Item must be collected (to distinguish silk thread from webs). Only makes sense for items of type THREAD.
|-
| [{{text anchor|POTASHABLE}}] (Deprecated)
| Alias for [CONTAINS_LYE].
|-
| [{{text anchor|REACTION_CLASS}}:X]
| Item's material has a [REACTION_CLASS] token with the appropriate ID.
|-
| [{{text anchor|UNROTTEN}}]
| Item must not be rotten, mainly for organic materials.
|-
| [{{text anchor|USE_BODY_COMPONENT}}]
| Item must be a body part (CORPSE or CORPSEPIECE).
|-
| [{{text anchor|WEB_ONLY}}]
| Item must be undisturbed (to distinguish silk thread from webs). Only makes sense for items of type THREAD.
|-
| [{{text anchor|WORTHLESS_STONE_ONLY}}]
| Item material must be non-[[economic]].
|}

{{Category|Modding}}
{{Category|Tokens}}
[[ru:Building token]]

Reaction

2021-05-22T16:00:12Z

Ralpha: reordered item alphabetically

{{Quality|Superior|19:56, 28 August 2013 (UTC)}}
{{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 (sometimes) quite simple to add additional ones. There is a separate page with custom [[reaction examples]].

== Reaction differences between modes ==

In [[fortress mode]], reactions are linked to specific buildings, and must be added to a civilization's [[entity token|entity file]] to be usable by that civilization. This has the useful effect of limiting new items and materials (such as special [[wood]] or [[metal]]) to civilizations that have the requisite reaction — so that if you give your custom civilization a reaction to produce "star metal" or some other custom material, only they will be able to use it.

In [[adventure mode]], reactions are freely available in the {{k|x}} menu via the {{DFtext|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]
* ''[[#Reaction identifier|identifier]]'': The internal ID of the reaction.
* ''[[#Reaction name|name]]'': The name of the reaction, visible to the player in the Fortress mode or Adventure mode menus.
* ''[[#Building|building]]'': The building ID that the reaction uses, and the relevant keyboard shortcut.
* ''[[#Reagents|...reagents...]]'': Zero or more reagents (ingredients) that are required to be in stock for the reaction to be possible.
* ''[[#Products|...products...]]'': Zero or more products that are created from the reaction.
* ''[[#fuel|fuel]]'': (optional) If present, the reaction requires charcoal, coke or a magma-powered workshop.
* ''[[#skill|skill]]'': (optional) The skill required and trained by the reaction.
* ''[[#automatic|automatic]]'': (optional) If present, the reaction will automatically be enqueued whenever it can possibly be performed.
* ''[[#adventure mode|adventure mode]]'': (optional) If present, the reaction is used by the player in Adventure mode instead.

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

=== Reaction name ===

This can be anything at all, and is usually used to describe the reaction. '''Tan a hide''', for example, is the name of the default leather-producing reaction. Generally this should be written as a small descriptive verb phrase, with the first letter capitalized, for consistency with the existing reactions.

=== Building ===

[BUILDING:<BUILDING NAME>:<BUILDING KEY>]
* ''name'': The ID (that is the internal TOKEN each building can be referred to into reactions) 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 TOKENS are as follows:
* KILN - [[Kiln]] and [[Magma kiln]]
* SMELTER - [[Smelter]] and [[Magma smelter]]
* TANNER - [[Tanner's shop]]
* KITCHEN - [[Kitchen]]
* QUERN - [[Quern]]
* MILLSTONE - [[Millstone]]
* STILL - [[Still]]
* FARMER - [[Farmer's workshop]]
* CRAFTSMAN - [[Craftsdwarf's workshop]]
* GLASS{{version|0.42.01}} - [[Glass furnace]]
* WOOD{{version|0.42.01}} - [[Wood furnace]]
* MASON{{version|0.42.01}} - [[Mason's workshop]]
* ASHERY{{version|0.42.01}} - [[Ashery]]
* LEATHER{{version|0.42.01}} - [[Leather works]]
* BOWYER{{version|0.42.01}} - [[Bowyer's workshop]]
* SIEGE{{version|0.42.01}} - [[Siege workshop]]
* CLOTHES{{version|0.42.01}} - [[Clothier's shop]]
* METALSMITH{{version|0.42.01}} - [[Metalsmith's forge]]
* CARPENTER{{version|0.42.01}} - [[Carpenter's workshop]]
* Any custom (raw-defined) building type, such as:
** SOAP_MAKER - [[Soap maker's workshop]]
** SCREW_PRESS - [[Screw press]]

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

=== Category ===

{{new in v0.42}}

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.

{| {{prettytable}}
|- bgcolor="#dddddd"
! 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 || [[interface.txt|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.
|}

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

==== name ====

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

Most reagents are simply named '''A''', '''B''', and so forth in default reactions, although names such as '''TOOLSTONE''' 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 token]]s 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 [[item token|full list]] is available.

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

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

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

==== material token ====

[[Material token]]s come in several forms. For most reagents, this will typically be INORGANIC:MATERIAL_ID or NONE:NONE (to allow multiple materials using other 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:

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| [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|name]] of the reagent).
|-
| [UNROTTEN]
| Reagent must not be rotten, mainly for organic materials.
|-
| style="vertical-align: top"| [CONTAINS_LYE]
| Reagent must be a BARREL or TOOL which contains at least one item of type LIQUID_MISC made of LYE. Use of this token is discouraged, as it does not work with buckets (instead, use [CONTAINS:lye] — note the colon — and a corresponding lye reagent [REAGENT:lye:150:LIQUID_MISC:NONE:LYE]).
|-
| [POTASHABLE]
| Alias for [CONTAINS_LYE].
|-
| [NOT_WEB]
| Reagent must be collected (to distinguish silk thread from webs). Only makes sense for items of type THREAD.
|-
| [WEB_ONLY]
| Reagent must be undisturbed (to distinguish silk thread from webs). Only makes sense for items of type THREAD.
|-
| [EMPTY]
| If the reagent is a container, it must be empty.
|-
| [NOT_CONTAIN_BARREL_ITEM]
| If the reagent is a container, it must not contain [[lye]] or [[milk]]. Not necessary if specifying [EMPTY].
|-
| [BAG]
| Reagent must be a bag - that is, a BOX made of plant fiber, silk, yarn, or leather.
|-
| [GLASS_MATERIAL]
| Reagent material must have the [IS_GLASS] token. All 3 types of [[glass]] have this token hardcoded.
|-
| [BUILDMAT]
| Reagent must be a general [[building material]] - BAR, BLOCKS, BOULDER, or WOOD.
|-
| [FIRE_BUILD_SAFE]
| Reagent material must be 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 - excludes sharp stones (produced using knapping) and most types of weapon/ammo.
|-
| [HAS_EDGE]{{version|0.42.01}}
| Reagent must have an edge.
|-
| [NOT_ENGRAVED]
| Reagent has not been engraved (excludes memorial slabs).
|-
| [NOT_IMPROVED]
| Reagent has not been decorated.
|-
| [DOES_NOT_ABSORB]
| Reagent material must have [ABSORPTION:0]
|-
| [FOOD_STORAGE_CONTAINER]
| Reagent is either a BARREL or a TOOL with the FOOD_STORAGE use.
|-
| [HARD_ITEM_MATERIAL]
| 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 [[stack]]s 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.

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| [FORCE_EDGE]
| Product is given a sharp edge. Used for knapping.
|-
| [PRODUCT_PASTE]
| Product is created in the SOLID_PASTE state.
|-
| [PRODUCT_PRESSED]
| Product is created in the SOLID_PRESSED state.
|-
| [PRODUCT_DIMENSION:<size>]
| Specifies the 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:

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| COVERED
| Item is encrusted/studded/decorated with <material>.
|-
| GLAZED
| Item is glazed with <material>.
|-
| RINGS_HANGING
| Item is adorned with hanging rings of <material>.
|-
| BANDS
| Item is encircled with bands of <material>.
|-
| SPIKES
| Item menaces with spikes of <material>.
|-
| 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 token|SKILL token]] determines what skill the reaction requires and what skill it trains. Only one skill may be specified. For custom reactions, the amount of experience gained is linearly correlated with the amount of product created; a reaction with no product will yield no experience for the performing dwarf. A reaction with no skill associated will always be instant.

One may also adjust how much skill is gained using the [SKILL_IP:<integer>] token. The default is 30; more will increase the amount of skill gain. Attribute gain from the skill gain can also be adjusted with [ATTRIBUTE_IP:<integer>], with the default being 10.{{version|0.47.01}}

It's also possible to change how much skill affects the outcome (i.e. quality) of the reaction using the [SKILL_ROLL_RANGE:<basic range>:<multiplier>] token.{{version|0.47.01}} The default is [SKILL_ROLL_RANGE:11:5]. The first number is the base roll and the second number is how much the dwarf's skill can affect the reaction; the skill roll is random(basic 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 basic range is 1). The higher result on the roll, the better. Both numbers can be lowered to the skill harder. For example, 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 have 0 to 10 while legendary+0 (skill 15) dwarves can have 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 range from 0 to 40 for proficient dwarves, with unskilled dwarves always having 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.{{version|0.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:

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

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

|-
| {{text anchor|ANY_BONE_MATERIAL}}
|
| Reagent material must have the [BONE] token.

|-
| {{text anchor|ANY_HORN_MATERIAL}}
|
| Reagent material must have the [HORN] token.

|-
| {{text anchor|ANY_LEATHER_MATERIAL}}
|
| Reagent material must have the [LEATHER] token.

|-
| {{text anchor|ANY_PEARL_MATERIAL}}
|
| Reagent material must have the [PEARL] token.

|-
| {{text anchor|ANY_PLANT_MATERIAL}}
|
| Reagent material must be subordinate to a PLANT object.

|-
| {{text anchor|ANY_SHELL_MATERIAL}}
|
| Reagent material must have the [SHELL] token.

|-
| {{text anchor|ANY_SILK_MATERIAL}}
|
| Reagent material must have the [SILK] token.

|-
| {{text anchor|ANY_SOAP_MATERIAL}}
|
| Reagent material must have the [SOAP] token.

|-
| {{text anchor|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].

|-
| {{text anchor|ANY_TOOTH_MATERIAL}}
|
| Reagent material must have the [TOOTH] token.

|-
| {{text anchor|ANY_YARN_MATERIAL}}
|
| Reagent material must have the [YARN] token.

|-
| {{text anchor|ATTRIBUTE_IP}}{{version|0.47.01}}
| integer
| Amount of attributes given per skill improvement. Default is 10.

|-
| {{text anchor|AUTOMATIC}}
|
| the reaction will be queued automatically if the reaction reagents are all present.

|-
| {{text anchor|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.

|-
| {{text anchor|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

|-
| {{text anchor|BUILDMAT}}
|
| Reagent is able to be used to build structures (Stone, Wood, Blocks, Bars?).

|-
| {{text anchor|CAN_USE_ARTIFACT}}
|
| Reagent can be an Artifact. Using [PRESERVE_REAGENT] with this is strongly advised.

|-
| {{text anchor|CAN_USE_HOSPITAL_RESERVED}}{{version|0.42.01}}
|
| Allows the reagent to be an item that is otherwise reserved for use by a [[healthcare|hospital]].

|-
| {{text anchor|CAN_USE_LOCATION_RESERVED}}{{version|0.42.01}}
|
| Allows the reagent to be an item that is otherwise reserved for use by a [[locations|location]].

|-
| {{text anchor|CATEGORY}}{{version|0.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.

|-
| {{text anchor|CATEGORY_NAME}}{{version|0.42.01}}
| String
| The name of the category as displayed in-game.

|-
| {{text anchor|CATEGORY_DESCRIPTION}}{{version|0.42.01}}
| String
| 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}}
| Category ID
| 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}}
| [[interface.txt|Hotkey token]]
| 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}}
| required content
| Reagent is a container that holds the specified reagent.

|-
| {{text anchor|CONTAINS_LYE}} (Deprecated)
|
| 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}}
| String
| Description of the reaction

|-
| {{text anchor|DOES_NOT_ABSORB}}
|
| Reagent material must have [ABSORPTION:0]

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

|-
| {{text anchor|EMPTY}}
|
| If the reagent is a container, it must be empty.

|-
| {{text anchor|FIRE_BUILD_SAFE}}
|
| Reagent must be considered fire safe - i.e. not wood, and not coal.

|-
| {{text anchor|FORCE_EDGE}}
|
| Product is given a sharp edge. Used for knapping.

|-
| {{text anchor|FOOD_STORAGE_CONTAINER}}
|
| Reagent must be a barrel or any non-absorbing tool with [TOOL_USE:FOOD_STORAGE]

|-
| {{text anchor|FUEL}}
|
| Requires that the reaction either use up a unit of coal or charcoal or else be performed at a magma workshop

|-
| {{text anchor|GLASS_MATERIAL}}
|
| Reagent material has [IS_GLASS].

|-
| {{text anchor|HAS_EDGE}}{{version|0.42.01}}
|
| Reagent must be sharpened (used for carving).

|-
| {{text anchor|HAS_ITEM_REACTION_PRODUCT}}
| PRODUCT_ID (custom)
| 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}}
| PRODUCT_ID (custom)
| 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}}
| Tool-use token
| 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.

|-
| {{text anchor|HAS_WRITING_IMPROVEMENT}}{{version|0.42.01}}
|
| Reagent must contain writing.

|-
| {{text anchor|IMPROVEMENT}}
|
* Probability
* Reagent Name
* Improvement type
* Material Token
| Improvement types include BANDS, COVERED, GLAZED, RINGS_HANGING, and SPIKES

|-
| {{text anchor|MAGMA_BUILD_SAFE}}
|
| Currently broken - behaves exactly the same as FIRE_BUILD_SAFE.

|-
| {{text anchor|MAX_MULTIPLIER}}{{version|0.42.01}}
| number
| 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}}
|
* Inorganic material
| Reagent material must be an ore of the specified metal

|-
| {{text anchor|MIN_DIMENSION}}
|
* size
| Requires that the reagent have a dimension of at least this value. Only effective with BAR, POWDER_MISC, LIQUID_MISC, DRINK, THREAD, CLOTH, and GLOB items.

|-
| {{text anchor|NAME}}
| name
| defines the name used by the reaction in-game

|-
| {{text anchor|NO_EDGE_ALLOWED}}
|
| Reagent must not be sharpened (used for knapping).

|-
| {{text anchor|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.

|-
| {{text anchor|NOT_ENGRAVED}}
|
| Reagent must not be an engraved memorial slab.
|-
| {{text anchor|NOT_IMPROVED}}
|
| Reagent has not been decorated.

|-
| {{text anchor|NOT_PRESSED}}
|
| Reagent must not be in the SOLID_PRESSED state.

|-
| {{text anchor|NOT_WEB}}
|
| Reagent must be "collected" - used with THREAD:NONE to exclude webs.

|-
| {{text anchor|POTASHABLE}} (Deprecated)
|
| Alias for CONTAINS_LYE.

|-
| {{text anchor|PRESERVE_REAGENT}}
|
| Reagent is not destroyed, which is the normal effect, at the completion of the reaction. Typically used for containers.

|-
| {{text anchor|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.

|-
| {{text anchor|PRODUCT_DIMENSION}}
| size
| 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.

|-
| {{text anchor|PRODUCT_PASTE}}
|
| Product is created in the SOLID_PASTE state.

|-
| {{text anchor|PRODUCT_PRESSED}}
|
| Product is created in the SOLID_PRESSED state.

|-
| {{text anchor|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.

|-
| {{text anchor|PRODUCT_TOKEN}}{{version|0.42.01}}
| name
| 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}}
| Identifier
| defines a new reaction

|-
| {{text anchor|REACTION_CLASS}}
| CLASS_ID (custom)
| 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).

|-
| {{text anchor|REAGENT}}
|
* name/id
* quantity
* [[item token]]
* [[material token]]
| Requires a given reagent as an input for a reaction

|-
| {{text anchor|SKILL}}
| Skill Token
| Skill used by the reaction

|-
| {{text anchor|SKILL_IP}}{{version|0.47.01}}
| integer
| Amount of skill given per product made. Default is 30.

|-
| {{text anchor|SKILL_ROLL_RANGE}}{{version|0.47.01}}
|
* basic range
* multiplier
| The skill roll is random(basic range) + random((skill level * multipler)/2 + 1) + random((skill level * multipler)/2 + 1). random(x) returns a number between 0 and x-1, so basic range is always 1 or more. The default is 11. The default multiplier is 5. Higher skill rolls give better results.

|-
| {{text anchor|TRANSFER_ARTIFACT_STATUS}}{{version|0.42.01}}
|
| Transfers artifact status from the reagent to the product.

|-
| {{text anchor|UNROTTEN}}
|
| Reagent must not be rotten, mainly for organic materials.

|-
| {{text anchor|USE_BODY_COMPONENT}}
|
| Reagent material must come off a creature's body.

|-
| {{text anchor|WEB_ONLY}}
|
| Reagent must be "undisturbed" - used with THREAD:NONE to gather webs.

|-
| {{text anchor|WORTHLESS_STONE_ONLY}}
|
| Reagent is not made of an economic stone.

|}

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

Building token

2021-05-22T15:15:59Z

Ralpha: reordered item alphabetically

{{Quality|Superior|21:42, 20 September 2016 (UTC)}}
{{av}}

'''Building tokens''' control the functionality of custom buildings.

All custom buildings are defined as objects of type BUILDING_WORKSHOP or BUILDING_FURNACE; workshops show up in the {{K|b}}-{{K|w}} menu, while furnaces show up in the {{K|b}}-{{K|e}} menu.

You also must add any new custom buildings to the [[Entity token|civilization]] that you want to use it.

Additionally, furnaces must be designed by an [[architect]] before being constructed (and will gain [[quality]] accordingly), though they will always use the labor(s) specified in the building definition, rather than ones based on the materials being used.

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

|-
| {{text anchor|NAME}}
| name
| The name of the custom building.

|-
| {{text anchor|NAME_COLOR}}
| [[Color#Modding_color|fg:bg:bright]]
| The color of the building's name when {{K|q}}uerying it. Seemingly ignored for furnaces, which are hardcoded to 4:0:1.

|-
| {{text anchor|DIM}}
| width:height
| The size of the custom building, in number of tiles. Defaults to 3:3. Maximum possible size is 31x31.

|-
| {{text anchor|WORK_LOCATION}}
| x:y
| The tile (1:1 for upper-left) in which dwarves will stand when they are performing tasks. Defaults to 3:3 (bottom-right).

|-
| {{text anchor|BUILD_LABOR}}
| [[labor token]]
| The labor required to construct the custom building. If multiple BUILD_LABOR tokens are specified, then any of the indicated labors can be used to construct the building; if none are specified, then no labors are required. For furnaces, this labor does not come into play until after the workshop has been designed by an [[architect]].

|-
| {{text anchor|BUILD_KEY}}
| [[Interface.txt#Key_bindings|key bind]]
| The shortcut key used in the Build menu for selecting the custom building. For example: "CUSTOM_SHIFT_S"

|-
| {{text anchor|BLOCK}}
|
* row
* tiles...
| Specifies whether or not each workshop tile blocks movement. The first parameter is the row (1 = top), and each subsequent parameter is a 0 (nonblocking) or 1 (blocking) for each column, left to right.

|-
| {{text anchor|TILE}}
|
* stage
* row
* tiles...
| Specifies the characters used to represent the custom building. The first parameter is the building stage, varying from 0 (awaiting construction) to N (completed) where N is between 1 and 3, the 2nd parameter is the row number, and each subsequent parameter is a character number (or literal character enclosed in 'quotes').

|-
| {{text anchor|COLOR}}
|
* stage
* row
* colors...
| Specifies the colors in which the custom building's tiles will be displayed. The first parameter is the building stage, the 2nd parameter is the row number, and subsequent parameters are either sets of 3 numbers (foreground:background:brightness) or the token "MAT" to use the color of the primary building material. MAT may not be available on BUILDING_FURNACEs.{{verify}}

|-
| {{text anchor|BUILD_ITEM}}
|
* quantity
* [[item token]]
* [[material token]]
| Specifies one of the objects necessary to construct the custom building. Each BUILD_ITEM can be followed by zero or more modifiers.

|-
| {{text anchor|NEEDS_MAGMA}}
|
| Specifies that one of the building's tiles (other than the WORK_LOCATION) must be hanging over [[magma]] in order for the building to function. Buildings with this token also ignore the [FUEL] token in their reactions.
|}

==Item Modifiers==
Building items have many of the same modifiers as [[Reactions#Modifiers|reagents]] in custom reactions.

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| [{{text anchor|ANY_BONE_MATERIAL}}]
| Item material must have the [BONE] token.
|-
| [{{text anchor|ANY_HORN_MATERIAL}}]
| Item material must have the [HORN] token.
|-
| [{{text anchor|ANY_LEATHER_MATERIAL}}]
| Item material must have the [LEATHER] token.
|-
| [{{text anchor|ANY_PEARL_MATERIAL}}]
| Item material must have the [PEARL] token.
|-
| [{{text anchor|ANY_PLANT_MATERIAL}}]
| Item material must be subordinate to a PLANT object.
|-
| [{{text anchor|ANY_SHELL_MATERIAL}}]
| Item material must have the [SHELL] token.
|-
| [{{text anchor|ANY_SILK_MATERIAL}}]
| Item material must have the [SILK] token.
|-
| [{{text anchor|ANY_SOAP_MATERIAL}}]
| Item material must have the [SOAP] token.
|-
| [{{text anchor|ANY_STRAND_TISSUE}}]
| Item is made of a tissue having [TISSUE_SHAPE:STRANDS], intended for matching hair and wool. Must be used with [USE_BODY_COMPONENT].
|-
| [{{text anchor|ANY_TOOTH_MATERIAL}}]
| Item material must have the [TOOTH] token.
|-
| [{{text anchor|ANY_YARN_MATERIAL}}]
| Item material must have the [YARN] token.
|-
| [{{text anchor|BAG}}]
| Item must be a bag - that is, a BOX made of plant fiber, silk, yarn, or leather.
|-
| [{{text anchor|BUILDMAT}}]
| Item must be a general [[building material]] - BAR, BLOCKS, BOULDER, or WOOD.
|-
| [{{text anchor|CAN_USE_ARTIFACT}}]
| Item can be an Artifact.
|-
| [{{text anchor|CONTAINS_LYE}}]
| Item must be a BARREL or TOOL which contains at least one item of type LIQUID_MISC made of LYE.
|-
| [{{text anchor|EMPTY}}]
| If the item is a container, it must be empty.
|-
| [{{text anchor|FIRE_BUILD_SAFE}}]
| Item material must be stable at temperatures below 11000. Only works with items of type BAR, BLOCKS, BOULDER, WOOD, and ANVIL - all others are considered unsafe.
|-
| [{{text anchor|GLASS_MATERIAL}}]
| Item material must have the [IS_GLASS] token. All 3 types of [[glass]] have this token hardcoded.
|-
| [{{text anchor|HAS_MATERIAL_REACTION_PRODUCT}}:X]
| Item's material has a [MATERIAL_REACTION_PRODUCT] token with the appropriate ID.
|-
| [{{text anchor|HAS_TOOL_USE}}:X]
| Item must be a [[tool]] with the specific TOOL_USE value. The item type must be TOOL:NONE for this to make any sense.
|-
| [{{text anchor|MAGMA_BUILD_SAFE}}]
| Item material must be stable at temperatures below 12000. Only works with items of type BAR, BLOCKS, BOULDER, WOOD, and ANVIL - all others are considered unsafe.
|-
| [{{text anchor|METAL_ORE}}:X]
| Item material must be an ore of the specified metal.
|-
| [{{text anchor|MIN_DIMENSION}}:X]
| Item's dimension must be at least this large. The item type must be BAR, POWDER_MISC, LIQUID_MISC, DRINK, THREAD, or CLOTH for this to work.
|-
| [{{text anchor|NO_EDGE_ALLOWED}}]
| Item must not have an edge - excludes sharp stones (produced using knapping) and most types of weapon/ammo.
|-
| [{{text anchor|NOT_CONTAIN_BARREL_ITEM}}]
| If the item is a container, it must not contain [[lye]] or [[milk]]. Not necessary if specifying [EMPTY].
|-
| [{{text anchor|NOT_ENGRAVED}}]
| Item has not been engraved (excludes memorial slabs).
|-
| [{{text anchor|NOT_WEB}}]
| Item must be collected (to distinguish silk thread from webs). Only makes sense for items of type THREAD.
|-
| [{{text anchor|POTASHABLE}}]
| Alias for [CONTAINS_LYE].
|-
| [{{text anchor|REACTION_CLASS}}:X]
| Item's material has a [REACTION_CLASS] token with the appropriate ID.
|-
| [{{text anchor|UNROTTEN}}]
| Item must not be rotten, mainly for organic materials.
|-
| [{{text anchor|USE_BODY_COMPONENT}}]
| Item must be a body part (CORPSE or CORPSEPIECE).
|-
| [{{text anchor|WEB_ONLY}}]
| Item must be undisturbed (to distinguish silk thread from webs). Only makes sense for items of type THREAD.
|-
| [{{text anchor|WORTHLESS_STONE_ONLY}}]
| Item material must be non-[[economic]].
|}

{{Category|Modding}}
{{Category|Tokens}}
[[ru:Building token]]

Building token

2021-05-22T15:03:15Z

Ralpha: reordered item alphabetically

{{Quality|Superior|21:42, 20 September 2016 (UTC)}}
{{av}}

'''Building tokens''' control the functionality of custom buildings.

All custom buildings are defined as objects of type BUILDING_WORKSHOP or BUILDING_FURNACE; workshops show up in the {{K|b}}-{{K|w}} menu, while furnaces show up in the {{K|b}}-{{K|e}} menu.

You also must add any new custom buildings to the [[Entity token|civilization]] that you want to use it.

Additionally, furnaces must be designed by an [[architect]] before being constructed (and will gain [[quality]] accordingly), though they will always use the labor(s) specified in the building definition, rather than ones based on the materials being used.

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

|-
| {{text anchor|NAME}}
| name
| The name of the custom building.

|-
| {{text anchor|NAME_COLOR}}
| [[Color#Modding_color|fg:bg:bright]]
| The color of the building's name when {{K|q}}uerying it. Seemingly ignored for furnaces, which are hardcoded to 4:0:1.

|-
| {{text anchor|DIM}}
| width:height
| The size of the custom building, in number of tiles. Defaults to 3:3. Maximum possible size is 31x31.

|-
| {{text anchor|WORK_LOCATION}}
| x:y
| The tile (1:1 for upper-left) in which dwarves will stand when they are performing tasks. Defaults to 3:3 (bottom-right).

|-
| {{text anchor|BUILD_LABOR}}
| [[labor token]]
| The labor required to construct the custom building. If multiple BUILD_LABOR tokens are specified, then any of the indicated labors can be used to construct the building; if none are specified, then no labors are required. For furnaces, this labor does not come into play until after the workshop has been designed by an [[architect]].

|-
| {{text anchor|BUILD_KEY}}
| [[Interface.txt#Key_bindings|key bind]]
| The shortcut key used in the Build menu for selecting the custom building. For example: "CUSTOM_SHIFT_S"

|-
| {{text anchor|BLOCK}}
|
* row
* tiles...
| Specifies whether or not each workshop tile blocks movement. The first parameter is the row (1 = top), and each subsequent parameter is a 0 (nonblocking) or 1 (blocking) for each column, left to right.

|-
| {{text anchor|TILE}}
|
* stage
* row
* tiles...
| Specifies the characters used to represent the custom building. The first parameter is the building stage, varying from 0 (awaiting construction) to N (completed) where N is between 1 and 3, the 2nd parameter is the row number, and each subsequent parameter is a character number (or literal character enclosed in 'quotes').

|-
| {{text anchor|COLOR}}
|
* stage
* row
* colors...
| Specifies the colors in which the custom building's tiles will be displayed. The first parameter is the building stage, the 2nd parameter is the row number, and subsequent parameters are either sets of 3 numbers (foreground:background:brightness) or the token "MAT" to use the color of the primary building material. MAT may not be available on BUILDING_FURNACEs.{{verify}}

|-
| {{text anchor|BUILD_ITEM}}
|
* quantity
* [[item token]]
* [[material token]]
| Specifies one of the objects necessary to construct the custom building. Each BUILD_ITEM can be followed by zero or more modifiers.

|-
| {{text anchor|NEEDS_MAGMA}}
|
| Specifies that one of the building's tiles (other than the WORK_LOCATION) must be hanging over [[magma]] in order for the building to function. Buildings with this token also ignore the [FUEL] token in their reactions.
|}

==Item Modifiers==
Building items have many of the same modifiers as [[Reactions#Modifiers|reagents]] in custom reactions.

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| [{{text anchor|ANY_BONE_MATERIAL}}]
| Item material must have the [BONE] token.
|-
| [{{text anchor|ANY_HORN_MATERIAL}}]
| Item material must have the [HORN] token.
|-
| [{{text anchor|ANY_LEATHER_MATERIAL}}]
| Item material must have the [LEATHER] token.
|-
| [{{text anchor|ANY_PEARL_MATERIAL}}]
| Item material must have the [PEARL] token.
|-
| [{{text anchor|ANY_PLANT_MATERIAL}}]
| Item material must be subordinate to a PLANT object.
|-
| [{{text anchor|ANY_SHELL_MATERIAL}}]
| Item material must have the [SHELL] token.
|-
| [{{text anchor|ANY_SILK_MATERIAL}}]
| Item material must have the [SILK] token.
|-
| [{{text anchor|ANY_SOAP_MATERIAL}}]
| Item material must have the [SOAP] token.
|-
| [{{text anchor|ANY_STRAND_TISSUE}}]
| Item is made of a tissue having [TISSUE_SHAPE:STRANDS], intended for matching hair and wool. Must be used with [USE_BODY_COMPONENT].
|-
| [{{text anchor|ANY_TOOTH_MATERIAL}}]
| Item material must have the [TOOTH] token.
|-
| [{{text anchor|ANY_YARN_MATERIAL}}]
| Item material must have the [YARN] token.
|-
| [{{text anchor|BAG}}]
| Item must be a bag - that is, a BOX made of plant fiber, silk, yarn, or leather.
|-
| [{{text anchor|BUILDMAT}}]
| Item must be a general [[building material]] - BAR, BLOCKS, BOULDER, or WOOD.
|-
| [{{text anchor|CAN_USE_ARTIFACT}}]
| Item can be an Artifact.
|-
| [{{text anchor|CONTAINS_LYE}}]
| Item must be a BARREL or TOOL which contains at least one item of type LIQUID_MISC made of LYE.
|-
| [{{text anchor|EMPTY}}]
| If the item is a container, it must be empty.
|-
| [{{text anchor|FIRE_BUILD_SAFE}}]
| Item material must be stable at temperatures below 11000. Only works with items of type BAR, BLOCKS, BOULDER, WOOD, and ANVIL - all others are considered unsafe.
|-
| [{{text anchor|GLASS_MATERIAL}}]
| Item material must have the [IS_GLASS] token. All 3 types of [[glass]] have this token hardcoded.
|-
| [{{text anchor|HAS_TOOL_USE}}:X]
| Item must be a [[tool]] with the specific TOOL_USE value. The item type must be TOOL:NONE for this to make any sense.
|-
| [{{text anchor|HAS_MATERIAL_REACTION_PRODUCT}}:X]
| Item's material has a [MATERIAL_REACTION_PRODUCT] token with the appropriate ID.
|-
| [{{text anchor|MAGMA_BUILD_SAFE}}]
| Item material must be stable at temperatures below 12000. Only works with items of type BAR, BLOCKS, BOULDER, WOOD, and ANVIL - all others are considered unsafe.
|-
| [{{text anchor|METAL_ORE}}:X]
| Item material must be an ore of the specified metal.
|-
| [{{text anchor|MIN_DIMENSION}}:X]
| Item's dimension must be at least this large. The item type must be BAR, POWDER_MISC, LIQUID_MISC, DRINK, THREAD, or CLOTH for this to work.
|-
| [{{text anchor|NO_EDGE_ALLOWED}}]
| Item must not have an edge - excludes sharp stones (produced using knapping) and most types of weapon/ammo.
|-
| [{{text anchor|NOT_CONTAIN_BARREL_ITEM}}]
| If the item is a container, it must not contain [[lye]] or [[milk]]. Not necessary if specifying [EMPTY].
|-
| [{{text anchor|NOT_ENGRAVED}}]
| Item has not been engraved (excludes memorial slabs).
|-
| [{{text anchor|NOT_WEB}}]
| Item must be collected (to distinguish silk thread from webs). Only makes sense for items of type THREAD.
|-
| [{{text anchor|POTASHABLE}}]
| Alias for [CONTAINS_LYE].
|-
| [{{text anchor|REACTION_CLASS}}:X]
| Item's material has a [REACTION_CLASS] token with the appropriate ID.
|-
| [{{text anchor|UNROTTEN}}]
| Item must not be rotten, mainly for organic materials.
|-
| [{{text anchor|USE_BODY_COMPONENT}}]
| Item must be a body part (CORPSE or CORPSEPIECE).
|-
| [{{text anchor|WEB_ONLY}}]
| Item must be undisturbed (to distinguish silk thread from webs). Only makes sense for items of type THREAD.
|-
| [{{text anchor|WORTHLESS_STONE_ONLY}}]
| Item material must be non-[[economic]].
|}

{{Category|Modding}}
{{Category|Tokens}}
[[ru:Building token]]

Building token

2021-05-22T14:59:31Z

Ralpha: reordered item alphabetically

{{Quality|Superior|21:42, 20 September 2016 (UTC)}}
{{av}}

'''Building tokens''' control the functionality of custom buildings.

All custom buildings are defined as objects of type BUILDING_WORKSHOP or BUILDING_FURNACE; workshops show up in the {{K|b}}-{{K|w}} menu, while furnaces show up in the {{K|b}}-{{K|e}} menu.

You also must add any new custom buildings to the [[Entity token|civilization]] that you want to use it.

Additionally, furnaces must be designed by an [[architect]] before being constructed (and will gain [[quality]] accordingly), though they will always use the labor(s) specified in the building definition, rather than ones based on the materials being used.

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

|-
| {{text anchor|NAME}}
| name
| The name of the custom building.

|-
| {{text anchor|NAME_COLOR}}
| [[Color#Modding_color|fg:bg:bright]]
| The color of the building's name when {{K|q}}uerying it. Seemingly ignored for furnaces, which are hardcoded to 4:0:1.

|-
| {{text anchor|DIM}}
| width:height
| The size of the custom building, in number of tiles. Defaults to 3:3. Maximum possible size is 31x31.

|-
| {{text anchor|WORK_LOCATION}}
| x:y
| The tile (1:1 for upper-left) in which dwarves will stand when they are performing tasks. Defaults to 3:3 (bottom-right).

|-
| {{text anchor|BUILD_LABOR}}
| [[labor token]]
| The labor required to construct the custom building. If multiple BUILD_LABOR tokens are specified, then any of the indicated labors can be used to construct the building; if none are specified, then no labors are required. For furnaces, this labor does not come into play until after the workshop has been designed by an [[architect]].

|-
| {{text anchor|BUILD_KEY}}
| [[Interface.txt#Key_bindings|key bind]]
| The shortcut key used in the Build menu for selecting the custom building. For example: "CUSTOM_SHIFT_S"

|-
| {{text anchor|BLOCK}}
|
* row
* tiles...
| Specifies whether or not each workshop tile blocks movement. The first parameter is the row (1 = top), and each subsequent parameter is a 0 (nonblocking) or 1 (blocking) for each column, left to right.

|-
| {{text anchor|TILE}}
|
* stage
* row
* tiles...
| Specifies the characters used to represent the custom building. The first parameter is the building stage, varying from 0 (awaiting construction) to N (completed) where N is between 1 and 3, the 2nd parameter is the row number, and each subsequent parameter is a character number (or literal character enclosed in 'quotes').

|-
| {{text anchor|COLOR}}
|
* stage
* row
* colors...
| Specifies the colors in which the custom building's tiles will be displayed. The first parameter is the building stage, the 2nd parameter is the row number, and subsequent parameters are either sets of 3 numbers (foreground:background:brightness) or the token "MAT" to use the color of the primary building material. MAT may not be available on BUILDING_FURNACEs.{{verify}}

|-
| {{text anchor|BUILD_ITEM}}
|
* quantity
* [[item token]]
* [[material token]]
| Specifies one of the objects necessary to construct the custom building. Each BUILD_ITEM can be followed by zero or more modifiers.

|-
| {{text anchor|NEEDS_MAGMA}}
|
| Specifies that one of the building's tiles (other than the WORK_LOCATION) must be hanging over [[magma]] in order for the building to function. Buildings with this token also ignore the [FUEL] token in their reactions.
|}

==Item Modifiers==
Building items have many of the same modifiers as [[Reactions#Modifiers|reagents]] in custom reactions.

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| [{{text anchor|ANY_PLANT_MATERIAL}}]
| Item material must be subordinate to a PLANT object.
|-
| [{{text anchor|ANY_SILK_MATERIAL}}]
| Item material must have the [SILK] token.
|-
| [{{text anchor|ANY_YARN_MATERIAL}}]
| Item material must have the [YARN] token.
|-
| [{{text anchor|ANY_SOAP_MATERIAL}}]
| Item material must have the [SOAP] token.
|-
| [{{text anchor|ANY_LEATHER_MATERIAL}}]
| Item material must have the [LEATHER] token.
|-
| [{{text anchor|ANY_BONE_MATERIAL}}]
| Item material must have the [BONE] token.
|-
| [{{text anchor|ANY_STRAND_TISSUE}}]
| Item is made of a tissue having [TISSUE_SHAPE:STRANDS], intended for matching hair and wool. Must be used with [USE_BODY_COMPONENT].
|-
| [{{text anchor|ANY_SHELL_MATERIAL}}]
| Item material must have the [SHELL] token.
|-
| [{{text anchor|ANY_TOOTH_MATERIAL}}]
| Item material must have the [TOOTH] token.
|-
| [{{text anchor|ANY_HORN_MATERIAL}}]
| Item material must have the [HORN] token.
|-
| [{{text anchor|ANY_PEARL_MATERIAL}}]
| Item material must have the [PEARL] token.
|-
| [{{text anchor|BAG}}]
| Item must be a bag - that is, a BOX made of plant fiber, silk, yarn, or leather.
|-
| [{{text anchor|BUILDMAT}}]
| Item must be a general [[building material]] - BAR, BLOCKS, BOULDER, or WOOD.
|-
| [{{text anchor|CAN_USE_ARTIFACT}}]
| Item can be an Artifact.
|-
| [{{text anchor|CONTAINS_LYE}}]
| Item must be a BARREL or TOOL which contains at least one item of type LIQUID_MISC made of LYE.
|-
| [{{text anchor|EMPTY}}]
| If the item is a container, it must be empty.
|-
| [{{text anchor|FIRE_BUILD_SAFE}}]
| Item material must be stable at temperatures below 11000. Only works with items of type BAR, BLOCKS, BOULDER, WOOD, and ANVIL - all others are considered unsafe.
|-
| [{{text anchor|GLASS_MATERIAL}}]
| Item material must have the [IS_GLASS] token. All 3 types of [[glass]] have this token hardcoded.
|-
| [{{text anchor|HAS_TOOL_USE}}:X]
| Item must be a [[tool]] with the specific TOOL_USE value. The item type must be TOOL:NONE for this to make any sense.
|-
| [{{text anchor|HAS_MATERIAL_REACTION_PRODUCT}}:X]
| Item's material has a [MATERIAL_REACTION_PRODUCT] token with the appropriate ID.
|-
| [{{text anchor|MAGMA_BUILD_SAFE}}]
| Item material must be stable at temperatures below 12000. Only works with items of type BAR, BLOCKS, BOULDER, WOOD, and ANVIL - all others are considered unsafe.
|-
| [{{text anchor|METAL_ORE}}:X]
| Item material must be an ore of the specified metal.
|-
| [{{text anchor|MIN_DIMENSION}}:X]
| Item's dimension must be at least this large. The item type must be BAR, POWDER_MISC, LIQUID_MISC, DRINK, THREAD, or CLOTH for this to work.
|-
| [{{text anchor|NO_EDGE_ALLOWED}}]
| Item must not have an edge - excludes sharp stones (produced using knapping) and most types of weapon/ammo.
|-
| [{{text anchor|NOT_CONTAIN_BARREL_ITEM}}]
| If the item is a container, it must not contain [[lye]] or [[milk]]. Not necessary if specifying [EMPTY].
|-
| [{{text anchor|NOT_ENGRAVED}}]
| Item has not been engraved (excludes memorial slabs).
|-
| [{{text anchor|NOT_WEB}}]
| Item must be collected (to distinguish silk thread from webs). Only makes sense for items of type THREAD.
|-
| [{{text anchor|POTASHABLE}}]
| Alias for [CONTAINS_LYE].
|-
| [{{text anchor|REACTION_CLASS}}:X]
| Item's material has a [REACTION_CLASS] token with the appropriate ID.
|-
| [{{text anchor|UNROTTEN}}]
| Item must not be rotten, mainly for organic materials.
|-
| [{{text anchor|USE_BODY_COMPONENT}}]
| Item must be a body part (CORPSE or CORPSEPIECE).
|-
| [{{text anchor|WEB_ONLY}}]
| Item must be undisturbed (to distinguish silk thread from webs). Only makes sense for items of type THREAD.
|-
| [{{text anchor|WORTHLESS_STONE_ONLY}}]
| Item material must be non-[[economic]].
|}

{{Category|Modding}}
{{Category|Tokens}}
[[ru:Building token]]

DF2014 Talk:Building token

2021-05-22T14:20:35Z

Ralpha: /* Key Token? */

== Key Token? ==
What exactly is a "Key Token"?--[[Special:Contributions/87.143.19.205|87.143.19.205]] 22:52, 27 September 2014 (UTC)

This refers to the [[Interface.txt#Key_bindings|key bind]], Updated the article. --[[User:Ralpha|Ralpha]] ([[User talk:Ralpha|talk]]) 14:19, 22 May 2021 (UTC)

Building token

2021-05-22T14:17:55Z

Ralpha: Added key bind clarification

{{Quality|Superior|21:42, 20 September 2016 (UTC)}}
{{av}}

'''Building tokens''' control the functionality of custom buildings.

All custom buildings are defined as objects of type BUILDING_WORKSHOP or BUILDING_FURNACE; workshops show up in the {{K|b}}-{{K|w}} menu, while furnaces show up in the {{K|b}}-{{K|e}} menu.

You also must add any new custom buildings to the [[Entity token|civilization]] that you want to use it.

Additionally, furnaces must be designed by an [[architect]] before being constructed (and will gain [[quality]] accordingly), though they will always use the labor(s) specified in the building definition, rather than ones based on the materials being used.

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

|-
| {{text anchor|NAME}}
| name
| The name of the custom building.

|-
| {{text anchor|NAME_COLOR}}
| [[Color#Modding_color|fg:bg:bright]]
| The color of the building's name when {{K|q}}uerying it. Seemingly ignored for furnaces, which are hardcoded to 4:0:1.

|-
| {{text anchor|DIM}}
| width:height
| The size of the custom building, in number of tiles. Defaults to 3:3. Maximum possible size is 31x31.

|-
| {{text anchor|WORK_LOCATION}}
| x:y
| The tile (1:1 for upper-left) in which dwarves will stand when they are performing tasks. Defaults to 3:3 (bottom-right).

|-
| {{text anchor|BUILD_LABOR}}
| [[labor token]]
| The labor required to construct the custom building. If multiple BUILD_LABOR tokens are specified, then any of the indicated labors can be used to construct the building; if none are specified, then no labors are required. For furnaces, this labor does not come into play until after the workshop has been designed by an [[architect]].

|-
| {{text anchor|BUILD_KEY}}
| [[Interface.txt#Key_bindings|key bind]]
| The shortcut key used in the Build menu for selecting the custom building. For example: "CUSTOM_SHIFT_S"

|-
| {{text anchor|BLOCK}}
|
* row
* tiles...
| Specifies whether or not each workshop tile blocks movement. The first parameter is the row (1 = top), and each subsequent parameter is a 0 (nonblocking) or 1 (blocking) for each column, left to right.

|-
| {{text anchor|TILE}}
|
* stage
* row
* tiles...
| Specifies the characters used to represent the custom building. The first parameter is the building stage, varying from 0 (awaiting construction) to N (completed) where N is between 1 and 3, the 2nd parameter is the row number, and each subsequent parameter is a character number (or literal character enclosed in 'quotes').

|-
| {{text anchor|COLOR}}
|
* stage
* row
* colors...
| Specifies the colors in which the custom building's tiles will be displayed. The first parameter is the building stage, the 2nd parameter is the row number, and subsequent parameters are either sets of 3 numbers (foreground:background:brightness) or the token "MAT" to use the color of the primary building material. MAT may not be available on BUILDING_FURNACEs.{{verify}}

|-
| {{text anchor|BUILD_ITEM}}
|
* quantity
* [[item token]]
* [[material token]]
| Specifies one of the objects necessary to construct the custom building. Each BUILD_ITEM can be followed by zero or more modifiers.

|-
| {{text anchor|NEEDS_MAGMA}}
|
| Specifies that one of the building's tiles (other than the WORK_LOCATION) must be hanging over [[magma]] in order for the building to function. Buildings with this token also ignore the [FUEL] token in their reactions.
|}

==Item Modifiers==
Building items have many of the same modifiers as [[Reactions#Modifiers|reagents]] in custom reactions.

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| [{{text anchor|REACTION_CLASS}}:X]
| Item's material has a [REACTION_CLASS] token with the appropriate ID.
|-
| [{{text anchor|HAS_MATERIAL_REACTION_PRODUCT}}:X]
| Item's material has a [MATERIAL_REACTION_PRODUCT] token with the appropriate ID.
|-
| [{{text anchor|UNROTTEN}}]
| Item must not be rotten, mainly for organic materials.
|-
| [{{text anchor|CONTAINS_LYE}}]
| Item must be a BARREL or TOOL which contains at least one item of type LIQUID_MISC made of LYE.
|-
| [{{text anchor|POTASHABLE}}]
| Alias for [CONTAINS_LYE].
|-
| [{{text anchor|NOT_WEB}}]
| Item must be collected (to distinguish silk thread from webs). Only makes sense for items of type THREAD.
|-
| [{{text anchor|WEB_ONLY}}]
| Item must be undisturbed (to distinguish silk thread from webs). Only makes sense for items of type THREAD.
|-
| [{{text anchor|EMPTY}}]
| If the item is a container, it must be empty.
|-
| [{{text anchor|NOT_CONTAIN_BARREL_ITEM}}]
| If the item is a container, it must not contain [[lye]] or [[milk]]. Not necessary if specifying [EMPTY].
|-
| [{{text anchor|BAG}}]
| Item must be a bag - that is, a BOX made of plant fiber, silk, yarn, or leather.
|-
| [{{text anchor|GLASS_MATERIAL}}]
| Item material must have the [IS_GLASS] token. All 3 types of [[glass]] have this token hardcoded.
|-
| [{{text anchor|BUILDMAT}}]
| Item must be a general [[building material]] - BAR, BLOCKS, BOULDER, or WOOD.
|-
| [{{text anchor|FIRE_BUILD_SAFE}}]
| Item material must be stable at temperatures below 11000. Only works with items of type BAR, BLOCKS, BOULDER, WOOD, and ANVIL - all others are considered unsafe.
|-
| [{{text anchor|MAGMA_BUILD_SAFE}}]
| Item material must be stable at temperatures below 12000. Only works with items of type BAR, BLOCKS, BOULDER, WOOD, and ANVIL - all others are considered unsafe.
|-
| [{{text anchor|CAN_USE_ARTIFACT}}]
| Item can be an Artifact.
|-
| [{{text anchor|WORTHLESS_STONE_ONLY}}]
| Item material must be non-[[economic]].
|-
| [{{text anchor|ANY_PLANT_MATERIAL}}]
| Item material must be subordinate to a PLANT object.
|-
| [{{text anchor|ANY_SILK_MATERIAL}}]
| Item material must have the [SILK] token.
|-
| [{{text anchor|ANY_YARN_MATERIAL}}]
| Item material must have the [YARN] token.
|-
| [{{text anchor|ANY_SOAP_MATERIAL}}]
| Item material must have the [SOAP] token.
|-
| [{{text anchor|ANY_LEATHER_MATERIAL}}]
| Item material must have the [LEATHER] token.
|-
| [{{text anchor|ANY_BONE_MATERIAL}}]
| Item material must have the [BONE] token.
|-
| [{{text anchor|ANY_STRAND_TISSUE}}]
| Item is made of a tissue having [TISSUE_SHAPE:STRANDS], intended for matching hair and wool. Must be used with [USE_BODY_COMPONENT].
|-
| [{{text anchor|ANY_SHELL_MATERIAL}}]
| Item material must have the [SHELL] token.
|-
| [{{text anchor|ANY_TOOTH_MATERIAL}}]
| Item material must have the [TOOTH] token.
|-
| [{{text anchor|ANY_HORN_MATERIAL}}]
| Item material must have the [HORN] token.
|-
| [{{text anchor|ANY_PEARL_MATERIAL}}]
| Item material must have the [PEARL] token.
|-
| [{{text anchor|USE_BODY_COMPONENT}}]
| Item must be a body part (CORPSE or CORPSEPIECE).
|-
| [{{text anchor|NO_EDGE_ALLOWED}}]
| Item must not have an edge - excludes sharp stones (produced using knapping) and most types of weapon/ammo.
|-
| [{{text anchor|NOT_ENGRAVED}}]
| Item has not been engraved (excludes memorial slabs).
|-
| [{{text anchor|METAL_ORE}}:X]
| Item material must be an ore of the specified metal.
|-
| [{{text anchor|MIN_DIMENSION}}:X]
| Item's dimension must be at least this large. The item type must be BAR, POWDER_MISC, LIQUID_MISC, DRINK, THREAD, or CLOTH for this to work.
|-
| [{{text anchor|HAS_TOOL_USE}}:X]
| Item must be a [[tool]] with the specific TOOL_USE value. The item type must be TOOL:NONE for this to make any sense.
|}

{{Category|Modding}}
{{Category|Tokens}}
[[ru:Building token]]

Tissue definition token

2021-05-01T21:36:08Z

Ralpha: Added info to descriptions

{{Quality|Superior|12:23, 18 May 2015 (UTC)}}
{{av}}

__TOC__

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

|-
| {{text anchor|TISSUE_NAME}}
|
*name
*plural
|plural can alternatively be NP (No Plural) or STP (Standard Plural, adds an 's' on the end).

|-
| {{text anchor|TISSUE_MATERIAL}}
|
* [[material token]]
| Defines the tissue material.

|-
| {{text anchor|RELATIVE_THICKNESS}}
|
*value
| The relative thickness of the tissue. A higher thickness is harder to penetrate, but raising a tissue's relative thickness decreases the thickness of all other tissues.

|-
| {{text anchor|HEALING_RATE}}
|
*value
| Lower is faster. Omitting the token will result in a tissue that never heals.

|-
| {{text anchor|VASCULAR}}
|
*value
| Related to how much said tissue bleeds. Higher = More bleeding (Which is why the heart has the highest value.)

|-
| {{text anchor|PAIN_RECEPTORS}}
|
*value
| Related to how much pain your character will suffer when said tissue is damaged. Higher = More pain when damaged (Which is why the bone tissue has a much higher value than other tissues. A broken bone hurts a lot more than a flesh cut.)

|-
| {{text anchor|THICKENS_ON_STRENGTH}}
| N/A
| The thickness of the tissue increases when character strength increases.

|-
| {{text anchor|THICKENS_ON_ENERGY_STORAGE}}
| N/A
| Thickness of said tissue increases when the character eats and doesn't exercise sufficiently.

|-
| {{text anchor|ARTERIES}}
| N/A
| The tissue contains arteries. Edged attacks have the chance to break an artery, increasing blood loss.

|-
| {{text anchor|SCARS}}
| N/A
| Simply, whether or not the tissue will be scarred once healed.

|-
| {{text anchor|STRUCTURAL}}
| N/A
| Holds the body part together. A cut or a fracture disables the body part it's in.

|-
| {{text anchor|CONNECTIVE_TISSUE_ANCHOR}}
| N/A
| Any ligaments or tendons are part of this tissue. Vulnerable to edged attacks, damage disables the limb.

|-
| {{text anchor|SETTABLE}}
| N/A
| The tissue will not heal, or heals slower, until it is set by a bone doctor.

|-
| {{text anchor|SPLINTABLE}}
| N/A
| The broken tissue can be fixed with a cast or a splint to restore function while it heals.

|-
| {{text anchor|FUNCTIONAL}}
| N/A
| The tissue performs some sort of special function (e.g. sight, hearing, breathing, etc.) An organ with such a function will stop working if a sufficient amount of damage is sustained by its FUNCTIONAL tissues. If an organ has no FUNCTIONAL tissues, it will stop working only if it is severed or destroyed entirely by heat or cold.

|-
| {{text anchor|NERVOUS}}
| N/A
| Nervous function - not used. This token is used in [[Body_token#NERVOUS|[OBJECT:BODY]]] tokens.

|-
| {{text anchor|THOUGHT}}
| N/A
| If a creature has no functioning parts with the THOUGHT token, it will be unable to move or breathe. NO_THOUGHT_CENTER_FOR_MOVEMENT bypasses this limitation.

|-
| {{text anchor|MUSCULAR}}
| N/A
| Seems to affect where sensory or motor nerves are located, and whether damage to this tissue will render a limb useless.

|-
| {{text anchor|SMELL}}
| N/A
| Used to smell - not used. This token is used in [[Body_token#SMELL|[OBJECT:BODY]]] tokens.

|-
| {{text anchor|HEAR}}
| N/A
| Used to hearing - not used. This token is used in [[Body_token#HEAR|[OBJECT:BODY]]] tokens.

|-
| {{text anchor|FLIGHT}}
| N/A
| Unknown - not used. Most likely related to flying, see [[Body_token#FLIER|[FLIER] in [OBJECT:BODY]]].

|-
| {{text anchor|BREATHE}}
| N/A
| Used to breathing - not used. This token is used in [[Body_token#BREATHE|[OBJECT:BODY]]] tokens.

|-
| {{text anchor|SIGHT}}
| N/A
| Used to seeing - not used. This token is used in [[Body_token#SIGHT|[OBJECT:BODY]]] tokens.

|-
| {{text anchor|CONNECTS}}
| N/A
| Holds body parts together. A body part will not be severed unless all of its component tissues with the CONNECTS tag are severed.

|-
| {{text anchor|MAJOR_ARTERIES}}
| N/A
| Causes tissue to sometimes severely bleed when damaged. This is independent of its VASCULAR value.

|-
| {{text anchor|INSULATION}}
|
*value
| Tissue supplies the creature with heat insulation. Higher values result in more insulation.

|-
| {{text anchor|COSMETIC}}
| N/A
| ?

|-
| {{text anchor|STYLEABLE}}
| N/A
| The tissue can be styled as per a tissue style (defined in an [[Entity_token|entity]] entry)

|-
| {{text anchor|TISSUE_SHAPE}}
|
*value
| Value can be one of the following:
;LAYER
:Regular layer tissue.
;STRANDS
:Can be spun into thread at a farmer's workshop. Edge attacks will pass right through the tissue.
;FEATHERS
:Edge attacks will pass right through the tissue.
;SCALES
:?
;CUSTOM
:?

|-
| {{text anchor|SUBORDINATE_TO_TISSUE}}
|
*value
| Tissue is implicitly attached to another tissue and will fall off if that tissue layer is destroyed. Used for hair and feathers, which are subordinate to skin.

|-
| {{text anchor|TISSUE_MAT_STATE}}
|
*SOLID, SOLID_POWDER, LIQUID, or GAS 
(possibly others, as well. Needs testing.)
| Sets/forces a default material state for the selected tissue.

|-
| {{text anchor|TISSUE_LEAKS}}
| N/A
| The selected tissue leaks out of the creature when the layers above it are pierced.
|}

== Tissue layer tokens ==

These are used in creature raws to override the above for whatever reason.

{| {{prettytable}}
|- bgcolor="#ddd"
! width="20%" | Token
! width="20%" | Arguments
! width="60%" | Description

|-
| {{text anchor|SET_LAYER_TISSUE}}
|
* tissue
| Sets a tissue layer to be made of a different tissue.

|-
| {{text anchor|TL_RELATIVE_THICKNESS}}
|
* value
| Sets a new relative thickness for selected tissue layers.

|-
| {{text anchor|TL_CONNECTS}}
|
| Gives the CONNECTS attribute to selected layers.

|-
| {{text anchor|TL_MAJOR_ARTERIES}}
|
| Gives Major Artery attribute to selected layers.

|-
| {{text anchor|TL_HEALING_RATE}}
|
* value
| Sets a new HEALING_RATE of the selected tissue layers.

|-
| {{text anchor|TL_VASCULAR}}
|
| Sets a new VASCULAR value (which modulates bleeding) for selected tissue layers.

|-
| {{text anchor|TL_PAIN_RECEPTORS}}
|
| Sets a new number of pain receptors for selected tissue layers.
|}

== Default tissues ==

=== Values ===

{| {{prettytable}} style="margin: 1em 1em 1em 0; background: #f9f9f9; border: 1px #aaa solid; border-collapse: collapse; font-size: 70%;"
|- bgcolor="#999999"
! style="font-size: 150%;"| TISSUE_TEMPLATE !! TISSUE_NAME !! TISSUE_MATERIAL !! TISSUE_MAT_STATE !! RELATIVE_THICKNESS !! HEALING_RATE !! VASCULAR !! PAIN_RECEPTORS !! SUBORDINATE_TO_TISSUE !! INSULATION !! TISSUE_SHAPE
|-
| SKIN_TEMPLATE || skin:NP || LOCAL_CREATURE_MAT:SKIN || || 1 || 100 || 1 || 5 || || || LAYER
|-
| FAT_TEMPLATE || fat:NP || LOCAL_CREATURE_MAT:FAT || || 1 || 100 || 3 || 5 || || 100 || LAYER
|-
| MUSCLE_TEMPLATE || muscle:muscles || LOCAL_CREATURE_MAT:MUSCLE || || 3 || 100 || 5 || 5 || || || LAYER
|-
| BONE_TEMPLATE || bone:NP || LOCAL_CREATURE_MAT:BONE || || 2 || 1000 || 3 || 50 || || || LAYER
|-
| SHELL_TEMPLATE || shell:NP || LOCAL_CREATURE_MAT:SHELL || || 2 || 1000 || || || || || LAYER
|-
| HORN_TEMPLATE || horn:NP || LOCAL_CREATURE_MAT:HORN || || 2 || || || || || || LAYER
|-
| HOOF_TEMPLATE || hoof:NP || LOCAL_CREATURE_MAT:HOOF || || 2 || || || || || || LAYER
|-
| CARTILAGE_TEMPLATE || cartilage:NP || LOCAL_CREATURE_MAT:CARTILAGE || || 2 || || || || || || LAYER
|-
| HAIR_TEMPLATE || hair:NP || LOCAL_CREATURE_MAT:HAIR || || 1 || || || || SKIN || 100 || STRANDS
|-
| CHEEK_WHISKERS_TEMPLATE || cheek whisker:STP || LOCAL_CREATURE_MAT:HAIR || || 2 || || || || SKIN || || STRANDS
|-
| CHIN_WHISKERS_TEMPLATE || chin whisker:STP || LOCAL_CREATURE_MAT:HAIR || || 2 || || || || SKIN || || STRANDS
|-
| MOUSTACHE_TEMPLATE || moustache:NP || LOCAL_CREATURE_MAT:HAIR || || 2 || || || || SKIN || || STRANDS
|-
| SIDEBURNS_TEMPLATE || sideburns:NP || LOCAL_CREATURE_MAT:HAIR || || 2 || || || || SKIN || || STRANDS
|-
| EYEBROW_TEMPLATE || eyebrow:NP || LOCAL_CREATURE_MAT:HAIR || || 2 || || || || SKIN || || STRANDS
|-
| EYELASH_TEMPLATE || eyelash:eyelashes || LOCAL_CREATURE_MAT:HAIR || || 2 || || || || SKIN || || STRANDS
|-
| FEATHER_TEMPLATE || feather:STP || LOCAL_CREATURE_MAT:FEATHER || || 2 || || || || SKIN || 100 || FEATHERS
|-
| SCALE_TEMPLATE || scale:STP || LOCAL_CREATURE_MAT:SCALE || || 1 || 100 || 1 || 5 || || || SCALES
|-
| NAIL_TEMPLATE || nail:NP || LOCAL_CREATURE_MAT:NAIL || || 2 || || || || || || LAYER
|-
| CLAW_TEMPLATE || claw:NP || LOCAL_CREATURE_MAT:CLAW || || 2 || || || || || || LAYER
|-
| TALON_TEMPLATE || talon:NP || LOCAL_CREATURE_MAT:TALON || || 2 || || || || || || LAYER
|-
| TOOTH_TEMPLATE || tooth:NP || LOCAL_CREATURE_MAT:TOOTH || || 2 || || || || || || LAYER
|-
| IVORY_TEMPLATE || ivory:NP || LOCAL_CREATURE_MAT:IVORY || || 2 || || || || || || LAYER
|-
| EYE_TEMPLATE || eye tissue:NP || LOCAL_CREATURE_MAT:EYE || || 1 || 100 || 3 || 5 || || || LAYER
|-
| NERVE_TEMPLATE || nervous tissue:NP || LOCAL_CREATURE_MAT:NERVE || || 1 || || 3 || || || || LAYER
|-
| BRAIN_TEMPLATE || brain tissue:NP || LOCAL_CREATURE_MAT:BRAIN || || 1 || || 3 || || || || LAYER
|-
| LUNG_TEMPLATE || lung tissue:NP || LOCAL_CREATURE_MAT:LUNG || || 1 || 100 || 8 || 5 || || || LAYER
|-
| HEART_TEMPLATE || heart tissue:NP || LOCAL_CREATURE_MAT:HEART || || 1 || 100 || 10 || 5 || || || LAYER
|-
| LIVER_TEMPLATE || liver tissue:NP || LOCAL_CREATURE_MAT:LIVER || || 1 || 100 || 8 || 5 || || || LAYER
|-
| GUT_TEMPLATE || gut:NP || LOCAL_CREATURE_MAT:GUT || || 1 || 100 || 3 || 5 || || || LAYER
|-
| STOMACH_TEMPLATE || stomach tissue:NP || LOCAL_CREATURE_MAT:STOMACH || || 1 || 100 || 3 || 5 || || || LAYER
|-
| PANCREAS_TEMPLATE || pancreatic tissue:NP || LOCAL_CREATURE_MAT:PANCREAS || || 1 || 100 || 3 || 5 || || || LAYER
|-
| SPLEEN_TEMPLATE || spleen tissue:NP || LOCAL_CREATURE_MAT:SPLEEN || || 1 || 100 || 5 || 5 || || || LAYER
|-
| KIDNEY_TEMPLATE || kidney tissue:NP || LOCAL_CREATURE_MAT:KIDNEY || || 1 || 100 || 8 || 5 || || || LAYER
|-
| FLAME_TEMPLATE || flames:NP || LOCAL_CREATURE_MAT:FLAME || GAS || 1 || || || || || || LAYER
|-
| CHITIN_TEMPLATE || chitin:NP || LOCAL_CREATURE_MAT:CHITIN || || 1 || 100 || 1 || 5 || || || LAYER
|-
| SPINE_TEMPLATE || spine:NP || LOCAL_CREATURE_MAT:SPINE || || 2 || || || || || || LAYER
|-
| SPONGE_TEMPLATE || sponge:NP || LOCAL_CREATURE_MAT:SPONGE || || 1 || 100 || 3 || 5 || || 100 || LAYER
|- bgcolor="#999999"
! style="font-size: 150%;"| TISSUE_TEMPLATE !! TISSUE_NAME !! TISSUE_MATERIAL !! TISSUE_MAT_STATE !! RELATIVE_THICKNESS !! HEALING_RATE !! VASCULAR !! PAIN_RECEPTORS !! SUBORDINATE_TO_TISSUE !! INSULATION !! TISSUE_SHAPE
|}

=== Flags ===

{| {{prettytable}} style="margin: 1em 1em 1em 0; background: #f9f9f9; border: 1px #aaa solid; border-collapse: collapse; font-size: 70%;"
|- bgcolor="#999999" style="font-size: 70%;"
! style="font-size: 150%;"| TISSUE_TEMPLATE !! THICKENS_ON_ENERGY_STORAGE !! THICKENS_ON_STRENGTH !! ARTERIES !! SCARS !! MUSCULAR !! FUNCTIONAL !! STRUCTURAL !! CONNECTIVE_TISSUE_ANCHOR !! CONNECTS !! SETTABLE !! SPLINTABLE !! COSMETIC !! STYLEABLE
|-
| SKIN_TEMPLATE || || || || X || || || || || X || || || ||
|-
| FAT_TEMPLATE || X || || || X || || || || || X || || || ||
|-
| MUSCLE_TEMPLATE || || X || X || X || X || || || || X || || || ||
|-
| BONE_TEMPLATE || || || || || || || X || X || X || X || X || ||
|-
| SHELL_TEMPLATE || || || || || || || X || || X || X || X || ||
|-
| HORN_TEMPLATE || || || || || || || X || || X || || || ||
|-
| HOOF_TEMPLATE || || || || || || || X || || X || || || ||
|-
| CARTILAGE_TEMPLATE || || || || || || || X || || X || || || ||
|-
| HAIR_TEMPLATE || || || || || || || || || || || || X || X
|-
| CHEEK_WHISKERS_TEMPLATE || || || || || || || || || || || || X || X
|-
| CHIN_WHISKERS_TEMPLATE || || || || || || || || || || || || X || X
|-
| MOUSTACHE_TEMPLATE || || || || || || || || || || || || X || X
|-
| SIDEBURNS_TEMPLATE || || || || || || || || || || || || X || X
|-
| EYEBROW_TEMPLATE || || || || || || || || || || || || X || X
|-
| EYELASH_TEMPLATE || || || || || || || || || || || || X || X
|-
| FEATHER_TEMPLATE || || || || || || || || || || || || ||
|-
| SCALE_TEMPLATE || || || || X || || || || || X || || || ||
|-
| NAIL_TEMPLATE || || || || || || || X || || X || || || ||
|-
| CLAW_TEMPLATE || || || || || || || X || || X || || || ||
|-
| TALON_TEMPLATE || || || || || || || X || || X || || || ||
|-
| TOOTH_TEMPLATE || || || || || || || X || || X || || || ||
|-
| IVORY_TEMPLATE || || || || || || || X || || X || || || ||
|-
| EYE_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| NERVE_TEMPLATE || || || || X || || X || || || X || || || ||
|-
| BRAIN_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| LUNG_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| HEART_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| LIVER_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| GUT_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| STOMACH_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| PANCREAS_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| SPLEEN_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| KIDNEY_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| FLAME_TEMPLATE || || || || || X || X || X || || X || || || ||
|-
| CHITIN_TEMPLATE || || || || X || || || X || X || X || X || X || ||
|-
| SPINE_TEMPLATE || || || || || || || X || || X || || || ||
|-
| SPONGE_TEMPLATE || || || || X || || || || || X || || || ||
|- bgcolor="#999999" style="font-size: 70%;"
! style="font-size: 150%;"| TISSUE_TEMPLATE !! THICKENS_ON_ENERGY_STORAGE !! THICKENS_ON_STRENGTH !! ARTERIES !! SCARS !! MUSCULAR !! FUNCTIONAL !! STRUCTURAL !! CONNECTIVE_TISSUE_ANCHOR !! CONNECTS !! SETTABLE !! SPLINTABLE !! COSMETIC !! STYLEABLE
|}

==See Also==
*[[Material definition token]]

{{Category|Modding}}
{{Category|Tokens}}
[[ru:Tissue definition token]]

Tissue definition token

2021-05-01T21:11:38Z

Ralpha: Added info

{{Quality|Superior|12:23, 18 May 2015 (UTC)}}
{{av}}

__TOC__

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

|-
| {{text anchor|TISSUE_NAME}}
|
*name
*plural
|plural can alternatively be NP (No Plural) or STP (Standard Plural, adds an 's' on the end).

|-
| {{text anchor|TISSUE_MATERIAL}}
|
* [[material token]]
| Defines the tissue material.

|-
| {{text anchor|RELATIVE_THICKNESS}}
|
*value
| The relative thickness of the tissue. A higher thickness is harder to penetrate, but raising a tissue's relative thickness decreases the thickness of all other tissues.

|-
| {{text anchor|HEALING_RATE}}
|
*value
| Lower is faster. Omitting the token will result in a tissue that never heals.

|-
| {{text anchor|VASCULAR}}
|
*value
| Related to how much said tissue bleeds. Higher = More bleeding (Which is why the heart has the highest value.)

|-
| {{text anchor|PAIN_RECEPTORS}}
|
*value
| Related to how much pain your character will suffer when said tissue is damaged. Higher = More pain when damaged (Which is why the bone tissue has a much higher value than other tissues. A broken bone hurts a lot more than a flesh cut.)

|-
| {{text anchor|THICKENS_ON_STRENGTH}}
| N/A
| The thickness of the tissue increases when character strength increases.

|-
| {{text anchor|THICKENS_ON_ENERGY_STORAGE}}
| N/A
| Thickness of said tissue increases when the character eats and doesn't exercise sufficiently.

|-
| {{text anchor|ARTERIES}}
| N/A
| The tissue contains arteries. Edged attacks have the chance to break an artery, increasing blood loss.

|-
| {{text anchor|SCARS}}
| N/A
| Simply, whether or not the tissue will be scarred once healed.

|-
| {{text anchor|STRUCTURAL}}
| N/A
| Holds the body part together. A cut or a fracture disables the body part it's in.

|-
| {{text anchor|CONNECTIVE_TISSUE_ANCHOR}}
| N/A
| Any ligaments or tendons are part of this tissue. Vulnerable to edged attacks, damage disables the limb.

|-
| {{text anchor|SETTABLE}}
| N/A
| The tissue will not heal, or heals slower, until it is set by a bone doctor.

|-
| {{text anchor|SPLINTABLE}}
| N/A
| The broken tissue can be fixed with a cast or a splint to restore function while it heals.

|-
| {{text anchor|FUNCTIONAL}}
| N/A
| The tissue performs some sort of special function (e.g. sight, hearing, breathing, etc.) An organ with such a function will stop working if a sufficient amount of damage is sustained by its FUNCTIONAL tissues. If an organ has no FUNCTIONAL tissues, it will stop working only if it is severed or destroyed entirely by heat or cold.

|-
| {{text anchor|NERVOUS}}
| N/A
| Nervous function - not used. This token is used in [[Body_token#NERVOUS|[OBJECT:BODY]]] tokens.

|-
| {{text anchor|THOUGHT}}
| N/A
| If a creature has no functioning parts with the THOUGHT token, it will be unable to move or breathe. NO_THOUGHT_CENTER_FOR_MOVEMENT bypasses this limitation.

|-
| {{text anchor|MUSCULAR}}
| N/A
| Seems to affect where sensory or motor nerves are located, and whether damage to this tissue will render a limb useless.

|-
| {{text anchor|SMELL}}
| N/A
| Unknown - not used.

|-
| {{text anchor|HEAR}}
| N/A
| Unknown - not used.

|-
| {{text anchor|FLIGHT}}
| N/A
| Unknown - not used.

|-
| {{text anchor|BREATHE}}
| N/A
| Unknown - not used.

|-
| {{text anchor|SIGHT}}
| N/A
| Unknown - not used.

|-
| {{text anchor|CONNECTS}}
| N/A
| Holds body parts together. A body part will not be severed unless all of its component tissues with the CONNECTS tag are severed.

|-
| {{text anchor|MAJOR_ARTERIES}}
| N/A
| Causes tissue to sometimes severely bleed when damaged. This is independent of its VASCULAR value.

|-
| {{text anchor|INSULATION}}
|
*value
| Tissue supplies the creature with heat insulation. Higher values result in more insulation.

|-
| {{text anchor|COSMETIC}}
| N/A
| ?

|-
| {{text anchor|STYLEABLE}}
| N/A
| The tissue can be styled as per a tissue style (defined in an [[Entity_token|entity]] entry)

|-
| {{text anchor|TISSUE_SHAPE}}
|
*value
| Value can be one of the following:
;LAYER
:Regular layer tissue.
;STRANDS
:Can be spun into thread at a farmer's workshop. Edge attacks will pass right through the tissue.
;FEATHERS
:Edge attacks will pass right through the tissue.
;SCALES
:?
;CUSTOM
:?

|-
| {{text anchor|SUBORDINATE_TO_TISSUE}}
|
*value
| Tissue is implicitly attached to another tissue and will fall off if that tissue layer is destroyed. Used for hair and feathers, which are subordinate to skin.

|-
| {{text anchor|TISSUE_MAT_STATE}}
|
*SOLID, SOLID_POWDER, LIQUID, or GAS 
(possibly others, as well. Needs testing.)
| Sets/forces a default material state for the selected tissue.

|-
| {{text anchor|TISSUE_LEAKS}}
| N/A
| The selected tissue leaks out of the creature when the layers above it are pierced.
|}

== Tissue layer tokens ==

These are used in creature raws to override the above for whatever reason.

{| {{prettytable}}
|- bgcolor="#ddd"
! width="20%" | Token
! width="20%" | Arguments
! width="60%" | Description

|-
| {{text anchor|SET_LAYER_TISSUE}}
|
* tissue
| Sets a tissue layer to be made of a different tissue.

|-
| {{text anchor|TL_RELATIVE_THICKNESS}}
|
* value
| Sets a new relative thickness for selected tissue layers.

|-
| {{text anchor|TL_CONNECTS}}
|
| Gives the CONNECTS attribute to selected layers.

|-
| {{text anchor|TL_MAJOR_ARTERIES}}
|
| Gives Major Artery attribute to selected layers.

|-
| {{text anchor|TL_HEALING_RATE}}
|
* value
| Sets a new HEALING_RATE of the selected tissue layers.

|-
| {{text anchor|TL_VASCULAR}}
|
| Sets a new VASCULAR value (which modulates bleeding) for selected tissue layers.

|-
| {{text anchor|TL_PAIN_RECEPTORS}}
|
| Sets a new number of pain receptors for selected tissue layers.
|}

== Default tissues ==

=== Values ===

{| {{prettytable}} style="margin: 1em 1em 1em 0; background: #f9f9f9; border: 1px #aaa solid; border-collapse: collapse; font-size: 70%;"
|- bgcolor="#999999"
! style="font-size: 150%;"| TISSUE_TEMPLATE !! TISSUE_NAME !! TISSUE_MATERIAL !! TISSUE_MAT_STATE !! RELATIVE_THICKNESS !! HEALING_RATE !! VASCULAR !! PAIN_RECEPTORS !! SUBORDINATE_TO_TISSUE !! INSULATION !! TISSUE_SHAPE
|-
| SKIN_TEMPLATE || skin:NP || LOCAL_CREATURE_MAT:SKIN || || 1 || 100 || 1 || 5 || || || LAYER
|-
| FAT_TEMPLATE || fat:NP || LOCAL_CREATURE_MAT:FAT || || 1 || 100 || 3 || 5 || || 100 || LAYER
|-
| MUSCLE_TEMPLATE || muscle:muscles || LOCAL_CREATURE_MAT:MUSCLE || || 3 || 100 || 5 || 5 || || || LAYER
|-
| BONE_TEMPLATE || bone:NP || LOCAL_CREATURE_MAT:BONE || || 2 || 1000 || 3 || 50 || || || LAYER
|-
| SHELL_TEMPLATE || shell:NP || LOCAL_CREATURE_MAT:SHELL || || 2 || 1000 || || || || || LAYER
|-
| HORN_TEMPLATE || horn:NP || LOCAL_CREATURE_MAT:HORN || || 2 || || || || || || LAYER
|-
| HOOF_TEMPLATE || hoof:NP || LOCAL_CREATURE_MAT:HOOF || || 2 || || || || || || LAYER
|-
| CARTILAGE_TEMPLATE || cartilage:NP || LOCAL_CREATURE_MAT:CARTILAGE || || 2 || || || || || || LAYER
|-
| HAIR_TEMPLATE || hair:NP || LOCAL_CREATURE_MAT:HAIR || || 1 || || || || SKIN || 100 || STRANDS
|-
| CHEEK_WHISKERS_TEMPLATE || cheek whisker:STP || LOCAL_CREATURE_MAT:HAIR || || 2 || || || || SKIN || || STRANDS
|-
| CHIN_WHISKERS_TEMPLATE || chin whisker:STP || LOCAL_CREATURE_MAT:HAIR || || 2 || || || || SKIN || || STRANDS
|-
| MOUSTACHE_TEMPLATE || moustache:NP || LOCAL_CREATURE_MAT:HAIR || || 2 || || || || SKIN || || STRANDS
|-
| SIDEBURNS_TEMPLATE || sideburns:NP || LOCAL_CREATURE_MAT:HAIR || || 2 || || || || SKIN || || STRANDS
|-
| EYEBROW_TEMPLATE || eyebrow:NP || LOCAL_CREATURE_MAT:HAIR || || 2 || || || || SKIN || || STRANDS
|-
| EYELASH_TEMPLATE || eyelash:eyelashes || LOCAL_CREATURE_MAT:HAIR || || 2 || || || || SKIN || || STRANDS
|-
| FEATHER_TEMPLATE || feather:STP || LOCAL_CREATURE_MAT:FEATHER || || 2 || || || || SKIN || 100 || FEATHERS
|-
| SCALE_TEMPLATE || scale:STP || LOCAL_CREATURE_MAT:SCALE || || 1 || 100 || 1 || 5 || || || SCALES
|-
| NAIL_TEMPLATE || nail:NP || LOCAL_CREATURE_MAT:NAIL || || 2 || || || || || || LAYER
|-
| CLAW_TEMPLATE || claw:NP || LOCAL_CREATURE_MAT:CLAW || || 2 || || || || || || LAYER
|-
| TALON_TEMPLATE || talon:NP || LOCAL_CREATURE_MAT:TALON || || 2 || || || || || || LAYER
|-
| TOOTH_TEMPLATE || tooth:NP || LOCAL_CREATURE_MAT:TOOTH || || 2 || || || || || || LAYER
|-
| IVORY_TEMPLATE || ivory:NP || LOCAL_CREATURE_MAT:IVORY || || 2 || || || || || || LAYER
|-
| EYE_TEMPLATE || eye tissue:NP || LOCAL_CREATURE_MAT:EYE || || 1 || 100 || 3 || 5 || || || LAYER
|-
| NERVE_TEMPLATE || nervous tissue:NP || LOCAL_CREATURE_MAT:NERVE || || 1 || || 3 || || || || LAYER
|-
| BRAIN_TEMPLATE || brain tissue:NP || LOCAL_CREATURE_MAT:BRAIN || || 1 || || 3 || || || || LAYER
|-
| LUNG_TEMPLATE || lung tissue:NP || LOCAL_CREATURE_MAT:LUNG || || 1 || 100 || 8 || 5 || || || LAYER
|-
| HEART_TEMPLATE || heart tissue:NP || LOCAL_CREATURE_MAT:HEART || || 1 || 100 || 10 || 5 || || || LAYER
|-
| LIVER_TEMPLATE || liver tissue:NP || LOCAL_CREATURE_MAT:LIVER || || 1 || 100 || 8 || 5 || || || LAYER
|-
| GUT_TEMPLATE || gut:NP || LOCAL_CREATURE_MAT:GUT || || 1 || 100 || 3 || 5 || || || LAYER
|-
| STOMACH_TEMPLATE || stomach tissue:NP || LOCAL_CREATURE_MAT:STOMACH || || 1 || 100 || 3 || 5 || || || LAYER
|-
| PANCREAS_TEMPLATE || pancreatic tissue:NP || LOCAL_CREATURE_MAT:PANCREAS || || 1 || 100 || 3 || 5 || || || LAYER
|-
| SPLEEN_TEMPLATE || spleen tissue:NP || LOCAL_CREATURE_MAT:SPLEEN || || 1 || 100 || 5 || 5 || || || LAYER
|-
| KIDNEY_TEMPLATE || kidney tissue:NP || LOCAL_CREATURE_MAT:KIDNEY || || 1 || 100 || 8 || 5 || || || LAYER
|-
| FLAME_TEMPLATE || flames:NP || LOCAL_CREATURE_MAT:FLAME || GAS || 1 || || || || || || LAYER
|-
| CHITIN_TEMPLATE || chitin:NP || LOCAL_CREATURE_MAT:CHITIN || || 1 || 100 || 1 || 5 || || || LAYER
|-
| SPINE_TEMPLATE || spine:NP || LOCAL_CREATURE_MAT:SPINE || || 2 || || || || || || LAYER
|-
| SPONGE_TEMPLATE || sponge:NP || LOCAL_CREATURE_MAT:SPONGE || || 1 || 100 || 3 || 5 || || 100 || LAYER
|- bgcolor="#999999"
! style="font-size: 150%;"| TISSUE_TEMPLATE !! TISSUE_NAME !! TISSUE_MATERIAL !! TISSUE_MAT_STATE !! RELATIVE_THICKNESS !! HEALING_RATE !! VASCULAR !! PAIN_RECEPTORS !! SUBORDINATE_TO_TISSUE !! INSULATION !! TISSUE_SHAPE
|}

=== Flags ===

{| {{prettytable}} style="margin: 1em 1em 1em 0; background: #f9f9f9; border: 1px #aaa solid; border-collapse: collapse; font-size: 70%;"
|- bgcolor="#999999" style="font-size: 70%;"
! style="font-size: 150%;"| TISSUE_TEMPLATE !! THICKENS_ON_ENERGY_STORAGE !! THICKENS_ON_STRENGTH !! ARTERIES !! SCARS !! MUSCULAR !! FUNCTIONAL !! STRUCTURAL !! CONNECTIVE_TISSUE_ANCHOR !! CONNECTS !! SETTABLE !! SPLINTABLE !! COSMETIC !! STYLEABLE
|-
| SKIN_TEMPLATE || || || || X || || || || || X || || || ||
|-
| FAT_TEMPLATE || X || || || X || || || || || X || || || ||
|-
| MUSCLE_TEMPLATE || || X || X || X || X || || || || X || || || ||
|-
| BONE_TEMPLATE || || || || || || || X || X || X || X || X || ||
|-
| SHELL_TEMPLATE || || || || || || || X || || X || X || X || ||
|-
| HORN_TEMPLATE || || || || || || || X || || X || || || ||
|-
| HOOF_TEMPLATE || || || || || || || X || || X || || || ||
|-
| CARTILAGE_TEMPLATE || || || || || || || X || || X || || || ||
|-
| HAIR_TEMPLATE || || || || || || || || || || || || X || X
|-
| CHEEK_WHISKERS_TEMPLATE || || || || || || || || || || || || X || X
|-
| CHIN_WHISKERS_TEMPLATE || || || || || || || || || || || || X || X
|-
| MOUSTACHE_TEMPLATE || || || || || || || || || || || || X || X
|-
| SIDEBURNS_TEMPLATE || || || || || || || || || || || || X || X
|-
| EYEBROW_TEMPLATE || || || || || || || || || || || || X || X
|-
| EYELASH_TEMPLATE || || || || || || || || || || || || X || X
|-
| FEATHER_TEMPLATE || || || || || || || || || || || || ||
|-
| SCALE_TEMPLATE || || || || X || || || || || X || || || ||
|-
| NAIL_TEMPLATE || || || || || || || X || || X || || || ||
|-
| CLAW_TEMPLATE || || || || || || || X || || X || || || ||
|-
| TALON_TEMPLATE || || || || || || || X || || X || || || ||
|-
| TOOTH_TEMPLATE || || || || || || || X || || X || || || ||
|-
| IVORY_TEMPLATE || || || || || || || X || || X || || || ||
|-
| EYE_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| NERVE_TEMPLATE || || || || X || || X || || || X || || || ||
|-
| BRAIN_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| LUNG_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| HEART_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| LIVER_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| GUT_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| STOMACH_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| PANCREAS_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| SPLEEN_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| KIDNEY_TEMPLATE || || || || X || || X || X || || X || || || ||
|-
| FLAME_TEMPLATE || || || || || X || X || X || || X || || || ||
|-
| CHITIN_TEMPLATE || || || || X || || || X || X || X || X || X || ||
|-
| SPINE_TEMPLATE || || || || || || || X || || X || || || ||
|-
| SPONGE_TEMPLATE || || || || X || || || || || X || || || ||
|- bgcolor="#999999" style="font-size: 70%;"
! style="font-size: 150%;"| TISSUE_TEMPLATE !! THICKENS_ON_ENERGY_STORAGE !! THICKENS_ON_STRENGTH !! ARTERIES !! SCARS !! MUSCULAR !! FUNCTIONAL !! STRUCTURAL !! CONNECTIVE_TISSUE_ANCHOR !! CONNECTS !! SETTABLE !! SPLINTABLE !! COSMETIC !! STYLEABLE
|}

==See Also==
*[[Material definition token]]

{{Category|Modding}}
{{Category|Tokens}}
[[ru:Tissue definition token]]

Reaction

2021-04-25T23:12:04Z

Ralpha: Added Description

{{Quality|Superior|19:56, 28 August 2013 (UTC)}}
{{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 (sometimes) quite simple to add additional ones. There is a separate page with custom [[reaction examples]].

== Reaction differences between modes ==

In [[fortress mode]], reactions are linked to specific buildings, and must be added to a civilization's [[entity token|entity file]] to be usable by that civilization. This has the useful effect of limiting new items and materials (such as special [[wood]] or [[metal]]) to civilizations that have the requisite reaction — so that if you give your custom civilization a reaction to produce "star metal" or some other custom material, only they will be able to use it.

In [[adventure mode]], reactions are freely available in the {{k|x}} menu via the {{DFtext|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]
* ''[[#Reaction identifier|identifier]]'': The internal ID of the reaction.
* ''[[#Reaction name|name]]'': The name of the reaction, visible to the player in the Fortress mode or Adventure mode menus.
* ''[[#Building|building]]'': The building ID that the reaction uses, and the relevant keyboard shortcut.
* ''[[#Reagents|...reagents...]]'': Zero or more reagents (ingredients) that are required to be in stock for the reaction to be possible.
* ''[[#Products|...products...]]'': Zero or more products that are created from the reaction.
* ''[[#fuel|fuel]]'': (optional) If present, the reaction requires charcoal, coke or a magma-powered workshop.
* ''[[#skill|skill]]'': (optional) The skill required and trained by the reaction.
* ''[[#automatic|automatic]]'': (optional) If present, the reaction will automatically be enqueued whenever it can possibly be performed.
* ''[[#adventure mode|adventure mode]]'': (optional) If present, the reaction is used by the player in Adventure mode instead.

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

=== Reaction name ===

This can be anything at all, and is usually used to describe the reaction. '''Tan a hide''', for example, is the name of the default leather-producing reaction. Generally this should be written as a small descriptive verb phrase, with the first letter capitalized, for consistency with the existing reactions.

=== Building ===

[BUILDING:<BUILDING NAME>:<BUILDING KEY>]
* ''name'': The ID (that is the internal TOKEN each building can be referred to into reactions) 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 TOKENS are as follows:
* KILN - [[Kiln]] and [[Magma kiln]]
* SMELTER - [[Smelter]] and [[Magma smelter]]
* TANNER - [[Tanner's shop]]
* KITCHEN - [[Kitchen]]
* QUERN - [[Quern]]
* MILLSTONE - [[Millstone]]
* STILL - [[Still]]
* FARMER - [[Farmer's workshop]]
* CRAFTSMAN - [[Craftsdwarf's workshop]]
* GLASS{{version|0.42.01}} - [[Glass furnace]]
* WOOD{{version|0.42.01}} - [[Wood furnace]]
* MASON{{version|0.42.01}} - [[Mason's workshop]]
* ASHERY{{version|0.42.01}} - [[Ashery]]
* LEATHER{{version|0.42.01}} - [[Leather works]]
* BOWYER{{version|0.42.01}} - [[Bowyer's workshop]]
* SIEGE{{version|0.42.01}} - [[Siege workshop]]
* CLOTHES{{version|0.42.01}} - [[Clothier's shop]]
* METALSMITH{{version|0.42.01}} - [[Metalsmith's forge]]
* CARPENTER{{version|0.42.01}} - [[Carpenter's workshop]]
* Any custom (raw-defined) building type, such as:
** SOAP_MAKER - [[Soap maker's workshop]]
** SCREW_PRESS - [[Screw press]]

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

=== Category ===

{{new in v0.42}}

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.

{| {{prettytable}}
|- bgcolor="#dddddd"
! 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 || [[interface.txt|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.
|}

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

==== name ====

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

Most reagents are simply named '''A''', '''B''', and so forth in default reactions, although names such as '''TOOLSTONE''' 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 token]]s 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 [[item token|full list]] is available.

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

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

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

==== material token ====

[[Material token]]s come in several forms. For most reagents, this will typically be INORGANIC:MATERIAL_ID or NONE:NONE (to allow multiple materials using other 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:

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| [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|name]] of the reagent).
|-
| [UNROTTEN]
| Reagent must not be rotten, mainly for organic materials.
|-
| style="vertical-align: top"| [CONTAINS_LYE]
| Reagent must be a BARREL or TOOL which contains at least one item of type LIQUID_MISC made of LYE. Use of this token is discouraged, as it does not work with buckets (instead, use [CONTAINS:lye] — note the colon — and a corresponding lye reagent [REAGENT:lye:150:LIQUID_MISC:NONE:LYE]).
|-
| [POTASHABLE]
| Alias for [CONTAINS_LYE].
|-
| [NOT_WEB]
| Reagent must be collected (to distinguish silk thread from webs). Only makes sense for items of type THREAD.
|-
| [WEB_ONLY]
| Reagent must be undisturbed (to distinguish silk thread from webs). Only makes sense for items of type THREAD.
|-
| [EMPTY]
| If the reagent is a container, it must be empty.
|-
| [NOT_CONTAIN_BARREL_ITEM]
| If the reagent is a container, it must not contain [[lye]] or [[milk]]. Not necessary if specifying [EMPTY].
|-
| [BAG]
| Reagent must be a bag - that is, a BOX made of plant fiber, silk, yarn, or leather.
|-
| [GLASS_MATERIAL]
| Reagent material must have the [IS_GLASS] token. All 3 types of [[glass]] have this token hardcoded.
|-
| [BUILDMAT]
| Reagent must be a general [[building material]] - BAR, BLOCKS, BOULDER, or WOOD.
|-
| [FIRE_BUILD_SAFE]
| Reagent material must be 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 - excludes sharp stones (produced using knapping) and most types of weapon/ammo.
|-
| [HAS_EDGE]{{version|0.42.01}}
| Reagent must have an edge.
|-
| [NOT_ENGRAVED]
| Reagent has not been engraved (excludes memorial slabs).
|-
| [NOT_IMPROVED]
| Reagent has not been decorated.
|-
| [DOES_NOT_ABSORB]
| Reagent material must have [ABSORPTION:0]
|-
| [FOOD_STORAGE_CONTAINER]
| Reagent is either a BARREL or a TOOL with the FOOD_STORAGE use.
|-
| [HARD_ITEM_MATERIAL]
| 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 [[stack]]s 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.

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| [FORCE_EDGE]
| Product is given a sharp edge. Used for knapping.
|-
| [PRODUCT_PASTE]
| Product is created in the SOLID_PASTE state.
|-
| [PRODUCT_PRESSED]
| Product is created in the SOLID_PRESSED state.
|-
| [PRODUCT_DIMENSION:<size>]
| Specifies the 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:

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| COVERED
| Item is encrusted/studded/decorated with <material>.
|-
| GLAZED
| Item is glazed with <material>.
|-
| RINGS_HANGING
| Item is adorned with hanging rings of <material>.
|-
| BANDS
| Item is encircled with bands of <material>.
|-
| SPIKES
| Item menaces with spikes of <material>.
|-
| 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 token|SKILL token]] determines what skill the reaction requires and what skill it trains. Only one skill may be specified. For custom reactions, the amount of experience gained is linearly correlated with the amount of product created; a reaction with no product will yield no experience for the performing dwarf. Similarly, the amount of time a reaction takes is correlated with experience gained; if a reaction has zero experience gain due to having no skill associated, the reaction will take minimal time.

==== 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.{{version|0.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:

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

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

|-
| {{text anchor|ANY_BONE_MATERIAL}}
|
| Reagent material must have the [BONE] token.

|-
| {{text anchor|ANY_HORN_MATERIAL}}
|
| Reagent material must have the [HORN] token.

|-
| {{text anchor|ANY_LEATHER_MATERIAL}}
|
| Reagent material must have the [LEATHER] token.

|-
| {{text anchor|ANY_PEARL_MATERIAL}}
|
| Reagent material must have the [PEARL] token.

|-
| {{text anchor|ANY_PLANT_MATERIAL}}
|
| Reagent material must be subordinate to a PLANT object.

|-
| {{text anchor|ANY_SHELL_MATERIAL}}
|
| Reagent material must have the [SHELL] token.

|-
| {{text anchor|ANY_SILK_MATERIAL}}
|
| Reagent material must have the [SILK] token.

|-
| {{text anchor|ANY_SOAP_MATERIAL}}
|
| Reagent material must have the [SOAP] token.

|-
| {{text anchor|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].

|-
| {{text anchor|ANY_TOOTH_MATERIAL}}
|
| Reagent material must have the [TOOTH] token.

|-
| {{text anchor|ANY_YARN_MATERIAL}}
|
| Reagent material must have the [YARN] token.

|-
| {{text anchor|AUTOMATIC}}
|
| the reaction will be queued automatically if the reaction reagents are all present.

|-
| {{text anchor|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.

|-
| {{text anchor|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

|-
| {{text anchor|BUILDMAT}}
|
| Reagent is able to be used to build structures (Stone, Wood, Blocks, Bars?).

|-
| {{text anchor|CAN_USE_ARTIFACT}}
|
| Reagent can be an Artifact. Using [PRESERVE_REAGENT] with this is strongly advised.

|-
| {{text anchor|CAN_USE_HOSPITAL_RESERVED}}{{version|0.42.01}}
|
| Allows the reagent to be an item that is otherwise reserved for use by a [[healthcare|hospital]].

|-
| {{text anchor|CAN_USE_LOCATION_RESERVED}}{{version|0.42.01}}
|
| Allows the reagent to be an item that is otherwise reserved for use by a [[locations|location]].

|-
| {{text anchor|CATEGORY}}{{version|0.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.

|-
| {{text anchor|CATEGORY_NAME}}{{version|0.42.01}}
| String
| The name of the category as displayed in-game.

|-
| {{text anchor|CATEGORY_DESCRIPTION}}{{version|0.42.01}}
| String
| 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}}
| Category ID
| 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}}
| [[interface.txt|Hotkey token]]
| 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}}
| required content
| Reagent is a container that holds the specified reagent.

|-
| {{text anchor|CONTAINS_LYE}} (Deprecated)
|
| 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}}
| String
| Description of the reaction

|-
| {{text anchor|DOES_NOT_ABSORB}}
|
| Reagent material must have [ABSORPTION:0]

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

|-
| {{text anchor|EMPTY}}
|
| If the reagent is a container, it must be empty.

|-
| {{text anchor|FIRE_BUILD_SAFE}}
|
| Reagent must be considered fire safe - i.e. not wood, and not coal.

|-
| {{text anchor|FORCE_EDGE}}
|
| Product is given a sharp edge. Used for knapping.

|-
| {{text anchor|FOOD_STORAGE_CONTAINER}}
|
| Reagent must be a barrel or any non-absorbing tool with [TOOL_USE:FOOD_STORAGE]

|-
| {{text anchor|FUEL}}
|
| Requires that the reaction either use up a unit of coal or charcoal or else be performed at a magma workshop

|-
| {{text anchor|GLASS_MATERIAL}}
|
| Reagent material has [IS_GLASS].

|-
| {{text anchor|HAS_ITEM_REACTION_PRODUCT}}
| PRODUCT_ID (custom)
| 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}}
| PRODUCT_ID (custom)
| 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}}
| Tool-use token
| 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.

|-
| {{text anchor|HAS_WRITING_IMPROVEMENT}}{{version|0.42.01}}
|
| Reagent must contain writing.

|-
| {{text anchor|IMPROVEMENT}}
|
* Probability
* Reagent Name
* Improvement type
* Material Token
| Improvement types include BANDS, COVERED, GLAZED, RINGS_HANGING, and SPIKES

|-
| {{text anchor|MAGMA_BUILD_SAFE}}
|
| Currently broken - behaves exactly the same as FIRE_BUILD_SAFE.

|-
| {{text anchor|MAX_MULTIPLIER}}{{version|0.42.01}}
| number
| 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}}
|
* Inorganic material
| Reagent material must be an ore of the specified metal

|-
| {{text anchor|MIN_DIMENSION}}
|
* size
| Requires that the reagent have a dimension of at least this value. Only effective with BAR, POWDER_MISC, LIQUID_MISC, DRINK, THREAD, CLOTH, and GLOB items.

|-
| {{text anchor|NAME}}
| name
| defines the name used by the reaction in-game

|-
| {{text anchor|NO_EDGE_ALLOWED}}
|
| Reagent must not be sharpened (used for knapping).

|-
| {{text anchor|HAS_EDGE}}{{version|0.42.01}}
|
| Reagent must be sharpened (used for carving).

|-
| {{text anchor|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.

|-
| {{text anchor|NOT_ENGRAVED}}
|
| Reagent must not be an engraved memorial slab.
|-
| {{text anchor|NOT_IMPROVED}}
|
| Reagent has not been decorated.

|-
| {{text anchor|NOT_PRESSED}}
|
| Reagent must not be in the SOLID_PRESSED state.

|-
| {{text anchor|NOT_WEB}}
|
| Reagent must be "collected" - used with THREAD:NONE to exclude webs.

|-
| {{text anchor|POTASHABLE}} (Deprecated)
|
| Alias for CONTAINS_LYE.

|-
| {{text anchor|PRESERVE_REAGENT}}
|
| Reagent is not destroyed, which is the normal effect, at the completion of the reaction. Typically used for containers.

|-
| {{text anchor|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.

|-
| {{text anchor|PRODUCT_DIMENSION}}
| size
| 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.

|-
| {{text anchor|PRODUCT_PASTE}}
|
| Product is created in the SOLID_PASTE state.

|-
| {{text anchor|PRODUCT_PRESSED}}
|
| Product is created in the SOLID_PRESSED state.

|-
| {{text anchor|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.

|-
| {{text anchor|PRODUCT_TOKEN}}{{version|0.42.01}}
| name
| 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}}
| Identifier
| defines a new reaction

|-
| {{text anchor|REACTION_CLASS}}
| CLASS_ID (custom)
| 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).

|-
| {{text anchor|REAGENT}}
|
* name/id
* quantity
* [[item token]]
* [[material token]]
| Requires a given reagent as an input for a reaction

|-
| {{text anchor|SKILL}}
| Skill Token
| Skill used by the reaction

|-
| {{text anchor|TRANSFER_ARTIFACT_STATUS}}{{version|0.42.01}}
|
| Transfers artifact status from the reagent to the product.

|-
| {{text anchor|UNROTTEN}}
|
| Reagent must not be rotten, mainly for organic materials.

|-
| {{text anchor|USE_BODY_COMPONENT}}
|
| Reagent material must come off a creature's body.

|-
| {{text anchor|WEB_ONLY}}
|
| Reagent must be "undisturbed" - used with THREAD:NONE to gather webs.

|-
| {{text anchor|WORTHLESS_STONE_ONLY}}
|
| Reagent is not made of an economic stone.

|}

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

Reaction

2021-04-25T22:11:16Z

Ralpha: Marked tag as Deprecated

{{Quality|Superior|19:56, 28 August 2013 (UTC)}}
{{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 (sometimes) quite simple to add additional ones. There is a separate page with custom [[reaction examples]].

== Reaction differences between modes ==

In [[fortress mode]], reactions are linked to specific buildings, and must be added to a civilization's [[entity token|entity file]] to be usable by that civilization. This has the useful effect of limiting new items and materials (such as special [[wood]] or [[metal]]) to civilizations that have the requisite reaction — so that if you give your custom civilization a reaction to produce "star metal" or some other custom material, only they will be able to use it.

In [[adventure mode]], reactions are freely available in the {{k|x}} menu via the {{DFtext|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]
* ''[[#Reaction identifier|identifier]]'': The internal ID of the reaction.
* ''[[#Reaction name|name]]'': The name of the reaction, visible to the player in the Fortress mode or Adventure mode menus.
* ''[[#Building|building]]'': The building ID that the reaction uses, and the relevant keyboard shortcut.
* ''[[#Reagents|...reagents...]]'': Zero or more reagents (ingredients) that are required to be in stock for the reaction to be possible.
* ''[[#Products|...products...]]'': Zero or more products that are created from the reaction.
* ''[[#fuel|fuel]]'': (optional) If present, the reaction requires charcoal, coke or a magma-powered workshop.
* ''[[#skill|skill]]'': (optional) The skill required and trained by the reaction.
* ''[[#automatic|automatic]]'': (optional) If present, the reaction will automatically be enqueued whenever it can possibly be performed.
* ''[[#adventure mode|adventure mode]]'': (optional) If present, the reaction is used by the player in Adventure mode instead.

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

=== Reaction name ===

This can be anything at all, and is usually used to describe the reaction. '''Tan a hide''', for example, is the name of the default leather-producing reaction. Generally this should be written as a small descriptive verb phrase, with the first letter capitalized, for consistency with the existing reactions.

=== Building ===

[BUILDING:<BUILDING NAME>:<BUILDING KEY>]
* ''name'': The ID (that is the internal TOKEN each building can be referred to into reactions) 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 TOKENS are as follows:
* KILN - [[Kiln]] and [[Magma kiln]]
* SMELTER - [[Smelter]] and [[Magma smelter]]
* TANNER - [[Tanner's shop]]
* KITCHEN - [[Kitchen]]
* QUERN - [[Quern]]
* MILLSTONE - [[Millstone]]
* STILL - [[Still]]
* FARMER - [[Farmer's workshop]]
* CRAFTSMAN - [[Craftsdwarf's workshop]]
* GLASS{{version|0.42.01}} - [[Glass furnace]]
* WOOD{{version|0.42.01}} - [[Wood furnace]]
* MASON{{version|0.42.01}} - [[Mason's workshop]]
* ASHERY{{version|0.42.01}} - [[Ashery]]
* LEATHER{{version|0.42.01}} - [[Leather works]]
* BOWYER{{version|0.42.01}} - [[Bowyer's workshop]]
* SIEGE{{version|0.42.01}} - [[Siege workshop]]
* CLOTHES{{version|0.42.01}} - [[Clothier's shop]]
* METALSMITH{{version|0.42.01}} - [[Metalsmith's forge]]
* CARPENTER{{version|0.42.01}} - [[Carpenter's workshop]]
* Any custom (raw-defined) building type, such as:
** SOAP_MAKER - [[Soap maker's workshop]]
** SCREW_PRESS - [[Screw press]]

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

=== Category ===

{{new in v0.42}}

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.

{| {{prettytable}}
|- bgcolor="#dddddd"
! 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 || [[interface.txt|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.
|}

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

==== name ====

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

Most reagents are simply named '''A''', '''B''', and so forth in default reactions, although names such as '''TOOLSTONE''' 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 token]]s 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 [[item token|full list]] is available.

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

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

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

==== material token ====

[[Material token]]s come in several forms. For most reagents, this will typically be INORGANIC:MATERIAL_ID or NONE:NONE (to allow multiple materials using other 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:

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| [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|name]] of the reagent).
|-
| [UNROTTEN]
| Reagent must not be rotten, mainly for organic materials.
|-
| style="vertical-align: top"| [CONTAINS_LYE]
| Reagent must be a BARREL or TOOL which contains at least one item of type LIQUID_MISC made of LYE. Use of this token is discouraged, as it does not work with buckets (instead, use [CONTAINS:lye] — note the colon — and a corresponding lye reagent [REAGENT:lye:150:LIQUID_MISC:NONE:LYE]).
|-
| [POTASHABLE]
| Alias for [CONTAINS_LYE].
|-
| [NOT_WEB]
| Reagent must be collected (to distinguish silk thread from webs). Only makes sense for items of type THREAD.
|-
| [WEB_ONLY]
| Reagent must be undisturbed (to distinguish silk thread from webs). Only makes sense for items of type THREAD.
|-
| [EMPTY]
| If the reagent is a container, it must be empty.
|-
| [NOT_CONTAIN_BARREL_ITEM]
| If the reagent is a container, it must not contain [[lye]] or [[milk]]. Not necessary if specifying [EMPTY].
|-
| [BAG]
| Reagent must be a bag - that is, a BOX made of plant fiber, silk, yarn, or leather.
|-
| [GLASS_MATERIAL]
| Reagent material must have the [IS_GLASS] token. All 3 types of [[glass]] have this token hardcoded.
|-
| [BUILDMAT]
| Reagent must be a general [[building material]] - BAR, BLOCKS, BOULDER, or WOOD.
|-
| [FIRE_BUILD_SAFE]
| Reagent material must be 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 - excludes sharp stones (produced using knapping) and most types of weapon/ammo.
|-
| [HAS_EDGE]{{version|0.42.01}}
| Reagent must have an edge.
|-
| [NOT_ENGRAVED]
| Reagent has not been engraved (excludes memorial slabs).
|-
| [NOT_IMPROVED]
| Reagent has not been decorated.
|-
| [DOES_NOT_ABSORB]
| Reagent material must have [ABSORPTION:0]
|-
| [FOOD_STORAGE_CONTAINER]
| Reagent is either a BARREL or a TOOL with the FOOD_STORAGE use.
|-
| [HARD_ITEM_MATERIAL]
| 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 [[stack]]s 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.

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| [FORCE_EDGE]
| Product is given a sharp edge. Used for knapping.
|-
| [PRODUCT_PASTE]
| Product is created in the SOLID_PASTE state.
|-
| [PRODUCT_PRESSED]
| Product is created in the SOLID_PRESSED state.
|-
| [PRODUCT_DIMENSION:<size>]
| Specifies the 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:

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| COVERED
| Item is encrusted/studded/decorated with <material>.
|-
| GLAZED
| Item is glazed with <material>.
|-
| RINGS_HANGING
| Item is adorned with hanging rings of <material>.
|-
| BANDS
| Item is encircled with bands of <material>.
|-
| SPIKES
| Item menaces with spikes of <material>.
|-
| 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 token|SKILL token]] determines what skill the reaction requires and what skill it trains. Only one skill may be specified. For custom reactions, the amount of experience gained is linearly correlated with the amount of product created; a reaction with no product will yield no experience for the performing dwarf. Similarly, the amount of time a reaction takes is correlated with experience gained; if a reaction has zero experience gain due to having no skill associated, the reaction will take minimal time.

==== 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.{{version|0.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:

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

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

|-
| {{text anchor|ANY_BONE_MATERIAL}}
|
| Reagent material must have the [BONE] token.

|-
| {{text anchor|ANY_HORN_MATERIAL}}
|
| Reagent material must have the [HORN] token.

|-
| {{text anchor|ANY_LEATHER_MATERIAL}}
|
| Reagent material must have the [LEATHER] token.

|-
| {{text anchor|ANY_PEARL_MATERIAL}}
|
| Reagent material must have the [PEARL] token.

|-
| {{text anchor|ANY_PLANT_MATERIAL}}
|
| Reagent material must be subordinate to a PLANT object.

|-
| {{text anchor|ANY_SHELL_MATERIAL}}
|
| Reagent material must have the [SHELL] token.

|-
| {{text anchor|ANY_SILK_MATERIAL}}
|
| Reagent material must have the [SILK] token.

|-
| {{text anchor|ANY_SOAP_MATERIAL}}
|
| Reagent material must have the [SOAP] token.

|-
| {{text anchor|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].

|-
| {{text anchor|ANY_TOOTH_MATERIAL}}
|
| Reagent material must have the [TOOTH] token.

|-
| {{text anchor|ANY_YARN_MATERIAL}}
|
| Reagent material must have the [YARN] token.

|-
| {{text anchor|AUTOMATIC}}
|
| the reaction will be queued automatically if the reaction reagents are all present.

|-
| {{text anchor|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.

|-
| {{text anchor|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

|-
| {{text anchor|BUILDMAT}}
|
| Reagent is able to be used to build structures (Stone, Wood, Blocks, Bars?).

|-
| {{text anchor|CAN_USE_ARTIFACT}}
|
| Reagent can be an Artifact. Using [PRESERVE_REAGENT] with this is strongly advised.

|-
| {{text anchor|CAN_USE_HOSPITAL_RESERVED}}{{version|0.42.01}}
|
| Allows the reagent to be an item that is otherwise reserved for use by a [[healthcare|hospital]].

|-
| {{text anchor|CAN_USE_LOCATION_RESERVED}}{{version|0.42.01}}
|
| Allows the reagent to be an item that is otherwise reserved for use by a [[locations|location]].

|-
| {{text anchor|CATEGORY}}{{version|0.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.

|-
| {{text anchor|CATEGORY_NAME}}{{version|0.42.01}}
| String
| The name of the category as displayed in-game.

|-
| {{text anchor|CATEGORY_DESCRIPTION}}{{version|0.42.01}}
| String
| 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}}
| Category ID
| 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}}
| [[interface.txt|Hotkey token]]
| 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}}
| required content
| Reagent is a container that holds the specified reagent.

|-
| {{text anchor|CONTAINS_LYE}} (Deprecated)
|
| 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|DOES_NOT_ABSORB}}
|
| Reagent material must have [ABSORPTION:0]

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

|-
| {{text anchor|EMPTY}}
|
| If the reagent is a container, it must be empty.

|-
| {{text anchor|FIRE_BUILD_SAFE}}
|
| Reagent must be considered fire safe - i.e. not wood, and not coal.

|-
| {{text anchor|FORCE_EDGE}}
|
| Product is given a sharp edge. Used for knapping.

|-
| {{text anchor|FOOD_STORAGE_CONTAINER}}
|
| Reagent must be a barrel or any non-absorbing tool with [TOOL_USE:FOOD_STORAGE]

|-
| {{text anchor|FUEL}}
|
| Requires that the reaction either use up a unit of coal or charcoal or else be performed at a magma workshop

|-
| {{text anchor|GLASS_MATERIAL}}
|
| Reagent material has [IS_GLASS].

|-
| {{text anchor|HAS_ITEM_REACTION_PRODUCT}}
| PRODUCT_ID (custom)
| 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}}
| PRODUCT_ID (custom)
| 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}}
| Tool-use token
| 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.

|-
| {{text anchor|HAS_WRITING_IMPROVEMENT}}{{version|0.42.01}}
|
| Reagent must contain writing.

|-
| {{text anchor|IMPROVEMENT}}
|
* Probability
* Reagent Name
* Improvement type
* Material Token
| Improvement types include BANDS, COVERED, GLAZED, RINGS_HANGING, and SPIKES

|-
| {{text anchor|MAGMA_BUILD_SAFE}}
|
| Currently broken - behaves exactly the same as FIRE_BUILD_SAFE.

|-
| {{text anchor|MAX_MULTIPLIER}}{{version|0.42.01}}
| number
| 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}}
|
* Inorganic material
| Reagent material must be an ore of the specified metal

|-
| {{text anchor|MIN_DIMENSION}}
|
* size
| Requires that the reagent have a dimension of at least this value. Only effective with BAR, POWDER_MISC, LIQUID_MISC, DRINK, THREAD, CLOTH, and GLOB items.

|-
| {{text anchor|NAME}}
| name
| defines the name used by the reaction in-game

|-
| {{text anchor|NO_EDGE_ALLOWED}}
|
| Reagent must not be sharpened (used for knapping).

|-
| {{text anchor|HAS_EDGE}}{{version|0.42.01}}
|
| Reagent must be sharpened (used for carving).

|-
| {{text anchor|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.

|-
| {{text anchor|NOT_ENGRAVED}}
|
| Reagent must not be an engraved memorial slab.
|-
| {{text anchor|NOT_IMPROVED}}
|
| Reagent has not been decorated.

|-
| {{text anchor|NOT_PRESSED}}
|
| Reagent must not be in the SOLID_PRESSED state.

|-
| {{text anchor|NOT_WEB}}
|
| Reagent must be "collected" - used with THREAD:NONE to exclude webs.

|-
| {{text anchor|POTASHABLE}} (Deprecated)
|
| Alias for CONTAINS_LYE.

|-
| {{text anchor|PRESERVE_REAGENT}}
|
| Reagent is not destroyed, which is the normal effect, at the completion of the reaction. Typically used for containers.

|-
| {{text anchor|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.

|-
| {{text anchor|PRODUCT_DIMENSION}}
| size
| 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.

|-
| {{text anchor|PRODUCT_PASTE}}
|
| Product is created in the SOLID_PASTE state.

|-
| {{text anchor|PRODUCT_PRESSED}}
|
| Product is created in the SOLID_PRESSED state.

|-
| {{text anchor|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.

|-
| {{text anchor|PRODUCT_TOKEN}}{{version|0.42.01}}
| name
| 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}}
| Identifier
| defines a new reaction

|-
| {{text anchor|REACTION_CLASS}}
| CLASS_ID (custom)
| 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).

|-
| {{text anchor|REAGENT}}
|
* name/id
* quantity
* [[item token]]
* [[material token]]
| Requires a given reagent as an input for a reaction

|-
| {{text anchor|SKILL}}
| Skill Token
| Skill used by the reaction

|-
| {{text anchor|TRANSFER_ARTIFACT_STATUS}}{{version|0.42.01}}
|
| Transfers artifact status from the reagent to the product.

|-
| {{text anchor|UNROTTEN}}
|
| Reagent must not be rotten, mainly for organic materials.

|-
| {{text anchor|USE_BODY_COMPONENT}}
|
| Reagent material must come off a creature's body.

|-
| {{text anchor|WEB_ONLY}}
|
| Reagent must be "undisturbed" - used with THREAD:NONE to gather webs.

|-
| {{text anchor|WORTHLESS_STONE_ONLY}}
|
| Reagent is not made of an economic stone.

|}

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

Reaction

2021-04-25T20:20:05Z

Ralpha: Small corrections

{{Quality|Superior|19:56, 28 August 2013 (UTC)}}
{{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 (sometimes) quite simple to add additional ones. There is a separate page with custom [[reaction examples]].

== Reaction differences between modes ==

In [[fortress mode]], reactions are linked to specific buildings, and must be added to a civilization's [[entity token|entity file]] to be usable by that civilization. This has the useful effect of limiting new items and materials (such as special [[wood]] or [[metal]]) to civilizations that have the requisite reaction — so that if you give your custom civilization a reaction to produce "star metal" or some other custom material, only they will be able to use it.

In [[adventure mode]], reactions are freely available in the {{k|x}} menu via the {{DFtext|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]
* ''[[#Reaction identifier|identifier]]'': The internal ID of the reaction.
* ''[[#Reaction name|name]]'': The name of the reaction, visible to the player in the Fortress mode or Adventure mode menus.
* ''[[#Building|building]]'': The building ID that the reaction uses, and the relevant keyboard shortcut.
* ''[[#Reagents|...reagents...]]'': Zero or more reagents (ingredients) that are required to be in stock for the reaction to be possible.
* ''[[#Products|...products...]]'': Zero or more products that are created from the reaction.
* ''[[#fuel|fuel]]'': (optional) If present, the reaction requires charcoal, coke or a magma-powered workshop.
* ''[[#skill|skill]]'': (optional) The skill required and trained by the reaction.
* ''[[#automatic|automatic]]'': (optional) If present, the reaction will automatically be enqueued whenever it can possibly be performed.
* ''[[#adventure mode|adventure mode]]'': (optional) If present, the reaction is used by the player in Adventure mode instead.

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

=== Reaction name ===

This can be anything at all, and is usually used to describe the reaction. '''Tan a hide''', for example, is the name of the default leather-producing reaction. Generally this should be written as a small descriptive verb phrase, with the first letter capitalized, for consistency with the existing reactions.

=== Building ===

[BUILDING:<BUILDING NAME>:<BUILDING KEY>]
* ''name'': The ID (that is the internal TOKEN each building can be referred to into reactions) 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 TOKENS are as follows:
* KILN - [[Kiln]] and [[Magma kiln]]
* SMELTER - [[Smelter]] and [[Magma smelter]]
* TANNER - [[Tanner's shop]]
* KITCHEN - [[Kitchen]]
* QUERN - [[Quern]]
* MILLSTONE - [[Millstone]]
* STILL - [[Still]]
* FARMER - [[Farmer's workshop]]
* CRAFTSMAN - [[Craftsdwarf's workshop]]
* GLASS{{version|0.42.01}} - [[Glass furnace]]
* WOOD{{version|0.42.01}} - [[Wood furnace]]
* MASON{{version|0.42.01}} - [[Mason's workshop]]
* ASHERY{{version|0.42.01}} - [[Ashery]]
* LEATHER{{version|0.42.01}} - [[Leather works]]
* BOWYER{{version|0.42.01}} - [[Bowyer's workshop]]
* SIEGE{{version|0.42.01}} - [[Siege workshop]]
* CLOTHES{{version|0.42.01}} - [[Clothier's shop]]
* METALSMITH{{version|0.42.01}} - [[Metalsmith's forge]]
* CARPENTER{{version|0.42.01}} - [[Carpenter's workshop]]
* Any custom (raw-defined) building type, such as:
** SOAP_MAKER - [[Soap maker's workshop]]
** SCREW_PRESS - [[Screw press]]

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

=== Category ===

{{new in v0.42}}

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.

{| {{prettytable}}
|- bgcolor="#dddddd"
! 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 || [[interface.txt|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.
|}

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

==== name ====

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

Most reagents are simply named '''A''', '''B''', and so forth in default reactions, although names such as '''TOOLSTONE''' 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 token]]s 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 [[item token|full list]] is available.

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

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

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

==== material token ====

[[Material token]]s come in several forms. For most reagents, this will typically be INORGANIC:MATERIAL_ID or NONE:NONE (to allow multiple materials using other 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:

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| [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|name]] of the reagent).
|-
| [UNROTTEN]
| Reagent must not be rotten, mainly for organic materials.
|-
| style="vertical-align: top"| [CONTAINS_LYE]
| Reagent must be a BARREL or TOOL which contains at least one item of type LIQUID_MISC made of LYE. Use of this token is discouraged, as it does not work with buckets (instead, use [CONTAINS:lye] — note the colon — and a corresponding lye reagent [REAGENT:lye:150:LIQUID_MISC:NONE:LYE]).
|-
| [POTASHABLE]
| Alias for [CONTAINS_LYE].
|-
| [NOT_WEB]
| Reagent must be collected (to distinguish silk thread from webs). Only makes sense for items of type THREAD.
|-
| [WEB_ONLY]
| Reagent must be undisturbed (to distinguish silk thread from webs). Only makes sense for items of type THREAD.
|-
| [EMPTY]
| If the reagent is a container, it must be empty.
|-
| [NOT_CONTAIN_BARREL_ITEM]
| If the reagent is a container, it must not contain [[lye]] or [[milk]]. Not necessary if specifying [EMPTY].
|-
| [BAG]
| Reagent must be a bag - that is, a BOX made of plant fiber, silk, yarn, or leather.
|-
| [GLASS_MATERIAL]
| Reagent material must have the [IS_GLASS] token. All 3 types of [[glass]] have this token hardcoded.
|-
| [BUILDMAT]
| Reagent must be a general [[building material]] - BAR, BLOCKS, BOULDER, or WOOD.
|-
| [FIRE_BUILD_SAFE]
| Reagent material must be 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 - excludes sharp stones (produced using knapping) and most types of weapon/ammo.
|-
| [HAS_EDGE]{{version|0.42.01}}
| Reagent must have an edge.
|-
| [NOT_ENGRAVED]
| Reagent has not been engraved (excludes memorial slabs).
|-
| [NOT_IMPROVED]
| Reagent has not been decorated.
|-
| [DOES_NOT_ABSORB]
| Reagent material must have [ABSORPTION:0]
|-
| [FOOD_STORAGE_CONTAINER]
| Reagent is either a BARREL or a TOOL with the FOOD_STORAGE use.
|-
| [HARD_ITEM_MATERIAL]
| 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 [[stack]]s 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.

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| [FORCE_EDGE]
| Product is given a sharp edge. Used for knapping.
|-
| [PRODUCT_PASTE]
| Product is created in the SOLID_PASTE state.
|-
| [PRODUCT_PRESSED]
| Product is created in the SOLID_PRESSED state.
|-
| [PRODUCT_DIMENSION:<size>]
| Specifies the 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:

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| COVERED
| Item is encrusted/studded/decorated with <material>.
|-
| GLAZED
| Item is glazed with <material>.
|-
| RINGS_HANGING
| Item is adorned with hanging rings of <material>.
|-
| BANDS
| Item is encircled with bands of <material>.
|-
| SPIKES
| Item menaces with spikes of <material>.
|-
| 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 token|SKILL token]] determines what skill the reaction requires and what skill it trains. Only one skill may be specified. For custom reactions, the amount of experience gained is linearly correlated with the amount of product created; a reaction with no product will yield no experience for the performing dwarf. Similarly, the amount of time a reaction takes is correlated with experience gained; if a reaction has zero experience gain due to having no skill associated, the reaction will take minimal time.

==== 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.{{version|0.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:

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

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

|-
| {{text anchor|ANY_BONE_MATERIAL}}
|
| Reagent material must have the [BONE] token.

|-
| {{text anchor|ANY_HORN_MATERIAL}}
|
| Reagent material must have the [HORN] token.

|-
| {{text anchor|ANY_LEATHER_MATERIAL}}
|
| Reagent material must have the [LEATHER] token.

|-
| {{text anchor|ANY_PEARL_MATERIAL}}
|
| Reagent material must have the [PEARL] token.

|-
| {{text anchor|ANY_PLANT_MATERIAL}}
|
| Reagent material must be subordinate to a PLANT object.

|-
| {{text anchor|ANY_SHELL_MATERIAL}}
|
| Reagent material must have the [SHELL] token.

|-
| {{text anchor|ANY_SILK_MATERIAL}}
|
| Reagent material must have the [SILK] token.

|-
| {{text anchor|ANY_SOAP_MATERIAL}}
|
| Reagent material must have the [SOAP] token.

|-
| {{text anchor|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].

|-
| {{text anchor|ANY_TOOTH_MATERIAL}}
|
| Reagent material must have the [TOOTH] token.

|-
| {{text anchor|ANY_YARN_MATERIAL}}
|
| Reagent material must have the [YARN] token.

|-
| {{text anchor|AUTOMATIC}}
|
| the reaction will be queued automatically if the reaction reagents are all present.

|-
| {{text anchor|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.

|-
| {{text anchor|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

|-
| {{text anchor|BUILDMAT}}
|
| Reagent is able to be used to build structures (Stone, Wood, Blocks, Bars?).

|-
| {{text anchor|CAN_USE_ARTIFACT}}
|
| Reagent can be an Artifact. Using [PRESERVE_REAGENT] with this is strongly advised.

|-
| {{text anchor|CAN_USE_HOSPITAL_RESERVED}}{{version|0.42.01}}
|
| Allows the reagent to be an item that is otherwise reserved for use by a [[healthcare|hospital]].

|-
| {{text anchor|CAN_USE_LOCATION_RESERVED}}{{version|0.42.01}}
|
| Allows the reagent to be an item that is otherwise reserved for use by a [[locations|location]].

|-
| {{text anchor|CATEGORY}}{{version|0.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.

|-
| {{text anchor|CATEGORY_NAME}}{{version|0.42.01}}
| String
| The name of the category as displayed in-game.

|-
| {{text anchor|CATEGORY_DESCRIPTION}}{{version|0.42.01}}
| String
| 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}}
| Category ID
| 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}}
| [[interface.txt|Hotkey token]]
| 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}}
| required content
| Reagent is a container that holds the specified reagent.

|-
| {{text anchor|CONTAINS_LYE}} (Deprecated)
|
| 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|DOES_NOT_ABSORB}}
|
| Reagent material must have [ABSORPTION:0]

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

|-
| {{text anchor|EMPTY}}
|
| If the reagent is a container, it must be empty.

|-
| {{text anchor|FIRE_BUILD_SAFE}}
|
| Reagent must be considered fire safe - i.e. not wood, and not coal.

|-
| {{text anchor|FORCE_EDGE}}
|
| Product is given a sharp edge. Used for knapping.

|-
| {{text anchor|FOOD_STORAGE_CONTAINER}}
|
| Reagent must be a barrel or any non-absorbing tool with [TOOL_USE:FOOD_STORAGE]

|-
| {{text anchor|FUEL}}
|
| Requires that the reaction either use up a unit of coal or charcoal or else be performed at a magma workshop

|-
| {{text anchor|GLASS_MATERIAL}}
|
| Reagent material has [IS_GLASS].

|-
| {{text anchor|HAS_ITEM_REACTION_PRODUCT}}
| PRODUCT_ID (custom)
| 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}}
| PRODUCT_ID (custom)
| 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}}
| Tool-use token
| 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.

|-
| {{text anchor|HAS_WRITING_IMPROVEMENT}}{{version|0.42.01}}
|
| Reagent must contain writing.

|-
| {{text anchor|IMPROVEMENT}}
|
* Probability
* Reagent Name
* Improvement type
* Material Token
| Improvement types include BANDS, COVERED, GLAZED, RINGS_HANGING, and SPIKES

|-
| {{text anchor|MAGMA_BUILD_SAFE}}
|
| Currently broken - behaves exactly the same as FIRE_BUILD_SAFE.

|-
| {{text anchor|MAX_MULTIPLIER}}{{version|0.42.01}}
| number
| 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}}
|
* Inorganic material
| Reagent material must be an ore of the specified metal

|-
| {{text anchor|MIN_DIMENSION}}
|
* size
| Requires that the reagent have a dimension of at least this value. Only effective with BAR, POWDER_MISC, LIQUID_MISC, DRINK, THREAD, CLOTH, and GLOB items.

|-
| {{text anchor|NAME}}
| name
| defines the name used by the reaction in-game

|-
| {{text anchor|NO_EDGE_ALLOWED}}
|
| Reagent must not be sharpened (used for knapping).

|-
| {{text anchor|HAS_EDGE}}{{version|0.42.01}}
|
| Reagent must be sharpened (used for carving).

|-
| {{text anchor|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.

|-
| {{text anchor|NOT_ENGRAVED}}
|
| Reagent must not be an engraved memorial slab.
|-
| {{text anchor|NOT_IMPROVED}}
|
| Reagent has not been decorated.

|-
| {{text anchor|NOT_PRESSED}}
|
| Reagent must not be in the SOLID_PRESSED state.

|-
| {{text anchor|NOT_WEB}}
|
| Reagent must be "collected" - used with THREAD:NONE to exclude webs.

|-
| {{text anchor|POTASHABLE}}
|
| Alias for CONTAINS_LYE.

|-
| {{text anchor|PRESERVE_REAGENT}}
|
| Reagent is not destroyed, which is the normal effect, at the completion of the reaction. Typically used for containers.

|-
| {{text anchor|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.

|-
| {{text anchor|PRODUCT_DIMENSION}}
| size
| 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.

|-
| {{text anchor|PRODUCT_PASTE}}
|
| Product is created in the SOLID_PASTE state.

|-
| {{text anchor|PRODUCT_PRESSED}}
|
| Product is created in the SOLID_PRESSED state.

|-
| {{text anchor|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.

|-
| {{text anchor|PRODUCT_TOKEN}}{{version|0.42.01}}
| name
| 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}}
| Identifier
| defines a new reaction

|-
| {{text anchor|REACTION_CLASS}}
| CLASS_ID (custom)
| 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).

|-
| {{text anchor|REAGENT}}
|
* name/id
* quantity
* [[item token]]
* [[material token]]
| Requires a given reagent as an input for a reaction

|-
| {{text anchor|SKILL}}
| Skill Token
| Skill used by the reaction

|-
| {{text anchor|TRANSFER_ARTIFACT_STATUS}}{{version|0.42.01}}
|
| Transfers artifact status from the reagent to the product.

|-
| {{text anchor|UNROTTEN}}
|
| Reagent must not be rotten, mainly for organic materials.

|-
| {{text anchor|USE_BODY_COMPONENT}}
|
| Reagent material must come off a creature's body.

|-
| {{text anchor|WEB_ONLY}}
|
| Reagent must be "undisturbed" - used with THREAD:NONE to gather webs.

|-
| {{text anchor|WORTHLESS_STONE_ONLY}}
|
| Reagent is not made of an economic stone.

|}

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

Reaction

2021-04-25T19:52:57Z

Ralpha: /* Full token list */

{{Quality|Superior|19:56, 28 August 2013 (UTC)}}
{{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 (sometimes) quite simple to add additional ones. There is a separate page with custom [[reaction examples]].

== Reaction differences between modes ==

In [[fortress mode]], reactions are linked to specific buildings, and must be added to a civilization's [[entity token|entity file]] to be usable by that civilization. This has the useful effect of limiting new items and materials (such as special [[wood]] or [[metal]]) to civilizations that have the requisite reaction — so that if you give your custom civilization a reaction to produce "star metal" or some other custom material, only they will be able to use it.

In [[adventure mode]], reactions are freely available in the {{k|x}} menu via the {{DFtext|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]
* ''[[#Reaction identifier|identifier]]'': The internal ID of the reaction.
* ''[[#Reaction name|name]]'': The name of the reaction, visible to the player in the Fortress mode or Adventure mode menus.
* ''[[#Building|building]]'': The building ID that the reaction uses, and the relevant keyboard shortcut.
* ''[[#Reagents|...reagents...]]'': Zero or more reagents (ingredients) that are required to be in stock for the reaction to be possible.
* ''[[#Products|...products...]]'': Zero or more products that are created from the reaction.
* ''[[#fuel|fuel]]'': (optional) If present, the reaction requires charcoal, coke or a magma-powered workshop.
* ''[[#skill|skill]]'': (optional) The skill required and trained by the reaction.
* ''[[#automatic|automatic]]'': (optional) If present, the reaction will automatically be enqueued whenever it can possibly be performed.
* ''[[#adventure mode|adventure mode]]'': (optional) If present, the reaction is used by the player in Adventure mode instead.

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

=== Reaction name ===

This can be anything at all, and is usually used to describe the reaction. '''Tan a hide''', for example, is the name of the default leather-producing reaction. Generally this should be written as a small descriptive verb phrase, with the first letter capitalized, for consistency with the existing reactions.

=== Building ===

[BUILDING:<BUILDING NAME>:<BUILDING KEY>]
* ''name'': The ID (that is the internal TOKEN each building can be referred to into reactions) 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 TOKENS are as follows:
* KILN - [[Kiln]] and [[Magma kiln]]
* SMELTER - [[Smelter]] and [[Magma smelter]]
* TANNER - [[Tanner's shop]]
* KITCHEN - [[Kitchen]]
* QUERN - [[Quern]]
* MILLSTONE - [[Millstone]]
* STILL - [[Still]]
* FARMER - [[Farmer's workshop]]
* CRAFTSMAN - [[Craftsdwarf's workshop]]
* GLASS{{version|0.42.01}} - [[Glass furnace]]
* WOOD{{version|0.42.01}} - [[Wood furnace]]
* MASON{{version|0.42.01}} - [[Mason's workshop]]
* ASHERY{{version|0.42.01}} - [[Ashery]]
* LEATHER{{version|0.42.01}} - [[Leather works]]
* BOWYER{{version|0.42.01}} - [[Bowyer's workshop]]
* SIEGE{{version|0.42.01}} - [[Siege workshop]]
* CLOTHES{{version|0.42.01}} - [[Clothier's shop]]
* METALSMITH{{version|0.42.01}} - [[Metalsmith's forge]]
* CARPENTER{{version|0.42.01}} - [[Carpenter's workshop]]
* Any custom (raw-defined) building type, such as:
** SOAP_MAKER - [[Soap maker's workshop]]
** SCREW_PRESS - [[Screw press]]

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

=== Category ===

{{new in v0.42}}

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.

{| {{prettytable}}
|- bgcolor="#dddddd"
! 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 || [[interface.txt|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.
|}

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

==== name ====

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

Most reagents are simply named '''A''', '''B''', and so forth in default reactions, although names such as '''TOOLSTONE''' 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 token]]s 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 [[item token|full list]] is available.

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

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

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

==== material token ====

[[Material token]]s come in several forms. For most reagents, this will typically be INORGANIC:MATERIAL_ID or NONE:NONE (to allow multiple materials using other 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:

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| [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|name]] of the reagent).
|-
| [UNROTTEN]
| Reagent must not be rotten, mainly for organic materials.
|-
| style="vertical-align: top"| [CONTAINS_LYE]
| Reagent must be a BARREL or TOOL which contains at least one item of type LIQUID_MISC made of LYE. Use of this token is discouraged, as it does not work with buckets (instead, use [CONTAINS:lye] — note the colon — and a corresponding lye reagent [REAGENT:lye:150:LIQUID_MISC:NONE:LYE]).
|-
| [POTASHABLE]
| Alias for [CONTAINS_LYE].
|-
| [NOT_WEB]
| Reagent must be collected (to distinguish silk thread from webs). Only makes sense for items of type THREAD.
|-
| [WEB_ONLY]
| Reagent must be undisturbed (to distinguish silk thread from webs). Only makes sense for items of type THREAD.
|-
| [EMPTY]
| If the reagent is a container, it must be empty.
|-
| [NOT_CONTAIN_BARREL_ITEM]
| If the reagent is a container, it must not contain [[lye]] or [[milk]]. Not necessary if specifying [EMPTY].
|-
| [BAG]
| Reagent must be a bag - that is, a BOX made of plant fiber, silk, yarn, or leather.
|-
| [GLASS_MATERIAL]
| Reagent material must have the [IS_GLASS] token. All 3 types of [[glass]] have this token hardcoded.
|-
| [BUILDMAT]
| Reagent must be a general [[building material]] - BAR, BLOCKS, BOULDER, or WOOD.
|-
| [FIRE_BUILD_SAFE]
| Reagent material must be 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 - excludes sharp stones (produced using knapping) and most types of weapon/ammo.
|-
| [HAS_EDGE]{{version|0.42.01}}
| Reagent must have an edge.
|-
| [NOT_ENGRAVED]
| Reagent has not been engraved (excludes memorial slabs).
|-
| [NOT_IMPROVED]
| Reagent has not been decorated.
|-
| [DOES_NOT_ABSORB]
| Reagent material must have [ABSORPTION:0]
|-
| [FOOD_STORAGE_CONTAINER]
| Reagent is either a BARREL or a TOOL with the FOOD_STORAGE use.
|-
| [HARD_ITEM_MATERIAL]
| 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 [[stack]]s 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.

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| [FORCE_EDGE]
| Product is given a sharp edge. Used for knapping.
|-
| [PRODUCT_PASTE]
| Product is created in the SOLID_PASTE state.
|-
| [PRODUCT_PRESSED]
| Product is created in the SOLID_PRESSED state.
|-
| [PRODUCT_DIMENSION:<size>]
| Specifies the 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:

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Meaning
|-
| COVERED
| Item is encrusted/studded/decorated with <material>.
|-
| GLAZED
| Item is glazed with <material>.
|-
| RINGS_HANGING
| Item is adorned with hanging rings of <material>.
|-
| BANDS
| Item is encircled with bands of <material>.
|-
| SPIKES
| Item menaces with spikes of <material>.
|-
| 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 token|SKILL token]] determines what skill the reaction requires and what skill it trains. Only one skill may be specified. For custom reactions, the amount of experience gained is linearly correlated with the amount of product created; a reaction with no product will yield no experience for the performing dwarf. Similarly, the amount of time a reaction takes is correlated with experience gained; if a reaction has zero experience gain due to having no skill associated, the reaction will take minimal time.

==== 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.{{version|0.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:

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

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

|-
| {{text anchor|ANY_BONE_MATERIAL}}
|
| Reagent material must have the [BONE] token.

|-
| {{text anchor|ANY_HORN_MATERIAL}}
|
| Reagent material must have the [HORN] token.

|-
| {{text anchor|ANY_LEATHER_MATERIAL}}
|
| Reagent material must have the [LEATHER] token.

|-
| {{text anchor|ANY_PEARL_MATERIAL}}
|
| Reagent material must have the [PEARL] token.

|-
| {{text anchor|ANY_PLANT_MATERIAL}}
|
| Reagent material must be subordinate to a PLANT object.

|-
| {{text anchor|ANY_SHELL_MATERIAL}}
|
| Reagent material must have the [SHELL] token.

|-
| {{text anchor|ANY_SILK_MATERIAL}}
|
| Reagent material must have the [SILK] token.

|-
| {{text anchor|ANY_SOAP_MATERIAL}}
|
| Reagent material must have the [SOAP] token.

|-
| {{text anchor|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].

|-
| {{text anchor|ANY_TOOTH_MATERIAL}}
|
| Reagent material must have the [TOOTH] token.

|-
| {{text anchor|ANY_YARN_MATERIAL}}
|
| Reagent material must have the [YARN] token.

|-
| {{text anchor|AUTOMATIC}}
|
| the reaction will be queued automatically if the reaction reagents are all present.

|-
| {{text anchor|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.

|-
| {{text anchor|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

|-
| {{text anchor|BUILDMAT}}
|
| Reagent is able to be used to build structures (Stone, Wood, Blocks, Bars?).

|-
| {{text anchor|CAN_USE_ARTIFACT}}
|
| Reagent can be an Artifact. Using [PRESERVE_REAGENT] with this is strongly advised.

|-
| {{text anchor|CAN_USE_HOSPITAL_RESERVED}}{{version|0.42.01}}
|
| Allows the reagent to be an item that is otherwise reserved for use by a [[healthcare|hospital]].

|-
| {{text anchor|CAN_USE_LOCATION_RESERVED}}{{version|0.42.01}}
|
| Allows the reagent to be an item that is otherwise reserved for use by a [[locations|location]].

|-
| {{text anchor|CATEGORY}}{{version|0.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.

|-
| {{text anchor|CATEGORY_NAME}}{{version|0.42.01}}
| String
| The name of the category as displayed in-game.

|-
| {{text anchor|CATEGORY_DESCRIPTION}}{{version|0.42.01}}
| String
| 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}}
| Category ID
| 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}}
| [[interface.txt|Hotkey token]]
| 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}}
| required content
| Reagent is a container that holds the specified reagent.

|-
| {{text anchor|CONTAINS_LYE}} (Deprecated)
|
| 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|DOES_NOT_ABSORB}}
|
| Reagent material must have [ABSORPTION:0]

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

|-
| {{text anchor|EMPTY}}
|
| If the reagent is a container, it must be empty.

|-
| {{text anchor|FIRE_BUILD_SAFE}}
|
| Reagent must be considered fire safe - i.e. not wood, and not coal.

|-
| {{text anchor|FORCE_EDGE}}
|
| Product is given a sharp edge. Used for knapping.

|-
| {{text anchor|FOOD_STORAGE_CONTAINER}}
|
| Reagent must be a barrel or any non-absorbing tool with [TOOL_USE:FOOD_STORAGE]

|-
| {{text anchor|FUEL}}
|
| Requires that the reaction either use up a unit of coal or charcoal or else be performed at a magma workshop

|-
| {{text anchor|GLASS_MATERIAL}}
|
| Reagent material has [IS_GLASS].

|-
| {{text anchor|HAS_ITEM_REACTION_PRODUCT}}
| PRODUCT_ID (custom)
| Similar to MATERIAL_REACTION_PRODUCT, but requires the reagen'ts material to have a matching ITEM_REACTION_PRODUCT entry.

|-
| {{text anchor|HAS_MATERIAL_REACTION_PRODUCT}}
| PRODUCT_ID (custom)
| Similar to REACTION_CLASS, but requires the reagent's 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}}
| 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.

|-
| {{text anchor|HAS_WRITING_IMPROVEMENT}}{{version|0.42.01}}
|
| Reagent must contain writing.

|-
| {{text anchor|IMPROVEMENT}}
|
* Probability
* Reagent Name
* Improvement type
* Material Token
| Improvement types include BANDS, COVERED, GLAZED, RINGS_HANGING, and SPIKES

|-
| {{text anchor|MAGMA_BUILD_SAFE}}
|
| Currently broken - behaves exactly the same as FIRE_BUILD_SAFE.

|-
| {{text anchor|MAX_MULTIPLIER}}{{version|0.42.01}}
| number
| 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}}
|
* Inorganic material
| Reagent material must be an ore of the specified metal

|-
| {{text anchor|MIN_DIMENSION}}
|
* size
| Requires that the reagent have a dimension of at least this value. Only effective with BAR, POWDER_MISC, LIQUID_MISC, DRINK, THREAD, CLOTH, and GLOB items.

|-
| {{text anchor|NAME}}
| name
| defines the name used by the reaction in-game

|-
| {{text anchor|NO_EDGE_ALLOWED}}
|
| Reagent must not be sharpened (used for knapping).

|-
| {{text anchor|HAS_EDGE}}{{version|0.42.01}}
|
| Reagent must be sharpened (used for carving).

|-
| {{text anchor|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.

|-
| {{text anchor|NOT_ENGRAVED}}
|
| Reagent must not be an engraved memorial slab.
|-
| {{text anchor|NOT_IMPROVED}}
|
| Reagent has not been decorated.

|-
| {{text anchor|NOT_PRESSED}}
|
| Reagent must not be in the SOLID_PRESSED state.

|-
| {{text anchor|NOT_WEB}}
|
| Reagent must be "collected" - used with THREAD:NONE to exclude webs.

|-
| {{text anchor|POTASHABLE}}
|
| Alias for CONTAINS_LYE.

|-
| {{text anchor|PRESERVE_REAGENT}}
|
| Reagent is not destroyed, which is the normal effect, at the completion of the reaction. Typically used for containers.

|-
| {{text anchor|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.

|-
| {{text anchor|PRODUCT_DIMENSION}}
| size
| 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.

|-
| {{text anchor|PRODUCT_PASTE}}
|
| Product is created in the SOLID_PASTE state.

|-
| {{text anchor|PRODUCT_PRESSED}}
|
| Product is created in the SOLID_PRESSED state.

|-
| {{text anchor|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.

|-
| {{text anchor|PRODUCT_TOKEN}}{{version|0.42.01}}
| name
| 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}}
| Identifier
| defines a new reaction

|-
| {{text anchor|REACTION_CLASS}}
| CLASS_ID (custom)
| 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).

|-
| {{text anchor|REAGENT}}
|
* name/id
* quantity
* [[item token]]
* [[material token]]
| Requires a given reagent as an input for a reaction

|-
| {{text anchor|SKILL}}
| Skill Token
| Skill used by the reaction

|-
| {{text anchor|TRANSFER_ARTIFACT_STATUS}}{{version|0.42.01}}
|
| Transfers artifact status from the reagent to the product.

|-
| {{text anchor|UNROTTEN}}
|
| Reagent must not be rotten, mainly for organic materials.

|-
| {{text anchor|USE_BODY_COMPONENT}}
|
| Reagent material must come off a creature's body.

|-
| {{text anchor|WEB_ONLY}}
|
| Reagent must be "undisturbed" - used with THREAD:NONE to gather webs.

|-
| {{text anchor|WORTHLESS_STONE_ONLY}}
|
| Reagent is not made of an economic stone.

|}

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

Item definition token

2020-10-11T17:15:10Z

Ralpha: ordered item types

{{Quality|Fine|07:17, 17 May 2015 (UTC)}}
{{av}}
'''Item definition tokens''' are used in item definitions in the raws.

Item types:
* ITEM_AMMO - [[ammo token]]
* ITEM_ARMOR - [[Armor token|armor-type armor token]]
* ITEM_FOOD - see below
* ITEM_GLOVES - [[Armor token|gloves-type armor token]]
* ITEM_HELM - [[Armor token|helm-type armor token]]
* ITEM_INSTRUMENT - [[instrument token]]
* ITEM_PANTS - [[Armor token|pants-type armor token]]
* ITEM_SHIELD - [[Armor token|shield-type armor token]]
* ITEM_SHOES - [[Armor token|shoes-type armor token]]
* ITEM_SIEGEAMMO - see below
* ITEM_TOOL - [[tool token]]
* ITEM_TOY - see below
* ITEM_TRAPCOMP - [[trap component token]]
* ITEM_WEAPON - [[weapon token]]

==Toy Tokens==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|NAME}}
| singular:plural
| What this item will be called in-game.

|-
| {{text anchor|HARD_MAT}}
|
| Presumably prevents the item from being made from cloth, silk, or leather, present on everything but puzzleboxes and drums. Appears to work backwards for [[strange mood]]s.

|}

==Siege Ammo Tokens==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|NAME}}
| singular:plural
| What this item will be called in-game.

|-
| {{text anchor|CLASS}}
|
| Specifies what type of siege engine uses this ammunition. Currently, only BALLISTA is permitted.

|}

==Food Tokens==
{| {{prettytable}}
|- bgcolor="#ddd"
! Token
! Arguments
! Description

|-
| {{text anchor|NAME}}
| singular:plural
| What this item will be called in-game.

|-
| {{text anchor|LEVEL}}
|
| Specifies the number of ingredients that are used in this type of prepared meal - 2 for Easy, 3 for Fine, 4 for Lavish. Defaults to 2.

|}

{{Category|Modding}}
{{Category|Tokens}}

[[ru:Item definition token]]

Utilities

2020-09-30T22:11:14Z

Ralpha: Added DF Storyteller

{{Quality|Masterwork|13:28, 28 September 2013 (UTC)}}
{{av}}

'''Utilities''' are third-party applications useful for ''Dwarf Fortress'' players and modders, and this page serves as a list of them. ''Dwarf Fortress'' is a difficult game to play, and any help that can be had in the task is welcome help. This page lists utilities useful for modders and players alike. If you would like to add an article on a ''specific'' game utility to the wiki, please do so under the [http://dwarffortresswiki.org/index.php?title=Special%3AAllPages&from=&to=&namespace=102 Utility] namespace. Not included on this page: [[Main:Tileset repository|tileset repositories]] and [[Main:Graphics set repository|graphics set repositories]], due to having been given their own, separate pages. [[Modding|Mods]] have also been listed under their own [http://dwarffortresswiki.org/index.php?title=Special%3AAllPages&from=&to=&namespace=104 Modification] namespace. To avoid namespace clutter, websites ''are'' considered utilities, though they really aren't, and have been included.

A [http://www.bay12forums.com/smf/index.php?board=29.0 subsection of the Bay12 forums] is devoted to such third-party programs, and contains development threads for most of them.

The [[Utilities#Lazy Newb Pack|Lazy Newb Pack]] is an effort to make ''Dwarf Fortress'' more accessible for new players by bundling and configuring utilities, graphics and tilesets, and extras such as reference material or more intuitive controls.

==Launchers==

=== [[Utility:Lazy_Newb_Pack|Lazy Newb Pack]] ===
<gallery widths=90px heights=150px>
File:Lnp-gui1.png|The original LNP launcher, options tab
File:Lnp-gui2.png|The graphics tab
File:Lnp-gui3.png|The utilities tab
File:Lnp-gui5.png|The advanced tab
File:lnp-dfhack.png|The DFHack tab
</gallery>
A commonly-used software bundle with a nice launcher. Allows you to start playing DF really quickly on a new machine - no need to download and integrate [[Graphics set repository|tilesets]] and tools like Dwarf Therapist, SoundSense, etc. - or even know what you need to get. The newer packs also include many third-party fixes for common bugs, which work automatically, and a large number of significant user interface improvements. The launcher makes changing settings or graphics options much easier (press button, instead of editing files) and can even remember to launch selected utilities whenever you open a game of ''Dwarf Fortress''. See the [[Utility:Lazy_Newb_Pack|Lazy Newb Pack]] page for more information, or the forum thread for your platform.

*[http://www.bay12forums.com/smf/index.php?topic=126076 PeridexisErrant's Starter Pack] (Windows)
*[http://www.bay12forums.com/smf/index.php?topic=128960 MacNewbie Pack] (OS X)
*[http://www.bay12forums.com/smf/index.php?topic=156011 Unofficial Linux LNP] (Linux)

===[http://www.bay12forums.com/smf/index.php?topic=140808 PyLNP] ===
A cross-platform LNP port, written in Python. The launcher and configuration interface for all of the Lazy Newb Packs. PyLNP is under active development for bugfixes, addition of features pioneered by other launchers, and creation of entirely new features - such as rebuilding the raws of modded saves to change graphics packs.

===[http://www.bay12forums.com/smf/index.php?topic=102316 Manila Launcher] ===
A Java interface that allows easy option toggling, update and devlog checking, and tileset, mod and color scheme switching. Designed for players who prefer vanilla DF to a bundle like the above.

== 3D Visualizers ==

=== [[Utility:Stonesense|Stonesense]] ===
Stonesense is a third party visualizer, implemented as a [[Utility:DFHack|DFHack]] plugin, that lets you view your fortress in a classic isometric perspective. It runs alongside ''Dwarf Fortress'', and can follow the main game's view, updating in real-time. It is included in DFHack, and can be opened by typing <code>stonesense</code> or <code>ssense</code> into the console window.
[[File:stonesense_prev.jpg|frameless|250px|none]]

=== [http://www.bay12forums.com/smf/index.php?topic=63484 Fortress Overseer] ===
Fortress Overseer is the only 3D visualizer supporting v0.31. It has been completely rewritten and is currently updated to support v0.34.11 and v0.31.25. Overseer works indirectly, by using [[Utility:DFHack|DFHack]]'s <code>mapexport</code> to export a file which can then be rendered in 3D. DirectX 9 must be installed, though this requirement is not documented. Has not been tested for 0.40.13.
[[File:fortress_viewer.jpg|frameless|250px|none]]

=== [http://www.bay12forums.com/smf/index.php?topic=146473.0 Armok Vision] ===
Armok Vision is a 3D real-time visualizer using Unity for version 0.40.24. It works as a separate program communicating with the game through fast network interfaces.
[[File:armok_vision.png|frameless|250px|none]]

=== [http://www.bay12forums.com/smf/index.php?topic=70700.0 Isoworld] ===
Isoworld is an isometric world map viewer, which can display each of the detailed maps exported from [[Legends mode]]. It also has a pictographic view which makes finding waterfalls easy.

Isoworld can link with [[Utility:DFHack|DFHack]] to display a game view at full spatial resolution in wider context, including tracking the player's view. This is particularly useful for adventure mode.
[[File:isoworld_prev.png|thumb|240px|none|Looks nostalgic.]]

=== [http://www.bay12forums.com/smf/index.php?topic=159578.0 Voxel Fortress] ===
Voxel Fortress is a converter from DF worlds to a voxel format. It takes an export of one of the two elevation maps (for the voxels coordinates), and any other one (for the colors).
The map is saved in .xraw format. An additional utility (e.g. [https://ephtracy.github.io/index.html?page=mv_renderer MagicaVoxel Viewer]) is required to see the voxel representation of the map.

[[File:voxel_prev.png|frameless|250px|none]]

== Music and Sounds ==

=== [[Utility:SoundSense|SoundSense]] ===
[[File:soundsense_prev.png|thumb|100px|right|Soundsense]]SoundSense is a tool that parses game logs and reacts to game events with sound effects, incidental music and dwarfy comments. You can look it up on the [http://www.bay12forums.com/smf/index.php?topic=60287 forum thread], or directly download it at [http://df.zweistein.cz/soundsense/ the SoundSense homepage]. Due to it being written in Java, Soundsense is portable to all platforms.

Due to development having slowed down, a [https://github.com/calmhorizons/soundsense fork] was released that most notably disables the broken auto-updater and adds the option to minimize Soundsense to the system tray.

Note that older Soundsense users may have different default seasonal soundtracks, which were removed and replaced in early 2011. These are available [http://www.krauselabs.net/dump/music.zip here].

=== [http://www.bay12forums.com/smf/index.php?topic=159567.0 SoundCenSe] ===

[[File:soundCenSe_prev.png|thumb|100px|right|SoundCenSe]]A C# port of SoundSense, it uses the existing sound pack files and XML's present in SoundSense, but with some added enhancements. More information regarding what specific type of enhancements and how to install SoundCenSe can be gathered at the [http://www.bay12forums.com/smf/index.php?topic=159567.0 official forum thread]. If problems emerge while trying to get SoundSense to work with the latest versions of Java, this port may prove to be a useful alternative.

Downloads for the windows and linux binaries are available [https://github.com/Algorithman/SoundCenSe/releases here], while code releases can be obtained from the [https://github.com/Algorithman/SoundCenSe GitHub site].

== Game manipulation tools ==

===[[Utility:DFHack|DFHack]]===

[[Utility:DFHack|DFHack]] is an advanced ''Dwarf Fortress'' memory access library and a set of tools and scripts using this library, providing direct object-oriented access to Dwarf Fortress's internals as if it were compiled into the game itself. Runs on Windows, Linux, and OS X. The standard configuration enables a variety of included bugfixes and interface upgrades, and provides many useful tools such as "clean all".

DFHack has an [http://www.bay12forums.com/smf/index.php?topic=164123 official forum thread]. Code is available from the [https://github.com/DFHack/dfhack GitHub site], along with [https://github.com/DFHack/dfhack/releases releases].

Falconne's UI plugins are included in DFHack, as are automation tools Autolabor, Workflow, Autobutcher, and many others.

[[File:dfhack_cmd.png|thumb|240px|none|DFHack's console.]]

==== User Interface Plugins ====
A collection of DFHack plugins by Falconne that improve the in-game interface with features such as:
* Search function in screens with big lists.
* Ability to place furniture before it's built and have it automatically allocated when available.
* Ability to place constructions with box select (like laying designations), including easier material selection and open space placement (without having to wait till adjacent constructions are built).
* Easier pasturing, live happiness monitor, mouse support, stocks dashboard.

==== Binary patches ====
Binary patches are utilities made by users to fix known bugs that haven't been addressed by [[main:Toady One|Toady One]] yet. DF2014 is in active development, so there are no binary patches yet.

==== Feature plugins ====
These plugins add features to the game.
* [http://www.bay12forums.com/smf/index.php?topic=127116 Digging invaders], a plugin that allows hostiles to dig and deconstruct walls to path to one's fortress.
* [http://www.bay12forums.com/smf/index.php?topic=128487 Rendermax], a plugin that implements a lighting system at the graphics level.
* [http://www.bay12forums.com/smf/index.php?topic=136155 Dwarven Emigration], a script that allows unhappy dwarves to emigrate with their families.

==== Interaction plugins ====
[http://www.bay12forums.com/smf/index.php?topic=135597 DFHack scripts designed for modders to use as "spells"] (not in standard package)

==== Miscellaneous plugins ====
[http://www.bay12forums.com/smf/index.php?topic=135506 DFHack script collection] (not in standard package)

=== remotefortressreader ===

A critical internal DFHack plugin, [https://github.com/DFHack/dfhack/tree/develop/plugins/remotefortressreader developed within the same repository]. It provides a protobuf-based (currently v2.4.1) RPC connection to the game, enabling remote clients like Armok Vision. The service listens on <code>127.0.0.1:5000</code> (configurable within <code>dfhack-config/remote-server.json</code>).

Currently there are no change-based or change-driven notifications, so remote fortress clients must perform the expensive operation of polling the desired volume every frame (via e.g. <code>GetBlockList</code>). Additionally, the sidebar menu state is shared with the native view, to avoid reimplementing construction material dependencies.

==Dwarf Therapist==
===[http://www.bay12forums.com/smf/index.php?topic=168411.0 Dwarf Therapist]===
Dwarf Therapist gives you an advanced GUI to manage and check dwarf job allocations, military assignments, statistics (such as attributes, personality traits and happiness), sort dwarves by various criteria (e.g. profession, migration wave, happiness, number of assigned jobs etc.) and generally manage the Dwarven Resources of your fortress in a very convenient way. This version contains the "labor optimizer" semi-automatic labor management system.

Splinterz' fork of Dwarf Therapist is the currently updated version, and available for Windows, Mac and GNU + Linux. Besides the Bay12 forum thread, there's more information on the [https://github.com/Dwarf-Therapist/Dwarf-Therapist GitHub project page].

See the [http://www.bay12forums.com/smf/index.php?topic=168411.0 forum thread] for current downloads.

[[File:dwarf_therapist.png|thumb|280px|none]]

====[[Utility:Dwarf Therapist/Addons Repository|Dwarf Therapist Addons Repository]]====

A collection of customizations for Dwarf Therapist submitted by the community.

Addons include:

* custom professions
* custom roles
* optimization plans
* filter scripts
* new grid views

== Fortress layout tools ==
<strike>=== [http://www.bay12forums.com/smf/index.php?topic=87731 DF Designator] ===
DF Designator helps you build fortresses from either image files or Quickfort .CSV files. It also has a user interface that allows you to assign hotkeys to blueprints and to combine blueprints in multi z-level designs. Windows, Mac and Linux versions are available. DF Designator uses 'typewriter style' playback, and is thus very slow for large projects.</strike>

=== [https://github.com/joelpt/quickfort Quickfort] ===
Quickfort is a utility for ''Dwarf Fortress'' that helps you build fortresses from "blueprint" .CSV files (comma separated values). These files are easily created and edited in an app like Excel. Most building-oriented DF commands are supported through the use of multiple .CSV files to describe the different phases of DF construction (designation, building, stockpiles, and making adjustments. Recent versions of Quickfort work by converting the blueprint into a native macro for ''Dwarf Fortress'', then executing the macro. This allows for enormously faster playback compared to early versions or DF Designator.

====[https://www.mediafire.com/folder/u38qsqr1bq6wu/Community_Quickfort_Blueprints_v2 Quickfort Community Blueprints]====

A large collection of blueprints, published to remove the last hint of hassle in creating a fortress. You can download the lot without a paid account [http://www.mediafire.com/download/n6im1ok6z02n8nc/Community_Quickfort_Blueprints_v2.zip here].

===[http://www.bay12forums.com/smf/index.php?topic=55025 ChromaFort]===
Chromafort is a tool designed to complement [[Utilities#Quickfort|Quickfort]], by converting images into quickfort-compatible .csv files. It works with 24-bit bitmap (.bmp) files. There are a number of known issues that can affect any image that is not square, and the size must be an exponent of two (8, 16, 32, 64...); other images may show nonexistent colours and/or come out highly distorted.

===[http://www.bay12forums.com/smf/index.php?topic=138590 Picturefort]===
Picturefort is an attempt to make "Chromafort, but ''better''" - it performs the same function of converting an image to a [[Utilities#Quickfort|Quickfort]]-compatible .csv file. Unlike Chromafort, Picturefort can handle a large number of image formats (though .bmp or .png are recommended); images can be of any shape and within reason size; and while as of May 2014 it is only available on Windows, there are plans for a Linux version.

===[http://www.bay12forums.com/smf/index.php?topic=154849.0 Symmetricity]===
A fortress planner with a focus on multiple planes of symmetry. It can output csv for quickfort. It's early in development so it's probably not suitable for serious use cases.

== Modding tools ==

===[http://www.bay12forums.com/smf/index.php?topic=140853.0 Rubble]===

A useful plugin-based modding tool that generates raws and supports easy installation of reactions, tilesets, macros, modding fixes and DFHack scripts. It is a fork of the now abandoned [http://www.bay12forums.com/smf/index.php?topic=125997.0 Blast]. Binaries are available for Linux 32-bits, OS X 32-bits and Windows 64-bits, as well as the source (written in Go with building instructions). As of 4.0, a GUI is available for Windows.

=== [http://www.bay12forums.com/smf/index.php?topic=150857.0 PyDwarf] ===

For players, PyDwarf is an easy way to manage and configure preferred mods in a way that avoids almost entirely the problems of outdated mods or incompatible groups of mods. For modders, PyDwarf's mod manager exposes a powerful Python API for interacting with raws and other data files.

=== [http://www.bay12forums.com/smf/index.php?topic=103360 Raw Explorer] ===
A tree-based raw files browser, editor and manager.

=== [http://www.bay12forums.com/smf/index.php?topic=174431.0 Dwarf_RAW] ===
A GUI for editing raw files, updated 2019.

=== [http://www.bay12forums.com/smf/index.php?topic=140645.0 Dwarf Fortress real-life material helper] ===
A Python script that generates raws based on custom real-life material values.

=== [http://www.bay12forums.com/smf/index.php?topic=140688.0 Roses' Random Creature Script] ===
A Python script that generates random creature raws.

=== [http://www.bay12forums.com/smf/index.php?topic=175695.0 DF duplisearch] ===
A Python script/.exe file that checks your raws folder for duplicated objects.

== World Map / World Gen Tools ==
=== [http://dffd.wimbli.com/file.php?id=2354 Perfect World DF] ===
Requires an additional (tiny) download to be functional for current versions (40.#): [http://dffd.wimbli.com/file.php?id=8756 WorldGen.xml] . Easy access to world settings for quick modification to allow highly customized world generation far easier and faster than DF's ingame advanced map maker. [http://www.bay12forums.com/smf/index.php?topic=57428.0 forum thread]

=== [http://pastebin.com/jdVKPzpt Fortress World Generator] ===
A bash script for automating world generation of large numbers of worlds on GNU/Linux.

=== [http://www.bay12forums.com/smf/index.php?topic=73095 Dwarf Map Maker] ===
A Photoshop action script which turns legends mode exported maps into a much prettier fantasy map. There is also a version available [http://www.bay12forums.com/smf/index.php?topic=73095.msg2261106#msg2261106 for GIMP].

=== [http://www.bay12forums.com/smf/index.php?topic=137076.msg5085575#msg5085575 Satellite Map Maker] ===
A GIMP script based on the Dwarf Map Maker that creates a satellite image of ''Dwarf Fortress'' world maps.

==Legends tools==

=== [http://www.bay12forums.com/smf/index.php?topic=72702 Legends Viewer] ===
<gallery widths=200px>
File:legends_prev.png|Historical Figures view
File:legends_prev2.png|Infrastructure view
File:legends_prev3.png|Other/Eras view
</gallery>
[http://www.bay12forums.com/smf/index.php?topic=154617 Unofficial Branch for 0.47.XX version of DF]

Legends Viewer loads up the legends you can export in a much more usable format than the [[Legends mode]] of DF itself. Legends Viewer can open pages in new tabs, filter information on a wide range of criteria, and display information on the map as well. Binaries are only available for Windows, as well as the source (written in C#).

It takes four files as input: the legends XML file, the sites and pops text, world history text, and a map image. It can load these separately, but it is recommended to load them as a single compressed archive (folder) - the XML can be multiple GB uncompressed for long histories, and reduce to less than 5% of its size.

If you have played a fortress and then exported legends, you may get an error about unreadable HEX characters. This is caused by Workflow, which saves its settings as unreadable historical figures. There are several ways to fix this:
* Clear the workflow settings in fortress mode before exporting legends
* Edit the XML by hand, [http://www.bay12forums.com/smf/index.php?topic=72702.msg4629392#msg4629392 as described here] (any platform)
* Use the [http://www.bay12forums.com/smf/index.php?topic=131307 Legends Processing script] (windows only), which fixes the XML and also creates a compressed folder as described above

=== [http://www.bay12forums.com/smf/index.php?topic=128932.0 World Viewer] ===
[[File:world_viewer_prev.png|thumb|200px|none|"Race" tab view]]
An alternative to Legends Viewer that most specifically features a timeline of historical events. Binaries are only available for Windows, as well as the source (written in C#).

=== [http://www.uristmaps.org Uristmaps] ===
[[File:uristmaps_prev.png|thumb|200px|none|Zoomed-in area of a map view.]]
A web-based interface that displays worlds in the way of an interactive map complete with features and structures.

=== [http://www.bay12forums.com/smf/index.php?topic=155307.0 LegendsBrowser] ===
[[File:legendsbrowser.png|thumb|200px|none|Civilizations view]]
A web-based multi-platform (Win, Linux, OSX) Viewer. It displays an interactive map and legends information (using legends_plus.xml generated via DFHack).

=== [https://dfstoryteller.com/ DF Storyteller] ===
<gallery widths=200px>
File:DF_Storyteller_Logo.svg|DF Storyteller Logo
File:DF_Storyteller_explain_workings.png|Explains how DF Storyteller works
File:The_Bard_historical_figure_screenshot.png|Screenshot of Historical Figure in The Bard visualizer
</gallery>
Dwarf Fortress Storyteller (DF Storyteller, DF ST) is an application that parses Dwarf Fortress legends files, stores them internally and makes them queryable using API's. (Cross platform: Windows, Linux, macOS)
This utility can be used to easily create new visualizers to view the legends data. A list of visualizers can be found [https://gitlab.com/df_storyteller/df-storyteller/-/blob/master/docs/paintings.md here].
An example of a visualizer is [https://gitlab.com/df_storyteller/the-bard The Bard] created in DF ST.

== Remote playing tools ==

=== [[Utility:Dfterm3|Dfterm3]]===

[[Utility:Dfterm3|Dfterm3]] is a remote ''Dwarf Fortress''-playing software for multiple users through a web interface. DFterm3 enables play through a web interface, and games can also be viewed on mobile - or even played if a bluetooth keyboard is attached. The web interface should work with Chrome or Firefox browsers, but there are known problems using Internet Explorer. DFTerm3 functions via a DFHack plugin, and is thus dependent on each version of DFHack.

It is a successor to [[Utility:dfterm2|dfterm2]], which functions similarly using telnet instead of a web browser. This utility only works with version 0.34.11 or earlier.

=== [http://www.bay12forums.com/smf/index.php?topic=139167.0 Webfort] ===
[[File:webfortress.png|thumb|200px|none|Playable in Mac browser.]]
A newer alternative to dfterm3 that functions similarly, but players must wait in a queue before assuming control for a given period of time. It also functions via a DFHack plugin. Binaries are available for Windows, as well as the source (written in C++). ''(Note: [https://github.com/mifki/df-webfort main repo] unmaintained. [https://github.com/Ankoku/df-webfort New repo] last updated 5/22/2015.)''

=== [http://www.bay12forums.com/smf/index.php?topic=140892.0 DorfServer] ===
[[File:dorfserver.png|thumb|200px|none|Like Twitch, without Twitch.]]
A remote SSH-based ''Dwarf Fortress'' host software. ([http://www.bay12forums.com/smf/index.php?topic=140892.0 repo])

=== [http://www.bay12forums.com/smf/index.php?topic=139975.0 DFEverywhere] ===

A utility that connects a locally-run ''Dwarf Fortress'' instance to a proprietary remote website, allowing remote browser-based play. ''(Note: Main website no longer available. [https://github.com/tpainter/df_everywhere Client source here.])''

=== [http://mifki.com/df Dwarf Fortress Remote] ===

iOS app (paid) that allows one to play ''Dwarf Fortress'' remotely with native UI. A server can be set up at home, or on DigitalOcean, AWS or other hosting service.

=== [http://www.bay12forums.com/smf/index.php?topic=176070.msg DFPlex ] ===

DFPlex is a plugin for DFHack which introduces simultaneous, real-time online co-op to fortress mode: each player has their own independent view, cursor, menus, etc. so nobody has to wrestle for control. It's a fork of webfort, so players join just by connecting from their web browser.

==Language tools==

===[http://www.bay12forums.com/smf/index.php?topic=47332.0 DFLang]===
A language creating tool.

===[http://www.bay12forums.com/smf/index.php?topic=136098.0 Toadese Language Utility]===
A language editing and translating tool.

===[http://www.bay12forums.com/smf/index.php?topic=140432.0 DFlangOpt]===
A little tool meant to prevent redundancy when importing or updating language files.

===[http://dffd.wimbli.com/file.php?id=8288 Python language extraction and injection script]===
This simple script will extract words from language files and put them a word per line, for easy automatic translation or treatment. It can also read that list and put the translated words back in their place.

==Announcement tools==

===[http://www.bay12forums.com/smf/index.php?topic=130590 DFMon] ===

An announcement monitoring/filtering program, useful to hide some types of job cancellation spam or other more advanced filtering. Note that you can set the game to announce no job cancellations ''without'' any utilities or mods from the {{k|o}}rders menu, with {{k|x}}.

===[http://www.bay12forums.com/smf/index.php?topic=130030 DF Announcement Filter]===

An alternative to DFMon written in Java (and thus portable to Linux and OS X).

===[http://www.bay12forums.com/smf/index.php?topic=153777 Announcement Window+]===

Announcement Window+ is a Python application that interfaces with ''Dwarf Fortress'' to print announcements and combat reports to a separate window. It was written to fix some annoying bugs that are present in DF Announcement Filter, which is no longer being updated.

[[File:announce+_prev.png|thumb|300px|none|One less game-pausing hotkey.]]

==Filesharing websites==

=== [http://dffd.wimbli.com/ Dwarf Fortress File Depot] ===
The Dwarf Fortress File Upload Service - an excellent place to store mods, community games, tilesets and other files. Courtesy of [[User:Janus|Janus]]; for files related to Dwarf Fortress only.

=== [http://mkv25.net/dfma/ Dwarf Fortress Map Archive] ===
{{main|Utility:Dwarf Fortress Map Archive}}

The Dwarf Fortress Map Archive is a large collection of user-submitted maps and videos and a nice flash viewer for perusing them. Maps are uploaded, stored, and downloaded in a special compressed format created by the DF Map Compressor; videos are stored in a compressed version of Toady One's own video-recording format.

Read more about the [[User:Markavian/DF_Map_Archive|DF Map Archive]] on Markavian's User page.

== Other/miscellaneous ==

=== [http://shadowlord13.googlepages.com/dfmap-index.html DF Map Compressor] ===
[[File:dfmapcomp.png|thumb|200px|none|Main program window.]]
The DF Map Compressor encodes multiple bitmaps exported from ''Dwarf Fortress'' into a single, very compressed, .fdf-map file. The fdf-map file can then be shared with your friends by uploading to the DF Map Archive that features an online viewer (written in Flash).

=== [http://www.mindwerks.net/projects/exita/ Exita] ===
Exita is a Python program that takes your DF world map exports and dump them into several different text outputs.

===[http://www.bay12forums.com/smf/index.php?topic=132153.0 DwarfFamily]===
A tool that lets you import your legends XML file and converts all dwarf entries to a .GED file, which you can use in Family Tree programs like MyHeritage to display a family tree for the dwarves.

===[https://www.dropbox.com/s/dea50wrs557w283/kobold.py Kobold name generator]===
A Python script that generates random names in the way of kobold utterances

=== [http://www.bay12forums.com/smf/index.php?topic=717.0 CMVPlayer] ===

First released by Jifodus in April 2007. This application enables playback of the DF movies (.cmv) without starting DF. It also provides some more functionalities, such as:
* Rewind
* Pause
* Play frame per frame

To use, simply unzip the file, and drop and drag the movie on CMVPlayer.exe. ''(Note: Main website is no longer available.)''

===[https://play.google.com/store/apps/details?id=dae.dfnews Dwarf Fortress News - Android App]===
Watches the ''Dwarf Fortress'' devblog. Receives Push Notifications on new updates.

{{Category|Modding}}
{{Category|Community}}
[[ru:Utilities]]

File:The Bard historical figure screenshot.png

2020-09-30T22:05:32Z

Ralpha: A Screenshot of [https://gitlab.com/df_storyteller/the-bard The Bard], a visualizer created using DF Storyteller.

== Summary ==
A Screenshot of [https://gitlab.com/df_storyteller/the-bard The Bard], a visualizer created using DF Storyteller.
== Licensing ==
{{self|cc-by-sa-3.0}}

File:DF Storyteller Logo.svg

2020-09-30T22:01:49Z

Ralpha: Logo of DF Storyteller

== Summary ==
Logo of DF Storyteller
== Licensing ==
{{self|cc-by-sa-3.0}}

File:DF Storyteller explain workings.png

2020-09-30T22:00:09Z

Ralpha: Explains how DF Storyteller works

== Summary ==
Explains how DF Storyteller works
== Licensing ==
{{self|cc-by-sa-3.0}}

Legends

2020-07-12T19:52:17Z

Ralpha: Added new map types

{{Quality|Exceptional|06:48, 6 October 2013 (UTC)}}
{{av}}

'''Legends''' mode is one of the three main methods of interacting with an already-generated [[World generation|world]]. You cannot start Legends mode (or [[Dwarf fortress mode|Fortress]] or [[Adventurer mode|Adventurer]] mode) until you create a new world.

Legends mode allows you to inspect the history of a world. Many players choose to design a world where the option '''Reveal all history''' is set to YES. However, if you set the option to NO, then the vast majority of the world's history will be hidden from Legends mode, and only uncovered by brave adventurers. In fact, there are many ways for an adventurer to uncover the past. Talk to people in civilized sites and they will tell you of their families, surroundings and local history. Past events can also be found by viewing [[coins]] or items with images, or by visiting abandoned [[fortress]]es and viewing the [[engraving|engraved]] tiles within.

You don't ''have'' to have an adventure or fortress game active in order to use legends mode. Some players simply enjoy legends mode for the option of looking at the interactive historical map, or to read about the last time their favorite kingdom went to war, or for the ability to export lists of all the sites and governments active in the world.

==Legends information==

=== Number of Events Undiscovered ===
A self-explanatory number indicating how many "legends" are still lost in the mists of time. If you chose to reveal all history during world generation, the number displayed should be 0. Otherwise, better get out there and adventure some more.

=== Historical Figures ===
The number to the right indicates how many [[historical figure]]s exist in this world's history. Historical figures include entries on [[megabeast]]s, [[forgotten beast]]s, [[demon]]s, [[deity|gods]], [[Dwarf|dwarves]], [[human]]s, [[goblin]]s, [[kobold]]s, and named [[creature]]s.

=== Sites ===
The number to the right indicates how many [[site]]s have existed throughout this world's history. [[Site]]s include things like [[town]]s, [[Tower (necromancy)|tower]]s, [[fortress]]es, [[forest retreat]]s, and [[cave]]s.

=== Regions ===
A list of the various regions of the world, along with the various historical events that occurred within those regions.

=== Civilizations and Entities ===
The number to the right indicates how many civilizations, local governments, and religions have existed throughout this world's history. The histories of these various groups can be viewed as well, detailing events like when a site was founded, when a person was kidnapped, or when a road was completed.

=== Structures ===
Structures are buildings found throughout the world. Fortresses, towers, shops, taverns, temples and more can all be found in this list.
Temples are the central location of [[religion]]s, and can be 'profaned' by historical figures, though it is not explained what this involves.

=== Historical Map ===
The historical map is a relatively new and very cool feature of Legends mode. From here you can view the territorial disputes between different civilizations and entities, including those who were destroyed before your starting year. If you are new to ''Dwarf Fortress'', reading the map may be a little difficult, but play around with these buttons and you might get a better grasp of what you are seeing. Press {{k|Enter}} while looking at the map to change between the political and geographical view of the world. The geographic map is colored (blue seas, gray mountains, green forests etc.) while the political map's background is tan (think parchment) with colored fields corresponding to the territories of different civilizations. Civilizations can lay claim to the same area, causing the colored territory markers to overlap. You can also see how territories changes over time by moving 10 or 100 years forward and back through time. Pressing {{k|c}} while looking at the political map will show local government territories instead of civilizations, but that's generally a pretty messy scene.

=== The Age of... ===
During world generation, the [[Calendar#Ages|Ages]] are named for the greatest powers extant in the world. Ages commonly advance during world generation (e.g. Age of Legends, Age of Heroes, Age of Humans) due to the death of megabeasts, and they sometimes even regress due to the creation of [[night creature]]s and the birth of new [[megabeast]]s. When you choose to look at the history of an [[Calendar#Ages|Age]], you will be given a list of all historical events in chronological order. Here you can read the battle reports from various wars, or the duels that took place between long dead champions, or the <s>burninations</s> rampages of [[megabeast]]s amongst the [[peasant]]s. See [[Calendar#Ages|here]] for a list of ages and their conditions.

==Exporting information from Legends Mode==

Legends mode has built-in tools to export lists of events, maps at various scales, and data such as locations of sites. This is particularly useful as input data for the utilities described below; there are even tools to make this export process easier.

=== XML dump ===

Once you've generated a world, you can dump much of the historical data into an XML file for external analysis. The XML dump currently doesn't include every detail of world history but it contains many of the important ones. Be warned that a large world with a thousand years of history can produce an XML dump up to a full gigabyte in size, which may prove unwieldy. Press {{k|x}} while in Legends mode to produce an XML dump (it will be placed in the root ''Dwarf Fortress'' directory and named the same as your game's save folder) See [[Main:XML dump|XML dump]] for information on the XML file's format.

=== Export Map/Gen Information===
Another option is to export the map/gen information by pressing {{k|p}} in Legends mode. This produces three .txt files and one bitmap image that are placed in the root directory of ''Dwarf Fortress''. The exported data files are named by the save file name, and the current world date:
# (save name)-world_gen_param.txt - contains the world generation settings.
# [[World History file|(save name)-(year)-(month)-(day)-world_history.txt]] - Includes some information about the deities, and rulers of the Human, Dwarven, Elven, and Goblin civilizations.
# [[World Sites file|(save name)-(year)-(month)-(day)-world_sites_and_pops.txt]] - Lists the sites' population, owner, parent civilization and warlord. This one will also list all the animal populations above and below ground including demons.
# (save name)-(year)-(month)-(day)-world_map.bmp - This is the full world map as it is shown on the embark screen, and unlike the detailed maps below will depend on the tileset and colour scheme you have installed.

=== Export Detailed Maps ===
Pressing {{k|d}} in Legends mode reveals a list of the different kinds of map you can export. The images are exported to the game's root directory when you highlight the one you want and press {{k|Enter}}.

*'''Standard biome+site map (detailed map)
*[[Advanced_world_generation#Elevation|Elevations]] incl. lake and ocean floors
*[[Advanced_world_generation#Elevation|Elevations]] respecting water level
*[[Advanced_world_generation#Temperature|Temperature]]
*[[Advanced_world_generation#Rainfall|Rainfall]]
*[[Advanced_world_generation#Drainage|Drainage]]
*[[Advanced_world_generation#Savagery|Savagery]]
*[[Advanced_world_generation#Volcanism|Volcanism]]
*[[Vegetation|Current vegetation]]
*[[Evil]]
*[[Water|Salinity]]
* Diplomacy
* Hydrological map (rivers, streams, lakes, oceans)
* [[Noble|Nobility]]
* Cadaster (Structures, roads, ...)
* [[Trading|Trade]]

<gallery>
Image:Standard biome and site map.png|Biome & site map
Image:World_graphic-el-region5-203-10075.PNG|Elevation incl. lake and ocean floors
Image:World_graphic-elw-region5-203-10075.PNG|Elevation respecting water level
Image:World graphic-tmp-region5-203-10075.PNG|Temperature
Image:World_graphic-rain-region5-203-10075.PNG|Rainfall
Image:World_graphic-drn-region5-203-10075.PNG|Drainage
Image:World_graphic-sav-region5-203-10075.PNG|Savagery
Image:World_graphic-vol-region5-203-10075.PNG|Volcanism
Image:World_graphic-veg-region5-203-10075.PNG|Current vegetation
Image:World_graphic-evil-region5-203-10075.PNG|Evil
Image:World_graphic-sal-region5-203-10075.PNG|Salinity
</gallery>

==Legends Utilities==

There are many [[utilities]] that work with the data exported from Legends mode, or make exporting that info easier.

===Export tools===

[http://dffd.wimbli.com/file.php?id=7696 The dfhack script 'exportmaps'] will export all detailed maps, saving a lot of time on large worlds compared to exporting them individually and waiting for each to finish. [https://github.com/PeridexisErrant/dfhack/blob/master/scripts/exportlegends.lua exportlegends] likewise exports all detailed maps, as well as their worldgen info and legends XML.

[http://www.bay12forums.com/smf/index.php?topic=131307 Export processing script] can automate processing of Legends information, and is included in the Windows [[Utility:Lazy_Newb_Pack|Lazy Newb Pack]]. If GIMP is installed, the script will use Dwarf Map Maker (see below); optipng can be used to compress the images from bitmaps to .png files. This tool also removes non-printing ASCII characters from the XML dump that can crash Legends Viewer (usually caused by DFHack's workflow), and creates a compressed folder for each region suitable for Legends Viewer (or simply compresses the XML if some parts have not been exported).

===Legends viewing tools and visualisers===

The most famous is likely [[Utilities#Legends_Viewer|Legends Viewer]], an alternative interface that recreates legends mode from exported data with many more features such as graphs, filtering, sorting, and hyperlinks. There are alternative tools with similar functionality, including [[DF2014:Utilities#World_Viewer|World Viewer]].

[http://www.bay12forums.com/smf/index.php?topic=73095.msg2261106#msg2261106 The Dwarf Map Maker] is available as a GIMP script (free software) or a photoshop actionscript. Both use the detailed maps to produce a pretty fantasy map that looks somewhat like a satellite image. The GIMP script is called as part of PeridexisErrant's legends processing script, if the dependencies are present.

{{Translation| dwarven = gomath | elvish = liceva | goblin = olzul | human = en}}

{{Category|Guides}}
[[ru:Legends]]

Ages

2020-06-16T01:25:37Z

Ralpha: Adding link to Ages

#REDIRECT [[cv:Calendar#Ages]]

Bay 12 Forums

2020-06-07T14:01:57Z

Ralpha: Fixed broken links

The '''[http://www.bay12forums.com/smf/index.php Bay 12 Games Forums]''' are the main hub of fan-based activity and discussion surrounding the game. Users can ask questions about game play, exchange stories of their exploits, advertise their own contributions (mods, tools, pregenerated worlds), make suggestions for improvements, or discuss the game in a more general fashion. [[Toady One]] is known to read the forums and occasionally respond to posts when he sees fit. In the past [[bugs]] were also reported here, but they have since been moved into the domain of the [http://www.bay12games.com/dwarves/mantisbt/my_view_page.php Bug Tracker], although workarounds and such are still discussed on the wiki.

== Subforums ==
=== Bay 12 Games ===
*'''[http://www.bay12forums.com/smf/index.php?board=8.0 Announcements]''': This is where Toady One posts general announcements, mostly the Bay 12 Games Report, a monthly report on the status of the game's development. It is read-only.

=== Dwarf Fortress ===
*'''[http://www.bay12forums.com/smf/index.php?board=10.0 DF Announcements]''': This is where announcements on Dwarf Fortress specifically are made, usually specifying new release. As a matter of procedure, the most recent announcement thread is open to fans, but the rest are locked.
*'''[http://www.bay12forums.com/smf/index.php?board=6.0 DF Bug Reports]''': This used to be where bugs were reported, before the [http://www.bay12games.com/dwarves/mantisbt/my_view_page.php Bug Tracker] was created. New threads cannot be created, but old ones are still live, and occasional necromancy is common.
*'''[http://www.bay12forums.com/smf/index.php?board=5.0 DF Suggestions]''': Where suggestions on the game are made, and players can freely discuss ways of how the game could be improved. Any suggestions are welcome, ranging from minor changes to the display up to major additions like magic systems. While [[Toady One]] is known to visit this forum, non-trivial suggestions are very rarely implemented into the game. Vote counting will not win him over either.
*'''[http://www.bay12forums.com/smf/index.php?board=7.0 DF Gameplay Questions]''': This is the place where you can go if you encounter something you do not understand, which neither looks like a [[bug]] nor is explained sufficiently in the wiki. Questions about specific game mechanisms are common, but people also often ask for advice about how to implement certain ideas or features here. Topics range in complexity from "how do I start a farm?" to "is it possible to use perpetual motion to your advantage outside of power generation?"
*'''[http://www.bay12forums.com/smf/index.php?board=22.0 DF Wiki Discussion]''': A subforum of the above, this is where the wiki (you're looking at it) is discussed. Grounds for discussion is rather more niche than the other forums, so activity is low, but the wiki admins and contributors do watch it.
*'''[http://www.bay12forums.com/forum/index.php?board=11.0 DF Dwarf Mode Discussion]''' is especially dedicated to discussions about [[dwarf fortress mode]]. This forum usually contains discussions about either ideas for ways to play in [[fortress mode]] or experiences with [[fortress mode]]. The content therein ranges from anecdotal to inspirational - it is a place of humor, revelry, fun, and occasional !!SCIENCE!! alike.
*'''[http://www.bay12forums.com/smf/index.php?board=12.0 DF Adventure Mode Discussion]''' is the counterpart to the previously described forum. It is dedicated to discussions about [[adventurer mode]]. Like its [[fortress mode]] counterpart, this forum ranges from ideas to anecdotes as people describe both their experiences as well as their ideas for [[adventurer mode]] playing.
*'''[http://www.bay12forums.com/smf/index.php?board=14.0 DF Community Games & Stories]''', dedicated to discussions about community games and stories. In this forum, fans can advertise their community games, succession games, and the like and also handle the actually post exchange that is required for organizing such events. And they also exchange the stories of what happens in the game. Please note that, like the other forums, this forum does not offer upload facilities.
*'''[http://www.bay12forums.com/smf/index.php?board=13.0 DF Modding]''' is dedicated to discussions about [[modding]]. Fans use it to advertise their mods, exchange experiences with the modding process, and also ask and answer questions about how to mod the game successfully. It has multiple subforums as well.
*'''[http://www.bay12forums.com/smf/index.php?board=2.0 DF General Discussion]''' is the catch for all forum for dwarf fortress. Any discussions that do not fit nicely in any of the other DF forums go here. Topics here range from random ranting only loosely related to the game, over dwarf fortress' public image, fanart exchanges, general thoughts on the game, [[Toady One]], and the developments surrounding both. A noteworthy special feature is the '''Future of the Fortress''' threads started by [[Toady One]] as a community Q&A meant to discuss future development. This is the main source of dev news, alongside the dev notes.

=== Other Projects ===
*'''[http://www.bay12forums.com/smf/index.php?board=1.0 Slaves to Armok: God of Blood]''' is the very first forum from the site and is dedicated to discussions concerning the predecessor of dwarf fortress. It was locked in 2010, but looking through it you can find some 2001-era Toady One commentary.
*'''[http://www.bay12forums.com/smf/index.php?board=3.0 Curses]''' is dedicated to discussions about other ASCII based games by Bay 12 Games.
*'''[http://www.bay12forums.com/smf/index.php?board=4.0 Other Games]''': Ever wish you could discuss your thoughts on games with probably the most eclectic gaming community of them all? Well, now you can!
*'''[http://www.bay12forums.com/smf/index.php?board=21.0 Play With Your Buddies]''': Just what it sounds like, LPs and the like. Subforum of Other Games.

=== Finally ===
*'''[http://www.bay12forums.com/smf/index.php?board=16.0 Creative Projects]''': Visual arts, music, writing, and anything else you are working on that you'd like to share.
*'''[http://www.bay12forums.com/smf/index.php?board=17.0 General Discussion]''': Discussions, commentary, reviews, news, friendly debates. All thoughts welcome.
*'''[http://www.bay12forums.com/smf/index.php?board=18.0 Life Advice]''': Please do not solicit medical or legal advice from the Internet.
*'''[http://www.bay12forums.com/smf/index.php?board=15.0 Forum Games and Roleplaying]''': You can participate in the only multiplayer games B12 is likely to have anything to do with here. Feel free to start one of your own. Has Roll to Dodge and Mafia sub-boards.

== Rules and suggestions ==
The forum rules have been more or less {{f|38443.msg642398#msg642398|laid out}} in this thread.

Some suggestions:

;Use the Search Function
The forums offer a search function (look in the upper right corner). The forums see a lot of activity day by day and thus chances are great that someone already asked the same question before or made a similar suggestion previously.

Please note that the search function offers searching a single forum or all forums, defaulting to the forum from where you visited the search function. There may be cases where people posted in an unexpected forum, so you might wish to search in all forums the issue you wish to discuss might fit in (for instance, questions about how to create certain structures in fortress mode could fit both in the ''DF Gameplay Questions'' or the ''DF Dwarf Mode Discussions'' subforums.

;Support Existing Threads
Instead of starting new threads, consider participating in threads already dealing with the issue. This is especially an important issue for suggestions as some of the obvious ones tend to resurface regularly.

[[Category:Community]]
[[Category:Guides]]
[[ru:Bay 12 Forums]]
{{unversioned}}

Bay 12 Forums

2020-06-07T14:01:24Z

Ralpha: Fixed broken links

The '''[http://www.bay12forums.com/smf/index.php Bay 12 Games Forums]''' are the main hub of fan-based activity and discussion surrounding the game. Users can ask questions about game play, exchange stories of their exploits, advertise their own contributions (mods, tools, pregenerated worlds), make suggestions for improvements, or discuss the game in a more general fashion. [[Toady One]] is known to read the forums and occasionally respond to posts when he sees fit. In the past [[bugs]] were also reported here, but they have since been moved into the domain of the [http://www.bay12games.com/dwarves/mantisbt/my_view_page.php Bug Tracker], although workarounds and such are still discussed on the wiki.

== Subforums ==
=== Bay 12 Games ===
*'''[http://www.bay12forums.com/smf/index.php?board=8.0 Announcements]''': This is where Toady One posts general announcements, mostly the Bay 12 Games Report, a monthly report on the status of the game's development. It is read-only.

=== Dwarf Fortress ===
*'''[http://www.bay12forums.com/smf/index.php?board=10.0 DF Announcements]''': This is where announcements on Dwarf Fortress specifically are made, usually specifying new release. As a matter of procedure, the most recent announcement thread is open to fans, but the rest are locked.
*'''[http://www.bay12forums.com/smf/index.php?board=6.0 DF Bug Reports]''': This used to be where bugs were reported, before the [http://www.bay12games.com/dwarves/mantisbt/my_view_page.php Bug Tracker] was created. New threads cannot be created, but old ones are still live, and occasional necromancy is common.
*'''[http://www.bay12forums.com/smf/index.php?board=5.0 DF Suggestions]''': Where suggestions on the game are made, and players can freely discuss ways of how the game could be improved. Any suggestions are welcome, ranging from minor changes to the display up to major additions like magic systems. While [[Toady One]] is known to visit this forum, non-trivial suggestions are very rarely implemented into the game. Vote counting will not win him over either.
*'''[http://www.bay12forums.com/smf/index.php?board=7.0 DF Gameplay Questions]''': This is the place where you can go if you encounter something you do not understand, which neither looks like a [[bug]] nor is explained sufficiently in the wiki. Questions about specific game mechanisms are common, but people also often ask for advice about how to implement certain ideas or features here. Topics range in complexity from "how do I start a farm?" to "is it possible to use perpetual motion to your advantage outside of power generation?"
*'''[http://www.bay12forums.com/smf/index.php?board=22.0 DF Wiki Discussion]''': A subforum of the above, this is where the wiki (you're looking at it) is discussed. Grounds for discussion is rather more niche than the other forums, so activity is low, but the wiki admins and contributors do watch it.
*'''[http://www.bay12forums.com/forum/index.php?board=11.0 DF Dwarf Mode Discussion]''' is especially dedicated to discussions about [[dwarf fortress mode]]. This forum usually contains discussions about either ideas for ways to play in [[fortress mode]] or experiences with [[fortress mode]]. The content therein ranges from anecdotal to inspirational - it is a place of humor, revelry, fun, and occasional !!SCIENCE!! alike.
*'''[http://www.bay12forums.com/smf/index.php?board=12.0 DF Adventure Mode Discussion]''' is the counterpart to the previously described forum. It is dedicated to discussions about [[adventurer mode]]. Like its [[fortress mode]] counterpart, this forum ranges from ideas to anecdotes as people describe both their experiences as well as their ideas for [[adventurer mode]] playing.
*'''[http://www.bay12forums.com/smf/index.php?board=14.0 DF Community Games & Stories]''', dedicated to discussions about community games and stories. In this forum, fans can advertise their community games, succession games, and the like and also handle the actually post exchange that is required for organizing such events. And they also exchange the stories of what happens in the game. Please note that, like the other forums, this forum does not offer upload facilities.
*'''[http://www.bay12forums.com/smf/index.php?board=13.0 DF Modding]''' is dedicated to discussions about [[modding]]. Fans use it to advertise their mods, exchange experiences with the modding process, and also ask and answer questions about how to mod the game successfully. It has multiple subforums as well.
*'''[http://www.bay12forums.com/smf/index.php?board=2.0 DF General Discussion]''' is the catch for all forum for dwarf fortress. Any discussions that do not fit nicely in any of the other DF forums go here. Topics here range from random ranting only loosely related to the game, over dwarf fortress' public image, fanart exchanges, general thoughts on the game, [[Toady One]], and the developments surrounding both. A noteworthy special feature is the '''Future of the Fortress''' threads started by [[Toady One]] as a community Q&A meant to discuss future development. This is the main source of dev news, alongside the dev notes.

=== Other Projects ===
*'''[http://www.bay12forums.com/smf/index.php?board=1.0 Slaves to Armok: God of Blood]''' is the very first forum from the site and is dedicated to discussions concerning the predecessor of dwarf fortress. It was locked in 2010, but looking through it you can find some 2001-era Toady One commentary.
*'''[http://www.bay12games.com/forum/index.php?board=3.0 Curses]''' is dedicated to discussions about other ASCII based games by Bay 12 Games.
*'''[http://www.bay12forums.com/smf/index.php?board=4.0 Other Games]''': Ever wish you could discuss your thoughts on games with probably the most eclectic gaming community of them all? Well, now you can!
*'''[http://www.bay12forums.com/smf/index.php?board=21.0 Play With Your Buddies]''': Just what it sounds like, LPs and the like. Subforum of Other Games.

=== Finally ===
*'''[http://www.bay12forums.com/smf/index.php?board=16.0 Creative Projects]''': Visual arts, music, writing, and anything else you are working on that you'd like to share.
*'''[http://www.bay12forums.com/smf/index.php?board=17.0 General Discussion]''': Discussions, commentary, reviews, news, friendly debates. All thoughts welcome.
*'''[http://www.bay12forums.com/smf/index.php?board=18.0 Life Advice]''': Please do not solicit medical or legal advice from the Internet.
*'''[http://www.bay12forums.com/smf/index.php?board=15.0 Forum Games and Roleplaying]''': You can participate in the only multiplayer games B12 is likely to have anything to do with here. Feel free to start one of your own. Has Roll to Dodge and Mafia sub-boards.

== Rules and suggestions ==
The forum rules have been more or less {{f|38443.msg642398#msg642398|laid out}} in this thread.

Some suggestions:

;Use the Search Function
The forums offer a search function (look in the upper right corner). The forums see a lot of activity day by day and thus chances are great that someone already asked the same question before or made a similar suggestion previously.

Please note that the search function offers searching a single forum or all forums, defaulting to the forum from where you visited the search function. There may be cases where people posted in an unexpected forum, so you might wish to search in all forums the issue you wish to discuss might fit in (for instance, questions about how to create certain structures in fortress mode could fit both in the ''DF Gameplay Questions'' or the ''DF Dwarf Mode Discussions'' subforums.

;Support Existing Threads
Instead of starting new threads, consider participating in threads already dealing with the issue. This is especially an important issue for suggestions as some of the obvious ones tend to resurface regularly.

[[Category:Community]]
[[Category:Guides]]
[[ru:Bay 12 Forums]]
{{unversioned}}

Bay 12 Forums

2020-06-07T14:00:46Z

Ralpha: Fixed broken links

The '''[http://www.bay12forums.com/smf/index.php Bay 12 Games Forums]''' are the main hub of fan-based activity and discussion surrounding the game. Users can ask questions about game play, exchange stories of their exploits, advertise their own contributions (mods, tools, pregenerated worlds), make suggestions for improvements, or discuss the game in a more general fashion. [[Toady One]] is known to read the forums and occasionally respond to posts when he sees fit. In the past [[bugs]] were also reported here, but they have since been moved into the domain of the [http://www.bay12games.com/dwarves/mantisbt/my_view_page.php Bug Tracker], although workarounds and such are still discussed on the wiki.

== Subforums ==
=== Bay 12 Games ===
*'''[http://www.bay12games.com/forum/index.php?board=8.0 Announcements]''': This is where Toady One posts general announcements, mostly the Bay 12 Games Report, a monthly report on the status of the game's development. It is read-only.

=== Dwarf Fortress ===
*'''[http://www.bay12forums.com/smf/index.php?board=10.0 DF Announcements]''': This is where announcements on Dwarf Fortress specifically are made, usually specifying new release. As a matter of procedure, the most recent announcement thread is open to fans, but the rest are locked.
*'''[http://www.bay12forums.com/smf/index.php?board=6.0 DF Bug Reports]''': This used to be where bugs were reported, before the [http://www.bay12games.com/dwarves/mantisbt/my_view_page.php Bug Tracker] was created. New threads cannot be created, but old ones are still live, and occasional necromancy is common.
*'''[http://www.bay12forums.com/smf/index.php?board=5.0 DF Suggestions]''': Where suggestions on the game are made, and players can freely discuss ways of how the game could be improved. Any suggestions are welcome, ranging from minor changes to the display up to major additions like magic systems. While [[Toady One]] is known to visit this forum, non-trivial suggestions are very rarely implemented into the game. Vote counting will not win him over either.
*'''[http://www.bay12forums.com/smf/index.php?board=7.0 DF Gameplay Questions]''': This is the place where you can go if you encounter something you do not understand, which neither looks like a [[bug]] nor is explained sufficiently in the wiki. Questions about specific game mechanisms are common, but people also often ask for advice about how to implement certain ideas or features here. Topics range in complexity from "how do I start a farm?" to "is it possible to use perpetual motion to your advantage outside of power generation?"
*'''[http://www.bay12forums.com/smf/index.php?board=22.0 DF Wiki Discussion]''': A subforum of the above, this is where the wiki (you're looking at it) is discussed. Grounds for discussion is rather more niche than the other forums, so activity is low, but the wiki admins and contributors do watch it.
*'''[http://www.bay12forums.com/forum/index.php?board=11.0 DF Dwarf Mode Discussion]''' is especially dedicated to discussions about [[dwarf fortress mode]]. This forum usually contains discussions about either ideas for ways to play in [[fortress mode]] or experiences with [[fortress mode]]. The content therein ranges from anecdotal to inspirational - it is a place of humor, revelry, fun, and occasional !!SCIENCE!! alike.
*'''[http://www.bay12forums.com/smf/index.php?board=12.0 DF Adventure Mode Discussion]''' is the counterpart to the previously described forum. It is dedicated to discussions about [[adventurer mode]]. Like its [[fortress mode]] counterpart, this forum ranges from ideas to anecdotes as people describe both their experiences as well as their ideas for [[adventurer mode]] playing.
*'''[http://www.bay12forums.com/smf/index.php?board=14.0 DF Community Games & Stories]''', dedicated to discussions about community games and stories. In this forum, fans can advertise their community games, succession games, and the like and also handle the actually post exchange that is required for organizing such events. And they also exchange the stories of what happens in the game. Please note that, like the other forums, this forum does not offer upload facilities.
*'''[http://www.bay12forums.com/smf/index.php?board=13.0 DF Modding]''' is dedicated to discussions about [[modding]]. Fans use it to advertise their mods, exchange experiences with the modding process, and also ask and answer questions about how to mod the game successfully. It has multiple subforums as well.
*'''[http://www.bay12forums.com/smf/index.php?board=2.0 DF General Discussion]''' is the catch for all forum for dwarf fortress. Any discussions that do not fit nicely in any of the other DF forums go here. Topics here range from random ranting only loosely related to the game, over dwarf fortress' public image, fanart exchanges, general thoughts on the game, [[Toady One]], and the developments surrounding both. A noteworthy special feature is the '''Future of the Fortress''' threads started by [[Toady One]] as a community Q&A meant to discuss future development. This is the main source of dev news, alongside the dev notes.

=== Other Projects ===
*'''[http://www.bay12forums.com/smf/index.php?board=1.0 Slaves to Armok: God of Blood]''' is the very first forum from the site and is dedicated to discussions concerning the predecessor of dwarf fortress. It was locked in 2010, but looking through it you can find some 2001-era Toady One commentary.
*'''[http://www.bay12games.com/forum/index.php?board=3.0 Curses]''' is dedicated to discussions about other ASCII based games by Bay 12 Games.
*'''[http://www.bay12forums.com/smf/index.php?board=4.0 Other Games]''': Ever wish you could discuss your thoughts on games with probably the most eclectic gaming community of them all? Well, now you can!
*'''[http://www.bay12forums.com/smf/index.php?board=21.0 Play With Your Buddies]''': Just what it sounds like, LPs and the like. Subforum of Other Games.

=== Finally ===
*'''[http://www.bay12forums.com/smf/index.php?board=16.0 Creative Projects]''': Visual arts, music, writing, and anything else you are working on that you'd like to share.
*'''[http://www.bay12forums.com/smf/index.php?board=17.0 General Discussion]''': Discussions, commentary, reviews, news, friendly debates. All thoughts welcome.
*'''[http://www.bay12forums.com/smf/index.php?board=18.0 Life Advice]''': Please do not solicit medical or legal advice from the Internet.
*'''[http://www.bay12forums.com/smf/index.php?board=15.0 Forum Games and Roleplaying]''': You can participate in the only multiplayer games B12 is likely to have anything to do with here. Feel free to start one of your own. Has Roll to Dodge and Mafia sub-boards.

== Rules and suggestions ==
The forum rules have been more or less {{f|38443.msg642398#msg642398|laid out}} in this thread.

Some suggestions:

;Use the Search Function
The forums offer a search function (look in the upper right corner). The forums see a lot of activity day by day and thus chances are great that someone already asked the same question before or made a similar suggestion previously.

Please note that the search function offers searching a single forum or all forums, defaulting to the forum from where you visited the search function. There may be cases where people posted in an unexpected forum, so you might wish to search in all forums the issue you wish to discuss might fit in (for instance, questions about how to create certain structures in fortress mode could fit both in the ''DF Gameplay Questions'' or the ''DF Dwarf Mode Discussions'' subforums.

;Support Existing Threads
Instead of starting new threads, consider participating in threads already dealing with the issue. This is especially an important issue for suggestions as some of the obvious ones tend to resurface regularly.

[[Category:Community]]
[[Category:Guides]]
[[ru:Bay 12 Forums]]
{{unversioned}}

Bow

2020-03-11T23:34:48Z

Ralpha: Added material clarification

{{Quality|Fine|18:25, 23 August 2014 (UTC)}}
{{av}}

:''For a comparison of different weapons, see [[Weapon]].''

A '''bow''' (not to be confused with a dwarven [[crossbow]]) is a ranged [[weapon]] that fires projectiles called [[arrow]]s. Bows behave similarly to crossbows for the most part, though they seem to be preferred by [[elf|elves]] and [[goblin]]s.

As ranged weapons, bows use and train the [[bowman]] (bowdwarf) skill; as melee weapons bows use and train the [[swordsman]] (swordsdwarf) skill instead. Dwarves cannot [[forge]] bows nor [[arrow]]s, limiting supply to artifacts, and whatever low-[[quality]] specimens can be traded from elven [[caravan]]s and scavenged from invaders. Due to their marked similarity to native weapons, your dwarves would likely be better served in battle with high-quality crossbows and bolts than inferior imported bows and arrows. All dwarves can equip bows.

Bows do not have to be made out of [[wood]]. They can, [[Weapon#Material|like all other weapons]], also me made out of metal.

==Bugs==
* If a [[squad]] is assigned multiple ammo types, dwarves with "individual choice ranged" may carry the wrong ammo{{bug|1374}}.

{{Translation
| dwarven = egdoth
| elvish = ramí
| goblin = uneg
| human = ethro
}}

{{gamedata|{{raw|DF2014:item_weapon.txt|ITEM_WEAPON|ITEM_WEAPON_BOW}}}}
{{Weapons}}
{{Category|Weapons}}

Troll

2020-03-08T19:44:50Z

Ralpha: Fixed category tag

{{Quality|Exceptional|01:51, 28 April 2013 (UTC)}}
{{Creaturelookup/0
|wiki=yes
}}
{{av}}
{{creaturedesc}}

'''Trolls''' are large, predatory, dangerous subterranean evil [[creature]]s who inhabit all layers of the [[caverns]] and often appear under the command of [[goblin]]s during [[siege]]s. Over four times larger than a [[dwarf]], they are [[building destroyer]]s, and will path to your [[building]]s simply for the joy of sheer destruction. During sieges, they act as battering rams, so [[trap design|design your defenses accordingly]]. They are not related to [[night troll]]s, despite the similar names.

Wild trolls meander the underground and attack dwarves who approach or provoke them (or at least are supposed to, but currently don't {{bug|10031}}). Many of them are enslaved/absorbed by goblins during world generation and become their servants, inhabiting their [[dark pit]]s in truly huge numbers (sometimes enough to cause overwhelming lag {{bug|7526}}) and aiding their smaller masters in their battles against other races. Goblins shear trolls for their fur, making them the evil race's equivalent of [[sheep]]. As they are intelligent (although incapable of speech), civilized trolls may gain non-military professions among goblin society.

Trolls will almost certainly appear accompanying goblins when they siege your fortress. They are quite tough and have a variety of different ways to cause injury to your dwarves due to their humanoid bodies and large tusks. Since they only rarely wear [[armor]] (when appearing as helpers of [[goblin christmas|Goblin Claus]]), they will be easy targets for a decently-skilled squad of axedwarves, though silk-wearing trolls can complicate things if [[copper]] and [[silver]] are the only available metals. Trolls can and will wrestle your dwarves, which can lead to some broken bones in your military. Unlike goblins, trolls are natural swimmers, which could be a problem for a fortress relying on a moat for defense, or using a drowning chamber or underground lake as a means of administering dwarven justice. Trolls can climb, so it is possible for them to get to level one of a cavern through [[deep pit]]s and access your fortress to <s>crush the heads of</s> play with your dwarves.

Trolls notably possess cyan-colored [[blood]] (possibly [[wikipedia:Hemocyanin|hemocyanin]]-based). Their behavior as a servant race of goblins is done via the combination of the {{token|EVIL}} and {{token|SLOW_LEARNER}} creature tokens and the fact they live underground; through modding, players can create their own subterranean goblin servants who will accompany trolls in battle by giving their race these two tokens.

Some dwarves [[Preferences|like]] trolls for their ''terrifying features''.

[[File:Troll Drawing.jpg|thumb|center|300px|A dwarf battling a troll, drawn in crayon by [[Main:Bay 12 Games|Bay 12 Games]].]]

{{gamedata}}
{{creatures}}
[[Category:DF2014:Shearable]]

DF2014:Graphics set repository

2020-02-25T16:09:12Z

Ralpha: Added the Meph tileset

{{Quality|Superior|10:59, 18 May 2015 (UTC)}}
{{av}}

{{For/see|user-created tilesets|[[Tileset repository]]}}

{{Mod}}

[[Graphics set]]s are used to change the appearance of [[Main:creature|creatures]] in the game. They usually come with certain [[DF2014:Tilesets|tilesets]] and are designed to work together. They can significantly change the appearance of the game and make it easier for players to tell what is happening onscreen. This page serves as a repository for custom graphic sets made by users.

==32×32 square graphics sets==

===Vettingr===
[[Image:vet_prev.png|thumb|right|Screenshot of game using the Vettlingr Graphics Pack]]
{{GraphicsSet
| image = [[Image:vet_intro.png|256px]]
| download link = [http://www.bay12forums.com/smf/index.php?topic=172078.0 Official Forum Thread] or [http://dffd.bay12games.com/file.php?id=14072]
| author = vettlingr
| sprite = 32×32
| resolution = 1920×600
| current version = 1.3
| df compatible = 0.44.12
| installation = Instructions at download site
| comments = Last updated: October 08, 2019. This is a Dwarf Fortress Tileset for 32x32. Featuring over 1000 unique sprites for most creatures, professions and job titles, as well as environments, furniture, items and more.

If you like your dwarves big-nosed and stunty, with a hint of Anglo-Saxon or Nordic design. Perhaps you like gothic horror or a darker style for your dwarven dungeon paired with a beautiful consistent design. Fret not, thy tileset pack is here!
}}

===Meph Tileset===

{{GraphicsSet

| download link = [http://www.bay12forums.com/smf/index.php?topic=161047.0 Official Forum Thread], [http://dffd.bay12games.com/file.php?id=13407 for windows] or [http://dffd.bay12games.com/file.php?id=12516 for linux (Raws/Graphics only)]
| author = Meph
| sprite = 32×32
| resolution = Variable
| current version = 5.3
| df compatible = 0.44.12
| installation = Instructions at download site
| comments = Last updated: September 10, 2019. The Meph tileset is the first graphical 32x32 tileset for Dwarf Fortress. It was born from my research about tilesets, finding old, abandoned 24x and 32x sprites by Dibujor and Obsidian Soul, both inactive since 2015. I thought that their sprites are too good to waste and started with them as a basis for a new tileset.

The Meph tileset uses Dfhack and TWBT.
}}

==24×24 square graphics sets==

===GemSet===
[[Image:Gemsetgameplay.png|thumb|right|Screenshot of game using the Gemset Graphics Pack]]
{{GraphicsSet
| image = [[Image:Gemset_Logo.png|256px]]
| download link = [http://www.bay12forums.com/smf/index.php?topic=150753.0] or [http://dffd.bay12games.com/file.php?id=10857]
| author = DragonDePlatino
| sprite = 24×24 / 48×48
| resolution = 1920×600
| current version = 1.3 ɑ4
| df compatible = 0.42.04
| installation = Instructions at download site
| comments = Last updated: May 17, 2015. The DFgraphics github version is currently the only one actively maintained.
The first complete 24×24 graphics set for Dwarf Fortress, GemSet provides the aesthetics of ASCII and convenience of graphics.

Drawn natively in a 24×24 resolution for 1080p and 4K displays, GemSet is the highest-resolution graphics set to-date. The entire graphics set uses a bright 32-color palette with the intention of keeping everything crystal-clear on even the highest-resolution displays. All profession graphics are color-coded according to their ASCII counterparts and black has been kept as the dominant color of the graphics set.

All creature graphics are finished and TWBT support is currently in-development.
}}

===Dungeon Set===
[[Image:Dungeonsetgameplay.jpeg|thumb|right|Screenshot of game using the Dungeon Set Graphics Pack]]
{{GraphicsSet
| image = [[Image:Dungeonsetlogo.png|256px]]
| download link = [http://www.bay12forums.com/smf/index.php?topic=152766.msg6467509 Official Forum Thread]
| author = utkonos
| sprite = 24×24
| resolution = 1920×600
| current version = 1.03
| df compatible = 0.43.03
| installation = Instructions at download site
| comments = Last updated: June 28, 2016.
A TWBT compatible graphics set drawn in a realistic style.
}}

==18×18 square graphics sets==

===CLA's ASCII-like Graphics Set===
[[Image:Zscrn-cla.jpg|thumb|right|Screenshot of game using CLA's ASCII-like Graphics Set]]
{{GraphicsSet
| image = [[Image:ZwymD.png|256px]]
| download link = [http://www.bay12forums.com/smf/index.php?topic=105376.0 Official Forum Thread], [https://github.com/DFgraphics/CLA/releases Github]
| author = CLA
| sprite = 18×18
| resolution = 1440×450
| current version = 26
| df compatible = 0.44.12
| installation = Available pre-installed or as a patch
| comments = Last updated: April 15, 2019
ASCII-Like, uses stylized letters to show what the creature is while still allowing it to look like the letter. Tileset based on [[DF2014:Tileset_repository#18.C3.9718|Haowan]] with opaque ground tiles
}}

===Ironhand and Wormslayer's Graphics Pack===
[[Image:Zscrn-ironhand.jpg|thumb|right|Screenshot of game using Ironhand and Wormslayer's Graphics Pack]]
{{GraphicsSet
| image = [[Image:Ironhandtileset.png|256px]]
| download link = [http://www.bay12forums.com/smf/index.php?topic=53180.0 Official Forum Thread] (and [http://dffd.bay12games.com/file.php?id=13283 DFFD for v0.44]), [https://github.com/DFgraphics/Ironhand/releases Github]
| author = Ironhand and Wormslayer
| sprite = 18×18 / [http://www.bay12forums.com/smf/index.php?topic=122400.0 unofficial 16×16 version (Ironhand16 for 0.40.09)]
| resolution = 1440×450
| current version = 0.68
| df compatible = 0.44.12
| installation = Available pre-installed or as a patch
| comments = Last updated: June 24, 2018.
}}

==16×16 square graphics sets==

===Beefmo 2012===
{{GraphicsSet
| download link = [http://dffd.wimbli.com/file.php?id=2087 Beefmo 2012 page on DFFD]
| author = Beefmo and Thirin
| sprite = 16×16
| resolution = 1024×768 or higher
| current version = 0.54
| df compatible = 0.34.11
| installation = Instructions at download site
| comments = Last updated: Dec 26, 2012. No longer maintained.
Exhaustive collection of sprites for all civilized races (dwarves, elves, goblins, humans, and kobolds) including unique images for each profession within each race, as well as zombie, skeleton, and ghost forms. There is also a huge gallery of creatures including livestock, wildlife, and cavern fauna. Many of the animals are collected from other sets and modified to fit, plus many unique to this tile set -- as such it is one of the most comprehensive collections of creature graphics available. Most of the new 2012 animals and animal-men are present, though some are still TBD. The art style is clear and consistent with clean lines and solid colors; classic pixel art. There is also a version available patched onto Obsidian and ready to be used with LNP. This version can be found [http://dffd.wimbli.com/file.php?id=8624 here].
}}

===Geoduck's 16×16 Graphics Set===
[[File:Zscr-geoduck.jpg|thumb|right|Screenshot of game using Geoduck's Graphics Set and Shizzle's ASCII tileset]]
{{GraphicsSet
| image = [[Image:Geoduck logo.png|256px]]
| download link = [http://www.geoduckthings.net/dwarf/dwarffortress16.html Geoduck's Dwarf Fortress 16x16 page]
| author = Geoduck
| sprite = 16×16
| resolution = 1024×768 or higher
| current version = 2.0
| df compatible = 0.43.03
| installation = Instructions at download site
| comments = Last updated: May 29, 2016
Set for Dwaves/Goblins/Humans/Elves/Kobolds which attempts to combine compactness with greater simplicity, clarity and ease of viewing. Designed for Fortress mode play, but includes Adventurer tiles. Created from scratch, but originally inspired in part by PTTG's graphics set for .40d.
}}

===Rally Ho! Graphics Set===
{{GraphicsSet
| image = [[Image:Rallyhologo.png|256px]]
| download link = [http://www.bay12forums.com/smf/index.php?topic=149172.0 Rydel's Forum Thread], [https://github.com/DFgraphics/Rally-Ho/releases Github]
| author = Rydel
| sprite = 16×16
| resolution = 1024×768 or higher
| current version = 2.0
| df compatible = 0.43.05
| installation = Instructions in readme
| comments = Last updated: March 27, 2017. The DFgraphics github version is currently the only one actively maintained.
Rally Ho! is a 16×16 graphics set for Dwarf Fortress 2016 (43.04-43.05) based on graphics from the Final Fantasy series of video games, especially the NES, SNES, GB, and GBA games.
}}

===Mayday's Graphic Set===
[[Image:Zscrn-mayday.jpg|thumb|right|Screenshot of game using Mayday's Graphic Set]]
{{GraphicsSet
| image = [[Image:DFG13.png|256px]]
| download link = [http://mayday.w.staszic.waw.pl/df.php Mayday's site] or [https://github.com/DFgraphics/Mayday/releases GitHub]
| author = [[User:Mikemayday|Mikemayday]]
| sprite = 16×16
| resolution = 1280 horizontal
| current version = 40_05
| df compatible = 0.40.05
| installation = [http://mayday.w.staszic.waw.pl/df.php Available as a pre-installed copy].
| comments = Last updated: 28 July 2014. The DFgraphics github version is currently the only one actively maintained.
Combined with a customized main tileset. Credits go to Beefmo, Sphr, DR, Tocky, Herrbdog, Bane18, Dragon Warrior games and me (although I did much more organizing and editing than actually creating).

There's an [https://github.com/rofl0r/df-mayday inofficial patch] that supports 0.43.05 (the non-graphic related parts of the original mayday (key bindings, embark profile) have been sacrified to make forward ports easier).
}}

===Obsidian Graphics Set===
[[Image:Zscrn-obsidian.jpg|thumb|right|Screenshot of game using the Obsidian Graphics Set]]
{{GraphicsSet
| image = [[Image:Obsidian Graphics Set.png|256px]]
| download link = [http://www.bay12forums.com/smf/index.php?topic=126934.msg4302701#msg4302701 Official Forum Page] or [https://github.com/DFgraphics/Obsidian/releases GitHub]
| author = [[User:Obsidian Soul|Obsidian Soul]]
| sprite = 16×16
| resolution = 1024×768 or higher
| current version = 0.8
| df compatible = 0.34.11 (unofficial DF2014 update available, see description)
| installation = Instructions at download site
| comments = Last updated: July 24, 2013. The DFgraphics github version is currently the only one actively maintained. '''[https://dwarffortresswiki.org/index.php/File:Obsidian_spritesheet_v1.png Click here for a full sprite sheet!]'''
A graphics set that focuses on consistency and stylized realism to harmonize the different tiles and give a more "medieval" atmosphere to the game. Unlike other tilesets, this also specifically sets aside different tiles for grass with modifications to their graphics raws. This makes it easier to distinguish pasturable areas from bare rock and sand, tell apart different biomes, as well as letting you plan green (or blue, if you're going with cave moss) gardens along your entrance halls. Just make sure to forbid traffic on it to avoid trampling them to bare ground.

Unofficial updates for DF2014 are bundled with PeridexisErrant's [http://www.bay12forums.com/smf/index.php?topic=126076 DF Starter Pack] for Windows, fricy's [http://www.bay12forums.com/smf/index.php?topic=128960 MacNewbie Pack] for Mac, and Beautato's [http://www.bay12forums.com/smf/index.php?topic=140966.0 Linux Lazy Newb Pack] for Linux.
}}

===Phoebus' Graphics Set===
[[Image:Zscrn-phoebus.jpg|thumb|right|Screenshot of game using Phoebus' Graphics Pack]]
{{GraphicsSet
| image = [[Image:Phoebus_16x16.png|256px]]
| forum thread = [http://www.bay12forums.com/smf/index.php?topic=137096.0 Official Forum Thread] or [https://github.com/DFgraphics/Phoebus/releases GitHub]
| download link = [https://github.com/DFgraphics/Phoebus GitHub repository]
| author = Phoebus
| sprite = 16×16
| resolution = 1280×400
| current version = 0.44.06
| installation = Available pre-installed or as a patch
| comments = Phoebus quit supporting it but community tries to keep it up to date, see github repo
}}

===Spacefox Graphics Set===
[[Image:Spacefoxscr.png|thumb|right|Screenshot of game using the Spacefox Graphics Set]]
{{GraphicsSet
| image = [[Image:Spacefox-preview.png|256px]]
| download link = [https://github.com/DFgraphics/Spacefox GitHub repository]
| author = Spacefox
| sprite = 16×16
| resolution = 1280×400
| current version = 43.05e
| df compatible = 0.43.05
| installation = Instructions at download site
A tile and graphic set created with a simple, clean look as a goal. Inspired by Jolly Bastion and referenced from tile sets that have come before. This graphic and tileset is still very much a WIP. It should be completely playable as it is based off Phoebus' Tileset and comes with all of it's graphical assets.
}}

===Tergel Graphics Set===
{{GraphicsSet
| image = [[Image:Tergellogo.png|256px]]
| download link = [http://www.bay12forums.com/smf/index.php?topic=145802.0 Forum thread], [https://github.com/DFgraphics/Tergel Github]
| author = CowThing
| sprite = 12×12 or 16×16
| resolution = 1024×768
| current version = 5.0
| df compatible = 0.44.05
| installation = Instructions at download site
| comments = Last updated: Dec 22, 2017. The DFgraphics github version is currently the only one actively maintained.
Tergel is an ASCII tileset combined with simple pixel art. CowThing wanted to enhance the ASCII feel, while keeping the game readable, and give the game a happier feel. This tileset was derived from Simple Mood by Rogue Yun. Also inspired by Taffer, Jolly Bastion, Quale's "scroll-o-sprites", and many others.
}}

==15×15 square graphics sets==

===Duerer 15×15 Graphics Set===
[[File:Duererscreenshot.png|thumb|right|Screenshot of game using the Duerer graphics set.]]
{{GraphicsSet
| image = [[Image:Duererlogo.png|256px]]
| download link = [http://www.bay12forums.com/smf/?topic=142083.0 Forum thread]
| author = HaterSkater
| sprite = 15×15
| resolution = 1280×400
| current version = 0.6.A
| df compatible = 0.42.02
| installation = Instructions at download site
| comments = Last updated: December 6, 2015. No longer maintained.
That's it. Engraved Dwarf Fortress.
The idea of this set arose after a series of experiments including noise application to other tilesets, and, in other hand, after 4 year study of art history. Resulting tileset looks like hand drawn graphics and engravings made in XV-XVI century or maps of same epoch.
}}

==12×12 square graphics sets==

===Geoduck's 12×12 Graphics Set===
[[File:Zscr-geoduck.jpg|thumb|right|Screenshot of game using Geoduck's Graphics Set and Shizzle's ASCII tileset]]
{{GraphicsSet
| image = [[Image:Geoduck12x12dwarfsample2.png|256px]]
| download link = [http://www.geoduckthings.net/dwarf/dwarffortress.html Geoduck's 12x12 Dwarf Fortress page]
| author = Geoduck
| sprite = 12×12
| resolution = 1024×768
| current version = 3.0
| df compatible = 0.34.11
| installation = Instructions at download site
| comments = Last updated: May 22, 2013
Set for Dwaves/Goblins/Humans/Elves/Kobolds which attempts to combine the compactness of 12×12 tiles with greater simplicity, clarity and ease of viewing. Designed for Fortress mode play, but includes Adventurer tiles. Created from scratch, but inspired in part by PTTG's graphics set for .40d. Goblin design taken from Dwarf Fortress Forum game-image.
}}

==10×10 square graphics sets==

===Taffer's Tilesets & Graphics===
[[File:Zscr-taffer.jpg|thumb|right|Screenshot of game using Taffer's Tileset & Graphics]]
{{GraphicsSet
| image = [[Image:Taffergraphics.png|250px]]
| download link = [https://github.com/DFgraphics/Taffer/releases Github]
| author = Taffer
| sprite = 10×10, 20×20
| resolution = Any
| current version = 4.8
| df compatible = 0.43.05
| installation = Unzip over DF install
| comments = Last updated: January 10, 2017
Sharp looking, vanilla styled tilesets that strive to strike a good balance between nice, attractive graphics, while avoiding odd graphical oddities. I have positioned many tiles carefully and put a lot of thought into each one, often obsessively so. I find the cumulative differences from the ASCII add quite a bit to the game. I'm a bit of a perfectionist and the update log attests to that, but the result is pleasing and well-polished. Alternate walls are included, as is the color set and racial graphics for dwarves, humans, elves, goblins, and kobolds.
}}

==16×24 non-square graphics sets==

===Anon's Tileset and Creature Graphics===
[[Image:Anontileset_screen2.PNG|100px|thumb|right|Screenshot of a worldgen fortress, as seen using Anon's Tileset and Creature Graphics.]]
{{GraphicsSet
| image = [[Image:Anontileset_screen1.PNG]]
| download link = [http://dffd.bay12games.com/file.php?id=12544]
| author = TilesetAnon
| sprite = 16×24
| current version = 1.01
| df compatible = 0.43.05
| installation = Available as a patch
| comments = Last updated: July 10, 2017
A clean and simple tileset with creature graphics, intended to give a comfy NES-era RPG feel.
}}

{{Category|Mods}}
{{Category|Interface}}
{{Category|Graphics}}