From 4efb01142913d5f1d72878e8bb409f6353443b6d Mon Sep 17 00:00:00 2001 From: Myk Taylor Date: Thu, 5 Nov 2020 16:01:44 -0800 Subject: [PATCH 01/10] quickfort guide: 'c' stockpiles don't make sense explain why "custom" stockpiles aren't meaningful to create in a blueprint and what the user should do instead --- docs/guides/quickfort-user-guide.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/guides/quickfort-user-guide.rst b/docs/guides/quickfort-user-guide.rst index 964776f65..0df4bc24c 100644 --- a/docs/guides/quickfort-user-guide.rst +++ b/docs/guides/quickfort-user-guide.rst @@ -502,7 +502,12 @@ meeting area all at once: #zone main pasture and picnic area nmg(10x10) -The order of the individual letters doesn't matter. +The order of the individual letters doesn't matter. Note that "custom" +(:kbd:`c`) stockpiles cannot be declared in a blueprint since what would +get created would depend on what happens to be set in the "custom stockpile +settings" in your game. Instead, place stockpiles using the keys that +represent the types you want to store and then use a ``#query`` blueprint to +customize them. 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 From edf55b2ae64a2965ea581436ec19751a8c407ca9 Mon Sep 17 00:00:00 2001 From: Myk Taylor Date: Thu, 5 Nov 2020 16:11:27 -0800 Subject: [PATCH 02/10] use numbered lists in meta blueprints section --- docs/guides/quickfort-user-guide.rst | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/guides/quickfort-user-guide.rst b/docs/guides/quickfort-user-guide.rst index 0df4bc24c..f8061b766 100644 --- a/docs/guides/quickfort-user-guide.rst +++ b/docs/guides/quickfort-user-guide.rst @@ -897,13 +897,13 @@ Meta blueprints Meta blueprints are blueprints that script a series of other blueprints. Many blueprint packages follow this pattern: -- Apply dig blueprint to designate dig areas -- Wait for miners to dig -- **Apply build buildprint** to designate buildings -- **Apply place buildprint** to designate stockpiles -- **Apply query blueprint** to configure stockpiles -- Wait for buildings to get built -- Apply a different query blueprint to configure rooms +1. Apply dig blueprint to designate dig areas +#. Wait for miners to dig +#. **Apply build buildprint** to designate buildings +#. **Apply place buildprint** to designate stockpiles +#. **Apply query blueprint** to configure stockpiles +#. Wait for buildings to get built +#. Apply a different query blueprint to configure rooms 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 @@ -947,12 +947,12 @@ blueprints into one: Now your sequence is shortened to: -- Apply dig blueprint to designate dig areas -- Wait for miners to dig -- **Apply meta buildprint** to build buildings and designate/configure - stockpiles -- Wait for buildings to get built -- Apply the final query blueprint to configure the room +1. Apply dig blueprint to designate dig areas +#. Wait for miners to dig +#. **Apply meta buildprint** to build buildings and designate/configure + stockpiles +#. Wait for buildings to get built +#. Apply the final query blueprint to configure the room You can use meta blueprints to lay out your fortress at a larger scale as well. The ``#<`` and ``#>`` notation is valid in meta blueprints, so you can, for From e8f4b4016b8dff8dc56c53db9a7eca2e126e35c2 Mon Sep 17 00:00:00 2001 From: Myk Taylor Date: Thu, 5 Nov 2020 16:18:33 -0800 Subject: [PATCH 03/10] reinforce that meta blueprints can't cross files they must refer to labels that are within the same .xlsx or .csv file --- docs/guides/quickfort-user-guide.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/guides/quickfort-user-guide.rst b/docs/guides/quickfort-user-guide.rst index f8061b766..5ab0956f7 100644 --- a/docs/guides/quickfort-user-guide.rst +++ b/docs/guides/quickfort-user-guide.rst @@ -1015,6 +1015,11 @@ a big fort, so we're planning for a lot of bedrooms): Note that for blueprints without an explicit label, we still need to address them by their auto-generated numerical label. +It's worth calling out that ``#meta`` blueprints can only refer to blueprints +that are defined in the same file. This means that all blueprints that a +``#meta`` blueprint needs to script must be in sheets within the same +.xlsx spreadsheet or concatenated into the same .csv file. + You can then hide the blueprints that you now manage with the ``#meta``-mode blueprint from ``quickfort list`` by adding a ``hidden()`` marker to their modelines. That way the output of ``quickfort list`` won't be cluttered by From 2ec8dd12253aeb99e45fe48085d9e0fbd0cf37a9 Mon Sep 17 00:00:00 2001 From: myk002 Date: Wed, 11 Nov 2020 16:53:29 -0800 Subject: [PATCH 04/10] update quickfort guide and aliases - move bit of alias documentation from aliases-common to aliases.txt - document new behavior for 'c'ustom stockpiles --- data/quickfort/aliases-common.txt | 7 +++---- dfhack-config/quickfort/aliases.txt | 6 +++++- docs/guides/quickfort-user-guide.rst | 11 +++++------ 3 files changed, 13 insertions(+), 11 deletions(-) diff --git a/data/quickfort/aliases-common.txt b/data/quickfort/aliases-common.txt index 857160711..59705f9f7 100644 --- a/data/quickfort/aliases-common.txt +++ b/data/quickfort/aliases-common.txt @@ -17,10 +17,6 @@ # # Aliases that don't fit into those two categories have comments explaining # their usage. -# -# There is also a non-alphanumeric alias built into the code for the common -# shorthand for "make room": -# r+ expands to r+& ######################################## @@ -41,6 +37,9 @@ give10down: {give move={Down 10}} give10left: {give move={Left 10}} give10right: {give move={Right 10}} +# usage example: {givename name="myname"} +givename: {Ctrl}n{name}& + # use to toggle a sequence of stockpile options. for example: {togglesequence 5} togglesequence: &{Down} togglesequence2: &{Down 2} diff --git a/dfhack-config/quickfort/aliases.txt b/dfhack-config/quickfort/aliases.txt index 2743a39f3..9be32107e 100644 --- a/dfhack-config/quickfort/aliases.txt +++ b/dfhack-config/quickfort/aliases.txt @@ -95,8 +95,12 @@ # ! expands to {Ctrl} # ^ expands to {ESC} # +# There is also a non-standard alias built into the code for the common +# shorthand for "make room": +# r+ expands to r+& +# # If you need literal verisons of the shorthand characters, surround them in -# curly brackets, for example: "{~}" +# curly brackets, for example: "{!}" # # # Add your custom aliases here: diff --git a/docs/guides/quickfort-user-guide.rst b/docs/guides/quickfort-user-guide.rst index 5ab0956f7..1d9c1a024 100644 --- a/docs/guides/quickfort-user-guide.rst +++ b/docs/guides/quickfort-user-guide.rst @@ -502,12 +502,11 @@ meeting area all at once: #zone main pasture and picnic area nmg(10x10) -The order of the individual letters doesn't matter. Note that "custom" -(:kbd:`c`) stockpiles cannot be declared in a blueprint since what would -get created would depend on what happens to be set in the "custom stockpile -settings" in your game. Instead, place stockpiles using the keys that -represent the types you want to store and then use a ``#query`` blueprint to -customize them. +The order of the individual letters doesn't matter. If you want to configure the +stockpile from scratch in a ``#query`` blueprint, you can place unconfigured +"custom" stockpiles with (:kbd:`c`). It is more efficient, though, to place +stockpiles using the keys that represent the types you want to store, and +then only use a ``#query`` blueprint if you need fine-grained customization. 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 From 625f003bc69ce53f2031dc6805a6fa3e08318b9b Mon Sep 17 00:00:00 2001 From: myk002 Date: Thu, 12 Nov 2020 23:20:53 -0800 Subject: [PATCH 05/10] add names for quantums and zones --- data/quickfort/aliases-common.txt | 15 +++++++++++++-- dfhack-config/quickfort/aliases.txt | 12 ++++++------ 2 files changed, 19 insertions(+), 8 deletions(-) diff --git a/data/quickfort/aliases-common.txt b/data/quickfort/aliases-common.txt index 59705f9f7..e4d2ef1cd 100644 --- a/data/quickfort/aliases-common.txt +++ b/data/quickfort/aliases-common.txt @@ -37,7 +37,8 @@ give10down: {give move={Down 10}} give10left: {give move={Left 10}} give10right: {give move={Right 10}} -# usage example: {givename name="myname"} +# Keep in mind that building, stockpile, and zone names have a maximum length +# of 20 characters. usage example: {givename name="myname"} givename: {Ctrl}n{name}& # use to toggle a sequence of stockpile options. for example: {togglesequence 5} @@ -49,7 +50,9 @@ 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}{enablefurniture}{enablestone}{enableammo}{enablecoins}{enablebars}{enablegems}{enablefinishedgoods}{enableleather}{enablecloth}{enablewood}{enableweapons}{enablearmor}{enablesheet} +# Optionally set a name for the stockpile by specifying the 'name' parameter, +# for example: {quantum name="my name"} +quantum: {linksonly}{nocontainers}{enableanimals}{enablefood}{enablefurniture}{enablestone}{enableammo}{enablecoins}{enablebars}{enablegems}{enablefinishedgoods}{enableleather}{enablecloth}{enablewood}{enableweapons}{enablearmor}{enablesheet}{givename} ################################## @@ -84,6 +87,14 @@ quantumstopfromwest: {quantumstopprefix}s{Left}p^{Right}{quantumstopsuffix} quantumstopfromnorth: {quantumstopprefix}s{Up}p^{Down}{quantumstopsuffix} +################################## +# zone aliases +################################## + +# usage example: {namezone name="my zone name"} +namezone: ^i{givename}^q + + ################################## # animal stockpile adjustments ################################## diff --git a/dfhack-config/quickfort/aliases.txt b/dfhack-config/quickfort/aliases.txt index 9be32107e..1d1ebff9f 100644 --- a/dfhack-config/quickfort/aliases.txt +++ b/dfhack-config/quickfort/aliases.txt @@ -58,12 +58,12 @@ # The syntax for defining aliases is: # aliasname: keystrokes # -# Where aliasname is at least two letters or digits long and keystrokes are -# whatever you would type into the DF UI. A keystroke can also be a named -# keycode from the DF interface definition file (data/init/interface.txt), -# enclosed in curly brackets like an alias, like: "{Right}" or "{Enter}". In -# order to avoid naming conflicts between aliases and keycodes, the convention -# is to start aliases with a lowercase letter. +# Where aliasname is at least two letters or digits long (including dashes and +# underscores) and keystrokes are whatever you would type into the DF UI. A +# keystroke can also be a named keycode from the DF interface definition file +# (data/init/interface.txt), enclosed in curly brackets like an alias, like: +# "{Right}" or "{Enter}". In # order to avoid naming conflicts between aliases +# and keycodes, the convention is to start aliases with a lowercase letter. # # Anything enclosed within curly brackets can also have a number after it, # indicating how many times that alias or keycode should be repeated. For From 647093f5c8b60c1b80d047b29b5db46f189dfa45 Mon Sep 17 00:00:00 2001 From: Myk Taylor Date: Thu, 5 Nov 2020 16:01:44 -0800 Subject: [PATCH 06/10] quickfort guide: 'c' stockpiles don't make sense explain why "custom" stockpiles aren't meaningful to create in a blueprint and what the user should do instead --- docs/guides/quickfort-user-guide.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/guides/quickfort-user-guide.rst b/docs/guides/quickfort-user-guide.rst index 964776f65..0df4bc24c 100644 --- a/docs/guides/quickfort-user-guide.rst +++ b/docs/guides/quickfort-user-guide.rst @@ -502,7 +502,12 @@ meeting area all at once: #zone main pasture and picnic area nmg(10x10) -The order of the individual letters doesn't matter. +The order of the individual letters doesn't matter. Note that "custom" +(:kbd:`c`) stockpiles cannot be declared in a blueprint since what would +get created would depend on what happens to be set in the "custom stockpile +settings" in your game. Instead, place stockpiles using the keys that +represent the types you want to store and then use a ``#query`` blueprint to +customize them. 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 From 93c8de9b237996aa047f0741af7992a8c4eecc5f Mon Sep 17 00:00:00 2001 From: Myk Taylor Date: Thu, 5 Nov 2020 16:11:27 -0800 Subject: [PATCH 07/10] use numbered lists in meta blueprints section --- docs/guides/quickfort-user-guide.rst | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/guides/quickfort-user-guide.rst b/docs/guides/quickfort-user-guide.rst index 0df4bc24c..f8061b766 100644 --- a/docs/guides/quickfort-user-guide.rst +++ b/docs/guides/quickfort-user-guide.rst @@ -897,13 +897,13 @@ Meta blueprints Meta blueprints are blueprints that script a series of other blueprints. Many blueprint packages follow this pattern: -- Apply dig blueprint to designate dig areas -- Wait for miners to dig -- **Apply build buildprint** to designate buildings -- **Apply place buildprint** to designate stockpiles -- **Apply query blueprint** to configure stockpiles -- Wait for buildings to get built -- Apply a different query blueprint to configure rooms +1. Apply dig blueprint to designate dig areas +#. Wait for miners to dig +#. **Apply build buildprint** to designate buildings +#. **Apply place buildprint** to designate stockpiles +#. **Apply query blueprint** to configure stockpiles +#. Wait for buildings to get built +#. Apply a different query blueprint to configure rooms 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 @@ -947,12 +947,12 @@ blueprints into one: Now your sequence is shortened to: -- Apply dig blueprint to designate dig areas -- Wait for miners to dig -- **Apply meta buildprint** to build buildings and designate/configure - stockpiles -- Wait for buildings to get built -- Apply the final query blueprint to configure the room +1. Apply dig blueprint to designate dig areas +#. Wait for miners to dig +#. **Apply meta buildprint** to build buildings and designate/configure + stockpiles +#. Wait for buildings to get built +#. Apply the final query blueprint to configure the room You can use meta blueprints to lay out your fortress at a larger scale as well. The ``#<`` and ``#>`` notation is valid in meta blueprints, so you can, for From 76759184d3f54e6eb3bd9c94f3d3ef3835682afa Mon Sep 17 00:00:00 2001 From: Myk Taylor Date: Thu, 5 Nov 2020 16:18:33 -0800 Subject: [PATCH 08/10] reinforce that meta blueprints can't cross files they must refer to labels that are within the same .xlsx or .csv file --- docs/guides/quickfort-user-guide.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/guides/quickfort-user-guide.rst b/docs/guides/quickfort-user-guide.rst index f8061b766..5ab0956f7 100644 --- a/docs/guides/quickfort-user-guide.rst +++ b/docs/guides/quickfort-user-guide.rst @@ -1015,6 +1015,11 @@ a big fort, so we're planning for a lot of bedrooms): Note that for blueprints without an explicit label, we still need to address them by their auto-generated numerical label. +It's worth calling out that ``#meta`` blueprints can only refer to blueprints +that are defined in the same file. This means that all blueprints that a +``#meta`` blueprint needs to script must be in sheets within the same +.xlsx spreadsheet or concatenated into the same .csv file. + You can then hide the blueprints that you now manage with the ``#meta``-mode blueprint from ``quickfort list`` by adding a ``hidden()`` marker to their modelines. That way the output of ``quickfort list`` won't be cluttered by From 01741ce6c607995ae9e4456394c2e334061072f3 Mon Sep 17 00:00:00 2001 From: myk002 Date: Wed, 11 Nov 2020 16:53:29 -0800 Subject: [PATCH 09/10] update quickfort guide and aliases - move bit of alias documentation from aliases-common to aliases.txt - document new behavior for 'c'ustom stockpiles --- data/quickfort/aliases-common.txt | 7 +++---- dfhack-config/quickfort/aliases.txt | 6 +++++- docs/guides/quickfort-user-guide.rst | 11 +++++------ 3 files changed, 13 insertions(+), 11 deletions(-) diff --git a/data/quickfort/aliases-common.txt b/data/quickfort/aliases-common.txt index 857160711..59705f9f7 100644 --- a/data/quickfort/aliases-common.txt +++ b/data/quickfort/aliases-common.txt @@ -17,10 +17,6 @@ # # Aliases that don't fit into those two categories have comments explaining # their usage. -# -# There is also a non-alphanumeric alias built into the code for the common -# shorthand for "make room": -# r+ expands to r+& ######################################## @@ -41,6 +37,9 @@ give10down: {give move={Down 10}} give10left: {give move={Left 10}} give10right: {give move={Right 10}} +# usage example: {givename name="myname"} +givename: {Ctrl}n{name}& + # use to toggle a sequence of stockpile options. for example: {togglesequence 5} togglesequence: &{Down} togglesequence2: &{Down 2} diff --git a/dfhack-config/quickfort/aliases.txt b/dfhack-config/quickfort/aliases.txt index 2743a39f3..9be32107e 100644 --- a/dfhack-config/quickfort/aliases.txt +++ b/dfhack-config/quickfort/aliases.txt @@ -95,8 +95,12 @@ # ! expands to {Ctrl} # ^ expands to {ESC} # +# There is also a non-standard alias built into the code for the common +# shorthand for "make room": +# r+ expands to r+& +# # If you need literal verisons of the shorthand characters, surround them in -# curly brackets, for example: "{~}" +# curly brackets, for example: "{!}" # # # Add your custom aliases here: diff --git a/docs/guides/quickfort-user-guide.rst b/docs/guides/quickfort-user-guide.rst index 5ab0956f7..1d9c1a024 100644 --- a/docs/guides/quickfort-user-guide.rst +++ b/docs/guides/quickfort-user-guide.rst @@ -502,12 +502,11 @@ meeting area all at once: #zone main pasture and picnic area nmg(10x10) -The order of the individual letters doesn't matter. Note that "custom" -(:kbd:`c`) stockpiles cannot be declared in a blueprint since what would -get created would depend on what happens to be set in the "custom stockpile -settings" in your game. Instead, place stockpiles using the keys that -represent the types you want to store and then use a ``#query`` blueprint to -customize them. +The order of the individual letters doesn't matter. If you want to configure the +stockpile from scratch in a ``#query`` blueprint, you can place unconfigured +"custom" stockpiles with (:kbd:`c`). It is more efficient, though, to place +stockpiles using the keys that represent the types you want to store, and +then only use a ``#query`` blueprint if you need fine-grained customization. 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 From d2472335fce9fb431f5ea2dc3859776116176b76 Mon Sep 17 00:00:00 2001 From: myk002 Date: Thu, 12 Nov 2020 23:20:53 -0800 Subject: [PATCH 10/10] add names for quantums and zones --- data/quickfort/aliases-common.txt | 15 +++++++++++++-- dfhack-config/quickfort/aliases.txt | 12 ++++++------ 2 files changed, 19 insertions(+), 8 deletions(-) diff --git a/data/quickfort/aliases-common.txt b/data/quickfort/aliases-common.txt index 59705f9f7..e4d2ef1cd 100644 --- a/data/quickfort/aliases-common.txt +++ b/data/quickfort/aliases-common.txt @@ -37,7 +37,8 @@ give10down: {give move={Down 10}} give10left: {give move={Left 10}} give10right: {give move={Right 10}} -# usage example: {givename name="myname"} +# Keep in mind that building, stockpile, and zone names have a maximum length +# of 20 characters. usage example: {givename name="myname"} givename: {Ctrl}n{name}& # use to toggle a sequence of stockpile options. for example: {togglesequence 5} @@ -49,7 +50,9 @@ 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}{enablefurniture}{enablestone}{enableammo}{enablecoins}{enablebars}{enablegems}{enablefinishedgoods}{enableleather}{enablecloth}{enablewood}{enableweapons}{enablearmor}{enablesheet} +# Optionally set a name for the stockpile by specifying the 'name' parameter, +# for example: {quantum name="my name"} +quantum: {linksonly}{nocontainers}{enableanimals}{enablefood}{enablefurniture}{enablestone}{enableammo}{enablecoins}{enablebars}{enablegems}{enablefinishedgoods}{enableleather}{enablecloth}{enablewood}{enableweapons}{enablearmor}{enablesheet}{givename} ################################## @@ -84,6 +87,14 @@ quantumstopfromwest: {quantumstopprefix}s{Left}p^{Right}{quantumstopsuffix} quantumstopfromnorth: {quantumstopprefix}s{Up}p^{Down}{quantumstopsuffix} +################################## +# zone aliases +################################## + +# usage example: {namezone name="my zone name"} +namezone: ^i{givename}^q + + ################################## # animal stockpile adjustments ################################## diff --git a/dfhack-config/quickfort/aliases.txt b/dfhack-config/quickfort/aliases.txt index 9be32107e..1d1ebff9f 100644 --- a/dfhack-config/quickfort/aliases.txt +++ b/dfhack-config/quickfort/aliases.txt @@ -58,12 +58,12 @@ # The syntax for defining aliases is: # aliasname: keystrokes # -# Where aliasname is at least two letters or digits long and keystrokes are -# whatever you would type into the DF UI. A keystroke can also be a named -# keycode from the DF interface definition file (data/init/interface.txt), -# enclosed in curly brackets like an alias, like: "{Right}" or "{Enter}". In -# order to avoid naming conflicts between aliases and keycodes, the convention -# is to start aliases with a lowercase letter. +# Where aliasname is at least two letters or digits long (including dashes and +# underscores) and keystrokes are whatever you would type into the DF UI. A +# keystroke can also be a named keycode from the DF interface definition file +# (data/init/interface.txt), enclosed in curly brackets like an alias, like: +# "{Right}" or "{Enter}". In # order to avoid naming conflicts between aliases +# and keycodes, the convention is to start aliases with a lowercase letter. # # Anything enclosed within curly brackets can also have a number after it, # indicating how many times that alias or keycode should be repeated. For