From 5223891984e07aba3c6a435f7a0d8e8a2649df39 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Sun, 15 Feb 2015 18:13:58 +1100 Subject: [PATCH 1/3] Update and clarify readme Fixed typos. Made hyperlinks inline. Some editorial changes for clarification. Updated and expanded introduction. Fixed a few formatting errors. --- Readme.rst | 222 +++++++++++++++++++++++++++-------------------------- 1 file changed, 115 insertions(+), 107 deletions(-) diff --git a/Readme.rst b/Readme.rst index 56678afc3..cf0cc45df 100644 --- a/Readme.rst +++ b/Readme.rst @@ -6,39 +6,56 @@ DFHack Readme Introduction ============ -DFHack is a Dwarf Fortress memory access library and a set of basic -tools that use it. Tools come in the form of plugins or (not yet) -external tools. It is an attempt to unite the various ways tools -access DF memory and allow for easier development of new tools. +DFHack is a Dwarf Fortress memory access library, distributed with scripts +and plugins implementing a wide variety of useful functions and tools. + +For users, it provides a significant suite of bugfixes and interface +enhancements by default, and more can be enabled. There are also many tools +(such as ``workflow`` or ``autodump``) which can make life easier. You can +even add third-party scripts and plugins to do almost anything! + +For modders, DFHack makes many things possible. Custom reactions, new +interactions, magic creature abilities, and more can be set through scripts +and custom raws. Non-standard DFHack scripts and inits can be stored in the +raw directory, making raws or saves fully self-contained for distribution - +or for coexistence in a single DF install, even with incompatible components. + +For developers, DFHack unites the various ways tools access DF memory and +allows easier development of new tools. As an open-source project under +various copyleft licences, contributions are welcome. .. contents:: ============== Getting DFHack ============== -The project is currently hosted on github_ -at http://github.com/DFHack/dfhack +The project is currently hosted at http://www.github.com/ + +Recent releases are available in source and binary formats `on the releases +page`_, while the binaries for releases 40.15-r1 to 34.11-r4 are on DFFD_. +Even older versions are available here_. -.. _github: http://www.github.com/ +.. _`on the releases page`: http://github.com/DFHack/dfhack/releases +.. _DFFD: http://dffd.bay12games.com/search.php?string=DFHack&id=15 +.. _here: http://dethware.org/dfhack/download -Older releases can be downloaded from here: http://dethware.org/dfhack/download +All new releases are announced in `the bay12 forums thread`_, which is also a +good place for discussion and questions. -All new releases are announced in the bay12 thread: -http://www.bay12forums.com/smf/index.php?topic=139553.0 +.. _`the bay12 forums thread`: http://www.bay12forums.com/smf/index.php?topic=139553 ============= Compatibility ============= -DFHack works on Windows XP, Vista, 7, any modern Linux distribution, or OS X -10.6.8-10.9. +DFHack is available for Windows (XP or later), Linux (any modern distribution), +or OS X (10.6.8 to 10.9). -Recent versions can be found on the releases_ page. Most releases only support -the version of DF mentioned in their title (e.g. DFHack 0.40.24-r2 only supports -DF 0.40.24), but some releases support earlier DF versions as well. +Most releases only support the version of DF mentioned in their title - for +example, DFHack 0.40.24-r2 only supports DF 0.40.24 - but some releases +support earlier DF versions as well. Wherever possible, use the latest version +built for the target version of DF. -.. _releases: http://github.com/DFHack/dfhack/releases - -On Windows, you have to use the SDL version of DF. +On Windows, DFHack is compatible with the SDL version of DF, but not the legacy version. It is also possible to use the Windows DFHack with Wine under Linux and OS X. @@ -95,7 +112,7 @@ DFHack basically extends what DF can do with something similar to the drop-down console found in Quake engine games. On Windows, this is a separate command line window. On linux, the terminal used to launch the dfhack script is taken over (so, make sure you start from a terminal). Basic interaction with dfhack -involves entering commands into the console. For some basic instroduction, +involves entering commands into the console. For some basic instructions, use the 'help' command. To list all possible commands, use the 'ls' command. Many commands have their own help or detailed description. You can use 'command help' or 'command ?' to show that. @@ -158,22 +175,28 @@ In this case, updating symbols.xml is not necessary. ============================= Something doesn't work, help! ============================= -First, don't panic :) Second, dfhack keeps a few log files in DF's folder -- stderr.log and stdout.log. You can look at those and possibly find out what's -happening. -If you found a bug, you can either report it in the bay12 DFHack thread, -the issues tracker on github, contact me (peterix@gmail.com) or visit the -#dfhack IRC channel on freenode. +First, don't panic :) + +Second, dfhack keeps a few log files in DF's folder (``stderr.log`` and +``stdout.log``). Looking at these might help you solve the problem. +If it doesn't, you can ask for help in the forum thread or on IRC. + +If you found a bug, you can report it in the Bay12 DFHack thread, the issues +tracker on github, or visit the #dfhack IRC channel on freenode. ============= The init file ============= -If your DF folder contains a file named ``dfhack.init``, its contents will be run -every time you start DF. This allows setting up keybindings. An example file -is provided as ``dfhack.init-example`` - you can tweak it and rename to dfhack.init -if you want to use this functionality. +If your DF folder contains a file named ``dfhack.init``, its contents will be +run every time you start DF. This allows keybindings and other settings to +persist across runs. An example file is provided as ``dfhack.init-example`` - +you can tweak it and rename to ``dfhack.init`` if you want to use this +functionality. If only the example init file is found, will be used and a +warning will be shown. -When a savegame is loaded, the ``onLoad.init`` file in its raw folder is run. It works the same way as ``dfhack.init``. It is recommended that modders use this to improve mobility of save games. +When a savegame is loaded, an ``onLoad.init`` file in its raw folder is run, +as a save-portable alternative to ``dfhack.init``. It is recommended that +modders use this to improve mobility of save games and compatibility of mods. Setting keybindings =================== @@ -252,10 +275,10 @@ If the first non-whitespace character is ``:``, the command is parsed in a speci alternative mode: first, non-whitespace characters immediately following the ``:`` are used as the command name; the remaining part of the line, starting with the first non-whitespace character *after* the command name, is used verbatim as the first argument. -The following two command lines are exactly equivalent: +The following two command lines are exactly equivalent:: -* ``:foo a b "c d" e f`` -* ``foo "a b \"c d\" e f"`` + :foo a b "c d" e f + foo "a b \"c d\" e f" This is intended for commands like ``rb_eval`` that evaluate script language statements. @@ -396,13 +419,14 @@ that pre-filled. rendermax --------- A collection of renderer replacing/enhancing filters. For better effect try changing the -black color in palette to non totally black. For more info see thread in forums: -http://www.bay12forums.com/smf/index.php?topic=128487.0 +black color in palette to non totally black. For more info see `the Bay12 forum thread`_. + +.. _`the Bay12 forum thread`: http://www.bay12forums.com/smf/index.php?topic=128487 Options: ``rendermax trippy`` - Randomizes each tiles color. Used for fun mainly. + Randomizes the color of each tiles. Used for fun, or testing. ``rendermax light`` Enable lighting engine. ``rendermax light reload`` @@ -467,8 +491,6 @@ care to exactly preserve the mineral counts reported by ``prospect all``. The amounts of different layer stones may slightly change in some cases if vein mass shifts between Z layers. -This command is very unlikely to work on maps generated before version 0.34.08. - Note that there is no undo option other than restoring from backup. changelayer @@ -609,8 +631,8 @@ Options: :building: Subsequent items will become part of the currently selected building. Best used for loading traps; do not use with workshops, or you will need to deconstruct the building to use the item. -deramp (by zilpin) ------------------- +deramp +------ Removes all ramps designated for removal from the map. This is useful for replicating the old channel digging designation. It also removes any and all 'down ramps' that can remain after a cave-in (you don't have to designate anything for that to happen). @@ -1006,9 +1028,9 @@ A permanent alias for 'digl x'. digexp ------ -This command can be used for exploratory mining. +This command is for `exploratory mining`_. -See: http://df.magmawiki.com/index.php/DF2010:Exploratory_mining +.. _`exploratory mining`: http://dwarffortresswiki.org/index.php/cv:Exploratory_mining There are two variables that can be set: pattern and filter. @@ -1207,16 +1229,11 @@ Cursor must be placed on a floor tile so the items can be dumped there. Options: :destroy: Destroy instead of dumping. Doesn't require a cursor. -:destroy-here: Destroy items only under the cursor. +:destroy-here: Destroy items only under the cursor. Alias ``autodump-destroy-here``, for keybindings. :visible: Only process items that are not hidden. :hidden: Only process hidden items. :forbidden: Only process forbidden items (default: only unforbidden). -autodump-destroy-here ---------------------- -Destroy items marked for dumping under cursor. Identical to autodump -destroy-here, but intended for use as keybinding. - autodump-destroy-item --------------------- Destroy the selected item. The item may be selected in the 'k' list, or inside @@ -1359,8 +1376,9 @@ armor stands, and in containers. Also, the default capacity of armor stands is way too low, so you may want to also apply the ``armorstand-capacity`` patch. Check out - http://www.bay12games.com/dwarves/mantisbt/view.php?id=1445 - for more information about the bugs. + `the bug report`_ for more information. + +.. _`the bug report`: http://www.bay12games.com/dwarves/mantisbt/view.php?id=1445 Note that the buildings in the armory are used as follows: @@ -1435,8 +1453,7 @@ produce undesirable results. There are a few good ones though. You just lost a fortress and gained an adventurer. You could also do this. You are in fort game mode, managing your fortress and paused at the esc menu. - You switch to the adventure game mode, then use Dfusion to *assume control of a creature* and then - save or retire. + You switch to the adventure game mode, assume control of a creature, then save or retire. You just created a returnable mountain home and gained an adventurer. @@ -1446,39 +1463,39 @@ I take no responsibility of anything that happens as a result of using this tool Visualizer and data export ========================== -ssense / stonesense -------------------- +stonesense +---------- An isometric visualizer that runs in a second window. This requires working graphics acceleration and at least a dual core CPU (otherwise it will slow -down DF). - -All the data resides in the 'stonesense' directory. For detailed instructions, -see stonesense/README.txt +down DF). Invoked with ``stonesense``, or alias ``ssense``. -Compatible with Windows > XP SP3 and most modern Linux distributions. +For detailed information, see the `stonesense readme`_, the `wiki page`_, +or the `Bay12 forum thread`_. -Older versions, support and extra graphics can be found in the bay12 forum -thread: http://www.bay12forums.com/smf/index.php?topic=43260.0 +.. _`stonesense readme`: https://github.com/DFHack/stonesense/blob/master/README.md +.. _`wiki page`: http://dwarffortresswiki.org/index.php/Utility:Stonesense +.. _`Bay12 forum thread`: http://www.bay12forums.com/smf/index.php?topic=43260 -Some additional resources: -http://df.magmawiki.com/index.php/Utility:Stonesense/Content_repository +Stonesense works on Windows XP SP3 or later, and most modern Linux distributions. +Each stonesense version is built for a particular version of DFHack, so +releases are now done through DFHack. mapexport --------- -Export the current loaded map as a file. This will be eventually usable -with visualizers. +Export the current loaded map as a file. This was used by visualizers for +DF 34.11, but is now basically obsolete. dwarfexport ----------- -Export dwarves to RuneSmith-compatible XML. +Export dwarves to RuneSmith-compatible XML; also unused by modern tools. exportlegends ------------- Controls legends mode to export data - especially useful to set-and-forget large worlds, or when you want a map of every site when there are several hundred. -The 'info' option exports more data than is possible in vanilla, to a -region-date-legends_plus.xml" file developed to extend the World +The 'info' option exports more data than is possible in vanilla, to a +``region-date-legends_plus.xml`` file developed to extend the World Viewer utility and potentially compatible with others. Options: @@ -1626,13 +1643,15 @@ in the game UI. Constraint format ~~~~~~~~~~~~~~~~~ -The contstraint spec consists of 4 parts, separated with '/' characters:: +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, in the same syntax you would e.g. use -for a custom reaction input. See this list for more info: http://dwarffortresswiki.org/index.php/Item_token +for a custom reaction input. See `this page`_ for more info. + +.. _`this page`: http://dwarffortresswiki.org/index.php/Material_token The subsequent parts are optional: @@ -1645,9 +1664,9 @@ The subsequent parts are optional: - 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 this page for more details on the unabbreviated raw syntax: + See `this page`_ for more details on the unabbreviated raw syntax. - http://dwarffortresswiki.org/index.php/Material_token + .. _`this page`: http://dwarffortresswiki.org/index.php/Material_token - A comma-separated list of miscellaneous flags, which currently can be used to ignore imported items or items below a certain quality. @@ -1975,15 +1994,11 @@ add some new races with 'watch'. If you simply want to stop it completely use Settings and watchlist are stored in the savegame, so that you can have different settings for each world. If you want to copy your watchlist to -another savegame you can use the command list_export: -:: - - Load savegame where you made the settings. - Start a CMD shell and navigate to the df directory. Type the following into the shell: - dfhack-run autobutcher list_export > autobutcher.bat - Load the savegame where you want to copy the settings to, run the batch file (from the shell): - autobutcher.bat +another savegame you can export and then import them with ``list_export``: +To export them, open a terminal in the DF directory, and run +``dfhack-run autobutcher list_export > autobutcher.bat`` (or ``.sh`` on OSX or +Linux). To import, load your new save and run the script you created. autochop --------- @@ -1994,7 +2009,7 @@ Open the dashboard by running:: getplants autochop -The plugin must be activated (with 'a') before it can be used. You can then set logging quotas +The plugin must be activated (with ``c``) before it can be used. You can then set logging quotas and restrict designations to specific burrows (with 'Enter') if desired. The plugin's activity cycle runs once every in game day. @@ -2055,16 +2070,16 @@ Other jobs are automatically assigned as described above. Each of these setting Jobs are rarely assigned to nobles with responsibilities for meeting diplomats or merchants, never to the chief medical dwarf, and less often to the bookeeper and manager. -Hunting is never assigned without a butchery, and fishing is nver assigned without a fishery. +Hunting is never assigned without a butchery, and fishing is never assigned without a fishery. For each labor a preference order is calculated based on skill, biased against masters of other trades and excluding those who can't do the job. The labor is then added to the best dwarves for that labor. We assign at least the minimum number of dwarfs, in order of preference, and then assign additional dwarfs that meet any of these conditions: - * The dwarf is idle and there are no idle dwarves assigned to this labor - * The dwarf has nonzero skill associated with the labor - * The labor is mining, hunting, or woodcutting and the dwarf currently has it enabled. +* The dwarf is idle and there are no idle dwarves assigned to this labor +* The dwarf has non-zero skill associated with the labor +* The labor is mining, hunting, or woodcutting and the dwarf currently has it enabled. We stop assigning dwarfs when we reach the maximum allowed. @@ -2078,18 +2093,10 @@ twice. dfusion ------- -This is the DFusion lua plugin system by Warmist, running as a DFHack plugin. There are two parts to this plugin: an interactive script that shows a text based menu and lua modules. Some of the functionality of is intentionaly left out of the menu: +This is the DFusion system (a DFHack precursor) by Warmist, running as a DFHack +plugin. For detail on this legacy system, see the `Bay12 forums thread`_. -:Friendship: a binary plugin that allows multi race forts (to use make a script that imports plugins.dfusion.friendship and use Friendship:install{table} table should contain list of race names.) -:Embark: a binary plugin that allows multi race embark (to use make a script that imports plugins.dfusion.embark and use Embark:install{table} table should contain list of race names or list of pairs (race-name, caste_id)). - -See the bay12 thread for details: http://www.bay12forums.com/smf/index.php?topic=93317.0 - - -.. note:: - - * Some of the DFusion plugins aren't completely ported yet. This can lead to crashes. - * The game will be suspended while you're using dfusion. Don't panic when it doesn't respond. +.. _`Bay12 forums thread`: http://www.bay12forums.com/smf/index.php?topic=93317 embark-tools ------------ @@ -2201,7 +2208,8 @@ Scripts in this subdirectory fix various bugs and issues, some of them obscure. * fix/growth-bug - Fixes locally born units such that they will grow larger than their birth size. Note that this bug was fixed in DF version 0.40.02. + Fixes locally born units such that they will grow larger than their birth size. + Note that this bug was fixed in DF version 0.40.02. * fix/item-occupancy @@ -2235,7 +2243,7 @@ directory. * gui/stockpiles Load and save stockpile settings from the 'q' menu. - Usage: + Usage:: gui/stockpiles -save to save the current stockpile gui/stockpiles -load to load settings into the current stockpile @@ -2317,11 +2325,11 @@ deathcause ========== Focus a body part ingame, and this script will display the cause of death of the creature. -Also works when selecting units from the 'u'nitlist viewscreen. +Also works when selecting units from the (``u``) unitlist viewscreen. dfstatus ======== -Show a quick overview of critical stock quantities, including food, dirnks, wood, and various bars. +Show a quick overview of critical stock quantities, including food, drinks, wood, and various bars. exterminate =========== @@ -2344,7 +2352,7 @@ such as vampires, it also sets animal.vanish_countdown to 2. An alternate mode is selected by adding a 2nd argument to the command, ``magma``. In this case, a column of 7/7 magma is generated on top of the targets until they die (Warning: do not call on magma-safe creatures. Also, -using this mode on birds is not recommanded.) +using this mode on birds is not recommended.) Will target any unit on a revealed tile of the map, including ambushers, but ignore caged/chained creatures. @@ -2381,7 +2389,7 @@ same line. The syntax of the file itself is similar to digfort or quickfort. At present, only buildings constructed of an item with the same name as the building -are supported. All other characters are ignored. For example: +are supported. All other characters are ignored. For example:: `,`,d,`,` `,f,`,t,` @@ -2424,7 +2432,7 @@ two-across pit with stairs but no walls. hotkey-notes ============ -Lists the key, name, and jump position of your hotkeys. +Lists the key, name, and jump position of your hotkeys in the DFHack console. lever ===== @@ -2916,11 +2924,11 @@ work again. The existing issues are: * Even if assigned by the script, **the game will unassign the racks again without a binary patch**. This patch is called ``weaponrack-unassign``, and can be applied via - the binpatch program, or the matching script. See this for more info - about the bug: - http://www.bay12games.com/dwarves/mantisbt/view.php?id=1445 + the binpatch program, or the matching script. See `the bug report`_ for more info. + +.. _`the bug report`: http://www.bay12games.com/dwarves/mantisbt/view.php?id=1445 -* Haulers still take equpment stored in the armory away to the stockpiles, +* Haulers still take equipment stored in the armory away to the stockpiles, unless the ``fix-armory`` plugin above is used. The script interface simply lets you designate one of the squads that From 944ee2f53aa4baf4a8cea0717df068227093e0c6 Mon Sep 17 00:00:00 2001 From: Peridexis Errant Date: Mon, 16 Feb 2015 18:04:48 +1100 Subject: [PATCH 2/3] More readme clarification Fix DF version numbers. Make newlines at headings consistent. Consistent 4-space indentation where practical. Fix indented blocks. Remove duplicate sections. Minor editorial fixes. --- Readme.rst | 227 +++++++++++++++-------------------------------------- 1 file changed, 64 insertions(+), 163 deletions(-) diff --git a/Readme.rst b/Readme.rst index cf0cc45df..bab2fc9ad 100644 --- a/Readme.rst +++ b/Readme.rst @@ -5,7 +5,6 @@ DFHack Readme ============ Introduction ============ - DFHack is a Dwarf Fortress memory access library, distributed with scripts and plugins implementing a wide variety of useful functions and tools. @@ -32,7 +31,7 @@ Getting DFHack The project is currently hosted at http://www.github.com/ Recent releases are available in source and binary formats `on the releases -page`_, while the binaries for releases 40.15-r1 to 34.11-r4 are on DFFD_. +page`_, while the binaries for releases 0.40.15-r1 to 0.34.11-r4 are on DFFD_. Even older versions are available here_. .. _`on the releases page`: http://github.com/DFHack/dfhack/releases @@ -81,7 +80,6 @@ file created in your DF folder. Getting started =============== - If DFHack is installed correctly, it will automatically pop up a console window once DF is started as usual on windows. Linux and Mac OS X require running the dfhack script from the terminal, and will use that terminal for @@ -107,7 +105,6 @@ For more information, refer to the rest of this document. ============ Using DFHack ============ - DFHack basically extends what DF can do with something similar to the drop-down console found in Quake engine games. On Windows, this is a separate command line window. On linux, the terminal used to launch the dfhack script is taken over @@ -137,7 +134,6 @@ Most of the commands come from plugins. Those reside in 'hack/plugins/'. Patched binaries ================ - On linux and OSX, users of patched binaries may have to find the relevant section in symbols.xml, and add a new line with the checksum of their executable:: @@ -162,16 +158,13 @@ system console: The patches are expected to be encoded in text format used by IDA. - Live patching ------------- - As an alternative, you can use the ``binpatch`` dfhack command to apply/remove patches live in memory during a DF session. In this case, updating symbols.xml is not necessary. - ============================= Something doesn't work, help! ============================= @@ -200,7 +193,6 @@ modders use this to improve mobility of save games and compatibility of mods. Setting keybindings =================== - To set keybindings, use the built-in ``keybinding`` command. Like any other command it can be used at any time from the console, but it is also meaningful in the DFHack init file. @@ -239,7 +231,6 @@ for context ``foo/bar/baz``, possible matches are any of ``@foo/bar/baz``, ``@fo Enabling plugins ================ - Many plugins can be in a distinct enabled or disabled state. Some of them activate and deactivate automatically depending on the contents of the world raws. Others store their state in world data. However a @@ -256,11 +247,9 @@ arguments for the command:: enable manipulator search - ======== Commands ======== - DFHack command syntax consists of a command name, followed by arguments separated by whitespace. To include whitespace in an argument, quote it in double quotes. To include a double quote character, use ``\"`` inside double quotes. @@ -286,7 +275,6 @@ Almost all the commands support using the 'help ' built-in command to retrieve further help without having to look at this document. Alternatively, some accept a 'help'/'?' option on their command line. - Game progress ============= @@ -339,41 +327,33 @@ Toggle between displaying/not displaying liquid depth as numbers. stockpile settings management ----------------------------- - Save and load stockpile settings. See the gui/stockpiles for an in-game GUI to this plugin. copystock ~~~~~~~~~ - Copies the parameters of the currently highlighted stockpile to the custom stockpile settings and switches to custom stockpile placement mode, effectively allowing you to copy/paste stockpiles easily. savestock ~~~~~~~~~ - Saves the currently highlighted stockpile's settings to a file in your Dwarf Fortress folder. This file can be used to copy settings between game saves or players. -example: +example:: -``` -savestock food_settings.dfstock -``` + savestock food_settings.dfstock loadstock ~~~~~~~~~ - Loads a saved stockpile settings file and applies it to the currently selected stockpile. -example: +example:: -``` -loadstock food_settings.dfstock -``` + loadstock food_settings.dfstock To use savestock and loadstock, use the 'q' command to highlight a stockpile. Then run savestock giving it a descriptive filename. Then, in a different (or @@ -387,7 +367,6 @@ there or in a subfolder for easy access. Filenames should not have spaces. **Limitations:** Generated materials, divine metals, etc are not saved as they are different in every world. - rename ------ Allows renaming various things. @@ -460,8 +439,7 @@ Usage: advtools -------- -A package of different adventure mode tools (currently just one) - +A package of different adventure mode tools. Usage: @@ -479,7 +457,6 @@ Map modification 3dveins ------- - Removes all existing veins from the map and generates new ones using 3D Perlin noise, in order to produce a layout that smoothly flows between Z levels. The vein distribution is based on the world seed, so running @@ -685,7 +662,6 @@ settings in liquids were made it paints a point of 7/7 magma by default). Intended to be used as keybinding. Requires an active in-game cursor. - tiletypes --------- Can be used for painting map tiles and is an interactive command, much like @@ -765,7 +741,7 @@ You can use several different brushes for painting tiles: Example:: - range 10 10 1 + range 10 10 1 This will change the brush to a rectangle spanning 10x10 tiles on one z-level. The range starts at the position of the cursor and goes to the east, south and @@ -842,7 +818,6 @@ Options: :rain: make it rain. :clear: clear the sky. - Map inspection ============== @@ -912,7 +887,6 @@ Options: Pre-embark estimate ~~~~~~~~~~~~~~~~~~~ - If prospect is called during the embark selection screen, it displays an estimate of layer stone availability. @@ -1094,7 +1068,6 @@ Examples: * 'digcircle filled 3' = Dig a filled circle with diameter = 3. * 'digcircle' = Do it again. - digtype ------- For every tile on the map of the same vein type as the selected tile, this command designates it to have the same designation as the selected tile. If the selected tile has no designation, they will be dig designated. @@ -1191,7 +1164,6 @@ Options: Specifying both -t and -s will have no effect. If no plant IDs are specified, all valid plant IDs will be listed. - Cleanup and garbage disposal ============================ @@ -1259,8 +1231,6 @@ Example: This will confiscate rotten and dropped food, garbage on the floors and any worn items with 'X' damage and above. - - Bugfixes ======== @@ -1273,9 +1243,8 @@ fixdiplomats Up to version 0.31.12, Elves only sent Diplomats to your fortress to propose tree cutting quotas due to a bug; once that bug was fixed, Elves stopped caring about excess tree cutting. This command adds a Diplomat position to all Elven -civilizations, allowing them to negotiate tree cutting quotas (and allowing you -to violate them and potentially start wars) in case you haven't already modified -your raws accordingly. +civilizations, allowing them to negotiate tree cutting quotas - and you to +violate them and start wars. fixmerchants ------------ @@ -1447,19 +1416,17 @@ produce undesirable results. There are a few good ones though. .. admonition:: Example - You are in fort game mode, managing your fortress and paused. - You switch to the arena game mode, *assume control of a creature* and then - switch to adventure game mode(1). - You just lost a fortress and gained an adventurer. - You could also do this. - You are in fort game mode, managing your fortress and paused at the esc menu. - You switch to the adventure game mode, assume control of a creature, then save or retire. - You just created a returnable mountain home and gained an adventurer. - + You are in fort game mode, managing your fortress and paused. + You switch to the arena game mode, *assume control of a creature* and then + switch to adventure game mode(1). + You just lost a fortress and gained an adventurer. + You could also do this. + You are in fort game mode, managing your fortress and paused at the esc menu. + You switch to the adventure game mode, assume control of a creature, then save or retire. + You just created a returnable mountain home and gained an adventurer. I take no responsibility of anything that happens as a result of using this tool - Visualizer and data export ========================== @@ -1483,7 +1450,7 @@ releases are now done through DFHack. mapexport --------- Export the current loaded map as a file. This was used by visualizers for -DF 34.11, but is now basically obsolete. +DF 0.34.11, but is now basically obsolete. dwarfexport ----------- @@ -1522,7 +1489,6 @@ Options: If only region and name are given, all exports are performed. - Job management ============== @@ -1642,7 +1608,6 @@ in the game UI. Constraint format ~~~~~~~~~~~~~~~~~ - The constraint spec consists of 4 parts, separated with '/' characters:: ITEM[:SUBTYPE]/[GENERIC_MAT,...]/[SPECIFIC_MAT:...]/[LOCAL,] @@ -1673,7 +1638,6 @@ The subsequent parts are optional: Constraint examples ~~~~~~~~~~~~~~~~~~~ - Keep metal bolts within 900-1000, and wood/bone within 150-200:: workflow amount AMMO:ITEM_AMMO_BOLTS/METAL 1000 100 @@ -1807,7 +1771,6 @@ Filters: Usage with single units ~~~~~~~~~~~~~~~~~~~~~~~ - One convenient way to use the zone tool is to bind the command 'zone assign' to a hotkey, maybe also the command 'zone set'. Place the in-game cursor over a pen/pasture or pit, use 'zone set' to mark it. Then you can select units @@ -1817,7 +1780,6 @@ own dwarves, by the way. Usage with filters ~~~~~~~~~~~~~~~~~~ - All filters can be used together with the 'assign' command. Restrictions: It's not possible to assign units who are inside built cages @@ -1839,7 +1801,6 @@ Most filters can be negated (e.g. 'not grazer' -> race is not a grazer). Mass-renaming ~~~~~~~~~~~~~ - Using the 'nick' command you can set the same nickname for multiple units. If used without 'assign', 'all' or 'count' it will rename all units in the current default target zone. Combined with 'assign', 'all' or 'count' (and @@ -1847,7 +1808,6 @@ further optional filters) it will rename units matching the filter conditions. Cage zones ~~~~~~~~~~ - Using the 'tocages' command you can assign units to a set of cages, for example a room next to your butcher shop(s). They will be spread evenly among available cages to optimize hauling to and butchering from them. For this to work you need @@ -1859,7 +1819,6 @@ the usual filters. Examples ~~~~~~~~ - ``zone assign all own ALPACA minage 3 maxage 10`` Assign all own alpacas who are between 3 and 10 years old to the selected pasture. @@ -1906,22 +1865,18 @@ autobutcher Assigns lifestock for slaughter once it reaches a specific count. Requires that you add the target race(s) to a watch list. Only tame units will be processed. -Named units will be completely ignored (to protect specific animals from -autobutcher you can give them nicknames with the tool 'rename unit' for single -units or with 'zone nick' to mass-rename units in pastures and cages). - -Creatures trained for war or hunting will be ignored as well. - -Creatures assigned to cages will be ignored if the cage is defined as a room -(to avoid butchering unnamed zoo animals). - -Creatures who will not reproduce (because they're not interested in the opposite -sex or have been gelded) have first priority for butchering. +Units will be ignored if they are: +* Nicknamed (for custom protection; you can use the ``rename unit`` tool + individually, or ``zone nick` for groups) +* Caged, if and only if the cage is defined as a room (to protect zoos) +* Trained for war or hunting -Once you have too much adults, the oldest will be butchered first. -Once you have too much kids, the youngest will be butchered first. -If you don't set any target count the following default will be used: -1 male kid, 5 female kids, 1 male adult, 5 female adults. +Creatures who will not reproduce (because they're not interested in the +opposite sex or have been gelded) will be butchered before those who will. +Older adults and younger children will be butchered first if the population +is above the target (default 1 male, 5 female kids and adults). Note that +you may need to set a target above 1 to have a reliable breeding population +due to asexuality etc. Options: @@ -1985,10 +1940,9 @@ settings so that you can use 'unwatch' without the need to enter the values again. Note: 'autobutcher unwatch all' works, but only makes sense if you want to keep the plugin running with the 'autowatch' feature or manually add some new races with 'watch'. If you simply want to stop it completely use -'autobutcher stop' instead. -:: +'autobutcher stop' instead.:: - autobutcher unwatch ALPACA CAT + autobutcher unwatch ALPACA CAT **Note:** @@ -2007,21 +1961,19 @@ quotas. Open the dashboard by running:: - getplants autochop + getplants autochop The plugin must be activated (with ``c``) before it can be used. You can then set logging quotas and restrict designations to specific burrows (with 'Enter') if desired. The plugin's activity cycle runs once every in game day. -If you add -:: +If you add:: - enable getplants + enable getplants to your dfhack.init there will be a hotkey to open the dashboard from the chop designation menu. - autolabor --------- Automatically manage dwarf labors to efficiently complete jobs. @@ -2116,8 +2068,15 @@ Tools: petcapRemover ------------- - -This plugin allows you to remove or raise the pet population cap. In vanilla DF, pets will not reproduce unless the population is below 50 and the number of children of that species is below a certain percentage. This plugin allows removing the second restriction and removing or raising the first. Pets still require PET or PET_EXOTIC tags in order to reproduce. Type help petcapRemover for exact usage. In order to make population more stable and avoid sudden population booms as you go below the raised population cap, this plugin counts pregnancies toward the new population cap. It can still go over, but only in the case of multiple births. +This plugin allows you to remove or raise the pet population cap. In vanilla +DF, pets will not reproduce unless the population is below 50 and the number of +children of that species is below a certain percentage. This plugin allows +removing the second restriction and removing or raising the first. Pets still +require PET or PET_EXOTIC tags in order to reproduce. Type help petcapRemover +for exact usage. In order to make population more stable and avoid sudden +population booms as you go below the raised population cap, this plugin counts +pregnancies toward the new population cap. It can still go over, but only in the +case of multiple births. `petcapRemover` cause pregnancies now and schedule the next check @@ -2159,12 +2118,10 @@ log-region ---------- When enabled in dfhack.init, each time a fort is loaded identifying information will be written to the gamelog. Assists in parsing the file if you switch between forts, and adds information for story-building. - ======= Scripts ======= - -Lua or ruby scripts placed in the hack/scripts/ directory are considered for +Lua or ruby scripts placed in the ``hack/scripts/`` directory are considered for execution as if they were native DFHack commands. They are listed at the end of the 'ls' command output. @@ -2172,11 +2129,10 @@ Note: scripts in subdirectories of hack/scripts/ can still be called, but will only be listed by ls if called as 'ls -a'. This is intended as a way to hide scripts that are obscure, developer-oriented, or should be used as keybindings. -Some notable scripts: +The following scripts are distibuted with DFHack: fix/* ===== - Scripts in this subdirectory fix various bugs and issues, some of them obscure. * fix/blood-del @@ -2232,7 +2188,6 @@ Scripts in this subdirectory fix various bugs and issues, some of them obscure. gui/* ===== - Scripts that implement dialogs inserted into the main game window are put in this directory. @@ -2255,7 +2210,6 @@ the DF folder before trying to use this plugin. binpatch ======== - Checks, applies or removes binary patches directly in memory at runtime:: binpatch check/apply/remove @@ -2377,7 +2331,7 @@ Usage: fortplan [filename] Designates furniture for building according to a .csv file with quickfort-style syntax. Companion to digfort. -The first line of the file must contain the following: +The first line of the file must contain the following:: #build start(X; Y; ) @@ -2422,7 +2376,7 @@ Creates a pit to the underworld at the cursor. Takes three arguments: diameter of the pit in tiles, whether to wall off the pit, and whether to insert stairs. If no arguments are given, the default -is "hfs-pit 1 0 0", ie single-tile wide with no walls or stairs. +is "hfs-pit 1 0 0", ie single-tile wide with no walls or stairs.:: hfs-pit 4 0 1 hfs-pit 2 1 0 @@ -2466,7 +2420,6 @@ Examples:: lua === - There are the following ways to invoke this command: 1. ``lua`` (without any parameters) @@ -2516,7 +2469,6 @@ or '--all' for all items. quicksave ========= - If called in dwarf mode, makes DF immediately auto-save the game by setting a flag normally used in seasonal auto-save. @@ -2526,13 +2478,11 @@ Sets stress to -1,000,000; the normal range is 0 to 500,000 with very stable or setfps ====== - Run ``setfps `` to set the FPS cap at runtime, in case you want to watch combat in slow motion or something :) siren ===== - Wakes up sleeping units, cancels breaks and stops parties either everywhere, or in the burrows given as arguments. In return, adds bad thoughts about noise, tiredness and lack of protection. Also, the units with interrupted @@ -2541,7 +2491,6 @@ emergencies, e.g. when a siege appears, and all your military is partying. soundsense-season ================= - It is a well known issue that Soundsense cannot detect the correct current season when a savegame is loaded and has to play random season music until a season switch occurs. @@ -2626,8 +2575,18 @@ Undesignates building base materials for dumping. ======== modtools ======== - -These scripts are mostly useful for raw modders and scripters. They all have standard arguments: arguments are of the form ``tool -argName1 argVal1 -argName2 argVal2``. This is equivalent to ``tool -argName2 argVal2 -argName1 argVal1``. It is not necessary to provide a value to an argument name: ``tool -argName3`` is fine. Supplying the same argument name multiple times will result in an error. Argument names are preceded with a dash. The ``-help`` argument will print a descriptive usage string describing the nature of the arguments. For multiple word argument values, brackets must be used: ``tool -argName4 [ sadf1 sadf2 sadf3 ]``. In order to allow passing literal braces as part of the argument, backslashes are used: ``tool -argName4 [ \] asdf \foo ]`` sets ``argName4`` to ``\] asdf foo``. The ``*-trigger`` scripts have a similar policy with backslashes. +These scripts are mostly useful for raw modders and scripters. They all have +standard arguments: arguments are of the form ``tool -argName1 argVal1 +-argName2 argVal2``. This is equivalent to ``tool -argName2 argVal2 -argName1 +argVal1``. It is not necessary to provide a value to an argument name: ``tool +-argName3`` is fine. Supplying the same argument name multiple times will +result in an error. Argument names are preceded with a dash. The ``-help`` +argument will print a descriptive usage string describing the nature of the +arguments. For multiple word argument values, brackets must be used: ``tool +-argName4 [ sadf1 sadf2 sadf3 ]``. In order to allow passing literal braces as +part of the argument, backslashes are used: ``tool -argName4 [ \] asdf \foo ]`` +sets ``argName4`` to ``\] asdf foo``. The ``*-trigger`` scripts have a similar +policy with backslashes. * add-syndrome @@ -2704,7 +2663,6 @@ These scripts are mostly useful for raw modders and scripters. They all have sta ======================= In-game interface tools ======================= - These tools work by displaying dialogs or overlays in the game window, and are mostly implemented by lua scripts. @@ -2722,10 +2680,8 @@ are mostly implemented by lua scripts. All of these tools are disabled by default - in order to make them available, you must enable the plugins which provide them. - Dwarf Manipulator ================= - Implemented by the 'manipulator' plugin. To activate, open the unit screen and press 'l'. @@ -2778,10 +2734,8 @@ The following mouse shortcuts are also available: Pressing ESC normally returns to the unit screen, but Shift-ESC would exit directly to the main dwarf mode screen. - Search ====== - Implemented by the 'search' plugin. The search plugin adds search to the Stocks, Animals, Trading, Stockpile, @@ -2820,10 +2774,8 @@ on items actually shown in the rightmost list, so it is possible to select only fat or tallow by forbidding fats, then searching for fat/tallow, and using Permit Fats again while the list is filtered. - AutoMaterial ============ - Implemented by the 'automaterial' plugin. This makes building constructions (walls, floors, fortifications, etc) a little bit @@ -2871,7 +2823,6 @@ When autotrade is enabled for a stockpile, any items placed in it will be design Track Stop Menu =============== - The `q` menu of track stops is completely blank by default. To enable one:: enable trackstop @@ -2885,7 +2836,6 @@ It re-uses the keybindings from the track stop building interface: gui/advfort =========== - This script allows to perform jobs in adventure mode. For more complete help press '?' while script is running. It's most confortable to use this as a keybinding. (e.g. keybinding set Ctrl-T gui/advfort). Possible arguments: @@ -2909,7 +2859,6 @@ An example of player digging in adventure mode: gui/assign-rack =============== - Bind to a key (the example config uses P), and activate when viewing a weapon rack in the 'q' mode. @@ -2938,7 +2887,6 @@ of currently assigned racks for every valid squad. gui/choose-weapons ================== - Bind to a key (the example config uses Ctrl-W), and activate in the Equip->View/Customize page of the military screen. @@ -2952,7 +2900,6 @@ and may lead to inappropriate weapons being selected. gui/clone-uniform ================= - Bind to a key (the example config uses Ctrl-C), and activate in the Uniforms page of the military screen with the cursor in the leftmost list. @@ -2961,7 +2908,6 @@ and selects the newly created copy. gui/companion-order =================== - A script to issue orders for companions. Select companions with lower case chars, issue orders with upper case. Must be in look or talk mode to issue command on tile. @@ -2978,7 +2924,6 @@ case. Must be in look or talk mode to issue command on tile. gui/gm-editor ============= - There are three ways to open this editor: * using gui/gm-editor command/keybinding - opens editor on what is selected @@ -2997,7 +2942,6 @@ in-game help. Hotkeys ======= - Opens an in-game screen showing DFHack keybindings that are valid in the current mode. .. image:: images/hotkeys.png @@ -3007,19 +2951,6 @@ globally active hotkey in dfhack.init, e.g.:: keybinding add Ctrl-F1 hotkeys -Hotkeys -======= - -Opens an in-game screen showing DFHack keybindings that are valid in the current mode. - -.. image:: images/hotkeys.png - -Type ``hotkeys`` into the DFHack console to open the screen, or bind the command to a -globally active hotkey in dfhack.init, e.g.: - - ``keybinding add Ctrl-F1 hotkeys`` - - Stockpile Automation ==================== Enable the autodump plugin in your dfhack.init with @@ -3028,18 +2959,8 @@ Enable the autodump plugin in your dfhack.init with When querying a stockpile an option will appear to toggle autodump for this stockpile. Any items placed in this stockpile will be designated to be dumped. -Stockpile Automation -==================== -Enable the automelt plugin in your dfhack.init with - ``enable automelt`` - -When querying a stockpile an option will appear to toggle automelt for this stockpile. -Any items placed in this stockpile will be designated to be melted. - - gui/liquids =========== - To use, bind to a key (the example config uses Alt-L) and activate in the 'k' mode. .. image:: images/liquids.png @@ -3066,7 +2987,6 @@ After setting up the desired operations using the described keys, use ``Enter`` gui/mechanisms ============== - To use, bind to a key (the example config uses Ctrl-M) and activate in the 'q' mode. .. image:: images/mechanisms.png @@ -3080,15 +3000,17 @@ re-entering the mechanisms ui. gui/mod-manager =============== +A simple way to install and remove small mods. -A way to simply install and remove small mods. It looks for specially formatted mods in -df subfolder 'mods'. Mods are not included, for example mods see: `github mini mod repository `_ +It looks for specially formatted mods in df subfolder 'mods'. Mods are not +included, but some examples are `available here`_. + +.. _`available here`: https://github.com/warmist/df-mini-mods .. image:: images/mod-manager.png gui/rename ========== - Backed by the rename plugin, this script allows entering the desired name via a simple dialog in the game ui. @@ -3117,7 +3039,6 @@ unit profession change to Ctrl-Shift-T. gui/room-list ============= - To use, bind to a key (the example config uses Alt-R) and activate in the 'q' mode, either immediately or after opening the assign owner page. @@ -3126,10 +3047,8 @@ either immediately or after opening the assign owner page. The script lists other rooms owned by the same owner, or by the unit selected in the assign list, and allows unassigning them. - gui/guide-path ============== - Bind to a key (the example config uses Alt-P), and activate in the Hauling menu with the cursor over a Guide order. @@ -3140,7 +3059,6 @@ computes it when the order is executed for the first time. gui/workflow ============ - Bind to a key (the example config uses Alt-W), and activate with a job selected in a workshop in the 'q' mode. @@ -3202,7 +3120,6 @@ limit (maximum) and the dark green line is that minus the gap (minimum). gui/workshop-job ================ - Bind to a key (the example config uses Alt-A), and activate with a job selected in a workshop in the 'q' mode. @@ -3250,7 +3167,6 @@ you have to unset the material first. ============= Behavior Mods ============= - These plugins, when activated via configuration UI or by detecting certain structures in RAWs, modify the game engine behavior concerning the target objects to add features not otherwise present. @@ -3263,7 +3179,6 @@ objects to add features not otherwise present. Siege Engine ============ - The siege-engine plugin enables siege engines to be linked to stockpiles, and aimed at an arbitrary rectangular area across Z levels, instead of the original four directions. Also, catapults can be ordered to load arbitrary objects, not @@ -3271,7 +3186,6 @@ just stones. Rationale --------- - Siege engines are a very interesting feature, but sadly almost useless in the current state because they haven't been updated since 2D and can only aim in four directions. This is an attempt to bring them more up to date until Toady has time to work on it. Actual improvements, @@ -3279,7 +3193,6 @@ e.g. like making siegers bring their own, are something only Toady can do. Configuration UI ---------------- - The configuration front-end to the plugin is implemented by the gui/siege-engine script. Bind it to a key (the example config uses Alt-A) and activate after selecting a siege engine in 'q' mode. @@ -3306,10 +3219,8 @@ Exiting from the siege engine script via ESC reverts the view to the state prior the script. Shift-ESC retains the current viewport, and also exits from the 'q' mode to main menu. - Power Meter =========== - The power-meter plugin implements a modified pressure plate that detects power being supplied to gear boxes built in the four adjacent N/S/W/E tiles. @@ -3322,16 +3233,13 @@ in the build menu. The script follows the general look and feel of the regular pressure plate build configuration page, but configures parameters relevant to the modded power meter building. - Steam Engine ============ - The steam-engine plugin detects custom workshops with STEAM_ENGINE in their token, and turns them into real steam engines. Rationale --------- - The vanilla game contains only water wheels and windmills as sources of power, but windmills give relatively little power, and water wheels require flowing water, which must either be a real river and thus immovable and @@ -3344,7 +3252,6 @@ in a new way with some glue code and a bit of custom logic. Construction ------------ - The workshop needs water as its input, which it takes via a passable floor tile below it, like usual magma workshops do. The magma version also needs magma. @@ -3370,7 +3277,6 @@ is extracted from the workshop raws. Operation --------- - In order to operate the engine, queue the Stoke Boiler job (optionally on repeat). A furnace operator will come, possibly bringing a bar of fuel, and perform it. As a result, a "boiling water" item will appear @@ -3405,7 +3311,6 @@ use rate by 10%. Explosions ---------- - The engine must be constructed using barrel, pipe and piston from fire-safe, or in the magma version magma-safe metals. @@ -3416,7 +3321,6 @@ tantruming dwarf. Save files ---------- - It should be safe to load and view engine-using fortresses from a DF version without DFHack installed, except that in such case the engines won't work. However actually making modifications @@ -3425,10 +3329,8 @@ can easily result in inconsistent state once this plugin is available again. The effects may be as weird as negative power being generated. - Add Spatter =========== - This plugin makes reactions with names starting with ``SPATTER_ADD_`` produce contaminants on the items instead of improvements. The produced contaminants are immune to being washed away by water or destroyed by @@ -3439,4 +3341,3 @@ be bought from caravans. :) To be really useful this needs patches from bug 808, ``tweak fix-dimensions`` and ``tweak advmode-contained``. - From 7972aa2fbca0a764b26bf28139452655aea39ec0 Mon Sep 17 00:00:00 2001 From: lethosor Date: Mon, 16 Feb 2015 09:56:34 -0500 Subject: [PATCH 3/3] Fix syntax errors in Readme.rst --- Readme.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Readme.rst b/Readme.rst index bab2fc9ad..22b147944 100644 --- a/Readme.rst +++ b/Readme.rst @@ -1866,8 +1866,9 @@ Assigns lifestock for slaughter once it reaches a specific count. Requires that you add the target race(s) to a watch list. Only tame units will be processed. Units will be ignored if they are: + * Nicknamed (for custom protection; you can use the ``rename unit`` tool - individually, or ``zone nick` for groups) + individually, or ``zone nick`` for groups) * Caged, if and only if the cage is defined as a room (to protect zoos) * Trained for war or hunting @@ -3000,7 +3001,7 @@ re-entering the mechanisms ui. gui/mod-manager =============== -A simple way to install and remove small mods. +A simple way to install and remove small mods. It looks for specially formatted mods in df subfolder 'mods'. Mods are not included, but some examples are `available here`_.