[quickfort] add documentation and test data for config mode (#2070)

- documents the new config mode
- adds integration test data for [quickfort] implement config mode scripts#361
- adds a note recommending that config mode be used instead of the quickfort query_unsafe setting
- converts the dreamfort /setup blueprint to use config mode; also adjust the aliases used in that blueprint to no longer escape from and re-enter query mode
- adds some more distinctive anchor names for the quickfort and blueprint guides
develop
Myk 2022-04-01 09:21:16 -07:00 committed by GitHub
parent 1f49d4a7cf
commit b8c33d8ed0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 61 additions and 19 deletions

@ -55,7 +55,7 @@ Optionally copy the premade profession definitions from hack/examples/profession
Optionally copy the premade Dreamfort embark profile from the online spreadsheets to the data/init/embark_profiles.txt file Optionally copy the premade Dreamfort embark profile from the online spreadsheets to the data/init/embark_profiles.txt file
"" ""
-- Set settings and preload initial orders -- -- Set settings and preload initial orders --
quickfort run library/dreamfort.csv -n /setup,# Place the cursor on the center of your starting wagon. Run before making any manual adjustments to settings! Run the /setup_help blueprint for details on what this blueprint does. quickfort run library/dreamfort.csv -n /setup,# Run before making any manual adjustments to settings! Run the /setup_help blueprint for details on what this blueprint does.
"quickfort orders library/dreamfort.csv -n ""/surface2, /farming2, /surface3, /farming3, /industry2, /surface4""","# Queue up orders required to get the fort minimally functional and secure. You can remove the order for the anvil (you brought one with you, right?)." "quickfort orders library/dreamfort.csv -n ""/surface2, /farming2, /surface3, /farming3, /industry2, /surface4""","# Queue up orders required to get the fort minimally functional and secure. You can remove the order for the anvil (you brought one with you, right?)."
"" ""
-- Find a good starting spot on the surface -- -- Find a good starting spot on the surface --
@ -134,19 +134,19 @@ The following settings are changed:
These are all set for your convenience. Nothing in Dreamfort depends on these settings staying as they are. Feel free to change any setting to your personal preference. These are all set for your convenience. Nothing in Dreamfort depends on these settings staying as they are. Feel free to change any setting to your personal preference.
"" ""
#aliases #aliases
startnobles: ^n{Down 4}{togglesequence 8}{Up}s{Up}&^^q startnobles: n{Down 4}{togglesequence 8}{Up}s{Up}&^^
startorders: ^ohrov^Wl^^q startorders: ohrov^Wl^^
startburrows: ^wa&nInside&^^q startburrows: wa&nInside&^^
metalarmorsetup: A{Right 2}{Down 2}&{Down}&{Left}&M{Right}{Down}&{Left}{Down}{Right}{Down}&{Left}{Down 2}L{Right}{Down 2}&{Left}{Down 3}&M{Right}{Down}&{Left 2} metalarmorsetup: A{Right 2}{Down 2}&{Down}&{Left}&M{Right}{Down}&{Left}{Down}{Right}{Down}&{Left}{Down 2}L{Right}{Down 2}&{Left}{Down 3}&M{Right}{Down}&{Left 2}
startmilitary: ^mnr{Down}r{metalarmorsetup}{Down}racNSiege&{Right}&^q startmilitary: mnr{Down}r{metalarmorsetup}{Down}racNSiege&{Right}&^
sethotkey: {fkey}n{name}& sethotkey: {fkey}n{name}&
starthotkeys: ^H{sethotkey fkey={F2} name=Farming}{sethotkey fkey={F3} name=Industry}{sethotkey fkey={F4} name=Services}{sethotkey fkey={F5} name=Guildhall}{sethotkey fkey={F6} name=Quarry}{sethotkey fkey={F7} name=Cavern}{sethotkey fkey={F8} name=Magma}^q starthotkeys: H{sethotkey fkey={F2} name=Farming}{sethotkey fkey={F3} name=Industry}{sethotkey fkey={F4} name=Services}{sethotkey fkey={F5} name=Guildhall}{sethotkey fkey={F6} name=Quarry}{sethotkey fkey={F7} name=Cavern}{sethotkey fkey={F8} name=Magma}^
"" ""
"#query label(setup) start(center tile of the wagon) message(Please set the zoom targets of the hotkeys (the 'H' menu) according to where you actually end up digging the levels. "#config label(setup) message(Please set the zoom targets of the hotkeys (the 'H' menu) according to where you actually end up digging the levels.
As you build your fort, expand the ""Inside"" burrow to include new civilian-safe areas. As you build your fort, expand the ""Inside"" burrow to include new civilian-safe areas.
Optionally, add a leather cloak to your military uniforms to enhance the protection of the uniforms. Optionally, add a leather cloak to your military uniforms to enhance the protection of the uniforms.
Nothing in Dreamfort depends on these settings staying as they are. Feel free to change any setting to your personal preference.) assign nobles, set standing orders, create burrows, make adjustments to military uniforms, and set hotkey names" Nothing in Dreamfort depends on these settings staying as they are. Feel free to change any setting to your personal preference.) assign nobles, set standing orders, create burrows, make adjustments to military uniforms, and set hotkey names"
{startnobles}{startorders}{startburrows}{startmilitary}{starthotkeys}{F1} {startnobles}{startorders}{startburrows}{startmilitary}{starthotkeys}
"#meta label(dig_all) start(central stairs on industry level) dig industry, services, guildhall, suites, and apartments levels. does not include farming." "#meta label(dig_all) start(central stairs on industry level) dig industry, services, guildhall, suites, and apartments levels. does not include farming."
# Note that this blueprint will only work for the unified dreamfort.csv. It won't work for the individual .xlsx files (since #meta blueprints can't cross file boundaries). # Note that this blueprint will only work for the unified dreamfort.csv. It won't work for the individual .xlsx files (since #meta blueprints can't cross file boundaries).
"" ""

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

@ -3,7 +3,8 @@
#place hidden() #place hidden()
#zone hidden() #zone hidden()
#query hidden() #query hidden()
#meta hidden() #config hidden()
#notes hidden()
#ignore #ignore
#aliases #aliases
#meta hidden()
#notes hidden()

1 #dig hidden()
3 #place hidden()
4 #zone hidden()
5 #query hidden()
6 #meta hidden() #config hidden()
#notes hidden()
7 #ignore
8 #aliases
9 #meta hidden()
10 #notes hidden()

@ -22,9 +22,9 @@ force_marker_mode=false
# Skip query blueprint sanity checks that detect common blueprint errors and # Skip query blueprint sanity checks that detect common blueprint errors and
# halt or skip keycode playback. Checks include ensuring a configurable building # halt or skip keycode playback. Checks include ensuring a configurable building
# exists at the designated cursor position and verifying the active UI screen is # exists at the designated cursor position and verifying the active UI screen is
# the same before and after sending keys for the cursor position. Temporarily # the same before and after sending keys for the cursor position. If you find
# enable this if you are running a query blueprint that sends a key sequence # you need to enable this for one of your own blueprints, you should probably be
# that is *not* related to stockpile or building configuration. # using a config blueprint, not a query blueprint.
query_unsafe=false query_unsafe=false
# Set to the maximum number of resources you want assigned to stockpiles of the # Set to the maximum number of resources you want assigned to stockpiles of the

@ -1,3 +1,4 @@
.. _config-examples-guide:
.. _dfhack-examples-guide: .. _dfhack-examples-guide:
DFHack Example Configuration File Index DFHack Example Configuration File Index

@ -1,3 +1,4 @@
.. _blueprint-library-guide:
.. _quickfort-library-guide: .. _quickfort-library-guide:
Blueprint Library Index Blueprint Library Index

@ -1,5 +1,5 @@
.. _quickfort-user-guide:
.. _quickfort-blueprint-guide: .. _quickfort-blueprint-guide:
.. _quickfort-user-guide:
Quickfort Blueprint Editing Guide Quickfort Blueprint Editing Guide
================================= =================================
@ -1077,12 +1077,13 @@ Other blueprint modes
In addition to the powerful ``#meta`` mode described above, there are a few In addition to the powerful ``#meta`` mode described above, there are a few
additional blueprint modes that become useful when you are sharing your additional blueprint modes that become useful when you are sharing your
blueprints with others or managing complex blueprint sets. Instead of mapping blueprints with others or managing complex blueprint sets. Instead of mapping
tile positions to map modifications and keystroke sequences like the basic modes tile positions to map modifications like the basic modes do, these "blueprints"
do, these "blueprints" have specialized, higher-level uses: have specialized, higher-level uses:
============== =========== ============== ===========
Blueprint mode Description Blueprint mode Description
============== =========== ============== ===========
config Play back key sequences that are not related to map tiles
notes Display long messages, such as help text or blueprint notes Display long messages, such as help text or blueprint
walkthroughs walkthroughs
aliases Define aliases that can be used by other ``#query`` blueprints aliases Define aliases that can be used by other ``#query`` blueprints
@ -1091,6 +1092,44 @@ ignore Hide a section of your spreadsheet from quickfort, useful for
scratch space or personal notes scratch space or personal notes
============== =========== ============== ===========
.. _quickfort-config-blueprints:
Config blueprints
`````````````````
A ``#config`` blueprint is used to send unfiltered keystrokes directly to the
DF UI without interacting with specific map tiles. They have access to the same
keystroke aliases as ``#query`` blueprints, but ``#config`` blueprints differ
from ``#query`` blueprints in a few critical ways:
- Whereas the "home" mode for ``#query`` blueprints is the "query" mode
(:kbd:`q`), ``#config`` blueprints start on the default map screen -- the view
you have when you're looking at the map with no sidebar visible. The keystroke
or alias sequence in each spreadsheet cell in a ``#config`` blueprint must
begin and end on the default map screen.
- The cursor position is not set for ``#config`` blueprints. This means that it
doesn't matter what spreadsheet cell you put your text in. The blueprint cell
location does not correspond to a map tile.
A ``#config`` blueprint is best used for accessing game menus that are not
associated with map tiles, such as the hotkey menu (:kbd:`H`), the military
menu (:kbd:`m`), or the standing orders menu (:kbd:`o`). In other words, use a
``#config`` blueprint when you want to configure the game itself, not the tiles
on the map. A ``#config`` blueprint is better for these menus than a ``#query``
blueprint because the cursor can jump around in unpredictable ways when
accessing these non-cursor modes and then re-entering query mode. This will
cause quickfort to detect a ``#query`` blueprint error and stop executing.
Also, ``#query`` blueprints will skip playing back a key sequence entirely if
it doesn't detect a building or zone on the target tile. A ``#config``
blueprint doesn't need a building or zone to exist in order to run.
Note that you *can* enter any mode you want during a ``#config`` blueprint
keystroke sequence (as long as you get back to the default map screen by the end
of the sequence), even modes that provide a cursor on the screen. It's just that
the position of that cursor is not guaranteed to be on any specific tile. If you
need access to a cursor, you probably should be using a ``#query`` blueprint
instead.
.. _quickfort-notes: .. _quickfort-notes:
Notes blueprints Notes blueprints
@ -1779,10 +1818,10 @@ Links
- `Quickfort command reference <quickfort>` - `Quickfort command reference <quickfort>`
- `quickfort-alias-guide` - `quickfort-alias-guide`
- `quickfort-library-guide` - `blueprint-library-guide`
- :forums:`Quickfort forum thread <176889>` - :forums:`Quickfort forum thread <176889>`
- :issue:`DFHack issue tracker <>` - :issue:`DFHack issue tracker <>`
- :source:`Quickfort blueprint library source <data/blueprints/library>` - :source:`Blueprint library source <data/blueprints/library>`
- :source-scripts:`Quickfort source code <internal/quickfort>` - :source-scripts:`Quickfort source code <internal/quickfort>`
**Related tools:** **Related tools:**

@ -1 +1 @@
Subproject commit 946fdffdf113e3ef11aa87b817ee8ea136daad55 Subproject commit 7205e4ec20d3df0f2c12e2f279cb4d9205673e6c