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

develop
lethosor 2020-10-27 23:45:39 -04:00
commit 64114551dd
No known key found for this signature in database
GPG Key ID: 76A269552F4F58C1
4 changed files with 167 additions and 86 deletions

@ -1070,7 +1070,7 @@ query_stockpiles/farming_query_stockpiles
,,,,,,,,,,,,,,,,,,,,,bodyparts,linksonly,`,,`,`,`,`,`,`,`,`,`,`,`,`,`,`
,,,,,,,,,,,,,,,,,,,,,`,`,`,`,give2left,`,`,`,`,`,`,`,`,`,`,`,`,`
,,,,,,,,,,,,,,,,,,,,,`,`,`,,`,`,`,`,`,`,`,`,`,`,`,`,`,`
,,,,,,,,,,,,,,,,,,,,,,{quantumstopfromnorth}{namelastrouteprefix}Trash Dumper{namelastroutesuffix},,,`,`,`,`,`,`,`,`,`,`,`,`,`,`
,,,,,,,,,,,,,,,,,,,,,,"{quantumstopfromnorth name=""Trash Dumper""}",,,`,`,`,`,`,`,`,`,`,`,`,`,`,`
,,,,,,,,,,,,,,,,,,,,,,quantum,,,`,`,`,`,`,`,`,`,`,`,`,`,`,`
@ -1279,7 +1279,7 @@ query/industry_query
,,,,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`
,,,,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`
,,,,`,`,`,`,`,`,`,`,`,`,`,`,`,{quantum}g{Up}{Left 5}&,`,`,`,`,`,`,`,`,`,`,`,`,`
,,,,`,`,`,`,`,`,`,`,`,`,`,`,`,{quantumstopfromsouth}{namelastrouteprefix}Stoneworker quantum{namelastroutesuffix},`,`,`,`,`,`,`,`,`,`,`,`,`
,,,,`,`,`,`,`,`,`,`,`,`,`,`,`,"{quantumstopfromsouth name=""Stoneworker quantum""}",`,`,`,`,`,`,`,`,`,`,`,`,`
,,,,`,`,`,`,`,`,`,`,`,`,`,`,otherstone,,,`,`,`,`,`,`,`,`,`,`,`,`
,,miscliquid,`,`,`,`,`,`,`,`,`,`,`,`,`,~,nocontainers,~,`,`,`,`,`,`,`,`,`,`,`,`,`,steelbars
,,nocontainers,`,`,`,`,`,`,`,`,`,`,`,`,`,~,~,~,`,`,`,`,`,`,`,`,`,`,`,`,`,`
@ -1287,7 +1287,7 @@ query/industry_query
,,`,`,`,`,`,`,`,`,`,`,`,`,,,`,,`,,,`,`,`,`,`,`,`,`,`,`,`,`
,,`,`,`,`,`,`,`,`,`,`,`,`,,`,`,`,`,`,,`,`,`,`,`,`,`,`,`,`,`,`
,,`,`,`,`,`,`,`,`,{cages}{permittraps},,,`,`,`,,,,`,`,`,forbidotherstone,,,`,`,`,`,`,`,`,t{Left 6}{Down}&
,,`,`,`,`,`,`,{quantum}g{Up 10}{Right 4}&,{quantumstopfromeast}{namelastrouteprefix}Goods/Wood quantum{namelastroutesuffix},~,nocontainers,~,`,,`,,`,,`,,`,~,nocontainers,~,{quantumstopfromwest}{namelastrouteprefix}Metalworker quantum{namelastroutesuffix},quantum,`,`,`,`,`,`
,,`,`,`,`,`,`,{quantum}g{Up 10}{Right 4}&,"{quantumstopfromeast name=""Goods/Wood quantum""}",~,nocontainers,~,`,,`,,`,,`,,`,~,nocontainers,~,"{quantumstopfromwest name=""Metalworker quantum""}",quantum,`,`,`,`,`,`
,,`,`,`,`,`,`,`,`,{tallow}{permitdye},,,`,`,`,,,,`,`,`,forbidpotash,,,`,`,`,`,`,`,`,t{Left 6}{Up}&
,,`,`,`,`,`,`,`,`,`,`,`,`,,`,`,`,`,`,,`,`,`,`,`,`,`,`,`,`,`,`
,,`,`,`,`,`,`,`,`,`,`,`,`,,,`,,`,,,`,`,`,`,`,`,`,`,`,`,`,`
@ -1295,7 +1295,7 @@ query/industry_query
,,`,`,`,`,`,`,`,`,`,`,`,`,`,`,craftrefuse,,,`,`,`,`,`,`,`,`,`,`,`,`,`,`
,,`,`,`,`,`,`,`,`,`,`,`,`,`,`,~,nocontainers,~,`,`,`,`,`,`,`,`,`,`,`,`,`,coal
,,,,`,`,`,`,`,`,`,`,`,`,`,`,~,~,~,`,`,`,`,`,nocontainers,`,t{Up 7}&,~,~,~,~
,,,,`,`,`,`,`,`,`,`,`,`,`,`,`,{quantumstopfromnorth}{namelastrouteprefix}Clothier/Bones quantum{namelastroutesuffix},`,`,`,`,`,`,{ironweapons}{permitsteelweapons}{forbidmasterworkweapons}{forbidartifactweapons}
,,,,`,`,`,`,`,`,`,`,`,`,`,`,`,"{quantumstopfromnorth name=""Clothier/Bones quantum""}",`,`,`,`,`,`,{ironweapons}{permitsteelweapons}{forbidmasterworkweapons}{forbidartifactweapons}
,,,,`,`,`,`,`,`,`,`,`,`,`,`,`,quantum,`,`,`,`,`,`,{ironarmor}{permitsteelarmor},forbidmasterworkarmor,forbidartifactarmor,~,~,~,~
,,,,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`
,,,,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,nocontainers,give2up,t{Up 11}&,~,~,~,~
@ -1320,7 +1320,7 @@ Garbage dump
Manual steps you have to take:
"If you want to declare the dining room as a tavern, the bedrooms at the top can be assigned to the tavern as rented rooms."
"Configure the soap stockpiles to take from the industry level ""Metalworker"" quantum stockpile (which holds all the bars)"
"Convert the bath pit zones to pond zones when you are ready to fill them with 3-depth water. This is the only really fiddly bit, since you have to carefully disable the pond zone again when the final bucket to bring the water to an even 3-depth is on the way."
"Activate the bath pond zones when you are ready to fill them with 3-depth water. This is the only really fiddly bit, since you have to carefully disable the pond zone again when the final bucket to bring the water to an even 3-depth is on the way."
"Fill the cisterns with water, either with a bucket brigade or by plumbing flowing water. Fill so that there are two z-levels of 7-depth water. If you want to fill with buckets, designate a pond zone on the level below the main floor. If you feel adventurous and are experienced with water pressure, you can instead route (depressurized!) water to the second-to-bottom level (the one above the up staircases)."
"#dig label(services1) start(23; 22; staircase center) message(This would be a good time to queue manager orders for /services2. Once the area is dug out, continue with /services2.)"
@ -1533,7 +1533,7 @@ query_stockpiles/services_query_stockpiles
,,`,`,`,`,`,`,,`,`,`,`,`,`
#zone label(services_zone) start(23; 22) hidden() use the meta blueprints for normal application
#zone label(services_zone) start(23; 22) hidden() message(activate the bath pond zones when you are ready to fill them with 3-depth water) use the meta blueprints for normal application
,,`,`,`,,,`,`,`,,,`,`,`
@ -1554,9 +1554,9 @@ query_stockpiles/services_query_stockpiles
,,`,`,`,`,`,`,`,`,`,`,`,`,`,,,,`,`,`,`,`,`,`,`,`,,,,`,`,`,`,`,`,`,`,`
,,`,`,`,`,`,`,`,`,`,`,`,`,`,,,,,,,,`,,,,,,,,`,`,`,`,`,`,`,`,`
,,`,`,`,`,`,`,`,`,`,`,`,`,`,,`,`,`,,`,`,`,`,`,,`,`,`,,`,`,`,`,`,`,`,`,`
,,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,pa,`,`,`,`,`,`,`,`,`,pa,`,`,`,`,`,`,`,`,`,`,`
,,`,`,`,`,`,`,`,`,`,`,`,`,`,,`,pa,`,,`,`,`,`,`,,`,pa,`,,`,`,`,`,`,`,`,`,`
,,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,pa,`,`,`,`,`,`,`,`,`,pa,`,`,`,`,`,`,`,`,`,`,`
,,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,apPf(1x3),`,`,`,`,`,`,`,`,`,apPf(1x3),`,`,`,`,`,`,`,`,`,`,`
,,`,`,`,`,`,`,`,`,`,`,`,`,`,,`,~,`,,`,`,`,`,`,,`,~,`,,`,`,`,`,`,`,`,`,`
,,`,`,`,`,`,`,`,`,`,`,`,`,`,`,`,~,`,`,`,`,`,`,`,`,`,~,`,`,`,`,`,`,`,`,`,`,`
,,`,`,`,`,`,`,`,`,`,`,`,`,`,,`,`,`,,`,`,`,`,`,,`,`,`,,`,`,`,`,`,`,`,`,`
,,`,`,`,`,`,`,`,`,`,`,`,`,`,,,,,,,,d,,,,,,,,`,`,`,`,`,`,`,`,`
,,,,,,`,`,,`,`,,,,,,,,,,,,,,,,,,,,`,`,`,`,`,`,`,`,`

Can't render this file because it has a wrong number of fields in line 78.

@ -1,8 +1,8 @@
# Common baseline for aliases for quickfort query mode blueprints.
#
# Please DO NOT EDIT this file directly. Instead, custom aliases should be added
# to dfhack-config/quickfort/aliases.txt. See that file for syntax
# documentation.
# Please DO NOT EDIT this file directly. It will get overwritten when DFHack
# is updated. Instead, custom aliases should be added to
# dfhack-config/quickfort/aliases.txt. See that file for syntax documentation.
#
# The aliases in this file were tested in DF 0.47.04 on 2020 Jul 18.
#
@ -31,14 +31,15 @@ linksonly: a
nocontainers: CE
# for configuring stockpiles to give to other nearby stockpiles/workshops
give2up: g{Up 2}&
give2down: g{Down 2}&
give2left: g{Left 2}&
give2right: g{Right 2}&
give10up: g{Up 10}&
give10down: g{Down 10}&
give10left: g{Left 10}&
give10right: g{Right 10}&
give: g{move}&
give2up: {give move={Up 2}}
give2down: {give move={Down 2}}
give2left: {give move={Left 2}}
give2right: {give move={Right 2}}
give10up: {give move={Up 10}}
give10down: {give move={Down 10}}
give10left: {give move={Left 10}}
give10right: {give move={Right 10}}
# use to toggle a sequence of stockpile options. for example: {togglesequence 5}
togglesequence: &{Down}
@ -49,7 +50,7 @@ enablesequence: e{Down}
# clothes and armor in this quantum stockpile will rot away. If you want bones
# in your quantum stockpile, apply this alias to a refuse stockpile (but don't
# put useful clothes or armor in there!)
quantum: {linksonly}{nocontainers}{enableanimals}{enablefood}{furnitureprefix}{enablestone}{enableammo}{enablecoins}{enablebars}{enablegems}{enablefinishedgoods}{enableleather}{enablecloth}{enablewood}}{enableweapons}{enablearmor}{enablesheet}
quantum: {linksonly}{nocontainers}{enableanimals}{enablefood}{enablefurniture}{enablestone}{enableammo}{enablecoins}{enablebars}{enablegems}{enablefinishedgoods}{enableleather}{enablecloth}{enablewood}{enableweapons}{enablearmor}{enablesheet}
##################################
@ -58,25 +59,30 @@ quantum: {linksonly}{nocontainers}{enableanimals}{enablefood}{furnitureprefix}{e
# Run one of the quantumstopfrom* aliases over a track stop that is set to dump
# into a quantum stockpile. The alias will set up the stop to accept all types
# (the actual types stored in the quantum stockpile is controlled by the feeder
# stockpile) and link the indicated adjacent feeder stockpile (for example, the
# quantumstopfromsouth alias will link to a feeder stockpile to the South). All
# you need to do afterwards is assign a vehicle to the stop (and optionally
# give the route a name --see the namelastroute* aliases below). The track stop
# does not need to be constructed yet, but the feeder stockpile needs to exist
# so we can link it.
quantumstopprefix: ^hrs&xxx&{enablesequence 17}^
quantumstopfromeast: {quantumstopprefix}s{Right}p^{Left}^q
quantumstopfromsouth: {quantumstopprefix}s{Down}p^{Up}^q
quantumstopfromwest: {quantumstopprefix}s{Left}p^{Right}^q
quantumstopfromnorth: {quantumstopprefix}s{Up}p^{Down}^q
# Give a name to the most recently defined route. Keep in mind that names have
# a maximum length of 22 characters. It assumes that the route has exactly one
# stop defined. Use it with the quantumstopfrom* aliases above like this:
# {quantumstopfromeast}{namelastrouteprefix}Trash Dumper{namelastroutesuffix}
# (the actual types stored in the quantum stockpile should be controlled by the
# feeder stockpile) and link the indicated adjacent feeder stockpile. For
# example, the quantumstopfromsouth alias should be used over a track stop set
# to dump to the North and take items from a feeder stockpile one tile to the
# South. All you need to do afterwards is assign a vehicle to the stop. The
# track stop does not need to be constructed yet, but the feeder stockpile needs
# to exist so we can link to it.
#
# Be sure to define the optional 'name' parameter if you want to give your
# quantum hauling routes custom names. Keep in mind that names have a maximum
# length of 22 characters. For example:
# {quantumstopfromsouth name="Trash Dump"}
#
# For several examples of these aliases, see
# https://docs.google.com/spreadsheets/d/1gvTJxxRxZ5V4vXkqwhL-qlr_lXCNt8176TK14m4kSOU
namelastrouteprefix: ^h--n
namelastroutesuffix: &^q
namelastroute: {namelastrouteprefix}{name}{namelastroutesuffix}
quantumstopprefix: ^hrs&xxx&{enablesequence 17}^
quantumstopsuffix: ^q{namelastroute}
quantumstopfromeast: {quantumstopprefix}s{Right}p^{Left}{quantumstopsuffix}
quantumstopfromsouth: {quantumstopprefix}s{Down}p^{Up}{quantumstopsuffix}
quantumstopfromwest: {quantumstopprefix}s{Left}p^{Right}{quantumstopsuffix}
quantumstopfromnorth: {quantumstopprefix}s{Up}p^{Down}{quantumstopsuffix}
##################################

@ -1,6 +1,6 @@
# aliases for quickfort query mode blueprints
# Aliases for quickfort #query mode blueprints
#
# This file defines custom keycode shortcuts for query mode blueprints.
# This file defines custom keycode shortcuts for #query mode blueprints.
# Definitions in this file take precedence over any definitions in the baseline
# aliases configuration file at hack/data/quickfort/aliases-common.txt. See that
# file for the many useful aliases that are already defined.
@ -69,6 +69,20 @@
# indicating how many times that alias or keycode should be repeated. For
# example: "{togglesequence 9}" or "{Down 5}".
#
# Finally, you can specify sub-aliases that will only be defined while the
# current alias is being resolved by adding them after the alias name (but
# before the repetition number, if it is specified), for example:
# {quantumstopfromeast name="Trash Dump"}
# The value of the sub-alias 'name' is used by quantumstopfromeast (or one of
# the aliases it calls) to give a useful name to your quantum dump hauling
# route. You can also use this format to temporarily override the value of an
# existing regularly-defined alias.
#
# Sub-aliases must be in one of the following formats:
# subaliasname=valwithnospaces
# subaliasname="val with spaces"
# subaliasname={someotheralias repetitions}
#
# Ctrl, Alt, and Shift modifiers can be specified for the next keycode by adding
# them into the key sequence. For example, Alt-h is written as "{Alt}h".
#

@ -5,32 +5,38 @@ Quickfort User Guide
`Quickfort <quickfort>` is a DFHack script 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 <https://sheets.new>`__. You can also build
your plan "for real" in Dwarf Fortress, and then export your map using the `blueprint`
plugin. Most layout and building-oriented DF commands are supported through the
use of multiple files or spreadsheets, each describing a different phase of DF
construction: designation, building, placing stockpiles/zones, and setting
configuration.
The original idea and 1.0 codebase came from :wiki:`Valdemar's <User:Valdemar>`
auto-designation macro. Joel Thornton (joelpt) reimplemented the core logic in
Python and extended its functionality with `Quickfort
2.0 <https://github.com/joelpt/quickfort>`__. This DFHack-native implementation,
called "DFHack Quickfort" or just "quickfort", builds upon Quickfort 2.0's
formats and features. DFHack Quickfort is written in Lua and interacts with
Dwarf Fortress memory structures directly, allowing for instantaneous blueprint
application, error checking and recovery, and many other advanced features.
such as MS Excel and `Google Sheets <https://sheets.new>`__. Most layout and
building-oriented DF commands are supported through the use of multiple files or
spreadsheets, each describing a different phase of DF construction: designation,
building, placing stockpiles/zones, and setting configuration.
The original idea came from :wiki:`Valdemar's <User:Valdemar>` auto-designation
macro. Joel Thornton reimplemented the core logic in Python and extended its
functionality with `Quickfort 2.0 <https://github.com/joelpt/quickfort>`__. This
DFHack-native implementation, called "DFHack Quickfort" or just "quickfort",
builds upon Quickfort 2.0's formats and features. Any blueprint that worked in
Python Quickfort 2.0 should work with DFHack Quickfort. DFHack Quickfort is
written in Lua and interacts with Dwarf Fortress memory structures directly,
allowing for instantaneous blueprint application, error checking and recovery,
and many other advanced features.
This document focuses on DFHack Quickfort's capabilities and teaches players how
to understand and build blueprint files. Some of the text was originally written
by Joel Thornton, reused here with his permission.
For those just looking to apply blueprints, check out the `quickfort command's
documentation <quickfort>` for syntax. There are also many ready-to-use blueprints
available in the ``blueprints/library`` subfolder in your DFHack installation.
Browse them on your computer or :source:`online <data/blueprints/library>`,
or run ``quickfort list -l`` at the ``[DFHack]#`` prompt to list them, and then
``quickfort run`` to apply them to your fort!
to understand and create blueprint files. Some of the text was originally
written by Joel Thornton, reused here with his permission.
For those just looking to apply existing blueprints, check out the `quickfort
command's documentation <quickfort>` for syntax. There are many ready-to-use
blueprints available in the ``blueprints/library`` subfolder in your DFHack
installation. Browse them on your computer or
:source:`online <data/blueprints/library>`, or run ``quickfort list -l`` at the
``[DFHack]#`` prompt to list them, and then ``quickfort run`` to apply them to
your fort!
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 your map using the DFHack `blueprint` plugin.
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.
@ -96,6 +102,7 @@ Features
created stockpiles
- Automatic splitting of stockpiles and zones that exceed maximum dimension
limits
- Full access to all zone settings, such as hospital supply counts
- Query mode
@ -478,37 +485,57 @@ It is very common to have stockpiles that accept multiple categories of items or
zones that permit more than one activity. Although it is perfectly valid to
declare a single-purpose stockpile or zone and then modify it with a ``#query``
blueprint, quickfort also supports directly declaring all the types on the
``#place`` and ``#zone`` blueprints. For example, to declare a 10x10 area that
is a pasture, a fruit picking area, and a meeting area all at once, you could
write:
``#place`` and ``#zone`` blueprints. For example, to declare a 20x10 stockpile
that accepts both corpses and refuse, you could write:
::
#place refuse heap
yr(20x10)
And similarly, to declare a zone that is a pasture, a fruit picking area, and a
meeting area all at once:
::
#zone main pasture and picnic area
nmg(10x10)
And similarly, to declare a stockpile that accepts both corpses and refuse, you
could write:
The order of the individual letters doesn't matter.
Detailed configuration for zones, such as the pit/pond toggle, can also be set
by mimicking the hotkeys used to set them. Note that gather flags default to
true, so specifying them in a blueprint will turn the toggles off. If you need
to set configuration from multiple zone subscreens, separate the key sections
with ``^``. Note the special syntax for setting hospital supply levels, which
have no in-game hotkeys:
::
#place refuse heap
yr(20x10)
#zone a combination hospital and shrub (but not fruit) gathering zone
gGtf^hH{hospital buckets=5 splints=20}(10x10)
The order of the individual letters doesn't matter.
The valid hospital settings (and their maximum values) are:
::
thread (1500000)
cloth (1000000)
splints (100)
crutches (100)
powder (15000)
buckets (100)
soap (15000)
To toggle the ``active`` flag for zones, add an ``a`` character to the string.
For example, to create a *disabled* pit zone (that you later intend to turn into
a pond and carefully fill to 3-depth water):
For example, to create a *disabled* pond zone (that you later intend to
carefully fill with 3-depth water for a dwarven bathtub):
::
#zone disabled future pond zone
pa(1x3)
Note that while this notation covers most use cases, tweaking low-level zone
parameters, like hospital supply levels or converting between pits and ponds,
must still be done manually or with a ``#query`` blueprint.
#zone disabled pond zone
apPf(1x3)
Minecart tracks
~~~~~~~~~~~~~~~
@ -1321,11 +1348,6 @@ 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -1333,7 +1355,7 @@ The industry_ level: when not to use aliases
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.
first are the key sequences that are *not* in aliases.
.. topic:: Tip
@ -1353,6 +1375,45 @@ 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.
There are also good examples in the query blueprint for how to use the
``permit`` and ``forbid`` stockpile aliases.
.. 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:
# Make a stockpile accept only a particular item type in a category
# Permit an item type, but do not otherwise change the stockpile configuration
# 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 ``{alias1}{alias2}`` syntax:
::
#query Incorrectly configure a 3x3 food stockpile to accept tallow and dye
tallow
permitdye
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 everything forbidden, then tallow permitted, then dye
permitted. The algorithm could happen to apply them in the opposite order,
though, and we'd end up with dye being permitted, then everything being
forbidden and tallow being enabled. To make sure you always get what you want,
write order-sensitive aliases on the same line:
::
#query Properly configure a 3x3 food stockpile to accept tallow and dye
{tallow}{permitdye}
The services_ level: handling multi-level dig blueprints
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~