From bb0d4c410dae7194271ac8df04ce31d9d388ba6d Mon Sep 17 00:00:00 2001 From: Myk Taylor Date: Mon, 6 Mar 2023 00:00:25 -0800 Subject: [PATCH] update docs --- docs/plugins/buildingplan.rst | 126 ++++++++++++++++++++++++++++------ docs/plugins/overlay.rst | 4 +- 2 files changed, 107 insertions(+), 23 deletions(-) diff --git a/docs/plugins/buildingplan.rst b/docs/plugins/buildingplan.rst index f77e5b590..d6fce19b8 100644 --- a/docs/plugins/buildingplan.rst +++ b/docs/plugins/buildingplan.rst @@ -18,41 +18,41 @@ for the placed building, it will be created in a suspended state. Buildingplan will periodically scan for appropriate items and attach them. Once all items are attached, the construction job will be unsuspended and a dwarf will come and build the building. If you have the `unsuspend` overlay enabled (it is enabled -by default), then buildingplan-suspended buildings will appear with a ``P`` marker -on the main map, as opposed to the usual ``x`` marker for "regular" suspended -buildings. +by default), then buildingplan-suspended buildings will appear with a ``P`` +marker on the main map, as opposed to the usual ``x`` marker for "regular" +suspended buildings. If you want to impose restrictions on which items are chosen for the buildings, buildingplan has full support for quality and material filters. Before you place -a building, you can select a component item in the list and hit ``f`` or click on -the ``filter`` button next to the item description. This will let you choose your -desired item quality range, whether the item must be decorated, and even which -specific materials the item must be made out of. This lets you create layouts -with a consistent color, if that is part of your design. +a building, you can select a component item in the list and hit ``f`` or click +on the ``filter`` button next to the item description. This will let you choose +your desired item quality range, whether the item must be decorated, and even +which specific materials the item must be made out of. This lets you create +layouts with a consistent color, if that is part of your design. If you just care about the heat sensitivity of the building, you can set the building to be fire- or magma-proof in the placement UI screen or in any item -filter screen, and the restriction will apply to all building items. This makes it -very easy to create magma-safe pump stacks, for example. +filter screen, and the restriction will apply to all building items. This makes +it very easy to create magma-safe pump stacks, for example. Buildingplan works very well in conjuction with other design tools like -`gui/quickfort`, which allow you to apply a building layout from a blueprint. You -can apply very large, complicated layouts, and the buildings will simply be built -when your dwarves get around to producing the needed materials. If you set filters -in the buildingplan UI before applying the blueprint, the filters will be applied -to the blueprint buildings, just as if you had planned them from the buildingplan -placement UI. +`gui/quickfort`, which allow you to apply a building layout from a blueprint. +You can apply very large, complicated layouts, and the buildings will simply be +built when your dwarves get around to producing the needed materials. If you +set filters in the buildingplan UI before applying the blueprint, the filters +will be applied to the blueprint buildings, just as if you had planned them +from the buildingplan placement UI. One way to integrate buildingplan into your gameplay is to create manager workorders to ensure you always have a few blocks/doors/beds/etc. available. You can then place as many of each building as you like. Produced items will be used -to build the planned buildings as they are produced, with minimal space dedicated -to stockpiles. The DFHack `orders` library can help with setting up these manager -workorders for you. +to build the planned buildings as they are produced, with minimal space +dedicated to stockpiles. The DFHack `orders` library can help with setting up +these manager workorders for you. If you do not wish to use the ``buildingplan`` interface, you can turn off the -``buildingplan.planner`` overlay in `gui/overlay`. You should not disable the -``buildingplan`` service entirely in `gui/control-panel` since then existing +``buildingplan.planner`` overlay in `gui/control-panel`. You should not disable +the ``buildingplan`` service entirely in `gui/control-panel` since existing planned buildings in loaded forts will stop functioning. Usage @@ -92,3 +92,87 @@ constructions:: on-new-fortress buildingplan set boulders false on-new-fortress buildingplan set logs false + +Building placement +------------------ + +Once you have selected a building type to build in the vanilla build menu, the +`buildingplan` placement UI appears as an `overlay` widget, covering the +vanilla building placement panel. + +For basic usage, you don't need to change any settings. Just click to place +buildings of the selected type and right click to exit building mode. Any +buildings that require materials that you don't have on hand will be suspended +and built when the items are available. + +When building constructions, you'll get a few extra options, like whether the +construction area should be hollow or what types of stairs you'd like at the +top and bottom of a stairwell. Also, unlike other buildings, it is ok if some +tiles selected in the construction area are not appropriate for building. For +example, if you want to fill an area with flooring, you can select the entire +area, and any tiles with existing buildings or walls will simply be skipped. + +Setting heat safety filters ++++++++++++++++++++++++++++ + +If you specifically need the building to be magma- or fire-safe, click on the +"Building safety" button or hit :kbd:`g` until the desired heat safety is +displayed. This filter applies to all items used to construct the building. + +Setting quality and material filters +++++++++++++++++++++++++++++++++++++ + +If you want to set restrictions on the items chosen to complete the planned +building, you can click on the "filter" button next to the item name or select +the item with the :kbd:`*` and :kbd:`/` keys and hit :kbd:`f` to bring up the +filter dialog. + +You can select whether the item must be decorated, and you can drag the ends of +the "Item quality" slider to set your desired quality range. Note that blocks, +boulders, logs, and bars don't have a quality and the quality options are +disabled for those types. As you change the quality settings, the number of +currently available matched items of each material appears in the materials +list. + +You can click on specific materials to allow only items of those materials when +building the current type of building. You can also allow or disallow entire +categories of materials by clicking on the "Type" options on the left. Note +that it is perfectly fine to choose materials that currently show 0 quantity. +`buildingplan` will patiently watch for items made of materials you have +selected. + +Choosing specific items ++++++++++++++++++++++++ + +If you want to choose specific items, click on the "Choose from items" toggle +or hit :kbd:`i` before placing the building. When you click to place the +building, a dialog will come up that allows you choose which items to use. The +list is sorted by most recently used materials for that building type by +default, but you can change to sort by name or by available quantity by +clicking on the "Sort by" selector or hitting :kbd:`R`. + +You can select the maximum quantity of a specified item by clicking on the item +name or selecting it with the arrow keys and hitting :kbd:`Enter`. You can +instead select items one at a time by Ctrl-clicking (:kbd:`Shift`:kbd:`Right`) +to increment or Ctrl-Shift-clicking (:kbd:`Shift`:kbd:`Left`) to decrement. + +Once you are satisfied with your choices, click on the "Build" button or hit +:kbd:`B` to continue building. Note that you don't have to select all the items +that the building needs. Any remaining items will be automatically chosen from +other available items (or future items if not all items are available yet). If +there are multiple item types to choose for the current building, one dialog +will appear per item type. + +Building status +--------------- + +When viewing a planned building, a separate `overlay` widget appears on the +building info sheet, showing you which items have been attached and which items +are still pending. For the pending items, you can see its position in the +fulfillment queue. If there is a particular building that you need built ASAP, +you can click on the "make top priority" button (or hit :kbd:`Ctrl`:kbd:`T`) to +bump the items for this building to the front of their respective queues. + +Note that each item type and filter configuration has its own queue, so even if +an item is in queue position 1, there may be other queues that snag the needed +item first. diff --git a/docs/plugins/overlay.rst b/docs/plugins/overlay.rst index ab63de67e..313220fd4 100644 --- a/docs/plugins/overlay.rst +++ b/docs/plugins/overlay.rst @@ -7,8 +7,8 @@ overlay The overlay framework manages the on-screen widgets that other tools (including 3rd party plugins and scripts) can register for display. For a graphical -configuration interface, please see `gui/overlay`. If you are a developer who -wants to write an overlay widget, please see the `overlay-dev-guide`. +configuration interface, please see `gui/control-panel`. If you are a developer +who wants to write an overlay widget, please see the `overlay-dev-guide`. Usage -----