update docs

develop
Myk Taylor 2023-02-26 10:53:30 -08:00
parent fbd3cd44d6
commit 63d752b3f8
No known key found for this signature in database
2 changed files with 61 additions and 38 deletions

@ -1308,7 +1308,7 @@ legacy Python Quickfort. This setting has no effect on DFHack Quickfort, which
will use buildingplan to manage everything designated in a ``#build`` blueprint will use buildingplan to manage everything designated in a ``#build`` blueprint
regardless of the buildingplan UI settings. regardless of the buildingplan UI settings.
However, quickfort *does* use `buildingplan's filters <buildingplan-filters>` However, quickfort *does* use `buildingplan's filters <buildingplan>`
for each building type. For example, you can use the buildingplan UI to set the for each building type. For example, you can use the buildingplan UI to set the
type of stone you want your walls made out of. Or you can specify that all type of stone you want your walls made out of. Or you can specify that all
buildingplan-managed chairs and tables must be of Masterful quality. The current buildingplan-managed chairs and tables must be of Masterful quality. The current

@ -2,32 +2,73 @@ buildingplan
============ ============
.. dfhack-tool:: .. dfhack-tool::
:summary: Plan building construction before you have materials. :summary: Plan building layouts with or without materials.
:tags: fort design buildings :tags: fort design buildings
This plugin adds a planning mode for building placement. You can then place Buildingplan allows you to place furniture, constructions, and other buildings,
furniture, constructions, and other buildings before the required materials are regardless of whether the required materials are available. This allows you to
available, and they will be created in a suspended state. Buildingplan will focus purely on design elements when you are laying out your fort, and defers
periodically scan for appropriate items, and the jobs will be unsuspended when item production concerns to a more convenient time.
the items are available.
Buildingplan is as an alternative to the vanilla building placement UI. It
This is very powerful when used with tools like `quickfort`, which allow you to appears after you have selected the type of building, furniture, or construction
set a building plan according to a blueprint, and the buildings will simply be that you want to place in the vanilla build menu. Buildingplan then takes over
built when you can build them. for the actual placement step. If any building materials are not available yet
for the placed building, it will be created in a suspended state. Buildingplan
You can use manager work orders or `workflow` to ensure you always have one or will periodically scan for appropriate items and attach them. Once all items are
two doors/beds/tables/chairs/etc. available, and place as many as you like. attached, the construction job will be unsuspended and a dwarf will come and
Materials are used to build the planned buildings as they are produced, with build the building. If you have the `unsuspend` overlay enabled (it is enabled
minimal space dedicated to stockpiles. 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.
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.
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.
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.
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
planned buildings in loaded forts will stop functioning.
Usage Usage
----- -----
:: ::
enable buildingplan
buildingplan [status] buildingplan [status]
buildingplan set <setting> true|false buildingplan set <setting> (true|false)
Examples
--------
``buildingplan``
Print a report of current settings, which kinds of buildings are planned,
and what kinds of materials the buildings are waiting for.
.. _buildingplan-settings: .. _buildingplan-settings:
@ -49,23 +90,5 @@ want to add this line to your ``dfhack-config/init/onMapLoad.init`` file to
always configure `buildingplan` to just use blocks for buildings and always configure `buildingplan` to just use blocks for buildings and
constructions:: constructions::
on-new-fortress buildingplan set boulders false; buildingplan set logs false on-new-fortress buildingplan set boulders false
on-new-fortress buildingplan set logs false
.. _buildingplan-filters:
Item filtering
--------------
While placing a building, you can set filters for what materials you want the
building made out of, what quality you want the component items to be, and
whether you want the items to be decorated.
If a building type takes more than one item to construct, use
:kbd:`Ctrl`:kbd:`Left` and :kbd:`Ctrl`:kbd:`Right` to select the item that you
want to set filters for. Any filters that you set will be used for all buildings
of the selected type placed from that point onward (until you set a new filter
or clear the current one). Buildings placed before the filters were changed will
keep the filter values that were set when the building was placed.
For example, you can be sure that all your constructed walls are the same color
by setting a filter to accept only certain types of stone.