Dwarf Fortress Wiki - User contributions [en]

Dipscript

2022-12-21T00:30:39Z

Trainzack: Already updated pre-migrated article tag.

{{av}}
{{removed feature}}

A '''dipscript''', or "diplomat script", is what controlled the behavior of visiting [[diplomat]]s when they met with your [[noble]]s in previous versions of Dwarf Fortress. As of 50.01, this functionality has been embedded in the executable and is no longer user-modifiable.

For how dipscripts were structured in previous versions of the game, see [[DF2014:Dipscript]].

{{Category|Files}}
{{Category|Modding}}
[[ru:Dipscript]]

Talk:Speech file

2022-12-20T07:06:29Z

Trainzack: Created page with "== 50.01 Revisions == This page should probably be moved with the other token pages, since the new version replaces the old system with TEXT_SET objects. ~~~~"

== 50.01 Revisions ==

This page should probably be moved with the other token pages, since the new version replaces the old system with TEXT_SET objects. [[User:Trainzack|Trainzack]] ([[User talk:Trainzack|talk]]) 07:06, 20 December 2022 (UTC)

Speech file

2022-12-20T07:05:15Z

Trainzack: Updated some information for 50.01, though there is more work to be done.

'''Speech files''' are text files that define sentences which can be spoken by people in [[adventure mode]] and phrases used to name [[books]]. Most of them are found in the <code>data/vanilla/vanilla_text/objects</code> folder, though the creature specific files can be found in <code>data/vanilla/vanilla_creatures/objects</code>. Like other raw files, mods can replace or introduce new sentences.

== List of files ==

{| class="wikitable"
! File !! Uses !! Example
|-
| {{text anchor|text_ab_specific_hf_seeker}}
|
| seek out [CONTEXT:HIST_FIG:TRANS_NAME] at [CONTEXT:ABSTRACT_BUILDING:TRANS_NAME] over in [CONTEXT:SITE:TRANS_NAME]

|-
| {{text anchor|text_animal_slayer}}
|
| I have taken down [CONTEXT:NUMBER] [CONTEXT:RACE:NUMBERED_NAME] while stalking [CONTEXT:PLACE:TRANS_NAME].

|-
| {{text anchor|text_arch_info_justification}}
|
| It is said that the [CONTEXT:ARCH_ELEMENT] of [CONTEXT:ABSTRACT_BUILDING:TRANS_NAME] [CONTEXT:JUSTIFICATION] [CONTEXT:DEF_SPHERE] for the glory of [CONTEXT:HIST_FIG:TRANS_NAME].

|-
| {{text anchor|text_book_art}}
| Used when naming books.
| And [ANY_PRONOUN] Sang '[NAME]!'

|-
| {{text anchor|text_book_instruction}}
| Used when naming books.
| A Course on [NAME]

|-
| {{text anchor|text_child_age_proclamation}}
|
| I'm [CONTEXT:NUMBER]!

|-
| {{text anchor|text_current_profession_no_year}}
|
| I am a [CONTEXT:UNIT_NAME].

|-
| {{text anchor|text_current_profession_year}}
|
| This is my [CONTEXT:ORDINAL] year as a [CONTEXT:UNIT_NAME].

|-
| {{text anchor|text_curse}}
|
| Who dares to enter my house? I curse you!

|-
| {{text anchor|text_dwarf}}
| Used when boasting about killing a [[dwarf]]. See also [[Creature token#SPEECH]].
| whose hammer shattered on the anvil of my power

|-
| {{text anchor|text_elf}}
| Used when boasting about killing an [[elf]]. See also [[Creature token#SPEECH]].
| whose fragile bones shattered before the power of my contempt

|-
| {{text anchor|text_family_relationship_additional}}
|
| [CONTEXT:HIST_FIG:PRO_SUB] is also my [CONTEXT:FAMILY_RELATIONSHIP]

|-
| {{text anchor|text_family_relationship_additional_dead}}
|
| [CONTEXT:HIST_FIG:PRO_SUB] was also my [CONTEXT:FAMILY_RELATIONSHIP]

|-
| {{text anchor|text_family_relationship_no_spec}}
|
| I have [CONTEXT:INDEF_FAMILY_RELATIONSHIP] named [CONTEXT:HIST_FIG:TRANS_NAME]

|-
| {{text anchor|text_family_relationship_no_spec_dead}}
|
| I had [CONTEXT:INDEF_FAMILY_RELATIONSHIP] named [CONTEXT:HIST_FIG:TRANS_NAME]

|-
| {{text anchor|text_family_relationship_spec}}
|
| my [CONTEXT:FAMILY_RELATIONSHIP] is named [CONTEXT:HIST_FIG:TRANS_NAME]

|-
| {{text anchor|text_family_relationship_spec_dead}}
|
| my [CONTEXT:FAMILY_RELATIONSHIP] was named [CONTEXT:HIST_FIG:TRANS_NAME]

|-
| {{text anchor|text_general}}
|
| who lies dead, now only an embarrassing memory

|-
| {{text anchor|text_goodbye_worship_1}}
|
| upon arising in the mornings,

|-
| {{text anchor|text_goodbye_worship_2}}
|
| always remember to

|-
| {{text anchor|text_goodbye_worship_3}}
|
| speak the praises of [SPEAKER:HF_LINK:DEITY:RANDOM_DEF_SPHERE]

|-
| {{text anchor|text_greet}}
| Used when greeting another person.
| Greetings. My name is [SPEAKER:TRANS_NAME].

|-
| {{text anchor|text_greet_baby}}
| Used when greeting a [[baby]].
| A baby! How adorable!

|-
| {{text anchor|text_greet_reply}}
| Used when replying to another person's greeting.
| Ah, hello. I'm [SPEAKER:TRANS_NAME].

|-
| {{text anchor|text_greet_reply_after_hero}}
| Used by NPCs when replying to the player character's greeting after becoming a [[hero]].
| I am [SPEAKER:TRANS_NAME]. How can I be of service?

|-
| {{text anchor|text_greet_reply_diff_language}}
| Used when replying to the greeting of a person who is of another race.
| Hello, [AUDIENCE:RACE]. I am [SPEAKER:TRANS_NAME].

|-
| {{text anchor|text_greet_reply_unusual_first}}
| Used when replying to the greeting of a person whose first name is unusual.{{verify|June 2015}}
| You know, you don't meet many people with the name [AUDIENCE:FIRST_NAME]

|-
| {{text anchor|text_greet_worship}}
| Used for greetings by [[priest]]s and faithful people.{{verify|June 2015}}
| This servant of [SPEAKER:HF_LINK:DEITY:TRANS_NAME] greets you.

|-
| {{text anchor|text_guard_profession}}
| Used by guards when you ask them about their profession. See also [[#soldier_profession|soldier_profession]].
| I am a guard.

|-
| {{text anchor|text_guard_warning}}
|
| Don't start any trouble.

|-
| {{text anchor|text_hist_fig_slayer}}
|
| It is I that felled [CONTEXT:HIST_FIG:TRANS_NAME] the [CONTEXT:HIST_FIG:RACE].

|-
| {{text anchor|text_hunting_profession}}
|
| I hunt great beasts in [CONTEXT:PLACE:TRANS_NAME].

|-
| {{text anchor|text_hunting_profession_year}}
|
| I have hunted great beasts in [CONTEXT:PLACE:TRANS_NAME] for [CONTEXT:NUMBER] of my years.

|-
| {{text anchor|text_justification_antithetical}}
|
| can be thought of as the antithesis of

|-
| {{text anchor|text_justification_experience}}
|
| can allow one to experience

|-
| {{text anchor|text_justification_proximity}}
|
| can bring one near to

|-
| {{text anchor|text_justification_reminder}}
|
| can remind one of

|-
| {{text anchor|text_justification_representation}}
|
| can be thought of as a representation of

|-
| {{text anchor|text_lair_hunter_minotaur}}
| Used by [[minotaur]]s while hunting adventures in their lairs. See also [[Creature token#LAIR_HUNTER_SPEECH]].
| I'll eat you whole!

|-
| {{text anchor|text_mercenary_profession}}
|
| I seek fortune and glory by offering my skill at arms in [CONTEXT:PLACE:TRANS_NAME].

|-
| {{text anchor|text_mercenary_profession_year}}
|
| I have sought fortune and glory by offering my skill at arms in [CONTEXT:PLACE:TRANS_NAME] for [CONTEXT:NUMBER] of my years.

|-
| {{text anchor|text_no_family}}
| Used by NPCs when you ask them about their [[family]], but they don't have any.
| I have no family to speak of.

|-
| {{text anchor|text_past_hunting_profession}}
|
| In the past, I hunted great beasts.

|-
| {{text anchor|text_past_mercenary_profession}}
|
| In the past, I sought fortune and glory by offering my skill at arms.

|-
| {{text anchor|text_past_profession_no_year}}
|
| I was once a [CONTEXT:UNIT_NAME].

|-
| {{text anchor|text_past_profession_year}}
|
| I was a [CONTEXT:UNIT_NAME] for [CONTEXT:NUMBER] of the years of my life.

|-
| {{text anchor|text_past_snatcher_profession}}
|
| Once it was my calling to rescue lost children.

|-
| {{text anchor|text_past_thief_profession}}
|
| I once sought great treasures.

|-
| {{text anchor|text_past_wandering_profession}}
|
| I once wandered the wilds.

|-
| {{text anchor|text_positive}}
| Used to express positive [[feeling]]s.
| wonderful! fantastic! very good

|-
| {{text anchor|text_same_site_ab_specific_hf_seeker}}
|
| seek out [CONTEXT:HIST_FIG:TRANS_NAME] here in [CONTEXT:SITE:TRANS_NAME] at [CONTEXT:ABSTRACT_BUILDING:TRANS_NAME]

|-
| {{text anchor|text_same_site_specific_hf_seeker}}
|
| seek out [CONTEXT:HIST_FIG:TRANS_NAME] here in [CONTEXT:SITE:TRANS_NAME]

|-
| {{text anchor|text_site_specific_hf_seeker}}
|
| seek out [CONTEXT:HIST_FIG:TRANS_NAME] over in [CONTEXT:SITE:TRANS_NAME]

|-
| {{text anchor|text_slayer}}
|
| bane death nemesis vanquisher

|-
| {{text anchor|text_snatcher_profession}}
|
| I rescue lost children and bring them back to [CONTEXT:PLACE:TRANS_NAME].

|-
| {{text anchor|text_snatcher_profession_year}}
|
| For [CONTEXT:NUMBER] of my years, I have been rescuing lost children and bringing them back to [CONTEXT:PLACE:TRANS_NAME].

|-
| {{text anchor|text_soldier_profession}}
| Used by [[soldier]]s when you ask them about their profession. See also [[#guard_profession|guard_profession]].
| I am a soldier.

|-
| {{text anchor|text_task_recommendation}}
|
| [CONTEXT:ANY:TRANS_NAME] might have a task for you

|-
| {{text anchor|text_temple_already_member}}
|
| your task is simple; all you need is to

|-
| {{text anchor|text_temple_become_member}}
|
| Welcome to [CONTEXT:ENTITY:TRANS_NAME]. Praise be to [CONTEXT:ENTITY:WORSHIP_HF:TRANS_NAME]! As a member of [CONTEXT:ENTITY:TRANS_NAME], you can now seek the higher mysteries of [CONTEXT:ENTITY:WORSHIP_HF:TRANS_NAME].

|-
| {{text anchor|text_thief_profession}}
|
| I seek treasures and bring them back to [CONTEXT:PLACE:TRANS_NAME].

|-
| {{text anchor|text_thief_profession_year}}
|
| I seek treasures and bring them back to [CONTEXT:PLACE:TRANS_NAME] and have done so for [CONTEXT:NUMBER] of the years of my life.

|-
| {{text anchor|text_threat}}
| Used by NPC [[bandit]]s{{verify|June 2015}} before attacking you.
| Prepare to die!

|-
| {{text anchor|text_unknown_hf_seeker}}
|
| seek out [CONTEXT:HIST_FIG:TRANS_NAME], wherever [CONTEXT:HIST_FIG:PRO_SUB] might be

|-
| {{text anchor|text_wandering_profession}}
|
| I wander [CONTEXT:PLACE:TRANS_NAME].

|-
| {{text anchor|text_wandering_profession_year}}
|
| I have wandered [CONTEXT:PLACE:TRANS_NAME] for [CONTEXT:NUMBER] of my years.
|}

== Adding custom files ==

New speech tokens can be added with mods {{verify}}. It is also possible to add new files and associate them with custom creatures.

{| class="wikitable"
|+ [[Creature token]]s
! Token !! Example uses

|-
| [[Creature token#CASTE_SPEECH|CASTE_SPEECH]]
|

|-
| [[Creature token#LAIR_HUNTER_SPEECH|LAIR_HUNTER_SPEECH]]
| [[minotaur]] ([[#lair_hunter_minotaur|lair_hunter_minotaur.txt]])

|-
| [[Creature token#SPEECH|SPEECH]]
| [[dwarf]] ([[#dwarf|dwarf.txt]]), [[elf]] ([[#elf|elf.txt]])

|-
| [[Creature token#SPEECH_FEMALE|SPEECH_FEMALE]]
|

|-
| [[Creature token#SPEECH_MALE|SPEECH_MALE]]
|
|}

== Special tokens ==

Speech files can contain tokens in square brackets (<code>[]</code>), which are replaced with context-specific strings before the speech is displayed.

=== Context tokens ===

These give special information about the background of the conversation.

{| class="wikitable"
! Token !! Type !! Meaning

|-
| [CONTEXT:ABSTRACT_BUILDING]
| building
|
* [[#ab_specific_hf_seeker|ab_specific_hf_seeker]]: the building in which the historical figure that the speaker wants you to seek is

|-
| [CONTEXT:HIST_FIG]
| creature
|
* [[#ab_specific_hf_seeker|ab_specific_hf_seeker]]: the historical figure the speaker wants you to seek

|-
| [CONTEXT:NUMBER]
| number
|
* [[#animal_slayer|animal_slayer]]: number of animals slain
* [[#child_age_proclamation|child_age_proclamation]]: age in years of the child

|-
| [CONTEXT:ORDINAL]
| number
|
* [[#current_profession_year|current_profession_year]]: the number of years the speaker has had their profession

|-
| [CONTEXT:PLACE]
| site
|
* [[#animal_slayer|animal_slayer]]: the place where the speaker slew the animals

|-
| [CONTEXT:RACE]
| race
|
* [[#animal_slayer|animal_slayer]]: the race of the animals the speaker has slain

|-
| [CONTEXT:SITE]
| site
|
* [[#ab_specific_hf_seeker|ab_specific_hf_seeker]]: the site where the historical figure the speaker wants you to seek is

|-
| [CONTEXT:UNIT_NAME]
| text
|
* [[#current_profession_no_year|current_profession_no_year]]: the name of the speaker's profession
|}

[[Category:DF2014:Files]]
[[Category:DF2014:Modding]]

Modding

2022-12-20T06:51:09Z

Trainzack: Reducing article quality level as this feature has changed dramatically in 50.01 and the documentation here needs expanding.

{{Quality|Tattered|14:13, 7 November 2013 (UTC)}}
{{av}}
{{For/see|a list of Dwarf Fortress mods|[[List of mods]]}}
{{Modding}}
'''Modding''' refers to modifying the game's files. ''Dwarf Fortress'' is remarkably moddable.

== Resource Overview==
[[File:modding_icon.png|120px|right]]This section serves as a portal to all modding-related pages on the wiki.

Game data documentation:
* [[Raw file]]
* [[Token]]
* [[Graphics]]
* [[Speech file]]
* [[Dipscript]]

Tools & Utilities
* [http://www.bay12forums.com/smf/index.php?board=13.0 Official bay12 Forum for modding]
* [[Utilities#Modding tools]]
* [[Character table]]

Guides:
* [[#Guide|Guide to Modding]]
* [[Memory hacking]], [[Main:Offset Finding Methods|Offset Finding Methods]]
* [[Category:DF2014:Modding Examples]]

Game Files:
* Gameplay settings: [[announcements.txt]] • [[d_init.txt]]
* Settings: [[colors.txt]] • [[init.txt]] • [[interface.txt]]
* Log files: [[errorlog.txt]] • [[gamelog.txt]]
* [[Saved game folder]] 

Miscellaneous
* Development: [[DF2014:Release information|Release information]] • [[Main:Dwarf_Fortress_Talk|Developer diaries]] • [[Main:Dwarf_Fortress_Development|Roadmap]]
* [[Main:Screenshot|Screenshot]]

== Guide ==
This is intended to be a guide to inform those new to ''Dwarf Fortress'' modding on what elements of the game can be modified, and how. After reading through this guide, a user should be capable of editing creatures, entities, materials ''et al'', and creating their own.

Generally, breaking stuff is fine - nothing that can be changed will affect the DF executable, and new additions can be easily removed.

This guide is based on [[40d:Modding guide|Teldin's guide]], originally created for version 0.27.176.39c. Per wiki tradition, it has been updated through all the major releases since then; hopefully it reflects current knowledge.

=== Token reference ===
It's always good to refer to tokens on the wiki. Even experienced modders have to look up tokens! A list of articles about tokens can be found [[Token|here]].

=== Basics of DF modding ===
All the base data that can be edited by prospective modders can be found in the \raw\ folder. This folder contains two subfolders: "graphics" (where you insert [[Graphics set repository|graphics sets]]), and "objects", which contains all the data for, generally, everything in the game that is not hardcoded.

Within the \raw\objects folder are a large number of text files - these are the [[raw file|raw files]], and editing them is quite easy - you can also create your own if you wish. For now, take a look at one of the existing files. For example, if you open creature_standard.txt, it should look something like this:

{{code|
creature_standard

[OBJECT:CREATURE]

[CREATURE:DWARF]
[DESCRIPTION:A short, sturdy creature fond of drink and industry.]
[NAME:dwarf:dwarves:dwarven]
[CASTE_NAME:dwarf:dwarves:dwarven]
[CREATURE_TILE:1][COLOR:3:0:0]
[CREATURE_SOLDIER_TILE:2]
...
}}

As you can see, each file comprises a header string stating the file name, a second header stating the type of object data it contains, followed by the contents of the file itself. These are all necessary elements of the file, and without them, the file will be ignored by the game. You may have also noticed the file naming scheme - this is also important; files containing creatures have names starting with "creature_", entity file names must begin with "entity_", etc..

Below the headers, there begins a list of entries. Each entry is made up of its own header (in this case, "[CREATURE:DWARF]"), again stating the type of object, and then the object's unique identifier - if an identifier isn't unique, the game will mess up and you'll get some serious, and potentially very trippy, errors. ([[Duplicated raws|For example...]]) Below that, we have the body of the entry, which determines the entry's specific properties.

The body of an entry is made up of a series of "tokens", which are essentially flags that can be added or removed to affect the entry's attributes. Most of these effects are hardcoded: for example, it's possible to make a creature only eat meat with the [CARNIVOROUS] token, but it's impossible to create your own token detailing a specific diet for the creature.

Before we continue, a few key things to remember when modding the raw files:

* Try to avoid modifying the existing raw files when adding objects. It makes removing mods far easier.
* When adding files, all you need to include to ensure proper references are maintained is the token identifiers. The game will load up all *.txt files in the raw folder, and searches through them by tokens. For example, you can add a new pair of leather boots and not even have to add it to the item_shoes.txt file, but rather make your own file, say item_shoes_new.txt and ensure you have the token listed, ex. [ITEM_SHOES:ITEM_SHOES_BOOTS_NEW].

* If you want to edit an already-existing creature, always back up the files you plan on editing to a different location. Since v0.31.22, the game no longer loads backup files with an extension other than ".txt", but duplicate entries are still a very bad thing.
* When a new world is generated, all the raw files get copied into a \raw\ folder within the applicable save folder. If you want to change something within a world that's already been generated, you'll have to edit those files, not the ones in ~DF\raw\objects.
* There's nothing stopping you from just copying an existing creature/entity/whatever, changing the identifier, and modifying it. This can save you a lot of time, especially when it comes to entities... which are coincidentally what we'll be talking about next.

=== Modding civilizations (entities) ===

Entities - the objects that determine how civilizations work - are stored in entity_default.txt (though, like all other files, you may add more). They follow the same format as any other raw file:

{{code|
entity_default

[OBJECT:ENTITY]

[ENTITY:ENTITYNAME]
[CREATURE:CREATURETYPE]
[TRANSLATION:LANGUAGETYPE]
[BIOME_SUPPORT:BIOMETOKEN:FREQUENCY]
...[OTHER TAGS]...
}}

Most of the time, it doesn't matter which order these tokens are in or where they're placed so long as they're below the "ENTITY:" identifier, but there are some important exceptions in the case of other files, especially creatures, which can contain a lot of "nested" tokens.

"[CREATURE:]" links the civilization with a specific creature defined in a creature file. This is the creature that'll be making up the entity's population, and, therefore, the creature you'll be playing as in fortress or adventure mode if the entity is a playable one. For example, if you wanted to do something silly, you could switch the "CREATURE:DWARF" entry in entity_default.txt with "CREATURE:ELF" and you would be marching elves around in fortress mode, although they would still use dwarven technology, language and names and so forth. Oh, and before you get any funny ideas - it ''is'' possible to define more than one creature for a civ, but that won't work in quite the way you probably expect; later on, in the creature section, you'll learn about castes, which will provide a much more viable alternative, so try to bear with us until then.

"[TRANSLATION:]" defines the language file that the entity will be using, which will determine what their untranslated words are for things. This doesn't determine which words they use for naming things, only the way those words are spelled. The default language files are HUMAN, DWARF, ELF, and GOBLIN.

"[BIOME_SUPPORT:]" defines the biomes that civs will attempt to settle in. The "FREQUENCY" value determines the likelihood of them building there, but also raises an important point: most of the values you'll be setting for things are relative to each other. If one were to type:

{{code|
[BIOME_SUPPORT:ANY_FOREST:1]
[BIOME_SUPPORT:SAVANNA:2]
}}

This would have very much the same effect as:

{{code|
[BIOME_SUPPORT:ANY_FOREST:5]
[BIOME_SUPPORT:SAVANNA:10]
}}

This holds true for a lot of values throughout the files, excluding when it simply doesn't make sense, such as in materials.

You can find many details about the rest of the civilization tokens [[entity token|here]].

Besides those mentioned, some fundamental ones are the SITE_CONTROLLABLE token, which lets you control the civ in fortress mode, the OUTSIDER_CONTROLLABLE token, which allows you to play in adventure mode as an outsider, and the ALL_MAIN_POPS_CONTROLLABLE token, which allows you to play a civ native (non-outsider) in adventure mode. Other tokens that you should pay attention to are START_BIOME and the ones regarding sites, but in general, you can just run through the aforementioned list and add or remove what you want.

If you have more than one civ with the SITE_CONTROLLABLE token, all the available civs from those entities will appear in the group selection section on the embark screen. It may not be immediately obvious from which species each civ may be - while this can be determined from legends mode, the topmost species in the "neighbors" display in the embark screen is always the same as the currently selected species; if your group is dwarven, dwarves will be topmost, whilst (say) elves will be topmost if your chosen group is elven. By default, the game seems to choose a civ (and therefore a species if there is more than one) at random.

You can also attempt to discern the civ yourself by the names it uses - this is the realm of "symbols", collections of words centered around a specific concept. The civ will use the words comprising whatever symbols are applicable to it for various things. This association might be a little confusing at first, so, let's refer to the DWARF entity:

{{code|
[SELECT_SYMBOL:WAR:NAME_WAR]
[SUBSELECT_SYMBOL:WAR:VIOLENT]
[SELECT_SYMBOL:BATTLE:NAME_BATTLE]
[SUBSELECT_SYMBOL:BATTLE:VIOLENT]
[SELECT_SYMBOL:SIEGE:NAME_SIEGE]
[SUBSELECT_SYMBOL:SIEGE:VIOLENT]
}}

Here, we can see that dwarves will generally name their wars first after words in the "NAME_WAR" symbol group, and then, after words in the "VIOLENT" symbol group. This might, for example, result in a war being named "The War of Carnage". The symbols used for the other types of conflict are arrayed in a similar fashion. It would be trivial to replace the instances of VIOLENT with, say, PEACE and end up with a battle called "The Clash of Calm" or something.

{{code|
[SELECT_SYMBOL:ROAD:NAME_ROAD]
[SELECT_SYMBOL:TUNNEL:NAME_TUNNEL]
[SELECT_SYMBOL:BRIDGE:NAME_BRIDGE]
[SELECT_SYMBOL:WALL:NAME_WALL]
}}

The above applies here. Dwarves are fond of naming their roads and tunnels after... roads and tunnels.

{{code|
[SELECT_SYMBOL:REMAINING:ARTIFICE]
[SELECT_SYMBOL:REMAINING:EARTH]
[CULL_SYMBOL:ALL:DOMESTIC]
[CULL_SYMBOL:ALL:SUBORDINATE]
[CULL_SYMBOL:ALL:EVIL]
[CULL_SYMBOL:ALL:UNTOWARD]
[CULL_SYMBOL:ALL:FLOWERY]
[CULL_SYMBOL:ALL:NEGATIVE]
[CULL_SYMBOL:ALL:UGLY]
[CULL_SYMBOL:ALL:NEGATOR]
}}

This section deals with everything else. The things that haven't already been dealt with (hence the "REMAINING") - such as site names, kingdom names, the names of individuals, and such - will have names from the ARTIFICE and EARTH symbol groups. After that, the dwarf entity is told to cull all inappropriate symbols - this applies to everything (hence the "ALL") so if the game happens to choose a symbol associated with, say, EVIL for one of the battles, it'll scrap that name and try again. This sort of thing adds a lot of flavour to DF's entities and can account for a lot of a civ's perceived personality.

Another basic thing to note: any entity token that's dealing with weapons, armor, clothing, etc., will state the items that the civ can build natively, not necessarily the ones they can wear or use. For example, you could create a species with no clothes specified, but then rob a clothes shop in adventurer mode and wear everything you want, or give them weapons that are too large to wield and they could sell them, but not use them.

An easy method of creating a civilization is just to copy-paste a similar one to the bottom of the entity_default.txt file and edit things to your liking. Remember to always change the civ's "ENTITY:" identifier! This can be anything, so long as it's not already existing.

At the end of some of the default entries you'll find a list of positions, both ones that'll directly affect you in fort mode (such as nobles) and ones that'll primarily affect worldgen and adventure mode. A list of the tokens applicable to positions can be found [[position token|here]]; they don't require a great deal of explanation.

==== Trade ====
The following [[entity token]]s affect the appearance of [[trading]] [[caravan]]s:

* [[Entity token#ACTIVE_SEASON|[ACTIVE_SEASON]]] - Defines the seasons when an entity may visit your fortress.
* [[Entity token#PROGRESS_TRIGGER_POPULATION|[PROGRESS_TRIGGER_*]]] - Defines the triggers which control when an entity will become interested in your fortress.
* [[Entity token#COMMON_DOMESTIC_PACK|[COMMON_DOMESTIC_PACK]]] - Allows the civilization to use domestic pack animals. If an entity lacks pack animals (pr ability to pull wagons), it will be unable to send caravans (showing as {{DFtext|No Trade|6:1}} at the [[embark]] screen), unless it has domesticated any suitable animal species.
* [[Entity token#COMMON_DOMESTIC_PULL|[COMMON_DOMESTIC_PULL]]] - Allows the civilization to use domestic animals to pull [[wagon]]s, assuming their [[Ethic#KILL_PLANT|KILL_PLANT ethic]] permits them to use wagons in the first place.
* [[Entity token#MERCHANT_BODYGUARDS|[MERCHANT_BODYGUARDS]]] - Caravan will be guarded by [[soldier]]s.

=== Modding creatures ===

Creature modding is great fun – you can change nearly any aspect of a creature, or make your own completely from scratch.

Modding creatures is very similar to modding civs: it's just a matter of editing, adding, or removing tokens, enclosed in square brackets underneath the creature's [CREATURE:] header. The creature entries contain all of the information about each and every non-random creature in the game, from animals to dwarves to goblins to even caravan wagons. A lot of the creature tokens are fairly self-explanatory; you can find a list of such tokens [[creature token|here]]. But before you start creating your own creatures, you'll want to learn how the tissues system works.

==== Creature materials and tissues ====

In the most basic sense, a creature is a series of body parts. These parts are defined in their own file, and we'll talk about them later, as a specific aspect of how creatures work, which throws off a lot of prospective modders, is the relationship between body parts, tissues, and materials. We're going to show you part of the creature entry for a bronze colossus (bear with us):

{{code|
...
[BODY:HUMANOID:2EYES:2EARS:NOSE:HUMANOID_JOINTS:5FINGERS:5TOES]
[NO_THOUGHT_CENTER_FOR_MOVEMENT]
[TISSUE:BRONZE]
[TISSUE_NAME:bronze:bronze]
[TISSUE_MATERIAL:INORGANIC:BRONZE]
[MUSCULAR]
[FUNCTIONAL]
[STRUCTURAL]
[RELATIVE_THICKNESS:1]
[CONNECTS]
[TISSUE_SHAPE:LAYER]
[TISSUE_LAYER:BY_CATEGORY:ALL:BRONZE]
...
}}

At the top, we can see the "BODY:" token, followed by a list of body parts. As you've probably guessed, these parts make up the physical form of the colossus. But the colossus has to be made out of something - it has to have tissues, and those tissues also have to be made out of something - in this case, bronze.

Below the BODY token you'll see a TISSUE token, followed by an identifier, much like the others we've seen. The TISSUE block is determining how the tissue works, and which purposes it'll serve. As the colossus is just going to be made out of this one tissue, this tissue needs to act like bone, muscle, and everything else combined, hence the MUSCULAR, FUNCTIONAL and STRUCTURAL tokens. The tissue also references a material - INORGANIC:BRONZE - the properties of which are declared in the inorganic materials file, and the tissue is subsequently made out of this material. With us so far?

Below the tissue definition is the TISSUE_LAYER line. TISSUE_LAYER allows you to control where each tissue is applied. Its first argument defines if it's to search by body part category (BY_CATEGORY), body part type (BY_TYPE), or look for a specific part (BY_TOKEN). That's followed by the parts argument itself, which is in this case ALL (so the game's looking for parts in all categories, which is to say, every body part). This is followed by the tissue to be applied, BRONZE. So the TISSUE_LAYER token is telling the game to select all body parts in every category and make them out of the tissue "BRONZE". The colossus is now made of bronze.

By now you're probably thinking "Wow, if this was for a creature made out of however many tissues, this would be amazingly longwinded" and you're right. Luckily, there are two methods by which we can speed things up a lot.

Firstly, there are material and tissue templates. Let's say you were going to make a lot of creatures out of bronze, and you didn't want to have to copy and paste the bronze tissue all over the place. Instead, you create a tissue template. This goes, as you've probably guessed, in a tissue template file.

{{code|
[TISSUE_TEMPLATE:BRONZE_TEMPLATE]
[TISSUE_NAME:bronze:bronze]
[TISSUE_MATERIAL:INORGANIC:BRONZE]
[MUSCULAR]
[FUNCTIONAL]
[STRUCTURAL]
[RELATIVE_THICKNESS:1]
[CONNECTS]
[TISSUE_SHAPE:LAYER]
}}

Now, instead of applying the tissue to each and every bronze creature you're making, you can just refer to the template:

{{code|
...
[BODY:HUMANOID:2EYES:2EARS:NOSE:HUMANOID_JOINTS:5FINGERS:5TOES]
[NO_THOUGHT_CENTER_FOR_MOVEMENT]
[USE_TISSUE_TEMPLATE:BRONZE:BRONZE_TEMPLATE]
[TISSUE_LAYER:BY_CATEGORY:ALL:BRONZE]
...
}}

Material templates work in the same way, but refer to materials instead of tissues.

However, if we're looking at something like a dwarf, even with the templates, editing can get very slow indeed:

{{code|
...
[USE_MATERIAL_TEMPLATE:SKIN:SKIN_TEMPLATE]
[USE_MATERIAL_TEMPLATE:FAT:FAT_TEMPLATE]
[USE_MATERIAL_TEMPLATE:MUSCLE:MUSCLE_TEMPLATE]
[USE_MATERIAL_TEMPLATE:BONE:BONE_TEMPLATE]
[USE_MATERIAL_TEMPLATE:CARTILAGE:CARTILAGE_TEMPLATE]
[USE_MATERIAL_TEMPLATE:HAIR:HAIR_TEMPLATE]
[USE_MATERIAL_TEMPLATE:TOOTH:TOOTH_TEMPLATE]
[USE_MATERIAL_TEMPLATE:EYE:EYE_TEMPLATE]
[USE_MATERIAL_TEMPLATE:NERVE:NERVE_TEMPLATE]
[USE_MATERIAL_TEMPLATE:BRAIN:BRAIN_TEMPLATE]
[USE_MATERIAL_TEMPLATE:LUNG:LUNG_TEMPLATE]
[USE_MATERIAL_TEMPLATE:HEART:HEART_TEMPLATE]
[USE_MATERIAL_TEMPLATE:LIVER:LIVER_TEMPLATE]
[USE_MATERIAL_TEMPLATE:GUT:GUT_TEMPLATE]
[USE_MATERIAL_TEMPLATE:STOMACH:STOMACH_TEMPLATE]
[USE_MATERIAL_TEMPLATE:PANCREAS:PANCREAS_TEMPLATE]
[USE_MATERIAL_TEMPLATE:SPLEEN:SPLEEN_TEMPLATE]
[USE_MATERIAL_TEMPLATE:KIDNEY:KIDNEY_TEMPLATE]
[USE_TISSUE_TEMPLATE:SKIN:SKIN_TEMPLATE]
[USE_TISSUE_TEMPLATE:FAT:FAT_TEMPLATE]
[USE_TISSUE_TEMPLATE:MUSCLE:MUSCLE_TEMPLATE]
...
}}

This is where body detail plans, which have their own file, and are designed to help automate some of the more common processes in creature creation, come in. The first entry in b_detail_plan_default.txt does exactly what we've been trying to do above: it takes all the common materials and shoves them into one plan, which can be referenced with a single token.

{{code|
...
[BODY_DETAIL_PLAN:STANDARD_MATERIALS]
...
}}

Much easier. But what about the TISSUE_LAYER tokens? Will we have to type out all of those manually?

Nope, detail plans have that covered as well. It's possible to place variable arguments into a detail plan. For example:

{{code|
[BODY_DETAIL_PLAN:VERTEBRATE_TISSUE_LAYERS]
[BP_LAYERS:BY_CATEGORY:BODY:ARG3:50:ARG2:5:ARG1:1]
[BP_LAYERS:BY_CATEGORY:BODY_UPPER:ARG3:50:ARG2:5:ARG1:1]
[BP_LAYERS:BY_CATEGORY:BODY_LOWER:ARG3:50:ARG2:5:ARG1:1]
[BP_LAYERS:BY_CATEGORY:ARM:ARG4:25:ARG3:25:ARG2:5:ARG1:1]
[BP_LAYERS:BY_CATEGORY:ARM_UPPER:ARG4:25:ARG3:25:ARG2:5:ARG1:1]
...
[BP_LAYERS:BY_CATEGORY:NOSE:ARG5:4:ARG1:1]
...
}}

First an argument is placed in the plan (ARG1, ARG2 etc.), followed by the thickness of the tissue that will be inserted in place of the argument. So when we reference the VERTEBRATE_TISSUE_LAYERS plan, we'll be able to do something like this:

{{code|
[BODY_DETAIL_PLAN:VERTEBRATE_TISSUE_LAYERS:SKIN:FAT:MUSCLE:BONE:CARTILAGE]
}}

ARG1 in the detail plan is replaced by SKIN, the first tissue we entered. ARG2 is replaced by FAT, ARG3 by MUSCLE, ARG4 by BONE, and ARG5 by CARTILAGE. Hence, our creature's body part designated as BODY is made up of SKIN with thickness 1, FAT with thickness 5, and MUSCLE with thickness 50. Its nose is made up of SKIN (thickness 1) and CARTILAGE (thickness 4).

Things left out of the body plans aside, our dwarf's entire body, material, tissue and tissue layer tokens have been boiled down to this:

{{code|
...
[BODY:HUMANOID:2EYES:2EARS:NOSE:2LUNGS:HEART:GUTS:ORGANS:HUMANOID_JOINTS:
THROAT:NECK:SPINE:BRAIN:SKULL:5FINGERS:5TOES:MOUTH:FACIAL_FEATURES:TEETH:RIBCAGE]
[BODY_DETAIL_PLAN:STANDARD_MATERIALS]
[BODY_DETAIL_PLAN:STANDARD_TISSUES]
[BODY_DETAIL_PLAN:VERTEBRATE_TISSUE_LAYERS:SKIN:FAT:MUSCLE:BONE:CARTILAGE]
...
}}

This can save you a lot of time and space if you're making lots of changes common to many creatures. In general, if you're making a creature that's fleshy or chitinous, there are detail plans already included in the game to help you out. You should only have to resort to declaring tissues individually (like our bronze colossus) if you're doing something really out-of-the-ordinary.

Another great thing about templates (and so, detail plans) is that they can be modified after being declared. Let's say we wanted our dwarves to be perpetually on fire (don't ask). We declare the body stuff normally:

{{code|
...
[BODY:HUMANOID:2EYES:2EARS:NOSE:2LUNGS:HEART:GUTS:ORGANS:HUMANOID_JOINTS:
THROAT:NECK:SPINE:BRAIN:SKULL:5FINGERS:5TOES:MOUTH:FACIAL_FEATURES:TEETH:RIBCAGE]
[BODY_DETAIL_PLAN:STANDARD_MATERIALS]
[BODY_DETAIL_PLAN:STANDARD_TISSUES]
[BODY_DETAIL_PLAN:VERTEBRATE_TISSUE_LAYERS:SKIN:FAT:MUSCLE:BONE:CARTILAGE]
...
}}

We then select the appropriate material:

{{code|
...
[BODY:HUMANOID:2EYES:2EARS:NOSE:2LUNGS:HEART:GUTS:ORGANS:HUMANOID_JOINTS:
THROAT:NECK:SPINE:BRAIN:SKULL:5FINGERS:5TOES:MOUTH:FACIAL_FEATURES:TEETH:RIBCAGE]
[BODY_DETAIL_PLAN:STANDARD_MATERIALS]
[BODY_DETAIL_PLAN:STANDARD_TISSUES]
[BODY_DETAIL_PLAN:VERTEBRATE_TISSUE_LAYERS:SKIN:FAT:MUSCLE:BONE:CARTILAGE]
[SELECT_MATERIAL:SKIN]
[MAT_FIXED_TEMP:10600]
...
}}

We don't want them burning to death, so we'll need to stop that from happening:

{{code|
...
[BODY:HUMANOID:2EYES:2EARS:NOSE:2LUNGS:HEART:GUTS:ORGANS:HUMANOID_JOINTS:
THROAT:NECK:SPINE:BRAIN:SKULL:5FINGERS:5TOES:MOUTH:FACIAL_FEATURES:TEETH:RIBCAGE]
[BODY_DETAIL_PLAN:STANDARD_MATERIALS]
[BODY_DETAIL_PLAN:STANDARD_TISSUES]
[BODY_DETAIL_PLAN:VERTEBRATE_TISSUE_LAYERS:SKIN:FAT:MUSCLE:BONE:CARTILAGE]
[SELECT_MATERIAL:SKIN]
[MAT_FIXED_TEMP:10600]
[SELECT_MATERIAL:ALL]
[HEATDAM_POINT:NONE]
...
}}

Note that this makes use of DF's built-in temperature scale. You can read more about that [[Temperature|on this page]]. We're also referencing material tokens, which we haven't gone over yet - we'll talk about making your own materials later.

==== Creature castes ====

Another potentially extremely powerful part of the creature raws is the caste system. The caste system handles both true biological castes and lesser variations, such as sexes.

To understand the true potential of the caste system, we only need to take a look at the raws for antmen, found in creature_subterrenean.txt:

{{code|
...
[CASTE:WORKER]
[CASTE_NAME:worker ant woman:worker ant women:worker ant woman]
Female, but non-breeding.
[POP_RATIO:10000]
[CASTE:SOLDIER]
[CASTE_NAME:soldier ant woman:soldier ant women:soldier ant woman]
Female, but non-breeding.
[POP_RATIO:1000]
[CASTE:DRONE]
[MALE]
[CASTE_NAME:drone ant man:drone ant men:drone ant man]
[POP_RATIO:5]
[CASTE:QUEEN]
[FEMALE]
[CASTE_NAME:queen ant woman:queen ant women:queen ant woman]
[POP_RATIO:1]
[SELECT_CASTE:WORKER]
[SELECT_ADDITIONAL_CASTE:SOLDIER]
[SELECT_ADDITIONAL_CASTE:QUEEN]
[BODY:HUMANOID_4ARMS:2EYES:HEART:GUTS:BRAIN:MOUTH]
[BODYGLOSS:INSECT_UPPERBODY:INSECT_LOWERBODY]
[SELECT_CASTE:DRONE]
[BODY:HUMANOID_4ARMS:2EYES:HEART:GUTS:BRAIN:MOUTH:2WINGS]
[BODYGLOSS:INSECT_UPPERBODY:INSECT_LOWERBODY]
[FLIER]
[SELECT_CASTE:ALL]
[BODY_DETAIL_PLAN:CHITIN_MATERIALS]
[BODY_DETAIL_PLAN:CHITIN_TISSUES]
[BODY_DETAIL_PLAN:EXOSKELETON_TISSUE_LAYERS:CHITIN:FAT:MUSCLE]
[BODY_DETAIL_PLAN:STANDARD_HEAD_POSITIONS]
[ATTACK:PUNCH:BODYPART:BY_TYPE:GRASP]
[ATTACK_SKILL:GRASP_STRIKE]
[ATTACK_VERB:punch:punches]
...
}}

It's evident that the process of creating and editing castes is comparable to the modifications we were making to tissues and materials earlier: A caste is declared, and modifications to the base creature are made. Declared castes can be selected and subsequently modified, again, just like tissues and materials.

In this case, each caste is declared, given its own name, and a POP_RATIO, which determines how commonly a birth results in that caste - for every 10000 workers born, there'll be an average of 1000 soldiers, 5 drones and one queen. You've probably also noticed that the DRONE and QUEEN castes have the MALE and FEMALE tokens respectively - these tokens determine how breeding works. A creature without both a MALE caste and a FEMALE caste will be unable to breed (no asexual creatures yet, unfortunately). As they lack FEMALE, the workers and soldiers are unable to breed with the male drones.

After this, there are some modifications to bodyparts. In this case, the drones have wings and the FLIER token, which the other castes lack. It's entirely possible for creatures of different castes to have completely different body structures, even to the extent that they don't resemble each other at all. If you read the section of this guide that dealt with entities, you may remember a passing mention of multi-creature civilisations and how they don't quite work as you may think they would. The castes system is your workaround. You could create a caste that is, for all intents and purposes, a human, and another caste of the same creature that acts exactly like a giant cave spider, put the creature in a civ, and get a human-spider civ. The only flaw in this approach is that the castes will interbreed.

That's the most complex components of creature creation out of the way. You should find the rest trivial by comparison.

=== Modding items ===

Items are fairly simple to deal with. By default, each item type is contained in its own file; this may help make browsing for a specific item easier, but from a purely technical point of view, it's possible to throw all items into one file. Unfortunately, [[Item definition token|item definition tokens]] don't seem to be especially well-documented (at least not as well as the other object types), but you should be able to figure out most things by way of our explanations and your assumptions.

Let's look at the entry for, of course, the thong:

{{code|
[ITEM_PANTS:ITEM_PANTS_THONG]
[NAME:thong:thongs]
[LAYER:UNDER]
[COVERAGE:25]
[LAYER_SIZE:10]
[LAYER_PERMIT:30]
[MATERIAL_SIZE:1]
[SOFT]
[LEATHER]
[STRUCTURAL_ELASTICITY_WOVEN_THREAD]
}}

Most of these are pretty obvious if one compares them to the other entries in the file. There's a layer for the item, determining where it's worn; a coverage value to determine how well it protects you from cold and other things; a size token to determine how much it counts for when it's under something else; a layer permit token to determine how much can be worn under it; and a material size token to determine how much raw material it takes to make it.

Now, if you wanted to mod these to turn them into metal thongs (ouch!), you would simply have to add [METAL] to it somewhere. Simple! These tokens work by tying into material properties - some materials are designated as suitable for making hard items, some for soft, etc..

Weapons involve a little more detail:

{{code|
[ITEM_WEAPON:ITEM_WEAPON_SWORD_2H]
[NAME:two-handed sword:two-handed swords]
[SIZE:900]
[SKILL:SWORD]
[TWO_HANDED:67500]
[MINIMUM_SIZE:62500]
[MATERIAL_SIZE:5]
[ATTACK:EDGE:100000:8000:slash:slashes:NO_SUB:1250]
[ATTACK:EDGE:50:4000:stab:stabs:NO_SUB:1000]
[ATTACK:BLUNT:100000:8000:slap:slaps:flat:1250]
[ATTACK:BLUNT:100:1000:strike:strikes:pommel:1000]
}}

SIZE determines how heavy the weapon is. This has a substantial effect on weapon effectiveness. SKILL determines which skill is used in using the weapon; a list of skills can be found [[skill token|on this page]]. MINIMUM_SIZE determines the minimum size a creature must be before the weapon can be wielded, while TWO_HANDED determines how large a creature must be in order to wield the weapon with one hand.

Attacks take a little more explanation. The first value determines the contact area of the weapon's attack; this should be high for slashing weapons and low for bludgeoning, piercing and poking ones. The second value determines how deep the weapon penetrates - for BLUNT attacks this value is ignored as they're not supposed to penetrate anyway, but in the case of EDGE attacks it should generally be lower for slashing attacks and higher for stabbing attacks.

Following these are the nouns and verb used; they should be self-explanatory. Finally, we have the velocity modifier, which has a multiplying effect on the weapon's size for the purposes of determining how powerful it is in combat.

Other, more miscellaneous items are generally simple and shouldn't require any further explanation.

Once you've made an item, you just add it to the civ entry so a civilization can actually craft it, and it's done.

=== Modding language files ===

Let's say you added a whole new species. Sure, you could just swipe one of the existing translation files and steal their language for your species, but that's the lazy way! If you want to create a whole new language, it is very simple.

First, you'd need a whole new language_RACE file, such as language_LIZARDMAN.txt, along with "language_LIZARDMAN" at the top of the file proceeded by [OBJECT:LANGUAGE] and [TRANSLATION:LIZARDMAN]. After that, it's just a matter of copy-pasting one of the existing language lists and editing the finished 'translated' word. That's it! Then just add the translation link to your civ in entity_default.txt and it'll be added to the game on worldgen.

(Note that the name of the file doesn't actually matter; however, it's good form to name the file after a creature if only that creature speaks the language.)

=== Modding body parts ===

Imagine you have this fantastic idea for a multi-tentacled winged spider-monster. Sounds great! But in order to make this a reality you may need to create a new set of body parts for it. That's no problem! Making body parts is easy, though it may look complicated at first.

All of the default body definitions are located in body_default.txt and then linked to a creature in the creature's entry. We've talked about how bodyparts make up creatures earlier, in the creature section. You can mix and match them in the creature entry and it makes no difference, as long as they're there: each body part will link itself to the appropriate connection automatically when the creature is first created.

Body parts work by sections: you can add as many sections as you want to a body part definition, but generally you should keep it fairly low for ease of use. Each body section entry is in the, very simple, format:

{{code|
[BODY:BODYNAME]
[BP:TOKENID:name][TOKENSGOHERE][DEFAULT_RELSIZE:][CATEGORY:WHATEVER]
}}

The most important tokens are "CONTYPE" and "CON": CONTYPE means the body part in question is connected to a certain ''type'' of body part, while CON means it's connected to a ''specific'' one. TOKENID is yet another identifier, which should be unique, as it's referenced every time something uses CON or BY_TOKEN. DEFAULT_RELSIZE defines, of course, what the body part's size is in relation to the other parts. CATEGORY defines a category for the part, which can be unique or shared with other parts. This is referenced whenever BY_CATEGORY is used.

A list of body part tokens can be found [[body token|here]].

Let's take a simple example, a head:

{{code|
[BODY:BASIC_HEAD]
[BP:HD:head:STP][CONTYPE:UPPERBODY][HEAD][CATEGORY:HEAD]
[DEFAULT_RELSIZE:300]
}}

It connects directly to an upper body.

{{code|
[BODY:2EYES]
[BP:REYE:right eye:STP][CONTYPE:HEAD][SIGHT][EMBEDDED][SMALL][RIGHT][CATEGORY:EYE]
[DEFAULT_RELSIZE:5]
[BP:LEYE:left eye:STP][CONTYPE:HEAD][SIGHT][EMBEDDED][SMALL][LEFT][CATEGORY:EYE]
[DEFAULT_RELSIZE:5]
}}

These are a pair of eyes, connecting to the head.

{{code|
[BODY:HUMANOID]
[BP:UB:upper body:upper bodies][UPPERBODY][CATEGORY:BODY_UPPER]
[DEFAULT_RELSIZE:1000]
[BP:LB:lower body:lower bodies][CON:UB][LOWERBODY][CATEGORY:BODY_LOWER]
[DEFAULT_RELSIZE:1000]
[BP:HD:head:STP][CON:UB][HEAD][CATEGORY:HEAD]
[DEFAULT_RELSIZE:300]
[BP:RUA:right upper arm:STP][CON:UB][LIMB][RIGHT][CATEGORY:ARM_UPPER]
[DEFAULT_RELSIZE:200]
[BP:LUA:left upper arm:STP][CON:UB][LIMB][LEFT][CATEGORY:ARM_UPPER]
[DEFAULT_RELSIZE:200]
[BP:RLA:right lower arm:STP][CON:RUA][LIMB][RIGHT][CATEGORY:ARM_LOWER]
[DEFAULT_RELSIZE:200]
[BP:LLA:left lower arm:STP][CON:LUA][LIMB][LEFT][CATEGORY:ARM_LOWER]
[DEFAULT_RELSIZE:200]
[BP:RH:right hand:STP][CON:RLA][GRASP][RIGHT][CATEGORY:HAND]
[DEFAULT_RELSIZE:80]
[BP:LH:left hand:STP][CON:LLA][GRASP][LEFT][CATEGORY:HAND]
[DEFAULT_RELSIZE:80]
[BP:RUL:right upper leg:STP][CON:LB][LIMB][RIGHT][CATEGORY:LEG_UPPER]
[DEFAULT_RELSIZE:500]
[BP:LUL:left upper leg:STP][CON:LB][LIMB][LEFT][CATEGORY:LEG_UPPER]
[DEFAULT_RELSIZE:500]
[BP:RLL:right lower leg:STP][CON:RUL][LIMB][RIGHT][CATEGORY:LEG_LOWER]
[DEFAULT_RELSIZE:400]
[BP:LLL:left lower leg:STP][CON:LUL][LIMB][LEFT][CATEGORY:LEG_LOWER]
[DEFAULT_RELSIZE:400]
[BP:RF:right foot:right feet][CON:RLL][STANCE][RIGHT][CATEGORY:FOOT]
[DEFAULT_RELSIZE:120]
[BP:LF:left foot:left feet][CON:LLL][STANCE][LEFT][CATEGORY:FOOT]
[DEFAULT_RELSIZE:120]
}}

An entire humanoid body. The foot bone's connected to the ankle bone...

"BODYGLOSS" entries, which you can sometimes find applied to creature entries, are simply replacement words for specific part name strings in a creature. For example, you'll find the bodygloss [BODYGLOSS:CLAW_HAND:hand:claw] in body_default.txt; you can then use this in a creature via "[BODYGLOSS:CLAW_HAND]" and it'll replace all instances of "hand" with "claw" in that creature. Be warned, however—if you were to, say make a bodygloss [BODYGLOSS:EARSTALK:ear:stalk:ears:stalk], it would not only change "ear" and "ears" to "stalk" and "stalks", it would also change "h'''ear'''t" to "h'''stalk'''t"! For all intents and purposes the body part will still function as the proper part, though.

=== Modding plants ===

Plants are, again, not unlike creatures. With what you've learned so far in regard to tokens and the materials system, running through the notes included in plant_standard.txt should explain most things. [[Plant token|Here's the list of plant-specific tokens]].

Below is the [[plump helmet]] raw description:

{{code|
[PLANT:MUSHROOM_HELMET_PLUMP]
[NAME:plump helmet][NAME_PLURAL:plump helmets][ADJ:plump helmet]
[USE_MATERIAL_TEMPLATE:STRUCTURAL:STRUCTURAL_PLANT_TEMPLATE]
[MATERIAL_VALUE:2]
[BASIC_MAT:LOCAL_PLANT_MAT:STRUCTURAL]
[EDIBLE_VERMIN]
[EDIBLE_RAW]
[EDIBLE_COOKED]
[PICKED_TILE:161][PICKED_COLOR:6:13:0]
[GROWDUR:300][VALUE:2]
[USE_MATERIAL_TEMPLATE:DRINK:PLANT_ALCOHOL_TEMPLATE]
[STATE_NAME_ADJ:ALL_SOLID:frozen dwarven wine]
[STATE_NAME_ADJ:LIQUID:dwarven wine]
[STATE_NAME_ADJ:GAS:boiling dwarven wine]
[MATERIAL_VALUE:2]
[DISPLAY_COLOR:5:0:0]
[EDIBLE_RAW]
[EDIBLE_COOKED]
[PREFIX:NONE]
[DRINK:LOCAL_PLANT_MAT:DRINK]

[USE_MATERIAL_TEMPLATE:SEED:SEED_TEMPLATE]
[MATERIAL_VALUE:1]
[EDIBLE_VERMIN]
[EDIBLE_COOKED]
[SEED:plump helmet spawn:plump helmet spawn:4:0:1:LOCAL_PLANT_MAT:SEED]
[SPRING][SUMMER][AUTUMN][WINTER]
[FREQUENCY:100]
[CLUSTERSIZE:5]
[PREFSTRING:rounded tops]
[WET][DRY]
[BIOME:SUBTERRANEAN_WATER]
[UNDERGROUND_DEPTH:1:3]
[SHRUB_TILE:142]
[DEAD_SHRUB_TILE:28]
[SHRUB_COLOR:5:13:0]
[DEAD_SHRUB_COLOR:5:6:0]
}}

Let's look at this line by line: 
First, we define its file name. In this case it's MUSHROOM_HELMET_PLUMP. Next we define its in-game name (plump helmet) and its adjective for if you were to craft with it (e.g. plump helmet earrings).

{{code|
[USE_MATERIAL_TEMPLATE:STRUCTURAL:STRUCTURAL_PLANT_TEMPLATE]
[MATERIAL_VALUE:2]
[BASIC_MAT:LOCAL_PLANT_MAT:STRUCTURAL]
}}

This defines the structure and material of the plant. It references STRUCTURAL_PLANT_TEMPLATE in the first line, so if you were to say, add wings to the template, the plump helmet plant would be winged. This is for the plant itself, not the end plump helmets.

After that we get our edible tokens. These say that vermin can eat the plant, and it can be eaten raw or cooked by your dwarves. So if you wanted a plant vermin would leave alone, you'd remove the [EDIBLE_VERMIN] token.

{{code|
[EDIBLE_VERMIN]
[EDIBLE_RAW]
[EDIBLE_COOKED]
}}

Next, [PICKED_TILE:161] is the character (161 in this case) shown when the crop is harvested. See [[Main:Character table|character table]] for a table of usable tiles. [PICKED_COLOR:6:13:0] is the color used for the crop's tile when harvested. It's in a foreground:background:brightness format. See [[color]] for the colors usable.

{{code|
[PICKED_TILE:161][PICKED_COLOR:6:13:0]
}}

[GROWDUR:300] is how long it takes for your crop to grow. There are 1008 growdur units in a season. 
[VALUE:2] Is the value of the harvested plant (default 1).

{{code|
[GROWDUR:300][VALUE:2]
}}

This defines the plant's alcohol states. [STATE_NAME_ADJ:ALL_SOLID:] is the frozen name, followed is the actual drink name, and then its boiling name. These are achieved by either Scorching or Freezing climates. [DISPLAY_COLOR] is, of course, color, and [EDIBLE_RAW] and [EDIBLE_COOKED] are saying you can drink the alcohol raw or cooked.

{{code|
[USE_MATERIAL_TEMPLATE:DRINK:PLANT_ALCOHOL_TEMPLATE]
[STATE_NAME_ADJ:ALL_SOLID:frozen dwarven wine]
[STATE_NAME_ADJ:LIQUID:dwarven wine]
[STATE_NAME_ADJ:GAS:boiling dwarven wine]
[MATERIAL_VALUE:2]
[DISPLAY_COLOR:5:0:0]
[EDIBLE_RAW]
[EDIBLE_COOKED]
[PREFIX:NONE]
[DRINK:LOCAL_PLANT_MAT:DRINK]
}}

After that we get our seed template:

{{code|
[USE_MATERIAL_TEMPLATE:SEED:SEED_TEMPLATE]
[MATERIAL_VALUE:1]
[EDIBLE_VERMIN]
[EDIBLE_COOKED]
[SEED:plump helmet spawn:plump helmet spawn:4:0:1:LOCAL_PLANT_MAT:SEED]
}}

And all this says is that the seeds may be eaten by vermin or cooked. Then it gives the name of our plant's seed, its plural name, its foreground, background, and brightness colors, followed by its seed material; said material should have [SEED_MAT] to permit proper stockpiling.

And finally for the last chunk we have this:

{{code|
[SPRING][SUMMER][AUTUMN][WINTER]
[FREQUENCY:100]
[CLUSTERSIZE:5]
[PREFSTRING:rounded tops]
[WET][DRY]
[BIOME:SUBTERRANEAN_WATER]
[UNDERGROUND_DEPTH:1:3]
[SHRUB_TILE:142]
[DEAD_SHRUB_TILE:28]
[SHRUB_COLOR:5:13:0]
[DEAD_SHRUB_COLOR:5:6:0]
}}

First we define what season(s) the plant may grow in, then we define how frequently this plant is generated in a particular area, followed by how many harvested crop items may come from 1 plant. [PREFSTRING:] is what your dwarves like about the plant, which in this case is the rounded tops. [WET][DRY] are the conditions under which the plant can grow. Wet means it can grow close to water, dry means it can grow away from water. This does not mean you can grow the plant on dry stone however. It is just for natural spawning of the plant. 
[BIOME] Is what biome the plant grows in. [UNDERGROUND_DEPTH:Minimum:Maximum] Is the highest and lowest cavern levels that the plant can appear in if its biome is subterranean. Dwarven civilizations will only export (via the embark screen or caravans) things that are available at depth 1. Defaults to 0:0 (surface only). 
Lastly, [SHRUB_TILE] is the character used for the naturally spawning shrub of this plant, [DEAD_SHRUB] is the dead shrub character. [SHRUB_COLOR] Is the shrub's color, and [DEAD_SHRUB_COLOR] is, of course, the dead shrub's color.

While this may or may not look like a lot of tokens, it's very easy. Just copy an existing plant and edit it to your new plant. 
For the rest of the tokens, see [[plant token]].

==== Trees ====

Trees are another kind of plant that can be modded. Being plants, they use many of the same tokens as edible crops, but differ in having a few tree-specific tokens.

Below is the [[apple|apple tree]] raw description:

{{code|
[PLANT:APPLE] malus sieversii
[NAME:apple tree][NAME_PLURAL:apple trees][ADJ:apple tree]
[USE_MATERIAL_TEMPLATE:STRUCTURAL:STRUCTURAL_PLANT_TEMPLATE]
[BASIC_MAT:LOCAL_PLANT_MAT:STRUCTURAL]
[USE_MATERIAL_TEMPLATE:WOOD:WOOD_TEMPLATE]
[STATE_NAME:ALL_SOLID:apple wood]
[STATE_ADJ:ALL_SOLID:apple wood]
[PREFIX:NONE]
[SOLID_DENSITY:745] *** http://www.csudh.edu/oliver/chemdata/woods.htm
[STATE_COLOR:ALL_SOLID:CHOCOLATE] *** http://www.forestryforum.com/board/index.php/topic,61009.0.html
[USE_MATERIAL_TEMPLATE:DRINK:PLANT_ALCOHOL_TEMPLATE]
[STATE_NAME_ADJ:ALL_SOLID:frozen apple cider]
[STATE_NAME_ADJ:LIQUID:apple cider]
[STATE_NAME_ADJ:GAS:boiling apple cider]
[MATERIAL_VALUE:2]
[DISPLAY_COLOR:6:0:0]
[EDIBLE_RAW]
[EDIBLE_COOKED]
[PREFIX:NONE]
[DRINK:LOCAL_PLANT_MAT:DRINK]
[USE_MATERIAL_TEMPLATE:LEAF:LEAF_TEMPLATE]
[STATE_COLOR:ALL:GREEN]
[DISPLAY_COLOR:2:0:0]
[USE_MATERIAL_TEMPLATE:FLOWER:FLOWER_TEMPLATE]
[STATE_COLOR:ALL:ROSE]
[DISPLAY_COLOR:5:0:1]
[USE_MATERIAL_TEMPLATE:FRUIT:FRUIT_TEMPLATE]
[STATE_COLOR:ALL:RUST]
[DISPLAY_COLOR:4:0:0]
[EDIBLE_VERMIN]
[EDIBLE_RAW]
[EDIBLE_COOKED]
[STOCKPILE_PLANT_GROWTH]
[MATERIAL_REACTION_PRODUCT:DRINK_MAT:LOCAL_PLANT_MAT:DRINK]
[MATERIAL_REACTION_PRODUCT:SEED_MAT:LOCAL_PLANT_MAT:SEED]
[USE_MATERIAL_TEMPLATE:SEED:SEED_TEMPLATE]
[MATERIAL_VALUE:1]
[EDIBLE_VERMIN]
[SEED:apple seed:apple seeds:0:0:1:LOCAL_PLANT_MAT:SEED]
[TREE:LOCAL_PLANT_MAT:WOOD][TREE_TILE:5]
[TRUNK_PERIOD:10]
[HEAVY_BRANCH_DENSITY:25]
[BRANCH_DENSITY:50]
[MAX_TRUNK_HEIGHT:3]
[HEAVY_BRANCH_RADIUS:1]
[BRANCH_RADIUS:2]
[TRUNK_BRANCHING:2]
[MAX_TRUNK_DIAMETER:1]
[TRUNK_WIDTH_PERIOD:200]
[ROOT_DENSITY:5]
[ROOT_RADIUS:3]
[STANDARD_TILE_NAMES]
[PREFSTRING:fruit]
[DRY]
[BIOME:ANY_TEMPERATE]
[SAPLING]
[GROWTH:LEAVES]
[GROWTH_NAME:apple leaf:apple leaves]
[GROWTH_ITEM:PLANT_GROWTH:NONE:LOCAL_PLANT_MAT:LEAF]
[GROWTH_DENSITY:1000]
[GROWTH_HOST_TILE:BRANCHES_AND_TWIGS]
[GROWTH_HOST_TILE:SAPLING]
[GROWTH_TIMING:0:300000]
[GROWTH_PRINT:0:6:2:0:0:0:209999:1]
[GROWTH_PRINT:0:6:6:0:1:210000:239999:1] autumn color
[GROWTH_PRINT:0:6:4:0:1:240000:269999:1]
[GROWTH_PRINT:0:6:4:0:0:270000:300000:1]
[GROWTH_DROPS_OFF]
[GROWTH:FLOWERS]
[GROWTH_NAME:apple flower:STP]
[GROWTH_ITEM:PLANT_GROWTH:NONE:LOCAL_PLANT_MAT:FLOWER]
[GROWTH_DENSITY:1000]
[GROWTH_HOST_TILE:BRANCHES_AND_TWIGS]
[GROWTH_TIMING:60000:119999]
[GROWTH_PRINT:5:5:5:0:1:60000:119999:2]
[GROWTH:FRUIT]
[GROWTH_NAME:apple:STP]
[GROWTH_ITEM:PLANT_GROWTH:NONE:LOCAL_PLANT_MAT:FRUIT]
[GROWTH_DENSITY:1000]
[GROWTH_HOST_TILE:BRANCHES_AND_TWIGS]
[GROWTH_TIMING:120000:200000]
[GROWTH_DROPS_OFF_NO_CLOUD]
[GROWTH_PRINT:'%':'%':4:0:0:120000:200000:3]
[GROWTH_HAS_SEED]
}}

The first lines are the same as the ones we saw being used in the plump helmets, defining the plant object, giving it a name, and deciding that it should use the standard STRUCTURAL_PLANT material for its structure.

{{code|
[PLANT:APPLE] malus sieversii
[NAME:apple tree][NAME_PLURAL:apple trees][ADJ:apple tree]
[USE_MATERIAL_TEMPLATE:STRUCTURAL:STRUCTURAL_PLANT_TEMPLATE]
[BASIC_MAT:LOCAL_PLANT_MAT:STRUCTURAL]
}}

Adding the token [[DF2014:Material_definition_token#DISPLAY_COLOR|DISPLAY_COLOR]] directly after [USE_MATERIAL_TEMPLATE] would allow us to change the color of the tree.

{{code|
[USE_MATERIAL_TEMPLATE:STRUCTURAL:STRUCTURAL_PLANT_TEMPLATE]
[DISPLAY_COLOR:1:0:0]
[BASIC_MAT:LOCAL_PLANT_MAT:STRUCTURAL]
}}

would give us a dark blue apple tree. This method is used by the game in [[birch|birches]] and [[spore tree|various]] [[nether-cap|underground]] [[blood thorn|trees]].

Next come the definitions of various other materials used by the tree:

{{code|
[USE_MATERIAL_TEMPLATE:WOOD:WOOD_TEMPLATE]
[STATE_NAME:ALL_SOLID:apple wood]
[STATE_ADJ:ALL_SOLID:apple wood]
[PREFIX:NONE]
[SOLID_DENSITY:745] *** http://www.csudh.edu/oliver/chemdata/woods.htm
[STATE_COLOR:ALL_SOLID:CHOCOLATE] *** http://www.forestryforum.com/board/index.php/topic,61009.0.html
[USE_MATERIAL_TEMPLATE:DRINK:PLANT_ALCOHOL_TEMPLATE]
[STATE_NAME_ADJ:ALL_SOLID:frozen apple cider]
[STATE_NAME_ADJ:LIQUID:apple cider]
[STATE_NAME_ADJ:GAS:boiling apple cider]
[MATERIAL_VALUE:2]
[DISPLAY_COLOR:6:0:0]
[EDIBLE_RAW]
[EDIBLE_COOKED]
[PREFIX:NONE]
[DRINK:LOCAL_PLANT_MAT:DRINK]
[USE_MATERIAL_TEMPLATE:LEAF:LEAF_TEMPLATE]
[STATE_COLOR:ALL:GREEN]
[DISPLAY_COLOR:2:0:0]
[USE_MATERIAL_TEMPLATE:FLOWER:FLOWER_TEMPLATE]
[STATE_COLOR:ALL:ROSE]
[DISPLAY_COLOR:5:0:1]
[USE_MATERIAL_TEMPLATE:FRUIT:FRUIT_TEMPLATE]
[STATE_COLOR:ALL:RUST]
[DISPLAY_COLOR:4:0:0]
[EDIBLE_VERMIN]
[EDIBLE_RAW]
[EDIBLE_COOKED]
[STOCKPILE_PLANT_GROWTH]
[MATERIAL_REACTION_PRODUCT:DRINK_MAT:LOCAL_PLANT_MAT:DRINK]
[MATERIAL_REACTION_PRODUCT:SEED_MAT:LOCAL_PLANT_MAT:SEED]
[USE_MATERIAL_TEMPLATE:SEED:SEED_TEMPLATE]
[MATERIAL_VALUE:1]
[EDIBLE_VERMIN]
[SEED:apple seed:apple seeds:0:0:1:LOCAL_PLANT_MAT:SEED]
}}

From them, we get to know what the parts of the tree can be used for, as well as how they will appear when separated from the tree. Any alterations that can be done to materials normally can be done here, such as changing the value or adding a [[syndrome]].

[TREE:LOCAL_PLANT_MAT:WOOD][TREE_TILE:5]

[TREE] is what turns your plant object into an actual tree. The following argument describes what material the harvested logs should be made of. If NONE, the felled tree will give no logs. [TREE_TILE] is the tile the tree shows up as on the world map.

Note that all vanilla trees (that give logs) use the WOOD material defined above as the argument for [TREE], as opposed to the STRUCTURAL material. Thus, any changes to the properties of the wood harvested should be done to the WOOD material.

The following tokens decide the dimensions of the tree, and how it grows.

{{code|
[TRUNK_PERIOD:10]
[HEAVY_BRANCH_DENSITY:25]
[BRANCH_DENSITY:50]
[MAX_TRUNK_HEIGHT:3]
[HEAVY_BRANCH_RADIUS:1]
[BRANCH_RADIUS:2]
[TRUNK_BRANCHING:2]
[MAX_TRUNK_DIAMETER:1]
[TRUNK_WIDTH_PERIOD:200]
[ROOT_DENSITY:5]
[ROOT_RADIUS:3]
}}

[TRUNK_PERIOD] and [TRUNK_WIDTH_PERIOD] determine how long it takes for the trunk to grow one tile taller respectively wider, in years. [MAX_TRUNK_HEIGHT:3] and [MAX_TRUNK_DIAMETER:1] determine the maximum value the above can reach. [TRUNK_BRANCHING] decides how "curvy" the tree is, with [TRUNK_BRANCHING:0] meaning the tree is entirely straight.

[HEAVY_BRANCH_DENSITY:25], [HEAVY_BRANCH_RADIUS:1], [BRANCH_DENSITY:50], [BRANCH_RADIUS:2], [ROOT_DENSITY:5], and [ROOT_RADIUS:3] determine the density (how many are there, integer ranging 0-100) and radius (in tiles) away from the trunk, of heavy branches, normal branches and roots respectively.

[STANDARD_TILE_NAMES] makes the tree use standard names for the trunk, branches etc. Otherwise custom ones can be used. (see [[Plant_token|full plant token list]])

[SAPLING] ensures saplings of this tree are called "[tree name] sapling", instead of the standard "young [tree name]".

Lastly, we are introduced to the [GROWTH] token. [GROWTH] defines growths growing on a plant, in this case our apple tree. Apple trees have three growths: leaves, flowers and fruits.

{{code|
[GROWTH:FRUIT]
[GROWTH_NAME:apple:STP]
[GROWTH_ITEM:PLANT_GROWTH:NONE:LOCAL_PLANT_MAT:FRUIT]
[GROWTH_DENSITY:1000]
[GROWTH_HOST_TILE:BRANCHES_AND_TWIGS]
[GROWTH_TIMING:120000:200000]
[GROWTH_DROPS_OFF_NO_CLOUD]
[GROWTH_PRINT:'%':'%':4:0:0:120000:200000:3]
[GROWTH_HAS_SEED]
}}

First comes the name of the growth. Then, with [GROWTH_ITEM], what kind of growth it is, in this case a PLANT_GROWTH made out of the local FRUIT material. [GROWTH_DENSITY] says how densely the growth grows, and [GROWTH_HOST_TILE] where on the tree it grows. [GROWTH_TIMING] decides when the growth appears, in annual ticks. The growth then drops off, leaving no clouds (items to be picked up by your dwarves). [GROWTH_PRINT] sets it to look like a red '%', and [GROWTH_HAS_SEED] implies that eating this growth will leave you with a seed.

=== Workshops ===

Workshops are raw-designed pretty differently from everything else in the game, being buildable structures rather than items or methods to gain items. However, they are fairly simple. For example, here's the raw for the [[soap maker's workshop]]:

{{code|code=
[BUILDING_WORKSHOP:SOAP_MAKER]
[NAME:Soap Maker's Workshop]
[NAME_COLOR:7:0:1]
[DIM:3:3]
[WORK_LOCATION:2:2]
[BUILD_LABOR:SOAP_MAKER]
[BUILD_KEY:CUSTOM_SHIFT_S]
[BLOCK:1:0:0:1]
[BLOCK:2:0:0:1]
[BLOCK:3:0:0:0]
[TILE:0:1:' ':' ':150]
[TILE:0:2:' ':' ':'/']
[TILE:0:3:'-':' ':' ']
[COLOR:0:1:0:0:0:0:0:0:6:0:0]
[COLOR:0:2:0:0:0:0:0:0:6:0:0]
[COLOR:0:3:6:0:0:0:0:0:0:0:0]
[TILE:1:1:' ':' ':'=']
[TILE:1:2:'-':' ':8]
[TILE:1:3:' ':' ':150]
[COLOR:1:1:0:0:0:0:0:0:6:0:0]
[COLOR:1:2:6:0:0:0:0:0:6:0:0]
[COLOR:1:3:0:0:0:0:0:0:6:0:0]
[TILE:2:1:'-':' ':8]
[TILE:2:2:' ':' ':8]
[TILE:2:3:' ':150:' ']
[COLOR:2:1:6:0:0:0:0:0:6:0:0]
[COLOR:2:2:0:0:0:0:0:0:6:0:0]
[COLOR:2:3:0:0:0:6:0:0:0:0:0]
[TILE:3:1:150:' ':8]
[TILE:3:2:' ':' ':8]
[TILE:3:3:' ':240:' ']
[COLOR:3:1:6:0:0:0:0:0:6:7:0]
[COLOR:3:2:0:0:0:0:0:0:6:7:0]
[COLOR:3:3:0:0:0:7:0:1:0:0:0]
[BUILD_ITEM:1:BUCKET:NONE:NONE:NONE][EMPTY][CAN_USE_ARTIFACT]
[BUILD_ITEM:1:NONE:NONE:NONE:NONE][BUILDMAT][WORTHLESS_STONE_ONLY][CAN_USE_ARTIFACT]
}}

A line-by-line breakdown:

{{code|
[NAME:Soap Maker's Workshop]
[NAME_COLOR:7:0:1]
}}

These are the name of the workshop ("Soap Maker's Workshop") and [[color]] of the workshop's name when examined with 'q' (White with a black background).

{{code|
[DIM:3:3]
[WORK_LOCATION:2:2]
}}

DIM refers to how large the workshop will be, in this case 3 wide, 3 tall. WORK_LOCATION tells where the creature using it (usually a dwarf) will work, numbered from the top right--in this case, 2:2, or the middle. Multiple work locations can be defined, even outside the dim.

{{code|
[BUILD_LABOR:SOAP_MAKER]
[BUILD_KEY:CUSTOM_SHIFT_S]
}}

These refer to the worker required to build it (soap maker) and the key used to build it in the workshop menu (capital S).

{{code|
[BLOCK:1:0:0:1]
...
}}
This is a bit more complex, and is where we get to the meaty part of workshop making--the tiles' properties. BLOCK refers to which tiles will be untraversable--1 means blocked, 0 means unblocked. The first number refers to row, and the next 3 refer to column, so 1:0:0:1 means that, on the first row, the first two tiles will be unblocked and the last will be blocked.

{{code|
[TILE:0:1:' ':' ':150]
...
}}
The TILE token tells which tile will go where. note, however, that there are 5 entries here instead of 4. The first number, in this case, refers to build stage, numbered from 0 to 3; 3 or 1 is fully built (depending on whether there are stages), 0 is just placed, and 2 is always an intermediate stage, while 1 is usually an intermediate stage. Whether 1 is an intermediate stage or not depends on if there are a 2 and 3 stage; if 2 and 3 exist, 1 will be intermediate. The second number and beyond are similar to BLOCK; however, instead of 1s and 0s, you must input tiles. The tiles themselves can be given in quotes (as in ' ') or given as a number, which can be looked up [[Tilesets|here]]. Here, we have 150, which is û.

{{code|
[COLOR:1:1:0:0:0:0:0:0:6:0:0]
...
}}
Color is as TILE, but with colors instead of tiles; however, colors are made up of 3 numbers each or MAT. MAT refers to the color of the material used to make it; the 3 numbers refer to foreground:background:foreground brightness, and can be looked up [[Color|here]]. For example, 4:2:1 will give you bright red with a dark green background.

{{code|
[BUILD_ITEM:1:BUCKET:NONE:NONE:NONE][EMPTY][CAN_USE_ARTIFACT]
[BUILD_ITEM:1:NONE:NONE:NONE:NONE][BUILDMAT][WORTHLESS_STONE_ONLY][CAN_USE_ARTIFACT]
}}
These refer to items required to build the building. These are in the same format as [[Reaction|reaction reagents and products]]--quantity:[[Item token|item]]:[[Material token|material]]. You'll learn more about those on the article about [[Reaction|reactions]], though. The second BUILD_ITEM is special-- it uses modifiers exclusively to determine its requirements. BUILDMAT refers to wood logs, wood blocks, stone boulders, and stone blocks; WORTHLESS_STONE_ONLY means it can't use economic stone; CAN_USE_ARTIFACT means that it... can use artifacts. EMPTY, in the bucket's case, means that the bucket must be empty.

More can be seen at the [[Building token|building tokens]] article.

=== Reactions ===

Reactions are the crafting recipes used in [[workshop]]s, and by the [[adventurer mode|adventurer]]. By adding new reactions you can make new items available, or enable you to get items or materials in new ways. The reactions can also be given to entities, in which case they will make use of them during both world gen and play; making a reaction that creates [[steel]] directly from [[plant fiber]]s, would allow the elves to craft steel and arrive clad in it in a [[siege]].

Not all crafting reactions are defined in the raws, but some are, such as those for [[ceramic industry|pottery]] and [[Metal#Alloys_2|alloy]] making.

An in-depth guide for reactions is available [[Reactions|here]].

=== Materials ===

As we've seen when talking about creatures, materials are vital. Materials show up in two forms: material templates, which generally show up in creatures, and specific materials (designated as "inorganic"), which are (by default, at least) consigned purely to metal and stone types.

Let's take a look at METAL_TEMPLATE in material_template_default.txt. It's evident that most of the basic properties of metals are already defined in the template - it goes red and melts at a high enough temperature, it's heavy, and (as noted by the very bottom token) is a metal. We already know just how useful templates can be to creatures, and the same applies to other materials.

Now let's take a look at inorganic_metal.txt. You can see that the metals here refer to the templates, and, just like we did with creatures, then modify the properties of that template and expand upon it.

Finally, let's look at inorganic_stone_mineral.txt. Here we can see that in addition to the changes made to the template, there are also ENVIRONMENT tokens - these tell the game where to place these minerals during worldgen.

[[material definition token|Here's a list of material tokens]]. It should also help you out with any modifications you want to make regarding those creature modifications we were making a while back. See, it all ties together in the end. The beauty of the current materials system is that there's actually very little difference between, say, leather and iron - they're fundamentally the same thing, just with different properties, which is how things really should be.

== Examples ==
:''Main articles: [[:Category:DF2014:Modding_Examples]]''

The Hydling below was made by Mysteryguye (and annotated, updated and separated into blocks by Putnam), to act as an example creature.

{{code|code=
[CREATURE:HYDLING]
[DESCRIPTION:A seven-headed small hairy thing, about the size of a dog. It is very loyal to its masters, and will promptly disembowel any enemy straying too close.]
This is the description that shows up in-game when viewing the creature.

[NAME:hydling:hydlings:hydlish] If there were a civ made of hydlings, it would appear as "hydlings" in the neighbors screen.

[CASTE_NAME:hydling:hydlings:hydlish]

[CREATURE_TILE:'='][COLOR:2:0:1] Will appear as a light green "=".

[PETVALUE:78][NATURAL] Creature is known to be naturally occurring by the game. Will cost 40 embark points to buy.

[LARGE_ROAMING] Will spawn outdoors, wandering around.

[COMMON_DOMESTIC][TRAINABLE][PET] Can be bought on embark as a pet, war animal, or hunting animal.

[BONECARN] Can eat meat and bones only--no vegetables.

[PREFSTRING:loyalty] Dwarves will like it for its loyalty.

[LARGE_PREDATOR] Will attack rather than flee.

[BODY:BASIC_2PARTBODY:7HEADNECKS:BASIC_FRONTLEGS:BASIC_REARLEGS:TAIL:2EYES:NOSE:2LUNGS:HEART:GUTS:ORGANS:THROAT:SPINE:BRAIN:SKULL:3TOES_FQ_REG:3TOES_RQ_REG:MOUTH:TONGUE:GENERIC_TEETH_WITH_FANGS:RIBCAGE]

Has a lower body, upper body, 4 legs, a tail, ten eyes, ten ears, five noses, two lungs, a heart, guts, a pancreas etc., and 5 heads with all that goes with those.

[BODYGLOSS:PAW] Feet will be called "paws"

[BODY_DETAIL_PLAN:STANDARD_MATERIALS] Declares the standard materials that most creatures' tissues are made of.

[BODY_DETAIL_PLAN:STANDARD_TISSUES] This declares the tissues that the creature's tissue layers are made of.

[BODY_DETAIL_PLAN:VERTEBRATE_TISSUE_LAYERS:SKIN:FAT:MUSCLE:BONE:CARTILAGE] And this describes the tissue layers that the creature is made of.

[BODY_DETAIL_PLAN:BODY_HAIR_TISSUE_LAYERS:HAIR] Creature will be covered with a layer of fur.

[USE_MATERIAL_TEMPLATE:NAIL:NAIL_TEMPLATE] And it'll have nails.

[USE_TISSUE_TEMPLATE:NAIL:NAIL_TEMPLATE]

[TISSUE_LAYER:BY_CATEGORY:TOE:NAIL:FRONT] On the toe, specifically.

[SELECT_TISSUE_LAYER:HEART:BY_CATEGORY:HEART]
[PLUS_TISSUE_LAYER:SKIN:BY_CATEGORY:THROAT]
[TL_MAJOR_ARTERIES] Heart and throat--called above--will cause heavy bleeding if ruptured.

[BODY_DETAIL_PLAN:STANDARD_HEAD_POSITIONS] Places eyes, ears and what-have-you into their correct placement, so that you don't have people punching out eyes from behind.

[BODY_DETAIL_PLAN:HUMANOID_RIBCAGE_POSITIONS] Sets the ribcage as being around lungs and heart.

[USE_MATERIAL_TEMPLATE:SINEW:SINEW_TEMPLATE] Defines sinew so that...
[TENDONS:LOCAL_CREATURE_MAT:SINEW:200] Tendons...
[LIGAMENTS:LOCAL_CREATURE_MAT:SINEW:200] ...And ligaments can be defined.

[HAS_NERVES] Creature has nerves, and as such can be disabled by severing them.

[USE_MATERIAL_TEMPLATE:BLOOD:BLOOD_TEMPLATE] Defines the material BLOOD using the template BLOOD_TEMPLATE.
[BLOOD:LOCAL_CREATURE_MAT:BLOOD:LIQUID] Defines the creature's BLOOD as being made of the above-defined BLOOD material in a LIQUID state.

[CREATURE_CLASS:GENERAL_POISON] Creature can be affected by syndromes that affect GENERAL_POISON.

[GETS_WOUND_INFECTIONS] Pretty much self-explanatory. Creature can get infected from wounds.
[GETS_INFECTIONS_FROM_ROT] And from necrosis.

[USE_MATERIAL_TEMPLATE:PUS:PUS_TEMPLATE] Defines PUS using PUS_TEMPLATE.
[PUS:LOCAL_CREATURE_MAT:PUS:LIQUID] Defines PUS as being made of PUS.

[BODY_SIZE:0:0:1000] Creature will be 1000 cubic centimeters at birth...
[BODY_SIZE:1:0:12500] 12500 cubic centimeters at 1 year old...
[BODY_SIZE:2:0:30000] and 30000 cubic centimeters at 2.

[BODY_APPEARANCE_MODIFIER:LENGTH:90:95:98:100:102:105:110] Creature can be anywhere from 90% to 110% as long as others.
[BODY_APPEARANCE_MODIFIER:HEIGHT:90:95:98:100:102:105:110] As above, but with height.
[BODY_APPEARANCE_MODIFIER:BROADNESS:90:95:98:100:102:105:110] As above, but with broadness. This puts the minimum size of the creature (when fully grown) at 21870 and the maximum size at 39930.

[MAXAGE:20:30] Creature will die of old age between the ages of 20 and 30, no later than 30, no sooner than 20.

[CAN_DO_INTERACTION:MATERIAL_EMISSION] Creature can use the MATERIAL_EMISSION interaction.
[CDI:ADV_NAME:Hurl fireball] In adventurer mode, the MATERIAL_EMISSION interaction will appear as "Hurl fireball".
[CDI:USAGE_HINT:ATTACK] Creature will use MATERIAL_EMISSION when it's attacking, on creatures that it's attacking.
[CDI:BP_REQUIRED:BY_CATEGORY:HEAD] Creature must have at least one HEAD to use MATERIAL_EMISSION.
[CDI:FLOW:FIREBALL] The MATERIAL_EMISSION will shoot a fireball.
[CDI:TARGET:C:LINE_OF_SIGHT] The target for the emission--a location--must be within the line of sight of the Hydling.
[CDI:TARGET_RANGE:C:15] And must be, at most, 15 tiles away.
[CDI:MAX_TARGET_NUMBER:C:1] The hydling can only shoot at one target at a time...
[CDI:WAIT_PERIOD:30] and only every 30 ticks (3 tenths of a second at 100 FPS)

[ATTACK:BITE:CHILD_BODYPART_GROUP:BY_CATEGORY:HEAD:BY_CATEGORY:TOOTH] Defines a BITE attack that uses teeth.
[ATTACK_SKILL:BITE] Attack uses the BITE skill.
[ATTACK_VERB:nom:noms] "The Hydling noms the Elf in the left first toe, tearing the muscle!"
[ATTACK_CONTACT_PERC:100] Will use all of the tooth. Note that this can be more than 100.
[ATTACK_PENETRATION_PERC:100] Will sink the tooth all the way in. This can also be more than 100.
[ATTACK_FLAG_EDGE] Attack is an EDGE attack.
[ATTACK_PRIORITY:MAIN] Attack is of priority MAIN. Other option is SECOND.
[ATTACK_FLAG_CANLATCH] Attack can latch on.
[ATTACK_PREPARE_AND_RECOVER:3:3] Takes 3 ticks to wind up attack and 3 to recover from it.
[ATTACK_FLAG_INDEPENDENT_MULTIATTACK] Can use each head independently.

[ATTACK:SCRATCH:CHILD_TISSUE_LAYER_GROUP:BY_TYPE:STANCE:BY_CATEGORY:ALL:NAIL] As above, but for nail instead of teeth.
[ATTACK_SKILL:STANCE_STRIKE] Uses the kicking skill.
[ATTACK_VERB:slice:slices] "You slice the Elf in the left foot and the severed part sails off in an arc!"
[ATTACK_CONTACT_PERC:100] Uses the whole nail.
[ATTACK_PENETRATION_PERC:100] The whole nail goes in.
[ATTACK_FLAG_EDGE] Attack is an edge attack.
[ATTACK_PREPARE_AND_RECOVER:3:3]
[ATTACK_PRIORITY:SECOND]

[CHILD:1] Hydling will become an adult at 1 year old.

[GENERAL_CHILD_NAME:hydie:hydies] Children will appear as "hydies".

[DIURNAL] Is active during the daytime.

[HOMEOTHERM:10070] Has a body temperature of 102 Fahrenheit.

[APPLY_CREATURE_VARIATION:STANDARD_QUADRUPED_GAITS:900:730:561:351:1900:2900] Can run at 25 kph
[APPLY_CREATURE_VARIATION:STANDARD_SWIMMING_GAITS:3512:2634:1756:878:4900:6900] Can swim at 10 kph
[APPLY_CREATURE_VARIATION:STANDARD_CRAWLING_GAITS:6561:6115:5683:1755:7456:8567] Can crawl at 5 kph
[SWIMS_INNATE]Swims innately.

[CASTE:FEMALE] Defines a caste called FEMALE.
[FEMALE] FEMALE caste is female.

[CASTE:MALE] As above, but with male.
[MALE] See above.
}}

== Utilities ==
{{main|Utilities#Modding_tools|l1=Utilities § Modding_tools}}
There are several utilities that assist in modding efforts. There is [http://www.bay12forums.com/smf/index.php?topic=28829.0 a list of them] on the [[Bay 12 Forums]].

== See also ==
{{catbox|DF2014:Modding}}

* [[Raw file]]
* [[Token]]

{{Category|Modding}}
{{Category|Guides}}
[[ru:Modding]]

Dwarf Fortress Wiki talk:Versions

2022-12-20T06:47:40Z

Trainzack: /* v50 migration */

{{archive|
# [[DF Talk:Versions/Archive 1|Page 1]]}}

== Version 0.31.19 starts a new DF generation? ==

My reading of Toady's comments on the release of 0.31.19 is that it came out basically because he felt it would take too long to get DF all the way to 0.32. With the ore changes, the sitefinder changes, the addition of grazing and several different industries, there's a lot of changes between 31.18 and 31.19. So I'm thinking it might be a good idea to call it the first release of DF2011 - and what we refer to as "DF2010" would then become 0.31.18.

Thoughts? --[[User:DeMatt|DeMatt]] 07:06, 28 February 2011 (UTC)

==Revisiting Redirects==

I wasn't around when the redirect policy was created, and I'm having trouble understanding the rationale. The example claims that linking [[Main:Cheese]] to [[cv:Cheese maker]] is problematic...but mainspace only ever redirects to the current version. If the best target in the current version is cheese maker, why not link to it directly? (It's not, at least for Cheese, since [[DF2012:Cheese]] exists now.) The explanation seems to be claiming that 40d articles that link to Cheese will follow the Mainspace link--but that hasn't been the case for a long while now. Articles in 40d automatically link against other articles in 40d, so that version remains internally consistent no matter where mainspace links to in the current version. For a current example, what do we gain by linking [[Main:Mead]] to [[cv:Mead]] and linking [[DF2012:Mead]] to [[DF2012:Alcohol]]?

If this really is just an outdated procedure, I recommend we drop the mummery and allow mainspace to link to cv:(best target). Double redirects ''may'' work (sometimes, but [[Main:Mead]] demonstrates a common problem where automatic redirection fails), but if they are unnecessary I think they should be avoided, partly because of problems like [[Main:Mead]] and partly because of the effort required to protect double redirects from users who believe they are problematic.--[[User:Loci|Loci]] ([[User talk:Loci|talk]]) 20:16, 8 January 2014 (UTC)

:I was just thinking that. I'm currently attempting to write a basic extension to eliminate the need for mainspace redirects entirely, although Mediawiki's class structure may make this more difficult than I had hoped (the only method I've found for resolving redirects takes the ''article text'' instead of a title, e.g. "#REDIRECT ..."). I do agree that the current situation with redirects isn't ideal, so I'm hoping this will work better (once I get it to work). --[[User:Lethosor|Lethosor]] ([[User talk:Lethosor|talk]]) 20:42, 8 January 2014 (UTC)

Okay, that wasn't quite as clear as I meant it to be. In general, I think this is a tricky situation. Mediawiki wasn't designed to have five content namespaces, and certainly not chains of redirects between them. The problem that was pointed out in the [[DF:REDIR|policy]] is the fact that with:
Main:Foo -> cv:Bar
pages in the cv: namespace can't use [[<nowiki/>foo]], since the namespace links modification causes it to be treated as [[<nowiki/>cv:foo]] instead, which doesn't exist. The current suggested solution is this:
Main:Foo -> cv:Foo -> cv:Bar
This fixes the problem of [[<nowiki/>foo]] not working on cv pages, but creates issues with double redirects not always working. Another solution, which is more intuitive to new editors, is:
Main:Foo -> cv:Bar
cv:Foo -> cv:Bar
Both require creating two redirects. The first method has the advantage of ''ensuring'' that the cv redirect exists (otherwise, main:foo would be a redlink), while the second has the advantage of working more reliably in a couple cases.

What I'm trying to do is make main:Foo "jump" to cv:Foo when cv:foo exists, ''even if main:foo doesn't exist'' (basically it would treat all mainspace pages as redirects to cv pages, but only if the cv page exists and not the mainspace page). I had main:Bar jumping to cv:Bar fine, but if cv:Foo redirected to cv:Bar, accessing main:Foo would mysteriously stop at cv:Foo even if I increased the redirect limit. What I'm trying to do now is follow the redirects internally, without relying on Mediawiki to do it automatically - unfortunately, that has proved to be harder than I had hoped (and I sent my web server into an infinite loop while trying). I will try to work on this some more when I get a chance, although I'm not sure when that'll be yet :(. For now, feel free to fix broken double mainspace redirects as necessary, as long as redirects in the DF2012 namespace stay pointing to the right page (and new mainspace redirects get added in the DF2012 namespace too). --[[User:Lethosor|Lethosor]] ([[User talk:Lethosor|talk]]) 04:21, 9 January 2014 (UTC)

:You're treating cv like a namespace--it's not. It is simply shorthand for "fill in the current version here". [http://dwarffortresswiki.org/index.php?title=User_talk:Briess&diff=182404&oldid=181281 As I discovered a long time ago on a server not far away], linking from Main:Foo to cv:Foo tends to break redirection chains. If, instead of linking to cv:Foo, you link to DF2012:Foo, it might just work. It would, of course, be better if your patch could evaluate cv itself, but even if you have to hardcode the current version it's a single point of maintenance that requires update very infrequently. (For that matter, we could probably dispense with the cv hack entirely and just have a bot update mainspace links from DF2012 to DF201X when we switch to a new version.)--[[User:Loci|Loci]] ([[User talk:Loci|talk]]) 20:05, 9 January 2014 (UTC)
::I know cv isn't a namespace - I was just trying to avoid future confusion when the DF2012 namespace changes. It's interesting that changing "cv" to "DF2012" fixes some broken redirects, although I've found that simply making an edit to a broken redirect can usually fix it as well. I've actually had the most problems with double redirects when the second one (in the DF2012 namespace) doesn't use the DF2012 prefix (e.g. main:Foo containing <nowiki>[[cv:Foo]] and DF2012:Foo containing [[Bar]]</nowiki>). I'd rather keep the cv alias even if it isn't necessary for mainspace redirects when I get the patch to work, since it makes it easier to refer to the current version of the page (for example, several MDF articles contain links to a vanilla page for things that don't change in the mod).
::Also, using aliases like "cv" is supported by Mediawiki; in fact, several WMF wikis use them (for example, "[[wikipedia:WP:Redirects|WP:Redirects]]" on Wikipedia). It's quite likely that Mediawiki isn't processing double redirects using aliases correctly, though, since that's uncommon on most wikis. --[[User:Lethosor|Lethosor]] ([[User talk:Lethosor|talk]]) 21:35, 9 January 2014 (UTC)

In light of the lack of support for the current redirect policy, I propose we replace the current redirect section with:

:Mainspace article pages should use the cv: alias when redirecting to a versioned page, which will automatically update the link when a new version is released. For example, page "Main:Foo" should redirect to page "cv:Bar" (where "Bar" is the page that best describes the topic Foo in the current version).

:Pages in mainspace should only redirect to an older versioned page if that content no longer exists in the current version of the game (e.g. [[Cave river]], [[Chunk]]). In these cases the cv: alias cannot be used.

:Pages inside a versioned namespace should not use the cv: alias. Instead, they should redirect to the best page within that versioned namespace (e.g. [[DF2012:Dodging]], [[v0.31:Drink]]).

:Due to limitations of the wiki software, double redirects should be avoided if possible. When fixing double redirects in mainspace, please make sure to use the cv: alias as appropriate.

If no one objects, I will make this change in a few days.--[[User:Loci|Loci]] ([[User talk:Loci|talk]]) 20:21, 15 January 2014 (UTC)

:Okay with me. It may be worth mentioning that double redirects only really need to be changed when they don't work (since changing a lot of redirects that work isn't necessary), but I think it's clearer and more relevant than the current policy. —[[User:Lethosor|Lethosor]] ([[User talk:Lethosor|talk]]) 00:26, 16 January 2014 (UTC)

Done.--[[User:Loci|Loci]] ([[User talk:Loci|talk]]) 20:55, 22 January 2014 (UTC)

I was finally able to get my extension to work after being motivated by one too many malfunctioning redirects. It now causes nonexistent pages in the main namespace to behave exactly like redirects to their DF2012 counterparts (when linked to, accessed directly, and transcluded). Double redirects also work (up to 100, in fact, although that was a temporary safety measure that I'll probably change). This means we'll be able to safely get rid of all mainspace redirects (redirects that redirect to something other than "cv" will still function if not deleted). —[[User:Lethosor|Lethosor]] ([[User talk:Lethosor|talk]]) 01:20, 14 March 2014 (UTC)
:What about articles which don't exist in the current version but do exist in older versions? Will those still need mainspace redirects, or will your extension be able to automatically redirect them to v0.31/40d/23a? --[[User:Quietust|Quietust]] ([[User talk:Quietust|talk]]) 01:29, 14 March 2014 (UTC)
::It ignores all mainspace pages that actually have content, including redirects, so pages like [[masons guild]] won't be affected (unless deleted). —[[User:Lethosor|Lethosor]] ([[User talk:Lethosor|talk]]) 01:47, 14 March 2014 (UTC)

Done and deployed. [[Cat]] is still treated as a redirect, even though I just deleted it (try clicking on the "redirected from" link). Pages that exist are ignored, so [[Masons guild]] and [[History of Dwarf Fortress]] still function normally (as a redirect to a 23a page and a non-redirect, respectively). —[[User:Lethosor|Lethosor]] ([[User talk:Lethosor|talk]]) 18:57, 14 April 2014 (UTC)

I'm sending around a bot right now to delete all redirects of the format "foo -> cv:foo" (a surprising number don't fit this format, so I'm leaving them alone for now). —[[User:Lethosor|Lethosor]] ([[User talk:Lethosor|talk]]) 20:43, 14 April 2014 (UTC)

:I'm confused. Do we use double redirects or not? Is there a single place we define our linking policy (including redirects), and is it updated?
:I had trouble linking to [[Consolidated_development]] in [[v0.34:Dragon]]. It kept pointing to v0.34:Consolidated_development, which does not exist. I ended up linking to Main:Consolidated_development to make it work. --[[User:Nahno|Nahno]] ([[User talk:Nahno|talk]]) 10:18, 1 July 2014 (UTC)

::That's a separate problem altogether - links in the versioned namespaces (v0.34, v0.31, 40d, 23a) automatically link to pages within their namespace. I may be able to set up a fallback to mainspace once I'm able to deploy again, but for now the "main:" alias is the intended solution. —[[User:Lethosor|Lethosor]] ([[User talk:Lethosor|talk]]) 11:36, 1 July 2014 (UTC)

== Google often directs people to the 0.31 page ==

I've noticed a couple of times that finding a wiki page from an external search will often drop me onto a page from an older version. Is it possible to mitigate this somehow for new players? I could imagine something like redirecting old:Bar -> cv:Bar unless the user has come from old:Foo; no idea if that would actually work though. [[User:PeridexisErrant|PeridexisErrant]] ([[User talk:PeridexisErrant|talk]]) 11:48, 4 May 2014 (UTC)

:As a temporary solution, I could write a script that displays a banner of some kind if the user came from an external site. I'll ask Briess if he can do anything on the server level to increase the weighting of the current version's pages. (Obviously there are situations where people are looking for old pages, like [[23a:dungeon master]], so we don't want to disable indexing entirely on old pages.) —[[User:Lethosor|Lethosor]] ([[User talk:Lethosor|talk]]) 17:03, 4 May 2014 (UTC)

== DF2014? ==

As Toady [http://www.bay12games.com/dwarves/ draws closer to a new release], it might be worthwhile to discuss the addition of a new version to the wiki. The upcoming release covers two years of changes and introduces a number of new plants, foods, drinks, multi-tile trees, climbing, jumping, etc., so it is likely to have significant changes from the current DF2012. To avoid having people start new pages (and lose all the effort spent refining the prior version's page), I think it would be best to have a bot automatically copy over the DF2012 pages as a starting point for DF2014. I would suggest that these copied pages include a noticebox template mentioning that the content may be outdated, so that we can easily track which pages have been reviewed. I think either the {{tl|version check}} or {{tl|old}} template would work. --[[User:Loci|Loci]] ([[User talk:Loci|talk]]) 19:43, 5 May 2014 (UTC)

:This is what [[User:QuietBot]] did after the 0.34 release, so it's certainly possible to use the same script to migrate to DF2014. I would like a way of tagging migrated pages, since inaccuracies in some pages went unnoticed for months after they were migrated. Since {{tl|old}} is already in use, {{tl|version check}} may be a better solution (it can be reworded slightly, or we can make a separate template for DF2014 migration). —[[User:Lethosor|Lethosor]] ([[User talk:Lethosor|talk]]) 19:23, 1 June 2014 (UTC)
:Made [[Template:DF2014 migrated]] as an example. Any thoughts? —[[User:Lethosor|Lethosor]] ([[User talk:Lethosor|talk]]) 19:32, 1 June 2014 (UTC)

== Redirects inconsistency ==

Following a redirect is supposed to be exactly the same as going straight to the page it redirects to, but this actually isn't the case:
* Go to [[Seeds]] and you get [[v0.34:Seed]] (outdated)
* Go to http://dwarffortresswiki.org/index.php?title=Seeds&redirect=no and click on the link and you get to [[DF2014:Seed]] (current)
So if you search for "seed", the top result is the DF2014 version. But search for "seeds" and you get the redirect, which sends you to the outdated page instead. [[User:Hairy Dude|Hairy Dude]] ([[User talk:Hairy Dude|talk]]) 23:22, 22 February 2015 (UTC)

While I'm talking about redirects, it seems redirects to sections don't work: see [[DF2014:How do I manage my seeds and crops]]. I know MediaWiki is capable of this trick because Wikipedia does it. [[User:Hairy Dude|Hairy Dude]] ([[User talk:Hairy Dude|talk]]) 23:32, 22 February 2015 (UTC)

:I have absolutely no idea why [[seeds]] redirects to a v0.34 page - it could be a Mediawiki bug. The section links issue is due to a known issue in the redirect extension we use, which has yet to be fixed. —[[User:Lethosor|Lethosor]] ([[User talk:Lethosor|talk]]) 00:01, 23 February 2015 (UTC)
:It looks like deleting both [[Seeds]] and [[DF2014:Seeds]] fixed things (by allowing AutoRedirect to handle the redirects instead). Feel free to tag any others with {{tl|bad redirect}}. —[[User:Lethosor|Lethosor]] ([[User talk:Lethosor|talk]]) 00:03, 23 February 2015 (UTC)
::It gets stranger. [[Vial]] redirects explicitly to [[cv:Flask]] which displays (when you look at it with &redirect=no) as [[DF2014:Flask]], but still goes to the v0.34 version. It seems redirects interpret the cv: pseudo-namespace (or whatever it's called) in an outdated way. [[User:Hairy Dude|Hairy Dude]] ([[User talk:Hairy Dude|talk]]) 18:08, 23 February 2015 (UTC)
::I've added a note to this page about this issue. If it gets resolved, the note should be removed. [[User:Hairy Dude|Hairy Dude]] ([[User talk:Hairy Dude|talk]]) 21:04, 23 February 2015 (UTC)

==Reorganizing versions==

The internet deals with moved content... poorly. Google is still linking to v0.34 pages more than a year after the switch to "DF2014", and even the wiki software still has cached links pointing to the old version pages.

I propose reorganizing versions on the wiki to avoid moving content whenever possible. Instead of having a temporary "current version" namespace that changes occasionally, all the current information gets promoted to the Main namespace. When the next version split occurs, the Main articles as of a certain revision number can be copied to the newly-created permanent "old version" namespace, while all the current information remains in Main. This not only fixes the link rot issue, but it has a few other benefits as well: fewer administrative tasks, no lockdown (a historical version of the Main pages can be copied at any point, even if the Main articles are already modified for the new version), almost all the article history is maintained in the Main article (instead of being spread unevenly across multiple versions), no "temporary" namespaces are needed, fewer problematic long redirect chains, and hopefully less user confusion (since Main gets priority in search results, etc.).

As an example, today we would not have a DF2014 namespace (which is good because "temporary" namespaces historically disappear anyway). If you ran a search for [[seed]] you'd end up at Main:seed, which would have all the current information on seeds. The version box at the top of the page would still link to the older versions of the seed article. When a new version is released, an admin would choose a revision number and copy the Main:seed article as it exists at that revision number to v0.40:seed. That's it. One historical copy that needs little to no new editing, and zero redirections/moves.--[[User:Loci|Loci]] ([[User talk:Loci|talk]]) 19:02, 27 July 2015 (UTC)

:Makes sense to me. It would involve a lot of work, though (e.g. fixing templates and categories to account for the current version being in mainspace), although that should be doable thanks to {{tl|category}}, {{tl|version switch}}, etc.. A bot could be set up to copy revisions from before a release date as well, which would be more difficult (and maybe slower) than a direct copy, but not severely. —[[User:Lethosor|Lethosor]] ([[User talk:Lethosor|talk]]) 17:24, 30 July 2015 (UTC)

:Actually, there are a few issues with that, namely that there wouldn't be an easy way to distinguish between versioned and non-versioned mainspace pages. There are ways to resolve Google search priority (we can exclude pages from older versions from search engine results if there are newer versions of those pages available, for example). —[[User:Lethosor|Lethosor]] ([[User talk:Lethosor|talk]]) 19:47, 6 August 2015 (UTC)

::There aren't very many non-versioned mainspace pages, and determining if a page is versioned is as simple as looking for the version template and/or categories added by the version template (e.g. copy [http://dwarffortresswiki.org/index.php/Category:Current this category] instead of Main:*). The problem with "suggesting" newer pages to Google is that they obviously aren't crawling our wiki regularly (if they were, the fact that the mainspace redirects point to new pages would automatically be picked up). Even if your Google hints worked they wouldn't do anything for all the other broken links out on the 'net.--[[User:Loci|Loci]] ([[User talk:Loci|talk]]) 20:35, 6 August 2015 (UTC)

::: Google actually crawls the wiki constantly - we probably get crawl hits from google for a continuous block of 2-3 hours per day, each and every day. Why they are slow to update is beyond me though. I can't remember why we didn't do this initially, but there was a technical limitation involved if I remember correctly. --[[User:Briess|Briess]] ([[User talk:Briess|talk]]) 22:05, 6 August 2015 (UTC)

::: There are <meta> tags that can be used to hide pages from search results (for search engines that recognize them, that is). Searching for {{tl|av}} or [[:Category:Current]] might work, although we'd have to make sure all of the DF2014 pages include that (some pages don't, particularly some disambiguation pages, although all of them should). —[[User:Lethosor|Lethosor]] ([[User talk:Lethosor|talk]]) 22:53, 6 August 2015 (UTC)

:Is there a particular reason main and current are separate to begin with?—[[User:CLA|CLA]] ([[User talk:CLA|talk]]) 00:17, 7 August 2015 (UTC)

::It's mostly intended to distinguish between versioned and non-versioned pages and make version-related templates simpler to work with, since every versioned page has a namespace. I wasn't active here in 2010 when this system was created, so Briess and Emi would know more.
::Another issue I just thought of with Loci's suggestion is categories - currently, categories like [[:Category:Animals]] are used to organize the versioned sub-categories. Sure, we can change {{tl|Category}} to categorize mainspace pages in [[:Category:v0.40:Animals]] or [[:Category:DF2014:Animals]], but that would be less straightforward because there wouldn't be a namespace with that name (until pages are migrated when a newer major version is released). —[[User:Lethosor|Lethosor]] ([[User talk:Lethosor|talk]]) 13:05, 7 August 2015 (UTC)

:Moving current pages to the main namespace sounds like a great idea. -[[User:Jecowa|Jecowa]] ([[User talk:Jecowa|talk]]) 20:47, 4 January 2018 (UTC)

Another thought: dealing with migrating redirects could be difficult with this proposal - specifically, determining which redirects should be migrated to a versioned namespace. Redirects can't contain {{tl|av}}, at least not before ``#REDIRECT``. I ''think'' it would be possible to copy pages in two stages, though - all non-redirects first, then all redirects whose targets were also copied. Thoughts? Anything I'm missing? —[[User:Lethosor|Lethosor]] ([[User talk:Lethosor|talk]]) 23:41, 27 June 2019 (UTC)

Some subpages (particularly /raw and /Edit notice) also deliberately lack {{tl|av}}, although those shouldn't be too hard to handle. —[[User:Lethosor|Lethosor]] ([[User talk:Lethosor|talk]]) 00:35, 9 July 2019 (UTC)

:Redirect pages (and all other edge cases I've looked at) can be included in categories (like [[:Category:Current]]) to determine whether or not they should be copied into an archival version. But if the redirects are "properly qualified" then they can all be copied over blindly. Mainspace redirects pointing to versioned information should use a blank namespace (which will be automatically constrained to the archival namespace); mainspace redirects pointing to unversioned information should use an explicit "Main" (which will automatically link back to the unversioned page). Then, when [[[[Toady]]]] gets copied to [[[[v0.4x:Toady]]]] it will point back to [[[[Main:Toady One]]]]. Meanwhile, [[[[Beer]]]], copied to [[[[v0.4x:Beer]]]], will properly point to [[[[v0.4x:Alcohol]]]].--[[User:Loci|Loci]] ([[User talk:Loci|talk]]) 20:00, 14 July 2019 (UTC)

::I think qualifying redirects is the best solution here - categorizing redirects manually is another possible source of errors, since categories (or a lack thereof) would only be visible on the redirect page itself, and [[:Category:Current]] is a hidden category. Copying over mainspace redirects into versioned namespaces would also resolve some issues that have come up due to those not reliably existing currently. I should be able to set up a bot script to add "main:" to current mainspace redirects (and it shouldn't break anything, since those redirects go to other mainspace pages anyway). —[[User:Lethosor|Lethosor]] ([[User talk:Lethosor|talk]]) 21:57, 14 July 2019 (UTC)

(Note: I wrote all of this without noticing the previous discussion above.) I was wondering, when the wiki creates a new namespace for a major release again, if it is possible to ''not'' create a namespace for the next current version (e.g. "DF202x") and instead have the mainspace articles (which are currently redirects) become the new cv and move the content there. Therefore, [[cv:Cat]] would just be "[[Cat]]" (or [[Main:Cat]]).

Certain namespace-related templates like [[Template:Ns/0]] would need to be changed, though nothing significant as far as I know. For most cases, any "DF2014" would be replaced with "Main" or even blank. There's also multiple extensions handling the current namespace system and they may need to be modified too, though I'm not sure if or how much. I'm guessing based on the discussions above that it will change stuff up.

My reason is the current namespace is increasingly becoming more anachronistic. "DF2014" could be misinterpreted as "this page is about the 2014 version of the game" or "this page was last updated in 2014", which I've seen a few people in forums mention. Granted that [[Template:Av]] is on the top of very article, I still think the namespace is inconsistent with the recentness of the article. But how is this related to what I'm asking for? Let's say we continue the current system: if we happen to do a new namespace change this year and create DF2020, the next major release (after graphics/UI) will be mythgen, which is estimated to take several years to develop (the Big Wait), and so the anachronism will start over again. The proposed way will prevent this from occurring for the next major release and every release thereafter.

I think the confusion with having a namespace that becomes old-fashioned overtime supersedes the confusion with not marking current versioned articles with a namespace. Most users just search "Cat" on the search bar and naturally expect to get information about the latest release of DF. So if users go a page that's just titled "Cat", they won't expect outdated info about cats from a previous release. That's how the current system works anyways. We'll be skipping the two-step process that we have now. It'll make several wiki tasks much simpler as well. Editors can create new articles for current versions without remembering to add a namespace. It'll fix any existing issues with (double) redirects; instead of [[Main:Kitten]] redirecting to [[cv:Kitten]], which goes to [[DF2014:Kitten]], which then redirects to [[DF2014:Cat]], [[Main:Kitten]] would just redirect to [[Main:Cat]]. And the cv: alias will no longer be necessary since "cv:" = "Main:" and will be forever.

There's no need to differentiate the current version and previous versions with a namespace for the current version is what I'm saying. Articles of previous versions will retain their respective namespaces. Users will still type "40d:Cat" to go to the 40d version of the article, but if they want the current version, they'll just type "Cat" (like now). The mainspace containing the "live" version of an article is natural and would create no uncertainty when browsing the wiki. And it would simplify the wiki somewhat and future-proof this anachronism problem. As a bonus, this change will also prevent web search engines from showing previous version pages when typing "DF cat" or something. (This isn't happening right now as DF2014 has been the current namespace for ~6 years, but it'll happen again when everything moves to a new namespace.)

This is the gist of it, and I may have ignored most of the problems with this proposal. I have personally wished for the whole version namespacing be made less complicated and have been seeking for a solution, and I feel like this is the best way to go about in the future. – [[User:Doorkeeper|Doorkeeper]] 21:27, 14 August 2020 (UTC)

:<s>Whoops, looks like Loci already proposed this exact thing long ago. I definitely missed that discussion and should have checked first. My apologies. I'll move my text to that section and remove this one. – [[User:Doorkeeper|Doorkeeper]] 21:36, 14 August 2020 (UTC)</s> Done. – [[User:Doorkeeper|Doorkeeper]] 21:40, 14 August 2020 (UTC)

:The main issue I have with that is that putting pages about the current version in a namespace also differentiates between those pages and pages not about ''any'' version (for example, [[Toady One]] does not need a 40d or v0.34 page). Yes, we can use {{tl|av}} to mark versioned pages, but people often forget to add that to new pages. The current system also allows determining whether a page is versioned or not from its title, which makes migrations a lot faster. Relying on {{tl|av}} would require either reading the content of every page (which would slow scripts down significantly) or cross-checking with the list of all pages including the template (feasible, but a bit more complicated, and still susceptible to missing templates). I suppose that manually fixing and migrating pages missing {{tl|av}} later wouldn't be too much work, though.
:I am definitely in favor of changing "DF2014" (or a new namespace) to "Current", though. I was in favor of "DF2014" in 2014, but I don't think it makes sense anymore, and "Current" seemed to be a popular alternative in both the DF2012 and DF2014 discussions on the matter. —[[User:Lethosor|Lethosor]] ([[User talk:Lethosor|talk]]) 04:02, 16 August 2020 (UTC)

== Weird redirect behaviour ==

[[Pump stack]] redirects to [[cv:Screw pump#Pump stack]]. If you look at the redirect itself it says it redirects to DF2014 namespace, which is correct. But if you actually follow the redirect, it goes to v0.34 namespace. [[User:Hairy Dude|Hairy Dude]] ([[User talk:Hairy Dude|talk]]) 16:10, 20 August 2018 (UTC)
:Yeah, that's part of the issue described in the above section (the wiki caching part, not on Google's end.) —[[User:Lethosor|Lethosor]] ([[User talk:Lethosor|talk]]) 15:00, 21 August 2018 (UTC)

== v50 organization ==

Some wiki admins have had a talk on Discord and decided that the most sustainable path forward is to put content for all future versions of DF in the main namespace. We will be working on a bot to do this in the next few days. Feel free to chime in with suggestions here. —[[User:Lethosor|Lethosor]] ([[User talk:Lethosor|talk]]) 22:56, 14 December 2022 (UTC)

:Is it maybe possible to do backwards-namespacing? Like we have a "Main" namespace, which people are free to update, and whenever there's a new version of DF the "Main" namespace is copied into a namespace for the then old version, much like how you'd branch a stable branch from a development branch when working with a git-project? [[User:Therahedwig|Therahedwig]] ([[User talk:Therahedwig|talk]]) 23:13, 14 December 2022 (UTC)

::Yeah, we could do that if we decide to. We were talking about doing that for v50, actually, and might still do something similar to preserve edit history if it doesn't end up being too hard to automate. Our hope is that we will not introduce new namespaces for v50 -> v5x, unless there is a serious breaking change (and hopefully there isn't one). But if we change our mind, one advantage of the type of migration you mentioned is that it can be done retroactively - we can copy historical revisions that were current at the time of the release, and would only lose some typo fixes made after the release that apply to earlier versions as well. —[[User:Lethosor|Lethosor]] ([[User talk:Lethosor|talk]]) 02:11, 15 December 2022 (UTC)

ETA is < 24 hours. Doing some final checks on a migration script. —[[User:Lethosor|Lethosor]] ([[User talk:Lethosor|talk]]) 07:08, 19 December 2022 (UTC)

== v50 migration ==

The initial migration script is done. New content is in the '''main''' namespace, e.g. [[Cat]]. Old content is still at [[DF2014:Cat]]. History was migrated to the ''new'' (main namespace) articles.

I know several things are broken still. Please reply if you find any others:
* Versioned templates haven't been migrated yet (e.g. {{tl|vermin}} on [[Ant]])
** I am working on a script to handle this.
* Raws are missing on all pages that use them.
** This also affects sidebars, such as on [[Cat]] and [[Microcline]].
** This will be addressed with an upgrade to the DFRawFunctions extension. This will take some time because the layout of the raws has changed significantly, so we cannot do a straightforward migration here.

—[[User:Lethosor|Lethosor]] ([[User talk:Lethosor|talk]]) 04:54, 20 December 2022 (UTC)
:The quality levels of the 50.03 pages seem to be missing. I'm not sure if that's covered under that first point. [[User:Trainzack|Trainzack]] ([[User talk:Trainzack|talk]]) 06:47, 20 December 2022 (UTC)

Saved game folder

2022-12-20T06:44:34Z

Trainzack: Reducing article quality as this feature has been greatly changed in 50.01.

{{Quality|Tattered|21:05, 11 May 2013 (UTC)}}
{{av}}

The '''saved game''' files are the files that store a player's progress in ''Dwarf Fortress''. The game can be saved manually or automatically.

The '''saved game folder''' is the location where the files and information corresponding to each [[world generation|world]] (also referred to by, at least, the game, given the default characterisation of the file names as "regions") are stored and accessed by ''Dwarf Fortress''. Knowledge on the technicalities of the saved game folder is crucial if one wishes to change their computer, make a backup, or wants to share a save with someone else.

See also: [[Importing and exporting worlds]].

== Saving ==
At any time when you are playing Dwarf Fortress, you can manually save the game through the escape menu option. Simply hit {{key|Esc}} and then select Save Game. Doing so assumes you want to exit and it will take you back to the main menu. Dwarf Fortress only permits one save per world: there are no do-overs!

You can make use of auto-save feature, which allows to periodically (Seasonally or Yearly) save the game. This can be seen as either a way to prevent loss of progress or removing the ability to correct mistakes and change decisions made during the course of play forcing you to rely on skills instead of on the ability to retry indefinitely. To enable '''auto-save''' functionality and controlling its behavior, see: [[d_init.txt]].

Although the game has permanent death and you might want to play it in that spirit, the game is also in alpha, can crash, and your world can become corrupted by an error. You can make use of a auto-backup feature, which will create a copy of your saves so that you'll have several copies of your world at different times. To enable '''auto-backup''' functionality, see: [[d_init.txt]]. Making backups can save you a lot of grief.

== Save folder format ==
{| class=wikitable style="float:right; margin:10px;"
|
[[File:Folder-orange.svg|20px|link=]] save
 &emsp;[[File:Folder.svg|20px|link=]] current
 &emsp;[[File:Folder.svg|20px|link=]] region#
 &emsp;[[File:Folder.svg|20px|link=]] region#-year-month-day
|}

Your saved games are located in your ''Dwarf Fortress'' [[save game folder]]. The save folder will contain one or more sub-folders, each one holding one of your worlds, and a "current" folder. The "current" folder is used to track the changes to the active world while ''Dwarf Fortress'' is running; it is not important unless ''Dwarf Fortress'' is open, and can safely be deleted otherwise.

By default, individual worlds are saved in the format: ''region#'', where # is a number, starting with region1 and then incrementing; however, world directories can be renamed without consequence '''if the game is not running''' (this will not change the actual name of the world). If using auto-backup, then backup folders will be named ''region#-year-month-day'', for example region1-00202-01-01. (In versions prior to v0.43, the format was ''region#-season-year'' (for example region1-Spring-202) instead.)

This can become confusing if you frequently [[cheating|savescum]]<abbr id="info" class="information" title="To reload the last saved game whenever the player character dies or an unfavorable outcome has been encountered.">‡</abbr>. There is no way to change the name of these folders inside the game, but it is safe to change them using the standard methods of your operating system if the game is not running. However, '''never''' alter or delete the folder with the name of the game you're playing ''while saving'' from the game, or while that game is running!

=== Contents ===
The saved game folder will usually have these contents:

* A subdirectory, ''raw'', containing the raws directly copied from the time the world was generated.
** Inside it, is an ''objects'' folder containing the contents of the raws. This must be kept, but the contents inside can be modified to an extent.
** There is also a ''graphics'' folder for [[Graphics set repository|graphics]] for creatures.
** Finally, there may be an ''interaction examples'' folder. This, along with any files or folders not present in the aforementioned two folders, can be safely deleted.
* A series of files named ''art_image-#.dat''. As their name would suggest, these files store information about art and are necessary for proper functioning. Don't replace!
* A series of files named ''feature-#-#.dat''. These files store information about map features such as [[river]]s, [[cavern]]s, [[magma sea]]s, and [[adamantine|hidden fun stuff]]. These files are only generated for parts of the world you have explored (e.g. by embarking in Fortress mode), but using the Site Finder will tend to generate them for the entire world. Replacing these files will usually cause unwanted effects such as magma seas present on the surface or spires of [[adamantine]] spiraling up into the sky.
* A series of files named ''region_snapshot-#.dat''. These are the historical maps available in [[Legends|Legends mode]].
* A series of files named ''site-#.dat''. These files store the detailed map data of previously abandoned or retired fortresses.
* A series of files named ''unit-#.dat''. These contain the details of historical creatures which might potentially visit your fortress. Prior to version 0.44.10, modifying or deleting these files would lead to the dreaded "Nemesis Unit Load Failed" crash, but now the game will attempt to gracefully recover from such corruption by regenerating the unit from other available information.
* Depending on the mode currently active (or the lack thereof), a large file named ''world.sav'' or ''world.dat''. In [[fortress mode]], this file is named ''world.sav'' and includes the current fortress data, as well as the world data. In a save without a currently active game, this is the main save folder. The custom raws generated for the [[forgotten beast]]s, [[titan]]s, [[demon]]s, [[night creature]]s, and [[Evil|evil effects]] are stored inside this file. Replacing this entire file will almost certainly crash the game; however, replacing certain portions of the raws included may still keep the save folder working.

Missing one or more of the aforementioned important files may indicate a problem with the save; this is a very common source of crashes.

For basic backups, though, all you need to keep to is: Always copy the whole folder, not parts of it.

== Manually backing up saves ==
Toady recommends that you make backups, and always save to a fresh file:

# Copy the relevant region folder in "data/save" to a safe location.
# When you want to reuse it, copy that region back to "data/save".

Do '''not''' overwrite an old folder, as it might leave residual files.

== Restoring saves ==
: ''See also: [[Save compatibility]]''

Restoring a savegame from backup can be very confusing: The game saves back to the directory you loaded, so if you load a seasonal save, the game will save to that folder (e.g. [region1-01056-01-01]) and not to the original folder ([region1]) where you might expect it.

This can cause some high blood pressure and panic when you see your 'Region X' save is several years older than expected, and it might look like you lost all your (fortress/adv party) work to some bug. The "missing" save is, however, going to be in the directory you loaded previously. ''Dwarf Fortress'' lists the in-game year of each save on the right of the load screen; the highest year will generally be the most recent save (unless you've savescummed from earlier saves).

''Dwarf Fortress'' autosaves to the original folder and then copies the save to a backup folder, so you should generally be able to recover from a crash by simply loading the 'main' save folder--it should be as recent as the latest "backup" save. If you want to load a backup savegame, it's recommended that you copy/rename the save to indicate that. For instance, using the examples above, copy [region1-01056-01-01] to [region1-fix] and continue play on that save (creating new backup saves of the form [region1-fix-01056-04-01]). Remember to only modify saves while the game is not running, per the instructions for savescumming above.

'''Warning''': Save folders can be large, ranging from 20 MB for small saves to several hundred megabytes for large saves. If you run out of hard drive space while saving, ''Dwarf Fortress'' will ''pretend'' to save correctly, but the save will be unloadable. Opening other saves to verify that they still work, then saving and exiting, will corrupt your previously-working saves as well. If you don't want the game to save, just kill the application. Make sure you have sufficient free disk space before launching ''Dwarf Fortress''! {{bug|2587}}

==Hints==
On Linux or macOS, you can replace the ''raw'' directory with a symbolic link to ''../../../raw'' if you want to save a few megabytes on every backup. [http://www.bay12forums.com/smf/index.php?topic=145908| Forum thread].

[[Category:Modding]]
[[ru:Saved game folder]]

Dipscript

2022-12-20T06:43:13Z

Trainzack: As this feature was removed in 50.01, the page has been converted into a brief description of the status of this feature (like the economy page).

Graphics

2022-12-20T06:38:04Z

Trainzack: Setting quality to tattered because this system has been entirely changed for 50.XX

{{Quality|Tattered}}{{av}}
:{{for/see|a list of all tile characters used in DF|[[Tilesets]]}}
:{{for/see|a chart with the default ASCII characters|[[Main:Character table|Character table]]}}
:{{for/see|user-created creature tilesets|[[Main:Tileset repository|Tileset repository]]}}
:{{for/see|information about Graphic sets|[[Graphic set|Graphic set]]}}
:{{for/see|information on how tilesets get colored|[[color]]}}
----

Although commonly referred to as text or "ASCII"-graphics, DF uses a bitmap [[tilesets|tileset]]* with characters from the [[Main:Character table|IBM Code Page 437]], displayed with a foreground and background color picked from 16 predefined [[Color scheme|colors]]. Text files (and often hardcoded values) define the tile, and colors of all objects.
Both color scheme and tileset can be changed (see below), and definitions that are in text files can be modified. In addition, interface text can be displayed with a TrueType font and [[creatures]] (which normally are displayed as [[tilesets#list of creatures...|letters]]) can be assigned to separate tilesets called [[graphic set]]s. The main tileset is sometimes called "character tileset", while the graphic sets are also referred to as "object tilesets".

*except when using [[Technical_tricks#Video_Card_Options|PRINT_MODE:TEXT]]
==General Information==
===Tileset===
{{Main|Tilesets}}
The main tileset (also called 'character set' or just 'tileset') is an image in BMP or PNG format that contains the 256 different tiles, corresponding to the [[Main:character table|IBM Code Page 437]], which are used to display all objects, creatures, and UI elements in game. The tiles are always arranged in a 16x16 grid, but its dimensions can be varied. You can have both square and non-square tiles, with 16x16 pixels being the most common size. Creatures are displayed as [[Tilesets#Main_creature_tiles|colored letters]] (a white 'B' is a [[polar bear]], a brown 'd' a [[dog]], and a grey 'c' is a [[cat]]).

As the tileset is limited to only 256 tiles, some objects share the same tile. Most notably, even with upper and lower case letters and 16 colors, a lot of creatures still look identical (goblin, goat, various gibbons, gremlin, goose, etc). The tile for bins, up/down stairs and the cursor are the same; bags use the same tile as the symbol for "male"; and the "female" symbol shares a graphic with amulets. Roads and large rivers on the world map, minecart tracks and walls all share the same tiles as well.

Some of those can be changed in the raws and init files, and creatures can have separate graphics, but in most cases they are hardcoded.

That also can be used to categorize custom tilesets: Those that are made for and come bundled with modified raws/init files, and those that are made for and work with the default raws. Usually, the latter are more symbolic, or 'ASCII-like', while the former are often more pictographic, detailed or "pixel-arty". These sometimes are also bundled with their own creature graphics.
Tilesets that are made for default raws have the advantage that you can use them immediately without any work for any new version that is released. With modified raws, you need to manually edit the new raws again, or wait for the maintainer to do that.

===Graphic set===
{{Main|Graphic set}}
Graphic sets are additional tilesets used to give objects different graphics. As opposed to the main tileset, any number of tiles can be arranged in any grid configuration. Currently, DF only supports graphic sets for creatures. Every graphic set needs a corresponding text file that assigns a tile to a creature.

=== Color ===
{{Main|Color}}
In general, a tileset has white tiles with a transparent background. White pixels show the foreground color, transparent pixels (magenta pixels for .bmp) the background color. Black pixels remain black. Shades of grey, partial transparency and even colored tiles can be used for various effects. Additionally, creature graphics can be set to be displayed in the colors they're drawn in.

Otherwise, the game selects from 16 colors (the [[color scheme]]) to decide the color: which of the 16 colors the game uses depends on the [[Color#Color_values|color value]] or [[Color#Color_tokens|color token]] of the material/item.

==Installation==
{{further information|Tilesets|Graphic set|Color scheme}}
===Repositories===
The wiki has repositories for [[Main:Tileset_repository|tilesets]], [[Graphics_set_repository|graphic sets]], and [[color scheme]]s. You will find more in the [http://www.bay12forums.com/smf/index.php?board=28.0 bay 12 graphics subforum] and on [http://dffd.wimbli.com/ DFFD]. Some graphic sets and tilesets are additionally maintained on [https://github.com/DFgraphics github].
Often, tileset creators offer preinstalled downloads or folders you just have to drop into your DF folder and overwrite files when prompted. They usually come with installation instructions either in a readme file or in their respective forum thread. In addition, there are various [[Utilities#Launchers|launcher]] applications that let you install and change graphics automatically.

For manual installation of the various components, see here:

===Tileset===
Put the tileset you want to use into the data/art/ folder. Open up [[init.txt]] (in data/init/) with a text editor and change the entries FONT, FULLFONT, GRAPHICS_FONT, and GRAPHICS_FULLFONT to the filename of your new tileset.
===Creature Graphics===
Put the graphic set ''into a subfolder'' in raw/graphics and the corresponding text file directly in raw/graphics. If you have an active save you will have to put them into the raw folder of your save as well (data/save/<your region>/raw/graphics). Finally, set GRAPHICS to YES in data/init/[[init.txt]]

===Color Scheme===
Replace colors.txt in data/init with your new colors.
===True Type Font===
Replace font.ttf in data/art with your new font.
{{Category| Interface}}

Talk:Main Page

2022-12-17T14:37:08Z

Trainzack: /* steam release */

{{Archive|
# [[Talk:Main Page/archive1|Archive 1]]
# [[Talk:Main Page/archive2|Archive 2]]
# [[Talk:Main Page/archive3|Archive 3]]
}}

== How to create a new language page? ==

I've just seen one dwarf requesting a Japanese page.

If possible, I'll gladly translate this wiki into Korean. Korea is relatively a small country so the language is not that widely used, but surely there are some players, I guess.

I don't know where to ask about this :9

== Free SSL Certificate ==

If the operators want to re-enable https, they can get a free (as in beer) certificate from https://letsencrypt.org/ . Instructions are on that site and it's very easy.
:HTTPS is enabled now as of the June 2019 upgrades. —[[User:Lethosor|Lethosor]] ([[User talk:Lethosor|talk]]) 22:53, 3 July 2019 (UTC)

== Re: Discord ==

I notice there's a Discord on this page. But shouldn't it be the Kitfox Games Discord, since that's the only official Discord for Dwarf Fortress?

[[User:AlastríonaCatskill|AlastríonaCatskill]] ([[User talk:AlastríonaCatskill|talk]]) 13:43, 12 February 2020 (UTC)
;I wasn't aware of it. If that is the case, then it should probably be added to the page. [[User:OluapPlayer|OluapPlayer]] ([[User talk:OluapPlayer|talk]]) 16:03, 12 February 2020 (UTC)

Yeah, the only reason there is one at all is because somebody added some random one. I changed it to the only DF discord I knew of at the time. The only way I've now been able to find it is to search for 'Kitfox Games discord'. It's not listed on the bay12 links page, a forum thread, the reddit, or the Steam pages. Anyway, I've DMed Victoria on the KitfoxGames discord to make sure they're OK with adding the invite to this page. [[User:Ziusudra|Ziusudra]] ([[User talk:Ziusudra|talk]]) 20:08, 12 February 2020 (UTC)

...Sorry, is it too late for this? I mean, while we're still discussing this, it looks like [https://dwarffortresswiki.org/index.php/Talk:Main_Page#B12G_Discord someone else got left behind as well]. Add, or not? [[User:Silverwing235|Silverwing235]] ([[User talk:Silverwing235|talk]]) 22:21, 12 February 2020 (UTC)

I'm not sure what you were trying to link to. Do you mean this: http://www.bay12forums.com/smf/index.php?topic=163555.0 Note that the thread was locked because of drama. There's a lot of red flags: the drama, despite using the name Bay12Games it never uses the word 'unofficial', the rules channel posts are from a deleted user, the announcements channel hasn't updated in well over a year, many channels haven't been active in months. I'm not so much saying no, but I am asking: should it be linked?

There's also this: http://www.bay12forums.com/smf/index.php?topic=157332.0 But that invite is invalid. [[User:Ziusudra|Ziusudra]] ([[User talk:Ziusudra|talk]]) 02:35, 13 February 2020 (UTC)

Ah, it's a ''dead'' discord. I see now. There was just no response to the April '17 topic, I stumbled across it all and got curious. No, I don't think it should be linked. Thanks for the analysis, anyway! [[User:Silverwing235|Silverwing235]] ([[User talk:Silverwing235|talk]]) 11:44, 13 February 2020 (UTC)

== [[Multithreading]] ==

Would it be OK to create [[Multithreading]] page describing why (preferably with citations)
* even perfectly implemented boost would not be significant
* multithreading is not something that can be bolted on complex program
* DF is complicated case where taking advantage of multithreading is not obvious http://www.bay12forums.com/smf/index.php?topic=34311.msg7833713#msg7833713
* DF is filled with many gamebreaking bugs unfixed for many years, multithreading bugs are unusually awful to fix
* author of DF has minimal experiences with multithreading
* writing multithreaded code is hard
* writing correct multithreaded code is awfully hard
* fixing bugs in a multithreaded code is nightmare

and multithreading is not going to happen, ever

http://www.bay12forums.com/smf/index.php?topic=34311.msg7833713#msg7833713
http://www.bay12forums.com/smf/index.php?topic=107833.0
https://bholley.net/blog/2015/must-be-this-tall-to-write-multi-threaded-code.html + “At Mozilla, there is a sign on the wall behind one of our engineer’s desks. The sign has a dark horizontal line, below which is the text, ‘You must be this tall to write multi-threaded code.’ The line is roughly nine feet off the ground. We created Rust to allow us to lower that sign.” http://www.oreilly.com/programming/free/files/why-rust.pdf

[[User:Mko|Mko]] ([[User talk:Mko|talk]]) 03:07, 28 March 2020 (UTC)
:I disagree with some of your talking points
:* In DF each AI actor makes its own decisions, the computations can be done in parallel for an ncores speedup
:* This parallelism should be built into the lowest design levels of the program, it can be done in a DF-like program
:* With training and experience a good developer can write and debug multithreaded code.
:I agree that multithreading is unlikely to be done in DF; It can not easily be bolted on and I rather see the developer spend time on game-play.
:Is it worth to create a wiki page for what is essentially a one line explanation?
:--[[User:MathFox|MathFox]] ([[User talk:MathFox|talk]]) 18:40, 31 March 2020 (UTC)
::We would essentially be writing a page about a thing that doesn't matter to Dwarf Fortress. I can't agree to the existence of a page that's basically "This subject doesn't exist in the context of the game but here's the reasons why it should or shouldn't". This is better reserved for forum discussion, not a wiki. [[User:OluapPlayer|OluapPlayer]] ([[User talk:OluapPlayer|talk]]) 12:54, 1 April 2020 (UTC)

== Re: Discord II ==

Good morning.

I was confiding with some friends, who had alerted me to the "Unofficial Bay 12 Discord" posted on this Wiki. Simply put, allegations of the use of ableist slurs were thrown, as well as screenshot evidence of using hard racist slurs against people of colour.

I feel that the Unofficial Discord should hereby be removed from the social media part of the website for the following reasons:
* No official connection to Bay 12 or the publishers [and, by extension, every non-Bay12 forum should be removed - especially dead ones]
* This unofficial Discord is actively opposed to the standpoints that Toady One and Threetoe have posted on the bay12games site over the recent days.
* This unofficial Discord uses slurs and other problematic language that actively harms the image of the Dwarf Fortress community
* This unofficial Discord will likely make it so that people steer away from the game.

I do not feel comfortable with the Wiki platforming a known racist Discord server, as that is de facto support of the messages of that server.
[[User:AlastríonaCatskill|AlastríonaCatskill]] ([[User talk:AlastríonaCatskill|talk]]) 12:02, 21 June 2020 (UTC)

Update: Apparently, this same Discord has been banned from the r/dwarffortress subreddit for as long as one of the mods can remember, and the link to it was banned on the official Kitfox Discord as well. I can post the screenshots I have of actively problematic behaviour on this Discord but I will not do it unless necessary, as the contents are alarming like that which will not be named. [[User:AlastríonaCatskill|AlastríonaCatskill]] ([[User talk:AlastríonaCatskill|talk]]) 12:10, 21 June 2020 (UTC)

:I've removed the link. Safe to say, we don't need the wiki to be associated with this sort of people. [[User:OluapPlayer|OluapPlayer]] ([[User talk:OluapPlayer|talk]]) 21:58, 21 June 2020 (UTC)

::The "Unofficial Bay 12 Discord" was already not linked on the main page - the only place it was mentioned is this talk page. Are you talking about that one or the Unofficial Dwarf Fortress Discord that is linked on the main page? The latter does have it's #elfposting channel, but that channel is initially hidden, opt-in only, and clearly labelled as a lawless zone. For an analogy, there are many very awful subreddits, but we still link to reddit - (yeah that's a little different but not much). Otherwise the unofficial DF discord is well modded and such behavior is not allowed in other channels. So, are you certain which discord/channel the screenshots came from? [[User:Ziusudra|Ziusudra]] ([[User talk:Ziusudra|talk]]) 22:29, 21 June 2020 (UTC)

Since there's some confusion, AlastríonaCatskill, could you confirm and/or provide some evidence that following the link that was on the main page (removed in [https://dwarffortresswiki.org/index.php?title=Main_Page&diff=253449&oldid=251109]) takes you to the discord that you were referring to? The only reference I can find to a discord removed from the /r/dwarffortress sidebar is for a different discord, not the one that was linked on the main page (although it's possible that just the invite link was different). I just want to make sure that we're removing the right one here. If you have anything that you don't want to share publicly, you can PM me on the forums (same username) or [[Special:EmailUser/Lethosor|email me]] through the wiki, which I think is working. —[[User:Lethosor|Lethosor]] ([[User talk:Lethosor|talk]]) 01:45, 22 June 2020 (UTC)

:@Lethosor, I have emailed you the relevant images via the link you had created. The Discord that was on the main page and removed today is indeed what was being referred to, especially with the confirmation of the #elfposting channel being from said Discord. In my opinion, @Ziusudra, the inclusion of a problematic part of that community, even as opt-in, is unacceptable in my book for a community to be platformed on this Wiki. [[User:AlastríonaCatskill|AlastríonaCatskill]] ([[User talk:AlastríonaCatskill|talk]]) 03:26, 22 June 2020 (UTC)

Hello, I am the owner of the Unofficial Dwarf Fortress discord. I just want to clear a few things up and open a channel of communication.
Several years ago, the original owner of the discord left, in no small part due to all the sexism and racism and such.
After a few days of an having an interim owner, it was given to another user, who onboarded several users as admins, including me.
The new owner tried a lot to curb terrible stuff on the server, however this often lead to drama.

The r/dwarffortress delisting happened after some of that drama spawned a new discord with a more "free speech" orientation,
things spilling over to the forums and other places. Some time after that, she left the server to me, due to the amount of
stress running that place caused her. When I took over I also tried to make it a better place, but with slower and subtler
methods that wouldn't spark drama. Completely disallowing some behaviour outside of #elfposting was part of that,
and later making that channel hidden by default was another. Now, the discord is much much better to be in
than it ever was before, though it still has major flaws. I don't like #elfposting at all myself, but I don't rule with an iron fist nor
do I know what much I can do without sparking massive drama again. Since April this year I have had some plans to make the discord
quite a bit better, however some of my mods have been against it in part due to feeling it would cause bigger problems
(though, as you probably know, some of them participate in #elfposting).
With recent events, both within and outside the DF community, we have decided to move ahead, every mod on board,
with some plans including phasing out the #elfposting channel in a way which will not create large issues for moderation.
It will be fully gone within one (1) week of now.

Also, I am a tad annoyed that you posted about this here but completely neglected contacting us. In the future, could you
please contact me or one of my mods when you have any concerns about the server? I really do care about these things and we need feedback.
—[[User:Lonjil|Lonjil]] ([[User talk:Lonjil|talk]]) 10:32, 22 June 2020 (UTC)

: Thank you for replying here Lonjil. Unfortunately, I cannot trust your take on this matter for several reasons.
: # One of the moderators has an anti-semitic stereotype profile picture
: # Even if the only place of no censorship is the elfposting channel, and even if it is opt-in, the complete chaos of racist slurs allowed there is completely unacceptable for minority players and an extremely toxic environment. There have been instances of straight hate speech on the channel / server as well, suggesting to kill people of colour and LGBTQIAA+ people.
: In short, the toxicity of your Discord's community makes it not just uncomfortable, but downright dangerous for minority people playing Dwarf Fortress. As Tarn and Zach have made liberal-to-leftist political views in the past, the chances of minorities to play the game is higher - and I wouldn't want to be a person of colour signing up for a shitposting channel to only be met with over 10,000 instances of the hard-n word being used. The Discord should remain off of the Wiki until things shape up and all instances of hate speech be purged from server history. Personally I would rather all non-official channels of communication be removed from the page, period, but that is a less pressing discussion than active hatred of minorities being platformed on the Wiki via your unofficial Discord. [[User:AlastríonaCatskill|AlastríonaCatskill]] ([[User talk:AlastríonaCatskill|talk]]) 12:30, 22 June 2020 (UTC)

:: Small edit / follow-up to my previous message. My friend tells me that elfposting is the most commonly used channel, which goes to show the level of hatred allowed into the community. It may be best to remove the channel in entirety, and make a new meme channel with no hate speech allowed. [[User:AlastríonaCatskill|AlastríonaCatskill]] ([[User talk:AlastríonaCatskill|talk]]) 12:33, 22 June 2020 (UTC)

::: The admin you are referring to is a jew, who lives in Israel. I prefer to not police people of other ethnicities when it comes to negative stereotypes and such of themselves, they know what they are comfortable with far better than I ever could.

::: Elfposting is not, by any reasonable measure, the most used channel. It has fewer users than any other channel. It has a fair number of messages, but only because there is no rule against spamming in there. So, nearly all of it is spam, which was the point of the channel to begin with.

::: "It may be best to remove the channel in entirety" this is exactly what is happening, as I already said. We're giving the channel regulars a few days to hear the news, but then the channel will be gone. We already have a more pleasant meme channel from an experiment we did in April, which we are bringing back. —[[User:Lonjil|Lonjil]] ([[User talk:Lonjil|talk]]) 13:57, 22 June 2020 (UTC)

Hi all - thanks for keeping this discussion civil. I've been investigating the policies of other DF communities, and I've come to the conclusion that it would be best for the wiki to only link to the official DF Discord (Kitfox). I'll also make a pass through the other sites linked on the main page. I'm sorry to those of you working hard to maintain Discords and other unofficial communities out there - I know it's difficult, and I don't want to judge your communities without being a part of them. However, there will always be debates like these about whether a community deserves to be linked from a more "official" place, like the wiki, and no matter where we draw the line(s), people will be upset. The policy of only linking to the Kitfox Discord seems to have worked for other communities, which is why I'm applying it here. I would be happy to have a broader discussion at [[DF:Centralized Discussion]] if anyone wants to. —[[User:Lethosor|Lethosor]] ([[User talk:Lethosor|talk]]) 01:48, 23 June 2020 (UTC)

== Put Chinese language wiki on other Languages ==
Found it on Internet([http://cdf.wikidot.com/start]) – [[template:unsigned|unsigned]] comment by [[User:45.58.187.66|45.58.187.66]]

:I added a link to it. I'm not sure what the process is for adding interwiki link support (support for links to pages in the sidebar, like how [[DF2014:Cat]] links to http://dfwk.ru/Cat) but I can look into that too. —[[User:Lethosor|Lethosor]] ([[User talk:Lethosor|talk]]) 01:40, 19 August 2020 (UTC)
::Hello! I'm the admin of [https://dfzh.huijiwiki.com/ Chinese Dwarf Fortress wiki], and I've previous put its link on the main page. We've now enabled interwiki link from our site to English site, and we wish to get one back from English site to CN site as well. Hope that is possible, and thanks so much! The URL for our site should be: <code>https://dfzh.huijiwiki.com/wiki/$1</code> [[User:Xjtu-blacksmith|xjtu-blacksmith 黑山雁]] ([[User talk:Xjtu-blacksmith|talk]]) 11:26, 1 November 2022 (UTC)

:::Added. Prefix is "zh", for example: https://dwarffortresswiki.org/index.php?title=Main_Page&diff=266849&oldid=266730 —[[User:Lethosor|Lethosor]] ([[User talk:Lethosor|talk]]) 19:45, 28 November 2022 (UTC)

== Villains Wiki ==

To started putting some creatures on the Villains Wiki, because I want to spread the word of Dwarf Fortress around, and these creatures fit the theme of the wiki anyway. Here's an example page, and the template of all pages: 
[https://villains.fandom.com/wiki/Goblins_(Dwarf_Fortress) Villains - Goblins] 
[https://villains.fandom.com/wiki/Template:Dwarf_Fortress_Villains Villains - Template of DF Villains]

If anyone could add more info to those pages, or think more creatures should be on that wiki, please let me know. Or you could add it yourself. -- [[User:Zippy|Zippy]] ([[User talk:Zippy|talk]]) 13:37, 9 January 2021 (UTC)

== Replace Chinese Wiki with the new one on Fandom ==

The previous Chinese wiki on wikidot seems to be inactive for a long time, with its main page refers to the download link of v0.44.10, and most pages are never updated even earlier than that version. Recently we are working on a new site on Fandom ([https://dwarf-fortress.fandom.com/zh]), trying to keep everything up to date. Wish to replace the links on dwarffortresswiki's main page and the sidebar link (inter-language link) with the one at Fandom, so that more people may get to the right place and join us. [[User:Xjtu-blacksmith|xjtu-blacksmith 黑山雁]] ([[User talk:Xjtu-blacksmith|talk]]) 04:16, 30 December 2021 (UTC)

:I've added the link of Fandom site onto the main page, without removing the previous one. [[User:Xjtu-blacksmith|xjtu-blacksmith 黑山雁]] ([[User talk:Xjtu-blacksmith|talk]]) 11:09, 12 May 2022 (UTC)
:We've migrated Chinese Wiki to huijiwiki.com, which is now shown on Main Page. [[User:Xjtu-blacksmith|xjtu-blacksmith 黑山雁]] ([[User talk:Xjtu-blacksmith|talk]]) 07:41, 29 May 2022 (UTC)

::Added. The "zh" prefix should work for links. —[[User:Lethosor|Lethosor]] ([[User talk:Lethosor|talk]]) 19:43, 28 November 2022 (UTC)

== Kitfox Discord ==

<blockquote>
''2022-04-15 BlueManedHawk . . (8,594 bytes) (-135)‎ . . (The Kitfox Games discord server has an unethical code of law. I don't think the wiki should be supporting it.)''

''2022-04-15 Ziusudra . . (8,729 bytes) (+135)‎ . . (Undo revision 263652 by BlueManedHawk[:] please discuss changes such as this on the talk page first) (Tag: Undo)''
</blockquote>

Alright, I can do that.

The Kitfox Games discord server has a code of law that contains the following immoralities:

:- Is very vague and nebulous, allowing the moderators to exploit the vagueness to be able to do very different things in similar circumstances in alignment with their biases. (Not that they do that, but the fact that it's possible is concerning.) 
:- Contains a "These rules are subject to common sense." clause, essentially meaning that the moderators are able to do whatever they want and hide it behind the barrier of "common sense". This goes completely against the point of the concept of rules in the first place as a promise from those in power in regards to what they will and will not do. 
:- Allows for infinite punishment.

That last one could do with a bit of explaining. Let us begin with the premise that the punishment for a crime should be proportional to the severity of the crime. I think we can all agree on this. Therefore, an infinite punishment should only ever be given for an infinite crime. However, humans are not infallible. People make mistakes. And this means that if a court of law is able to administer an infinite punishment, they run the risk of accidentally giving somebody an infinite punishment that they do not deserve. This, I think we can all agree, is unnacceptable. Therefore, infinite punishment cannot every be administered ethically.

I hope that this explains why I want the link to the Kitfox games discord removed.

Regards,

—[[User:BlueManedHawk|BlueManedHawk]] ([[User talk:BlueManedHawk|talk]]) 22:29, 15 April 2022 (UTC)
:* Their rules are not vague or nebulous, they even give examples of what the rules cover. Of all the discords I am on, their rules are some of the most detailed.
:* The "''depending on the action and our judgement''" is quite similar to the "''depending on how disruptive you were and your prior history''" found in the DF forum rules, and is pretty standard social media boilerplate and is itself common sense.
:* Their rules state "''Breaking these rules will result in a warning or ban''", which is not at all "''infinite punishment''", and is again quite similar to the "''If you violate the guidelines, you will be warned, muted for a period of days, or banned completely''" on the forums. It's not like they can keep anyone from playing the game or interacting with the other communities.
: Your referring to their rules as "code of law" is hyperbolic. Their rules are quite similar to the rules of the forum. So, I disagree and think the link should stay. [[User:Ziusudra|Ziusudra]] ([[User talk:Ziusudra|talk]]) 23:13, 15 April 2022 (UTC)
::* The rules are pretty vague. Examples aren't enough. A strict, clear, unambiguous definition is necessary to prevent abuse.
::* While it is true that their clause is ''normal'', that doesn't mean it's ''right''.
::* The explanation of bans doesn't explain how long the bans will last. Since there's nothing explicitly stating that infinite punishment won't be given, and since "ban" by itself generally refers to a permanent ban, I think that it's allowing infinite punishment.
::* I'm not sure how the term "code of law" is hyperbolic. I use the term synonymously with "set of rules".
::* I can't seem to find a code of law for the forums. However, if what you said is true, then clearly we should also remove the link to the forums.
::
:: Regards,
::
:: —[[User:BlueManedHawk|BlueManedHawk]] ([[User talk:BlueManedHawk|talk]]) 02:59, 16 April 2022 (UTC)
::: http://www.bay12forums.com/smf/index.php?topic=27009 It's linked in the header at the top of every forum page, though if the header is collapsed you won't see it.
::: Unambiguous rules are technically impossible since human behavior is limitless. That's why we hav judges for actual laws - even society's strictest laws need a human adjudicator. Then, even with "permanent bans", both Kitfox and Bay12 hav public email addresses and twitter accounts which can be used to petition to hav a ban removed.
::: Finally, suggesting the removal of the links to the official forums for the game this wiki is dedicated to is unreasonable, to the point of making me wonder if you're trolling. [[User:Ziusudra|Ziusudra]] ([[User talk:Ziusudra|talk]]) 04:59, 16 April 2022 (UTC)

::::I agree with Ziusudra. More broadly, I think we should keep links to "official" DF channels, and Kitfox is a DF publisher. If a potential for "infinite punishment" warrants removing links to the offending site, then by your logic, we should remove all links to the wiki from the wiki because users here have been banned permanently. That has been done based on the best judgement of the people who volunteer their time to run the wiki and has been open to appeals, and I expect other channels are similar. I'm not interested in entertaining this argument here. If you have specific issues with a specific external site, I suggest that you get in touch with the moderators there instead. —[[User:Lethosor|Lethosor]] ([[User talk:Lethosor|talk]]) 05:34, 16 April 2022 (UTC)

:::::Hello.

:::::As I mentioned below, the DFWiki is in a position of power, and by removing the link to them, we can potentially force their hand into making their code of law more moral. On the other hand, keeping the link there could potentially be seen as supporting their immoral behavior, tarnishing the reputation of the site. This is why I brought up my issues with an external site onto this one: because these issues also affect it.

:::::It is true that by my logic, the DFwiki is operating immorally. However, I would like to mention that ''you are in a position of power on the wiki'', Lethosor. I would think that you have the ability to change the Wiki's code of law to be more moral. You have the choice to make the wiki a better place, and I advise that you take it.

:::::Regards,

:::::—[[User:BlueManedHawk|BlueManedHawk]] ([[User talk:BlueManedHawk|talk]]) 06:22, 16 April 2022 (UTC)

::::Hello.

::::* I don't know which header you're referring to—wherever it is, it seems to not be there for me. Regardless, I thank you for clarifying which guidelines you were referring to.
::::* Unambiguous rules are largely impossible because nobody has yet created an unambiguous language. However, that doesn't mean that we shouldn't still seek to get as close to unambiguous as possible when constructing a code of law.
::::* Claiming that the bans are transient because it's possible to appeal them is optimistic, and while there is a place for optimism, this is not it. Any potential that a legal system has for corruption is one that we cannot assume will not be used, and often, corruption begets corruption, continuing the cycle until a revolution happens.
::::* Being a central repository of knowledge on DF, the DFwiki is in a position of power. If we do remove the link to the Kitfox discord under the condition that they make their code of law more moral, then we can theoretically force their hand, maybe. There is, of course, a risk to this, and this should be deliberated before a decision is made.
::::* I am not a troll. Why does everybody keep thinking that?

::::Regards,

::::—[[User:BlueManedHawk|BlueManedHawk]] ([[User talk:BlueManedHawk|talk]]) 06:22, 16 April 2022 (UTC)

== Advertisements problem ==

One of the full-page advertisements(a pop-up that obscures the whole page) had what looked like a "close" button, but it just tried to redirect me to another page.
Full page advertisments aren't untoward but like, web elements that say 'close' are expected to do what they say, otherwise it's intercepting clicks. – [[template:unsigned|unsigned]] comment by [[User:Eerr|Eerr]]

:Do you have a screenshot of the offending ad, or can you take one if it happens again? My understanding is that that is something we (admins) don't have control over, but we can report misleading ads to Google. —[[User:Lethosor|Lethosor]] ([[User talk:Lethosor|talk]]) 03:09, 2 June 2022 (UTC)

== Kitfox Discord (again) ==

Hi. I'm again requesting the removal of the link to the Kitfox discord server for only two reasons this time: the code of law gives infinite power to the moderators, and the criminal justice system uses punishment to deal with criminals. These are obviously both immoral, and until the server fixes these issues, the DF wiki ought to remove the link so as not to seem to be promoting them. [[User:BlueManedHawk|BlueManedHawk]] ([[User talk:BlueManedHawk|talk]]) 21:45, 15 September 2022 (UTC)
:And again, I don't support removing the official publisher's discord just because you think that there is some thing wrong with their completely normal and reasonable moderation practices, none of which involves "infinite power", "punishment", "criminals", or other such hyperbole. Banning is not "punishment", it is protection of the community from those that act to harm it, nor is it "infinite power" since all it does is keep those rule breakers off one discord server and nothing else. All of which also happens on both the Bay12 Forums and this very wiki, both of which, by your logic, you should immediately stop using lest you appear to be promoting them. [[User:Ziusudra|Ziusudra]] ([[User talk:Ziusudra|talk]]) 03:45, 16 September 2022 (UTC)
::Normalizing of horribly unethical practices is not okay. I do not think it is hyperbole to use the terms "infinite power, "punishment", and "criminals". The server is a jurisdiction like any other, and it should be held to the same standards of morality as any other—this includes not using punishment as a means to deal with those who break the law. It is completely possible to protect the community without using bans—bans simply get rid of problems instead of fixing them, and are ineffective against the diligent. Infinite power is not an okay thing to give to those who govern a jurisdiction—dictatorial power structures have been shown to fail many times over throughout history.
::
::If we simply must keep any official venues for DF on the main page, regardless of morality (this includes the forums, which i agree should also be removed), then the Wiki ought to put a disclaimer of some sort clarifying that they are being listed not in support of the governance policies of the communities, but simply because they are official.
::
::[[User:BlueManedHawk|BlueManedHawk]] ([[User talk:BlueManedHawk|talk]]) 17:24, 17 September 2022 (UTC)
:::Good god, how many of these discussions are you gonna keep making? Is there anything that ''doesn't'' offend you? -- [[User:Zippy|Zippy]] ([[User talk:Zippy|talk]]) 13:14, 22 September 2022 (UTC)
::::There's no need to be rude. But to answer your question, i'm going to have as many discussions as are necessary until a concensus is reached. [[User:BlueManedHawk|BlueManedHawk]] ([[User talk:BlueManedHawk|talk]]) 21:43, 22 September 2022 (UTC)
:::::You can't keep just keep making constant requests of "guys can we please remove that and that and that and this and this because of like business and anti-competitive stuff and yeah and like" but then turn around and go "why does everyone think I'm a troll?" Can you seriously not connect those two things together? I've been part of this community for a long time, and you are the one and only person who gets all offended by things that no one else would even care to think about. This wiki is not the place for that. -- [[User:Zippy|Zippy]] ([[User talk:Zippy|talk]]) 10:48, 23 September 2022 (UTC)
::::::I really don't understand why people think that i'm a troll. If you or someone else were to explain it to me in a manner that's more polite than your previous messages have been, i'd be happy to listen. [[User:BlueManedHawk|BlueManedHawk]] ([[User talk:BlueManedHawk|talk]]) 20:18, 23 September 2022 (UTC)
:::::::Hmmmmmmm, no. I'm gonna skip the "polite" thing and just speak the truth. No regrets. The fact that you can't see why people think you're a troll makes the situation even worse. You're someone who got all bent out of shape over a Minecraft diamond reference, something that no one else would ever care about. You keep saying you don't see how people think you're a troll when it was explained to you many times. All this goofy legal stuff you keep bringing up is best left elsewhere. Not here. -- [[User:Zippy|Zippy]] ([[User talk:Zippy|talk]]) 13:59, 24 September 2022 (UTC)

== Wiki logo ==

The new wiki logo requires getting used to. Personally, I wouldn't mind something simpler like [[:File:Dfhack-logo.png|DFhacks]] with a more fancy version going to the mainpage. Maybe someone from the community can come up with something, here is what [https://ibb.co/26J569S my meager skill] able to come up with --[[User:Jan|Jan]] ([[User talk:Jan|talk]]) 13:20, 7 December 2022 (UTC)
:I just noticed it and I have to agree. It's like being hit in the face with a brick. It references DF relatively deep lore ([[obsidian]] and [[semi-molten rock]]) and it feels way too harsh compared to the relatively relatable and much more early-game relevant icon of a dwarf mining. --[[User:Lurker|Lurker]] ([[User talk:Lurker|talk]]) 13:01, 10 December 2022 (UTC)
:: For reference here is the [[:File:DFDefault.png|digger]] from the classic intro and bellow rendering of what steam version uses in its loading phase, as well as [https://ibb.co/mtzdLm3 this simple variant]
<diagram>
¦¦¦¦¦¦
¦ ¦
¦ ¦
¦ ¦ ¦ ¦
▒ ▒
▒▒▒▒▒▒▒▒
▒▒ ¦¦ ▒▒
▒▒▒▒▒▒
▒▒▒
▒▒
</diagram> --[[User:Jan|Jan]] ([[User talk:Jan|talk]]) 15:39, 11 December 2022 (UTC)

== steam release ==

: "''We are working on a migration that will be complete in the next few days''"
Any estimate on how long that is going to take? --[[User:Jan|Jan]] ([[User talk:Jan|talk]]) 08:53, 10 December 2022 (UTC)
: Additionally, who is working on this wiki migration, and why is it a closed process? I feel like the migration could have been largely completed by now if everyone was able to help, but that sentiment may just be coming from my ignorance. [[User:Trainzack|Trainzack]] ([[User talk:Trainzack|talk]]) 00:40, 17 December 2022 (UTC)
::See thread at [[Dwarf_Fortress_Wiki_talk:Versions#v50_organization]]. Emi and I are planning to use a MediaWiki bot for this. My current ETA is 2 days from now. I've asked for help in a few places to write such a bot and have had no responses. My concern with a manual migration (e.g. if we have people copy over just some pages manually) is that it would likely result in a state that is much more complicated to finish. I'm sorry it hasn't gotten done yet. Open to help with automating this. —[[User:Lethosor|Lethosor]] ([[User talk:Lethosor|talk]]) 04:39, 17 December 2022 (UTC)
:::Ah, that page completely eluded me! Thanks for pointing in that direction. I would be totally willing to help write a bot, just let me know what I can do. [[User:Trainzack|Trainzack]] ([[User talk:Trainzack|talk]]) 14:37, 17 December 2022 (UTC)

Talk:Main Page

2022-12-17T00:41:07Z

Trainzack: /* steam release */

Reaction

2022-11-25T04:20:30Z

Trainzack: Fix [SKILL_ROLE_RANGE] typo

{{Quality|Superior|19:56, 28 August 2013 (UTC)}}
{{av}}
{{Modding}}

'''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 token assigns a unique ID to your reaction.
[REACTION:<reaction identifier>]

The ''reaction identifier'' may be anything, so long as it is unique within the raw data files. A good habit to get into is to append a short prefix or suffix to each name related to the name of your mod, to ensure nobody else is going to make an identical reaction and thereby mess up the game if their mod is run alongside yours. This is referenced in an entity definition via [[Entity_token#PERMITTED_REACTION|PERMITTED_REACTION]] to allow that entity to use the reaction.

=== Reaction name ===
The REACTION_NAME token assigns a descriptive name to your reaction in-game.
[REACTION_NAME:<name>]

==== name ====
This can be anything at all, and is how the reaction will appear in the job list of the building it is assigned to, and so should describe the reaction. '''Tan a hide''', for example, is the name of the default leather-producing reaction. Generally this should be written as a small descriptive verb phrase, with the first letter capitalized, for consistency with the existing reactions.

=== Building ===
The BUILDING token assigns the reaction to a building. Adding multiple BUILDING tokens will cause the reaction to be available at all of the specified buildings. Omitting the BUILDING token entirely will make the reaction unusable in Fortress mode (often used to restrict certain reactions to [[Reaction#Adventure_Mode_enabled|Adventure mode]]).

[BUILDING:<building name>:<building key>]
* [[#building name|''building name:'']] The ID of the building the reaction appears in.
* [[#building key|''building key:'']] The hotkey to queue up the reaction in the specified building.

==== building name ====
This is the ID of the building where the reaction will be carried out. Valid building names are as follows:

* ASHERY{{version|0.42.01}} - [[Ashery]]
* BOWYER{{version|0.42.01}} - [[Bowyer's workshop]]
* CARPENTER{{version|0.42.01}} - [[Carpenter's workshop]]
* CLOTHES{{version|0.42.01}} - [[Clothier's shop]]
* CRAFTSMAN - [[Craftsdwarf's workshop]]
* FARMER - [[Farmer's workshop]]
* GLASS{{version|0.42.01}} - [[Glass furnace]]
* KILN - [[Kiln]] and [[Magma kiln]]
* KITCHEN - [[Kitchen]]
* LEATHER{{version|0.42.01}} - [[Leather works]]
* MASON{{version|0.42.01}} - [[Mason's workshop]]
* METALSMITH{{version|0.42.01}} - [[Metalsmith's forge]]
* MILLSTONE - [[Millstone]]
* QUERN - [[Quern]]
* SIEGE{{version|0.42.01}} - [[Siege workshop]]
* SMELTER - [[Smelter]] and [[Magma smelter]]
* STILL - [[Still]]
* TANNER - [[Tanner's shop]]
* WOOD{{version|0.42.01}} - [[Wood furnace]]
* Any custom (raw-defined) building, such as:
** SOAP_MAKER - [[Soap maker's workshop]]
** SCREW_PRESS - [[Screw press]]

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

=== Category ===

{{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 || Hotkey token || Optional. If present, this category can be selected from its parent menu (whether a building or a parent category) using the given hotkey. Uses the same format as the BUILDING KEY described above.
|}

==== Adding reactions to an existing category ====

Just include the tag [CATEGORY:<category_id>] within your reaction definition, and if the category exists, your reaction will be added to its menu. You can only add reactions to custom categories.

Each reaction can belong to only one category.

=== Reagents ===

REAGENTs are a little bit complicated. They are the ingredients that the reaction will use. You can define as many as you like within a reaction.

[REAGENT:<name>:<quantity>:<item token>:<material token>][...modifiers...]
* ''[[#name|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 category of item you require; WEAPON, TOY or SKIN_TANNED, for example.

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

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

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

==== material token ====

[[Material 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).

Note that in reactions using INORGANIC reagents, if during gameplay you wish to use the {{k|d}}etails option to select a specific material when queuing up a job using the reaction, you ''must'' specify the material token as INORGANIC:NONE rather than NONE:NONE.

==== 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
! Description
|-
| [REACTION_CLASS:X]
| Reagent material must have the specified reaction class - see below for more details.
|-
| [HAS_MATERIAL_REACTION_PRODUCT:X]
| Reagent material must have the specified material reaction product - see below for more details.
|-
| [HAS_ITEM_REACTION_PRODUCT:X]
| Reagent material must have the specified item reaction product - see below for more details. This can be used interchangeably with HAS_MATERIAL_REACTION_PRODUCT.
|-
| [CONTAINS:X]
| Reagent is a container that holds the specified reagent (where ''X'' is the [[#name|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 token|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
! Description
|-
| [FORCE_EDGE]
| Product is given a sharp edge. Used for knapping.
|-
| [PRODUCT_PASTE]
| Product is created in the SOLID_PASTE state.
|-
| [PRODUCT_PRESSED]
| Product is created in the SOLID_PRESSED state.
|-
| [PRODUCT_DIMENSION:<size>]
| Specifies the dimensions of the product. A product of 150 is typical for BAR, POWDER_MISC, LIQUID_MISC, DRINK, and GLOB. 15000 is typical for THREAD, and a size of 10000 is typical for CLOTH. Has no effect on any other item types. Note: this is not the actual volume of the product, which is hard-coded by the item token.
|-
| [PRODUCT_TO_CONTAINER:<id>]
| Places the product in a container; <id> must be the name of a reagent with the PRESERVE_REAGENT token and a container item type.
|}

=== Improvements ===

Improvements are applied to existing reagents. A reaction can have as many improvements as it likes.

Restating this in the above style, we have:
[IMPROVEMENT:<probability>:<reagent name>:<improvement type>:<material token>]

==== probability ====

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

==== reagent name ====

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

==== improvement type ====

The following improvement types can be used:

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Description
|-
| COVERED
| Item is encrusted/studded/decorated with <material>.
|-
| GLAZED
| Item is glazed with <material>.
|-
| RINGS_HANGING
| Item is adorned with hanging rings of <material>.
|-
| BANDS
| Item is encircled with bands of <material>.
|-
| SPIKES
| Item menaces with spikes of <material>.
|-
| PAGES
| Adds pages to a [[book]].
|}

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

==== material token ====

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

If you want the decoration's material to be derived from one of the reagents, you can use GET_MATERIAL_FROM_REAGENT:reagent:REACTION_PRODUCT_ID in place of the material token. You can also specify GET_MATERIAL_FROM_REAGENT:reagent:NONE in order to directly use the reagent's own material.

=== Other tokens ===

==== fuel ====

The FUEL token means that the reaction requires coke or charcoal to be performed. Fuel is not needed when the reaction is performed at a magma workshop (a [[magma kiln]], [[magma smelter]], or any custom building having [NEEDS_MAGMA]).

==== skill ====

The [[Skill token|skill tokens]] determine what skill the reaction requires and trains; also how quickly skill is gained, how quickly those skill gains raise attributes, and how skill level affects the quality of the reaction product.

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Arguments
! Description
|-
| SKILL || [[Skill token]] || (Optional) This identifies the skill required to carry out the reaction and is trained when the reaction is performed. Only one skill may be specified; if multiple skill tokens are defined only the last will be used. A reaction with no product will yield no experience gain. A reaction with no SKILL token will always complete instantly.
|-
| SKILL_IP || Integer || (Optional, requires SKILL token) This adjusts the amount of skill gained each time the reaction is carried out. The default value is 30; higher values increase the amount of skill gain.
|-
| ATTRIBUTE_IP{{version|0.47.01}} || Integer || (Optional, requires SKILL token) This adjusts the amount of [[Attribute|attribute]] gain that skill gain from this reaction results in. The default value is 10; higher values increase the amount of attribute gain.
|-
| SKILL_ROLL_RANGE{{version|0.47.01}} || Range:Multiplier || (Optional, requires SKILL token) This changes how much skill level affects the quality of the reaction product. The default is [SKILL_ROLL_RANGE:11:5]. The ''range'' is the base "die roll" and the ''multiplier'' determines how much the dwarf's skill can affect the reaction; the skill roll is random(range) + random((skill level * multipler)/2 + 1) + random((skill level * multipler)/2 + 1), where random(x) gives a random number from 0 to x-1, inclusive (which also means that the minimum for the range is 1). The higher result on the roll, the better. Both numbers can be lowered to make the skill check harder. For example, with the default values a dwarf who is proficient in a skill has a skill level of 5; their roll will be random(11)+random(13)+random(13), meaning this dwarf can roll anywhere from 0 to 34; similarly, unskilled dwarves can roll 0 to 10 while legendary+0 (skill 15) dwarves can roll 0 to 84. If this is changed to [SKILL_ROLL_RANGE:1:8], then instead a proficient dwarf will have random(1)+random(21)+random(21), giving a roll of 0 to 40, with unskilled dwarves always rolling 0 and legendary dwarves going all the way up to 120.

As a consequence, increasing the multiplier will always make legendary dwarves more effective, even if base roll is reduced to its minimum of 1, with the default going up to 84 for default and 90 for [SKILL_ROLL_RANGE:1:6].
|}

==== automatic ====

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

This token only works with jobs performed at a [[kiln]], [[smelter]], [[tanner's shop]], [[kitchen]], or custom workshop, and [[standing orders]] allow you to limit which ones trigger; custom reactions performed at a [[quern]], [[millstone]]{{verify}}, [[still]]{{verify}} or [[craftsdwarf's workshop]]{{verify}} cannot be made automatic.

==== Adventure Mode enabled ====

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

==== max multiplier ====

The [MAX_MULTIPLIER:<#>] token 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}}

==== description ====

The [DESCRIPTION:<string>] token provides a text description of the reaction when it is highlighted in the building UI. Multiple DESCRIPTION tokens can be defined in a reaction, and each will appear on a new line. The pop-up box that contains the description is limited to 325 characters total. Alternatively, this token can reference a DESCRIPTION token in an existing tool definition by replacing ''string'' with USE_TOOL:<ITEM_SUBTYPE>; or an existing instrument definition with USE_INSTRUMENT:<ITEM_SUBTYPE>.

== 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
! Type
! 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 modifier
| Reagent material must have the [BONE] token.

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

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

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

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

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

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

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

|-
| {{text anchor|ANY_STRAND_TISSUE}}
|
| Reagent modifier
| Reagent is made of a tissue having [TISSUE_SHAPE:STRANDS], intended for matching hair and wool. Must be used with [USE_BODY_COMPONENT].

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

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

|-
| {{text anchor|ATTRIBUTE_IP}}{{version|0.47.01}}
|
* Integer
| Skill modifier
| Amount of attribute gain 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 modifier
| Reagent has to be a bag. Intended to be used with an item type of BOX, to prevent chests, coffers, and other containers from being used instead.

|-
| {{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 modifier
| Reagent is able to be used to build structures (Stone, Wood, Blocks, Bars?).

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

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

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

|-
| {{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
| Category
| The name of the category as displayed in-game.

|-
| {{text anchor|CATEGORY_DESCRIPTION}}{{version|0.42.01}}
|
* String
| Category
| If present, when the category is highlighted in a building menu, this string will be displayed in the Helpful Hint box.

|-
| {{text anchor|CATEGORY_PARENT}}{{version|0.42.01}}
|
* Category ID
| Category
| If present, this category will be a submenu of the indicated category, rather than a submenu of the reaction's building.

|-
| {{text anchor|CATEGORY_KEY}}{{version|0.42.01}}
|
* Hotkey
| Category
| If present, this category can be selected from its parent menu (whether a building or a parent category) using the given hotkey.

|-
| {{text anchor|CONTAINS}}
|
* Reagent name
| Reagent modifier
| Reagent is a container that holds the specified reagent.

|-
| {{text anchor|CONTAINS_LYE}} (Deprecated)
|
| Reagent modifier
| If the reagent is a container, it must contain LYE. No longer used - instead, use one reagent for the LYE itself and another reagent with [CONTAINS:lye_reagent].

|-
| {{text anchor|DESCRIPTION}}
|
* String
|
| A description of the reaction that appears when it is highlighted in the building UI. ''String'' can also be replaced with a reference to existing DESCRIPTION tokens in tools (using USE_TOOL:<tool_id>) or musical instruments (using USE_TOOL:<instrument_id>).

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

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

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

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

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

|-
| {{text anchor|FOOD_STORAGE_CONTAINER}}
|
| Reagent modifier
| 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 modifier
| Reagent material has [IS_GLASS].

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

|-
| {{text anchor|HAS_ITEM_REACTION_PRODUCT}}
|
* PRODUCT_ID (custom)
| Reagent modifier
| Similar to HAS_MATERIAL_REACTION_PRODUCT, but requires the reagents material to have a matching ITEM_REACTION_PRODUCT entry.

|-
| {{text anchor|HAS_MATERIAL_REACTION_PRODUCT}}
|
* PRODUCT_ID (custom)
| Reagent modifier
| Similar to REACTION_CLASS, but requires the reagents material to have a matching [[Material definition token|MATERIAL_REACTION_PRODUCT]] entry. Intended for reactions which transform one class of material into another, such as skin->leather and fat->tallow.

|-
| {{text anchor|HAS_TOOL_USE}}
|
* [[Tool token|Tool-use token]]
| Reagent modifier
| Reagent must be a [[tool]] with the specific TOOL_USE value. The reagents item type must be TOOL:NONE for this to make any sense.

|-
| {{text anchor|HAS_WRITING_IMPROVEMENT}}{{version|0.42.01}}
|
| Reagent modifier
| 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}}
|
| Reagent modifier
| Currently broken - Reagent must be considered [[magma-safe]] (stable [[temperature]] below {{ct|12000}}).

|-
| {{text anchor|MAX_MULTIPLIER}}{{version|0.42.01}}
|
* Integer
|
| Sets the maximum number of times a reaction is allowed to run when using stacked reagents. This can be used to ensure that the reaction doesn't repeat until the entire stack is depleted.

|-
| {{text anchor|METAL_ORE}}
|
* Inorganic material
| Reagent modifier
| Reagent material must be an ore of the specified metal.

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

|-
| {{text anchor|NAME}}
|
* Name
|
| Defines the name used by the reaction in-game.

|-
| {{text anchor|NO_EDGE_ALLOWED}}
|
| Reagent modifier
| Reagent must not have an edge, so must be blunt. Sharp stones (produced using knapping) and most types of weapon/ammo can not be used with this token.

|-
| {{text anchor|NOT_CONTAIN_BARREL_ITEM}}
|
| Reagent modifier
| If the reagent is a Barrel, it must not contain an item that has to reside in a barrel. Barrel items appear to be lye and milk. Alcohol appears to be covered as part of [EMPTY]. A reaction which places an item in a barrel should probably have both tags.

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

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

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

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

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

|-
| {{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
| Product modifier
| Specifies the size of the product. A size of 150 is typical for BAR, POWDER_MISC, LIQUID_MISC, DRINK, and GLOB. A size of 15000 is typical for THREAD, and a size of 10000 is typical for CLOTH.

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

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

|-
| {{text anchor|PRODUCT_TO_CONTAINER}}
|
* Reagent ID
| Product modifier
| Places the product in a container; <id> must be the name of a reagent with the PRESERVE_REAGENT token and a container item type.

|-
| {{text anchor|PRODUCT_TOKEN}}{{version|0.42.01}}
|
* Name
| Product modifier
| Allows the product to be referred to by the given name, for the purpose of being passed down as argument in other tokens.

|-
| {{text anchor|REACTION}}
|
* Identifier
|
| Defines a new reaction.

|-
| {{text anchor|REACTION_CLASS}}
|
* CLASS_ID (custom)
| Reagent modifier
| Requires the reagent's material to have a matching [[Material definition token|REACTION_CLASS]] entry. Intended for reactions which accept a variety of materials but where the input material does not determine the output material, such as FLUX (for making pig iron and steel) and GYPSUM (for producing plaster powder).

|-
| {{text anchor|REAGENT}}
|
* Name/id
* Quantity
* [[Item token]]
* [[Material token]]
|
| Specifies 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
| Skill modifier
| Amount of skill given per product made. Default is 30.

|-
| {{text anchor|SKILL_ROLL_RANGE}}{{version|0.47.01}}
|
* Range
* Multiplier
| Skill modifier
| Determines how [[skill]] level affects [[quality]] of the reaction product. The skill roll is random(range) + random((skill level * multipler)/2 + 1) + random((skill level * multipler)/2 + 1). random(x) returns a number between 0 and x-1, so range is always 1 or more. The default is 11. The default multiplier is 5. Higher skill rolls give better results.

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

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

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

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

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

|}

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

Reaction

2022-11-24T00:55:14Z

Trainzack: Add links

{{Quality|Superior|19:56, 28 August 2013 (UTC)}}
{{av}}
{{Modding}}

'''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 token assigns a unique ID to your reaction.
[REACTION:<reaction identifier>]

The ''reaction identifier'' may be anything, so long as it is unique within the raw data files. A good habit to get into is to append a short prefix or suffix to each name related to the name of your mod, to ensure nobody else is going to make an identical reaction and thereby mess up the game if their mod is run alongside yours. This is referenced in an entity definition via [[Entity_token#PERMITTED_REACTION|PERMITTED_REACTION]] to allow that entity to use the reaction.

=== Reaction name ===
The REACTION_NAME token assigns a descriptive name to your reaction in-game.
[REACTION_NAME:<name>]

==== name ====
This can be anything at all, and is how the reaction will appear in the job list of the building it is assigned to, and so should describe the reaction. '''Tan a hide''', for example, is the name of the default leather-producing reaction. Generally this should be written as a small descriptive verb phrase, with the first letter capitalized, for consistency with the existing reactions.

=== Building ===
The BUILDING token assigns the reaction to a building. Adding multiple BUILDING tokens will cause the reaction to be available at all of the specified buildings. Omitting the BUILDING token entirely will make the reaction unusable in Fortress mode (often used to restrict certain reactions to [[Reaction#Adventure_Mode_enabled|Adventure mode]]).

[BUILDING:<building name>:<building key>]
* [[#building name|''building name:'']] The ID of the building the reaction appears in.
* [[#building key|''building key:'']] The hotkey to queue up the reaction in the specified building.

==== building name ====
This is the ID of the building where the reaction will be carried out. Valid building names are as follows:

* ASHERY{{version|0.42.01}} - [[Ashery]]
* BOWYER{{version|0.42.01}} - [[Bowyer's workshop]]
* CARPENTER{{version|0.42.01}} - [[Carpenter's workshop]]
* CLOTHES{{version|0.42.01}} - [[Clothier's shop]]
* CRAFTSMAN - [[Craftsdwarf's workshop]]
* FARMER - [[Farmer's workshop]]
* GLASS{{version|0.42.01}} - [[Glass furnace]]
* KILN - [[Kiln]] and [[Magma kiln]]
* KITCHEN - [[Kitchen]]
* LEATHER{{version|0.42.01}} - [[Leather works]]
* MASON{{version|0.42.01}} - [[Mason's workshop]]
* METALSMITH{{version|0.42.01}} - [[Metalsmith's forge]]
* MILLSTONE - [[Millstone]]
* QUERN - [[Quern]]
* SIEGE{{version|0.42.01}} - [[Siege workshop]]
* SMELTER - [[Smelter]] and [[Magma smelter]]
* STILL - [[Still]]
* TANNER - [[Tanner's shop]]
* WOOD{{version|0.42.01}} - [[Wood furnace]]
* Any custom (raw-defined) building, such as:
** SOAP_MAKER - [[Soap maker's workshop]]
** SCREW_PRESS - [[Screw press]]

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

=== Category ===

{{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 || Hotkey token || Optional. If present, this category can be selected from its parent menu (whether a building or a parent category) using the given hotkey. Uses the same format as the BUILDING KEY described above.
|}

==== Adding reactions to an existing category ====

Just include the tag [CATEGORY:<category_id>] within your reaction definition, and if the category exists, your reaction will be added to its menu. You can only add reactions to custom categories.

Each reaction can belong to only one category.

=== Reagents ===

REAGENTs are a little bit complicated. They are the ingredients that the reaction will use. You can define as many as you like within a reaction.

[REAGENT:<name>:<quantity>:<item token>:<material token>][...modifiers...]
* ''[[#name|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 category of item you require; WEAPON, TOY or SKIN_TANNED, for example.

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

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

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

==== material token ====

[[Material 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).

Note that in reactions using INORGANIC reagents, if during gameplay you wish to use the {{k|d}}etails option to select a specific material when queuing up a job using the reaction, you ''must'' specify the material token as INORGANIC:NONE rather than NONE:NONE.

==== 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
! Description
|-
| [REACTION_CLASS:X]
| Reagent material must have the specified reaction class - see below for more details.
|-
| [HAS_MATERIAL_REACTION_PRODUCT:X]
| Reagent material must have the specified material reaction product - see below for more details.
|-
| [HAS_ITEM_REACTION_PRODUCT:X]
| Reagent material must have the specified item reaction product - see below for more details. This can be used interchangeably with HAS_MATERIAL_REACTION_PRODUCT.
|-
| [CONTAINS:X]
| Reagent is a container that holds the specified reagent (where ''X'' is the [[#name|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 token|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
! Description
|-
| [FORCE_EDGE]
| Product is given a sharp edge. Used for knapping.
|-
| [PRODUCT_PASTE]
| Product is created in the SOLID_PASTE state.
|-
| [PRODUCT_PRESSED]
| Product is created in the SOLID_PRESSED state.
|-
| [PRODUCT_DIMENSION:<size>]
| Specifies the dimensions of the product. A product of 150 is typical for BAR, POWDER_MISC, LIQUID_MISC, DRINK, and GLOB. 15000 is typical for THREAD, and a size of 10000 is typical for CLOTH. Has no effect on any other item types. Note: this is not the actual volume of the product, which is hard-coded by the item token.
|-
| [PRODUCT_TO_CONTAINER:<id>]
| Places the product in a container; <id> must be the name of a reagent with the PRESERVE_REAGENT token and a container item type.
|}

=== Improvements ===

Improvements are applied to existing reagents. A reaction can have as many improvements as it likes.

Restating this in the above style, we have:
[IMPROVEMENT:<probability>:<reagent name>:<improvement type>:<material token>]

==== probability ====

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

==== reagent name ====

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

==== improvement type ====

The following improvement types can be used:

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Description
|-
| COVERED
| Item is encrusted/studded/decorated with <material>.
|-
| GLAZED
| Item is glazed with <material>.
|-
| RINGS_HANGING
| Item is adorned with hanging rings of <material>.
|-
| BANDS
| Item is encircled with bands of <material>.
|-
| SPIKES
| Item menaces with spikes of <material>.
|-
| PAGES
| Adds pages to a [[book]].
|}

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

==== material token ====

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

If you want the decoration's material to be derived from one of the reagents, you can use GET_MATERIAL_FROM_REAGENT:reagent:REACTION_PRODUCT_ID in place of the material token. You can also specify GET_MATERIAL_FROM_REAGENT:reagent:NONE in order to directly use the reagent's own material.

=== Other tokens ===

==== fuel ====

The FUEL token means that the reaction requires coke or charcoal to be performed. Fuel is not needed when the reaction is performed at a magma workshop (a [[magma kiln]], [[magma smelter]], or any custom building having [NEEDS_MAGMA]).

==== skill ====

The [[Skill token|skill tokens]] determine what skill the reaction requires and trains; also how quickly skill is gained, how quickly those skill gains raise attributes, and how skill level affects the quality of the reaction product.

{| {{prettytable}}
|- bgcolor="#dddddd"
! Token
! Arguments
! Description
|-
| SKILL || [[Skill token]] || (Optional) This identifies the skill required to carry out the reaction and is trained when the reaction is performed. Only one skill may be specified; if multiple skill tokens are defined only the last will be used. A reaction with no product will yield no experience gain. A reaction with no SKILL token will always complete instantly.
|-
| SKILL_IP || Integer || (Optional, requires SKILL token) This adjusts the amount of skill gained each time the reaction is carried out. The default value is 30; higher values increase the amount of skill gain.
|-
| ATTRIBUTE_IP{{version|0.47.01}} || Integer || (Optional, requires SKILL token) This adjusts the amount of [[Attribute|attribute]] gain that skill gain from this reaction results in. The default value is 10; higher values increase the amount of attribute gain.
|-
| SKILL_ROLE_RANGE{{version|0.47.01}} || Range:Multiplier || (Optional, requires SKILL token) This changes how much skill level affects the quality of the reaction product. The default is [SKILL_ROLL_RANGE:11:5]. The ''range'' is the base "die roll" and the ''multiplier'' determines how much the dwarf's skill can affect the reaction; the skill roll is random(range) + random((skill level * multipler)/2 + 1) + random((skill level * multipler)/2 + 1), where random(x) gives a random number from 0 to x-1, inclusive (which also means that the minimum for the range is 1). The higher result on the roll, the better. Both numbers can be lowered to make the skill check harder. For example, with the default values a dwarf who is proficient in a skill has a skill level of 5; their roll will be random(11)+random(13)+random(13), meaning this dwarf can roll anywhere from 0 to 34; similarly, unskilled dwarves can roll 0 to 10 while legendary+0 (skill 15) dwarves can roll 0 to 84. If this is changed to [SKILL_ROLL_RANGE:1:8], then instead a proficient dwarf will have random(1)+random(21)+random(21), giving a roll of 0 to 40, with unskilled dwarves always rolling 0 and legendary dwarves going all the way up to 120.

As a consequence, increasing the multiplier will always make legendary dwarves more effective, even if base roll is reduced to its minimum of 1, with the default going up to 84 for default and 90 for [SKILL_ROLL_RANGE:1:6].
|}

==== automatic ====

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

This token only works with jobs performed at a [[kiln]], [[smelter]], [[tanner's shop]], [[kitchen]], or custom workshop, and [[standing orders]] allow you to limit which ones trigger; custom reactions performed at a [[quern]], [[millstone]]{{verify}}, [[still]]{{verify}} or [[craftsdwarf's workshop]]{{verify}} cannot be made automatic.

==== Adventure Mode enabled ====

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

==== max multiplier ====

The [MAX_MULTIPLIER:<#>] token 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}}

==== description ====

The [DESCRIPTION:<string>] token provides a text description of the reaction when it is highlighted in the building UI. Multiple DESCRIPTION tokens can be defined in a reaction, and each will appear on a new line. The pop-up box that contains the description is limited to 325 characters total. Alternatively, this token can reference a DESCRIPTION token in an existing tool definition by replacing ''string'' with USE_TOOL:<ITEM_SUBTYPE>; or an existing instrument definition with USE_INSTRUMENT:<ITEM_SUBTYPE>.

== 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
! Type
! 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 modifier
| Reagent material must have the [BONE] token.

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

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

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

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

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

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

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

|-
| {{text anchor|ANY_STRAND_TISSUE}}
|
| Reagent modifier
| Reagent is made of a tissue having [TISSUE_SHAPE:STRANDS], intended for matching hair and wool. Must be used with [USE_BODY_COMPONENT].

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

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

|-
| {{text anchor|ATTRIBUTE_IP}}{{version|0.47.01}}
|
* Integer
| Skill modifier
| Amount of attribute gain 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 modifier
| Reagent has to be a bag. Intended to be used with an item type of BOX, to prevent chests, coffers, and other containers from being used instead.

|-
| {{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 modifier
| Reagent is able to be used to build structures (Stone, Wood, Blocks, Bars?).

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

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

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

|-
| {{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
| Category
| The name of the category as displayed in-game.

|-
| {{text anchor|CATEGORY_DESCRIPTION}}{{version|0.42.01}}
|
* String
| Category
| If present, when the category is highlighted in a building menu, this string will be displayed in the Helpful Hint box.

|-
| {{text anchor|CATEGORY_PARENT}}{{version|0.42.01}}
|
* Category ID
| Category
| If present, this category will be a submenu of the indicated category, rather than a submenu of the reaction's building.

|-
| {{text anchor|CATEGORY_KEY}}{{version|0.42.01}}
|
* Hotkey
| Category
| If present, this category can be selected from its parent menu (whether a building or a parent category) using the given hotkey.

|-
| {{text anchor|CONTAINS}}
|
* Reagent name
| Reagent modifier
| Reagent is a container that holds the specified reagent.

|-
| {{text anchor|CONTAINS_LYE}} (Deprecated)
|
| Reagent modifier
| If the reagent is a container, it must contain LYE. No longer used - instead, use one reagent for the LYE itself and another reagent with [CONTAINS:lye_reagent].

|-
| {{text anchor|DESCRIPTION}}
|
* String
|
| A description of the reaction that appears when it is highlighted in the building UI. ''String'' can also be replaced with a reference to existing DESCRIPTION tokens in tools (using USE_TOOL:<tool_id>) or musical instruments (using USE_TOOL:<instrument_id>).

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

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

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

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

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

|-
| {{text anchor|FOOD_STORAGE_CONTAINER}}
|
| Reagent modifier
| 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 modifier
| Reagent material has [IS_GLASS].

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

|-
| {{text anchor|HAS_ITEM_REACTION_PRODUCT}}
|
* PRODUCT_ID (custom)
| Reagent modifier
| Similar to HAS_MATERIAL_REACTION_PRODUCT, but requires the reagents material to have a matching ITEM_REACTION_PRODUCT entry.

|-
| {{text anchor|HAS_MATERIAL_REACTION_PRODUCT}}
|
* PRODUCT_ID (custom)
| Reagent modifier
| Similar to REACTION_CLASS, but requires the reagents material to have a matching [[Material definition token|MATERIAL_REACTION_PRODUCT]] entry. Intended for reactions which transform one class of material into another, such as skin->leather and fat->tallow.

|-
| {{text anchor|HAS_TOOL_USE}}
|
* [[Tool token|Tool-use token]]
| Reagent modifier
| Reagent must be a [[tool]] with the specific TOOL_USE value. The reagents item type must be TOOL:NONE for this to make any sense.

|-
| {{text anchor|HAS_WRITING_IMPROVEMENT}}{{version|0.42.01}}
|
| Reagent modifier
| 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}}
|
| Reagent modifier
| Currently broken - Reagent must be considered [[magma-safe]] (stable [[temperature]] below {{ct|12000}}).

|-
| {{text anchor|MAX_MULTIPLIER}}{{version|0.42.01}}
|
* Integer
|
| Sets the maximum number of times a reaction is allowed to run when using stacked reagents. This can be used to ensure that the reaction doesn't repeat until the entire stack is depleted.

|-
| {{text anchor|METAL_ORE}}
|
* Inorganic material
| Reagent modifier
| Reagent material must be an ore of the specified metal.

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

|-
| {{text anchor|NAME}}
|
* Name
|
| Defines the name used by the reaction in-game.

|-
| {{text anchor|NO_EDGE_ALLOWED}}
|
| Reagent modifier
| Reagent must not have an edge, so must be blunt. Sharp stones (produced using knapping) and most types of weapon/ammo can not be used with this token.

|-
| {{text anchor|NOT_CONTAIN_BARREL_ITEM}}
|
| Reagent modifier
| If the reagent is a Barrel, it must not contain an item that has to reside in a barrel. Barrel items appear to be lye and milk. Alcohol appears to be covered as part of [EMPTY]. A reaction which places an item in a barrel should probably have both tags.

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

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

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

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

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

|-
| {{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
| Product modifier
| Specifies the size of the product. A size of 150 is typical for BAR, POWDER_MISC, LIQUID_MISC, DRINK, and GLOB. A size of 15000 is typical for THREAD, and a size of 10000 is typical for CLOTH.

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

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

|-
| {{text anchor|PRODUCT_TO_CONTAINER}}
|
* Reagent ID
| Product modifier
| Places the product in a container; <id> must be the name of a reagent with the PRESERVE_REAGENT token and a container item type.

|-
| {{text anchor|PRODUCT_TOKEN}}{{version|0.42.01}}
|
* Name
| Product modifier
| Allows the product to be referred to by the given name, for the purpose of being passed down as argument in other tokens.

|-
| {{text anchor|REACTION}}
|
* Identifier
|
| Defines a new reaction.

|-
| {{text anchor|REACTION_CLASS}}
|
* CLASS_ID (custom)
| Reagent modifier
| Requires the reagent's material to have a matching [[Material definition token|REACTION_CLASS]] entry. Intended for reactions which accept a variety of materials but where the input material does not determine the output material, such as FLUX (for making pig iron and steel) and GYPSUM (for producing plaster powder).

|-
| {{text anchor|REAGENT}}
|
* Name/id
* Quantity
* [[Item token]]
* [[Material token]]
|
| Specifies 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
| Skill modifier
| Amount of skill given per product made. Default is 30.

|-
| {{text anchor|SKILL_ROLL_RANGE}}{{version|0.47.01}}
|
* Range
* Multiplier
| Skill modifier
| Determines how [[skill]] level affects [[quality]] of the reaction product. The skill roll is random(range) + random((skill level * multipler)/2 + 1) + random((skill level * multipler)/2 + 1). random(x) returns a number between 0 and x-1, so range is always 1 or more. The default is 11. The default multiplier is 5. Higher skill rolls give better results.

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

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

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

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

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

|}

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

Instrument token

2022-11-23T23:41:02Z

Trainzack: Added more information about skill tokens.

{{Quality|Exceptional|14:41, 22 July 2018 (UTC)}}
{{av}}
{{Modding}}

Since v0.42.01, [[instruments]] are procedurally generated for each world, but if so desired, it is still possible to define custom instruments in the raws by using an [ITEM_INSTRUMENT] token. Most [[tool token]]s can be used as before, but there are a few instrument-specific tokens, as listed in the table below.

The information on this page is sourced from the file <code>raw/objects/examples and notes/item_instrument_example.txt</code>, which also includes useful example instrument definitions.
{{clear}}

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

|-
| {{text anchor|PLACED_AS_BUILDING}}
|
| Makes the instrument stationary.

|-
| {{text anchor|DOMINANT_MATERIAL_PIECE}}
|
* instrument piece
| Sets a piece as the central part of the instrument.

|-
| {{text anchor|INSTRUMENT_PIECE}}
|
* token
* tool token
* singular
* plural
* STANDARD/ALWAYS_PLURAL/ALWAYS_SINGULAR
| Defines an instrument piece. ''token'' is the identifier that can be used in other raw tags to refer to this instrument piece. ''tool token'' is the tool which is required (and consumed) during the construction process to create this instrument piece.

If an instrument does not have any pieces, SELF can be used for any argument which needs to be an instrument piece.

|-
| {{text anchor|VOLUME_mB}}
|
* min
* max
| The instrument's volume range, in millibels (100 mB = 1 dB).

|-
| {{text anchor|SOUND_PRODUCTION}}
|
* various tokens
| Defines how a musician can produce sound when using this instrument. Can be used multiple times. Valid tokens and their required additional arguments are:
* PLUCKED_BY_BP, PLUCKED (requires two tokens, actor then target)
* BOWED (two tokens)
* STRUCK_BY_BP, STRUCK (two tokens)
* VIBRATE_BP_AGAINST_OPENING
* BLOW_AGAINST_FIPPLE, BLOW_OVER_OPENING_SIDE, BLOW_OVER_OPENING_END, BLOW_OVER_SINGLE_REED, BLOW_OVER_DOUBLE_REED, BLOW_OVER_FREE_REED
* STRUCK_TOGETHER, SHAKEN
* SCRAPED (two tokens), FRICTION (two tokens)
* RESONATOR
* BAG_OVER_REED (two tokens), AIR_OVER_REED (two tokens), AIR_OVER_FREE_REED (two tokens), AIR_AGAINST_FIPPLE (two tokens)

|-
| {{text anchor|PITCH_CHOICE}}
|
* method
| Defines how the pitch can be varied by the musician. Can be used multiple times. Valid methods are:
* MEMBRANE_POSITION
* SUBPART_CHOICE
* KEYBOARD
* STOPPING_FRET (requires two tokens, first for "string" second for "neck" -- or whatever is being pressed against what), STOPPING_AGAINST_BODY (two tokens), STOPPING_HOLE, STOPPING_HOLE_KEY
* SLIDE
* HARMONIC_SERIES
* VALVE_ROUTES_AIR
* BP_IN_BELL
* FOOT_PEDALS (two token, first is what is being changed e.g. "strings", second is "body" which has pedalboard -- or whatever piece is being stepped on)

|-
| {{text anchor|TUNING}}
|
* method
* instrument piece
| Can be used multiple times. Valid methods are: PEGS, ADJUSTABLE_BRIDGES, CROOKS, TIGHTENING, LEVERS.

|-
| {{text anchor|PITCH_RANGE}}
|
* min pitch
* max pitch
| From the example file:
<blockquote>Pitch is <min>:<max> in cents with middle C at zero. There are 1200 cents in an octave. The game verbally differentiates values from -4200 to 4200, but you can go outside that if you like. The in-game generated instruments will range from roughly C0 to C8 (-4800 to 4800), sometimes beyond for really unusual ones.

You can also use INDEFINITE_PITCH.
</blockquote>

|-
| {{text anchor|INDEFINITE_PITCH}}
|
| May replace {{token|PITCH_RANGE|ins}}.

|-
| {{text anchor|TIMBRE}}
|
* any number of timbre words
| Valid timbre words are: CLEAR, NOISY, FULL, THIN, ROUND, SHARP, SMOOTH, CHOPPY, STEADY, EVOLVING, STRONG, DELICATE, BRIGHT, GRACEFUL, SPARSE, BREATHY, STRAINED, BROAD, LIGHT, MELLOW, WOBBLING, FOCUSED, EVEN, FLUID, VIBRATING, QUAVERING, EERIE, FRAGILE, BRITTLE, PURE, PIERCING, STRIDENT, WAVERING, HARSH, REEDY, NASAL, BUZZY, ROUGH, WARM, RUGGED, HEAVY, FLAT, DARK, CRISP, SONOROUS, WATERY, GENTLE, SLICING, LIQUID, RAUCOUS, BREEZY, RASPY, WISPY, SHRILL, MUDDY, RICH, DULL, FLOATING, RINGING, RESONANT, SWEET, RIPPLING, SPARKLING.

|-
| {{text anchor|REGISTER}}
|
* min pitch
* max pitch
* any number of timbre words
| See [[#PITCH_RANGE|PITCH_RANGE]] and [[#TIMBRE|TIMBRE]] for possible values. The pitch range overrides the global pitch for a register, but the register timbres are added to the global ones.

|-
| {{text anchor|MUSIC_SKILL}}
|
* skill token
| Which skill should be trained by playing the instrument. Any [[skill token]] is valid, but the in-game generated instruments only use PLAY_KEYBOARD_INSTRUMENT, PLAY_STRINGED_INSTRUMENT, PLAY_WIND_INSTRUMENT, or PLAY_PERCUSSION_INSTRUMENT. Levels in this skill do not seem to have any effect on the quality of music produced. Can only be used once.

|-
| {{text anchor|DESCRIPTION}}
|
* description
| A general description of the completed instrument. Multiple [DESCRIPTION] tokens can be used in the same definition, with each appearing on a new line.

|}

{{category|Tokens}}
[[ru:Instrument token]]