quickfort — DFHack 50.13-r4 documentation (2024)

Quickfort reads stored blueprint files and applies them to the game map.You can apply blueprints that designate digging, build buildings, placestockpiles, mark zones, and more. If you find yourself spending time doingsimilar or repetitive designs in your forts, this tool can be an immense help.

Note that this is the commandline tool. Please see gui/quickfort if you’d likea graphical in-game UI for selecting, previewing, and applying blueprints.

You can create the blueprints by hand (see the Quickfort blueprint creation guide fordetails) or you can build your plan “for real” in Dwarf Fortress, and thenexport your map using gui/blueprint. This way you can effectively copy andpaste sections of your fort. Player-created blueprints are stored in thedfhack-config/blueprints directory.

There are many ready-to-use blueprints in theblueprint library that is distributed with DFHack,so you can use this tool productively even if you haven’t created any blueprintsyourself. Additional library blueprints can beadded with mods as well.

Usage¶

quickfort list [-m|--mode <mode>] [-u|--useronly] [-h|--hidden] [<search string>]: Lists available blueprints. Blueprints are .csv files or sheets within.xlsx files that contain a #<mode> comment in the upper-left cell(please see Quickfort blueprint creation guide for more information on modes). Bydefault, library blueprints are included and blueprints that contain ahidden() marker in their modeline are excluded from the returned list.Specify -u or -h to exclude library or include hidden blueprints,respectively. The list can additionally 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 reported list may not be contiguous ifthere are hidden or filtered blueprints that are not being shown.
quickfort delete <filename> [<filename> ...]: Delete the specified blueprint file(s). Only player-owned blueprints (storedin the dfhack-config/blueprints directory) can be deleted. Blueprintsprovided by mods or the standard DFHack library cannot be deleted by thiscommand.
quickfort gui [<filename or search terms>]: Invokes the quickfort UI with the specified parameters, giving you aninteractive blueprint preview to work with before you apply it to the map.See the gui/quickfort documentation for details.
quickfort <command>[,<command>...] <list_id>[,<list_id>...] [<options>]: Applies the blueprint(s) with the id number(s) reported from the listcommand.
quickfort <command>[,<command>...] <filename> [-n|--name <name>[,<name>...]] [<options>]: Applies a blueprint in the specified file. The optional name parametercan select a specific blueprint from a file that contains multipleblueprints with the format <sheetname>/<label> for .xlsx files, 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 inthe first sheet is used.
quickfort set [<key> <value>]: Allows you to modify the global quickfort configuration. Just runquickfort set to show current settings. See the Configuration sectionbelow for available keys and values.
quickfort reset: Resets quickfort configuration to defaults.

<command> is one of:

run:

Applies the blueprint at your current in-game cursor position.

Examples¶

quickfort gui library/aquifer_tap.csv -n /dig: Show the in-game preview for the “dig” blueprint in thelibrary/aquifer_tap.csv file. You can interactively reposition theblueprint and apply it where you like (it’s intended to be applied in alight aquifer layer – run the associated “help” blueprint for more info).
quickfort list: List all available blueprints.
quickfort list dreamfort help: List all the blueprints that have both “dreamfort” and “help” as keywords.
quickfort run library/dreamfort.csv: Run the first blueprint in the library/dreamfort.csv file (which happensto be the “notes” blueprint that displays the help).
quickfort run library/pump_stack.csv -n /dig --repeat up,80 --transform ccw,flipv: Dig a pump stack through 160 z-levels up from the current cursor location(each repetition of the library/pump_stack.csv -n /dig blueprint is 2z-levels). Also transform the blueprint by rotating counterclockwise andflipping vertically in order to fit the pump stack through sometricky-shaped caverns 50 z-levels above. Note that this kind of carefulpositioning is much easier to do interactively with gui/quickfort, but itcan be done via the commandline as well if you know exactly whattransformations and positioning you need.
quickfort orders 10,11,12 --dry-run: Process the blueprints with ids 10, 11, and 12 (runquickfort list to see which blueprints these are for you) and calculatewhat materials will be needed by your dwarves to actually complete thestructures that the blueprints will designate. Display that list to thescreen, but don’t actually enqueue the workorders (the --dry-run optionprevents actual changes to the game).

Command options¶

<options> can be zero or more of:

-c, --cursor <x>,<y>,<z>: Use the specified map coordinates instead of the current keyboard mapcursor for the the blueprint start position. If this option is specified,then an active keyboard map cursor is not necessary.
-d, --dry-run: Go through all the motions and print statistics on what would be done, butdon’t actually change any game state.
-m, --marker <type>[,<type>...]: Apply the given marker(s) to the tiles designated by the #dig blueprintthat you are applying. Valid marker types are: blueprint (designate butdon’t dig), warm (dig even if the tiles are warm), and damp (digeven if the tiles are damp). warm and damp markers are interpretedby the dig tool for interruption-free digging through warm and damp tiles.
-p, --priority <num>: Set the priority to the given number (1-7) for tiles designated by the#dig blueprint that you are applying. That is, tiles that normally havea priority of 4 will instead have the priority you specify. If theblueprint uses other explicit priorities, they will be shifted up or downaccordingly.
--preserve-engravings <quality>: Don’t designate tiles for digging/carving if they have an engraving with atleast the specified quality. Valid values for quality are: None,Ordinary, WellCrafted, FinelyCrafted, Superior,Exceptional, and Masterful. Specify None to ignore engravingswhen designating tiles. Note that if Masterful tiles are dug out, thedwarf who engraved the masterwork will get negative thoughts. If notspecified, 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 ofz-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 gamemap. See the Transformations section below for details.
-v, --verbose: Output extra debugging information. This is especially useful if you’retrying to figure out why the blueprint isn’t being applied like you expect.

Transformations¶

All transformations are anchored at the blueprint start cursor position. This isthe upper left corner by default, but it can be modified if the blueprint has astart() modeline marker. This means that the blueprint tilethat would normally appear under your cursor will still appear under yourcursor, 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).

Configuration¶

The quickfort script has a few global configuration options that you cancustomize with the quickfort set command. Modified settings are only keptfor the current session and will be reset when you restart DF.

blueprints_user_dir (default: dfhack-config/blueprints): Directory tree to search for player-created blueprints. It can be set to anabsolute or relative path. If set to a relative path, it resolves to adirectory under the DF folder. Note that if you change this directory, youwill not see blueprints written by the DFHack blueprint plugin (whichalways writes to the dfhack-config/blueprints dir).
blueprints_library_dir (default: hack/data/blueprints): Directory tree to search for library blueprints.
force_marker_mode (default: false): If true, will designate all dig blueprints in marker=blueprint mode. Iffalse, only cells with dig codes explicitly prefixed with mb in theblueprint cell will be designated in marker mode.
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 ofthe relevant types. Set to -1 for DF defaults (number of stockpile tilesfor stockpiles that take barrels and bins, and 1 wheelbarrow for stonestockpiles). The default here for wheelbarrows is 0 since usingwheelbarrows can decrease the efficiency of your fort unless you assignan appropriate number of wheelbarrows to the stockpile. Blueprints canoverride this value for specific stockpiles.

API¶

The quickfort script can be called programmatically by other scripts, either viathe commandline interface with dfhack.run_script() or via the API functionsdefined in quickfort.lua, available from the return value ofreqscript('quickfort):

quickfort.apply_blueprint(params)

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

params is a table with the following fields:

mode (required): The blueprint mode, e.g. dig, build, etc.
data (required): A sparse map populated such that data[z][y][x] yields the blueprint textthat should be applied to the tile at map coordinate (x, y, z). You canalso just pass a string instead of a table and it will be interpreted asthe value of data[0][0][0].
command: The quickfort command to execute, e.g. run, orders, etc. Defaults torun.
pos: A coordinate that serves as the reference point for the coordinates in thedata map. That is, the text at data[z][y][x] will be shifted to beapplied to coordinate (pos.x + x, pos.y + y, pos.z + z). If notspecified, defaults to {x=0, y=0, z=0}, which means that the coordinatesin the data map are used without shifting.
aliases: A map of blueprint alias names to their expansions. If not specified,defaults to {}.
marker: A map of strings to booleans indicating which markers should be applied tothis dig mode blueprint. See Command options above for details. Ifnot specified, defaults to {blueprint=false, warm=false, damp=false}.
priority: An integer between 1 and 7, inclusive, indicating the base priorityfor this dig blueprint. If not specified, defaults to 4.
preserve_engravings: Don’t designate tiles for digging or carving if they have an engraving withat least the specified quality. Value is a df.item_quality enum name orvalue, or the string None (or, equivalently, -1) to indicate that noengravings should be preserved. Defaults to df.item_quality.Masterful.
dry_run: Just calculate statistics, such as how many tiles are outside the boundariesof 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 quickfort = reqscript('quickfort')-- dig a 10x10 block at the mouse cursor positionquickfort.apply_blueprint{mode='dig', data='d(10x10)', pos=dfhack.gui.getMousePos()}-- dig a 10x10 block starting at coordinate x=30, y=40, z=50quickfort.apply_blueprint{mode='dig', data={[50]={[40]={[30]='d(10x10)'}}}}