Make the manager orders library available by default (#2233)

* move orders out of examples directory

* install orders into library dir

* read orders from new library dir

* update documentation

* update dreamfort references to orders import

* update changelog

* ignore json files in pre-commit

.pre-commit-config.yaml

@@ -41,4 +41,4 @@ repos:
       entry: python3 ci/authors-rst.py
       files: docs/Authors\.rst
       pass_filenames: false
-exclude: '^(depends/|data/examples/.*\.json$|.*\.diff$)'
+exclude: '^(depends/|data/.*\.json$|.*\.diff$)'

data/CMakeLists.txt

@@ -1,6 +1,9 @@
 install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/quickfort/
         DESTINATION "${DFHACK_DATA_DESTINATION}/data/quickfort")
 
+install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/orders/
+        DESTINATION dfhack-config/orders/library)
+
 install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/examples/
         DESTINATION "${DFHACK_DATA_DESTINATION}/examples")
 

data/blueprints/library/dreamfort.csv

@@ -31,7 +31,7 @@
 "Other DFHack commands also work very well with Dreamfort, such as autofarm, autonestbox, prioritize, seedwatch, tailor, and, of course, buildingplan. An init file that gets everything configured for you is distributed with DFHack as hack/examples/init/onMapLoad_dreamfort.init."
 Put that file in your Dwarf Fortress directory -- the same directory that has dfhack.init.
 ""
-"Also copy the files in hack/examples/orders/ to dfhack-config/orders/ and the files in hack/examples/professions/ to professions/. We'll be using these files later. See https://docs.dfhack.org/en/stable/docs/guides/examples-guide.html for more information, including suggestions on how many dwarves of each profession you are likely to need at each stage of fort maturity."
+"Also copy the files in hack/examples/professions/ to professions/. We'll be using these files later. See https://docs.dfhack.org/en/stable/docs/guides/examples-guide.html for more information, including suggestions on how many dwarves of each profession you are likely to need at each stage of fort maturity."
 ""
 "Once you have your starting surface workshops up and running, you might want to configure buildingplan (in its global settings, accessible from any building placement screen, e.g.: b-a-G) to only use blocks for constructions so it won't use your precious wood, boulders, and bars to build floors and walls. If you bring at least 7 blocks with you on embark, you can even set this in your onMapLoad.init file like this:"
 on-new-fortress buildingplan set boulders false; buildingplan set logs false
@@ -50,7 +50,6 @@ interactively."
 ""
 -- Preparation (before you embark!) --
 Copy hack/examples/init/onMapLoad_dreamfort.init to your DF directory
-Copy the fort automation orders from hack/examples/orders/*.json to the dfhack-config/orders/ directory
 Optionally copy the premade profession definitions from hack/examples/professions/ to the professions/ directory
 Optionally copy the premade Dreamfort embark profile from the online spreadsheets to the data/init/embark_profiles.txt file
 ""
@@ -75,7 +74,7 @@ quickfort run library/dreamfort.csv -n /industry2,# Run when the industry level
 prioritize ConstructBuilding,# To get those workshops up and running ASAP. You may have to run this several times as the materials for the building construction jobs become ready.
 quickfort run library/dreamfort.csv -n /surface4,"# Run after the walls and floors are built on the surface. Even if /surface3 is finished before you run /industry2, though, wait until after /industry2 to run this blueprint so that surface walls, floors, and roofing don't prevent your workshops from being built (due to lack of blocks)."
 "quickfort orders,run library/dreamfort.csv -n /services2",# Run when the services levels have been dug out. Feel free to remove the orders for the ropes if you already brought them with you.
-orders import basic,"# Run after the first migration wave, so you have dorfs to do all the basic tasks. Note that this is the ""orders"" plugin, not the ""quickfort orders"" command."
+orders import library/basic,"# Run after the first migration wave, so you have dorfs to do all the basic tasks. Note that this is the ""orders"" plugin, not the ""quickfort orders"" command."
 "quickfort orders,run library/dreamfort.csv -n /surface5","# Run when all marked trees on the surface are chopped down and walls and floors have been constructed, including the roof section over the future barracks."
 prioritize ConstructBuilding,# Run when you see the bridges ready to be built so the busy masons come and build them.
 "quickfort orders,run library/dreamfort.csv -n /surface6",# Run when at least the beehives and weapon rack are constructed and you have linked all levers to their respective bridges.
@@ -86,7 +85,7 @@ prioritize ConstructBuilding,# Run when you see the bridges ready to be built so
 "Also consider bringing magma up to your services level so you can replace the forge and furnaces on your industry level with more powerful magma versions. This is especially important if your embark has insufficient trees to convert into charcoal. Keep in mind that moving magma is a tricky process and can take a long time. Don't forget to continue making progress through the checklist! If you choose to use magma, I suggest getting it in place before importing the military and smelting automation orders since they make heavy use of furnaces and forges."
 ""
 -- Mature fort (third migration wave onward) --
-orders import furnace,# Automated production of basic furnace-related items. Don't forget to create a sand collection zone (or remove the sand- and glass-related orders if you have no sand).
+orders import library/furnace,# Automated production of basic furnace-related items. Don't forget to create a sand collection zone (or remove the sand- and glass-related orders if you have no sand).
 "quickfort orders,run library/dreamfort.csv -n /suites2",# Run when the suites level has been dug out.
 "quickfort orders,run library/dreamfort.csv -n /surface8","# Run if/when you need longer trap corridors on the surface for larger sieges, anytime after you run /surface7."
 "quickfort orders,run library/dreamfort.csv -n /apartments2",# Run when the first apartment level has been dug out.
@@ -95,11 +94,11 @@ orders import furnace,# Automated production of basic furnace-related items. Don
 "quickfort orders,run library/dreamfort.csv -n ""/guildhall3, /guildhall4""",# Optionally run after /guildhall2 to build default furnishings and declare a library and temple.
 "quickfort orders,run library/dreamfort.csv -n /apartments3",# Run when all beds have been constructed on the first apartments level.
 "quickfort orders,run library/dreamfort.csv -n /farming4",# Run once you have a cache of potash.
-orders import military,# Automated production of military equipment. Turn on automelt in the meltables piles on the industry level to automatically upgrade all metal military equipment to masterwork quality. These orders are optional if you are not using a military.
+orders import library/military,# Automated production of military equipment. Turn on automelt in the meltables piles on the industry level to automatically upgrade all metal military equipment to masterwork quality. These orders are optional if you are not using a military.
-orders import smelting,# Automated production of all types of metal bars.
+orders import library/smelting,# Automated production of all types of metal bars.
 "quickfort orders,run library/dreamfort.csv -n /services4","# Run when you need a jail, anytime after the restraints are placed from /services3."
-orders import rockstock,# Maintains a small stock of all types of rock furniture.
+orders import library/rockstock,# Maintains a small stock of all types of rock furniture.
-orders import glassstock,# Maintains a small stock of all types of glass furniture and parts (only import if you have sand).
+orders import library/glassstock,# Maintains a small stock of all types of glass furniture and parts (only import if you have sand).
 ""
 -- Repeat for each remaining apartments level as needed --
 "quickfort orders,run library/dreamfort.csv -n /apartments2",# Run when the apartment level has been dug out.
@@ -1830,7 +1829,6 @@ Workshops:
 Manual steps you have to take:
 - Assign minecarts to your quantum stockpile hauling routes
 "- Give from the ""Goods"" quantum stockpile to the jugs, pots, and bags stockpiles on the farming level"
-- Copy the fort automation manager orders (the .json files) from hack/examples/orders/ and put them in your dfhack-config/orders/ directory.
 ""
 Optional manual steps you can take:
 - Restrict the Mechanic's workshop to only allow skilled workers so unskilled trap-resetters won't be tasked to build mechanisms.
@@ -1846,11 +1844,11 @@ Industry Walkthrough:
 ""
 "3) Once the area is dug out, run /industry2. Remember to assign minecarts to to your quantum stockpile hauling routes, and if the farming level is already built, give from the ""Goods"" quantum stockpile (the one on the left) to the jugs, pots, and bags stockpiles on the farming level."
 ""
-"4) Once you have enough dwarves to do maintenance tasks (that is, after the first or second migration wave), run ""orders import basic"" to use the provided basic.json to take care of your fort's basic needs, such as food, booze, and raw material processing."
+"4) Once you have enough dwarves to do maintenance tasks (that is, after the first or second migration wave), run ""orders import library/basic"" to use the provided basic.json to take care of your fort's basic needs, such as food, booze, and raw material processing."
 ""
 "5) If you want to automatically melt goblinite and other low-quality weapons and armor, mark the south-east stockpiles for auto-melt. If you don't have a high density of trees to make into charcoal, though, be sure to route magma to the level beneath this one and replace the forge and furnaces with magma equivalents."
 ""
-"6) Once you have magma furnaces (or abundant fuel) and more dwarves, run ""orders import furnace"", ""orders import military"", and ""orders import smelting"" to import the remaining fort automation orders. The military orders are optional if you are not planning to have a military, of course."
+"6) Once you have magma furnaces (or abundant fuel) and more dwarves, run ""orders import library/furnace"", ""orders import library/military"", and ""orders import library/smelting"" to import the remaining fort automation orders. The military orders are optional if you are not planning to have a military, of course."
 ""
 "7) At any time, feel free to build extra workshops or designate custom stockpiles in the unused space in the top and bottom right. The space is there for you to use!"
 "#dig label(industry1) start(18; 18; central stairs) message(Once the area is dug out, continue with /industry2.)"
@@ -1969,7 +1967,7 @@ query/industry_query
 - assign minecarts to to your quantum stockpile hauling routes (use ""assign-minecarts all"")
 - if the farming level is already built, give from the ""Goods"" quantum stockpile to the jugs, pots, and bags stockpiles on the farming level
 - if you want to automatically melt goblinite and other low-quality weapons and armor, mark the south-east stockpiles for auto-melt
-- once you have enough dwarves, run ""orders import basic"" to automate your fort's basic needs (see /industry_help for more info on this file)
+- once you have enough dwarves, run ""orders import library/basic"" to automate your fort's basic needs (see /industry_help for more info on this file)
 - optionally, restrict the labors for your Craftsdwarf's and Mechanic's workshops as per the guidance in /industry_help)"
 
 

docs/Plugins.rst

@@ -1129,6 +1129,7 @@ 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.
@@ -1141,6 +1142,103 @@ 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 <data/orders/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 <data/orders/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 <data/orders/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 <data/orders/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 <data/orders/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 <data/orders/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)
+
 .. _seedwatch:
 
 seedwatch

docs/changelog.txt

@@ -42,6 +42,8 @@ changelog.txt uses a syntax similar to RST, with a few special sequences:
 
 ## Misc Improvements
 - ``materials.ItemTraitsDialog``: added a default ``on_select``-handler which toggles the traits.
+
+- `orders`: added useful library of manager orders. see them with ``orders list`` and import them with, for example, ``orders import library/basic``
 - `prospect`: add new ``--show`` option to give the player control over which report sections are shown. e.g. ``prospect all --show ores`` will just show information on ores.
 
 ## Documentation

docs/guides/examples-guide.rst

@@ -48,105 +48,6 @@ it is useful (and customizable) for any fort. It includes the following config:
   settings won't be overridden.
 - Enables `automelt`, `tailor`, `zone`, `nestboxes`, and `autonestbox`.
 
-The ``orders/`` subfolder
--------------------------
-
-The :source:`orders/ <data/examples/orders>` subfolder contains manager orders
-that, along with the ``onMapLoad_dreamfort.init`` file above, allow a fort to be
-self-sustaining. Copy them to your ``dfhack-config/orders/`` folder and import
-as required with the `orders` DFHack plugin.
-
-:source:`basic.json <data/examples/orders/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 <data/examples/orders/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 <data/examples/orders/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 <data/examples/orders/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 <data/examples/orders/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 <data/examples/orders/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)
-
 The ``professions/`` subfolder
 ------------------------------
 

library/modules/Filesystem.cpp

@@ -246,6 +246,7 @@ static int listdir_recursive_impl (std::string prefix, std::string path,
     int err = Filesystem::listdir(prefixed_path, curdir_files);
     if (err)
         return err;
+    bool out_of_depth = false;
     for (auto file = curdir_files.begin(); file != curdir_files.end(); ++file)
     {
         if (*file == "." || *file == "..")
@@ -254,6 +255,12 @@ static int listdir_recursive_impl (std::string prefix, std::string path,
         std::string path_file = path + *file;
         if (Filesystem::isdir(prefixed_file))
         {
+            if (depth == 0)
+            {
+                out_of_depth = true;
+                continue;
+            }
+
             files.insert(std::pair<std::string, bool>(include_prefix ? prefixed_file : path_file, true));
             err = listdir_recursive_impl(prefix, path_file + "/", files, depth - 1, include_prefix);
             if (err)
@@ -264,7 +271,7 @@ static int listdir_recursive_impl (std::string prefix, std::string path,
             files.insert(std::pair<std::string, bool>(include_prefix ? prefixed_file : path_file, false));
         }
     }
-    return 0;
+    return out_of_depth ? -1 : 0;
 }
 
 int Filesystem::listdir_recursive (std::string dir, std::map<std::string, bool> &files,

plugins/orders.cpp

@@ -41,6 +41,7 @@ DFHACK_PLUGIN("orders");
 REQUIRE_GLOBAL(world);
 
 static const std::string ORDERS_DIR = "dfhack-config/orders";
+static const std::string ORDERS_LIBRARY_DIR = "dfhack-config/orders/library";
 
 static command_result orders_command(color_ostream & out, std::vector<std::string> & parameters);
 
@@ -53,7 +54,7 @@ DFhackCExport command_result plugin_init(color_ostream & out, std::vector<Plugin
         false,
         "orders - Manipulate manager orders\n"
         "  orders list\n"
-        "    Shows the list of previously exported orders."
+        "    Shows the list of previously exported orders.\n"
         "  orders export [name]\n"
         "    Exports the current list of manager orders to a file named dfhack-config/orders/[name].json.\n"
         "  orders import [name]\n"
@@ -121,6 +122,30 @@ static command_result orders_command(color_ostream & out, std::vector<std::strin
     return CR_WRONG_USAGE;
 }
 
+static void list_library(color_ostream &out) {
+    std::map<std::string, bool> files;
+    if (0 < Filesystem::listdir_recursive(ORDERS_LIBRARY_DIR, files, 0, false)) {
+        // if the library directory doesn't exist, just skip it
+        return;
+    }
+
+    if (files.empty()) {
+        // if no files in the library directory, just skip it
+        return;
+    }
+
+    for (auto it : files)
+    {
+        if (it.second)
+            continue; // skip directories
+        std::string name = it.first;
+        if (name.length() <= 5 || name.rfind(".json") != name.length() - 5)
+            continue; // skip non-.json files
+        name.resize(name.length() - 5);
+        out << "library/" << name << std::endl;
+    }
+}
+
 static command_result orders_list_command(color_ostream & out)
 {
     // use listdir_recursive instead of listdir even though orders doesn't
@@ -150,6 +175,8 @@ static command_result orders_list_command(color_ostream & out)
         out << name << std::endl;
     }
 
+    list_library(out);
+
     return CR_OK;
 }
 
@@ -889,12 +916,20 @@ static command_result orders_import(color_ostream &out, Json::Value &orders)
 
 static command_result orders_import_command(color_ostream & out, const std::string & name)
 {
-    if (!is_safe_filename(out, name))
+    std::string fname = name;
+    bool is_library = false;
+    if (0 == name.find("library/")) {
+        is_library = true;
+        fname = name.substr(8);
+    }
+
+    if (!is_safe_filename(out, fname))
     {
         return CR_WRONG_USAGE;
     }
 
-    const std::string filename(ORDERS_DIR + "/" + name + ".json");
+    const std::string filename((is_library ? ORDERS_LIBRARY_DIR : ORDERS_DIR) +
+                                    "/" + fname + ".json");
     Json::Value orders;
 
     {