diff --git a/data/dfhack-config/init/examples/README.md b/data/dfhack-config/init/examples/README.md deleted file mode 100644 index 99060b0a3..000000000 --- a/data/dfhack-config/init/examples/README.md +++ /dev/null @@ -1,9 +0,0 @@ -# Example DFHack init scripts - -This folder contains ready-to-use examples of DFHack init scripts. -You can use them by copying them to the dfhack-config/init folder. -You can use them unmodified, or you can customize them to better -suit your preferences. - -For information on each of the files in this library, see the -[DFHack Example Configuration File Guide](https://docs.dfhack.org/en/stable/docs/guides/examples-guide.html). diff --git a/data/dfhack-config/init/examples/onMapLoad_dreamfort.init b/data/dfhack-config/init/examples/onMapLoad_dreamfort.init deleted file mode 100644 index 13d4ea8fc..000000000 --- a/data/dfhack-config/init/examples/onMapLoad_dreamfort.init +++ /dev/null @@ -1,76 +0,0 @@ -# This dfhack config file automates common tasks for your forts. -# It was written for the Dreamfort set of quickfort blueprints, but the -# configuration here is useful for any fort! Copy this file to your -# dfhack-config/init directory to use. Feed free to edit or override -# to your liking. - -# Uncomment this next line if you want buildingplan (and quickfort) to use only -# blocks (not bars or logs) for constructions and workshops. If you do -# uncomment, be sure to bring some blocks with you for starting workshops! -#on-new-fortress buildingplan set boulders false; buildingplan set logs false - -# Disable cooking of useful item types when you start a new fortress. -on-new-fortress ban-cooking all - -# Show a warning dialog when units are starving -repeat -name warn-starving -time 10 -timeUnits days -command [ warn-starving ] - -# Force dwarves to drop tattered clothing instead of clinging to the scraps -repeat -name cleanowned -time 1 -timeUnits months -command [ cleanowned X ] - -# Automatically enqueue orders to shear and milk animals -repeat -name autoShearCreature -time 14 -timeUnits days -command [ workorder ShearCreature ] -repeat -name autoMilkCreature -time 14 -timeUnits days -command [ workorder "{\"job\":\"MilkCreature\",\"item_conditions\":[{\"condition\":\"AtLeast\",\"value\":2,\"flags\":[\"empty\"],\"item_type\":\"BUCKET\"}]}" ] - -# Fulfill high-volume orders before slower once-daily orders -repeat -name orders-sort -time 1 -timeUnits days -command [ orders sort ] - -# Manages crop assignment for farm plots -enable autofarm -autofarm default 30 -autofarm threshold 150 GRASS_TAIL_PIG - -# allows you to configure a stockpile to automatically mark items for melting -enable automelt - -# creates manager orders to produce replacements for worn clothing -enable tailor - -# auto-assigns nesting birds to nestbox zones and protects fertile eggs from -# being gathered and eaten -enable autonestbox nestboxes - -# manages seed stocks -enable seedwatch -seedwatch all 30 - -# ensures important tasks get assigned to workers. -# otherwise many job types can get ignored in busy forts. -on-new-fortress prioritize -aq defaults - -# autobutcher settings are saved in the savegame, so we only need to set them once. -# this way, any custom settings you set during gameplay are not overwritten -# -# feel free to change this to "target 0 0 0 0" if you don't expect to want to raise -# any animals not listed here -- you can always change it anytime during the game -# later if you change your mind. -on-new-fortress enable autobutcher -on-new-fortress autobutcher target 2 2 2 2 new -# dogs and cats. You should raise the limits for dogs if you will be training them -# for hunting or war. -on-new-fortress autobutcher target 2 2 2 2 DOG -on-new-fortress autobutcher target 1 1 2 2 CAT -# geese are our primary source of bones and leather. let the younglings grow up -# before we butcher so we get adult-scale products from them. BIRD_PEAFOWL_BLUE, -# BIRD_CHICKEN, and BIRD_TURKEY are also viable. feel free to change this to -# your bird of choice. -on-new-fortress autobutcher target 50 50 14 2 BIRD_GOOSE -# alpaca, sheep, and llamas give wool. we need to keep these numbers low, though, or -# else risk running out of grass for grazing. -on-new-fortress autobutcher target 2 2 4 2 ALPACA SHEEP LLAMA -# pigs give milk and meat and are zero-maintenance. -on-new-fortress autobutcher target 5 5 6 2 PIG -# immediately butcher all unprofitable animals -on-new-fortress autobutcher target 0 0 0 0 HORSE YAK DONKEY WATER_BUFFALO GOAT CAVY BIRD_DUCK BIRD_GUINEAFOWL -# watch for new animals -on-new-fortress autobutcher autowatch diff --git a/docs/guides/examples-guide.rst b/docs/guides/examples-guide.rst deleted file mode 100644 index d2581cf81..000000000 --- a/docs/guides/examples-guide.rst +++ /dev/null @@ -1,49 +0,0 @@ -.. _config-examples-guide: -.. _dfhack-examples-guide: - -DFHack config file examples -=========================== - -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 :file:`dfhack-config/init` -folder -- the same directory as ``dfhack.init``. - -.. _onMapLoad-dreamfort-init: - -:source:`onMapLoad_dreamfort.init ` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This is the config file that designed for 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 scripts, like `cleanowned` and - `fix/stuckdoors`. -- Keeps your manager orders intelligently ordered with `orders` ``sort`` so no - orders block other orders from ever getting completed. -- 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 protect 30 of every type of seed. -- Configures `prioritize` to automatically boost the priority of important and - time-sensitive tasks that could otherwise get ignored in busy forts, like - hauling food, tanning hides, 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`. diff --git a/docs/guides/index.rst b/docs/guides/index.rst index 95f9ff32a..6660dfae5 100644 --- a/docs/guides/index.rst +++ b/docs/guides/index.rst @@ -8,7 +8,5 @@ These pages are detailed guides covering DFHack tools. :maxdepth: 1 /docs/guides/modding-guide - /docs/guides/examples-guide /docs/guides/quickfort-library-guide /docs/guides/quickfort-user-guide - /docs/guides/quickfort-alias-guide diff --git a/docs/guides/quickfort-alias-guide.rst b/docs/guides/quickfort-alias-guide.rst deleted file mode 100644 index a89e6f338..000000000 --- a/docs/guides/quickfort-alias-guide.rst +++ /dev/null @@ -1,875 +0,0 @@ -.. _quickfort-alias-guide: - -Quickfort keystroke alias reference -=================================== - -Aliases allow you to use simple words to represent complicated key sequences -when configuring buildings and stockpiles in quickfort ``#query`` and -``#config`` blueprints. - -For example, say you have the following ``#build`` and ``#place`` blueprints:: - - #build masonry workshop - ~, ~,~,`,`,` - ~,wm,~,`,`,` - ~, ~,~,`,`,` - - #place stockpile for mason - ~,~,~,s,s,s - ~,~,~,s,s,s - ~,~,~,s,s,s - -and you want to configure the stockpile to hold only non-economic ("other") -stone and to give to the adjacent mason workshop. You could write the -key sequences directly:: - - #query configure stockpile with expanded key sequences - ~,~,~,s{Down 5}deb{Right}{Down 2}p^,`,` - ~,~,~,g{Left 2}&, `,` - ~,~,~,`, `,` - -or you could use aliases:: - - #query configure stockpile with aliases - ~,~,~,otherstone,`,` - ~,~,~,give2left, `,` - ~,~,~,`, `,` - -If the stockpile had only a single tile, you could also replay both aliases in -a single cell:: - - #query configure mason with multiple aliases in one cell - ~,~,~,{otherstone}{give2left},`,` - ~,~,~,`, `,` - ~,~,~,`, `,` - -With aliases, blueprints are much easier to read and understand. They also -save you from having to copy the same long key sequences everywhere. - -Alias definition files ----------------------- - -DFHack comes with a library of aliases for you to use that are always -available when you run a ``#query`` blueprint. Many blueprints can be built -with just those aliases. This "standard alias library" is stored in -:source:`data/quickfort/aliases-common.txt` (installed under the ``hack`` folder -in your DFHack installation). The aliases in that file are described at the -`bottom of this document `. - -Please do not edit the aliases in the standard library directly. The file will -get overwritten when DFHack is updated and you'll lose your changes. Instead, -add your custom aliases to :source:`dfhack-config/quickfort/aliases.txt` or -directly to your blueprints in an `#aliases ` -section. Your custom alias definitions take precedence over any definitions in -the standard library. - -Alias syntax and usage ----------------------- - -The syntax for defining aliases is:: - - aliasname: expansion - -Where ``aliasname`` is at least two letters or digits long (dashes and -underscores are also allowed) and ``expansion`` is whatever you would type -into the DF UI. - -You use an alias by typing its name into a ``#query`` blueprint cell where you -want it to be applied. You can use an alias by itself or as part of a larger -sequence, potentially with other aliases. If the alias is the only text in the -cell, the alias name is matched and its expansion is used. If the alias has -other keys before or after it, the alias name must be surrounded in curly -brackets (:kbd:`{` and :kbd:`}`). An alias can be surrounded in curly brackets -even if it is the only text in the cell, it just isn't necessary. For example, -the following blueprint uses the ``aliasname`` alias by itself in the first -two rows and uses it as part of a longer sequence in the third row:: - - #query apply alias 'aliasname' in three different ways - aliasname - {aliasname} - literaltext{aliasname}literaltext - -For a more concrete example of an alias definition, a simple alias that -configures a stockpile to have no bins (:kbd:`C`) and no barrels (:kbd:`E`) -assigned to it would look like this:: - - nocontainers: CE - -The alias definition can also contain references to other aliases by including -the alias names in curly brackets. For example, ``nocontainers`` could be -equivalently defined like this:: - - nobins: C - nobarrels: E - nocontainers: {nobins}{nobarrels} - -Aliases used in alias definitions *must* be surrounded by curly brackets, even -if they are the only text in the definition:: - - alias1: text1 - alias2: alias1 - alias3: {alias1} - -Here, ``alias1`` and ``alias3`` expand to ``text1``, but ``alias2`` expands to -the literal text ``alias1``. - -Keycodes -~~~~~~~~ - -Non-printable characters, like the arrow keys, are represented by their -keycode name and are also surrounded by curly brackets, like ``{Right}`` or -``{Enter}``. Keycodes are used exactly like aliases -- they just have special -expansions that you wouldn't be able to write yourself. In order to avoid -naming conflicts between aliases and keycodes, the convention is to start -aliases with a lowercase letter. - -Any keycode name from the DF interface definition file -(data/init/interface.txt) is valid, but only a few keycodes are actually -useful for blueprints:: - - Up - Down - Left - Right - Enter - ESC - Backspace - Space - Tab - -There is also one pseudo-keycode that quickfort recognizes:: - - Empty - -which has an empty expansion. It is primarily useful for defining blank default values for `Sub-aliases`_. - -Repetitions -~~~~~~~~~~~ - -Anything enclosed within curly brackets can also have a number, indicating how -many times that alias or keycode should be repeated. For example: -``{togglesequence 9}`` or ``{Down 5}`` will repeat the ``togglesequence`` -alias nine times and the ``Down`` keycode five times, respectively. - -Modifier keys -~~~~~~~~~~~~~ - -Ctrl, Alt, and Shift modifiers can be specified for the next key by adding -them into the key sequence. For example, Alt-h is written as ``{Alt}h``. - -Shorthand characters -~~~~~~~~~~~~~~~~~~~~ - -Some frequently-used keycodes are assigned shorthand characters. Think of them -as single-character aliases that don't need to be surrounded in curly -brackets:: - - & expands to {Enter} - @ expands to {Shift}{Enter} - ~ expands to {Alt} - ! expands to {Ctrl} - ^ expands to {ESC} - -If you need literal versions of the shorthand characters, surround them in -curly brackets, for example: use ``{!}`` for a literal exclamation point. - -Built-in aliases -~~~~~~~~~~~~~~~~ - -Most aliases that come with DFHack are in ``aliases-common.txt``, but there is -one alias built into the code for the common shorthand for "make room":: - - r+ expands to r+{Enter} - -This needs special code support since ``+`` can't normally be used in alias -names. You can use it just like any other alias, either by itself in a cell -(``r+``) or surrounded in curly brackets (``{r+}``). - -Sub-aliases -~~~~~~~~~~~ - -You can specify sub-aliases that will only be defined while the current alias -is being resolved. This is useful for "injecting" custom behavior into the -middle of a larger alias. As a simple example, the ``givename`` alias is defined -like this:: - - givename: !n{name}& - -Note the use of the ``name`` alias inside of the ``givename`` expansion. In your -``#query`` blueprint, you could write something like this, say, while over your -main drawbridge:: - - {givename name="Front Gate"} - -The value that you give the sub-alias ``name`` will be used when the -``givename`` alias is expanded. Without sub-aliases, we'd have to define -``givename`` like this:: - - givenameprefix: !n - givenamesuffix: & - -and use it like this:: - - {givenameprefix}Front Gate{givenamesuffix} - -which is more difficult to write and more difficult to understand. - -A handy technique is to define an alias with some sort of default -behavior and then use sub-aliases to override that behavior as necessary. For -example, here is a simplified version of the standard ``quantum`` alias that -sets up quantum stockpiles:: - - quantum_enable: {enableanimals}{enablefood}{enablefurniture}... - quantum: {linksonly}{nocontainers}{quantum_enable} - -You can use the default behavior of ``quantum_enable`` by just using the -``quantum`` alias by itself. But you can override ``quantum_enable`` to just -enable furniture for some specific stockpile like this:: - - {quantum quantum_enable={enablefurniture}} - -If an alias uses a sub-alias in its expansion, but the sub-alias is not defined -when the alias is used, quickfort will halt the ``#query`` blueprint with an -error. If you want your aliases to work regardless of whether sub-aliases are -defined, then you must define them with default values like ``quantum_enable`` -above. If a default value should be blank, like the ``name`` sub-alias used by -the ``givename`` alias above, define it with the ``{Empty}`` pesudo-keycode:: - - name: {Empty} - -Sub-aliases must be in one of the following formats:: - - subaliasname=keyswithnospaces - subaliasname="keys with spaces or {aliases}" - subaliasname={singlealias} - -If you specify both a sub-alias and a number of repetitions, the number for -repetitions goes last, right before the :kbd:`}`:: - - {alias subaliasname=value repetitions} - -Beyond query mode ------------------ -``#query`` blueprints normally do things in DF :kbd:`q`\uery mode, but nobody -said that we have to *stay* in query mode. ``#query`` blueprints send -arbitrary key sequences to Dwarf Fortress. Anything you can do by typing keys -into DF, you can do in a ``#query`` blueprint. It is absolutely fine to -temporarily exit out of query mode, go into, say, hauling or zone or hotkey -mode, and do whatever needs to be done. - -You just have to make certain to exit out of that alternate mode and get back -into :kbd:`q`\uery mode at the end of the key sequence. That way quickfort can -continue on configuring the next tile -- a tile configuration that assumes the -game is still in query mode. - -For example, here is the standard library alias for giving a name to a zone:: - - namezone: ^i{givename}^q - -The first :kbd:`\^` exits out of query mode. Then :kbd:`i` enters zones mode. -We then reuse the standard alias for giving something a name. Finally, we exit -out of zones mode with another :kbd:`\^` and return to :kbd:`q`\uery mode. - -.. _quickfort-alias-library: - -The DFHack standard alias library ---------------------------------- - -DFHack comes with many useful aliases for you to use in your blueprints. Many -blueprints can be built with just these aliases alone, with no custom aliases -required. - -This section goes through all aliases provided by the DFHack standard alias -library, discussing their intended usage and detailing sub-aliases that you -can define to customize their behavior. - -If you do define your own custom aliases in -``dfhack-config/quickfort/aliases.txt``, try to build on library alias -components. For example, if you create an alias to modify particular furniture -stockpile settings, start your alias with ``{furnitureprefix}`` instead of -``s{Down 2}``. Using library prefixes will allow library sub-aliases to work -with your aliases just like they do with library aliases. In this case, using -``{furnitureprefix}`` will allow your stockpile customization alias to work -with both stockpiles and hauling routes. - -Note that some aliases use the DFHack-provided search prompts. If you get errors -while running ``#query`` blueprints, ensure the DFHack `search-plugin` plugin is -enabled. - -Naming aliases -~~~~~~~~~~~~~~ - -These aliases give descriptive names to workshops, levers, stockpiles, zones, -etc. Dwarf Fortress building, stockpile, and zone names have a maximum length -of 20 characters. - -======== =========== -Alias Sub-aliases -======== =========== -givename name -namezone name -======== =========== - -``givename`` works anywhere you can hit Ctrl-n to customize a name, like when -the cursor is over buildings and stockpiles. Example:: - - #place - f(10x2) - - #query - {booze}{givename name=booze} - -``namezone`` is intended to be used when over an activity zone. It includes -commands to get into zones mode, set the zone name, and get back to query -mode. Example:: - - #zone - n(2x2) - - #query - {namezone name="guard dog pen"} - -Quantum stockpile aliases -~~~~~~~~~~~~~~~~~~~~~~~~~ - -These aliases make it easy to create :wiki:`minecart stop-based quantum stockpiles `. - -+----------------------+------------------+ -| Alias | Sub-aliases | -+======================+==================+ -| quantum | | name | -| | | quantum_enable | -+----------------------+------------------+ -| quantumstopfromnorth | | name | -+----------------------+ | stop_name | -| quantumstopfromsouth | | route_enable | -+----------------------+ | -| quantumstopfromeast | | -+----------------------+ | -| quantumstopfromwest | | -+----------------------+------------------+ -| sp_link | | move | -| | | move_back | -+----------------------+------------------+ -| quantumstop | | name | -| | | stop_name | -| | | route_enable | -| | | move | -| | | move_back | -| | | sp_links | -+----------------------+------------------+ - -The idea is to use a minecart on a track stop to dump an infinite number of -items into a receiving "quantum" stockpile, which significantly simplifies -stockpile management. These aliases configure the quantum stockpile and -hauling route that make it all work. Here is a complete example for quantum -stockpiling weapons, armor, and ammunition. It has a 3x1 feeder stockpile on -the bottom (South), the trackstop in the center, and the quantum stockpile on -the top (North). Note that the feeder stockpile is the only stockpile that -needs to be configured to control which types of items end up in the quantum -stockpile. By default, the hauling route and quantum stockpile itself simply -accept whatever is put into them. - -:: - - #place - ,c - , - pdz(3x1) - - #build - , - ,trackstopN - - #query message(remember to assign a minecart to the new route) - ,quantum - ,quantumstopfromsouth - nocontainers - -The ``quantum`` alias configures a 1x1 stockpile to be a quantum stockpile. It -bans all containers and prevents the stockpile from being manually filled. By -default, it also enables storage of all item categories (except corpses and -refuse), so it doesn't really matter what letter you use to place the -stockpile. :wiki:`Refuse` is excluded by default since otherwise clothes and -armor in the quantum stockpile would rot away. If you want corpses or bones in -your quantum stockpile, use :kbd:`y` and/or :kbd:`r` to place the stockpile -and the ``quantum`` alias will just enable the remaining types. If you *do* -enable refuse in your quantum stockpile, be sure you avoid putting useful -clothes or armor in there! - -The ``quantumstopfromsouth`` alias is run over the track stop and configures -the hauling route, again, allowing all item categories into the minecart by -default so any item that can go into the feeder stockpile can then be placed -in the minecart. It also links the hauling route with the feeder stockpile to -the South.The track stop does not need to be fully constructed before the -``#query`` blueprint is run, but the feeder stockpile needs to exist so we can -link to it. This means that the three blueprints above can be run one right -after another, without any dwarven labor in between them, and the quantum -stockpile will work properly. - -Finally, the ``nocontainers`` alias simply configures the feeder stockpile to -not have any containers (which would just get in the way here). If we wanted -to be more specific about what item types we want in the quantum stockpile, we -could configure the feeder stockpile further, for example with standard -`stockpile adjustment aliases `. - -After the blueprints are run, the last step is to manually assign a minecart -to the newly-defined hauling route. - -You can define sub-aliases to customize how these aliases work, for example to -have fine-grained control over what item types are enabled for the route and -quantum stockpile. We'll go over those options below, but first, here is an -example for how to just give names to everything:: - - #query message(remember to assign a minecart to the new route) - ,{quantum name="armory quantum"} - ,{quantumstopfromsouth name="Armory quantum" stop_name="Armory quantum stop"}{givename name="armory dumper"} - {givename name="armory feeder"} - -All ``name`` sub-aliases are completely optional, of course. Keep in mind that -hauling route names have a maximum length of 22 characters, hauling route stop -names have a maximum length of 21 characters, and all other names have a -maximum length of 20 characters. - -If you want to be absolutely certain that nothing ends up in your quantum -stockpile other than what you've configured in the feeder stockpile, you can -set the ``quantum_enable`` sub-alias for the ``quantum`` alias. This can -prevent, for example, somebody's knocked-out tooth from being considered part -of your furniture quantum stockpile when it happened to land on it during a -fistfight:: - - #query - {quantum name="furniture quantum" quantum_enable={enablefurniture}} - -You can have similar control over the hauling route if you need to be more -selective about what item types are allowed into the minecart. If you have -multiple specialized quantum stockpiles that use a common feeder pile, for -example, you can set the ``route_enable`` sub-alias:: - - #query - {quantumstopfromsouth name="Steel bar quantum" route_enable="{enablebars}{steelbars}"} - -Any of the `stockpile configuration aliases ` can -be used for either the ``quantum_enable`` or ``route_enable`` sub-aliases. -Experienced Dwarf Fortress players may be wondering how the same aliases can -work in both contexts since the keys for entering the configuration screen -differ. Fear not! There is some sub-alias magic at work here. If you define -your own stockpile configuration aliases, you can use the magic yourself by -building your aliases on the ``*prefix`` aliases described later in this -guide. - -Finally, the ``quantumstop`` alias is a more general version of the simpler -``quantumstopfrom*`` aliases. The ``quantumstopfrom*`` aliases assume that a -single feeder stockpile is orthogonally adjacent to your track stop (which is -how most people set them up). If your feeder stockpile is somewhere further -away, or you have multiple feeder stockpiles to link, you can use the -``quantumstop`` alias directly. In addition to the sub-aliases used in the -``quantumstopfrom*`` alias, you can define the ``move`` and ``move_back`` -sub-aliases, which let you specify the cursor keys required to move from the -track stop to the (single) feeder stockpile and back again, respectively:: - - #query - {quantumstop move="{Right 2}{Up}" move_back="{Down}{Left 2}"} - -If you have multiple stockpiles to link, define the ``sp_links`` sub-alias, -which can chain several ``sp_link`` aliases together, each with their own -movement configuration:: - - #query - {quantumstop sp_links="{sp_link move=""{Right}{Up}"" move_back=""{Down}{Left}""}{sp_link move=""{Right}{Down}"" move_back=""{Up}{Left}""}"} - -Note the doubled quotes for quoted elements that are within the outer quotes. - -Farm plots -~~~~~~~~~~ - -Sets a farm plot to grow the first or last type of seed in the list of -available seeds for all four seasons. The last seed is usually Plump helmet -spawn, suitable for post-embark. But if you only have one seed type, that'll -be grown instead. - -+------------------+ -| Alias | -+==================+ -| growlastcropall | -+------------------+ -| growfirstcropall | -+------------------+ - -Instead of these aliases, though, it might be more useful to use the DFHack -`autofarm` plugin. - -Stockpile configuration utility aliases -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -================ =========== -Alias Sub-aliases -================ =========== -linksonly -maxbins -maxbarrels -nobins -nobarrels -nocontainers -give2up -give2down -give2left -give2right -give10up -give10down -give10left -give10right -give move -togglesequence -togglesequence2 -forbidsearch search -permitsearch search -togglesearch search -masterworkonly prefix -artifactonly prefix -togglemasterwork prefix -toggleartifact prefix -================ =========== - -``linksonly``, ``maxbins``, ``maxbarrels``, ``nobins``, ``nobarrels``, and -``nocontainers`` set the named basic properties on stockpiles. ``nocontainers`` -sets bins and barrels to 0, but does not affect wheelbarrows since the hotkeys -for changing the number of wheelbarrows depend on whether you have DFHack's -``tweak max-wheelbarrow`` enabled. It is better to set the number of -wheelbarrows via the `quickfort` ``stockpiles_max_wheelbarrows`` setting (set to -``0`` by default), or explicitly when you define the stockpile in the ``#place`` -blueprint. - -The ``give*`` aliases set a stockpile to give to a workshop or another -stockpile located at the indicated number of tiles in the indicated direction -from the current tile. For example, here we use the ``give2down`` alias to -connect an ``otherstone`` stockpile with a mason workshop:: - - #place - s,s,s,s,s - s, , , ,s - s, , , ,s - s, , , ,s - s,s,s,s,s - - #build - `,`,`,`,` - `, , , ,` - `, ,wm,,` - `, , , ,` - `,`,`,`,` - - #query - , ,give2down - otherstone - -and here is a generic stone stockpile that gives to a stockpile that only -takes flux:: - - #place - s(10x1) - s(10x10) - - #query - flux - , - give2up - -If you want to give to some other tile that is not already covered by the -``give2*`` or ``give10*`` aliases, you can use the generic ``give`` alias and -specify the movement keys yourself in the ``move`` sub-alias. Here is how to -give to a stockpile or workshop one z-level above, 9 tiles to the left, and 14 -tiles down:: - - #query - {give move="<{Left 9}{Down 14}"} - -``togglesequence`` and ``togglesequence2`` send ``{Down}{Enter}`` or -``{Down 2}{Enter}`` to toggle adjacent (or alternating) items in a list. This -is useful when toggling a bunch of related item types in the stockpile config. -For example, the ``dye`` alias in the standard alias library needs to select -four adjacent items:: - - dye: {foodprefix}b{Right}{Down 11}{Right}{Down 28}{togglesequence 4}^ - -``forbidsearch``, ``permitsearch``, and ``togglesearch`` use the DFHack -`search-plugin` plugin to forbid or permit a filtered list, or toggle the first -(or only) item in the list. Specify the search string in the ``search`` -sub-alias. Be sure to move the cursor over to the right column before invoking -these aliases. The search filter will be cleared before this alias completes. - -Finally, the ``masterwork`` and ``artifact`` group of aliases configure the -corresponding allowable core quality for the stockpile categories that have -them. This alias is used to implement category-specific aliases below, like -``artifactweapons`` and ``forbidartifactweapons``. - -.. _quickfort-stockpile-aliases: - -Stockpile adjustment aliases -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -For each stockpile item category, there are three standard aliases: - -* ``*prefix`` aliases enter the stockpile configuration screen and position - the cursor at a particular item category in the left-most column, ready for - further keys that configure the elements within that category. All other - stockpile adjustment aliases are built on these prefixes. You can use them - yourself to create stockpile adjustment aliases that aren't already covered - by the standard library aliases. Using the library prefix instead of - creating your own also allows your stockpile configuration aliases to be - used for both stockpiles and hauling routes. For example, here is the - library definition for ``booze``:: - - booze: {foodprefix}b{Right}{Down 5}p{Down}p^ - -* ``enable*`` aliases enter the stockpile configuration screen, enable all - subtypes of the named category, and exit the stockpile configuration screen -* ``disable*`` aliases enter the stockpile configuration screen, disable all - subtypes of the named category, and exit the stockpile configuration screen - -==================== ==================== ===================== -Prefix Enable Disable -==================== ==================== ===================== -animalsprefix enableanimals disableanimals -foodprefix enablefood disablefood -furnitureprefix enablefurniture disablefurniture -corpsesprefix enablecorpses disablecorpses -refuseprefix enablerefuse disablerefuse -stoneprefix enablestone disablestone -ammoprefix enableammo disableammo -coinsprefix enablecoins disablecoins -barsprefix enablebars disablebars -gemsprefix enablegems disablegems -finishedgoodsprefix enablefinishedgoods disablefinishedgoods -leatherprefix enableleather disableleather -clothprefix enablecloth disablecloth -woodprefix enablewood disablewood -weaponsprefix enableweapons disableweapons -armorprefix enablearmor disablearmor -sheetprefix enablesheet disablesheet -==================== ==================== ===================== - -Then, for each item category, there are aliases that manipulate interesting -subsets of that category: - -* Exclusive aliases forbid everything within a category and then enable only - the named item type (or named class of items) -* ``forbid*`` aliases forbid the named type and leave the rest of the - stockpile untouched. -* ``permit*`` aliases permit the named type and leave the rest of the - stockpile untouched. - -Note that for specific item types (items in the third stockpile configuration -column), you can only toggle the item type on and off. Aliases can't know -whether sending the ``{Enter}`` key will enable or disable the type. The -``forbid*`` aliases that affect these item types assume the item type was -enabled and toggle it off. Likewise, the ``permit*`` aliases assume the item -type was disabled and toggle it on. If the item type is not in the expected -enabled/disabled state when the alias is run, the aliases will not behave -properly. - -Animal stockpile adjustments -```````````````````````````` - -=========== =========== ============ -Exclusive Forbid Permit -=========== =========== ============ -cages forbidcages permitcages -traps forbidtraps permittraps -=========== =========== ============ - -Food stockpile adjustments -`````````````````````````` - -=============== ==================== ==================== -Exclusive Forbid Permit -=============== ==================== ==================== -preparedfood forbidpreparedfood permitpreparedfood -unpreparedfish forbidunpreparedfish permitunpreparedfish -plants forbidplants permitplants -booze forbidbooze permitbooze -seeds forbidseeds permitseeds -dye forbiddye permitdye -tallow forbidtallow permittallow -miscliquid forbidmiscliquid permitmiscliquid -wax forbidwax permitwax -=============== ==================== ==================== - -Furniture stockpile adjustments -``````````````````````````````` - -=================== ========================= ========================= -Exclusive Forbid Permit -=================== ========================= ========================= -pots forbidpots permitpots -bags -buckets forbidbuckets permitbuckets -sand forbidsand permitsand -masterworkfurniture forbidmasterworkfurniture permitmasterworkfurniture -artifactfurniture forbidartifactfurniture permitartifactfurniture -=================== ========================= ========================= - -Notes: - -* The ``bags`` alias excludes coffers and other boxes by forbidding all - materials other than cloth, yarn, silk, and leather. Therefore, it is - difficult to create ``forbidbags`` and ``permitbags`` without affecting other - types of furniture stored in the same stockpile. - -* Because of the limitations of Dwarf Fortress, ``bags`` cannot distinguish - between empty bags and bags filled with gypsum powder. - -Refuse stockpile adjustments -```````````````````````````` - -=========== ================== ================== -Exclusive Forbid Permit -=========== ================== ================== -corpses forbidcorpses permitcorpses -rawhides forbidrawhides permitrawhides -tannedhides forbidtannedhides permittannedhides -skulls forbidskulls permitskulls -bones forbidbones permitbones -shells forbidshells permitshells -teeth forbidteeth permitteeth -horns forbidhorns permithorns -hair forbidhair permithair -usablehair forbidusablehair permitusablehair -craftrefuse forbidcraftrefuse permitcraftrefuse -=========== ================== ================== - -Notes: - -* ``usablehair`` Only hair and wool that can make usable clothing is included, - i.e. from sheep, llamas, alpacas, and trolls. -* ``craftrefuse`` includes everything a craftsdwarf or tailor can use: skulls, - bones, shells, teeth, horns, and "usable" hair/wool (defined above). - -Stone stockpile adjustments -``````````````````````````` - -============= ==================== ==================== -Exclusive Forbid Permit -============= ==================== ==================== -metal forbidmetal permitmetal -iron forbidiron permitiron -economic forbideconomic permiteconomic -flux forbidflux permitflux -plaster forbidplaster permitplaster -coalproducing forbidcoalproducing permitcoalproducing -otherstone forbidotherstone permitotherstone -bauxite forbidbauxite permitbauxite -clay forbidclay permitclay -============= ==================== ==================== - -Ammo stockpile adjustments -`````````````````````````` - -============== ==================== ==================== -Exclusive Forbid Permit -============== ==================== ==================== -bolts -\ forbidmetalbolts -\ forbidwoodenbolts -\ forbidbonebolts -masterworkammo forbidmasterworkammo permitmasterworkammo -artifactammo forbidartifactammo permitartifactammo -============== ==================== ==================== - -Bar stockpile adjustments -````````````````````````` - -=========== ================== -Exclusive Forbid -=========== ================== -bars forbidbars -metalbars forbidmetalbars -ironbars forbidironbars -steelbars forbidsteelbars -pigironbars forbidpigironbars -otherbars forbidotherbars -coal forbidcoal -potash forbidpotash -ash forbidash -pearlash forbidpearlash -soap forbidsoap -blocks forbidblocks -=========== ================== - -Gem stockpile adjustments -````````````````````````` - -=========== ================ -Exclusive Forbid -=========== ================ -roughgems forbidroughgems -roughglass forbidroughglass -cutgems forbidcutgems -cutglass forbidcutglass -cutstone forbidcutstone -=========== ================ - -Finished goods stockpile adjustments -```````````````````````````````````` - -======================= ============================= ============================= -Exclusive Forbid Permit -======================= ============================= ============================= -stonetools -woodentools -crafts forbidcrafts permitcrafts -goblets forbidgoblets permitgoblets -masterworkfinishedgoods forbidmasterworkfinishedgoods permitmasterworkfinishedgoods -artifactfinishedgoods forbidartifactfinishedgoods permitartifactfinishedgoods -======================= ============================= ============================= - -Cloth stockpile adjustments -``````````````````````````` - -================ ====================== ====================== -Exclusive Forbid Permit -================ ====================== ====================== -thread forbidthread permitthread -adamantinethread forbidadamantinethread permitadamantinethread -cloth forbidcloth permitcloth -adamantinecloth forbidadamantinecloth permitadamantinecloth -================ ====================== ====================== - -Notes: - -* ``thread`` and ``cloth`` refers to all materials that are not adamantine. - -Weapon stockpile adjustments -```````````````````````````` - -================= ======================== ======================= -Exclusive Forbid Permit -================= ======================== ======================= -\ forbidweapons permitweapons -\ forbidtrapcomponents permittrapcomponents -metalweapons forbidmetalweapons permitmetalweapons -\ forbidstoneweapons permitstoneweapons -\ forbidotherweapons permitotherweapons -ironweapons forbidironweapons permitironweapons -bronzeweapons forbidbronzeweapons permitbronzeweapons -copperweapons forbidcopperweapons permitcopperweapons -steelweapons forbidsteelweapons permitsteelweapons -masterworkweapons forbidmasterworkweapons permitmasterworkweapons -artifactweapons forbidartifactweapons permitartifactweapons -================= ======================== ======================= - -Armor stockpile adjustments -``````````````````````````` - -=============== ====================== ===================== -Exclusive Forbid Permit -=============== ====================== ===================== -metalarmor forbidmetalarmor permitmetalarmor -otherarmor forbidotherarmor permitotherarmor -ironarmor forbidironarmor permitironarmor -bronzearmor forbidbronzearmor permitbronzearmor -copperarmor forbidcopperarmor permitcopperarmor -steelarmor forbidsteelarmor permitsteelarmor -masterworkarmor forbidmasterworkarmor permitmasterworkarmor -artifactarmor forbidartifactarmor permitartifactarmor -=============== ====================== ===================== diff --git a/docs/guides/quickfort-user-guide.rst b/docs/guides/quickfort-user-guide.rst index a06413d40..8d1466a0a 100644 --- a/docs/guides/quickfort-user-guide.rst +++ b/docs/guides/quickfort-user-guide.rst @@ -1,5 +1,6 @@ .. _quickfort-blueprint-guide: .. _quickfort-user-guide: +.. _quickfort-alias-guide: Quickfort blueprint creation guide ================================== @@ -1728,7 +1729,6 @@ Links **Quickfort links:** - `Quickfort command reference ` -- `quickfort-alias-guide` - `blueprint-library-guide` - :forums:`Quickfort forum thread <176889>` - :issue:`DFHack issue tracker <>` diff --git a/scripts b/scripts index 0119ab1b6..ba832ff90 160000 --- a/scripts +++ b/scripts @@ -1 +1 @@ -Subproject commit 0119ab1b6d540e192c77f114c5ea7f7aeab9b39a +Subproject commit ba832ff90f04846dd0e575c0f4f25cb36a0e5afd