Quickfort 2

A spreadsheet driven construction tool for Dwarf Fortress


With Quickfort, you can turn spreadsheet files like these


into something like this.



Quickfort 2.04

by joelpt quickfort@joelpt.net

http://joelpt.net/quickfort

User Manual

Quickfort 2 is a utility for Dwarf Fortress that helps you build fortresses from "blueprint" .CSV, .XLS, and .XLSX files. Many applications exist to edit these files, such as MS Excel and Google Docs. Most building-oriented DF commands are supported through the use of multiple files/worksheets, each describing a different phase of DF construction (designation, building, stockpiles, and making adjustments).

Original idea and 1.0 codebase from Valdemar's designator.ahk script.

User contributed blueprints can be found here.

See the Links section for various tools that work with Quickfort.

Table of Contents

Features

For the impatient

WINDOWS USERS: Run Quickfort.exe for the GUI interface.

LINUX/OSX USERS: Please set [MACRO_MS:0] in your data/init/init.txt for best DF macro playback performance.

Run the command line qfconvert tool via python to generate DF macro files:

> cd src/qfconvert
> python ./qfconvert.py

or chmod +x qfconvert.py to run it like a shell script.

Command line example using qfconvert:

> python ./qfconvert.py myblueprint.xls <DF folder>/data/init/macros/foo.mak

... then play your macro in DF with Ctrl+L, select foo, Ctrl+P.

Quickfort 2.0: What's new

See the changelog for newer changes since version 2.00.

Quickfort 2.0 is a major rewrite of Quickfort 1.11.

The new blueprint conversion engine 'qfconvert' has been rewritten in cross- platform Python, enabling non-Windows users to utilize the app via the command line. More importantly, the use of Python makes possible a much more advanced implementation of how Quickfort does its job.

The new conversion engine is much smarter about how it designates your blueprints. Instead of using the "typewriter" (line-by-line) approach of QF1.x, QF2 tries to minimize the total number of commands (keystrokes) sent to Dwarf Fortress. It does this by analyzing your blueprint, finding the largest contiguous areas that can possibly be designated with single DF commands; for example, a 10x10 room can be dug out with one 'd' command instead of 100 single-tile designations. While designating these areas, QF2 also attempts to minimize the amount of cursor travel between areas.

QF2 is smarter about designating objects of various sizes. For example, workshops can now be designated by filling a 3x3 area of a blueprint with 'wc' instead of just a single 'wc' in the center of a 3x3 area. This makes some kinds of blueprints easier to create and read.

The new engine also has a reworked blueprint transformation framework which supports things like blueprint repetition, rotation, and in-cell modification.

QF2 supports outputting and executing DF macros instead of sending keystrokes to the DF window (QF1.x style). This results in blueprint playbacks that are faster and more reliable vs. keysending. Since DF macros are native to DF, they can be used on any OS that runs Dwarf Fortress. Keysending is still used by the Windows-only Quickfort GUI for certain operations, i.e. Alt+V "visualize".

Quickfort's minimalist Windows-only "GUI" is a partial rewrite of the AutoHotKey script that was Quickfort 1.x. It has seen a number of significant improvements, such as blueprint previews and the ability to choose a worksheet from a multisheet XLS/XLSX file. It is now a "thin" GUI implementation, providing only the mousetip-based GUI and DF-keysending functionality, and relying on qfconvert for all blueprint processing and manipulation.

A list of the shiny new bits:

This new codebase for Quickfort 2.0 will enable lots of interesting new features and experiments in future releases. Features such as '#all' blueprints, '#meta' blueprints, and an Undo mode are all on the 2.x release schedule.

For users of Quickfort 1.x

A few things have changed in Quickfort's basic operation in the move from 1.0 to 2.0:

Windows Quick Start

  1. Download and extract the Quickfort2.##.zip file from https://github.com/joelpt/quickfort/downloads
  2. Run Quickfort.exe.
  3. Launch Dwarf Fortress and get into a Fortress mode game.
  4. Press Alt+F to open the Quickfort file browser.
  5. Browse into the Tests folder and select obama.csv
  6. Some information will be shown about the blueprint in a popup window. Click OK to continue.
  7. Follow Quickfort's tooltip instructions to switch to Designate mode and select an empty underground z-level.
  8. Press Alt+V to see the outline of where the blueprint will be placed. The entire area should be clear.
  9. If you are satisfied (start at least 3 cells from the map edge), press Alt+D to designate.
  10. Wait a few seconds while the blueprint is designated.

Linux/OSX Quick Start

You must have Python 2.6.4 installed.

Run the command line conversion tool via python:

> cd src/qfconvert
> python ./qfconvert.py

or chmod +x qfconvert.py and run it like a shell script.

Examples:

> python ./qfconvert.py --info myblueprint.xls
  (..information about myblueprint.xls..)

> python ./qfconvert.py myblueprint.xls <DF folder>/data/init/macros/foo.mak

... then play mymacro.mak in DF with Ctrl+L, select foo, Ctrl+P.

Windows Basic Usage

Please see the Troubleshooting section for solutions to common problems.

Quickfort's GUI consists of a mouse tooltip, hotkeys and a few popup windows.

Start Dwarf Fortress (windowed mode recommended). Run Quickfort.exe.

Use Alt+F to select a CSV file to execute. There are some samples in the Blueprints folder. Quickfort will give instructions in the mouse tooltip for positioning the in-game cursor.

Once positioned, use Alt+D to begin designating your blueprint in game. Quickfort will send the commands necessary to DF to dig, build, place, or query according to the chosen blueprint.

Alt+Q/W/A/S can be used to change the starting corner for the blueprint (that is, which corner of the blueprint you'll put the starting cursor at). The current starting corner setting will be shown in the QF tooltip. These hotkeys have no effect if the blueprint specifies a starting cursor position; see the Specifying a starting position section for more details.

Alt+R can be used to repeat a blueprint any number of times to the north, south, east, west, up, and down. This can be useful for digging multilevel staircases/shafts, repeating room complexes, etc. Alt+R can also be used to rotate, flip, tesselate, and search-and-replace blueprints: see the Transformations section for more details.

Alt+T opens the Quickfort command line. Here you can enter a single-line QF-style command. Commands entered this way can be repeated with Alt+R as well.

After a build completes, Alt+D can be used to designate the same blueprint again, or use Alt+F again to select a new blueprint. Alt+E can be used to select a different worksheet from a currently selected multisheet XLS/XLSX file, or just view the information for the current CSV or worksheet.

Alt+N can be used to save a named macro to DF's macros folder. This can be useful if you designate a particular blueprint often and would rather access it from DF's Ctrl+L menu than go through Quickfort every time.

Alt+H can be used to hide QF's mouse tooltip; all hotkeys will continue to work. Alt+M toggles from QF's rather wordy mousetip to a minimal one, if you know what you're doing.

Alt+K toggles between macro and keys modes. In macro mode, QF will utilize DF's built-in macro functionality to execute commands. In keys mode, QF will literally send keystrokes to the DF window to perform those same commands (this was QF1.x's approach). Keys mode is a bit slower, but if you're having trouble designating with macro mode, try switching to keys mode.

Shift+Alt+Z suspends/resumes Quickfort, useful if you find it to interfere with other windows.

Shift+Alt+X exits Quickfort.

Editing Blueprints

The format of Quickfort-compatible blueprint files is straightforward.

Use a spreadsheet editor such as Excel, Google Docs, or LibreOffice to edit these files. There are also a number of blueprint editing tools that export Quickfort compatible blueprint files; see the Links section.

The first line of the spreadsheet should look like this:

#dig This is a comment.

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

dig     Designations menu (d)
build   Build menu (b)
place   Place stockpiles menu (p)
query   Set building tasks/prefs menu (q)

Optionally following this keyword and a space, you may enter a comment. This comment will appear by default after loading the blueprint with Quickfort (Alt+F). You can use this space for explanations, attribution, etc. Newlines may be embedded by using \n.

Below this line begin entering the keys you want sent in each cell. For example, we could dig out a 4x4 room like so (spaces are used as column separators here):

#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 for layout purposes.

If you run into problems (e.g. Excel saving 'blank' cells and rows unnecessarily), use # symbols as shown above to clearly delineate the area. They tell QF where the edges of your blueprint are. They can also be used to enforce a blueprint of a larger width or height than the filled cells would otherwise occupy.

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 d  Cw #
#  #  #  #  #

Note my generosity - I've placed a bed (b), chest (h) and door (d) here as well. Note that you must use the full series of keys needed to build something in each cell, e.g. 'Cw' enters DF's constructions submenu (C) and selects 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(2x1)#
` ` ` ` #
# # # # #

This illustration may be a little hard to understand. The f(2x1) is in column 2, row 3. All the other cells are empty. QF considers both ` and ~ characters within cells to be empty cells; this can help with multilayer or fortresswide blueprint layouts as 'chalk lines'.

With f(2x1), we've asked QF to place a Food stockpile 2 units wide by 1 high unit, or f(2x1). QF sends the necessary keys to resize the placement region. This also works properly in all modes, including build mode (floors Cf(10x10), bridges ga(4x4), etc. that are sized with UMKH keys).

Note that the f(2x1) syntax isn't actually necessary here; we could have just used:

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

QF2 is smart enough to recognize this as a 2x1 food stockpile, and creates it as such rather than as two 1x1 food stockpiles. This applies to most cases where f(WxH) could also be used. The f(WxH) style can still be useful in cases where the layout would be ambiguous; consider an L-shaped food stockpile(s).

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

#query
` ` ` ` #
` r+` ` #
` booze #
` ` ` ` #
# # # # #

In column 2, row 2 we have "r+". This sends r+ keys to DF when the cursor is over the bed, causing us to 'make room' and then increase its size to ensure the 'room' fills the entire area.

In column 2, row 3 we have "booze". booze is an alias keyword defined in the included config/aliases.txt file. This particular alias sets a food stockpile to carry booze only, by sending the commands needed to navigate DF's stockpile settings menu.

The included Blueprints/Examples/bedroom-*.csv files provide a good simple example of a 4-layer QF blueprint. Check out aliases.txt for some helpful starting aliases. Blueprints/TheQuickFortress/ provides a good detailed set of examples covering some more complex designs.

Area expansion syntax

In Quickfort 2.0, 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 always takes the form:

cmds(WxH)

In Quickfort 2.0, the above two examples of specifying a contiguous 3x3 area produce identical output: a single 3x3 designation will be performed, rather than nine 1x1 designations as the first example might suggest.

Sometimes, how an area should be identified is ambiguous:

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

QF2 wants to make the largest contiguous areas. Should it draw a tall 2x4 food stockpile on the left with a second 2x2 stockpile in the lower right? Or should it have a long 4x2 along the bottom with a 2x2 in the upper left? QF2 will choose one or the other, but you have no guarantee which way it will choose.

If you need to guarantee a certain area arrangement unambiguously, use area expansion syntax:

# place L shaped food stockpile; ~ markers denote placement (ignored by QF2)
f(2x4)` #
~ ~ ` ` #
~ ~ f f #
~ ~ f f #
# # # # #

Automatic area expansion

In Quickfort 1.x, buildings larger than 1x1, like workshops, had to be placed in blueprints in a single cell, usually in the "center" of the building's footprint, with empty cells around it to leave room for that footprint.

Starting with Quickfort 2.0, this is no longer necessary.

The following blueprints are equivalent:

#build workshop in row 2, col 2 that will occupy the 3x3 area (QF1.x style)
`  `  `  #
`  wm `  #
`  `  `  #
#  #  #  #

#build workshop: QF2 understands that we want one 3x3 workshop
wm wm wm #
wm wm wm #
wm wm wm #
#  #  #  #

This is called automatic area expansion.

Both the area expansion syntax and automatic area expansion also work 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 the same bridge
ga ga ga ga #
ga ga ga ga #
#  #  #  #  #

This can be especially helpful for laying out structures like screw pump towers and waterwheels, whose "center point" can be non-obvious.

Specifying a starting position

You can optionally specify a cursor starting position for a particular blueprint, simplifying the task of blueprint alignment. This can be helpful for blueprints that are based on a central staircase, for example.

To specify a cursor starting position, use the following modified format for the header line of your blueprint:

#mode start(X;Y;STARTCOMMENT) comment

where X and Y specify the starting cursor position (1;1 is the top left cell) and STARTCOMMENT (optional) is a description displayed to the QF user of where to position their cursor. This description appears in the pre-playback mouse tooltip.

A couple examples:

#dig start(3; 3; Center tile of a 5-tile square) Regular blueprint comment
#build start(10;15)

When a start() parameter is found in a CSV file, the normal Alt+Q/W/A/S keys will override (ignore) said parameter. Alt+Z will un-ignore the start() parameter.

See Blueprints/Tests/starting-position.csv for a simple example. The Blueprints/TheQuickFortress/*.csv examples all utilize start().

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  #
#  #  #  #

Most multilevel blueprints use #>, but there are a few use cases for #< such as building a screw pump tower. See Blueprints/Examples/screw-pump-tower-*.csv for an example.

Multiple build phases

A complete QF specification for a floor of your fortress may contain 4 or more separate blueprints, one for each "phase" of construction (dig/designate, build, place stockpiles, building adjustments).

Starting with Quickfort 2.0, all phases and even variations can be kept in a single .XLS or .XLSX file using multiple worksheets. Tools like Excel make it easy to work with multiple worksheets and also retains all worksheet styling such as cell sizes and coloring.

After opening a multisheet XLS/XLSX blueprint using Alt+F, Quickfort will present a dialog allowing you to choose which sheet to use. Alt+E can be subsequently used to select a different sheet from the same file.

Quickfort 2.0 is also fully compatible with using single-sheet .CSV files for blueprints. The build phases suggest a convenient naming scheme for CSV based blueprint "stacks", as seen in the Blueprints/General folder:

bedroom-dig.csv
bedroom-build.csv
bedroom-stockpile.csv
bedroom-adjust.csv

The naming scheme is up to you, of course. A similar approach is used in the Blueprints/TheQuickFortress folder.

Protip: After digging out an area, it's often wise to dump all leftover stone in the area before beginning the build phase. You may also wish to smooth and/or engrave the area before starting the build phase, as dwarves may be unable to access walls/floors that are behind/under built objects.

Manual material selection

Quickfort supports manual material selection for #build blueprints. This enables you to manually select the materials that Quickfort should build with during playback.

Currently, manual material selection only works on Windows when using the Quickfort GUI (Quickfort.exe). It also requires using QF's key-sending playback method because user interaction is required during playback. Lastly, note that this feature is considered EXPERIMENTAL. Most types of constructions should work with manual material selection, but some are untested.

To use manual material selection, just append :label to the end of any cells in a #build blueprint. label can be any alphanumeric label that you'd like to use to identify the material to be used. Multiple different labels can be used in a single blueprint, allowing for multiple distinct materials to be applied during construction.

A simple example:

#build Uses 3 different materials to build 3 rows of flooring
Cf:top,Cf:top,Cf:top,Cf:top,Cf:top
Cf:mid,Cf:mid,Cf:mid,Cf:mid,Cf:mid
Cf:bot,Cf:bot,Cf:bot,Cf:bot,Cf:bot

After starting playback with Alt+D, when Quickfort first encounters a new :label, you will be prompted to help Quickfort memorize the material you want to use for cells with that label. There are three steps to memorize a material:

  1. Use DF's +-/* keys to highlight the desired material in DF's material menu
  2. Click to the LEFT of the FIRST letter of the highlighted material
  3. Click to the RIGHT of the LAST letter of the highlighted material

Quickfort uses onscreen prompts and sound notifications to take you through these steps.

The process lets Quickfort take a screen-clipping of the region between your mouse-clicks. This clipping of the highlighted material's row is then used by Quickfort as a "fingerprint" of your chosen material.

When QF encounters another cell with the same :label later, it will search through the materials list, automatically moving the highlight and checking if the "fingerprint" is found onscreen. When the correct material is again highlighted, QF will use the material and continue.

Important notes about memorization

In memorization steps 2 and 3, you should normally click just OUTSIDE of the highlighted material's name (to the left or right). This ensures that a fingerprint taken of material "marble" is distinguishable from a fingerprint for "marble bars"; if we had just clicked on the "m" and "e" in "marble", the fingerprint for "marble" would also match "marble bars" since "marble" is contained within "marble bars". By clicking OUTSIDE the letters, we include the empty space before/after "marble" and thus will not confuse it with "marble bars".

On step 3, note that for very long material names like "petrified wood blocks", you should click to the LEFT of the Dist column in the material menu instead (on the last letter of the material name before the Dist column).

If QF mis-selects a material you memorized, try to click nearer the top and bottom edges of your highlighted material during memorization. This will make the fingerprint larger and thus less liable to later mis-identification.

Minecart tracks

Quickfort supports the designation of minecart tracks, stops, and rollers through the normal mechanisms, e.g. a #build blueprint with CS in a cell will designate a track stop.

For track segments (CT...), you must select from DF's menu to choose the desired track segment, then send {Enter} to select it. For example, to designate a "Track (E)" segment, which is the third item in the track segments menu, you would use:

CT{+ 2}{Enter}

To simplify such designations, a series of aliases have been created for the various track-related designations. You can use these instead of the aforementioned approach.

The aliases are:

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

-- Track stops that dump to N/S/E/W --
trackstopN
trackstopS
trackstopE
trackstopW

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

#build Example track
trackstopW trackEW trackEW trackEW trackstopE

See Blueprints/Tests/minetracks.csv for a larger example.

Command prompt

Quickfort's command prompt can be accessed with Alt+T. Here you can enter commands as 'cells' to be played back. These can also be transformed with Alt+R if desired; see the Transformations section.

Commands must be prefixed with the desired build phase, so that QF knows how to handle your commands properly:

// Dig a row of 4 cells
Alt+T -> dig d,d,d,d

// Build a big bridge
Alt+T -> build ga(10x10)

// Aliases
Alt+T -> query booze

// Build phase may be abbreviated
Alt+T -> q booze

Here we dig out a tiny room, give it a bed and a door, place a food stockpile in it, turn it into a bedroom, and set the stockpile to accept only booze:

Alt+T ->   dig d,d,d,d
Alt+T -> build b,`,`,d
Alt+T -> place `,f,f,`
Alt+T -> query r+,booze,`,`

Multirow 'blueprints' can also be entered at the command prompt by separating lines with # like so:

Alt+T -> dig d,d#d,d

#dig Above command produces this result
d d #
d d #
# # #

Alt+T -> dig d,d#d,d##

#dig Above command produces this result
d d #
d d #
` ` #
# # #

Note in the second example how the command ends with ##. This is because the # is treated as the end-of-row marker. If you want to add a final blank row to a multirow command, therefore, you need to end with two #'s: one to end the preceding line and another to end the last line.

Transformations

Quickfort supports repeating and transforming your blueprints in various ways.

Use the Alt+R hotkey to open the transformation prompt and see a simple syntax primer. Enter ? to receive additional help.

Transformations: Simple repetition

A blueprint can be repeated in any direction: north, south, east, west, up-z, and down-z.

It can be repeated any number of times and repetitions can be performed in 1, 2 or 3 dimensions.

The syntax is #D ... where # is the number of times to repeat and D is the first letter of the direction you want to repeat in.

Alt+R -> 3n
Repeats the blueprint three times to the north

Alt+R -> 4e 2s
Repeats the blueprint 4x east and 2x south (8 repetitions total)

Alt+R -> 2e 2s 2d
Repeats the blueprint in a 2x2x2 cube pattern (multi-z-level)

Transformations: Simple transformation

A blueprint can be transformed in the following ways:

Alt+R -> rotcw
Rotates the blueprint 90 degrees clockwise.

Alt+R -> rotccw
Rotates the blueprint 90 degrees counterclockwise.

Alt+R -> fliph
Flips the blueprint horizontally (left edge becomes right edge).

Alt+R -> flipv
Flips the blueprint vertically (top edge becomes bottom edge).

Alt+R -> flipv fliph
Mirror the blueprint around both x and y axes.

Advanced transformations

Repetition and transformation commands can be combined for some interesting effects. To get the effect you want, however, you need to understand how Quickfort 2.0's transformation engine works.

QF keeps track of two transformation buckets during transformation. We will call these buckets the Memory bucket, or bucket A, and the Working bucket, or bucket B.

Let's follow an example and observe how the buckets change as we execute the following transformation sequence:

#dig The blueprint we'll be transforming
d d d #
d ` ` #
` ` ` #
# # # #

Alt+R -> rotcw 3e flipv 2s rotccw

At the start of a transformation sequence, QF sets both buckets A and B to the original, untransformed blueprint.

Starting contents of transformation buckets (before any transformation):

    d d d    d d d
    d . .    d . .
    . . .    . . .
    --A--    --B--

QF then executes each command in the transformation sequence in order.

Transformation commands like rotcw affect only the Working bucket B. The contents of B will be replaced with the transformed version of B.

After rotcw transformation (only modifies B):

    d d d    . d d
    d . .    . . d
    . . .    . . d
    --A--    --B--

Repetition commands like 3e, on the other hand, utilize both buckets A and B. More specifically, A and B are repeated in series in the direction you indicate. The result of that repetition then replaces the contents of both A and B. If you specify 3e, for example, you are actually getting the content of the buckets in series as the result: ABA.

After 3e repetition (ABA):

    d d d . d d d d d    d d d . d d d d d
    d . . . . d d . .    d . . . . d d . .
    . . . . . d . . .    . . . . . d . . .
    --------A--------    --------B--------

Once all transformations in the sequence have been performed, the contents of Working bucket B are returned as the result, to be designated by Quickfort.

We have flipv 2s rotccw remaining to execute from our original transformation sequence rotcw 3e flipv 2s rotccw. Let's execute the remaining steps and see the result:

After flipv transformation (only modifies B):

    d d d . d d d d d    . . . . . d . . .
    d . . . . d d . .    d . . . . d d . .
    . . . . . d . . .    d d d . d d d d d
    --------A--------    --------B--------

After 2s (AB):

    d d d . d d d d d    d d d . d d d d d
    d . . . . d d . .    d . . . . d d . .
    . . . . . d . . .    . . . . . d . . .
    . . . . . d . . .    . . . . . d . . .
    d . . . . d d . .    d . . . . d d . .
    d d d . d d d d d    d d d . d d d d d
    --------A--------    --------B--------

After rotccw (only modifies B):

    d d d . d d d d d    d . . . . d
    d . . . . d d . .    d . . . . d
    . . . . . d . . .    d d . . d d
    . . . . . d . . .    d d d d d d
    d . . . . d d . .    d . . . . d
    d d d . d d d d d    . . . . . .
    --------A--------    d . . . . d
                         d . . . . d
                         d d . . d d
                         -----B-----

Returning B as finished result:

    d . . . . d
    d . . . . d
    d d . . d d
    d d d d d d
    d . . . . d
    . . . . . .
    d . . . . d
    d . . . . d
    d d . . d d
    -----------

Making sense yet? To get a better handle on how this all works, the best approach is probably to just start experimenting with the Alt+R command. Also see transformation debugging.

While it may seem unintuitive at first, this approach for transformation was intentionally chosen for Quickfort 2.0. It is meant to retain the simple QF1.x-style 2e 2s repeat functionality, while also allowing the mixing of QF1.x repetition commands with QF2.x transformation commands and allowing for interesting tesselations.

Author's note: I would be glad to hear of any suggestions for an alternative approach/syntax here.

Advanced transformations: alignment

Consider the state our transformation buckets were in just before returning the result in the preceding example:

d d d . d d d d d    d . . . . d
d . . . . d d . .    d . . . . d
. . . . . d . . .    d d . . d d
. . . . . d . . .    d d d d d d
d . . . . d d . .    d . . . . d
d d d . d d d d d    . . . . . .
--------A--------    d . . . . d
                     d . . . . d
                     d d . . d d
                     -----B-----

Suppose we add a 2e onto the end of that transformation sequence:

Alt+R -> rotcw 3e flipv 2s rotccw 2e

What do we get?

. . . . . . . . . d . . . . d
. . . . . . . . . d . . . . d
. . . . . . . . . d d . . d d
d d d . d d d d d d d d d d d
d . . . . d d . . d . . . . d
. . . . . d . . . . . . . . .
. . . . . d . . . d . . . . d
d . . . . d d . . d . . . . d
d d d . d d d d d d d . . d d
-----------------------------

You can see what has happened. A and B have been combined to repeat 2e, but since their width and height differ from one another, Quickfort by default aligns the two blueprints along their common bottom edge.

The horizontal and vertical alignment employed during transformation can be controlled using the halign= and valign= commands in your transformation sequence. Their syntax is:

halign=left|middle|right|l|m|r (default: right)
valign=top|middle|bottom|t|m|b (default: bottom)

Compare these results:

Alt+R -> rotcw 3e flipv 2s rotccw valign=top 2e

d d d . d d d d d d . . . . d
d . . . . d d . . d . . . . d
. . . . . d . . . d d . . d d
. . . . . d . . . d d d d d d
d . . . . d d . . d . . . . d
d d d . d d d d d . . . . . .
. . . . . . . . . d . . . . d
. . . . . . . . . d . . . . d
. . . . . . . . . d d . . d d
-----------------------------

Alt+R -> rotcw 3e flipv 2s rotccw valign=middle 2e

. . . . . . . . . d . . . . d
d d d . d d d d d d . . . . d
d . . . . d d . . d d . . d d
. . . . . d . . . d d d d d d
. . . . . d . . . d . . . . d
d . . . . d d . . . . . . . .
d d d . d d d d d d . . . . d
. . . . . . . . . d . . . . d
. . . . . . . . . d d . . d d
-----------------------------

Alt+R -> rotcw 3e flipv 2s rotccw valign=b 2e

. . . . . . . . . d . . . . d
. . . . . . . . . d . . . . d
. . . . . . . . . d d . . d d
d d d . d d d d d d d d d d d
d . . . . d d . . d . . . . d
. . . . . d . . . . . . . . .
. . . . . d . . . d . . . . d
d . . . . d d . . d . . . . d
d d d . d d d d d d d . . d d
-----------------------------

Note that 2e/2w repetitions are only affected by valign, and 2s/2n repetitions are only affected by halign. This is because we are specifying alignment along the shared axis between the repeated sections. Thus valign=top 2s doesn't do anything more than just 2s, because it's the shared horizontal axis between the northern and southern copy that they are aligned along.

If you expect to do a lot of combined rotation and repetition to make interesting patterns and variety in your fortress, strongly consider using perfectly square blueprints (width == height), which when repeated in a direction will adjoin nicely with neighboring designated blueprints. You'll worry much less about halign/valign issues within complex transform sequences.

Advanced transformations: the whirlpool pattern

The so-called whirlpool pattern is the 'holy grail' for many symmetrical/fractal layouts. It can make for very attractive and effective fortress layouts. The design rotates a blueprint clockwise around a central point resulting in 4-fold rotational symmetry. (I looked it up.)

This can be accomplished using QF transformation, but with a twist (no pun intended).

#dig
d d d #
d ` ` #
` ` i #
# # # #

You might expect that you could do it this way:

Alt+R -> rotcw 2e rotcw 2s

But because the second rotcw only applies to Working bucket B, we end up with this:

d d d . d d
d . . . . d
. . i i . d
. . . . d d
. . . . . d
. . . i . d
. . . i . .
. . . . . d
. . . d d d
-----------

Not quite what we're looking for.

What we can do instead of the second rotcw is to flip bucket B both horizontally and vertically. When we then repeat 2s, we repeat A and B (the symmetrical mirror image of A) below (south of) it.

Alt+R -> rotcw 2e fliph flipv 2s

d d d . d d    }
d . . . . d    } rows from A: rotcw 2e
. . i i . d    }
d . i i . .   }
d . . . . d   } rows from B: rotcw 2e fliph flipv
d d . d d d   }
-----------

Voila.

Formula for the whirlpool pattern:

Alt+R -> rotcw 2e fliph flipv 2s

This effect can be trivially made larger. Try these and compare the results:

Alt+R -> rotcw 2e fliph flipv 2s 2e 2s

Alt+R -> 2e 2s rotcw 2e fliph flipv 2s

For extra credit: how would you reverse the whirlpool transform to proceed in a counterclockwise fashion (starting with rotccw)?

Advanced transformations: multiple Z-levels

Z-level repetitions are treated as a special case in Quickfort. When included in the transformation sequence, they are always executed last. Thus the following produce identical results:

Alt+R -> rotcw 2e 2s 10d
Alt+R -> 10d rotcw 2e 2s

Z-level repetitions may be used in conjunction with multi-z-level blueprints. See Blueprints/Examples/screw-pump-tower-*.csv for an example.

Using multiple #d/#u transformations in a single sequence is not well supported. Prefer combining them into one transformation, e.g. 6d instead of 3d 2d.

Advanced transformations: the ! command

Normally transformations only apply to Working bucket B, leaving Memory bucket A untouched. Sometimes you may want to have what is in bucket B copied to bucket A. The ! command performs this operation.

Compare the output of the two transformation sequences below:

#dig
d d d #
d ` ` #
` ` i #
# # # #

Alt+R -> rotcw 2e

d d d . d d
d . . . . d
. . i i . d
-----------

Alt+R -> rotcw ! 2e

. d d . d d
. . d . . d
i . d i . d
------------

In the second example, we copied B to A after rotating B, but before repeating 2e. We're essentially using the ! command to "pre-rotate" A before we perform our repetition.

Generally speaking, the ! command can be thought of as a transformation sequence separator. rotcw ! 2e is the same as executing the sequence rotcw, then executing a separate sequence 2e on the rotcw transformation's result.

Alt+R -> rotcw 2e: rotate B, then repeat AB twice east
Alt+R -> rotcw ! 2e: rotate the blueprint, then repeat it twice east

Advanced transformations: Search and replace

The substitution command can be used to change the contents of cells using a regular-expression based search and replace.

The syntax is:

s/pattern/replacement/

For example, to change all Ts (stonefall trap) cells on a blueprint into Tw (weapon trap) cells:

Alt+R -> s/Ts/Tw/

pattern is a regular expression pattern; for more information please see http://www.regular-expressions.info/. Most of the time, just using a simple substring pattern will do what you expect.

replacement is the value to replace pattern with, and can be any valid string. Use \1, \2, ... for regex capture-group matching.

Quickfort additionally supports two more useful features: matching empty cells (s//replacement/) and match negation (s/~pattern/replacement/).

Alt+R -> s//d/
Matches all empty cells in a blueprint and fills them with `d`

Alt+R -> s/~d/i/
Turns all cells which do NOT match `d` into `i`

Alt+R -> s/~/d/
Turns all NON-empty cells into `d`

By default, Quickfort matches anywhere within the contents of a cell. Thus the following:

Alt+R -> s/oo/ee/

will turn cells containing booze into beeze. To require the entire cell to match, use regex's ^ (match at start) and & (match at end) codes:

Alt+R -> s/^oo&/ee/
Used on cell `booze`, has no effect - cell stays as `booze`;
used on cell `oo`, cell becomes `ee`

Quickfort only updates Working bucket B with s/foo/bar/ commands. This allows for making alternating patterns if desired. If this is not what you want, either put the s/foo/bar commands after other transformation commands, or follow it with a ! command.

A few more examples:

Alt+R -> s/Cw/Cw:foo/
Adds manual material label `:foo` to all `Cw` cells

Alt+R -> s/(Cw|Cf)/\1:foo/
Adds manual material label `:foo` to all `Cw` or `Cf` cells

Alt+R -> s/Cf/Cf:foo/ ! s/Cf:foo/Cf:bar/ 4e fliph flipv 4s
Repeat a flooring blueprint as a checkerboard, using alternating manual mats

Advanced transformations: Change build phase

Particularly when using the s/pattern/replacement/ substitution command, it can be useful to change the build phase without editing the blueprint directly. This can be accomplished using the phase=... command.

For these examples, assume we start with a #dig blueprint. Observe:

Alt+R -> phase=build
Simply changes the #dig blueprint into a #build blueprint.

Alt+R -> phase=build s/d/Cf/
Sets as #build print, then changes all `d` cells into `Cf` (floor tiles).

Alt+R -> phase=b s//Cw/ s/~Cw//
Sets as #build, turns empty cells into `Cw` walls, and clears all others.

All build phases and their first-letter abbreviations are accepted.

Advanced transformations: debugging

By running qfconvert.exe or qfconvert.py from the command line, you can see the progression of a particular transformation sequence and the contents of buckets A and B after each step:

> qfconvert.exe blueprints/Tests/transform-test.xls --mode=key --transform="rotcw 2e fliph flipv 2s" --show-transforms

or using abbreviated syntax:

> qfconvert.exe blueprints/Tests/transform-test.xls -mkey -t "rotcw 2e fliph flipv 2s" -X

The use of --mode=key is just to avoid being spammed with DF-macro output (very verbose).

Stupid dwarf tricks

Dig a 2x2 column of up/down stairs deep into the earth:

Alt+T -> dig i(2x2)
Alt+R -> 100d

Undesignate a large chunk of the map on multiple z-levels:

Alt+T -> dig x(100x100)
Alt+R -> 10d

Undesignate (undo) a #dig or #place blueprint:

Alt+R -> s/~/x/

Undesignate (undo) a #build blueprint (make sure you are in DF 'q' mode first):

Alt+R -> phase=q s/~/x/

Manually choose and use the same material for all walls in a #build blueprint:

Alt+R -> s/Cw/Cw:foo/

Add 'Cf' flooring in #build mode on top of each 'd' cell of a #dig blueprint:

Alt+R -> phase=build s/d/Cf/ s/~Cf//

Troubleshooting

Create an Excel macro to size all columns to a uniform narrow width

This tip can help when working with a lot of files.

We'll create a new Ctrl+T hotkey in your local Excel installation:

  1. In Excel, go to Tools->Macro->Record New Macro
  2. For macro name, enter: NarrowColumns
  3. For shortcut key enter: Ctrl+T (or your preference)
  4. Make sure it is set to store macro in Personal Macro Workbook.
  5. Hit OK.
  6. Click the gray corner cell in the very top left of the spreadsheet, between the row headers and the column headers. This should highlight the whole spreadsheet.
  7. Right click on column header A and select Choose Column Width.
  8. Type 2 and hit Enter.
  9. Go to Tools->Macro->Stop Recording.
  10. Exit and restart Excel (this allows you to save your new macro).

Now, hit Ctrl+T in Excel at any time to size all columns of the current sheet to a 2 unit width.

Other Excel tips

Quickfort official links

Visual designers for Quickfort

The following tools allow you to lay out multiple phases of a blueprint visually, and output Quickfort compatible blueprint files.

Image-to-blueprint converters

The following tools convert image files (e.g. BMP) into Quickfort CSV files.

Similar utilities to Quickfort

The following tools work similarly to Quickfort, operating on CSV blueprint files.

If you look hard you can still find a few remnants of designator.ahk in the latest Quickfort.ahk source file!

Todo/Future Ideas

Changelog

2.04 (2012 May 29)

2.03 (2012 January 10)

2.02 (2011 December 12)

2.01 (2011 July 4)

2.00 (2011 June 21)

2.00pre5 (2011 June 19)

2.00pre4 (2011 June 17)

2.00pre3 (2010 July 31)

1.11 (2010 April 15)

1.10 (2010 April 5)

1.09 (2010 March 13)

1.08 (2009 July 30)

1.07 (2009 July 21)

1.06 (2009 July 3)

1.05 (2009 July 1)

1.04 (2009 June 9)

1.03 (2009 June 7)

1.02 (2009 June 3)

1.01 (2009 May 30)

1.0

Credits and License

Quickfort is written by joelpt quickfort@joelpt.net.

Thanks to the following individuals whose code contributions are present in Quickfort:

bakergo (proper CSV file parsing; many good suggestions)
Valdemar (author of designator.ahk, which QF 1.00 was based on)

Thanks to the following individuals whose bug-hunting or feature-requesting resulted in improvements to Quickfort:

Snuffy
Xinael
Jhoosier
LegoLord
shadow_slicer
starrrie
Aklyon
Root Infinity
Thundercraft
kurzedmetal
Robik
VenomIreland

Copyright 2012 Joel Thornton

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.