From f894634eef5868225f0f120fc489222e05d223a2 Mon Sep 17 00:00:00 2001 From: Myk Taylor Date: Wed, 14 Jun 2023 11:28:41 -0700 Subject: [PATCH] update dreamfort case study and general formatting --- docs/guides/quickfort-library-guide.rst | 2 +- docs/guides/quickfort-user-guide.rst | 1098 ++++++++++++----------- 2 files changed, 580 insertions(+), 520 deletions(-) diff --git a/docs/guides/quickfort-library-guide.rst b/docs/guides/quickfort-library-guide.rst index 534bb1639..acf5f7b60 100644 --- a/docs/guides/quickfort-library-guide.rst +++ b/docs/guides/quickfort-library-guide.rst @@ -137,7 +137,7 @@ Crypt ````` .. image:: https://drive.google.com/uc?export=download&id=16iT_ho7BIRPD_eofuxdlVQ4FunR1Li23 - :alt: Annotated screenshot of the dreamfort noble suites + :alt: Annotated screenshot of the dreamfort crypt :target: https://drive.google.com/file/d/16iT_ho7BIRPD_eofuxdlVQ4FunR1Li23 :align: center diff --git a/docs/guides/quickfort-user-guide.rst b/docs/guides/quickfort-user-guide.rst index 0e1af8992..e76935ddd 100644 --- a/docs/guides/quickfort-user-guide.rst +++ b/docs/guides/quickfort-user-guide.rst @@ -46,65 +46,65 @@ See the `Links`_ section for more information and online resources. Features -------- -- 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 - - Easy undo - - 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 +- 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 + - Easy undo + - 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 + - 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 +- Zone and place modes - - Define zones and stockpiles of any shape, not just rectangles - - Configurable numbers of bins, barrels and wheelbarrows assigned to created + - 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` + - 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 + - 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 + - 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 + - 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 + - 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 + - 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 + - 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 + - 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) - - Attach track stops to hauling routes + - Set building properties (such as a name) + - Attach track stops to hauling routes Introduction to blueprints -------------------------- @@ -116,7 +116,7 @@ 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 + #dig The keyword ``dig`` tells Quickfort we are going to be specifying designations. The following "mode" keywords are understood: @@ -140,19 +140,19 @@ 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 + #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 # - # # # # # + #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 @@ -164,12 +164,12 @@ 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 # - # # # # # + #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 @@ -180,12 +180,12 @@ undug walls. Now, let's add some walls and furniture:: - #build - Cw Cw Cw Cw # - Cw b h Cw # - Cw Cw # - Cw Cw Cw # - # # # # # + #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. And note my generosity -- in addition to @@ -194,12 +194,12 @@ well. 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 - ` ` ` # - # # # # # + #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 @@ -229,54 +229,54 @@ Area expansion syntax In Quickfort, the following blueprints are equivalent:: - #dig a 3x3 area - d d d # - d d d # - d d d # - # # # # + #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)# - ` ` ` # - ` ` ` # - # # # # + #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) + 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 # - # # # # # + #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) # - ~ ~ ~ ~ # - # # # # # + #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 # - # # # # # + #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. @@ -284,25 +284,25 @@ 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(4x2) ` # + ` ` ` ` # + # # # # # - #build a 4x2 bridge from row 1, col 1 - ga ga ga ga # - ga ga ga ga # - # # # # # + #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) ` # - # # # # # + #build a 4x2 bridge from row 2, col 4 + ` ` ` ` # + ga(4x-2) ` # + # # # # # Property syntax ~~~~~~~~~~~~~~~ @@ -324,12 +324,12 @@ 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) + #place + f{name=Seeds links_only=true}:=seeds(3x2) - f - f{name="Seeds feeder" give_to=Seeds}:=seeds - f{containers=0} + 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. @@ -341,19 +341,19 @@ Buildings larger than 1x1, like workshops, can be represented in any of three ways. You can designate just their center tile with empty cells around it to leave room for the footprint, like this:: - #build a mason workshop in row 2, col 2 that will occupy the 3x3 area - ` ` ` # - ` wm ` # - ` ` ` # - # # # # + #build a mason workshop in row 2, col 2 that will occupy the 3x3 area + ` ` ` # + ` wm ` # + ` ` ` # + # # # # Or you can fill out the entire footprint like this:: - #build a mason workshop - wm wm wm # - wm wm wm # - wm wm wm # - # # # # + #build a mason workshop + wm wm wm # + wm wm wm # + wm wm wm # + # # # # This format may be verbose for regular workshops, but it can be very helpful for laying out structures like screw pump towers and waterwheels, whose "center @@ -361,18 +361,18 @@ point" can be non-obvious. Or you can use area expansion syntax:: - #build a mason workshop - wm(3x3) # - ` ` ` # - ` ` ` # - # # # # + #build a mason workshop + wm(3x3) # + ` ` ` # + ` ` ` # + # # # # This style can be convenient for laying out multiple buildings of the same type. If you are building a large-scale block factory, for example, this will create 20 mason workshops all in a row:: - #build line of 20 mason workshops - wm(60x3) + #build line of 20 mason workshops + wm(60x3) Quickfort will intelligently break large areas of the same designation into appropriately-sized chunks. @@ -386,15 +386,15 @@ each floor. :: - #dig Stairs leading down to a small room below - j ` ` # - ` ` ` # - ` ` ` # - #> # # # - u d d # - d d d # - d d d # - # # # # + #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. @@ -423,29 +423,29 @@ is ``[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 # - # # # # # # + #dig dig the interior of the room at high priority + d d d d d # + d d1 d1 d1 d # + d d1 d1 d1 d # + d d1 d1 d1 d # + d d d d d # + # # # # # # + + #dig dig the interior of the room at high priority + d d d d d # + d d1(3x3) d # + d ` ` ` d # + d ` ` ` d # + d d d d d # + # # # # # # + + #dig dig the interior of the room at high priority + 4 4 4 4 4 # + 4 1 1 1 4 # + 4 1 1 1 4 # + 4 1 1 1 4 # + 4 4 4 4 4 # + # # # # # # Marker mode ~~~~~~~~~~~ @@ -456,13 +456,13 @@ any other designation letter to indicate that the tile should be designated in marker mode. For example, to dig out the perimeter of a room, but leave the center of the room marked for digging later:: - #dig - d d d d d # - d md md md d # - d md md md d # - d md md md d # - d d d d d # - # # # # # # + #dig + d d d d d # + d md md md d # + d md md md d # + d md md md d # + d d d d d # + # # # # # # Then you can use DF's "Toggle Standard/Marking" icons (DF calls them "blueprints", but hopefully that won't get too confusing in this context) to @@ -487,37 +487,37 @@ 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 ` # - # # # # + ` start here ` # + ` ` ` # + ` end here ` # + # # # # Then to carve the cross, you'd do a horizontal segment:: - ` ` ` # - start here ` end here # - ` ` ` # - # # # # + ` ` ` # + 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 ` # - # # # # + #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) ` ` # - ` ` ` # - # # # # + #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!" @@ -525,28 +525,28 @@ 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) ` ` # - # # # # + #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) # - # # # # + #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 # - # # # # + #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 @@ -576,29 +576,29 @@ 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 + d - #zone a single tile garbage dump zone named "The Dump" - d{name="The Dump"} + #zone a single tile garbage dump zone named "The Dump" + d{name="The Dump"} - #zone interrogation room - o{name=Interrogation assigned_unit=sheriff} + #zone interrogation room + o{name=Interrogation assigned_unit=sheriff} - #zone a small inactive pond zone - p{name="Fill me" pond=true active=false}(3x3) + #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) + #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) + #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. @@ -608,16 +608,16 @@ 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) + #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) + #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. @@ -631,7 +631,7 @@ 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{properties}:configuration(expansion) You're already familiar with `Property syntax`_ and `Area expansion syntax`_, so let's focus in on the remaining elements. @@ -646,8 +646,8 @@ Although it is perfectly valid to declare a single-purpose stockpile, example, to declare a 20x10 stockpile that accepts both corpses and refuse, you could write:: - #place refuse heap - yr(20x10) + #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`). It is more efficient, though, to place @@ -708,6 +708,57 @@ tiles:: #place f10(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 ----------- @@ -724,17 +775,17 @@ Other than names, most buildings do not have any extra properties. See the The syntax otherwise looks just like stockpiles, except that it only makes sense to have a single symbol to indicate what to build on that tile:: - symbol{properties}:configuration(expansion) + symbol{properties}:configuration(expansion) Here's an example of a simple 5x5 square of flooring:: - #build - Cf(5x5) + #build + Cf(5x5) or a named Jeweler's workshop that takes from specific stockpiles:: - #build - wj{name="Encrusting center" take_from="Furniture,Gem storage"} + #build + wj{name="Encrusting center" take_from="Furniture,Gem storage"} The ``:configuration`` part is only relevant for hauling routes, which we'll go over in the next section. @@ -754,10 +805,10 @@ 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"} + #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 @@ -771,14 +822,14 @@ propertly. 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 + #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. @@ -787,10 +838,10 @@ 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"} + #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. @@ -803,16 +854,16 @@ 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 +- 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 + #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 @@ -820,11 +871,11 @@ 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 new pastures) + #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: @@ -851,11 +902,11 @@ the task of blueprint alignment. This is very helpful for blueprints that are based on a central staircase, but it comes in handy whenever a blueprint has an obvious "center". For example:: - #build start(2;2;center of workshop) label(masonw) a mason workshop - wm wm wm # - wm wm wm # - wm wm wm # - # # # # + #build start(2;2;center of workshop) label(masonw) a mason workshop + wm wm wm # + wm wm wm # + wm wm wm # + # # # # will build the workshop *centered* on the cursor, not down and to the right of the cursor. @@ -870,8 +921,8 @@ don't actually care where the cursor is, but that refer to other blueprints that have fully-specified ``start()`` markers. For example, a meta blueprint that refers to the ``masonw`` blueprint above could look like this:: - #meta start(center of workshop) a mason workshop - /masonw + #meta start(center of workshop) a mason workshop + /masonw You can use semicolons, commas, or spaces to separate the elements of the ``start()`` marker, whatever is most convenient. @@ -898,8 +949,8 @@ 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" + "#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 @@ -936,14 +987,14 @@ references them. A few examples might make this clearer. Say you have a .csv file with blueprints that prepare bedrooms for your dwarves:: - #dig label(bed1) dig out the rooms - ... - #zone label(bed2) declare bedroom zones - ... - #place label(bed3) add food stockpiles - ... - #build label(bed4) build the furniture - ... + #dig label(bed1) dig out the rooms + ... + #zone label(bed2) declare bedroom zones + ... + #place label(bed3) add food stockpiles + ... + #build label(bed4) build the furniture + ... Note how I've given them all labels so we can address them safely. If I hadn't given them labels, they would receive default labels of "1", "2", "3", etc, but @@ -955,10 +1006,10 @@ label name that isn't going to change over time. So let's add a meta blueprint to this file that will combine the last three blueprints into one:: - "#meta label(bed234) combines zone, place, and build blueprints" - /bed2 - /bed3 - /bed4 + "#meta label(bed234) combines zone, place, and build blueprints" + /bed2 + /bed3 + /bed4 Now your sequence is shortened to: @@ -988,24 +1039,24 @@ dig_bedrooms one #dig blueprint, no label We can add a sheet named "dig_all" with the following contents (we're expecting a big fort, so we're digging 5 levels of bedrooms):: - #meta label(dig_it) dig the whole fortress - dig_farming/1 - #> - dig_industry/1 - #> - dig_dining/main - #> - dig_dining/basement - #> - dig_dining/waterway - #> - dig_dining/cistern - #> - dig_guildhall/1 - #> - dig_suites/1 - #> - dig_bedrooms/1 repeat(down 5) + #meta label(dig_it) dig the whole fortress + dig_farming/1 + #> + dig_industry/1 + #> + dig_dining/main + #> + dig_dining/basement + #> + dig_dining/waterway + #> + dig_dining/cistern + #> + dig_guildhall/1 + #> + dig_suites/1 + #> + dig_bedrooms/1 repeat(down 5) Note that for blueprints without an explicit label, we still need to address them by their auto-generated numeric label. @@ -1147,18 +1198,18 @@ convenient for long messages or messages that span many lines. The lines in a 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. + "#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" + 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 + #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... + 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 @@ -1197,38 +1248,38 @@ than a directory of files. For example, you can write multiple blueprints in one file like this:: - #dig label(bed1) - d d d d # - d d d d # - d d d d # - d d d d # - # # # # # - #zone label(bed2) - b(4x4) # + #dig label(bed1) + d d d d # + d d d d # + d d d d # + d d d d # + # # # # # + #zone label(bed2) + b(4x4) # + # + # + # + # # # # # + #place label(bed3) + # + f(2x2) # + # # - # - # - # # # # # - #place label(bed3) - # - f(2x2) # - # - # - # # # # # - #build label(bed4) - b f h # - # - # - t c # - # # # # # + # # # # # + #build label(bed4) + b f h # + # + # + t c # + # # # # # Of course, you could still choose to keep your blueprints in separate files and just give related blueprints similar names:: - bedroom.1.dig.csv - bedroom.2.zone.csv - bedroom.3.place.csv - bedroom.4.build.csv + bedroom.1.dig.csv + bedroom.2.zone.csv + bedroom.3.place.csv + bedroom.4.build.csv The naming and organization is completely up to you. @@ -1296,11 +1347,11 @@ Extra Manager Orders In ``#build`` blueprints, there are a few building types that will generate extra manager orders for related materials: -- Track stops will generate an order for a minecart -- Traction benches will generate orders for a table, mechanism, and rope -- Levers will generate an order for an extra two mechanisms for connecting the - lever to a target -- Cage traps will generate an order for a cage +- Track stops will generate an order for a minecart +- Traction benches will generate orders for a table, mechanism, and rope +- Levers will generate an order for an extra two mechanisms for connecting the + lever to a target +- Cage traps will generate an order for a cage Stockpiles in ``#place`` blueprints that `specify wheelbarrow or container @@ -1310,28 +1361,28 @@ number of bins, pots, or wheelbarrows. Tips and tricks --------------- -- After digging out an area, you may wish to smooth and/or engrave the area - before starting the build phase, as dwarves may be unable to access walls or - floors that are behind/under built objects. - -- If you are designating more than one level for digging at a time, you can - make your miners more efficient by using marker mode on all levels but one. - This prevents your miners from digging out a few tiles on one level, then - running down/up the stairs to do a few tiles on an adjacent level. With only - one level "live" and all other levels in marker mode, your miners can - concentrate on one level at a time. You just have to remember to "unmark" a - new level when your miners are done with their current one. Alternately, if - you have a chokepoint between levels (e.g. a central staircase), you can set - the chokepoint to be dug at a lower priority than all the other tiles on the - level. This will ensure your miners complete digging out a level before - continuing on to the next. - -- As of DF 0.34.x, it is no longer possible to build doors at the same time - that you build adjacent walls. Doors must now be built *after* adjacent - walls are constructed. This does not affect the more common case where walls - exist as a side-effect of having dug-out a room in a ``#dig`` blueprint, but - if you are building your own walls, be aware that walls must be built before - you run the blueprint to designate attached doors. +- After digging out an area, you may wish to smooth and/or engrave the area + before starting the build phase, as dwarves may be unable to access walls or + floors that are behind/under built objects. + +- If you are designating more than one level for digging at a time, you can + make your miners more efficient by using marker mode on all levels but one. + This prevents your miners from digging out a few tiles on one level, then + running down/up the stairs to do a few tiles on an adjacent level. With only + one level "live" and all other levels in marker mode, your miners can + concentrate on one level at a time. You just have to remember to "unmark" a + new level when your miners are done with their current one. Alternately, if + you have a chokepoint between levels (e.g. a central staircase), you can set + the chokepoint to be dug at a lower priority than all the other tiles on the + level. This will ensure your miners complete digging out a level before + continuing on to the next. + +- As of DF 0.34.x, it is no longer possible to build doors at the same time + that you build adjacent walls. Doors must now be built *after* adjacent + walls are constructed. This does not affect the more common case where walls + exist as a side-effect of having dug-out a room in a ``#dig`` blueprint, but + if you are building your own walls, be aware that walls must be built before + you run the blueprint to designate attached doors. - Quickfort is a very powerful tool. See the `case study ` below for more ideas on how to build awesome blueprints! @@ -1339,16 +1390,16 @@ Tips and tricks Caveats and limitations ----------------------- -- Weapon traps and upright spear/spike traps can currently only be built with a - single weapon. +- Weapon traps and upright spear/spike traps can currently only be built with a + single weapon. -- Pressure plates can be built, but they cannot be usefully configured yet. +- Pressure plates can be built, but they cannot be usefully configured yet. -- Building instruments is not yet supported. +- Building instruments is not yet supported. -- DFHack Quickfort is a large project, and there are bound to be bugs! If you - run into any, please report them at the :issue:`DFHack issue tracker <>` so - they can be addressed. +- DFHack Quickfort is a large project, and there are bound to be bugs! If you + run into any, please report them at the :issue:`DFHack issue tracker <>` so + they can be addressed. .. _dreamfort-case-study: @@ -1376,9 +1427,9 @@ Dreamfort blueprint set. Then we'll walk through the spreadsheets for each of the fort levels in turn, calling out feature usage examples and explaining the parts that might not be obvious just from looking at them. -If you haven't built Dreamfort before, maybe try an embark in a flat area and -take it for a spin! It will help put the following sections in context. There is -also a pre-built Dreamfort available for download on +If you haven't built Dreamfort before, maybe try an embark in a relatively flat +area and take it for a spin! It will help put the following sections in +context. There is also a pre-built Dreamfort available for download on :dffd:`dffd <15434>` if you just want an interactive reference. Dreamfort organization and packaging @@ -1388,9 +1439,9 @@ The Dreamfort blueprints are distributed with DFHack as :source:`one large .csv file `, but editing in that format would be frustrating. Instead, the blueprints are edited `online as Google drive spreadsheets -`__. +`__. Either the .csv file or the .xlsx files can be read and applied by quickfort, -but it made more sense to distribute the blueprints as a .csv so users would +but it made more sense to distribute the blueprints as a .csv so players would only have to remember one filename. Also, .csv files are text-based, which works more naturally with the DFHack source control system. We use the `xlsx2csv `__ utility to do the conversion @@ -1406,7 +1457,7 @@ walkthrough and other useful details. This is the first sheet in each spreadsheet so it will be selected by default if the user doesn't specify a label name. For example, just running ``quickfort run library/dreamfort.csv`` will display Dreamfort's `introduction text -`__. +`__. Do not neglect writing the help text! Not only will it give others a chance to use your blueprints appropriately, but the help you write will remind *you* what @@ -1415,11 +1466,11 @@ you were thinking when you wrote the blueprint in the first place. The surface_ level: how to manage complexity ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. _surface: https://docs.google.com/spreadsheets/d/1vlxOuDOTsjsZ5W45Ri1kJKgp3waFo8r505LfZVg5wkU +.. _surface: https://docs.google.com/spreadsheets/d/17HfnCJY4WDPlLdiLuUNc0gwyf6BiSdayndjvFYXzS7c -.. image:: https://drive.google.com/uc?export=download&id=1YL_vQJLB2YnUEFrAg9y3HEdFq3Wpw9WP +.. image:: https://drive.google.com/uc?export=download&id=1dlu3nmwQszav-ZaTx-ac28wrcaYBQc_t :alt: Annotated screenshot of the dreamfort surface level - :target: https://drive.google.com/file/d/1YL_vQJLB2YnUEFrAg9y3HEdFq3Wpw9WP + :target: https://drive.google.com/file/d/1dlu3nmwQszav-ZaTx-ac28wrcaYBQc_t :align: center For smaller blueprints, packaging and usability are not really that important - @@ -1427,9 +1478,9 @@ just write it, run it, and you're done. However, as your blueprints become larger and more detailed, there are some best practices that can help you deal with the added complexity. Dreamfort's surface level is many steps long since there are trees to be cleared, holes to be dug, flooring to be laid, and -bridges to be built, and each step requires the previous step to be completely -finished before it can begin. Therefore, a lot of thought went into minimizing -the toil associated with applying so many blueprints. +bridges to be linked to control levers, and each step requires the previous +step to be completely finished before it can begin. Therefore, a lot of thought +went into minimizing the toil associated with applying so many blueprints. .. topic:: Tip @@ -1440,13 +1491,13 @@ The single most effective way to make your blueprint sets easier to use is to group them with `meta blueprints `. For the Dreamfort set of blueprints, each logical "step" generally takes more than one blueprint. For example, with ``#meta`` blueprints, setting up pastures with a ``#zone`` -blueprint, placing starting stockpiles with a ``#place`` blueprint, building -starting workshops with a ``#build`` blueprint, and configuring the stockpiles -with a ``#query`` blueprint can all be done with a single command. Bundling -blueprints with ``#meta`` blueprints reduced the number of steps in Dreamfort -from 61 to 30, and it also made it much clearer to see which blueprints can be -applied at once without unpausing the game. Check out dreamfort_surface's "`meta -`__" +blueprint, placing starting stockpiles with a ``#place`` blueprint, and building +starting workshops with a ``#build`` blueprint can all be done with a single +command. Bundling blueprints with ``#meta`` blueprints reduced the number of +steps in Dreamfort from 100 to about 25, and it also made it much clearer to +see which blueprints can be applied at once without unpausing the game. Check +out dreamfort_surface's "`meta +`__" sheet to see how much meta blueprints can simplify your life. You can define `as many blueprints as you want ` on one @@ -1458,25 +1509,27 @@ having a bird's eye view of your entire plan in one sheet. Keep the blueprint list uncluttered by using ``hidden()`` markers. If a blueprint is bundled into a meta blueprint, it does not need to appear in -the ``quickfort list`` output since you won't be running it directly. Add a -`hidden() marker ` to those blueprints to keep the list -output tidy. You can still access hidden blueprints with ``quickfort list ---hidden`` if you need to -- for example to reapply a partially completed -``#build`` blueprint -- but now they won’t clutter up the normal blueprint list. +the `gui/quickfort` blueprint load dialog or ``quickfort list`` output since +you won't be running it directly. Add a `hidden() marker ` to +those blueprints to keep the list output tidy. You can still access hidden +blueprints by toggling the "Hidden" setting in `gui/quickfort` or by passing the +``--hidden`` option to ``quickfort list`` if you need to, for example to +reapply a partially completed ``#build`` blueprint, but now they won’t clutter +up the normal blueprint list. .. topic:: Tip Name your blueprints with a common prefix so you can find them easily. This goes for both the file name and the `modeline label() `. -Searching and filtering is implemented for both the -``quickfort list`` command and the quickfort interactive dialog. If you give -related blueprints a common prefix, it makes it easy to set the filters to -display just the blueprints that you're interested in. If you have a lot of -blueprints, this can save you a lot of time. Dreamfort uses the level name as a -prefix for the labels, like "surface1", "surface2", "farming1", etc. So if I’m -in the middle of applying the surface blueprints, I’d set the filter to -``dreamfort surface`` to just display the relevant blueprints. +Searching and filtering is implemented for both `gui/quickfort` and the +``quickfort list`` command. If you give related blueprints a common prefix, it +makes it easy to set the filters to display just the blueprints that you're +interested in. If you have a lot of blueprints, this can save you a lot of +time. Dreamfort uses the level name as a prefix for the labels, like +"surface1", "surface2", "farming1", etc. So if I’m in the middle of applying +the surface blueprints, I’d set the filter to ``dreamfort surface`` to just +display the relevant blueprints. .. topic:: Tip @@ -1496,7 +1549,7 @@ sheet, like in surface's meta sheet. things to include in messages are: * The name of the next blueprint to apply and when to run it -* Whether ``quickfort orders`` should be run for the current or an upcoming step +* Whether orders should be generated for the current or an upcoming step * Any actions that you have to perform manually after running the blueprint, like assigning minecarts to hauling routes or pasturing animals in newly-created zones @@ -1505,136 +1558,96 @@ These things are just too easy to forget. Adding a ``message()`` can save you from time-wasting mistakes. Note that ``message()`` markers can still appear on the ``hidden()`` blueprints, and they'll still get shown when the blueprint is run via a ``#meta`` blueprint. For an example of this, check out the `zones -sheet `__ +sheet `__ where the pastures are defined. The farming_ level: fun with stockpiles ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. _farming: https://docs.google.com/spreadsheets/d/1iuj807iGVk6vsfYY4j52v9_-wsszA1AnFqoxeoehByg +.. _farming: https://docs.google.com/spreadsheets/d/1RZ67upSpQx7hX-AkqiFXVJl8o5GGdDX1WDOJNz-wOiA -.. image:: https://drive.google.com/uc?export=download&id=1fBC3G5Y888l4tVe5REAyAd_zeojADVme +.. image:: https://drive.google.com/uc?export=download&id=1vDaedLcgoexUdKREUz75ZXQi0ZSdwWwj :alt: Annotated screenshot of the dreamfort farming level - :target: https://drive.google.com/file/d/1fBC3G5Y888l4tVe5REAyAd_zeojADVme + :target: https://drive.google.com/file/d/1vDaedLcgoexUdKREUz75ZXQi0ZSdwWwj :align: center It is usually convenient to store closely associated blueprints in the same spreadsheet. The farming level is very closely tied to the surface because the -miasma vents dug on the surface have to perfectly line up with where waste -products are placed on the farming level. However, surface is a separate z-level +miasma vents dug on the surface have to perfectly line up with where rottables +can accumulate on the farming level. However, surface is a separate z-level and, more importantly, already has many many blueprints of its own. Farming is therefore split into a separate file. .. topic:: Tip - Automate stockpile chains when you can, and write ``message()`` reminders - when you can't. - -The farming level starts doing interesting things with ``#query`` blueprints and -stockpiles. Note the `careful customization -`__ of the food stockpiles and the -stockpile chains set up with the ``give*`` aliases. This is so when multiple -stockpiles can hold the same item, the largest can keep the smaller ones filled. -For example the ``give2up`` alias funnels seeds from the seeds feeder pile to -the container-enabled seed storage pile. If you have multiple stockpiles holding -the same type on different z-levels, though, this can be tricky to set up with a -blueprint. Here, the jugs and pots stockpiles must be manually linked to the -quantum stockpile on the industry level, since we can't know beforehand how many -z-levels away that is. Note how we call that out in the ``#query`` blueprint's -``message()``. + Automate stockpile chains with the ``take_from`` and ``give_to`` properties. + +The farming level starts doing interesting things with stockpiles in its +``#place`` blueprints. Note the `careful customization +`__ +of the food stockpiles and the stockpile chains set up with the ``take_from`` +and ``give_to`` properties. For example, the "Seeds" stockpile is set to +``link_only=true`` and the "Seeds feeder" stockpile has ``containers=0`` and +``give_to=Seeds``. This minimizes container churn for the common task of seed +recovery. When finding the named stockpiles to link, quickfort will search the +other stockpiles created in the same blueprint first. If no stockpiles by that +name are found, then existing stockpiles/workshops are searched. This is how +many of the stockpiles on this level are configured to take from the starter +stockpiles on the surface. .. topic:: Tip - Use aliases to set up hauling routes and quantum stockpiles. + Quantum stockpiles are super easy to define, if you want to use them. -Hauling routes are notoriously fiddly to set up, but they can be automated with -blueprints. Check out the Southern area of the ``#place`` and ``#query`` -blueprints for how the quantum refuse dump is configured with simple aliases -from the alias library. +Hauling routes are notoriously fiddly to set up by hand, but they can be easily +automated with blueprints. Check out the Southern area of the ``#place`` and +``#build`` blueprints for how the quantum refuse dump is configured with simple +``take_from`` and ``route`` properties attached to the track stop. -The industry_ level: when not to use aliases -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The industry_ level: advanced linking +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. _industry: https://docs.google.com/spreadsheets/d/1gvTJxxRxZ5V4vXkqwhL-qlr_lXCNt8176TK14m4kSOU +.. _industry: https://docs.google.com/spreadsheets/d/16nzXGrznQmtkrmQv7FeKsVYnv8SSA7eBl1M-97NmuQk -.. image:: https://drive.google.com/uc?export=download&id=1emMaHHCaUPcdRbkLQqvr-0ZCs2tdM5X7 +.. image:: https://drive.google.com/uc?export=download&id=1c8YTHxTgJY5tUII-BOWdLhmDFAHwIOEs :alt: Annotated screenshot of the dreamfort industry level - :target: https://drive.google.com/file/d/1emMaHHCaUPcdRbkLQqvr-0ZCs2tdM5X7 + :target: https://drive.google.com/file/d/1c8YTHxTgJY5tUII-BOWdLhmDFAHwIOEs :align: center -The industry level is densely packed and has more complicated examples of -stockpile configurations and quantum dumps. However, what I'd like to call out -first are the key sequences that are *not* in aliases. +The industry level is densely packed and has more intracate stockpile and +hauling route configuration. .. topic:: Tip - Don't use aliases for ad-hoc cursor movements. - -It may be tempting to put all query blueprint key sequences into aliases to make -them easier to edit, keep them all in one place, and make them reusable, but -some key sequences just aren't very valuable as aliases. - -`Check out `__ -the Eastern (goods) and Northern (stone and gems) quantum stockpiles -- cells -I19 and R10. They give to the jeweler's workshop to prevent the jeweler from -using the gems held in reserve for strange moods. The keys are not aliased since -they're dependent on the relative positions of the tiles where they are -interpreted, which is easiest to see in the blueprint itself. Also, if you move -the workshop, it's easier to fix the stockpile link right there in the blueprint -instead of editing a separate alias definition. + Name things. -There are also good examples in the ``#query`` blueprint for how to use the -``permit`` and ``forbid`` stockpile aliases. +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. .. topic:: Tip - Put all configuration that must be applied in a particular order in the - same spreadsheet cell. - -Most of the baseline aliases distributed with DFHack fall into one of three -categories: - -1. Make a stockpile accept only a particular item type in a category -2. Permit an item type, but do not otherwise change the stockpile configuration -3. Forbid an item type, but do not otherwise change the stockpile configuration - -If you have a stockpile that covers multiple tiles, it might seem natural to put -one alias per spreadsheet cell. The aliases still all get applied to the -stockpile, and with only one alias per cell, you can just type the alias name -and avoid having to use the messier-looking ``{aliasname}`` syntax:: + You can give to or take from multiple sources. - #place Declare a food stockpile - f(3x3) - #query Incorrectly configure a food stockpile to accept tallow and dye - tallow - permitdye +Some of the feeder stockpiles on this level are split up so that no one item +type can fill the whole pile. The track stops that drive the quantum stockpiles +have to take from all of them at once. When specifying multiple link targets +that have spaces in their names, remember to surround the whole list with +quotes. For example:: -However, in quickfort there are no guarantees about which cell will be -processed first. In the example above, we obviously intend for the food -stockpile to have tallow exclusively permitted, then to add dye. It could happen -that the two aliases are applied in the opposite order, though, and we'd end up -with dye being permitted, then everything (including dye) being forbidden, and, -finally, tallow being enabled. To make sure you always get what you want, write -order-sensitive aliases on the same line:: - - #place Declare a food stockpile - f(3x3) - #query Properly configure a food stockpile to accept tallow and dye - {tallow}{permitdye} - -You can see a more complex example of this with the ``meltables`` stockpiles in -the `lower left corner `__ -of the industry level. + #build + trackstopW{name="Goods/wood dumper" take_from="Wood feeder,Goods feeder,Furniture feeder" route="Goods/wood quantum"} The services_ level: handling multi-level dig blueprints ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. _services: https://docs.google.com/spreadsheets/d/1IBy6_pGEe6WSBCLukDz_5I-4vi_mpHuJJyOp2j6SJlY +.. _services: https://docs.google.com/spreadsheets/d/1xu8vNKGlGDN9L3MVB4qp2Ytef9oAWvuET6RkuZXmCaE -.. image:: https://drive.google.com/uc?export=download&id=13vDIkTVOZGkM84tYf4O5nmRs4VZdE1gh +.. image:: https://drive.google.com/uc?export=download&id=1RQMy_zYQWM5GN7-zjn6LoLWmnrJjkxPM :alt: Annotated screenshot of the dreamfort services level - :target: https://drive.google.com/file/d/13vDIkTVOZGkM84tYf4O5nmRs4VZdE1gh + :target: https://drive.google.com/file/d/1RQMy_zYQWM5GN7-zjn6LoLWmnrJjkxPM :align: center Services is a multi-level blueprint that includes a well cistern beneath the @@ -1646,27 +1659,31 @@ priorities `. Use dig priorities to control ramp creation. -We can `ensure `__ +We can `ensure `__ the bottom level is carved out before the layer above is channeled by assigning -the channel designations lower priorities (the ``h5``\s in the third layer -- -scroll down). +the channel designations lower priorities (the ``h5``\s in the lower layers -- +scroll down). This works here because there is only a single column of +higher-priority stairs for a dwarf to dig down to get below the lower-priority +channels. If the dig area has multiple tiles exposed, it is harder to control +dig order since a second dwarf may not have access to any higher-priority tiles +and may start digging the lower-priority designations prematurely. An alternative is to have a follow-up blueprint that removes any undesired ramps. We did this on the -`surface `__ +`surface `__ and -`farming `__ +`farming `__ levels with the miasma vents since it would be too complicated to synchronize -the digging between the two layers. +simultaneous digging of the two layers. The guildhall_ level: avoiding smoothing issues ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. _guildhall: https://docs.google.com/spreadsheets/d/1wwKcOpEW-v_kyEnFyXS0FTjvLwJsyWbCUmEGaXWxJyU +.. _guildhall: https://docs.google.com/spreadsheets/d/1DltZIHkw7zpNiQdSvXLcHdbwdttPwl35pVpBUYy90TA -.. image:: https://drive.google.com/uc?export=download&id=17jHiCKeZm6FSS-CI4V0r0GJZh09nzcO_ +.. image:: https://drive.google.com/uc?export=download&id=1mt66QOkfBqFLtw6AJKU6GNYmhB72XSJG :alt: Annotated screenshot of the dreamfort guildhall level - :target: https://drive.google.com/file/d/17jHiCKeZm6FSS-CI4V0r0GJZh09nzcO_ + :target: https://drive.google.com/file/d/1mt66QOkfBqFLtw6AJKU6GNYmhB72XSJG :align: center The goal of this level is to provide rooms for ``locations`` like guildhalls, @@ -1685,24 +1702,65 @@ blocks a corner, or if a line of statues blocks a wall segment, it forces the player to smooth before building the statues. Otherwise they have to bother with temporarily removing statues to smooth the walls behind them. -The beds_ levels: multi level meta blueprints -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The suites_ level: balance of flexibility +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. _beds: https://docs.google.com/spreadsheets/d/1QNHORq6YmYfuVVMP5yGAFCQluary_JbgZ-UXACqKs9g +.. _suites: https://docs.google.com/spreadsheets/d/1pZ5mnYzzYLSni-LA3rfHZ6dFX8n7rTW088iBwsCI7N4 -.. image:: https://drive.google.com/uc?export=download&id=1IBqCf6fF3lw7sHiBE_15Euubysl5AAiS +.. image:: https://drive.google.com/uc?export=download&id=16XRb1w5zFoyVq2LBMx_aCwOyjFq7GULc :alt: Annotated screenshot of the dreamfort noble suites - :target: https://drive.google.com/file/d/1IBqCf6fF3lw7sHiBE_15Euubysl5AAiS + :target: https://drive.google.com/file/d/16XRb1w5zFoyVq2LBMx_aCwOyjFq7GULc :align: center -.. image:: https://drive.google.com/uc?export=download&id=1mDQQXG8BnXqasRGFC9R5N6xNALiswEyr +In designing this level, we needed to choose between two approaches: + +1. Create rooms with specific, pre-determined purposes, laying out furniture + and zoning with appropriate types +#. Lay out each room the same so each can serve any purpose + +Each has pros and cons. The first option reduces more toil by pre-creating the +zones. If we go this route, we can also auto-assign the rooms to the various +roles (if they exist when the blueprint is run). Each room can be customized +for its intended purpose: offices can look like offices, bedrooms could look +like bedrooms, and so on. However, if the needs of the fort don't correspond to +the pre-determined layouts, or if the needs of the fort *change* significantly, +then the blueprint can become more of a hinderance than a help. + +As you can see from the screenshot, we went with option 2. The ability to +re-zone arbitrarily to meet changing noble needs was too great of a benefit to +ignore. The downside, of course, is that you have to zone and assign your own +rooms. However, as soon as you gain a barony or a duchy, you'd be doing that +anyway with option 1. + +With option 2, if you need a "better" bedroom, you'd just expand the zone to +cover the neighboring "unit". Satisfying the monarch is also simple: plop down +a new suites level and assign each block of 4 rooms to one zone. four units for +the bedroom, four for the office, four for the dining hall, and four for the +tomb. Smooth and engrave and you're done. Of course, more asthetic-minded +players are always free to design custom areas too. These blueprints are +designed to be functional more than beautiful. + +The beds_ and crypt_ levels: copy and paste and repeat +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _beds: https://docs.google.com/spreadsheets/d/1pZ5mnYzzYLSni-LA3rfHZ6dFX8n7rTW088iBwsCI7N4 + +.. _crypt: https://docs.google.com/spreadsheets/d/1yTr48EFgXIoswhzL2RXpzUBvY8Sa-XKEacf6zXriZvM + +.. image:: https://drive.google.com/uc?export=download&id=16-NXlodLIQjeZUMSmsWRafeytwU2dXQo :alt: Annotated screenshot of the dreamfort apartments - :target: https://drive.google.com/file/d/1mDQQXG8BnXqasRGFC9R5N6xNALiswEyr + :target: https://drive.google.com/file/d/16-NXlodLIQjeZUMSmsWRafeytwU2dXQo + :align: center + +.. image:: https://drive.google.com/uc?export=download&id=16iT_ho7BIRPD_eofuxdlVQ4FunR1Li23 + :alt: Annotated screenshot of the dreamfort crypt + :target: https://drive.google.com/file/d/16iT_ho7BIRPD_eofuxdlVQ4FunR1Li23 :align: center -The suites and apartments blueprints are straightforward. The only fancy bit -is the meta blueprint that digs the stack of apartment levels, which brings us -to our final tip: +The apartments and crypt blueprints are straightforward, other than the sheer +number of zones. Copy-paste in Google Sheets was used heavily here. The only +fancy bit is the meta blueprint that digs the stack of apartment levels, which +brings us to our final tip: .. topic:: Tip @@ -1713,36 +1771,36 @@ aquifer between the farming and industry levels, and we can't know beforehand how many z-levels we need to skip. We can, however, automate the digging of everything from the industry level down, including designating all apartment levels at once. See the -`#meta `__ +`#meta `__ blueprint in the `Dreamfort help spreadsheet -`__ +`__ for how it uses a ``repeat()`` marker for the ``/apartments1`` blueprint to -apply it to five z-levels at once. +apply it to three z-levels at once. That's it! I hope this guide was useful to you. Please leave feedback on the -forums if you have ideas on how this guide (or the dreamfort blueprints) can be -improved! +forums or on the DFHack Discord server if you have ideas on how this guide (or +the dreamfort blueprints themselves) can be improved! Links ----- **Quickfort links:** -- `Quickfort command reference ` -- `blueprint-library-guide` -- :forums:`Quickfort forum thread <176889>` -- :issue:`DFHack issue tracker <>` -- :source:`Blueprint library source ` -- :source-scripts:`Quickfort source code ` +- `Quickfort command reference ` +- `blueprint-library-guide` +- :forums:`Quickfort forum thread <176889>` +- :issue:`DFHack issue tracker <>` +- :source:`Blueprint library source ` +- :source-scripts:`Quickfort source code ` **Related tools:** -- DFHack's `blueprint plugin ` can generate blueprints from actual - DF maps. -- DFHack's `buildingplan plugin ` sets material and quality - constraints for quickfort-placed buildings. -- `Python Quickfort `__ is the previous, - Python-based implementation that DFHack's quickfort script was inspired by. +- DFHack's `blueprint plugin ` can generate blueprints from actual + DF maps. +- DFHack's `buildingplan plugin ` sets material and quality + constraints for quickfort-placed buildings. +- `Python Quickfort `__ is the previous, + Python-based implementation that DFHack's quickfort script was inspired by. .. _quickfort_guide_appendix: @@ -1952,9 +2010,11 @@ Property Description In addition to the type-specific properties listed below, all building types accept the ``name`` property. -Moreover, all workshops and furnaces accept ``take_from`` and ``give_to`` -properties, which are comma-separated lists of names (the same as the -correponding stockpile properties above). +Moreover, all workshops and furnaces accept the ``max_general_orders`` +property, which sets the maximum number of general workorders that the building +can accept, and the ``take_from`` and ``give_to`` properties, which are +comma-separated lists of names (the same as the correponding stockpile +properties above). ================= ============================= ========== Symbol Type Properties