# quickfort

Tags: fort | design | productivity | buildings | map | stockpiles

Command: `quickfort`

Apply pre-designed blueprints to your fort.

Quickfort reads blueprint files stored in the `blueprints` subfolder under the main DF game folder and applies the blueprint of your choice to the game map. You can apply blueprints that designate digging, build buildings, place stockpiles, mark zones, and/or configure settings. If you find yourself spending time doing similar or repetitive things in your forts, this tool can be an immense help.

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

You can create the blueprints by hand (see the Quickfort blueprint creation guide for details) or you can build your plan “for real” in Dwarf Fortress, and then export your map using gui/blueprint. This way you can effectively copy and paste sections of your fort if you need to.

There are many ready-to-use blueprints in the blueprint library that is distributed with DFHack, so you can use this tool productively even if you haven’t created any blueprints yourself.

## Usage

`quickfort list [-m|--mode <mode>] [-u|--useronly] [-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 (please see Quickfort blueprint creation guide for more information on modes). By default, blueprints in the `blueprints/library/` subfolder are included and blueprints that contain a `hidden()` 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 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_id>[,<list_id>...] [<options>]`

  Applies the blueprint(s) with the id number(s) reported 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>` 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 in the first sheet is used.

`quickfort set [<key> <value>]`

  Allows you to modify the global 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 `dfhack-config/quickfort/quickfort.txt`.

`<command>` is one of:

run:

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

orders:

  Uses the manager interface to queue up workorders to manufacture items needed by 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 and config blueprints since they can contain arbitrary key sequences that are not reversible.

## Examples

`quickfort gui library/aquifer_tap.csv -n /dig`

  Show the in-game preview for the “dig” blueprint in the `library/aquifer_tap.csv` file. You can interactively reposition the blueprint and apply it where you like (it’s intended to be applied in a light 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 happens to be the 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 2 z-levels). Also transform the blueprint by rotating counterclockwise and flipping vertically in order to fit the pump stack through some tricky-shaped caverns 50 z-levels above. Note that this kind of careful positioning is much easier to do with gui/quickfort, but it can be done via the commandline as well if you know exactly what transformations and positioning you need.

`quickfort orders 10,11,12 --dry-run`

  Process the blueprints with ids `10`, `11`, and `12` (run `quickfort list` to see which blueprints these are for you) and calculate what materials will be needed by your dwarves to actually complete the structures that the blueprints will designate. Display that list to the screen, but don’t actually enqueue the workorders (the `--dry-run` option prevents 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 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 you’re trying 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 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).

## Configuration

The quickfort script reads its global 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, and 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 reference, 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.

## API

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, available from the return value of `reqscript('quickfort)`:

- `quickfort.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 without shifting.

`aliases`

  A map of query blueprint aliases names to their expansions. If not specified, defaults to `{}`.

`preserve_engravings`

  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 the string `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='d(10x10)',
                              pos=guidm.getCursorPos()}

    -- dig a 10x10 block starting at coordinate x=30, y=40, z=50
    quickfort.apply_blueprint{mode='dig', data={[50]={[40]={[30]='d(10x10)'}}}}