From 3e2320aa607154642cbefad116f92a5ef35c4974 Mon Sep 17 00:00:00 2001 From: myk002 Date: Sat, 9 Jul 2022 23:01:46 -0700 Subject: [PATCH] split the plugin docs into individual files --- docs/plugins/3dveins.rst | 14 ++ docs/plugins/add-spatter.rst | 6 + docs/plugins/adv-bodyswap.rst | 12 ++ docs/plugins/alltraffic.rst | 11 ++ docs/plugins/autobutcher.rst | 91 ++++++++++ docs/plugins/autochop.rst | 16 ++ docs/plugins/autoclothing.rst | 14 ++ docs/plugins/autodump.rst | 29 ++++ docs/plugins/autofarm.rst | 21 +++ docs/plugins/autogems.rst | 7 + docs/plugins/autohauler.rst | 20 +++ docs/plugins/autolabor.rst | 70 ++++++++ docs/plugins/automaterial.rst | 33 ++++ docs/plugins/automelt.rst | 5 + docs/plugins/autonestbox.rst | 19 ++ docs/plugins/autotrade.rst | 5 + docs/plugins/blueprint.rst | 112 ++++++++++++ docs/plugins/buildingplan.rst | 88 ++++++++++ docs/plugins/burrows.rst | 38 ++++ docs/plugins/changeitem.rst | 26 +++ docs/plugins/changelayer.rst | 60 +++++++ docs/plugins/changevein.rst | 10 ++ docs/plugins/clean.rst | 16 ++ docs/plugins/cleanconst.rst | 7 + docs/plugins/cleanowned.rst | 19 ++ docs/plugins/command-prompt.rst | 16 ++ docs/plugins/confirm.rst | 12 ++ docs/plugins/createitem.rst | 48 ++++++ docs/plugins/cursecheck.rst | 42 +++++ docs/plugins/debug.rst | 89 ++++++++++ docs/plugins/deramp.rst | 6 + docs/plugins/dig-now.rst | 61 +++++++ docs/plugins/dig.rst | 20 +++ docs/plugins/digFlood.rst | 18 ++ docs/plugins/digcircle.rst | 35 ++++ docs/plugins/digexp.rst | 31 ++++ docs/plugins/diggingInvaders.rst | 29 ++++ docs/plugins/digl.rst | 20 +++ docs/plugins/diglx.rst | 20 +++ docs/plugins/digtype.rst | 19 ++ docs/plugins/digv.rst | 20 +++ docs/plugins/digvx.rst | 20 +++ docs/plugins/dwarfmonitor.rst | 78 +++++++++ docs/plugins/dwarfvet.rst | 19 ++ docs/plugins/embark-assistant.rst | 9 + docs/plugins/embark-tools.rst | 12 ++ docs/plugins/fastdwarf.rst | 14 ++ docs/plugins/filltraffic.rst | 17 ++ docs/plugins/fix-armory.rst | 4 + docs/plugins/fix-job-postings.rst | 5 + docs/plugins/fix-unit-occupancy.rst | 12 ++ docs/plugins/fixveins.rst | 5 + docs/plugins/flows.rst | 5 + docs/plugins/follow.rst | 5 + docs/plugins/forceequip.rst | 7 + docs/plugins/generated-creature-renamer.rst | 15 ++ docs/plugins/getplants.rst | 37 ++++ docs/plugins/hotkeys.rst | 8 + docs/plugins/infiniteSky.rst | 16 ++ docs/plugins/isoworldremote.rst | 3 + docs/plugins/job-duplicate.rst | 6 + docs/plugins/job-material.rst | 15 ++ docs/plugins/job.rst | 15 ++ docs/plugins/labormanager.rst | 105 +++++++++++ docs/plugins/lair.rst | 12 ++ docs/plugins/liquids-here.rst | 6 + docs/plugins/liquids.rst | 65 +++++++ docs/plugins/manipulator.rst | 182 ++++++++++++++++++++ docs/plugins/misery.rst | 14 ++ docs/plugins/mode.rst | 21 +++ docs/plugins/mousequery.rst | 16 ++ docs/plugins/nestboxes.rst | 5 + docs/plugins/nopause.rst | 4 + docs/plugins/orders.rst | 116 +++++++++++++ docs/plugins/petcapRemover.rst | 19 ++ docs/plugins/plant.rst | 16 ++ docs/plugins/power-meter.rst | 6 + docs/plugins/probe.rst | 13 ++ docs/plugins/prospect.rst | 51 ++++++ docs/plugins/prospector.rst | 51 ++++++ docs/plugins/rb.rst | 4 + docs/plugins/regrass.rst | 3 + docs/plugins/remotefortressreader.rst | 4 + docs/plugins/rename.rst | 19 ++ docs/plugins/rendermax.rst | 18 ++ docs/plugins/restrictice.rst | 4 + docs/plugins/restrictliquids.rst | 4 + docs/plugins/resume.rst | 4 + docs/plugins/reveal.rst | 23 +++ docs/plugins/revflood.rst | 23 +++ docs/plugins/revforget.rst | 23 +++ docs/plugins/revtoggle.rst | 23 +++ docs/plugins/ruby.rst | 4 + docs/plugins/search.rst | 40 +++++ docs/plugins/seedwatch.rst | 27 +++ docs/plugins/showmood.rst | 3 + docs/plugins/siege-engine.rst | 12 ++ docs/plugins/sort-items.rst | 17 ++ docs/plugins/sort-units.rst | 17 ++ docs/plugins/spectate.rst | 5 + docs/plugins/spotclean.rst | 6 + docs/plugins/steam-engine.rst | 84 +++++++++ docs/plugins/stockflow.rst | 31 ++++ docs/plugins/stockpiles.rst | 28 +++ docs/plugins/stocks.rst | 6 + docs/plugins/stonesense.rst | 10 ++ docs/plugins/strangemood.rst | 19 ++ docs/plugins/tailor.rst | 11 ++ docs/plugins/tiletypes-command.rst | 10 ++ docs/plugins/tiletypes-here-point.rst | 6 + docs/plugins/tiletypes-here.rst | 14 ++ docs/plugins/tiletypes.rst | 82 +++++++++ docs/plugins/title-folder.rst | 3 + docs/plugins/title-version.rst | 3 + docs/plugins/trackstop.rst | 5 + docs/plugins/tubefill.rst | 11 ++ docs/plugins/tweak.rst | 91 ++++++++++ docs/plugins/unreveal.rst | 23 +++ docs/plugins/workNow.rst | 12 ++ docs/plugins/workflow.rst | 113 ++++++++++++ docs/plugins/zone.rst | 130 ++++++++++++++ 121 files changed, 3239 insertions(+) create mode 100644 docs/plugins/3dveins.rst create mode 100644 docs/plugins/add-spatter.rst create mode 100644 docs/plugins/adv-bodyswap.rst create mode 100644 docs/plugins/alltraffic.rst create mode 100644 docs/plugins/autobutcher.rst create mode 100644 docs/plugins/autochop.rst create mode 100644 docs/plugins/autoclothing.rst create mode 100644 docs/plugins/autodump.rst create mode 100644 docs/plugins/autofarm.rst create mode 100644 docs/plugins/autogems.rst create mode 100644 docs/plugins/autohauler.rst create mode 100644 docs/plugins/autolabor.rst create mode 100644 docs/plugins/automaterial.rst create mode 100644 docs/plugins/automelt.rst create mode 100644 docs/plugins/autonestbox.rst create mode 100644 docs/plugins/autotrade.rst create mode 100644 docs/plugins/blueprint.rst create mode 100644 docs/plugins/buildingplan.rst create mode 100644 docs/plugins/burrows.rst create mode 100644 docs/plugins/changeitem.rst create mode 100644 docs/plugins/changelayer.rst create mode 100644 docs/plugins/changevein.rst create mode 100644 docs/plugins/clean.rst create mode 100644 docs/plugins/cleanconst.rst create mode 100644 docs/plugins/cleanowned.rst create mode 100644 docs/plugins/command-prompt.rst create mode 100644 docs/plugins/confirm.rst create mode 100644 docs/plugins/createitem.rst create mode 100644 docs/plugins/cursecheck.rst create mode 100644 docs/plugins/debug.rst create mode 100644 docs/plugins/deramp.rst create mode 100644 docs/plugins/dig-now.rst create mode 100644 docs/plugins/dig.rst create mode 100644 docs/plugins/digFlood.rst create mode 100644 docs/plugins/digcircle.rst create mode 100644 docs/plugins/digexp.rst create mode 100644 docs/plugins/diggingInvaders.rst create mode 100644 docs/plugins/digl.rst create mode 100644 docs/plugins/diglx.rst create mode 100644 docs/plugins/digtype.rst create mode 100644 docs/plugins/digv.rst create mode 100644 docs/plugins/digvx.rst create mode 100644 docs/plugins/dwarfmonitor.rst create mode 100644 docs/plugins/dwarfvet.rst create mode 100644 docs/plugins/embark-assistant.rst create mode 100644 docs/plugins/embark-tools.rst create mode 100644 docs/plugins/fastdwarf.rst create mode 100644 docs/plugins/filltraffic.rst create mode 100644 docs/plugins/fix-armory.rst create mode 100644 docs/plugins/fix-job-postings.rst create mode 100644 docs/plugins/fix-unit-occupancy.rst create mode 100644 docs/plugins/fixveins.rst create mode 100644 docs/plugins/flows.rst create mode 100644 docs/plugins/follow.rst create mode 100644 docs/plugins/forceequip.rst create mode 100644 docs/plugins/generated-creature-renamer.rst create mode 100644 docs/plugins/getplants.rst create mode 100644 docs/plugins/hotkeys.rst create mode 100644 docs/plugins/infiniteSky.rst create mode 100644 docs/plugins/isoworldremote.rst create mode 100644 docs/plugins/job-duplicate.rst create mode 100644 docs/plugins/job-material.rst create mode 100644 docs/plugins/job.rst create mode 100644 docs/plugins/labormanager.rst create mode 100644 docs/plugins/lair.rst create mode 100644 docs/plugins/liquids-here.rst create mode 100644 docs/plugins/liquids.rst create mode 100644 docs/plugins/manipulator.rst create mode 100644 docs/plugins/misery.rst create mode 100644 docs/plugins/mode.rst create mode 100644 docs/plugins/mousequery.rst create mode 100644 docs/plugins/nestboxes.rst create mode 100644 docs/plugins/nopause.rst create mode 100644 docs/plugins/orders.rst create mode 100644 docs/plugins/petcapRemover.rst create mode 100644 docs/plugins/plant.rst create mode 100644 docs/plugins/power-meter.rst create mode 100644 docs/plugins/probe.rst create mode 100644 docs/plugins/prospect.rst create mode 100644 docs/plugins/prospector.rst create mode 100644 docs/plugins/rb.rst create mode 100644 docs/plugins/regrass.rst create mode 100644 docs/plugins/remotefortressreader.rst create mode 100644 docs/plugins/rename.rst create mode 100644 docs/plugins/rendermax.rst create mode 100644 docs/plugins/restrictice.rst create mode 100644 docs/plugins/restrictliquids.rst create mode 100644 docs/plugins/resume.rst create mode 100644 docs/plugins/reveal.rst create mode 100644 docs/plugins/revflood.rst create mode 100644 docs/plugins/revforget.rst create mode 100644 docs/plugins/revtoggle.rst create mode 100644 docs/plugins/ruby.rst create mode 100644 docs/plugins/search.rst create mode 100644 docs/plugins/seedwatch.rst create mode 100644 docs/plugins/showmood.rst create mode 100644 docs/plugins/siege-engine.rst create mode 100644 docs/plugins/sort-items.rst create mode 100644 docs/plugins/sort-units.rst create mode 100644 docs/plugins/spectate.rst create mode 100644 docs/plugins/spotclean.rst create mode 100644 docs/plugins/steam-engine.rst create mode 100644 docs/plugins/stockflow.rst create mode 100644 docs/plugins/stockpiles.rst create mode 100644 docs/plugins/stocks.rst create mode 100644 docs/plugins/stonesense.rst create mode 100644 docs/plugins/strangemood.rst create mode 100644 docs/plugins/tailor.rst create mode 100644 docs/plugins/tiletypes-command.rst create mode 100644 docs/plugins/tiletypes-here-point.rst create mode 100644 docs/plugins/tiletypes-here.rst create mode 100644 docs/plugins/tiletypes.rst create mode 100644 docs/plugins/title-folder.rst create mode 100644 docs/plugins/title-version.rst create mode 100644 docs/plugins/trackstop.rst create mode 100644 docs/plugins/tubefill.rst create mode 100644 docs/plugins/tweak.rst create mode 100644 docs/plugins/unreveal.rst create mode 100644 docs/plugins/workNow.rst create mode 100644 docs/plugins/workflow.rst create mode 100644 docs/plugins/zone.rst diff --git a/docs/plugins/3dveins.rst b/docs/plugins/3dveins.rst new file mode 100644 index 000000000..0e6841792 --- /dev/null +++ b/docs/plugins/3dveins.rst @@ -0,0 +1,14 @@ +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. + +The only undo option is to restore your save from backup. diff --git a/docs/plugins/add-spatter.rst b/docs/plugins/add-spatter.rst new file mode 100644 index 000000000..15b99ff52 --- /dev/null +++ b/docs/plugins/add-spatter.rst @@ -0,0 +1,6 @@ +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`. diff --git a/docs/plugins/adv-bodyswap.rst b/docs/plugins/adv-bodyswap.rst new file mode 100644 index 000000000..46b961517 --- /dev/null +++ b/docs/plugins/adv-bodyswap.rst @@ -0,0 +1,12 @@ +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. + +Usage: + +* When viewing unit details, body-swaps into that unit. +* In the main adventure mode screen, reverts transient swap. + +:dfhack-keybind:`adv-bodyswap` diff --git a/docs/plugins/alltraffic.rst b/docs/plugins/alltraffic.rst new file mode 100644 index 000000000..1e9116954 --- /dev/null +++ b/docs/plugins/alltraffic.rst @@ -0,0 +1,11 @@ +alltraffic +========== +Set traffic designations for every single tile of the map - useful for resetting +traffic designations. See also `filltraffic`, `restrictice`, and `restrictliquids`. + +Options: + +:H: High Traffic +:N: Normal Traffic +:L: Low Traffic +:R: Restricted Traffic diff --git a/docs/plugins/autobutcher.rst b/docs/plugins/autobutcher.rst new file mode 100644 index 000000000..d761cbdbe --- /dev/null +++ b/docs/plugins/autobutcher.rst @@ -0,0 +1,91 @@ +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. + +Units will be ignored if they are: + +* 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 + +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. + +Options: + +: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. + +.. note:: + + 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. + + 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. + + +Examples: + +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. :: + + autobutcher target 4 3 2 1 ALPACA BIRD_TURKEY + autobutcher target 0 0 0 0 CAT + autobutcher watch ALPACA BIRD_TURKEY CAT + autobutcher start + +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. :: + + autobutcher target 0 0 0 0 new + autobutcher autowatch + autobutcher start + +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. :: + + autobutcher unwatch ALPACA CAT diff --git a/docs/plugins/autochop.rst b/docs/plugins/autochop.rst new file mode 100644 index 000000000..4a669480f --- /dev/null +++ b/docs/plugins/autochop.rst @@ -0,0 +1,16 @@ +autochop +======== +Automatically manage tree cutting designation to keep available logs withing given +quotas. + +Open the dashboard by running:: + + enable autochop + +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. diff --git a/docs/plugins/autoclothing.rst b/docs/plugins/autoclothing.rst new file mode 100644 index 000000000..7169844dd --- /dev/null +++ b/docs/plugins/autoclothing.rst @@ -0,0 +1,14 @@ +autoclothing +============ + +Automatically manage clothing work orders, allowing the user to set how many of +each clothing type every citizen should have. Usage:: + + 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. diff --git a/docs/plugins/autodump.rst b/docs/plugins/autodump.rst new file mode 100644 index 000000000..9bd74cff7 --- /dev/null +++ b/docs/plugins/autodump.rst @@ -0,0 +1,29 @@ +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. + +Cursor must be placed on a floor tile so the items can be dumped there. + +Options: + +: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). + +``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` diff --git a/docs/plugins/autofarm.rst b/docs/plugins/autofarm.rst new file mode 100644 index 000000000..b330517d0 --- /dev/null +++ b/docs/plugins/autofarm.rst @@ -0,0 +1,21 @@ +autofarm +======== + +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.) + +Use the `enable` or `disable ` commands to change whether this plugin is +enabled. + +Usage: + +* ``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 diff --git a/docs/plugins/autogems.rst b/docs/plugins/autogems.rst new file mode 100644 index 000000000..59800e1b9 --- /dev/null +++ b/docs/plugins/autogems.rst @@ -0,0 +1,7 @@ +autogems +======== +Creates a new Workshop Order setting, automatically cutting rough gems +when `enabled `. + +See `gui/autogems` for a configuration UI. If necessary, the ``autogems-reload`` +command reloads the configuration file produced by that script. diff --git a/docs/plugins/autohauler.rst b/docs/plugins/autohauler.rst new file mode 100644 index 000000000..289874f94 --- /dev/null +++ b/docs/plugins/autohauler.rst @@ -0,0 +1,20 @@ +autohauler +========== +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. diff --git a/docs/plugins/autolabor.rst b/docs/plugins/autolabor.rst new file mode 100644 index 000000000..b63b9102b --- /dev/null +++ b/docs/plugins/autolabor.rst @@ -0,0 +1,70 @@ +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 equipment (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. diff --git a/docs/plugins/automaterial.rst b/docs/plugins/automaterial.rst new file mode 100644 index 000000000..81de0cb3d --- /dev/null +++ b/docs/plugins/automaterial.rst @@ -0,0 +1,33 @@ +automaterial +============ +This makes building constructions (walls, floors, fortifications, etc) a little bit +easier by saving you from having to trawl through long lists of materials each time +you place one. + +Firstly, it moves the last used material for a given construction type to the top of +the list, if there are any left. So if you build a wall with chalk blocks, the next +time you place a wall the chalk blocks will be at the top of the list, regardless of +distance (it only does this in "grouped" mode, as individual item lists could be huge). +This should mean you can place most constructions without having to search for your +preferred material type. + +.. image:: ../images/automaterial-mat.png + +Pressing :kbd:`a` while highlighting any material will enable that material for "auto select" +for this construction type. You can enable multiple materials as autoselect. Now the next +time you place this type of construction, the plugin will automatically choose materials +for you from the kinds you enabled. If there is enough to satisfy the whole placement, +you won't be prompted with the material screen - the construction will be placed and you +will be back in the construction menu as if you did it manually. + +When choosing the construction placement, you will see a couple of options: + +.. image:: ../images/automaterial-pos.png + +Use :kbd:`a` here to temporarily disable the material autoselection, e.g. if you need +to go to the material selection screen so you can toggle some materials on or off. + +The other option (auto type selection, off by default) can be toggled on with :kbd:`t`. If you +toggle this option on, instead of returning you to the main construction menu after selecting +materials, it returns you back to this screen. If you use this along with several autoselect +enabled materials, you should be able to place complex constructions more conveniently. diff --git a/docs/plugins/automelt.rst b/docs/plugins/automelt.rst new file mode 100644 index 000000000..73f8ba502 --- /dev/null +++ b/docs/plugins/automelt.rst @@ -0,0 +1,5 @@ +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 `. diff --git a/docs/plugins/autonestbox.rst b/docs/plugins/autonestbox.rst new file mode 100644 index 000000000..f19cad42c --- /dev/null +++ b/docs/plugins/autonestbox.rst @@ -0,0 +1,19 @@ +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. + +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. diff --git a/docs/plugins/autotrade.rst b/docs/plugins/autotrade.rst new file mode 100644 index 000000000..4f0d95efd --- /dev/null +++ b/docs/plugins/autotrade.rst @@ -0,0 +1,5 @@ +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 `. diff --git a/docs/plugins/blueprint.rst b/docs/plugins/blueprint.rst new file mode 100644 index 000000000..6d5e306d1 --- /dev/null +++ b/docs/plugins/blueprint.rst @@ -0,0 +1,112 @@ +blueprint +========= +The ``blueprint`` command exports the structure of a portion of your fortress in +a blueprint file that you (or anyone else) can later play back with `quickfort`. + +Blueprints are ``.csv`` or ``.xlsx`` files created in the ``blueprints`` +subdirectory of your DF folder. The map area to turn into a blueprint is either +selected interactively with the ``blueprint gui`` command or, if the GUI is not +used, starts at the active cursor location and extends right and down for the +requested width and height. + +**Usage:** + + ``blueprint [] [ []] []`` + + ``blueprint gui [ []] []`` + +**Examples:** + +``blueprint gui`` + Runs `gui/blueprint`, the interactive frontend, where all configuration for + a ``blueprint`` command can be set visually and interactively. + +``blueprint 30 40 bedrooms`` + Generates blueprints for an area 30 tiles wide by 40 tiles tall, starting + from the active cursor on the current z-level. Blueprints are written + sequentially to ``bedrooms.csv`` in the ``blueprints`` directory. + +``blueprint 30 40 bedrooms dig --cursor 108,100,150`` + Generates only the ``#dig`` blueprint in the ``bedrooms.csv`` file, and + the start of the blueprint area is set to a specific value instead of using + the in-game cursor position. + +**Positional Parameters:** + +:``width``: Width of the area (in tiles) to translate. +:``height``: Height of the area (in tiles) to translate. +:``depth``: Number of z-levels to translate. Positive numbers go *up* from the + cursor and negative numbers go *down*. Defaults to 1 if not specified, + indicating that the blueprint should only include the current z-level. +:``name``: Base name for blueprint files created in the ``blueprints`` + directory. If no name is specified, "blueprint" is used by default. The + string must contain some characters other than numbers so the name won't be + confused with the optional ``depth`` parameter. + +**Phases:** + +If you want to generate blueprints only for specific phases, add their names to +the commandline, anywhere after the blueprint base name. You can list multiple +phases; just separate them with a space. + +:``dig``: Generate quickfort ``#dig`` blueprints for digging natural stone. +:``carve``: Generate quickfort ``#dig`` blueprints for smoothing and carving. +:``build``: Generate quickfort ``#build`` blueprints for constructions and + buildings. +:``place``: Generate quickfort ``#place`` blueprints for placing stockpiles. +:``zone``: Generate quickfort ``#zone`` blueprints for designating zones. +:``query``: Generate quickfort ``#query`` blueprints for configuring rooms. + +If no phases are specified, phases are autodetected. For example, a ``#place`` +blueprint will be created only if there are stockpiles in the blueprint area. + +**Options:** + +``-c``, ``--cursor ,,``: + Use the specified map coordinates instead of the current cursor position for + the upper left corner of the blueprint range. If this option is specified, + then an active game map cursor is not necessary. +``-e``, ``--engrave``: + Record engravings in the ``carve`` phase. If this option is not specified, + engravings are ignored. +``-f``, ``--format ``: + Select the output format of the generated files. See the ``Output formats`` + section below for options. If not specified, the output format defaults to + "minimal", which will produce a small, fast ``.csv`` file. +``-h``, ``--help``: + Show command help text. +``-s``, ``--playback-start ,,``: + Specify the column and row offsets (relative to the upper-left corner of the + blueprint, which is ``1,1``) where the player should put the cursor when the + blueprint is played back with `quickfort`, in + `quickfort start marker ` format, for example: + ``10,10,central stairs``. If there is a space in the comment, you will need + to surround the parameter string in double quotes: ``"-s10,10,central stairs"`` or + ``--playback-start "10,10,central stairs"`` or + ``"--playback-start=10,10,central stairs"``. +``-t``, ``--splitby ``: + Split blueprints into multiple files. See the ``Splitting output into + multiple files`` section below for details. If not specified, defaults to + "none", which will create a standard quickfort + `multi-blueprint ` file. + +**Output formats:** + +Here are the values that can be passed to the ``--format`` flag: + +:``minimal``: + Creates ``.csv`` files with minimal file size that are fast to read and + write. This is the default. +:``pretty``: + Makes the blueprints in the ``.csv`` files easier to read and edit with a text + editor by adding extra spacing and alignment markers. + +**Splitting output into multiple files:** + +The ``--splitby`` flag can take any of the following values: + +:``none``: + Writes all blueprints into a single file. This is the standard format for + quickfort fortress blueprint bundles and is the default. +:``phase``: + Creates a separate file for each phase. diff --git a/docs/plugins/buildingplan.rst b/docs/plugins/buildingplan.rst new file mode 100644 index 000000000..ca6273d10 --- /dev/null +++ b/docs/plugins/buildingplan.rst @@ -0,0 +1,88 @@ +buildingplan +============ +When active (via ``enable buildingplan``), this plugin adds a planning mode for +building placement. You can then place furniture, constructions, and other buildings +before the required materials are available, and they will be created in a suspended +state. Buildingplan will periodically scan for appropriate items, and the jobs will +be unsuspended when the items are available. + +This is very useful when combined with `workflow` - you can set a constraint +to always have one or two doors/beds/tables/chairs/etc available, and place +as many as you like. The plugins then take over and fulfill the orders, +with minimal space dedicated to stockpiles. + +.. _buildingplan-filters: + +Item filtering +-------------- + +While placing a building, you can set filters for what materials you want the building made +out of, what quality you want the component items to be, and whether you want the items to +be decorated. + +If a building type takes more than one item to construct, use :kbd:`Ctrl`:kbd:`Left` and +:kbd:`Ctrl`:kbd:`Right` to select the item that you want to set filters for. Any filters that +you set will be used for all buildings of the selected type placed from that point onward +(until you set a new filter or clear the current one). Buildings placed before the filters +were changed will keep the filter values that were set when the building was placed. + +For example, you can be sure that all your constructed walls are the same color by setting +a filter to accept only certain types of stone. + +Quickfort mode +-------------- + +If you use the external Python Quickfort to apply building blueprints instead of the native +DFHack `quickfort` script, you must enable Quickfort mode. This temporarily enables +buildingplan for all building types and adds an extra blank screen after every building +placement. This "dummy" screen is needed for Python Quickfort to interact successfully with +Dwarf Fortress. + +Note that Quickfort mode is only for compatibility with the legacy Python Quickfort. The +DFHack `quickfort` script does not need Quickfort mode to be enabled. The `quickfort` script +will successfully integrate with buildingplan as long as the buildingplan plugin is enabled. + +.. _buildingplan-settings: + +Global settings +--------------- + +The buildingplan plugin has several global settings that can be set from the UI (:kbd:`G` +from any building placement screen, for example: :kbd:`b`:kbd:`a`:kbd:`G`). These settings +can also be set from the ``DFHack#`` prompt once a map is loaded (or from your +``onMapLoad.init`` file) with the syntax:: + + buildingplan set + +and displayed with:: + + buildingplan set + +The available settings are: + ++----------------+---------+-----------+---------------------------------------+ +| Setting | Default | Persisted | Description | ++================+=========+===========+=======================================+ +| all_enabled | false | no | Enable planning mode for all building | +| | | | types. | ++----------------+---------+-----------+---------------------------------------+ +| blocks | true | yes | Allow blocks, boulders, logs, or bars | ++----------------+---------+ | to be matched for generic "building | +| boulders | true | | material" items | ++----------------+---------+ | | +| logs | true | | | ++----------------+---------+ | | +| bars | false | | | ++----------------+---------+-----------+---------------------------------------+ +| quickfort_mode | false | no | Enable compatibility mode for the | +| | | | legacy Python Quickfort (not required | +| | | | for DFHack quickfort) | ++----------------+---------+-----------+---------------------------------------+ + +For example, to ensure you only use blocks when a "building material" item is required, you +could add this to your ``onMapLoad.init`` file:: + + on-new-fortress buildingplan set boulders false; buildingplan set logs false + +Persisted settings (i.e. ``blocks``, ``boulders``, ``logs``, and ``bars``) are saved with +your game, so you only need to set them to the values you want once. diff --git a/docs/plugins/burrows.rst b/docs/plugins/burrows.rst new file mode 100644 index 000000000..787b3ff37 --- /dev/null +++ b/docs/plugins/burrows.rst @@ -0,0 +1,38 @@ +burrows +======= +Miscellaneous burrow control. Allows manipulating burrows and automated burrow +expansion while digging. + +Options: + +: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 + +Features: + +: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. diff --git a/docs/plugins/changeitem.rst b/docs/plugins/changeitem.rst new file mode 100644 index 000000000..c6da2516f --- /dev/null +++ b/docs/plugins/changeitem.rst @@ -0,0 +1,26 @@ +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. + +Options: + +: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. + +Examples: + +``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. diff --git a/docs/plugins/changelayer.rst b/docs/plugins/changelayer.rst new file mode 100644 index 000000000..87c27921c --- /dev/null +++ b/docs/plugins/changelayer.rst @@ -0,0 +1,60 @@ +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: + +: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. + +Examples: + +``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. + +.. note:: + + * 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? diff --git a/docs/plugins/changevein.rst b/docs/plugins/changevein.rst new file mode 100644 index 000000000..ad7ab3d54 --- /dev/null +++ b/docs/plugins/changevein.rst @@ -0,0 +1,10 @@ +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. + +Example: + +``changevein NATIVE_PLATINUM`` + Convert vein at cursor position into platinum ore. diff --git a/docs/plugins/clean.rst b/docs/plugins/clean.rst new file mode 100644 index 000000000..f2d0c361d --- /dev/null +++ b/docs/plugins/clean.rst @@ -0,0 +1,16 @@ +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. + +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. + +Extra options for ``map``: + +:mud: Remove mud in addition to the normal stuff. +:snow: Also remove snow coverings. diff --git a/docs/plugins/cleanconst.rst b/docs/plugins/cleanconst.rst new file mode 100644 index 000000000..a8169d83b --- /dev/null +++ b/docs/plugins/cleanconst.rst @@ -0,0 +1,7 @@ +cleanconst +========== +Cleans up construction materials. + +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. diff --git a/docs/plugins/cleanowned.rst b/docs/plugins/cleanowned.rst new file mode 100644 index 000000000..7f80e35cf --- /dev/null +++ b/docs/plugins/cleanowned.rst @@ -0,0 +1,19 @@ +cleanowned +========== +Confiscates items owned by dwarfs. By default, owned food on the floor +and rotten items are confistacted and dumped. + +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. + +Example: + +``cleanowned scattered X`` + This will confiscate rotten and dropped food, garbage on the floors and any + worn items with 'X' damage and above. diff --git a/docs/plugins/command-prompt.rst b/docs/plugins/command-prompt.rst new file mode 100644 index 000000000..061b405ef --- /dev/null +++ b/docs/plugins/command-prompt.rst @@ -0,0 +1,16 @@ +command-prompt +============== +An in-game DFHack terminal, where you can enter other commands. + +:dfhack-keybind:`command-prompt` + +Usage: ``command-prompt [entry]`` + +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. + +Otherwise somewhat similar to `gui/quickcmd`. + +.. image:: ../images/command-prompt.png diff --git a/docs/plugins/confirm.rst b/docs/plugins/confirm.rst new file mode 100644 index 000000000..c7fb89bb0 --- /dev/null +++ b/docs/plugins/confirm.rst @@ -0,0 +1,12 @@ +confirm +======= +Implements several confirmation dialogs for potentially destructive actions +(for example, seizing goods from traders or deleting hauling routes). + +Usage: + +:enable confirm: Enable all confirmations; alias ``confirm enable all``. + Replace with ``disable`` to disable. +:confirm help: List available confirmation dialogues. +:confirm enable option1 [option2...]: + Enable (or disable) specific confirmation dialogues. diff --git a/docs/plugins/createitem.rst b/docs/plugins/createitem.rst new file mode 100644 index 000000000..f37154f80 --- /dev/null +++ b/docs/plugins/createitem.rst @@ -0,0 +1,48 @@ +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. + +Specify the item and material information as you would indicate them in +custom reaction raws, with the following differences: + +* 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. + +Corpses, body parts, and prepared meals cannot be created using this tool. + +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. + +Examples: + +* Create 2 pairs of steel gauntlets:: + + createitem GLOVES:ITEM_GLOVES_GAUNTLETS INORGANIC:STEEL 2 + +* Create tower-cap logs:: + + createitem WOOD PLANT_MAT:TOWER_CAP:WOOD + +* Create bilberries:: + + createitem PLANT_GROWTH BILBERRY:FRUIT + +For more examples, :wiki:`see this wiki page `. + +To change where new items are placed, first run the command with a +destination type while an appropriate destination is selected. + +Options: + +: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). diff --git a/docs/plugins/cursecheck.rst b/docs/plugins/cursecheck.rst new file mode 100644 index 000000000..1bf1803fa --- /dev/null +++ b/docs/plugins/cursecheck.rst @@ -0,0 +1,42 @@ +cursecheck +========== +Checks a single map tile or the whole map/world for cursed creatures (ghosts, +vampires, necromancers, werebeasts, zombies). + +With an active in-game cursor only the selected tile will be observed. +Without a cursor the whole map will be checked. + +By default cursed creatures will be only counted in case you just want to find +out if you have any of them running around in your fort. Dead and passive +creatures (ghosts who were put to rest, killed vampires, ...) are ignored. +Undead skeletons, corpses, bodyparts and the like are all thrown into the curse +category "zombie". Anonymous zombies and resurrected body parts will show +as "unnamed creature". + +Options: + +:detail: Print full name, date of birth, date of curse and some status + info (some vampires might use fake identities in-game, though). +:ids: Print the creature and race IDs. +:nick: Set the type of curse as nickname (does not always show up + in-game, some vamps don't like nicknames). +:all: Include dead and passive cursed creatures (can result in a quite + long list after having FUN with necromancers). +:verbose: Print all curse tags (if you really want to know it all). + +Examples: + +``cursecheck detail all`` + Give detailed info about all cursed creatures including deceased ones (no + in-game cursor). +``cursecheck nick`` + Give a nickname all living/active cursed creatures on the map(no in-game + cursor). + +.. note:: + + If you do a full search (with the option "all") former ghosts will show up + with the cursetype "unknown" because their ghostly flag is not set. + + Please report any living/active creatures with cursetype "unknown" - + this is most likely with mods which introduce new types of curses. diff --git a/docs/plugins/debug.rst b/docs/plugins/debug.rst new file mode 100644 index 000000000..2bef7d28a --- /dev/null +++ b/docs/plugins/debug.rst @@ -0,0 +1,89 @@ +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``. + +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 + +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. + +Usage: ``debugfilter [subcommand] [parameters...]`` + +The following subcommands are supported: + +help +---- +Give overall help or a detailed help for a subcommand. + +Usage: ``debugfilter help [subcommand]`` + +category +-------- +List available debug plugin and category names. + +Usage: ``debugfilter category [plugin regex] [category regex]`` + +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``. + +filter +------ +List active and passive debug print level changes. + +Usage: ``debugfilter filter [id]`` + +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. + +set +--- +Creates a new debug filter to set category printing levels. + +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]`` + +Stores the filter in the configuration file to until ``unset`` is used to remove +it. + +Level is the minimum debug printing level to show in log. + +* ``trace``: Possibly very noisy messages which can be printed many times per second + +* ``debug``: Messages that happen often but they should happen only a couple of times per second + +* ``info``: Important state changes that happen rarely during normal execution + +* ``warning``: Enabled by default. Shows warnings about unexpected events which code managed to handle correctly. + +* ``error``: Enabled by default. Shows errors which code can't handle without user intervention. + +unset +----- +Delete a space separated list of filters + +Usage: ``debugfilter unset [id...]`` + +disable +------- +Disable a space separated list of filters but keep it in the filter list + +Usage: ``debugfilter disable [id...]`` + +enable +------ +Enable a space sperate list of filters + +Usage: ``debugfilter enable [id...]`` diff --git a/docs/plugins/deramp.rst b/docs/plugins/deramp.rst new file mode 100644 index 000000000..a6b944381 --- /dev/null +++ b/docs/plugins/deramp.rst @@ -0,0 +1,6 @@ +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). diff --git a/docs/plugins/dig-now.rst b/docs/plugins/dig-now.rst new file mode 100644 index 000000000..b6f4d64f7 --- /dev/null +++ b/docs/plugins/dig-now.rst @@ -0,0 +1,61 @@ +dig-now +======= + +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. + +Note that no units will get mining or engraving experience for the dug/engraved +tiles. + +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. + +Usage:: + + dig-now [ []] [] + +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. + +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. + +Examples: + +``dig-now`` + Dig designated tiles according to standard game rules. + +``dig-now --clean`` + Dig designated tiles, but don't generate any boulders, ores, or gems. + +``dig-now --dump here`` + Dig tiles and dump all generated boulders, ores, and gems at the tile under + the game cursor. + +Options: + +:``-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. diff --git a/docs/plugins/dig.rst b/docs/plugins/dig.rst new file mode 100644 index 000000000..f09626d0c --- /dev/null +++ b/docs/plugins/dig.rst @@ -0,0 +1,20 @@ +dig +=== +This plugin makes many automated or complicated dig patterns easy. + +Basic commands: + +: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``. + +:dfhack-keybind:`digv` + +.. note:: + + 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. diff --git a/docs/plugins/digFlood.rst b/docs/plugins/digFlood.rst new file mode 100644 index 000000000..dd957feb2 --- /dev/null +++ b/docs/plugins/digFlood.rst @@ -0,0 +1,18 @@ +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. + +Usage: + +: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 diff --git a/docs/plugins/digcircle.rst b/docs/plugins/digcircle.rst new file mode 100644 index 000000000..fc31b65df --- /dev/null +++ b/docs/plugins/digcircle.rst @@ -0,0 +1,35 @@ +digcircle +========= +A command for easy designation of filled and hollow circles. +It has several types of options. + +Shape: + +:hollow: Set the circle to hollow (default) +:filled: Set the circle to filled +:#: Diameter in tiles (default = 0, does nothing) + +Action: + +:set: Set designation (default) +:unset: Unset current designation +:invert: Invert designations already present + +Designation types: + +:dig: Normal digging designation (default) +:ramp: Ramp digging +:ustair: Staircase up +:dstair: Staircase down +:xstair: Staircase up/down +:chan: Dig channel + +After you have set the options, the command called with no options +repeats with the last selected parameters. + +Examples: + +``digcircle filled 3`` + Dig a filled circle with diameter = 3. +``digcircle`` + Do it again. diff --git a/docs/plugins/digexp.rst b/docs/plugins/digexp.rst new file mode 100644 index 000000000..e4412d051 --- /dev/null +++ b/docs/plugins/digexp.rst @@ -0,0 +1,31 @@ +digexp +====== +This command is for :wiki:`exploratory mining `. + +There are two variables that can be set: pattern and filter. + +Patterns: + +: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. + +Filters: + +:all: designate whole z-level +:hidden: designate only hidden tiles of z-level (default) +:designated: Take current designation and apply pattern to it. + +After you have a pattern set, you can use ``expdig`` to apply it again. + +Examples: + +``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 diff --git a/docs/plugins/diggingInvaders.rst b/docs/plugins/diggingInvaders.rst new file mode 100644 index 000000000..0557225fb --- /dev/null +++ b/docs/plugins/diggingInvaders.rst @@ -0,0 +1,29 @@ +diggingInvaders +=============== +Makes invaders dig or destroy constructions to get to your dwarves. + +To enable/disable the pluging, use: ``diggingInvaders (1|enable)|(0|disable)`` + +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 +============================== ======= ====== ================================= + diff --git a/docs/plugins/digl.rst b/docs/plugins/digl.rst new file mode 100644 index 000000000..f09626d0c --- /dev/null +++ b/docs/plugins/digl.rst @@ -0,0 +1,20 @@ +dig +=== +This plugin makes many automated or complicated dig patterns easy. + +Basic commands: + +: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``. + +:dfhack-keybind:`digv` + +.. note:: + + 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. diff --git a/docs/plugins/diglx.rst b/docs/plugins/diglx.rst new file mode 100644 index 000000000..f09626d0c --- /dev/null +++ b/docs/plugins/diglx.rst @@ -0,0 +1,20 @@ +dig +=== +This plugin makes many automated or complicated dig patterns easy. + +Basic commands: + +: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``. + +:dfhack-keybind:`digv` + +.. note:: + + 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. diff --git a/docs/plugins/digtype.rst b/docs/plugins/digtype.rst new file mode 100644 index 000000000..1c2d49eaa --- /dev/null +++ b/docs/plugins/digtype.rst @@ -0,0 +1,19 @@ +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. + +Options: + +:dig: +:channel: +:ramp: +:updown: up/down stairs +:up: up stairs +:down: down stairs +:clear: clear designation diff --git a/docs/plugins/digv.rst b/docs/plugins/digv.rst new file mode 100644 index 000000000..f09626d0c --- /dev/null +++ b/docs/plugins/digv.rst @@ -0,0 +1,20 @@ +dig +=== +This plugin makes many automated or complicated dig patterns easy. + +Basic commands: + +: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``. + +:dfhack-keybind:`digv` + +.. note:: + + 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. diff --git a/docs/plugins/digvx.rst b/docs/plugins/digvx.rst new file mode 100644 index 000000000..f09626d0c --- /dev/null +++ b/docs/plugins/digvx.rst @@ -0,0 +1,20 @@ +dig +=== +This plugin makes many automated or complicated dig patterns easy. + +Basic commands: + +: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``. + +:dfhack-keybind:`digv` + +.. note:: + + 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. diff --git a/docs/plugins/dwarfmonitor.rst b/docs/plugins/dwarfmonitor.rst new file mode 100644 index 000000000..cbe3e8bdc --- /dev/null +++ b/docs/plugins/dwarfmonitor.rst @@ -0,0 +1,78 @@ +dwarfmonitor +============ +Records dwarf activity to measure fort efficiency. + +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``) + +:dfhack-keybind:`dwarfmonitor` + +Widget configuration: + +The following types of widgets (defined in :file:`hack/lua/plugins/dwarfmonitor.lua`) +can be displayed on the main fortress mode screen: + +: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 + +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: + +.. code-block:: lua + + { + "widgets": [ + { + "type": "widget type (weather, misery, etc.)", + "x": X coordinate, + "y": Y coordinate + <...additional options...> + } + ] + } + +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. + +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. + +Some widgets support additional options: + +* ``date`` widget: + + * ``format``: specifies the format of the date. The following characters + are replaced (all others, such as punctuation, are not modified) + + * ``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 + + The default date format is ``Y-M-D``, per the ISO8601_ standard. + + .. _ISO8601: https://en.wikipedia.org/wiki/ISO_8601 + +* ``cursor`` widget: + + * ``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. diff --git a/docs/plugins/dwarfvet.rst b/docs/plugins/dwarfvet.rst new file mode 100644 index 000000000..1ceb1bc2f --- /dev/null +++ b/docs/plugins/dwarfvet.rst @@ -0,0 +1,19 @@ +dwarfvet +======== +Enables Animal Caretaker functionality + +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. + +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). + +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 diff --git a/docs/plugins/embark-assistant.rst b/docs/plugins/embark-assistant.rst new file mode 100644 index 000000000..4500a919e --- /dev/null +++ b/docs/plugins/embark-assistant.rst @@ -0,0 +1,9 @@ +embark-assistant +================ + +This plugin provides embark site selection help. It has to be run with the +``embark-assistant`` command while the pre-embark screen is displayed and shows +extended (and correct(?)) resource information for the embark rectangle as well +as normally undisplayed sites in the current embark region. It also has a site +selection tool with more options than DF's vanilla search tool. For detailed +help invoke the in game info screen. diff --git a/docs/plugins/embark-tools.rst b/docs/plugins/embark-tools.rst new file mode 100644 index 000000000..fcab18fc7 --- /dev/null +++ b/docs/plugins/embark-tools.rst @@ -0,0 +1,12 @@ +embark-tools +============ +A collection of embark-related tools. Usage and available tools:: + + embark-tools enable/disable tool [tool]... + +:anywhere: Allows embarking anywhere (including sites, mountain-only biomes, + and oceans). Use with caution. +:mouse: Implements mouse controls (currently in the local embark region only) +:sand: Displays an indicator when sand is present in the currently-selected + area, similar to the default clay/stone indicators. +:sticky: Maintains the selected local area while navigating the world map diff --git a/docs/plugins/fastdwarf.rst b/docs/plugins/fastdwarf.rst new file mode 100644 index 000000000..65d2a3d45 --- /dev/null +++ b/docs/plugins/fastdwarf.rst @@ -0,0 +1,14 @@ +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. + +: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 + +See `superdwarf` for a per-creature version. diff --git a/docs/plugins/filltraffic.rst b/docs/plugins/filltraffic.rst new file mode 100644 index 000000000..6a9c57c9f --- /dev/null +++ b/docs/plugins/filltraffic.rst @@ -0,0 +1,17 @@ +filltraffic +=========== +Set traffic designations using flood-fill starting at the cursor. +See also `alltraffic`, `restrictice`, and `restrictliquids`. Options: + +: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. + +Example: + +``filltraffic H`` + When used in a room with doors, it will set traffic to HIGH in just that room. diff --git a/docs/plugins/fix-armory.rst b/docs/plugins/fix-armory.rst new file mode 100644 index 000000000..f4b988420 --- /dev/null +++ b/docs/plugins/fix-armory.rst @@ -0,0 +1,4 @@ +fix-armory +========== +`This plugin requires a binpatch `, which has not +been available since DF 0.34.11 diff --git a/docs/plugins/fix-job-postings.rst b/docs/plugins/fix-job-postings.rst new file mode 100644 index 000000000..198dcd61d --- /dev/null +++ b/docs/plugins/fix-job-postings.rst @@ -0,0 +1,5 @@ +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). diff --git a/docs/plugins/fix-unit-occupancy.rst b/docs/plugins/fix-unit-occupancy.rst new file mode 100644 index 000000000..bf999c8a3 --- /dev/null +++ b/docs/plugins/fix-unit-occupancy.rst @@ -0,0 +1,12 @@ +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. diff --git a/docs/plugins/fixveins.rst b/docs/plugins/fixveins.rst new file mode 100644 index 000000000..58678d154 --- /dev/null +++ b/docs/plugins/fixveins.rst @@ -0,0 +1,5 @@ +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. diff --git a/docs/plugins/flows.rst b/docs/plugins/flows.rst new file mode 100644 index 000000000..3df451195 --- /dev/null +++ b/docs/plugins/flows.rst @@ -0,0 +1,5 @@ +flows +===== +A tool for checking how many tiles contain flowing liquids. If you suspect that +your magma sea leaks into HFS, you can use this tool to be sure without +revealing the map. diff --git a/docs/plugins/follow.rst b/docs/plugins/follow.rst new file mode 100644 index 000000000..a91c14f73 --- /dev/null +++ b/docs/plugins/follow.rst @@ -0,0 +1,5 @@ +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. diff --git a/docs/plugins/forceequip.rst b/docs/plugins/forceequip.rst new file mode 100644 index 000000000..2278bca22 --- /dev/null +++ b/docs/plugins/forceequip.rst @@ -0,0 +1,7 @@ +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. + +For more information run ``forceequip help``. See also `modtools/equip-item`. diff --git a/docs/plugins/generated-creature-renamer.rst b/docs/plugins/generated-creature-renamer.rst new file mode 100644 index 000000000..bb486a4ee --- /dev/null +++ b/docs/plugins/generated-creature-renamer.rst @@ -0,0 +1,15 @@ +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. + +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. + +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. + +The new names are saved with the save, and the plugin, when enabled, only runs once +per save, unless there's an update. diff --git a/docs/plugins/getplants.rst b/docs/plugins/getplants.rst new file mode 100644 index 000000000..5a719b3ab --- /dev/null +++ b/docs/plugins/getplants.rst @@ -0,0 +1,37 @@ +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. + +Options: + +:``-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 + +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. + +.. note:: + + 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. + + 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). diff --git a/docs/plugins/hotkeys.rst b/docs/plugins/hotkeys.rst new file mode 100644 index 000000000..57c3b3af5 --- /dev/null +++ b/docs/plugins/hotkeys.rst @@ -0,0 +1,8 @@ +hotkeys +======= +Opens an in-game screen showing which DFHack keybindings are +active in the current context. See also `hotkey-notes`. + +.. image:: ../images/hotkeys.png + +:dfhack-keybind:`hotkeys` diff --git a/docs/plugins/infiniteSky.rst b/docs/plugins/infiniteSky.rst new file mode 100644 index 000000000..328ee83bd --- /dev/null +++ b/docs/plugins/infiniteSky.rst @@ -0,0 +1,16 @@ +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. + +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. + +.. warning:: + + :issue:`Sometimes <254>` new z-levels disappear and cause cave-ins. + Saving and loading after creating new z-levels should fix the problem. diff --git a/docs/plugins/isoworldremote.rst b/docs/plugins/isoworldremote.rst new file mode 100644 index 000000000..7bacc2b57 --- /dev/null +++ b/docs/plugins/isoworldremote.rst @@ -0,0 +1,3 @@ +isoworldremote +============== +A plugin that implements a `remote API ` used by Isoworld. diff --git a/docs/plugins/job-duplicate.rst b/docs/plugins/job-duplicate.rst new file mode 100644 index 000000000..a18d73df3 --- /dev/null +++ b/docs/plugins/job-duplicate.rst @@ -0,0 +1,6 @@ +job-duplicate +============= +In :kbd:`q` mode, when a job is highlighted within a workshop or furnace +building, calling ``job-duplicate`` instantly duplicates the job. + +:dfhack-keybind:`job-duplicate` diff --git a/docs/plugins/job-material.rst b/docs/plugins/job-material.rst new file mode 100644 index 000000000..f1b37fc1d --- /dev/null +++ b/docs/plugins/job-material.rst @@ -0,0 +1,15 @@ +job-material +============ +Alter the material of the selected job. Similar to ``job item-material ...`` + +Invoked as:: + + job-material + +:dfhack-keybind:`job-material` + +* 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. diff --git a/docs/plugins/job.rst b/docs/plugins/job.rst new file mode 100644 index 000000000..26f163864 --- /dev/null +++ b/docs/plugins/job.rst @@ -0,0 +1,15 @@ +job +=== +Command for general job query and manipulation. + +Options: + +*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. diff --git a/docs/plugins/labormanager.rst b/docs/plugins/labormanager.rst new file mode 100644 index 000000000..d16a10e33 --- /dev/null +++ b/docs/plugins/labormanager.rst @@ -0,0 +1,105 @@ +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. + +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. + +.. warning:: + + *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* + +Simple usage: + +:enable labormanager: Enables the plugin with default settings. + (Persistent per fortress) + +:disable labormanager: Disables the plugin. + +Anything beyond this is optional - labormanager works fairly well on the +default settings. + +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. + +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. + +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. + +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. + +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. + +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. + +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. + +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. + +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. + +Advanced usage: + +: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. diff --git a/docs/plugins/lair.rst b/docs/plugins/lair.rst new file mode 100644 index 000000000..b80e71e3a --- /dev/null +++ b/docs/plugins/lair.rst @@ -0,0 +1,12 @@ +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. + +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``. + +Options: + +:lair: Mark the map as monster lair +:lair reset: Mark the map as ordinary (not lair) diff --git a/docs/plugins/liquids-here.rst b/docs/plugins/liquids-here.rst new file mode 100644 index 000000000..d838170a2 --- /dev/null +++ b/docs/plugins/liquids-here.rst @@ -0,0 +1,6 @@ +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). + +Intended to be used as keybinding. Requires an active in-game cursor. diff --git a/docs/plugins/liquids.rst b/docs/plugins/liquids.rst new file mode 100644 index 000000000..d55962ad5 --- /dev/null +++ b/docs/plugins/liquids.rst @@ -0,0 +1,65 @@ +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`. + +.. warning:: + + Spawning and deleting liquids can mess up pathing data and + temperatures (creating heat traps). You've been warned. + +.. note:: + + `gui/liquids` is an in-game UI for this script. + +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. + +Usage: point the DF cursor at a tile you want to modify and use the commands. + +If you only want to add or remove water or magma from one tile, +`source` may be easier to use. + +Commands +-------- +Misc commands: + +:q: quit +:help, ?: print this list of commands +:: put liquid + +Modes: + +: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 + +Set-Modes and flow properties (only for magma/water): + +: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): + +: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 + +Brush size and shape: + +: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) diff --git a/docs/plugins/manipulator.rst b/docs/plugins/manipulator.rst new file mode 100644 index 000000000..024438d85 --- /dev/null +++ b/docs/plugins/manipulator.rst @@ -0,0 +1,182 @@ +manipulator +=========== +An in-game equivalent to the popular program Dwarf Therapist. + +To activate, open the unit screen and press :kbd:`l`. + +.. image:: ../images/manipulator.png + +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). + +Cells with teal backgrounds denote skills not controlled by labors, e.g. +military and social skills. + +.. image:: ../images/manipulator2.png + +Press :kbd:`t` to toggle between Profession, Squad, and Job views. + +.. image:: ../images/manipulator3.png + +Use the arrow keys or number pad to move the cursor around, holding :kbd:`Shift` to +move 10 tiles at a time. + +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. + +Press Enter to toggle the selected labor for the selected unit, or Shift+Enter +to toggle all labors within the selected category. + +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). + +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. + +The following mouse shortcuts are also available: + +* 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. + +Pressing :kbd:`Esc` normally returns to the unit screen, but :kbd:`Shift`:kbd:`Esc` would exit +directly to the main dwarf mode screen. + +Professions +----------- + +The manipulator plugin supports saving professions: a named set of labors that can be +quickly applied to one or multiple dwarves. + +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. + +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. + +Professions are saved as human-readable text files in the +``dfhack-config/professions`` folder within the DF folder, and can be edited or +deleted there. + +The professions library +~~~~~~~~~~~~~~~~~~~~~~~ + +The manipulator plugin comes with a library of professions that you can assign +to your dwarves. + +If you'd rather use Dwarf Therapist to manage your labors, it is easy to import +these professions to DT and use them there. Simply assign the professions you +want to import to a dwarf. Once you have assigned a profession to at least one +dwarf, you can select "Import Professions from DF" in the DT "File" menu. The +professions will then be available for use in DT. + +In the charts below, the "At Start" and "Max" columns indicate the approximate +number of dwarves of each profession that you are likely to need at the start of +the game and how many you are likely to need in a mature fort. These are just +approximations. Your playstyle may demand more or fewer of each profession. + +============= ======== ===== ================================================= +Profession At Start Max Description +============= ======== ===== ================================================= +Chef 0 3 Buchery, Tanning, and Cooking. It is important to + focus just a few dwarves on cooking since + well-crafted meals make dwarves very happy. They + are also an excellent trade good. +Craftsdwarf 0 4-6 All labors used at Craftsdwarf's workshops, + Glassmaker's workshops, and kilns. +Doctor 0 2-4 The full suite of medical labors, plus Animal + Caretaking for those using the dwarfvet plugin. +Farmer 1 4 Food- and animal product-related labors. This + profession also has the ``Alchemist`` labor + enabled since they need to focus on food-related + jobs, though you might want to disable + ``Alchemist`` for your first farmer until there + are actual farming duties to perform. +Fisherdwarf 0 0-1 Fishing and fish cleaning. If you assign this + profession to any dwarf, be prepared to be + inundated with fish. Fisherdwarves *never stop + fishing*. Be sure to also run ``prioritize -a + PrepareRawFish ExtractFromRawFish`` or else + caught fish will just be left to rot. +Hauler 0 >20 All hauling labors plus Siege Operating, Mechanic + (so haulers can assist in reloading traps) and + Architecture (so haulers can help build massive + windmill farms and pump stacks). As you + accumulate enough Haulers, you can turn off + hauling labors for other dwarves so they can + focus on their skilled tasks. You may also want + to restrict your Mechanic's workshops to only + skilled mechanics so your haulers don't make + low-quality mechanisms. +Laborer 0 10-12 All labors that don't improve quality with skill, + such as Soapmaking and furnace labors. +Marksdwarf 0 10-30 Similar to Hauler. See the description for + Meleedwarf below for more details. +Mason 2 2-4 Masonry and Gem Cutting/Encrusting. In the early + game, you may need to run "`prioritize` + ConstructBuilding" to get your masons to build + wells and bridges if they are too busy crafting + stone furniture. +Meleedwarf 0 20-50 Similar to Hauler, but without most civilian + labors. This profession is separate from Hauler + so you can find your military dwarves easily. + Meleedwarves and Marksdwarves have Mechanics and + hauling labors enabled so you can temporarily + deactivate your military after sieges and allow + your military dwarves to help clean up. +Migrant 0 0 You can assign this profession to new migrants + temporarily while you sort them into professions. + Like Marksdwarf and Meleedwarf, the purpose of + this profession is so you can find your new + dwarves more easily. +Miner 2 2-10 Mining and Engraving. This profession also has + the ``Alchemist`` labor enabled, which disables + hauling for those using the `autohauler` plugin. + Once the need for Miners tapers off in the late + game, dwarves with this profession make good + military dwarves, wielding their picks as + weapons. +Outdoorsdwarf 1 2-4 Carpentry, Bowyery, Woodcutting, Animal Training, + Trapping, Plant Gathering, Beekeeping, and Siege + Engineering. +Smith 0 2-4 Smithing labors. You may want to specialize your + Smiths to focus on a single smithing skill to + maximize equipment quality. +StartManager 1 0 All skills not covered by the other starting + professions (Miner, Mason, Outdoorsdwarf, and + Farmer), plus a few overlapping skills to + assist in critical tasks at the beginning of the + game. Individual labors should be turned off as + migrants are assigned more specialized + professions that cover them, and the StartManager + dwarf can eventually convert to some other + profession. +Tailor 0 2 Textile industry labors: Dying, Leatherworking, + Weaving, and Clothesmaking. +============= ======== ===== ================================================= + +A note on autohauler +~~~~~~~~~~~~~~~~~~~~ + +These profession definitions are designed to work well with or without the +`autohauler` plugin (which helps to keep your dwarves focused on skilled labors +instead of constantly being distracted by hauling). If you do want to use +autohauler, adding the following lines to your ``onMapLoad.init`` file will +configure it to let the professions manage the "Feed water to civilians" and +"Recover wounded" labors instead of enabling those labors for all hauling +dwarves:: + + on-new-fortress enable autohauler + on-new-fortress autohauler FEED_WATER_CIVILIANS allow + on-new-fortress autohauler RECOVER_WOUNDED allow diff --git a/docs/plugins/misery.rst b/docs/plugins/misery.rst new file mode 100644 index 000000000..1c146a10f --- /dev/null +++ b/docs/plugins/misery.rst @@ -0,0 +1,14 @@ +misery +====== +When enabled, fake bad thoughts will be added to all dwarves. + +Usage: + +: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. diff --git a/docs/plugins/mode.rst b/docs/plugins/mode.rst new file mode 100644 index 000000000..9b3fc6984 --- /dev/null +++ b/docs/plugins/mode.rst @@ -0,0 +1,21 @@ +mode +==== +This command lets you see and change the game mode directly. + +.. warning:: + + Only use ``mode`` after making a backup of your save! + + Not all combinations are good for every situation and most of them will + produce undesirable results. There are a few good ones though. + +Examples: + + * 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: + + * 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. diff --git a/docs/plugins/mousequery.rst b/docs/plugins/mousequery.rst new file mode 100644 index 000000000..2f613acaa --- /dev/null +++ b/docs/plugins/mousequery.rst @@ -0,0 +1,16 @@ +mousequery +========== +Adds mouse controls to the DF interface, e.g. click-and-drag designations. + +Options: + +: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. + +Usage:: + + mousequery [plugin] [rbutton] [track] [edge] [live] [enable|disable] diff --git a/docs/plugins/nestboxes.rst b/docs/plugins/nestboxes.rst new file mode 100644 index 000000000..2b633f31b --- /dev/null +++ b/docs/plugins/nestboxes.rst @@ -0,0 +1,5 @@ +nestboxes +========= + +Automatically scan for and forbid fertile eggs incubating in a nestbox. +Toggle status with `enable` or `disable `. diff --git a/docs/plugins/nopause.rst b/docs/plugins/nopause.rst new file mode 100644 index 000000000..c30543187 --- /dev/null +++ b/docs/plugins/nopause.rst @@ -0,0 +1,4 @@ +nopause +======= +Disables pausing (both manual and automatic) with the exception of pause forced +by `reveal` ``hell``. This is nice for digging under rivers. diff --git a/docs/plugins/orders.rst b/docs/plugins/orders.rst new file mode 100644 index 000000000..eb0e8a7ca --- /dev/null +++ b/docs/plugins/orders.rst @@ -0,0 +1,116 @@ +orders +====== + +A plugin for manipulating manager orders. + +Subcommands: + +:list: Shows the list of previously exported orders, including the orders library. +: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. + +You can keep your orders automatically sorted by adding the following command to +your ``onMapLoad.init`` file:: + + repeat -name orders-sort -time 1 -timeUnits days -command [ orders sort ] + + +The orders library +------------------ + +DFHack comes with a library of useful manager orders that are ready for import: + +:source:`basic.json ` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This collection of orders handles basic fort necessities: + +- prepared meals and food products (and by-products like oil) +- booze/mead +- thread/cloth/dye +- pots/jugs/buckets/mugs +- bags of leather, cloth, silk, and yarn +- crafts and totems from otherwise unusable by-products +- mechanisms/cages +- splints/crutches +- lye/soap +- ash/potash +- beds/wheelbarrows/minecarts +- scrolls + +You should import it as soon as you have enough dwarves to perform the tasks. +Right after the first migration wave is usually a good time. + +:source:`furnace.json ` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This collection creates basic items that require heat. It is separated out from +``basic.json`` to give players the opportunity to set up magma furnaces first in +order to save resources. It handles: + +- charcoal (including smelting of bituminous coal and lignite) +- pearlash +- sand +- green/clear/crystal glass +- adamantine processing +- item melting + +Orders are missing for plaster powder until DF :bug:`11803` is fixed. + +:source:`military.json ` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This collection adds high-volume smelting jobs for military-grade metal ores and +produces weapons and armor: + +- leather backpacks/waterskins/cloaks/quivers/armor +- bone/wooden bolts +- smelting for platinum, silver, steel, bronze, bismuth bronze, and copper (and + their dependencies) +- bronze/bismuth bronze/copper bolts +- platinum/silver/steel/iron/bismuth bronze/bronze/copper weapons and armor, + with checks to ensure only the best available materials are being used + +If you set a stockpile to take weapons and armor of less than masterwork quality +and turn on `automelt` (like what `dreamfort` provides on its industry level), +these orders will automatically upgrade your military equipment to masterwork. +Make sure you have a lot of fuel (or magma forges and furnaces) before you turn +``automelt`` on, though! + +This file should only be imported, of course, if you need to equip a military. + +:source:`smelting.json ` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This collection adds smelting jobs for all ores. It includes handling the ores +already managed by ``military.json``, but has lower limits. This ensures all +ores will be covered if a player imports ``smelting`` but not ``military``, but +the higher-volume ``military`` orders will take priority if both are imported. + +:source:`rockstock.json ` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This collection of orders keeps a small stock of all types of rock furniture. +This allows you to do ad-hoc furnishings of guildhalls, libraries, temples, or +other rooms with `buildingplan` and your masons will make sure there is always +stock on hand to fulfill the plans. + +:source:`glassstock.json ` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Similar to ``rockstock`` above, this collection keeps a small stock of all types +of glass furniture. If you have a functioning glass industry, this is more +sustainable than ``rockstock`` since you can never run out of sand. If you have +plenty of rock and just want the variety, you can import both ``rockstock`` and +``glassstock`` to get a mixture of rock and glass furnishings in your fort. + +There are a few items that ``glassstock`` produces that ``rockstock`` does not, +since there are some items that can not be made out of rock, for example: + +- tubes and corkscrews for building magma-safe screw pumps +- windows +- terrariums (as an alternative to wooden cages) diff --git a/docs/plugins/petcapRemover.rst b/docs/plugins/petcapRemover.rst new file mode 100644 index 000000000..65ebaeeab --- /dev/null +++ b/docs/plugins/petcapRemover.rst @@ -0,0 +1,19 @@ +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 diff --git a/docs/plugins/plant.rst b/docs/plugins/plant.rst new file mode 100644 index 000000000..b621b890d --- /dev/null +++ b/docs/plugins/plant.rst @@ -0,0 +1,16 @@ +plant +===== +A tool for creating shrubs, growing, or getting rid of them. + +Subcommands: + +: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. + +For mass effects, use one of the additional options: + +:shrubs: affect all shrubs on the map +:trees: affect all trees on the map +:all: affect every plant! diff --git a/docs/plugins/power-meter.rst b/docs/plugins/power-meter.rst new file mode 100644 index 000000000..163ef91be --- /dev/null +++ b/docs/plugins/power-meter.rst @@ -0,0 +1,6 @@ +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. + +The configuration front-end is implemented by `gui/power-meter`. diff --git a/docs/plugins/probe.rst b/docs/plugins/probe.rst new file mode 100644 index 000000000..1dcc28336 --- /dev/null +++ b/docs/plugins/probe.rst @@ -0,0 +1,13 @@ +probe +===== + +This plugin provides multiple commands that print low-level properties of the +selected objects. + +* ``probe``: prints some properties of the tile selected with :kbd:`k`. Some of + these properties can be passed into `tiletypes`. +* ``cprobe``: prints some properties of the unit selected with :kbd:`v`, as well + as the IDs of any worn items. `gui/gm-unit` and `gui/gm-editor` are more + complete in-game alternatives. +* ``bprobe``: prints some properties of the building selected with :kbd:`q` or + :kbd:`t`. `gui/gm-editor` is a more complete in-game alternative. diff --git a/docs/plugins/prospect.rst b/docs/plugins/prospect.rst new file mode 100644 index 000000000..a8979f1cc --- /dev/null +++ b/docs/plugins/prospect.rst @@ -0,0 +1,51 @@ +prospect +======== + +**Usage:** + + ``prospect [all|hell] []`` + +Shows a summary of resources that exist on the map. By default, only the visible +part of the map is scanned. Include the ``all`` keyword if you want ``prospect`` +to scan the whole map as if it were revealed. Use ``hell`` instead of ``all`` if +you also want to see the Z range of HFS tubes in the 'features' report section. + +**Options:** + +:``-h``, ``--help``: + Shows this help text. +:``-s``, ``--show ``: + Shows only the named comma-separated list of report sections. Report section + names are: summary, liquids, layers, features, ores, gems, veins, shrubs, + and trees. If run during pre-embark, only the layers, ores, gems, and veins + report sections are available. +:``-v``, ``--values``: + Includes material value in the output. Most useful for the 'gems' report + section. + +**Examples:** + +``prospect all`` + Shows the entire report for the entire map. + +``prospect hell --show layers,ores,veins`` + Shows only the layers, ores, and other vein stone report sections, and + includes information on HFS tubes when a fort is loaded. + +``prospect all -sores`` + Show only information about ores for the pre-embark or fortress map report. + +**Pre-embark estimate:** + +If prospect is called during the embark selection screen, it displays an +estimate of layer stone availability. If the ``all`` keyword is specified, it +also estimates ores, gems, and vein material. The estimate covers all tiles of +the embark rectangle. + +.. note:: + + The results of pre-embark prospect are an *estimate*, and can at best be + expected to be somewhere within +/- 30% of the true amount; sometimes it + does a lot worse. Especially, it is not clear how to precisely compute how + many soil layers there will be in a given embark tile, so it can report a + whole extra layer, or omit one that is actually present. diff --git a/docs/plugins/prospector.rst b/docs/plugins/prospector.rst new file mode 100644 index 000000000..a8979f1cc --- /dev/null +++ b/docs/plugins/prospector.rst @@ -0,0 +1,51 @@ +prospect +======== + +**Usage:** + + ``prospect [all|hell] []`` + +Shows a summary of resources that exist on the map. By default, only the visible +part of the map is scanned. Include the ``all`` keyword if you want ``prospect`` +to scan the whole map as if it were revealed. Use ``hell`` instead of ``all`` if +you also want to see the Z range of HFS tubes in the 'features' report section. + +**Options:** + +:``-h``, ``--help``: + Shows this help text. +:``-s``, ``--show ``: + Shows only the named comma-separated list of report sections. Report section + names are: summary, liquids, layers, features, ores, gems, veins, shrubs, + and trees. If run during pre-embark, only the layers, ores, gems, and veins + report sections are available. +:``-v``, ``--values``: + Includes material value in the output. Most useful for the 'gems' report + section. + +**Examples:** + +``prospect all`` + Shows the entire report for the entire map. + +``prospect hell --show layers,ores,veins`` + Shows only the layers, ores, and other vein stone report sections, and + includes information on HFS tubes when a fort is loaded. + +``prospect all -sores`` + Show only information about ores for the pre-embark or fortress map report. + +**Pre-embark estimate:** + +If prospect is called during the embark selection screen, it displays an +estimate of layer stone availability. If the ``all`` keyword is specified, it +also estimates ores, gems, and vein material. The estimate covers all tiles of +the embark rectangle. + +.. note:: + + The results of pre-embark prospect are an *estimate*, and can at best be + expected to be somewhere within +/- 30% of the true amount; sometimes it + does a lot worse. Especially, it is not clear how to precisely compute how + many soil layers there will be in a given embark tile, so it can report a + whole extra layer, or omit one that is actually present. diff --git a/docs/plugins/rb.rst b/docs/plugins/rb.rst new file mode 100644 index 000000000..359d6149b --- /dev/null +++ b/docs/plugins/rb.rst @@ -0,0 +1,4 @@ +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``. diff --git a/docs/plugins/regrass.rst b/docs/plugins/regrass.rst new file mode 100644 index 000000000..f3d00d8e1 --- /dev/null +++ b/docs/plugins/regrass.rst @@ -0,0 +1,3 @@ +regrass +======= +Regrows all the grass. Not much to it ;) diff --git a/docs/plugins/remotefortressreader.rst b/docs/plugins/remotefortressreader.rst new file mode 100644 index 000000000..287debca8 --- /dev/null +++ b/docs/plugins/remotefortressreader.rst @@ -0,0 +1,4 @@ +remotefortressreader +==================== +An in-development plugin for realtime fortress visualisation. +See :forums:`Armok Vision <146473>`. diff --git a/docs/plugins/rename.rst b/docs/plugins/rename.rst new file mode 100644 index 000000000..55534e636 --- /dev/null +++ b/docs/plugins/rename.rst @@ -0,0 +1,19 @@ +rename +====== +Allows renaming various things. Use `gui/rename` for an in-game interface. + +Options: + +``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. diff --git a/docs/plugins/rendermax.rst b/docs/plugins/rendermax.rst new file mode 100644 index 000000000..a173a75db --- /dev/null +++ b/docs/plugins/rendermax.rst @@ -0,0 +1,18 @@ +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. + +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 diff --git a/docs/plugins/restrictice.rst b/docs/plugins/restrictice.rst new file mode 100644 index 000000000..558fb5679 --- /dev/null +++ b/docs/plugins/restrictice.rst @@ -0,0 +1,4 @@ +restrictice +=========== +Restrict traffic on all tiles on top of visible ice. +See also `alltraffic`, `filltraffic`, and `restrictliquids`. diff --git a/docs/plugins/restrictliquids.rst b/docs/plugins/restrictliquids.rst new file mode 100644 index 000000000..4f6cd9550 --- /dev/null +++ b/docs/plugins/restrictliquids.rst @@ -0,0 +1,4 @@ +restrictliquids +=============== +Restrict traffic on all visible tiles with liquid. +See also `alltraffic`, `filltraffic`, and `restrictice`. diff --git a/docs/plugins/resume.rst b/docs/plugins/resume.rst new file mode 100644 index 000000000..ccca39e28 --- /dev/null +++ b/docs/plugins/resume.rst @@ -0,0 +1,4 @@ +resume +====== +Allows automatic resumption of suspended constructions, along with colored +UI hints for construction status. diff --git a/docs/plugins/reveal.rst b/docs/plugins/reveal.rst new file mode 100644 index 000000000..da7be8277 --- /dev/null +++ b/docs/plugins/reveal.rst @@ -0,0 +1,23 @@ +reveal +====== +This reveals the map. By default, HFS will remain hidden so that the demons +don't spawn. You can use ``reveal hell`` to reveal everything. With hell revealed, +you won't be able to unpause until you hide the map again. If you really want +to unpause with hell revealed, use ``reveal demons``. + +Reveal also works in adventure mode, but any of its effects are negated once +you move. When you use it this way, you don't need to run ``unreveal``. + +Usage and related commands: + +:reveal: Reveal the whole map, except for HFS to avoid demons spawning +:reveal hell: Also show hell, but requires ``unreveal`` before unpausing +:reveal demon: Reveals everything and allows unpausing - good luck! +:unreveal: Reverts the effects of ``reveal`` +:revtoggle: Switches between ``reveal`` and ``unreveal`` +:revflood: Hide everything, then reveal tiles with a path to the cursor. + Note that tiles behind constructed walls are also revealed as a + workaround for :bug:`1871`. +:revforget: Discard info about what was visible before revealing the map. + Only useful where (e.g.) you abandoned with the fort revealed + and no longer want the data. diff --git a/docs/plugins/revflood.rst b/docs/plugins/revflood.rst new file mode 100644 index 000000000..da7be8277 --- /dev/null +++ b/docs/plugins/revflood.rst @@ -0,0 +1,23 @@ +reveal +====== +This reveals the map. By default, HFS will remain hidden so that the demons +don't spawn. You can use ``reveal hell`` to reveal everything. With hell revealed, +you won't be able to unpause until you hide the map again. If you really want +to unpause with hell revealed, use ``reveal demons``. + +Reveal also works in adventure mode, but any of its effects are negated once +you move. When you use it this way, you don't need to run ``unreveal``. + +Usage and related commands: + +:reveal: Reveal the whole map, except for HFS to avoid demons spawning +:reveal hell: Also show hell, but requires ``unreveal`` before unpausing +:reveal demon: Reveals everything and allows unpausing - good luck! +:unreveal: Reverts the effects of ``reveal`` +:revtoggle: Switches between ``reveal`` and ``unreveal`` +:revflood: Hide everything, then reveal tiles with a path to the cursor. + Note that tiles behind constructed walls are also revealed as a + workaround for :bug:`1871`. +:revforget: Discard info about what was visible before revealing the map. + Only useful where (e.g.) you abandoned with the fort revealed + and no longer want the data. diff --git a/docs/plugins/revforget.rst b/docs/plugins/revforget.rst new file mode 100644 index 000000000..da7be8277 --- /dev/null +++ b/docs/plugins/revforget.rst @@ -0,0 +1,23 @@ +reveal +====== +This reveals the map. By default, HFS will remain hidden so that the demons +don't spawn. You can use ``reveal hell`` to reveal everything. With hell revealed, +you won't be able to unpause until you hide the map again. If you really want +to unpause with hell revealed, use ``reveal demons``. + +Reveal also works in adventure mode, but any of its effects are negated once +you move. When you use it this way, you don't need to run ``unreveal``. + +Usage and related commands: + +:reveal: Reveal the whole map, except for HFS to avoid demons spawning +:reveal hell: Also show hell, but requires ``unreveal`` before unpausing +:reveal demon: Reveals everything and allows unpausing - good luck! +:unreveal: Reverts the effects of ``reveal`` +:revtoggle: Switches between ``reveal`` and ``unreveal`` +:revflood: Hide everything, then reveal tiles with a path to the cursor. + Note that tiles behind constructed walls are also revealed as a + workaround for :bug:`1871`. +:revforget: Discard info about what was visible before revealing the map. + Only useful where (e.g.) you abandoned with the fort revealed + and no longer want the data. diff --git a/docs/plugins/revtoggle.rst b/docs/plugins/revtoggle.rst new file mode 100644 index 000000000..da7be8277 --- /dev/null +++ b/docs/plugins/revtoggle.rst @@ -0,0 +1,23 @@ +reveal +====== +This reveals the map. By default, HFS will remain hidden so that the demons +don't spawn. You can use ``reveal hell`` to reveal everything. With hell revealed, +you won't be able to unpause until you hide the map again. If you really want +to unpause with hell revealed, use ``reveal demons``. + +Reveal also works in adventure mode, but any of its effects are negated once +you move. When you use it this way, you don't need to run ``unreveal``. + +Usage and related commands: + +:reveal: Reveal the whole map, except for HFS to avoid demons spawning +:reveal hell: Also show hell, but requires ``unreveal`` before unpausing +:reveal demon: Reveals everything and allows unpausing - good luck! +:unreveal: Reverts the effects of ``reveal`` +:revtoggle: Switches between ``reveal`` and ``unreveal`` +:revflood: Hide everything, then reveal tiles with a path to the cursor. + Note that tiles behind constructed walls are also revealed as a + workaround for :bug:`1871`. +:revforget: Discard info about what was visible before revealing the map. + Only useful where (e.g.) you abandoned with the fort revealed + and no longer want the data. diff --git a/docs/plugins/ruby.rst b/docs/plugins/ruby.rst new file mode 100644 index 000000000..359d6149b --- /dev/null +++ b/docs/plugins/ruby.rst @@ -0,0 +1,4 @@ +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``. diff --git a/docs/plugins/search.rst b/docs/plugins/search.rst new file mode 100644 index 000000000..57b9e5df4 --- /dev/null +++ b/docs/plugins/search.rst @@ -0,0 +1,40 @@ + +.. _search-plugin: + +search +====== +The search plugin adds search to the Stocks, Animals, Trading, Stockpile, +Noble (assignment candidates), Military (position candidates), Burrows +(unit list), Rooms, Announcements, Job List and Unit List screens. + +.. image:: ../images/search.png + +Searching works the same way as the search option in :guilabel:`Move to Depot`. +You will see the Search option displayed on screen with a hotkey (usually :kbd:`s`). +Pressing it lets you start typing a query and the relevant list will start +filtering automatically. + +Pressing :kbd:`Enter`, :kbd:`Esc` or the arrow keys will return you to browsing the now +filtered list, which still functions as normal. You can clear the filter +by either going back into search mode and backspacing to delete it, or +pressing the "shifted" version of the search hotkey while browsing the +list (e.g. if the hotkey is :kbd:`s`, then hitting :kbd:`Shift`:kbd:`s` will clear any +filter). + +Leaving any screen automatically clears the filter. + +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. + +In the stockpile screen the option only appears if the cursor is in the +rightmost list: + +.. image:: ../images/search-stockpile.png + +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. diff --git a/docs/plugins/seedwatch.rst b/docs/plugins/seedwatch.rst new file mode 100644 index 000000000..1d5ab9e62 --- /dev/null +++ b/docs/plugins/seedwatch.rst @@ -0,0 +1,27 @@ +seedwatch +========= +Watches the numbers of seeds available and enables/disables seed and plant cooking. + +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. + +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. + +Options: + +: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. + +Examples: + +``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. diff --git a/docs/plugins/showmood.rst b/docs/plugins/showmood.rst new file mode 100644 index 000000000..9276766c4 --- /dev/null +++ b/docs/plugins/showmood.rst @@ -0,0 +1,3 @@ +showmood +======== +Shows all items needed for the currently active strange mood. diff --git a/docs/plugins/siege-engine.rst b/docs/plugins/siege-engine.rst new file mode 100644 index 000000000..0e9511d3d --- /dev/null +++ b/docs/plugins/siege-engine.rst @@ -0,0 +1,12 @@ +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: + +* 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 + +The front-end is implemented by `gui/siege-engine`. diff --git a/docs/plugins/sort-items.rst b/docs/plugins/sort-items.rst new file mode 100644 index 000000000..d18f33c4e --- /dev/null +++ b/docs/plugins/sort-items.rst @@ -0,0 +1,17 @@ +.. _sort: + +sort-items +========== +Sort the visible item list:: + + sort-items order [order...] + +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. + +Item order examples:: + + description material wear type quality + +The orderings are defined in ``hack/lua/plugins/sort/*.lua`` diff --git a/docs/plugins/sort-units.rst b/docs/plugins/sort-units.rst new file mode 100644 index 000000000..1a88381ce --- /dev/null +++ b/docs/plugins/sort-units.rst @@ -0,0 +1,17 @@ +sort-units +========== +Sort the visible unit list:: + + sort-units order [order...] + +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. + +Unit order examples:: + + name age arrival squad squad_position profession + +The orderings are defined in ``hack/lua/plugins/sort/*.lua`` + +:dfhack-keybind:`sort-units` diff --git a/docs/plugins/spectate.rst b/docs/plugins/spectate.rst new file mode 100644 index 000000000..6c2ca9e24 --- /dev/null +++ b/docs/plugins/spectate.rst @@ -0,0 +1,5 @@ +spectate +======== +Simple plugin to automate following random dwarves. Most of the time things will +be weighted towards z-levels with the highest job activity. Simply enter the +``spectate`` command to toggle the plugin's state. diff --git a/docs/plugins/spotclean.rst b/docs/plugins/spotclean.rst new file mode 100644 index 000000000..9ccdd2cc6 --- /dev/null +++ b/docs/plugins/spotclean.rst @@ -0,0 +1,6 @@ +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. + +:dfhack-keybind:`spotclean` diff --git a/docs/plugins/steam-engine.rst b/docs/plugins/steam-engine.rst new file mode 100644 index 000000000..416ac9ad1 --- /dev/null +++ b/docs/plugins/steam-engine.rst @@ -0,0 +1,84 @@ +steam-engine +============ +The steam-engine plugin detects custom workshops with STEAM_ENGINE in +their token, and turns them into real steam engines. + +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. + +Compared to the :wiki:`water reactor ` +exploit, steam engines make a lot of sense! + +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. + +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. + +.. note:: + + 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. + +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. + +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. + +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%. + +Explosions +---------- +The engine must be constructed using barrel, pipe and piston +from fire-safe, or in the magma version magma-safe metals. + +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. + +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. diff --git a/docs/plugins/stockflow.rst b/docs/plugins/stockflow.rst new file mode 100644 index 000000000..c3db7a673 --- /dev/null +++ b/docs/plugins/stockflow.rst @@ -0,0 +1,31 @@ +stockflow +========= +Allows the fortress bookkeeper to queue jobs through the manager, +based on space or items available in stockpiles. + +Inspired by `workflow`. + +Usage: + +``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. + +While enabled, the :kbd:`q` menu of each stockpile will have two new options: + +* :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. + +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. + +In fast mode, new work orders will be enqueued once per day, instead of +waiting for the bookkeeper. diff --git a/docs/plugins/stockpiles.rst b/docs/plugins/stockpiles.rst new file mode 100644 index 000000000..000527ce5 --- /dev/null +++ b/docs/plugins/stockpiles.rst @@ -0,0 +1,28 @@ +.. _stocksettings: + +stockpiles +========== +Offers the following commands to save and load stockpile settings. +See `gui/stockpiles` for an in-game interface. + +: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` + +: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`` + +:loadstock: Loads a saved stockpile settings file and applies it to the currently selected + stockpile. e.g.: ``loadstock food_settings.dfstock`` + +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. + +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. diff --git a/docs/plugins/stocks.rst b/docs/plugins/stocks.rst new file mode 100644 index 000000000..cbfbce978 --- /dev/null +++ b/docs/plugins/stocks.rst @@ -0,0 +1,6 @@ +stocks +====== +Replaces the DF stocks screen with an improved version. + +:dfhack-keybind:`stocks` + diff --git a/docs/plugins/stonesense.rst b/docs/plugins/stonesense.rst new file mode 100644 index 000000000..b6c154e66 --- /dev/null +++ b/docs/plugins/stonesense.rst @@ -0,0 +1,10 @@ +.. _plugin-stonesense: + +stonesense +========== +An isometric visualizer that runs in a second window. Usage: + +:stonesense: Open the visualiser in a new window. Alias ``ssense``. +:ssense overlay: Overlay DF window, replacing the map area. + +For more information, see `the full Stonesense README `. diff --git a/docs/plugins/strangemood.rst b/docs/plugins/strangemood.rst new file mode 100644 index 000000000..0d578c363 --- /dev/null +++ b/docs/plugins/strangemood.rst @@ -0,0 +1,19 @@ +strangemood +=========== +Creates a strange mood job the same way the game itself normally does it. + +Options: + +:-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. diff --git a/docs/plugins/tailor.rst b/docs/plugins/tailor.rst new file mode 100644 index 000000000..ee1567fdb --- /dev/null +++ b/docs/plugins/tailor.rst @@ -0,0 +1,11 @@ +tailor +====== + +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. + +Use the `enable` and `disable ` commands to toggle this plugin's status, or run +``tailor status`` to check its current status. diff --git a/docs/plugins/tiletypes-command.rst b/docs/plugins/tiletypes-command.rst new file mode 100644 index 000000000..0f75c633e --- /dev/null +++ b/docs/plugins/tiletypes-command.rst @@ -0,0 +1,10 @@ +tiletypes-command +----------------- +Runs tiletypes commands, separated by ``;``. This makes it possible to change +tiletypes modes from a hotkey or via dfhack-run. + +Example:: + + tiletypes-command p any ; p s wall ; p sp normal + +This resets the paint filter to unsmoothed walls. diff --git a/docs/plugins/tiletypes-here-point.rst b/docs/plugins/tiletypes-here-point.rst new file mode 100644 index 000000000..8951bdff8 --- /dev/null +++ b/docs/plugins/tiletypes-here-point.rst @@ -0,0 +1,6 @@ +tiletypes-here-point +-------------------- +Apply the current tiletypes options at the in-game cursor position to a single +tile. Can be used from a hotkey. + +This command supports the same options as `tiletypes-here` above. diff --git a/docs/plugins/tiletypes-here.rst b/docs/plugins/tiletypes-here.rst new file mode 100644 index 000000000..fe9ceefd9 --- /dev/null +++ b/docs/plugins/tiletypes-here.rst @@ -0,0 +1,14 @@ +tiletypes-here +-------------- +Apply the current tiletypes options at the in-game cursor position, including +the brush. Can be used from a hotkey. + +Options: + +:``-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. diff --git a/docs/plugins/tiletypes.rst b/docs/plugins/tiletypes.rst new file mode 100644 index 000000000..41f780521 --- /dev/null +++ b/docs/plugins/tiletypes.rst @@ -0,0 +1,82 @@ +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 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. + +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. + +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:: + + filter material STONE + filter shape FORTIFICATION + paint shape FLOOR + +Or turn mineral vein floors back into walls:: + + filter shape FLOOR + filter material MINERAL + paint shape WALL + +The tool also allows tweaking some tile flags:: + + paint hidden 1 + paint hidden 0 + +This will hide previously revealed tiles (or show hidden with the 0 option). + +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:: + + paint stone MICROCLINE + +This mode is incompatible with the regular ``material`` setting, so changing +it cancels the specific stone selection:: + + paint material ANY + +Since different vein types have different drop rates, it is possible to choose +which one to use in painting:: + + paint veintype CLUSTER_SMALL + +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. + +Any paint or filter option (or the entire paint or filter) can be disabled entirely by using the ANY keyword:: + + paint hidden ANY + paint shape ANY + filter material any + filter shape any + filter any + +You can use several different brushes for painting tiles: + +: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 + +Example:: + + range 10 10 1 + +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. + +For more details, use ``tiletypes help``. diff --git a/docs/plugins/title-folder.rst b/docs/plugins/title-folder.rst new file mode 100644 index 000000000..4e1ef40ec --- /dev/null +++ b/docs/plugins/title-folder.rst @@ -0,0 +1,3 @@ +title-folder +============= +Displays the DF folder name in the window title bar when enabled. diff --git a/docs/plugins/title-version.rst b/docs/plugins/title-version.rst new file mode 100644 index 000000000..aed7a02e0 --- /dev/null +++ b/docs/plugins/title-version.rst @@ -0,0 +1,3 @@ +title-version +============= +Displays the DFHack version on DF's title screen when enabled. diff --git a/docs/plugins/trackstop.rst b/docs/plugins/trackstop.rst new file mode 100644 index 000000000..b012df34d --- /dev/null +++ b/docs/plugins/trackstop.rst @@ -0,0 +1,5 @@ +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. diff --git a/docs/plugins/tubefill.rst b/docs/plugins/tubefill.rst new file mode 100644 index 000000000..99c0b76bd --- /dev/null +++ b/docs/plugins/tubefill.rst @@ -0,0 +1,11 @@ +tubefill +======== +Fills all the adamantine veins again. Veins that were hollow will be left +alone. + +Options: + +:hollow: fill in naturally hollow veins too + +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. diff --git a/docs/plugins/tweak.rst b/docs/plugins/tweak.rst new file mode 100644 index 000000000..4ce7b6d38 --- /dev/null +++ b/docs/plugins/tweak.rst @@ -0,0 +1,91 @@ +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 +:partial-items: Displays percentages on partially-consumed items such as hospital cloth +: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 diff --git a/docs/plugins/unreveal.rst b/docs/plugins/unreveal.rst new file mode 100644 index 000000000..da7be8277 --- /dev/null +++ b/docs/plugins/unreveal.rst @@ -0,0 +1,23 @@ +reveal +====== +This reveals the map. By default, HFS will remain hidden so that the demons +don't spawn. You can use ``reveal hell`` to reveal everything. With hell revealed, +you won't be able to unpause until you hide the map again. If you really want +to unpause with hell revealed, use ``reveal demons``. + +Reveal also works in adventure mode, but any of its effects are negated once +you move. When you use it this way, you don't need to run ``unreveal``. + +Usage and related commands: + +:reveal: Reveal the whole map, except for HFS to avoid demons spawning +:reveal hell: Also show hell, but requires ``unreveal`` before unpausing +:reveal demon: Reveals everything and allows unpausing - good luck! +:unreveal: Reverts the effects of ``reveal`` +:revtoggle: Switches between ``reveal`` and ``unreveal`` +:revflood: Hide everything, then reveal tiles with a path to the cursor. + Note that tiles behind constructed walls are also revealed as a + workaround for :bug:`1871`. +:revforget: Discard info about what was visible before revealing the map. + Only useful where (e.g.) you abandoned with the fort revealed + and no longer want the data. diff --git a/docs/plugins/workNow.rst b/docs/plugins/workNow.rst new file mode 100644 index 000000000..bacecf612 --- /dev/null +++ b/docs/plugins/workNow.rst @@ -0,0 +1,12 @@ +workNow +======= +Don't allow dwarves to idle if any jobs are available. + +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: + +: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 diff --git a/docs/plugins/workflow.rst b/docs/plugins/workflow.rst new file mode 100644 index 000000000..17db57e69 --- /dev/null +++ b/docs/plugins/workflow.rst @@ -0,0 +1,113 @@ +workflow +======== +Manage control of repeat jobs. `gui/workflow` provides a simple +front-end integrated in the game UI. + +Usage: + +``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: + + - 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. + +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. + +Constraint format +----------------- +The constraint spec consists of 4 parts, separated with ``/`` characters:: + + ITEM[:SUBTYPE]/[GENERIC_MAT,...]/[SPECIFIC_MAT:...]/[LOCAL,] + +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 subsequent parts are optional: + +- A generic material spec constrains the item material to one of + the hard-coded generic classes, which currently include:: + + 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. + +- A comma-separated list of miscellaneous flags, which currently can + be used to ignore imported items or items below a certain quality. + +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 + +Keep the number of prepared food & drink stacks between 90 and 120:: + + workflow count FOOD 120 30 + workflow count DRINK 120 30 + +Make sure there are always 25-30 empty bins/barrels/bags:: + + workflow count BIN 30 + workflow count BARREL 30 + workflow count BOX/CLOTH,SILK,YARN 30 + +Make sure there are always 15-20 coal and 25-30 copper bars:: + + workflow count BAR//COAL 20 + workflow count BAR//COPPER 30 + +Produce 15-20 gold crafts:: + + workflow count CRAFTS//GOLD 20 + +Collect 15-20 sand bags and clay boulders:: + + workflow count POWDER_MISC/SAND 20 + workflow count BOULDER/CLAY 20 + +Make sure there are always 80-100 units of dimple dye:: + + workflow amount POWDER_MISC//MUSHROOM_CUP_DIMPLE:MILL 100 20 + +.. note:: + + 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. + +Maintain 10-100 locally-made crafts of exceptional quality:: + + workflow count CRAFTS///LOCAL,EXCEPTIONAL 100 90 diff --git a/docs/plugins/zone.rst b/docs/plugins/zone.rst new file mode 100644 index 000000000..a3112c147 --- /dev/null +++ b/docs/plugins/zone.rst @@ -0,0 +1,130 @@ +zone +==== +Helps a bit with managing activity zones (pens, pastures and pits) and cages. + +:dfhack-keybind:`zone` + +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. + +Filters: + +: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. + +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. + +Usage with filters +------------------ +All filters can be used together with the 'assign' command. + +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. + +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). + +Most filters can be negated (e.g. 'not grazer' -> race is not a grazer). + +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. + +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.