diff --git a/data/blueprints/library/dreamfort.csv b/data/blueprints/library/dreamfort.csv index e2de895af..801bb32e6 100644 --- a/data/blueprints/library/dreamfort.csv +++ b/data/blueprints/library/dreamfort.csv @@ -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 "" -- 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?)." "" -- 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. "" #aliases -startnobles: ^n{Down 4}{togglesequence 8}{Up}s{Up}&^^q -startorders: ^ohrov^Wl^^q -startburrows: ^wa&nInside&^^q +startnobles: n{Down 4}{togglesequence 8}{Up}s{Up}&^^ +startorders: ohrov^Wl^^ +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} -startmilitary: ^mnr{Down}r{metalarmorsetup}{Down}racNSiege&{Right}&^q +startmilitary: mnr{Down}r{metalarmorsetup}{Down}racNSiege&{Right}&^ 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. 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" -{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." # 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). "" diff --git a/data/blueprints/library/test/quickfort/list/all_modes.csv b/data/blueprints/library/test/quickfort/list/all_modes.csv index 96594220f..c8a042846 100644 --- a/data/blueprints/library/test/quickfort/list/all_modes.csv +++ b/data/blueprints/library/test/quickfort/list/all_modes.csv @@ -3,7 +3,8 @@ #place hidden() #zone hidden() #query hidden() -#meta hidden() -#notes hidden() +#config hidden() #ignore #aliases +#meta hidden() +#notes hidden() diff --git a/data/blueprints/library/test/quickfort/list/all_modes_separate_sheets.xlsx b/data/blueprints/library/test/quickfort/list/all_modes_separate_sheets.xlsx index 4fcfbf867..47445283f 100644 Binary files a/data/blueprints/library/test/quickfort/list/all_modes_separate_sheets.xlsx and b/data/blueprints/library/test/quickfort/list/all_modes_separate_sheets.xlsx differ diff --git a/data/blueprints/library/test/quickfort/list/all_modes_single_sheet.xlsx b/data/blueprints/library/test/quickfort/list/all_modes_single_sheet.xlsx index 052f4e3fb..51331918c 100644 Binary files a/data/blueprints/library/test/quickfort/list/all_modes_single_sheet.xlsx and b/data/blueprints/library/test/quickfort/list/all_modes_single_sheet.xlsx differ diff --git a/dfhack-config/quickfort/quickfort.txt b/dfhack-config/quickfort/quickfort.txt index 3a57bfbaf..e3f5aeaec 100644 --- a/dfhack-config/quickfort/quickfort.txt +++ b/dfhack-config/quickfort/quickfort.txt @@ -22,9 +22,9 @@ force_marker_mode=false # Skip query blueprint sanity checks that detect common blueprint errors and # halt or skip keycode playback. Checks include ensuring a configurable building # 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 -# enable this if you are running a query blueprint that sends a key sequence -# that is *not* related to stockpile or building configuration. +# the same before and after sending keys for the cursor position. If you find +# you need to enable this for one of your own blueprints, you should probably be +# using a config blueprint, not a query blueprint. query_unsafe=false # Set to the maximum number of resources you want assigned to stockpiles of the diff --git a/docs/guides/examples-guide.rst b/docs/guides/examples-guide.rst index add0ceb28..409ceaa00 100644 --- a/docs/guides/examples-guide.rst +++ b/docs/guides/examples-guide.rst @@ -1,3 +1,4 @@ +.. _config-examples-guide: .. _dfhack-examples-guide: DFHack Example Configuration File Index diff --git a/docs/guides/quickfort-library-guide.rst b/docs/guides/quickfort-library-guide.rst index 1878fdd7a..366272052 100644 --- a/docs/guides/quickfort-library-guide.rst +++ b/docs/guides/quickfort-library-guide.rst @@ -1,3 +1,4 @@ +.. _blueprint-library-guide: .. _quickfort-library-guide: Blueprint Library Index diff --git a/docs/guides/quickfort-user-guide.rst b/docs/guides/quickfort-user-guide.rst index efd19d1c1..fd4156f36 100644 --- a/docs/guides/quickfort-user-guide.rst +++ b/docs/guides/quickfort-user-guide.rst @@ -1,5 +1,5 @@ -.. _quickfort-user-guide: .. _quickfort-blueprint-guide: +.. _quickfort-user-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 additional blueprint modes that become useful when you are sharing your blueprints with others or managing complex blueprint sets. Instead of mapping -tile positions to map modifications and keystroke sequences like the basic modes -do, these "blueprints" have specialized, higher-level uses: +tile positions to map modifications like the basic modes do, these "blueprints" +have specialized, higher-level uses: ============== =========== 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 walkthroughs 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 ============== =========== +.. _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: Notes blueprints @@ -1779,10 +1818,10 @@ Links - `Quickfort command reference ` - `quickfort-alias-guide` -- `quickfort-library-guide` +- `blueprint-library-guide` - :forums:`Quickfort forum thread <176889>` - :issue:`DFHack issue tracker <>` -- :source:`Quickfort blueprint library source ` +- :source:`Blueprint library source ` - :source-scripts:`Quickfort source code ` **Related tools:** diff --git a/scripts b/scripts index 946fdffdf..7205e4ec2 160000 --- a/scripts +++ b/scripts @@ -1 +1 @@ -Subproject commit 946fdffdf113e3ef11aa87b817ee8ea136daad55 +Subproject commit 7205e4ec20d3df0f2c12e2f279cb4d9205673e6c