MetzNet
/
dfhack
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

update docs for labormanager

develop
myk002 2022-07-27 17:14:18 -07:00
parent 58c0f94a2d
commit e94f1891c2
No known key found for this signature in database
GPG Key ID: 8A39CA0FA0C16E78
2 changed files with 122 additions and 129 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

216
docs/plugins/labormanager.rst
Unescape Escape View File

@ -1,105 +1,127 @@
labormanager labormanager
============ ============
Automatically manage dwarf labors to efficiently complete jobs. Tags:
Labormanager is derived from autolabor (above) but uses a completely :dfhack-keybind:`labormanager`
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 Automatically manage dwarf labors. Labormanager is derived from `autolabor`
dwarfs, and the map to determine how many dwarves need to be assigned to but uses a completely different approach to assigning jobs to dwarves. While
what labors in order to meet all current labor needs without starving autolabor tries to keep as many dwarves busy as possible, labormanager instead
any particular type of job. strives to get jobs done as quickly as possible.
Labormanager frequently scans the current job list, current list of dwarves, 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.
Dwarves on active military duty or dwarves assigned to burrows are left
untouched.
.. warning:: .. warning::
*As with autolabor, labormanager will override any manual changes you As with autolabor, labormanager will override any manual changes you make to
make to labors while it is enabled, including through other tools such labors while it is enabled, including through other tools such as Dwarf
as Dwarf Therapist* Therapist. Do not run both autolabor and labormanager at the same time!
Simple usage: Usage::
:enable labormanager: Enables the plugin with default settings. enable labormanager
(Persistent per fortress)
Anything beyond this is optional - labormanager works well with the default
:disable labormanager: Disables the plugin. 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.
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
The default priorities for each labor vary (some labors are higher many jobs of each labor is needed, it then sorts them by adjusted priority.
priority by default than others). The way the plugin works is that, once (Labors other than hauling have a bias added to them based on how long it's been
it determines how many of each labor is needed, it then sorts them by since they were last used to prevent job starvation.) The labor with the highest
adjusted priority. (Labors other than hauling have a bias added to them priority is selected, the "best fit" dwarf for that labor is assigned to that
based on how long it's been since they were last used, to prevent job labor, and then its priority is *halved*. This process is repeated until either
starvation.) The labor with the highest priority is selected, the "best dwarves or labors run out.
fit" dwarf for that labor is assigned to that labor, and then its
priority is *halved*. This process is repeated until either dwarfs or Because there is no easy way to detect how many haulers are actually needed at
labors run out. 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
Because there is no easy way to detect how many haulers are actually dwarf is always assigned to construction removing and cleaning because these
needed at any moment, the plugin always ensures that at least one dwarf jobs also cannot be easily detected. Lever pulling is always assigned to
is assigned to each of the hauling labors, even if no hauling jobs are everyone. Any dwarves for which there are no jobs will be assigned hauling,
detected. At least one dwarf is always assigned to construction removing lever pulling, and cleaning labors. If you use animal trainers, note that
and cleaning because these jobs also cannot be easily detected. Lever labormanager will misbehave if you assign specific trainers to specific animals;
pulling is always assigned to everyone. Any dwarfs for which there are results are only guaranteed if you use "any trainer".
no jobs will be assigned hauling, lever pulling, and cleaning labors. If
you use animal trainers, note that labormanager will misbehave if you Labormanager also sometimes assigns extra labors to currently busy dwarfs so
assign specific trainers to specific animals; results are only guaranteed that when they finish their current job, they will go off and do something
if you use "any trainer", and animal trainers will probably be useful instead of standing around waiting for a job.
overallocated in any case.
There is special handling to ensure that at least one dwarf is assigned to haul
Labormanager also sometimes assigns extra labors to currently busy food whenever food is detected left in a place where it will rot if not stored.
dwarfs so that when they finish their current job, they will go off and This will cause a dwarf to go idle if you have no stockpiles to haul food to.
do something useful instead of standing around waiting for a job.
Dwarves who are unable to work (child, in the military, wounded, handless,
There is special handling to ensure that at least one dwarf is assigned asleep, in a meeting) are entirely excluded from labor assignment. Any dwarf
to haul food whenever food is detected left in a place where it will rot explicitly assigned to a burrow will also be completely ignored by labormanager.
if not stored. This will cause a dwarf to go idle if you have no
storepiles to haul food to. The fitness algorithm for assigning jobs to dwarves generally attempts to favor
dwarves who are more skilled over those who are less skilled. It also tries to
Dwarfs who are unable to work (child, in the military, wounded, avoid assigning female dwarfs with children to jobs that are "outside", favors
handless, asleep, in a meeting) are entirely excluded from labor assigning "outside" jobs to dwarfs who are carrying a tool that could be used as
assignment. Any dwarf explicitly assigned to a burrow will also be a weapon, and tries to minimize how often dwarves have to reequip.
completely ignored by labormanager.
Labormanager automatically determines medical needs and reserves health care
The fitness algorithm for assigning jobs to dwarfs generally attempts to providers as needed. Note that this may cause idling if you have injured dwarves
favor dwarfs who are more skilled over those who are less skilled. It but no or inadequate hospital facilities.
also tries to avoid assigning female dwarfs with children to jobs that
are "outside", favors assigning "outside" jobs to dwarfs who are Hunting is never assigned without a butchery, and fishing is never assigned
carrying a tool that could be used as a weapon, and tries to minimize without a fishery, and neither of these labors is assigned unless specifically
how often dwarfs have to reequip. enabled (see below).
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 The method by which labormanager determines what labor is needed for a
particular job is complicated and, in places, incomplete. In some particular job is complicated and, in places, incomplete. In some situations,
situations, labormanager will detect that it cannot determine what labor labormanager will detect that it cannot determine what labor is required. It
is required. It will, by default, pause and print an error message on will, by default, pause and print an error message on the dfhack console,
the dfhack console, followed by the message "LABORMANAGER: Game paused followed by the message "LABORMANAGER: Game paused so you can investigate the
so you can investigate the above message.". If this happens, please open above message.". If this happens, please open an :issue:`<issue>` on GitHub,
an issue on github, reporting the lines that immediately preceded this reporting the lines that immediately preceded this message. You can tell
message. You can tell labormanager to ignore this error and carry on by labormanager to ignore this error and carry on by running
typing ``labormanager pause-on-error no``, but be warned that some job may go ``labormanager pause-on-error no``, but be warned that some job may go undone in
undone in this situation. this situation.
Advanced usage: Examples
--------
:labormanager enable: Turn plugin on.
:labormanager disable: Turn plugin off. ``labormanager priority BREWER 500``
:labormanager priority <labor> <value>: Set the priority value (see above) for labor <labor> to <value>. Boost the priority of brewing jobs.
:labormanager reset <labor>: Reset the priority value of labor <labor> to its default. ``labormanager max FISH 1``
:labormanager reset-all: Reset all priority values to their defaults. Only assign fishing to one dwarf at a time. Note that you also have to run
:labormanager allow-fishing: Allow dwarfs to fish. *Warning* This tends to result in most of the fort going fishing. ``labormanager allow-fishing`` for any dwarves to be assigned fishing at
:labormanager forbid-fishing: Forbid dwarfs from fishing. Default behavior. all.
: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. Advanced usage
: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. ``labormanager list``
Show current priorities and current allocation stats. Use this command to
see the IDs for all labors.
``labormanager status``
Show basic status information.
``labormanager priority <labor> <value>``
Set the priority value for labor <labor> to <value>.
``labormanager max <labor> <value>``
Set maximum number of dwarves that can be assigned to a labor.
``labormanager max <labor> none``
Unrestrict the number of dwarves that can be assigned to a labor.
``labormanager max <labor> disable``
Don't manage the specified labor. Dwarves who you have manually enabled this
labor on will be less likely to have managed labors assigned to them.
``labormanager reset-all|reset <labor>``
Return a labor (or all labors) to the default priority.
``labormanager allow-fishing|forbid-fishing``
Allow/disallow fisherdwarves. *Warning* Allowing fishing tends to result in
most of the fort going fishing. Fishing is forbidden by default.
``labormanager allow-hunting|forbid-hunting``
Allow/disallow hunterdwarves. *Warning* Allowing hunting tends to result in
as many dwarves going hunting as you have crossbows. Hunting is forbidden by
default.
``labormanager pause-on-error yes|no``
Make labormanager pause/continue if the labor inference engine fails. See
the above section for details.

35
plugins/labormanager/labormanager.cpp
Unescape Escape View File

@ -845,38 +845,9 @@ DFhackCExport command_result plugin_init(color_ostream &out, std::vector <Plugin
// Fill the command list with your commands. // Fill the command list with your commands.
commands.push_back(PluginCommand( commands.push_back(PluginCommand(
"labormanager", "Automatically manage dwarf labors.", "labormanager",
labormanager, 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: labormanager));
" labormanager enable\n"
" labormanager disable\n"
" Enables or disables the plugin.\n"
" labormanager max <labor> <maximum>\n"
" Set max number of dwarves assigned to a labor.\n"
" labormanager max <labor> unmanaged\n"
" labormanager max <labor> disable\n"
" Don't attempt to manage this labor.\n"
" Any dwarves with unmanaged labors assigned will be less\n"
" likely to have managed labors assigned to them.\n"
" labormanager max <labor> none\n"
" Unrestrict the number of dwarves assigned to a labor.\n"
" labormanager priority <labor> <priority>\n"
" Change the assignment priority of a labor (default is 100)\n"
" labormanager reset <labor>\n"
" Return a labor to the default handling.\n"
" labormanager reset-all\n"
" Return all labors to the default handling.\n"
" labormanager list\n"
" List current status of all labors.\n"
" labormanager status\n"
" Show basic status information.\n"
"Function:\n"
" When enabled, labormanager periodically checks your dwarves and enables or\n"
" disables labors. Generally, each dwarf will be assigned exactly one labor.\n"
" Warning: labormanager will override any manual changes you make to labors\n"
" while it is enabled, except where the labor is marked as unmanaged.\n"
" Do not try to run both autolabor and labormanager at the same time.\n"
));
generate_labor_to_skill_map(); generate_labor_to_skill_map();