.. _quickfort-blueprint-guide: .. _quickfort-user-guide: .. _quickfort-alias-guide: Quickfort blueprint creation guide ================================== `Quickfort ` is a DFHack tool 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 actions are supported through the use of multiple files or spreadsheets, each describing a different phase of DF construction: designating digging, defining zones, placing stockpiles, and building. The original idea came from :wiki:`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, preserving compatibility with existing blueprints (where possible -- DF itself has changed since then). In contrast with the earlier quickfort implementations, which interacted with DF by simulating keyboard input, DFHack Quickfort calls lower-level API functions to designate tiles and configure buildings. This allows for nearly instantaneous blueprint application, error checking and recovery, and many other advanced features. This guide focuses on DFHack Quickfort's capabilities and blueprint syntax, 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. If you are just looking to apply existing blueprints to your fort, check out `gui/quickfort` (or `quickfort` for the commandline version). There are many ready-to-use blueprints available in the `quickfort-library-guide` distributed with DFHack. 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 that section of your map using `gui/blueprint`. 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. .. contents:: Table of Contents :local: :depth: 2 Feature summary --------------- - General - Blueprint modes for all phases of fort design - Read blueprints from .csv or multi-worksheet .xlsx files - Near-instant application, even for very large and complex blueprints - Blueprints can span multiple z-levels - Easy sharing of blueprints with multi-blueprint files - Scripted application of sequences of blueprints - Undo applied blueprints - Rotate blueprints or flip them around - Automatic cropping of blueprints that extend off the map - Generate manager orders for items required by a blueprint - Includes a library of ready-to-use blueprints - Blueprint debugging - 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 - Zone and place modes - Define zones and stockpiles of any shape, not just rectangles - Configurable numbers of bins, barrels and wheelbarrows assigned to created stockpiles - Automatic splitting of stockpiles that exceed maximum dimension limits - Create and attach locations to zones - Full control over stockpile configuration based on the `stockpiles` settings library - Configurable zone/location settings, such as the pit/pond toggle or hospital supply quantities - Build mode - Integrated with DFHack `buildingplan`: you can place buildings before manufacturing building materials and you can use the `buildingplan` UI for setting materials and quality 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 causing errors and interrupting 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) - Set building properties (such as a name) - Can attach and configure track stops as part of hauling routes - Burrow mode - Supports creating, adding to, and subtracting from burrows. Introduction to 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 specifying designations. The following "mode" keywords are understood: ============== =========== Blueprint mode Description ============== =========== dig Designations (digging, traffic, dumping, etc.) build Constructions, buildings, and furniture place Stockpiles zone Activity zones ============== =========== 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 design operations, 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`` 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 # # # # # # The letter ``d`` here stands for "dig". The character sequences in these blueprints are based on the old (pre-v50) keyboard shortcuts for the various DF menus. Please see the `quickfort_guide_appendix` below for a full reference. Note the :kbd:`#` 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 zone it as a bedroom:: #zone b b b b # b b b b # b b b b # b b b b # # # # # # This looks very similar to the ``#dig`` blueprint above, but with ``b``\s instead of ``d``\s. The ``b``\s mark the area for a ``b``\edroom zone just like the ``#dig`` blueprint marked the area for digging. It's important to wait until after the area is completely dug out before applying further blueprints since zones can't be applied to hidden tiles and furniture can't be built in undug walls. Now, let's add some walls and furniture:: #build Cw Cw Cw Cw # Cw b h Cw # Cw Cw # Cw Cw Cw # # # # # # The :kbd:`C`:kbd:`w` cells represent the constructed walls, leaving space for a door that we might want to add later. Quickfort uses `buildingplan` for managing buildings, so the walls will be built out of whatever matches the current buildingplan filter set for walls. Also note my generosity -- in addition to the bed (:kbd:`b`) I've built a container (:kbd:`h`) for this lucky dwarf. Finally, let's place a booze stockpile in the 2 unoccupied tiles in the room:: #place personal booze stockpile ` ` ` ` # ` ~ ~ ` # ` f f{name="bedroom booze"}:=booze ` ` ` # # # # # # This illustration may be a little hard to understand. The two :kbd:`f` characters are in row 3, columns 2 and 3. All the other cells are empty. QF considers both :kbd:`\`` (backtick -- the character under the tilde) and :kbd:`~` (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. You can also treat disconnected segments as belonging to the same stockpile, but we'll get into `Label syntax`_ later. Now what's all that business attached to the second ``f``? The part between the curly brackets specifies properties, in this case the name that we want to give the stockpile. The remaining part, from the colon (``:``) onward, applies the ``booze`` preset from the `stockpiles` library. That will configure the stockpile to accept only booze. You can use presets (along with other options that we'll go over later) to configure stockpiles however you want, directly from the ``#place`` blueprint. And that's it! You now have a series of blueprints that you can "stamp" across your fort to quickly build new bedrooms. 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:: text(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, :kbd:`~` 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) ` # # # # # # Property syntax ~~~~~~~~~~~~~~~ Many things you can designate with `quickfort` are configurable. All buildings, stockpiles, and zones, for example, can be named. These configuration elements are expressed as properties. Properties are written between curly brackets (``{}``). There can be multiple properties defined between those brackets, separated by spaces. Each property has a name and a value, with an equal sign to connect them. If a property value has a space within it, it should be surrounded by double quotes (``"``). If you have defined the area of something over multiple spreadsheet cells, you can specify properties in just one of those cells and they will apply to the whole object. You can even split properties up among multiple cells if that is more convenient. If you are using expansion syntax, the expansion part always goes last. Here's an example of a seed stockpile that is configured to take from a seed feeder stockpile:: #place f{name=Seeds links_only=true}:=seeds(3x2) f f{name="Seeds feeder" give_to=Seeds}:=seeds f{containers=0} Different modes and different types may have different properties that you can configure. See the `quickfort_guide_appendix` for a full list. Label syntax ~~~~~~~~~~~~ Labels are different from the ``name`` property. They are only used internally by Quickfort to associate tiles with a particular zones or stockpiles. This is useful for when you want to define two touching zones or stockpiles of the same type(s), but you can't use expansion syntax because they are non-rectangular. It is also useful for marking two *disconnected* regions as belonging to the same zone or stockpile. Note that every tile in the zone or stockpile must be marked with the same label:: #place two touching stockpiles of the same type f/feed f/feed f/feed{name="Seeds feeder" containers=0}:=seeds f/feed f f/feed 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 ~~~~~~~~~~~~~~~~~~~~~~~~ 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 stonecutter 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 stonecutter 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 stonecutter 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 stonecutter workshops all in a row:: #build line of 20 stonecutter 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 mode --------- ``#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`_. .. _quickfort-dig-priorities: Dig priorities ~~~~~~~~~~~~~~ DF designation priorities are supported in ``#dig`` blueprints. The full syntax is ``[markers][symbol][number][expansion]``, where if the ``symbol`` is not specified, ``d`` is assumed, and if ``number`` is not specified, ``4`` is assumed (the default priority). So all of these blueprints are 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 # # # # # # # At least one of the symbol and the priority number must be specified. Dig markers ~~~~~~~~~~~ There are three types of markers you can apply to dig designated tiles. You can apply multiple markers to the same tile by including multiple marker prefixes. For example, a tile that is in blueprint mode and that is also marked for warm and damp dig would be written as:: #dig mbmwmdd Blueprint marker ```````````````` "Blueprint" markers are useful for when you want to plan out your digging, but you don't want to dig everything just yet. Here, "blueprint" refers to the vanilla UI "blueprint mode" vs. "standard mode" buttons. You can use DF's "Change blueprints to standard selections" button to convert the "blueprint" marked tiles to regular designations. 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 mbd mbd mbd d # d mbd mbd mbd d # d mbd mbd mbd d # d d d d d # # # # # # # To apply an entire dig blueprint in blueprint 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 by running ``quickfort set force_marker_mode true``. Note that the state of the in-game vanilla button that you use to draw designations in either Standard or "Blueprint" mode does not have any effect on `quickfort`. Warm and damp dig markers ````````````````````````` Warm and damp dig markers allow digging to continue uninterrupted through warm or damp tiles. These markers are useful to include in blueprints that are expected to be applied near magma or in damp/aquifer layers. See the `dig` tool for more info on warm and damp dig. The prefix for warm dig is ``mw`` and the prefix for damp dig is ``md``. Carved minecart 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 ``track`` 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. #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. See the full list of zone symbols in the `#zone mode reference`_. Zone designation syntax ~~~~~~~~~~~~~~~~~~~~~~~ A zone is declared with a symbol followed by optional properties:: #zone a single tile garbage dump zone d #zone a single tile garbage dump zone named "The Dump" d{name="The Dump"} #zone interrogation room o{name=Interrogation assigned_unit=sheriff} #zone a small inactive pond zone p{name="Fill me" pond=true active=false}(3x3) If you want multiple zones that have the same footprint, they can be declared from the same cell:: #zone pasture and training area n{name="Main pasture"}t{name="Pet training area"}(14x10) or from different corners of the same rectangle:: #zone pasture and training area n{name="Main pasture"}(10x2) t{name="Pet training area"}(10x-2) 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Hospitals, guildhalls, taverns, libraries, and temples are locations. You can declare a location in the properties for a zone:: #zone metalcrafter hall m{location=guildhall profession=metalcrafter}(7x7) You can attach multiple zones to a single location by giving the location a label (not a name -- you can name zones, but you can't directly name locations) and then using that label for each of the zones you want to attach:: #zone tavern and rented room b{location=tavern/bigpub name="Rent me"}(3x1) h{location=tavern/bigpub name="Central pub" allow=residents}(25x40) Note that the label ("bigpub" in this case) will never appear in-game. It is only used in the context of the blueprint to identify a common location. #place mode ----------- ``#place`` mode is dedicated to stockpiles, which are a major design element in any fortress. 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/label{properties}:configuration(expansion) 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 ~~~~~~~~~~~~~~~ The type of stockpile corresponds to the category of items it accepts. Some types will cause the stockpile to accept bins or barrels. See the full list in the `#place mode reference`_. It is very common to have stockpiles that accept multiple categories of items. Although it is perfectly valid to declare a single-purpose stockpile, `quickfort` also supports directly declaring all the categories at once. For example, to declare a 20x10 stockpile that accepts both corpses and refuse, you could write:: #place refuse heap 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`). .. _quickfort-place-containers: 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 in the properties. 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 s{wheelbarrows=5}(3x3) #place a bar, ammo, weapon, and armor stockpile with 20 bins 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 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! 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, the following blueprint will enqueue orders for 10 rock pots, even though the stockpile only has 9 tiles:: #place f{barrels=10}(3x3) Stockpile configuration ~~~~~~~~~~~~~~~~~~~~~~~ Quickfort uses the `stockpiles` plugin and `stockpiles-library` to configure stockpile settings, and provides a syntax that is easy to write in a blueprint yet still allows you to access the full power of the `stockpiles` command. The syntax is:: : [/] [ [/]...] ```` is one of ``=``, ``-``, or ``+``, representing the three `stockpiles` import modes: ``set``, ``disable``, or ``enable``, respectively. Note that if you are using an ``=`` op, then it should go first in the list. Any ``=`` configuration segment will override anything that comes before it. For example, a blueprint like:: #place f:=booze(5x4) would be equivalent to creating a 5x4 food stockpile in the UI, then selecting it and running this command:: stockpiles import --mode=set booze you can also add a slash (``/``) and a comma-separated list of filter strings to customize the settings further:: #place p{name="Metal weapons"}:-cat_weapons/other/(7x3) Note that the "op" in this case lets us disable the matched preset, which in this case is the "Other materials" types in the Weapons category. This configuration is equivalent to the `stockpiles` command:: stockpiles import --mode=disable cat_weapons --filter=other/ And we can chain multiple `stockpiles` commands together by adding another "op" character and another preset:: #place p{name="Steel weapons"}:-cat_weapons/mats/,other/+steelweapons(7x3) which corresponds to running these two commands:: stockpiles import --mode=disable cat_weapons --filter=mats/,other/ stockpiles import --mode=enable steelweapons With the combination of the library presets and custom filter strings, you can configure any stockpile any way you like! #build mode ----------- ``#build`` mode handles buildings, furniture (which are also "buildings" according to DF), constructions (including constructed tracks), and hauling routes. Building designation syntax ~~~~~~~~~~~~~~~~~~~~~~~~~~~ The syntax is very similar to the syntax for stockpiles, except that it only makes sense to have a single symbol to indicate what to build on that tile:: symbol{properties}:configuration(expansion) See the `#build mode reference`_ for properties that you can specify for each building type. Here's an example of a simple 5x5 square of flooring:: #build Cf(5x5) or a named Jeweler's workshop that takes from specific stockpiles:: #build wj{name="Encrusting center" take_from="Furniture,Gem storage"} or a forge that specializes in high-quality armor:: #build wf{name=Armorer labors=Armoring min_skill=Master} The ``:configuration`` part is only relevant for hauling routes, which we'll go over in the next section. Hauling route definitions ~~~~~~~~~~~~~~~~~~~~~~~~~ Hauling routes are defined by properties and configuration attached to track stops. You can define a single-stop hauling route for a quantum stockpile as easily as a multi-stop stone quarry transportation line. The stockpile-like ``:configuration`` part of the syntax controls which item types are considered "desired" for the hauling route stop. If it's not specified, then all item types are accepted. This is the most common case since most hauling route contents are filtered by the stockpiles that the stops take from, but the flexibility is there for when multiple stops take different items from the same stockpile, or when a stop only wants a subset of items from a stockpile. Here is a common setup for a quantum stone stockpile:: #place s{name="Stone quantum" quantum=true} ~ s5{name="Stone feeder"}(3x3) #build ~ trackstopW{take_from="Stone feeder" route="Stone dumper"} This sets up the quantum stockpile and the feeder stockpile in the ``#place`` blueprint, followed by the trackstop and the hauling route configuration in the ``#build`` blueprint. The ``route`` property is the name of the hauling route 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 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:: #place s{name="Other stone quantum" quantum=true} ~ s5e{name="Rock feeder"}(3x3) s{name="Ore/clay stone quantum" quantum=true} ~ s{name="Gem quantum" quantum=true} ~ #build ~ trackstopW{take_from="Rock feeder" route="Other stone"}:=otherstone ~ trackstopW{take_from="Rock feeder" route="Ore/clay"}:=cat_stone-otherstone ~ trackstopW{take_from="Rock feeder" route="Gems"}:=cat_gems You can see how we make use of the stockpile-style configuration syntax to fine-tune the items desired by the hauling route stop. Finally, let's make a series of stops on a common hauling route. There is nothing particularly special about this example. If the ``route`` property names an existing route, the stop will be added to that route:: #dig trackE trackEW trackEW trackW #build trackstop{route="Tick tock"} ~ ~ trackstop{route="Tick tock"} These two track stops (which do not dump their contents) simply exist on a common route at the ends of a connected carved track. #burrow mode ------------ ``#burrow`` mode can create, extend, and remove tiles from burrows. Burrow designation syntax ~~~~~~~~~~~~~~~~~~~~~~~~~ The syntax should look familiar by now:: symbol{properties}(expansion) See the `#burrow mode reference`_ for symbol and property definitions. Here's how to create (or add to, if a burrow by that name already exists) a 5x5 burrow named ``Inside+``. It will also register this burrow with `gui/civ-alert` if no burrow has yet been registered:: #burrow a{create=true name=Inside+ civalert=true}(5x5) Why the trailing ``+``? That's to indicate to the `burrow` plugin that the burrow should grow as adjacent tiles are dug out. Similarly, here is how to erase a tile from all burrows that currently include it:: #burrow e .. _quickfort-modeline: 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) No explicit 'start()' so cursor is in upper left #meta label(digwholefort) start(center of stairs on surface) #dig label(dig_dining) hidden() called by the digwholefort meta blueprint #zone label(pastures) message(remember to assign animals to the pastures) .. _quickfort-label: Blueprint 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: 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(stonew) a stonecutter 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 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 stonecutter workshop /stonew You can use semicolons, commas, or spaces to separate the elements of the ``start()`` marker, whichever you prefer. .. _quickfort-hidden: Hiding blueprints ~~~~~~~~~~~~~~~~~ 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-message: Messages ~~~~~~~~ A blueprint with a ``message()`` marker will display a message after the 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" 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() ` 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: 1. Apply a dig blueprint to designate dig areas #. Wait for miners to dig #. **Apply another dig blueprint** to designate traffic costs #. **Apply a zone blueprint** to designate zones #. **Apply a place buildprint** to designate and configure stockpiles #. **Apply a build buildprint** to designate buildings 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) in the same format used by the `quickfort` command: ``/