Live patching

As an alternative, you can use the binpatch dfhack command to apply/remove patches live in memory during a DF session.

In this case, updating symbols.xml is not necessary.

die

Instantly kills DF without saving.

forcepause

Forces DF to pause. This is useful when your FPS drops below 1 and you lose control of the game.

• Activate with 'forcepause 1'
• Deactivate with 'forcepause 0'

nopause

Disables pausing (both manual and automatic) with the exception of pause forced by 'reveal hell'. This is nice for digging under rivers.

fastdwarf

Controls speedydwarf and teledwarf. Speedydwarf makes dwarves move quickly and perform tasks quickly. Teledwarf makes dwarves move instantaneously, but do jobs at the same speed.

• 'fastdwarf 0 0' disables both
• 'fastdwarf 0 1' disables speedydwarf and enables teledwarf
• 'fastdwarf 1 0' enables speedydwarf and disables teledwarf
• 'fastdwarf 1 1' enables both
• 'fastdwarf 0' disables both
• 'fastdwarf 1' enables speedydwarf and disables teledwarf
• 'fastdwarf 2 ...' sets a native debug flag in the game memory that implements an even more aggressive version of speedydwarf.

follow

Makes the game view follow the currently highlighted unit after you exit from current menu/cursor mode. Handy for watching dwarves running around. Deactivated by moving the view manually.

tidlers

Toggle between all possible positions where the idlers count can be placed.

twaterlvl

Toggle between displaying/not displaying liquid depth as numbers.

copystock

Copies the parameters of the currently highlighted stockpile to the custom stockpile settings and switches to custom stockpile placement mode, effectively allowing you to copy/paste stockpiles easily.

rename

Allows renaming various things.

Options:

rename squad <index> "name":
	Rename squad by index to 'name'.
rename hotkey <index> "name":
	Rename hotkey by index. This allows assigning longer commands to the DF hotkeys.
rename unit "nickname":
	Rename a unit/creature highlighted in the DF user interface.
rename unit-profession "custom profession":
	Change proffession name of the highlighted unit/creature.
rename building "name":
	Set a custom name for the selected building. The building must be one of stockpile, workshop, furnace, trap, siege engine or an activity zone.

command-prompt

A one line command prompt in df. Same as entering command into dfhack console. Best used as a keybinding. Can be called with optional "entry" that will start prompt with that pre-filled.

rendermax

A collection of renderer replacing/enhancing filters. For better effect try changing the black color in palette to non totally black. For more info see thread in forums: http://www.bay12forums.com/smf/index.php?topic=128487.0

Options:

rendermax trippy:
	Randomizes each tiles color. Used for fun mainly.
rendermax light:
	Enable lighting engine.
rendermax light reload:
	Reload the settings file.
rendermax light sun <x>|cycle:
	Set time to <x> (in hours) or set it to df time cycle.
rendermax occlusionON|occlusionOFF:
	Show debug occlusion info.
rendermax disable:
	Disable any filter that is enabled.

An image showing lava and dragon breath. Not pictured here: sunlight, shining items/plants, materials that color the light etc...

adv-bodyswap

This allows taking control over your followers and other creatures in adventure mode. For example, you can make them pick up new arms and armor and equip them properly.

Usage:

• When viewing unit details, body-swaps into that unit.
• In the main adventure mode screen, reverts transient swap.

advtools

A package of different adventure mode tools (currently just one)

Usage:

list-equipped [all]:
	List armor and weapons equipped by your companions. If all is specified, also lists non-metal clothing.
metal-detector [all-types] [non-trader]:
	Reveal metal armor and weapons in shops. The options disable the checks on item type and being in shop.

3dveins

Removes all existing veins from the map and generates new ones using 3D Perlin noise, in order to produce a layout that smoothly flows between Z levels. The vein distribution is based on the world seed, so running the command for the second time should produce no change. It is best to run it just once immediately after embark.

This command is intended as only a cosmetic change, so it takes care to exactly preserve the mineral counts reported by prospect all. The amounts of different layer stone may slightly change in some cases if vein mass shifts between Z layers.

This command is very unlikely to work on maps generated before version 0.34.08.

Note that there is no undo option other than restoring from backup.

changelayer

Changes material of the geology layer under cursor to the specified inorganic RAW material. Can have impact on all surrounding regions, not only your embark! By default changing stone to soil and vice versa is not allowed. By default changes only the layer at the cursor position. Note that one layer can stretch across lots of z levels. By default changes only the geology which is linked to the biome under the cursor. That geology might be linked to other biomes as well, though. Mineral veins and gem clusters will stay on the map. Use 'changevein' for them.

tl;dr: You will end up with changing quite big areas in one go, especially if you use it in lower z levels. Use with care.

Options:

all_biomes:	Change selected layer for all biomes on your map. Result may be undesirable since the same layer can AND WILL be on different z-levels for different biomes. Use the tool 'probe' to get an idea how layers and biomes are distributed on your map.
all_layers:	Change all layers on your map (only for the selected biome unless 'all_biomes' is added). Candy mountain, anyone? Will make your map quite boring, but tidy.
force:	Allow changing stone to soil and vice versa. !!THIS CAN HAVE WEIRD EFFECTS, USE WITH CARE!! Note that soil will not be magically replaced with stone. You will, however, get a stone floor after digging so it will allow the floor to be engraved. Note that stone will not be magically replaced with soil. You will, however, get a soil floor after digging so it could be helpful for creating farm plots on maps with no soil.
verbose:	Give some details about what is being changed.
trouble:	Give some advice about known problems.

Examples:

changelayer GRANITE

Convert layer at cursor position into granite.

changelayer SILTY_CLAY force

Convert layer at cursor position into clay even if it's stone.

changelayer MARBLE all_biomes all_layers

Convert all layers of all biomes which are not soil into marble.

changevein

Changes material of the vein under cursor to the specified inorganic RAW material. Only affects tiles within the current 16x16 block - for veins and large clusters, you will need to use this command multiple times.

Example:

changevein NATIVE_PLATINUM

Convert vein at cursor position into platinum ore.

changeitem

Allows changing item material and base quality. By default the item currently selected in the UI will be changed (you can select items in the 'k' list or inside containers/inventory). By default change is only allowed if materials is of the same subtype (for example wood<->wood, stone<->stone etc). But since some transformations work pretty well and may be desired you can override this with 'force'. Note that some attributes will not be touched, possibly resulting in weirdness. To get an idea how the RAW id should look like, check some items with 'info'. Using 'force' might create items which are not touched by crafters/haulers.

Options:

info:	Don't change anything, print some info instead.
here:	Change all items at the cursor position. Requires in-game cursor.
material, m:	Change material. Must be followed by valid material RAW id.
quality, q:	Change base quality. Must be followed by number (0-5).
force:	Ignore subtypes, force change to new material.

Examples:

changeitem m INORGANIC:GRANITE here

Change material of all items under the cursor to granite.

changeitem q 5

Change currently selected item to masterpiece quality.

colonies

Allows listing all the vermin colonies on the map and optionally turning them into honey bee colonies.

Options:

bees:	turn colonies into honey bee colonies

createitem

Allows creating new items of arbitrary types and made of arbitrary materials. By default, items created are spawned at the feet of the selected unit.

Specify the item and material information as you would indicate them in custom reaction raws, with the following differences: * Separate the item and material with a space rather than a colon * If the item has no subtype, omit the :NONE * If the item is REMAINS, FISH, FISH_RAW, VERMIN, PET, or EGG, specify a CREATURE:CASTE pair instead of a material token.

Corpses, body parts, and prepared meals cannot be created using this tool.

Examples:

createitem GLOVES:ITEM_GLOVES_GAUNTLETS INORGANIC:STEEL 2

Create 2 pairs of steel gauntlets.

createitem WOOD PLANT_MAT:TOWER_CAP:WOOD

Create tower-cap logs.

createitem FISH FISH_SHAD:MALE 5

Create a stack of 5 cleaned shad, ready to eat.

To change where new items are placed, first run the command with a destination type while an appropriate destination is selected.

Options:

floor:	Subsequent items will be placed on the floor beneath the selected unit's feet.
item:	Subsequent items will be stored inside the currently selected item.
building:	Subsequent items will become part of the currently selected building. Best used for loading traps; do not use with workshops, or you will need to deconstruct the building to use the item.

deramp (by zilpin)

Removes all ramps designated for removal from the map. This is useful for replicating the old channel digging designation. It also removes any and all 'down ramps' that can remain after a cave-in (you don't have to designate anything for that to happen).

feature

Enables management of map features.

• Discovering a magma feature (magma pool, volcano, magma sea, or curious underground structure) permits magma workshops and furnaces to be built.
• Discovering a cavern layer causes plants (trees, shrubs, and grass) from that cavern to grow within your fortress.

Options:

list:	Lists all map features in your current embark by index.
show X:	Marks the selected map feature as discovered.
hide X:	Marks the selected map feature as undiscovered.

infiniteSky

Automatically allocates new z-levels of sky at the top of the map as you build up, or on request allocates many levels all at once.

Examples:

infiniteSky n Raise the sky by n z-levels. infiniteSky enable/disable Enables/disables monitoring of constructions. If you build anything in the second to highest z-level, it will allocate one more sky level. This is so you can continue to build stairs upward.

liquids

Allows adding magma, water and obsidian to the game. It replaces the normal dfhack command line and can't be used from a hotkey. Settings will be remembered as long as dfhack runs. Intended for use in combination with the command liquids-here (which can be bound to a hotkey).

For more information, refer to the command's internal help.

liquids-here

Run the liquid spawner with the current/last settings made in liquids (if no settings in liquids were made it paints a point of 7/7 magma by default).

Intended to be used as keybinding. Requires an active in-game cursor.

tiletypes

Can be used for painting map tiles and is an interactive command, much like liquids.

The tool works with two set of options and a brush. The brush determines which tiles will be processed. First set of options is the filter, which can exclude some of the tiles from the brush by looking at the tile properties. The second set of options is the paint - this determines how the selected tiles are changed.

Both paint and filter can have many different properties including things like general shape (WALL, FLOOR, etc.), general material (SOIL, STONE, MINERAL, etc.), state of 'designated', 'hidden' and 'light' flags.

The properties of filter and paint can be partially defined. This means that you can for example do something like this:

filter material STONE
filter shape FORTIFICATION
paint shape FLOOR

This will turn all stone fortifications into floors, preserving the material.

Or this:

filter shape FLOOR
filter material MINERAL
paint shape WALL

Turning mineral vein floors back into walls.

The tool also allows tweaking some tile flags:

Or this:

paint hidden 1
paint hidden 0

This will hide previously revealed tiles (or show hidden with the 0 option).

More recently, the tool supports changing the base material of the tile to an arbitrary stone from the raws, by creating new veins as required. Note that this mode paints under ice and constructions, instead of overwriting them. To enable, use:

paint stone MICROCLINE

This mode is incompatible with the regular material setting, so changing it cancels the specific stone selection:

paint material ANY

Since different vein types have different drop rates, it is possible to choose which one to use in painting:

paint veintype CLUSTER_SMALL

When the chosen type is CLUSTER (the default), the tool may automatically choose to use layer stone or lava stone instead of veins if its material matches the desired one.

Any paint or filter option (or the entire paint or filter) can be disabled entirely by using the ANY keyword:

paint hidden ANY
paint shape ANY
filter material any
filter shape any
filter any

You can use several different brushes for painting tiles:

• Point. (point)
• Rectangular range. (range)
• A column ranging from current cursor to the first solid tile above. (column)
• DF map block - 16x16 tiles, in a regular grid. (block)

Example:

range 10 10 1

This will change the brush to a rectangle spanning 10x10 tiles on one z-level. The range starts at the position of the cursor and goes to the east, south and up.

For more details, see the 'help' command while using this.

tiletypes-commands

Runs tiletypes commands, separated by ;. This makes it possible to change tiletypes modes from a hotkey.

tiletypes-here

Apply the current tiletypes options at the in-game cursor position, including the brush. Can be used from a hotkey.

tiletypes-here-point

Apply the current tiletypes options at the in-game cursor position to a single tile. Can be used from a hotkey.

tubefill

Fills all the adamantine veins again. Veins that were hollow will be left alone.

Options:

hollow:	fill in naturally hollow veins too

Beware that filling in hollow veins will trigger a demon invasion on top of your miner when you dig into the region that used to be hollow.

plant

A tool for creating shrubs, growing, or getting rid of them.

Subcommands:

create:	Create a new shrub/sapling.
grow:	Make saplings grow into trees.
extirpate:	Kills trees and shrubs, turning them into ashes instantly.
immolate:	Similar to extirpate, but sets the plants on fire instead. The fires can and will spread ;)

create creates a new sapling under the cursor. Takes a raw ID as argument (e.g. TOWER_CAP). The cursor must be located on a dirt or grass floor tile.

grow works on the sapling under the cursor, and turns it into a tree. Works on all shrubs of the map if the cursor is hidden.

extirpate and immolate work only on the plant under the cursor.

For mass effects, use one of the additional options:

shrubs:	affect all shrubs on the map
trees:	affect all trees on the map
all:	affect every plant!

regrass

Regrows grass. Not much to it ;)

weather

Prints the current weather map by default.

Also lets you change the current weather to 'clear sky', 'rainy' or 'snowing'.

Options:

snow:	make it snow everywhere.
rain:	make it rain.
clear:	clear the sky.

cursecheck

Checks a single map tile or the whole map/world for cursed creatures (ghosts, vampires, necromancers, werebeasts, zombies).

With an active in-game cursor only the selected tile will be observed. Without a cursor the whole map will be checked.

By default cursed creatures will be only counted in case you just want to find out if you have any of them running around in your fort. Dead and passive creatures (ghosts who were put to rest, killed vampires, ...) are ignored. Undead skeletons, corpses, bodyparts and the like are all thrown into the curse category "zombie". Anonymous zombies and resurrected body parts will show as "unnamed creature".

Options:

detail:	Print full name, date of birth, date of curse and some status info (some vampires might use fake identities in-game, though).
nick:	Set the type of curse as nickname (does not always show up in-game, some vamps don't like nicknames).
all:	Include dead and passive cursed creatures (can result in a quite long list after having FUN with necromancers).
verbose:	Print all curse tags (if you really want to know it all).

Examples:

cursecheck detail all

Give detailed info about all cursed creatures including deceased ones (no in-game cursor).

cursecheck nick

Give a nickname all living/active cursed creatures on the map(no in-game cursor).

flows

A tool for checking how many tiles contain flowing liquids. If you suspect that your magma sea leaks into HFS, you can use this tool to be sure without revealing the map.

probe

Can be used to determine tile properties like temperature.

prospect

Prints a big list of all the present minerals and plants. By default, only the visible part of the map is scanned.

Options:

all:	Scan the whole map, as if it was revealed.
value:	Show material value in the output. Most useful for gems.
hell:	Show the Z range of HFS tubes. Implies 'all'.

reveal

This reveals the map. By default, HFS will remain hidden so that the demons don't spawn. You can use 'reveal hell' to reveal everything. With hell revealed, you won't be able to unpause until you hide the map again. If you really want to unpause with hell revealed, use 'reveal demons'.

Reveal also works in adventure mode, but any of its effects are negated once you move. When you use it this way, you don't need to run 'unreveal'.

unreveal

Reverts the effects of 'reveal'.

revtoggle

Switches between 'reveal' and 'unreveal'.

revflood

This command will hide the whole map and then reveal all the tiles that have a path to the in-game cursor.

revforget

When you use reveal, it saves information about what was/wasn't visible before revealing everything. Unreveal uses this information to hide things again. This command throws away the information. For example, use in cases where you abandoned with the fort revealed and no longer want the data.

showmood

Shows all items needed for the currently active strange mood.

autoSyndrome

This plugin replaces "boiling rock" syndromes. Without this plugin, it is possible to add a syndrome to a unit by making the unit perform a custom reaction. First, add the syndrome to a rock which boils at room temperature. Make sure that the syndrome is spread by inhaling. Then, add a custom reaction which creates that rock. When the reaction is performed, the rock will be created, then boil. Hopefully, the dwarf will inhale the gas and become afflicted with the syndrome. This has disadvantages.

1. The creating unit might not inhale the gas. This makes it difficult to balance gameplay, as it is hard to measure this probability.
2. A different unit might inhale the gas. Pets or children might inhale the gas, which may be undesired.

To fix this problem, you can use autoSyndrome. The plugin monitors when custom reactions are completed within dwarf mode. If certain conditions are met, then the syndrome is immediately applied. The conditions are described below in priority order. If multiple products are created by the reaction, each one is considered independently in order. If a rock has multiple syndromes, each one is considered independently. If the conditions are all met, then the appropriate target will be instantly afficted with the appropriate syndrome, and the syndrome will behave just like any other.

1. The recently completed reaction must be a custom reaction, not a built-in one.
2. The product must be an inorganic boulder. Its boiling temperature is ignored.
3. The syndrome must have [SYN_CLASS:\AUTO_SYNDROME].
4. If the syndrome has [SYN_CLASS:\ALLOW_MULTIPLE_TARGETS] then an unbounded number of units can be targetted by the syndrome. If absent, at most one will be affected, and the worker will be considered first.
5. If the syndrome has [SYN_CLASS:\ALLOW_NONWORKER_TARGETS] then units that are in the building might be targetted. If absent, only the worker will be targetted. Even if present, the worker will be considered first.
6. If the syndrome has [SYN_CLASS:\PRESERVE_ROCK] then the stone or stones created will not be destroyed. If absent, they will be. Leaving this out ensures that gasses from boiling rocks will not sidestep the plugin, affecting nearby units using existing gameplay mechanics (because said gasses will never get a chance to be created).
7. If there are no SYN_IMMUNE_CREATURE, SYN_AFFECTED_CREATURE, SYN_IMMUNE_CLASS, or SYN_AFFECTED_CLASS then any creature can be targetted, if it meets the above restrictions.
8. If the target creature is specified as SYN_IMMUNE_CREATURE in the syndrome tags, then it will not be affected.
9. If it is specified as SYN_AFFECTED_CREATURE then it will be affected.
10. If it has SYN_IMMUNE_CLASS it will not be affected.
11. It it has SYN_AFFECTED_CLASS it will be affected.

Note that tags like [SYN_INHALED] are ignored.

The plugin will work for transformations, but doesn't seem to properly apply CE_BLEEDING, for example. Further testing is required.

If the reaction is run twice, by default, a second instance of the syndrome is added. This behavior can be customized. With [SYN_CLASS:\RESET_POLICY DoNothing], units already afflicted with the syndrome will not be considered for syndrome application. With [SYN_CLASS:\RESET_POLICY ResetDuration] the existing syndrome timer is reset. With [SYN_CLASS:\RESET_POLICY AddDuration] the duration of the longest effect in the syndrome is added to the remaining duration of the existing syndrome. The tag [SYN_CLASS:\RESET_POLICY NewInstance] re-establishes the default behavior. If more than one such tag is present, the last one takes priority.

It is also possible to directly trigger dfhack plugins and scripts using autoSyndrome. If a syndrome has [SYN_CLASS:\COMMAND] then all following SYN_CLASS tags will be used to create a console command. The command will behave exactly as if the user had typed it in to the dfhack console. For example

[SYN_CLASS:\COMMAND] [SYN_CLASS:prospect] [SYN_CLASS:all]

would run the command "prospect all" whenever the given rock is created. The \AUTO_SYNDROME tag IS required for commands to execute. Note that since all SYN_CLASS tags after the \COMMAND tag are interpreted as part of the command, tags like \WORKER_ONLY must be placed before \COMMAND, or not at all in order to work.

There are also certain "special" arguments that can be passed.

1. \LOCATION: pass the x, y, and z coordinates of the work tile of the building which completed the job as separate arguments.
2. \WORKER_ID: pass the unit id of the unit that finished the job as an argument.
3. \REACTION_INDEX: pass the id of the completed reaction as an argument.

A note on spaces: when a plugin command executes in dfhack, it always has a list of arguments. Arguments are strings which tell the plugin what the user wants it to do. When the user types in a command, arguments will be separated by whitespace. However, if autoSyndrome is given a tag like [SYN_CLASS:123 abcde] after a [SYN_CLASS:\COMMAND] tag, this will still be treated as ONE argument. This may or may not cause problems, depending on the command in question. To be safe, never include spaces in as an argument to a command.

For example, suppose a reaction creates a rock which has a syndrome with the SYN_CLASS tags \AUTO_SYNDROME, \COMMAND, printArgs, id_comes_next, \WORKER_ID, location_comes_next, \LOCATION in that order. Suppose the reaction is done at (35,96,112) by unit number 15. This would be equivalent to typing printArgs id_comes_next 15 location_comes_next 35 96 112 into the DFHack console and pressing enter.

Other syndrome classes that occur before \COMMAND (or in absence of any \COMMAND synclass) are ignored.

It is not currently possible to execute more than one command per syndrome. Instead, use multiple syndromes to achieve the same effect. Note that it is possible to have multiple syndromes on the same stone.

Again, note that plugins AND scripts can be executed this way, and arguments will be passed according to the same rules.

outsideOnly

This plugin makes it so that buildings whose names begin with OUTSIDE_ONLY cannot be built inside. If the player attempts to do so, the building will automatically be deconstructed.

syndromeTrigger

This plugin allows DFHack commands to be executed whenever a unit becomes afflicted with a syndrome. This can happen due to a boiling rock, an interaction, autoSyndrome, etc. Regardless of the cause, if the appropriate SYN_CLASS tags are present, the command will execute.

The syntax is very similar to autoSyndrome. If the syndrome has the \COMMAND tag, every subsequent SYN_CLASS tag will be used to create a console command. The following tags are "special":

1. \LOCATION: this will be replaced by three arguments, one for each coordinate of the location of the unit.
2. \UNIT_ID: this will be replaced by the identifier of the unit afllicted with the syndrome.
3. \SYNDROME_ID: this will be replaced by the identifier of the syndrome in question.

If there is a [SYN_CLASS:\AUTO_SYNDROME] tag, then the command, if any, will NOT be executed by syndromeTrigger, because it should already have been executed by autoSyndrome.

burrow

Miscellaneous burrow control. Allows manipulating burrows and automated burrow expansion while digging.

Options:

enable feature ...

Enable features of the plugin.

disable feature ...

Disable features of the plugin.

clear-unit burrow burrow ...

Remove all units from the burrows.

clear-tiles burrow burrow ...

Remove all tiles from the burrows.

set-units target-burrow src-burrow ...

Clear target, and adds units from source burrows.

add-units target-burrow src-burrow ...

Add units from the source burrows to the target.

remove-units target-burrow src-burrow ...

Remove units in source burrows from the target.

set-tiles target-burrow src-burrow ...

Clear target and adds tiles from the source burrows.

add-tiles target-burrow src-burrow ...

Add tiles from the source burrows to the target.

remove-tiles target-burrow src-burrow ...

Remove tiles in source burrows from the target.

For these three options, in place of a source burrow it is possible to use one of the following keywords: ABOVE_GROUND, SUBTERRANEAN, INSIDE, OUTSIDE, LIGHT, DARK, HIDDEN, REVEALED

Features:

auto-grow:	When a wall inside a burrow with a name ending in '+' is dug out, the burrow is extended to newly-revealed adjacent walls. This final '+' may be omitted in burrow name args of commands above. Digging 1-wide corridors with the miner inside the burrow is SLOW.

digv

Designates a whole vein for digging. Requires an active in-game cursor placed over a vein tile. With the 'x' option, it will traverse z-levels (putting stairs between the same-material tiles).

digvx

A permanent alias for 'digv x'.

digl

Designates layer stone for digging. Requires an active in-game cursor placed over a layer stone tile. With the 'x' option, it will traverse z-levels (putting stairs between the same-material tiles). With the 'undo' option it will remove the dig designation instead (if you realize that digging out a 50 z-level deep layer was not such a good idea after all).

diglx

A permanent alias for 'digl x'.

digexp

This command can be used for exploratory mining.

See: http://df.magmawiki.com/index.php/DF2010:Exploratory_mining

There are two variables that can be set: pattern and filter.

Patterns:

diag5:	diagonals separated by 5 tiles
diag5r:	diag5 rotated 90 degrees
ladder:	A 'ladder' pattern
ladderr:	ladder rotated 90 degrees
clear:	Just remove all dig designations
cross:	A cross, exactly in the middle of the map.

Filters:

all:	designate whole z-level
hidden:	designate only hidden tiles of z-level (default)
designated:	Take current designation and apply pattern to it.

After you have a pattern set, you can use 'expdig' to apply it again.

Examples:

designate the diagonal 5 patter over all hidden tiles:

• expdig diag5 hidden

apply last used pattern and filter:

• expdig

Take current designations and replace them with the ladder pattern:

• expdig ladder designated

digcircle

A command for easy designation of filled and hollow circles. It has several types of options.

Shape:

hollow:	Set the circle to hollow (default)
filled:	Set the circle to filled
#:	Diameter in tiles (default = 0, does nothing)

Action:

set:	Set designation (default)
unset:	Unset current designation
invert:	Invert designations already present

Designation types:

dig:	Normal digging designation (default)
ramp:	Ramp digging
ustair:	Staircase up
dstair:	Staircase down
xstair:	Staircase up/down
chan:	Dig channel

After you have set the options, the command called with no options repeats with the last selected parameters.

Examples:

• 'digcircle filled 3' = Dig a filled circle with radius = 3.
• 'digcircle' = Do it again.

digtype

For every tile on the map of the same vein type as the selected tile, this command designates it to have the same designation as the selected tile. If the selected tile has no designation, they will be dig designated. If an argument is given, the designation of the selected tile is ignored, and all appropriate tiles are set to the specified designation.

Options:

dig:
channel:
ramp:
updown:	up/down stairs
up:	up stairs
down:	down stairs
clear:	clear designation

digFlood

Automatically digs out specified veins as they are discovered. It runs once every time a dwarf finishes a dig job. It will only dig out appropriate tiles that are adjacent to the finished dig job. To add a vein type, use digFlood 1 [type]. This will also enable the plugin. To remove a vein type, use digFlood 0 [type] 1 to disable, then remove, then re-enable.

digFlood 0 disable

digFlood 1 enable

digFlood 0 MICROCLINE COAL_BITUMINOUS 1 disable plugin, remove microcline and bituminous coal from monitoring, then re-enable the plugin

digFlood CLEAR remove all inorganics from monitoring

digFlood digAll1 ignore the monitor list and dig any vein

digFlood digAll0 disable digAll mode

See help digFlood for details.

filltraffic

Set traffic designations using flood-fill starting at the cursor.

Traffic Type Codes:

H:	High Traffic
N:	Normal Traffic
L:	Low Traffic
R:	Restricted Traffic

Other Options:

X:	Fill accross z-levels.
B:	Include buildings and stockpiles.
P:	Include empty space.

Example:

'filltraffic H' - When used in a room with doors, it will set traffic to HIGH in just that room.

alltraffic

Set traffic designations for every single tile of the map (useful for resetting traffic designations).

Traffic Type Codes:

H:	High Traffic
N:	Normal Traffic
L:	Low Traffic
R:	Restricted Traffic

Example:

'alltraffic N' - Set traffic to 'normal' for all tiles.

restrictliquid

Restrict traffic on all visible tiles with liquid.

restrictice

Restrict traffic on all tiles on top of visible ice.

getplants

This tool allows plant gathering and tree cutting by RAW ID. Specify the types of trees to cut down and/or shrubs to gather by their plant names, separated by spaces.

Options:

-t:	Select trees only (exclude shrubs)
-s:	Select shrubs only (exclude trees)
-c:	Clear designations instead of setting them
-x:	Apply selected action to all plants except those specified (invert selection)

Specifying both -t and -s will have no effect. If no plant IDs are specified, all valid plant IDs will be listed.

clean

Cleans all the splatter that get scattered all over the map, items and creatures. In an old fortress, this can significantly reduce FPS lag. It can also spoil your !!FUN!!, so think before you use it.

Options:

map:	Clean the map tiles. By default, it leaves mud and snow alone.
units:	Clean the creatures. Will also clean hostiles.
items:	Clean all the items. Even a poisoned blade.

Extra options for 'map':

mud:	Remove mud in addition to the normal stuff.
snow:	Also remove snow coverings.

spotclean

Works like 'clean map snow mud', but only for the tile under the cursor. Ideal if you want to keep that bloody entrance 'clean map' would clean up.

autodump

This utility lets you quickly move all items designated to be dumped. Items are instantly moved to the cursor position, the dump flag is unset, and the forbid flag is set, as if it had been dumped normally. Be aware that any active dump item tasks still point at the item.

Cursor must be placed on a floor tile so the items can be dumped there.

Options:

destroy:	Destroy instead of dumping. Doesn't require a cursor.
destroy-here:	Destroy items only under the cursor.
visible:	Only process items that are not hidden.
hidden:	Only process hidden items.
forbidden:	Only process forbidden items (default: only unforbidden).

autodump-destroy-here

Destroy items marked for dumping under cursor. Identical to autodump destroy-here, but intended for use as keybinding.

autodump-destroy-item

Destroy the selected item. The item may be selected in the 'k' list, or inside a container. If called again before the game is resumed, cancels destroy.

cleanowned

Confiscates items owned by dwarfs. By default, owned food on the floor and rotten items are confistacted and dumped.

Options:

all:	confiscate all owned items
scattered:	confiscated and dump all items scattered on the floor
x:	confiscate/dump items with wear level 'x' and more
X:	confiscate/dump items with wear level 'X' and more
dryrun:	a dry run. combine with other options to see what will happen without it actually happening.

Example:

cleanowned scattered X

This will confiscate rotten and dropped food, garbage on the floors and any worn items with 'X' damage and above.

drybuckets

This utility removes water from all buckets in your fortress, allowing them to be safely used for making lye.

fixdiplomats

Up to version 0.31.12, Elves only sent Diplomats to your fortress to propose tree cutting quotas due to a bug; once that bug was fixed, Elves stopped caring about excess tree cutting. This command adds a Diplomat position to all Elven civilizations, allowing them to negotiate tree cutting quotas (and allowing you to violate them and potentially start wars) in case you haven't already modified your raws accordingly.

fixmerchants

This command adds the Guild Representative position to all Human civilizations, allowing them to make trade agreements (just as they did back in 0.28.181.40d and earlier) in case you haven't already modified your raws accordingly.

fixveins

Removes invalid references to mineral inclusions and restores missing ones. Use this if you broke your embark with tools like tiletypes, or if you accidentally placed a construction on top of a valuable mineral floor.

tweak

Contains various tweaks for minor bugs.

One-shot subcommands:

Subcommands that persist until disabled or DF quit:

stable-cursor:	Saves the exact cursor position between t/q/k/d/etc menus of dwarfmode.
patrol-duty:	Makes Train orders not count as patrol duty to stop unhappy thoughts. Does NOT fix the problem when soldiers go off-duty (i.e. civilian).
readable-build-plate:
	Fixes rendering of creature weight limits in pressure plate build menu.
stable-temp:	Fixes performance bug 6012 by squashing jitter in temperature updates. In very item-heavy forts with big stockpiles this can improve FPS by 50-100%
fast-heat:	Further improves temperature update performance by ensuring that 1 degree of item temperature is crossed in no more than specified number of frames when updating from the environment temperature. This reduces the time it takes for stable-temp to stop updates again when equilibrium is disturbed.
fix-dimensions:	Fixes subtracting small amount of thread/cloth/liquid from a stack by splitting the stack and subtracting from the remaining single item. This is a necessary addition to the binary patch in bug 808.
advmode-contained:
	Works around bug 6202, i.e. custom reactions with container inputs in advmode. The issue is that the screen tries to force you to select the contents separately from the container. This forcefully skips child reagents.
fast-trade:	Makes Shift-Enter in the Move Goods to Depot and Trade screens select the current item (fully, in case of a stack), and scroll down one line.
military-stable-assign:
	Preserve list order and cursor position when assigning to squad, i.e. stop the rightmost list of the Positions page of the military screen from constantly resetting to the top.
military-color-assigned:
	Color squad candidates already assigned to other squads in yellow/green to make them stand out more in the list.
military-training:
	Speeds up melee squad training by removing an almost certainly unintended inverse dependency of training speed on unit count (i.e. the more units you have, the slower it becomes), and making the units spar more.
hive-crash:	The hive code crashes if there are ungathered products in a hive without bees (bug 6368). This tweak prevents it by auto-gathering the products if this happens.
craft-age-wear:	Fixes the behavior of crafted items wearing out over time (bug 6003). With this tweak, items made from cloth and leather will gain a level of wear every 20 years.
adamantine-cloth-wear:
	Prevents adamantine clothing from wearing out while being worn (bug 6481).

fix-armory

Enables a fix for storage of squad equipment in barracks.

Specifically, it prevents your haulers from moving squad equipment to stockpiles, and instead queues jobs to store it on weapon racks, armor stands, and in containers.

Note that the buildings in the armory are used as follows:

• Weapon racks (when patched) are used to store any assigned weapons. Each rack belongs to a specific squad, and can store up to 5 weapons.
• Armor stands belong to specific squad members and are used for armor and shields. By default one stand can store one item of each type (hence one boot or gauntlet); if patched, the limit is raised to 2, which should be sufficient.
• Cabinets are used to store assigned clothing for a specific squad member. They are never used to store owned clothing.
• Chests (boxes, etc) are used for a flask, backpack or quiver assigned to the squad member. Due to a probable bug, food is dropped out of the backpack when it is stored.

Contrary to the common misconception, all these uses are controlled by the Individual Equipment usage flag. The Squad Equipment flag is actually intended for ammo, but the game does even less in that area than for armor and weapons. This plugin implements the following rules almost from scratch:

• Combat ammo is stored in chests inside rooms with Squad Equipment enabled.
• If a chest is assigned to a squad member due to Individual Equipment also being set, it is only used for that squad's ammo; otherwise, any squads with Squad Equipment on the room will use all of the chests at random.
• Training ammo is stored in chests inside archery ranges designated from archery targets, and controlled by the same Train flag as archery training itself. This is inspired by some defunct code for weapon racks.

There are some minor traces in the game code to suggest that the first of these rules is intended by Toady; the rest are invented by this plugin.

lair

This command allows you to mark the map as 'monster lair', preventing item scatter on abandon. When invoked as 'lair reset', it does the opposite.

Unlike reveal, this command doesn't save the information about tiles - you won't be able to restore state of real monster lairs using 'lair reset'.

Options:

lair:	Mark the map as monster lair
lair reset:	Mark the map as ordinary (not lair)

mode

This command lets you see and change the game mode directly. Not all combinations are good for every situation and most of them will produce undesirable results. There are a few good ones though.

I take no responsibility of anything that happens as a result of using this tool

ssense / stonesense

An isometric visualizer that runs in a second window. This requires working graphics acceleration and at least a dual core CPU (otherwise it will slow down DF).

All the data resides in the 'stonesense' directory. For detailed instructions, see stonesense/README.txt

Compatible with Windows > XP SP3 and most modern Linux distributions.

Older versions, support and extra graphics can be found in the bay12 forum thread: http://www.bay12forums.com/smf/index.php?topic=43260.0

Some additional resources: http://df.magmawiki.com/index.php/Utility:Stonesense/Content_repository

mapexport

Export the current loaded map as a file. This will be eventually usable with visualizers.

dwarfexport

Export dwarves to RuneSmith-compatible XML.

exportlegends

Exports data from legends mode; allowing a set-and-forget export of large worlds.

Options:

maps:	Exports all fifteen detailed maps
all:	first exports the world/gen info, then the XML, then all detailed maps

job

Command for general job query and manipulation.

Options:

no extra options

Print details of the current job. The job can be selected in a workshop, or the unit/jobs screen.

list

Print details of all jobs in the selected workshop.

item-material <item-idx> <material[:subtoken]>

Replace the exact material id in the job item.

item-type <item-idx> <type[:subtype]>

Replace the exact item type id in the job item.

job-material

Alter the material of the selected job.

Invoked as:

job-material <inorganic-token>

Intended to be used as a keybinding:

• In 'q' mode, when a job is highlighted within a workshop or furnace, changes the material of the job. Only inorganic materials can be used in this mode.
• In 'b' mode, during selection of building components positions the cursor over the first available choice with the matching material.

job-duplicate

Duplicate the selected job in a workshop:

• In 'q' mode, when a job is highlighted within a workshop or furnace building, instantly duplicates the job.

stockflow

Allows the fortress bookkeeper to queue jobs through the manager.

Usage:

stockflow enable

Enable the plugin.

stockflow disable

Disable the plugin.

stockflow list

List any work order settings for your stockpiles.

stockflow status

Display whether the plugin is enabled.

While enabled, the 'q' menu of each stockpile will have two new options:

• j: Select a job to order, from an interface like the manager's screen.
• J: Cycle between several options for how many such jobs to order.

Whenever the bookkeeper updates stockpile records, new work orders will be placed on the manager's queue for each such selection, reduced by the number of identical orders already in the queue.

workflow

Manage control of repeat jobs.

Usage:

workflow enable [option...], workflow disable [option...]

If no options are specified, enables or disables the plugin. Otherwise, enables or disables any of the following options:

• drybuckets: Automatically empty abandoned water buckets.
• auto-melt: Resume melt jobs when there are objects to melt.

workflow jobs

List workflow-controlled jobs (if in a workshop, filtered by it).

workflow list

List active constraints, and their job counts.

workflow list-commands

List active constraints as workflow commands that re-create them; this list can be copied to a file, and then reloaded using the script built-in command.

workflow count <constraint-spec> <cnt-limit> [cnt-gap]

Set a constraint, counting every stack as 1 item.

workflow amount <constraint-spec> <cnt-limit> [cnt-gap]

Set a constraint, counting all items within stacks.

workflow unlimit <constraint-spec>

Delete a constraint.

workflow unlimit-all

Delete all constraints.

ITEM[:SUBTYPE]/[GENERIC_MAT,...]/[SPECIFIC_MAT:...]/[LOCAL,<quality>]

workflow amount AMMO:ITEM_AMMO_BOLTS/METAL 1000 100
workflow amount AMMO:ITEM_AMMO_BOLTS/WOOD,BONE 200 50

workflow count FOOD 120 30
workflow count DRINK 120 30

workflow count BIN 30
workflow count BARREL 30
workflow count BOX/CLOTH,SILK,YARN 30

workflow count BAR//COAL 20
workflow count BAR//COPPER 30

workflow count CRAFTS//GOLD 20

workflow count POWDER_MISC/SAND 20
workflow count BOULDER/CLAY 20

workflow amount POWDER_MISC//MUSHROOM_CUP_DIMPLE:MILL 100 20

workflow count CRAFTS///LOCAL,EXCEPTIONAL 100 90

seedwatch

Tool for turning cooking of seeds and plants on/off depending on how much you have of them.

See 'seedwatch help' for detailed description.

zone

Helps a bit with managing activity zones (pens, pastures and pits) and cages.

Options:

set:	Set zone or cage under cursor as default for future assigns.
assign:	Assign unit(s) to the pen or pit marked with the 'set' command. If no filters are set a unit must be selected in the in-game ui. Can also be followed by a valid zone id which will be set instead.
unassign:	Unassign selected creature from it's zone.
nick:	Mass-assign nicknames, must be followed by the name you want to set.
remnick:	Mass-remove nicknames.
tocages:	Assign unit(s) to cages inside a pasture.
uinfo:	Print info about unit(s). If no filters are set a unit must be selected in the in-game ui.
zinfo:	Print info about zone(s). If no filters are set zones under the cursor are listed.
verbose:	Print some more info.
filters:	Print list of valid filter options.
examples:	Print some usage examples.
not:	Negates the next filter keyword.

Filters:

all:	Process all units (to be used with additional filters).
count:	Must be followed by a number. Process only n units (to be used with additional filters).
unassigned:	Not assigned to zone, chain or built cage.
minage:	Minimum age. Must be followed by number.
maxage:	Maximum age. Must be followed by number.
race:	Must be followed by a race RAW ID (e.g. BIRD_TURKEY, ALPACA, etc). Negatable.
caged:	In a built cage. Negatable.
own:	From own civilization. Negatable.
merchant:	Is a merchant / belongs to a merchant. Should only be used for pitting, not for stealing animals (slaughter should work).
war:	Trained war creature. Negatable.
hunting:	Trained hunting creature. Negatable.
tamed:	Creature is tame. Negatable.
trained:	Creature is trained. Finds war/hunting creatures as well as creatures who have a training level greater than 'domesticated'. If you want to specifically search for war/hunting creatures use 'war' or 'hunting' Negatable.
trainablewar:	Creature can be trained for war (and is not already trained for war/hunt). Negatable.
trainablehunt:	Creature can be trained for hunting (and is not already trained for war/hunt). Negatable.
male:	Creature is male. Negatable.
female:	Creature is female. Negatable.
egglayer:	Race lays eggs. Negatable.
grazer:	Race is a grazer. Negatable.
milkable:	Race is milkable. Negatable.

autonestbox

Assigns unpastured female egg-layers to nestbox zones. Requires that you create pen/pasture zones above nestboxes. If the pen is bigger than 1x1 the nestbox must be in the top left corner. Only 1 unit will be assigned per pen, regardless of the size. The age of the units is currently not checked, most birds grow up quite fast. Egglayers who are also grazers will be ignored, since confining them to a 1x1 pasture is not a good idea. Only tame and domesticated own units are processed since pasturing half-trained wild egglayers could destroy your neat nestbox zones when they revert to wild. When called without options autonestbox will instantly run once.

Options:

start:	Start running every X frames (df simulation ticks). Default: X=6000, which would be every 60 seconds at 100fps.
stop:	Stop running automatically.
sleep:	Must be followed by number X. Changes the timer to sleep X frames between runs.

autobutcher

Assigns lifestock for slaughter once it reaches a specific count. Requires that you add the target race(s) to a watch list. Only tame units will be processed.

Named units will be completely ignored (to protect specific animals from autobutcher you can give them nicknames with the tool 'rename unit' for single units or with 'zone nick' to mass-rename units in pastures and cages).

Creatures trained for war or hunting will be ignored as well.

Creatures assigned to cages will be ignored if the cage is defined as a room (to avoid butchering unnamed zoo animals).

Once you have too much adults, the oldest will be butchered first. Once you have too much kids, the youngest will be butchered first. If you don't set any target count the following default will be used: 1 male kid, 5 female kids, 1 male adult, 5 female adults.

Options:

start:	Start running every X frames (df simulation ticks). Default: X=6000, which would be every 60 seconds at 100fps.
stop:	Stop running automatically.
sleep:	Must be followed by number X. Changes the timer to sleep X frames between runs.
watch R:	Start watching a race. R can be a valid race RAW id (ALPACA, BIRD_TURKEY, etc) or a list of ids seperated by spaces or the keyword 'all' which affects all races on your current watchlist.
unwatch R:	Stop watching race(s). The current target settings will be remembered. R can be a list of ids or the keyword 'all'.
forget R:	Stop watching race(s) and forget it's/their target settings. R can be a list of ids or the keyword 'all'.
autowatch:	Automatically adds all new races (animals you buy from merchants, tame yourself or get from migrants) to the watch list using default target count.
noautowatch:	Stop auto-adding new races to the watchlist.
list:	Print the current status and watchlist.
list_export:	Print status and watchlist in a format which can be used to import them to another savegame (see notes).
target fk mk fa ma R:
	Set target count for specified race(s). fk = number of female kids, mk = number of male kids, fa = number of female adults, ma = number of female adults. R can be a list of ids or the keyword 'all' or 'new'. R = 'all': change target count for all races on watchlist and set the new default for the future. R = 'new': don't touch current settings on the watchlist, only set the new default for future entries.
example:	Print some usage examples.

Examples:

You want to keep max 7 kids (4 female, 3 male) and max 3 adults (2 female, 1 male) of the race alpaca. Once the kids grow up the oldest adults will get slaughtered. Excess kids will get slaughtered starting with the youngest to allow that the older ones grow into adults. Any unnamed cats will be slaughtered as soon as possible.

autobutcher target 4 3 2 1 ALPACA BIRD_TURKEY
autobutcher target 0 0 0 0 CAT
autobutcher watch ALPACA BIRD_TURKEY CAT
autobutcher start

Automatically put all new races onto the watchlist and mark unnamed tame units for slaughter as soon as they arrive in your fort. Settings already made for specific races will be left untouched.

autobutcher target 0 0 0 0 new
autobutcher autowatch
autobutcher start

Stop watching the races alpaca and cat, but remember the target count settings so that you can use 'unwatch' without the need to enter the values again. Note: 'autobutcher unwatch all' works, but only makes sense if you want to keep the plugin running with the 'autowatch' feature or manually add some new races with 'watch'. If you simply want to stop it completely use 'autobutcher stop' instead.

autobutcher unwatch ALPACA CAT

Note:

Settings and watchlist are stored in the savegame, so that you can have different settings for each world. If you want to copy your watchlist to another savegame you can use the command list_export:

Load savegame where you made the settings.
Start a CMD shell and navigate to the df directory. Type the following into the shell:
dfhack-run autobutcher list_export > autobutcher.bat
Load the savegame where you want to copy the settings to, run the batch file (from the shell):
autobutcher.bat

autochop

Automatically manage tree cutting designation to keep available logs withing given quotas.

Open the dashboard by running:

getplants autochop

The plugin must be activated (with 'a') before it can be used. You can then set logging quotas and restrict designations to specific burrows (with 'Enter') if desired. The plugin's activity cycle runs once every in game day.

If you add

enable getplants

to your dfhack.init there will be a hotkey to open the dashboard from the chop designation menu.

autolabor

Automatically manage dwarf labors.

When enabled, autolabor periodically checks your dwarves and enables or disables labors. It tries to keep as many dwarves as possible busy but also tries to have dwarves specialize in specific skills.

For detailed usage information, see 'help autolabor'.

catsplosion

Makes cats just multiply. It is not a good idea to run this more than once or twice.

dfusion

This is the DFusion lua plugin system by Warmist, running as a DFHack plugin. There are two parts to this plugin: an interactive script that shows a text based menu and lua modules. Some of the functionality of is intentionaly left out of the menu:

Friendship:	a binary plugin that allows multi race forts (to use make a script that imports plugins.dfusion.friendship and use Friendship:install{table} table should contain list of race names.)
Embark:	a binary plugin that allows multi race embark (to use make a script that imports plugins.dfusion.embark and use Embark:install{table} table should contain list of race names or list of pairs (race-name, caste_id)).

See the bay12 thread for details: http://www.bay12forums.com/smf/index.php?topic=93317.0

misery

When enabled, every new negative dwarven thought will be multiplied by a factor (2 by default).

Usage:

strangemood

Creates a strange mood job the same way the game itself normally does it.

Options:

-force:	Ignore normal strange mood preconditions (no recent mood, minimum moodable population, artifact limit not reached).
-unit:	Make the strange mood strike the selected unit instead of picking one randomly. Unit eligibility is still enforced.
-type T:	Force the mood to be of a particular type instead of choosing randomly based on happiness. Valid values are "fey", "secretive", "possessed", "fell", and "macabre".
-skill S:	Force the mood to use a specific skill instead of choosing the highest moodable skill. Valid values are "miner", "carpenter", "engraver", "mason", "tanner", "weaver", "clothier", "weaponsmith", "armorsmith", "metalsmith", "gemcutter", "gemsetter", "woodcrafter", "stonecrafter", "metalcrafter", "glassmaker", "leatherworker", "bonecarver", "bowyer", and "mechanic".

Known limitations: if the selected unit is currently performing a job, the mood will not be started.

log-region

When enabled in dfhack.init, each time a fort is loaded identifying information will be written to the gamelog. Assists in parsing the file if you switch between forts, and adds information for story-building.

Rationale

Siege engines are a very interesting feature, but sadly almost useless in the current state because they haven't been updated since 2D and can only aim in four directions. This is an attempt to bring them more up to date until Toady has time to work on it. Actual improvements, e.g. like making siegers bring their own, are something only Toady can do.

Configuration UI

The configuration front-end to the plugin is implemented by the gui/siege-engine script. Bind it to a key (the example config uses Alt-A) and activate after selecting a siege engine in 'q' mode.

The main mode displays the current target, selected ammo item type, linked stockpiles and the allowed operator skill range. The map tile color is changed to signify if it can be hit by the selected engine: green for fully reachable, blue for out of range, red for blocked, yellow for partially blocked.

Pressing 'r' changes into the target selection mode, which works by highlighting two points with Enter like all designations. When a target area is set, the engine projectiles are aimed at that area, or units within it (this doesn't actually change the original aiming code, instead the projectile trajectory parameters are rewritten as soon as it appears).

After setting the target in this way for one engine, you can 'paste' the same area into others just by pressing 'p' in the main page of this script. The area to paste is kept until you quit DF, or select another area manually.

Pressing 't' switches to a mode for selecting a stockpile to take ammo from.

Exiting from the siege engine script via ESC reverts the view to the state prior to starting the script. Shift-ESC retains the current viewport, and also exits from the 'q' mode to main menu.

Rationale

The vanilla game contains only water wheels and windmills as sources of power, but windmills give relatively little power, and water wheels require flowing water, which must either be a real river and thus immovable and limited in supply, or actually flowing and thus laggy.

Steam engines are an alternative to water reactors that actually makes sense, and hopefully doesn't lag. Also, unlike e.g. animal treadmills, it can be done just by combining existing features of the game engine in a new way with some glue code and a bit of custom logic.

Construction

The workshop needs water as its input, which it takes via a passable floor tile below it, like usual magma workshops do. The magma version also needs magma.

After constructing the building itself, machines can be connected to the edge tiles that look like gear boxes. Their exact position is extracted from the workshop raws.

Operation

In order to operate the engine, queue the Stoke Boiler job (optionally on repeat). A furnace operator will come, possibly bringing a bar of fuel, and perform it. As a result, a "boiling water" item will appear in the 't' view of the workshop.

Every such item gives 100 power, up to a limit of 300 for coal, and 500 for a magma engine. The building can host twice that amount of items to provide longer autonomous running. When the boiler gets filled to capacity, all queued jobs are suspended; once it drops back to 3+1 or 5+1 items, they are re-enabled.

While the engine is providing power, steam is being consumed. The consumption speed includes a fixed 10% waste rate, and the remaining 90% are applied proportionally to the actual load in the machine. With the engine at nominal 300 power with 150 load in the system, it will consume steam for actual 300*(10% + 90%*150/300) = 165 power.

Masterpiece mechanism and chain will decrease the mechanical power drawn by the engine itself from 10 to 5. Masterpiece barrel decreases waste rate by 4%. Masterpiece piston and pipe decrease it by further 4%, and also decrease the whole steam use rate by 10%.

Explosions

The engine must be constructed using barrel, pipe and piston from fire-safe, or in the magma version magma-safe metals.

During operation weak parts get gradually worn out, and eventually the engine explodes. It should also explode if toppled during operation by a building destroyer, or a tantruming dwarf.

Save files

It should be safe to load and view engine-using fortresses from a DF version without DFHack installed, except that in such case the engines won't work. However actually making modifications to them, or machines they connect to (including by pulling levers), can easily result in inconsistent state once this plugin is available again. The effects may be as weird as negative power being generated.