Dfhack Automatic Job Assignments

DFHack plugins are the commands, that are compiled with a specific version. They can provide anything from a small keybinding, to a complete overhaul of game subsystems or the entire renderer.

Most commands offered by plugins are listed here, hopefully organised in a way you will find useful.

Data inspection and visualizers¶

stonesense¶

An isometric visualizer that runs in a second window. Usage:

stonesense:Open the visualiser in a new window. Alias .
ssense overlay:Overlay DF window, replacing the map area.

For more information, see the full Stonesense README.

blueprint¶

Exports a portion of your fortress into QuickFort style blueprint files.:

Options (If only region and name are given, export all):

x,y,z:Size of map area to export
name:Name of export files
dig:Export dig commands to “<name>-dig.csv”
build:Export build commands to “<name>-build.csv”
place:Export stockpile commands to “<name>-place.csv”
query:Export query commands to “<name>-query.csv”

Goes very well with fortplan, for re-importing.

blueprint<x><y><z><name>[dig][build][place][query]

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:

Give detailed info about all cursed creatures including deceased ones (no in-game cursor).
Give a nickname all living/active cursed creatures on the map(no in-game cursor).

Note

If you do a full search (with the option “all”) former ghosts will show up with the cursetype “unknown” because their ghostly flag is not set.

Please report any living/active creatures with cursetype “unknown” - this is most likely with mods which introduce new types of curses.

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.

pathable¶

This plugin implements the back end of the gui/pathable script. It exports a single Lua function, in :

  • : Paint each visible of the screen green or red, depending on whether it can be pathed to from the tile at . If is specified and true, do not draw unrevealed tiles.

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

If prospect is called during the embark selection screen, it displays an estimate of layer stone availability.

Note

The results of pre-embark prospect are an estimate, and can at best be expected to be somewhere within +/- 30% of the true amount; sometimes it does a lot worse. Especially, it is not clear how to precisely compute how many soil layers there will be in a given embark tile, so it can report a whole extra layer, or omit one that is actually present.

Options:

all:Also estimate vein mineral amounts.

reveal¶

This reveals the map. By default, HFS will remain hidden so that the demons don’t spawn. You can use 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 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 .

Usage and related commands:

reveal:Reveal the whole map, except for HFS to avoid demons spawning
reveal hell:Also show hell, but requires before unpausing
reveal demon:Reveals everything and allows unpausing - good luck!
unreveal:Reverts the effects of
revtoggle:Switches between and
revflood:Hide everything, then reveal tiles with a path to the cursor (useful to make walled-off rooms vanish)
revforget:Discard info about what was visible before revealing the map. Only useful where (eg) you abandoned with the fort revealed and no longer want the data.

showmood¶

Shows all items needed for the currently active strange mood.

Bugfixes¶

fix-unit-occupancy¶

This plugin fixes issues with unit occupancy, notably phantom “unit blocking tile” messages (Bug 3499). It can be run manually, or periodically when enabled with the built-in enable/disable commands:

(no argument):Run the plugin once immediately, for the whole map.
-h, here, cursor:
 Run immediately, only operate on the tile at the cursor
-n, dry, dry-run:
 Run immediately, do not write changes to map
interval <X>:Run the plugin every ticks (when enabled). The default is 1200 ticks, or 1 day. Ticks are only counted when the game is unpaused.

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.

petcapRemover¶

Allows you to remove or raise the pet population cap. In vanilla DF, pets will not reproduce unless the population is below 50 and the number of children of that species is below a certain percentage. This plugin allows removing the second restriction and removing or raising the first. Pets still require PET or PET_EXOTIC tags in order to reproduce. Type for exact usage. In order to make population more stable and avoid sudden population booms as you go below the raised population cap, this plugin counts pregnancies toward the new population cap. It can still go over, but only in the case of multiple births.

Usage:

petcapRemover:cause pregnancies now and schedule the next check
petcapRemover every n:
 set how often in ticks the plugin checks for possible pregnancies
petcapRemover cap n:
 set the new cap to n. if n = 0, no cap
petcapRemover pregtime n:
 sets the pregnancy duration to n ticks. natural pregnancies are 300000 ticks for the current race and 200000 for everyone else

tweak¶

Contains various tweaks for minor bugs.

One-shot subcommands:

clear-missing:Remove the missing status from the selected unit. This allows engraving slabs for ghostly, but not yet found, creatures.
clear-ghostly:Remove the ghostly status from the selected unit and mark it as dead. This allows getting rid of bugged ghosts which do not show up in the engraving slab menu at all, even after using clear-missing. It works, but is potentially very dangerous - so use with care. Probably (almost certainly) it does not have the same effects like a proper burial. You’ve been warned.
fixmigrant:Remove the resident/merchant flag from the selected unit. Intended to fix bugged migrants/traders who stay at the map edge and don’t enter your fort. Only works for dwarves (or generally the player’s race in modded games). Do NOT abuse this for ‘real’ caravan merchants (if you really want to kidnap them, use ‘tweak makeown’ instead, otherwise they will have their clothes set to forbidden etc).
makeown:Force selected unit to become a member of your fort. Can be abused to grab caravan merchants and escorts, even if they don’t belong to the player’s race. Foreign sentients (humans, elves) can be put to work, but you can’t assign rooms to them and they don’t show up in DwarfTherapist because the game treats them like pets. Grabbing draft animals from a caravan can result in weirdness (animals go insane or berserk and are not flagged as tame), but you are allowed to mark them for slaughter. Grabbing wagons results in some funny spam, then they are scuttled.

Subcommands that persist until disabled or DF quits:

adamantine-cloth-wear:
 

Prevents adamantine clothing from wearing out while being worn (Bug 6481).

advmode-contained:
 

Works around Bug 6202, 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.

block-labors:

Prevents labors that can’t be used from being toggled

burrow-name-cancel:
 

Implements the “back” option when renaming a burrow, which currently does nothing (Bug 1518)

cage-butcher:

Adds an option to butcher units when viewing cages with

civ-view-agreement:
 

Fixes overlapping text on the “view agreement” screen

condition-material:
 

Fixes a crash in the work order contition material list (Bug 9905).

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.

embark-profile-name:
 

Allows the use of lowercase letters when saving embark profiles

eggs-fertile:

Displays a fertility indicator on nestboxes

farm-plot-select:
 

Adds “Select all” and “Deselect all” options to farm plot menus

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.

fast-trade:

Makes Shift-Down in the Move Goods to Depot and Trade screens select the current item (fully, in case of a stack), and scroll down one line.

fps-min:

Fixes the in-game minimum FPS setting

hide-priority:

Adds an option to hide designation priority indicators

hotkey-clear:

Adds an option to clear currently-bound hotkeys (in the menu)

import-priority-category:
 

Allows changing the priority of all goods in a category when discussing an import agreement with the liaison

kitchen-prefs-color:
 

Changes color of enabled items to green in kitchen preferences

kitchen-prefs-empty:
 

Fixes a layout issue with empty kitchen tabs (Bug 9000)

max-wheelbarrow:
 

Allows assigning more than 3 wheelbarrows to a stockpile

military-color-assigned:
 

Color squad candidates already assigned to other squads in yellow/green to make them stand out more in the list.

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.

nestbox-color:

Fixes the color of built nestboxes

shift-8-scroll:

Gives Shift-8 (or ) priority when scrolling menus, instead of scrolling the map

stable-cursor:

Saves the exact cursor position between t/q/k/d/b/etc menus of fortress mode.

title-start-rename:
 

Adds a safe rename option to the title screen “Start Playing” menu

tradereq-pet-gender:
 

Displays pet genders on the trade request screen

UI Upgrades¶

Note

In order to avoid user confusion, as a matter of policy all GUI tools display the word DFHack on the screen somewhere while active.

When that is not appropriate because they merely add keybinding hints to existing DF screens, they deliberately use red instead of green for the key.

automelt¶

When automelt is enabled for a stockpile, any meltable items placed in it will be designated to be melted. This plugin adds an option to the menu when enabled.

autotrade¶

When autotrade is enabled for a stockpile, any items placed in it will be designated to be taken to the Trade Depot whenever merchants are on the map. This plugin adds an option to the menu when enabled.

command-prompt¶

An in-game DFHack terminal, where you can enter other commands.

Keybinding: CtrlShiftP

Usage:

If called with an entry, it starts with that text filled in. Most useful for developers, who can set a keybinding to open a laungage interpreter for lua or Ruby by starting with the :lua or :rb commands.

Otherwise somewhat similar to gui/quickcmd.

hotkeys¶

Opens an in-game screen showing which DFHack keybindings are active in the current context. See also hotkey-notes.

Keybinding: CtrlF1

Keybinding: AltF1

ruby¶

Ruby language plugin, which evaluates the following arguments as a ruby string. Best used as , for the special parsing mode. Alias .

manipulator¶

An in-game equivalent to the popular program Dwarf Therapist.

To activate, open the unit screen and press .

The far left column displays the unit’s Happiness (color-coded based on its value), Name, Profession/Squad, and the right half of the screen displays each dwarf’s labor settings and skill levels (0-9 for Dabbling through Professional, A-E for Great through Grand Master, and U-Z for Legendary through Legendary+5).

Cells with teal backgrounds denote skills not controlled by labors, e.g. military and social skills.

Press to toggle between Profession, Squad, and Job views.

Use the arrow keys or number pad to move the cursor around, holding to move 10 tiles at a time.

Press the Z-Up () and Z-Down () keys to move quickly between labor/skill categories. The numpad Z-Up and Z-Down keys seek to the first or last unit in the list. seeks to the top left corner.

Press Enter to toggle the selected labor for the selected unit, or Shift+Enter to toggle all labors within the selected category.

Press the keys to sort the unit list according to the currently selected skill/labor, and press the keys to sort the unit list by Name, Profession/Squad, Happiness, or Arrival order (using to select which sort method to use here).

With a unit selected, you can press the key to view its properties (and possibly set a custom nickname or profession) or the key to exit Manipulator and zoom to its position within your fortress.

The following mouse shortcuts are also available:

  • Click on a column header to sort the unit list. Left-click to sort it in one direction (descending for happiness or labors/skills, ascending for name, profession or squad) and right-click to sort it in the opposite direction.
  • Left-click on a labor cell to toggle that labor. Right-click to move the cursor onto that cell instead of toggling it.
  • Left-click on a unit’s name, profession or squad to view its properties.
  • Right-click on a unit’s name, profession or squad to zoom to it.

Pressing normally returns to the unit screen, but would exit directly to the main dwarf mode screen.

Professions¶

The manipulator plugin supports saving Professions: a named set of Labors labors that can be quickly applied to one or multiple Dwarves.

To save a Profession highlight a Dwarf and press . The Profession will be saved using the Custom Profession Name of the Dwarf, or the default for that Dwarf if no Custom Profession Name has been set.

To apply a Profession either highlight a single Dwarf, or select multiple with , and press to select the Profession to apply. All labors for the selected Dwarves will be reset to the labors of the chosen Profession.

search¶

The search plugin adds search to the Stocks, Animals, Trading, Stockpile, Noble (assignment candidates), Military (position candidates), Burrows (unit list), Rooms, Announcements, Job List and Unit List screens.

Searching works the same way as the search option in Move to Depot. You will see the Search option displayed on screen with a hotkey (usually ). Pressing it lets you start typing a query and the relevant list will start filtering automatically.

Pressing , or the arrow keys will return you to browsing the now filtered list, which still functions as normal. You can clear the filter by either going back into search mode and backspacing to delete it, or pressing the “shifted” version of the search hotkey while browsing the list (e.g. if the hotkey is , then hitting will clear any filter).

Leaving any screen automatically clears the filter.

In the Trade screen, the actual trade will always only act on items that are actually visible in the list; the same effect applies to the Trade Value numbers displayed by the screen. Because of this, the key is blocked while search is active, so you have to reset the filters first. Pressing will clear both search strings.

In the stockpile screen the option only appears if the cursor is in the rightmost list:

Note that the ‘Permit XXX’/’Forbid XXX’ keys conveniently operate only on items actually shown in the rightmost list, so it is possible to select only fat or tallow by forbidding fats, then searching for fat/tallow, and using Permit Fats again while the list is filtered.

nopause¶

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

embark-assistant¶

This plugin provides embark site selection help. It has to be run with the command while the pre-embark screen is displayed and shows extended (and correct(?)) resource information for the embark rectangle as well as normally undisplayed sites in the current embark region. It also has a site selection tool with more options than DF’s vanilla search tool. For detailed help invoke the in game info screen. Requires 42 lines to display properly.

automaterial¶

This makes building constructions (walls, floors, fortifications, etc) a little bit easier by saving you from having to trawl through long lists of materials each time you place one.

Firstly, it moves the last used material for a given construction type to the top of the list, if there are any left. So if you build a wall with chalk blocks, the next time you place a wall the chalk blocks will be at the top of the list, regardless of distance (it only does this in “grouped” mode, as individual item lists could be huge). This should mean you can place most constructions without having to search for your preferred material type.

Pressing while highlighting any material will enable that material for “auto select” for this construction type. You can enable multiple materials as autoselect. Now the next time you place this type of construction, the plugin will automatically choose materials for you from the kinds you enabled. If there is enough to satisfy the whole placement, you won’t be prompted with the material screen - the construction will be placed and you will be back in the construction menu as if you did it manually.

When choosing the construction placement, you will see a couple of options:

Use here to temporarily disable the material autoselection, e.g. if you need to go to the material selection screen so you can toggle some materials on or off.

The other option (auto type selection, off by default) can be toggled on with . If you toggle this option on, instead of returning you to the main construction menu after selecting materials, it returns you back to this screen. If you use this along with several autoselect enabled materials, you should be able to place complex constructions more conveniently.

buildingplan¶

When active (via ), this plugin adds a planning mode for furniture placement. You can then place furniture and other buildings before the required materials are available, and the job will be unsuspended when the item is created.

Very useful when combined with workflow - you can set a constraint to always have one or two doors/beds/tables/chairs/etc available, and place as many as you like. The plugins then take over and fulfill the orders, with minimal space dedicated to stockpiles.

confirm¶

Implements several confirmation dialogs for potentially destructive actions (for example, seizing goods from traders or deleting hauling routes).

Usage:

enable confirm:Enable all confirmations; alias . Replace with to disable.
confirm help:List available confirmation dialogues.
confirm enable option1 [option2…]:
 Enable (or disable) specific confirmation dialogues.

follow¶

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

mousequery¶

Adds mouse controls to the DF interface, eg click-and-drag designations.

Options:

plugin:enable/disable the entire plugin
rbutton:enable/disable right mouse button
track:enable/disable moving cursor in build and designation mode
edge:enable/disable active edge scrolling (when on, will also enable tracking)
live:enable/disable query view when unpaused
delay:Set delay when edge scrolling in tracking mode. Omit amount to display current setting.

Usage:

mousequery[plugin][rbutton][track][edge][live][enable|disable]

resume¶

Allows automatic resumption of suspended constructions, along with colored UI hints for construction status.

title-folder¶

Displays the DF folder name in the window title bar when enabled.

title-version¶

Displays the DFHack version on DF’s title screen when enabled.

trackstop¶

Adds a menu for track stops, which is completely blank by default. This allows you to view and/or change the track stop’s friction and dump direction settings, using the keybindings from the track stop building interface.

sort-items¶

Sort the visible item list:

Sort the item list using the given sequence of comparisons. The prefix for an order makes undefined values sort first. The prefix reverses the sort order for defined values.

Item order examples:

The orderings are defined in

sort-itemsorder[order...]
descriptionmaterialweartypequality

sort-units¶

Sort the visible unit list:

Sort the unit list using the given sequence of comparisons. The prefix for an order makes undefined values sort first. The prefix reverses the sort order for defined values.

Unit order examples:

The orderings are defined in

Keybinding: AltShiftN ->

Keybinding: AltShiftR ->

Keybinding: AltShiftT ->

Keybinding: AltShiftQ ->

sort-unitsorder[order...]
nameagearrivalsquadsquad_positionprofession

stocks¶

Replaces the DF stocks screen with an improved version.

Keybinding: CtrlShiftZ -> in

stocksettings¶

Offers the following commands to save and load stockpile settings. See gui/stockpiles for an in-game interface.

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.

Keybinding: AltP

savestock:Saves the currently highlighted stockpile’s settings to a file in your Dwarf Fortress folder. This file can be used to copy settings between game saves or players. eg:
loadstock:Loads a saved stockpile settings file and applies it to the currently selected stockpile. eg:

To use savestock and loadstock, use the command to highlight a stockpile. Then run savestock giving it a descriptive filename. Then, in a different (or the same!) gameworld, you can highlight any stockpile with then execute the command passing it the name of that file. The settings will be applied to that stockpile.

Note that files are relative to the DF folder, so put your files there or in a subfolder for easy access. Filenames should not have spaces. Generated materials, divine metals, etc are not saved as they are different in every world.

rename¶

Allows renaming various things. Use gui/rename for an in-game interface.

Options:

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

rendermax¶

A collection of renderer replacing/enhancing filters. For better effect try changing the black color in palette to non totally black. See Bay12 forums thread 128487 for more info.

Options:

trippy:Randomizes the color of each tiles. Used for fun, or testing.
light:Enable lighting engine.
light reload:Reload the settings file.
light sun <x>|cycle:
 Set time to <x> (in hours) or set it to df time cycle.
occlusionON, occlusionOFF:
 Show debug occlusion info.
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…

Job and Fortress management¶

autolabor¶

Automatically manage dwarf labors to efficiently complete jobs. Autolabor tries to keep as many dwarves as possible busy but also tries to have dwarves specialize in specific skills.

The key is that, for almost all labors, once a dwarf begins a job it will finish that job even if the associated labor is removed. Autolabor therefore frequently checks which dwarf or dwarves should take new jobs for that labor, and sets labors accordingly. Labors with equiptment (mining, hunting, and woodcutting), which are abandoned if labors change mid-job, are handled slightly differently to minimise churn.

Warning

autolabor will override any manual changes you make to labors while it is enabled, including through other tools such as Dwarf Therapist

Simple usage:

enable autolabor:
 Enables the plugin with default settings. (Persistent per fortress)
disable autolabor:
 Disables the plugin.

Anything beyond this is optional - autolabor works well on the default settings.

By default, each labor is assigned to between 1 and 200 dwarves (2-200 for mining). By default 33% of the workforce become haulers, who handle all hauling jobs as well as cleaning, pulling levers, recovering wounded, removing constructions, and filling ponds. Other jobs are automatically assigned as described above. Each of these settings can be adjusted.

Jobs are rarely assigned to nobles with responsibilities for meeting diplomats or merchants, never to the chief medical dwarf, and less often to the bookeeper and manager.

Hunting is never assigned without a butchery, and fishing is never assigned without a fishery.

For each labor a preference order is calculated based on skill, biased against masters of other trades and excluding those who can’t do the job. The labor is then added to the best <minimum> dwarves for that labor. We assign at least the minimum number of dwarfs, in order of preference, and then assign additional dwarfs that meet any of these conditions:

  • The dwarf is idle and there are no idle dwarves assigned to this labor
  • The dwarf has non-zero skill associated with the labor
  • The labor is mining, hunting, or woodcutting and the dwarf currently has it enabled.

We stop assigning dwarfs when we reach the maximum allowed.

Advanced usage:

autolabor <labor> <minimum> [<maximum>]:
 Set number of dwarves assigned to a labor.
autolabor <labor> haulers:
 Set a labor to be handled by hauler dwarves.
autolabor <labor> disable:
 Turn off autolabor for a specific labor.
autolabor <labor> reset:
 Return a labor to the default handling.
autolabor reset-all:
 Return all labors to the default handling.
autolabor list:List current status of all labors.
autolabor status:
 Show basic status information.

See autolabor-artisans for a differently-tuned setup.

Examples:

Keep at least 5 dwarves with mining enabled.
Keep exactly 1 dwarf with gemcutting enabled.
Keep 1 dwarf with cooking enabled, selected only from the top 3.
Have haulers feed and water wounded dwarves.
Turn off autolabor for wood cutting.

labormanager¶

Automatically manage dwarf labors to efficiently complete jobs. Labormanager is derived from autolabor (above) but uses a completely different approach to assigning jobs to dwarves. While autolabor tries to keep as many dwarves busy as possible, labormanager instead strives to get jobs done as quickly as possible.

Labormanager frequently scans the current job list, current list of dwarfs, and the map to determine how many dwarves need to be assigned to what labors in order to meet all current labor needs without starving any particular type of job.

Warning

As with autolabor, labormanager will override any manual changes you make to labors while it is enabled, including through other tools such as Dwarf Therapist

Simple usage:

enable labormanager:
 Enables the plugin with default settings. (Persistent per fortress)
disable labormanager:
 Disables the plugin.

Anything beyond this is optional - labormanager works fairly well on the default settings.

The default priorities for each labor vary (some labors are higher priority by default than others). The way the plugin works is that, once it determines how many of each labor is needed, it then sorts them by adjusted priority. (Labors other than hauling have a bias added to them based on how long it’s been since they were last used, to prevent job starvation.) The labor with the highest priority is selected, the “best fit” dwarf for that labor is assigned to that labor, and then its priority is halved. This process is repeated until either dwarfs or labors run out.

Because there is no easy way to detect how many haulers are actually needed at any moment, the plugin always ensures that at least one dwarf is assigned to each of the hauling labors, even if no hauling jobs are detected. At least one dwarf is always assigned to construction removing and cleaning because these jobs also cannot be easily detected. Lever pulling is always assigned to everyone. Any dwarfs for which there are no jobs will be assigned hauling, lever pulling, and cleaning labors. If you use animal trainers, note that labormanager will misbehave if you assign specific trainers to specific animals; results are only guaranteed if you use “any trainer”, and animal trainers will probably be overallocated in any case.

Labormanager also sometimes assigns extra labors to currently busy dwarfs so that when they finish their current job, they will go off and do something useful instead of standing around waiting for a job.

There is special handling to ensure that at least one dwarf is assigned to haul food whenever food is detected left in a place where it will rot if not stored. This will cause a dwarf to go idle if you have no storepiles to haul food to.

Dwarfs who are unable to work (child, in the military, wounded, handless, asleep, in a meeting) are entirely excluded from labor assignment. Any dwarf explicitly assigned to a burrow will also be completely ignored by labormanager.

The fitness algorithm for assigning jobs to dwarfs generally attempts to favor dwarfs who are more skilled over those who are less skilled. It also tries to avoid assigning female dwarfs with children to jobs that are “outside”, favors assigning “outside” jobs to dwarfs who are carrying a tool that could be used as a weapon, and tries to minimize how often dwarfs have to reequip.

Labormanager automatically determines medical needs and reserves health care providers as needed. Note that this may cause idling if you have injured dwarfs but no or inadequate hospital facilities.

Hunting is never assigned without a butchery, and fishing is never assigned without a fishery, and neither of these labors is assigned unless specifically enabled.

The method by which labormanager determines what labor is needed for a particular job is complicated and, in places, incomplete. In some situations, labormanager will detect that it cannot determine what labor is required. It will, by default, pause and print an error message on the dfhack console, followed by the message “LABORMANAGER: Game paused so you can investigate the above message.”. If this happens, please open an issue on github, reporting the lines that immediately preceded this message. You can tell labormanager to ignore this error and carry on by typing , but be warned that some job may go undone in this situation.

Advanced usage:

labormanager enable:
 Turn plugin on.
labormanager disable:
 Turn plugin off.
labormanager priority <labor> <value>:
 Set the priority value (see above) for labor <labor> to <value>.
labormanager reset <labor>:
 Reset the priority value of labor <labor> to its default.
labormanager reset-all:
 Reset all priority values to their defaults.
labormanager allow-fishing:
 Allow dwarfs to fish. Warning This tends to result in most of the fort going fishing.
labormanager forbid-fishing:
 Forbid dwarfs from fishing. Default behavior.
labormanager allow-hunting:
 Allow dwarfs to hunt. Warning This tends to result in as many dwarfs going hunting as you have crossbows.
labormanager forbid-hunting:
 Forbid dwarfs from hunting. Default behavior.
labormanager list:
 Show current priorities and current allocation stats.
labormanager pause-on-error yes:
 Make labormanager pause if the labor inference engine fails. See above.
labormanager pause-on-error no:
 Allow labormanager to continue past a labor inference engine failure.

autohauler¶

Autohauler is an autolabor fork.

Rather than the all-of-the-above means of autolabor, autohauler will instead only manage hauling labors and leave skilled labors entirely to the user, who will probably use Dwarf Therapist to do so.

Idle dwarves will be assigned the hauling labors; everyone else (including those currently hauling) will have the hauling labors removed. This is to encourage every dwarf to do their assigned skilled labors whenever possible, but resort to hauling when those jobs are not available. This also implies that the user will have a very tight skill assignment, with most skilled labors only being assigned to just one dwarf, no dwarf having more than two active skilled labors, and almost every non-military dwarf having at least one skilled labor assigned.

Autohauler allows skills to be flagged as to prevent hauling labors from being assigned when the skill is present. By default this is the unused ALCHEMIST labor but can be changed by the user.

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

Invoked as:

Keybinding: ShiftA ->

Keybinding: ShiftM ->

Keybinding: ShiftD ->

Keybinding: ShiftR ->

Keybinding: ShiftI ->

Keybinding: ShiftB ->

Keybinding: ShiftO ->

Keybinding: ShiftT ->

Keybinding: ShiftG ->

  • In 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 mode, during selection of building components positions the cursor over the first available choice with the matching material.
job-material<inorganic-token>

job-duplicate¶

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

Keybinding: CtrlD

autogems¶

Creates a new Workshop Order setting, automatically cutting rough gems when enabled.

stockflow¶

Allows the fortress bookkeeper to queue jobs through the manager, based on space or items available in stockpiles.

Inspired by workflow.

Usage:

Enable the plugin.
Disable the plugin.
Enable the plugin in fast mode.
List any work order settings for your stockpiles.
Display whether the plugin is enabled.

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

  • : Select a job to order, from an interface like the manager’s screen.
  • : 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.

In fast mode, new work orders will be enqueued once per day, instead of waiting for the bookkeeper.

workflow¶

Manage control of repeat jobs. gui/workflow provides a simple front-end integrated in the game UI.

Usage:

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.
List workflow-controlled jobs (if in a workshop, filtered by it).
List active constraints, and their job counts.
List active constraints as workflow commands that re-create them; this list can be copied to a file, and then reloaded using the built-in command.

xTATTEREDx ·+FINE+ ·*SUPERIOR* ·≡EXCEPTIONAL≡ ·☼MASTERWORK☼

"To get a job done, a dwarf has to do it." - Boss Urist McOverstates-the-obvious

[edit]Introduction to Labor

At the most basic level, labor is how you get things done. When you want your dwarf to do a job of work you must assign that dwarf to a "labor" type that corresponds with the job. You, as the fortress overseer, create jobs to be done by designating them, and the dwarves who have been assigned the corresponding labor type appropriate to the job will complete the job. Your dwarves function as semi-autonomous entities, fulfilling their own basic needs as they see fit, while also meeting the demand of work to be done when time and conditions allow. Assigning specific labors to your dwarves tells them what type of work you want them to do. A labor "preference" simply designates whether a dwarf is allowed do a particular job or not. Multiple labors can be assigned to a single dwarf, (unless they are exclusive - see below) but specialization within a category is usually best as this will result in highly skilled (faster/ higher quality) labor.

[edit] Basic Terminology

  • Labor: the ability to complete a job specific to a given type of work, which must be assigned individually to each dwarf.
  • Preference: a somewhat ambiguous term associated with process of assigning a labor to a dwarf. Dwarves do not merely prefer assigned labors over unassigned labors; instead, they will completely refuse to do unassigned labors.
  • Skill: the level of proficiency a dwarf has when performing a specific labor. Skill increases with experience in completing the work. (The term labor and skill are NOT synonyms. Skill is a measure of proficiency for a given labor, while a labor is the ability to do the work.)
  • Profession: Each dwarf is assigned a professional title, which is determined from the dwarf's assigned / preferred labors that has the highest skill level.
  • Job: a specific task or work order queued to be completed, which can only be completed by a dwarf assigned to the labor that corresponds to the job. Typically there are multiple jobs that can be completed by a specific labor.
  • Additionally, basic needs also appear as jobs, such as eating, sleeping, drinking, etc.. These are not assigned, but are created automatically as needed.
  • Social Skill:Social skills are not labors, in that no work is performed using them, but they are similar in that they are unique abilities which will increase in competency the more they are used.
  • Miscellaneous Abilities: are similar to labors and social skills, but again are not used in the performance of work. An example is swimming.

[edit]Assigning Labors

There are several steps required to assign a particular labor to a dwarf. For an example, lets say you have designated a section of underground rock to be mined in order to make a tunnel for your fortress. This designation of work is a "job", and will now appear in your j job's menu as "dig". In order for a dwarf to complete the job, you must assign a dwarf the mining labor. This can be done as follows:

  1. From the main map screen, select the unit list menu, u, which will list all your Dwarves and show their current activity.
    • Alternatively, you can use the view menu.
  2. From the unit list menu, arrow scroll down to select the dwarf whom you want to assign a labor to then select z to zoom to their location. Your view will change to the main map, and the dwarf you have chosen should be flashing on and off. In the task window on the right you will see information about the selected dwarf, in the Dwarf Details menu.
    • The default view for the selected dwarf in the Dwarf Details menu is 'general' g, which will list the dwarf's nickname or first name, dwarvish last name, and profession, followed below by their nickname or first name and last name as it reads in English, and their noble title if they are a noble. This is followed by a list that shows the current job (or lack thereof) in blue text, combat role c, labors b, and miscellaneous social skills and abilities m. To see only the current labors, turn the combat c and miscellaneous m sections off.
  3. From the Dwarf Details screen, select p for preference, and then l for labor. This will take you to the Labor Categories screen, which categorizes the individual labor options into various categories based on similarity of work. (See Labor Categories below.)
    • Note that Mining is unique on the list, as it is the only item that is a labor in its own right, and not a category of several labors.
  4. Scroll through the list using the + or - keys, select a category, and scroll through the individual labor list, and once you have the desired labor selected, press Enter. For this example, since Mining is a labor and not a category you need only select Mining from the category menu.
  5. Exiting: To return to the Dwarf Details screen, select preference p then general g, and you should see the new assigned labor in the list. You can also exit directly to the main screen by selecting Esc.
    • Note that changes in labors will not always take effect immediately, if a labor is deselected on a dwarf, say Mining, who is performing the job, they will first finish mining the current tile and then stop mining.

Utilities

You may have noticed that the UI for managing dwarves is a bit difficult to use. If you are using a supported operating system, Dwarf Therapist and/or DFHack can make this much easier.


Note: The word "preference" can be confusing, as it suggest that a dwarf will do work associated with any labor, but will 'prefer' and prioritize work associated with labors you have assigned. This is not the case. A dwarf will only do work associated with assigned preferred labors, so it is not a preference, but is in fact functions as a switch to enable or disable the labor. (Prioritization of work is based on several factors that are not fully understood, but are presented in micromanaging tricks.)

Once designated as a labor preference, a single labor can be applied to many different jobs. For instance, a dwarf with the bone carving labor designated might carve a totem out of a skull, craft bone practice bolts for a crossbow, create bone armor, or carve bone crafts to trade. Each of these is a different possible job allowed by designating the associated labor.

[edit] Labor & Tool Requirements:

For certain jobs, such as mining in our example, a tool is also required for the job to be completed. Miners need picks, Wood cutters need a battle axe, and Hunters need a crossbow. If a labor needs a tool, the labor is considered exclusive such that you can only assign one of the three labors listed to any single dwarf. Additionally, the assignment of these tools overrides any uniform assigned to a dwarf's squad, so military dwarves should never be assigned any of the aforementioned labors.

[edit] Labor & Facility Requirements:

Many jobs require a workshop or some other facility in order to be completed. Jobs are designated by way of the workshop, and any dwarf with the corresponding labor associated with the workshop will go to the shop, provided they are not eating, sleeping, drinking, etc..., and begin to complete the task. Most workshop jobs also require some raw materials in order to complete the production.

[edit] Labor Categories

Labor is divided into the following categories which are typically related by function or material, and for which there are multiple labors associated with each category:

Mining
Carpentry, Crossbow-making, Wood cutting
Masonry, Stone detailing
Animal care*, Animal training, Hunting, Small animal dissection*, Trapping*
Diagnosis, Dressing wounds, Feed Patients/Prisoners, Recovering Wounded, Setting bones, Surgery, Suturing
Beekeeping, Brewing, Butchery, Cheese making, Cooking, Dyeing,Farming (Fields), Lye Making, Milking, Milling, Plant Gathering, Plant Processing, Potash Making, Shearing, Soap making, Spinning, Tanning, Wood Burning
Fishing, Fish cleaning, Fish dissection
Armoring, Blacksmithing, Furnace operating, Metalcrafting, Weaponsmithing
Gem cutting, Gem setting
Book Binding, Bone Carving, Clothesmaking, Glassmaking, Glazing, Leatherworking, Pottery, Stonecrafting, Strand Extraction, Wax Working, Weaving, Woodcrafting
Mechanic, Pump operating, Siege engineer, Siege operator
Animal/Food/Item/Refuse/Stone/Trade Good/Water/Wood Hauling, Burial, Push/Haul Vehicles
Alchemy*, Architecture, Cleaning, Construction removal, Lever operation, Road building, Wall/Floor construction
* Useless / Limited Labors:
  • As of 8-2014, Animal Care & Alchemy are not functioning.
  • Trapping, Small Animal Dissection, and Fish Dissection have limited utility.


In the preference screen, a labor category is dark gray if there are no labors under it enabled, light gray if there are some jobs enabled, and white if all jobs are enabled. (These distinctions can sometimes be very hard to tell apart in the default color scheme.)

[edit] Jobs that are not associated with Labor

[edit] Managing Labor & Demand

  • To quickly change a dwarf's labor preferences, access the labor screen by viewing the dwarf, then select preferences and labor. Use + and - to move the cursor up and down to highlight different categories or skills to enable or disable. Or, use Dwarf Therapist/DFHack.
  • Using u can help you quickly locate dwarves. Select a dwarf, hit z for "zoom to creature" and you'll automatically be placed in view mode on that dwarf. Use p-l to get to the labor configuration menu.
  • You can view a list of all current, queued, and suspended jobs on the jobs menu. A list of what job each dwarf is currently performing is visible on the units menu.
  • A manager is incredibly useful for managing production jobs (workshop based). He or she can queue up a significant list of jobs without the need to select the various workshops, and place orders in bulk (or to be repeated). That said, there are some caveats, the most important being that queued jobs must be done in the correct order of materials required, or the orders will auto cancel. Also, you should not assign your manager to labors that are in high demand, as this will keep them from going to their office to place the orders.
  • Migrating dwarves will typically arrive with a certain number of labors already active. You will probably want to change the assigned labors, as often they will not meet your demand, or may be useless based on your access to raw materials.

[edit]Advanced Labor Management & Design

Managing your dwarves can be a tricky, and time consuming business. Many a fortress has been abandoned not because of destruction from external threat, but rather from labor management fatigue. Dwarf Therapist or DFHack are both useful tools that assist you in managing your labors.

As your fortress grows, so will your labor pool, and the way you assign that labor will change over time. Typically at embark you will have at least one Miner, a Wood cutter, Farmer, Carpenter, Mason/Stonecrafter, Cook/Brewer, Mechanic/Architect, one of which will also be a Broker / Appraiser. There are multiple combinations but this is typical (see Embark and Starting build). Early on, you will probably want to focus on fortress design and development, such that you will place priority on mining and masonry, supplemented by carpentry.

In order to maximize the benefit of highly skilled labor, you will eventually want to specialize your labor, such that each dwarf has a very limited number of labors assigned.

Hauling: Nothing can bog down your production like the distraction of hauling jobs. Losing your fort to a siege is fun, but losing because all your skilled laborers spend all their time hauling stuff is no fun. One solution is to use dedicated haulers. The migrants who appear & have no skilled labor, and whose attributes pretty much suck all around, aka peasants, are best used as dedicated haulers.

[edit]Labor, Skill, and product quality

The amount of experience a dwarf has with a certain labor will determine how well he goes about performing this labor. The more experience, the greater the skill. Certain job types can be completed more quickly based on the skill of the labor. There are exceptions, such as nursing and hauling which will never be completed more quickly regardless of skill.

Certain labors will produce products that have a quality tag, typically those associated with the production of an item from a workshop. The table below lists in which labors the dwarf's experience will impact the quality of produced items and in which labors a higher experience will only be beneficial for the speed of production.

  • Many labors, most notably hauling, have no associated skill, do not generate experience, and do not improve with practice.
Category Labors Quality-effects? Details
Mining no speed only
Woodworker yes item, furniture, and designed building quality
yes weapon quality
no speed only
Stoneworking yes item, furniture, and designed building quality
yes engraving quality, speed only for smoothing and track carving
Hunting/Related yes training quality
no not implemented
no success rate tends to rise from increasing ambusher and marksdwarf skills
no success rate? trap quality?Verify
no speed only
Healthcare (Doctoral) yes success chance, accuracy (and speed) of treatment
Healthcare (Nursing) no unskilled
Farming/Related no speed only
no speed only
yes crop yield (stack size)
yes dye quality
no less likely to be injured
no speed only
no speed only
no speed only
no speed only
no speed only
no speed only
yes success and plant yield (stack size)
no speed only
no speed only
no speed only
no speed only
no speed only
yes meal and ingredient quality
no speed only
no speed onlyVerify
Fishing/Related yes fish stack size
no speed only
no speed only
Metalsmithing no speed only
yes weapon quality
yes armor quality
yes item, furniture, designed building quality
yes craft, item, decoration, designed building quality
Jewelry yes gem craft quality
yes decoration quality
Crafts yes clothing, decoration, craft quality
yes craft quality
yes craft quality
yes craft, decoration quality
yes craft, item, furniture quality
yes cloth quality
yes clothing, decoration quality
no speed only
yes craft, item, furniture quality
no no experience gain Bug:4577
yes craft quality
Engineering yes part, ammunition quality
yes accuracy
yes mechanism, furniture quality
no -
Hauling no unskilled
Other Jobs yes building design quality
no not implemented
no unskilled
no unskilled
no unskilled
no unskilled
no unskilled

0 thoughts on “Dfhack Automatic Job Assignments

Leave a Reply

Your email address will not be published. Required fields are marked *