diff --git a/docs/Plugins.rst b/docs/Plugins.rst index 17f0c968f..cc88381fb 100644 --- a/docs/Plugins.rst +++ b/docs/Plugins.rst @@ -473,6 +473,42 @@ UI Upgrades :local: +.. _automaterial: + +automaterial +============ +This makes building constructions (walls, floors, fortifications, etc) a little bit +easier by saving you from having to trawl through long lists of materials each time +you place one. + +Firstly, it moves the last used material for a given construction type to the top of +the list, if there are any left. So if you build a wall with chalk blocks, the next +time you place a wall the chalk blocks will be at the top of the list, regardless of +distance (it only does this in "grouped" mode, as individual item lists could be huge). +This should mean you can place most constructions without having to search for your +preferred material type. + +.. image:: images/automaterial-mat.png + +Pressing :kbd:`a` while highlighting any material will enable that material for "auto select" +for this construction type. You can enable multiple materials as autoselect. Now the next +time you place this type of construction, the plugin will automatically choose materials +for you from the kinds you enabled. If there is enough to satisfy the whole placement, +you won't be prompted with the material screen - the construction will be placed and you +will be back in the construction menu as if you did it manually. + +When choosing the construction placement, you will see a couple of options: + +.. image:: images/automaterial-pos.png + +Use :kbd:`a` here to temporarily disable the material autoselection, e.g. if you need +to go to the material selection screen so you can toggle some materials on or off. + +The other option (auto type selection, off by default) can be toggled on with :kbd:`t`. If you +toggle this option on, instead of returning you to the main construction menu after selecting +materials, it returns you back to this screen. If you use this along with several autoselect +enabled materials, you should be able to place complex constructions more conveniently. + .. _automelt: automelt @@ -489,6 +525,112 @@ When autotrade is enabled for a stockpile, any items placed in it will be designated to be taken to the Trade Depot whenever merchants are on the map. This plugin adds an option to the :kbd:`q` menu when `enabled `. +.. _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 +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. + +.. _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. + +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. + +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. + +.. _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:: + + buildingplan set + +and displayed with:: + + buildingplan set + +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:: + + on-new-fortress buildingplan set boulders false; buildingplan set logs false + +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. + +.. _confirm: + +confirm +======= +Implements several confirmation dialogs for potentially destructive actions +(for example, seizing goods from traders or deleting hauling routes). + +Usage: + +:enable confirm: Enable all confirmations; alias ``confirm enable all``. + Replace with ``disable`` to disable. +:confirm help: List available confirmation dialogues. +:confirm enable option1 [option2...]: + Enable (or disable) specific confirmation dialogues. + .. _command-prompt: command-prompt @@ -601,6 +743,41 @@ Enable a space sperate list of filters Usage: ``debugfilter enable [id...]`` +.. _embark-assistant: + +embark-assistant +================ + +This plugin provides embark site selection help. It has to be run with the +``embark-assistant`` command while the pre-embark screen is displayed and shows +extended (and correct(?)) resource information for the embark rectangle as well +as normally undisplayed sites in the current embark region. It also has a site +selection tool with more options than DF's vanilla search tool. For detailed +help invoke the in game info screen. + +.. _embark-tools: + +embark-tools +============ +A collection of embark-related tools. Usage and available tools:: + + embark-tools enable/disable tool [tool]... + +:anywhere: Allows embarking anywhere (including sites, mountain-only biomes, + and oceans). Use with caution. +:mouse: Implements mouse controls (currently in the local embark region only) +:sand: Displays an indicator when sand is present in the currently-selected + area, similar to the default clay/stone indicators. +:sticky: Maintains the selected local area while navigating the world map + +.. _follow: + +follow +====== +Makes the game view follow the currently highlighted unit after you exit from the +current menu or cursor mode. Handy for watching dwarves running around. Deactivated +by moving the view manually. + .. _hotkeys: hotkeys @@ -612,14 +789,6 @@ active in the current context. See also `hotkey-notes`. :dfhack-keybind:`hotkeys` -.. _rb: -.. _ruby: - -ruby -==== -Ruby language plugin, which evaluates the following arguments as a ruby string. -Best used as ``:rb [string]``, for the special parsing mode. Alias ``rb_eval``. - .. _manipulator: manipulator @@ -692,47 +861,24 @@ the selected dwarves will be reset to the labors of the chosen profession. Professions are saved as human-readable text files in the "professions" folder within the DF folder, and can be edited or deleted there. -.. comment - the link target "search" is reserved for the Sphinx search page -.. _search-plugin: - -search -====== -The search plugin adds search to the Stocks, Animals, Trading, Stockpile, -Noble (assignment candidates), Military (position candidates), Burrows -(unit list), Rooms, Announcements, Job List and Unit List screens. - -.. image:: images/search.png - -Searching works the same way as the search option in :guilabel:`Move to Depot`. -You will see the Search option displayed on screen with a hotkey (usually :kbd:`s`). -Pressing it lets you start typing a query and the relevant list will start -filtering automatically. - -Pressing :kbd:`Enter`, :kbd:`Esc` or the arrow keys will return you to browsing the now -filtered list, which still functions as normal. You can clear the filter -by either going back into search mode and backspacing to delete it, or -pressing the "shifted" version of the search hotkey while browsing the -list (e.g. if the hotkey is :kbd:`s`, then hitting :kbd:`Shift`:kbd:`s` will clear any -filter). - -Leaving any screen automatically clears the filter. +.. _mousequery: -In the Trade screen, the actual trade will always only act on items that -are actually visible in the list; the same effect applies to the Trade -Value numbers displayed by the screen. Because of this, the :kbd:`t` key is -blocked while search is active, so you have to reset the filters first. -Pressing :kbd:`Alt`:kbd:`C` will clear both search strings. +mousequery +========== +Adds mouse controls to the DF interface, e.g. click-and-drag designations. -In the stockpile screen the option only appears if the cursor is in the -rightmost list: +Options: -.. image:: images/search-stockpile.png +:plugin: enable/disable the entire plugin +:rbutton: enable/disable right mouse button +:track: enable/disable moving cursor in build and designation mode +:edge: enable/disable active edge scrolling (when on, will also enable tracking) +:live: enable/disable query view when unpaused +:delay: Set delay when edge scrolling in tracking mode. Omit amount to display current setting. -Note that the 'Permit XXX'/'Forbid XXX' keys conveniently operate only -on items actually shown in the rightmost list, so it is possible to select -only fat or tallow by forbidding fats, then searching for fat/tallow, and -using Permit Fats again while the list is filtered. +Usage:: + mousequery [plugin] [rbutton] [track] [edge] [live] [enable|disable] .. _nopause: @@ -741,228 +887,104 @@ nopause Disables pausing (both manual and automatic) with the exception of pause forced by `reveal` ``hell``. This is nice for digging under rivers. -.. _embark-assistant: - -embark-assistant -================ - -This plugin provides embark site selection help. It has to be run with the -``embark-assistant`` command while the pre-embark screen is displayed and shows -extended (and correct(?)) resource information for the embark rectangle as well -as normally undisplayed sites in the current embark region. It also has a site -selection tool with more options than DF's vanilla search tool. For detailed -help invoke the in game info screen. - -.. _embark-tools: +.. _rename: -embark-tools -============ -A collection of embark-related tools. Usage and available tools:: +rename +====== +Allows renaming various things. Use `gui/rename` for an in-game interface. - embark-tools enable/disable tool [tool]... +Options: -:anywhere: Allows embarking anywhere (including sites, mountain-only biomes, - and oceans). Use with caution. -:mouse: Implements mouse controls (currently in the local embark region only) -:sand: Displays an indicator when sand is present in the currently-selected - area, similar to the default clay/stone indicators. -:sticky: Maintains the selected local area while navigating the world map - -.. _automaterial: - -automaterial -============ -This makes building constructions (walls, floors, fortifications, etc) a little bit -easier by saving you from having to trawl through long lists of materials each time -you place one. - -Firstly, it moves the last used material for a given construction type to the top of -the list, if there are any left. So if you build a wall with chalk blocks, the next -time you place a wall the chalk blocks will be at the top of the list, regardless of -distance (it only does this in "grouped" mode, as individual item lists could be huge). -This should mean you can place most constructions without having to search for your -preferred material type. - -.. image:: images/automaterial-mat.png - -Pressing :kbd:`a` while highlighting any material will enable that material for "auto select" -for this construction type. You can enable multiple materials as autoselect. Now the next -time you place this type of construction, the plugin will automatically choose materials -for you from the kinds you enabled. If there is enough to satisfy the whole placement, -you won't be prompted with the material screen - the construction will be placed and you -will be back in the construction menu as if you did it manually. - -When choosing the construction placement, you will see a couple of options: - -.. image:: images/automaterial-pos.png - -Use :kbd:`a` here to temporarily disable the material autoselection, e.g. if you need -to go to the material selection screen so you can toggle some materials on or off. - -The other option (auto type selection, off by default) can be toggled on with :kbd:`t`. If you -toggle this option on, instead of returning you to the main construction menu after selecting -materials, it returns you back to this screen. If you use this along with several autoselect -enabled materials, you should be able to place complex constructions more conveniently. - -.. _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 -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. - -.. _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. - -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. - -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. - -.. _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:: - - buildingplan set - -and displayed with:: - - buildingplan set - -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:: +``rename squad "name"`` + Rename squad by index to 'name'. +``rename hotkey \"name\"`` + Rename hotkey by index. This allows assigning + longer commands to the DF hotkeys. +``rename unit "nickname"`` + Rename a unit/creature highlighted in the DF user interface. +``rename unit-profession "custom profession"`` + Change proffession name of the highlighted unit/creature. +``rename building "name"`` + Set a custom name for the selected building. + The building must be one of stockpile, workshop, furnace, trap, + siege engine or an activity zone. - on-new-fortress buildingplan set boulders false; buildingplan set logs false +.. _rendermax: -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. +rendermax +========= +A collection of renderer replacing/enhancing filters. For better effect try changing the +black color in palette to non totally black. See :forums:`128487` for more info. -.. _confirm: +Options: -confirm -======= -Implements several confirmation dialogs for potentially destructive actions -(for example, seizing goods from traders or deleting hauling routes). +:trippy: Randomizes the color of each tiles. Used for fun, or testing. +:light: Enable lighting engine. +:light reload: Reload the settings file. +:light sun |cycle: Set time to (in hours) or set it to df time cycle. +:occlusionON, occlusionOFF: Show debug occlusion info. +:disable: Disable any filter that is enabled. -Usage: +An image showing lava and dragon breath. Not pictured here: sunlight, shining items/plants, +materials that color the light etc... -:enable confirm: Enable all confirmations; alias ``confirm enable all``. - Replace with ``disable`` to disable. -:confirm help: List available confirmation dialogues. -:confirm enable option1 [option2...]: - Enable (or disable) specific confirmation dialogues. +.. image:: images/rendermax.png -.. _follow: +.. _resume: -follow +resume ====== -Makes the game view follow the currently highlighted unit after you exit from the -current menu or cursor mode. Handy for watching dwarves running around. Deactivated -by moving the view manually. - -.. _mousequery: - -mousequery -========== -Adds mouse controls to the DF interface, e.g. click-and-drag designations. +Allows automatic resumption of suspended constructions, along with colored +UI hints for construction status. -Options: +.. _rb: +.. _ruby: -:plugin: enable/disable the entire plugin -:rbutton: enable/disable right mouse button -:track: enable/disable moving cursor in build and designation mode -:edge: enable/disable active edge scrolling (when on, will also enable tracking) -:live: enable/disable query view when unpaused -:delay: Set delay when edge scrolling in tracking mode. Omit amount to display current setting. +ruby +==== +Ruby language plugin, which evaluates the following arguments as a ruby string. +Best used as ``:rb [string]``, for the special parsing mode. Alias ``rb_eval``. -Usage:: +.. comment - the link target "search" is reserved for the Sphinx search page +.. _search-plugin: - mousequery [plugin] [rbutton] [track] [edge] [live] [enable|disable] +search +====== +The search plugin adds search to the Stocks, Animals, Trading, Stockpile, +Noble (assignment candidates), Military (position candidates), Burrows +(unit list), Rooms, Announcements, Job List and Unit List screens. -.. _resume: +.. image:: images/search.png -resume -====== -Allows automatic resumption of suspended constructions, along with colored -UI hints for construction status. +Searching works the same way as the search option in :guilabel:`Move to Depot`. +You will see the Search option displayed on screen with a hotkey (usually :kbd:`s`). +Pressing it lets you start typing a query and the relevant list will start +filtering automatically. -.. _title-folder: +Pressing :kbd:`Enter`, :kbd:`Esc` or the arrow keys will return you to browsing the now +filtered list, which still functions as normal. You can clear the filter +by either going back into search mode and backspacing to delete it, or +pressing the "shifted" version of the search hotkey while browsing the +list (e.g. if the hotkey is :kbd:`s`, then hitting :kbd:`Shift`:kbd:`s` will clear any +filter). -title-folder -============= -Displays the DF folder name in the window title bar when enabled. +Leaving any screen automatically clears the filter. -.. _title-version: +In the Trade screen, the actual trade will always only act on items that +are actually visible in the list; the same effect applies to the Trade +Value numbers displayed by the screen. Because of this, the :kbd:`t` key is +blocked while search is active, so you have to reset the filters first. +Pressing :kbd:`Alt`:kbd:`C` will clear both search strings. -title-version -============= -Displays the DFHack version on DF's title screen when enabled. +In the stockpile screen the option only appears if the cursor is in the +rightmost list: -.. _trackstop: +.. image:: images/search-stockpile.png -trackstop -========= -Adds a :kbd:`q` menu for track stops, which is completely blank by default. -This allows you to view and/or change the track stop's friction and dump -direction settings, using the keybindings from the track stop building interface. +Note that the 'Permit XXX'/'Forbid XXX' keys conveniently operate only +on items actually shown in the rightmost list, so it is possible to select +only fat or tallow by forbidding fats, then searching for fat/tallow, and +using Permit Fats again while the list is filtered. .. _sort: .. _sort-items: @@ -1003,14 +1025,6 @@ The orderings are defined in ``hack/lua/plugins/sort/*.lua`` :dfhack-keybind:`sort-units` -.. _stocks: - -stocks -====== -Replaces the DF stocks screen with an improved version. - -:dfhack-keybind:`stocks` - .. _stocksettings: .. _stockpiles: @@ -1041,48 +1055,34 @@ Note that files are relative to the DF folder, so put your files there or in a subfolder for easy access. Filenames should not have spaces. Generated materials, divine metals, etc are not saved as they are different in every world. -.. _rename: +.. _stocks: -rename +stocks ====== -Allows renaming various things. Use `gui/rename` for an in-game interface. +Replaces the DF stocks screen with an improved version. -Options: +:dfhack-keybind:`stocks` -``rename squad "name"`` - Rename squad by index to 'name'. -``rename hotkey \"name\"`` - Rename hotkey by index. This allows assigning - longer commands to the DF hotkeys. -``rename unit "nickname"`` - Rename a unit/creature highlighted in the DF user interface. -``rename unit-profession "custom profession"`` - Change proffession name of the highlighted unit/creature. -``rename building "name"`` - Set a custom name for the selected building. - The building must be one of stockpile, workshop, furnace, trap, - siege engine or an activity zone. -.. _rendermax: +.. _title-folder: -rendermax -========= -A collection of renderer replacing/enhancing filters. For better effect try changing the -black color in palette to non totally black. See :forums:`128487` for more info. +title-folder +============= +Displays the DF folder name in the window title bar when enabled. -Options: +.. _title-version: -:trippy: Randomizes the color of each tiles. Used for fun, or testing. -:light: Enable lighting engine. -:light reload: Reload the settings file. -:light sun |cycle: Set time to (in hours) or set it to df time cycle. -:occlusionON, occlusionOFF: Show debug occlusion info. -:disable: Disable any filter that is enabled. +title-version +============= +Displays the DFHack version on DF's title screen when enabled. -An image showing lava and dragon breath. Not pictured here: sunlight, shining items/plants, -materials that color the light etc... +.. _trackstop: -.. image:: images/rendermax.png +trackstop +========= +Adds a :kbd:`q` menu for track stops, which is completely blank by default. +This allows you to view and/or change the track stop's friction and dump +direction settings, using the keybindings from the track stop building interface. ===========================