From c8d329e3346d230f588abb314a713b32e1777fc6 Mon Sep 17 00:00:00 2001 From: myk002 Date: Mon, 16 Aug 2021 05:57:40 -0700 Subject: [PATCH] add documentation for examples files --- docs/guides/examples-guide.rst | 207 ++++++++++++++++++++++++ docs/guides/quickfort-library-guide.rst | 2 + 2 files changed, 209 insertions(+) create mode 100644 docs/guides/examples-guide.rst diff --git a/docs/guides/examples-guide.rst b/docs/guides/examples-guide.rst new file mode 100644 index 000000000..0fed9a9c3 --- /dev/null +++ b/docs/guides/examples-guide.rst @@ -0,0 +1,207 @@ +.. _dfhack-examples-guide: + +DFHack Example Configuration File Guide +======================================= + +The :source:`hack/examples ` folder contains ready-to-use +examples of various DFHack configuration files. You can use them by copying them +to appropriate folders where DFHack and its plugins can find them (details +below). You can use them unmodified, or you can customize them to better suit +your preferences. + +The ``init/`` subfolder +----------------------- + +The :source:`init/ ` subfolder contains useful DFHack +`init-files` that you can copy into your main Dwarf Fortress folder -- the same +directory as ``dfhack.init``. + +:source:`onMapLoad_dreamfort.init ` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is the config file that comes with the `dreamfort` set of blueprints, but +it is useful (and customizable) for any fort. It includes the following config: + +- Calls `ban-cooking` for items that have important alternate uses and should + not be cooked. This configuration is only set when a fortress is first + started, so later manual changes will not be overridden. +- Automates calling of various fort maintenance and `scripts-fix`, like + `cleanowned` and `fix/stuckdoors`. +- Periodically enqueues orders to shear and milk shearable and milkable pets. +- Sets up `autofarm` to grow 30 units of every crop, except for pig tails, which + is set to 150 units to support the textile industry. +- Sets up `seedwatch` to keep 30 of every type of seed. +- Configures `prioritize` to automatically boost the priority of important tasks + that could otherwise get ignored in busy forts, like storing items in + vehicles, pulling levers, and removing constructions. +- Optimizes `autobutcher` settings for raising geese, alpacas, sheep, llamas, + and pigs. Adds sensible defaults for all other animals, including dogs and + cats. There are instructions in the file for customizing the settings for + other combinations of animals. These settings are also only set when a + fortress is first started, so any later changes you make to autobutcher + settings won't be overridden. +- Enables `automelt`, `tailor`, `zone`, `nestboxes`, and `autonestbox`. + +The ``orders/`` subfolder +------------------------- + +The :source:`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 ` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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/bags (of leather, cloth, silk, and yarn) +- crafts and totems from otherwise unusable by-products +- splints/crutches +- lye/soap +- ash/potash + +You should import it as soon as you have enough dwarves to perform the +maintenance 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) +- plaster +- pearlash +- sand +- green/clear/crystal glass +- adamantine processing +- item melting + +: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, and copper (and their + dependencies) +- bronze/copper bolts +- platinum/silver/steel/iron/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. + +The ``professions/`` subfolder +------------------------------ + +The :source:`professions/ ` subfolder contains +professions, or sets of related labors, that you can assign to your dwarves with +the DFHack `manipulator` plugin. Copy them into the ``professions/`` +subdirectory under the main Dwarf Fortress folder (you may have to create this +subdirectory) and assign them to your dwarves in the manipulator UI, accessible +from the ``units`` screen via the :kbd:`l` hotkey. Make sure that the +``manipulator`` plugin is enabled in your ``dfhack.init`` file! You can assign a +profession to a dwarf by selecting the dwarf in the ``manipulator`` UI and +hitting :kbd:`p`. The list of professions that you copied into the +``professions/`` folder will show up for you to choose from. This is very useful +for assigning roles to new migrants to ensure that all the tasks in your fort +have adequate numbers of dwarves attending to them. + +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. + +============= ======== ===== ================================================= +Profession At Start Max Description +============= ======== ===== ================================================= +StartManager 1 0 All skills not covered by the other starting + professions (Miner, Mason, Outdoorsdwarf, and + Craftsdwarf), 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 convert to some other profession once there + are enough dwarves to cover all the specialized + professions. +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. +Mason 2 2-4 Masonry and Architecture. 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. Late + game, you can turn off their Architcture labors + since that will be better handled by your + Haulers. +Outdoorsdwarf 1 2-3 Woodcutting, Animal Training, Trapping, Plant + Gathering, Beekeeping, and Mechanics. This + profession is also the only non-military + profession to have Recover wounded enabled (since + Outdoorsdwarves will have a battleaxe to defend + themselves with). +Craftsdwarf 1 3-4 All labors used at Carpenter's workshops, + Jeweler's workshops, and Craftsdwarf's workshops. +Chef 0 2 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. +Clothier 0 2 Textile industry labors: Dying, Leatherworking, + Weaving, and Clothesmaking. +Doctor 0 2-4 The full suite of medical labors, plus Animal + Caretaking for those using the dwarfvet plugin. +Farmer 0 5 Food- and animal product-related labors. +Fisherdwarf 0 0 Fishing. If you assign this profession to any + dwarf, be prepared to be inundated with fish. + Fisherdwarves *never stop fishing*. +Hauler 0 >20 All hauling labors plus 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. +Marksdwarf 0 10 Same as Hauler, but with a different name so you + can find your military dwarves more easily. +Meleedwarf 0 50 Mostly the same as Hauler, but with a different + name so you can find your military dwarves more + easily. This profession also has the Recover + Wounded labor enabled. +Smith 0 4 Smithing, Glassmaking, Pottery, and Siege + Engineering labors. You will likely want to + specialize your Smiths to focus on either weapons + or armor to maximize equipment quality. +Unskilled 0 10-12 All labors that don't improve quality with skill, + such as furnace labors, Soapmaking, and Pump + Operating. +============= ======== ===== ================================================= diff --git a/docs/guides/quickfort-library-guide.rst b/docs/guides/quickfort-library-guide.rst index d0b308747..39b86adda 100644 --- a/docs/guides/quickfort-library-guide.rst +++ b/docs/guides/quickfort-library-guide.rst @@ -20,6 +20,8 @@ help sections that walk you through how to build the fort, step by step. - :source:`library/dreamfort.csv ` - :source:`library/quickfortress.csv ` +.. _dreamfort: + Dreamfort ~~~~~~~~~