From 6c3bac2d6caf7382a88a929afa485a4c3f89487a Mon Sep 17 00:00:00 2001 From: Myk Taylor Date: Sat, 17 Oct 2020 22:20:39 -0700 Subject: [PATCH 1/6] document extended zone configuration syntax --- docs/guides/quickfort-user-guide.rst | 53 +++++++++++++++++++--------- 1 file changed, 37 insertions(+), 16 deletions(-) diff --git a/docs/guides/quickfort-user-guide.rst b/docs/guides/quickfort-user-guide.rst index bef85b161..f4b15969a 100644 --- a/docs/guides/quickfort-user-guide.rst +++ b/docs/guides/quickfort-user-guide.rst @@ -96,6 +96,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 +479,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 ~~~~~~~~~~~~~~~ From ea5a5414c93af8f280b0d5c84ec286f741e1d018 Mon Sep 17 00:00:00 2001 From: Myk Taylor Date: Sat, 17 Oct 2020 22:21:50 -0700 Subject: [PATCH 2/6] document (and use) parameterized aliases --- data/quickfort/aliases-common.txt | 62 ++++++++++++++++------------- dfhack-config/quickfort/aliases.txt | 18 ++++++++- 2 files changed, 50 insertions(+), 30 deletions(-) diff --git a/data/quickfort/aliases-common.txt b/data/quickfort/aliases-common.txt index ed9a34393..d5f52efcf 100644 --- a/data/quickfort/aliases-common.txt +++ b/data/quickfort/aliases-common.txt @@ -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} @@ -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} ################################## diff --git a/dfhack-config/quickfort/aliases.txt b/dfhack-config/quickfort/aliases.txt index 2b90e67c4..2743a39f3 100644 --- a/dfhack-config/quickfort/aliases.txt +++ b/dfhack-config/quickfort/aliases.txt @@ -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". # From 914c24d873a1ac9d975d6da56e0a27f18b434b84 Mon Sep 17 00:00:00 2001 From: Myk Taylor Date: Sat, 17 Oct 2020 22:22:32 -0700 Subject: [PATCH 3/6] use new quickfort features in dreamfort parameterized aliases and configurable zones --- data/blueprints/library/dreamfort.csv | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/data/blueprints/library/dreamfort.csv b/data/blueprints/library/dreamfort.csv index 8924df3c6..64d32ce8d 100644 --- a/data/blueprints/library/dreamfort.csv +++ b/data/blueprints/library/dreamfort.csv @@ -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,,,,,,,,`,`,`,`,`,`,`,`,` ,,,,,,`,`,,`,`,,,,,,,,,,,,,,,,,,,,`,`,`,`,`,`,`,`,` From 05d2e5b65c370e3ab467f0e3efe93c82615d3f31 Mon Sep 17 00:00:00 2001 From: Myk Taylor Date: Sun, 18 Oct 2020 13:49:11 -0700 Subject: [PATCH 4/6] update case study: order-dependent aliases since the example I had used no longer exists now that we have parameterized aliases. I had to find another example in the industry blueprints. I made it a proper "tip" and added more explanation as well. --- docs/guides/quickfort-user-guide.rst | 46 ++++++++++++++++++++++++---- 1 file changed, 40 insertions(+), 6 deletions(-) diff --git a/docs/guides/quickfort-user-guide.rst b/docs/guides/quickfort-user-guide.rst index f4b15969a..2dfaa74b1 100644 --- a/docs/guides/quickfort-user-guide.rst +++ b/docs/guides/quickfort-user-guide.rst @@ -1342,11 +1342,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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1354,7 +1349,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 @@ -1374,6 +1369,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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 83e8755e6d9877be076ab380bf2b7cacb504a796 Mon Sep 17 00:00:00 2001 From: Myk Taylor Date: Fri, 23 Oct 2020 20:26:37 -0700 Subject: [PATCH 5/6] fix typos in quantum alias --- data/quickfort/aliases-common.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data/quickfort/aliases-common.txt b/data/quickfort/aliases-common.txt index d5f52efcf..857160711 100644 --- a/data/quickfort/aliases-common.txt +++ b/data/quickfort/aliases-common.txt @@ -50,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} ################################## From a0c86b8a9bea6fcf9e0e04fb3dd4665329a5407f Mon Sep 17 00:00:00 2001 From: Myk Taylor Date: Sat, 24 Oct 2020 21:14:09 -0700 Subject: [PATCH 6/6] rewrite quickfort user guide into spend more space highlighting how users can use the blueprint plugin to avoid learning how to write blueprints themselves --- docs/guides/quickfort-user-guide.rst | 54 +++++++++++++++------------- 1 file changed, 30 insertions(+), 24 deletions(-) diff --git a/docs/guides/quickfort-user-guide.rst b/docs/guides/quickfort-user-guide.rst index 2dfaa74b1..9e5db34c3 100644 --- a/docs/guides/quickfort-user-guide.rst +++ b/docs/guides/quickfort-user-guide.rst @@ -5,32 +5,38 @@ Quickfort User Guide `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 `__. 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 ` -auto-designation macro. Joel Thornton (joelpt) reimplemented the core logic in -Python and extended its functionality with `Quickfort -2.0 `__. 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 `__. 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 ` auto-designation +macro. Joel Thornton reimplemented the core logic in Python and extended its +functionality with `Quickfort 2.0 `__. 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 ` 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 `, -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 ` 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 `, 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.