update docs for autolabor

develop
myk002 2022-07-18 14:53:06 -07:00
parent 6c760d1a3d
commit 87e67ea8b3
No known key found for this signature in database
GPG Key ID: 8A39CA0FA0C16E78
3 changed files with 61 additions and 87 deletions

@ -21,7 +21,8 @@ can be changed by the user.
Usage: Usage:
- ``enable autohauler`` - ``enable autohauler``
Start managing hauling labors. Start managing hauling labors. This is normally all you need to do.
Autohauler works well on default settings.
- ``autohauler status`` - ``autohauler status``
Show autohauler status and status of fort dwarves. Show autohauler status and status of fort dwarves.
- ``autohauler <labor> haulers`` - ``autohauler <labor> haulers``

@ -1,70 +1,82 @@
autolabor autolabor
========= =========
Automatically manage dwarf labors to efficiently complete jobs.
Autolabor tries to keep as many dwarves as possible busy but
also tries to have dwarves specialize in specific skills.
The key is that, for almost all labors, once a dwarf begins a job it will finish that Automatically manage dwarf labors. Autolabor attempts to keep as many dwarves as
job even if the associated labor is removed. Autolabor therefore frequently checks possible busy while allowing dwarves to specialize in specific skills.
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 Autolabor frequently checks how many jobs of each type are available and sets
if labors change mid-job, are handled slightly differently to minimise churn. labors proportionally in order to get them all done quickly. Labors with
equipment -- mining, hunting, and woodcutting -- which are abandoned if labors
change mid-job, are handled slightly differently to minimise churn.
Dwarves on active military duty or dwarves assigned to burrows are left
untouched by autolabor.
.. warning:: .. warning::
*autolabor will override any manual changes you make to labors while autolabor will override any manual changes you make to labors while it is
it is enabled, including through other tools such as Dwarf Therapist* enabled, including through other tools such as Dwarf Therapist.
Simple usage: Usage::
:enable autolabor: Enables the plugin with default settings. (Persistent per fortress) enable autolabor
:disable autolabor: Disables the plugin.
Anything beyond this is optional - autolabor works well on the default settings. Anything beyond this is optional - autolabor works well with the default
settings. Once you have enabled it in a fortress, it stays enabled until you
explicitly disable it, even if you save and reload your game.
By default, each labor is assigned to between 1 and 200 dwarves (2-200 for mining). By default, each labor is assigned to between 1 and 200 dwarves (2-200 for
By default 33% of the workforce become haulers, who handle all hauling jobs as well mining). 33% of the workforce become haulers, who handle all hauling jobs as
as cleaning, pulling levers, recovering wounded, removing constructions, and filling ponds. well as cleaning, pulling levers, recovering wounded, removing constructions,
Other jobs are automatically assigned as described above. Each of these settings can be adjusted. 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, Jobs are rarely assigned to nobles with responsibilities for meeting diplomats
never to the chief medical dwarf, and less often to the bookeeper and manager. 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. 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 For each labor, a preference order is calculated based on skill, biased against
trades and excluding those who can't do the job. The labor is then added to the best <minimum> masters of other trades and excluding those who can't do the job. The labor is
dwarves for that labor. We assign at least the minimum number of dwarfs, in order of preference, then added to the best <minimum> dwarves for that labor, then to additional
and then assign additional dwarfs that meet any of these conditions: dwarfs that meet any of these conditions:
* The dwarf is idle and there are no idle dwarves assigned to this labor * 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 dwarf has non-zero skill associated with the labor
* The labor is mining, hunting, or woodcutting and the dwarf currently has it enabled. * The labor is mining, hunting, or woodcutting and the dwarf currently has it enabled.
We stop assigning dwarfs when we reach the maximum allowed. We stop assigning dwarves when we reach the maximum allowed.
Advanced usage: Advanced usage:
:autolabor <labor> <minimum> [<maximum>]: - ``autolabor <labor> <minimum> [<maximum>] [<talent pool>]``
Set number of dwarves assigned to a labor. Set range of dwarves assigned to a labor, optionally specifying the size of
:autolabor <labor> haulers: Set a labor to be handled by hauler dwarves. the pool of most skilled dwarves that will ever be considered for this
:autolabor <labor> disable: Turn off autolabor for a specific labor. labor.
:autolabor <labor> reset: Return a labor to the default handling. - ``autolabor <labor> haulers``
:autolabor reset-all: Return all labors to the default handling. Set a labor to be handled by hauler dwarves.
:autolabor list: List current status of all labors. - ``autolabor <labor> disable``
:autolabor status: Show basic status information. Turn off autolabor for a specific labor.
- ``autolabor reset-all|<labor> reset``
Return a labor (or 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. See `autolabor-artisans` for a differently-tuned setup.
Examples: Examples:
``autolabor MINE`` - ``autolabor MINE 5``
Keep at least 5 dwarves with mining enabled. Keep at least 5 dwarves with mining enabled.
``autolabor CUT_GEM 1 1`` - ``autolabor CUT_GEM 1 1``
Keep exactly 1 dwarf with gemcutting enabled. Keep exactly 1 dwarf with gemcutting enabled.
``autolabor COOK 1 1 3`` - ``autolabor COOK 1 1 3``
Keep 1 dwarf with cooking enabled, selected only from the top 3. Keep 1 dwarf with cooking enabled, selected only from the top 3.
``autolabor FEED_WATER_CIVILIANS haulers`` - ``autolabor FEED_WATER_CIVILIANS haulers``
Have haulers feed and water wounded dwarves. Have haulers feed and water wounded dwarves.
``autolabor CUTWOOD disable`` - ``autolabor CUTWOOD disable``
Turn off autolabor for wood cutting. Turn off autolabor for wood cutting.

@ -686,48 +686,9 @@ DFhackCExport command_result plugin_init ( color_ostream &out, std::vector <Plug
// Fill the command list with your commands. // Fill the command list with your commands.
commands.push_back(PluginCommand( commands.push_back(PluginCommand(
"autolabor", "Automatically manage dwarf labors.", "autolabor",
autolabor, false, /* true means that the command can't be used from non-interactive user interface */ "Automatically manage dwarf labors.",
// Extended help string. Used by CR_WRONG_USAGE and the help command: autolabor));
" autolabor enable\n"
" autolabor disable\n"
" Enables or disables the plugin.\n"
" autolabor <labor> <minimum> [<maximum>] [<talent pool>]\n"
" Set number of dwarves assigned to a labor.\n"
" autolabor <labor> haulers\n"
" Set a labor to be handled by hauler dwarves.\n"
" autolabor <labor> disable\n"
" Turn off autolabor for a specific labor.\n"
" autolabor <labor> reset\n"
" Return a labor to the default handling.\n"
" autolabor reset-all\n"
" Return all labors to the default handling.\n"
" autolabor list\n"
" List current status of all labors.\n"
" autolabor status\n"
" Show basic status information.\n"
"Function:\n"
" When enabled, autolabor periodically checks your dwarves and enables or\n"
" disables labors. It tries to keep as many dwarves as possible busy but\n"
" also tries to have dwarves specialize in specific skills.\n"
" Warning: autolabor will override any manual changes you make to labors\n"
" while it is enabled.\n"
" To prevent particular dwarves from being managed by autolabor, put them\n"
" in any burrow.\n"
" To restrict the assignment of a labor to only the top <n> most skilled\n"
" dwarves, add a talent pool number <n>.\n"
"Examples:\n"
" autolabor MINE 2\n"
" Keep at least 2 dwarves with mining enabled.\n"
" autolabor CUT_GEM 1 1\n"
" Keep exactly 1 dwarf with gemcutting enabled.\n"
" autolabor COOK 1 1 3\n"
" Keep 1 dwarf with cooking enabled, selected only from the top 3.\n"
" autolabor FEED_WATER_CIVILIANS haulers\n"
" Have haulers feed and water wounded dwarves.\n"
" autolabor CUTWOOD disable\n"
" Turn off autolabor for wood cutting.\n"
));
init_state(); init_state();