f f f{name=Seeds links_only=true take_from="Seeds feeder"}:=seeds
#zone one pasture in two disconnected regions
n/slots n/slots n/slots
n/slots{name="Pasture slots"}(3x1)
Automatic area expansion
~~~~~~~~~~~~~~~~~~~~~~~~
@ -341,7 +366,7 @@ 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
#build a stonecutter workshop in row 2, col 2 that will occupy the 3x3 area
` ` ` #
` wm ` #
` ` ` #
@ -349,7 +374,7 @@ leave room for the footprint, like this::
Or you can fill out the entire footprint like this::
#build a mason workshop
#build a stonecutter workshop
wm wm wm #
wm wm wm #
wm wm wm #
@ -361,7 +386,7 @@ point" can be non-obvious.
Or you can use area expansion syntax::
#build a mason workshop
#build a stonecutter workshop
wm(3x3) #
` ` ` #
` ` ` #
@ -369,9 +394,9 @@ Or you can use area expansion syntax::
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::
20 stonecutter workshops all in a row::
#build line of 20 mason workshops
#build line of 20 stonecutter workshops
wm(60x3)
Quickfort will intelligently break large areas of the same designation into
@ -411,7 +436,7 @@ You can go up or down multiple levels by adding a number after the ``<`` or
---------
``#dig`` blueprints are normally the first step in any design. They define the
boundaries and layouts for the blueprints for later stages of construction. Despite their name, ``#dig``` blueprints are for more than just digging. They also handle smoothing, carving, traffic designations, and marking items on the ground for dumping, forbidding, or other similar tags. See the full list of supported designations in the `#dig mode reference`_.
boundaries and layouts for the blueprints for later stages of construction. Despite their name, ``#dig`` blueprints are for more than just digging. They also handle smoothing, carving, traffic designations, and marking items on the ground for dumping, forbidding, or other similar tags. See the full list of supported designations in the `#dig mode reference`_.
.._quickfort-dig-priorities:
@ -569,7 +594,10 @@ sequence of blueprints until no tiles are designated by the "erase" blueprint.
#zone mode
----------
Zones define how regions of your fort should be treated. They are also the anchor point for "locations" like taverns and hospitals. Unlike stockpiles or buildings, zones can overlap, which can lead to some interesting layouts.
Zones define how regions of your fort should be treated. They are also the
anchor point for "locations" like taverns and hospitals. Unlike stockpiles or
buildings, zones can overlap, which can lead to some interesting layouts. See
the full list of zone symbols in the `#zone mode reference`_.
Zone designation syntax
~~~~~~~~~~~~~~~~~~~~~~~
@ -602,6 +630,10 @@ or from different corners of the same rectangle::
and you can use this technique to achieve partial overlap, of course. The only configuration that can't be specified in a single blueprint is multiple non-rectangular zones that are partially overlapping. You will have to use multiple ``#zone`` blueprints to achieve that.
You can also use labels (see `Label syntax`_ above) to separate adjacent
non-rectangular zones that happen to be of the same type or to combine
disconnected regions into a single zone.
Locations, locations, locations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -631,9 +663,11 @@ Stockpile designation syntax
Just like zones, stockpiles can have properties like names or lists of other stockpiles to take from. Unlike zones, stockpiles can have configuration specifiers for exactly what types of items to accept. The full syntax looks like this::
types{properties}:configuration(expansion)
types/label{properties}:configuration(expansion)
You're already familiar with `Property syntax`_ and `Area expansion syntax`_, so let's focus in on the remaining elements.
with every component other than the type being optional. You're already
familiar with `Property syntax`_, `Label syntax`_, and
`Area expansion syntax`_, so let's focus in on the remaining elements.
Stockpile types
~~~~~~~~~~~~~~~
@ -650,10 +684,7 @@ could write::
yr(20x10)
The order of the individual letters doesn't matter. If you want to configure the
stockpile from scratch, you can place unconfigured "custom" stockpiles with (:kbd:`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 from scratch, you can place unconfigured "custom" stockpiles with (:kbd:`c`).
.._quickfort-place-containers:
@ -662,16 +693,25 @@ 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.
for individual stockpiles as well in the properties.
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::
Individual properties for ``bins``, ``barrels``, and ``wheelbarrows`` are
supported. You can also set them all at once with the ``containers`` alias (it
usually just makes sense to set this to 0 when you don't want any containers of
any type). For example::
#place a stone stockpile with 5 wheelbarrows
s5(3x3)
s{wheelbarrows=5}(3x3)
#place a bar, ammo, weapon, and armor stockpile with 20 bins
bzpd20(5x5)
bzpd{bins=20}(5x5)
#place a weapon stockpile with no bins
p{containers=0}(9x2)
That last one could have equivalently used ``bins=0``, but sometimes you just
don't want to have to think about which stockpile types take which type of
container.
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
@ -679,34 +719,14 @@ 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
Generating manager orders for 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::
size of the stockpile. For example, the following blueprint will enqueue orders
for 10 rock pots, even though the stockpile only has 9 tiles::
#place
f10(3x3)
f{barrels=10}(3x3)
Stockpile configuration
~~~~~~~~~~~~~~~~~~~~~~~
@ -817,7 +837,7 @@ to create (or attach to if it already exists). If you are applying a quantum
stockpile blueprint more than once in a fort, be sure to *avoid* defining the
``route`` property so that each application of the blueprint creates a unique
hauling route. Two quantum stockpiles on the same route will not function
propertly.
properly (since one of the stops will be missing a minecart).
Let's look at a slightly more complicated setup where we sort the stone into
different output quantum stockpiles::
@ -882,15 +902,15 @@ elements before we discuss them in more detail::
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.
Labels are displayed in the blueprint selection dialog and the output of
``quickfort list`` 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.
.._quickfort-start:
@ -902,7 +922,7 @@ 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
#build start(2;2;center of workshop) label(stonew) a stonecutter workshop
wm wm wm #
wm wm wm #
wm wm wm #
@ -913,30 +933,29 @@ 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::
top left cell. The optional comment will show up in the blueprint listings 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 ``stonew`` blueprint above could look like this::
#meta start(center of workshop) a mason workshop
/masonw
#meta start(center of workshop) a stonecutter workshop
/stonew
You can use semicolons, commas, or spaces to separate the elements of the
``start()`` marker, whatever is most convenient.
``start()`` marker, whichever you prefer.
.._quickfort-hidden:
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 <quickfort-meta>`.
A blueprint with a ``hidden()`` marker won't appear in the blueprint listings
unless hidden blueprints are specifically requested. 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 <quickfort-meta>`.
.._quickfort-message:
@ -944,10 +963,10 @@ 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::
blueprint is applied. 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"
@ -956,16 +975,79 @@ 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.
.._quickfort-other-modes:
Other blueprint modes
---------------------
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
============== ===========
notes Display long messages, such as help text or blueprint
walkthroughs
ignore Hide a section of your spreadsheet from quickfort, useful for
scratch space or personal notes
meta Script sequences of blueprints together, transform them, and/or
repeat them across multiple z-levels
============== ===========
.._quickfort-notes:
#notes mode
~~~~~~~~~~~
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() <quickfort-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.
#ignore mode
~~~~~~~~~~~~
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.
.._quickfort-meta:
#meta mode
----------
~~~~~~~~~~
``#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.
Scripting blueprints together
`````````````````````````````
A common scenario where meta blueprints are useful is when you have several
phases to link together. For example you might:
@ -979,7 +1061,7 @@ phases to link together. For example you might:
Those last four "apply"s might as well get done in one command instead of four.
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:
section) 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.
@ -1061,24 +1143,19 @@ a big fort, so we're digging 5 levels of bedrooms)::
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/dig_it
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``.
from the blueprint selection lists by adding a ``hidden()`` marker to their
modelines. That way, the blueprint lists 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 by toggling the "Hidden" setting in the `gui/quickfort` load dialog or 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
@ -1093,8 +1170,7 @@ 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
````````````````````
**Repeating blueprints**
Syntax: repeat(<direction>[, ]<number>)
@ -1115,8 +1191,7 @@ lines are all equivalent::
/2beds repeat(down, 3)
/2beds repeat(>3)
Shifting blueprints
```````````````````
**Shifting blueprints**
Syntax: shift(<x shift>[[,] <y shift>])
@ -1126,8 +1201,7 @@ 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
In order to be a target for a stockpile or workshop link, the stockpile or
building must have a name. That's not the only reason you should give things
names, though. The game is just much easier to play when stockpiles and key
buildings have descriptive names. Which lever controls the bridge named "Right outer gate"? You can click on that bridge, click on "show linked buildings", zoom to the lever, and click on the lever. Or you can scan your mouse over the levers and click onYou can always edit names in-game, but
blueprints are a great way to automate this task.
buildings have descriptive names. Which lever controls the bridge named "Right
outer gate"? You can click on that bridge, click on "show linked buildings",
zoom to the lever, and click on the lever. Or you can scan your mouse over the
levers and click on the lever with the same name as the target bridge. You can
always edit names in-game, but blueprints are a great way to automate this task.
Myk Taylor