diff --git a/docs/Plugins.rst b/docs/Plugins.rst index 2e8eb34f3..bf337a527 100644 --- a/docs/Plugins.rst +++ b/docs/Plugins.rst @@ -15,6 +15,161 @@ hopefully organised in a way you will find useful. :local: :depth: 2 +======== +Bugfixes +======== + +.. contents:: + :local: + +.. _fix-armory: + +fix-armory +========== +`This plugin requires a binpatch `, which has not +been available since DF 0.34.11 + +.. _fix-unit-occupancy: + +fix-unit-occupancy +================== +This plugin fixes issues with unit occupancy, notably phantom +"unit blocking tile" messages (:bug:`3499`). It can be run manually, or +periodically when enabled with the built-in enable/disable commands: + +:(no argument): Run the plugin once immediately, for the whole map. +:-h, here, cursor: Run immediately, only operate on the tile at the cursor +:-n, dry, dry-run: Run immediately, do not write changes to map +:interval : Run the plugin every ``X`` ticks (when enabled). + The default is 1200 ticks, or 1 day. + Ticks are only counted when the game is unpaused. + +.. _fixveins: + +fixveins +======== +Removes invalid references to mineral inclusions and restores missing ones. +Use this if you broke your embark with tools like `tiletypes`, or if you +accidentally placed a construction on top of a valuable mineral floor. + +.. _petcapRemover: + +petcapRemover +============= +Allows you to remove or raise the pet population cap. In vanilla +DF, pets will not reproduce unless the population is below 50 and the number of +children of that species is below a certain percentage. This plugin allows +removing the second restriction and removing or raising the first. Pets still +require PET or PET_EXOTIC tags in order to reproduce. Type ``help petcapRemover`` +for exact usage. In order to make population more stable and avoid sudden +population booms as you go below the raised population cap, this plugin counts +pregnancies toward the new population cap. It can still go over, but only in the +case of multiple births. + +Usage: + +:petcapRemover: cause pregnancies now and schedule the next check +:petcapRemover every n: set how often in ticks the plugin checks for possible pregnancies +:petcapRemover cap n: set the new cap to n. if n = 0, no cap +:petcapRemover pregtime n: sets the pregnancy duration to n ticks. natural pregnancies are + 300000 ticks for the current race and 200000 for everyone else + +.. _tweak: + +tweak +===== +Contains various tweaks for minor bugs. + +One-shot subcommands: + +:clear-missing: Remove the missing status from the selected unit. + This allows engraving slabs for ghostly, but not yet + found, creatures. +:clear-ghostly: Remove the ghostly status from the selected unit and mark + it as dead. This allows getting rid of bugged ghosts + which do not show up in the engraving slab menu at all, + even after using clear-missing. It works, but is + potentially very dangerous - so use with care. Probably + (almost certainly) it does not have the same effects like + a proper burial. You've been warned. +:fixmigrant: Remove the resident/merchant flag from the selected unit. + Intended to fix bugged migrants/traders who stay at the + map edge and don't enter your fort. Only works for + dwarves (or generally the player's race in modded games). + Do NOT abuse this for 'real' caravan merchants (if you + really want to kidnap them, use 'tweak makeown' instead, + otherwise they will have their clothes set to forbidden etc). +:makeown: Force selected unit to become a member of your fort. + Can be abused to grab caravan merchants and escorts, even if + they don't belong to the player's race. Foreign sentients + (humans, elves) can be put to work, but you can't assign rooms + to them and they don't show up in DwarfTherapist because the + game treats them like pets. Grabbing draft animals from + a caravan can result in weirdness (animals go insane or berserk + and are not flagged as tame), but you are allowed to mark them + for slaughter. Grabbing wagons results in some funny spam, then + they are scuttled. + +Subcommands that persist until disabled or DF quits: + +.. comment: sort these alphabetically + +:adamantine-cloth-wear: Prevents adamantine clothing from wearing out while being worn (:bug:`6481`). +:advmode-contained: Works around :bug:`6202`, custom reactions with container inputs + in advmode. The issue is that the screen tries to force you to select + the contents separately from the container. This forcefully skips child + reagents. +:block-labors: Prevents labors that can't be used from being toggled +:burrow-name-cancel: Implements the "back" option when renaming a burrow, + which currently does nothing (:bug:`1518`) +:cage-butcher: Adds an option to butcher units when viewing cages with :kbd:`q` +:civ-view-agreement: Fixes overlapping text on the "view agreement" screen +:condition-material: Fixes a crash in the work order contition material list (:bug:`9905`). +:craft-age-wear: Fixes the behavior of crafted items wearing out over time (:bug:`6003`). + With this tweak, items made from cloth and leather will gain a level of + wear every 20 years. +:do-job-now: Adds a job priority toggle to the jobs list +:embark-profile-name: Allows the use of lowercase letters when saving embark profiles +:eggs-fertile: Displays a fertility indicator on nestboxes +:farm-plot-select: Adds "Select all" and "Deselect all" options to farm plot menus +:fast-heat: Further improves temperature update performance by ensuring that 1 degree + of item temperature is crossed in no more than specified number of frames + when updating from the environment temperature. This reduces the time it + takes for stable-temp to stop updates again when equilibrium is disturbed. +:fast-trade: Makes Shift-Down in the Move Goods to Depot and Trade screens select + the current item (fully, in case of a stack), and scroll down one line. +:fps-min: Fixes the in-game minimum FPS setting +:hide-priority: Adds an option to hide designation priority indicators +:hotkey-clear: Adds an option to clear currently-bound hotkeys (in the :kbd:`H` menu) +:import-priority-category: + Allows changing the priority of all goods in a + category when discussing an import agreement with the liaison +:kitchen-prefs-all: Adds an option to toggle cook/brew for all visible items in kitchen preferences +:kitchen-prefs-color: Changes color of enabled items to green in kitchen preferences +:kitchen-prefs-empty: Fixes a layout issue with empty kitchen tabs (:bug:`9000`) +:max-wheelbarrow: Allows assigning more than 3 wheelbarrows to a stockpile +:military-color-assigned: + Color squad candidates already assigned to other squads in yellow/green + to make them stand out more in the list. + + .. image:: images/tweak-mil-color.png + +:military-stable-assign: + Preserve list order and cursor position when assigning to squad, + i.e. stop the rightmost list of the Positions page of the military + screen from constantly resetting to the top. +:nestbox-color: Fixes the color of built nestboxes +:reaction-gloves: Fixes reactions to produce gloves in sets with correct handedness (:bug:`6273`) +:shift-8-scroll: Gives Shift-8 (or :kbd:`*`) priority when scrolling menus, instead of scrolling the map +:stable-cursor: Saves the exact cursor position between t/q/k/d/b/etc menus of fortress mode, if the + map view is near enough to its previous position. +:stone-status-all: Adds an option to toggle the economic status of all stones +:title-start-rename: Adds a safe rename option to the title screen "Start Playing" menu +:tradereq-pet-gender: Displays pet genders on the trade request screen + +.. comment: sort these alphabetically + + =============================== Data inspection and visualizers =============================== @@ -302,2899 +457,2742 @@ An isometric visualizer that runs in a second window. Usage: For more information, see `the full Stonesense README `. - - -======== -Bugfixes -======== +=========================== +Job and Fortress management +=========================== .. contents:: :local: -.. _fix-armory: - -fix-armory -========== -`This plugin requires a binpatch `, which has not -been available since DF 0.34.11 -.. _fix-unit-occupancy: +.. _autobutcher: -fix-unit-occupancy -================== -This plugin fixes issues with unit occupancy, notably phantom -"unit blocking tile" messages (:bug:`3499`). It can be run manually, or -periodically when enabled with the built-in enable/disable commands: +autobutcher +=========== +Assigns lifestock for slaughter once it reaches a specific count. Requires that +you add the target race(s) to a watch list. Only tame units will be processed. -:(no argument): Run the plugin once immediately, for the whole map. -:-h, here, cursor: Run immediately, only operate on the tile at the cursor -:-n, dry, dry-run: Run immediately, do not write changes to map -:interval : Run the plugin every ``X`` ticks (when enabled). - The default is 1200 ticks, or 1 day. - Ticks are only counted when the game is unpaused. +Units will be ignored if they are: -.. _fixveins: +* Nicknamed (for custom protection; you can use the `rename` ``unit`` tool + individually, or `zone` ``nick`` for groups) +* Caged, if and only if the cage is defined as a room (to protect zoos) +* Trained for war or hunting -fixveins -======== -Removes invalid references to mineral inclusions and restores missing ones. -Use this if you broke your embark with tools like `tiletypes`, or if you -accidentally placed a construction on top of a valuable mineral floor. +Creatures who will not reproduce (because they're not interested in the +opposite sex or have been gelded) will be butchered before those who will. +Older adults and younger children will be butchered first if the population +is above the target (default 1 male, 5 female kids and adults). Note that +you may need to set a target above 1 to have a reliable breeding population +due to asexuality etc. See `fix-ster` if this is a problem. -.. _petcapRemover: +Options: -petcapRemover -============= -Allows you to remove or raise the pet population cap. In vanilla -DF, pets will not reproduce unless the population is below 50 and the number of -children of that species is below a certain percentage. This plugin allows -removing the second restriction and removing or raising the first. Pets still -require PET or PET_EXOTIC tags in order to reproduce. Type ``help petcapRemover`` -for exact usage. In order to make population more stable and avoid sudden -population booms as you go below the raised population cap, this plugin counts -pregnancies toward the new population cap. It can still go over, but only in the -case of multiple births. +:example: Print some usage examples. +:start: Start running every X frames (df simulation ticks). + Default: X=6000, which would be every 60 seconds at 100fps. +:stop: Stop running automatically. +:sleep : Changes the timer to sleep X frames between runs. +:watch R: Start watching a race. R can be a valid race RAW id (ALPACA, + BIRD_TURKEY, etc) or a list of ids seperated by spaces or + the keyword 'all' which affects all races on your current + watchlist. +:unwatch R: Stop watching race(s). The current target settings will be + remembered. R can be a list of ids or the keyword 'all'. +:forget R: Stop watching race(s) and forget it's/their target settings. + R can be a list of ids or the keyword 'all'. +:autowatch: Automatically adds all new races (animals you buy from merchants, + tame yourself or get from migrants) to the watch list using + default target count. +:noautowatch: Stop auto-adding new races to the watchlist. +:list: Print the current status and watchlist. +:list_export: Print the commands needed to set up status and watchlist, + which can be used to import them to another save (see notes). +:target : + Set target count for specified race(s). The first four arguments + are the number of female and male kids, and female and male adults. + R can be a list of spceies ids, or the keyword ``all`` or ``new``. + ``R = 'all'``: change target count for all races on watchlist + and set the new default for the future. ``R = 'new'``: don't touch + current settings on the watchlist, only set the new default + for future entries. +:list_export: Print the commands required to rebuild your current settings. -Usage: +.. note:: -:petcapRemover: cause pregnancies now and schedule the next check -:petcapRemover every n: set how often in ticks the plugin checks for possible pregnancies -:petcapRemover cap n: set the new cap to n. if n = 0, no cap -:petcapRemover pregtime n: sets the pregnancy duration to n ticks. natural pregnancies are - 300000 ticks for the current race and 200000 for everyone else + Settings and watchlist are stored in the savegame, so that you can have + different settings for each save. If you want to copy your watchlist to + another savegame you must export the commands required to recreate your settings. -.. _tweak: + To export, open an external terminal in the DF directory, and run + ``dfhack-run autobutcher list_export > filename.txt``. To import, load your + new save and run ``script filename.txt`` in the DFHack terminal. -tweak -===== -Contains various tweaks for minor bugs. -One-shot subcommands: +Examples: -:clear-missing: Remove the missing status from the selected unit. - This allows engraving slabs for ghostly, but not yet - found, creatures. -:clear-ghostly: Remove the ghostly status from the selected unit and mark - it as dead. This allows getting rid of bugged ghosts - which do not show up in the engraving slab menu at all, - even after using clear-missing. It works, but is - potentially very dangerous - so use with care. Probably - (almost certainly) it does not have the same effects like - a proper burial. You've been warned. -:fixmigrant: Remove the resident/merchant flag from the selected unit. - Intended to fix bugged migrants/traders who stay at the - map edge and don't enter your fort. Only works for - dwarves (or generally the player's race in modded games). - Do NOT abuse this for 'real' caravan merchants (if you - really want to kidnap them, use 'tweak makeown' instead, - otherwise they will have their clothes set to forbidden etc). -:makeown: Force selected unit to become a member of your fort. - Can be abused to grab caravan merchants and escorts, even if - they don't belong to the player's race. Foreign sentients - (humans, elves) can be put to work, but you can't assign rooms - to them and they don't show up in DwarfTherapist because the - game treats them like pets. Grabbing draft animals from - a caravan can result in weirdness (animals go insane or berserk - and are not flagged as tame), but you are allowed to mark them - for slaughter. Grabbing wagons results in some funny spam, then - they are scuttled. +You want to keep max 7 kids (4 female, 3 male) and max 3 adults (2 female, +1 male) of the race alpaca. Once the kids grow up the oldest adults will get +slaughtered. Excess kids will get slaughtered starting with the youngest +to allow that the older ones grow into adults. Any unnamed cats will +be slaughtered as soon as possible. :: -Subcommands that persist until disabled or DF quits: + autobutcher target 4 3 2 1 ALPACA BIRD_TURKEY + autobutcher target 0 0 0 0 CAT + autobutcher watch ALPACA BIRD_TURKEY CAT + autobutcher start -.. comment: sort these alphabetically +Automatically put all new races onto the watchlist and mark unnamed tame units +for slaughter as soon as they arrive in your fort. Settings already made +for specific races will be left untouched. :: -:adamantine-cloth-wear: Prevents adamantine clothing from wearing out while being worn (:bug:`6481`). -:advmode-contained: Works around :bug:`6202`, custom reactions with container inputs - in advmode. The issue is that the screen tries to force you to select - the contents separately from the container. This forcefully skips child - reagents. -:block-labors: Prevents labors that can't be used from being toggled -:burrow-name-cancel: Implements the "back" option when renaming a burrow, - which currently does nothing (:bug:`1518`) -:cage-butcher: Adds an option to butcher units when viewing cages with :kbd:`q` -:civ-view-agreement: Fixes overlapping text on the "view agreement" screen -:condition-material: Fixes a crash in the work order contition material list (:bug:`9905`). -:craft-age-wear: Fixes the behavior of crafted items wearing out over time (:bug:`6003`). - With this tweak, items made from cloth and leather will gain a level of - wear every 20 years. -:do-job-now: Adds a job priority toggle to the jobs list -:embark-profile-name: Allows the use of lowercase letters when saving embark profiles -:eggs-fertile: Displays a fertility indicator on nestboxes -:farm-plot-select: Adds "Select all" and "Deselect all" options to farm plot menus -:fast-heat: Further improves temperature update performance by ensuring that 1 degree - of item temperature is crossed in no more than specified number of frames - when updating from the environment temperature. This reduces the time it - takes for stable-temp to stop updates again when equilibrium is disturbed. -:fast-trade: Makes Shift-Down in the Move Goods to Depot and Trade screens select - the current item (fully, in case of a stack), and scroll down one line. -:fps-min: Fixes the in-game minimum FPS setting -:hide-priority: Adds an option to hide designation priority indicators -:hotkey-clear: Adds an option to clear currently-bound hotkeys (in the :kbd:`H` menu) -:import-priority-category: - Allows changing the priority of all goods in a - category when discussing an import agreement with the liaison -:kitchen-prefs-all: Adds an option to toggle cook/brew for all visible items in kitchen preferences -:kitchen-prefs-color: Changes color of enabled items to green in kitchen preferences -:kitchen-prefs-empty: Fixes a layout issue with empty kitchen tabs (:bug:`9000`) -:max-wheelbarrow: Allows assigning more than 3 wheelbarrows to a stockpile -:military-color-assigned: - Color squad candidates already assigned to other squads in yellow/green - to make them stand out more in the list. + autobutcher target 0 0 0 0 new + autobutcher autowatch + autobutcher start - .. image:: images/tweak-mil-color.png +Stop watching the races alpaca and cat, but remember the target count +settings so that you can use 'unwatch' without the need to enter the +values again. Note: 'autobutcher unwatch all' works, but only makes sense +if you want to keep the plugin running with the 'autowatch' feature or manually +add some new races with 'watch'. If you simply want to stop it completely use +'autobutcher stop' instead. :: -:military-stable-assign: - Preserve list order and cursor position when assigning to squad, - i.e. stop the rightmost list of the Positions page of the military - screen from constantly resetting to the top. -:nestbox-color: Fixes the color of built nestboxes -:reaction-gloves: Fixes reactions to produce gloves in sets with correct handedness (:bug:`6273`) -:shift-8-scroll: Gives Shift-8 (or :kbd:`*`) priority when scrolling menus, instead of scrolling the map -:stable-cursor: Saves the exact cursor position between t/q/k/d/b/etc menus of fortress mode, if the - map view is near enough to its previous position. -:stone-status-all: Adds an option to toggle the economic status of all stones -:title-start-rename: Adds a safe rename option to the title screen "Start Playing" menu -:tradereq-pet-gender: Displays pet genders on the trade request screen + autobutcher unwatch ALPACA CAT -.. comment: sort these alphabetically +.. _autochop: -=========== -UI Upgrades -=========== +autochop +======== +Automatically manage tree cutting designation to keep available logs withing given +quotas. -.. note:: - In order to avoid user confusion, as a matter of policy all GUI tools - display the word :guilabel:`DFHack` on the screen somewhere while active. +Open the dashboard by running:: - When that is not appropriate because they merely add keybinding hints to - existing DF screens, they deliberately use red instead of green for the key. + enable autochop -.. contents:: - :local: +The plugin must be activated (with :kbd:`d`-:kbd:`t`-:kbd:`c`-:kbd:`a`) before +it can be used. You can then set logging quotas and restrict designations to +specific burrows (with 'Enter') if desired. The plugin's activity cycle runs +once every in game day. +If you add ``enable autochop`` to your dfhack.init there will be a hotkey to +open the dashboard from the chop designation menu. -.. _automaterial: +.. _autoclothing: -automaterial +autoclothing ============ -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. +Automatically manage clothing work orders, allowing the user to set how many of +each clothing type every citizen should have. Usage:: -.. image:: images/automaterial-mat.png + autoclothing [number] -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. +Examples: -When choosing the construction placement, you will see a couple of options: +* ``autoclothing cloth "short skirt" 10``: + Sets the desired number of cloth short skirts available per citizen to 10. +* ``autoclothing cloth dress``: + Displays the currently set number of cloth dresses chosen per citizen. -.. image:: images/automaterial-pos.png +.. _autodump: -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. +autodump +======== +This plugin adds an option to the :kbd:`q` menu for stckpiles when `enabled `. +When autodump is enabled for a stockpile, any items placed in the stockpile will +automatically be designated to be dumped. -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. +Alternatively, you can use it to quickly move all items designated to be dumped. +Items are instantly moved to the cursor position, the dump flag is unset, +and the forbid flag is set, as if it had been dumped normally. +Be aware that any active dump item tasks still point at the item. -.. _automelt: +Cursor must be placed on a floor tile so the items can be dumped there. -automelt -======== -When automelt is enabled for a stockpile, any meltable items placed -in it will be designated to be melted. -This plugin adds an option to the :kbd:`q` menu when `enabled `. +Options: -.. _autotrade: +:destroy: Destroy instead of dumping. Doesn't require a cursor. + If called again before the game is resumed, cancels destroy. +:destroy-here: As ``destroy``, but only the selected item in the :kbd:`k` list, + or inside a container. + Alias ``autodump-destroy-here``, for keybindings. + :dfhack-keybind:`autodump-destroy-here` +:visible: Only process items that are not hidden. +:hidden: Only process hidden items. +:forbidden: Only process forbidden items (default: only unforbidden). -autotrade -========= -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 `. +``autodump-destroy-item`` destroys the selected item, which may be selected +in the :kbd:`k` list, or inside a container. If called again before the game +is resumed, cancels destruction of the item. +:dfhack-keybind:`autodump-destroy-item` -.. _buildingplan: +.. _autofarm: -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. +autofarm +======== -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. +Automatically handles crop selection in farm plots based on current plant +stocks, and selects crops for planting if current stock is below a threshold. +Selected crops are dispatched on all farmplots. (Note that this plugin replaces +an older Ruby script of the same name.) -.. _buildingplan-filters: +Use the `enable` or `disable ` commands to change whether this plugin is +enabled. -Item filtering --------------- +Usage: -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. +* ``autofarm runonce``: + Updates all farm plots once, without enabling the plugin +* ``autofarm status``: + Prints status information, including any applied limits +* ``autofarm default 30``: + Sets the default threshold +* ``autofarm threshold 150 helmet_plump tail_pig``: + Sets thresholds of individual plants -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. +.. _autogems: -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. +autogems +======== +Creates a new Workshop Order setting, automatically cutting rough gems +when `enabled `. -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. +See `gui/autogems` for a configuration UI. If necessary, the ``autogems-reload`` +command reloads the configuration file produced by that script. -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. +.. _autohauler: -.. _buildingplan-settings: +autohauler +========== +Autohauler is an autolabor fork. -Global settings ---------------- +Rather than the all-of-the-above means of autolabor, autohauler will instead +only manage hauling labors and leave skilled labors entirely to the user, who +will probably use Dwarf Therapist to do so. -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:: +Idle dwarves will be assigned the hauling labors; everyone else (including +those currently hauling) will have the hauling labors removed. This is to +encourage every dwarf to do their assigned skilled labors whenever possible, +but resort to hauling when those jobs are not available. This also implies +that the user will have a very tight skill assignment, with most skilled +labors only being assigned to just one dwarf, no dwarf having more than two +active skilled labors, and almost every non-military dwarf having at least +one skilled labor assigned. - buildingplan set +Autohauler allows skills to be flagged as to prevent hauling labors from +being assigned when the skill is present. By default this is the unused +ALCHEMIST labor but can be changed by the user. -and displayed with:: +.. _autolabor: - buildingplan set +autolabor +========= +Automatically manage dwarf labors to efficiently complete jobs. +Autolabor tries to keep as many dwarves as possible busy but +also tries to have dwarves specialize in specific skills. -The available settings are: +The key is that, for almost all labors, once a dwarf begins a job it will finish that +job even if the associated labor is removed. Autolabor therefore frequently checks +which dwarf or dwarves should take new jobs for that labor, and sets labors accordingly. +Labors with equiptment (mining, hunting, and woodcutting), which are abandoned +if labors change mid-job, are handled slightly differently to minimise churn. -+----------------+---------+-----------+---------------------------------------+ -| 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) | -+----------------+---------+-----------+---------------------------------------+ +.. warning:: -For example, to ensure you only use blocks when a "building material" item is required, you -could add this to your ``onMapLoad.init`` file:: + *autolabor will override any manual changes you make to labors while + it is enabled, including through other tools such as Dwarf Therapist* - on-new-fortress buildingplan set boulders false; buildingplan set logs false +Simple usage: -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. +:enable autolabor: Enables the plugin with default settings. (Persistent per fortress) +:disable autolabor: Disables the plugin. -.. _confirm: +Anything beyond this is optional - autolabor works well on the default settings. -confirm -======= -Implements several confirmation dialogs for potentially destructive actions -(for example, seizing goods from traders or deleting hauling routes). +By default, each labor is assigned to between 1 and 200 dwarves (2-200 for mining). +By default 33% of the workforce become haulers, who handle all hauling jobs as well +as cleaning, pulling levers, recovering wounded, removing constructions, and filling ponds. +Other jobs are automatically assigned as described above. Each of these settings can be adjusted. -Usage: +Jobs are rarely assigned to nobles with responsibilities for meeting diplomats or merchants, +never to the chief medical dwarf, and less often to the bookeeper and manager. -: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. +Hunting is never assigned without a butchery, and fishing is never assigned without a fishery. -.. _command-prompt: +For each labor a preference order is calculated based on skill, biased against masters of other +trades and excluding those who can't do the job. The labor is then added to the best +dwarves for that labor. We assign at least the minimum number of dwarfs, in order of preference, +and then assign additional dwarfs that meet any of these conditions: -command-prompt -============== -An in-game DFHack terminal, where you can enter other commands. +* The dwarf is idle and there are no idle dwarves assigned to this labor +* The dwarf has non-zero skill associated with the labor +* The labor is mining, hunting, or woodcutting and the dwarf currently has it enabled. -:dfhack-keybind:`command-prompt` +We stop assigning dwarfs when we reach the maximum allowed. -Usage: ``command-prompt [entry]`` +Advanced usage: -If called with an entry, it starts with that text filled in. -Most useful for developers, who can set a keybinding to open -a laungage interpreter for lua or Ruby by starting with the -`:lua ` or `:rb ` commands. +:autolabor []: + Set number of dwarves assigned to a labor. +:autolabor haulers: Set a labor to be handled by hauler dwarves. +:autolabor disable: Turn off autolabor for a specific labor. +:autolabor reset: Return a labor to the default handling. +:autolabor reset-all: Return all labors to the default handling. +:autolabor list: List current status of all labors. +:autolabor status: Show basic status information. -Otherwise somewhat similar to `gui/quickcmd`. +See `autolabor-artisans` for a differently-tuned setup. -.. image:: images/command-prompt.png +Examples: +``autolabor MINE`` + Keep at least 5 dwarves with mining enabled. +``autolabor CUT_GEM 1 1`` + Keep exactly 1 dwarf with gemcutting enabled. +``autolabor COOK 1 1 3`` + Keep 1 dwarf with cooking enabled, selected only from the top 3. +``autolabor FEED_WATER_CIVILIANS haulers`` + Have haulers feed and water wounded dwarves. +``autolabor CUTWOOD disable`` + Turn off autolabor for wood cutting. -.. _debug: +.. _autonestbox: -debug -===== -Manager for DFHack runtime debug prints. Debug prints are grouped by plugin name, -category name and print level. Levels are ``trace``, ``debug``, ``info``, -``warning`` and ``error``. +autonestbox +=========== +Assigns unpastured female egg-layers to nestbox zones. Requires that you create +pen/pasture zones above nestboxes. If the pen is bigger than 1x1 the nestbox +must be in the top left corner. Only 1 unit will be assigned per pen, regardless +of the size. The age of the units is currently not checked, most birds grow up +quite fast. Egglayers who are also grazers will be ignored, since confining them +to a 1x1 pasture is not a good idea. Only tame and domesticated own units are +processed since pasturing half-trained wild egglayers could destroy your neat +nestbox zones when they revert to wild. When called without options autonestbox +will instantly run once. -The runtime message printing is controlled using filters. Filters set the -visible messages of all matching categories. Matching uses regular expression syntax, -which allows listing multiple alternative matches or partial name matches. -This syntax is a C++ version of the ECMA-262 grammar (Javascript regular expressions). -Details of differences can be found at -https://en.cppreference.com/w/cpp/regex/ecmascript +Options: -Persistent filters are stored in ``dfhack-config/runtime-debug.json``. -Oldest filters are applied first. That means a newer filter can override the -older printing level selection. +:start: Start running every X frames (df simulation ticks). + Default: X=6000, which would be every 60 seconds at 100fps. +:stop: Stop running automatically. +:sleep: Must be followed by number X. Changes the timer to sleep X + frames between runs. -Usage: ``debugfilter [subcommand] [parameters...]`` +.. _clean: -The following subcommands are supported: +clean +===== +Cleans all the splatter that get scattered all over the map, items and +creatures. In an old fortress, this can significantly reduce FPS lag. It can +also spoil your !!FUN!!, so think before you use it. -help ----- -Give overall help or a detailed help for a subcommand. +Options: -Usage: ``debugfilter help [subcommand]`` +:map: Clean the map tiles. By default, it leaves mud and snow alone. +:units: Clean the creatures. Will also clean hostiles. +:items: Clean all the items. Even a poisoned blade. -category --------- -List available debug plugin and category names. +Extra options for ``map``: -Usage: ``debugfilter category [plugin regex] [category regex]`` +:mud: Remove mud in addition to the normal stuff. +:snow: Also remove snow coverings. -The list can be filtered using optional regex parameters. If filters aren't -given then the it uses ``"."`` regex which matches any character. The regex -parameters are good way to test regex before passing them to ``set``. +.. _cleanowned: -filter ------- -List active and passive debug print level changes. +cleanowned +========== +Confiscates items owned by dwarfs. By default, owned food on the floor +and rotten items are confistacted and dumped. -Usage: ``debugfilter filter [id]`` +Options: -Optional ``id`` parameter is the id listed as first column in the filter list. -If id is given then the command shows information for the given filter only in -multi line format that is better format if filter has long regex. +:all: confiscate all owned items +:scattered: confiscated and dump all items scattered on the floor +:x: confiscate/dump items with wear level 'x' and more +:X: confiscate/dump items with wear level 'X' and more +:dryrun: a dry run. combine with other options to see what will happen + without it actually happening. -set ---- -Creates a new debug filter to set category printing levels. +Example: -Usage: ``debugfilter set [level] [plugin regex] [category regex]`` +``cleanowned scattered X`` + This will confiscate rotten and dropped food, garbage on the floors and any + worn items with 'X' damage and above. -Adds a filter that will be deleted when DF process exists or plugin is unloaded. +.. _dwarfmonitor: -Usage: ``debugfilter set persistent [level] [plugin regex] [category regex]`` +dwarfmonitor +============ +Records dwarf activity to measure fort efficiency. -Stores the filter in the configuration file to until ``unset`` is used to remove -it. +Options: -Level is the minimum debug printing level to show in log. +:enable : Start monitoring ``mode``. ``mode`` can be "work", "misery", + "weather", or "all". This will enable all corresponding widgets, + if applicable. +:disable : Stop monitoring ``mode``, and disable corresponding widgets, if applicable. +:stats: Show statistics summary +:prefs: Show dwarf preferences summary +:reload: Reload configuration file (``dfhack-config/dwarfmonitor.json``) -* ``trace``: Possibly very noisy messages which can be printed many times per second +:dfhack-keybind:`dwarfmonitor` -* ``debug``: Messages that happen often but they should happen only a couple of times per second +Widget configuration: -* ``info``: Important state changes that happen rarely during normal execution +The following types of widgets (defined in :file:`hack/lua/plugins/dwarfmonitor.lua`) +can be displayed on the main fortress mode screen: -* ``warning``: Enabled by default. Shows warnings about unexpected events which code managed to handle correctly. +:date: Show the in-game date +:misery: Show overall happiness levels of all dwarves +:weather: Show current weather (rain/snow) +:cursor: Show the current mouse cursor position -* ``error``: Enabled by default. Shows errors which code can't handle without user intervention. +The file :file:`dfhack-config/dwarfmonitor.json` can be edited to control the +positions and settings of all widgets displayed. This file should contain a +JSON object with the key ``widgets`` containing an array of objects - see the +included file in the ``dfhack-config`` folder for an example: -unset ------ -Delete a space separated list of filters +.. code-block:: lua -Usage: ``debugfilter unset [id...]`` + { + "widgets": [ + { + "type": "widget type (weather, misery, etc.)", + "x": X coordinate, + "y": Y coordinate + <...additional options...> + } + ] + } -disable -------- -Disable a space separated list of filters but keep it in the filter list +X and Y coordinates begin at zero (in the upper left corner of the screen). +Negative coordinates will be treated as distances from the lower right corner, +beginning at 1 - e.g. an x coordinate of 0 is the leftmost column, while an x +coordinate of 1 is the rightmost column. -Usage: ``debugfilter disable [id...]`` +By default, the x and y coordinates given correspond to the leftmost tile of +the widget. Including an ``anchor`` option set to ``right`` will cause the +rightmost tile of the widget to be located at this position instead. -enable ------- -Enable a space sperate list of filters +Some widgets support additional options: -Usage: ``debugfilter enable [id...]`` +* ``date`` widget: -.. _embark-assistant: + * ``format``: specifies the format of the date. The following characters + are replaced (all others, such as punctuation, are not modified) -embark-assistant -================ + * ``Y`` or ``y``: The current year + * ``M``: The current month, zero-padded if necessary + * ``m``: The current month, *not* zero-padded + * ``D``: The current day, zero-padded if necessary + * ``d``: The current day, *not* zero-padded -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. + The default date format is ``Y-M-D``, per the ISO8601_ standard. -.. _embark-tools: + .. _ISO8601: https://en.wikipedia.org/wiki/ISO_8601 -embark-tools -============ -A collection of embark-related tools. Usage and available tools:: +* ``cursor`` widget: - embark-tools enable/disable tool [tool]... + * ``format``: Specifies the format. ``X``, ``x``, ``Y``, and ``y`` are + replaced with the corresponding cursor cordinates, while all other + characters are unmodified. + * ``show_invalid``: If set to ``true``, the mouse coordinates will both be + displayed as ``-1`` when the cursor is outside of the DF window; otherwise, + nothing will be displayed. -: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 +.. _dwarfvet: -.. _follow: +dwarfvet +======== +Enables Animal Caretaker functionality -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. +Always annoyed your dragons become useless after a minor injury? Well, with +dwarfvet, your animals become first rate members of your fort. It can also +be used to train medical skills. -.. _hotkeys: +Animals need to be treated in an animal hospital, which is simply a hospital +that is also an animal training zone. The console will print out a list on game +load, and whenever one is added or removed. Dwarfs must have the Animal Caretaker +labor to treat animals. Normal medical skills are used (and no experience is given +to the Animal Caretaker skill). -hotkeys -======= -Opens an in-game screen showing which DFHack keybindings are -active in the current context. See also `hotkey-notes`. +Options: -.. image:: images/hotkeys.png +:enable: Enables Animal Caretakers to treat and manage animals +:disable: Turns off the plguin +:report: Reports all zones that the game considers animal hospitals -:dfhack-keybind:`hotkeys` +.. _fix-job-postings: -.. _manipulator: +fix-job-postings +---------------- +This command fixes crashes caused by previous versions of workflow, mostly in +DFHack 0.40.24-r4, and should be run automatically when loading a world (but can +also be run manually if desired). -manipulator -=========== -An in-game equivalent to the popular program Dwarf Therapist. +.. _job: -To activate, open the unit screen and press :kbd:`l`. +job +=== +Command for general job query and manipulation. -.. image:: images/manipulator.png +Options: -The far left column displays the unit's Happiness (color-coded based on its -value), Name, Profession/Squad, and the right half of the screen displays each -dwarf's labor settings and skill levels (0-9 for Dabbling through Professional, -A-E for Great through Grand Master, and U-Z for Legendary through Legendary+5). +*no extra options* + Print details of the current job. The job can be selected + in a workshop, or the unit/jobs screen. +**list** + Print details of all jobs in the selected workshop. +**item-material ** + Replace the exact material id in the job item. +**item-type ** + Replace the exact item type id in the job item. -Cells with teal backgrounds denote skills not controlled by labors, e.g. -military and social skills. +.. _job-material: -.. image:: images/manipulator2.png +job-material +============ +Alter the material of the selected job. Similar to ``job item-material ...`` -Press :kbd:`t` to toggle between Profession, Squad, and Job views. +Invoked as:: -.. image:: images/manipulator3.png + job-material -Use the arrow keys or number pad to move the cursor around, holding :kbd:`Shift` to -move 10 tiles at a time. +:dfhack-keybind:`job-material` -Press the Z-Up (:kbd:`<`) and Z-Down (:kbd:`>`) keys to move quickly between labor/skill -categories. The numpad Z-Up and Z-Down keys seek to the first or last unit -in the list. :kbd:`Backspace` seeks to the top left corner. +* In :kbd:`q` mode, when a job is highlighted within a workshop or furnace, + changes the material of the job. Only inorganic materials can be used + in this mode. +* In :kbd:`b` mode, during selection of building components positions the cursor + over the first available choice with the matching material. -Press Enter to toggle the selected labor for the selected unit, or Shift+Enter -to toggle all labors within the selected category. +.. _job-duplicate: -Press the :kbd:`+`:kbd:`-` keys to sort the unit list according to the currently selected -skill/labor, and press the :kbd:`*`:kbd:`/` keys to sort the unit list by Name, Profession/Squad, -Happiness, or Arrival order (using :kbd:`Tab` to select which sort method to use here). +job-duplicate +============= +In :kbd:`q` mode, when a job is highlighted within a workshop or furnace +building, calling ``job-duplicate`` instantly duplicates the job. -With a unit selected, you can press the :kbd:`v` key to view its properties (and -possibly set a custom nickname or profession) or the :kbd:`c` key to exit -Manipulator and zoom to its position within your fortress. +:dfhack-keybind:`job-duplicate` -The following mouse shortcuts are also available: +.. _labormanager: -* Click on a column header to sort the unit list. Left-click to sort it in one - direction (descending for happiness or labors/skills, ascending for name, - profession or squad) and right-click to sort it in the opposite direction. -* Left-click on a labor cell to toggle that labor. Right-click to move the - cursor onto that cell instead of toggling it. -* Left-click on a unit's name, profession or squad to view its properties. -* Right-click on a unit's name, profession or squad to zoom to it. +labormanager +============ +Automatically manage dwarf labors to efficiently complete jobs. +Labormanager is derived from autolabor (above) but uses a completely +different approach to assigning jobs to dwarves. While autolabor tries +to keep as many dwarves busy as possible, labormanager instead strives +to get jobs done as quickly as possible. -Pressing :kbd:`Esc` normally returns to the unit screen, but :kbd:`Shift`:kbd:`Esc` would exit -directly to the main dwarf mode screen. +Labormanager frequently scans the current job list, current list of +dwarfs, and the map to determine how many dwarves need to be assigned to +what labors in order to meet all current labor needs without starving +any particular type of job. -Professions ------------ +.. warning:: -The manipulator plugin supports saving professions: a named set of labors that can be -quickly applied to one or multiple dwarves. + *As with autolabor, labormanager will override any manual changes you + make to labors while it is enabled, including through other tools such + as Dwarf Therapist* -To save a profession, highlight a dwarf and press :kbd:`P`. The profession will be saved using -the custom profession name of the dwarf, or the default for that dwarf if no custom profession -name has been set. +Simple usage: -To apply a profession, either highlight a single dwarf or select multiple with -:kbd:`x`, and press :kbd:`p` to select the profession to apply. All labors for -the selected dwarves will be reset to the labors of the chosen profession. +:enable labormanager: Enables the plugin with default settings. + (Persistent per fortress) -Professions are saved as human-readable text files in the "professions" folder -within the DF folder, and can be edited or deleted there. +:disable labormanager: Disables the plugin. -.. _mousequery: +Anything beyond this is optional - labormanager works fairly well on the +default settings. -mousequery -========== -Adds mouse controls to the DF interface, e.g. click-and-drag designations. +The default priorities for each labor vary (some labors are higher +priority by default than others). The way the plugin works is that, once +it determines how many of each labor is needed, it then sorts them by +adjusted priority. (Labors other than hauling have a bias added to them +based on how long it's been since they were last used, to prevent job +starvation.) The labor with the highest priority is selected, the "best +fit" dwarf for that labor is assigned to that labor, and then its +priority is *halved*. This process is repeated until either dwarfs or +labors run out. -Options: +Because there is no easy way to detect how many haulers are actually +needed at any moment, the plugin always ensures that at least one dwarf +is assigned to each of the hauling labors, even if no hauling jobs are +detected. At least one dwarf is always assigned to construction removing +and cleaning because these jobs also cannot be easily detected. Lever +pulling is always assigned to everyone. Any dwarfs for which there are +no jobs will be assigned hauling, lever pulling, and cleaning labors. If +you use animal trainers, note that labormanager will misbehave if you +assign specific trainers to specific animals; results are only guaranteed +if you use "any trainer", and animal trainers will probably be +overallocated in any case. -: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. +Labormanager also sometimes assigns extra labors to currently busy +dwarfs so that when they finish their current job, they will go off and +do something useful instead of standing around waiting for a job. -Usage:: +There is special handling to ensure that at least one dwarf is assigned +to haul food whenever food is detected left in a place where it will rot +if not stored. This will cause a dwarf to go idle if you have no +storepiles to haul food to. - mousequery [plugin] [rbutton] [track] [edge] [live] [enable|disable] +Dwarfs who are unable to work (child, in the military, wounded, +handless, asleep, in a meeting) are entirely excluded from labor +assignment. Any dwarf explicitly assigned to a burrow will also be +completely ignored by labormanager. -.. _nopause: +The fitness algorithm for assigning jobs to dwarfs generally attempts to +favor dwarfs who are more skilled over those who are less skilled. It +also tries to avoid assigning female dwarfs with children to jobs that +are "outside", favors assigning "outside" jobs to dwarfs who are +carrying a tool that could be used as a weapon, and tries to minimize +how often dwarfs have to reequip. -nopause -======= -Disables pausing (both manual and automatic) with the exception of pause forced -by `reveal` ``hell``. This is nice for digging under rivers. +Labormanager automatically determines medical needs and reserves health +care providers as needed. Note that this may cause idling if you have +injured dwarfs but no or inadequate hospital facilities. -.. _rename: +Hunting is never assigned without a butchery, and fishing is never +assigned without a fishery, and neither of these labors is assigned +unless specifically enabled. -rename -====== -Allows renaming various things. Use `gui/rename` for an in-game interface. +The method by which labormanager determines what labor is needed for a +particular job is complicated and, in places, incomplete. In some +situations, labormanager will detect that it cannot determine what labor +is required. It will, by default, pause and print an error message on +the dfhack console, followed by the message "LABORMANAGER: Game paused +so you can investigate the above message.". If this happens, please open +an issue on github, reporting the lines that immediately preceded this +message. You can tell labormanager to ignore this error and carry on by +typing ``labormanager pause-on-error no``, but be warned that some job may go +undone in this situation. -Options: +Advanced usage: -``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. +:labormanager enable: Turn plugin on. +:labormanager disable: Turn plugin off. +:labormanager priority : Set the priority value (see above) for labor to . +:labormanager reset : Reset the priority value of labor to its default. +:labormanager reset-all: Reset all priority values to their defaults. +:labormanager allow-fishing: Allow dwarfs to fish. *Warning* This tends to result in most of the fort going fishing. +:labormanager forbid-fishing: Forbid dwarfs from fishing. Default behavior. +:labormanager allow-hunting: Allow dwarfs to hunt. *Warning* This tends to result in as many dwarfs going hunting as you have crossbows. +:labormanager forbid-hunting: Forbid dwarfs from hunting. Default behavior. +:labormanager list: Show current priorities and current allocation stats. +:labormanager pause-on-error yes: Make labormanager pause if the labor inference engine fails. See above. +:labormanager pause-on-error no: Allow labormanager to continue past a labor inference engine failure. -.. _rendermax: +.. _nestboxes: -rendermax +nestboxes ========= -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. - -Options: - -: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. -An image showing lava and dragon breath. Not pictured here: sunlight, shining items/plants, -materials that color the light etc... - -.. image:: images/rendermax.png +Automatically scan for and forbid fertile eggs incubating in a nestbox. +Toggle status with `enable` or `disable `. -.. _resume: +.. _orders: -resume +orders ====== -Allows automatic resumption of suspended constructions, along with colored -UI hints for construction status. - -.. _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``. -.. comment - the link target "search" is reserved for the Sphinx search page -.. _search-plugin: +A plugin for manipulating manager orders. -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. +Subcommands: -.. image:: images/search.png +:export NAME: Exports the current list of manager orders to a file named ``dfhack-config/orders/NAME.json``. +:import NAME: Imports manager orders from a file named ``dfhack-config/orders/NAME.json``. +:clear: Deletes all manager orders in the current embark. +:sort: Sorts current manager orders by repeat frequency so daily orders don't + prevent other orders from ever being completed: one-time orders first, then + yearly, seasonally, monthly, then finally daily. -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. +You can keep your orders automatically sorted by adding the following command to +your ``onMapLoad.init`` file:: -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). + repeat -name orders-sort -time 1 -timeUnits days -command [ orders sort ] -Leaving any screen automatically clears the filter. +.. _seedwatch: -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. +seedwatch +========= +Watches the numbers of seeds available and enables/disables seed and plant cooking. -In the stockpile screen the option only appears if the cursor is in the -rightmost list: +Each plant type can be assigned a limit. If their number falls below that limit, +the plants and seeds of that type will be excluded from cookery. +If the number rises above the limit + 20, then cooking will be allowed. -.. image:: images/search-stockpile.png +The plugin needs a fortress to be loaded and will deactivate automatically otherwise. +You have to reactivate with 'seedwatch start' after you load the game. -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. +Options: -.. _sort: -.. _sort-items: +:all: Adds all plants from the abbreviation list to the watch list. +:start: Start watching. +:stop: Stop watching. +:info: Display whether seedwatch is watching, and the watch list. +:clear: Clears the watch list. -sort-items -========== -Sort the visible item list:: +Examples: - sort-items order [order...] +``seedwatch MUSHROOM_HELMET_PLUMP 30`` + add ``MUSHROOM_HELMET_PLUMP`` to the watch list, limit = 30 +``seedwatch MUSHROOM_HELMET_PLUMP`` + removes ``MUSHROOM_HELMET_PLUMP`` from the watch list. +``seedwatch all 30`` + adds all plants from the abbreviation list to the watch list, the limit being 30. -Sort the item list using the given sequence of comparisons. -The ``<`` prefix for an order makes undefined values sort first. -The ``>`` prefix reverses the sort order for defined values. +.. _spotclean: -Item order examples:: +spotclean +========= +Works like ``clean map snow mud``, but only for the tile under the cursor. Ideal +if you want to keep that bloody entrance ``clean map`` would clean up. - description material wear type quality +:dfhack-keybind:`spotclean` -The orderings are defined in ``hack/lua/plugins/sort/*.lua`` +.. _stockflow: -.. _sort-units: +stockflow +========= +Allows the fortress bookkeeper to queue jobs through the manager, +based on space or items available in stockpiles. -sort-units -========== -Sort the visible unit list:: +Inspired by `workflow`. - sort-units order [order...] +Usage: -Sort the unit list using the given sequence of comparisons. -The ``<`` prefix for an order makes undefined values sort first. -The ``>`` prefix reverses the sort order for defined values. +``stockflow enable`` + Enable the plugin. +``stockflow disable`` + Disable the plugin. +``stockflow fast`` + Enable the plugin in fast mode. +``stockflow list`` + List any work order settings for your stockpiles. +``stockflow status`` + Display whether the plugin is enabled. -Unit order examples:: +While enabled, the :kbd:`q` menu of each stockpile will have two new options: - name age arrival squad squad_position profession +* :kbd:`j`: Select a job to order, from an interface like the manager's screen. +* :kbd:`J`: Cycle between several options for how many such jobs to order. -The orderings are defined in ``hack/lua/plugins/sort/*.lua`` +Whenever the bookkeeper updates stockpile records, new work orders will +be placed on the manager's queue for each such selection, reduced by the +number of identical orders already in the queue. -:dfhack-keybind:`sort-units` +In fast mode, new work orders will be enqueued once per day, instead of +waiting for the bookkeeper. -.. _stocksettings: -.. _stockpiles: +.. _tailor: -stockpiles -========== -Offers the following commands to save and load stockpile settings. -See `gui/stockpiles` for an in-game interface. +tailor +====== -:copystock: Copies the parameters of the currently highlighted stockpile to the custom - stockpile settings and switches to custom stockpile placement mode, effectively - allowing you to copy/paste stockpiles easily. - :dfhack-keybind:`copystock` +Whenever the bookkeeper updates stockpile records, this plugin will scan every unit in the fort, +count up the number that are worn, and then order enough more made to replace all worn items. +If there are enough replacement items in inventory to replace all worn items, the units wearing them +will have the worn items confiscated (in the same manner as the `cleanowned` plugin) so that they'll +reeequip with replacement items. -:savestock: Saves the currently highlighted stockpile's settings to a file in your Dwarf - Fortress folder. This file can be used to copy settings between game saves or - players. e.g.: ``savestock food_settings.dfstock`` +Use the `enable` and `disable ` commands to toggle this plugin's status, or run +``tailor status`` to check its current status. -:loadstock: Loads a saved stockpile settings file and applies it to the currently selected - stockpile. e.g.: ``loadstock food_settings.dfstock`` +.. _workflow: -To use savestock and loadstock, use the :kbd:`q` command to highlight a stockpile. -Then run savestock giving it a descriptive filename. Then, in a different (or -the same!) gameworld, you can highlight any stockpile with :kbd:`q` then execute the -``loadstock`` command passing it the name of that file. The settings will be -applied to that stockpile. +workflow +======== +Manage control of repeat jobs. `gui/workflow` provides a simple +front-end integrated in the game UI. -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. +Usage: -.. _stocks: +``workflow enable [option...], workflow disable [option...]`` + If no options are specified, enables or disables the plugin. + Otherwise, enables or disables any of the following options: -stocks -====== -Replaces the DF stocks screen with an improved version. + - drybuckets: Automatically empty abandoned water buckets. + - auto-melt: Resume melt jobs when there are objects to melt. +``workflow jobs`` + List workflow-controlled jobs (if in a workshop, filtered by it). +``workflow list`` + List active constraints, and their job counts. +``workflow list-commands`` + List active constraints as workflow commands that re-create them; + this list can be copied to a file, and then reloaded using the + ``script`` built-in command. +``workflow count [cnt-gap]`` + Set a constraint, counting every stack as 1 item. +``workflow amount [cnt-gap]`` + Set a constraint, counting all items within stacks. +``workflow unlimit `` + Delete a constraint. +``workflow unlimit-all`` + Delete all constraints. -:dfhack-keybind:`stocks` +Function +-------- +When the plugin is enabled, it protects all repeat jobs from removal. +If they do disappear due to any cause, they are immediately re-added to their +workshop and suspended. +In addition, when any constraints on item amounts are set, repeat jobs that +produce that kind of item are automatically suspended and resumed as the item +amount goes above or below the limit. The gap specifies how much below the limit +the amount has to drop before jobs are resumed; this is intended to reduce +the frequency of jobs being toggled. -.. _title-folder: +Constraint format +----------------- +The constraint spec consists of 4 parts, separated with ``/`` characters:: -title-folder -============= -Displays the DF folder name in the window title bar when enabled. + ITEM[:SUBTYPE]/[GENERIC_MAT,...]/[SPECIFIC_MAT:...]/[LOCAL,] -.. _title-version: +The first part is mandatory and specifies the item type and subtype, +using the raw tokens for items (the same syntax used custom reaction inputs). +For more information, see :wiki:`this wiki page `. -title-version -============= -Displays the DFHack version on DF's title screen when enabled. +The subsequent parts are optional: -.. _trackstop: +- A generic material spec constrains the item material to one of + the hard-coded generic classes, which currently include:: -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. + PLANT WOOD CLOTH SILK LEATHER BONE SHELL SOAP TOOTH HORN PEARL YARN + METAL STONE SAND GLASS CLAY MILK +- A specific material spec chooses the material exactly, using the + raw syntax for reaction input materials, e.g. ``INORGANIC:IRON``, + although for convenience it also allows just ``IRON``, or ``ACACIA:WOOD`` etc. + See the link above for more details on the unabbreviated raw syntax. -=========================== -Job and Fortress management -=========================== +- A comma-separated list of miscellaneous flags, which currently can + be used to ignore imported items or items below a certain quality. -.. contents:: - :local: +Constraint examples +------------------- +Keep metal bolts within 900-1000, and wood/bone within 150-200:: + workflow amount AMMO:ITEM_AMMO_BOLTS/METAL 1000 100 + workflow amount AMMO:ITEM_AMMO_BOLTS/WOOD,BONE 200 50 -.. _autobutcher: +Keep the number of prepared food & drink stacks between 90 and 120:: -autobutcher -=========== -Assigns lifestock for slaughter once it reaches a specific count. Requires that -you add the target race(s) to a watch list. Only tame units will be processed. + workflow count FOOD 120 30 + workflow count DRINK 120 30 -Units will be ignored if they are: +Make sure there are always 25-30 empty bins/barrels/bags:: -* Nicknamed (for custom protection; you can use the `rename` ``unit`` tool - individually, or `zone` ``nick`` for groups) -* Caged, if and only if the cage is defined as a room (to protect zoos) -* Trained for war or hunting + workflow count BIN 30 + workflow count BARREL 30 + workflow count BOX/CLOTH,SILK,YARN 30 -Creatures who will not reproduce (because they're not interested in the -opposite sex or have been gelded) will be butchered before those who will. -Older adults and younger children will be butchered first if the population -is above the target (default 1 male, 5 female kids and adults). Note that -you may need to set a target above 1 to have a reliable breeding population -due to asexuality etc. See `fix-ster` if this is a problem. +Make sure there are always 15-20 coal and 25-30 copper bars:: -Options: + workflow count BAR//COAL 20 + workflow count BAR//COPPER 30 -:example: Print some usage examples. -:start: Start running every X frames (df simulation ticks). - Default: X=6000, which would be every 60 seconds at 100fps. -:stop: Stop running automatically. -:sleep : Changes the timer to sleep X frames between runs. -:watch R: Start watching a race. R can be a valid race RAW id (ALPACA, - BIRD_TURKEY, etc) or a list of ids seperated by spaces or - the keyword 'all' which affects all races on your current - watchlist. -:unwatch R: Stop watching race(s). The current target settings will be - remembered. R can be a list of ids or the keyword 'all'. -:forget R: Stop watching race(s) and forget it's/their target settings. - R can be a list of ids or the keyword 'all'. -:autowatch: Automatically adds all new races (animals you buy from merchants, - tame yourself or get from migrants) to the watch list using - default target count. -:noautowatch: Stop auto-adding new races to the watchlist. -:list: Print the current status and watchlist. -:list_export: Print the commands needed to set up status and watchlist, - which can be used to import them to another save (see notes). -:target : - Set target count for specified race(s). The first four arguments - are the number of female and male kids, and female and male adults. - R can be a list of spceies ids, or the keyword ``all`` or ``new``. - ``R = 'all'``: change target count for all races on watchlist - and set the new default for the future. ``R = 'new'``: don't touch - current settings on the watchlist, only set the new default - for future entries. -:list_export: Print the commands required to rebuild your current settings. +Produce 15-20 gold crafts:: -.. note:: + workflow count CRAFTS//GOLD 20 - Settings and watchlist are stored in the savegame, so that you can have - different settings for each save. If you want to copy your watchlist to - another savegame you must export the commands required to recreate your settings. +Collect 15-20 sand bags and clay boulders:: - To export, open an external terminal in the DF directory, and run - ``dfhack-run autobutcher list_export > filename.txt``. To import, load your - new save and run ``script filename.txt`` in the DFHack terminal. + workflow count POWDER_MISC/SAND 20 + workflow count BOULDER/CLAY 20 +Make sure there are always 80-100 units of dimple dye:: -Examples: + workflow amount POWDER_MISC//MUSHROOM_CUP_DIMPLE:MILL 100 20 -You want to keep max 7 kids (4 female, 3 male) and max 3 adults (2 female, -1 male) of the race alpaca. Once the kids grow up the oldest adults will get -slaughtered. Excess kids will get slaughtered starting with the youngest -to allow that the older ones grow into adults. Any unnamed cats will -be slaughtered as soon as possible. :: +.. note:: - autobutcher target 4 3 2 1 ALPACA BIRD_TURKEY - autobutcher target 0 0 0 0 CAT - autobutcher watch ALPACA BIRD_TURKEY CAT - autobutcher start + In order for this to work, you have to set the material of the PLANT input + on the Mill Plants job to MUSHROOM_CUP_DIMPLE using the `job item-material ` + command. Otherwise the plugin won't be able to deduce the output material. -Automatically put all new races onto the watchlist and mark unnamed tame units -for slaughter as soon as they arrive in your fort. Settings already made -for specific races will be left untouched. :: +Maintain 10-100 locally-made crafts of exceptional quality:: - autobutcher target 0 0 0 0 new - autobutcher autowatch - autobutcher start + workflow count CRAFTS///LOCAL,EXCEPTIONAL 100 90 -Stop watching the races alpaca and cat, but remember the target count -settings so that you can use 'unwatch' without the need to enter the -values again. Note: 'autobutcher unwatch all' works, but only makes sense -if you want to keep the plugin running with the 'autowatch' feature or manually -add some new races with 'watch'. If you simply want to stop it completely use -'autobutcher stop' instead. :: +.. _workNow: - autobutcher unwatch ALPACA CAT +workNow +======= +Don't allow dwarves to idle if any jobs are available. -.. _autochop: +When workNow is active, every time the game pauses, DF will make dwarves +perform any appropriate available jobs. This includes when you one step +through the game using the pause menu. Usage: -autochop -======== -Automatically manage tree cutting designation to keep available logs withing given -quotas. +:workNow: print workNow status +:workNow 0: deactivate workNow +:workNow 1: activate workNow (look for jobs on pause, and only then) +:workNow 2: make dwarves look for jobs whenever a job completes -Open the dashboard by running:: +.. _zone: - enable autochop +zone +==== +Helps a bit with managing activity zones (pens, pastures and pits) and cages. -The plugin must be activated (with :kbd:`d`-:kbd:`t`-:kbd:`c`-:kbd:`a`) before -it can be used. You can then set logging quotas and restrict designations to -specific burrows (with 'Enter') if desired. The plugin's activity cycle runs -once every in game day. +:dfhack-keybind:`zone` -If you add ``enable autochop`` to your dfhack.init there will be a hotkey to -open the dashboard from the chop designation menu. +Options: -.. _autoclothing: +:set: Set zone or cage under cursor as default for future assigns. +:assign: Assign unit(s) to the pen or pit marked with the 'set' command. + If no filters are set a unit must be selected in the in-game ui. + Can also be followed by a valid zone id which will be set + instead. +:unassign: Unassign selected creature from it's zone. +:nick: Mass-assign nicknames, must be followed by the name you want + to set. +:remnick: Mass-remove nicknames. +:enumnick: Assign enumerated nicknames (e.g. "Hen 1", "Hen 2"...). Must be + followed by the prefix to use in nicknames. +:tocages: Assign unit(s) to cages inside a pasture. +:uinfo: Print info about unit(s). If no filters are set a unit must + be selected in the in-game ui. +:zinfo: Print info about zone(s). If no filters are set zones under + the cursor are listed. +:verbose: Print some more info. +:filters: Print list of valid filter options. +:examples: Print some usage examples. +:not: Negates the next filter keyword. -autoclothing -============ +Filters: -Automatically manage clothing work orders, allowing the user to set how many of -each clothing type every citizen should have. Usage:: +:all: Process all units (to be used with additional filters). +:count: Must be followed by a number. Process only n units (to be used + with additional filters). +:unassigned: Not assigned to zone, chain or built cage. +:minage: Minimum age. Must be followed by number. +:maxage: Maximum age. Must be followed by number. +:race: Must be followed by a race RAW ID (e.g. BIRD_TURKEY, ALPACA, + etc). Negatable. +:caged: In a built cage. Negatable. +:own: From own civilization. Negatable. +:merchant: Is a merchant / belongs to a merchant. Should only be used for + pitting, not for stealing animals (slaughter should work). +:war: Trained war creature. Negatable. +:hunting: Trained hunting creature. Negatable. +:tamed: Creature is tame. Negatable. +:trained: Creature is trained. Finds war/hunting creatures as well as + creatures who have a training level greater than 'domesticated'. + If you want to specifically search for war/hunting creatures use + 'war' or 'hunting' Negatable. +:trainablewar: Creature can be trained for war (and is not already trained for + war/hunt). Negatable. +:trainablehunt: Creature can be trained for hunting (and is not already trained + for war/hunt). Negatable. +:male: Creature is male. Negatable. +:female: Creature is female. Negatable. +:egglayer: Race lays eggs. Negatable. +:grazer: Race is a grazer. Negatable. +:milkable: Race is milkable. Negatable. - autoclothing [number] - -Examples: - -* ``autoclothing cloth "short skirt" 10``: - Sets the desired number of cloth short skirts available per citizen to 10. -* ``autoclothing cloth dress``: - Displays the currently set number of cloth dresses chosen per citizen. - -.. _autodump: - -autodump -======== -This plugin adds an option to the :kbd:`q` menu for stckpiles when `enabled `. -When autodump is enabled for a stockpile, any items placed in the stockpile will -automatically be designated to be dumped. - -Alternatively, you can use it to quickly move all items designated to be dumped. -Items are instantly moved to the cursor position, the dump flag is unset, -and the forbid flag is set, as if it had been dumped normally. -Be aware that any active dump item tasks still point at the item. +Usage with single units +----------------------- +One convenient way to use the zone tool is to bind the command 'zone assign' to +a hotkey, maybe also the command 'zone set'. Place the in-game cursor over +a pen/pasture or pit, use 'zone set' to mark it. Then you can select units +on the map (in 'v' or 'k' mode), in the unit list or from inside cages +and use 'zone assign' to assign them to their new home. Allows pitting your +own dwarves, by the way. -Cursor must be placed on a floor tile so the items can be dumped there. +Usage with filters +------------------ +All filters can be used together with the 'assign' command. -Options: +Restrictions: It's not possible to assign units who are inside built cages +or chained because in most cases that won't be desirable anyways. +It's not possible to cage owned pets because in that case the owner +uncages them after a while which results in infinite hauling back and forth. -:destroy: Destroy instead of dumping. Doesn't require a cursor. - If called again before the game is resumed, cancels destroy. -:destroy-here: As ``destroy``, but only the selected item in the :kbd:`k` list, - or inside a container. - Alias ``autodump-destroy-here``, for keybindings. - :dfhack-keybind:`autodump-destroy-here` -:visible: Only process items that are not hidden. -:hidden: Only process hidden items. -:forbidden: Only process forbidden items (default: only unforbidden). +Usually you should always use the filter 'own' (which implies tame) unless you +want to use the zone tool for pitting hostiles. 'own' ignores own dwarves unless +you specify 'race DWARF' (so it's safe to use 'assign all own' to one big +pasture if you want to have all your animals at the same place). 'egglayer' and +'milkable' should be used together with 'female' unless you have a mod with +egg-laying male elves who give milk or whatever. Merchants and their animals are +ignored unless you specify 'merchant' (pitting them should be no problem, +but stealing and pasturing their animals is not a good idea since currently they +are not properly added to your own stocks; slaughtering them should work). -``autodump-destroy-item`` destroys the selected item, which may be selected -in the :kbd:`k` list, or inside a container. If called again before the game -is resumed, cancels destruction of the item. -:dfhack-keybind:`autodump-destroy-item` +Most filters can be negated (e.g. 'not grazer' -> race is not a grazer). -.. _autofarm: +Mass-renaming +------------- +Using the 'nick' command you can set the same nickname for multiple units. +If used without 'assign', 'all' or 'count' it will rename all units in the +current default target zone. Combined with 'assign', 'all' or 'count' (and +further optional filters) it will rename units matching the filter conditions. -autofarm -======== +Cage zones +---------- +Using the 'tocages' command you can assign units to a set of cages, for example +a room next to your butcher shop(s). They will be spread evenly among available +cages to optimize hauling to and butchering from them. For this to work you need +to build cages and then place one pen/pasture activity zone above them, covering +all cages you want to use. Then use 'zone set' (like with 'assign') and use +'zone tocages filter1 filter2 ...'. 'tocages' overwrites 'assign' because it +would make no sense, but can be used together with 'nick' or 'remnick' and all +the usual filters. -Automatically handles crop selection in farm plots based on current plant -stocks, and selects crops for planting if current stock is below a threshold. -Selected crops are dispatched on all farmplots. (Note that this plugin replaces -an older Ruby script of the same name.) +Examples +-------- +``zone assign all own ALPACA minage 3 maxage 10`` + Assign all own alpacas who are between 3 and 10 years old to the selected + pasture. +``zone assign all own caged grazer nick ineedgrass`` + Assign all own grazers who are sitting in cages on stockpiles (e.g. after + buying them from merchants) to the selected pasture and give them + the nickname 'ineedgrass'. +``zone assign all own not grazer not race CAT`` + Assign all own animals who are not grazers, excluding cats. +``zone assign count 5 own female milkable`` + Assign up to 5 own female milkable creatures to the selected pasture. +``zone assign all own race DWARF maxage 2`` + Throw all useless kids into a pit :) +``zone nick donttouchme`` + Nicknames all units in the current default zone or cage to 'donttouchme'. + Mostly intended to be used for special pastures or cages which are not marked + as rooms you want to protect from autobutcher. +``zone tocages count 50 own tame male not grazer`` + Stuff up to 50 owned tame male animals who are not grazers into cages built + on the current default zone. -Use the `enable` or `disable ` commands to change whether this plugin is -enabled. +================ +Map modification +================ -Usage: +.. contents:: + :local: -* ``autofarm runonce``: - Updates all farm plots once, without enabling the plugin -* ``autofarm status``: - Prints status information, including any applied limits -* ``autofarm default 30``: - Sets the default threshold -* ``autofarm threshold 150 helmet_plump tail_pig``: - Sets thresholds of individual plants +.. _3dveins: -.. _autogems: +3dveins +======= +Removes all existing veins from the map and generates new ones using +3D Perlin noise, in order to produce a layout that smoothly flows between +Z levels. The vein distribution is based on the world seed, so running +the command for the second time should produce no change. It is best to +run it just once immediately after embark. -autogems -======== -Creates a new Workshop Order setting, automatically cutting rough gems -when `enabled `. +This command is intended as only a cosmetic change, so it takes +care to exactly preserve the mineral counts reported by `prospect` ``all``. +The amounts of different layer stones may slightly change in some cases +if vein mass shifts between Z layers. -See `gui/autogems` for a configuration UI. If necessary, the ``autogems-reload`` -command reloads the configuration file produced by that script. +The only undo option is to restore your save from backup. -.. _autohauler: +.. _alltraffic: -autohauler +alltraffic ========== -Autohauler is an autolabor fork. - -Rather than the all-of-the-above means of autolabor, autohauler will instead -only manage hauling labors and leave skilled labors entirely to the user, who -will probably use Dwarf Therapist to do so. - -Idle dwarves will be assigned the hauling labors; everyone else (including -those currently hauling) will have the hauling labors removed. This is to -encourage every dwarf to do their assigned skilled labors whenever possible, -but resort to hauling when those jobs are not available. This also implies -that the user will have a very tight skill assignment, with most skilled -labors only being assigned to just one dwarf, no dwarf having more than two -active skilled labors, and almost every non-military dwarf having at least -one skilled labor assigned. - -Autohauler allows skills to be flagged as to prevent hauling labors from -being assigned when the skill is present. By default this is the unused -ALCHEMIST labor but can be changed by the user. - -.. _autolabor: - -autolabor -========= -Automatically manage dwarf labors to efficiently complete jobs. -Autolabor tries to keep as many dwarves as possible busy but -also tries to have dwarves specialize in specific skills. - -The key is that, for almost all labors, once a dwarf begins a job it will finish that -job even if the associated labor is removed. Autolabor therefore frequently checks -which dwarf or dwarves should take new jobs for that labor, and sets labors accordingly. -Labors with equiptment (mining, hunting, and woodcutting), which are abandoned -if labors change mid-job, are handled slightly differently to minimise churn. - -.. warning:: - - *autolabor will override any manual changes you make to labors while - it is enabled, including through other tools such as Dwarf Therapist* - -Simple usage: - -:enable autolabor: Enables the plugin with default settings. (Persistent per fortress) -:disable autolabor: Disables the plugin. - -Anything beyond this is optional - autolabor works well on the default settings. - -By default, each labor is assigned to between 1 and 200 dwarves (2-200 for mining). -By default 33% of the workforce become haulers, who handle all hauling jobs as well -as cleaning, pulling levers, recovering wounded, removing constructions, and filling ponds. -Other jobs are automatically assigned as described above. Each of these settings can be adjusted. - -Jobs are rarely assigned to nobles with responsibilities for meeting diplomats or merchants, -never to the chief medical dwarf, and less often to the bookeeper and manager. - -Hunting is never assigned without a butchery, and fishing is never assigned without a fishery. - -For each labor a preference order is calculated based on skill, biased against masters of other -trades and excluding those who can't do the job. The labor is then added to the best -dwarves for that labor. We assign at least the minimum number of dwarfs, in order of preference, -and then assign additional dwarfs that meet any of these conditions: - -* The dwarf is idle and there are no idle dwarves assigned to this labor -* The dwarf has non-zero skill associated with the labor -* The labor is mining, hunting, or woodcutting and the dwarf currently has it enabled. - -We stop assigning dwarfs when we reach the maximum allowed. - -Advanced usage: - -:autolabor []: - Set number of dwarves assigned to a labor. -:autolabor haulers: Set a labor to be handled by hauler dwarves. -:autolabor disable: Turn off autolabor for a specific labor. -:autolabor reset: Return a labor to the default handling. -:autolabor reset-all: Return all labors to the default handling. -:autolabor list: List current status of all labors. -:autolabor status: Show basic status information. - -See `autolabor-artisans` for a differently-tuned setup. - -Examples: - -``autolabor MINE`` - Keep at least 5 dwarves with mining enabled. -``autolabor CUT_GEM 1 1`` - Keep exactly 1 dwarf with gemcutting enabled. -``autolabor COOK 1 1 3`` - Keep 1 dwarf with cooking enabled, selected only from the top 3. -``autolabor FEED_WATER_CIVILIANS haulers`` - Have haulers feed and water wounded dwarves. -``autolabor CUTWOOD disable`` - Turn off autolabor for wood cutting. - -.. _autonestbox: - -autonestbox -=========== -Assigns unpastured female egg-layers to nestbox zones. Requires that you create -pen/pasture zones above nestboxes. If the pen is bigger than 1x1 the nestbox -must be in the top left corner. Only 1 unit will be assigned per pen, regardless -of the size. The age of the units is currently not checked, most birds grow up -quite fast. Egglayers who are also grazers will be ignored, since confining them -to a 1x1 pasture is not a good idea. Only tame and domesticated own units are -processed since pasturing half-trained wild egglayers could destroy your neat -nestbox zones when they revert to wild. When called without options autonestbox -will instantly run once. +Set traffic designations for every single tile of the map - useful for resetting +traffic designations. See also `filltraffic`, `restrictice`, and `restrictliquids`. Options: -:start: Start running every X frames (df simulation ticks). - Default: X=6000, which would be every 60 seconds at 100fps. -:stop: Stop running automatically. -:sleep: Must be followed by number X. Changes the timer to sleep X - frames between runs. +:H: High Traffic +:N: Normal Traffic +:L: Low Traffic +:R: Restricted Traffic -.. _clean: +.. _burrows: -clean -===== -Cleans all the splatter that get scattered all over the map, items and -creatures. In an old fortress, this can significantly reduce FPS lag. It can -also spoil your !!FUN!!, so think before you use it. +burrows +======= +Miscellaneous burrow control. Allows manipulating burrows and automated burrow +expansion while digging. Options: -:map: Clean the map tiles. By default, it leaves mud and snow alone. -:units: Clean the creatures. Will also clean hostiles. -:items: Clean all the items. Even a poisoned blade. +:enable feature ...: + Enable features of the plugin. +:disable feature ...: + Disable features of the plugin. +:clear-unit burrow burrow ...: + Remove all units from the burrows. +:clear-tiles burrow burrow ...: + Remove all tiles from the burrows. +:set-units target-burrow src-burrow ...: + Clear target, and adds units from source burrows. +:add-units target-burrow src-burrow ...: + Add units from the source burrows to the target. +:remove-units target-burrow src-burrow ...: + Remove units in source burrows from the target. +:set-tiles target-burrow src-burrow ...: + Clear target and adds tiles from the source burrows. +:add-tiles target-burrow src-burrow ...: + Add tiles from the source burrows to the target. +:remove-tiles target-burrow src-burrow ...: + Remove tiles in source burrows from the target. + + For these three options, in place of a source burrow it is + possible to use one of the following keywords: ABOVE_GROUND, + SUBTERRANEAN, INSIDE, OUTSIDE, LIGHT, DARK, HIDDEN, REVEALED -Extra options for ``map``: +Features: -:mud: Remove mud in addition to the normal stuff. -:snow: Also remove snow coverings. +:auto-grow: When a wall inside a burrow with a name ending in '+' is dug + out, the burrow is extended to newly-revealed adjacent walls. + This final '+' may be omitted in burrow name args of commands above. + Digging 1-wide corridors with the miner inside the burrow is SLOW. -.. _cleanowned: +.. _changeitem: -cleanowned +changeitem ========== -Confiscates items owned by dwarfs. By default, owned food on the floor -and rotten items are confistacted and dumped. +Allows changing item material and base quality. By default the item currently +selected in the UI will be changed (you can select items in the 'k' list +or inside containers/inventory). By default change is only allowed if materials +is of the same subtype (for example wood<->wood, stone<->stone etc). But since +some transformations work pretty well and may be desired you can override this +with 'force'. Note that some attributes will not be touched, possibly resulting +in weirdness. To get an idea how the RAW id should look like, check some items +with 'info'. Using 'force' might create items which are not touched by +crafters/haulers. Options: -:all: confiscate all owned items -:scattered: confiscated and dump all items scattered on the floor -:x: confiscate/dump items with wear level 'x' and more -:X: confiscate/dump items with wear level 'X' and more -:dryrun: a dry run. combine with other options to see what will happen - without it actually happening. +:info: Don't change anything, print some info instead. +:here: Change all items at the cursor position. Requires in-game cursor. +:material, m: Change material. Must be followed by valid material RAW id. +:quality, q: Change base quality. Must be followed by number (0-5). +:force: Ignore subtypes, force change to new material. -Example: +Examples: -``cleanowned scattered X`` - This will confiscate rotten and dropped food, garbage on the floors and any - worn items with 'X' damage and above. +``changeitem m INORGANIC:GRANITE here`` + Change material of all items under the cursor to granite. +``changeitem q 5`` + Change currently selected item to masterpiece quality. -.. _dwarfmonitor: +.. _changelayer: -dwarfmonitor -============ -Records dwarf activity to measure fort efficiency. +changelayer +=========== +Changes material of the geology layer under cursor to the specified inorganic +RAW material. Can have impact on all surrounding regions, not only your embark! +By default changing stone to soil and vice versa is not allowed. By default +changes only the layer at the cursor position. Note that one layer can stretch +across lots of z levels. By default changes only the geology which is linked +to the biome under the cursor. That geology might be linked to other biomes +as well, though. Mineral veins and gem clusters will stay on the map. Use +`changevein` for them. + +tl;dr: You will end up with changing quite big areas in one go, especially if +you use it in lower z levels. Use with care. Options: -:enable : Start monitoring ``mode``. ``mode`` can be "work", "misery", - "weather", or "all". This will enable all corresponding widgets, - if applicable. -:disable : Stop monitoring ``mode``, and disable corresponding widgets, if applicable. -:stats: Show statistics summary -:prefs: Show dwarf preferences summary -:reload: Reload configuration file (``dfhack-config/dwarfmonitor.json``) +:all_biomes: Change selected layer for all biomes on your map. + Result may be undesirable since the same layer can AND WILL + be on different z-levels for different biomes. Use the tool + 'probe' to get an idea how layers and biomes are distributed + on your map. +:all_layers: Change all layers on your map (only for the selected biome + unless 'all_biomes' is added). + Candy mountain, anyone? Will make your map quite boring, + but tidy. +:force: Allow changing stone to soil and vice versa. !!THIS CAN HAVE + WEIRD EFFECTS, USE WITH CARE!! + Note that soil will not be magically replaced with stone. + You will, however, get a stone floor after digging so it + will allow the floor to be engraved. + Note that stone will not be magically replaced with soil. + You will, however, get a soil floor after digging so it + could be helpful for creating farm plots on maps with no + soil. +:verbose: Give some details about what is being changed. +:trouble: Give some advice about known problems. -:dfhack-keybind:`dwarfmonitor` +Examples: -Widget configuration: +``changelayer GRANITE`` + Convert layer at cursor position into granite. +``changelayer SILTY_CLAY force`` + Convert layer at cursor position into clay even if it's stone. +``changelayer MARBLE all_biomes all_layers`` + Convert all layers of all biomes which are not soil into marble. -The following types of widgets (defined in :file:`hack/lua/plugins/dwarfmonitor.lua`) -can be displayed on the main fortress mode screen: +.. note:: -:date: Show the in-game date -:misery: Show overall happiness levels of all dwarves -:weather: Show current weather (rain/snow) -:cursor: Show the current mouse cursor position + * If you use changelayer and nothing happens, try to pause/unpause the game + for a while and try to move the cursor to another tile. Then try again. + If that doesn't help try temporarily changing some other layer, undo your + changes and try again for the layer you want to change. Saving + and reloading your map might also help. + * You should be fine if you only change single layers without the use + of 'force'. Still it's advisable to save your game before messing with + the map. + * When you force changelayer to convert soil to stone you might experience + weird stuff (flashing tiles, tiles changed all over place etc). + Try reverting the changes manually or even better use an older savegame. + You did save your game, right? -The file :file:`dfhack-config/dwarfmonitor.json` can be edited to control the -positions and settings of all widgets displayed. This file should contain a -JSON object with the key ``widgets`` containing an array of objects - see the -included file in the ``dfhack-config`` folder for an example: +.. _changevein: -.. code-block:: lua +changevein +========== +Changes material of the vein under cursor to the specified inorganic RAW +material. Only affects tiles within the current 16x16 block - for veins and +large clusters, you will need to use this command multiple times. - { - "widgets": [ - { - "type": "widget type (weather, misery, etc.)", - "x": X coordinate, - "y": Y coordinate - <...additional options...> - } - ] - } +Example: -X and Y coordinates begin at zero (in the upper left corner of the screen). -Negative coordinates will be treated as distances from the lower right corner, -beginning at 1 - e.g. an x coordinate of 0 is the leftmost column, while an x -coordinate of 1 is the rightmost column. +``changevein NATIVE_PLATINUM`` + Convert vein at cursor position into platinum ore. -By default, the x and y coordinates given correspond to the leftmost tile of -the widget. Including an ``anchor`` option set to ``right`` will cause the -rightmost tile of the widget to be located at this position instead. +.. _cleanconst: -Some widgets support additional options: +cleanconst +========== +Cleans up construction materials. -* ``date`` widget: +This utility alters all constructions on the map so that they spawn their +building component when they are disassembled, allowing their actual +build items to be safely deleted. This can improve FPS in extreme situations. - * ``format``: specifies the format of the date. The following characters - are replaced (all others, such as punctuation, are not modified) +.. _deramp: - * ``Y`` or ``y``: The current year - * ``M``: The current month, zero-padded if necessary - * ``m``: The current month, *not* zero-padded - * ``D``: The current day, zero-padded if necessary - * ``d``: The current day, *not* zero-padded +deramp +====== +Removes all ramps designated for removal from the map. This is useful for +replicating the old channel digging designation. It also removes any and +all 'down ramps' that can remain after a cave-in (you don't have to designate +anything for that to happen). - The default date format is ``Y-M-D``, per the ISO8601_ standard. +.. _dig: +.. _digv: +.. _digvx: +.. _digl: +.. _diglx: - .. _ISO8601: https://en.wikipedia.org/wiki/ISO_8601 +dig +=== +This plugin makes many automated or complicated dig patterns easy. -* ``cursor`` widget: +Basic commands: - * ``format``: Specifies the format. ``X``, ``x``, ``Y``, and ``y`` are - replaced with the corresponding cursor cordinates, while all other - characters are unmodified. - * ``show_invalid``: If set to ``true``, the mouse coordinates will both be - displayed as ``-1`` when the cursor is outside of the DF window; otherwise, - nothing will be displayed. +:digv: Designate all of the selected vein for digging. +:digvx: Also cross z-levels, digging stairs as needed. Alias for ``digv x``. +:digl: Like ``digv``, for layer stone. Also supports an ``undo`` option + to remove designations, for if you accidentally set 50 levels at once. +:diglx: Also cross z-levels, digging stairs as needed. Alias for ``digl x``. -.. _dwarfvet: +:dfhack-keybind:`digv` -dwarfvet -======== -Enables Animal Caretaker functionality +.. note:: -Always annoyed your dragons become useless after a minor injury? Well, with -dwarfvet, your animals become first rate members of your fort. It can also -be used to train medical skills. + All commands implemented by the `dig` plugin (listed by ``ls dig``) support + specifying the designation priority with ``-p#``, ``-p #``, or ``p=#``, + where ``#`` is a number from 1 to 7. If a priority is not specified, the + priority selected in-game is used as the default. -Animals need to be treated in an animal hospital, which is simply a hospital -that is also an animal training zone. The console will print out a list on game -load, and whenever one is added or removed. Dwarfs must have the Animal Caretaker -labor to treat animals. Normal medical skills are used (and no experience is given -to the Animal Caretaker skill). +.. _digcircle: -Options: +digcircle +========= +A command for easy designation of filled and hollow circles. +It has several types of options. -:enable: Enables Animal Caretakers to treat and manage animals -:disable: Turns off the plguin -:report: Reports all zones that the game considers animal hospitals +Shape: -.. _fix-job-postings: +:hollow: Set the circle to hollow (default) +:filled: Set the circle to filled +:#: Diameter in tiles (default = 0, does nothing) -fix-job-postings ----------------- -This command fixes crashes caused by previous versions of workflow, mostly in -DFHack 0.40.24-r4, and should be run automatically when loading a world (but can -also be run manually if desired). +Action: + +:set: Set designation (default) +:unset: Unset current designation +:invert: Invert designations already present + +Designation types: -.. _job: +:dig: Normal digging designation (default) +:ramp: Ramp digging +:ustair: Staircase up +:dstair: Staircase down +:xstair: Staircase up/down +:chan: Dig channel -job -=== -Command for general job query and manipulation. +After you have set the options, the command called with no options +repeats with the last selected parameters. -Options: +Examples: -*no extra options* - Print details of the current job. The job can be selected - in a workshop, or the unit/jobs screen. -**list** - Print details of all jobs in the selected workshop. -**item-material ** - Replace the exact material id in the job item. -**item-type ** - Replace the exact item type id in the job item. +``digcircle filled 3`` + Dig a filled circle with diameter = 3. +``digcircle`` + Do it again. -.. _job-material: +.. _digexp: -job-material -============ -Alter the material of the selected job. Similar to ``job item-material ...`` +digexp +====== +This command is for :wiki:`exploratory mining `. -Invoked as:: +There are two variables that can be set: pattern and filter. - job-material +Patterns: -:dfhack-keybind:`job-material` +:diag5: diagonals separated by 5 tiles +:diag5r: diag5 rotated 90 degrees +:ladder: A 'ladder' pattern +:ladderr: ladder rotated 90 degrees +:clear: Just remove all dig designations +:cross: A cross, exactly in the middle of the map. -* In :kbd:`q` mode, when a job is highlighted within a workshop or furnace, - changes the material of the job. Only inorganic materials can be used - in this mode. -* In :kbd:`b` mode, during selection of building components positions the cursor - over the first available choice with the matching material. +Filters: -.. _job-duplicate: +:all: designate whole z-level +:hidden: designate only hidden tiles of z-level (default) +:designated: Take current designation and apply pattern to it. -job-duplicate -============= -In :kbd:`q` mode, when a job is highlighted within a workshop or furnace -building, calling ``job-duplicate`` instantly duplicates the job. +After you have a pattern set, you can use ``expdig`` to apply it again. -:dfhack-keybind:`job-duplicate` +Examples: -.. _labormanager: +``expdig diag5 hidden`` + Designate the diagonal 5 patter over all hidden tiles +``expdig`` + Apply last used pattern and filter +``expdig ladder designated`` + Take current designations and replace them with the ladder pattern -labormanager -============ -Automatically manage dwarf labors to efficiently complete jobs. -Labormanager is derived from autolabor (above) but uses a completely -different approach to assigning jobs to dwarves. While autolabor tries -to keep as many dwarves busy as possible, labormanager instead strives -to get jobs done as quickly as possible. +.. _digFlood: -Labormanager frequently scans the current job list, current list of -dwarfs, and the map to determine how many dwarves need to be assigned to -what labors in order to meet all current labor needs without starving -any particular type of job. +digFlood +======== +Automatically digs out specified veins as they are discovered. It runs once +every time a dwarf finishes a dig job. It will only dig out appropriate tiles +that are adjacent to the finished dig job. To add a vein type, use ``digFlood 1 [type]``. +This will also enable the plugin. To remove a vein type, use ``digFlood 0 [type] 1`` +to disable, then remove, then re-enable. -.. warning:: +Usage: - *As with autolabor, labormanager will override any manual changes you - make to labors while it is enabled, including through other tools such - as Dwarf Therapist* +:help digflood: detailed help message +:digFlood 0: disable the plugin +:digFlood 1: enable the plugin +:digFlood 0 MICROCLINE COAL_BITUMINOUS 1: + disable plugin, remove microcline and bituminous coal from monitoring, then re-enable the plugin +:digFlood CLEAR: remove all inorganics from monitoring +:digFlood digAll1: ignore the monitor list and dig any vein +:digFlood digAll0: disable digAll mode -Simple usage: +.. _digtype: -:enable labormanager: Enables the plugin with default settings. - (Persistent per fortress) +digtype +======= +For every tile on the map of the same vein type as the selected tile, +this command designates it to have the same designation as the +selected tile. If the selected tile has no designation, they will be +dig designated. +If an argument is given, the designation of the selected tile is +ignored, and all appropriate tiles are set to the specified +designation. -:disable labormanager: Disables the plugin. +Options: -Anything beyond this is optional - labormanager works fairly well on the -default settings. +:dig: +:channel: +:ramp: +:updown: up/down stairs +:up: up stairs +:down: down stairs +:clear: clear designation -The default priorities for each labor vary (some labors are higher -priority by default than others). The way the plugin works is that, once -it determines how many of each labor is needed, it then sorts them by -adjusted priority. (Labors other than hauling have a bias added to them -based on how long it's been since they were last used, to prevent job -starvation.) The labor with the highest priority is selected, the "best -fit" dwarf for that labor is assigned to that labor, and then its -priority is *halved*. This process is repeated until either dwarfs or -labors run out. +.. _filltraffic: -Because there is no easy way to detect how many haulers are actually -needed at any moment, the plugin always ensures that at least one dwarf -is assigned to each of the hauling labors, even if no hauling jobs are -detected. At least one dwarf is always assigned to construction removing -and cleaning because these jobs also cannot be easily detected. Lever -pulling is always assigned to everyone. Any dwarfs for which there are -no jobs will be assigned hauling, lever pulling, and cleaning labors. If -you use animal trainers, note that labormanager will misbehave if you -assign specific trainers to specific animals; results are only guaranteed -if you use "any trainer", and animal trainers will probably be -overallocated in any case. +filltraffic +=========== +Set traffic designations using flood-fill starting at the cursor. +See also `alltraffic`, `restrictice`, and `restrictliquids`. Options: -Labormanager also sometimes assigns extra labors to currently busy -dwarfs so that when they finish their current job, they will go off and -do something useful instead of standing around waiting for a job. +:H: High Traffic +:N: Normal Traffic +:L: Low Traffic +:R: Restricted Traffic +:X: Fill across z-levels. +:B: Include buildings and stockpiles. +:P: Include empty space. -There is special handling to ensure that at least one dwarf is assigned -to haul food whenever food is detected left in a place where it will rot -if not stored. This will cause a dwarf to go idle if you have no -storepiles to haul food to. +Example: -Dwarfs who are unable to work (child, in the military, wounded, -handless, asleep, in a meeting) are entirely excluded from labor -assignment. Any dwarf explicitly assigned to a burrow will also be -completely ignored by labormanager. +``filltraffic H`` + When used in a room with doors, it will set traffic to HIGH in just that room. -The fitness algorithm for assigning jobs to dwarfs generally attempts to -favor dwarfs who are more skilled over those who are less skilled. It -also tries to avoid assigning female dwarfs with children to jobs that -are "outside", favors assigning "outside" jobs to dwarfs who are -carrying a tool that could be used as a weapon, and tries to minimize -how often dwarfs have to reequip. +.. _getplants: -Labormanager automatically determines medical needs and reserves health -care providers as needed. Note that this may cause idling if you have -injured dwarfs but no or inadequate hospital facilities. +getplants +========= +This tool allows plant gathering and tree cutting by RAW ID. Specify the types +of trees to cut down and/or shrubs to gather by their plant names, separated +by spaces. -Hunting is never assigned without a butchery, and fishing is never -assigned without a fishery, and neither of these labors is assigned -unless specifically enabled. +Options: -The method by which labormanager determines what labor is needed for a -particular job is complicated and, in places, incomplete. In some -situations, labormanager will detect that it cannot determine what labor -is required. It will, by default, pause and print an error message on -the dfhack console, followed by the message "LABORMANAGER: Game paused -so you can investigate the above message.". If this happens, please open -an issue on github, reporting the lines that immediately preceded this -message. You can tell labormanager to ignore this error and carry on by -typing ``labormanager pause-on-error no``, but be warned that some job may go -undone in this situation. +:``-t``: Tree: Select trees only (exclude shrubs) +:``-s``: Shrub: Select shrubs only (exclude trees) +:``-f``: Farming: Designate only shrubs that yield seeds for farming. Implies -s +:``-c``: Clear: Clear designations instead of setting them +:``-x``: eXcept: Apply selected action to all plants except those specified (invert + selection) +:``-a``: All: Select every type of plant (obeys ``-t``/``-s``/``-f``) +:``-v``: Verbose: Lists the number of (un)designations per plant +:``-n *``: Number: Designate up to * (an integer number) plants of each species -Advanced usage: +Specifying both ``-t`` and ``-s`` or ``-f`` will have no effect. If no plant IDs are +specified, all valid plant IDs will be listed, with ``-t``, ``-s``, and ``-f`` +restricting the list to trees, shrubs, and farmable shrubs, respectively. -:labormanager enable: Turn plugin on. -:labormanager disable: Turn plugin off. -:labormanager priority : Set the priority value (see above) for labor to . -:labormanager reset : Reset the priority value of labor to its default. -:labormanager reset-all: Reset all priority values to their defaults. -:labormanager allow-fishing: Allow dwarfs to fish. *Warning* This tends to result in most of the fort going fishing. -:labormanager forbid-fishing: Forbid dwarfs from fishing. Default behavior. -:labormanager allow-hunting: Allow dwarfs to hunt. *Warning* This tends to result in as many dwarfs going hunting as you have crossbows. -:labormanager forbid-hunting: Forbid dwarfs from hunting. Default behavior. -:labormanager list: Show current priorities and current allocation stats. -:labormanager pause-on-error yes: Make labormanager pause if the labor inference engine fails. See above. -:labormanager pause-on-error no: Allow labormanager to continue past a labor inference engine failure. +.. note:: -.. _nestboxes: + DF is capable of determining that a shrub has already been picked, leaving + an unusable structure part behind. This plugin does not perform such a check + (as the location of the required information has not yet been identified). + This leads to some shrubs being designated when they shouldn't be, causing a + plant gatherer to walk there and do nothing (except clearing the + designation). See :issue:`1479` for details. -nestboxes -========= + The implementation another known deficiency: it's incapable of detecting that + raw definitions that specify a seed extraction reaction for the structural part + but has no other use for it cannot actually yield any seeds, as the part is + never used (parts of :bug:`6940`, e.g. Red Spinach), even though DF + collects it, unless there's a workshop reaction to do it (which there isn't + in vanilla). -Automatically scan for and forbid fertile eggs incubating in a nestbox. -Toggle status with `enable` or `disable `. +.. _infiniteSky: -.. _orders: +infiniteSky +=========== +Automatically allocates new z-levels of sky at the top of the map as you build up, +or on request allocates many levels all at once. -orders -====== +Usage: + +``infiniteSky n`` + Raise the sky by n z-levels. +``infiniteSky enable/disable`` + Enables/disables monitoring of constructions. If you build anything in the second to highest z-level, it will allocate one more sky level. This is so you can continue to build stairs upward. -A plugin for manipulating manager orders. +.. warning:: -Subcommands: + :issue:`Sometimes <254>` new z-levels disappear and cause cave-ins. + Saving and loading after creating new z-levels should fix the problem. -:export NAME: Exports the current list of manager orders to a file named ``dfhack-config/orders/NAME.json``. -:import NAME: Imports manager orders from a file named ``dfhack-config/orders/NAME.json``. -:clear: Deletes all manager orders in the current embark. -:sort: Sorts current manager orders by repeat frequency so daily orders don't - prevent other orders from ever being completed: one-time orders first, then - yearly, seasonally, monthly, then finally daily. +.. _liquids: -You can keep your orders automatically sorted by adding the following command to -your ``onMapLoad.init`` file:: +liquids +======= +Allows adding magma, water and obsidian to the game. It replaces the normal +dfhack command line and can't be used from a hotkey. Settings will be remembered +as long as dfhack runs. Intended for use in combination with the command +``liquids-here`` (which can be bound to a hotkey). See also :issue:`80`. - repeat -name orders-sort -time 1 -timeUnits days -command [ orders sort ] +.. warning:: -.. _seedwatch: + Spawning and deleting liquids can mess up pathing data and + temperatures (creating heat traps). You've been warned. -seedwatch -========= -Watches the numbers of seeds available and enables/disables seed and plant cooking. +.. note:: -Each plant type can be assigned a limit. If their number falls below that limit, -the plants and seeds of that type will be excluded from cookery. -If the number rises above the limit + 20, then cooking will be allowed. + `gui/liquids` is an in-game UI for this script. -The plugin needs a fortress to be loaded and will deactivate automatically otherwise. -You have to reactivate with 'seedwatch start' after you load the game. +Settings will be remembered until you quit DF. You can call `liquids-here` to execute +the last configured action, which is useful in combination with keybindings. -Options: +Usage: point the DF cursor at a tile you want to modify and use the commands. -:all: Adds all plants from the abbreviation list to the watch list. -:start: Start watching. -:stop: Stop watching. -:info: Display whether seedwatch is watching, and the watch list. -:clear: Clears the watch list. +If you only want to add or remove water or magma from one tile, +`source` may be easier to use. -Examples: +Commands +-------- +Misc commands: -``seedwatch MUSHROOM_HELMET_PLUMP 30`` - add ``MUSHROOM_HELMET_PLUMP`` to the watch list, limit = 30 -``seedwatch MUSHROOM_HELMET_PLUMP`` - removes ``MUSHROOM_HELMET_PLUMP`` from the watch list. -``seedwatch all 30`` - adds all plants from the abbreviation list to the watch list, the limit being 30. +:q: quit +:help, ?: print this list of commands +:: put liquid -.. _spotclean: +Modes: -spotclean -========= -Works like ``clean map snow mud``, but only for the tile under the cursor. Ideal -if you want to keep that bloody entrance ``clean map`` would clean up. +:m: switch to magma +:w: switch to water +:o: make obsidian wall instead +:of: make obsidian floors +:rs: make a river source +:f: flow bits only +:wclean: remove salt and stagnant flags from tiles -:dfhack-keybind:`spotclean` +Set-Modes and flow properties (only for magma/water): -.. _stockflow: +:s+: only add mode +:s.: set mode +:s-: only remove mode +:f+: make the spawned liquid flow +:f.: don't change flow state (read state in flow mode) +:f-: make the spawned liquid static -stockflow -========= -Allows the fortress bookkeeper to queue jobs through the manager, -based on space or items available in stockpiles. +Permaflow (only for water): -Inspired by `workflow`. +:pf.: don't change permaflow state +:pf-: make the spawned liquid static +:pf[NS][EW]: make the spawned liquid permanently flow +:0-7: set liquid amount -Usage: +Brush size and shape: -``stockflow enable`` - Enable the plugin. -``stockflow disable`` - Disable the plugin. -``stockflow fast`` - Enable the plugin in fast mode. -``stockflow list`` - List any work order settings for your stockpiles. -``stockflow status`` - Display whether the plugin is enabled. +:p, point: Single tile +:r, range: Block with cursor at bottom north-west (any place, any size) +:block: DF map block with cursor in it (regular spaced 16x16x1 blocks) +:column: Column from cursor, up through free space +:flood: Flood-fill water tiles from cursor (only makes sense with wclean) -While enabled, the :kbd:`q` menu of each stockpile will have two new options: +.. _liquids-here: -* :kbd:`j`: Select a job to order, from an interface like the manager's screen. -* :kbd:`J`: Cycle between several options for how many such jobs to order. +liquids-here +------------ +Run the liquid spawner with the current/last settings made in liquids (if no +settings in liquids were made it paints a point of 7/7 magma by default). -Whenever the bookkeeper updates stockpile records, new work orders will -be placed on the manager's queue for each such selection, reduced by the -number of identical orders already in the queue. +Intended to be used as keybinding. Requires an active in-game cursor. -In fast mode, new work orders will be enqueued once per day, instead of -waiting for the bookkeeper. +.. _plant: -.. _tailor: +plant +===== +A tool for creating shrubs, growing, or getting rid of them. -tailor -====== +Subcommands: -Whenever the bookkeeper updates stockpile records, this plugin will scan every unit in the fort, -count up the number that are worn, and then order enough more made to replace all worn items. -If there are enough replacement items in inventory to replace all worn items, the units wearing them -will have the worn items confiscated (in the same manner as the `cleanowned` plugin) so that they'll -reeequip with replacement items. +:create: Creates a new sapling under the cursor. Takes a raw ID as argument + (e.g. TOWER_CAP). The cursor must be located on a dirt or grass floor tile. +:grow: Turns saplings into trees; under the cursor if a sapling is selected, + or every sapling on the map if the cursor is hidden. -Use the `enable` and `disable ` commands to toggle this plugin's status, or run -``tailor status`` to check its current status. +For mass effects, use one of the additional options: -.. _workflow: +:shrubs: affect all shrubs on the map +:trees: affect all trees on the map +:all: affect every plant! -workflow -======== -Manage control of repeat jobs. `gui/workflow` provides a simple -front-end integrated in the game UI. +.. _regrass: -Usage: +regrass +======= +Regrows all the grass. Not much to it ;) -``workflow enable [option...], workflow disable [option...]`` - If no options are specified, enables or disables the plugin. - Otherwise, enables or disables any of the following options: +.. _restrictice: - - drybuckets: Automatically empty abandoned water buckets. - - auto-melt: Resume melt jobs when there are objects to melt. -``workflow jobs`` - List workflow-controlled jobs (if in a workshop, filtered by it). -``workflow list`` - List active constraints, and their job counts. -``workflow list-commands`` - List active constraints as workflow commands that re-create them; - this list can be copied to a file, and then reloaded using the - ``script`` built-in command. -``workflow count [cnt-gap]`` - Set a constraint, counting every stack as 1 item. -``workflow amount [cnt-gap]`` - Set a constraint, counting all items within stacks. -``workflow unlimit `` - Delete a constraint. -``workflow unlimit-all`` - Delete all constraints. +restrictice +=========== +Restrict traffic on all tiles on top of visible ice. +See also `alltraffic`, `filltraffic`, and `restrictliquids`. -Function --------- -When the plugin is enabled, it protects all repeat jobs from removal. -If they do disappear due to any cause, they are immediately re-added to their -workshop and suspended. +.. _restrictliquids: -In addition, when any constraints on item amounts are set, repeat jobs that -produce that kind of item are automatically suspended and resumed as the item -amount goes above or below the limit. The gap specifies how much below the limit -the amount has to drop before jobs are resumed; this is intended to reduce -the frequency of jobs being toggled. +restrictliquids +=============== +Restrict traffic on all visible tiles with liquid. +See also `alltraffic`, `filltraffic`, and `restrictice`. -Constraint format ------------------ -The constraint spec consists of 4 parts, separated with ``/`` characters:: +.. _tiletypes: - ITEM[:SUBTYPE]/[GENERIC_MAT,...]/[SPECIFIC_MAT:...]/[LOCAL,] +tiletypes +========= +Can be used for painting map tiles and is an interactive command, much like +`liquids`. Some properties of existing tiles can be looked up with `probe`. If +something goes wrong, `fixveins` may help. -The first part is mandatory and specifies the item type and subtype, -using the raw tokens for items (the same syntax used custom reaction inputs). -For more information, see :wiki:`this wiki page `. +The tool works with two set of options and a brush. The brush determines which +tiles will be processed. First set of options is the filter, which can exclude +some of the tiles from the brush by looking at the tile properties. The second +set of options is the paint - this determines how the selected tiles are +changed. -The subsequent parts are optional: +Both paint and filter can have many different properties including things like +general shape (WALL, FLOOR, etc.), general material (SOIL, STONE, MINERAL, +etc.), state of 'designated', 'hidden' and 'light' flags. -- A generic material spec constrains the item material to one of - the hard-coded generic classes, which currently include:: +The properties of filter and paint can be partially defined. This means that +you can for example turn all stone fortifications into floors, preserving the +material:: - PLANT WOOD CLOTH SILK LEATHER BONE SHELL SOAP TOOTH HORN PEARL YARN - METAL STONE SAND GLASS CLAY MILK + filter material STONE + filter shape FORTIFICATION + paint shape FLOOR -- A specific material spec chooses the material exactly, using the - raw syntax for reaction input materials, e.g. ``INORGANIC:IRON``, - although for convenience it also allows just ``IRON``, or ``ACACIA:WOOD`` etc. - See the link above for more details on the unabbreviated raw syntax. +Or turn mineral vein floors back into walls:: -- A comma-separated list of miscellaneous flags, which currently can - be used to ignore imported items or items below a certain quality. + filter shape FLOOR + filter material MINERAL + paint shape WALL -Constraint examples -------------------- -Keep metal bolts within 900-1000, and wood/bone within 150-200:: +The tool also allows tweaking some tile flags:: - workflow amount AMMO:ITEM_AMMO_BOLTS/METAL 1000 100 - workflow amount AMMO:ITEM_AMMO_BOLTS/WOOD,BONE 200 50 + paint hidden 1 + paint hidden 0 -Keep the number of prepared food & drink stacks between 90 and 120:: +This will hide previously revealed tiles (or show hidden with the 0 option). - workflow count FOOD 120 30 - workflow count DRINK 120 30 +More recently, the tool supports changing the base material of the tile to +an arbitrary stone from the raws, by creating new veins as required. Note +that this mode paints under ice and constructions, instead of overwriting +them. To enable, use:: -Make sure there are always 25-30 empty bins/barrels/bags:: + paint stone MICROCLINE - workflow count BIN 30 - workflow count BARREL 30 - workflow count BOX/CLOTH,SILK,YARN 30 +This mode is incompatible with the regular ``material`` setting, so changing +it cancels the specific stone selection:: -Make sure there are always 15-20 coal and 25-30 copper bars:: + paint material ANY - workflow count BAR//COAL 20 - workflow count BAR//COPPER 30 +Since different vein types have different drop rates, it is possible to choose +which one to use in painting:: -Produce 15-20 gold crafts:: + paint veintype CLUSTER_SMALL - workflow count CRAFTS//GOLD 20 +When the chosen type is ``CLUSTER`` (the default), the tool may automatically +choose to use layer stone or lava stone instead of veins if its material matches +the desired one. -Collect 15-20 sand bags and clay boulders:: +Any paint or filter option (or the entire paint or filter) can be disabled entirely by using the ANY keyword:: - workflow count POWDER_MISC/SAND 20 - workflow count BOULDER/CLAY 20 + paint hidden ANY + paint shape ANY + filter material any + filter shape any + filter any -Make sure there are always 80-100 units of dimple dye:: +You can use several different brushes for painting tiles: - workflow amount POWDER_MISC//MUSHROOM_CUP_DIMPLE:MILL 100 20 +:point: a single tile +:range: a rectangular range +:column: a column ranging from current cursor to the first solid tile above +:block: a DF map block - 16x16 tiles, in a regular grid -.. note:: +Example:: - In order for this to work, you have to set the material of the PLANT input - on the Mill Plants job to MUSHROOM_CUP_DIMPLE using the `job item-material ` - command. Otherwise the plugin won't be able to deduce the output material. + range 10 10 1 -Maintain 10-100 locally-made crafts of exceptional quality:: +This will change the brush to a rectangle spanning 10x10 tiles on one z-level. +The range starts at the position of the cursor and goes to the east, south and +up. - workflow count CRAFTS///LOCAL,EXCEPTIONAL 100 90 +For more details, use ``tiletypes help``. -.. _workNow: +.. _tiletypes-command: -workNow -======= -Don't allow dwarves to idle if any jobs are available. +tiletypes-command +----------------- +Runs tiletypes commands, separated by ``;``. This makes it possible to change +tiletypes modes from a hotkey or via dfhack-run. -When workNow is active, every time the game pauses, DF will make dwarves -perform any appropriate available jobs. This includes when you one step -through the game using the pause menu. Usage: +Example:: -:workNow: print workNow status -:workNow 0: deactivate workNow -:workNow 1: activate workNow (look for jobs on pause, and only then) -:workNow 2: make dwarves look for jobs whenever a job completes + tiletypes-command p any ; p s wall ; p sp normal -.. _zone: +This resets the paint filter to unsmoothed walls. -zone -==== -Helps a bit with managing activity zones (pens, pastures and pits) and cages. +.. _tiletypes-here: -:dfhack-keybind:`zone` +tiletypes-here +-------------- +Apply the current tiletypes options at the in-game cursor position, including +the brush. Can be used from a hotkey. Options: -:set: Set zone or cage under cursor as default for future assigns. -:assign: Assign unit(s) to the pen or pit marked with the 'set' command. - If no filters are set a unit must be selected in the in-game ui. - Can also be followed by a valid zone id which will be set - instead. -:unassign: Unassign selected creature from it's zone. -:nick: Mass-assign nicknames, must be followed by the name you want - to set. -:remnick: Mass-remove nicknames. -:enumnick: Assign enumerated nicknames (e.g. "Hen 1", "Hen 2"...). Must be - followed by the prefix to use in nicknames. -:tocages: Assign unit(s) to cages inside a pasture. -:uinfo: Print info about unit(s). If no filters are set a unit must - be selected in the in-game ui. -:zinfo: Print info about zone(s). If no filters are set zones under - the cursor are listed. -:verbose: Print some more info. -:filters: Print list of valid filter options. -:examples: Print some usage examples. -:not: Negates the next filter keyword. +:``-c``, ``--cursor ,,``: + Use the specified map coordinates instead of the current cursor position. If + this option is specified, then an active game map cursor is not necessary. +:``-h``, ``--help``: + Show command help text. +:``-q``, ``--quiet``: + Suppress non-error status output. -Filters: +.. _tiletypes-here-point: -:all: Process all units (to be used with additional filters). -:count: Must be followed by a number. Process only n units (to be used - with additional filters). -:unassigned: Not assigned to zone, chain or built cage. -:minage: Minimum age. Must be followed by number. -:maxage: Maximum age. Must be followed by number. -:race: Must be followed by a race RAW ID (e.g. BIRD_TURKEY, ALPACA, - etc). Negatable. -:caged: In a built cage. Negatable. -:own: From own civilization. Negatable. -:merchant: Is a merchant / belongs to a merchant. Should only be used for - pitting, not for stealing animals (slaughter should work). -:war: Trained war creature. Negatable. -:hunting: Trained hunting creature. Negatable. -:tamed: Creature is tame. Negatable. -:trained: Creature is trained. Finds war/hunting creatures as well as - creatures who have a training level greater than 'domesticated'. - If you want to specifically search for war/hunting creatures use - 'war' or 'hunting' Negatable. -:trainablewar: Creature can be trained for war (and is not already trained for - war/hunt). Negatable. -:trainablehunt: Creature can be trained for hunting (and is not already trained - for war/hunt). Negatable. -:male: Creature is male. Negatable. -:female: Creature is female. Negatable. -:egglayer: Race lays eggs. Negatable. -:grazer: Race is a grazer. Negatable. -:milkable: Race is milkable. Negatable. +tiletypes-here-point +-------------------- +Apply the current tiletypes options at the in-game cursor position to a single +tile. Can be used from a hotkey. -Usage with single units ------------------------ -One convenient way to use the zone tool is to bind the command 'zone assign' to -a hotkey, maybe also the command 'zone set'. Place the in-game cursor over -a pen/pasture or pit, use 'zone set' to mark it. Then you can select units -on the map (in 'v' or 'k' mode), in the unit list or from inside cages -and use 'zone assign' to assign them to their new home. Allows pitting your -own dwarves, by the way. +This command supports the same options as `tiletypes-here` above. -Usage with filters ------------------- -All filters can be used together with the 'assign' command. +.. _tubefill: -Restrictions: It's not possible to assign units who are inside built cages -or chained because in most cases that won't be desirable anyways. -It's not possible to cage owned pets because in that case the owner -uncages them after a while which results in infinite hauling back and forth. +tubefill +======== +Fills all the adamantine veins again. Veins that were hollow will be left +alone. -Usually you should always use the filter 'own' (which implies tame) unless you -want to use the zone tool for pitting hostiles. 'own' ignores own dwarves unless -you specify 'race DWARF' (so it's safe to use 'assign all own' to one big -pasture if you want to have all your animals at the same place). 'egglayer' and -'milkable' should be used together with 'female' unless you have a mod with -egg-laying male elves who give milk or whatever. Merchants and their animals are -ignored unless you specify 'merchant' (pitting them should be no problem, -but stealing and pasturing their animals is not a good idea since currently they -are not properly added to your own stocks; slaughtering them should work). +Options: -Most filters can be negated (e.g. 'not grazer' -> race is not a grazer). +:hollow: fill in naturally hollow veins too -Mass-renaming -------------- -Using the 'nick' command you can set the same nickname for multiple units. -If used without 'assign', 'all' or 'count' it will rename all units in the -current default target zone. Combined with 'assign', 'all' or 'count' (and -further optional filters) it will rename units matching the filter conditions. +Beware that filling in hollow veins will trigger a demon invasion on top of +your miner when you dig into the region that used to be hollow. -Cage zones ----------- -Using the 'tocages' command you can assign units to a set of cages, for example -a room next to your butcher shop(s). They will be spread evenly among available -cages to optimize hauling to and butchering from them. For this to work you need -to build cages and then place one pen/pasture activity zone above them, covering -all cages you want to use. Then use 'zone set' (like with 'assign') and use -'zone tocages filter1 filter2 ...'. 'tocages' overwrites 'assign' because it -would make no sense, but can be used together with 'nick' or 'remnick' and all -the usual filters. -Examples --------- -``zone assign all own ALPACA minage 3 maxage 10`` - Assign all own alpacas who are between 3 and 10 years old to the selected - pasture. -``zone assign all own caged grazer nick ineedgrass`` - Assign all own grazers who are sitting in cages on stockpiles (e.g. after - buying them from merchants) to the selected pasture and give them - the nickname 'ineedgrass'. -``zone assign all own not grazer not race CAT`` - Assign all own animals who are not grazers, excluding cats. -``zone assign count 5 own female milkable`` - Assign up to 5 own female milkable creatures to the selected pasture. -``zone assign all own race DWARF maxage 2`` - Throw all useless kids into a pit :) -``zone nick donttouchme`` - Nicknames all units in the current default zone or cage to 'donttouchme'. - Mostly intended to be used for special pastures or cages which are not marked - as rooms you want to protect from autobutcher. -``zone tocages count 50 own tame male not grazer`` - Stuff up to 50 owned tame male animals who are not grazers into cages built - on the current default zone. -================ -Map modification -================ +================= +Mods and Cheating +================= .. contents:: :local: -.. _3dveins: - -3dveins -======= -Removes all existing veins from the map and generates new ones using -3D Perlin noise, in order to produce a layout that smoothly flows between -Z levels. The vein distribution is based on the world seed, so running -the command for the second time should produce no change. It is best to -run it just once immediately after embark. - -This command is intended as only a cosmetic change, so it takes -care to exactly preserve the mineral counts reported by `prospect` ``all``. -The amounts of different layer stones may slightly change in some cases -if vein mass shifts between Z layers. +.. _add-spatter: -The only undo option is to restore your save from backup. +add-spatter +=========== +This plugin makes reactions with names starting with ``SPATTER_ADD_`` +produce contaminants on the items instead of improvements. The plugin is +intended to give some use to all those poisons that can be bought from caravans, +so they're immune to being washed away by water or destroyed by `clean`. -.. _alltraffic: +.. _adv-bodyswap: -alltraffic -========== -Set traffic designations for every single tile of the map - useful for resetting -traffic designations. See also `filltraffic`, `restrictice`, and `restrictliquids`. +adv-bodyswap +============ +This allows taking control over your followers and other creatures in adventure +mode. For example, you can make them pick up new arms and armor and equip them +properly. -Options: +Usage: -:H: High Traffic -:N: Normal Traffic -:L: Low Traffic -:R: Restricted Traffic +* When viewing unit details, body-swaps into that unit. +* In the main adventure mode screen, reverts transient swap. -.. _burrows: +:dfhack-keybind:`adv-bodyswap` -burrows -======= -Miscellaneous burrow control. Allows manipulating burrows and automated burrow -expansion while digging. +.. _createitem: -Options: +createitem +========== +Allows creating new items of arbitrary types and made of arbitrary materials. A +unit must be selected in-game to use this command. By default, items created are +spawned at the feet of the selected unit. -:enable feature ...: - Enable features of the plugin. -:disable feature ...: - Disable features of the plugin. -:clear-unit burrow burrow ...: - Remove all units from the burrows. -:clear-tiles burrow burrow ...: - Remove all tiles from the burrows. -:set-units target-burrow src-burrow ...: - Clear target, and adds units from source burrows. -:add-units target-burrow src-burrow ...: - Add units from the source burrows to the target. -:remove-units target-burrow src-burrow ...: - Remove units in source burrows from the target. -:set-tiles target-burrow src-burrow ...: - Clear target and adds tiles from the source burrows. -:add-tiles target-burrow src-burrow ...: - Add tiles from the source burrows to the target. -:remove-tiles target-burrow src-burrow ...: - Remove tiles in source burrows from the target. +Specify the item and material information as you would indicate them in +custom reaction raws, with the following differences: - For these three options, in place of a source burrow it is - possible to use one of the following keywords: ABOVE_GROUND, - SUBTERRANEAN, INSIDE, OUTSIDE, LIGHT, DARK, HIDDEN, REVEALED +* Separate the item and material with a space rather than a colon +* If the item has no subtype, the ``:NONE`` can be omitted +* If the item is ``REMAINS``, ``FISH``, ``FISH_RAW``, ``VERMIN``, ``PET``, or ``EGG``, + specify a ``CREATURE:CASTE`` pair instead of a material token. +* If the item is a ``PLANT_GROWTH``, specify a ``PLANT_ID:GROWTH_ID`` pair + instead of a material token. -Features: +Corpses, body parts, and prepared meals cannot be created using this tool. -:auto-grow: When a wall inside a burrow with a name ending in '+' is dug - out, the burrow is extended to newly-revealed adjacent walls. - This final '+' may be omitted in burrow name args of commands above. - Digging 1-wide corridors with the miner inside the burrow is SLOW. +To obtain the item and material tokens of an existing item, run +``createitem inspect``. Its output can be passed directly as arguments to +``createitem`` to create new matching items, as long as the item type is +supported. -.. _changeitem: +Examples: -changeitem -========== -Allows changing item material and base quality. By default the item currently -selected in the UI will be changed (you can select items in the 'k' list -or inside containers/inventory). By default change is only allowed if materials -is of the same subtype (for example wood<->wood, stone<->stone etc). But since -some transformations work pretty well and may be desired you can override this -with 'force'. Note that some attributes will not be touched, possibly resulting -in weirdness. To get an idea how the RAW id should look like, check some items -with 'info'. Using 'force' might create items which are not touched by -crafters/haulers. +* Create 2 pairs of steel gauntlets:: -Options: + createitem GLOVES:ITEM_GLOVES_GAUNTLETS INORGANIC:STEEL 2 -:info: Don't change anything, print some info instead. -:here: Change all items at the cursor position. Requires in-game cursor. -:material, m: Change material. Must be followed by valid material RAW id. -:quality, q: Change base quality. Must be followed by number (0-5). -:force: Ignore subtypes, force change to new material. +* Create tower-cap logs:: -Examples: + createitem WOOD PLANT_MAT:TOWER_CAP:WOOD -``changeitem m INORGANIC:GRANITE here`` - Change material of all items under the cursor to granite. -``changeitem q 5`` - Change currently selected item to masterpiece quality. +* Create bilberries:: -.. _changelayer: + createitem PLANT_GROWTH BILBERRY:FRUIT -changelayer -=========== -Changes material of the geology layer under cursor to the specified inorganic -RAW material. Can have impact on all surrounding regions, not only your embark! -By default changing stone to soil and vice versa is not allowed. By default -changes only the layer at the cursor position. Note that one layer can stretch -across lots of z levels. By default changes only the geology which is linked -to the biome under the cursor. That geology might be linked to other biomes -as well, though. Mineral veins and gem clusters will stay on the map. Use -`changevein` for them. +For more examples, :wiki:`see this wiki page `. -tl;dr: You will end up with changing quite big areas in one go, especially if -you use it in lower z levels. Use with care. +To change where new items are placed, first run the command with a +destination type while an appropriate destination is selected. Options: -:all_biomes: Change selected layer for all biomes on your map. - Result may be undesirable since the same layer can AND WILL - be on different z-levels for different biomes. Use the tool - 'probe' to get an idea how layers and biomes are distributed - on your map. -:all_layers: Change all layers on your map (only for the selected biome - unless 'all_biomes' is added). - Candy mountain, anyone? Will make your map quite boring, - but tidy. -:force: Allow changing stone to soil and vice versa. !!THIS CAN HAVE - WEIRD EFFECTS, USE WITH CARE!! - Note that soil will not be magically replaced with stone. - You will, however, get a stone floor after digging so it - will allow the floor to be engraved. - Note that stone will not be magically replaced with soil. - You will, however, get a soil floor after digging so it - could be helpful for creating farm plots on maps with no - soil. -:verbose: Give some details about what is being changed. -:trouble: Give some advice about known problems. +:floor: Subsequent items will be placed on the floor beneath the selected unit's feet. +:item: Subsequent items will be stored inside the currently selected item. +:building: Subsequent items will become part of the currently selected building. + Good for loading traps; do not use with workshops (or deconstruct to use the item). -Examples: +.. _dig-now: -``changelayer GRANITE`` - Convert layer at cursor position into granite. -``changelayer SILTY_CLAY force`` - Convert layer at cursor position into clay even if it's stone. -``changelayer MARBLE all_biomes all_layers`` - Convert all layers of all biomes which are not soil into marble. +dig-now +======= -.. note:: +Instantly completes non-marker dig designations, modifying tile shapes and +creating boulders, ores, and gems as if a miner were doing the mining or +engraving. By default, the entire map is processed and boulder generation +follows standard game rules, but the behavior is configurable. - * If you use changelayer and nothing happens, try to pause/unpause the game - for a while and try to move the cursor to another tile. Then try again. - If that doesn't help try temporarily changing some other layer, undo your - changes and try again for the layer you want to change. Saving - and reloading your map might also help. - * You should be fine if you only change single layers without the use - of 'force'. Still it's advisable to save your game before messing with - the map. - * When you force changelayer to convert soil to stone you might experience - weird stuff (flashing tiles, tiles changed all over place etc). - Try reverting the changes manually or even better use an older savegame. - You did save your game, right? +Note that no units will get mining or engraving experience for the dug/engraved +tiles. -.. _changevein: +Trees and roots are not currently handled by this plugin and will be skipped. +Requests for engravings are also skipped since they would depend on the skill +and creative choices of individual engravers. Other types of engraving (i.e. +smoothing and track carving) are handled. -changevein -========== -Changes material of the vein under cursor to the specified inorganic RAW -material. Only affects tiles within the current 16x16 block - for veins and -large clusters, you will need to use this command multiple times. +Usage:: -Example: + dig-now [ []] [] -``changevein NATIVE_PLATINUM`` - Convert vein at cursor position into platinum ore. +Where the optional ```` pair can be used to specify the coordinate bounds +within which ``dig-now`` will operate. If they are not specified, ``dig-now`` +will scan the entire map. If only one ```` is specified, only the tile at +that coordinate is processed. -.. _cleanconst: +Any ```` parameters can either be an ``,,`` triple (e.g. +``35,12,150``) or the string ``here``, which means the position of the active +game cursor should be used. -cleanconst -========== -Cleans up construction materials. +Examples: -This utility alters all constructions on the map so that they spawn their -building component when they are disassembled, allowing their actual -build items to be safely deleted. This can improve FPS in extreme situations. +``dig-now`` + Dig designated tiles according to standard game rules. -.. _deramp: +``dig-now --clean`` + Dig designated tiles, but don't generate any boulders, ores, or gems. -deramp -====== -Removes all ramps designated for removal from the map. This is useful for -replicating the old channel digging designation. It also removes any and -all 'down ramps' that can remain after a cave-in (you don't have to designate -anything for that to happen). +``dig-now --dump here`` + Dig tiles and dump all generated boulders, ores, and gems at the tile under + the game cursor. -.. _dig: -.. _digv: -.. _digvx: -.. _digl: -.. _diglx: +Options: -dig -=== -This plugin makes many automated or complicated dig patterns easy. +:``-c``, ``--clean``: + Don't generate any boulders, ores, or gems. Equivalent to + ``--percentages 0,0,0,0``. +:``-d``, ``--dump ``: + Dump any generated items at the specified coordinates. If the tile at those + coordinates is open space or is a wall, items will be generated on the + closest walkable tile below. +:``-e``, ``--everywhere``: + Generate a boulder, ore, or gem for every tile that can produce one. + Equivalent to ``--percentages 100,100,100,100``. +:``-h``, ``--help``: + Show quick usage help text. +:``-p``, ``--percentages ,,,``: + Set item generation percentages for each of the tile categories. The + ``vein`` category includes both the large oval clusters and the long stringy + mineral veins. Default is ``25,33,100,100``. +:``-z``, ``--cur-zlevel``: + Restricts the bounds to the currently visible z-level. -Basic commands: +.. _diggingInvaders: -:digv: Designate all of the selected vein for digging. -:digvx: Also cross z-levels, digging stairs as needed. Alias for ``digv x``. -:digl: Like ``digv``, for layer stone. Also supports an ``undo`` option - to remove designations, for if you accidentally set 50 levels at once. -:diglx: Also cross z-levels, digging stairs as needed. Alias for ``digl x``. +diggingInvaders +=============== +Makes invaders dig or destroy constructions to get to your dwarves. -:dfhack-keybind:`digv` +To enable/disable the pluging, use: ``diggingInvaders (1|enable)|(0|disable)`` -.. note:: +Basic usage: + +:add GOBLIN: registers the race GOBLIN as a digging invader. Case-sensitive. +:remove GOBLIN: unregisters the race GOBLIN as a digging invader. Case-sensitive. +:now: makes invaders try to dig now, if plugin is enabled +:clear: clears all digging invader races +:edgesPerTick n: makes the pathfinding algorithm work on at most n edges per tick. + Set to 0 or lower to make it unlimited. + +You can also use ``diggingInvaders setCost (race) (action) n`` to set the +pathing cost of particular action, or ``setDelay`` to set how long it takes. +Costs and delays are per-tile, and the table shows default values. + +============================== ======= ====== ================================= +Action Cost Delay Notes +============================== ======= ====== ================================= +``walk`` 1 0 base cost in the path algorithm +``destroyBuilding`` 2 1,000 delay adds to the job_completion_timer of destroy building jobs that are assigned to invaders +``dig`` 10,000 1,000 digging soil or natural stone +``destroyRoughConstruction`` 1,000 1,000 constructions made from boulders +``destroySmoothConstruction`` 100 100 constructions made from blocks or bars +============================== ======= ====== ================================= - All commands implemented by the `dig` plugin (listed by ``ls dig``) support - specifying the designation priority with ``-p#``, ``-p #``, or ``p=#``, - where ``#`` is a number from 1 to 7. If a priority is not specified, the - priority selected in-game is used as the default. -.. _digcircle: +.. _fastdwarf: -digcircle +fastdwarf ========= -A command for easy designation of filled and hollow circles. -It has several types of options. +Controls speedydwarf and teledwarf. Speedydwarf makes dwarves move quickly +and perform tasks quickly. Teledwarf makes dwarves move instantaneously, +but do jobs at the same speed. -Shape: +:fastdwarf 0: disables both (also ``0 0``) +:fastdwarf 1: enables speedydwarf and disables teledwarf (also ``1 0``) +:fastdwarf 2: sets a native debug flag in the game memory that implements an + even more aggressive version of speedydwarf. +:fastdwarf 0 1: disables speedydwarf and enables teledwarf +:fastdwarf 1 1: enables both -:hollow: Set the circle to hollow (default) -:filled: Set the circle to filled -:#: Diameter in tiles (default = 0, does nothing) +See `superdwarf` for a per-creature version. -Action: +.. _forceequip: -:set: Set designation (default) -:unset: Unset current designation -:invert: Invert designations already present +forceequip +========== +Forceequip moves local items into a unit's inventory. It is typically used to +equip specific clothing/armor items onto a dwarf, but can also be used to put +armor onto a war animal or to add unusual items (such as crowns) to any unit. -Designation types: +For more information run ``forceequip help``. See also `modtools/equip-item`. -:dig: Normal digging designation (default) -:ramp: Ramp digging -:ustair: Staircase up -:dstair: Staircase down -:xstair: Staircase up/down -:chan: Dig channel +.. _generated-creature-renamer: -After you have set the options, the command called with no options -repeats with the last selected parameters. +generated-creature-renamer +========================== +Automatically renames generated creatures, such as forgotten beasts, titans, +etc, to have raw token names that match the description given in-game. -Examples: +The ``list-generated`` command can be used to list the token names of all +generated creatures in a given save, with an optional ``detailed`` argument +to show the accompanying description. -``digcircle filled 3`` - Dig a filled circle with diameter = 3. -``digcircle`` - Do it again. +The ``save-generated-raws`` command will save a sample creature graphics file in +the Dwarf Fortress root directory, to use as a start for making a graphics set +for generated creatures using the new names that they get with this plugin. -.. _digexp: +The new names are saved with the save, and the plugin, when enabled, only runs once +per save, unless there's an update. -digexp -====== -This command is for :wiki:`exploratory mining `. +.. _lair: -There are two variables that can be set: pattern and filter. +lair +==== +This command allows you to mark the map as a monster lair, preventing item +scatter on abandon. When invoked as ``lair reset``, it does the opposite. -Patterns: +Unlike `reveal`, this command doesn't save the information about tiles - you +won't be able to restore state of real monster lairs using ``lair reset``. -:diag5: diagonals separated by 5 tiles -:diag5r: diag5 rotated 90 degrees -:ladder: A 'ladder' pattern -:ladderr: ladder rotated 90 degrees -:clear: Just remove all dig designations -:cross: A cross, exactly in the middle of the map. +Options: -Filters: +:lair: Mark the map as monster lair +:lair reset: Mark the map as ordinary (not lair) -:all: designate whole z-level -:hidden: designate only hidden tiles of z-level (default) -:designated: Take current designation and apply pattern to it. +.. _misery: -After you have a pattern set, you can use ``expdig`` to apply it again. +misery +====== +When enabled, fake bad thoughts will be added to all dwarves. -Examples: +Usage: -``expdig diag5 hidden`` - Designate the diagonal 5 patter over all hidden tiles -``expdig`` - Apply last used pattern and filter -``expdig ladder designated`` - Take current designations and replace them with the ladder pattern +:misery enable n: enable misery with optional magnitude n. If specified, n must + be positive. +:misery n: same as "misery enable n" +:misery enable: same as "misery enable 1" +:misery disable: stop adding new negative thoughts. This will not remove + existing negative thoughts. Equivalent to "misery 0". +:misery clear: remove fake thoughts, even after saving and reloading. Does + not change factor. -.. _digFlood: +.. _mode: -digFlood -======== -Automatically digs out specified veins as they are discovered. It runs once -every time a dwarf finishes a dig job. It will only dig out appropriate tiles -that are adjacent to the finished dig job. To add a vein type, use ``digFlood 1 [type]``. -This will also enable the plugin. To remove a vein type, use ``digFlood 0 [type] 1`` -to disable, then remove, then re-enable. +mode +==== +This command lets you see and change the game mode directly. -Usage: +.. warning:: -:help digflood: detailed help message -:digFlood 0: disable the plugin -:digFlood 1: enable the plugin -:digFlood 0 MICROCLINE COAL_BITUMINOUS 1: - disable plugin, remove microcline and bituminous coal from monitoring, then re-enable the plugin -:digFlood CLEAR: remove all inorganics from monitoring -:digFlood digAll1: ignore the monitor list and dig any vein -:digFlood digAll0: disable digAll mode + Only use ``mode`` after making a backup of your save! -.. _digtype: + Not all combinations are good for every situation and most of them will + produce undesirable results. There are a few good ones though. -digtype -======= -For every tile on the map of the same vein type as the selected tile, -this command designates it to have the same designation as the -selected tile. If the selected tile has no designation, they will be -dig designated. -If an argument is given, the designation of the selected tile is -ignored, and all appropriate tiles are set to the specified -designation. +Examples: -Options: + * You are in fort game mode, managing your fortress and paused. + * You switch to the arena game mode, *assume control of a creature* and then + * switch to adventure game mode(1). + You just lost a fortress and gained an adventurer. Alternatively: -:dig: -:channel: -:ramp: -:updown: up/down stairs -:up: up stairs -:down: down stairs -:clear: clear designation + * You are in fort game mode, managing your fortress and paused at the esc menu. + * You switch to the adventure game mode, assume control of a creature, then save or retire. + * You just created a returnable mountain home and gained an adventurer. -.. _filltraffic: +.. _power-meter: -filltraffic +power-meter =========== -Set traffic designations using flood-fill starting at the cursor. -See also `alltraffic`, `restrictice`, and `restrictliquids`. Options: +The power-meter plugin implements a modified pressure plate that detects power being +supplied to gear boxes built in the four adjacent N/S/W/E tiles. -:H: High Traffic -:N: Normal Traffic -:L: Low Traffic -:R: Restricted Traffic -:X: Fill across z-levels. -:B: Include buildings and stockpiles. -:P: Include empty space. +The configuration front-end is implemented by `gui/power-meter`. -Example: +.. _siege-engine: -``filltraffic H`` - When used in a room with doors, it will set traffic to HIGH in just that room. +siege-engine +============ +Siege engines in DF haven't been updated since the game was 2D, and can +only aim in four directions. To make them useful above-ground, +this plugin allows you to: -.. _getplants: +* link siege engines to stockpiles +* restrict operator skill levels (like workshops) +* load any object into a catapult, not just stones +* aim at a rectangular area in any direction, and across Z-levels -getplants -========= -This tool allows plant gathering and tree cutting by RAW ID. Specify the types -of trees to cut down and/or shrubs to gather by their plant names, separated -by spaces. +The front-end is implemented by `gui/siege-engine`. -Options: +.. _steam-engine: -:``-t``: Tree: Select trees only (exclude shrubs) -:``-s``: Shrub: Select shrubs only (exclude trees) -:``-f``: Farming: Designate only shrubs that yield seeds for farming. Implies -s -:``-c``: Clear: Clear designations instead of setting them -:``-x``: eXcept: Apply selected action to all plants except those specified (invert - selection) -:``-a``: All: Select every type of plant (obeys ``-t``/``-s``/``-f``) -:``-v``: Verbose: Lists the number of (un)designations per plant -:``-n *``: Number: Designate up to * (an integer number) plants of each species +steam-engine +============ +The steam-engine plugin detects custom workshops with STEAM_ENGINE in +their token, and turns them into real steam engines. -Specifying both ``-t`` and ``-s`` or ``-f`` will have no effect. If no plant IDs are -specified, all valid plant IDs will be listed, with ``-t``, ``-s``, and ``-f`` -restricting the list to trees, shrubs, and farmable shrubs, respectively. +The vanilla game contains only water wheels and windmills as sources of +power, but windmills give relatively little power, and water wheels require +flowing water, which must either be a real river and thus immovable and +limited in supply, or actually flowing and thus laggy. -.. note:: +Compared to the :wiki:`water reactor ` +exploit, steam engines make a lot of sense! - DF is capable of determining that a shrub has already been picked, leaving - an unusable structure part behind. This plugin does not perform such a check - (as the location of the required information has not yet been identified). - This leads to some shrubs being designated when they shouldn't be, causing a - plant gatherer to walk there and do nothing (except clearing the - designation). See :issue:`1479` for details. +Construction +------------ +The workshop needs water as its input, which it takes via a +passable floor tile below it, like usual magma workshops do. +The magma version also needs magma. - The implementation another known deficiency: it's incapable of detecting that - raw definitions that specify a seed extraction reaction for the structural part - but has no other use for it cannot actually yield any seeds, as the part is - never used (parts of :bug:`6940`, e.g. Red Spinach), even though DF - collects it, unless there's a workshop reaction to do it (which there isn't - in vanilla). +Due to DFHack limits, the workshop will collapse over true open space. +However down stairs are passable but support machines, so you can use them. + +After constructing the building itself, machines can be connected +to the edge tiles that look like gear boxes. Their exact position +is extracted from the workshop raws. + +Like with collapse above, due to DFHack limits the workshop +can only immediately connect to machine components built AFTER it. +This also means that engines cannot be chained without intermediate +axles built after both engines. + +Operation +--------- +In order to operate the engine, queue the Stoke Boiler job (optionally +on repeat). A furnace operator will come, possibly bringing a bar of fuel, +and perform it. As a result, a "boiling water" item will appear +in the :kbd:`t` view of the workshop. -.. _infiniteSky: +.. note:: -infiniteSky -=========== -Automatically allocates new z-levels of sky at the top of the map as you build up, -or on request allocates many levels all at once. + The completion of the job will actually consume one unit + of the appropriate liquids from below the workshop. This means + that you cannot just raise 7 units of magma with a piston and + have infinite power. However, liquid consumption should be slow + enough that water can be supplied by a pond zone bucket chain. -Usage: +Every such item gives 100 power, up to a limit of 300 for coal, +and 500 for a magma engine. The building can host twice that +amount of items to provide longer autonomous running. When the +boiler gets filled to capacity, all queued jobs are suspended; +once it drops back to 3+1 or 5+1 items, they are re-enabled. -``infiniteSky n`` - Raise the sky by n z-levels. -``infiniteSky enable/disable`` - Enables/disables monitoring of constructions. If you build anything in the second to highest z-level, it will allocate one more sky level. This is so you can continue to build stairs upward. +While the engine is providing power, steam is being consumed. +The consumption speed includes a fixed 10% waste rate, and +the remaining 90% are applied proportionally to the actual +load in the machine. With the engine at nominal 300 power with +150 load in the system, it will consume steam for actual +300*(10% + 90%*150/300) = 165 power. -.. warning:: +Masterpiece mechanism and chain will decrease the mechanical +power drawn by the engine itself from 10 to 5. Masterpiece +barrel decreases waste rate by 4%. Masterpiece piston and pipe +decrease it by further 4%, and also decrease the whole steam +use rate by 10%. - :issue:`Sometimes <254>` new z-levels disappear and cause cave-ins. - Saving and loading after creating new z-levels should fix the problem. +Explosions +---------- +The engine must be constructed using barrel, pipe and piston +from fire-safe, or in the magma version magma-safe metals. -.. _liquids: +During operation weak parts get gradually worn out, and +eventually the engine explodes. It should also explode if +toppled during operation by a building destroyer, or a +tantruming dwarf. -liquids -======= -Allows adding magma, water and obsidian to the game. It replaces the normal -dfhack command line and can't be used from a hotkey. Settings will be remembered -as long as dfhack runs. Intended for use in combination with the command -``liquids-here`` (which can be bound to a hotkey). See also :issue:`80`. +Save files +---------- +It should be safe to load and view engine-using fortresses +from a DF version without DFHack installed, except that in such +case the engines won't work. However actually making modifications +to them, or machines they connect to (including by pulling levers), +can easily result in inconsistent state once this plugin is +available again. The effects may be as weird as negative power +being generated. -.. warning:: +.. _strangemood: - Spawning and deleting liquids can mess up pathing data and - temperatures (creating heat traps). You've been warned. +strangemood +=========== +Creates a strange mood job the same way the game itself normally does it. -.. note:: +Options: - `gui/liquids` is an in-game UI for this script. +:-force: Ignore normal strange mood preconditions (no recent mood, minimum + moodable population, artifact limit not reached). +:-unit: Make the strange mood strike the selected unit instead of picking + one randomly. Unit eligibility is still enforced. +:-type : Force the mood to be of a particular type instead of choosing randomly based on happiness. + Valid values for T are "fey", "secretive", "possessed", "fell", and "macabre". +:-skill S: Force the mood to use a specific skill instead of choosing the highest moodable skill. + Valid values are "miner", "carpenter", "engraver", "mason", "tanner", "weaver", + "clothier", "weaponsmith", "armorsmith", "metalsmith", "gemcutter", "gemsetter", + "woodcrafter", "stonecrafter", "metalcrafter", "glassmaker", "leatherworker", + "bonecarver", "bowyer", and "mechanic". -Settings will be remembered until you quit DF. You can call `liquids-here` to execute -the last configured action, which is useful in combination with keybindings. +Known limitations: if the selected unit is currently performing a job, the mood will not be started. -Usage: point the DF cursor at a tile you want to modify and use the commands. +============== +Plugin Lua API +============== -If you only want to add or remove water or magma from one tile, -`source` may be easier to use. +Some plugins consist solely of native libraries exposed to Lua. They are listed +in the `lua-api` file under `lua-plugins`: -Commands --------- -Misc commands: +* `building-hacks` +* `cxxrandom` +* `eventful` +* `luasocket` +* `map-render` +* `pathable` +* `xlsxreader` -:q: quit -:help, ?: print this list of commands -:: put liquid +=========== +UI Upgrades +=========== -Modes: +.. note:: + In order to avoid user confusion, as a matter of policy all GUI tools + display the word :guilabel:`DFHack` on the screen somewhere while active. -:m: switch to magma -:w: switch to water -:o: make obsidian wall instead -:of: make obsidian floors -:rs: make a river source -:f: flow bits only -:wclean: remove salt and stagnant flags from tiles + When that is not appropriate because they merely add keybinding hints to + existing DF screens, they deliberately use red instead of green for the key. -Set-Modes and flow properties (only for magma/water): +.. contents:: + :local: -:s+: only add mode -:s.: set mode -:s-: only remove mode -:f+: make the spawned liquid flow -:f.: don't change flow state (read state in flow mode) -:f-: make the spawned liquid static -Permaflow (only for water): +.. _automaterial: -:pf.: don't change permaflow state -:pf-: make the spawned liquid static -:pf[NS][EW]: make the spawned liquid permanently flow -:0-7: set liquid amount +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. -Brush size and shape: +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. -:p, point: Single tile -:r, range: Block with cursor at bottom north-west (any place, any size) -:block: DF map block with cursor in it (regular spaced 16x16x1 blocks) -:column: Column from cursor, up through free space -:flood: Flood-fill water tiles from cursor (only makes sense with wclean) +.. image:: images/automaterial-mat.png -.. _liquids-here: +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. -liquids-here ------------- -Run the liquid spawner with the current/last settings made in liquids (if no -settings in liquids were made it paints a point of 7/7 magma by default). +When choosing the construction placement, you will see a couple of options: -Intended to be used as keybinding. Requires an active in-game cursor. +.. image:: images/automaterial-pos.png -.. _plant: +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. -plant -===== -A tool for creating shrubs, growing, or getting rid of them. +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. -Subcommands: +.. _automelt: -:create: Creates a new sapling under the cursor. Takes a raw ID as argument - (e.g. TOWER_CAP). The cursor must be located on a dirt or grass floor tile. -:grow: Turns saplings into trees; under the cursor if a sapling is selected, - or every sapling on the map if the cursor is hidden. +automelt +======== +When automelt is enabled for a stockpile, any meltable items placed +in it will be designated to be melted. +This plugin adds an option to the :kbd:`q` menu when `enabled `. -For mass effects, use one of the additional options: +.. _autotrade: -:shrubs: affect all shrubs on the map -:trees: affect all trees on the map -:all: affect every plant! +autotrade +========= +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 `. -.. _regrass: +.. _buildingplan: -regrass -======= -Regrows all the grass. Not much to it ;) +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. -.. _restrictice: +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. -restrictice -=========== -Restrict traffic on all tiles on top of visible ice. -See also `alltraffic`, `filltraffic`, and `restrictliquids`. +.. _buildingplan-filters: -.. _restrictliquids: +Item filtering +-------------- -restrictliquids -=============== -Restrict traffic on all visible tiles with liquid. -See also `alltraffic`, `filltraffic`, and `restrictice`. +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. -.. _tiletypes: +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. -tiletypes -========= -Can be used for painting map tiles and is an interactive command, much like -`liquids`. Some properties of existing tiles can be looked up with `probe`. If -something goes wrong, `fixveins` may help. +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. -The tool works with two set of options and a brush. The brush determines which -tiles will be processed. First set of options is the filter, which can exclude -some of the tiles from the brush by looking at the tile properties. The second -set of options is the paint - this determines how the selected tiles are -changed. +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. -Both paint and filter can have many different properties including things like -general shape (WALL, FLOOR, etc.), general material (SOIL, STONE, MINERAL, -etc.), state of 'designated', 'hidden' and 'light' flags. +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. -The properties of filter and paint can be partially defined. This means that -you can for example turn all stone fortifications into floors, preserving the -material:: +.. _buildingplan-settings: - filter material STONE - filter shape FORTIFICATION - paint shape FLOOR +Global settings +--------------- -Or turn mineral vein floors back into walls:: +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:: - filter shape FLOOR - filter material MINERAL - paint shape WALL + buildingplan set -The tool also allows tweaking some tile flags:: +and displayed with:: - paint hidden 1 - paint hidden 0 + buildingplan set -This will hide previously revealed tiles (or show hidden with the 0 option). +The available settings are: -More recently, the tool supports changing the base material of the tile to -an arbitrary stone from the raws, by creating new veins as required. Note -that this mode paints under ice and constructions, instead of overwriting -them. To enable, use:: ++----------------+---------+-----------+---------------------------------------+ +| 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) | ++----------------+---------+-----------+---------------------------------------+ - paint stone MICROCLINE +For example, to ensure you only use blocks when a "building material" item is required, you +could add this to your ``onMapLoad.init`` file:: -This mode is incompatible with the regular ``material`` setting, so changing -it cancels the specific stone selection:: + on-new-fortress buildingplan set boulders false; buildingplan set logs false - paint material ANY +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. -Since different vein types have different drop rates, it is possible to choose -which one to use in painting:: +.. _confirm: - paint veintype CLUSTER_SMALL +confirm +======= +Implements several confirmation dialogs for potentially destructive actions +(for example, seizing goods from traders or deleting hauling routes). -When the chosen type is ``CLUSTER`` (the default), the tool may automatically -choose to use layer stone or lava stone instead of veins if its material matches -the desired one. +Usage: -Any paint or filter option (or the entire paint or filter) can be disabled entirely by using the ANY keyword:: +: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. - paint hidden ANY - paint shape ANY - filter material any - filter shape any - filter any +.. _command-prompt: -You can use several different brushes for painting tiles: +command-prompt +============== +An in-game DFHack terminal, where you can enter other commands. -:point: a single tile -:range: a rectangular range -:column: a column ranging from current cursor to the first solid tile above -:block: a DF map block - 16x16 tiles, in a regular grid +:dfhack-keybind:`command-prompt` -Example:: +Usage: ``command-prompt [entry]`` - range 10 10 1 +If called with an entry, it starts with that text filled in. +Most useful for developers, who can set a keybinding to open +a laungage interpreter for lua or Ruby by starting with the +`:lua ` or `:rb ` commands. -This will change the brush to a rectangle spanning 10x10 tiles on one z-level. -The range starts at the position of the cursor and goes to the east, south and -up. +Otherwise somewhat similar to `gui/quickcmd`. -For more details, use ``tiletypes help``. +.. image:: images/command-prompt.png -.. _tiletypes-command: -tiletypes-command ------------------ -Runs tiletypes commands, separated by ``;``. This makes it possible to change -tiletypes modes from a hotkey or via dfhack-run. +.. _debug: -Example:: +debug +===== +Manager for DFHack runtime debug prints. Debug prints are grouped by plugin name, +category name and print level. Levels are ``trace``, ``debug``, ``info``, +``warning`` and ``error``. - tiletypes-command p any ; p s wall ; p sp normal +The runtime message printing is controlled using filters. Filters set the +visible messages of all matching categories. Matching uses regular expression syntax, +which allows listing multiple alternative matches or partial name matches. +This syntax is a C++ version of the ECMA-262 grammar (Javascript regular expressions). +Details of differences can be found at +https://en.cppreference.com/w/cpp/regex/ecmascript -This resets the paint filter to unsmoothed walls. +Persistent filters are stored in ``dfhack-config/runtime-debug.json``. +Oldest filters are applied first. That means a newer filter can override the +older printing level selection. -.. _tiletypes-here: +Usage: ``debugfilter [subcommand] [parameters...]`` -tiletypes-here --------------- -Apply the current tiletypes options at the in-game cursor position, including -the brush. Can be used from a hotkey. +The following subcommands are supported: -Options: +help +---- +Give overall help or a detailed help for a subcommand. -:``-c``, ``--cursor ,,``: - Use the specified map coordinates instead of the current cursor position. If - this option is specified, then an active game map cursor is not necessary. -:``-h``, ``--help``: - Show command help text. -:``-q``, ``--quiet``: - Suppress non-error status output. +Usage: ``debugfilter help [subcommand]`` -.. _tiletypes-here-point: +category +-------- +List available debug plugin and category names. -tiletypes-here-point --------------------- -Apply the current tiletypes options at the in-game cursor position to a single -tile. Can be used from a hotkey. +Usage: ``debugfilter category [plugin regex] [category regex]`` -This command supports the same options as `tiletypes-here` above. +The list can be filtered using optional regex parameters. If filters aren't +given then the it uses ``"."`` regex which matches any character. The regex +parameters are good way to test regex before passing them to ``set``. -.. _tubefill: +filter +------ +List active and passive debug print level changes. -tubefill -======== -Fills all the adamantine veins again. Veins that were hollow will be left -alone. +Usage: ``debugfilter filter [id]`` -Options: +Optional ``id`` parameter is the id listed as first column in the filter list. +If id is given then the command shows information for the given filter only in +multi line format that is better format if filter has long regex. -:hollow: fill in naturally hollow veins too +set +--- +Creates a new debug filter to set category printing levels. -Beware that filling in hollow veins will trigger a demon invasion on top of -your miner when you dig into the region that used to be hollow. +Usage: ``debugfilter set [level] [plugin regex] [category regex]`` +Adds a filter that will be deleted when DF process exists or plugin is unloaded. +Usage: ``debugfilter set persistent [level] [plugin regex] [category regex]`` -================= -Mods and Cheating -================= +Stores the filter in the configuration file to until ``unset`` is used to remove +it. -.. contents:: - :local: +Level is the minimum debug printing level to show in log. -.. _add-spatter: +* ``trace``: Possibly very noisy messages which can be printed many times per second -add-spatter -=========== -This plugin makes reactions with names starting with ``SPATTER_ADD_`` -produce contaminants on the items instead of improvements. The plugin is -intended to give some use to all those poisons that can be bought from caravans, -so they're immune to being washed away by water or destroyed by `clean`. +* ``debug``: Messages that happen often but they should happen only a couple of times per second -.. _adv-bodyswap: +* ``info``: Important state changes that happen rarely during normal execution -adv-bodyswap -============ -This allows taking control over your followers and other creatures in adventure -mode. For example, you can make them pick up new arms and armor and equip them -properly. +* ``warning``: Enabled by default. Shows warnings about unexpected events which code managed to handle correctly. -Usage: +* ``error``: Enabled by default. Shows errors which code can't handle without user intervention. -* When viewing unit details, body-swaps into that unit. -* In the main adventure mode screen, reverts transient swap. +unset +----- +Delete a space separated list of filters -:dfhack-keybind:`adv-bodyswap` +Usage: ``debugfilter unset [id...]`` -.. _createitem: +disable +------- +Disable a space separated list of filters but keep it in the filter list -createitem -========== -Allows creating new items of arbitrary types and made of arbitrary materials. A -unit must be selected in-game to use this command. By default, items created are -spawned at the feet of the selected unit. +Usage: ``debugfilter disable [id...]`` -Specify the item and material information as you would indicate them in -custom reaction raws, with the following differences: +enable +------ +Enable a space sperate list of filters -* Separate the item and material with a space rather than a colon -* If the item has no subtype, the ``:NONE`` can be omitted -* If the item is ``REMAINS``, ``FISH``, ``FISH_RAW``, ``VERMIN``, ``PET``, or ``EGG``, - specify a ``CREATURE:CASTE`` pair instead of a material token. -* If the item is a ``PLANT_GROWTH``, specify a ``PLANT_ID:GROWTH_ID`` pair - instead of a material token. +Usage: ``debugfilter enable [id...]`` -Corpses, body parts, and prepared meals cannot be created using this tool. +.. _embark-assistant: -To obtain the item and material tokens of an existing item, run -``createitem inspect``. Its output can be passed directly as arguments to -``createitem`` to create new matching items, as long as the item type is -supported. +embark-assistant +================ -Examples: +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. -* Create 2 pairs of steel gauntlets:: +.. _embark-tools: - createitem GLOVES:ITEM_GLOVES_GAUNTLETS INORGANIC:STEEL 2 +embark-tools +============ +A collection of embark-related tools. Usage and available tools:: -* Create tower-cap logs:: + embark-tools enable/disable tool [tool]... - createitem WOOD PLANT_MAT:TOWER_CAP:WOOD +: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 -* Create bilberries:: +.. _follow: - createitem PLANT_GROWTH BILBERRY:FRUIT +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. -For more examples, :wiki:`see this wiki page `. +.. _hotkeys: -To change where new items are placed, first run the command with a -destination type while an appropriate destination is selected. +hotkeys +======= +Opens an in-game screen showing which DFHack keybindings are +active in the current context. See also `hotkey-notes`. -Options: +.. image:: images/hotkeys.png -:floor: Subsequent items will be placed on the floor beneath the selected unit's feet. -:item: Subsequent items will be stored inside the currently selected item. -:building: Subsequent items will become part of the currently selected building. - Good for loading traps; do not use with workshops (or deconstruct to use the item). +:dfhack-keybind:`hotkeys` -.. _dig-now: +.. _manipulator: -dig-now -======= +manipulator +=========== +An in-game equivalent to the popular program Dwarf Therapist. -Instantly completes non-marker dig designations, modifying tile shapes and -creating boulders, ores, and gems as if a miner were doing the mining or -engraving. By default, the entire map is processed and boulder generation -follows standard game rules, but the behavior is configurable. +To activate, open the unit screen and press :kbd:`l`. -Note that no units will get mining or engraving experience for the dug/engraved -tiles. +.. image:: images/manipulator.png -Trees and roots are not currently handled by this plugin and will be skipped. -Requests for engravings are also skipped since they would depend on the skill -and creative choices of individual engravers. Other types of engraving (i.e. -smoothing and track carving) are handled. +The far left column displays the unit's Happiness (color-coded based on its +value), Name, Profession/Squad, and the right half of the screen displays each +dwarf's labor settings and skill levels (0-9 for Dabbling through Professional, +A-E for Great through Grand Master, and U-Z for Legendary through Legendary+5). -Usage:: +Cells with teal backgrounds denote skills not controlled by labors, e.g. +military and social skills. - dig-now [ []] [] +.. image:: images/manipulator2.png -Where the optional ```` pair can be used to specify the coordinate bounds -within which ``dig-now`` will operate. If they are not specified, ``dig-now`` -will scan the entire map. If only one ```` is specified, only the tile at -that coordinate is processed. +Press :kbd:`t` to toggle between Profession, Squad, and Job views. -Any ```` parameters can either be an ``,,`` triple (e.g. -``35,12,150``) or the string ``here``, which means the position of the active -game cursor should be used. +.. image:: images/manipulator3.png -Examples: +Use the arrow keys or number pad to move the cursor around, holding :kbd:`Shift` to +move 10 tiles at a time. -``dig-now`` - Dig designated tiles according to standard game rules. +Press the Z-Up (:kbd:`<`) and Z-Down (:kbd:`>`) keys to move quickly between labor/skill +categories. The numpad Z-Up and Z-Down keys seek to the first or last unit +in the list. :kbd:`Backspace` seeks to the top left corner. -``dig-now --clean`` - Dig designated tiles, but don't generate any boulders, ores, or gems. +Press Enter to toggle the selected labor for the selected unit, or Shift+Enter +to toggle all labors within the selected category. -``dig-now --dump here`` - Dig tiles and dump all generated boulders, ores, and gems at the tile under - the game cursor. +Press the :kbd:`+`:kbd:`-` keys to sort the unit list according to the currently selected +skill/labor, and press the :kbd:`*`:kbd:`/` keys to sort the unit list by Name, Profession/Squad, +Happiness, or Arrival order (using :kbd:`Tab` to select which sort method to use here). -Options: +With a unit selected, you can press the :kbd:`v` key to view its properties (and +possibly set a custom nickname or profession) or the :kbd:`c` key to exit +Manipulator and zoom to its position within your fortress. -:``-c``, ``--clean``: - Don't generate any boulders, ores, or gems. Equivalent to - ``--percentages 0,0,0,0``. -:``-d``, ``--dump ``: - Dump any generated items at the specified coordinates. If the tile at those - coordinates is open space or is a wall, items will be generated on the - closest walkable tile below. -:``-e``, ``--everywhere``: - Generate a boulder, ore, or gem for every tile that can produce one. - Equivalent to ``--percentages 100,100,100,100``. -:``-h``, ``--help``: - Show quick usage help text. -:``-p``, ``--percentages ,,,``: - Set item generation percentages for each of the tile categories. The - ``vein`` category includes both the large oval clusters and the long stringy - mineral veins. Default is ``25,33,100,100``. -:``-z``, ``--cur-zlevel``: - Restricts the bounds to the currently visible z-level. +The following mouse shortcuts are also available: -.. _diggingInvaders: +* Click on a column header to sort the unit list. Left-click to sort it in one + direction (descending for happiness or labors/skills, ascending for name, + profession or squad) and right-click to sort it in the opposite direction. +* Left-click on a labor cell to toggle that labor. Right-click to move the + cursor onto that cell instead of toggling it. +* Left-click on a unit's name, profession or squad to view its properties. +* Right-click on a unit's name, profession or squad to zoom to it. -diggingInvaders -=============== -Makes invaders dig or destroy constructions to get to your dwarves. +Pressing :kbd:`Esc` normally returns to the unit screen, but :kbd:`Shift`:kbd:`Esc` would exit +directly to the main dwarf mode screen. -To enable/disable the pluging, use: ``diggingInvaders (1|enable)|(0|disable)`` +Professions +----------- -Basic usage: +The manipulator plugin supports saving professions: a named set of labors that can be +quickly applied to one or multiple dwarves. -:add GOBLIN: registers the race GOBLIN as a digging invader. Case-sensitive. -:remove GOBLIN: unregisters the race GOBLIN as a digging invader. Case-sensitive. -:now: makes invaders try to dig now, if plugin is enabled -:clear: clears all digging invader races -:edgesPerTick n: makes the pathfinding algorithm work on at most n edges per tick. - Set to 0 or lower to make it unlimited. +To save a profession, highlight a dwarf and press :kbd:`P`. The profession will be saved using +the custom profession name of the dwarf, or the default for that dwarf if no custom profession +name has been set. -You can also use ``diggingInvaders setCost (race) (action) n`` to set the -pathing cost of particular action, or ``setDelay`` to set how long it takes. -Costs and delays are per-tile, and the table shows default values. +To apply a profession, either highlight a single dwarf or select multiple with +:kbd:`x`, and press :kbd:`p` to select the profession to apply. All labors for +the selected dwarves will be reset to the labors of the chosen profession. -============================== ======= ====== ================================= -Action Cost Delay Notes -============================== ======= ====== ================================= -``walk`` 1 0 base cost in the path algorithm -``destroyBuilding`` 2 1,000 delay adds to the job_completion_timer of destroy building jobs that are assigned to invaders -``dig`` 10,000 1,000 digging soil or natural stone -``destroyRoughConstruction`` 1,000 1,000 constructions made from boulders -``destroySmoothConstruction`` 100 100 constructions made from blocks or bars -============================== ======= ====== ================================= +Professions are saved as human-readable text files in the "professions" folder +within the DF folder, and can be edited or deleted there. +.. _mousequery: -.. _fastdwarf: +mousequery +========== +Adds mouse controls to the DF interface, e.g. click-and-drag designations. -fastdwarf -========= -Controls speedydwarf and teledwarf. Speedydwarf makes dwarves move quickly -and perform tasks quickly. Teledwarf makes dwarves move instantaneously, -but do jobs at the same speed. +Options: -:fastdwarf 0: disables both (also ``0 0``) -:fastdwarf 1: enables speedydwarf and disables teledwarf (also ``1 0``) -:fastdwarf 2: sets a native debug flag in the game memory that implements an - even more aggressive version of speedydwarf. -:fastdwarf 0 1: disables speedydwarf and enables teledwarf -:fastdwarf 1 1: enables both +: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. -See `superdwarf` for a per-creature version. +Usage:: -.. _forceequip: + mousequery [plugin] [rbutton] [track] [edge] [live] [enable|disable] -forceequip -========== -Forceequip moves local items into a unit's inventory. It is typically used to -equip specific clothing/armor items onto a dwarf, but can also be used to put -armor onto a war animal or to add unusual items (such as crowns) to any unit. +.. _nopause: -For more information run ``forceequip help``. See also `modtools/equip-item`. +nopause +======= +Disables pausing (both manual and automatic) with the exception of pause forced +by `reveal` ``hell``. This is nice for digging under rivers. -.. _generated-creature-renamer: +.. _rename: -generated-creature-renamer -========================== -Automatically renames generated creatures, such as forgotten beasts, titans, -etc, to have raw token names that match the description given in-game. +rename +====== +Allows renaming various things. Use `gui/rename` for an in-game interface. -The ``list-generated`` command can be used to list the token names of all -generated creatures in a given save, with an optional ``detailed`` argument -to show the accompanying description. +Options: -The ``save-generated-raws`` command will save a sample creature graphics file in -the Dwarf Fortress root directory, to use as a start for making a graphics set -for generated creatures using the new names that they get with this plugin. +``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. -The new names are saved with the save, and the plugin, when enabled, only runs once -per save, unless there's an update. +.. _rendermax: -.. _lair: +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. -lair -==== -This command allows you to mark the map as a monster lair, preventing item -scatter on abandon. When invoked as ``lair reset``, it does the opposite. +Options: -Unlike `reveal`, this command doesn't save the information about tiles - you -won't be able to restore state of real monster lairs using ``lair reset``. +: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. -Options: +An image showing lava and dragon breath. Not pictured here: sunlight, shining items/plants, +materials that color the light etc... -:lair: Mark the map as monster lair -:lair reset: Mark the map as ordinary (not lair) +.. image:: images/rendermax.png -.. _misery: +.. _resume: -misery +resume ====== -When enabled, fake bad thoughts will be added to all dwarves. +Allows automatic resumption of suspended constructions, along with colored +UI hints for construction status. -Usage: +.. _rb: +.. _ruby: -:misery enable n: enable misery with optional magnitude n. If specified, n must - be positive. -:misery n: same as "misery enable n" -:misery enable: same as "misery enable 1" -:misery disable: stop adding new negative thoughts. This will not remove - existing negative thoughts. Equivalent to "misery 0". -:misery clear: remove fake thoughts, even after saving and reloading. Does - not change factor. +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``. -.. _mode: +.. comment - the link target "search" is reserved for the Sphinx search page +.. _search-plugin: -mode -==== -This command lets you see and change the game mode directly. +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. -.. warning:: +.. image:: images/search.png - Only use ``mode`` after making a backup of your save! +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. - Not all combinations are good for every situation and most of them will - produce undesirable results. There are a few good ones though. +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). -Examples: +Leaving any screen automatically clears the filter. - * You are in fort game mode, managing your fortress and paused. - * You switch to the arena game mode, *assume control of a creature* and then - * switch to adventure game mode(1). - You just lost a fortress and gained an adventurer. Alternatively: +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. - * You are in fort game mode, managing your fortress and paused at the esc menu. - * You switch to the adventure game mode, assume control of a creature, then save or retire. - * You just created a returnable mountain home and gained an adventurer. +In the stockpile screen the option only appears if the cursor is in the +rightmost list: -.. _power-meter: +.. image:: images/search-stockpile.png -power-meter -=========== -The power-meter plugin implements a modified pressure plate that detects power being -supplied to gear boxes built in the four adjacent N/S/W/E tiles. +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. -The configuration front-end is implemented by `gui/power-meter`. +.. _sort: +.. _sort-items: -.. _siege-engine: +sort-items +========== +Sort the visible item list:: -siege-engine -============ -Siege engines in DF haven't been updated since the game was 2D, and can -only aim in four directions. To make them useful above-ground, -this plugin allows you to: + sort-items order [order...] -* link siege engines to stockpiles -* restrict operator skill levels (like workshops) -* load any object into a catapult, not just stones -* aim at a rectangular area in any direction, and across Z-levels +Sort the item list using the given sequence of comparisons. +The ``<`` prefix for an order makes undefined values sort first. +The ``>`` prefix reverses the sort order for defined values. -The front-end is implemented by `gui/siege-engine`. +Item order examples:: -.. _steam-engine: + description material wear type quality -steam-engine -============ -The steam-engine plugin detects custom workshops with STEAM_ENGINE in -their token, and turns them into real steam engines. +The orderings are defined in ``hack/lua/plugins/sort/*.lua`` -The vanilla game contains only water wheels and windmills as sources of -power, but windmills give relatively little power, and water wheels require -flowing water, which must either be a real river and thus immovable and -limited in supply, or actually flowing and thus laggy. +.. _sort-units: -Compared to the :wiki:`water reactor ` -exploit, steam engines make a lot of sense! +sort-units +========== +Sort the visible unit list:: -Construction ------------- -The workshop needs water as its input, which it takes via a -passable floor tile below it, like usual magma workshops do. -The magma version also needs magma. + sort-units order [order...] -Due to DFHack limits, the workshop will collapse over true open space. -However down stairs are passable but support machines, so you can use them. +Sort the unit list using the given sequence of comparisons. +The ``<`` prefix for an order makes undefined values sort first. +The ``>`` prefix reverses the sort order for defined values. -After constructing the building itself, machines can be connected -to the edge tiles that look like gear boxes. Their exact position -is extracted from the workshop raws. +Unit order examples:: -Like with collapse above, due to DFHack limits the workshop -can only immediately connect to machine components built AFTER it. -This also means that engines cannot be chained without intermediate -axles built after both engines. + name age arrival squad squad_position profession -Operation ---------- -In order to operate the engine, queue the Stoke Boiler job (optionally -on repeat). A furnace operator will come, possibly bringing a bar of fuel, -and perform it. As a result, a "boiling water" item will appear -in the :kbd:`t` view of the workshop. +The orderings are defined in ``hack/lua/plugins/sort/*.lua`` -.. note:: +:dfhack-keybind:`sort-units` - The completion of the job will actually consume one unit - of the appropriate liquids from below the workshop. This means - that you cannot just raise 7 units of magma with a piston and - have infinite power. However, liquid consumption should be slow - enough that water can be supplied by a pond zone bucket chain. +.. _stocksettings: +.. _stockpiles: -Every such item gives 100 power, up to a limit of 300 for coal, -and 500 for a magma engine. The building can host twice that -amount of items to provide longer autonomous running. When the -boiler gets filled to capacity, all queued jobs are suspended; -once it drops back to 3+1 or 5+1 items, they are re-enabled. +stockpiles +========== +Offers the following commands to save and load stockpile settings. +See `gui/stockpiles` for an in-game interface. -While the engine is providing power, steam is being consumed. -The consumption speed includes a fixed 10% waste rate, and -the remaining 90% are applied proportionally to the actual -load in the machine. With the engine at nominal 300 power with -150 load in the system, it will consume steam for actual -300*(10% + 90%*150/300) = 165 power. +:copystock: Copies the parameters of the currently highlighted stockpile to the custom + stockpile settings and switches to custom stockpile placement mode, effectively + allowing you to copy/paste stockpiles easily. + :dfhack-keybind:`copystock` -Masterpiece mechanism and chain will decrease the mechanical -power drawn by the engine itself from 10 to 5. Masterpiece -barrel decreases waste rate by 4%. Masterpiece piston and pipe -decrease it by further 4%, and also decrease the whole steam -use rate by 10%. +:savestock: Saves the currently highlighted stockpile's settings to a file in your Dwarf + Fortress folder. This file can be used to copy settings between game saves or + players. e.g.: ``savestock food_settings.dfstock`` -Explosions ----------- -The engine must be constructed using barrel, pipe and piston -from fire-safe, or in the magma version magma-safe metals. +:loadstock: Loads a saved stockpile settings file and applies it to the currently selected + stockpile. e.g.: ``loadstock food_settings.dfstock`` -During operation weak parts get gradually worn out, and -eventually the engine explodes. It should also explode if -toppled during operation by a building destroyer, or a -tantruming dwarf. +To use savestock and loadstock, use the :kbd:`q` command to highlight a stockpile. +Then run savestock giving it a descriptive filename. Then, in a different (or +the same!) gameworld, you can highlight any stockpile with :kbd:`q` then execute the +``loadstock`` command passing it the name of that file. The settings will be +applied to that stockpile. -Save files ----------- -It should be safe to load and view engine-using fortresses -from a DF version without DFHack installed, except that in such -case the engines won't work. However actually making modifications -to them, or machines they connect to (including by pulling levers), -can easily result in inconsistent state once this plugin is -available again. The effects may be as weird as negative power -being generated. +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. -.. _strangemood: +.. _stocks: -strangemood -=========== -Creates a strange mood job the same way the game itself normally does it. +stocks +====== +Replaces the DF stocks screen with an improved version. -Options: +:dfhack-keybind:`stocks` -:-force: Ignore normal strange mood preconditions (no recent mood, minimum - moodable population, artifact limit not reached). -:-unit: Make the strange mood strike the selected unit instead of picking - one randomly. Unit eligibility is still enforced. -:-type : Force the mood to be of a particular type instead of choosing randomly based on happiness. - Valid values for T are "fey", "secretive", "possessed", "fell", and "macabre". -:-skill S: Force the mood to use a specific skill instead of choosing the highest moodable skill. - Valid values are "miner", "carpenter", "engraver", "mason", "tanner", "weaver", - "clothier", "weaponsmith", "armorsmith", "metalsmith", "gemcutter", "gemsetter", - "woodcrafter", "stonecrafter", "metalcrafter", "glassmaker", "leatherworker", - "bonecarver", "bowyer", and "mechanic". -Known limitations: if the selected unit is currently performing a job, the mood will not be started. +.. _title-folder: -============== -Plugin Lua API -============== +title-folder +============= +Displays the DF folder name in the window title bar when enabled. -Some plugins consist solely of native libraries exposed to Lua. They are listed -in the `lua-api` file under `lua-plugins`: +.. _title-version: -* `building-hacks` -* `cxxrandom` -* `eventful` -* `luasocket` -* `map-render` -* `pathable` -* `xlsxreader` +title-version +============= +Displays the DFHack version on DF's title screen when enabled. + +.. _trackstop: + +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.