From fb143516cd898d14355353d0551205fe0bac3c5f Mon Sep 17 00:00:00 2001 From: myk002 Date: Sat, 30 Jan 2021 19:32:41 -0800 Subject: [PATCH] refresh the dreamfort case study --- docs/changelog.txt | 5 +- docs/guides/quickfort-user-guide.rst | 91 +++++++++++++++------------- 2 files changed, 50 insertions(+), 46 deletions(-) diff --git a/docs/changelog.txt b/docs/changelog.txt index 989a9c558..918768ff9 100644 --- a/docs/changelog.txt +++ b/docs/changelog.txt @@ -51,9 +51,8 @@ changelog.txt uses a syntax similar to RST, with a few special sequences: - `buildingplan`: added ability to set global settings from the console, e.g. ``buildingplan set boulders false`` - `buildingplan`: added "enable all" option for buildingplan (so you don't have to enable all building types individually). This setting is not persisted (just like quickfort_mode is not persisted), but it can be set from onMapLoad.init - `buildingplan`: modified ``Planning Mode`` status in the UI to show whether the plugin is in quickfort mode, "enable all" mode, or whether just the building type is enabled. -- `quickfort`: Dreamfort blueprint set improvements: added a streamlined checklist for all required dreamfort commands and gave names to stockpiles, levers, bridges, and zones -- `quickfort`: added aliases for bronze weapons and armor -- `quickfort`: added alias for tradeable crafts +- `quickfort`: Dreamfort blueprint set improvements: in addition to `significant `_ changes to the blueprints themselves, added a streamlined checklist for all required dreamfort commands for easy reference +- `quickfort`: added aliases for tradeable crafts and bronze weapons/armor ## Lua - ``dfhack.run_command()``: changed to interface directly with the console when possible, which allows interactive commands and commands that detect the console encoding to work properly diff --git a/docs/guides/quickfort-user-guide.rst b/docs/guides/quickfort-user-guide.rst index 96da52131..9cc5a56de 100644 --- a/docs/guides/quickfort-user-guide.rst +++ b/docs/guides/quickfort-user-guide.rst @@ -1158,19 +1158,18 @@ The Dreamfort blueprints we'll be discussing are available in the library as :source:`one large .csv file ` or `online `__ as -individual spreadsheets. Either can be read and applied by quickfort, but for us -humans, the online spreadsheets are much easier to work with. Each spreadsheet -has a "Notes" sheet with some useful details. Flip through some of the -spreadsheets and read the `walkthrough -`__ to get oriented. -Also, if you haven't built Dreamfort before, try an embark in a flat area and -take it for a spin! +individual spreadsheets. Either the .csv file or the exported spreadsheet .xlsx +files can be read and applied by quickfort, but for us humans, the online +spreadsheets are much easier to work with. Each spreadsheet has a "Notes" sheet +with some useful details. Flip through some of the spreadsheets and read the +`walkthrough `__ +to get oriented. Also, if you haven't built Dreamfort before, try an embark in a +flat area and take it for a spin! Almost every quickfort feature is used somewhere in Dreamfort, so the blueprints -as a whole are useful as practical examples. You can copy the blueprints and use -them as starting points for your own, or just refer to them when you create -something similar. +are useful as practical examples. You can copy the blueprints and use them as +starting points for your own, or just refer to them when you create something +similar. In this case study, we'll start by discussing the high level organization of the Dreamfort blueprint set, using the "surface" blueprints as an example. Then @@ -1200,16 +1199,15 @@ the toil associated with applying so many blueprints. The single most effective way to make your blueprint sets easier to use is to group them with `meta blueprints `. For the Dreamfort set of blueprints, each logical "step" generally takes more than one blueprint. For -example, setting up pastures with a ``#zone`` blueprint, placing starting -stockpiles with a #place blueprint, building starting workshops with a -``#build`` blueprint, and configuring the stockpiles with a ``#query`` blueprint -can all be done at once. Bundling blueprints like this reduced the number of -steps in Dreamfort from 47 to 24, and it also made it much clearer to see which -blueprints can be applied at once without unpausing the game. Check out -dreamfort_surface's "`meta -`__" sheet to -see how much meta blueprints can simplify your life. +example, with ``#meta`` blueprints, setting up pastures with a ``#zone`` +blueprint, placing starting stockpiles with a ``#place`` blueprint, building +starting workshops with a ``#build`` blueprint, and configuring the stockpiles +with a ``#query`` blueprint can all be done with a single command. Bundling +blueprints with ``#meta`` blueprints reduced the number of steps in Dreamfort +from 61 to 23, and it also made it much clearer to see which blueprints can be +applied at once without unpausing the game. Check out dreamfort_surface's "`meta +`__" +sheet to see how much meta blueprints can simplify your life. You can define `as many blueprints as you want ` on one sheet, but multi-blueprint sheets are especially useful when writing meta @@ -1220,7 +1218,7 @@ blueprints. It's like having a bird's eye view of your entire plan in one sheet. Keep the blueprint list uncluttered by using ``hidden()`` markers. If a blueprint is bundled into a meta blueprint, it does not need to appear in -the quickfort list output since you won't be running it directly. Add a +the ``quickfort list`` output since you won't be running it directly. Add a `hidden() marker ` to those blueprints to keep the list output tidy. You can still access hidden blueprints with ``quickfort list --hidden`` if you need to -- for example to reapply a partially completed @@ -1253,7 +1251,7 @@ sheet, like in surface's meta sheet. .. topic:: Tip - Use message() markers to remind yourself what to do next. + Use ``message()`` markers to remind yourself what to do next. `Messages ` are displayed after a blueprint is applied. Good things to include in messages are: @@ -1265,12 +1263,11 @@ things to include in messages are: zones These things are just too easy to forget. Adding a ``message()`` can save you -from time-wasting mistakes. Note that message() markers can still appear on the -``hidden()`` blueprints, and they'll still get shown when the blueprint is run -via a ``#meta`` blueprint. For an example of this, check out the `zones sheet -`__ where the -pastures are defined. +from time-wasting mistakes. Note that ``message()`` markers can still appear on +the ``hidden()`` blueprints, and they'll still get shown when the blueprint is +run via a ``#meta`` blueprint. For an example of this, check out the `zones +sheet `__ +where the pastures are defined. The farming_ level: fun with stockpiles ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1294,7 +1291,7 @@ stockpiles. Note the `careful customization wsszA1AnFqoxeoehByg/edit#gid=486506218>`__ of the food stockpiles and the stockpile chains set up with the ``give*`` aliases. This is so when multiple stockpiles can hold the same item, the largest can keep the smaller ones filled. -For example the ``give2left`` alias funnels seeds from the seeds feeder pile to +For example the ``give2up`` alias funnels seeds from the seeds feeder pile to the container-enabled seed storage pile. If you have multiple stockpiles holding the same type on different z-levels, though, this can be tricky to set up with a blueprint. Here, the jugs and pots stockpiles must be manually linked to the @@ -1308,7 +1305,7 @@ z-levels away that is. Note how we call that out in the ``#query`` blueprint's 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 with simple aliases +blueprints for how the quantum refuse dump is configured with simple aliases from the alias library. The industry_ level: when not to use aliases @@ -1328,15 +1325,14 @@ It may be tempting to put all query blueprint key sequences into aliases to make them easier to edit, keep them all in one place, and make them reusable, but some key sequences just aren't very valuable as aliases. -`Check out `__ the Eastern (goods) and Northern -(stone and gems) quantum stockpiles -- cells I19 and R10. They give to the -jeweler's workshop to prevent the jeweler from using the gems held in reserve -for strange moods. The keys are not aliased since they're dependent on the -relative positions of the tiles where they are interpreted, which is easiest to -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 a separate -alias definition. +`Check out `__ +the Eastern (goods) and Northern (stone and gems) quantum stockpiles -- cells +I19 and R10. They give to the jeweler's workshop to prevent the jeweler from +using the gems held in reserve for strange moods. The keys are not aliased since +they're dependent on the relative positions of the tiles where they are +interpreted, which is easiest to 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 a separate alias definition. There are also good examples in the ``#query`` blueprint for how to use the ``permit`` and ``forbid`` stockpile aliases. @@ -1377,6 +1373,10 @@ order-sensitive aliases on the same line:: #query Properly configure a food stockpile to accept tallow and dye {tallow}{permitdye} +You can see a more complex example of this with the ``meltables`` stockpiles in +the `lower right corner `__ +of the industry level. + The services_ level: handling multi-level dig blueprints ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1393,11 +1393,16 @@ priorities `. We can `ensure `__ the bottom level is carved out before the layer above is channelled by assigning -the channel designations lower priorities (the ``h5``\s in the third layer). +the channel designations lower priorities (the ``h5``\s in the third layer -- +scroll down). An alternative is to have a follow-up blueprint that removes any undesired -ramps. We did this on the surface and farming levels with the miasma vents since -it would be too complicated to synchronize the digging between the two layers. +ramps. We did this on the +`surface `__ +and +`farming `__ +levels with the miasma vents since it would be too complicated to synchronize +the digging between the two layers. The guildhall_ level: avoiding smoothing issues ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~