From 5c9be942a501c9aedb8bd49bc60cba26b49aa468 Mon Sep 17 00:00:00 2001 From: myk002 Date: Wed, 3 Aug 2022 23:40:35 -0700 Subject: [PATCH] update docs for workflow --- docs/plugins/workflow.rst | 153 +++++++++++++++++++++----------------- plugins/workflow.cpp | 81 ++------------------ 2 files changed, 91 insertions(+), 143 deletions(-) diff --git a/docs/plugins/workflow.rst b/docs/plugins/workflow.rst index f6b8c4475..cb20ad806 100644 --- a/docs/plugins/workflow.rst +++ b/docs/plugins/workflow.rst @@ -1,73 +1,69 @@ workflow ======== -Manage control of repeat jobs. `gui/workflow` provides a simple +Tags: +:dfhack-keybind:`workflow` +:dfhack-keybind:`fix-job-postings` + +Manage repeat jobs according to stock levels. `gui/workflow` provides a simple front-end integrated in the game UI. -Usage: +When the plugin is enabled, it protects all repeat jobs from removal. If they do +disappear due to any cause (raw materials not available, manual removal by the +player, etc.), they are immediately re-added to their workshop and suspended. + +If 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. -``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: +There is a good amount of overlap between this plugin and the vanilla manager +workorders, and both systems have their advantages. Vanilla manager workorders +can be more expressive about when to enqueue jobs. For example, you can gate the +activation of a vanilla workorder based on availability of raw materials, which +you cannot do in ``workflow``. However, ``workflow`` is often more convenient +for quickly keeping a small stock of various items on hand without having to +configure all the vanilla manager options. Also see the `orders` plugin for +a library of manager orders that may make managing your stocks even more +convenient than ``workflow`` can. - - drybuckets: Automatically empty abandoned water buckets. - - auto-melt: Resume melt jobs when there are objects to melt. +Usage: + +``enable workflow`` + Start monitoring for and managing workshop jobs that are set to repeat. +``workflow enable|disable drybuckets`` + Enables/disables automatic emptying of abandoned water buckets. +``workflow enable|disable auto-melt`` + Enables/disables automatic resumption of repeat melt jobs when there are + objects to melt. +``workflow count [gap]`` + Set a constraint, counting every stack as 1 item. If a gap is specified, + stocks are allowed to dip that many items below the target before relevant + jobs are resumed. +``workflow amount [gap]`` + Set a constraint, counting all items within stacks. If a gap is specified, + stocks are allowed to dip that many items below the target before relevant + jobs are resumed. +``workflow unlimit `` + Delete a constraint. +``workflow unlimit-all`` + Delete all constraints. ``workflow jobs`` - List workflow-controlled jobs (if in a workshop, filtered by it). + List workflow-controlled jobs (if in a workshop, filtered by it). ``workflow list`` - List active constraints, and their job counts. + 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 + 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. +``fix-job-postings [dry-run]`` + Fixes crashes caused the version of workflow released with DFHack + 0.40.24-r4. It will be run automatically if needed. If your save has never + been run with this version, you will never need this command. Specify the + ``dry-run`` keyword to see what this command would do without making any + changes to game state. + +Examples -------- -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 @@ -104,16 +100,39 @@ Make sure there are always 80-100 units of dimple dye:: .. 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. + 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 -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). +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 (``LOCAL``) or items below a certain quality (1-5, with + 5 being masterwork). diff --git a/plugins/workflow.cpp b/plugins/workflow.cpp index 600a8bef1..83f312bfd 100644 --- a/plugins/workflow.cpp +++ b/plugins/workflow.cpp @@ -73,84 +73,13 @@ DFhackCExport command_result plugin_init (color_ostream &out, std::vector [cnt-gap]\n" - " workflow amount [cnt-gap]\n" - " Set a constraint. The first form counts each stack as only 1 item.\n" - " workflow unlimit \n" - " Delete a constraint.\n" - " workflow unlimit-all\n" - " Delete all constraints.\n" - "Function:\n" - " - When the plugin is enabled, it protects all repeat jobs from removal.\n" - " If they do disappear due to any cause, they are immediately re-added\n" - " to their workshop and suspended.\n" - " - In addition, when any constraints on item amounts are set, repeat jobs\n" - " that produce that kind of item are automatically suspended and resumed\n" - " as the item amount goes above or below the limit. The gap specifies how\n" - " much below the limit the amount has to drop before jobs are resumed;\n" - " this is intended to reduce the frequency of jobs being toggled.\n" - "Constraint format:\n" - " The contstraint spec consists of 4 parts, separated with '/' characters:\n" - " ITEM[:SUBTYPE]/[GENERIC_MAT,...]/[SPECIFIC_MAT:...]/[LOCAL,]\n" - " The first part is mandatory and specifies the item type and subtype,\n" - " using the raw tokens for items, in the same syntax you would e.g. use\n" - " for a custom reaction input. The subsequent parts are optional:\n" - " - A generic material spec constrains the item material to one of\n" - " the hard-coded generic classes, like WOOD, METAL, YARN or MILK.\n" - " - A specific material spec chooses the material exactly, using the\n" - " raw syntax for reaction input materials, e.g. INORGANIC:IRON,\n" - " although for convenience it also allows just IRON, or ACACIA:WOOD.\n" - " - A comma-separated list of miscellaneous flags, which currently can\n" - " be used to ignore imported items or items below a certain quality.\n" - "Constraint examples:\n" - " workflow amount AMMO:ITEM_AMMO_BOLTS/METAL 1000 100\n" - " workflow amount AMMO:ITEM_AMMO_BOLTS/WOOD,BONE 200 50\n" - " Keep metal bolts within 900-1000, and wood/bone within 150-200.\n" - " workflow count FOOD 120 30\n" - " workflow count DRINK 120 30\n" - " Keep the number of prepared food & drink stacks between 90 and 120\n" - " workflow count BIN 30\n" - " workflow count BARREL 30\n" - " workflow count BOX/CLOTH,SILK,YARN 30\n" - " Make sure there are always 25-30 empty bins/barrels/bags.\n" - " workflow count BAR//COAL 20\n" - " workflow count BAR//COPPER 30\n" - " Make sure there are always 15-20 coal and 25-30 copper bars.\n" - " workflow count CRAFTS//GOLD 20\n" - " Produce 15-20 gold crafts.\n" - " workflow count POWDER_MISC/SAND 20\n" - " workflow count BOULDER/CLAY 20\n" - " Collect 15-20 sand bags and clay boulders.\n" - " workflow amount POWDER_MISC//MUSHROOM_CUP_DIMPLE:MILL 100 20\n" - " Make sure there are always 80-100 units of dimple dye.\n" - " In order for this to work, you have to set the material of\n" - " the PLANT input on the Mill Plants job to MUSHROOM_CUP_DIMPLE\n" - " using the 'job item-material' command.\n" - " workflow count CRAFTS///LOCAL,EXCEPTIONAL 100 90\n" - " Maintain 10-100 locally-made crafts of exceptional quality.\n" - ) - ); + "workflow", + "Manage repeat jobs according to stock levels.", + workflow_cmd)); commands.push_back(PluginCommand( "fix-job-postings", - "Fix broken job postings caused by certain versions of workflow", - fix_job_postings_cmd, false, - "fix-job-postings: Fix job postings\n" - "fix-job-postings dry|[any argument]: Dry run only (avoid making changes)\n" - )); + "Fix broken job postings caused by very old versions of workflow.", + fix_job_postings_cmd)); } init_state(out);