update docs for bulidingplan

develop
myk002 2022-07-18 16:58:01 -07:00
parent 629c22b148
commit 19a4accca4
No known key found for this signature in database
GPG Key ID: 8A39CA0FA0C16E78
2 changed files with 70 additions and 72 deletions

@ -1,88 +1,86 @@
buildingplan buildingplan
============ ============
When active (via ``enable buildingplan``), this plugin adds a planning mode for
building placement. You can then place furniture, constructions, and other buildings
before the required materials are available, and they will be created in a suspended
state. Buildingplan will periodically scan for appropriate items, and the jobs will
be unsuspended when the items are available.
This is very useful when combined with `workflow` - you can set a constraint Plan building construction before you have materials. This plugin adds a
to always have one or two doors/beds/tables/chairs/etc available, and place planning mode for building placement. You can then place furniture,
as many as you like. The plugins then take over and fulfill the orders, constructions, and other buildings before the required materials are available,
with minimal space dedicated to stockpiles. and they will be created in a suspended state. Buildingplan will periodically
scan for appropriate items, and the jobs will be unsuspended when the items are
available.
.. _buildingplan-filters: This is very useful when combined with manager work orders or `workflow` -- you
can set a constraint to always have one or two doors/beds/tables/chairs/etc.
Item filtering available, and place as many as you like. Materials are used to build the
-------------- planned buildings as they are produced, with minimal space dedicated to
stockpiles.
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 Usage::
a filter to accept only certain types of stone.
Quickfort mode enable buildingplan
-------------- buildingplan set
buildingplan set <setting> true|false
If you use the external Python Quickfort to apply building blueprints instead of the native
DFHack `quickfort` script, you must enable Quickfort mode. This temporarily enables
buildingplan for all building types and adds an extra blank screen after every building
placement. This "dummy" screen is needed for Python Quickfort to interact successfully with
Dwarf Fortress.
Note that Quickfort mode is only for compatibility with the legacy Python Quickfort. The Running ``buildingplan set`` without parameters displays the current settings.
DFHack `quickfort` script does not need Quickfort mode to be enabled. The `quickfort` script
will successfully integrate with buildingplan as long as the buildingplan plugin is enabled.
.. _buildingplan-settings: .. _buildingplan-settings:
Global settings Global settings
--------------- ---------------
The buildingplan plugin has several global settings that can be set from the UI (:kbd:`G` The buildingplan plugin has global settings that can be set from the UI
from any building placement screen, for example: :kbd:`b`:kbd:`a`:kbd:`G`). These settings (:kbd:`G` from any building placement screen, for example:
can also be set from the ``DFHack#`` prompt once a map is loaded (or from your :kbd:`b`:kbd:`a`:kbd:`G`). These settings can also be set via the
``onMapLoad.init`` file) with the syntax:: ``buildingplan set`` command. The available settings are:
- ``all_enabled`` (default: false)
Enable planning mode for all building types.
- ``blocks``, ``boulders``, ``logs``, ``bars`` (defaults: true, true, true, false)
Allow blocks, boulders, logs, or bars to be matched for generic "building
material" items.
- ``quickfort_mode`` (default: false)
Enable compatibility mode for the legacy Python Quickfort (this setting is
not required for DFHack `quickfort`)
The settings for ``blocks``, ``boulders``, ``logs``, and ``bars`` are saved with
your fort, so you only have to set them once and they will be persisted in your
save.
If you normally embark with some blocks on hand for early workshops, you might
want to add this line to your ``dfhack-config/init/onMapLoad.init`` file to
always configure buildingplan to just use blocks for buildlings and
constructions::
buildingplan set <setting> <true|false> on-new-fortress buildingplan set boulders false; buildingplan set logs false
and displayed with:: .. _buildingplan-filters:
buildingplan set Item filtering
--------------
The available settings are: 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.
| Setting | Default | Persisted | Description |
+================+=========+===========+=======================================+
| all_enabled | false | no | Enable planning mode for all building |
| | | | types. |
+----------------+---------+-----------+---------------------------------------+
| blocks | true | yes | Allow blocks, boulders, logs, or bars |
+----------------+---------+ | to be matched for generic "building |
| boulders | true | | material" items |
+----------------+---------+ | |
| logs | true | | |
+----------------+---------+ | |
| bars | false | | |
+----------------+---------+-----------+---------------------------------------+
| quickfort_mode | false | no | Enable compatibility mode for the |
| | | | legacy Python Quickfort (not required |
| | | | for DFHack quickfort) |
+----------------+---------+-----------+---------------------------------------+
For example, to ensure you only use blocks when a "building material" item is required, you
could add this to your ``onMapLoad.init`` file::
on-new-fortress buildingplan set boulders false; buildingplan set logs false 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.
Quickfort mode
--------------
If you use the external Python Quickfort to apply building blueprints instead of
the native DFHack `quickfort` script, you must enable Quickfort mode. This
temporarily enables buildingplan for all building types and adds an extra blank
screen after every building placement. This "dummy" screen is needed for Python
Quickfort to interact successfully with Dwarf Fortress.
Persisted settings (i.e. ``blocks``, ``boulders``, ``logs``, and ``bars``) are saved with Note that Quickfort mode is only for compatibility with the legacy Python
your game, so you only need to set them to the values you want once. Quickfort. The DFHack `quickfort` script does not need this Quickfort mode to be
enabled. The `quickfort` script will successfully integrate with buildingplan as
long as the buildingplan plugin itself is enabled.

@ -1058,9 +1058,9 @@ DFhackCExport command_result plugin_enable(color_ostream &out, bool enable)
DFhackCExport command_result plugin_init ( color_ostream &out, std::vector <PluginCommand> &commands) DFhackCExport command_result plugin_init ( color_ostream &out, std::vector <PluginCommand> &commands)
{ {
commands.push_back( commands.push_back(
PluginCommand( PluginCommand("buildingplan",
"buildingplan", "Plan building construction before you have materials", "Plan building construction before you have materials.",
buildingplan_cmd, false, "Run 'buildingplan debug [on|off]' to toggle debugging, or 'buildingplan version' to query the plugin version.")); buildingplan_cmd));
return CR_OK; return CR_OK;
} }