Quickfort blueprint creation guide
==================================

Quickfort is a DFHack script that helps you build fortresses from "blueprint" .csv and .xlsx files. Many applications exist to edit these files, such as MS Excel and Google Sheets. Most layout and building-oriented DF commands are supported through the use of multiple files or spreadsheets, each describing a different phase of DF construction: designation, building, placing stockpiles/zones, and setting configuration.

The original idea came from Valdemar's auto-designation macro. Joel Thornton reimplemented the core logic in Python and extended its functionality with Quickfort 2.0. This DFHack-native implementation, called "DFHack Quickfort" or just "quickfort", builds upon Quickfort 2.0's formats and features. Any blueprint that worked in Python Quickfort 2.0 should work with DFHack Quickfort. DFHack Quickfort interacts with Dwarf Fortress memory structures directly, allowing for instantaneous blueprint application, error checking and recovery, and many other advanced features.

This guide focuses on DFHack Quickfort's capabilities and teaches players how to understand and create blueprint files. Some of the text was originally written by Joel Thornton, reused here with his permission.

For those just looking to apply existing blueprints, check out the quickfort command's documentation for syntax. There are also many ready-to-use blueprints available in the "blueprints/library" subfolder in your DFHack installation. Browse them on your computer or online, or run gui/quickfort to browse and apply them to your fort!

Before you become an expert at writing blueprints, though, you should know that the easiest way to make a quickfort blueprint is to build your plan "for real" in Dwarf Fortress and then export your map using the DFHack blueprint plugin. You can apply those blueprints as-is in your next fort, or you can fine-tune them with additional features from this guide.

See the Links section for more information and online resources.


Table of Contents
^^^^^^^^^^^^^^^^^

* Features

* Creating blueprints

  * Area expansion syntax

  * Automatic area expansion

  * Multilevel blueprints

  * Dig priorities

  * Marker mode

  * Stockpiles and zones

  * Minecart tracks

  * Modeline markers

  * Meta blueprints

  * Other blueprint modes

* Packaging a set of blueprints

* Buildingplan integration

* Generating manager orders

  * Extra Manager Orders

* Tips and tricks

* Caveats and limitations

* Dreamfort case study: a practical guide to advanced blueprint design

  * Dreamfort organization and packaging

  * The surface level: how to manage complexity

  * The farming level: fun with stockpiles

  * The industry level: when not to use aliases

  * The services level: handling multi-level dig blueprints

  * The guildhall level: avoiding smoothing issues

  * The beds levels: multi level meta blueprints

* Links


Features
--------

* General

  * Manages blueprints to handle all phases of DF construction

  * Supports .csv and multi-worksheet .xlsx blueprint files

  * Near-instant application, even for very large and complex blueprints

  * Blueprints can span multiple z-levels

  * You can package all blueprints and keystroke aliases needed for an entire fortress in a single file for easy sharing

  * "meta" blueprints that simplify the application of sequences of blueprints

  * Undo functionality for dig, build, place, and zone blueprints

  * Rotate blueprints or flip them around to your preference when you apply them to the map

  * Automatic cropping of blueprints so you don't get errors if the blueprint extends off the map

  * Can generate manager orders for everything required by a build blueprint

  * Includes a library of ready-to-use blueprints

  * Blueprint debugging features

* Dig mode

  * Supports all types of designations, including dumping/forbidding items and setting traffic settings

  * Supports setting dig priorities

  * Supports applying dig blueprints in marker mode

  * Handles carving arbitrarily complex minecart tracks, including tracks that cross other tracks

* Build mode

  * Fully integrated with DFHack buildingplan: you can place buildings before manufacturing building materials and you can use the buildingplan UI for setting materials preferences

  * Designate entire constructions in mid-air without having to wait for each tile to become supported

  * Automatic expansion of building footprints to their minimum dimensions, so only the center tile of a multi-tile building needs to be recorded in the blueprint

  * Tile occupancy and validity checking so, for example, buildings that cannot be placed on a target tile will be skipped instead of messing up the blueprint. Blueprints that are only partially applied for any reason (e.g. you need to dig out some more tiles) can be safely reapplied to build the remaining buildings.

  * Relaxed rules for farm plot and road placement: you can still place the building even if an invalid tile (e.g. stone tiles for farm plots) splits the designated area into two disconnected parts

  * Intelligent boundary detection for adjacent buildings of the same type (e.g. a 6x6 block of "wj" cells will be correctly split into 4 jeweler's workshops)

* Place and zone modes

  * Define stockpiles and zones of any shape, not just rectangles

  * Configurable numbers of bins, barrels and wheelbarrows assigned to created stockpiles

  * Automatic splitting of stockpiles and zones that exceed maximum dimension limits

  * Fully configurable zone settings, such as pit/pond and hospital supply counts

* Query mode

  * Send arbitrary keystroke sequences to the UI -- *anything* you can do through the UI is supported

  * Supports aliases to simplify frequent keystroke combos

  * Includes a library of pre-made and tested aliases to simplify most common tasks, such as configuring stockpiles for important item types or creating hauling routes for quantum stockpiles.

  * Supports expanding aliases in other aliases for easy management of common subsequences

  * Supports repeating key sequences a specified number of times

  * Skips sending keys when the cursor is over a tile that does not have a stockpile or building, so missing buildings won't desynchronize your blueprint

  * Instant halting of query blueprint application when keystroke errors are detected, such as when a mistake in a key sequence leaves us stuck in a submenu, to make query blueprints easier to debug


Creating blueprints
-------------------

We recommend using a spreadsheet editor such as Excel, Google Sheets, or LibreOffice to edit blueprint files, but any text editor will do.

The format of Quickfort-compatible blueprint files is straightforward. The first line (or upper-left cell) of the spreadsheet should look like this:

   #dig

The keyword "dig" tells Quickfort we are going to be using the Designations menu in DF. The following "mode" keywords are understood:

+----------------+------------------------------------------+
| Blueprint mode | Description                              |
|================|==========================================|
| dig            | Designations menu ("d")                  |
+----------------+------------------------------------------+
| build          | Build menu ("b")                         |
+----------------+------------------------------------------+
| place          | Place stockpiles menu ("p")              |
+----------------+------------------------------------------+
| zone           | Activity zones menu ("i")                |
+----------------+------------------------------------------+
| query          | Set building tasks/prefs menu ("q")      |
+----------------+------------------------------------------+

If no modeline appears in the first cell, Quickfort assumes that it's looking at a "#dig" blueprint.

There are also other modes that don't directly correspond to Dwarf Fortress menus, but we'll talk about those later.

If you like, you may enter a comment after the mode keyword. This comment will appear in the output of "quickfort list" when run from the "DFHack#" prompt or in the dialog window when running gui/quickfort. You can use this space for explanations, attribution, etc.:

   #dig grand dining room

Below this line, begin entering keys in each spreadsheet cell that represent what you want designated in the corresponding game map tile. For example, we could dig out a 4x4 room like so (spaces are used as column separators here for readability, but a real .csv file would have commas):

   #dig
   d d d d #
   d d d d #
   d d d d #
   d d d d #
   # # # # #

Note the "#" symbols at the right end of each row and below the last row. These are completely optional, but can be helpful to make the row and column positions clear.

Once the dwarves have that dug out, let's build a walled-in bedroom within our dug-out area:

   #build
   Cw Cw Cw Cw #
   Cw b  h  Cw #
   Cw       Cw #
   Cw Cw    Cw #
   #  #  #  #  #

Note my generosity -- in addition to the bed ("b") I've built a chest ("c") here for the dwarf as well. You must use the full series of keys needed to build something in each cell, e.g. "C""w" indicates we should enter DF's constructions submenu ("C") and select walls ("w").

I'd also like to place a booze stockpile in the 2 unoccupied tiles in the room:

   #place Place a food stockpile
   ` ` ` ` #
   ` ~ ~ ` #
   ` f f ` #
   ` `   ` #
   # # # # #

This illustration may be a little hard to understand. The two "f" characters are in row 3, columns 2 and 3. All the other cells are empty. QF considers both "`" (backtick -- the character under the tilde) and "~" (tilde) characters within cells to be empty cells; this can help with multilayer or fortress-wide blueprint layouts as "chalk lines".

QF is smart enough to recognize this as a 2x1 food stockpile, and creates it as such rather than as two 1x1 food stockpiles. Quickfort treats any connected region of identical designations as a single entity. The tiles can be connected orthogonally or diagonally, just as long as they are touching.

Lastly, let's turn the bed into a bedroom and set the food stockpile to hold only booze.

   #query
   ` ` ` ` #
   ` r&  ` #
   ` booze #
   ` ` ` ` #
   # # # # #

In row 2, column 2 we have "r&". This sends the "r" key to DF when the cursor is over the bed, causing us to "make room" and "Enter", represented by special "&" alias, to indicate that we're done setting the size (the default room size is fine here).

In column 2, row 3 we have "booze". This is one of many alias keywords defined in the included aliases library. This particular alias sets a food stockpile to accept only booze. It sends the keys needed to navigate DF's stockpile settings menu, and then it sends an Escape character to exit back to the map. It is important to exit out of any menus that you enter while in query mode so that the cursor can move to the next tile when it is done with the current tile.

If there weren't an alias named "booze" then the literal characters "b""o""o""z""e" would have been sent, so be sure to spell those aliases correctly!

You can save a lot of time and effort by using aliases instead of adding all key sequences directly to your blueprints. For more details, check out the Quickfort keystroke alias reference. You can also see examples of aliases being used in the query blueprints in the DFHack blueprint library. You can create your own aliases by adding them to dfhack-config/quickfort/aliases.txt in your DFHack folder or you can package them together with your blueprint files.


Area expansion syntax
~~~~~~~~~~~~~~~~~~~~~

In Quickfort, the following blueprints are equivalent:

   #dig a 3x3 area
   d d d #
   d d d #
   d d d #
   # # # #

   #dig the same area with d(3x3) specified in row 1, col 1
   d(3x3)#
   ` ` ` #
   ` ` ` #
   # # # #

The second example uses Quickfort's "area expansion syntax", which takes the form:

   keys(WxH)

Note that area expansion syntax can only specify rectangular areas. If you want to create extent-based structures (e.g. farm plots or stockpiles) in different shapes, use the first format above. For example:

   #place A single L shaped food stockpile
   f f ` ` #
   f f ` ` #
   f f f f #
   f f f f #
   # # # # #

Area expansion syntax also sets boundaries, which can be useful if you want adjacent, but separate, stockpiles of the same type:

   #place Two touching but separate food stockpiles
   f(2x2)  #
   ~ ~ ` ` #
   f(4x2)  #
   ~ ~ ~ ~ #
   # # # # #

As mentioned previously, "~" characters are ignored as comment characters and can be used for visualizing the blueprint layout. This blueprint can be equivalently written as:

   #place Two touching but separate food stockpiles
   f(2x2)  #
   ~ ~ ` ` #
   f f f f #
   f f f f #
   # # # # #

since the area expansion syntax of the upper stockpile prevents it from combining with the lower, freeform syntax stockpile.

Area expansion syntax can also be used for buildings which have an adjustable size, like bridges. The following blueprints are equivalent:

   #build a 4x2 bridge from row 1, col 1
   ga(4x2)  `  #
   `  `  `  `  #
   #  #  #  #  #

   #build a 4x2 bridge from row 1, col 1
   ga ga ga ga #
   ga ga ga ga #
   #  #  #  #  #

If it is convenient to do so, you can place the cell with the expansion syntax in any corner of the resulting rectangle. Just use negative numbers to indicate which direction the designation should expand in. For example, the previous blueprint could also be written as:

   #build a 4x2 bridge from row 2, col 4
   `  `  `  `  #
   ga(4x-2) `  #
   #  #  #  #  #


Automatic area expansion
~~~~~~~~~~~~~~~~~~~~~~~~

Buildings larger than 1x1, like workshops, can be represented in any of three ways. You can designate just their center tile with empty cells around it to leave room for the footprint, like this:

   #build a mason workshop in row 2, col 2 that will occupy the 3x3 area
   ` `  ` #
   ` wm ` #
   ` `  ` #
   # #  # #

Or you can fill out the entire footprint like this:

   #build a mason workshop
   wm wm wm #
   wm wm wm #
   wm wm wm #
   #  #  #  #

This format may be verbose for regular workshops, but it can be very helpful for laying out structures like screw pump towers and waterwheels, whose "center point" can be non-obvious.

Or you can use area expansion syntax:

   #build a mason workshop
   wm(3x3)  #
   `  `  `  #
   `  `  `  #
   #  #  #  #

This style can be convenient for laying out multiple buildings of the same type. If you are building a large-scale block factory, for example, this will create 20 mason workshops all in a row:

   #build line of 20 mason workshops
   wm(60x3)

Quickfort will intelligently break large areas of the same designation into appropriately-sized chunks.


Multilevel blueprints
~~~~~~~~~~~~~~~~~~~~~

Multilevel blueprints are accommodated by separating Z-levels of the blueprint with "#>" (go down one z-level) or "#<" (go up one z-level) at the end of each floor.

   #dig Stairs leading down to a small room below
   j  `  `  #
   `  `  `  #
   `  `  `  #
   #> #  #  #
   u  d  d  #
   d  d  d  #
   d  d  d  #
   #  #  #  #

The marker must appear in the first column of the row to be recognized, just like a modeline.

You can go up or down multiple levels by adding a number after the "<" or ">". For example:

   #dig Two double-level quarries
   r(10x10)
   #>2
   r(10x10)


Dig priorities
~~~~~~~~~~~~~~

DF designation priorities are supported for "#dig" blueprints. The full syntax is "[letter][number][expansion]", where if the "letter" is not specified, "d" is assumed, and if "number" is not specified, "4" is assumed (the default priority). So each of these blueprints is equivalent:

   #dig dig the interior of the room at high priority
   d  d  d  d  d  #
   d  d1 d1 d1 d  #
   d  d1 d1 d1 d  #
   d  d1 d1 d1 d  #
   d  d  d  d  d  #
   #  #  #  #  #  #

   #dig dig the interior of the room at high priority
   d  d  d  d  d  #
   d  d1(3x3)  d  #
   d  `  `  `  d  #
   d  `  `  `  d  #
   d  d  d  d  d  #
   #  #  #  #  #  #

   #dig dig the interior of the room at high priority
   4  4  4  4  4  #
   4  1  1  1  4  #
   4  1  1  1  4  #
   4  1  1  1  4  #
   4  4  4  4  4  #
   #  #  #  #  #  #


Marker mode
~~~~~~~~~~~

Marker mode is useful for when you want to plan out your digging, but you don't want to dig everything just yet. In "#dig" mode, you can add a "m" before any other designation letter to indicate that the tile should be designated in marker mode. For example, to dig out the perimeter of a room, but leave the center of the room marked for digging later:

   #dig
   d  d  d  d d #
   d md md md d #
   d md md md d #
   d md md md d #
   d  d  d  d d #
   #  #  #  # # #

Then you can use "Toggle Standard/Marking" ("d""M") to convert the center tiles to regular designations at your leisure.

To apply an entire dig blueprint in marker mode, regardless of what the blueprint itself says, you can set the global quickfort setting "force_marker_mode" to "true" before you apply the blueprint.

Note that the in-game UI setting "Standard/Marker Only" ("d""m") does not have any effect on quickfort.


Stockpiles and zones
~~~~~~~~~~~~~~~~~~~~

It is very common to have stockpiles that accept multiple categories of items or zones that permit more than one activity. Although it is perfectly valid to declare a single-purpose stockpile or zone and then modify it with a "#query" blueprint, quickfort also supports directly declaring all the types in the "#place" and "#zone" blueprints. For example, to declare a 20x10 stockpile that accepts both corpses and refuse, you could write:

   #place refuse heap
   yr(20x10)

And similarly, to declare a zone that is a pasture, a fruit picking area, and a meeting area all at once:

   #zone main pasture and picnic area
   nmg(10x10)

The order of the individual letters doesn't matter. If you want to configure the stockpile from scratch in a "#query" blueprint, you can place unconfigured "custom" stockpiles with ("c"). It is more efficient, though, to place stockpiles using the keys that represent the categories of items that you want to store, and then only use a "#query" blueprint if you need fine-grained customization.


Stockpile bins, barrels, and wheelbarrows
`````````````````````````````````````````

Quickfort has global settings for default values for the number of bins, barrels, and wheelbarrows assigned to stockpiles, but these numbers can be set for individual stockpiles as well.

To set the number of bins, barrels, or wheelbarrows, just add a number after the letter that indicates what type of stockpile it is. For example:

   #place a stone stockpile with 5 wheelbarrows
   s5(3x3)

   #place a bar, ammo, weapon, and armor stockpile with 20 bins
   bzpd20(5x5)

If the specified number exceeds the number of available stockpile tiles, the number of available tiles is used. For wheelbarrows, that limit is reduced by 1 to ensure there is at least one non-wheelbarrow tile available in the stockpile. Otherwise no stone would ever be brought to the stockpile since all tiles would be occupied by wheelbarrows!

Quickfort figures out which container type is being set by looking at the letter that comes just before the number. For example "zf10" means 10 barrels in a stockpile that accepts both ammo and food, whereas "z10f" means 10 bins. If the stockpile category doesn't usually use any container type, like refuse or corpses, wheelbarrows are assumed:

   #place a corpse stockpile with 3 wheelbarrows
   y3(3x3)

Note that if you are not using expansion syntax, each tile of the stockpile must have the same text. Otherwise the stockpile boundaries will not be detected properly:

   #place a non-rectangular animal stockpile with 5 wheelbarrows
   a5,a5,a5,a5
   a5,  ,  ,a5
   a5,  ,  ,a5
   a5,a5,a5,a5

Running "quickfort orders" on a "#place" blueprint with explicitly set container/wheelbarrow counts will enqueue manager orders for the specified number of containers or wheelbarrows, even if that number exceeds the in-game size of the stockpile. For example, "quickfort orders" on the following blueprint will enqueue 10 rock pots, even though the stockpile only has 9 tiles:

   #place
   f10(3x3)


Zone detailed configuration
```````````````````````````

Detailed configuration for zones, such as the pit/pond toggle, can also be set by mimicking the hotkeys used to set them. Note that gather flags default to true, so specifying them in a blueprint will turn the toggles off. If you need to set configuration from multiple zone subscreens, separate the key sections with "^". Note the special syntax for setting hospital supply levels, which have no in-game hotkeys:

   #zone a combination hospital and shrub (but not fruit) gathering zone
   gGtf^hH{hospital buckets=5 splints=20}(10x10)

The valid hospital settings (and their maximum values) are:

   thread   (1500000)
   cloth    (1000000)
   splints  (100)
   crutches (100)
   plaster  (15000)
   buckets  (100)
   soap     (15000)

To toggle the "active" flag for zones, add an "a" character to the string. For example, to create a *disabled* pond zone (that you later intend to carefully fill with 3-depth water for a dwarven bathtub):

   #zone disabled pond zone
   apPf(1x3)


Minecart tracks
~~~~~~~~~~~~~~~

There are two ways to produce minecart tracks, and they are handled very differently by the game. You can carve them into hard natural floors or you can construct them out of building materials. Constructed tracks are conceptually simpler, so we'll start with them.


Constructed tracks
``````````````````

Quickfort supports the designation of track stops and rollers in "#build" blueprints. You can build a track stop with "C""S" and some number of "d" and "a" characters for selecting dump direction and friction. You can build a roller with "M""r" and some number of "s" and "q" characters for direction and speed. However, this can get confusing very quickly and is very difficult to read in a blueprint. Moreover, constructed track segments don't even have keys associated with them at all!

To solve this problem, Quickfort provides the following keywords for use in build blueprints:

   -- Track segments --
   trackN
   trackS
   trackE
   trackW
   trackNS
   trackNE
   trackNW
   trackSE
   trackSW
   trackEW
   trackNSE
   trackNSW
   trackNEW
   trackSEW
   trackNSEW

   -- Track/ramp segments --
   trackrampN
   trackrampS
   trackrampE
   trackrampW
   trackrampNS
   trackrampNE
   trackrampNW
   trackrampSE
   trackrampSW
   trackrampEW
   trackrampNSE
   trackrampNSW
   trackrampNEW
   trackrampSEW
   trackrampNSEW

   -- Horizontal and vertical roller segments --
   rollerH
   rollerV
   rollerNS
   rollerSN
   rollerEW
   rollerWE

   Note: append up to four 'q' characters to roller keywords to set roller
   speed. E.g. a roller that propels from East to West at the slowest speed can
   be specified with 'rollerEWqqqq'.

   -- Track stops that (optionally) dump to the N/S/E/W --
   trackstop
   trackstopN
   trackstopS
   trackstopE
   trackstopW

   Note: append up to four 'a' characters to trackstop keywords to set friction
   amount. E.g. a stop that applies the smallest amount of friction can be
   specified with 'trackstopaaaa'.

As an example, you can create an E-W track with stops at each end that dump to their outside directions with the following blueprint:

   #build Example track
   trackstopW trackEW trackEW trackEW trackstopE

Note that the **only** way to build track and track/ramp segments is with the keywords. The UI method of using "+" and "-" keys to select the track type from a list does not work since DFHack Quickfort doesn't actually send keys to the UI to build buildings. The text in your spreadsheet cells is mapped directly onto DFHack API calls. Only "#query" blueprints send actual keycodes to the UI.


Carved tracks
`````````````

In the game, you carve a minecart track by specifying a beginning and ending tile and the game "adds" the designation to the tiles in between. You cannot designate single tiles because DF needs a multi-tile track to figure out which direction the track should go on each tile. For example to carve two track segments that cross each other, you might use the cursor to designate a line of three vertical tiles like this:

   ` start here ` #
   ` `          ` #
   ` end here   ` #
   # #          # #

Then to carve the cross, you'd do a horizontal segment:

   `          ` `        #
   start here ` end here #
   `          ` `        #
   #          # #        #

This will result in a carved track that would be equivalent to a constructed track of the form:

   #build
   `      trackS    `      #
   trackE trackNSEW trackW #
   `      trackN    `      #
   #      #         #      #

Quickfort supports both styles of specification for carving tracks with "#dig" blueprints. You can use the "additive" style to carve tracks in segments or you can use the aliases to specify the track tile by tile. To designate track segments, use area expansion syntax with a height or width of 1:

   #dig
   `      T(1x3) ` #
   T(3x1) `      ` #
   `      `      ` #
   #      #      # #

"But wait!", I can hear you say, "How do you designate a track corner that opens to the South and East? You can't put both T(1xH) and T(Wx1) in the same cell!" This is true, but you can specify both width and height greater than 1, and for tracks, QF interprets it as an upper-left corner extending to the right W tiles and down H tiles. For example, to carve a track in a closed ring, you'd write:

   #dig
   T(3x3) ` T(1x3) #
   `      ` `      #
   T(3x1) ` `      #
   #      # #      #

You can also use negative numbers in the expansion syntax to indicate corners that are not upper-left corners. This blueprint will also carve a closed ring:

   #dig
   T(3x3) ` `        #
   `      ` `        #
   `      ` T(-3x-3) #
   #      # #        #

Or you could use the aliases to specify tile by tile:

   #dig
   trackSE trackEW trackSW #
   trackNS `       trackNS #
   trackNE trackEW trackNW #
   #       #       #       #

The aliases can also be used to designate a solid block of track. This is especially useful for obliterating low-quality engravings so you can re-smooth and re-engrave with higher quality. For example, you could use the following sequence of blueprints to ensure a 10x10 floor area contains only masterwork engravings:

   #dig smooth floor
   s(10x10)
   #dig engrave floor
   e(10x10)
   #dig erase low-quality engravings
   trackNSEW(10x10)

The tracks only remove low-quality engravings since quickfort won't designate masterwork engravings for destruction (unless forced to by a commandline parameter). You would run (and let your dwarves complete the jobs for) the sequence of blueprints until no tiles are designated by the "erase" blueprint.


Modeline markers
~~~~~~~~~~~~~~~~

The modeline has some additional optional components that we haven't talked about yet. You can:

* give a blueprint a label by adding a "label()" marker

* set a cursor offset and/or cursor placement hint by adding a "start()" marker

* hide a blueprint from being listed with a "hidden()" marker

* register a message to be displayed after the blueprint is successfully applied with a "message()" marker

The full modeline syntax, when all optional elements are specified, is:

   #mode label(mylabel) start(X;Y;STARTCOMMENT) hidden() message(mymessage) comment

Note that all elements are optional except for the initial "#mode" (though, as mentioned in the first section, if a modeline doesn't appear at all in the first cell of a spreadsheet, the blueprint is interpreted as a "#dig" blueprint with no optional markers). Here are a few examples of modelines with optional elements before we discuss them in more detail:

   #dig start(3; 3; Center tile of a 5-tile square) Regular blueprint comment
   #build label(noblebedroom) start(10;15)
   #query label(configstockpiles) No explicit 'start()' means cursor is at upper left corner
   #meta label(digwholefort) start(center of stairs on surface)
   #dig label(digdining) hidden() called by the digwholefort meta blueprint
   #zone label(pastures) message(remember to assign animals to the new pastures)


Blueprint labels
````````````````

Labels are displayed in the "quickfort list" output and are used for addressing specific blueprints when there are multiple blueprints in a single file or spreadsheet sheet (see Packaging a set of blueprints below). If a blueprint has no label, the label becomes the ordinal of the blueprint's position in the file or sheet. For example, the label of the first blueprint will be "1" if it is not otherwise set, the label of the second blueprint will be "2" if it is not otherwise set, etc. Labels that are explicitly defined must start with a letter to ensure the auto-generated labels don't conflict with user-defined labels.


Start positions
```````````````

Start positions specify a cursor offset for a particular blueprint, simplifying the task of blueprint alignment. This is very helpful for blueprints that are based on a central staircase, but it comes in handy whenever a blueprint has an obvious "center". For example:

   #build start(2;2;center of workshop) label(masonw) a mason workshop
   wm wm wm #
   wm wm wm #
   wm wm wm #
   #  #  #  #

will build the workshop *centered* on the cursor, not down and to the right of the cursor.

The two numbers specify the column and row (or 1-based X and Y offset) where the cursor is expected to be when you apply the blueprint. Position "1;1" is the top left cell. The optional comment will show up in the "quickfort list" output and should contain information about where to position the cursor. If the start position is "1;1", you can omit the numbers and just add a comment describing where to put the cursor. This is also useful for meta blueprints that don't actually care where the cursor is, but that refer to other blueprints that have fully-specified "start()" markers. For example, a meta blueprint that refers to the "masonw" blueprint above could look like this:

   #meta start(center of workshop) a mason workshop
   /masonw

You can use semicolons, commas, or spaces to separate the elements of the "start()" marker, whatever is most convenient.


Hiding blueprints
`````````````````

A blueprint with a "hidden()" marker won't appear in "quickfort list" output unless the "--hidden" flag is specified. The primary reason for hiding a blueprint (rather than, say, deleting it or moving it out of the "blueprints/" folder) is if a blueprint is intended to be run as part of a larger sequence managed by a meta blueprint.


Messages
````````

A blueprint with a "message()" marker will display a message after the blueprint is applied with "quickfort run". This is useful for reminding players to take manual steps that cannot be automated, like assigning minecarts to a route, or listing the next step in a series of blueprints. For long or multi-part messages, you can embed newlines:

   "#meta label(surface1) message(This would be a good time to start digging the industry level.
   Once the area is clear, continue with /surface2.) clear the embark site and set up pastures"

The quotes surrounding the cell text are only necessary if you are writing a .csv file by hand. Spreadsheet applications will surround multi-line text with quotes automatically when they save/export the file.


Meta blueprints
~~~~~~~~~~~~~~~

Meta blueprints are blueprints that control how other blueprints are applied. For example, meta blueprints can bundle a group of other blueprints so that they can be run with a single command. They can also encode logic, like rotating the blueprint or duplicating it across a specified number of z-levels.

A common scenario where meta blueprints are useful is when you have several phases to link together. For example you might:

1. Apply a dig blueprint to designate dig areas

2. Wait for miners to dig

3. **Apply a build buildprint** to designate buildings

4. **Apply a place buildprint** to designate stockpiles

5. **Apply a query blueprint** to configure stockpiles

6. Wait for buildings to get built

7. Apply a different query blueprint to configure rooms

Those three "apply"s in the middle might as well get done in one command instead of three. A "#meta" blueprint can help with that. A meta blueprint refers to other blueprints in the same file by their label (see the Modeline markers section above) in the same format used by the quickfort command: "<sheet name>/<label>", or just "/<label>" for blueprints in .csv files or blueprints in the same spreadsheet sheet as the "#meta" blueprint that references them.

A few examples might make this clearer. Say you have a .csv file with blueprints that prepare bedrooms for your dwarves:

   #dig label(bed1) dig out the rooms
   ...
   #build label(bed2) build the furniture
   ...
   #place label(bed3) add food stockpiles
   ...
   #query label(bed4) configure stockpiles
   ...
   #query label(bed5) set the built beds as rooms
   ...

Note how I've given them all labels so we can address them safely. If I hadn't given them labels, they would receive default labels of "1", "2", "3", etc, but those labels would change if I ever add more blueprints at the top. This is not a problem if we're just running the blueprints individually from the "quickfort list" command, but meta blueprints need a label name that isn't going to change over time.

So let's add a meta blueprint to this file that will combine the middle three blueprints into one:

   "#meta label(bed234) combines build, place, and stockpile config blueprints"
   /bed2
   /bed3
   /bed4

Now your sequence is shortened to:

1. Run /bed1 to designate dig areas

2. Wait for miners to dig

3. **Run /bed234 meta buildprint** to build buildings and designate/configure stockpiles

4. Wait for buildings to get built

5. Run /bed5 to configure the rooms as bedrooms

You can use meta blueprints to lay out your fortress at a larger scale as well. The "#<" and "#>" notation is valid in meta blueprints, so you can, for example, store the dig blueprints for all the levels of your fortress in different sheets in a spreadsheet, and then use a meta blueprint to designate your entire fortress for digging at once. For example, say you have a .xlsx spreadsheet with the following layout:

+---------------+-------------------------------------------------------+
| Sheet name    | Contents                                              |
|===============|=======================================================|
| dig_farming   | one #dig blueprint, no label                          |
+---------------+-------------------------------------------------------+
| dig_industry  | one #dig blueprint, no label                          |
+---------------+-------------------------------------------------------+
| dig_dining    | four #dig blueprints, with labels "main", "basement", |
|               | "waterway", and "cistern"                             |
+---------------+-------------------------------------------------------+
| dig_guildhall | one #dig blueprint, no label                          |
+---------------+-------------------------------------------------------+
| dig_suites    | one #dig blueprint, no label                          |
+---------------+-------------------------------------------------------+
| dig_bedrooms  | one #dig blueprint, no label                          |
+---------------+-------------------------------------------------------+

We can add a sheet named "dig_all" with the following contents (we're expecting a big fort, so we're digging 5 levels of bedrooms):

   #meta dig the whole fortress
   dig_farming/1
   #>
   dig_industry/1
   #>
   dig_dining/main
   #>
   dig_dining/basement
   #>
   dig_dining/waterway
   #>
   dig_dining/cistern
   #>
   dig_guildhall/1
   #>
   dig_suites/1
   #>
   dig_bedrooms/1 repeat(down 5)

Note that for blueprints without an explicit label, we still need to address them by their auto-generated numeric label.

The command to run the meta blueprint above would be:

   quickfort run myfort.xlsx -n dig_all

It's worth repeating that "#meta" blueprints can only refer to blueprints that are defined in the same file. This means that all blueprints that a meta blueprint needs to run must be in sheets within the same .xlsx spreadsheet or concatenated into the same .csv file.

You can then hide the blueprints that you now manage with the meta blueprint from "quickfort list" by adding a "hidden()" marker to their modelines. That way the output of "quickfort list" won't be cluttered by blueprints that you don't need to run directly. If you ever *do* need to access the meta-managed blueprints individually, you can still see them with "quickfort list --hidden".


Meta markers
````````````

In meta blueprints, you can tag referenced blueprints with markers to modify how they are applied. These markers are similar to Modeline markers, but are only usable in meta blueprints. Here's a quick list of examples, with more details below:

+---------------------+------------------------------------------------------------+
| Example             | Description                                                |
|=====================|============================================================|
| repeat(down 10)     | Repeats a blueprint down z-levels 10 times                 |
+---------------------+------------------------------------------------------------+
| shift(0 10)         | Adds 10 to the y coordinate of each blueprint tile         |
+---------------------+------------------------------------------------------------+
| transform(cw flipv) | Rotates a blueprint clockwise and then flips it vertically |
+---------------------+------------------------------------------------------------+

**Repeating blueprints**

Syntax: repeat(<direction>[, ]<number>)

The direction can be "up" or "down", and the repetition works even for blueprints that are themselves multi-level. For example:

   #meta label(2beds) dig 2 levels of bedrooms
   dig_bedrooms/1 repeat(down 2)

   #meta label(6beds) dig 6 levels of bedrooms
   /2beds repeat(down 3)

You can use "<" and ">" for short, instead of "up" and "down". The comma or space between the direction and the number is optional as well. The following lines are all equivalent:

   /2beds repeat(down 3)
   /2beds repeat(down, 3)
   /2beds repeat(>3)

**Shifting blueprints**

Syntax: shift(<x shift>[[,] <y shift>])

The values can be positive or negative. Negative values for x shift to the left, positive to the right. Negative values for y shift up, positive down. Note the semantics for the y axis are opposite compared to regular graphs on paper. This is because the y coordinates in the DF game map start a 0 at the top and increase as they go down.

**Transforming blueprints**

Syntax: transform(<transformation>[[,] <transformation>...])

Applies a geometric transformation to the blueprint. The supported transformations are:

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

If you specify more than one transformation, they will be applied in the order they appear in.

If you use both "shift()" and "transform()" markers on the same blueprint, shifting is applied after all transformations are complete. If you want shifting to be applied before the transformations, or in between transformations, you can use nested meta blueprints. For example, the following blueprint will shift the "/hallway" blueprint to the right by 20 units and then rotate it clockwise:

   #meta label(shift_right) hidden()
   /hallway shift(20)
   #meta label(rotate_after_shift)
   /shift_right transform(cw)

Transforming build blueprints will also change the properties of buildings that care about direction. For example, a bridge that opens to the North, rotated clockwise, will open to the East when applied to the map.

Direction keys that move the cursor on the map will also be transformed. For example, the keys "g{Up 4}&" that would cause a stockpile to give to a workshop 4 tiles to the North become "g{Right 4}&" when played back on a clockwise-rotated "#query" blueprint. Direction keys that don't move the map cursor, for example when on the stockpile configuration screen, are not changed by blueprint rotation.


Other blueprint modes
~~~~~~~~~~~~~~~~~~~~~

In addition to the powerful "#meta" mode described above, there are a few additional blueprint modes that become useful when you are sharing your blueprints with others or managing complex blueprint sets. Instead of mapping tile positions to map modifications like the basic modes do, these "blueprints" have specialized, higher-level uses:

+----------------+----------------------------------------------------------------+
| Blueprint mode | Description                                                    |
|================|================================================================|
| config         | Play back key sequences that are not related to map tiles      |
+----------------+----------------------------------------------------------------+
| notes          | Display long messages, such as help text or blueprint          |
|                | walkthroughs                                                   |
+----------------+----------------------------------------------------------------+
| aliases        | Define aliases that can be used by other "#query" blueprints   |
|                | in the same file                                               |
+----------------+----------------------------------------------------------------+
| ignore         | Hide a section of your spreadsheet from quickfort, useful for  |
|                | scratch space or personal notes                                |
+----------------+----------------------------------------------------------------+


Config blueprints
`````````````````

A "#config" blueprint is used to send unfiltered keystrokes directly to the DF UI without interacting with specific map tiles. They have access to the same keystroke aliases as "#query" blueprints, but "#config" blueprints differ from "#query" blueprints in a few critical ways:

* Whereas the "home" mode for "#query" blueprints is the "query" mode ("q"), "#config" blueprints start on the default map screen -- the view you have when you're looking at the map with no sidebar visible. The keystroke or alias sequence in each spreadsheet cell in a "#config" blueprint must begin and end on the default map screen.

* The cursor position is not set for "#config" blueprints. This means that it doesn't matter what spreadsheet cell you put your text in. The blueprint cell location does not correspond to a map tile.

A "#config" blueprint is best used for accessing game menus that are not associated with map tiles, such as the hotkey menu ("H"), the military menu ("m"), or the standing orders menu ("o"). In other words, use a "#config" blueprint when you want to configure the game itself, not the tiles on the map. A "#config" blueprint is better for these menus than a "#query" blueprint because the cursor can jump around in unpredictable ways when accessing these non-cursor modes and then re-entering query mode. This will cause quickfort to detect a "#query" blueprint error and stop executing. Also, "#query" blueprints will skip playing back a key sequence entirely if it doesn't detect a building or zone on the target tile. A "#config" blueprint doesn't need a building or zone to exist in order to run.

Note that you *can* enter any mode you want during a "#config" blueprint keystroke sequence (as long as you get back to the default map screen by the end of the sequence), even modes that provide a cursor on the screen. It's just that the position of that cursor is not guaranteed to be on any specific tile. If you need access to a cursor, you probably should be using a "#query" blueprint instead.


Notes blueprints
````````````````

Sometimes you just want to record some information about your blueprints, such as when to apply them, what preparations you need to make, or what the blueprints contain. The message() modeline marker is useful for small, single-line messages, but a "#notes" blueprint is more convenient for long messages or messages that span many lines. The lines in a "#notes" blueprint are output as if they were contained within one large multi-line "message()" marker. For example, the following (empty) "#meta" blueprint:

   "#meta label(help) message(This is the help text for the blueprint set
   contained in this file.

   First, make sure that you embark in...) blueprint set walkthrough"

could more naturally be written as a "#notes" blueprint:

   #notes label(help) blueprint set walkthrough
   This is the help text for the blueprint set
   contained in this file

   First, make sure that you embark in...

The "#meta" blueprint is all squashed into a single spreadsheet cell, using embedded newlines. Each line of the "#notes" "blueprint", however, is in a separate cell, allowing for much easier viewing and editing.


Aliases blueprints
``````````````````

There are keystroke aliases that come with DFHack that are usable by all blueprints, and you have the ability to define custom aliases in dfhack-config/quickfort/aliases.txt that are visible to all your blueprints as well. An "#aliases" blueprint can define custom aliases that are only visible to the current ".csv" or ".xlsx" file. Packaging aliases in the same file that uses them is convenient for specialized aliases that are only useful to a particular blueprint. Also, if you want to share your blueprint with others, defining your aliases in an "#aliases" blueprint will help your blueprint to work "out of the box", and you won't need others to add your custom aliases to their "dfhack-config/quickfort/aliases.txt" files.

Although we're calling them "blueprints", "#aliases" blueprints are not actual blueprints, and they don't show up when you run "quickfort list". The aliases are just automatically read in when you run any "#query" blueprint that is defined in the same file.

Aliases can be in either of two formats, and you can mix formats freely within the same "#aliases" section. The first format is the same as what is used in the "aliases.txt" files:

   #aliases
   aliasname: aliasdefinition

Aliases in this format must appear in the first column of a row.

The second format has the alias name in the first column and the alias definition in the second column, with no ":" separator:

   #aliases
   aliasname,aliasdefinition

There can be multiple #aliases sections defined in a .csv file or .xlsx spreadsheet. The aliases are simply combined into one list. If an alias is defined multiple times, the last definition wins.

See the Quickfort keystroke alias reference for help with the alias definition syntax.


Ignore blueprints
`````````````````

If you don't want some data to be visible to quickfort at all, use an "#ignore" blueprint. All lines until the next modeline in the file or sheet will be completely ignored. This can be useful for personal notes, scratch space, or temporarily "commented out" blueprints.


Packaging a set of blueprints
-----------------------------

A complete specification for a section of your fortress may contain 5 or more separate blueprints, one for each "phase" of construction (dig, build, place stockpiles, designate zones, and query adjustments).

To manage all the separate blueprints, it is often convenient to keep related blueprints in a single file. For .xlsx spreadsheets, you can keep each blueprint in a separate sheet. Online spreadsheet applications like Google Sheets make it easy to work with multiple related blueprints, and, as a bonus, they retain any formatting you've set, like column sizes and coloring.

For both .csv files and .xlsx spreadsheets you can also add as many blueprints as you want in a single file or sheet. Just add a modeline in the first column to indicate the start of a new blueprint. Instead of multiple .csv files, you can concatenate them into one single file. This is especially useful when you are sharing your blueprints with others. A single file is much easier to manage than a directory of files.

For example, you can write multiple blueprints in one file like this:

   #dig label(bed1)
   d d d d #
   d d d d #
   d d d d #
   d d d d #
   # # # # #
   #build label(bed2)
   b   f h #
           #
           #
   n       #
   # # # # #
   #place label(bed3)
           #
   f(2x2)  #
           #
           #
   # # # # #
   #query label(bed4)
           #
   booze   #
           #
           #
   # # # # #
   #query label(bed5)
   r{+ 3}& #
           #
           #
           #
   # # # # #

Of course, you could still choose to keep your blueprints in separate files and just give related blueprints similar names:

   bedroom.1.dig.csv
   bedroom.2.build.csv
   bedroom.3.place.csv
   bedroom.4.query.csv
   bedroom.5.query2.csv

The naming and organization is completely up to you.


Buildingplan integration
------------------------

Buildingplan is a DFHack plugin that keeps building construction jobs in a suspended state until the materials required for the job are available. This prevents a building designation from being canceled when a dwarf picks up the job but can't find the materials.

As long as the buildingplan plugin is enabled, quickfort will use it to manage construction. The buildingplan plugin has an "enabled" setting for each building type, but those settings only apply to buildings created through the buildingplan user interface. Quickfort will still use buildingplan to plan buildings even if the buildingplan UI says that building type is not "enabled".

In addition, buildingplan has a "quickfort_mode" setting for compatibility with legacy Python Quickfort. This setting has no effect on DFHack Quickfort, which will use buildingplan to manage everything designated in a "#build" blueprint regardless of the buildingplan UI settings.

However, quickfort *does* use buildingplan's filters for each building type. For example, you can use the buildingplan UI to set the type of stone you want your walls made out of. Or you can specify that all buildingplan-managed chairs and tables must be of Masterful quality. The current filter settings are saved with planned buildings when the "#build" blueprint is run. This means you can set the filters the way you want for one blueprint, run the blueprint, and then freely change them again for the next blueprint, even if the first set of buildings haven't been built yet.

Note that buildings are still constructed immediately if you already have the materials. However, with buildingplan you now have the freedom to apply "#build" blueprints before you manufacture the resources. The construction jobs will be fulfilled whenever the materials become available.

Since it can be difficult to figure out exactly what source materials you need for a "#build" blueprint, quickfort supplies the "orders" command. It enqueues manager orders for everything that the buildings in a "#build" blueprint require. See the next section for more details on this.

Alternately, if you know you only need a few types of items, the workflow plugin can be configured to build those items continuously for as long as they are needed.

If you do not want to enable the buildingplan plugin, run "quickfort orders" and make sure all manager orders are fulfilled before applying a "#build" blueprint. Otherwise you will get job cancellation spam when the buildings can't be built with available materials.


Generating manager orders
-------------------------

Quickfort can generate manager orders to make sure you have the proper items in stock for a "#build" blueprint.

Many items can be manufactured from different source materials. Orders will always choose rock when it can, then wood, then cloth, then iron. You can always remove orders that don't make sense for your fort and manually enqueue a similar order more to your liking. For example, if you want silk ropes instead of cloth ropes, make a new manager order for an appropriate quantity of silk ropes, and then remove the generated cloth rope order.

Anything that requires generic building materials (workshops, constructions, etc.) will result in an order for a rock block. One "Make rock blocks" job produces four blocks per boulder, so the number of jobs ordered will be the number of blocks you need divided by four (rounded up). You might end up with a few extra blocks, but not too many.

If you want your constructions to be in a consistent color, be sure to choose a rock type for all of your 'Make rock blocks' orders by selecting the order and hitting "d". You might want to set the rock type for other non-block orders to something different if you fear running out of the type of rock that you want to use for blocks. You should also set the buildingplan material filter for construction building types to that type of rock as well so other blocks you might have lying around aren't used.


Extra Manager Orders
~~~~~~~~~~~~~~~~~~~~

In "#build" blueprints, there are a few building types that will generate extra manager orders for related materials:

* Track stops will generate an order for a minecart

* Traction benches will generate orders for a table, mechanism, and rope

* Levers will generate an order for an extra two mechanisms for connecting the lever to a target

* Cage traps will generate an order for a cage

Stockpiles in "#place" blueprints that specify wheelbarrow or container counts will generate orders for the appropriate number of bins, pots, or wheelbarrows.


Tips and tricks
---------------

* During blueprint application, especially query blueprints, don't click the mouse on the DF window or type any keys. They can change the state of the game while the blueprint is being applied, resulting in strange errors.

* After digging out an area, you may wish to smooth and/or engrave the area before starting the build phase, as dwarves may be unable to access walls or floors that are behind/under built objects.

* If you are designating more than one level for digging at a time, you can make your miners more efficient by using marker mode on all levels but one. This prevents your miners from digging out a few tiles on one level, then running down/up the stairs to do a few tiles on an adjacent level. With only one level "live" and all other levels in marker mode, your miners can concentrate on one level at a time. You just have to remember to "unmark" a new level when your miners are done with their current one. Alternately, if you have a chokepoint between levels (e.g. a central staircase), you can set the chokepoint to be dug at a lower priority than all the other tiles on the level. This will ensure your miners complete digging out a level before continuing on to the next.

* As of DF 0.34.x, it is no longer possible to build doors ("d") at the same time that you build adjacent walls ("C""w"). Doors must now be built *after* adjacent walls are constructed. This does not affect the more common case where walls exist as a side-effect of having dug-out a room in a "#dig" blueprint, but if you are building your own walls, be aware that walls must be built before you run the blueprint to designate attached doors.

* Quickfort is a very powerful tool. See the case study below for more ideas on how to build awesome blueprints!


Caveats and limitations
-----------------------

* If you use the the "bags" alias, be aware that the game does not differentiate between empty and full bags. Therefore, you can get bags of gypsum power in your "bags" stockpile unless you are careful to assign all your gypsum to your hospital.

* Weapon traps and upright spear/spike traps can currently only be built with a single weapon.

* Pressure plates can be built, but they cannot be usefully configured yet.

* Building instruments is not yet supported.

* DFHack Quickfort is a large project, and there are bound to be bugs! Please report them at the DFHack issue tracker so they can be addressed.


Dreamfort case study: a practical guide to advanced blueprint design
--------------------------------------------------------------------

While syntax definitions and toy examples will certainly get you started with your blueprints, it may not be clear how all the quickfort features fit together or what the best practices are, especially for large and complex blueprint sets. This section walks through the "Dreamfort" blueprints found in the DFHack blueprint library, highlighting design choices and showcasing practical techniques that can help you create better blueprints. Note that this is not a guide for how to design the best *fort* (there is plenty about that on the wiki). This is essentially an extended tips and tricks section focused on how to make usable and useful quickfort blueprints that will save you time and energy.

Almost every quickfort feature is used somewhere in Dreamfort, so the blueprints are very useful as reference examples. You can copy the Dreamfort blueprints and use them as starting points for your own, or just refer to them when you create something similar.

In this case study, we'll start by discussing the high level organization of the Dreamfort blueprint set. Then we'll walk through the spreadsheets for each of the fort levels in turn, calling out feature usage examples and explaining the parts that might not be obvious just from looking at them.

If you haven't built Dreamfort before, maybe try an embark in a flat area and take it for a spin! It will help put the following sections in context. There is also a pre-built Dreamfort available for download on dffd if you just want an interactive reference.


Dreamfort organization and packaging
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The Dreamfort blueprints are distributed with DFHack as one large .csv file, but editing in that format would be frustrating. Instead, the blueprints are edited online as Google drive spreadsheets. Either the .csv file or the .xlsx files can be read and applied by quickfort, but it made more sense to distribute the blueprints as a .csv so users would only have to remember one filename. Also, .csv files are text-based, which works more naturally with the DFHack source control system. We use the xlsx2csv utility to do the conversion from .xlsx to .csv format.


Tip
^^^

Include a "#notes" section with information about how to use your blueprint.

Each spreadsheet has a "help" sheet with a "#notes" blueprint that displays a walkthrough and other useful details. This is the first sheet in each spreadsheet so it will be selected by default if the user doesn't specify a label name. For example, just running "quickfort run library/dreamfort.csv" will display Dreamfort's introduction text.

Do not neglect writing the help text! Not only will it give others a chance to use your blueprints appropriately, but the help you write will remind *you* what you were thinking when you wrote the blueprint in the first place.


Tip
^^^

Include custom alias definitions in the same file as the blueprint.

If any blueprint in the set uses custom aliases that other users won't have in their data/quickfort/aliases-common.txt files, be sure to define them in the blueprint itself in an Aliases blueprints section. Then other people can use your blueprint right away without having to manually copy aliases into their personal dfhack-config/quickfort/aliases.txt files.


The surface level: how to manage complexity
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

[image: Annotated screenshot of the dreamfort surface level][image]

For smaller blueprints, packaging and usability are not really that important - just write it, run it, and you're done. However, as your blueprints become larger and more detailed, there are some best practices that can help you deal with the added complexity. Dreamfort's surface level is many steps long since there are trees to be cleared, holes to be dug, flooring to be laid, and bridges to be built, and each step requires the previous step to be completely finished before it can begin. Therefore, a lot of thought went into minimizing the toil associated with applying so many blueprints.


Tip
^^^

Use meta blueprints to script blueprint sequences and reduce the number of quickfort commands you have to run.

The single most effective way to make your blueprint sets easier to use is to group them with meta blueprints. For the Dreamfort set of blueprints, each logical "step" generally takes more than one blueprint. For example, with "#meta" blueprints, setting up pastures with a "#zone" blueprint, placing starting stockpiles with a "#place" blueprint, building starting workshops with a "#build" blueprint, and configuring the stockpiles with a "#query" blueprint can all be done with a single command. Bundling blueprints with "#meta" blueprints reduced the number of steps in Dreamfort from 61 to 30, and it also made it much clearer to see which blueprints can be applied at once without unpausing the game. Check out dreamfort_surface's "meta" sheet to see how much meta blueprints can simplify your life.

You can define as many blueprints as you want on one sheet, but this is especially useful when writing meta blueprints. It's like having a bird's eye view of your entire plan in one sheet.


Tip
^^^

Keep the blueprint list uncluttered by using "hidden()" markers.

If a blueprint is bundled into a meta blueprint, it does not need to appear in the "quickfort list" output since you won't be running it directly. Add a hidden() marker to those blueprints to keep the list output tidy. You can still access hidden blueprints with "quickfort list --hidden" if you need to -- for example to reapply a partially completed "#build" blueprint -- but now they won’t clutter up the normal blueprint list.


Tip
^^^

Name your blueprints with a common prefix so you can find them easily.

This goes for both the file name and the modeline label(). Searching and filtering is implemented for both the "quickfort list" command and the quickfort interactive dialog. If you give related blueprints a common prefix, it makes it easy to set the filters to display just the blueprints that you're interested in. If you have a lot of blueprints, this can save you a lot of time. Dreamfort uses the level name as a prefix for the labels, like "surface1", "surface2", "farming1", etc. So if I’m in the middle of applying the surface blueprints, I’d set the filter to "dreamfort surface" to just display the relevant blueprints.


Tip
^^^

Add descriptive comments that remind you what the blueprint contains.

If you've been away from Dwarf Fortress for a while, it's easy to forget what your blueprints actually do. Make use of modeline comments so your descriptions are visible in the blueprint list. If you use meta blueprints, all your comments can be conveniently edited on one sheet, like in surface's meta sheet.


Tip
^^^

Use "message()" markers to remind yourself what to do next.

Messages are displayed after a blueprint is applied. Good things to include in messages are:

* The name of the next blueprint to apply and when to run it

* Whether "quickfort orders" should be run for the current or an upcoming step

* Any actions that you have to perform manually after running the blueprint, like assigning minecarts to hauling routes or pasturing animals in newly-created zones

These things are just too easy to forget. Adding a "message()" can save you from time-wasting mistakes. Note that "message()" markers can still appear on the "hidden()" blueprints, and they'll still get shown when the blueprint is run via a "#meta" blueprint. For an example of this, check out the zones sheet where the pastures are defined.


The farming level: fun with stockpiles
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

[image: Annotated screenshot of the dreamfort farming level][image]

It is usually convenient to store closely associated blueprints in the same spreadsheet. The farming level is very closely tied to the surface because the miasma vents dug on the surface have to perfectly line up with where waste products are placed on the farming level. However, surface is a separate z-level and, more importantly, already has many many blueprints of its own. Farming is therefore split into a separate file.


Tip
^^^

Automate stockpile chains when you can, and write "message()" reminders when you can't.

The farming level starts doing interesting things with "#query" blueprints and stockpiles. Note the careful customization of the food stockpiles and the stockpile chains set up with the "give*" aliases. This is so when multiple stockpiles can hold the same item, the largest can keep the smaller ones filled. For example the "give2up" alias funnels seeds from the seeds feeder pile to the container-enabled seed storage pile. If you have multiple stockpiles holding the same type on different z-levels, though, this can be tricky to set up with a blueprint. Here, the jugs and pots stockpiles must be manually linked to the quantum stockpile on the industry level, since we can't know beforehand how many z-levels away that is. Note how we call that out in the "#query" blueprint's "message()".


Tip
^^^

Use aliases to set up hauling routes and quantum stockpiles.

Hauling routes are notoriously fiddly to set up, but they can be automated with blueprints. Check out the Southern area of the "#place" and "#query" blueprints for how the quantum refuse dump is configured with simple aliases from the alias library.


The industry level: when not to use aliases
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

[image: Annotated screenshot of the dreamfort industry level][image]

The industry level is densely packed and has more complicated examples of stockpile configurations and quantum dumps. However, what I'd like to call out first are the key sequences that are *not* in aliases.


Tip
^^^

Don't use aliases for ad-hoc cursor movements.

It may be tempting to put all query blueprint key sequences into aliases to make them easier to edit, keep them all in one place, and make them reusable, but some key sequences just aren't very valuable as aliases.

Check out the Eastern (goods) and Northern (stone and gems) quantum stockpiles -- cells I19 and R10. They give to the jeweler's workshop to prevent the jeweler from using the gems held in reserve for strange moods. The keys are not aliased since they're dependent on the relative positions of the tiles where they are interpreted, which is easiest to see in the blueprint itself. Also, if you move the workshop, it's easier to fix the stockpile link right there in the blueprint instead of editing a separate alias definition.

There are also good examples in the "#query" blueprint for how to use the "permit" and "forbid" stockpile aliases.


Tip
^^^

Put all configuration that must be applied in a particular order in the same spreadsheet cell.

Most of the baseline aliases distributed with DFHack fall into one of three categories:

1. Make a stockpile accept only a particular item type in a category

2. Permit an item type, but do not otherwise change the stockpile configuration

3. Forbid an item type, but do not otherwise change the stockpile configuration

If you have a stockpile that covers multiple tiles, it might seem natural to put one alias per spreadsheet cell. The aliases still all get applied to the stockpile, and with only one alias per cell, you can just type the alias name and avoid having to use the messier-looking "{aliasname}" syntax:

   #place Declare a food stockpile
   f(3x3)
   #query Incorrectly configure a food stockpile to accept tallow and dye
   tallow
   permitdye

However, in quickfort there are no guarantees about which cell will be processed first. In the example above, we obviously intend for the food stockpile to have tallow exclusively permitted, then to add dye. It could happen that the two aliases are applied in the opposite order, though, and we'd end up with dye being permitted, then everything (including dye) being forbidden, and, finally, tallow being enabled. To make sure you always get what you want, write order-sensitive aliases on the same line:

   #place Declare a food stockpile
   f(3x3)
   #query Properly configure a food stockpile to accept tallow and dye
   {tallow}{permitdye}

You can see a more complex example of this with the "meltables" stockpiles in the lower left corner of the industry level.


The services level: handling multi-level dig blueprints
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

[image: Annotated screenshot of the dreamfort services level][image]

Services is a multi-level blueprint that includes a well cistern beneath the main level. Unwanted ramps caused by channeling are an annoyance, but we can avoid getting a ramp at the bottom of the cistern with careful use of dig priorities.


Tip
^^^

Use dig priorities to control ramp creation.

We can ensure the bottom level is carved out before the layer above is channeled by assigning the channel designations lower priorities (the "h5"s in the third layer -- scroll down).

An alternative is to have a follow-up blueprint that removes any undesired ramps. We did this on the surface and farming levels with the miasma vents since it would be too complicated to synchronize the digging between the two layers.


The guildhall level: avoiding smoothing issues
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

[image: Annotated screenshot of the dreamfort guildhall level][image]

The goal of this level is to provide rooms for "locations" like guildhalls, libraries, and temples. The value of these rooms is very important, so we are likely to smooth and engrave everything. To smooth or engrave a wall tile, a dwarf has to be adjacent to it, and since some furniture, like statues, block dwarves from entering a tile, where you put them affects what you can access.


Tip
^^^

Don't put statues in corners unless you want to smooth everything first.

In the guildhall level, the statues are placed so as not to block any wall corners. This gives the player freedom for choosing when to smooth. If a statue blocks a corner, or if a line of statues blocks a wall segment, it forces the player to smooth before building the statues. Otherwise they have to bother with temporarily removing statues to smooth the walls behind them.


The beds levels: multi level meta blueprints
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

[image: Annotated screenshot of the dreamfort noble suites][image][image: Annotated screenshot of the dreamfort apartments][image]

The suites and apartments blueprints are straightforward. The only fancy bit is the meta blueprint that digs the stack of apartment levels, which brings us to our final tip:


Tip
^^^

Use meta blueprints to lay out repeated adjacent levels.

We couldn't use this technique for the entire fortress since there is often an aquifer between the farming and industry levels, and we can't know beforehand how many z-levels we need to skip. We can, however, automate the digging of everything from the industry level down, including designating all apartment levels at once. See the #meta blueprint in the Dreamfort help spreadsheet for how it uses a "repeat()" marker for the "/apartments1" blueprint to apply it to five z-levels at once.

That's it! I hope this guide was useful to you. Please leave feedback on the forums if you have ideas on how this guide (or the dreamfort blueprints) can be improved!


Links
-----

**Quickfort links:**

* Quickfort command reference

* Quickfort keystroke alias reference

* Quickfort blueprint library

* Quickfort forum thread

* DFHack issue tracker

* Blueprint library source

* Quickfort source code

**Related tools:**

* DFHack's blueprint plugin can generate blueprints from actual DF maps.

* DFHack's buildingplan plugin sets material and quality constraints for quickfort-placed buildings.

* Python Quickfort is the previous, Python-based implementation that DFHack's quickfort script was inspired by.
