MetzNet
/
dfhack
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

update docs

develop
Myk Taylor 2023-03-06 00:00:25 -08:00
parent e9060624af
commit bb0d4c410d
No known key found for this signature in database
2 changed files with 107 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

126
docs/plugins/buildingplan.rst
Unescape Escape View File

@ -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.

4
docs/plugins/overlay.rst
Unescape Escape View File

@ -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
-----