From 19a4accca4c247ccd2f6c8999df5154d2cab0e4b Mon Sep 17 00:00:00 2001 From: myk002 Date: Mon, 18 Jul 2022 16:58:01 -0700 Subject: [PATCH] update docs for bulidingplan --- docs/plugins/buildingplan.rst | 136 +++++++++++++++++----------------- plugins/buildingplan.cpp | 6 +- 2 files changed, 70 insertions(+), 72 deletions(-) diff --git a/docs/plugins/buildingplan.rst b/docs/plugins/buildingplan.rst index ca6273d10..4b21da8af 100644 --- a/docs/plugins/buildingplan.rst +++ b/docs/plugins/buildingplan.rst @@ -1,88 +1,86 @@ 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 -to always have one or two doors/beds/tables/chairs/etc available, and place -as many as you like. The plugins then take over and fulfill the orders, -with minimal space dedicated to stockpiles. +Plan building construction before you have materials. 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. -.. _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. +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. +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. -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. +Usage:: -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. + enable buildingplan + buildingplan set + buildingplan set true|false -Note that Quickfort mode is only for compatibility with the legacy Python Quickfort. The -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. +Running ``buildingplan set`` without parameters displays the current settings. .. _buildingplan-settings: Global settings --------------- -The buildingplan plugin has several global settings that can be set from the UI (:kbd:`G` -from any building placement screen, for example: :kbd:`b`:kbd:`a`:kbd:`G`). These settings -can also be set from the ``DFHack#`` prompt once a map is loaded (or from your -``onMapLoad.init`` file) with the syntax:: +The buildingplan plugin has global settings that can be set from the UI +(:kbd:`G` from any building placement screen, for example: +:kbd:`b`:kbd:`a`:kbd:`G`). These settings can also be set via the +``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 + on-new-fortress buildingplan set boulders false; buildingplan set logs false -and displayed with:: +.. _buildingplan-filters: - buildingplan set +Item filtering +-------------- -The available settings are: - -+----------------+---------+-----------+---------------------------------------+ -| 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:: +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. - 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 -your game, so you only need to set them to the values you want once. +Note that Quickfort mode is only for compatibility with the legacy Python +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. diff --git a/plugins/buildingplan.cpp b/plugins/buildingplan.cpp index 594eaf48f..b13c8daa3 100644 --- a/plugins/buildingplan.cpp +++ b/plugins/buildingplan.cpp @@ -1058,9 +1058,9 @@ DFhackCExport command_result plugin_enable(color_ostream &out, bool enable) DFhackCExport command_result plugin_init ( color_ostream &out, std::vector &commands) { commands.push_back( - PluginCommand( - "buildingplan", "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.")); + PluginCommand("buildingplan", + "Plan building construction before you have materials.", + buildingplan_cmd)); return CR_OK; }