MetzNet
/
dfhack
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'myk002/quickfort_case_study' into develop

develop
lethosor 2020-10-08 01:01:37 -04:00
parent 6d18ef865d 3e2dd2a396
commit f54eb9627d
No known key found for this signature in database
GPG Key ID: 76A269552F4F58C1
2 changed files with 283 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
CMakeLists.txt
Unescape Escape View File

@ -442,6 +442,7 @@ if(BUILD_DOCS)
file(GLOB SPHINX_DEPS
"${CMAKE_CURRENT_SOURCE_DIR}/docs/*.rst"
"${CMAKE_CURRENT_SOURCE_DIR}/docs/guides/*.rst"
"${CMAKE_CURRENT_SOURCE_DIR}/docs/changelog.txt"
"${CMAKE_CURRENT_SOURCE_DIR}/docs/gen_changelog.py"
"${CMAKE_CURRENT_SOURCE_DIR}/docs/images/*.png"

286
docs/guides/quickfort-user-guide.rst
Unescape Escape View File

@ -861,10 +861,11 @@ blueprint packages follow this pattern:
Those three "apply"s in the middle might as well get done in one command instead
of three. A meta blueprint can encode that sequence. A meta blueprint refers to
other blueprints by their label (see the `Modeline markers <modeline-markers>`__
section above) in the same format used by the ``DFHack#`` quickfort command:
"/", or just "/" for blueprints in .csv files or blueprints in the same
spreadsheet sheet as the #meta blueprint that references them.
other blueprints by their label (see the `Modeline markers
<#modeline-markers>`__ section above) in the same format used by the ``DFHack#``
quickfort command: ``<sheet name>/<label>``, or just ``/<label>`` for blueprints
in .csv files or blueprints in the same spreadsheet sheet as the ``#meta``
blueprint that references them.
A few examples might make this clearer. Say you have a .csv file with the "bed"
blueprints in the previous section:
@ -1119,6 +1120,283 @@ Caveats and limitations
- This script is relatively new, and there are bound to be bugs! Please report
them at the :issue:`DFHack issue tracker <>` so they can be addressed.
Dreamfort case study: a practical guide to advanced blueprint design
--------------------------------------------------------------------
While syntax definitions and toy examples will certainly get you started with
your blueprints, it may not be clear how all the quickfort features fit together
or what the best practices are, especially for large and complex blueprint sets.
This section walks through the "Dreamfort" blueprints found in the DFHack
blueprint library, highlighting design choices and showcasing practical
techniques that can help you create better blueprints. Note that this is not a
guide for how to design the best forts (there is plenty about that `on the wiki
<http://dwarffortresswiki.org/index.php?title=Design_strategies>`__). This is
essentially an extended tips and tricks section focused on how to make usable
and useful quickfort blueprints that will save you time and energy.
The Dreamfort blueprints we'll be discussing are available in the library as
:source:`one large .csv file <data/blueprints/library/dreamfort.csv>`
or `online
<https://drive.google.com/drive/folders/1iS90EEVqUkxTeZiiukVj1pLloZqabKuP>`__ as
individual spreadsheets. Either can be read and applied by quickfort, but for us
humans, the online spreadsheets are much easier to work with. Each spreadsheet
has a "Notes" sheet with some useful details. Flip through some of the
spreadsheets and read the `walkthrough
<https://docs.google.com/spreadsheets/d/
13PVZ2h3Mm3x_G1OXQvwKd7oIR2lK4A1Ahf6Om1kFigw/edit#gid=0>`__ to get oriented.
Also, if you haven't built Dreamfort before, try an embark in a flat area and
take it for a spin!
Almost every quickfort feature is used somewhere in Dreamfort, so the blueprints
as a whole are useful as practical examples. You can copy the blueprints and use
them as starting points for your own, or just refer to them when you create
something similar.
In this case study, we'll start by discussing the high level organization of the
Dreamfort blueprint set, using the "surface" blueprints as an example. Then
we'll walk through the blueprints for each of the remaining fort levels in turn,
calling out feature usage examples and explaining the parts that might not be
obvious just from looking at them.
The surface_ level: how to manage complexity
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. _surface: https://docs.google.com/spreadsheets/d/1vlxOuDOTsjsZ5W45Ri1kJKgp3waFo8r505LfZVg5wkU/edit?usp=sharing
For smaller blueprints, packaging and usability are not really that important -
just write it, run it, and you're done. However, as your blueprints become
larger and more detailed, there are some best practices that can help you deal
with the added complexity. Dreamfort's surface level is many steps long since
there are trees to be cleared, holes to be dug, flooring to be laid, and
furniture 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.
.. topic:: Tip
Use meta blueprints to script blueprint sequences and reduce the number of
quickfort commands you have to run.
The single most effective way to make your blueprint sets easier to use is to
group them with `meta blueprints <#meta-blueprints>`__. For the Dreamfort set of
blueprints, each logical "step" generally takes more than one blueprint. For
example, 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 at once. Bundling blueprints like this reduced the number of
steps in Dreamfort from 47 to 24, 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
<https://docs.google.com/spreadsheets/d/
1vlxOuDOTsjsZ5W45Ri1kJKgp3waFo8r505LfZVg5wkU/edit#gid=972927200>`__" sheet to
see how much meta blueprints can simplify your life.
Note that one of the ``#meta`` blueprints just has one line. In this case, the
``#meta`` blueprint isn't strictly necessary. The referenced blueprint could
just be applied directly. However, quickfort lists blueprints in the order that
it reads them, and we chose to make a one-blueprint meta blueprint to ensure all
the steps appear in order in the quickfort list output.
By the way, you can define `as many blueprints as you want
<#packaging-a-set-of-blueprints>`__ on one sheet, but multi-blueprint sheets are
especially useful when writing meta blueprints. It's like having a bird's eye
view of your entire plan in one sheet.
.. topic:: Tip
Keep the blueprint list uncluttered with 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 <#hiding-blueprints>`__ 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.
.. 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()
<#blueprint-labels>`__. 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, of course, uses the
"dreamfort" prefix for the files and sequence names 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
Add descriptive comments that remind you what the blueprint contains.
If you've been away from Dwarf Fortress for a while, it's easy to forget what
your blueprints actually do. Make use of `modeline comments
<#modeline-markers>`__ so your descriptions are visible in the blueprint list.
If you use meta blueprints, all your comments can be conveniently edited on one
sheet, like in surface's meta sheet.
.. topic:: Tip
Use message() markers to remind yourself what to do next.
`Messages <#messages>`__ are displayed after a blueprint is applied. Good things
to include in messages are:
* The name of the next blueprint to apply and when to run it
* Whether quickfort orders should be run for an upcoming step
* Any manual actions that have to happen, like assigning minecarts to hauling
routes or pasturing animals after creating zones
These things are just too easy to forget. Adding a message() can save you from
time-wasting mistakes. Note that message() markers can still appear on the
hidden() blueprints, and they'll still get shown when the blueprint is run via
the ``#meta`` blueprint. For an example of this, check out the `zones sheet
<https://docs.google.com/spreadsheets/d/
1vlxOuDOTsjsZ5W45Ri1kJKgp3waFo8r505LfZVg5wkU/edit#gid=1226136256>`__ where the
pastures are defined.
The farming_ level: fun with stockpiles
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. _farming: https://docs.google.com/spreadsheets/d/1iuj807iGVk6vsfYY4j52v9_-wsszA1AnFqoxeoehByg/edit?usp=sharing
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 have to perfectly line up. However, surface is a separate z-level
and, more importantly, already has many many blueprints, so farming is 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
<https://docs.google.com/spreadsheets/d/1iuj807iGVk6vsfYY4j52v9_-
wsszA1AnFqoxeoehByg/edit#gid=486506218>`__ 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.
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().
.. topic:: Tip
Use aliases to set up hauling routes and quantum stockpiles.
Hauling routes are notoriously fiddly to set up, but they can be automated with
blueprints. Check out the Southern area of the ``#place`` and ``#query``
blueprints for how the quantum garbage dump is configured.
Note that aliases that must be applied in a particular order must appear in the
same cell. Otherwise there are no guarantees for which cell will be processed
first. For example, look at the track stop cells in the ``#query`` blueprint for
how the hauling routes are given names.
The industry_ level: when not to use aliases
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. _industry: https://docs.google.com/spreadsheets/d/1gvTJxxRxZ5V4vXkqwhL-qlr_lXCNt8176TK14m4kSOU/edit?usp=sharing
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
are the key sequences that are *not* in aliases.
.. 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 <https://docs.google.com/spreadsheets/d/1gvTJxxRxZ5V4vXkqwhL-
qlr_lXCNt8176TK14m4kSOU/edit#gid=787640554>`__ 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 the separate
aliases.txt file.
The services_ level: handling multi-level dig blueprints
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. _services: https://docs.google.com/spreadsheets/d/1IBy6_pGEe6WSBCLukDz_5I-4vi_mpHuJJyOp2j6SJlY/edit?usp=sharing
Services is a multi-level blueprint that includes a well cistern beneath the
main level. Unwanted ramps caused by channeling are an annoyance, but we can
avoid getting a ramp at the bottom of the cistern with careful use of `dig
priorities <#dig-priorities>`__.
.. topic:: Tip
Use dig priorities to control ramp creation.
We can `ensure <https://docs.google.com/spreadsheets/d/1IBy6_pGEe6WSBCLukDz_5I-
4vi_mpHuJJyOp2j6SJlY/edit#gid=962076234>`__ the bottom level is carved out
before the layer above is channelled by assigning the channel designations lower
priorities (row 76). This is easy to do here because it's just one tile and
there is no chance of cave-in. We could have used this technique on the farming
level for the miasma vents instead of requiring that the channels be dug before
the farming level is dug, but that would have been much more fiddly for the
larger areas.
The alternative is just to have a follow-up blueprint that removes any undesired
ramps. Using dig priorities to avoid the issue in the first place can be
cleaner, though.
The guildhall_ level: avoiding smoothing issues
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. _guildhall: https://docs.google.com/spreadsheets/d/1wwKcOpEW-v_kyEnFyXS0FTjvLwJsyWbCUmEGaXWxJyU/edit?usp=sharing
The goal of this level is to provide rooms for locations like guildhalls,
libraries, and temples. The value of these rooms is very important, so we are
likely to smooth and engrave everything. To smooth or engrave a wall tile, a
dwarf has to be adjacent to it, and since some furniture, like statues, block
dwarves from entering a tile, where you put them affects what you can access.
.. topic:: Tip
Don't put statues in corners unless you want to smooth everything first.
In the guildhall level, the statues are placed so as not to block any wall
corners. This gives the player freedom for choosing when to smooth. If statues
block wall segments, it forces the player to smooth before building the statues,
or else they have to mess with temporarily removing statues to smooth the walls
behind them.
The beds_ levels: multi level meta blueprints
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. _beds: https://docs.google.com/spreadsheets/d/1QNHORq6YmYfuVVMP5yGAFCQluary_JbgZ-UXACqKs9g/edit?usp=sharing
The suites and apartments blueprints are straightforward. The only fancy bit
here is the meta blueprint, which brings us to our final tip:
.. topic:: Tip
Use meta blueprints to lay out multiple adjacent levels.
We couldn't use this technique for the entire fortress since there is often an
aquifer between the farming and industry levels, and we can't know beforehand
how many z-levels we need to skip. Here, though, we can at least provide the
useful shortcut of designating all apartment levels at once. See the meta
blueprint for how it applies the apartments on six z-levels using ``#>`` between
apartment blueprint references.
That's it! I hope this guide was useful to you. Please leave feedback on the
forums if you have ideas on how this guide (or the dreamfort blueprints) can be
improved!
Links
-----