Topic: (31.13) Tutorial/Resource: The Anatomy of a Reaction (Read 4325 times)

kwd1968 · « **on:** September 21, 2010, 02:46:33 pm »

Dwarf Fortress : Anatomy of a Reaction (as of v31.13)

Reaction refers to the command in the reaction_(whatever) file.

It defines a process by which listed raw materials, called [REAGENT]s, are taken one at a time in listed order to a building (or not in adventure mode), and turned in to a [PRODUCT], giving the worker an increase in a defined skill. They are made up of individual lines that are started by '[' and ended by ']' and contain the parameters for each step of the reaction.

format:

[REACTION:(reaction name in capitals, no spaces, use '_')]

   [NAME:(text shown in the building's "add new task" menu or Adventure Mode's action/create menu)]

   [ADVENTURE_MODE_ENABLED] or [BUILDING:(building the reaction will appear in):(keyboard shortcut)]

   [REAGENT:(reagent 'name' usually single capital letter):(number value of how many):(items type):(item's subtype):(items's matgloss):(item's matgloss subtype)][(additional tags for further item screening/definition)]

   [PRODUCT:(percentage chance of success):(number of products made per task):(product's item type):(product's item subtype):(product's matgloss):(product's matgloss subtype)][(additional commands affecting the product)]

   [(several misc tags for reaction)]

   [SKILL:(skill to be increased by task doer)]

Simple right? The indents on the lines aren't necessary I think, but I do them to make it clear to me where the reaction starts and ends etc.

ok now a breakdown of every step. I'll be using the 'Line #' header for these, they refer to the formatting example above and are not used at all in the creation of reactions, simply as a tool for this tutorial.

----------------------------------------------
LINE 1
[REACTION:(reaction name)]

The easiest part of custom modding.

examples:

[REACTION:BRASS_MAKING]
[REACTION:BLAH]
[REACTION:CUSTOM_101010]

Accepts any name that is composed of all capital letters, numbers and underscores. Has no effect on the actual product itself so can be anything really. Usually named something that defines what the reaction does so the modder (or whoever) can easily refer back to it.

----------------------------------------------
LINE 2
[NAME:(text)]

The (text) is what will show up on the screen in the building "add new task" or adventure mode "create" menus and is usually a descriptor of what the reaction produces (and sometimes the materials, especially if you have multiple methods of making the same product).

examples:

[NAME:make soap]
[NAME:make brass bars (use ore)]
[NAME:make brass bars (use bars)]

----------------------------------------------
LINE 3
[ADVENTURE_MODE_ENABLED] or [BUILDING:(building name):(keyboard shortcut)]

Can only be one of these arguments.

Reactions with the [ADVENTURE_MODE_ENABLED] line will only work in Adventure Mode. They will appear in the "create" section of the action menu. Keyboard shortcuts are not defined in the reaction for adventure Mode, but in the key binding main menu (or at least I think they can be bound there, either way they can't be defined in the reaction).

Reactions with the [BUILDING:(building name):(keyboard shortcut)] only work in Fortress Mode. They will appear in the defined building's "add new task" menu.

Valid (building name) values are SMELTER, KITCHEN, TANNER, KILN, SOAP_MAKER and any custom building name that you may have designed yourself.

The (keyboard shortcut) is in the format of NONE, CUSTOM_(key), CUSTOM_SHIFT_(key), where (key) is always in capital letters. If defined it will add a green representation of the defined key and white colon before the Line 2 [NAME:(text)] entry in the "add new task" screen.

examples:

[BUILDING:SOAP_MAKER:CUSTOM_S]

makes the reaction appear in the SOAP_MAKER building and can be quick selected with the "s" key.

[BUILDING:KILN:CUSTOM_SHIFT_P]

makes the reaction appear in the KILN building and can be quick selected with the shift+"p" key.

[BUILDING:SMELTER:NONE]

makes the reaction appear in the SMELTER building with no quick key.

----------------------------------------------
LINE 4
[REAGENT:(name):(number):(item):(item subtype):(matgloss):(matgloss subtype)][(outside arguments)]

This is the start of the meat and potatoes of your reaction and could probably fill 5 tutorials on its own, but I'll try to do my best to be thorough.

[REAGENT]s are the 'building blocks' of your reactions and represent the raw material used to make the [PRODUCT](s). There can be multiple [REAGENT] lines in any given reaction (or none but those are rare and are usually 'cheats' to get free items or training).

(name)

Usually just a single capital letter, this entry can and usually is referred to in the later [PRODUCT] line for material definitions. You can have as many [REAGENT] lines as you want, just note that each one will define something that is needed/used in the reaction to make the [PRODUCT], though it may not contribute any material itself. The (name) entries on multiple lines DO NOT HAVE TO BE DIFFERENT, but if you have multiple lines with different items/materials but the same (name) entry the LAST one listed will be the one referrenced by any [PRODUCT] material requests for that (name). Therefore it is adviseable to use differnt values for (name) for each [REAGENT] defined. In Adventure Mode, the text for this entry is actually displayed when selecting the defined item for the reaction, so you may want to use a short descriptive entry for this for any Adventure Mode reactions, though capital letters etc. still work fine.

example:

A
B
C
tool stone
hammerstone

(number)

The amount of the item you are about to define that is required. Usually a low number but in special cases can be large values. BAR, POWDER_MISC, CLOTH and THREAD items have differnt formats for how they are measured in units. While most items are 1 item = 1 reagent unit, BARS are 1 BAR = 150 reagent units, POWDER_MISC is 1 item = 150 reagent units, THREAD (and CLOTH I believe not 100% sure though) are 1 item = 15000 reagent units. So having a (number) of 150 for a BAR reagent will only use 1 bar and 15000 for thread will only use 1 thread (or cloth...I think).

example:

1
2
150
15000

(item):(item subtype):(matgloss):(matgloss subtype)][(outside arguments)]

The item type and subtype (if any) of the [REAGENT] as well as the materials it is made of and any outside filters/restrictions independent of the [REAGENT] itself. These are listed later as there are quite alot of them.

----------------------------------------------
LINE 5
[PRODUCT:(number1):(number2):(item):(item subtype):(matgloss):(matgloss subtype)][(outside arguments)]

This line defines the end [PRODUCT] of your reaction, how many are made and from what material (and with outside arguments possibnly where it is stored upon creation). As with the [REAGENT] line, there can be multiple [PRODUCT] lines in any reaction. Each line defines its own separate [PRODUCT](s).

(number1)

The chance, in percent, of the [PRODUCT] actually being made. A value of 100 guarantees success. Values over 100 do not make multiples of the [PRODUCT]. Values under 100 mean that there is a chance to not make anything.

(number 2)

The amount of the [PRODUCT] that is made. [PRODUCT]s are usually single entites in themselves (if you make 10 there will be 10 individual things to stockpile), but certain item types are stacked (up to a specific number which is different for each stackable item type) and may possibly all come out as one or more number of stacks if the (number2) value is greater than 1.

(item):(item subtype):(matgloss):(matgloss subtype)][(outside arguments)]

The item type and subtype (if any) of the [PRODUCT] as well as the materials it is made of and any outside filters/restrictions independent of the [PRODUCT] itself. They follow the same guidelines and use the same values as [REAGENT] variables of the same type. These are listed later as there are quite alot of them.

----------------------------------------------
LINE 6
[(misc reaction parameters)]

These parameters are optional and do not have to be in a reaction. You can have both in one reaction as well if desired.

valid values:

[AUTOMATIC]

As soon as the required reagent(s) are available the reaction will be performed. No input is required from the player.

[FUEL]

Coke or charcoal is required for this reaction to take place.

----------------------------------------------
LINE 7
[SKILL:(text)]

Defines the skill that will be improved by the dwarf performing the reaction. Only one can be used (or at least when I tried to do multiples it crashed the game).

valid values:

Spoiler (click to show/hide)

----------------------------------------------
Valid ITEM and ITEM SUBTYPE Values

There are alot (yes ALOT) of different valid values for these variables, and they are mostly shared by both [REAGENT]s and [PRODUCT]s.

NOTE: if your [REAGENT] is a piece of furniture, only stockpiled/un set-up furniture will be used. As well, only building materials (BOULDER, BLOCKS, etc.) that are stockpiled will be used (no they won't tear the building down to recycle itself).

Spoiler (click to show/hide)

----------------------------------------------
Valid MATGLOSS and MATGLOSS SUBTYPE Values

Spoiler (click to show/hide)

----------------------------------------------
[REAGENT] line valid [(outside elements)]

Spoiler (click to show/hide)

----------------------------------------------
[PRODUCT] line valid [(outside elements)]

Spoiler (click to show/hide)

And there you have it, the Anatomy of a Reaction.

How To Use Your Custom Reactions

You should save all of your custom reactions in their own file (though you can use the reaction_other and reaction_smelter files given with standard DF if you so wish). The file name can really be anything but conventional formatting usually has the filename starting with reaction_(somethingorother). If making a mod the (somethingorother) is usually the name of the mod. The file format is a standard text (.txt) file.

Inside the actual file itself, the first line must be the filename.

So if your file is "reaction_custom", the first line in that file must be "reaction_custom" otherwise it won't work at all.

The next text line inside the file must be [OBJECT:REACTION]. If not, again, your reactions won't work.

From there on you can list your custom reactions however you wish.

The next step is to go to your "entity_default" file (or whatever entity_ file contains the race you are making reactions for). This file contains all the races in dwarf fortress, what weapons they can use, what buildings are available to them etc. It also contains a list of [PERMITTED_REACTION]s. For your chosen race to use the custom reactions you just made you have to add in each and every custom reaction, by name, as a [PERMITTED_REACTION:(reaction name)] line. Custom buildings that have these reactions are also added in this file using the [PERMITTED_BUILDING:(building name)] format. If the buildings and/or reactions are not added to the entity/race, that entity/race will not have access to those buildings and/or reactions. You must put the building in if it has been specified by the reaction to use it, otherwise you won't be able to access the reaction even though its use is permitted. And you must enter all the reactions connected to a specific added building otherwise, even though you can build the building, you won't have access to the reactions.

Any custom files you make for dwarf fortress must be located in the /raw/object directory of the dwarf fortress install before you generate a world in order for them to be available. You cannot add new files to already generated save game worlds, they won't work. You also cannot change any reaction names in an already created world (will crash it) but you can change everything else about the reaction so long as the name stays the same.

Adventure Mode reactions DO NOT have to be added to the entity_* file and are automatically loaded for all playable races.

Deon · « **Reply #1 on:** September 21, 2010, 02:50:12 pm »

Spoiler the lists, please

.
It's almost impossible to read now, otherwise it's fine.

I am afraid that it may be lost on other pages soon enough though, so it would be good to have it linked in some major guide like Shaostoul's guide.

I think it's VERY important to mention how to add reactions to old files and how to add new reaction files.

And the most important thing: don't forget to mention that you have to add PERMITTED_REACTION to entity, otherwise we will get another batch of "how do I make this to work" threads

.

P.S. You have a typo: "[UNROTTEN] [REAGENT] must be unhrotten"

kwd1968 · « **Reply #2 on:** September 21, 2010, 03:02:13 pm »

yeah was gonna save the how do I do this for part 2, but i can take it on the end here I guess.

Quietust · « **Reply #3 on:** September 21, 2010, 03:20:54 pm »

The SIEGEAMMO item type does have subtypes - they're defined in item_siegeammo.txt, and the usual subtype should be ITEM_SIEGEAMMO_BALLISTA.

Also, for the MATGLOSS values, amber, coral, and glass shouldn't be "any" material.

As for FILTH_*, FILTH_B is brown filth and is solid (i.e. feces), FILTH_Y is yellow filth and is liquid (i.e. urine), and UNKNOWN_SUBSTANCE is a white liquid associated with tentacle demons (yes, that liquid).

There are also a few other tokens you missed - NO_EDGE_ALLOWED (used for knapping reagents), FORCE_EDGE (used for knapping product), NOT_CONTAIN_BARREL_ITEM (spotted in disassembly, no idea what it does), and MIN_DIMENSION (ditto). Additionally, PRODUCT_DIMENSION is also apparently used for POWDER_MISC items, specifically plaster powder.

Dvalinn · « **Reply #4 on:** September 23, 2010, 08:53:58 pm »

This is a nice resource. There is one thing I found, though. When discussing the (keyboard shortcut) element of [BUILDING:(building name):(keyboard shortcut)], you say if the shortcut is left off, it will be treated as NONE. However, I found that when I omitted it, the reaction wasn't listed at all. This was using the kiln as the building, if that makes a difference. Putting NONE at the end made it appear properly.

News:

Author Topic: (31.13) Tutorial/Resource: The Anatomy of a Reaction (Read 4325 times)

kwd1968

(31.13) Tutorial/Resource: The Anatomy of a Reaction

Deon

Re: (31.13) Tutorial/Resource: The Anatomy of a Reaction

kwd1968

Re: (31.13) Tutorial/Resource: The Anatomy of a Reaction

Quietust

Re: (31.13) Tutorial/Resource: The Anatomy of a Reaction

Dvalinn

Re: (31.13) Tutorial/Resource: The Anatomy of a Reaction