Basic Scripts

Basic scripts are not stored in any subdirectory, and can be invoked directly. They are generally useful tools for any player.



View or set level of cavern adaptation for the selected unit or the whole fort.


adaptation <show|set> <him|all> [value]

The value must be between 0 and 800,000 (inclusive).


Adds unknown weapon and armor crafting recipes to your civ. E.g. some civilizations never learn to craft high boots. This script can help with that, and more. Only weapons, armor, and tools are currently supported; things such as instruments are not. Available options:

  • add-recipe all adds all available weapons and armor, including exotic items like blowguns, two-handed swords, and capes.

  • add-recipe native adds only native (but unknown) crafting recipes. Civilizations pick randomly from a pool of possible recipes, which means not all civs get high boots, for instance. This command gives you all the recipes your civilisation could have gotten.

  • add-recipe single <item token> adds a single item by the given item token. For example:

    add-recipe single SHOES:ITEM_SHOES_BOOTS


Adds a thought or emotion to the selected unit. Can be used by other scripts, or the gui invoked by running add-thought -gui with a unit selected.


Fixes Bug 6798. This bug is characterized by sleeping units who refuse to awaken in adventure mode regardless of talking to them, hitting them, or waiting so long you die of thirst. If you come accross one or more bugged sleepers in adventure mode, simply run the script and all nearby sleepers will be cured.




When creating an adventurer, raises all changeable skills and attributes to their maximum level.


Improves the “Bring up specific incident or rumor” menu in Adventure mode.

  • Moves entries into one line
  • Adds a “slew” keyword for filtering, making it easy to find your kills and not your companions’
  • Trims repetitive words

Keybinding: CtrlA in dungeonmode/ConversationSpeak


Animal control is a script useful for deciding what animals to butcher and geld.

While not as powerful as Dwarf Therapist in managing animals - in so far as DT allows you to sort by various stats and flags - this script does provide many options for filtering animals. Additionally you can mark animals for slaughter or gelding, you can even do so enmasse if you so choose.


animal-control -race DOG
animal-control -race DOG -male -notgelded -showstats
animal-control -markfor gelding -id 1988
animal-control -markfor slaughter -id 1988
animal-control -gelded -markedfor slaughter -unmarkfor slaughter

Selection options:

These options are used to specify what animals you want or do not want to select.

-all: Selects all units.
Note: cannot be used in conjunction with other selection options.

-id <value>: Selects the unit with the specified id value provided.

-race <value>: Selects units which match the race value provided.

-markedfor <action>: Selects units which have been marked for the action provided.
Valid actions: slaughter, gelding
-notmarkedfor <action>: Selects units which have not been marked for the action provided.
Valid actions: slaughter, gelding

-gelded: Selects units which have already been gelded.

-notgelded: Selects units which have not been gelded.

-male: Selects units which are male.

-female: Selects units which are female.

Command options:

  • -showstats: Displays physical attributes of the selected animals.
  • -markfor <action>: Marks selected animals for the action provided.
    Valid actions: slaughter, gelding
  • -unmarkfor <action>: Unmarks selected animals for the action provided.
    Valid actions: slaughter, gelding

Other options:

  • -help: Displays this information

Column abbreviations

Due to space constraints, the names of some output columns are abbreviated as follows:

  • str: strength
  • agi: agility
  • tgh: toughness
  • endur: endurance
  • recup: recuperation
  • disres: disease resistance


Runs the equivalent of rejuvenate, elevate-physical, elevate-mental, and brainwash on all dwarves currently on the map. This is an extreme change, which sets every stat and trait to an ideal easy-to-satisfy preference.

Without providing arguments, only attributes, age, and personalities will be adjusted. Adding arguments allows for skills or classes to be adjusted to legendary (maximum).


  • list

    Prints list of all skills

  • classes

    Prints list of all classes

  • all

    Set all skills, for all Dwarves, to legendary

  • <skill name>

    Set a specific skill, for all Dwarves, to legendary

    example: armoks-blessing RANGED_COMBAT

    All Dwarves become a Legendary Archer

  • <class name>

    Set a specific class (group of skills), for all Dwarves, to legendary

    example: armoks-blessing Medical

    All Dwarves will have all medical related skills set to legendary


A script to change the physical and mental attributes of a unit.

Attributes are divided into tiers from -4 to 4. Tier 0 is the standard level and represents the average values for that attribute, tier 4 is the maximum level, and tier -4 is the minimum level.

An example of the attribute “Strength”:

Tier Description
4 unbelievably strong
3 mighty
2 very strong
1 strong
0 (no description)
-1 weak
-2 very weak
-3 unquestionably weak
-4 unfathomably weak

For more information:


print the help page.
-unit <UNIT_ID>:
the target unit ID. If not present, the currently selected unit will be the target.
-attributes [ <ATTRIBUTE> <TIER> <ATTRIBUTE> <TIER> <...> ]:
the list of the attributes to modify and their tiers. The valid attribute names can be found in the wiki: (substitute any space with underscores); tiers range from -4 to 4. There must be a space before and after each square bracket.
reset all attributes to the average level (tier 0). If both this option and a list of attributes/tiers are present, the unit attributes will be reset and then the listed attributes will be modified.


assign-attributes -reset -attributes [ STRENGTH 2 AGILITY -1 SPATIAL_SENSE -1 ]

This will reset all attributes to a neutral value and will set the following values (if the currently selected unit is a dwarf):

  • Strength: a random value between 1750 and 1999 (tier 2);
  • Agility: a random value between 401 and 650 (tier -1);
  • Spatial sense: a random value between 1043 and 1292 (tier -1).

The final result will be: “She is very strong, but she is clumsy. She has a questionable spatial sense.”


A script to change the beliefs (values) of a unit.

Beliefs are defined with the belief token and a number from -3 to 3, which describes the different levels of belief strength, as explained here:

Strength Effect
3 Highest
2 Very High
1 High
0 Neutral
-1 Low
-2 Very Low
-3 Lowest

Resetting a belief means setting it to a level that does not trigger a report in the “Thoughts and preferences” screen.


print the help page.
-unit <UNIT_ID>:
set the target unit ID. If not present, the currently selected unit will be the target.
-beliefs [ <BELIEF> <LEVEL> <BELIEF> <LEVEL> <...> ]:
the beliefs to modify and their levels. The valid belief tokens can be found in the wiki page linked above; level values range from -3 to 3. There must be a space before and after each square bracket.
reset all beliefs to a neutral level. If the script is called with both this option and a list of beliefs/levels, first all the unit beliefs will be reset and then those beliefs listed after -beliefs will be modified.


assign-beliefs -reset -beliefs [ TRADITION 2 CRAFTSMANSHIP 3 POWER 0 CUNNING -1 ]

Resets all the unit beliefs, then sets the listed beliefs to the following values:

  • Tradition: a random value between 26 and 40 (level 2);
  • Craftsmanship: a random value between 41 and 50 (level 3);
  • Power: a random value between -10 and 10 (level 0);
  • Cunning: a random value between -25 and -11 (level -1).

The final result (for a dwarf) will be: “She personally is a firm believer in the value of tradition and sees guile and cunning as indirect and somewhat worthless.”

Note that the beliefs aligned with the cultural values of the unit have not triggered a report.


A script to change the facets (traits) of a unit.

Facets are defined with a token and a number from -3 to 3, which describes the different levels of facets strength, as explained here:

Strength Effect
3 Highest
2 Very High
1 High
0 Neutral
-1 Low
-2 Very Low
-3 Lowest

Resetting a facet means setting it to a level that does not trigger a report in the “Thoughts and preferences” screen.


print the help page.
-unit <UNIT_ID>:
set the target unit ID. If not present, the currently selected unit will be the target.
-beliefs [ <FACET> <LEVEL> <FACET> <LEVEL> <...> ]:
the facets to modify and their levels. The valid facet tokens can be found in the wiki page linked above; level values range from -3 to 3. There must be a space before and after each square bracket.
reset all facets to a neutral level. If the script is called with both this option and a list of facets/levels, first all the unit facets will be reset and then those facets listed after -facets will be modified.


assign-facets -reset -facets [ HATE_PROPENSITY -2 CHEER_PROPENSITY -1 ]

Resets all the unit facets, then sets the listed facets to the following values:

  • Hate propensity: a value between 10 and 24 (level -2);
  • Cheer propensity: a value between 25 and 39 (level -1).

The final result (for a dwarf) will be: “She very rarely develops negative feelings toward things. She is rarely happy or enthusiastic, and she is conflicted by this as she values parties and merrymaking in the abstract.”

Note that the facets are compared to the beliefs, and if conflicts arise they will be reported.


A script to change the goals (dreams) of a unit.

Goals are defined with the goal token and a true/false value that describes whether or not the goal has been accomplished. Be advised that this last feature has not been properly tested and might be potentially destructive: I suggest leaving it at false.

For a list of possible goals:

Bear in mind that nothing will stop you from assigning zero or more than one goal, but it’s not clear how it will affect the game.


print the help page.
-unit <UNIT_ID>:
set the target unit ID. If not present, the currently selected unit will be the target.
the goals to modify/add and whether they have been realized or not. The valid goal tokens can be found in the wiki page linked above. The flag must be a true/false value. There must be a space before and after each square bracket.
clear all goals. If the script is called with both this option and a list of goals, first all the unit goals will be erased and then those goals listed after -goals will be added.


assign-goals -reset -goals [ MASTER_A_SKILL false ]

Clears all the unit goals, then sets the “master a skill” goal. The final result will be: “dreams of mastering a skill”.


This script allows you to assign minecarts to hauling routes without having to use the in-game interface.


assign-minecarts list|all|<route id> [-q|--quiet]
list:will show you information about your hauling routes, including whether they have minecarts assigned to them.
all:will automatically assign a free minecart to all hauling routes that don’t have a minecart assigned to them.

If you specifiy a route id, only that route will get a minecart assigned to it (if it doesn’t already have one and there is a free minecart available).

Add -q or --quiet to suppress informational output.

Note that a hauling route must have at least one stop defined before a minecart can be assigned to it.


A script to change the preferences of a unit.

Preferences are classified into 12 types. The first 9 are:

  • like material;
  • like creature;
  • like food;
  • hate creature;
  • like item;
  • like plant;
  • like tree;
  • like colour;
  • like shape.

These can be changed using this script.

The remaining three are not currently managed by this script, and are: like poetic form, like musical form, like dance form.

To produce the correct description in the “thoughts and preferences” page, you must specify the particular type of preference. For each type, a description is provided in the section below.

You will need to know the token of the object you want your dwarf to like. You can find them in the wiki, otherwise in the folder “/raw/objects/” under the main DF directory you will find all the raws defined in the game.

For more information:


print the help page.
-unit <UNIT_ID>:
set the target unit ID. If not present, the currently selected unit will be the target.
-likematerial [ <TOKEN> <TOKEN> <...> ]:
usually a type of stone, a type of metal and a type of gem, plus it can also be a type of wood, a type of glass, a type of leather, a type of horn, a type of pearl, a type of ivory, a decoration material - coral or amber, a type of bone, a type of shell, a type of silk, a type of yarn, or a type of plant cloth. Write the full tokens. There must be a space before and after each square bracket.
-likecreature [ <TOKEN> <TOKEN> <...> ]:
one or more creatures liked by the unit. You can just list the species: the creature token will be something similar to CREATURE:SPARROW:SKIN, so the name of the species will be SPARROW. Nothing will stop you to write the full token, if you want: the script will just ignore the first and the last parts. There must be a space before and after each square bracket.
-likefood [ <TOKEN> <TOKEN> <...> ]:
usually a type of alcohol, plus it can be a type of meat, a type of fish, a type of cheese, a type of edible plant, a cookable plant/creature extract, a cookable mill powder, a cookable plant seed or a cookable plant leaf. Write the full tokens. There must be a space before and after each square bracket.
-hatecreature [ <TOKEN> <TOKEN> <...> ]:
works the same way as -likecreature, but this time it’s one or more creatures that the unit detests. They should be a type of HATEABLE vermin which isn’t already explicitly liked, but no check is performed about this. Like before, you can just list the creature species. There must be a space before and after each square bracket.
-likeitem [ <TOKEN> <TOKEN> <...> ]:
a kind of weapon, a kind of ammo, a kind of piece of armor, a piece of clothing (including backpacks or quivers), a type of furniture (doors, floodgates, beds, chairs, windows, cages, barrels, tables, coffins, statues, boxes, armor stands, weapon racks, cabinets, bins, hatch covers, grates, querns, millstones, traction benches, or slabs), a kind of craft (figurines, amulets, scepters, crowns, rings, earrings, bracelets, or large gems), or a kind of miscellaneous item (catapult parts, ballista parts, a type of siege ammo, a trap component, coins, anvils, totems, chains, flasks, goblets, buckets, animal traps, an instrument, a toy, splints, crutches, or a tool). The item tokens can be found here: If you want to specify an item subtype, look into the files listed under the column “Subtype” of the wiki page (they are in the “/raw/ojects/” folder), then specify the items using the full tokens found in those files (see examples below). There must be a space before and after each square bracket.
-likeplant [ <TOKEN> <TOKEN> <...> ]:
works in a similar way as -likecreature, this time with plants. You can just List the plant species (the middle part of the token). There must be a space before and after each square bracket.
-liketree [ <TOKEN> <TOKEN> <...> ]:
works exactly as -likeplant. I think this preference type is here for backward compatibility (?). You can still use it, however. As before, you can just list the tree (plant) species. There must be a space before and after each square bracket.
-likecolor [ <TOKEN> <TOKEN> <...> ]:
you can find the color tokens here: or inside the “descriptor_color_standard.txt” file (in the “/raw/ojects/” folder). You can use the full token or just the color name. There must be a space before and after each square bracket.
-likeshape [ <TOKEN> <TOKEN> <...> ]:
I couldn’t find a list of shape tokens in the wiki, but you can find them inside the “descriptor_shape_standard.txt” file (in the “/raw/ojects/” folder). You can use the full token or just the shape name. There must be a space before and after each square bracket.
clear all preferences. If the script is called with both this option and one or more preferences, first all the unit preferences will be cleared and then the listed preferences will be added.


  • “likes alabaster and willow wood”:

    assign-preferences -reset -likematerial [ INORGANIC:ALABASTER PLANT:WILLOW:WOOD ]
  • “likes sparrows for their …”:

    assign-preferences -reset -likecreature SPARROW
  • “prefers to consume dwarven wine and olives”:

    assign-preferences -reset -likefood [ PLANT:MUSHROOM_HELMET_PLUMP:DRINK PLANT:OLIVE:FRUIT ]
  • “absolutely detests jumping spiders:

    assign-preferences -reset -hatecreature SPIDER_JUMPING
  • “likes logs and battle axes”:

    assign-preferences -reset -likeitem [ WOOD ITEM_WEAPON:ITEM_WEAPON_AXE_BATTLE ]
  • “likes straberry plants for their …”:

    assign-preferences -reset -likeplant BERRIES_STRAW
  • “likes oaks for their …”:

    assign-preferences -reset -liketree OAK
  • “likes the color aqua”:

    assign-preferences -reset -likecolor AQUA
  • “likes stars”:

    assign-preferences -reset -likeshape STAR


A script to change the characteristics of a unit according to a profile loaded from a json file.

A profile can describe which attributes, skills, preferences, beliefs, goals and facets a unit must have. The script relies on the presence of the other assign-... modules in this collection: please refer to the other modules documentation for more specific information.

For information about the json schema, please see the the “/hack/scripts/dwarf_profiles.json” file.


print the help page.
-unit <UNIT_ID>:
the target unit ID. If not present, the target will be the currently selected unit.
-file <filename>:
the json file containing the profile to apply. It’s a relative path, starting from the DF root directory and ending at the json file. It must begin with a slash. Default value: “/hack/scripts/dwarf_profiles.json”.
-profile <profile>:
the profile to apply. It’s the name of the profile as stated in the json file.
-reset [ <list of characteristics> ]:
the characteristics to be reset/cleared. If not present, it will not clear or reset any characteristic, and it will simply add what is described in the profile. If it’s a valid list of characteristic, those characteristics will be reset, and then what is described in the profile will be applied. If set to PROFILE, it will reset only the characteristics directly modified by the profile (and then the new values described will be applied). If set to ALL, it will reset EVERY characteristic and then it will apply the profile. Accepted values: ALL, PROFILE, ATTRIBUTES, SKILLS, PREFERENCES, BELIEFS, GOALS, FACETS. There must be a space before and after each square bracket. If only one value is provided, the square brackets can be omitted.


  • Loads and applies the profile called “DOCTOR” in the default json file, resetting/clearing all the characteristics changed by the profile, leaving the others unchanged, and then applies the new values:

    assign-profile -profile DOCTOR -reset PROFILE
  • Loads and applies the profile called “ARCHER” in the provided (fictional) json, keeping all the old characteristics but the attributes and the skills, which will be reset (and then, if the profile provides some attributes or skills values, those new values will be applied):

    assign-profile -file /hack/scripts/military_profiles.json -profile ARCHER -reset [ ATTRIBUTES SKILLS ]


A script to change the skills of a unit.

Skills are defined by their token and their rank. Skills tokens can be found here:

Below you can find a list of the first 16 ranks:

Rank Skill name
0 Dabbling
1 Novice
2 Adequate
3 Competent
4 Skilled
5 Proficient
6 Talented
7 Adept
8 Expert
9 Professional
10 Accomplished
11 Great
12 Master
13 High Master
14 Grand Master
15+ Legendary

For more information:


print the help page.
-unit <UNIT_ID>:
the target unit ID. If not present, the currently selected unit will be the target.
-skills [ <SKILL> <RANK> <SKILL> <RANK> <...> ]:
the list of the skills to modify and their ranks. Rank values range from -1 (the skill is not learned) to normally 20 (legendary + 5). It is actually possible to go beyond 20, no check is performed. There must be a space before and after each square bracket.
clear all skills. If the script is called with both this option and a list of skills/ranks, first all the unit skills will be cleared and then the listed skills will be added.


assign-skills -reset -skills [ WOODCUTTING 3 AXE 2 ]

Clears all the unit skills, then adds the Wood cutter skill (competent level) and the Axeman skill (adequate level).


Runs an autolabor command, for all labors where skill level influences output quality. Examples:

autolabor-artisans 0 2 3
autolabor-artisans disable


Gives dwarves unique nicknames chosen randomly from dfhack-config/autonick.txt.

One nickname per line. Empty lines, lines beginning with # and repeat entries are discarded.

Dwarves with manually set nicknames are ignored.

If there are fewer available nicknames than dwarves, the remaining dwarves will go un-nicknamed.

You may wish to use this script with the “repeat” command, e.g: repeat -name autonick -time 3 -timeUnits months -command [ autonick all ]


autonick all [<options>] autonick help


-h, --help:Show this text.
-q, --quiet:Do not report how many dwarves were given nicknames.


Periodically check construction jobs and keep them unsuspended with the unsuspend script.


A more convenient way to ban cooking various categories of foods than the kitchen interface. Usage: ban-cooking <type>. Valid types are booze, honey, tallow, oil, seeds (non-tree plants with seeds), brew, fruit, mill, thread, and milk.


Implements functions for in-memory binpatches. See Patching the DF binary.


This script allows the player to take direct control of any unit present in adventure mode whilst giving up control of their current player character.

To specify the target unit, simply select it in the user interface, such as by opening the unit’s status screen or viewing its description, and enter “bodyswap” in the DFHack console.

Alternatively, the target unit can be specified by its unit id as shown below.


-unit id
    replace "id" with the unit id of your target
        bodyswap -unit 42


Modify the personality traits of the selected dwarf to match an idealised personality - for example, as stable and reliable as possible to prevent tantrums even after months of misery.

Usage: brainwash <type>, with one of the following types:

ideal:reliable, with generally positive personality traits
baseline:reset all personality traits to the average
stepford:amplifies all good qualities to an excessive degree
wrecked:amplifies all bad qualities to an excessive degree


Breaks up dances, such as broken or otherwise hung dances that occur when a unit can’t find a partner.


Instantly completes unsuspended building construction jobs. By default, all buildings on the map are completed, but the area of effect is configurable.

Note that no units will get architecture experience for any buildings that require that skill to construct.


build-now [<pos> [<pos>]] [<options>]

Where the optional <pos> pair can be used to specify the coordinate bounds within which build-now will operate. If they are not specified, build-now will scan the entire map. If only one <pos> is specified, only the building at that coordinate is built.

The <pos> parameters can either be an <x>,<y>,<z> triple (e.g. 35,12,150) or the string here, which means the position of the active game cursor.


Completes all unsuspended construction jobs on the map.
build-now here
Builds the unsuspended, unconstructed building under the cursor.


-h, --help:Show help text.
-q, --quiet:Suppress informational output (error messages are still printed).


Sets all unowned coffins to allow burial. burial -pets also allows burial of pets.


Allows consumption of sapient corpses. Use from an adventurer’s inventory screen or an individual item’s detail screen.


Adjusts properties of caravans on the map. See also force to create caravans.

This script has multiple subcommands. Commands listed with the argument [IDS] can take multiple caravan IDs (see caravan list). If no IDs are specified, then the commands apply to all caravans on the map.


  • list: lists IDs and information about all caravans on the map.
  • extend [DAYS] [IDS]: extends the time that caravans stay at the depot by the specified number of days (defaults to 7 if not specified). Also causes caravans to return to the depot if applicable.
  • happy [IDS]: makes caravans willing to trade again (after seizing goods, annoying merchants, etc.). Also causes caravans to return to the depot if applicable.
  • leave [IDS]: makes caravans pack up and leave immediately.
  • unload: fixes endless unloading at the depot. Run this if merchant pack animals were startled and now refuse to come to the trade depot.


Makes cats (and other animals) just multiply. It is not a good idea to run this more than once or twice.


catsplosion:Make all cats pregnant
catsplosion list:
 List IDs of all animals on the map
catsplosion ID …:
 Make animals with given ID(s) pregnant

Animals will give birth within two in-game hours (100 ticks or fewer).


Removes all smoke from the map. Note that this can leak memory and should be used sparingly.


This script removes all webs that are currently on the map, and also frees any creatures who have been caught in one.

Note that it does not affect sprayed webs until they settle on the ground.

Usable in both fortress and adventurer mode.

Web removal and unit release happen together by default. The following may be used to isolate one of these actions:


    Include this if you want to free all units from webs
    without removing any webs

    Include this if you want to remove all webs
    without freeing any units

See also fix/drop-webs.


List vermin colonies, place honey bees, or convert all vermin to honey bees. Usage:

colonies:List all vermin colonies on the map.
colonies place:Place a honey bee colony under the cursor.
colonies convert:
 Convert all existing colonies to honey bees.

The place and convert subcommands by default create or convert to honey bees, as this is the most commonly useful. However both accept an optional flag to use a different vermin type, for example colonies place ANT creates an ant colony and colonies convert TERMITE ends your beekeeping industry.


A script to manage color schemes.

Current features are :
  • Registration:
  • Loading:
  • Listing:
  • Default:Setting/Loading

For detailed information and usage, type color-schemes in console.

Loaded as a module, this script will export those methods :
  • register(path, force) : Register colors schemes by path (file or directory), relative to DF main directory
  • load(name) : Load a registered color scheme by name
  • list() : Return a list of registered color schemes
  • set_default(name) : Set the default color scheme
  • load_default() : Load the default color scheme

For more information about arguments and return values, see hack/scripts/color-schemes.lua.

Related scripts:


Sets the combat-hardened value on a unit, making them care more/less about seeing corpses. Requires a value and a target.

Valid values:

-value <0-100>:

A percent value to set combat hardened to.

-tier <1-4>:
Choose a tier of hardenedness to set it to.

1 = No hardenedness. 2 = “is getting used to tragedy” 3 = “is a hardened individual” 4 = “doesn’t really care about anything anymore” (max)

If neither are provided, the script defaults to using a value of 100.

Valid targets:

-all:All active units will be affected.
-citizens:All (sane) citizens of your fort will be affected. Will do nothing in adventure mode.
-unit <UNIT ID>:
 The given unit will be affected.

If no target is given, the provided unit can’t be found, or no unit id is given with the unit argument, the script will try and default to targeting the currently selected unit.


Merge stacks of drinks in the selected stockpile.


Merge stacks of plants or plant growths in the selected container or stockpile.


Spawn items under the cursor, to get your fortress started.

The first argument gives the item category, the second gives the material, and the optional third gives the number of items to create (defaults to 20).

Currently supported item categories: boulder, bar, plant, log, web.

Instead of material, using list makes the script list eligible materials.

The web item category will create an uncollected cobweb on the floor.

Note that the script does not enforce anything, and will let you create boulders of toad blood and stuff like that. However the list mode will only show ‘normal’ materials.


create-items boulders COAL_BITUMINOUS 12
create-items plant tail_pig
create-items log list
create-items bar CREATURE:CAT:SOAP
create-items bar adamantine


Select a body part ingame, or a unit from the u unit list, and this script will display the cause of death of the creature.


Moves the starting units and equipment to a specific underground region upon embarking.

This script can be run directly from the console at any point whilst setting up an embark.

Alternatively, create a file called “onLoad.init” in the DF raw folder (if one does not exist already) and enter the script command within it. Doing so will cause the script to run automatically and should hence be especially useful for modders who want their mod to include underground embarks by default.


deep-embark -depth CAVERN_2


-depth X
    replace "X" with one of the following:

    including this arg will prevent demon surges
    in the context of breached underworld spires
    (intended mainly for UNDERWORLD embarks)
    ("wildlife" demon spawning will be unaffected)

    if the script is being run from onLoad.init,
    including this arg will enable deep embarks
    when reclaiming sites too
    (there's no need to specify this if running
    the script directly from the console)

    re-enable normal surface embarks


Causes the selected item types to rot away. By default, items disappear after a few months, but you can choose to slow this down or even make things rot away instantly!

Now all those slightly worn wool shoes that dwarves scatter all over the place or the toes, teeth, fingers, and limbs from the last undead siege will deteriorate at a greatly increased rate, and eventually just crumble into nothing. As warm and fuzzy as a dining room full of used socks makes your dwarves feel, your FPS does not like it!

To always have deteriorate running in your forts, add a line like this to your onMapLoad.init file (use your preferred options, of course):

deteriorate start --types=corpses


deteriorate <command> [<options>]

<command> is one of:

start:Starts deteriorating items while you play.
stop:Stops running.
status:Shows the item types that are currently being monitored and their deterioration frequencies.
now:Causes all items (of the specified item types) to rot away within a few ticks.

You can control which item types are being monitored and their rotting rates by running the command multiple times with different options.

<options> are:

-f, --freq, --frequency <number>[,<timeunits>]
How often to increment the wear counters. <timeunits> can be one of days, months, or years and defaults to days if not specified. The default frequency of 1 day will result in items disappearing after several months. The number does not need to be a whole number. E.g. --freq=0.5,days is perfectly valid.
-q, --quiet
Silence non-error output.
-t, --types <types>
The item types to affect. This option is required for start, stop, and now commands. See below for valid types.

<types> is any of:

clothes:All clothing types that have an armor rating of 0, are on the ground, and are already starting to show signs of wear.
corpses:All non-dwarf corpses and body parts. This includes potentially useful remains such as hair, wool, hooves, bones, and skulls. Use them before you lose them!
food:All food and plants, regardles of whether they are in barrels or stockpiles. Seeds are left untouched.

You can specify multiple types by separating them with commas, e.g. deteriorate start --types=clothes,food.


  • Deteriorate corpses at twice the default rate:

    deteriorate start --types=corpses --freq=0.5,days
  • Deteriorate corpses quickly but food slowly:

    deteriorate start -tcorpses -f0.1
    deteriorate start -tfood -f3,months


The script will try its best to find a job related to the selected entity (which can be a job, dwarf, animal, item, building, plant or work order) and then mark this job as high priority. There is no visual indicator, please look at the dfhack console for output. If a work order is selected, every job currently present job from this work order is affected, but not the future ones.

For best experience add the following to your dfhack*.init:

keybinding add Alt-N do-job-now

Also see do-job-now tweak and prioritize.


Data tables for dwarf-op

  • -list [jobs|professions|types]


dorf_tables -list all
dorf_tables -list job_distributions
dorf_tables -list attrib_levels
dorf_tables -list jobs
dorf_tables -list professions
dorf_tables -list types

The data tables defined are described below.

Defines thresholds for each column of distributions. The columns must add up to the values in the thresholds row for that column. Every other row references an entry in ‘jobs’
Defines stat distributions, used for both physical and mental attributes. Each level gives a probability of a dwarf randomly being assigned an attribute level, and it provides a mean and standard deviation for the attribute’s value.

Defines dwarf-op’s nameable jobs. This is preferable to taking every profession and making a distribution that covers all 100+ profs.

Each job is comprised of required professions, optional professions, probabilities for each optional profession, a ‘max’ number of optional professions, and a list of type(s) to apply to dwarves in the defined job.


These are a subset of the professions DF has. All professions listed will match a profession dwarf fortress has built in, however not all the built-ins are defined here.

Each profession is defined with a set of job skills, these match the skills built in to dwarf fortress. Each skill is given a value which represents the bonus a dwarf will get to this skill. The skills are added in a random order, with the first few receiving the highest values (excluding the bonus just mentioned). Thus the bonuses are to ensure a minimum threshold is passed for certain skills deemed critical to a profession.


These are a sort of archetype system for applying to dwarves. It primarily includes physical attributes, but can include skills as well.

Each type has a probability of being applied to a dwarf just by pure luck - this is in addition to types applied by other means. Each type also has a list of attribute(s) each attribute has a attribute_level associated to it. Additionally each type may define a list of skills from the aforementioned job_skill listing, each skill is defined with a minimum value and maximum value, the given value is an evening distributed random number between these two numbers (inclusive).

To see a full list of built-in professions and jobs, you can run these commands:

devel/query -table df.profession
devel/query -table df.job_skill


Remove all ‘aquifer’ tags from the map blocks. Irreversible.


Dwarf optimization is a script designed to provide a robust solution to hacking dwarves to be better at work. The primary use case is as follows:

  1. take a dwarf
  2. delete their ability to do anything, even walk (job skills, phyiscal/mental attributes)
  3. load the job distribution table from dorf_tables
  4. update values in said table so the table accurately represents the distribution of your dwarves
  5. pick an under-represented job from the table
  6. apply the job to the dwarf, which means:
    • apply professions
    • provide custom profession name
    • add job skills
    • apply dwarf types
    • etc.

Beyond this use case of optimizing dwarves according to the tables in dorf_tables, this script makes each step in the process available to use separately, if you so choose.

There are two basic steps to using this script: selecting a subset of your dwarves, and running commands on those dwarves.


dwarf-op -help
dwarf-op -select <select-option> -<command> <args>


dwarf-op -select [ jobs Trader Miner Leader Rancher ] -applytype adaptable
dwarf-op -select all -clear -optimize
dwarf-op -select pall -clear -optimize
dwarf-op -select optimized -reroll
dwarf-op -select named -reroll inclusive -applyprofession RECRUIT

Select options:


Prepend the letter p to any option to include protected dwarves in your selection


same as typing ‘-select highlighted’


selects all dwarves.


selects only the in-game highlighted dwarf (from any screen). [Ignores protection status]


selects any dwarf with <name> in their name or nickname. (sub-string match) [Ignores protection status]


selects dwarves with user-given names.


selects dwarves without user-given names.


selects dwarves with custom professions. Excludes optimized dwarves.


selects dwarves based on session data. Dwarves who have been optimized should be listed in this data.


selects any dwarves that don’t appear in session data.


selects any dwarves which use protection signals in their name or profession. (i.e. ., ,)


selects any dwarves which don’t use protection signals in their name or profession.


selects any dwarves which are currently zeroed, or were originally drunks as their profession.


selects any dwarves with the listed jobs. This will only match with custom professions, or optimized dwarves (for optimized dwarves see jobs in dorf_tables).


dwarf-op -select [ jobs job1 job2 etc. ]


dwarf-op -select [ jobs Miner Trader ]

selects dwarves from the specified migration waves. Waves are enumerated starting at 0 and increasing by 1 with each wave. The waves go by season and year and thus should match what you see in list-waves or Dwarf Therapist. It is recommended that you -show the selected dwarves before modifying.


dwarf-op -select [ waves 0 1 3 5 7 13 ]

General commands:

  • -reset: deletes json file containing session data (bug: might not delete session data)
  • -resetall: deletes both json files. session data and existing persistent data (bug: might not delete session data)
  • -show: displays affected dwarves (id, name, migration wave, primary job). Useful for previewing selected dwarves before modifying them, or looking up the migration wave number for a group of dwarves.

Dwarf commands:

clean <value>: Cleans selected dwarves.
Checks for skills with a rating of <value> and deletes them from the dwarf’s skill list
-clear: Zeroes selected dwarves, or zeroes all dwarves if no selection is given.
No attributes, no labours. Assigns DRUNK profession.

-reroll [inclusive]: zeroes selected dwarves, then rerolls that dwarf based on its job.

  • Ignores dwarves with unlisted jobs.
  • optional argument: inclusive - means your dorf(s) get the best of N rolls.
  • See attrib_levels table in dorf_tables for p values describing the normal distribution of stats (each p value has a sub-distribution, which makes the bell curve not so bell-shaped). Labours do not follow the same stat system and are more uniformly random, which are compensated for in the description of jobs/professions.
-optimize: Performs a job search for unoptimized dwarves.
Each dwarf will be found a job according to the job_distribution table in dorf_tables.
-applyjobs: Applies the listed jobs to the selected dwarves.
  • List format: [ job1 job2 jobn ] (brackets and jobs all separated by spaces)
  • See jobs table in dorf_tables for available jobs.”
-applyprofessions: Applies the listed professions to the selected dwarves.
  • List format: [ prof1 prof2 profn ] (brackets and professions all separated by spaces)
  • See professions table in dorf_tables for available professions.
-applytypes: Applies the listed types to the selected dwarves.
  • List format: [ type1 type2 typen ] (brackets and types all separated by spaces)
  • See dwf_types table in dorf_tables for available types.

renamejob <name>: Renames the selected dwarves’ custom profession to whatever is specified

Other Arguments:

-help: displays this help information.

-debug: enables debugging print lines


Set all mental attributes of the selected dwarf to the maximum possible, or any number numbers between 0 and 5000 passed as an argument: elevate-mental 100 for example would make the dwarf very stupid indeed.


Set all physical attributes of the selected dwarf to the maximum possible, or any number numbers between 0 and 5000 passed as an argument. Higher is usually better, but an ineffective hammerer can be useful too…


Adjusts dwarves’ skills when embarking.

Note that already-used skill points are not taken into account or reset.

points N:Sets the skill points remaining of the selected dwarf to N.
points N all:Sets the skill points remaining of all dwarves to N.
max:Sets all skills of the selected dwarf to “Proficient”.
max all:Sets all skills of all dwarves to “Proficient”.
legendary:Sets all skills of the selected dwarf to “Legendary”.
legendary all:Sets all skills of all dwarves to “Legendary”.


Allows dwarves to emigrate from the fortress when stressed, in proportion to how badly stressed they are and adjusted for who they would have to leave with - a dwarven merchant being more attractive than leaving alone (or with an elf). The check is made monthly.

A happy dwarf (ie with negative stress) will never emigrate.


emigration enable|disable


Empties the contents of the selected bin onto the floor.


Controls legends mode to export data - especially useful to set-and-forget large worlds, or when you want a map of every site when there are several hundred.

The ‘info’ option exports more data than is possible in vanilla, to a region-date-legends_plus.xml file developed to extend World Viewer and other legends utilities.


exportlegends OPTION [FOLDER_NAME]

Valid values for OPTION are:

info:Exports the world/gen info, the legends XML, and a custom XML with more information
custom:Exports a custom XML with more information
sites:Exports all available site maps
maps:Exports all seventeen detailed maps
all:Equivalent to calling all of the above, in that order

FOLDER_NAME, if specified, is the name of the folder where all the files will be saved. This defaults to the legends-regionX-YYYYY-MM-DD format. A path is also allowed, although everything but the last folder has to exist. To export to the top-level DF folder, pass . for this argument.


  • Export all information to the legends-regionX-YYYYY-MM-DD folder:

    exportlegends all
  • Export all information to the region6 folder:

    exportlegends all region6
  • Export just the files included in info (above) to the legends-regionX-YYYYY-MM-DD folder:

    exportlegends info
  • Export just the custom XML file to the DF folder (no subfolder):

    exportlegends custom .

Keybinding: CtrlA -> "exportlegends all" in legends


Kills any unit of a given race.

With no argument, lists the available races and count eligible targets.

With the special argument this, targets only the selected creature. Alternatively, him, her, it, target, and selected do the same thing.

With the special argument undead, targets all undeads on the map, regardless of their race.

When specifying a race, a caste can be specified to further restrict the targeting. To do that, append and colon and the caste name after the race.

Any non-dead non-caged unit of the specified race gets its blood_count set to 0, which means immediate death at the next game tick. For creatures such as vampires, it also sets animal.vanish_countdown to 2.

An alternate mode is selected by adding a 2nd argument to the command, magma. In this case, a column of 7/7 magma is generated on top of the targets until they die (Warning: do not call on magma-safe creatures. Also, using this mode on birds is not recommended.) The final alternate mode is butcher, which marks them for butchering but does not kill.

Will target any unit on a revealed tile of the map, including ambushers, but ignore caged/chained creatures.


exterminate gob
exterminate gob:male
exterminate gob:enemy

To kill a single creature, select the unit with the ‘v’ cursor and:

exterminate this

To purify all elves on the map with fire (may have side-effects):

exterminate elve magma


This script allows the user to put out fires affecting map tiles, plants, units, items and buildings.

To select a target, place the cursor over it before running the script. Alternatively, use one of the arguments below.


    extinguish everything on the map

-location [ x y z ]
    extinguish only at the specified coordinates


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.


list:Lists all map features in your current embark by index.
magma:Enable magma furnaces (discovers a random magma feature).
show X:Marks the selected map feature as discovered.
hide X:Marks the selected map feature as undiscovered.


Use with a unit selected to make them focused and unstressed.

Alternatively, a unit can be specified by passing -unit UNIT_ID

Use -all to apply to all units on the map.


Lights things on fire: items, locations, entire inventories even! Use while viewing an item, unit inventory, or tile to start fires.


Utilizes the orientation tag to either fix infertile creatures or inflict infertility on creatures that you do not want to breed. Usage:

fix-ster [fert|ster] [all|animals|only:<creature>]

fert or ster is a required argument; whether to make the target fertile or sterile. Optional arguments specify the target: no argument for the selected unit, all for all units on the map, animals for all non-dwarf creatures, or only:<creature> to only process matching creatures.


Removes all unhappy thoughts due to lack of clothing.


A hotkey-friendly teleport that places your adventurer where your cursor is.


A simpler wrapper around the modtools/force script.


  • force event_type
  • force event_type civ_id - civ ID required for Diplomat and Caravan events

See modtools/force for a complete list of event types.


Removes emotions associated with seeing a dead body.


Saves a copy of a text screen, formatted in bbcode for posting to the Bay12 Forums. See markdown to export for Reddit etc.

This script will attempt to read the current df-screen, and if it is a text-viewscreen (such as the dwarf ‘thoughts’ screen or an item ‘description’) then append a marked-up version of this text to the target file. Previous entries in the file are not overwritten, so you may use the ‘forumdwarves’ command multiple times to create a single document containing the text from multiple screens (eg: text screens from several dwarves, or text screens from multiple artifacts/items, or some combination).

The screens which have been tested and known to function properly with this script are:

  1. dwarf/unit ‘thoughts’ screen
  2. item/art ‘description’ screen
  3. individual ‘historical item/figure’ screens

There may be other screens to which the script applies. It should be safe to attempt running the script with any screen active, with an error message to inform you when the selected screen is not appropriate for this script.

The target file’s name is ‘forumdwarves.txt’. A reminder to this effect will be displayed if the script is successful.


The text will be encoded in CP437, which is likely to be incompatible with the system default. This causes incorrect display of special characters (eg. é õ ç = é õ ç). You can fix this by opening the file in an editor such as Notepad++ and selecting the correct encoding before using the text.

Keybinding: CtrlShiftF in dwarfmode


Attempts to fully heal the selected unit from anything, optionally including death. Usage:

full-heal:Completely heal the currently selected unit.
full-heal -unit [unitId]:
 Apply command to the unit with the given ID, instead of selected unit.
full-heal -r [-keep_corpse]:
 Heal the unit, raising from the dead if needed. Add -keep_corpse to avoid removing their corpse. The unit can be targeted by selecting its corpse on the UI.
full-heal -all [-r] [-keep_corpse]:
 Heal all units on the map.
full-heal -all_citizens [-r] [-keep_corpse]:
 Heal all fortress citizens on the map. Does not include pets.
full-heal -all_civ [-r] [-keep_corpse]:
 Heal all units belonging to your parent civilisation, including pets and visitors.

For example, full-heal -r -keep_corpse -unit ID_NUM will fully heal unit ID_NUM. If this unit was dead, it will be resurrected without deleting the corpse - creepy!


Shows the sexual orientation of units, useful for social engineering or checking the viability of livestock breeding programs.


-all:shows orientation of every creature
-citizens:shows only orientation of citizens in fort mode
-named:shows orientation of all named units on map
(no target):shows orientation of the unit under the cursor

Orientation filters:

-notStraight:only creatures who are not strictly straight
-gayOnly:only creatures who are strictly gay
-biOnly:only creatures who can get into romances with both sexes
-straightOnly:only creatures who are strictly straight
-asexualOnly:only creatures who are strictly asexual


Geld allows the user to geld and ungeld animals.

Valid options:

-unit <id>: Gelds the unit with the specified ID.
This is optional; if not specified, the selected unit is used instead.

-ungeld: Ungelds the specified unit instead (see also ungeld).

-toggle: Toggles the gelded status of the specified unit.

-help: Shows this help information


Toggles an adventurer’s ghost status. Useful for walking through walls, avoiding attacks, or recovering after a death.


Instantly grow seeds inside farming plots.

With no argument, this command list the various seed types currently in use in your farming plots. With a seed type, the script will grow specified seeds, ready to be harvested.


  • list or help
    List the various seed types currently in use in your farming plots
  • <crop name>
    Grow specific planted seed type
  • all
    Grow all planted seeds


  • Grow plump helmet spawn:
    growcrops plump


Blocks all caravans, migrants, diplomats, and forgotten beasts (not wildlife). Useful for attempting the hermit challenge.

Use enable or disable to enable/disable, or help for this help.


This does not block sieges, and may not block visitors or monarchs.


Creates a pit to the underworld at the cursor, taking three numbers as arguments. Usage: hfs-pit <size> <walls> <stairs>

The first argument is size of the (square) pit in all directions. The second is 1 to wall off the sides of the pit on all layers except the underworld, or anything else to leave them open. The third parameter is 1 to add stairs. Stairs are buggy; they will not reveal the bottom until you dig somewhere, but underworld creatures will path in.


hfs-pit 1 0 0
    A single-tile wide pit with no walls or stairs.
    This is the default if no numbers are given.

hfs-pit 4 0 1
    A four-across pit with no stairs but adding walls.

hfs-pit 2 1 0
    A two-across pit with stairs but no walls.


Lists the key, name, and jump position of your hotkeys in the DFHack console.


Saves information about the current DFHack installation to install-info.txt in the current DF folder. Useful for bug reports.


Exports a table with custom description text for every item in the game. Used by view-item-info; see instructions there for how to override for mods.


Activate with a cursor on screen and you will go there rapidly. Attack something first to ride them there.


Allow manipulation of in-game levers from the dfhack console.

Can list levers, including state and links, with:

lever list

To queue a job so that a dwarf will pull the lever 42, use lever pull 42. This is the same as q querying the building and queue a P pull request.

To queue a job at high priority, add --high or --priority:

lever pull 42 --high

To magically toggle the lever immediately, add --now or --cheat:

lever pull 42 --now


This script behaves differently depending on whether it’s called pre embark or post embark. Pre embark it changes all aquifers in the world to light ones, while post embark it only changes the ones at the embark to light ones, leaving the rest of the world unchanged.

Pre embark: Changes the Drainage of all world tiles that would generate Heavy aquifers into a value that results in Light aquifers instead.

This script is based on logic revealed by ToadyOne in a FotF answer: Basically the Drainage is used as an “RNG” to cause an aquifer to be heavy about 5% of the time. The script shifts the matching numbers to a neighboring one, which does not result in any change of the biome.

Post embark: Clears the flags that mark aquifer tiles as heavy, converting them to light.


Enables the player to take control of their adventurer’s killer. Run this script after being presented with “You are deceased.”

The killer is identified by examining the historical event generated when the adventurer died. If this is unsuccessful, the killer is assumed to be the last unit to have attacked the adventurer prior to their death.

This will fail if the unit in question is no longer present on the local map.

(Adventure mode only!)


Lists Guildhall and Temple agreements in fortress mode. In addition:

  • Translates names of the associated Guilds and Orders respectively
  • Displays worshiped Professions and Deities respectively
  • Petition age and status satisfied, denied or expired, or blank for outstanding


list-agreements [options]


List outstanding, unfullfilled location agreements.
list-agreements all
Lists all location agreements, whether satisfied, denied, or expired.


all:list all agreements; past and present
help:shows this help screen


This script displays information about migration waves of the specified citizen(s).


list-waves -all -showarrival -granularity days
list-waves -all -showarrival
list-waves -unit -granularity days
list-waves -unit
list-waves -unit -all -showarrival -granularity days

Selection options:

These options are used to specify what wave information to display

Displays the highlighted unit’s arrival wave information
Displays all citizens’ arrival wave information

Other options:

-granularity <value>:
Specifies the granularity of wave enumeration: years, seasons, months, days If omitted, the default granularity is seasons, the same as Dwarf Therapist
Shows the arrival information for the selected unit. If -all is specified the info displayed will be relative to the granularity used. Note: this option is always used when -unit is used.


When run on the title screen or “load game” screen, loads the save with the given folder name without requiring interaction. Note that inactive saves (i.e. saves under the “start game” menu) are currently not supported.


load-save region1

This can also be run when starting DFHack from the command line. For example, on Linux/macOS:

./dfhack +load-save region1


Scan the map for metal ores.

Finds and designate for digging one tile of a specific metal ore. Only works for native metal ores, does not handle reaction stuff (eg STEEL).

When invoked with the list argument, lists metal ores available on the map.


locate-ore list
locate-ore hematite
locate-ore iron


There are the following ways to invoke this command:

  1. lua (without any parameters)

    This starts an interactive lua interpreter.

  2. lua -f "filename" or lua --file "filename"

    This loads and runs the file indicated by filename.

  3. lua -s ["filename"] or lua --save ["filename"]

    This loads and runs the file indicated by filename from the save directory. If the filename is not supplied, it loads “dfhack.lua”.

  4. :lua lua statement…

    Parses and executes the lua statement like the interactive interpreter would.


Makes the selected dwarf legendary in one skill, a group of skills, or all skills. View groups with make-legendary classes, or all skills with make-legendary list. Use make-legendary MINING when you need something dug up, or make-legendary all when only perfection will do.


Make the selected unit King or Queen of your civilisation.


Save a copy of a text screen in markdown (useful for Reddit, among other sites). See forum-dwarves for BBCode export (for e.g. the Bay12 Forums).

This script will attempt to read the current df-screen, and if it is a text-viewscreen (such as the dwarf ‘thoughts’ screen or an item / creature ‘description’) or an announcement list screen (such as announcements and combat reports) then append a marked-down version of this text to the target file (for easy pasting on reddit for example). Previous entries in the file are not overwritten, so you may use the``markdown`` command multiple times to create a single document containing the text from multiple screens (eg: text screens from several dwarves, or text screens from multiple artifacts/items, or some combination).


markdown [-n] [filename]
-n:overwrites contents of output file
filename:if provided, save to instead of the default

The screens which have been tested and known to function properly with this script are:

  1. dwarf/unit ‘thoughts’ screen
  2. item/art ‘description’ screen
  3. individual ‘historical item/figure’ screens
  4. manual
  5. announements screen
  6. combat reports screen
  7. latest news (when meeting with liaison)

There may be other screens to which the script applies. It should be safe to attempt running the script with any screen active, with an error message to inform you when the selected screen is not appropriate for this script.


Designate all creatures in cages on top of a pit/pond activity zone for pitting. Works best with an animal stockpile on top of the zone.

Works with a zone number as argument (eg Activity Zone #6 -> masspit 6) or with the game cursor on top of the area.


Forces an immediate migrant wave. Only works after migrants have arrived naturally. Roughly equivalent to modtools/force with:

modtools/force -eventType migrants


Run multiple dfhack commands. The argument is split around the character “;”, and all parts are run sequentially as independent dfhack commands. Useful for hotkeys.


multicmd locate-ore IRON; digv; digcircle 16


Rename units or items (including artifacts) with the native interface. If a first name is desired, press f. To clear the current first name, leave this blank.


Runs commands like multicmd, but only in a newborn fortress.

Use this in onMapLoad.init with f.e. ban-cooking:

on-new-fortress ban-cooking tallow; ban-cooking honey; ban-cooking oil; ban-cooking seeds; ban-cooking brew; ban-cooking fruit; ban-cooking mill; ban-cooking thread; ban-cooking milk;
on-new-fortress 3dveins


Runs commands like multicmd, but only unless not already ran once in current save. You may actually want on-new-fortress.

Only successfully ran commands are saved.


--help display this help
--rerun commands
 ignore saved commands
--reset deletes saved commands


Open a legends screen when in fortress mode. Requires a world loaded in fortress or adventure mode. Compatible with exportlegends.

Note that this script carries a significant risk of save corruption if the game is saved after exiting legends mode. To avoid this:

  1. Pause DF
  2. Run quicksave to save the game
  3. Run open-legends (this script) and browse legends mode as usual
  4. Immediately after exiting legends mode, run die to quit DF without saving (saving at this point instead may corrupt your save)

Note that it should be safe to run “open-legends” itself multiple times in the same DF session, as long as DF is killed immediately after the last run. Unpausing DF or running other commands risks accidentally autosaving the game, which can lead to save corruption.

The optional force argument will bypass all safety checks, as well as the save corruption warning.


Sets available points at the embark screen to the specified number. Eg. points 1000000 would allow you to buy everything, or points 0 would make life quite difficult.


Reports the current time: date, clock time, month, and season. Also reports location: z-level, cursor position, window size, and mouse location.


pref-adjust all removes/changes preferences from all dwarves, and pref-adjust one which works for a single currently selected dwarf. For either, the script inserts an ‘ideal’ set which is easy to satisfy:

… likes iron, steel, weapons, armor, shields/bucklers and plump helmets for their rounded tops. When possible, she prefers to consume dwarven wine, plump helmets, and prepared meals (quarry bush). She absolutely detests trolls, buzzards, vultures and crundles.

Additionally, pref-adjust goth will insert a less than ideal set, which is quite challenging, for a single dwarf:

… likes dwarf skin, corpses, body parts, remains, coffins, the color black, crosses, glumprongs for their living shadows and snow demons for their horrifying features. When possible, she prefers to consume sewer brew, gutter cruor and bloated tubers. She absolutely detests elves, humans and dwarves.

To see what values can be used with each type of preference, use pref-adjust list. Optionally, a single dwarf or all dwarves can have their preferences cleared manually with the use of pref-adjust clear and pref-adjust clear_all, respectively. Existing preferences are automatically cleared, normally.


Sets preferences for mooding to include a weapon type, equipment type, and material. If you also wish to trigger a mood, see strangemood.

Valid options:

show:show preferences of all units
c:clear preferences of selected unit
all:clear preferences of all units
axp:likes axes, breastplates, and steel
has:likes hammers, mail shirts, and steel
swb:likes short swords, high boots, and steel
spb:likes spears, high boots, and steel
mas:likes maces, shields, and steel
xbh:likes crossbows, helms, and steel
pig:likes picks, gauntlets, and steel
log:likes long swords, gauntlets, and steel
dap:likes daggers, greaves, and steel

Feel free to adjust the values as you see fit, change the has steel to platinum, change the axp axes to great axes, whatnot.


The prioritize script sets the do_now flag on all of the specified types of jobs that are ready to be picked up by a dwarf but not yet assigned to a dwarf. This will force them to get assigned and completed as soon as possible.

This script can also continue to monitor new jobs and automatically boost the priority of jobs of the specified types.

This is useful for ensuring important (but low-priority – according to DF) jobs don’t get indefinitely ignored in busy forts. The list of monitored job types is cleared whenever you unload a map, so you can add a section like the one below to your onMapLoad.init file to ensure important and time-sensitive job types are always completed promptly in your forts:

prioritize -a --haul-labor=Food,Body StoreItemInStockpile
prioritize -a --reaction-name=TAN_A_HIDE CustomReaction
prioritize -a PrepareRawFish ExtractFromRawFish CleanSelf

It is important to automatically prioritize only the most important job types. If you add too many job types, or if there are simply too many jobs of those types in your fort, the other tasks in your fort can get ignored. This causes the same problem the prioritize script is designed to solve. See the onMapLoad_dreamfort.init file in the hack/examples/init folder for a more complete, playtested set of job types to automatically prioritize.

If you need a bunch of jobs of a specific type prioritized right now, consider running prioritize without the -a parameter, which only affects currently available (but unassigned) jobs. For example:

prioritize ConstructBuilding

Also see the do-job-now tweak for adding a hotkey to the jobs screen that can toggle the priority of specific individual jobs and the do-job-now script, which boosts the priority of current jobs related to the selected job/unit/item/building/order.


prioritize [<options>] [<job_type> ...]


Prints out which job types are being automatically prioritized and how many jobs of each type we have prioritized since we started watching them.
prioritize -j
Prints out the list of active job types that you can prioritize right now.
prioritize ConstructBuilding DestroyBuilding
Prioritizes all current building construction and destruction jobs.
prioritize -a --haul-labor=Food,Body StoreItemInStockpile
Prioritizes all current and future food and corpse hauling jobs.


-a, --add:Prioritize all current and future jobs of the specified job types.
-d, --delete:Stop automatically prioritizing new jobs of the specified job types.
-h, --help:Show help text.
-j, --jobs:Print out how many unassigned jobs of each type there are. This is useful for discovering the types of the jobs that you can prioritize right now. If any job types are specified, only returns the count for those types.
-l, --haul-labor <labor>[,<labor>…]:
 For StoreItemInStockpile jobs, match only the specified hauling labor(s). Valid <labor> strings are: “Stone”, “Wood”, “Body”, “Food”, “Refuse”, “Item”, “Furniture”, and “Animals”. If not specified, defaults to matching all StoreItemInStockpile jobs.
-n, --reaction-name <name>[,<name>…]:
 For CustomReaction jobs, match only the specified reaction name(s). See the registry output (-r) for the full list of reaction names. If not specified, defaults to matching all CustomReaction jobs.
-q, --quiet:Suppress informational output (error messages are still printed).
-r, --registry:Print out the full list of valid job types, hauling labors, and reaction names.


Makes item appear on the table, like in adventure mode shops. Arguments:

  • -a or --all: apply to all items at the cursor


Teleports your adventurer to the location of your quest log map cursor.

Use by opening the quest log map and moving the cursor to your target location before running the script. Note that this can be done both within and outside of fast travel mode, and that it is possible to questport in situations where fast travel is normally prohibited.

It is currently not possible to questport into inaccessible locations like ocean and mountain tiles.

See reveal-adv-map if you wish to teleport into hidden map tiles.


Processes Quickfort-style blueprint files.

Quickfort blueprints record what you want at each map coordinate in a spreadsheet, storing the keys in a spreadsheet cell that you would press to make something happen at that spot on the DF map. Quickfort runs in one of five modes: dig, build, place, zone, or query. dig designates tiles for digging, build builds buildings and constructions, place places stockpiles, zone manages activity zones, and query changes building or stockpile settings. The mode is determined by a marker in the upper-left cell of the spreadsheet (e.g.: #dig in cell A1).

You can create these blueprints by hand or by using any spreadsheet application, saving them as .xlsx or .csv files. You can also build your plan “for real” in Dwarf Fortress, and then export your map using the DFHack blueprint plugin (or gui/blueprint script) for later replay. Blueprint files should go in the blueprints subfolder in the main DF folder.

For more details on blueprint file syntax, see the Quickfort Blueprint Editing Guide or browse through the ready-to-use examples in the Blueprint Library Index.


quickfort set [<key> <value>]
Allows you to modify the active quickfort configuration. Just run quickfort set to show current settings. See the Configuration section below for available keys and values.
quickfort reset
Resets quickfort configuration to the defaults in quickfort.txt.
quickfort list [-m|–mode <mode>] [-l|–library] [-h|–hidden] [search string]
Lists blueprints in the blueprints folder. Blueprints are .csv files or sheets within .xlsx files that contain a #<mode> comment in the upper-left cell. By default, blueprints in the blueprints/library/ subfolder or blueprints that contain a hidden() marker in their modeline are not shown. Specify -l or -h to include library or hidden blueprints, respectively. The list can be filtered by a specified mode (e.g. “-m build”) and/or strings to search for in a path, filename, mode, or comment. The id numbers in the list may not be contiguous if there are hidden or filtered blueprints that are not being shown.
quickfort gui [filename or search terms]
Invokes the quickfort UI with the specified parameters, giving you an interactive blueprint preview to work with before you apply it to the map. See the gui/quickfort documentation for details.
quickfort <command>[,<command>…] <list_num>[,<list_num>…] [<options>]
Applies the blueprint(s) with the number(s) from the list command.
quickfort <command>[,<command>…] <filename> [-n|–name <name>[,<name>…]] [<options>]
Applies a blueprint in the specified file. The optional name parameter can select a specific blueprint from a file that contains multiple blueprints with the format “sheetname/label”, or just “/label” for .csv files. The label is defined in the blueprint modeline, or, if not defined, defaults to its order in the sheet or file (e.g. “/2”). If the -n parameter is not specified, the first blueprint in the first sheet is used.

<command> is one of:

run:Applies the blueprint at your current in-game cursor position.
orders:Uses the manager interface to queue up orders to manufacture items for the specified blueprint(s).
undo:Applies the inverse of the specified blueprint. Dig tiles are undesignated, buildings are canceled or removed (depending on their construction status), and stockpiles/zones are removed. There is no effect for query blueprints since they can contain arbitrary key sequences.

<options> can be zero or more of:

-c, --cursor <x>,<y>,<z>
Use the specified map coordinates instead of the current map cursor for the the blueprint start position. If this option is specified, then an active game map cursor is not necessary.
-d, --dry-run
Go through all the motions and print statistics on what would be done, but don’t actually change any game state.
--preserve-engravings <quality>
Don’t designate tiles for digging if they have an engraving with at least the specified quality. Valid values for quality are: None, Ordinary, WellCrafted, FinelyCrafted, Superior, Exceptional, and Masterful. Specify None to ignore engravings when designating tiles. Note that if Masterful tiles are dug out, the dwarf who engraved the masterwork will get negative thoughts. If not specified, Masterful engravings are preserved by default.
-q, --quiet
Suppress non-error console output.
-r, --repeat <direction>[,]<num levels>
Repeats the specified blueprint(s) up or down the requested number of z-levels. Direction can be up or down, and can be abbreviated with < or >. For example, the following options are equivalent: --repeat down,5, -rdown5, and -r>5.
-s, --shift <x>[,<y>]
Shifts the blueprint by the specified offset before modifying the game map. The values for <x> and <y> can be negative. If both --shift and --transform are specified, the shift is always applied last.
-t, --transform <transformation>[,<transformation>...]
Applies geometric transformations to the blueprint before modifying the game map. See the Transformations section below for details.
-v, --verbose
Output extra debugging information. This is especially useful if the blueprint isn’t being applied like you expect.

Example commands:

quickfort list
quickfort list -l dreamfort help
quickfort run library/dreamfort.csv
quickfort run,orders library/dreamfort.csv -n /industry2
quickfort run 10 -dv


All transformations are anchored at the blueprint start cursor position. This is the upper left corner by default, but it can be modified if the blueprint has a start() modeline marker. This just means that the blueprint tile that would normally appear under your cursor will still appear under your cursor, regardless of how the blueprint is rotated or flipped.

<transformation> is one of:

rotcw or cw:Rotates the blueprint 90 degrees clockwise.
rotccw or ccw:Rotates the blueprint 90 degrees counterclockwise.
fliph:Flips the blueprint horizontally (left edge becomes right edge).
flipv:Flips the blueprint vertically (top edge becomes bottom edge).


The quickfort script reads its startup configuration from the dfhack-config/quickfort/quickfort.txt file, which you can customize. The settings may be dynamically modified by the quickfort set command for the current session, but settings changed with the quickfort set command will not change the configuration stored in the file:

blueprints_dir (default: ‘blueprints’)
Directory tree to search for blueprints. Can be set to an absolute or relative path. If set to a relative path, resolves to a directory under the DF folder. Note that if you change this directory, you will not see blueprints written by the DFHack blueprint plugin (which always writes to the blueprints dir) or blueprints in the quickfort blueprint library.
force_marker_mode (default: ‘false’)
If true, will designate all dig blueprints in marker mode. If false, only cells with dig codes explicitly prefixed with m will be designated in marker mode.
query_unsafe (default: ‘false’)
Skip query blueprint sanity checks that detect common blueprint errors and halt or skip keycode playback. Checks include ensuring a configurable building exists at the designated cursor position and verifying the active UI screen is the same before and after sending keys for the cursor position. If you find you need to enable this for one of your own blueprints, you should probably be using a config blueprint, not a query blueprint. Most players will never need to enable this setting.
stockpiles_max_barrels, stockpiles_max_bins, and stockpiles_max_wheelbarrows (defaults: -1, -1, 0)
Set to the maximum number of resources you want assigned to stockpiles of the relevant types. Set to -1 for DF defaults (number of stockpile tiles for stockpiles that take barrels and bins, 1 wheelbarrow for stone stockpiles). The default here for wheelbarrows is 0 since using wheelbarrows can decrease the efficiency of your fort unless you know how to use them properly. Blueprints can override this value for specific stockpiles.

There is one other configuration file in the dfhack-config/quickfort folder: aliases.txt. It defines keycode shortcuts for query blueprints. The format for this file is described in the Quickfort Keystroke Alias Guide, and default aliases that all players can use and build on are available in the The DFHack standard alias library. Some quickfort library aliases require the search plugin to be enabled.


The quickfort script can be called programmatically by other scripts either via the commandline interface with dfhack.run_script() or via the API functions defined in quickfort.lua:

  • apply_blueprint(params)

Applies the specified blueprint data and returns processing statistics. The statistics structure is a map of stat ids to {label=string, value=number}.

params is a table with the following fields:

mode:(required) The name of the blueprint mode, e.g. ‘dig’, ‘build’, etc.
data:(required) A sparse map populated such that data[z][y][x] yields the blueprint text that should be applied to the tile at map coordinate (x, y, z). You can also just pass a string and it will be interpreted as the value of data[0][0][0].
command:The quickfort command to execute, e.g. ‘run’, ‘orders’, etc. Defaults to ‘run’.
pos:A coordinate that serves as the reference point for the coordinates in the data map. That is, the text at data[z][y][x] will be shifted to be applied to coordinate (pos.x + x, pos.y + y, pos.z + z). If not specified, defaults to {x=0, y=0, z=0}, which means that the coordinates in the data map are used directly.
aliases:a map of query blueprint aliases names to their expansions. If not specified, defaults to {}.
 Don’t designate tiles for digging if they have an engraving with at least the specified quality. Value is a df.item_quality enum name or value, or “None” (or, equivalently, -1) to indicate that no engravings should be preserved. Defaults to df.item_quality.Masterful.
dry_run:Just calculate statistics, such as how many tiles are outside the boundaries of the map; don’t actually apply the blueprint. Defaults to false.
verbose:Output extra debugging information to the console. Defaults to false.

API usage example:

local guidm = require('gui.dwarfmode')
local quickfort = reqscript('quickfort')
-- dig a 10x10 block at the cursor position
quickfort.apply_blueprint{mode='dig', data={[0]={[0]={[0]='d(10x10)'}}},


If called in dwarf mode, makes DF immediately saves the game by setting a flag normally used in seasonal auto-save.

Keybinding: CtrlAltS in dwarfmode/Default


Show or modify the populations of animals in the region.


region-pops list [pattern]:
 Lists encountered populations of the region, possibly restricted by pattern.
region-pops list-all [pattern]:
 Lists all populations of the region.
region-pops boost <TOKEN> <factor>:
 Multiply all populations of TOKEN by factor. If the factor is greater than one, increases the population, otherwise decreases it.
region-pops boost-all <pattern> <factor>:
 Same as above, but match using a pattern acceptable to list.
region-pops incr <TOKEN> <factor>:
 Augment (or diminish) all populations of TOKEN by factor (additive).
region-pops incr-all <pattern> <factor>:
 Same as above, but match using a pattern acceptable to list.


Decreases the age of the selected dwarf to 20 years. Useful if valuable citizens are getting old.


  • -all: applies to all citizens
  • -force: also applies to units under 20 years old. Useful if there are too many babies around…
  • -dry-run: only list units that would be changed; don’t actually change ages


Sets stress to -1,000,000; the normal range is 0 to 500,000 with very stable or very stressed dwarves taking on negative or greater values respectively. Applies to the selected unit, or use remove-stress -all to apply to all units.

Using the argument -value 0 will reduce stress to the value 0 instead of -1,000,000. Negative values must be preceded by a backslash (): -value \-10000. Note that this can only be used to decrease stress - it cannot be increased with this argument.


Sets the wear on items in your fort to zero. Usage:

remove-wear all:
 Removes wear from all items in your fort.
remove-wear ID1 ID2 …:
 Removes wear from items with the given ID numbers.


Repeatedly calls a lua script at the specified interval. This can be used from init files. Note that any time units other than frames are unsupported when a world is not loaded (see dfhack.timeout()).

Usage examples:

repeat -name jim -time delay -timeUnits units -command [ printArgs 3 1 2 ]
repeat -time 1 -timeUnits months -command [ multicmd cleanowned scattered x; clean all ] -name clean
repeat -list

The first example is abstract; the second will regularly remove all contaminants and worn items from the game.


sets the name for the purposes of cancelling and making sure you don’t schedule the same repeating event twice. If not specified, it’s set to the first argument after -command.
-time DELAY -timeUnits UNITS
DELAY is some positive integer, and UNITS is some valid time unit for dfhack.timeout (default “ticks”). Units can be in simulation-time “frames” (raw FPS) or “ticks” (only while unpaused), while “days”, “months”, and “years” are by in-world time.
-command [ ... ]
... specifies the command to be run
-cancel NAME
cancels the repetition with the name NAME
prints names of scheduled commands


Brings a dead adventurer back to life, fully healing them in the process.

This script only targets the current player character in your party, and should be run after being presented with the “You are deceased” message. It is not possible to resurrect the adventurer after the game has been ended.


This script can be used to either reveal or hide all tiles on the world map in adventure mode (visible when viewing the quest log or fast travelling, for example).

Note that the script does not reveal hidden lairs, camps, etc. See reveal-hidden-sites for this functionality.


    Include this if you want to hide all world tiles instead
    of revealing them


This script reveals all sites in the world that have yet to be discovered by the player (camps, lairs, shrines, vaults, etc) thus making them visible on the map.

Usable in both fortress and adventure mode.

See reveal-adv-map if you also want to expose hidden world map tiles in adventure mode.


This script exposes all units on the map who are currently sneaking or waiting in ambush and thus hidden from the player’s view.

Usable in both fortress and adventure mode.


Swap color palettes when the seasons change.

For this script to work you need to add at least one color palette file to your save raw directory.

Palette file names:
“colors.txt”: The world “default” (worldgen and replacement) palette. “colors_spring.txt”: The palette displayed during spring. “colors_summer.txt”: The palette displayed during summer. “colors_autumn.txt”: The palette displayed during autumn. “colors_winter.txt”: The palette displayed during winter.

If you do not provide a world default palette, palette switching will be disabled for the current world. The seasonal palettes are optional, the default palette is not! The default palette will be used to replace any missing seasonal palettes and during worldgen.

When the world is unloaded or this script is disabled, the system default color palette (“/data/init/colors.txt”) will be loaded. The system default palette will always be used in the main menu, but your custom palettes should be used everywhere else.


season-palette start|enable or enable season-palette:
Begin swapping seasonal color palettes.
season-palette stop|disable or disable season-palette:
Stop swapping seasonal color palettes and load the default color palette.

If loaded as a module this script will export a single Lua function:

Load a color palette from the text file at “path”. This file must be in the same format as “/data/init/colors.txt”. If there is an error any changes will be reverted and this function will return false (returns true normally).


Edit a unit’s orientation. Interest levels are 0 for Uninterested, 1 for Romance, 2 for Marry.

unit <UNIT ID>:The given unit will be affected. If not found/provided, the script will try defaulting to the currently selected unit.
male <INTEREST>:
 Set the interest level towards male sexes
female <INTEREST>:
 Set the interest level towards female sexes
opposite <INTEREST>:
 Set the interest level towards the opposite sex to the unit
same <INTEREST>:
 Set the interest level towards the same sex as the unit
random:Randomise the unit’s interest towards both sexes, respecting their ORIENTATION token odds.

Other arguments:

help:Shows this help page.
view:Print the unit’s orientation values in the console.


Starting a new fortress/adventurer session is preceded by an “Updating World” process which is normally 2 weeks long. This script allows you to modify the duration of this timeskip, enabling you to jump into the game earlier or later than usual.

You can use this at any point before the timeskip begins (for example, while still at the “Start Playing” menu).

It is also possible to run the script while the world is updating, which can be useful if you decide to end the process earlier or later than initially planned.

Note that the change in timeskip duration will persist until either

  • the game is closed,
  • the “-clear” argument is used (see below),
  • or it is overwritten by setting a new duration.

The timeskip duration can be specified using any combination of the following arguments.


-ticks X
    Replace "X" with a positive integer (or 0)
    Adds the specified number of ticks to the timeskip duration
    The following conversions may help you calculate this:
        1 tick = 72 seconds = 1 minute 12 seconds
        50 ticks = 60 minutes = 1 hour
        1200 ticks = 24 hours = 1 day
        8400 ticks = 7 days = 1 week
        33600 ticks = 4 weeks = 1 month
        403200 ticks = 12 months = 1 year

-years X
    Replace "X" with a positive integer (or 0)
    Adds (403200 multiplied by X) ticks to the timeskip duration

-months X
    Replace "X" with a positive integer (or 0)
    Adds (33600 multiplied by X) ticks to the timeskip duration

-days X
    Replace "X" with a positive integer (or 0)
    Adds (1200 multiplied by X) ticks to the timeskip duration

-hours X
    Replace "X" with a positive integer (or 0)
    Adds (50 multiplied by X) ticks to the timeskip duration

    This resets the timeskip duration to its default value.
    Note that it won't affect timeskips which have already begun.


set-timeskip-duration -ticks 851249
    Sets the end of the timeskip to
    2 years, 1 month, 9 days, 8 hours, 58 minutes, 48 seconds
    from the current date.

set-timeskip-duration -years 2 -months 1 -days 9 -hours 8 -ticks 49
    Does the same thing as the previous example


Sets the FPS cap at runtime. Useful in case you want to speed up the game or watch combat in slow motion.


setfps <number>


Show syndromes affecting units and the remaining and maximum duration, along with (optionally) substantial detail on the effects.

Use one or more of the following options:

help:Show the help message
showall:Show units even if not affected by any syndrome
showeffects:Show detailed effects of each syndrome
 Show effects that only change the look of the unit
selected:Show selected unit
dwarves:Show dwarves
livestock:Show livestock
wildanimals:Show wild animals
hostile:Show hostiles (e.g. invaders, thieves, forgotten beasts etc)
world:Show all defined syndromes in the world
export:export:<filename> sends output to the given file, showing all syndromes affecting each unit with the maximum and present duration.


Wakes up sleeping units and stops parties, either everywhere or in the burrows given as arguments. In return, adds bad thoughts about noise, tiredness and lack of protection. The script is intended for emergencies, e.g. when a siege appears, and all your military is partying.


Create an infinite magma or water source or drain on a tile. For more complex commands, try the liquids plugin.

This script registers a map tile as a liquid source, and every 12 game ticks that tile receives or remove 1 new unit of flow based on the configuration.

Place the game cursor where you want to create the source (must be a flow-passable tile, and not too high in the sky) and call:

source add [magma|water] [0-7]

The number argument is the target liquid level (0 = drain, 7 = source).

To add more than 1 unit every time, call the command again on the same spot.

To delete one source, place the cursor over its tile and use source delete. To remove all existing sources, call source clear.

The list argument shows all existing sources.


source add water     - water source
source add magma 7   - magma source
source add water 0   - water drain


Provides a simpler interface to modtools/create-unit, for creating units.

Usage: spawnunit [-command] RACE CASTE [NAME] [x y z] [...]

The -command flag prints the generated modtools/create-unit command instead of running it. RACE and CASTE specify the race and caste of the unit to be created. The name and coordinates of the unit are optional. Any further arguments are simply passed on to modtools/create-unit.


Use before embarking (e.g. at the site selection screen or any time before) to change the number of dwarves you embark with from the default of 7.

  • startdwarf 10 would just allow a few more warm bodies to dig in
  • startdwarf 500 would lead to a severe food shortage and FPS issues

The number must be 7 or greater.


Somewhere between a “mod” and a “fps booster”, with a small impact on vanilla gameplay. It mostly helps prevent undead cascades in the caverns, where constant combat leads to hundreds of undead roaming the caverns and destroying your FPS.

With this script running, all undead that have been on the map for one month gradually decay, losing strength, speed, and toughness. After six months, they collapse upon themselves, never to be reanimated.

Usage: starvingdead (start|stop)


For dumping items inside cages. Will mark selected items for dumping, then a dwarf may come and actually dump them (or you can use autodump).


list:display the list of all cages and their item content on the console
items:dump items in the cage, excluding stuff worn by caged creatures
weapons:dump equipped weapons
armor:dump everything worn by caged creatures (including armor and clothing)
all:dump everything in the cage, on a creature or not

Without further arguments, all commands work on all cages and animal traps on the map. With the here argument, considers only the in-game selected cage (or the cage under the game cursor). To target only specific cages, you can alternatively pass cage IDs as arguments:

stripcaged weapons 25321 34228


Similar to fastdwarf, per-creature.

To make any creature superfast, target it ingame using ‘v’ and:

superdwarf add

Other options available: del, clear, list.

This script also shortens the ‘sleeping’ periods of targets.


Tame and train animals.

Usage: tame -read OR tame -set <level>

3:skillfully trained
4:expertly trained
5:exceptionally trained
6:masterfully trained


Teleports a unit to given coordinates.


gui/teleport is an in-game UI for this script.


  • prints ID of unit beneath cursor:

    teleport -showunitid
  • prints coordinates beneath cursor:

    teleport -showpos
  • teleports unit 1234 to 56,115,26

    teleport -unit 1234 -x 56 -y 115 -z 26


Toggle between all possible positions where the idlers count can be placed (see data/init/d_init.txt for details).


Controls the speed of the calendar and creatures. Fortress mode only. Experimental.

The script is also capable of dynamically speeding up the game based on your current FPS to mitigate the effects of FPS death. See examples below to see how.


timestream [-rate R] [-fps FPS] [-units [FLAG]] [-debug]


  • timestream -rate 2:
    Calendar runs at x2 normal speed, units run at normal speed
  • timestream -fps 100:
    Calendar runs at dynamic speed to simulate 100 FPS, units normal
  • timestream -fps 100 -units:
    Calendar & units are simulated at 100 FPS
  • timestream -rate 1:
    Resets everything back to normal, regardless of other arguments
  • timestream -rate 1 -fps 50 -units:
    Same as above
  • timestream -fps 100 -units 2:
    Activates a different mode for speeding up units, using the native DF debug_turbospeed flag (similar to fastdwarf 2) instead of adjusting timers of all units. This results in rubberbanding unit motion, so it is not recommended over the default method.

Original timestream.lua:


Print various properties of the selected item. Sometimes useful for troubleshooting issues such as why dwarves won’t pick up a certain item.


Toggle between displaying/not displaying liquid depth as numbers.

Keybinding: CtrlW


Undesignates building base materials for dumping.


Unforbids all items.


unforbid all [<options>]
unforbid help

<options> can be zero or more of:

-q, --quiet
Suppress non-error console output.


A wrapper around geld that ungelds the specified animal.

Valid options:

-unit <id>: Ungelds the unit with the specified ID.
This is optional; if not specified, the selected unit is used instead.

-help: Shows this help information


Prompt units to reevaluate their uniform, by removing/dropping potentially conflicting worn items.

Unlike a “replace clothing” designation, it won’t remove additional clothing if it’s coexisting with a uniform item already on that body part. It also won’t remove clothing (e.g. shoes, trousers) if the unit has yet to claim an armor item for that bodypart. (e.g. if you’re still manufacturing them.)

By default it simply prints info about the currently selected unit, to actually drop items, you need to provide it the -drop option.

The default algorithm assumes that there’s only one armor item assigned per body part, which means that it may miss cases where one piece of armor is blocked but the other is present. The -multi option can possibly get around this, but at the cost of ignoring left/right distinctions when dropping items.

In some cases, an assigned armor item can’t be put on because someone else is wearing/holding it. The -free option will cause the assigned item to be removed from the container/dwarven inventory and placed onto the ground, ready for pickup.

In no cases should the command cause a uniform item that is being properly worn to be removed/dropped.


(no target):Force the selected dwarf to put on their uniform.
-all:Force the uniform on all military dwarves.


(none):Simply show identified issues (dry-run).
-drop:Cause offending worn items to be placed on ground under unit.
-free:Remove to-equip items from containers or other’s inventories, and place on ground.
-multi:Be more agressive in removing items, best for when uniforms have muliple items per body part.


This script allows the user to play as any living (or undead) historical figure (except for deities) in adventure mode.

To use, simply enter “unretire-anyone” in the DFHack console at the start of adventure mode character creation. You will be presented with a searchable list from which you may choose your desired historical figure.

This figure will be added to the ‘Specific Person’ list at the bottom of the creature selection page. They can then be picked for use as a player character, as if regaining control of a retired adventurer.


Unsuspends building construction jobs, except for jobs managed by buildingplan and those where water flow > 1. See autounsuspend for keeping new jobs unsuspended.


A script to extend the item or unit viewscreen with additional information including a custom description of each item (when available), and properties such as material statistics, weapon attacks, armor effectiveness, and more.

The associated script item-descriptions supplies custom descriptions of items. Individual descriptions can be added or overridden by a similar script raw/scripts/more-item-descriptions.lua. Both work as sparse lists, so missing items simply go undescribed if not defined in the fallback.


Show combat reports for the current unit.

Current unit is unit near cursor in ‘v’, selected in ‘u’ list, unit/corpse/splatter at cursor in ‘k’. And newest unit with race when ‘k’ at race-specific blood spatter.

Keybinding: CtrlShiftR


If any (live) units are starving, very thirsty, or very drowsy, the game will be paused and a warning shown and logged to the console. If you only want to be warned about sane dwarves, use warn-starving sane.

Use with the repeat command for regular checks.

Use warn-starving all to display a list of all problematic units.


Will make a zoomable announcement whenever a creature that can eat food, guzzle drinks, or steal items enters the map and moves into a revealed location. Usage:

warn-stealers [start|stop]


Prints a map of the local weather, or with arguments clear, rain, and snow changes the weather.


workorder is a script to queue work orders as in j-m-q menu. It can automatically count how many creatures can be milked or sheared.

The most simple and obvious usage is automating shearing and milking of creatures using repeat:

repeat -time 14 -timeUnits days -command [ workorder ShearCreature ] -name autoShearCreature
repeat -time 14 -timeUnits days -command [ workorder MilkCreature ] -name autoMilkCreature

It is also possible to define complete work orders using json. It is very similar to what orders import filename does, with a few key differences. workorder is a planning tool aiming to provide scripting support for vanilla manager. As such it will ignore work order state like amount_left or is_active and can optionally take current orders into account. See description of <json>-parameter for more details.


  • workorder ShearCreature 10 add an order to “Shear Animal” 10 times.
  • workorder ShearCreature same, but calculate amount automatically (can be 0).
  • workorder MilkCreature same, but “Milk Animal”.

Advanced examples:

  • workorder "{\"job\":\"EncrustWithGems\",\"item_category\":[\"finished_goods\"],\"amount_total\":5}"
    add an order to EncrustWithGems finished_goods using any material (since not specified).
  • workorder "{\"job\":\"MilkCreature\",\"item_conditions\":[{\"condition\":\"AtLeast\",\"value\":2,\"flags\":[\"empty\"],\"item_type\":\"BUCKET\"}]}"
    same as workorder MilkCreature but with an item condition (“at least 2 empty buckets”).


workorder [ --<command> | <jobtype> [<amount>] | <json> | --file <file> ]

<command>:one of help, listtypes, verbose, very-verbose
--help this help.
--listtypes filter
 print all values for all used DF types (job_type, item_type etc.). <filter> is optional and is applied to type name (using Lua’s string.find), f.e. workorder -l "manager" is useful.

number or name from df.job_type.


optional number; if omitted, the script will try to determine amount automatically for some jobs. Currently supported are MilkCreature and ShearCreature jobs.


json-representation of a workorder. Must be a valid Lua string literal (see advanced examples: note usage of \). Use orders export some_file_name to get an idea how does the json-structure look like.

It’s important to note this script behaves differently compared to orders import some_file_name: workorder is meant as a planning tool and as such it will ignore some fields like amount_left, is_active or is_validated.

This script doesn’t need values in all fields:
  • id is only used for order conditions;
  • frequency is set to OneTime by default;
  • amount_total can be missing, a function name from this script (one of calcAmountFor_MilkCreature or calcAmountFor_ShearCreature) or Lua code called as load(code)(order, orders). Missing amount_total is equivalent to calcAmountFor_<order.job>.

A custom field __reduce_amount can be set if existing open orders should be taken into account reducing new order’s total_amount (possibly all the way to 0). An empty amount_total implies "__reduce_amount": true.

--file filename
 loads the json-representation of a workorder from a file in dfhack-config/workorder/.


--verbose toggle script’s verbosity.
--very-verbose toggle script’s very verbose mode.
--reset reset script environment for next execution.


Sets the status to Checking (from Active) of the selected work order (in the j-m or u-m screens). This makes the manager reevaluate its conditions.

Keybinding: AltR in jobmanagement/Main