From a091ba4a7078dda5fa1a470e6d112057a4ad024a Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Mon, 28 Sep 2015 11:11:11 +1000 Subject: [PATCH 01/91] Use .rst format for NEWS directly --- NEWS => NEWS.rst | 6 ++++++ README.rst | 2 +- docs/Changelog.rst | 7 ------- 3 files changed, 7 insertions(+), 8 deletions(-) rename NEWS => NEWS.rst (99%) delete mode 100644 docs/Changelog.rst diff --git a/NEWS b/NEWS.rst similarity index 99% rename from NEWS rename to NEWS.rst index 31525ef4d6..25cbb79706 100644 --- a/NEWS +++ b/NEWS.rst @@ -4,6 +4,12 @@ Items within each section are listed in alphabetical order to minimise merge conflicts. Try to match the style and level of detail of the other entries. +######### +Changelog +######### + +.. contents:: + DFHack Future ============= diff --git a/README.rst b/README.rst index 97ac6b36ed..e52d5dadc3 100644 --- a/README.rst +++ b/README.rst @@ -45,7 +45,7 @@ Other Contents: docs/Authors docs/Licenses - docs/Changelog + NEWS For Developers: diff --git a/docs/Changelog.rst b/docs/Changelog.rst deleted file mode 100644 index 9c2b4a3293..0000000000 --- a/docs/Changelog.rst +++ /dev/null @@ -1,7 +0,0 @@ -######### -Changelog -######### - -.. contents:: - -.. include:: ../NEWS From bd5eb82554579c7c74e6d5e8ba6544343d7f8401 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Mon, 19 Oct 2015 13:57:33 +1100 Subject: [PATCH 02/91] Get autodoc working properly. With a complete index, only generate needed files, etc. --- docs/3rdparty.rst | 12 ++++++++++++ docs/Scripts.rst | 11 +++++++++++ docs/conf.py.in | 26 +++++++++++++++----------- 3 files changed, 38 insertions(+), 11 deletions(-) create mode 100644 docs/3rdparty.rst diff --git a/docs/3rdparty.rst b/docs/3rdparty.rst new file mode 100644 index 0000000000..351f41699a --- /dev/null +++ b/docs/3rdparty.rst @@ -0,0 +1,12 @@ +###################### +Complete Scripts Index +###################### + +This is the complete index of documentation pulled from script source files. + +.. toctree:: + :glob: + :maxdepth: 2 + + /scripts/**include-all + diff --git a/docs/Scripts.rst b/docs/Scripts.rst index bb5f108f3d..cc3f0414ed 100644 --- a/docs/Scripts.rst +++ b/docs/Scripts.rst @@ -15,6 +15,17 @@ or from the init file. only be interrupted every 256 instructions. Use ``kill-lua force`` to interrupt the next instruction. +Here's an index to documentation pulled from script source files: + +.. toctree:: + :glob: + :maxdepth: 2 + + /docs/3rdparty/ + + +Here's the contents page for this document: + .. contents:: ================= diff --git a/docs/conf.py.in b/docs/conf.py.in index 7b915ddd01..cd23177204 100644 --- a/docs/conf.py.in +++ b/docs/conf.py.in @@ -14,32 +14,36 @@ # serve to show the default. import fnmatch -import io +from io import open import os import shlex import sys from os import listdir -from os.path import isfile, join, isdir +from os.path import isfile, join, isdir, relpath #import sys currentDir = '@CMAKE_CURRENT_SOURCE_DIR@' def makeIncludeAll(directory, extension): outputFile = join(directory,'include-all.rst') - #print(outputFile) files = [ f for f in listdir(directory) if isfile(join(directory,f)) and f.endswith(extension) ] files.sort() - out = open(outputFile, 'w') + dname = relpath(directory, relpath('..', currentDir)).replace('\\', '/') + while dname.startswith('..'): + dname = dname[3:] + TEMPLATE = '.. include:: /{}/{}\n :start-after: BEGIN_DOCS\n :end-before: END_DOCS' + out = [] for f in files: - #TODO: check if the file contains the BEGIN_DOCS string - #print(join(directory,f)) - fstream = io.open(join(directory,f), 'r', encoding='utf8') - data = fstream.read().replace('\n','') - fstream.close() + with open(join(directory,f), 'r', encoding='utf8') as fstream: + data = fstream.read().replace('\n','') if 'BEGIN_DOCS' in data: - out.write('.. include:: ' + join(directory,f) + '\n :start-after: BEGIN_DOCS\n :end-before: END_DOCS\n\n') - out.close() + out.append(TEMPLATE.format(dname, f)) + if out: + # Only write the file if the index is not empty + with open(outputFile, 'w') as outfile: + outfile.write(len(dname)*'=' + '\n' + dname + '\n' + len(dname)*'=' + '\n\n') + outfile.write('\n\n'.join(out)) def makeAllIncludeAll(directory, extension): for root, subdirs, files in os.walk(directory): From c5d6e693f87ac347d8372ef0194d5681ae07520c Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Mon, 19 Oct 2015 14:16:19 +1100 Subject: [PATCH 03/91] Use command name only for internal hyperlinks Because it's not actually that important to the user how a command is implemented, and the docs should reflect that. This also makes them easier to write! --- README.rst | 4 +- docs/Binpatches.rst | 8 ++-- docs/Contributing.rst | 6 +-- docs/Core.rst | 2 +- docs/Plugins.rst | 84 +++++++++++++++++++-------------------- docs/Scripts.rst | 88 ++++++++++++++++++++--------------------- scripts/add-thought.lua | 2 +- 7 files changed, 96 insertions(+), 98 deletions(-) diff --git a/README.rst b/README.rst index e52d5dadc3..801b7c7f22 100644 --- a/README.rst +++ b/README.rst @@ -8,11 +8,11 @@ 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 `plugins/workflow` or `plugins/autodump`) which can make life easier. +(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 ` +interactions, magic creature abilities, and more can be set through `modtools` 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. diff --git a/docs/Binpatches.rst b/docs/Binpatches.rst index 4ecdfa79b1..145dead898 100644 --- a/docs/Binpatches.rst +++ b/docs/Binpatches.rst @@ -7,7 +7,7 @@ Patching the DF binary Writing scripts and plugins for DFHack is not the only way to modify Dwarf Fortress. Before DFHack, it was common for tools to manually patch the binary to change behaviour, and DFHack still contains tools to do this via -the `scripts/binpatch` command. +the `binpatch` command. .. warning:: @@ -45,7 +45,7 @@ There are two methods to apply a patch. Patching at runtime ------------------- -The `scripts/binpatch` script checks, applies or removes binary patches +The `binpatch` script checks, applies or removes binary patches directly in memory at runtime:: binpatch [check|apply|remove] @@ -107,7 +107,7 @@ armor stands, and in containers. .. note:: In order to actually be used, weapon racks have to be patched and - manually assigned to a squad. See `scripts/gui/assign-rack`. + manually assigned to a squad. See `gui/assign-rack`. Note that the buildings in the armory are used as follows: @@ -171,7 +171,7 @@ work again. The existing issues are: .. _`the bug report`: http://www.bay12games.com/dwarves/mantisbt/view.php?id=1445 * Haulers still take equipment stored in the armory away to the stockpiles, - unless `plugins/fix-armory` is used. + unless `fix-armory` is used. The script interface simply lets you designate one of the squads that are assigned to the barracks/armory containing the selected stand as diff --git a/docs/Contributing.rst b/docs/Contributing.rst index a2c12c0877..c374a4b95c 100644 --- a/docs/Contributing.rst +++ b/docs/Contributing.rst @@ -158,12 +158,12 @@ describe the effect:: If it would be helpful to mention another DFHack command, don't just type the name - add a hyperlink! Specify the link target in backticks, and it will be -replaced with the corresponding title and linked: eg ```plugins/autolabor``` -=> `plugins/autolabor`. Link targets should be the path to the file +replaced with the corresponding title and linked: eg ```autolabor``` +=> `autolabor`. Link targets should be equivalent to the command described (without file extension), and placed above the heading of that section like this:: - .. _plugins/autolabor: + .. _autolabor: autolabor ========= diff --git a/docs/Core.rst b/docs/Core.rst index 4e20803117..d8e50431e9 100644 --- a/docs/Core.rst +++ b/docs/Core.rst @@ -112,7 +112,7 @@ However, bindings created this way are not automatically remembered between runs of the game, so it becomes necessary to use the dfhack.init file to ensure that they are re-created every time it is loaded. -Interactive commands like `plugins/liquids` cannot be used as hotkeys. +Interactive commands like `liquids` cannot be used as hotkeys. Many commands come from plugins, which are stored in ``hack/plugins/`` and must be compiled with the same version of DFHack. Others come diff --git a/docs/Plugins.rst b/docs/Plugins.rst index 77cdf6ed98..628006db31 100644 --- a/docs/Plugins.rst +++ b/docs/Plugins.rst @@ -18,7 +18,7 @@ Informative Plugins Visualizer and data export ========================== -.. _plugins/stonesense: +.. _stonesense: stonesense ---------- @@ -61,7 +61,7 @@ Options (If only region and name are given, export all): :place: Export stockpile commands to "-place.csv" :query: Export query commands to "-query.csv" -Goes very well with `plugins/fortplan`, for re-importing. +Goes very well with `fortplan`, for re-importing. Map inspection @@ -120,7 +120,7 @@ probe ----- Can be used to determine tile properties like temperature. -.. _plugins/prospect: +.. _prospect: prospect -------- @@ -148,7 +148,7 @@ Options: :all: Also estimate vein mineral amounts. -.. _plugins/reveal: +.. _reveal: reveal ------ @@ -248,7 +248,7 @@ Usage: :petcapRemover pregtime n: sets the pregnancy duration to n ticks. natural pregnancies are 300000 ticks for the current race and 200000 for everyone else -.. _plugins/tweak: +.. _tweak: tweak ===== @@ -328,7 +328,7 @@ Subcommands that persist until disabled or DF quits: :stable-cursor: Saves the exact cursor position between t/q/k/d/b/etc menus of fortress mode. :tradereq-pet-gender: Displays pet genders on the trade request screen -.. _plugins/fix-armory: +.. _fix-armory: fix-armory ========== @@ -501,7 +501,7 @@ furniture placement. You can then place furniture and other buildings before the required materials are available, and the job will be unsuspended when the item is created. -Very useful when combined with `plugins/workflow` - you can set a constraint +Very useful when combined with `workflow` - you can set a constraint to always have one or two doors/beds/tables/chairs/etc available, and place as many as you like. The plugins then take over and fulfill the orders, with minimal space dedicated to stockpiles. @@ -542,7 +542,7 @@ Usage:: mousequery [plugin] [rbutton] [track] [edge] [live] [enable|disable] -.. _plugins/resume: +.. _resume: resume ------ @@ -566,12 +566,12 @@ Toggle between displaying/not displaying liquid depth as numbers. stockpile management -------------------- -.. _plugins/stocksettings: +.. _stocksettings: import/export ~~~~~~~~~~~~~ The following commands allow you to save and load stockpile settings. -See `scripts/gui/stockpiles` for an in-game interface. +See `gui/stockpiles` for an in-game interface. :copystock: Copies the parameters of the currently highlighted stockpile to the custom stockpile settings and switches to custom stockpile placement mode, effectively @@ -609,11 +609,11 @@ designated to be taken to the Trade Depot whenever merchants are on the map. When autodump is enabled for a stockpile, any items placed in this stockpile will automatically be designated to be dumped. -.. _plugins/rename: +.. _rename: rename ------ -Allows renaming various things. Use `scripts/gui/rename` for an in-game interface. +Allows renaming various things. Use `gui/rename` for an in-game interface. Options: @@ -893,7 +893,7 @@ all valid plant IDs will be listed. Job and Fortress management =========================== -.. _plugins/autolabor: +.. _autolabor: autolabor ========= @@ -951,7 +951,7 @@ Advanced usage: :autolabor list: List current status of all labors. :autolabor status: Show basic status information. -See `scripts/autolabor-artisans` for a differently-tunde setup. +See `autolabor-artisans` for a differently-tunde setup. Examples: @@ -989,7 +989,7 @@ ALCHEMIST labor but can be changed by the user. Job management ============== -.. _plugins/job: +.. _job: job --- @@ -1060,13 +1060,13 @@ number of identical orders already in the queue. In fast mode, new work orders will be enqueued once per day, instead of waiting for the bookkeeper. -.. _plugins/workflow: +.. _workflow: workflow -------- Manage control of repeat jobs. -Check out `scripts/gui/workflow` for a simple front-end integrated +Check out `gui/workflow` for a simple front-end integrated in the game UI. Usage: @@ -1183,7 +1183,7 @@ Maintain 10-100 locally-made crafts of exceptional quality:: Cleanup and garbage disposal ============================ -.. _plugins/clean: +.. _clean: clean ----- @@ -1207,7 +1207,7 @@ spotclean Works like ``clean map snow mud``, but only for the tile under the cursor. Ideal if you want to keep that bloody entrance ``clean map`` would clean up. -.. _plugins/autodump: +.. _autodump: autodump -------- @@ -1360,7 +1360,7 @@ Examples: ``seedwatch all 30`` adds all plants from the abbreviation list to the watch list, the limit being 30. -.. _plugins/zone: +.. _zone: zone ---- @@ -1509,7 +1509,7 @@ Options: :sleep: Must be followed by number X. Changes the timer to sleep X frames between runs. -.. _plugins/autobutcher: +.. _autobutcher: autobutcher ----------- @@ -1518,8 +1518,8 @@ 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 `plugins/rename` ``unit`` tool - individually, or `plugins/zone` ``nick`` for groups) +* 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 @@ -1528,7 +1528,7 @@ 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. See `scripts/fix-ster` if this is a problem. +due to asexuality etc. See `fix-ster` if this is a problem. Options: @@ -1675,7 +1675,7 @@ the command for the second time should produce no change. It is best to run it just once immediately after embark. This command is intended as only a cosmetic change, so it takes -care to exactly preserve the mineral counts reported by `plugins/prospect` ``all``. +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. @@ -1692,7 +1692,7 @@ changes only the layer at the cursor position. Note that one layer can stretch across lots of z levels. By default changes only the geology which is linked to the biome under the cursor. That geology might be linked to other biomes as well, though. Mineral veins and gem clusters will stay on the map. Use -`plugins/changevein` for them. +`changevein` for them. tl;dr: You will end up with changing quite big areas in one go, especially if you use it in lower z levels. Use with care. @@ -1744,7 +1744,7 @@ Examples: Try reverting the changes manually or even better use an older savegame. You did save your game, right? -.. _plugins/changevein: +.. _changevein: changevein ========== @@ -1823,14 +1823,14 @@ Options: :show X: Marks the selected map feature as discovered. :hide X: Marks the selected map feature as undiscovered. -.. _plugins/fortplan: +.. _fortplan: fortplan ======== Usage: fortplan [filename] Designates furniture for building according to a .csv file with -quickfort-style syntax. Companion to `scripts/digfort`. +quickfort-style syntax. Companion to `digfort`. The first line of the file must contain the following:: @@ -1842,7 +1842,7 @@ is an optional description of where that is. You may also leave a description of the contents of the file itself following the closing parenthesis on the same line. -The syntax of the file itself is similar to `scripts/digfort` or +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:: @@ -1878,7 +1878,7 @@ Usage: cause cave-ins. Saving and loading after creating new z-levels should fix the problem. -.. _plugins/liquids: +.. _liquids: liquids ======= @@ -2138,7 +2138,7 @@ but do jobs at the same speed. :fastdwarf 0 1: disables speedydwarf and enables teledwarf :fastdwarf 1 1: enables both -.. _plugins/forceequip: +.. _forceequip: forceequip ========== @@ -2146,14 +2146,14 @@ Forceequip moves local items into a unit's inventory. It is typically used to equip specific clothing/armor items onto a dwarf, but can also be used to put armor onto a war animal or to add unusual items (such as crowns) to any unit. -For more information run ``forceequip help``. See also `scripts/modtools/equip-item`. +For more information run ``forceequip help``. See also `modtools/equip-item`. lair ==== This command allows you to mark the map as a monster lair, preventing item scatter on abandon. When invoked as ``lair reset``, it does the opposite. -Unlike `plugins/reveal`, this command doesn't save the information about tiles - you +Unlike `reveal`, this command doesn't save the information about tiles - you won't be able to restore state of real monster lairs using ``lair reset``. Options: @@ -2197,7 +2197,7 @@ Examples: * 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. -.. _plugins/strangemood: +.. _strangemood: strangemood =========== @@ -2227,7 +2227,7 @@ 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. -.. _plugins/siege-engine: +.. _siege-engine: Siege Engine ------------ @@ -2243,7 +2243,7 @@ just stones. Configuration UI ~~~~~~~~~~~~~~~~ -The configuration front-end to the plugin is implemented by `scripts/gui/siege-engine`. +The configuration front-end to the plugin is implemented by `gui/siege-engine`. Bind it to a key (the example config uses Alt-A) and activate after selecting a siege engine in ``q`` mode. @@ -2269,14 +2269,14 @@ 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. -.. _plugins/power-meter: +.. _power-meter: 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. -The configuration front-end is implemented by `scripts/gui/power-meter`. Bind it to a +The configuration front-end is implemented by `gui/power-meter`. Bind it to a key (the example config uses Ctrl-Shift-M) and activate after selecting Pressure Plate in the build menu. @@ -2384,11 +2384,11 @@ 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 -the `plugins/clean` ``items`` command. +the `clean` ``items`` command. The plugin is intended to give some use to all those poisons that can be bought from caravans. :) -To be really useful this needs patches from bug 808, `plugins/tweak` -``fix-dimensions`` and `plugins/tweak` ``advmode-contained``. +To be really useful this needs patches from bug 808, `tweak` +``fix-dimensions`` and `tweak` ``advmode-contained``. diff --git a/docs/Scripts.rst b/docs/Scripts.rst index cc3f0414ed..7cec3911d4 100644 --- a/docs/Scripts.rst +++ b/docs/Scripts.rst @@ -113,7 +113,7 @@ fix/stable-temp =============== Instantly sets the temperature of all free-lying items to be in equilibrium with the environment and stops temperature updates. In order to maintain this efficient -state however, use `plugins/tweak` ``stable-temp`` and `plugins/tweak` ``fast-heat``. +state however, use `tweak` ``stable-temp`` and `tweak` ``fast-heat``. fix/stuckdoors ============== @@ -162,7 +162,7 @@ gui/advfort_items ================= Does something with items in adventure mode jobs. -.. _scripts/gui/assign-rack: +.. _gui/assign-rack: gui/assign-rack =============== @@ -171,7 +171,7 @@ been available since DF 0.34.11 gui/autobutcher =============== -An in-game interface for `plugins/autobutcher`. +An in-game interface for `autobutcher`. gui/choose-weapons ================== @@ -210,7 +210,7 @@ case. Must be in look or talk mode to issue command on tile. * follow - rejoin the party after "wait" * leave - remove from party (can be rejoined by talking) -.. _scripts/gui/create-item: +.. _gui/create-item: gui/create-item =============== @@ -255,7 +255,7 @@ computes it when the order is executed for the first time. gui/hack-wish ============= -An alias for `scripts/gui/create-item`. Deprecated. +An alias for `gui/create-item`. Deprecated. gui/hello-world =============== @@ -267,7 +267,7 @@ To use, bind to a key (the example config uses Alt-L) and activate in the 'k' mo .. image:: images/liquids.png -This script is a gui front-end to `plugins/liquids` and works similarly, +This script is a gui front-end to `liquids` and works similarly, allowing you to add or remove water & magma, and create obsidian walls & floors. .. warning:: @@ -318,17 +318,17 @@ gui/no-dfhack-init ================== Shows a warning at startup if no valid ``dfhack.init`` file is found. -.. _scripts/gui/power-meter: +.. _gui/power-meter: gui/power-meter =============== -An in-game interface for `plugins/power-meter`. +An in-game interface for `power-meter`. -.. _scripts/gui/rename: +.. _gui/rename: gui/rename ========== -Backed by `plugins/rename`, this script allows entering the desired name +Backed by `rename`, this script allows entering the desired name via a simple dialog in the game ui. * ``gui/rename [building]`` in 'q' mode changes the name of a building. @@ -364,17 +364,17 @@ 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. -.. _scripts/gui/siege-engine: +.. _gui/siege-engine: gui/siege-engine ================ -An in-game interface for `plugins/siege-engine`. +An in-game interface for `siege-engine`. -.. _scripts/gui/stockpiles: +.. _gui/stockpiles: gui/stockpiles ============== -An in-game interface for `plugins/stocksettings`, to +An in-game interface for `stocksettings`, to load and save stockpile settings from the 'q' menu. Usage: @@ -392,7 +392,7 @@ gui/unit-info-viewer Displays age, birth, maxage, shearing, milking, grazing, egg laying, body size, and death info about a unit. Recommended keybinding Alt-I. -.. _scripts/gui/workflow: +.. _gui/workflow: gui/workflow ============ @@ -401,7 +401,7 @@ in a workshop in the 'q' mode. .. image:: images/workflow.png -This script provides a simple interface to constraints managed by `plugins/workflow`. +This script provides a simple interface to constraints managed by `workflow`. When active, it displays a list of all constraints applicable to the current job, and their current status. @@ -419,8 +419,8 @@ items and expanding the range each gives a 2x bonus). Pressing 'A' produces a list of possible outputs of this job as guessed by workflow, and lets you create a new constraint by choosing one as template. If you don't see the choice you want in the list, it likely means you have to adjust -the job material first using `plugins/job` ``item-material`` or `scripts/gui/workshop-job`, -as described in `plugins/workflow` documentation. In this manner, this feature +the job material first using `job` ``item-material`` or `gui/workshop-job`, +as described in `workflow` documentation. In this manner, this feature can be used for troubleshooting jobs that don't match the right constraints. .. image:: images/workflow-new1.png @@ -455,7 +455,7 @@ of stock history for the selected item, with the rightmost point representing the current stock value. The bright green dashed line is the target limit (maximum) and the dark green line is that minus the gap (minimum). -.. _scripts/gui/workshop-job: +.. _gui/workshop-job: gui/workshop-job ================ @@ -465,7 +465,7 @@ a workshop in the 'q' mode. .. image:: images/workshop-job.png The script shows a list of the input reagents of the selected job, and allows changing -them like the `plugins/job` ``item-type`` and `plugins/job` ``item-material`` commands. +them like the `job` ``item-type`` and `job` ``item-material`` commands. Specifically, pressing the 'i' key pops up a dialog that lets you select an item type from a list. @@ -503,7 +503,7 @@ material is matched against the barrel itself. Then, if you select, say, iron, and then try to change the input item type, now it won't let you select *plant*; you have to unset the material first. -.. _scripts/modtools: +.. _modtools: ======================== modtools/* - for modders @@ -544,14 +544,14 @@ modtools/create-unit ==================== Creates a unit. -.. _scripts/modtools/equip-item: +.. _modtools/equip-item: modtools/equip-item =================== Force a unit to equip an item; useful in conjunction with the ``create`` scripts above. -See also `plugins/forceequip`. +See also `forceequip`. modtools/force ============== @@ -631,8 +631,6 @@ Other Scripts ============= These scripts are not stored in any subdirectory, and can be invoked directly. -.. include:: ../scripts/include-all.rst - add-thought =========== Adds a thought or emotion to the selected unit. Can be used by other scripts, @@ -646,8 +644,8 @@ between 0 and 800,000 inclusive. armoks-blessing =============== -Runs the equivalent of `scripts/rejuvenate`, `scripts/elevate-physical`, -`scripts/elevate-mental`, and `scripts/brainwash` +Runs the equivalent of `rejuvenate`, `elevate-physical`, +`elevate-mental`, and `brainwash` on all dwarves currently on the map. This is an extreme change, which sets every stat to an ideal - legendary skills, great traits, and easy-to-satisfy preferences. Use in moderation; it's as 'cheaty' as DFHack gets. @@ -664,18 +662,18 @@ Usage:: autofarm default 30 autofarm threshold 150 helmet_plump tail_pig -.. _scripts/autolabor-artisans: +.. _autolabor-artisans: autolabor-artisans ================== -Runs `plugins/autolabor`, with settings tuned for small but highly skilled workforces. +Runs `autolabor`, with settings tuned for small but highly skilled workforces. -.. _scripts/autounsuspend: +.. _autounsuspend: autounsuspend ============= Automatically unsuspend jobs in workshops, on a recurring basis. -See `scripts/unsuspend` for one-off use, or `plugins/resume` ``all``. +See `unsuspend` for one-off use, or `resume` ``all``. ban-cooking =========== @@ -683,13 +681,13 @@ A more convenient way to ban cooking various categories of foods than the kitchen interface. Usage: ``ban-cooking ``. Valid types are ``booze``, ``honey``, ``tallow``, ``oil``, and ``seeds`` (non-tree plants with seeds). -.. _scripts/binpatch: +.. _binpatch: binpatch ======== Implements functions for in-memory binpatches. See `binpatches`. -.. _scripts/brainwash: +.. _brainwash: brainwash ========= @@ -747,7 +745,7 @@ dfusion ======= Interface to a lecacy script system. -.. _scripts/digfort: +.. _digfort: digfort ======= @@ -779,7 +777,7 @@ drain-aquifer ============= Remove all 'aquifer' tag from the map blocks. Irreversible. -.. _scripts/elevate-mental: +.. _elevate-mental: elevate-mental ============== @@ -787,7 +785,7 @@ Set all mental attributes of a dwarf to 2600, which is very high. Other numbers can be passed as an argument: ``elevate-mental 100`` for example would make the dwarf very stupid indeed. -.. _scripts/elevate-physical: +.. _elevate-physical: elevate-physical ================ @@ -853,7 +851,7 @@ fixnaked ======== Removes all unhappy thoughts due to lack of clothing. -.. _scripts/fix-ster: +.. _fix-ster: fix-ster ======== @@ -916,7 +914,7 @@ Lists the key, name, and jump position of your hotkeys in the DFHack console. item-descriptions ================= Exports a table with custom description text for every item in the game. -Used by `scripts/view-item-info`. +Used by `view-item-info`. lever ===== @@ -1063,7 +1061,7 @@ Usage: :region-pops incr-all : Same as above, but match using a pattern acceptable to list. -.. _scripts/rejuvenate: +.. _rejuvenate: rejuvenate ========== @@ -1080,7 +1078,7 @@ remove-wear =========== Sets the wear on all items in your fort to zero. -.. _scripts/repeat: +.. _repeat: repeat ====== @@ -1183,7 +1181,7 @@ The number must be 7 or greater. stripcaged ========== For dumping items inside cages. Will mark selected items for dumping, then -a dwarf may come and actually dump it. See also `plugins/autodump`. +a dwarf may come and actually dump it. See also `autodump`. With the ``items`` argument, only dumps items laying in the cage, excluding stuff worn by caged creatures. ``weapons`` will dump worn weapons, ``armor`` @@ -1226,14 +1224,14 @@ undump-buildings ================ Undesignates building base materials for dumping. -.. _scripts/unsuspend: +.. _unsuspend: unsuspend ========= -Unsuspend jobs in workshops, on a one-off basis. See `scripts/autounsuspend` +Unsuspend jobs in workshops, on a one-off basis. See `autounsuspend` for regular use. -.. _scripts/view-item-info: +.. _view-item-info: view-item-info ============== @@ -1250,6 +1248,6 @@ warn-starving ============= If any (live) units are starving, very thirsty, or very drowsy, the game will be paused and a warning shown and logged to the console. Use with the -`scripts/repeat` command for regular checks. +`repeat` command for regular checks. Use ``warn-starving all`` to display a list of all problematic units. diff --git a/scripts/add-thought.lua b/scripts/add-thought.lua index 27eec53228..7996e90095 100644 --- a/scripts/add-thought.lua +++ b/scripts/add-thought.lua @@ -4,7 +4,7 @@ --[[ BEGIN_DOCS -.. _scripts/add-thought +.. _add-thought: add-thought =========== From 18d2bc618335fa8e1c06cf154e57512c24e13af6 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Mon, 19 Oct 2015 14:59:35 +1100 Subject: [PATCH 04/91] Format 0.40.24-r3 changelog Including plenty of nice hyperlinks and a formatting which looks a lot better in HTML (but still decent in raw text, too). --- NEWS.rst | 148 ++++++++++++++++++++++++++++------------------- docs/Core.rst | 2 + docs/Lua API.rst | 4 ++ docs/Plugins.rst | 20 +++++++ docs/Scripts.rst | 10 ++++ 5 files changed, 126 insertions(+), 58 deletions(-) diff --git a/NEWS.rst b/NEWS.rst index 25cbb79706..ae37d9e909 100644 --- a/NEWS.rst +++ b/NEWS.rst @@ -4,11 +4,27 @@ Items within each section are listed in alphabetical order to minimise merge conflicts. Try to match the style and level of detail of the other entries. + Sections for each release are added as required, and consist solely of the + following in order as subheadings:: + + Internals + Lua + New [Internal Commands | Plugins | Scripts | Tweaks] + Fixes + Misc Improvements + Removed + + When referring to a script, plugin, or command, use backticks (```) to + create a link to the relevant documentation - and check that the docs are + still up to date! + + ######### Changelog ######### .. contents:: + :depth: 1 DFHack Future @@ -138,65 +154,81 @@ DFHack Future DFHack 0.40.24-r3 ================= -:: - Internals - Ruby library now included on OS X - ruby scripts should work on OS X 10.10 - libstdc++ should work with older versions of OS X - Added support for onLoadMap/onUnloadMap.init scripts - game type detection functions are now available in the World module - The DFHACK_LOG_MEM_RANGES environment variable can be used to log information to stderr.log on OS X - Fixed adventure mode menu names - Fixed command usage information for some commands - Lua - Lua scripts will only be reloaded if necessary - Added a df2console() wrapper, useful for printing DF (CP437-encoded) text to the console in a portable way - Added a strerror() wrapper - New internal commands - hide/show: hide and show the console on Windows - sc-script: Allows additional scripts to be run when certain events occur (similar to onLoad*.init scripts) - New plugins - autohauler: A hauling-only version of autolabor - New scripts - modtools/reaction-product-trigger: triggers callbacks when products are produced (contrast with when reactions complete) - New tweaks - fps-min: Fixes the in-game minimum FPS setting - shift-8-scroll: Gives Shift+8 (or *) priority when scrolling menus, instead of scrolling the map - tradereq-pet-gender: Displays pet genders on the trade request screen - New features - autolabor: A negative pool size can be specified to use the most unskilled dwarves - catsplosion: Works on any specified races - exportlegends: Now exports more information - Fixes - Fixed game type detection in: - 3dveins - createitem - reveal - seedwatch - Made PRELOAD_LIB more extensible on Linux - add-spatter, eventful: Fixed crash on world load - building-hacks: made buildings produce/consume correct amount of power - Gave add-thought a proper subthought arg. - fix-armory compiles and is available again (albeit with issues) - gui/gm-editor: Added search option (accessible with "s") - hack-wish: Made items stack properly. - modtools/skill-change: made level granularity work properly. - show-unit-syndromes should work - stockflow: Fixed error message in Arena mode - stockflow: No longer checks the DF version - stockflow: Fixed ballistic arrow head orders - stockflow: Now convinces the bookkeeper to update records more often - zone: Stopped crash when scrolling cage owner list - Misc Improvements - building-hacks: Added a way to allow building to work even if it consumes more power - than is available. Added setPower/getPower functions. - catsplosion: Can now trigger pregnancies in (most) other creatures - exportlegends: 'info' and 'all' exports legends_plus xml with more data for legends utilities - manipulator: - Added ability to edit nicknames/profession names - Added "Job" as a View Type, in addition to "Profession" and "Squad" - Custom profession templates, with masking - remotefortressreader: Exposes more information +Internals +--------- +- Ruby library now included on OSX - ruby scripts should work on OSX 10.10 +- libstdc++ should work with older versions of OS X +- Added support for ``onLoadMap.init``/``onUnloadMap.init`` scripts +- game type detection functions are now available in the World module +- The DFHACK_LOG_MEM_RANGES environment variable can be used to log information to ``stderr.log`` on OS X +- Fixed adventure mode menu names +- Fixed command usage information for some commands + +Lua +--- +- Lua scripts will only be reloaded if necessary +- Added a ``df2console()`` wrapper, useful for printing DF (CP437-encoded) text to the console in a portable way +- Added a ``strerror()`` wrapper + +New Internal Commands +--------------------- +- `hide, show`: hide and show the console on Windows +- sc-script: Allows additional scripts to be run when certain events occur (similar to onLoad*.init scripts) + +New Plugins +----------- +- `autohauler`: A hauling-only version of autolabor + +New Scripts +----------- +- `modtools/reaction-product-trigger`: triggers callbacks when products are produced (contrast with when reactions complete) + +New Tweaks +---------- +- `fps-min `: Fixes the in-game minimum FPS setting +- `shift-8-scroll `: Gives Shift+8 (or ``*``) priority when scrolling menus, instead of scrolling the map +- `tradereq-pet-gender `: Displays pet genders on the trade request screen + +Fixes +----- +- Fixed game type detection in `3dveins`, `gui/create-item`, `reveal`, `seedwatch` +- PRELOAD_LIB: More extensible on Linux +- `add-spatter`, `eventful`: Fixed crash on world load +- `add-thought`: Now has a proper subthought arg. +- `building-hacks`: Made buildings produce/consume correct amount of power +- `fix-armory`: compiles and is available again (albeit with issues) +- `gui/gm-editor`: Added search option (accessible with "s") +- `hack-wish `: Made items stack properly. +- `modtools/skill-change`: Made level granularity work properly. +- `show-unit-syndromes`: should work +- `stockflow`: + + - Fixed error message in Arena mode + - no longer checks the DF version + - fixed ballistic arrow head orders + - convinces the bookkeeper to update records more often' + +- `zone`: Stopped crash when scrolling cage owner list + +Misc Improvements +----------------- +- `autolabor`: A negative pool size can be specified to use the most unskilled dwarves +- `building-hacks`: + + - Added a way to allow building to work even if it consumes more power than is available. + - Added setPower/getPower functions. + +- `catsplosion`: Can now trigger pregnancies in (most) other creatures +- `exportlegends`: ``info`` and ``all`` options export ``legends_plus.xml`` with more data for legends utilities +- `manipulator`: + + - Added ability to edit nicknames/profession names + - added "Job" as a View Type, in addition to "Profession" and "Squad" + - added custom profession templates with masking + +- `remotefortressreader`: Exposes more information + DFHack 0.40.24-r2 ================= diff --git a/docs/Core.rst b/docs/Core.rst index d8e50431e9..6b9610afcd 100644 --- a/docs/Core.rst +++ b/docs/Core.rst @@ -294,6 +294,8 @@ forcepause Forces DF to pause. This is useful when your FPS drops below 1 and you lose control of the game. Activate with ``forcepause 1``; deactivate with ``forcepause 0``. +.. _`hide, show`: + hide / show ----------- Hides or shows the DFHack terminal window, respectively. To use ``show``, use diff --git a/docs/Lua API.rst b/docs/Lua API.rst index 0cee9a9dce..bb1a27b962 100644 --- a/docs/Lua API.rst +++ b/docs/Lua API.rst @@ -3247,6 +3247,8 @@ sort Does not export any native functions as of now. Instead, it calls lua code to perform the actual ordering of list items. +.. _eventful: + Eventful ======== @@ -3403,6 +3405,8 @@ Integrated tannery:: b=require "plugins.eventful" b.addReactionToShop("TAN_A_HIDE","LEATHERWORKS") +.. _building-hacks: + Building-hacks ============== diff --git a/docs/Plugins.rst b/docs/Plugins.rst index 628006db31..73128c081a 100644 --- a/docs/Plugins.rst +++ b/docs/Plugins.rst @@ -63,6 +63,12 @@ Options (If only region and name are given, export all): Goes very well with `fortplan`, for re-importing. +.. _remotefortressreader: + +remotefortressreader +==================== +An in-development plugin for realtime fortress visualisation. + Map inspection ============== @@ -348,6 +354,8 @@ UI Upgrades When that is not appropriate because they merely add keybinding hints to existing DF screens, they deliberately use red instead of green for the key. +.. _manipulator: + manipulator =========== An in-game equivalent to the popular program Dwarf Therapist. @@ -966,6 +974,8 @@ Examples: ``autolabor CUTWOOD disable`` Turn off autolabor for wood cutting. +.. _autohauler: + autohauler ---------- Rather than the all-of-the-above means of autolabor, autohauler will instead @@ -1030,6 +1040,8 @@ Duplicate the selected job in a workshop: * In 'q' mode, when a job is highlighted within a workshop or furnace building, instantly duplicates the job. +.. _stockflow: + stockflow --------- Allows the fortress bookkeeper to queue jobs through the manager, @@ -1332,6 +1344,8 @@ workNow ------- Force all dwarves to look for a job immediately, or as soon as the game is unpaused. +.. _seedwatch: + seedwatch --------- Watches the numbers of seeds available and enables/disables seed and plant cooking. @@ -1666,6 +1680,8 @@ A package of different adventure mode tools. Usage: Map modification ================ +.. _3dveins: + 3dveins ======= Removes all existing veins from the map and generates new ones using @@ -2091,6 +2107,8 @@ or 'snow', with those words as commands (eg ``weather rain``). Mods and Cheating ================= +.. _catsplosion: + catsplosion =========== Makes cats just *multiply*. It is not a good idea to run this more than once or @@ -2379,6 +2397,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: + add-spatter ----------- This plugin makes reactions with names starting with ``SPATTER_ADD_`` diff --git a/docs/Scripts.rst b/docs/Scripts.rst index 7cec3911d4..2bc2266e1d 100644 --- a/docs/Scripts.rst +++ b/docs/Scripts.rst @@ -221,6 +221,8 @@ gui/dfstatus Show a quick overview of critical stock quantities, including food, drinks, wood, and various bars. Sections can be enabled/disabled/configured by editing ``dfhack-config/dfstatus.lua``. +.. _gui/gm-editor: + gui/gm-editor ============= There are three ways to open this editor: @@ -594,6 +596,8 @@ modtools/random-trigger ======================= This triggers random dfhack commands with specified probabilities. +.. _modtools/reaction-product-trigger: + modtools/reaction-product-trigger ================================= This triggers dfhack commands when reaction products are produced, once per @@ -609,6 +613,8 @@ modtools/reaction-trigger-transition Scans raw files and creates a file to help modders transition from autoSyndrome to reaction-trigger. +.. _modtools/skill-change: + modtools/skill-change ===================== Sets or modifies a skill of a unit. @@ -792,6 +798,8 @@ elevate-physical As for elevate-mental, but for physical traits. High is good for soldiers, while having an ineffective hammerer can be useful too... +.. _exportlegends: + exportlegends ============= Controls legends mode to export data - especially useful to set-and-forget large @@ -1106,6 +1114,8 @@ setfps Run ``setfps `` to set the FPS cap at runtime, in case you want to watch combat in slow motion or something :) +.. _show-unit-syndromes: + show-unit-syndromes =================== Show syndromes affecting units and the remaining and maximum duration, along From fb2fdd0e89b90bcc2dd7b6dad659d735ed482fc4 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Tue, 20 Oct 2015 13:29:46 +1100 Subject: [PATCH 05/91] Format more of the NEWS file --- NEWS.rst | 427 ++++++++++++++++++++++++++--------------------- docs/Lua API.rst | 2 + docs/Plugins.rst | 24 +++ docs/Scripts.rst | 38 ++++- docs/conf.py.in | 2 +- 5 files changed, 302 insertions(+), 191 deletions(-) diff --git a/NEWS.rst b/NEWS.rst index ae37d9e909..471af4e0fa 100644 --- a/NEWS.rst +++ b/NEWS.rst @@ -24,7 +24,7 @@ Changelog ######### .. contents:: - :depth: 1 + :depth: 2 DFHack Future @@ -216,7 +216,7 @@ Misc Improvements - `autolabor`: A negative pool size can be specified to use the most unskilled dwarves - `building-hacks`: - - Added a way to allow building to work even if it consumes more power than is available. + - Added a way to allow building to work even if it consumes more power than is available. - Added setPower/getPower functions. - `catsplosion`: Can now trigger pregnancies in (most) other creatures @@ -232,140 +232,172 @@ Misc Improvements DFHack 0.40.24-r2 ================= -:: - Internals - Lua scripts can set environment variables of each other with dfhack.run_script_with_env. - Lua scripts can now call each others internal nonlocal functions with dfhack.script_environment(scriptName).functionName(arg1,arg2). - eventful Lua reactions no longer require LUA_HOOK as a prefix: you can register a - callback for the completion of any reaction with a name - Filesystem module now provides file access/modification times and can list directories (normally and recursively) - Units Module: New functions: - isWar - isHunter - isAvailableForAdoption - isOwnCiv - isOwnRace - getRaceName - getRaceNamePlural - getRaceBabyName - getRaceChildName - isBaby - isChild - isAdult - isEggLayer - isGrazer - isMilkable - isTrainableWar - isTrainableHunting - isTamable - isMale - isFemale - isMerchant - isForest - isMarkedForSlaughter - Buildings Module: New Functions: - isActivityZone - isPenPasture - isPitPond - isActive - findPenPitAt - Fixes - dfhack.run_script should correctly find save-specific scripts now. - Updated add-thought to properly affect stress. - hfs-pit should work now - Autobutcher takes gelding into account - init.lua existence checks should be more reliable (notably when using non-English locales) - Misc Improvements - Multiline commands are now possible inside dfhack.init scripts. See dfhack.init-example for example usage. +Internals +--------- +- Lua scripts can set environment variables of each other with dfhack.run_script_with_env. +- Lua scripts can now call each others internal nonlocal functions with dfhack.script_environment(scriptName).functionName(arg1,arg2). +- `eventful`: Lua reactions no longer require LUA_HOOK as a prefix; you can register a callback for the completion of any reaction with a name +- Filesystem module now provides file access/modification times and can list directories (normally and recursively) +- Units Module: New functions:: + + isWar + isHunter + isAvailableForAdoption + isOwnCiv + isOwnRace + getRaceName + getRaceNamePlural + getRaceBabyName + getRaceChildName + isBaby + isChild + isAdult + isEggLayer + isGrazer + isMilkable + isTrainableWar + isTrainableHunting + isTamable + isMale + isFemale + isMerchant + isForest + isMarkedForSlaughter + +- Buildings Module: New Functions:: + + isActivityZone + isPenPasture + isPitPond + isActive + findPenPitAt + +Fixes +----- +- ``dfhack.run_script`` should correctly find save-specific scripts now. +- `add-thought`: updated to properly affect stress. +- `hfs-pit`: should work now +- `autobutcher`: takes gelding into account +- init.lua existence checks should be more reliable (notably when using non-English locales) + +Misc Improvements +----------------- +Multiline commands are now possible inside dfhack.init scripts. See :file:`dfhack.init-example` for example usage. + DFHack 0.40.24-r1 ================= -:: - Internals - CMake shouldn't cache DFHACK_RELEASE anymore. People may need to manually update/delete - their CMake cache files to get rid of it. +Internals +--------- +CMake shouldn't cache DFHACK_RELEASE anymore. People may need to manually update/delete their CMake cache files to get rid of it. + DFHack 0.40.24-r0 ================= -:: - Internals - EventManager: fixed crash error with EQUIPMENT_CHANGE event. - key modifier state exposed to Lua - Fixes - dfhack script can now be run from other directories on OSX - New Plugins - blueprint: export part of your fortress to quickfort .csv files - New Scripts - hotkey-notes: print key, name, and jump position of hotkeys - Removed - embark.lua - needs_porting/* - Misc Improvements - added support for searching more lists +Internals +--------- +- `EventManager`: fixed crash error with EQUIPMENT_CHANGE event. +- key modifier state exposed to Lua (ie :kbd:`Ctrl`, :kbd:`Alt`, :kbd:`Shift`) + +Fixes +----- +``dfhack.sh`` can now be run from other directories on OSX + +New Plugins +----------- +- `blueprint`: export part of your fortress to quickfort .csv files + +New Scripts +----------- +- `hotkey-notes`: print key, name, and jump position of hotkeys + +Removed +------- +- embark.lua +- needs_porting/* + +Misc Improvements +----------------- +Added support for searching more lists + DFHack 0.40.23-r1 ================= -:: - Internals - plugins will not be loaded if globals they specify as required are not located (should prevent some crashes) - Fixes - Fixed numerous (mostly Lua-related) crashes on OS X by including a more up-to-date libstdc++ - Alt should no longer get stuck on Windows (and perhaps other platforms as well) - advfort works again - autobutcher takes sexualities into account - devel/export-dt-ini: Updated for 0.40.20+ - digfort: now checks file type and existence - exportlegends: Fixed map export - full-heal: Fixed a problem with selecting units in the GUI - gui/hack-wish: Fixed restrictive material filters - mousequery: Changed box-select key to Alt+M - plugins/dwarfmonitor: correct date display (month index, separator) - scripts/putontable: added to the readme - siren should work again - stderr.log: removed excessive debug output on OS X - trackstop: No longer prevents cancelling the removal of a track stop or roller. - Fixed a display issue with PRINT_MODE:TEXT - Fixed a symbol error (MapExtras::BiomeInfo::MAX_LAYERS) when compiling DFHack in Debug mode - New Plugins - fortplan: designate construction of (limited) buildings from .csv file, quickfort-style - New Scripts - gui/stockpiles: an in-game interface for saving and loading stockpile - settings files. - position: Reports the current date, time, month, and season, plus - some location info. Port/update of position.py - hfs-pit: Digs a hole to hell under the cursor. Replaces needs_porting/hellhole.cpp - Removed - embark.lua: Obsolete, use `embark-tools` - New tweaks: - eggs-fertile: Displays an egg fertility indicator on nestboxes - max-wheelbarrow: Allows assigning more than 3 wheelbarrows to a stockpile - Misc Improvements - embark-tools: Added basic mouse support on the local map - Made some adventure mode keybindings in dfhack.init-example only work in adventure mode - Added a default keybinding for "gui/companion-order" - further work on needs_porting +Internals +- plugins will not be loaded if globals they specify as required are not located (should prevent some crashes) + +Fixes +----- +- Fixed numerous (mostly Lua-related) crashes on OS X by including a more up-to-date libstdc++ +- :kbd:`Alt` should no longer get stuck on Windows (and perhaps other platforms as well) +- `gui/advfort` works again +- `autobutcher`: takes sexualities into account +- devel/export-dt-ini: Updated for 0.40.20+ +- `digfort`: now checks file type and existence +- `exportlegends`: Fixed map export +- `full-heal`: Fixed a problem with selecting units in the GUI +- `gui/hack-wish`: Fixed restrictive material filters +- `mousequery`: Changed box-select key to Alt+M +- `dwarfmonitor`: correct date display (month index, separator) +- `putontable`: added to the readme +- `siren` should work again +- stderr.log: removed excessive debug output on OS X +- `trackstop`: No longer prevents cancelling the removal of a track stop or roller. +- Fixed a display issue with ``PRINT_MODE:TEXT`` +- Fixed a symbol error (MapExtras::BiomeInfo::MAX_LAYERS) when compiling DFHack in Debug mode + +New Plugins +----------- +- `fortplan`: designate construction of (limited) buildings from .csv file, quickfort-style + +New Scripts +----------- +- `gui/stockpiles`: an in-game interface for saving and loading stockpile settings files. +- `position`: Reports the current date, time, month, and season, plus some location info. Port/update of position.py +- `hfs-pit`: Digs a hole to hell under the cursor. Replaces needs_porting/hellhole.cpp + +Removed +------- +- embark.lua: Obsolete, use `embark-tools` + +New tweaks +---------- +- `eggs-fertile `: Displays an egg fertility indicator on nestboxes +- `max-wheelbarrow `: Allows assigning more than 3 wheelbarrows to a stockpile + +Misc Improvements +----------------- +- `embark-tools`: Added basic mouse support on the local map +- Made some adventure mode keybindings in :file:`dfhack.init-example` only work in adventure mode +- `gui/companion-order`: added a default keybinding +- further work on needs_porting + DFHack 0.40.19-r1 ================= -:: - Fixes: - typo fix in modtools/reaction-trigger - modtools/item-trigger should now work with item types - New plugins: - savestock and loadstock: two commands for saving and loading - stockpile settings to a file. They can be used to migrate stockpile - settings between worlds and saves. - New scripts: - remove-stress [all]: set selected or all units unit to -1,000,000 stress - this script replaces removebadthoughts.rb - Misc improvements: - cmd-prompt can now access selected items, units, and buildings - autolabor plugin: add an optional talent pool parameter +Fixes +----- +- `modtools/reaction-trigger`: fixed typo +- `modtools/item-trigger`: should now work with item types + +New plugins +----------- +- `savestock, loadstock `: save and load stockpile settings across worlds and saves + +New scripts +----------- +- `remove-stress`: set selected or all units unit to -1,000,000 stress (this script replaces removebadthoughts) + +Misc improvements +----------------- +- `command-prompt`: can now access selected items, units, and buildings +- `autolabor`: add an optional talent pool parameter + DFHack 0.40.16-r1 ================= @@ -414,96 +446,113 @@ DFHack 0.40.16-r1 DFHack 0.40.15-r1 ================= -:: - Fixes: - - mousequery: Fixed behavior when selecting a tile on the lowest z-level - Internals: - - EventManager: deals with frame_counter getting reset properly now. - - modtools/item-trigger: fixed equip/unequip bug and corrected minor documentation error - - teleport: Updated with proper argument handling and proper unit-at-destination handling. - - autotrade: Removed the newly obsolete "Mark all" functionality. - - search: Adapts to the new trade screen column width - - tweak fast-trade: Switching the fast-trade keybinding to Shift-Up/Shift-Down, due to Select All conflict +Fixes +----- +- mousequery: Fixed behavior when selecting a tile on the lowest z-level + +Misc Improvements +----------------- +- `EventManager`: deals with frame_counter getting reset properly now. +- `modtools/item-trigger`: fixed equip/unequip bug and corrected minor documentation error +- `teleport`: Updated with proper argument handling and proper unit-at-destination handling. +- `autotrade `: Removed the newly obsolete :guilabel:`Mark all` functionality. +- `search`: Adapts to the new trade screen column width +- `tweak fast-trade `: Switching the fast-trade keybinding to Shift-Up/Shift-Down, due to Select All conflict + DFHack 0.40.14-r1 ================= -:: - Internals: - - The DFHack console can now be disabled by setting the DFHACK_DISABLE_CONSOLE - environment variable: "DFHACK_DISABLE_CONSOLE=1 ./dfhack" - Fixes: - - Stopped duplicate load/unload events when unloading a world - - Stopped "-e" from being echoed when DFHack quits on Linux - - automelt now uses a faster method to locate items - - autotrade: "Mark all" no longer double-marks bin contents - - drainaquifer.rb: replaced with a faster less buggy drain-aquifer.lua - - embark-tools no longer conflicts with keys on the notes screen - - fastdwarf: Fixed problems with combat/attacks - - forum-dwarves should work now - - manipulator now uses a stable sort, allowing sorting by multiple categories - - rendermax updated to work with 0.40 - New plugins: - - trackstop: Shows track stop friction and dump direction in its 'q' menu - New tweaks: - - farm-plot-select: Adds "Select all" and "Deselect all" options to farm plot menus - - import-priority-category: Allows changing the priority of all goods in a - category when discussing an import agreement with the liaison - - manager-quantity: Removes the limit of 30 jobs per manager order - - civ-view-agreement: Fixes overlapping text on the "view agreement" screen - - nestbox-color: Fixes the color of built nestboxes - Misc Improvements: - - exportlegends.lua can now handle site maps +Internals +--------- +- The DFHack console can now be disabled by setting the DFHACK_DISABLE_CONSOLE environment variable: ``DFHACK_DISABLE_CONSOLE=1 ./dfhack`` + +Fixes +----- +- Stopped duplicate load/unload events when unloading a world +- Stopped ``-e`` from being echoed when DFHack quits on Linux +- `automelt `: now uses a faster method to locate items +- `autotrade `: "Mark all" no longer double-marks bin contents +- `drain-aquifer`: new script replaces the buggy plugin +- `embark-tools`: no longer conflicts with keys on the notes screen +- `fastdwarf`: Fixed problems with combat/attacks +- `forum-dwarves`: should work now +- `manipulator`: now uses a stable sort, allowing sorting by multiple categories +- `rendermax`: updated to work with 0.40 + +New Plugins +----------- +- `trackstop`: Shows track stop friction and dump direction in its :kbd:`q` menu + +New Tweaks +---------- +- farm-plot-select: Adds "Select all" and "Deselect all" options to farm plot menus +- import-priority-category: Allows changing the priority of all goods in a category when discussing an import agreement with the liaison +- manager-quantity: Removes the limit of 30 jobs per manager order +- civ-view-agreement: Fixes overlapping text on the "view agreement" screen +- nestbox-color: Fixes the color of built nestboxes + +Misc Improvements +----------------- +- `exportlegends`: can now handle site maps + DFHack 0.40.13-r1 ================= -:: - Internals: - - unified spatter structs - - added ruby df.print_color(color, string) method for dfhack console - Fixes: - - no more -e after terminating - - fixed superdwarf +Internals +--------- +- unified spatter structs +- added ruby df.print_color(color, string) method for dfhack console + +Fixes +----- +- no more ``-e`` after terminating +- fixed `superdwarf` + DFHack 0.40.12-r1 ================= -:: - Fixes: - - possible crash fixed for hack-wish - - updated search to not conflict with BUILDJOB_SUSPEND - - workflow: job_material_category -> dfhack_material_category +Internals +--------- +- support for global :file:`onLoadWorld.init` and :file:`onUnloadWorld.init` files, called when loading and unloading a world +- Close file after loading a binary patch. - New plugins: - - hotkeys (by Falconne): Shows ingame viewscreen with all dfhack keybindings active in current mode. - - automelt: allows marking stockpiles for automelt - (i.e. any items placed in stocpile will be designated for melting) +New Plugins +----------- +- `hotkeys`: Shows ingame viewscreen with all dfhack keybindings active in current mode. +- `automelt `: allows marking stockpiles so any items placed in them will be designated for melting + +Fixes +----- +- possible crash fixed for `gui/hack-wish` +- `search`: updated to not conflict with BUILDJOB_SUSPEND +- `workflow`: job_material_category -> dfhack_material_category - Misc Improvements: - - now you can use @ to print things in interactive Lua with subtley different semantics - - optimizations for stockpiles for autotrade and stockflow - - updated exportlegends.lua to work with new maps, dfhack 40.11 r1+ +Misc Improvements +----------------- +- now you can use ``@`` to print things in interactive Lua with subtley different semantics +- optimizations for stockpiles for `autotrade ` and `stockflow` +- updated `exportlegends` to work with new maps, dfhack 40.11 r1+ - Internals: - - support for global onLoadWorld.init and onUnloadWorld.init files, - called when loading and unloading a world - - Close file after loading a binary patch. DFHack 0.40.11-r1 ================= -:: - Internals: - - Plugins on OS X now use ".plug.dylib" as an extension instead of ".plug.so" - Fixes: - - 3dveins should no longer hang/crash on specific maps - - Fixed some autotrade and search layout issues - - Updated deathcause - - hack-wish should work now - - reveal no longer allocates data for nonexistent map blocks - - Various documentation fixes and updates +Internals +- Plugins on OS X now use ``.plug.dylib` as an extension instead of ``.plug.so`` + +Fixes +----- +- `3dveins`: should no longer hang/crash on specific maps +- `autotrade `, `search`: fixed some layout issues +- `deathcause`: updated +- `gui/hack-wish`: should work now +- `reveal`: no longer allocates data for nonexistent map blocks +- Various documentation fixes and updates + DFHack v0.40.10-r1 ================== diff --git a/docs/Lua API.rst b/docs/Lua API.rst index bb1a27b962..e73bbb9e98 100644 --- a/docs/Lua API.rst +++ b/docs/Lua API.rst @@ -3291,6 +3291,8 @@ List of events Is called after calling (or not) native fillSidebarMenu(). Useful for job button tweaking (e.g. adding custom reactions) +.. _EventManager: + Events from EventManager ------------------------ These events are straight from EventManager module. Each of them first needs to be enabled. See functions for more info. If you register a listener before the game is loaded, be aware that no events will be triggered immediately after loading, so you might need to add another event listener for when the game first loads in some cases. diff --git a/docs/Plugins.rst b/docs/Plugins.rst index 73128c081a..2267fdea71 100644 --- a/docs/Plugins.rst +++ b/docs/Plugins.rst @@ -46,6 +46,8 @@ dwarfexport ----------- Export dwarves to RuneSmith-compatible XML; also unused by modern tools. +.. _blueprint: + blueprint --------- Exports a portion of your fortress into QuickFort style blueprint files.:: @@ -354,6 +356,12 @@ UI Upgrades When that is not appropriate because they merely add keybinding hints to existing DF screens, they deliberately use red instead of green for the key. +.. _hotkeys: + +hotkeys +======= +Shows the DFHack keybindings active on the current screen. + .. _manipulator: manipulator @@ -451,6 +459,8 @@ using Permit Fats again while the list is filtered. Game interface ============== +.. _embark-tools: + embark-tools ------------ A collection of embark-related tools. @@ -533,6 +543,8 @@ Makes the game view follow the currently highlighted unit after you exit from th current menu or cursor mode. Handy for watching dwarves running around. Deactivated by moving the view manually. +.. _mousequery: + mousequery ---------- Adds mouse controls to the DF interface, eg click-and-drag designations. @@ -561,6 +573,8 @@ tidlers ------- Toggle between all possible positions where the idlers count can be placed. +.. _trackstop: + trackstop --------- Adds a ``q`` menu for track stops, which is completely blank by default. @@ -602,6 +616,8 @@ Note that files are relative to the DF folder, so put your files there or in a subfolder for easy access. Filenames should not have spaces. Generated materials, divine metals, etc are not saved as they are different in every world. +.. _`Stockpile automation`: + Stockpile automation ~~~~~~~~~~~~~~~~~~~~ @@ -639,6 +655,8 @@ Options: The building must be one of stockpile, workshop, furnace, trap, siege engine or an activity zone. +.. _rendermax: + rendermax --------- A collection of renderer replacing/enhancing filters. For better effect try changing the @@ -1267,6 +1285,8 @@ Example: Fortress activity management ============================ +.. _dwarfmonitor: + dwarfmonitor ------------ Records dwarf activity to measure fort efficiency. @@ -2143,6 +2163,8 @@ Options: :building: Subsequent items will become part of the currently selected building. Good for loading traps; do not use with workshops (or deconstruct to use the item). +.. _fastdwarf: + fastdwarf ========= Controls speedydwarf and teledwarf. Speedydwarf makes dwarves move quickly @@ -2156,6 +2178,8 @@ but do jobs at the same speed. :fastdwarf 0 1: disables speedydwarf and enables teledwarf :fastdwarf 1 1: enables both +See `superdwarf` for a per-creature version. + .. _forceequip: forceequip diff --git a/docs/Scripts.rst b/docs/Scripts.rst index 2bc2266e1d..0b98da9cb6 100644 --- a/docs/Scripts.rst +++ b/docs/Scripts.rst @@ -135,6 +135,8 @@ directory. existing DF screens, they deliberately use red instead of green for the key. +.. _gui/advfort: + gui/advfort =========== This script allows to perform jobs in adventure mode. For more complete help @@ -194,6 +196,8 @@ page of the military screen with the cursor in the leftmost list. When invoked, the script duplicates the currently selected uniform template, and selects the newly created copy. +.. _gui/companion-order: + gui/companion-order =================== A script to issue orders for companions. Select companions with lower case chars, issue orders with upper @@ -255,6 +259,8 @@ the cursor over a Guide order. The script displays the cached path that will be used by the order; the game computes it when the order is executed for the first time. +.. _gui/hack-wish: + gui/hack-wish ============= An alias for `gui/create-item`. Deprecated. @@ -571,6 +577,8 @@ modtools/invader-item-destroyer This tool configurably destroys invader items to prevent clutter or to prevent the player from getting tools exclusive to certain races. +.. _modtools/item-trigger: + modtools/item-trigger ===================== This powerful tool triggers DFHack commands when a unit equips, unequips, or @@ -603,6 +611,8 @@ modtools/reaction-product-trigger This triggers dfhack commands when reaction products are produced, once per product. +.. _modtools/reaction-trigger: + modtools/reaction-trigger ========================= Triggers dfhack commands when custom reactions complete, regardless of whether @@ -706,6 +716,8 @@ burial Sets all unowned coffins to allow burial. ``burial -pets`` also allows burial of pets. +.. _command-prompt: + command-prompt ============== A one line command prompt in df. Same as entering command into dfhack console. Best @@ -741,6 +753,8 @@ Examples:: create-items bar CREATURE:CAT:SOAP create-items bar adamantine +.. _deathcause: + deathcause ========== Focus a body part ingame, and this script will display the cause of death of @@ -779,6 +793,8 @@ as an offset for the pattern: instead of starting at the cursor, it will start The script takes the plan filename, starting from the root df folder (where ``Dwarf Fortress.exe`` is found). +.. _drain-aquifer: + drain-aquifer ============= Remove all 'aquifer' tag from the map blocks. Irreversible. @@ -873,11 +889,15 @@ or sterile. Optional arguments specify the target: no argument for the selected unit, ``all`` for all units on the map, ``animals`` for all non-dwarf creatures, or ``only:`` to only process matching creatures. +.. _forum-dwarves: + forum-dwarves ============= Saves a copy of a text screen, formatted in bbcode for posting to the Bay12 Forums. Use ``forum-dwarves help`` for more information. +.. _full-heal: + full-heal ========= Attempts to fully heal the selected unit. ``full-heal -r`` attempts to resurrect the unit. @@ -901,6 +921,8 @@ For example, to grow 40 plump helmet spawn:: growcrops plump 40 +.. _hfs-pit: + hfs-pit ======= Creates a pit to the underworld at the cursor. @@ -915,6 +937,8 @@ is "hfs-pit 1 0 0", ie single-tile wide with no walls or stairs.:: First example is a four-across pit with stairs but no walls; second is a two-across pit with stairs but no walls. +.. _hotkey-notes: + hotkey-notes ============ Lists the key, name, and jump position of your hotkeys in the DFHack console. @@ -1021,6 +1045,8 @@ Sets available points at the embark screen to the specified number. Eg. ``points 1000000`` would allow you to buy everything, or ``points 0`` would make life quite difficult. +.. _position: + position ======== Reports the current time: date, clock time, month, and season. Also reports @@ -1038,6 +1064,8 @@ and ``pref-adjust`` inserts an 'ideal' set which is easy to satisfy:: prickle berries, plump helmets, strawberry wine, fisher berry wine, prickle berry wine, and dwarven wine. +.. _putontable: + putontable ========== Makes item appear on the table, like in adventure mode shops. Arguments: '-a' @@ -1076,6 +1104,8 @@ rejuvenate Set the age of the selected dwarf to 20 years. Useful if valuable citizens are getting old, or there are too many babies around... +.. _remove-stress: + remove-stress ============= Sets stress to -1,000,000; the normal range is 0 to 500,000 with very stable or @@ -1136,6 +1166,8 @@ Use one or more of the following options: :export: ``export:`` sends output to the given file, showing all syndromes affecting each unit with the maximum and present duration. +.. _siren: + siren ===== Wakes up sleeping units, cancels breaks and stops parties either everywhere, @@ -1208,9 +1240,11 @@ alternatively pass cage IDs as arguments:: stripcaged weapons 25321 34228 +.. _superdwarf: + superdwarf ========== -Similar to fastdwarf, per-creature. +Similar to `fastdwarf`, per-creature. To make any creature superfast, target it ingame using 'v' and:: @@ -1220,6 +1254,8 @@ Other options available: ``del``, ``clear``, ``list``. This script also shortens the 'sleeping' and 'on break' periods of targets. +.. _teleport: + teleport ======== Teleports a unit to given coordinates. diff --git a/docs/conf.py.in b/docs/conf.py.in index cd23177204..15e4490b1c 100644 --- a/docs/conf.py.in +++ b/docs/conf.py.in @@ -184,7 +184,7 @@ html_favicon = 'dfhack-icon.ico' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['../images'] +html_static_path = [] # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied From a305c40bb2507176caf638a6dabc246aa8f991da Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Tue, 20 Oct 2015 14:08:34 +1100 Subject: [PATCH 06/91] Finish formatting old NEWS --- NEWS.rst | 772 +++++++++++++++++++++++------------------------ docs/Plugins.rst | 8 + docs/Scripts.rst | 12 +- 3 files changed, 399 insertions(+), 393 deletions(-) diff --git a/NEWS.rst b/NEWS.rst index 471af4e0fa..304150e130 100644 --- a/NEWS.rst +++ b/NEWS.rst @@ -401,48 +401,38 @@ Misc improvements DFHack 0.40.16-r1 ================= -:: - Internals: - EventManager should handle INTERACTION triggers a little better. It still can get confused - about who did what but only rarely. - EventManager should no longer trigger REPORT events for old reports after loading a save. - lua/persist-table.lua: a convenient way of using persistent tables of arbitrary structure and dimension in Lua - Fixes: - mousequery: Disabled when linking levers - stocks: Melting should work now - scripts/full-heal: Updated with proper argument handling. - scripts/modtools/reaction-trigger-transition.lua - should produce the correct syntax now - scripts/superdwarf.rb should work better now - scripts/forum-dwarves.lua - update for new df-structures changes - New scripts: - scripts/ - adaptation.rb - view or set the cavern adaptation level of your citizens - add-thought.lua - allows the user to add thoughts to creatures. - gaydar.lua - detect the sexual orientation of units on the map - markdown.lua - Save a copy of a text screen in markdown (for reddit among others). - devel/ - all-bob.lua: renames everyone Bob to help test interaction-trigger - Misc improvements: - autodump: - Can now mark a stockpile for auto-dumping (similar to - automelt and autotrade) - buildingplan: - Can now auto-allocate rooms to dwarves with specific positions - (e.g. expedition leader, mayor) - dwarfmonitor - Now displays a weather indicator and date - lua/syndrome-util.lua - now you can remove syndromes by SYN_CLASS - scripts/modtools/add-syndrome.lua - now you can remove syndromes by SYN_CLASS - No longer writes empty .history files +Internals +--------- +- `EventManager` should handle INTERACTION triggers a little better. It still can get confused about who did what but only rarely. +- `EventManager` should no longer trigger REPORT events for old reports after loading a save. +- lua/persist-table: a convenient way of using persistent tables of arbitrary structure and dimension in Lua + +Fixes +----- +- `mousequery`: Disabled when linking levers +- `stocks`: Melting should work now +- `full-heal`: Updated with proper argument handling +- `modtools/reaction-trigger-transition`: should produce the correct syntax now +- `superdwarf`: should work better now +- `forum-dwarves`: update for new df-structures changes + +New Scripts +----------- +- `adaptation`: view or set the cavern adaptation level of your citizens +- `add-thought`: allows the user to add thoughts to creatures. +- `gaydar`: detect the sexual orientation of units on the map +- `markdown`: Save a copy of a text screen in markdown (for reddit among others). +- devel/all-bob: renames everyone Bob to help test interaction-trigger + +Misc Improvements +----------------- +- `autodump`: Can now mark a stockpile for auto-dumping (similar to automelt and autotrade) +- `buildingplan`: Can now auto-allocate rooms to dwarves with specific positions (e.g. expedition leader, mayor) +- `dwarfmonitor`: now displays a weather indicator and date +- lua/syndrome-util, `modtools/add-syndrome`: now you can remove syndromes by SYN_CLASS +- No longer write empty :file:`.history` files + DFHack 0.40.15-r1 ================= @@ -561,100 +551,64 @@ A few bugfixes. DFHack v0.40.08-r2 ================== -:: - Internals: - supported per save script folders - Items module: added createItem function - Sorted CMakeList for plugins and plugins/devel - diggingInvaders no longer builds if plugin building is disabled - EventManager: - EQUIPMENT_CHANGE now triggers for new units - new events: - ON_REPORT - UNIT_ATTACK - UNLOAD - INTERACTION - - New scripts: - lua/ - repeat-util.lua - makes it easier to make things repeat indefinitely - syndrome-util.lua - makes it easier to deal with unit syndromes - scripts/ - forum-dwarves.lua - helps copy df viewscreens to a file - full-heal.lua - fully heal a unit - remove-wear.lua - removes wear from all items in the fort - repeat.lua - repeatedly calls a script or a plugin - ShowUnitSyndromes.rb - shows syndromes affecting units and other relevant info - teleport.lua - teleports units - scripts/devel/ - print-args.lua - scripts/fix/ - blood-del.lua - makes it so civs don't bring barrels full of blood ichor or goo - feeding-timers.lua - reset the feeding timers of all units - scripts/gui/ - hack-wish.lua - creates items out of any material - unit-info-viewer.lua - displays information about units - scripts/modtools/ - add-syndrome.lua - add a syndrome to a unit or remove one - anonymous-script.lua - execute an lua script defined by a string. For example, - 'scripts/modtools/anonymous-script "print(args[2] .. args[1])" one two' - will print 'twoone'. Useful for the *-trigger scripts. - force.lua - forces events: caravan, migrants, diplomat, megabeast, curiousbeast, - mischievousbeast, flier, siege, nightcreature - item-trigger.lua - triggers commands based on equipping, unequipping, and wounding units with items - interaction-trigger.lua - triggers commands when interactions happen - invader-item-destroyer.lua - destroys invaders' items when they die - moddable-gods.lua - standardized version of Putnam's moddable gods script - outside-only.lua - register buildings as outside only or inside only - replaces outsideOnly plugin - projectile-trigger.lua - standardized version of projectileExpansion - reaction-trigger.lua - trigger commands when custom reactions complete - replaces autoSyndrome - reaction-trigger-transition.lua - a tool for converting mods from autoSyndrome to reaction-trigger - random-trigger.lua - triggers random scripts that you register - skill-change.lua - for incrementing and setting skills - spawn-flow.lua - creates flows, like mist or dragonfire - syndrome-trigger.lua - trigger commands when syndromes happen - transform-unit.lua - shapeshifts a unit, possibly permanently - - Misc improvements: - new function in utils.lua for standardized argument processing +Internals +--------- +- supported per save script folders +- Items module: added createItem function +- Sorted CMakeList for plugins and plugins/devel +- diggingInvaders no longer builds if plugin building is disabled +- `EventManager`: EQUIPMENT_CHANGE now triggers for new units. New events:: + + ON_REPORT + UNIT_ATTACK + UNLOAD + INTERACTION + +New Scripts +----------- +- lua/repeat-util: makes it easier to make things repeat indefinitely +- lua/syndrome-util: makes it easier to deal with unit syndromes +- forum-dwarves: helps copy df viewscreens to a file +- full-heal: fully heal a unit +- remove-wear: removes wear from all items in the fort +- repeat: repeatedly calls a script or a plugin +- ShowUnitSyndromes: shows syndromes affecting units and other relevant info +- teleport: teleports units +- devel/print-args +- fix/blood-del: makes it so civs don't bring barrels full of blood ichor or goo +- fix/feeding-timers: reset the feeding timers of all units +- gui/hack-wish: creates items out of any material +- gui/unit-info-viewer: displays information about units +- modtools/add-syndrome: add a syndrome to a unit or remove one +- modtools/anonymous-script: execute an lua script defined by a string. Useful for the ``*-trigger`` scripts. +- modtools/force: forces events: caravan, migrants, diplomat, megabeast, curiousbeast, mischievousbeast, flier, siege, nightcreature +- modtools/item-trigger: triggers commands based on equipping, unequipping, and wounding units with items +- modtools/interaction-trigger: triggers commands when interactions happen +- modtools/invader-item-destroyer: destroys invaders' items when they die +- modtools/moddable-gods: standardized version of Putnam's moddable gods script +- modtools/projectile-trigger: standardized version of projectileExpansion +- modtools/reaction-trigger: trigger commands when custom reactions complete; replaces autoSyndrome +- modtools/reaction-trigger-transition: a tool for converting mods from autoSyndrome to reaction-trigger +- modtools/random-trigger: triggers random scripts that you register +- modtools/skill-change: for incrementing and setting skills +- modtools/spawn-flow: creates flows, like mist or dragonfire +- modtools/syndrome-trigger: trigger commands when syndromes happen +- modtools/transform-unit: shapeshifts a unit, possibly permanently + +Misc improvements +----------------- +- new function in utils.lua for standardized argument processing + +Removed +------- +- digmat.rb: digFlood does the same functionality with less FPS impact +- scripts/invasionNow: scripts/modtools/force.lua does it better +- autoSyndrome replaced with scripts/modtools/reaction-trigger.lua +- syndromeTrigger replaced with scripts/modtools/syndrome-trigger.lua +- devel/printArgs plugin converted to scripts/devel/print-args.lua +- outsideOnly plugin replaced by modtools/outside-only - Removed - digmat.rb: digFlood does the same functionality with less FPS impact - scripts/invasionNow: scripts/modtools/force.lua does it better - autoSyndrome replaced with scripts/modtools/reaction-trigger.lua - syndromeTrigger replaced with scripts/modtools/syndrome-trigger.lua - devel/printArgs plugin converted to scripts/devel/print-args.lua DFHack v0.40.08-r1 ================== @@ -663,288 +617,322 @@ Was a mistake. Don't use it. DFHack v0.34.11-r5 ================== -:: - Internals: - - support for calling a lua function via a protobuf request (demonstrated by dfhack-run --lua). - - support for basic filesystem operations (e.g. chdir, mkdir, rmdir, stat) in C++ and Lua - - Lua API for listing files in directory. Needed for mod-manager. - - Lua API for creating unit combat reports and writing to gamelog. - - Lua API for running arbitrary DFHack commands - - support for multiple raw/init.d/*.lua init scripts in one save. - - eventful now has a more friendly way of making custom sidebars - - on Linux and OSX the console now supports moving the cursor back and forward by a whole word. - - New scripts: - - gui/mod-manager: allows installing/uninstalling mods into df from df/mods directory. - - gui/clone-uniform: duplicates the currently selected uniform in the military screen. - - fix/build-location: partial work-around for bug 5991 (trying to build wall while standing on it) - - undump-buildings: removes dump designation from materials used in buildings. - - exportlegends: exports data from legends mode, allowing a set-and-forget export of large worlds. - - log-region: each time a fort is loaded identifying information will be written to the gamelog. - - dfstatus: show an overview of critical stock quantities, including food, drinks, wood, and bars. - - New commands: - - 'plant create' - spawn a new shrub under the cursor - - command-prompt: a dfhack command prompt in df. - - New tweaks: - - craft-age-wear: make crafted items wear out with time like in old versions (bug 6003) - - adamantine-cloth-wear: stop adamantine clothing from wearing out (bug 6481) - - confirm-embark: adds a prompt before embarking (on the "prepare carefully" screen) - - New plugins: - - rendermax: replace the renderer with something else. Most interesting is "rendermax light"- a lighting engine for df. - - automelt: allows marking stockpiles for automelt (i.e. any items placed in stocpile will be designated for melting) - - embark-tools: implementations of Embark Anywhere, Nano Embark, and a few other embark-related utilities - - building-hacks: Allows to add custom functionality and/or animations to buildings. - - petcapRemover: triggers pregnancies in creatures so that you can effectively raise the default - pet population cap from the default 50 - - Misc improvements: - - plant: move the 'grow', 'extirpate' and 'immolate' commands as 'plant' subcommands - - digfort: improved csv parsing, add start() comment handling - - exterminate: allow specifying a caste (exterminate gob:male) - - createitem: in adventure mode it now defaults to the controlled unit as maker. - - autotrade: adds "(Un)mark All" options to both panes of trade screen. - - mousequery: several usability improvements. - - mousequery: show live overlay (in menu area) of what's on the tile under the mouse cursor. - - search: workshop profile search added. - - dwarfmonitor: add screen to summarise preferences of fortress dwarfs. - - getplants: add autochop function to automate woodcutting. - - stocks: added more filtering and display options. - - Siege engine plugin: +Internals +--------- +- support for calling a lua function via a protobuf request (demonstrated by dfhack-run --lua). +- support for basic filesystem operations (e.g. chdir, mkdir, rmdir, stat) in C++ and Lua +- Lua API for listing files in directory. Needed for mod-manager. +- Lua API for creating unit combat reports and writing to gamelog. +- Lua API for running arbitrary DFHack commands +- support for multiple ``raw/init.d/*.lua`` init scripts in one save. +- eventful now has a more friendly way of making custom sidebars +- on Linux and OSX the console now supports moving the cursor back and forward by a whole word. + +New scripts +----------- +- gui/mod-manager: allows installing/uninstalling mods into df from df/mods directory. +- gui/clone-uniform: duplicates the currently selected uniform in the military screen. +- fix/build-location: partial work-around for bug 5991 (trying to build wall while standing on it) +- undump-buildings: removes dump designation from materials used in buildings. +- exportlegends: exports data from legends mode, allowing a set-and-forget export of large worlds. +- log-region: each time a fort is loaded identifying information will be written to the gamelog. +- dfstatus: show an overview of critical stock quantities, including food, drinks, wood, and bars. +- command-prompt: a dfhack command prompt in df. + +New plugins +----------- +- rendermax: replace the renderer with something else, eg ``rendermax light``- a lighting engine +- automelt: allows marking stockpiles for automelt (i.e. any items placed in stocpile will be designated for melting) +- embark-tools: implementations of Embark Anywhere, Nano Embark, and a few other embark-related utilities +- building-hacks: Allows to add custom functionality and/or animations to buildings. +- petcapRemover: triggers pregnancies in creatures so that you can effectively raise the default pet population cap +- 'plant create': spawn a new shrub under the cursor + +New tweaks +---------- +- craft-age-wear: make crafted items wear out with time like in old versions (bug 6003) +- adamantine-cloth-wear: stop adamantine clothing from wearing out (bug 6481) +- confirm-embark: adds a prompt before embarking (on the "prepare carefully" screen) + +Misc improvements +----------------- +- plant: move the 'grow', 'extirpate' and 'immolate' commands as 'plant' subcommands +- digfort: improved csv parsing, add start() comment handling +- exterminate: allow specifying a caste (exterminate gob:male) +- createitem: in adventure mode it now defaults to the controlled unit as maker. +- autotrade: adds "(Un)mark All" options to both panes of trade screen. +- mousequery: several usability improvements. +- mousequery: show live overlay (in menu area) of what's on the tile under the mouse cursor. +- search: workshop profile search added. +- dwarfmonitor: add screen to summarise preferences of fortress dwarfs. +- getplants: add autochop function to automate woodcutting. +- stocks: added more filtering and display options. + +- Siege engine plugin: + - engine quality and distance to target now affect accuracy - firing the siege engine at a target produces a combat report - improved movement speed computation for meandering units - - operators in Prepare To Fire mode are released from duty once - hungry/thirsty if there is a free replacement + - operators in Prepare To Fire mode are released from duty once hungry/thirsty if there is a free replacement + DFHack v0.34.11-r4 ================== -:: - New commands: - - diggingInvaders - allows invaders to dig and/or deconstruct walls and buildings in order to get at your dwarves. - - digFlood - automatically dig out specified veins as they are revealed - - enable, disable - Built-in commands that can be used to enable/disable many plugins. - - restrictice - Restrict traffic on squares above visible ice. - - restrictliquid - Restrict traffic on every visible square with liquid. - - treefarm - automatically chop trees and dig obsidian - New scripts: - - autobutcher: A GUI front-end for the autobutcher plugin. - - invasionNow: trigger an invasion, or many - - locate_ore: scan the map for unmined ore veins - - masspit: designate caged creatures in a zone for pitting - - multicmd: run a sequence of dfhack commands, separated by ';' - - startdwarf: change the number of dwarves for a new embark - - digmat: dig veins/layers tile by tile, as discovered - Misc improvements: - - autoSyndrome: - disable by default - reorganized special tags - minimized error spam - reset policies: if the target already has an instance of the syndrome you can skip, - add another instance, reset the timer, or add the full duration to the time remaining - - core: fix SC_WORLD_(UN)LOADED event for arena mode - - exterminate: renamed from slayrace, add help message, add butcher mode - - fastdwarf: fixed bug involving fastdwarf and teledwarf being on at the same time - - magmasource: rename to 'source', allow water/magma sources/drains - - ruby: add df.dfhack_run "somecommand" - - syndromeTrigger: replaces and extends trueTransformation. Can trigger things when syndromes are added for any reason. - - tiletypes: support changing tile material to arbitrary stone. - - workNow: can optionally look for jobs when jobs are completed - New tweaks: - - hive-crash: Prevent crash if bees die in a hive with ungathered products (bug 6368). - New plugins: - - 3dveins: Reshapes all veins on the map in a way that flows between Z levels. May be unstable. Backup before using. - - autotrade: Automatically send items in marked stockpiles to trade depot, when trading is possible. - - buildingplan: Place furniture before it's built - - dwarfmonitor: Records dwarf activity to measure fort efficiency - - mousequery: Look and poke at the map elements with the mouse. - - outsideOnly: make raw-specified buildings impossible to build inside - - resume: A plugin to help display and resume suspended constructions conveniently - - stocks: An improved stocks display screen. - Internals: - - Core: there is now a per-save dfhack.init file for when the save is loaded, and another for when it is unloaded - - EventManager: fixed job completion detection, fixed removal of TICK events, added EQUIPMENT_CHANGE event - - Lua API for a better random number generator and perlin noise functions. - - Once: easy way to make sure something happens once per run of DF, such as an error message +New commands +------------ +- diggingInvaders - allows invaders to dig and/or deconstruct walls and buildings in order to get at your dwarves. +- digFlood - automatically dig out specified veins as they are revealed +- enable, disable - Built-in commands that can be used to enable/disable many plugins. +- restrictice - Restrict traffic on squares above visible ice. +- restrictliquid - Restrict traffic on every visible square with liquid. +- treefarm - automatically chop trees and dig obsidian + +New Scripts +----------- +- autobutcher: A GUI front-end for the autobutcher plugin. +- invasionNow: trigger an invasion, or many +- locate_ore: scan the map for unmined ore veins +- masspit: designate caged creatures in a zone for pitting +- multicmd: run a sequence of dfhack commands, separated by ';' +- startdwarf: change the number of dwarves for a new embark +- digmat: dig veins/layers tile by tile, as discovered + +Misc improvements +----------------- +- autoSyndrome: + + - disable by default + - reorganized special tags + - minimized error spam + - reset policies: if the target already has an instance of the syndrome you can skip, + add another instance, reset the timer, or add the full duration to the time remaining + +- core: fix SC_WORLD_(UN)LOADED event for arena mode +- exterminate: renamed from slayrace, add help message, add butcher mode +- fastdwarf: fixed bug involving fastdwarf and teledwarf being on at the same time +- magmasource: rename to ``source``, allow water/magma sources/drains +- ruby: add df.dfhack_run "somecommand" +- syndromeTrigger: replaces and extends trueTransformation. Can trigger things when syndromes are added for any reason. +- tiletypes: support changing tile material to arbitrary stone. +- workNow: can optionally look for jobs when jobs are completed + +New tweaks +---------- +- hive-crash: Prevent crash if bees die in a hive with ungathered products (bug 6368). + +New plugins +----------- +- 3dveins: Reshapes all veins on the map in a way that flows between Z levels. May be unstable. Backup before using. +- autotrade: Automatically send items in marked stockpiles to trade depot, when trading is possible. +- buildingplan: Place furniture before it's built +- dwarfmonitor: Records dwarf activity to measure fort efficiency +- mousequery: Look and poke at the map elements with the mouse. +- outsideOnly: make raw-specified buildings impossible to build inside +- resume: A plugin to help display and resume suspended constructions conveniently +- stocks: An improved stocks display screen. + +Internals +--------- +- Core: there is now a per-save dfhack.init file for when the save is loaded, and another for when it is unloaded +- EventManager: fixed job completion detection, fixed removal of TICK events, added EQUIPMENT_CHANGE event +- Lua API for a better random number generator and perlin noise functions. +- Once: easy way to make sure something happens once per run of DF, such as an error message + DFHack v0.34.11-r3 ================== -:: - Internals: - - support for displaying active keybindings properly. - - support for reusable widgets in lua screen library. - - Maps::canStepBetween: returns whether you can walk between two tiles in one step. - - EventManager: monitors various in game events centrally so that individual plugins - don't have to monitor the same things redundantly. - - Now works with OSX 10.6.8 - Notable bugfixes: - - autobutcher can be re-enabled again after being stopped. - - stopped Dwarf Manipulator from unmasking vampires. - - Stonesense is now fixed on OSX - Misc improvements: - - fastdwarf: new mode using debug flags, and some internal consistency fixes. - - added a small stand-alone utility for applying and removing binary patches. - - removebadthoughts: add --dry-run option - - superdwarf: work in adventure mode too - - tweak stable-cursor: carries cursor location from/to Build menu. - - deathcause: allow selection from the unitlist screen - - slayrace: allow targetting undeads - New tweaks: - - tweak military-training: speed up melee squad training up to 10x (normally 3-5x). - New scripts: - - binpatch: the same as the stand-alone binpatch.exe, but works at runtime. - - region-pops: displays animal populations of the region and allows tweaking them. - - lua: lua interpreter front-end converted to a script from a native command. - - dfusion: misc scripts with a text based menu. - - embark: lets you embark anywhere. - - lever: list and pull fort levers from the dfhack console. - - stripcaged: mark items inside cages for dumping, eg caged goblin weapons. - - soundsense-season: writes the correct season to gamelog.txt on world load. - - create-items: spawn items - - fix/cloth-stockpile: fixes bug 5739; needs to be run after savegame load every time. - New GUI scripts: - - gui/guide-path: displays the cached path for minecart Guide orders. - - gui/workshop-job: displays inputs of a workshop job and allows tweaking them. - - gui/workflow: a front-end for the workflow plugin (part inspired by falconne). - - gui/assign-rack: works together with a binary patch to fix weapon racks. - - gui/gm-editor: an universal editor for lots of dfhack things. - - gui/companion-order: a adventure mode command interface for your companions. - - gui/advfort: a way to do jobs with your adventurer (e.g. build fort). - New binary patches (for use with binpatch): - - armorstand-capacity: doubles the capacity of armor stands. - - custom-reagent-size: lets custom reactions use small amounts of inputs. - - deconstruct-heapfall: stops some items still falling on head when deconstructing. - - deconstruct-teleport: stops items from 16x16 block teleporting when deconstructing. - - hospital-overstocking: stops hospital overstocking with supplies. - - training-ammo: lets dwarves with quiver full of combat-only ammo train. - - weaponrack-unassign: fixes bug that negates work done by gui/assign-rack. - Workflow plugin: +Internals +--------- +- support for displaying active keybindings properly. +- support for reusable widgets in lua screen library. +- Maps::canStepBetween: returns whether you can walk between two tiles in one step. +- EventManager: monitors various in game events centrally so that individual plugins + don't have to monitor the same things redundantly. +- Now works with OSX 10.6.8 + +Notable bugfixes +---------------- +- autobutcher can be re-enabled again after being stopped. +- stopped Dwarf Manipulator from unmasking vampires. +- Stonesense is now fixed on OSX + +Misc improvements +----------------- +- fastdwarf: new mode using debug flags, and some internal consistency fixes. +- added a small stand-alone utility for applying and removing binary patches. +- removebadthoughts: add --dry-run option +- superdwarf: work in adventure mode too +- tweak stable-cursor: carries cursor location from/to Build menu. +- deathcause: allow selection from the unitlist screen +- slayrace: allow targetting undeads +- Workflow plugin: + - properly considers minecarts assigned to routes busy. - code for deducing job outputs rewritten in lua for flexibility. - logic fix: collecting webs produces silk, and ungathered webs are not thread. - items assigned to squads are considered busy, even if not in inventory. - shearing and milking jobs are supported, but only with generic MILK or YARN outputs. - workflow announces when the stock level gets very low once a season. - New Fix Armory plugin: - Together with a couple of binary patches and the gui/assign-rack script, - this plugin makes weapon racks, armor stands, chests and cabinets in - properly designated barracks be used again for storage of squad equipment. - New Search plugin by falconne: - Adds an incremental search function to the Stocks, Trading, Stockpile and Unit List screens. - New AutoMaterial plugin by falconne: - Makes building constructions (walls, floors, fortifications, etc) a little bit easier by - saving you from having to trawl through long lists of materials each time you place one. - Dfusion plugin: - Reworked to make use of lua modules, now all the scripts can be used from other scripts. - New Eventful plugin: - A collection of lua events, that will allow new ways to interact with df world. - Auto syndrome plugin: - A way of automatically applying boiling rock syndromes and calling dfhack commands controlled by raws. - Infinite sky plugin: - Create new z-levels automatically or on request. - True transformation plugin: - A better way of doing permanent transformations that allows later transformations. - Work now plugin: - Makes the game assign jobs every time you pause. + +- Auto syndrome plugin: A way of automatically applying boiling rock syndromes and calling dfhack commands controlled by raws. +- Infinite sky plugin: Create new z-levels automatically or on request. +- True transformation plugin: A better way of doing permanent transformations that allows later transformations. +- Work now plugin: Makes the game assign jobs every time you pause. + +New tweaks +---------- +- tweak military-training: speed up melee squad training up to 10x (normally 3-5x). + +New scripts +----------- +- binpatch: the same as the stand-alone binpatch.exe, but works at runtime. +- region-pops: displays animal populations of the region and allows tweaking them. +- lua: lua interpreter front-end converted to a script from a native command. +- dfusion: misc scripts with a text based menu. +- embark: lets you embark anywhere. +- lever: list and pull fort levers from the dfhack console. +- stripcaged: mark items inside cages for dumping, eg caged goblin weapons. +- soundsense-season: writes the correct season to gamelog.txt on world load. +- create-items: spawn items +- fix/cloth-stockpile: fixes bug 5739; needs to be run after savegame load every time. + +New GUI scripts +--------------- +- gui/guide-path: displays the cached path for minecart Guide orders. +- gui/workshop-job: displays inputs of a workshop job and allows tweaking them. +- gui/workflow: a front-end for the workflow plugin (part inspired by falconne). +- gui/assign-rack: works together with a binary patch to fix weapon racks. +- gui/gm-editor: an universal editor for lots of dfhack things. +- gui/companion-order: a adventure mode command interface for your companions. +- gui/advfort: a way to do jobs with your adventurer (e.g. build fort). + +New binary patches +------------------ +(for use with binpatch) + +- armorstand-capacity: doubles the capacity of armor stands. +- custom-reagent-size: lets custom reactions use small amounts of inputs. +- deconstruct-heapfall: stops some items still falling on head when deconstructing. +- deconstruct-teleport: stops items from 16x16 block teleporting when deconstructing. +- hospital-overstocking: stops hospital overstocking with supplies. +- training-ammo: lets dwarves with quiver full of combat-only ammo train. +- weaponrack-unassign: fixes bug that negates work done by gui/assign-rack. + +New Plugins +----------- +- fix-armory: Together with a couple of binary patches and the gui/assign-rack script, this plugin makes weapon racks, armor stands, chests and cabinets in properly designated barracks be used again for storage of squad equipment. +- search: Adds an incremental search function to the Stocks, Trading, Stockpile and Unit List screens. +- automaterial: Makes building constructions (walls, floors, fortifications, etc) a little bit easier by saving you from having to trawl through long lists of materials each time you place one. +- Dfusion: Reworked to make use of lua modules, now all the scripts can be used from other scripts. +- Eventful: A collection of lua events, that will allow new ways to interact with df world. DFHack v0.34.11-r2 ================== -:: - Internals: - - full support for Mac OS X. - - a plugin that adds scripting in ruby. - - support for interposing virtual methods in DF from C++ plugins. - - support for creating new interface screens from C++ and lua. - - added various other API functions. - Notable bugfixes: - - better terminal reset after exit on linux. - - seedwatch now works on reclaim. - - the sort plugin won't crash on cages anymore. - Misc improvements: - - autodump: can move items to any walkable tile, not just floors. - - stripcaged: by default keep armor, new dumparmor option. - - zone: allow non-domesticated birds in nestboxes. - - workflow: quality range in constraints. - - cleanplants: new command to remove rain water from plants. - - liquids: can paint permaflow, i.e. what makes rivers power water wheels. - - prospect: pre-embark prospector accounts for caves & magma sea in its estimate. - - rename: supports renaming stockpiles, workshops, traps, siege engines. - - fastdwarf: now has an additional option to make dwarves teleport to their destination. - New commands: - - misery: multiplies every negative thought gained (2x by default). - - digtype: designates every tile of the same type of vein on the map for 'digging' (any dig designation). - New tweaks: - - tweak stable-cursor: keeps exact cursor position between d/k/t/q/v etc menus. - - tweak patrol-duty: makes Train orders reduce patrol timer, like the binary patch does. - - tweak readable-build-plate: fix unreadable truncation in unit pressure plate build ui. - - tweak stable-temp: fixes bug 6012; may improve FPS by 50-100% on a slow item-heavy fort. - - tweak fast-heat: speeds up item heating & cooling, thus making stable-temp act faster. - - tweak fix-dimensions: fixes subtracting small amounts from stacked liquids etc. - - tweak advmode-contained: fixes UI bug in custom reactions with container inputs in advmode. - - tweak fast-trade: Shift-Enter for selecting items quckly in Trade and Move to Depot screens. - - tweak military-stable-assign: Stop rightmost list of military->Positions from jumping to top. - - tweak military-color-assigned: In same list, color already assigned units in brown & green. - New scripts: - - fixnaked: removes thoughts about nakedness. - - setfps: set FPS cap at runtime, in case you want slow motion or speed-up. - - siren: wakes up units, stops breaks and parties - but causes bad thoughts. - - fix/population-cap: run after every migrant wave to prevent exceeding the cap. - - fix/stable-temp: counts items with temperature updates; does instant one-shot stable-temp. - - fix/loyaltycascade: fix units allegiance, eg after ordering a dwarf merchant kill. - - deathcause: shows the circumstances of death for a given body. - - digfort: designate areas to dig from a csv file. - - drainaquifer: remove aquifers from the map. - - growcrops: cheat to make farm crops instantly grow. - - magmasource: continuously spawn magma from any map tile. - - removebadthoughts: delete all negative thoughts from your dwarves. - - slayrace: instakill all units of a given race, optionally with magma. - - superdwarf: per-creature fastdwarf. - New GUI scripts: - - gui/mechanisms: browse mechanism links of the current building. - - gui/room-list: browse other rooms owned by the unit when assigning one. - - gui/liquids: a GUI front-end for the liquids plugin. - - gui/rename: renaming stockpiles, workshops and units via an in-game dialog. - - gui/power-meter: front-end for the Power Meter plugin. - - gui/siege-engine: front-end for the Siege Engine plugin. - - gui/choose-weapons: auto-choose matching weapons in the military equip screen. - Autolabor plugin: +Internals +--------- +- full support for Mac OS X. +- a plugin that adds scripting in ruby. +- support for interposing virtual methods in DF from C++ plugins. +- support for creating new interface screens from C++ and lua. +- added various other API functions. + +Notable bugfixes +---------------- +- better terminal reset after exit on linux. +- seedwatch now works on reclaim. +- the sort plugin won't crash on cages anymore. + +Misc improvements +----------------- +- autodump: can move items to any walkable tile, not just floors. +- stripcaged: by default keep armor, new dumparmor option. +- zone: allow non-domesticated birds in nestboxes. +- workflow: quality range in constraints. +- cleanplants: new command to remove rain water from plants. +- liquids: can paint permaflow, i.e. what makes rivers power water wheels. +- prospect: pre-embark prospector accounts for caves & magma sea in its estimate. +- rename: supports renaming stockpiles, workshops, traps, siege engines. +- fastdwarf: now has an additional option to make dwarves teleport to their destination. +- Autolabor plugin: + - can set nonidle hauler percentage. - broker excluded from all labors when needed at depot. - likewise, anybody with a scheduled diplomat meeting. - New Dwarf Manipulator plugin: - Open the unit list, and press 'l' to access a Dwarf Therapist like UI in the game. - New Steam Engine plugin: - Dwarven Water Reactors don't make any sense whatsoever and cause lag, so this may be - a replacement for those concerned by it. The plugin detects if a workshop with a - certain name is in the raws used by the current world, and provides the necessary - behavior. See hack/raw/*_steam_engine.txt for the necessary raw definitions. - Note: Stuff like animal treadmills might be more period, but absolutely can't be - done with tools dfhack has access to. - New Power Meter plugin: - When activated, implements a pressure plate modification that detects power in gear - boxes built on the four adjacent N/S/W/E tiles. The gui/power-meter script implements - the necessary build configuration UI. - New Siege Engine plugin: - When enabled and configured via gui/siege-engine, allows aiming siege engines - at a designated rectangular area with 360 degree fire range and across Z levels; - this works by rewriting the projectile trajectory immediately after it appears. - Also supports loading catapults with non-boulder projectiles, taking from a stockpile, - and restricting operator skill range like with ordinary workshops. - Disclaimer: not in any way to undermine the future siege update from Toady, but - the aiming logic of existing engines hasn't been updated since 2D, and is almost - useless above ground :(. Again, things like making siegers bring their own engines - is totally out of the scope of dfhack and can only be done by Toady. - New Add Spatter plugin: - Detects reactions with certain names in the raws, and changes them from adding - improvements to adding item contaminants. This allows directly covering items - with poisons. The added spatters are immune both to water and 'clean items'. - Intended to give some use to all those giant cave spider poison barrels brought - by the caravans. + +New commands +------------ +- misery: multiplies every negative thought gained (2x by default). +- digtype: designates every tile of the same type of vein on the map for 'digging' (any dig designation). + +New tweaks +---------- +- tweak stable-cursor: keeps exact cursor position between d/k/t/q/v etc menus. +- tweak patrol-duty: makes Train orders reduce patrol timer, like the binary patch does. +- tweak readable-build-plate: fix unreadable truncation in unit pressure plate build ui. +- tweak stable-temp: fixes bug 6012; may improve FPS by 50-100% on a slow item-heavy fort. +- tweak fast-heat: speeds up item heating & cooling, thus making stable-temp act faster. +- tweak fix-dimensions: fixes subtracting small amounts from stacked liquids etc. +- tweak advmode-contained: fixes UI bug in custom reactions with container inputs in advmode. +- tweak fast-trade: Shift-Enter for selecting items quckly in Trade and Move to Depot screens. +- tweak military-stable-assign: Stop rightmost list of military->Positions from jumping to top. +- tweak military-color-assigned: In same list, color already assigned units in brown & green. + +New scripts +----------- +- fixnaked: removes thoughts about nakedness. +- setfps: set FPS cap at runtime, in case you want slow motion or speed-up. +- siren: wakes up units, stops breaks and parties - but causes bad thoughts. +- fix/population-cap: run after every migrant wave to prevent exceeding the cap. +- fix/stable-temp: counts items with temperature updates; does instant one-shot stable-temp. +- fix/loyaltycascade: fix units allegiance, eg after ordering a dwarf merchant kill. +- deathcause: shows the circumstances of death for a given body. +- digfort: designate areas to dig from a csv file. +- drainaquifer: remove aquifers from the map. +- growcrops: cheat to make farm crops instantly grow. +- magmasource: continuously spawn magma from any map tile. +- removebadthoughts: delete all negative thoughts from your dwarves. +- slayrace: instakill all units of a given race, optionally with magma. +- superdwarf: per-creature fastdwarf. +- gui/mechanisms: browse mechanism links of the current building. +- gui/room-list: browse other rooms owned by the unit when assigning one. +- gui/liquids: a GUI front-end for the liquids plugin. +- gui/rename: renaming stockpiles, workshops and units via an in-game dialog. +- gui/power-meter: front-end for the Power Meter plugin. +- gui/siege-engine: front-end for the Siege Engine plugin. +- gui/choose-weapons: auto-choose matching weapons in the military equip screen. + +New Plugins +----------- +- Dwarf Manipulator: Open the unit list, and press 'l' to access a Dwarf Therapist like UI in the game. +- Steam Engine: + Dwarven Water Reactors don't make any sense whatsoever and cause lag, so this may be + a replacement for those concerned by it. The plugin detects if a workshop with a + certain name is in the raws used by the current world, and provides the necessary + behavior. See ``hack/raw/*_steam_engine.txt`` for the necessary raw definitions. + Note: Stuff like animal treadmills might be more period, but absolutely can't be + done with tools dfhack has access to. +- Power Meter: + When activated, implements a pressure plate modification that detects power in gear + boxes built on the four adjacent N/S/W/E tiles. The gui/power-meter script implements + the necessary build configuration UI. +- Siege Engine: + When enabled and configured via gui/siege-engine, allows aiming siege engines + at a designated rectangular area with 360 degree fire range and across Z levels; + this works by rewriting the projectile trajectory immediately after it appears. + Also supports loading catapults with non-boulder projectiles, taking from a stockpile, + and restricting operator skill range like with ordinary workshops. + Disclaimer: not in any way to undermine the future siege update from Toady, but + the aiming logic of existing engines hasn't been updated since 2D, and is almost + useless above ground :(. Again, things like making siegers bring their own engines + is totally out of the scope of dfhack and can only be done by Toady. +- Add Spatter: + Detects reactions with certain names in the raws, and changes them from adding + improvements to adding item contaminants. This allows directly covering items + with poisons. The added spatters are immune both to water and 'clean items'. + Intended to give some use to all those giant cave spider poison barrels brought + by the caravans. diff --git a/docs/Plugins.rst b/docs/Plugins.rst index 2267fdea71..5f9e8018bb 100644 --- a/docs/Plugins.rst +++ b/docs/Plugins.rst @@ -512,6 +512,8 @@ toggle this option on, instead of returning you to the main construction menu af materials, it returns you back to this screen. If you use this along with several autoselect enabled materials, you should be able to place complex constructions more conveniently. +.. _buildingplan: + buildingplan ------------ When active (via ``enable buildingplan``), this plugin adds a planning mode for @@ -585,6 +587,12 @@ twaterlvl --------- Toggle between displaying/not displaying liquid depth as numbers. +.. _stocks: + +stocks +------ +An improved stocks screen. + stockpile management -------------------- diff --git a/docs/Scripts.rst b/docs/Scripts.rst index 0b98da9cb6..2eecf2562e 100644 --- a/docs/Scripts.rst +++ b/docs/Scripts.rst @@ -532,6 +532,8 @@ 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. +.. _modtools/add-syndrome: + modtools/add-syndrome ===================== This allows adding and removing syndromes from units. @@ -618,6 +620,8 @@ modtools/reaction-trigger Triggers dfhack commands when custom reactions complete, regardless of whether it produced anything, once per completion. +.. _modtools/reaction-trigger-transition: + modtools/reaction-trigger-transition ==================================== Scans raw files and creates a file to help modders transition from @@ -652,6 +656,8 @@ add-thought Adds a thought or emotion to the selected unit. Can be used by other scripts, or the gui invoked by running ``add-thought gui`` with a unit selected. +.. _adaptation: + adaptation ========== View or set level of cavern adaptation for the selected unit or the whole fort. @@ -902,6 +908,8 @@ full-heal ========= Attempts to fully heal the selected unit. ``full-heal -r`` attempts to resurrect the unit. +.. _gaydar: + gaydar ====== Shows the sexual orientation of units, useful for social engineering or checking @@ -1016,10 +1024,12 @@ make-monarch ============ Make the selected unit King or Queen of your civilisation. +.. _markdown: + markdown ======== Save a copy of a text screen in markdown (for reddit among others). -Use 'markdown help' for more details. +Use ``markdown help`` for more details. masspit ======= From a4708d07a18cc3380c5c65b91469d11c3d86dbaa Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Fri, 23 Oct 2015 12:34:54 +1100 Subject: [PATCH 07/91] Allow Sphinx-doc to work with or without cmake This mainly involved tweaking a few filenames and configuration paths to allow consistency in all scenarios. It cleared up a few errors in the process too! I also clarified the placement of the LICENSE file, and finished configuring the Alabaster style. This required moving some stuff out of the CMake system to conf.py to avoid later breakage. --- CMakeLists.txt | 17 +++--- LICENSE => LICENSE.rst | 10 ++++ README.rst | 2 +- docs/Contributing.rst | 7 ++- docs/Licenses.rst | 11 ---- docs/{conf.py.in => conf.py} | 73 ++++++++++++++---------- docs/{images => styles}/dfhack-icon.ico | Bin 7 files changed, 66 insertions(+), 54 deletions(-) rename LICENSE => LICENSE.rst (98%) delete mode 100644 docs/Licenses.rst rename docs/{conf.py.in => conf.py} (88%) rename docs/{images => styles}/dfhack-icon.ico (100%) diff --git a/CMakeLists.txt b/CMakeLists.txt index 84db3f36f5..649580f9ea 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -184,10 +184,7 @@ endif() # build the lib itself IF(BUILD_LIBRARY) add_subdirectory (library) - ## install the default documentation files - #install(FILES LICENSE NEWS "Lua API.html" Readme.html Compile.html Contributors.html DESTINATION ${DFHACK_USERDOC_DESTINATION}) - install(FILES LICENSE NEWS DESTINATION ${DFHACK_USERDOC_DESTINATION}) - #install(DIRECTORY docs/images DESTINATION ${DFHACK_USERDOC_DESTINATION}) + install(FILES LICENSE.rst NEWS.rst DESTINATION ${DFHACK_USERDOC_DESTINATION}) endif() install(DIRECTORY dfhack-config/ DESTINATION dfhack-config/default) @@ -204,21 +201,21 @@ if (BUILD_DOCS) if (NOT SPHINX_FOUND) message(SEND_ERROR "Sphinx not found but BUILD_DOCS enabled") endif() - set(SPHINX_THEME "alabaster") set(SPHINX_THEME_DIR) set(SPHINX_BINARY_BUILD_DIR "${CMAKE_CURRENT_SOURCE_DIR}/docs/_build") set(SPHINX_CACHE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/docs/_build/_doctrees") set(SPHINX_HTML_DIR "${CMAKE_CURRENT_SOURCE_DIR}/docs/html/") configure_file( - "${CMAKE_CURRENT_SOURCE_DIR}/docs/conf.py.in" - "${SPHINX_BINARY_BUILD_DIR}/conf.py" + "${CMAKE_CURRENT_SOURCE_DIR}/docs/conf.py" + "${SPHINX_BINARY_BUILD_DIR}/docs/conf.py" @ONLY) file(GLOB SPHINX_DEPS "${CMAKE_CURRENT_SOURCE_DIR}/docs/*.rst" "${CMAKE_CURRENT_SOURCE_DIR}/docs/images/*.png" - "${CMAKE_CURRENT_SOURCE_DIR}/docs/conf.py.in" + "${CMAKE_CURRENT_SOURCE_DIR}/docs/styles*" + "${CMAKE_CURRENT_SOURCE_DIR}/docs/conf.py" "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*.lua" "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*.lua" "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*/*.lua" @@ -230,14 +227,14 @@ if (BUILD_DOCS) "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*/*/*/*/*/*/*/*.lua" "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*/*/*/*/*/*/*/*/*.lua" ) - set(SPHINX_DEPS ${SPHINX_DEPS} LICENSE NEWS README.rst) + set(SPHINX_DEPS ${SPHINX_DEPS} LICENSE.rst NEWS.rst README.rst) set(SPHINX_OUTPUT "${CMAKE_CURRENT_SOURCE_DIR}/docs/html/.buildinfo") set_source_files_properties(${SPHINX_OUTPUT} PROPERTIES GENERATED TRUE) add_custom_command(OUTPUT ${SPHINX_OUTPUT} COMMAND ${SPHINX_EXECUTABLE} -a -E -q -b html - -c "${SPHINX_BINARY_BUILD_DIR}" + -c "${SPHINX_BINARY_BUILD_DIR}/docs" -d "${SPHINX_CACHE_DIR}" "${CMAKE_CURRENT_SOURCE_DIR}" "${SPHINX_HTML_DIR}" diff --git a/LICENSE b/LICENSE.rst similarity index 98% rename from LICENSE rename to LICENSE.rst index 9bdc729f08..490b07a6e7 100644 --- a/LICENSE +++ b/LICENSE.rst @@ -1,3 +1,13 @@ +.. _license: + +######## +Licenses +######## + +DFHack is distributed under a range of permissive and weakly copyleft licenses. + +The core uses the ZLib license; the others are described below. + License of DFHack ================= https://github.com/peterix/dfhack diff --git a/README.rst b/README.rst index 801b7c7f22..dcf3fb9059 100644 --- a/README.rst +++ b/README.rst @@ -44,7 +44,7 @@ Other Contents: :maxdepth: 1 docs/Authors - docs/Licenses + LICENSE NEWS For Developers: diff --git a/docs/Contributing.rst b/docs/Contributing.rst index c374a4b95c..867058e851 100644 --- a/docs/Contributing.rst +++ b/docs/Contributing.rst @@ -83,7 +83,7 @@ documentation is built with Sphinx, which runs automatically at compile time. DFHack consists of variously licensed code, but invariably weak copyleft. The main license is zlib/libpng, some bits are MIT licensed, and some are -BSD licensed. See the ``LICENSE`` document for more information. +BSD licensed. See the `license` for more information. Feel free to add your own extensions and plugins. Contributing back to the DFHack repository is welcome and the right thing to do :) @@ -118,6 +118,11 @@ comprehensive interface for visualisers such as Armok Vision. Documentation Standards ======================= +DFHack documentation is built with Sphinx, and configured automatically +through CMake. If you want to build the docs *only*, use this command:: + + sphinx-build -a -c docs . docs/html + Whether you're adding new code or just fixing old documentation (and there's plenty), there are a few important standards for completeness and consistent style. Treat this section as a guide rather than iron law, match the surrounding text, and you'll diff --git a/docs/Licenses.rst b/docs/Licenses.rst deleted file mode 100644 index c022277203..0000000000 --- a/docs/Licenses.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. _license: - -######## -Licenses -######## - -DFHack is distributed under a range of permissive and weakly copyleft licenses. - -The core uses the ZLib license; the others are described below. - -.. include:: ../LICENSE diff --git a/docs/conf.py.in b/docs/conf.py similarity index 88% rename from docs/conf.py.in rename to docs/conf.py index 15e4490b1c..59fd656a84 100644 --- a/docs/conf.py.in +++ b/docs/conf.py @@ -21,9 +21,11 @@ from os import listdir from os.path import isfile, join, isdir, relpath -#import sys currentDir = '@CMAKE_CURRENT_SOURCE_DIR@' +if currentDir.startswith('@'): + # Not running in CMake + currentDir = '.' def makeIncludeAll(directory, extension): outputFile = join(directory,'include-all.rst') @@ -90,22 +92,29 @@ def makeAllIncludeAll(directory, extension): # |version| and |release|, also used in various other places throughout the # built documents. -#def get_version(): -# """Return the DFHack version string, from CMakeLists.txt""" -# version, release = '', '' -# with open('CMakeLists.txt') as f: -# for s in f.readlines(): -# if fnmatch.fnmatch(s.upper(), 'SET(DF_VERSION "?.??.??")\n'): -# version = s.upper().replace('SET(DF_VERSION "', '') -# elif fnmatch.fnmatch(s.upper(), 'SET(DFHACK_RELEASE "r*")\n'): -# release = s.upper().replace('SET(DFHACK_RELEASE "', '').lower() -# return (version + '-' + release).replace('")\n', '') +def get_version(default): + """Return the DFHack version string, from CMakeLists.txt""" + version = release = '' + try: + with open('../CMakeLists.txt') as f: + for s in f.readlines(): + if fnmatch.fnmatch(s.upper(), 'SET(DF_VERSION "?.??.??")\n'): + version = s.upper().replace('SET(DF_VERSION "', '') + elif fnmatch.fnmatch(s.upper(), 'SET(DFHACK_RELEASE "r*")\n'): + release = s.upper().replace('SET(DFHACK_RELEASE "', '').lower() + return (version + '-' + release).replace('")\n', '') + except IOError: + return default # The short X.Y version. version = '@DFHACK_VERSION@' # The full version, including alpha/beta/rc tags. release = '@DFHACK_VERSION@' +if version == '@DFHACK_VERSION@': + # Not running through CMake... + version = release = get_version('@DFHACK_VERSION@') + # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # @@ -125,7 +134,7 @@ def makeAllIncludeAll(directory, extension): # The reST default role (used for this markup: `text`) to use for all # documents. -default_role = 'any' +default_role = 'ref' # If true, '()' will be appended to :func: etc. cross-reference text. #add_function_parentheses = True @@ -134,16 +143,9 @@ def makeAllIncludeAll(directory, extension): # unit titles (such as .. function::). #add_module_names = True -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - # If true, keep warnings as "system message" paragraphs in the built documents. #keep_warnings = False @@ -155,12 +157,18 @@ def makeAllIncludeAll(directory, extension): # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = '@SPHINX_THEME@' +html_theme = 'alabaster' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -#html_theme_options = {} +html_theme_options = { + #'logo': 'logo.png', + 'github_user': 'DFHack', + 'github_repo': 'dfhack', + 'github_button': False, + 'travis_button': False, +} # Add any paths that contain custom themes here, relative to this directory. #html_theme_path = [] @@ -170,7 +178,7 @@ def makeAllIncludeAll(directory, extension): #html_title = None # A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None +html_short_title = 'DFHack Docs' # The name of an image file (relative to this directory) to place at the top # of the sidebar. @@ -179,12 +187,12 @@ def makeAllIncludeAll(directory, extension): # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. -html_favicon = 'dfhack-icon.ico' +html_favicon = 'styles/dfhack-icon.ico' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = [] +html_static_path = ['styles'] # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied @@ -200,17 +208,24 @@ def makeAllIncludeAll(directory, extension): #html_use_smartypants = True # Custom sidebar templates, maps document names to template names. -#html_sidebars = {} +html_sidebars = { + '**': [ + 'about.html', + 'localtoc.html', + 'relations.html', + 'searchbox.html', + ] +} # Additional templates that should be rendered to pages, maps page names to # template names. #html_additional_pages = {} # If false, no module index is generated. -#html_domain_indices = True +html_domain_indices = False # If false, no index is generated. -#html_use_index = True +html_use_index = False # If true, the index is split into individual pages for each letter. #html_split_index = False @@ -238,10 +253,6 @@ def makeAllIncludeAll(directory, extension): # 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr' #html_search_language = 'en' -# A dictionary with options for the search language support, empty by default. -# Now only 'ja' uses this config value -#html_search_options = {'type': 'default'} - # The name of a javascript file (relative to the configuration directory) that # implements a search results scorer. If empty, the default will be used. #html_search_scorer = 'scorer.js' diff --git a/docs/images/dfhack-icon.ico b/docs/styles/dfhack-icon.ico similarity index 100% rename from docs/images/dfhack-icon.ico rename to docs/styles/dfhack-icon.ico From a60e525a5c6ebc148bed1880e0b4bf7a0d5ea84f Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Fri, 23 Oct 2015 12:57:18 +1100 Subject: [PATCH 08/91] Add custom styles for keybindings and ingame text And use them in Plugins.rst. Styles copied from PeridexisErrant/DF-Walkthrough, and derived from the wiki. --- docs/Plugins.rst | 76 ++++++++++++++++++++--------------------- docs/conf.py | 1 + docs/styles/cp437.ttf | Bin 0 -> 79440 bytes docs/styles/dfhack.css | 40 ++++++++++++++++++++++ 4 files changed, 79 insertions(+), 38 deletions(-) create mode 100644 docs/styles/cp437.ttf create mode 100644 docs/styles/dfhack.css diff --git a/docs/Plugins.rst b/docs/Plugins.rst index 5f9e8018bb..5891f4494f 100644 --- a/docs/Plugins.rst +++ b/docs/Plugins.rst @@ -368,7 +368,7 @@ manipulator =========== An in-game equivalent to the popular program Dwarf Therapist. -To activate, open the unit screen and press ``l``. +To activate, open the unit screen and press :kbd:`l`. .. image:: images/manipulator.png @@ -382,26 +382,26 @@ military and social skills. .. image:: images/manipulator2.png -Press ``t`` to toggle between Profession and Squad view. +Press :kbd:`t` to toggle between Profession and Squad view. .. image:: images/manipulator3.png -Use the arrow keys or number pad to move the cursor around, holding Shift to +Use the arrow keys or number pad to move the cursor around, holding :kbd:`Shift` to move 10 tiles at a time. -Press the Z-Up (``<``) and Z-Down (``>``) keys to move quickly between labor/skill +Press the Z-Up (:kbd:`<`) and Z-Down (:kbd:`>`) keys to move quickly between labor/skill categories. The numpad Z-Up and Z-Down keys seek to the first or last unit -in the list. Backspace seeks to the top left corner. +in the list. :kbd:`Backspace` seeks to the top left corner. Press Enter to toggle the selected labor for the selected unit, or Shift+Enter to toggle all labors within the selected category. -Press the ``+-`` keys to sort the unit list according to the currently selected -skill/labor, and press the ``*/`` keys to sort the unit list by Name, Profession/Squad, -Happiness, or Arrival order (using Tab to select which sort method to use here). +Press the :kbd:`+`:kbd:`-` keys to sort the unit list according to the currently selected +skill/labor, and press the :kbd:`*`:kbd:`/` keys to sort the unit list by Name, Profession/Squad, +Happiness, or Arrival order (using :kbd:`Tab` to select which sort method to use here). -With a unit selected, you can press the ``v`` key to view its properties (and -possibly set a custom nickname or profession) or the ``c`` key to exit +With a unit selected, you can press the :kbd:`v` key to view its properties (and +possibly set a custom nickname or profession) or the :kbd:`c` key to exit Manipulator and zoom to its position within your fortress. The following mouse shortcuts are also available: @@ -414,7 +414,7 @@ The following mouse shortcuts are also available: * Left-click on a unit's name, profession or squad to view its properties. * Right-click on a unit's name, profession or squad to zoom to it. -Pressing ``ESC`` normally returns to the unit screen, but ``Shift-ESC`` would exit +Pressing :kbd:`Esc` normally returns to the unit screen, but :kbd:`Shift`:kbd:`Esc` would exit directly to the main dwarf mode screen. search @@ -425,25 +425,25 @@ Noble (assignment candidates), Military (position candidates), Burrows .. image:: images/search.png -Searching works the same way as the search option in "Move to Depot" does. -You will see the Search option displayed on screen with a hotkey (usually ``s``). +Searching works the same way as the search option in :guilabel:`Move to Depot`. +You will see the Search option displayed on screen with a hotkey (usually :kbd:`s`). Pressing it lets you start typing a query and the relevant list will start filtering automatically. -Pressing ENTER, ESC or the arrow keys will return you to browsing the now +Pressing :kbd:`Enter`, :kbd:`Esc` or the arrow keys will return you to browsing the now filtered list, which still functions as normal. You can clear the filter by either going back into search mode and backspacing to delete it, or pressing the "shifted" version of the search hotkey while browsing the -list (e.g. if the hotkey is ``s``, then hitting ``Shift-s`` will clear any +list (e.g. if the hotkey is :kbd:`s`, then hitting :kbd:`Shift`:kbd:`s` will clear any filter). Leaving any screen automatically clears the filter. In the Trade screen, the actual trade will always only act on items that are actually visible in the list; the same effect applies to the Trade -Value numbers displayed by the screen. Because of this, the ``t`` key is +Value numbers displayed by the screen. Because of this, the :kbd:`t` key is blocked while search is active, so you have to reset the filters first. -Pressing ``Alt-C`` will clear both search strings. +Pressing :kbd:`Alt`:kbd:`C` will clear both search strings. In the stockpile screen the option only appears if the cursor is in the rightmost list: @@ -493,7 +493,7 @@ preferred material type. .. image:: images/automaterial-mat.png -Pressing ``a`` while highlighting any material will enable that material for "auto select" +Pressing :kbd:`a` while highlighting any material will enable that material for "auto select" for this construction type. You can enable multiple materials as autoselect. Now the next time you place this type of construction, the plugin will automatically choose materials for you from the kinds you enabled. If there is enough to satisfy the whole placement, @@ -504,10 +504,10 @@ When choosing the construction placement, you will see a couple of options: .. image:: images/automaterial-pos.png -Use ``a`` here to temporarily disable the material autoselection, e.g. if you need +Use :kbd:`a` here to temporarily disable the material autoselection, e.g. if you need to go to the material selection screen so you can toggle some materials on or off. -The other option (auto type selection, off by default) can be toggled on with ``t``. If you +The other option (auto type selection, off by default) can be toggled on with :kbd:`t`. If you toggle this option on, instead of returning you to the main construction menu after selecting materials, it returns you back to this screen. If you use this along with several autoselect enabled materials, you should be able to place complex constructions more conveniently. @@ -579,7 +579,7 @@ Toggle between all possible positions where the idlers count can be placed. trackstop --------- -Adds a ``q`` menu for track stops, which is completely blank by default. +Adds a :kbd:`q` menu for track stops, which is completely blank by default. This allows you to view and/or change the track stop's friction and dump direction settings, using the keybindings from the track stop building interface. @@ -614,9 +614,9 @@ See `gui/stockpiles` for an in-game interface. :loadstock: Loads a saved stockpile settings file and applies it to the currently selected stockpile. eg: ``loadstock food_settings.dfstock`` -To use savestock and loadstock, use the ``q`` command to highlight a stockpile. +To use savestock and loadstock, use the :kbd:`q` command to highlight a stockpile. Then run savestock giving it a descriptive filename. Then, in a different (or -the same!) gameworld, you can highlight any stockpile with ``q`` then execute the +the same!) gameworld, you can highlight any stockpile with :kbd:`q` then execute the ``loadstock`` command passing it the name of that file. The settings will be applied to that stockpile. @@ -1053,17 +1053,17 @@ Invoked as:: Intended to be used as a keybinding: -* In 'q' mode, when a job is highlighted within a workshop or furnace, +* In :kbd:`q` mode, when a job is highlighted within a workshop or furnace, changes the material of the job. Only inorganic materials can be used in this mode. -* In 'b' mode, during selection of building components positions the cursor +* In :kbd:`b` mode, during selection of building components positions the cursor over the first available choice with the matching material. job-duplicate ------------- Duplicate the selected job in a workshop: -* In 'q' mode, when a job is highlighted within a workshop or furnace building, +* In :kbd:`q` mode, when a job is highlighted within a workshop or furnace building, instantly duplicates the job. .. _stockflow: @@ -1086,10 +1086,10 @@ Usage: ``stockflow status`` Display whether the plugin is enabled. -While enabled, the ``q`` menu of each stockpile will have two new options: +While enabled, the :kbd:`q` menu of each stockpile will have two new options: -* ``j``: Select a job to order, from an interface like the manager's screen. -* ``J``: Cycle between several options for how many such jobs to order. +* :kbd:`j`: Select a job to order, from an interface like the manager's screen. +* :kbd:`J`: Cycle between several options for how many such jobs to order. Whenever the bookkeeper updates stockpile records, new work orders will be placed on the manager's queue for each such selection, reduced by the @@ -2294,8 +2294,8 @@ just stones. Configuration UI ~~~~~~~~~~~~~~~~ The configuration front-end to the plugin is implemented by `gui/siege-engine`. -Bind it to a key (the example config uses Alt-A) and activate after selecting -a siege engine in ``q`` mode. +Bind it to a key (the example config uses :kbd:`Alt`:kbd:`a`) and activate after selecting +a siege engine in :kbd:`q` mode. .. image:: images/siege-engine.png @@ -2304,19 +2304,19 @@ the allowed operator skill range. The map tile color is changed to signify if it hit by the selected engine: green for fully reachable, blue for out of range, red for blocked, yellow for partially blocked. -Pressing ``r`` changes into the target selection mode, which works by highlighting two points -with Enter like all designations. When a target area is set, the engine projectiles are +Pressing :kbd:`r` changes into the target selection mode, which works by highlighting two points +with :kbd:`Enter` like all designations. When a target area is set, the engine projectiles are aimed at that area, or units within it (this doesn't actually change the original aiming code, instead the projectile trajectory parameters are rewritten as soon as it appears). After setting the target in this way for one engine, you can 'paste' the same area into others -just by pressing ``p`` in the main page of this script. The area to paste is kept until you quit +just by pressing :kbd:`p` in the main page of this script. The area to paste is kept until you quit DF, or select another area manually. -Pressing ``t`` switches to a mode for selecting a stockpile to take ammo from. +Pressing :kbd:`t` switches to a mode for selecting a stockpile to take ammo from. Exiting from the siege engine script via ESC reverts the view to the state prior to starting -the script. Shift-ESC retains the current viewport, and also exits from the ``q`` mode to main +the script. :kbd:`Shift`:kbd:`Esc` retains the current viewport, and also exits from the :kbd:`q` mode to main menu. .. _power-meter: @@ -2327,7 +2327,7 @@ The power-meter plugin implements a modified pressure plate that detects power b supplied to gear boxes built in the four adjacent N/S/W/E tiles. The configuration front-end is implemented by `gui/power-meter`. Bind it to a -key (the example config uses Ctrl-Shift-M) and activate after selecting Pressure Plate +key (the example config uses :kbd:`Ctrl`:kbd:`Shift`:kbd:`M`) and activate after selecting Pressure Plate in the build menu. .. image:: images/power-meter.png @@ -2380,7 +2380,7 @@ 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 -in the 't' view of the workshop. +in the :kbd:`t` view of the workshop. .. note:: diff --git a/docs/conf.py b/docs/conf.py index 59fd656a84..c7e0d8e867 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -158,6 +158,7 @@ def get_version(default): # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. html_theme = 'alabaster' +html_style = 'dfhack.css' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the diff --git a/docs/styles/cp437.ttf b/docs/styles/cp437.ttf new file mode 100644 index 0000000000000000000000000000000000000000..f0f10a6982dbd8e4bdf37bb41d90c3b5a7e1fad3 GIT binary patch literal 79440 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 Date: Fri, 23 Oct 2015 13:06:56 +1100 Subject: [PATCH 09/91] Fix encoding issue --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index c7e0d8e867..ea7305c954 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -43,7 +43,7 @@ def makeIncludeAll(directory, extension): out.append(TEMPLATE.format(dname, f)) if out: # Only write the file if the index is not empty - with open(outputFile, 'w') as outfile: + with open(outputFile, 'w' if sys.version_info.major > 2 else 'wb') as outfile: outfile.write(len(dname)*'=' + '\n' + dname + '\n' + len(dname)*'=' + '\n\n') outfile.write('\n\n'.join(out)) From 0f65bb05646345499934d6d27c9f63e727300fcd Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Fri, 23 Oct 2015 14:22:52 +1100 Subject: [PATCH 10/91] CSS fix --- docs/styles/dfhack.css | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/styles/dfhack.css b/docs/styles/dfhack.css index 9b0d1b3b74..67f75b3b1e 100644 --- a/docs/styles/dfhack.css +++ b/docs/styles/dfhack.css @@ -33,7 +33,7 @@ * Use this for any text from an in-game announcement or menu. */ color: #CBC7C0; - font-family: cp437;, 'fixedsys', monospace; + font-family: cp437, 'fixedsys', monospace; background: #000000; font-size: 0.95em; padding: 0.05em 0.4em; From d98ee535a135011371e27ee464bd2b691f2478b0 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Fri, 23 Oct 2015 22:25:04 +1100 Subject: [PATCH 11/91] Much improved script docs generator Creates a single file for each kind of script (base, gui, fix...). This includes and correctly sorts content from any .lua or .rb file under the scripts directory. It's more robust and more readable than the old style, and doesn't write anything in the submodules. User-added scripts will be seamlessly added, if they have a docs section and Sphinx is run. --- docs/3rdparty.rst | 12 ------ docs/Scripts.rst | 32 ++++++---------- docs/conf.py | 98 +++++++++++++++++++++++++++++++---------------- 3 files changed, 76 insertions(+), 66 deletions(-) delete mode 100644 docs/3rdparty.rst diff --git a/docs/3rdparty.rst b/docs/3rdparty.rst deleted file mode 100644 index 351f41699a..0000000000 --- a/docs/3rdparty.rst +++ /dev/null @@ -1,12 +0,0 @@ -###################### -Complete Scripts Index -###################### - -This is the complete index of documentation pulled from script source files. - -.. toctree:: - :glob: - :maxdepth: 2 - - /scripts/**include-all - diff --git a/docs/Scripts.rst b/docs/Scripts.rst index 2eecf2562e..0e072e48f3 100644 --- a/docs/Scripts.rst +++ b/docs/Scripts.rst @@ -15,35 +15,27 @@ or from the init file. only be interrupted every 256 instructions. Use ``kill-lua force`` to interrupt the next instruction. -Here's an index to documentation pulled from script source files: - -.. toctree:: - :glob: - :maxdepth: 2 - - /docs/3rdparty/ - - Here's the contents page for this document: .. contents:: -================= -3rd-party scripts -================= -This listing is autogenerated from ``.rst`` files in the 3rdparty scripts directory. +The following pages document all the standard DFHack scripts. -.. warning:: +.. toctree:: + :glob: + :maxdepth: 2 + + /docs/_auto/* - Because this documentation is pulled in from external sources, - it may not match the DFHack distribution exactly. - * Some scripts should have a prefix (eg listed as ``myscript``, - should be ``gui/myscript``) but don't. - * Some sections of documentation may refer to scripts which are - not distributed with DFHack. +.. warning:: + The following documentation is pulled in from external ``README`` files. + + - it may not match the DFHack docs style + - some scripts have incorrect names, or are documented but unavailable + - some scripts have entries here and are also included above .. toctree:: :glob: diff --git a/docs/conf.py b/docs/conf.py index ea7305c954..61095a7c98 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -18,41 +18,71 @@ import os import shlex import sys +import shutil + + +def doc_dir(dirname, files): + """Yield (command, includepath) for each script in the directory.""" + sdir = os.path.relpath(dirname, '..').replace('\\', '/').replace('../', '') + for f in files: + if f[-3:] not in {'lua', '.rb'}: + continue + with open(os.path.join(dirname, f), 'r', encoding='utf8') as fstream: + text = [l.rstrip() for l in fstream.readlines() if l.strip()] + command = None + for line in text: + if line == len(line) * '=': + if command is not None: + yield command, sdir + '/' + f + break + command = line + # later, print an error for missing docs here + + +def document_scripts(): + """Autodoc for files with the magic script documentation marker strings. + + Creates a file for eack kind of script (base/devel/fix/gui/modtools) + with all the ".. include::" directives to pull out docs between the + magic strings. + """ + # First, we collect the commands and paths to include in our docs + scripts = [] + for root, _, files in os.walk('../scripts'): + scripts.extend(doc_dir(root, files)) + # Next we split by type and create include directives sorted by command + kinds = {'base': [], 'devel': [], 'fix': [], 'gui': [], 'modtools': []} + for s in scripts: + k_fname = s[0].split('/', 1) + if len(k_fname) == 1: + kinds['base'].append(s) + else: + kinds.get(k_fname[0], []).append(s) + template = ('.. include:: /{}\n :start-after: BEGIN_DOCS\n' + ' :end-before: END_DOCS') + for key, value in kinds.items(): + kinds[key] = [ + template.format(x[1]) for x in sorted(value, key=lambda x: x[0])] + # Finally, we write our _auto/* files for each kind of script + if not os.path.isdir('_auto'): + os.mkdir('_auto') + head = { + 'base': 'Basic Scripts', + 'devel': 'Development Scripts', + 'fix': 'Bugfixing Scripts', + 'gui': 'GUI Scripts', + 'modtools': 'Scripts for Modders'} + for k in head: + title = '{l}\n{t}\n{l}\n\n'.format(t=head[k], l=len(head[k])*'#') + mode = 'w' if sys.version_info.major > 2 else 'wb' + with open('_auto/{}.rst'.format(k), mode) as outfile: + outfile.write(title) + outfile.write('\n\n'.join(kinds[k])) + + +# Actually call the docs generator +document_scripts() -from os import listdir -from os.path import isfile, join, isdir, relpath - -currentDir = '@CMAKE_CURRENT_SOURCE_DIR@' -if currentDir.startswith('@'): - # Not running in CMake - currentDir = '.' - -def makeIncludeAll(directory, extension): - outputFile = join(directory,'include-all.rst') - files = [ f for f in listdir(directory) if isfile(join(directory,f)) and f.endswith(extension) ] - files.sort() - dname = relpath(directory, relpath('..', currentDir)).replace('\\', '/') - while dname.startswith('..'): - dname = dname[3:] - TEMPLATE = '.. include:: /{}/{}\n :start-after: BEGIN_DOCS\n :end-before: END_DOCS' - out = [] - for f in files: - with open(join(directory,f), 'r', encoding='utf8') as fstream: - data = fstream.read().replace('\n','') - if 'BEGIN_DOCS' in data: - out.append(TEMPLATE.format(dname, f)) - if out: - # Only write the file if the index is not empty - with open(outputFile, 'w' if sys.version_info.major > 2 else 'wb') as outfile: - outfile.write(len(dname)*'=' + '\n' + dname + '\n' + len(dname)*'=' + '\n\n') - outfile.write('\n\n'.join(out)) - -def makeAllIncludeAll(directory, extension): - for root, subdirs, files in os.walk(directory): - if isdir(root): - makeIncludeAll(root, extension) - -makeAllIncludeAll(currentDir + '/scripts', '.lua') # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the From 5e02e00e2c1d3460b6bd210c5f5142aa3965fab4 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Sat, 24 Oct 2015 00:33:35 +1100 Subject: [PATCH 12/91] Autogen script links, table of contents, and demo! Automatically generating the link target for each script saves a lot of time and potential for errors. Each kind-of-script page now includes a link target for that page, and also a table of contents. In-script markers to delimit text for Sphinx extraction now use native docstring markers from Ruby, which is a lot more elegant in .rb scripts - and robust, as long as the fisrt docstring is valid .rst! --- docs/Contributing.rst | 30 ++++++-- docs/Scripts.rst | 123 ++++++++------------------------- docs/conf.py | 13 ++-- scripts/adaptation.rb | 9 +++ scripts/add-thought.lua | 8 +-- scripts/armoks-blessing.lua | 9 +++ scripts/autofarm.rb | 16 +++++ scripts/autolabor-artisans.lua | 7 ++ scripts/autounsuspend.rb | 8 +++ 9 files changed, 114 insertions(+), 109 deletions(-) diff --git a/docs/Contributing.rst b/docs/Contributing.rst index 867058e851..343c2de7d2 100644 --- a/docs/Contributing.rst +++ b/docs/Contributing.rst @@ -128,9 +128,29 @@ there are a few important standards for completeness and consistent style. Trea this section as a guide rather than iron law, match the surrounding text, and you'll be fine. -Every script, plugin, or command should be documented. This is an active project, -and the best place to put this documentation might change. For now, it's usually -either ``docs/Scripts.rst`` or ``docs/Plugins.rst``. +Everything should be documented! For plugins, it's a work in progress - use +``docs/Plugins.rst`` for now. Core functions and general explanations should +go in the documents for that component; if it's not clear add a new section +as some may be missing. + +Scripts can use a custom autodoc function, based on the Sphinx ``include`` +directive and Ruby docstring conventions - any lines between ``=begin`` and +``=end`` are copied into the appropriate scripts documentation page. +They **must** have a heading which exactly matches the command, underlined +with ``=====`` to the same length. For example, a lua file would have:: + + --[[=begin + + add-thought + =========== + Adds a thought or emotion to the selected unit. Can be used by other scripts, + or the gui invoked by running ``add-thought gui`` with a unit selected. + + =end]] + +Ruby scripts use the same syntax, but obviously omit the leading ``--[[`` and +trailing ``]]`` which denote a multiline comment in lua. +``=begin`` and ``=end`` are native syntax (and matched in lua for convenience). Where the heading for a section is also the name of a command, the spelling and case should exactly match the command to enter in the DFHack command line. @@ -141,7 +161,7 @@ Sphinx (our documentation system) will make sure paragraphs flow. If there aren't many options or examples to show, they can go in a paragraph of text. Use double-backticks to put commands in monospaced font, like this:: - You can use ``cleanall scattered x`` to dump tattered or abandoned items. + You can use ``cleanowned scattered x`` to dump tattered or abandoned items. If the command takes more than three arguments, format the list as a table called Options. The table *only* lists arguments, not full commands. @@ -174,6 +194,8 @@ section like this:: ========= Add link targets if you need them, but otherwise plain headings are preferred. +Scripts using the in-source docs option, which should be all of them, have +link targets created automatically. Other ways to help ================== diff --git a/docs/Scripts.rst b/docs/Scripts.rst index 0e072e48f3..e6c3495ea4 100644 --- a/docs/Scripts.rst +++ b/docs/Scripts.rst @@ -15,12 +15,37 @@ or from the init file. only be interrupted every 256 instructions. Use ``kill-lua force`` to interrupt the next instruction. -Here's the contents page for this document: -.. contents:: +The following pages document all the standard DFHack scripts. +* Basic scripts are not stored in any subdirectory, and can be invoked directly. + They are generally useful tools for any player. +* ``devel/*`` scripts are intended for developers, or still substantially unfinished. + If you don't already know what they do, best to leave them alone. +* ``fix/*`` scripts fix various bugs and issues, some of them obscure. +* ``gui/*`` scripts implement dialogs in the main game window. + + In order to avoid user confusion, as a matter of policy all these tools + display the word "DFHack" on the screen somewhere while active. + When that is not appropriate because they merely add keybinding hints to + existing DF screens, they deliberately use red instead of green for the key. + +* ``modtools/*`` scripts provide tools for modders, often with changes + to the raw files, and are not intended to be called manually by end-users. + + 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. -The following pages document all the standard DFHack scripts. .. toctree:: :glob: @@ -44,16 +69,8 @@ The following pages document all the standard DFHack scripts. /scripts/3rdparty/*/* -======= -devel/* -======= -Scripts in this subdirectory are intended for developers, or still substantially -under development. If you don't already know what they do, best to leave them alone. -================================================ -fix/* - scripts that fix bugs or common problems -================================================ -Scripts in this subdirectory fix various bugs and issues, some of them obscure. + fix/blood-del ============= @@ -112,20 +129,6 @@ fix/stuckdoors Fix doors that are stuck open due to incorrect map occupancy flags, eg due to incorrect use of teleport. -======================================== -gui/* - scripts with an ingame interface -======================================== -Scripts that implement dialogs inserted into the main game window are put in this -directory. - -.. note:: - - In order to avoid user confusion, as a matter of policy all these tools - display the word "DFHack" on the screen somewhere while active. - - When that is not appropriate because they merely add keybinding hints to - existing DF screens, they deliberately use red instead of green for the key. - .. _gui/advfort: @@ -503,27 +506,6 @@ material is matched against the barrel itself. Then, if you select, say, iron, and then try to change the input item type, now it won't let you select *plant*; you have to unset the material first. -.. _modtools: - -======================== -modtools/* - for modders -======================== -Scripts which provide tools for modders, often with changes to the raw files. -Not intended to be called manually by end-users. - -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. - .. _modtools/add-syndrome: modtools/add-syndrome @@ -641,53 +623,6 @@ Transforms a unit into another unit type, possibly permanently. ============= Other Scripts ============= -These scripts are not stored in any subdirectory, and can be invoked directly. - -add-thought -=========== -Adds a thought or emotion to the selected unit. Can be used by other scripts, -or the gui invoked by running ``add-thought gui`` with a unit selected. - -.. _adaptation: - -adaptation -========== -View or set level of cavern adaptation for the selected unit or the whole fort. -Usage: ``adaptation [value]``. The ``value`` must be -between 0 and 800,000 inclusive. - -armoks-blessing -=============== -Runs the equivalent of `rejuvenate`, `elevate-physical`, -`elevate-mental`, and `brainwash` -on all dwarves currently on the map. This is an extreme change, which sets every -stat to an ideal - legendary skills, great traits, and easy-to-satisfy preferences. -Use in moderation; it's as 'cheaty' as DFHack gets. - -autofarm -======== -Automatically handle crop selection in farm plots based on current plant stocks. -Selects a crop for planting if current stock is below a threshold. -Selected crops are dispatched on all farmplots. - -Usage:: - - autofarm start - autofarm default 30 - autofarm threshold 150 helmet_plump tail_pig - -.. _autolabor-artisans: - -autolabor-artisans -================== -Runs `autolabor`, with settings tuned for small but highly skilled workforces. - -.. _autounsuspend: - -autounsuspend -============= -Automatically unsuspend jobs in workshops, on a recurring basis. -See `unsuspend` for one-off use, or `resume` ``all``. ban-cooking =========== diff --git a/docs/conf.py b/docs/conf.py index 61095a7c98..6d19423358 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -58,11 +58,13 @@ def document_scripts(): kinds['base'].append(s) else: kinds.get(k_fname[0], []).append(s) - template = ('.. include:: /{}\n :start-after: BEGIN_DOCS\n' - ' :end-before: END_DOCS') + template = ('.. _{}:\n\n' + '.. include:: /{}\n' + ' :start-after: =begin\n' + ' :end-before: =end\n') for key, value in kinds.items(): - kinds[key] = [ - template.format(x[1]) for x in sorted(value, key=lambda x: x[0])] + kinds[key] = [template.format(x[0], x[1]) + for x in sorted(value, key=lambda x: x[0])] # Finally, we write our _auto/* files for each kind of script if not os.path.isdir('_auto'): os.mkdir('_auto') @@ -73,7 +75,8 @@ def document_scripts(): 'gui': 'GUI Scripts', 'modtools': 'Scripts for Modders'} for k in head: - title = '{l}\n{t}\n{l}\n\n'.format(t=head[k], l=len(head[k])*'#') + title = '.. _{k}:\n\n{l}\n{t}\n{l}\n\n.. contents::\n\n'.format( + k=k, t=head[k], l=len(head[k])*'#') mode = 'w' if sys.version_info.major > 2 else 'wb' with open('_auto/{}.rst'.format(k), mode) as outfile: outfile.write(title) diff --git a/scripts/adaptation.rb b/scripts/adaptation.rb index 7ed7302d0d..6d2e630179 100644 --- a/scripts/adaptation.rb +++ b/scripts/adaptation.rb @@ -1,5 +1,14 @@ # View or set level of cavern adaptation for the selected unit or the whole fort # based on removebadthoughts.rb +=begin + +adaptation +========== +View or set level of cavern adaptation for the selected unit or the whole fort. +Usage: ``adaptation [value]``. The ``value`` must be +between 0 and 800,000 inclusive. + +=end # Color constants, values mapped to color_value enum in include/ColorText.h COLOR_GREEN = 2 diff --git a/scripts/add-thought.lua b/scripts/add-thought.lua index 7996e90095..0f82b555cd 100644 --- a/scripts/add-thought.lua +++ b/scripts/add-thought.lua @@ -1,18 +1,14 @@ -- Adds emotions to creatures. --@ module = true ---[[ -BEGIN_DOCS - -.. _add-thought: +--[[=begin add-thought =========== Adds a thought or emotion to the selected unit. Can be used by other scripts, or the gui invoked by running ``add-thought gui`` with a unit selected. -END_DOCS -]] +=end]] local utils=require('utils') diff --git a/scripts/armoks-blessing.lua b/scripts/armoks-blessing.lua index c93fb04c87..0ae373c31e 100644 --- a/scripts/armoks-blessing.lua +++ b/scripts/armoks-blessing.lua @@ -3,7 +3,16 @@ -- arguments allow for skills to be adjusted as well -- WARNING: USING THIS SCRIPT WILL ADJUST ALL DWARVES IN PLAY! -- by vjek +--[[=begin +armoks-blessing +=============== +Runs the equivalent of `rejuvenate`, `elevate-physical`, `elevate-mental`, and +`brainwash` on all dwarves currently on the map. This is an extreme change, +which sets every stat to an ideal - legendary skills, great traits, and +easy-to-satisfy preferences. + +=end]] function rejuvenate(unit) if unit==nil then print ("No unit available! Aborting with extreme prejudice.") diff --git a/scripts/autofarm.rb b/scripts/autofarm.rb index cc2f29dff8..ddfa7aae90 100644 --- a/scripts/autofarm.rb +++ b/scripts/autofarm.rb @@ -1,3 +1,19 @@ + +=begin + +autofarm +======== +Automatically handle crop selection in farm plots based on current plant stocks. +Selects a crop for planting if current stock is below a threshold. +Selected crops are dispatched on all farmplots. + +Usage:: + + autofarm start + autofarm default 30 + autofarm threshold 150 helmet_plump tail_pig + +=end class AutoFarm def initialize diff --git a/scripts/autolabor-artisans.lua b/scripts/autolabor-artisans.lua index 61aa963352..22d3946469 100644 --- a/scripts/autolabor-artisans.lua +++ b/scripts/autolabor-artisans.lua @@ -1,5 +1,12 @@ -- Executes an autolabor command for each labor where skill level influences output quality. +--[[=begin + +autolabor-artisans +================== +Runs `autolabor`, with settings tuned for small but highly skilled workforces. + +=end]] local artisan_labors = { "CARPENTER", "DETAIL", diff --git a/scripts/autounsuspend.rb b/scripts/autounsuspend.rb index 9613288ba1..f493cfb680 100644 --- a/scripts/autounsuspend.rb +++ b/scripts/autounsuspend.rb @@ -1,4 +1,12 @@ # un-suspend construction jobs, on a recurring basis +=begin + +autounsuspend +============= +Automatically unsuspend jobs in workshops, on a recurring basis. +See `unsuspend` for one-off use, or `resume` ``all``. + +=end class AutoUnsuspend attr_accessor :running From f8d965b8ea96a4f63751142914e5897a35e0ebe8 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Sat, 24 Oct 2015 01:37:39 +1100 Subject: [PATCH 13/91] Migrate fix, gui script docs; add link shortcuts Because it's a lot easier to link to bug reports this way. The migration is mostly just a copy-paste job, but I'm using keybinding styles where appropriate too. --- docs/Scripts.rst | 440 ------------------------------- docs/conf.py | 16 +- scripts/fix/blood-del.lua | 7 +- scripts/fix/build-location.lua | 8 + scripts/fix/dead-units.lua | 8 + scripts/fix/fat-dwarves.lua | 7 + scripts/fix/feeding-timers.lua | 6 + scripts/fix/item-occupancy.lua | 17 +- scripts/fix/loyaltycascade.rb | 6 + scripts/fix/population-cap.lua | 17 +- scripts/fix/stable-temp.lua | 8 + scripts/fix/stuckdoors.rb | 7 + scripts/gui/advfort.lua | 21 ++ scripts/gui/advfort_items.lua | 8 + scripts/gui/assign-rack.lua | 10 +- scripts/gui/autobutcher.lua | 6 + scripts/gui/choose-weapons.lua | 15 ++ scripts/gui/clone-uniform.lua | 10 + scripts/gui/companion-order.lua | 20 ++ scripts/gui/create-item.lua | 6 + scripts/gui/dfstatus.lua | 8 + scripts/gui/gm-editor.lua | 22 ++ scripts/gui/gm-unit.lua | 8 + scripts/gui/guide-path.lua | 12 + scripts/gui/hack-wish.lua | 7 + scripts/gui/hello-world.lua | 6 + scripts/gui/liquids.lua | 31 +++ scripts/gui/mechanisms.lua | 17 ++ scripts/gui/mod-manager.lua | 13 + scripts/gui/no-dfhack-init.lua | 6 + scripts/gui/power-meter.lua | 6 + scripts/gui/rename.lua | 30 +++ scripts/gui/room-list.lua | 12 + scripts/gui/siege-engine.lua | 6 + scripts/gui/stockpiles.lua | 17 ++ scripts/gui/unit-info-viewer.lua | 7 + scripts/gui/workflow.lua | 64 +++++ scripts/gui/workshop-job.lua | 48 ++++ 38 files changed, 510 insertions(+), 453 deletions(-) diff --git a/docs/Scripts.rst b/docs/Scripts.rst index e6c3495ea4..6a6deff87d 100644 --- a/docs/Scripts.rst +++ b/docs/Scripts.rst @@ -69,443 +69,6 @@ The following pages document all the standard DFHack scripts. /scripts/3rdparty/*/* - - - -fix/blood-del -============= -Makes it so that future caravans won't bring barrels full of blood, ichor, or goo. - -fix/build-location -================== -Fixes construction jobs that are stuck trying to build a wall while standing -on the same exact tile (bug 5991), designates the tile restricted traffic to -hopefully avoid jamming it again, and unsuspends them. - -fix/dead-units -============== -Removes uninteresting dead units from the unit list. Doesn't seem to give any -noticeable performance gain, but migrants normally stop if the unit list grows -to around 3000 units, and this script reduces it back. - -fix/fat-dwarves -=============== -Avoids 5-10% FPS loss due to constant recalculation of insulation for dwarves at -maximum fatness, by reducing the cap from 1,000,000 to 999,999. - -fix/feeding-timers -================== -Reset the GiveWater and GiveFood timers of all units as appropriate. - -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. - -fix/item-occupancy -================== -Diagnoses and fixes issues with nonexistant 'items occupying site', usually -caused by autodump bugs or other hacking mishaps. - -fix/loyaltycascade -================== -Aborts loyalty cascades by fixing units whose own civ is the enemy. - -fix/population-cap -================== -Run this after every migrant wave to ensure your population cap is not exceeded. -The issue with the cap is that it is compared to the population number reported -by the last caravan, so once it drops below the cap, migrants continue to come -until that number is updated again. - -fix/stable-temp -=============== -Instantly sets the temperature of all free-lying items to be in equilibrium with -the environment and stops temperature updates. In order to maintain this efficient -state however, use `tweak` ``stable-temp`` and `tweak` ``fast-heat``. - -fix/stuckdoors -============== -Fix doors that are stuck open due to incorrect map occupancy flags, eg due to -incorrect use of teleport. - - -.. _gui/advfort: - -gui/advfort -=========== -This script allows to perform jobs in adventure mode. For more complete help -press '?' while script is running. It's most comfortable to use this as a -keybinding. (e.g. keybinding set Ctrl-T gui/advfort). Possible arguments: - -* -a or --nodfassign - uses different method to assign items. - -* -i or --inventory - checks inventory for possible items to use in the job. - -* -c or --cheat - relaxes item requirements for buildings (e.g. walls from bones). - implies -a - -* job - selects that job (e.g. Dig or FellTree) - -An example of player digging in adventure mode: - -.. image:: images/advfort.png - -.. admonition:: DISCLAIMER - - advfort changes only persist in non procedural sites. Namely: player forts, caves, camps. - -gui/advfort_items -================= -Does something with items in adventure mode jobs. - -.. _gui/assign-rack: - -gui/assign-rack -=============== -`This script requires a binpatch `, which has not -been available since DF 0.34.11 - -gui/autobutcher -=============== -An in-game interface for `autobutcher`. - -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. - -Depending on the cursor location, it rewrites all 'individual choice weapon' entries -in the selected squad or position to use a specific weapon type matching the assigned -unit's top skill. If the cursor is in the rightmost list over a weapon entry, it rewrites -only that entry, and does it even if it is not 'individual choice'. - -Rationale: individual choice seems to be unreliable when there is a weapon shortage, -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. - -When invoked, the script duplicates the currently selected uniform template, -and selects the newly created copy. - -.. _gui/companion-order: - -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. - -.. image:: images/companion-order.png - -* move - orders selected companions to move to location. If companions are following they will move no more than 3 tiles from you. -* equip - try to equip items on the ground. -* pick-up - try to take items into hand (also wield) -* unequip - remove and drop equipment -* unwield - drop held items -* wait - temporarily remove from party -* follow - rejoin the party after "wait" -* leave - remove from party (can be rejoined by talking) - -.. _gui/create-item: - -gui/create-item -=============== -A graphical interface for creating items. - -gui/dfstatus -============ -Show a quick overview of critical stock quantities, including food, drinks, wood, and various bars. -Sections can be enabled/disabled/configured by editing ``dfhack-config/dfstatus.lua``. - -.. _gui/gm-editor: - -gui/gm-editor -============= -There are three ways to open this editor: - -* using gui/gm-editor command/keybinding - opens editor on what is selected - or viewed (e.g. unit/item description screen) - -* using gui/gm-editor - executes lua command and opens editor on - its results (e.g. gui/gm-editor "df.global.world.items.all" shows all items) - -* using gui/gm-editor dialog - shows an in game dialog to input lua command. Works - the same as version above. - -.. image:: images/gm-editor.png - -This editor allows to change and modify almost anything in df. Press '?' for an -in-game help. - -gui/gm-unit -=========== -An editor for various unit attributes. - -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. - -.. image:: images/guide-path.png - -The script displays the cached path that will be used by the order; the game -computes it when the order is executed for the first time. - -.. _gui/hack-wish: - -gui/hack-wish -============= -An alias for `gui/create-item`. Deprecated. - -gui/hello-world -=============== -A basic example for testing, or to start your own script from. - -gui/liquids -=========== -To use, bind to a key (the example config uses Alt-L) and activate in the 'k' mode. - -.. image:: images/liquids.png - -This script is a gui front-end to `liquids` and works similarly, -allowing you to add or remove water & magma, and create obsidian walls & floors. - -.. warning:: - - There is **no undo support**. Bugs in this plugin have been - known to create pathfinding problems and heat traps. - -The ``b`` key changes how the affected area is selected. The default *Rectangle* -mode works by selecting two corners like any ordinary designation. The ``p`` -key chooses between adding water, magma, obsidian walls & floors, or just -tweaking flags. - -When painting liquids, it is possible to select the desired level with ``+-``, -and choose between setting it exactly, only increasing or only decreasing -with ``s``. - -In addition, ``f`` allows disabling or enabling the flowing water computations -for an area, and ``r`` operates on the "permanent flow" property that makes -rivers power water wheels even when full and technically not flowing. - -After setting up the desired operations using the described keys, use ``Enter`` to apply them. - -gui/mechanisms -============== -To use, bind to a key (the example config uses Ctrl-M) and activate in the 'q' mode. - -.. image:: images/mechanisms.png - -Lists mechanisms connected to the building, and their links. Navigating the list centers -the view on the relevant linked buildings. - -To exit, press ESC or Enter; ESC recenters on the original building, while Enter leaves -focus on the current one. Shift-Enter has an effect equivalent to pressing Enter, and then -re-entering the mechanisms ui. - -gui/mod-manager -=============== -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`_. - -.. _`available here`: https://github.com/warmist/df-mini-mods - -.. image:: images/mod-manager.png - -gui/no-dfhack-init -================== -Shows a warning at startup if no valid ``dfhack.init`` file is found. - -.. _gui/power-meter: - -gui/power-meter -=============== -An in-game interface for `power-meter`. - -.. _gui/rename: - -gui/rename -========== -Backed by `rename`, this script allows entering the desired name -via a simple dialog in the game ui. - -* ``gui/rename [building]`` in 'q' mode changes the name of a building. - - .. image:: images/rename-bld.png - - The selected building must be one of stockpile, workshop, furnace, trap, or siege engine. - It is also possible to rename zones from the 'i' menu. - -* ``gui/rename [unit]`` with a unit selected changes the nickname. - - Unlike the built-in interface, this works even on enemies and animals. - -* ``gui/rename unit-profession`` changes the selected unit's custom profession name. - - .. image:: images/rename-prof.png - - Likewise, this can be applied to any unit, and when used on animals it overrides - their species string. - -The ``building`` or ``unit`` options are automatically assumed when in relevant ui state. - -The example config binds building/unit rename to Ctrl-Shift-N, and -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. - -.. image:: images/room-list.png - -The script lists other rooms owned by the same owner, or by the unit selected in the assign -list, and allows unassigning them. - -.. _gui/siege-engine: - -gui/siege-engine -================ -An in-game interface for `siege-engine`. - -.. _gui/stockpiles: - -gui/stockpiles -============== -An in-game interface for `stocksettings`, to -load and save stockpile settings from the 'q' menu. - -Usage: - -:gui/stockpiles -save: to save the current stockpile -:gui/stockpiles -load: to load settings into the current stockpile -:gui/stockpiles -dir : set the default directory to save settings into -:gui/stockpiles -help: to see this message - -Don't forget to ``enable stockpiles`` and create the ``stocksettings`` directory in -the DF folder before trying to use the GUI. - -gui/unit-info-viewer -==================== -Displays age, birth, maxage, shearing, milking, grazing, egg laying, body size, -and death info about a unit. Recommended keybinding Alt-I. - -.. _gui/workflow: - -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. - -.. image:: images/workflow.png - -This script provides a simple interface to constraints managed by `workflow`. -When active, it displays a list of all constraints applicable to the -current job, and their current status. - -A constraint specifies a certain range to be compared against either individual -*item* or whole *stack* count, an item type and optionally a material. When the -current count is below the lower bound of the range, the job is resumed; if it -is above or equal to the top bound, it will be suspended. Within the range, the -specific constraint has no effect on the job; others may still affect it. - -Pressing 'I' switches the current constraint between counting stacks or items. -Pressing 'R' lets you input the range directly; 'e', 'r', 'd', 'f' adjust the -bounds by 5, 10, or 20 depending on the direction and the 'I' setting (counting -items and expanding the range each gives a 2x bonus). - -Pressing 'A' produces a list of possible outputs of this job as guessed by -workflow, and lets you create a new constraint by choosing one as template. If you -don't see the choice you want in the list, it likely means you have to adjust -the job material first using `job` ``item-material`` or `gui/workshop-job`, -as described in `workflow` documentation. In this manner, this feature -can be used for troubleshooting jobs that don't match the right constraints. - -.. image:: images/workflow-new1.png - -If you select one of the outputs with Enter, the matching constraint is simply -added to the list. If you use Shift-Enter, the interface proceeds to the -next dialog, which allows you to edit the suggested constraint parameters to -suit your need, and set the item count range. - -.. image:: images/workflow-new2.png - -Pressing 'S' (or, with the example config, Alt-W in the 'z' stocks screen) -opens the overall status screen, which was copied from the C++ implementation -by falconne for better integration with the rest of the lua script: - -.. image:: images/workflow-status.png - -This screen shows all currently existing workflow constraints, and allows -monitoring and/or changing them from one screen. The constraint list can -be filtered by typing text in the field below. - -The color of the stock level number indicates how "healthy" the stock level -is, based on current count and trend. Bright green is very good, green is good, -red is bad, bright red is very bad. - -The limit number is also color-coded. Red means that there are currently no -workshops producing that item (i.e. no jobs). If it's yellow, that means the -production has been delayed, possibly due to lack of input materials. - -The chart on the right is a plot of the last 14 days (28 half day plots) worth -of stock history for the selected item, with the rightmost point representing -the current stock value. The bright green dashed line is the target -limit (maximum) and the dark green line is that minus the gap (minimum). - -.. _gui/workshop-job: - -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. - -.. image:: images/workshop-job.png - -The script shows a list of the input reagents of the selected job, and allows changing -them like the `job` ``item-type`` and `job` ``item-material`` commands. - -Specifically, pressing the 'i' key pops up a dialog that lets you select an item -type from a list. - -.. image:: images/workshop-job-item.png - -Pressing 'm', unless the item type does not allow a material, -lets you choose a material. - -.. image:: images/workshop-job-material.png - -Since there are a lot more materials than item types, this dialog is more complex -and uses a hierarchy of sub-menus. List choices that open a sub-menu are marked -with an arrow on the left. - -.. warning:: - - Due to the way input reagent matching works in DF, you must select an item type - if you select a material, or the material will be matched incorrectly in some cases. - If you press 'm' without choosing an item type, the script will auto-choose it - if there is only one valid choice, or pop up an error message box instead of the - material selection dialog. - -Note that both materials and item types presented in the dialogs are filtered -by the job input flags, and even the selected item type for material selection, -or material for item type selection. Many jobs would let you select only one -input item type. - -For example, if you choose a *plant* input item type for your prepare meal job, -it will only let you select cookable materials. - -If you choose a *barrel* item instead (meaning things stored in barrels, like -drink or milk), it will let you select any material, since in this case the -material is matched against the barrel itself. Then, if you select, say, iron, -and then try to change the input item type, now it won't let you select *plant*; -you have to unset the material first. - .. _modtools/add-syndrome: modtools/add-syndrome @@ -620,9 +183,6 @@ modtools/transform-unit Transforms a unit into another unit type, possibly permanently. -============= -Other Scripts -============= ban-cooking =========== diff --git a/docs/conf.py b/docs/conf.py index 6d19423358..bb65f361ee 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -100,7 +100,21 @@ def document_scripts(): # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = [] +extensions = ['sphinx.ext.extlinks'] + +# This config value must be a dictionary of external sites, mapping unique +# short alias names to a base URL and a prefix. +# See http://sphinx-doc.org/ext/extlinks.html +extlinks = { + 'wiki': ('http://dwarffortresswiki.org/%s', ''), + 'forums': ('http://www.bay12forums.com/smf/index.php?topic=%s', + 'Bay12 forums thread '), + 'dffd': ('http://dffd.bay12games.com/file.php?id=%s', 'DFFD file '), + 'bug': ('http://www.bay12games.com/dwarves/mantisbt/view.php?id=%s', + 'Bug ') +} +# some aliases for link directives +extlinks['forum'] = extlinks['forums'] # Add any paths that contain templates here, relative to this directory. templates_path = [] diff --git a/scripts/fix/blood-del.lua b/scripts/fix/blood-del.lua index 907135eb49..88d7d27566 100644 --- a/scripts/fix/blood-del.lua +++ b/scripts/fix/blood-del.lua @@ -1,8 +1,13 @@ ---blood-del.lua --makes it so that civs won't come with barrels full of blood, ichor, or goo --author Urist Da Vinci --edited by expwnent, scamtank +--[[=begin +fix/blood-del +============= +Makes it so that future caravans won't bring barrels full of blood, ichor, or goo. + +=end]] local my_entity=df.historical_entity.find(df.global.ui.civ_id) local sText=" " local k=0 diff --git a/scripts/fix/build-location.lua b/scripts/fix/build-location.lua index 0eea2c780c..9df518ec3e 100644 --- a/scripts/fix/build-location.lua +++ b/scripts/fix/build-location.lua @@ -1,7 +1,15 @@ -- Lets constructions reconsider the build location. -- Partial work-around for http://www.bay12games.com/dwarves/mantisbt/view.php?id=5991 +--[[=begin +fix/build-location +================== +Fixes construction jobs that are stuck trying to build a wall while standing +on the same exact tile (:bug:`5991`), designates the tile restricted traffic to +hopefully avoid jamming it again, and unsuspends them. + +=end]] local utils = require('utils') local count = 0 diff --git a/scripts/fix/dead-units.lua b/scripts/fix/dead-units.lua index 2d5558179b..7687a75cce 100644 --- a/scripts/fix/dead-units.lua +++ b/scripts/fix/dead-units.lua @@ -1,5 +1,13 @@ -- Remove uninteresting dead units from the unit list. +--[[=begin +fix/dead-units +============== +Removes uninteresting dead units from the unit list. Doesn't seem to give any +noticeable performance gain, but migrants normally stop if the unit list grows +to around 3000 units, and this script reduces it back. + +=end]] local units = df.global.world.units.active local dwarf_race = df.global.ui.race_id local dwarf_civ = df.global.ui.civ_id diff --git a/scripts/fix/fat-dwarves.lua b/scripts/fix/fat-dwarves.lua index 5394f6770b..5c450513e9 100644 --- a/scripts/fix/fat-dwarves.lua +++ b/scripts/fix/fat-dwarves.lua @@ -2,7 +2,14 @@ -- -- See for more info: -- http://www.bay12games.com/dwarves/mantisbt/view.php?id=5971 +--[[=begin +fix/fat-dwarves +=============== +Avoids 5-10% FPS loss due to constant recalculation of insulation for dwarves at +maximum fatness, by reducing the cap from 1,000,000 to 999,999. + +=end]] local num_fat = 0 local num_lagging = 0 diff --git a/scripts/fix/feeding-timers.lua b/scripts/fix/feeding-timers.lua index 84c6d45de0..84fab70865 100644 --- a/scripts/fix/feeding-timers.lua +++ b/scripts/fix/feeding-timers.lua @@ -2,7 +2,13 @@ -- original author: tejón -- rewritten by expwnent -- see repeat.lua for how to run this every so often automatically +--[[=begin +fix/feeding-timers +================== +Reset the GiveWater and GiveFood timers of all units as appropriate. + +=end]] local args = {...} if args[1] ~= nil then print("fix/feeding-timers usage") diff --git a/scripts/fix/item-occupancy.lua b/scripts/fix/item-occupancy.lua index 09c6b30306..bcf1b89032 100644 --- a/scripts/fix/item-occupancy.lua +++ b/scripts/fix/item-occupancy.lua @@ -1,10 +1,17 @@ -- Verify item occupancy and block item list integrity. --- --- Checks: --- 1) Item has flags.on_ground <=> it is in the correct block item list --- 2) A tile has items in block item list <=> it has occupancy.item --- 3) The block item lists are sorted. +--[[=begin + +fix/item-occupancy +================== +Diagnoses and fixes issues with nonexistant 'items occupying site', usually +caused by `autodump` bugs or other hacking mishaps. Checks that: + +#. Item has ``flags.on_ground`` <=> it is in the correct block item list +#. A tile has items in block item list <=> it has ``occupancy.item`` +#. The block item lists are sorted + +=end]] local utils = require 'utils' function check_block_items(fix) diff --git a/scripts/fix/loyaltycascade.rb b/scripts/fix/loyaltycascade.rb index b1caf9b105..2cf52dd93a 100644 --- a/scripts/fix/loyaltycascade.rb +++ b/scripts/fix/loyaltycascade.rb @@ -1,5 +1,11 @@ # script to fix loyalty cascade, when you order your militia to kill friendly units +=begin +fix/loyaltycascade +================== +Aborts loyalty cascades by fixing units whose own civ is the enemy. + +=end def fixunit(unit) return if unit.race != df.ui.race_id or unit.civ_id != df.ui.civ_id links = unit.hist_figure_tg.entity_links diff --git a/scripts/fix/population-cap.lua b/scripts/fix/population-cap.lua index c2e3293fb2..483941982a 100644 --- a/scripts/fix/population-cap.lua +++ b/scripts/fix/population-cap.lua @@ -1,11 +1,18 @@ -- Communicates current population to mountainhomes to avoid cap overshooting. --- The reason for population cap problems is that the population value it --- is compared against comes from the last dwarven caravan that successfully --- left for mountainhomes. This script instantly updates it. --- Note that a migration wave can still overshoot the limit by 1-2 dwarves because --- of the last migrant bringing his family. Likewise, king arrival ignores cap. +--[[=begin +fix/population-cap +================== +Run this after every migrant wave to ensure your population cap is not exceeded. + +The reason for population cap problems is that the population value it +is compared against comes from the last dwarven caravan that successfully +left for mountainhomes. This script instantly updates it. +Note that a migration wave can still overshoot the limit by 1-2 dwarves because +of the last migrant bringing his family. Likewise, king arrival ignores cap. + +=end]] local args = {...} local ui = df.global.ui diff --git a/scripts/fix/stable-temp.lua b/scripts/fix/stable-temp.lua index 63739f8ea3..a67bc7658f 100644 --- a/scripts/fix/stable-temp.lua +++ b/scripts/fix/stable-temp.lua @@ -1,5 +1,13 @@ -- Reset item temperature to the value of their tile. +--[[=begin +fix/stable-temp +=============== +Instantly sets the temperature of all free-lying items to be in equilibrium with +the environment and stops temperature updates. In order to maintain this efficient +state however, use `tweak` ``stable-temp`` and `tweak` ``fast-heat``. + +=end]] local args = {...} local apply = (args[1] == 'apply') diff --git a/scripts/fix/stuckdoors.rb b/scripts/fix/stuckdoors.rb index 249ed58102..f99d0f2633 100644 --- a/scripts/fix/stuckdoors.rb +++ b/scripts/fix/stuckdoors.rb @@ -2,7 +2,14 @@ # this may happen after people mess with the game by (incorrectly) teleporting units or items # a door may stick open if the map occupancy flags are wrong +=begin +fix/stuckdoors +============== +Fix doors that are stuck open due to incorrect map occupancy flags, eg due to +incorrect use of `teleport`. + +=end count = 0 df.world.buildings.all.each { |bld| # for all doors diff --git a/scripts/gui/advfort.lua b/scripts/gui/advfort.lua index f02fd6a697..6a15750e8e 100644 --- a/scripts/gui/advfort.lua +++ b/scripts/gui/advfort.lua @@ -1,5 +1,26 @@ -- allows to do jobs in adv. mode. +--[[=begin + +gui/advfort +=========== +This script allows to perform jobs in adventure mode. For more complete help +press :kbd:`?` while script is running. It's most comfortable to use this as a +keybinding. (e.g. ``keybinding set Ctrl-T gui/advfort``). Possible arguments: + +:-a, --nodfassign: uses different method to assign items. +:-i, --inventory: checks inventory for possible items to use in the job. +:-c, --cheat: relaxes item requirements for buildings (e.g. walls from bones). Implies -a +:job: selects that job (e.g. Dig or FellTree) + +An example of player digging in adventure mode: + +.. image:: /docs/images/advfort.png + +**WANRING:** changes only persist in non procedural sites, namely: player forts, caves, and camps. + +=end]] + --[==[ version: 0.044 changelog: diff --git a/scripts/gui/advfort_items.lua b/scripts/gui/advfort_items.lua index fb44413972..3727bf9a4a 100644 --- a/scripts/gui/advfort_items.lua +++ b/scripts/gui/advfort_items.lua @@ -1,3 +1,11 @@ + +--[[=begin + +gui/advfort_items +================= +Does something with items in adventure mode jobs. + +=end]] local _ENV = mkmodule('hack.scripts.gui.advfort_items') local gui=require('gui') diff --git a/scripts/gui/assign-rack.lua b/scripts/gui/assign-rack.lua index 92535d793c..3b18aa13e8 100644 --- a/scripts/gui/assign-rack.lua +++ b/scripts/gui/assign-rack.lua @@ -1,7 +1,15 @@ -- Assign weapon racks to squads. Requires the weaponrack-unassign patch. --- See bug 1445 for more info about the patches. +--[[=begin +gui/assign-rack +=============== +`This script requires a binpatch `, which has not +been available since DF 0.34.11 + +See :bug:`1445` for more info about the patches. + +=end]] local utils = require 'utils' local gui = require 'gui' local guidm = require 'gui.dwarfmode' diff --git a/scripts/gui/autobutcher.lua b/scripts/gui/autobutcher.lua index 013406f33b..59f3733c12 100644 --- a/scripts/gui/autobutcher.lua +++ b/scripts/gui/autobutcher.lua @@ -1,5 +1,11 @@ -- A GUI front-end for the autobutcher plugin. +--[[=begin +gui/autobutcher +=============== +An in-game interface for `autobutcher`. + +=end]] local gui = require 'gui' local utils = require 'utils' local widgets = require 'gui.widgets' diff --git a/scripts/gui/choose-weapons.lua b/scripts/gui/choose-weapons.lua index 85ad62b6e2..f545e1d30b 100644 --- a/scripts/gui/choose-weapons.lua +++ b/scripts/gui/choose-weapons.lua @@ -1,5 +1,20 @@ -- Rewrite individual choice weapons into specific types. +--[[=begin +gui/choose-weapons +================== +Bind to a key (the example config uses :kbd:`Ctrl`:kbd:`W`), and activate in the Equip->View/Customize +page of the military screen. + +Depending on the cursor location, it rewrites all 'individual choice weapon' entries +in the selected squad or position to use a specific weapon type matching the assigned +unit's top skill. If the cursor is in the rightmost list over a weapon entry, it rewrites +only that entry, and does it even if it is not 'individual choice'. + +Rationale: individual choice seems to be unreliable when there is a weapon shortage, +and may lead to inappropriate weapons being selected. + +=end]] local utils = require 'utils' local dlg = require 'gui.dialogs' diff --git a/scripts/gui/clone-uniform.lua b/scripts/gui/clone-uniform.lua index 2257c655f6..9893c38690 100644 --- a/scripts/gui/clone-uniform.lua +++ b/scripts/gui/clone-uniform.lua @@ -1,5 +1,15 @@ -- Clone the current uniform template in the military screen. +--[[=begin +gui/clone-uniform +================= +Bind to a key (the example config uses :kbd:`Ctrl`:kbd:`C`), and activate in the Uniforms +page of the military screen with the cursor in the leftmost list. + +When invoked, the script duplicates the currently selected uniform template, +and selects the newly created copy. + +=end]] local utils = require 'utils' local gui = require 'gui' diff --git a/scripts/gui/companion-order.lua b/scripts/gui/companion-order.lua index bef1e0968a..9d901a4c94 100644 --- a/scripts/gui/companion-order.lua +++ b/scripts/gui/companion-order.lua @@ -1,4 +1,24 @@ +--[[=begin + +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. + +.. image:: /docs/images/companion-order.png + +* move - orders selected companions to move to location. If companions are following they will move no more than 3 tiles from you. +* equip - try to equip items on the ground. +* pick-up - try to take items into hand (also wield) +* unequip - remove and drop equipment +* unwield - drop held items +* wait - temporarily remove from party +* follow - rejoin the party after "wait" +* leave - remove from party (can be rejoined by talking) + +=end]] + local gui = require 'gui' local dlg = require 'gui.dialogs' local args={...} diff --git a/scripts/gui/create-item.lua b/scripts/gui/create-item.lua index 2339c28c2e..b32b91a9bc 100644 --- a/scripts/gui/create-item.lua +++ b/scripts/gui/create-item.lua @@ -4,7 +4,13 @@ -- edited by expwnent --@module = true +--[[=begin +gui/create-item +=============== +A graphical interface for creating items. + +=end]] local function getGenderString(gender) local genderStr if gender==0 then diff --git a/scripts/gui/dfstatus.lua b/scripts/gui/dfstatus.lua index 32758cfbfa..9789affbcd 100644 --- a/scripts/gui/dfstatus.lua +++ b/scripts/gui/dfstatus.lua @@ -1,6 +1,14 @@ -- a quick access status screen -- originally written by enjia2000@gmail.com (stolencatkarma) +--[[=begin + +gui/dfstatus +============ +Show a quick overview of critical stock quantities, including food, drinks, wood, and various bars. +Sections can be enabled/disabled/configured by editing ``dfhack-config/dfstatus.lua``. + +=end]] local gui = require 'gui' function warn(msg) diff --git a/scripts/gui/gm-editor.lua b/scripts/gui/gm-editor.lua index 0743e19074..da0cf73c67 100644 --- a/scripts/gui/gm-editor.lua +++ b/scripts/gui/gm-editor.lua @@ -1,4 +1,26 @@ -- Interface powered item editor. + +--[[=begin + +gui/gm-editor +============= +There are three ways to open this editor: + +* using gui/gm-editor command/keybinding - opens editor on what is selected + or viewed (e.g. unit/item description screen) + +* using gui/gm-editor - executes lua command and opens editor on + its results (e.g. ``gui/gm-editor "df.global.world.items.all"`` shows all items) + +* using gui/gm-editor dialog - shows an in game dialog to input lua command. Works + the same as version above. + +.. image:: /docs/images/gm-editor.png + +This editor allows to change and modify almost anything in df. Press :kbd:`?` for +in-game help. + +=end]] local gui = require 'gui' local dialog = require 'gui.dialogs' local widgets =require 'gui.widgets' diff --git a/scripts/gui/gm-unit.lua b/scripts/gui/gm-unit.lua index 4855527293..e25ebf944e 100644 --- a/scripts/gui/gm-unit.lua +++ b/scripts/gui/gm-unit.lua @@ -1,4 +1,12 @@ -- Interface powered (somewhat user friendly) unit editor. + +--[[=begin + +gui/gm-unit +=========== +An editor for various unit attributes. + +=end]] local gui = require 'gui' local dialog = require 'gui.dialogs' local widgets =require 'gui.widgets' diff --git a/scripts/gui/guide-path.lua b/scripts/gui/guide-path.lua index a807e032d4..aa77c9deae 100644 --- a/scripts/gui/guide-path.lua +++ b/scripts/gui/guide-path.lua @@ -1,5 +1,17 @@ -- Show and manipulate the path used by Guide Cart orders. +--[[=begin +gui/guide-path +============== +Bind to a key (the example config uses :kbd:`Alt`:kbd:`P`), and activate in the Hauling menu with +the cursor over a Guide order. + +.. image:: /docs/images/guide-path.png + +The script displays the cached path that will be used by the order; the game +computes it when the order is executed for the first time. + +=end]] local utils = require 'utils' local gui = require 'gui' local guidm = require 'gui.dwarfmode' diff --git a/scripts/gui/hack-wish.lua b/scripts/gui/hack-wish.lua index 023ef9321c..de423abc26 100644 --- a/scripts/gui/hack-wish.lua +++ b/scripts/gui/hack-wish.lua @@ -1 +1,8 @@ --@ alias = 'gui/create-item' +--[[=begin + +gui/hack-wish +============= +An alias for `gui/create-item`. Deprecated. + +=end]] \ No newline at end of file diff --git a/scripts/gui/hello-world.lua b/scripts/gui/hello-world.lua index 122f2cd386..324aa11ad5 100644 --- a/scripts/gui/hello-world.lua +++ b/scripts/gui/hello-world.lua @@ -1,5 +1,11 @@ -- Test lua viewscreens. +--[[=begin +gui/hello-world +=============== +A basic example for testing, or to start your own script from. + +=end]] local gui = require 'gui' local text = 'Woohoo, lua viewscreen :)' diff --git a/scripts/gui/liquids.lua b/scripts/gui/liquids.lua index 322ae69524..27c454f9eb 100644 --- a/scripts/gui/liquids.lua +++ b/scripts/gui/liquids.lua @@ -1,5 +1,36 @@ -- Interface front-end for liquids plugin. +--[[=begin +gui/liquids +=========== +To use, bind to a key (the example config uses Alt-L) and activate in the :kbd:`k` mode. + +.. image:: /docs/images/liquids.png + +This script is a gui front-end to `liquids` and works similarly, +allowing you to add or remove water & magma, and create obsidian walls & floors. + +.. warning:: + + There is **no undo support**. Bugs in this plugin have been + known to create pathfinding problems and heat traps. + +The :kbd:`b` key changes how the affected area is selected. The default *Rectangle* +mode works by selecting two corners like any ordinary designation. The :kbd:`p` +key chooses between adding water, magma, obsidian walls & floors, or just +tweaking flags. + +When painting liquids, it is possible to select the desired level with :kbd:`+`:kbd:`-`, +and choose between setting it exactly, only increasing or only decreasing +with :kbd:`s`. + +In addition, :kbd:`f` allows disabling or enabling the flowing water computations +for an area, and :kbd:`r` operates on the "permanent flow" property that makes +rivers power water wheels even when full and technically not flowing. + +After setting up the desired operations using the described keys, use :kbd:`Enter` to apply them. + +=end]] local utils = require 'utils' local gui = require 'gui' local guidm = require 'gui.dwarfmode' diff --git a/scripts/gui/mechanisms.lua b/scripts/gui/mechanisms.lua index 607625524e..d65782469d 100644 --- a/scripts/gui/mechanisms.lua +++ b/scripts/gui/mechanisms.lua @@ -1,5 +1,22 @@ -- Shows mechanisms linked to the current building. +--[[=begin +gui/mechanisms +============== +To use, bind to a key (the example config uses :kbd:`Ctrl`:kbd:`M`) +and activate in :kbd:`q` mode. + +.. image:: /docs/images/mechanisms.png + +Lists mechanisms connected to the building, and their links. Navigating +the list centers the view on the relevant linked buildings. + +To exit, press :kbd:`Esc` or :kbd:`Enter`; :kbd:`Esc` recenters on +the original building, while :kbd:`Enter` leaves focus on the current +one. :kbd:`Shift`:kbd:`Enter` has an effect equivalent to pressing +:kbd:`Enter`, and then re-entering the mechanisms UI. + +=end]] local utils = require 'utils' local gui = require 'gui' local guidm = require 'gui.dwarfmode' diff --git a/scripts/gui/mod-manager.lua b/scripts/gui/mod-manager.lua index 2f2aa92ba7..3ff46525ea 100644 --- a/scripts/gui/mod-manager.lua +++ b/scripts/gui/mod-manager.lua @@ -1,7 +1,20 @@ -- a graphical mod manager for df local gui=require 'gui' local widgets=require 'gui.widgets' +--[[=begin +gui/mod-manager +=============== +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`_. + +.. _`available here`: https://github.com/warmist/df-mini-mods + +.. image:: /docs/images/mod-manager.png + +=end]] local entity_file=dfhack.getDFPath().."/raw/objects/entity_default.txt" local init_file=dfhack.getDFPath().."/raw/init.lua" local mod_dir=dfhack.getDFPath().."/hack/mods" diff --git a/scripts/gui/no-dfhack-init.lua b/scripts/gui/no-dfhack-init.lua index f6171d5c79..c4352211dd 100644 --- a/scripts/gui/no-dfhack-init.lua +++ b/scripts/gui/no-dfhack-init.lua @@ -1,5 +1,11 @@ -- Shows the warning about missing configuration file. +--[[=begin +gui/no-dfhack-init +================== +Shows a warning at startup if no valid :file:`dfhack.init` file is found. + +=end]] local gui = require 'gui' local dlg = require 'gui.dialogs' diff --git a/scripts/gui/power-meter.lua b/scripts/gui/power-meter.lua index ac30c92730..51908bd0fc 100644 --- a/scripts/gui/power-meter.lua +++ b/scripts/gui/power-meter.lua @@ -1,5 +1,11 @@ -- Interface front-end for power-meter plugin. +--[[=begin +gui/power-meter +=============== +An in-game interface for `power-meter`. + +=end]] local utils = require 'utils' local gui = require 'gui' local guidm = require 'gui.dwarfmode' diff --git a/scripts/gui/rename.lua b/scripts/gui/rename.lua index 70a09b2fab..3433f48815 100644 --- a/scripts/gui/rename.lua +++ b/scripts/gui/rename.lua @@ -1,5 +1,35 @@ -- Rename various objects via gui. +--[[=begin +gui/rename +========== +Backed by `rename`, this script allows entering the desired name +via a simple dialog in the game ui. + +* ``gui/rename [building]`` in :kbd:`q` mode changes the name of a building. + + .. image:: /docs/images/rename-bld.png + + The selected building must be one of stockpile, workshop, furnace, trap, or siege engine. + It is also possible to rename zones from the :kbd:`i` menu. + +* ``gui/rename [unit]`` with a unit selected changes the nickname. + + Unlike the built-in interface, this works even on enemies and animals. + +* ``gui/rename unit-profession`` changes the selected unit's custom profession name. + + .. image:: /docs/images/rename-prof.png + + Likewise, this can be applied to any unit, and when used on animals it overrides + their species string. + +The ``building`` or ``unit`` options are automatically assumed when in relevant UI state. + +The example config binds building/unit rename to :kbd:`Ctrl`:kbd:`Shift`:kbd:`N`, and +unit profession change to :kbd:`Ctrl`:kbd:`Shift`:kbd:`T`. + +=end]] local gui = require 'gui' local dlg = require 'gui.dialogs' local plugin = require 'plugins.rename' diff --git a/scripts/gui/room-list.lua b/scripts/gui/room-list.lua index 1f3e663da4..ac68903178 100644 --- a/scripts/gui/room-list.lua +++ b/scripts/gui/room-list.lua @@ -1,5 +1,17 @@ -- Browses rooms owned by a unit. +--[[=begin +gui/room-list +============= +To use, bind to a key (the example config uses :kbd:`Alt`:kbd:`R`) and activate in :kbd:`q` mode, +either immediately or after opening the assign owner page. + +.. image:: /docs/images/room-list.png + +The script lists other rooms owned by the same owner, or by the unit selected in the assign +list, and allows unassigning them. + +=end]] local utils = require 'utils' local gui = require 'gui' local guidm = require 'gui.dwarfmode' diff --git a/scripts/gui/siege-engine.lua b/scripts/gui/siege-engine.lua index 1e52008758..a880404706 100644 --- a/scripts/gui/siege-engine.lua +++ b/scripts/gui/siege-engine.lua @@ -1,5 +1,11 @@ -- Front-end for the siege engine plugin. +--[[=begin +gui/siege-engine +================ +An in-game interface for `siege-engine`. + +=end]] local utils = require 'utils' local gui = require 'gui' local guidm = require 'gui.dwarfmode' diff --git a/scripts/gui/stockpiles.lua b/scripts/gui/stockpiles.lua index 638ae2894e..4e2f28281a 100644 --- a/scripts/gui/stockpiles.lua +++ b/scripts/gui/stockpiles.lua @@ -1,5 +1,22 @@ -- lave/load stockpile settings with a GUI +--[[=begin +gui/stockpiles +============== +An in-game interface for `stocksettings`, to +load and save stockpile settings from the :kbd:`q` menu. + +Usage: + +:gui/stockpiles -save: to save the current stockpile +:gui/stockpiles -load: to load settings into the current stockpile +:gui/stockpiles -dir : set the default directory to save settings into +:gui/stockpiles -help: to see this message + +Don't forget to ``enable stockpiles`` and create the ``stocksettings`` directory in +the DF folder before trying to use the GUI. + +=end]] local stock = require 'plugins.stockpiles' function check_enabled() diff --git a/scripts/gui/unit-info-viewer.lua b/scripts/gui/unit-info-viewer.lua index 8e42a86c8e..1d7cb763d4 100644 --- a/scripts/gui/unit-info-viewer.lua +++ b/scripts/gui/unit-info-viewer.lua @@ -3,7 +3,14 @@ -- version 1.04 -- original author: Kurik Amudnil -- edited by expwnent +--[[=begin +gui/unit-info-viewer +==================== +Displays age, birth, maxage, shearing, milking, grazing, egg laying, body size, +and death info about a unit. Recommended keybinding :kbd:`Alt`:kbd:`I`. + +=end]] local gui = require 'gui' local widgets =require 'gui.widgets' local utils = require 'utils' diff --git a/scripts/gui/workflow.lua b/scripts/gui/workflow.lua index 77a87c9ce3..67b7477fc8 100644 --- a/scripts/gui/workflow.lua +++ b/scripts/gui/workflow.lua @@ -1,5 +1,69 @@ -- A GUI front-end for the workflow plugin. +--[[=begin +gui/workflow +============ +Bind to a key (the example config uses Alt-W), and activate with a job selected +in a workshop in :kbd:`q` mode. + +.. image:: /docs/images/workflow.png + +This script provides a simple interface to constraints managed by `workflow`. +When active, it displays a list of all constraints applicable to the +current job, and their current status. + +A constraint specifies a certain range to be compared against either individual +*item* or whole *stack* count, an item type and optionally a material. When the +current count is below the lower bound of the range, the job is resumed; if it +is above or equal to the top bound, it will be suspended. Within the range, the +specific constraint has no effect on the job; others may still affect it. + +Pressing :kbd:`i` switches the current constraint between counting stacks or items. +Pressing :kbd:`r` lets you input the range directly; +:kbd:`e`, :kbd:`r`, :kbd:`d`, :kbd:`f` adjust the +bounds by 5, 10, or 20 depending on the direction and the :kbd:`i` setting (counting +items and expanding the range each gives a 2x bonus). + +Pressing :kbd:`a` produces a list of possible outputs of this job as guessed by +workflow, and lets you create a new constraint by choosing one as template. If you +don't see the choice you want in the list, it likely means you have to adjust +the job material first using `job` ``item-material`` or `gui/workshop-job`, +as described in the `workflow` documentation. In this manner, this feature +can be used for troubleshooting jobs that don't match the right constraints. + +.. image:: /docs/images/workflow-new1.png + +If you select one of the outputs with :kbd:`Enter`, the matching constraint is simply +added to the list. If you use :kbd:`Shift`:kbd:`Enter`, the interface proceeds to the +next dialog, which allows you to edit the suggested constraint parameters to +suit your need, and set the item count range. + +.. image:: /docs/images/workflow-new2.png + +Pressing :kbd:`s` (or, with the example config, Alt-W in the :kbd:`z` stocks screen) +opens the overall status screen, which was copied from the C++ implementation +by falconne for better integration with the rest of the lua script: + +.. image:: /docs/images/workflow-status.png + +This screen shows all currently existing workflow constraints, and allows +monitoring and/or changing them from one screen. The constraint list can +be filtered by typing text in the field below. + +The color of the stock level number indicates how "healthy" the stock level +is, based on current count and trend. Bright green is very good, green is good, +red is bad, bright red is very bad. + +The limit number is also color-coded. Red means that there are currently no +workshops producing that item (i.e. no jobs). If it's yellow, that means the +production has been delayed, possibly due to lack of input materials. + +The chart on the right is a plot of the last 14 days (28 half day plots) worth +of stock history for the selected item, with the rightmost point representing +the current stock value. The bright green dashed line is the target +limit (maximum) and the dark green line is that minus the gap (minimum). + +=end]] local utils = require 'utils' local gui = require 'gui' local guidm = require 'gui.dwarfmode' diff --git a/scripts/gui/workshop-job.lua b/scripts/gui/workshop-job.lua index c4e2036142..f3af15d10b 100644 --- a/scripts/gui/workshop-job.lua +++ b/scripts/gui/workshop-job.lua @@ -1,5 +1,53 @@ -- Show and modify properties of jobs in a workshop. +--[[=begin +gui/workshop-job +================ +Bind to a key (the example config uses :kbd:`Alt`:kbd:`a`), and activate with a job selected in +a workshop in the :kbd:`q` mode. + +.. image:: /docs/images/workshop-job.png + +The script shows a list of the input reagents of the selected job, and allows changing +them like the `job` ``item-type`` and `job` ``item-material`` commands. + +Specifically, pressing the :kbd:`i` key pops up a dialog that lets you select an item +type from a list. + +.. image:: /docs/images/workshop-job-item.png + +Pressing :kbd:`m`, unless the item type does not allow a material, +lets you choose a material. + +.. image:: /docs/images/workshop-job-material.png + +Since there are a lot more materials than item types, this dialog is more complex +and uses a hierarchy of sub-menus. List choices that open a sub-menu are marked +with an arrow on the left. + +.. warning:: + + Due to the way input reagent matching works in DF, you must select an item type + if you select a material, or the material will be matched incorrectly in some cases. + If you press :kbd:`m` without choosing an item type, the script will auto-choose + if there is only one valid choice, or pop up an error message box instead of the + material selection dialog. + +Note that both materials and item types presented in the dialogs are filtered +by the job input flags, and even the selected item type for material selection, +or material for item type selection. Many jobs would let you select only one +input item type. + +For example, if you choose a *plant* input item type for your prepare meal job, +it will only let you select cookable materials. + +If you choose a *barrel* item instead (meaning things stored in barrels, like +drink or milk), it will let you select any material, since in this case the +material is matched against the barrel itself. Then, if you select, say, iron, +and then try to change the input item type, now it won't let you select *plant*; +you have to unset the material first. + +=end]] local utils = require 'utils' local gui = require 'gui' local guidm = require 'gui.dwarfmode' From abb882618b78e903f1fcc6cd1ff5601cb9b9edba Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Sat, 24 Oct 2015 10:57:04 +1100 Subject: [PATCH 14/91] Move modtools docs --- docs/Scripts.rst | 115 ------------------ scripts/modtools/add-syndrome.lua | 7 +- scripts/modtools/anonymous-script.lua | 14 ++- scripts/modtools/create-item.lua | 7 ++ scripts/modtools/create-unit.lua | 7 ++ scripts/modtools/equip-item.lua | 7 ++ scripts/modtools/force.lua | 6 + scripts/modtools/interaction-trigger.lua | 9 ++ scripts/modtools/invader-item-destroyer.lua | 7 ++ scripts/modtools/item-trigger.lua | 8 ++ scripts/modtools/moddable-gods.lua | 7 ++ scripts/modtools/outside-only.lua | 8 ++ scripts/modtools/projectile-trigger.lua | 6 + scripts/modtools/random-trigger.lua | 11 +- scripts/modtools/reaction-product-trigger.lua | 7 ++ .../modtools/reaction-trigger-transition.lua | 14 ++- scripts/modtools/reaction-trigger.lua | 8 ++ scripts/modtools/skill-change.lua | 14 +++ scripts/modtools/spawn-flow.lua | 6 + scripts/modtools/syndrome-trigger.lua | 6 + scripts/modtools/transform-unit.lua | 10 +- 21 files changed, 161 insertions(+), 123 deletions(-) diff --git a/docs/Scripts.rst b/docs/Scripts.rst index 6a6deff87d..3d12cc5d3b 100644 --- a/docs/Scripts.rst +++ b/docs/Scripts.rst @@ -69,121 +69,6 @@ The following pages document all the standard DFHack scripts. /scripts/3rdparty/*/* -.. _modtools/add-syndrome: - -modtools/add-syndrome -===================== -This allows adding and removing syndromes from units. - -modtools/anonymous-script -========================= -This allows running a short simple Lua script passed as an argument instead of -running a script from a file. This is useful when you want to do something too -complicated to make with the existing modtools, but too simple to be worth its -own script file. - -modtools/create-item -==================== -This is mostly the same as the other create item tools, but it uses standard -arguments. The other versions will be phased out in a later version. - -modtools/create-unit -==================== -Creates a unit. - -.. _modtools/equip-item: - -modtools/equip-item -=================== -Force a unit to equip an item; useful in conjunction with the ``create`` -scripts above. - -See also `forceequip`. - -modtools/force -============== -This tool triggers events like megabeasts, caravans, invaders, and migrants. - -modtools/interaction-trigger -============================ -This triggers events when a unit uses an interaction on another. It works by -scanning the announcements for the correct attack verb, so the attack verb -must be specified in the interaction. It includes an option to suppress this -announcement after it finds it. - -modtools/invader-item-destroyer -=============================== -This tool configurably destroys invader items to prevent clutter or to prevent -the player from getting tools exclusive to certain races. - -.. _modtools/item-trigger: - -modtools/item-trigger -===================== -This powerful tool triggers DFHack commands when a unit equips, unequips, or -attacks another unit with specified item types, specified item materials, or -specified item contaminants. - -modtools/moddable-gods -====================== -This is a standardized version of Putnam's moddableGods script. It allows you -to create gods on the command-line. - -modtools/outside-only -===================== -This allows you to specify certain custom buildings as outside only, or inside -only. If the player attempts to build a building in an inappropriate location, -the building will be destroyed. - -modtools/projectile-trigger -=========================== -This triggers dfhack commands when projectiles hit their targets. - -modtools/random-trigger -======================= -This triggers random dfhack commands with specified probabilities. - -.. _modtools/reaction-product-trigger: - -modtools/reaction-product-trigger -================================= -This triggers dfhack commands when reaction products are produced, once per -product. - -.. _modtools/reaction-trigger: - -modtools/reaction-trigger -========================= -Triggers dfhack commands when custom reactions complete, regardless of whether -it produced anything, once per completion. - -.. _modtools/reaction-trigger-transition: - -modtools/reaction-trigger-transition -==================================== -Scans raw files and creates a file to help modders transition from -autoSyndrome to reaction-trigger. - -.. _modtools/skill-change: - -modtools/skill-change -===================== -Sets or modifies a skill of a unit. - -modtools/spawn-flow -=================== -Creates flows at the specified location. - -modtools/syndrome-trigger -========================= -Triggers dfhack commands when syndromes are applied to units. - -modtools/transform-unit -======================= -Transforms a unit into another unit type, possibly permanently. - - - ban-cooking =========== A more convenient way to ban cooking various categories of foods than the diff --git a/scripts/modtools/add-syndrome.lua b/scripts/modtools/add-syndrome.lua index e151e1701b..4c04b05bd9 100644 --- a/scripts/modtools/add-syndrome.lua +++ b/scripts/modtools/add-syndrome.lua @@ -1,7 +1,12 @@ --modtools/add-syndrome.lua --author expwnent ---add syndromes to a target, or remove them +--[[=begin +modtools/add-syndrome +===================== +This allows adding and removing syndromes from units. + +=end]] local syndromeUtil = require 'syndrome-util' local utils = require 'utils' diff --git a/scripts/modtools/anonymous-script.lua b/scripts/modtools/anonymous-script.lua index 8e3ae1e7b9..3aecb918cf 100644 --- a/scripts/modtools/anonymous-script.lua +++ b/scripts/modtools/anonymous-script.lua @@ -1,9 +1,19 @@ --scripts/modtools/anonymous-script.lua --author expwnent --a tool for invoking simple lua scripts without putting them in a file first ---anonymous-script "print(args[1])" arg1 arg2 ---# prints "arg1" +--[[=begin +modtools/anonymous-script +========================= +This allows running a short simple Lua script passed as an argument instead of +running a script from a file. This is useful when you want to do something too +complicated to make with the existing modtools, but too simple to be worth its +own script file. Example:: + + anonymous-script "print(args[1])" arg1 arg2 + # prints "arg1" + +=end]] local args = {...} --automatically collect arguments to make the anonymous script more succinct diff --git a/scripts/modtools/create-item.lua b/scripts/modtools/create-item.lua index b7c88bb45f..0f38eafa0b 100644 --- a/scripts/modtools/create-item.lua +++ b/scripts/modtools/create-item.lua @@ -1,7 +1,14 @@ --scripts/modtools/create-item.lua --author expwnent --creates an item of a given type and material +--[[=begin +modtools/create-item +==================== +This is mostly the same as the other create item tools, but it uses standard +arguments. The other versions will be phased out in a later version. + +=end]] local utils = require 'utils' validArgs = --[[validArgs or--]] utils.invert({ diff --git a/scripts/modtools/create-unit.lua b/scripts/modtools/create-unit.lua index 948b94486b..b80a223743 100644 --- a/scripts/modtools/create-unit.lua +++ b/scripts/modtools/create-unit.lua @@ -12,6 +12,13 @@ set invasion_id, etc announcement for fake natural birth if appropriate ]] +--[[=begin + +modtools/create-unit +==================== +Creates a unit. Use ``modtools/create-unit -help`` for more info. + +=end]] --[[ if dfhack.gui.getCurViewscreen()._type ~= df.viewscreen_dwarfmodest or df.global.ui.main.mode ~= df.ui_sidebar_mode.LookAround then diff --git a/scripts/modtools/equip-item.lua b/scripts/modtools/equip-item.lua index 492fe2b1b8..359d983d68 100644 --- a/scripts/modtools/equip-item.lua +++ b/scripts/modtools/equip-item.lua @@ -1,6 +1,13 @@ -- modtools/equip-item.lua -- equip an item on a unit with a particular body part +--[[=begin +modtools/equip-item +=================== +Force a unit to equip an item with a particular body part; useful in +conjunction with the ``create`` scripts above. See also `forceequip`. + +=end]] local utils = require 'utils' function equipItem(unit, item, bodyPart, mode) diff --git a/scripts/modtools/force.lua b/scripts/modtools/force.lua index 2930d29302..2ae5300fae 100644 --- a/scripts/modtools/force.lua +++ b/scripts/modtools/force.lua @@ -2,7 +2,13 @@ -- author Putnam -- edited by expwnent -- Forces an event. +--[[=begin +modtools/force +============== +This tool triggers events like megabeasts, caravans, invaders, and migrants. + +=end]] local utils = require 'utils' local function findCiv(arg) diff --git a/scripts/modtools/interaction-trigger.lua b/scripts/modtools/interaction-trigger.lua index 10eca5d4ea..bf3a1c4f7e 100644 --- a/scripts/modtools/interaction-trigger.lua +++ b/scripts/modtools/interaction-trigger.lua @@ -1,7 +1,16 @@ --scripts/modtools/interaction-trigger.lua --author expwnent --triggers scripts when a unit does a unit interaction on another +--[[=begin +modtools/interaction-trigger +============================ +This triggers events when a unit uses an interaction on another. It works by +scanning the announcements for the correct attack verb, so the attack verb +must be specified in the interaction. It includes an option to suppress this +announcement after it finds it. + +=end]] local eventful = require 'plugins.eventful' local utils = require 'utils' diff --git a/scripts/modtools/invader-item-destroyer.lua b/scripts/modtools/invader-item-destroyer.lua index 2ec5eb5825..425d910e23 100644 --- a/scripts/modtools/invader-item-destroyer.lua +++ b/scripts/modtools/invader-item-destroyer.lua @@ -1,7 +1,14 @@ --scripts/modtools/invader-item-destroyer.lua --author expwnent --configurably deletes invader items when they die +--[[=begin +modtools/invader-item-destroyer +=============================== +This tool configurably destroys invader items to prevent clutter or to prevent +the player from getting tools exclusive to certain races. + +=end]] local eventful = require 'plugins.eventful' local utils = require 'utils' diff --git a/scripts/modtools/item-trigger.lua b/scripts/modtools/item-trigger.lua index c7f9c6d18e..78c8a43323 100644 --- a/scripts/modtools/item-trigger.lua +++ b/scripts/modtools/item-trigger.lua @@ -2,7 +2,15 @@ --author expwnent --based on itemsyndrome by Putnam --triggers scripts when a unit attacks another with a weapon type, a weapon of a particular material, or a weapon contaminated with a particular material, or when a unit equips/unequips a particular item type, an item of a particular material, or an item contaminated with a particular material +--[[=begin +modtools/item-trigger +===================== +This powerful tool triggers DFHack commands when a unit equips, unequips, or +attacks another unit with specified item types, specified item materials, or +specified item contaminants. + +=end]] local eventful = require 'plugins.eventful' local utils = require 'utils' diff --git a/scripts/modtools/moddable-gods.lua b/scripts/modtools/moddable-gods.lua index acdbd4a24f..c044d6c0af 100644 --- a/scripts/modtools/moddable-gods.lua +++ b/scripts/modtools/moddable-gods.lua @@ -1,7 +1,14 @@ --scripts/modtools/moddable-gods.lua --based on moddableGods by Putnam --edited by expwnent +--[[=begin +modtools/moddable-gods +====================== +This is a standardized version of Putnam's moddableGods script. It allows you +to create gods on the command-line. + +=end]] local utils = require 'utils' validArgs = validArgs or utils.invert({ diff --git a/scripts/modtools/outside-only.lua b/scripts/modtools/outside-only.lua index 5d2279f60e..9572f8932f 100644 --- a/scripts/modtools/outside-only.lua +++ b/scripts/modtools/outside-only.lua @@ -1,7 +1,15 @@ --scripts/modtools/outsideOnly.lua --author expwnent --enables outside only and inside only buildings +--[[=begin +modtools/outside-only +===================== +This allows you to specify certain custom buildings as outside only, or inside +only. If the player attempts to build a building in an inappropriate location, +the building will be destroyed. + +=end]] local eventful = require 'plugins.eventful' local utils = require 'utils' diff --git a/scripts/modtools/projectile-trigger.lua b/scripts/modtools/projectile-trigger.lua index 02dfb769a1..c20e8231fb 100644 --- a/scripts/modtools/projectile-trigger.lua +++ b/scripts/modtools/projectile-trigger.lua @@ -2,7 +2,13 @@ --author expwnent --based on Putnam's projectileExpansion --TODO: trigger based on contaminants +--[[=begin +modtools/projectile-trigger +=========================== +This triggers dfhack commands when projectiles hit their targets. + +=end]] local eventful = require 'plugins.eventful' local utils = require 'utils' diff --git a/scripts/modtools/random-trigger.lua b/scripts/modtools/random-trigger.lua index 4ad6813c19..a762d2dc49 100644 --- a/scripts/modtools/random-trigger.lua +++ b/scripts/modtools/random-trigger.lua @@ -1,7 +1,16 @@ --scripts/modtools/random-trigger.lua --triggers random scripts ---register a few scripts, then tell it to "go" and it will pick a random one based on the probability weights you specified. outcomes are mutually exclusive. To make independent random events, call the script multiple times. +--[[=begin +modtools/random-trigger +======================= +This triggers random dfhack commands with specified probabilities. +Register a few scripts, then tell it to "go" and it will pick one +based on the probability weights you specified. Outcomes are mutually +exclusive. To make independent random events, call the script multiple +times. + +=end]] local utils = require 'utils' local eventful = require 'plugins.eventful' diff --git a/scripts/modtools/reaction-product-trigger.lua b/scripts/modtools/reaction-product-trigger.lua index bc1cc5a482..fb6ba3029c 100644 --- a/scripts/modtools/reaction-product-trigger.lua +++ b/scripts/modtools/reaction-product-trigger.lua @@ -2,7 +2,14 @@ -- author expwnent -- trigger commands just before and after custom reactions produce items --@ module = true +--[[=begin +modtools/reaction-product-trigger +================================= +This triggers dfhack commands when reaction products are produced, once per +product. + +=end]] local eventful = require 'plugins.eventful' local utils = require 'utils' diff --git a/scripts/modtools/reaction-trigger-transition.lua b/scripts/modtools/reaction-trigger-transition.lua index 9e26758c2d..42f75f461f 100644 --- a/scripts/modtools/reaction-trigger-transition.lua +++ b/scripts/modtools/reaction-trigger-transition.lua @@ -1,8 +1,18 @@ -- scripts/modtools/reaction-trigger-transition.lua -- author expwnent --- prints useful things to the console and a file to help modders transition from autoSyndrome to reaction-trigger --- this script is basically an apology for breaking backward compatibiility +--[[=begin +modtools/reaction-trigger-transition +==================================== +Scans raw files and creates a file to help modders transition from +autoSyndrome to reaction-trigger. + +Prints useful things to the console and a file to help modders +transition from autoSyndrome to reaction-trigger. This script +is basically an apology for breaking backward compatibiility, +and will be removed eventually. + +=end]] local function maybeQuote(str) if str == '' or string.find(str,' ') then return ('"' .. str .. '"') diff --git a/scripts/modtools/reaction-trigger.lua b/scripts/modtools/reaction-trigger.lua index 93b5b0d2a2..ef20fa2e02 100644 --- a/scripts/modtools/reaction-trigger.lua +++ b/scripts/modtools/reaction-trigger.lua @@ -2,7 +2,15 @@ -- author expwnent -- replaces autoSyndrome: trigger commands when custom reactions are completed --@ module = true +--[[=begin +modtools/reaction-trigger +========================= +Triggers dfhack commands when custom reactions complete, regardless of whether +it produced anything, once per completion. Use the ``-help`` command +for more information. + +=end]] local eventful = require 'plugins.eventful' local syndromeUtil = require 'syndrome-util' local utils = require 'utils' diff --git a/scripts/modtools/skill-change.lua b/scripts/modtools/skill-change.lua index 7cdd4de677..55670fc902 100644 --- a/scripts/modtools/skill-change.lua +++ b/scripts/modtools/skill-change.lua @@ -3,7 +3,21 @@ --based on skillChange.lua by Putnam --TODO: update skill level once experience increases/decreases --TODO: skill rust? +--[[=begin +modtools/skill-change +===================== +Sets or modifies a skill of a unit. Args: + +:-help: print the help message +:-skill skillName: set the skill that we're talking about +:-mode (add/set): are we adding experience/levels or setting them? +:-granularity (experience/level): + direct experience, or experience levels? +:-unit id: id of the target unit +:-value amount: how much to set/add + +=end]] local utils = require 'utils' validArgs = validArgs or utils.invert({ diff --git a/scripts/modtools/spawn-flow.lua b/scripts/modtools/spawn-flow.lua index 3e6445120b..594c3d9179 100644 --- a/scripts/modtools/spawn-flow.lua +++ b/scripts/modtools/spawn-flow.lua @@ -1,7 +1,13 @@ --scripts/modtools/spawn-flow.lua --author expwnent --spawns flows at locations +--[[=begin +modtools/spawn-flow +=================== +Creates flows at the specified location. + +=end]] local utils = require 'utils' validArgs = validArgs or utils.invert({ diff --git a/scripts/modtools/syndrome-trigger.lua b/scripts/modtools/syndrome-trigger.lua index 9afff2641e..b03ad57839 100644 --- a/scripts/modtools/syndrome-trigger.lua +++ b/scripts/modtools/syndrome-trigger.lua @@ -1,7 +1,13 @@ --scripts/modtools/syndrome-trigger.lua --author expwnent --triggers scripts when units are infected with syndromes +--[[=begin +modtools/syndrome-trigger +========================= +Triggers dfhack commands when syndromes are applied to units. + +=end]] local eventful = require 'plugins.eventful' local utils = require 'utils' diff --git a/scripts/modtools/transform-unit.lua b/scripts/modtools/transform-unit.lua index 9a8a797721..c1cda390be 100644 --- a/scripts/modtools/transform-unit.lua +++ b/scripts/modtools/transform-unit.lua @@ -1,9 +1,15 @@ --scripts/modtools/transform-unit.lua --author expwnent --based on shapechange by Putnam ---warning: will crash arena mode if you view the unit on the same tick that it transforms ---if you wait until later, it will be fine +--[[=begin +modtools/transform-unit +======================= +Transforms a unit into another unit type, possibly permanently. +Warning: this will crash arena mode if you view the unit on the +same tick that it transforms. If you wait until later, it will be fine. + +=end]] local utils = require 'utils' normalRace = normalRace or {} From ddae19ad8b2ff8a7562ff1a4e4651c6e5aed6dda Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Sat, 24 Oct 2015 15:10:15 +1100 Subject: [PATCH 15/91] Move base scripts --- docs/Core.rst | 12 +- docs/Scripts.rst | 611 --------------------------------- scripts/ban-cooking.rb | 9 + scripts/binpatch.lua | 7 + scripts/brainwash.lua | 9 + scripts/burial.lua | 8 + scripts/create-items.rb | 30 ++ scripts/deathcause.rb | 8 + scripts/dfusion.lua | 8 + scripts/digfort.rb | 29 ++ scripts/drain-aquifer.lua | 7 + scripts/elevate-mental.lua | 11 +- scripts/elevate-physical.lua | 10 +- scripts/exportlegends.lua | 20 +- scripts/exterminate.rb | 45 ++- scripts/fix-ster.lua | 25 +- scripts/fixnaked.lua | 7 + scripts/forum-dwarves.lua | 8 + scripts/full-heal.lua | 8 +- scripts/gaydar.lua | 9 + scripts/growcrops.rb | 15 + scripts/hfs-pit.lua | 17 + scripts/hotkey-notes.lua | 7 + scripts/item-descriptions.lua | 9 + scripts/lever.rb | 18 + scripts/locate-ore.rb | 18 + scripts/log-region.lua | 9 + scripts/lua.lua | 24 ++ scripts/make-legendary.lua | 12 +- scripts/make-monarch.lua | 8 + scripts/markdown.lua | 8 + scripts/masspit.rb | 11 + scripts/multicmd.rb | 14 +- scripts/points.lua | 10 + scripts/position.lua | 8 + scripts/pref-adjust.lua | 17 +- scripts/putontable.lua | 11 +- scripts/quicksave.lua | 8 + scripts/region-pops.lua | 24 ++ scripts/rejuvenate.lua | 12 +- scripts/remove-stress.lua | 11 +- scripts/remove-wear.lua | 7 + scripts/repeat.lua | 24 ++ scripts/setfps.lua | 8 + scripts/show-unit-syndromes.rb | 26 +- scripts/siren.lua | 11 + scripts/soundsense-season.lua | 13 + scripts/source.rb | 30 ++ scripts/startdwarf.rb | 10 + scripts/stripcaged.rb | 23 ++ scripts/superdwarf.rb | 15 + scripts/teleport.lua | 12 + scripts/undump-buildings.lua | 8 + scripts/unsuspend.rb | 8 + scripts/view-item-info.lua | 17 +- scripts/warn-starving.lua | 11 + 56 files changed, 725 insertions(+), 650 deletions(-) diff --git a/docs/Core.rst b/docs/Core.rst index 6b9610afcd..2ad51db702 100644 --- a/docs/Core.rst +++ b/docs/Core.rst @@ -254,11 +254,19 @@ Opens an in-game screen showing DFHack keybindings that are active in the curren Type ``hotkeys`` into the DFHack console to open the screen, or bind the command to a globally active hotkey. The default keybinding is ``Ctrl-F1``. -In-game Console -=============== +.. _command-prompt: + +In-game command prompt +====================== The ``command-prompt`` plugin adds an in-game DFHack terminal, where you can enter other commands. It's default keybinding is Ctrl-Shift-P. +A one line command prompt in df. Same as entering command into dfhack console. Best +used as a keybinding. Can be called with optional "entry" that will start prompt with +that pre-filled. + +.. image:: images/command-prompt.png + Enabling plugins ================ Many plugins can be in a distinct enabled or disabled state. Some of diff --git a/docs/Scripts.rst b/docs/Scripts.rst index 3d12cc5d3b..4d730d1423 100644 --- a/docs/Scripts.rst +++ b/docs/Scripts.rst @@ -68,614 +68,3 @@ The following pages document all the standard DFHack scripts. /scripts/3rdparty/*/* - -ban-cooking -=========== -A more convenient way to ban cooking various categories of foods than the -kitchen interface. Usage: ``ban-cooking ``. Valid types are ``booze``, -``honey``, ``tallow``, ``oil``, and ``seeds`` (non-tree plants with seeds). - -.. _binpatch: - -binpatch -======== -Implements functions for in-memory binpatches. See `binpatches`. - -.. _brainwash: - -brainwash -========= -Modify the personality traits of the selected dwarf to match an 'ideal' -personality - as stable and reliable as possible. This makes dwarves very -stable, preventing tantrums even after months of misery. - -burial -====== -Sets all unowned coffins to allow burial. ``burial -pets`` also allows burial -of pets. - -.. _command-prompt: - -command-prompt -============== -A one line command prompt in df. Same as entering command into dfhack console. Best -used as a keybinding. Can be called with optional "entry" that will start prompt with -that pre-filled. - -.. image:: images/command-prompt.png - -create-items -============ -Spawn arbitrary items under the cursor. - -The first argument gives the item category, the second gives the material, -and the optionnal third gives the number of items to create (defaults to 20). - -Currently supported item categories: ``boulder``, ``bar``, ``plant``, ``log``, -``web``. - -Instead of material, using ``list`` makes the script list eligible materials. - -The ``web`` item category will create an uncollected cobweb on the floor. - -Note that the script does not enforce anything, and will let you create -boulders of toad blood and stuff like that. -However the ``list`` mode will only show 'normal' materials. - -Examples:: - - create-items boulders COAL_BITUMINOUS 12 - create-items plant tail_pig - create-items log list - create-items web CREATURE:SPIDER_CAVE_GIANT:SILK - create-items bar CREATURE:CAT:SOAP - create-items bar adamantine - -.. _deathcause: - -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``) unitlist viewscreen. - -dfusion -======= -Interface to a lecacy script system. - -.. _digfort: - -digfort -======= -A script to designate an area for digging according to a plan in csv format. - -This script, inspired from quickfort, can designate an area for digging. -Your plan should be stored in a .csv file like this:: - - # this is a comment - d;d;u;d;d;skip this tile;d - d;d;d;i - -Available tile shapes are named after the 'dig' menu shortcuts: -``d`` for dig, ``u`` for upstairs, ``d`` downstairs, ``i`` updown, -``h`` channel, ``r`` upward ramp, ``x`` remove designation. -Unrecognized characters are ignored (eg the 'skip this tile' in the sample). - -Empty lines and data after a ``#`` are ignored as comments. -To skip a row in your design, use a single ``;``. - -One comment in the file may contain the phrase ``start(3,5)``. It is interpreted -as an offset for the pattern: instead of starting at the cursor, it will start -3 tiles left and 5 tiles up from the cursor. - -The script takes the plan filename, starting from the root df folder (where -``Dwarf Fortress.exe`` is found). - -.. _drain-aquifer: - -drain-aquifer -============= -Remove all 'aquifer' tag from the map blocks. Irreversible. - -.. _elevate-mental: - -elevate-mental -============== -Set all mental attributes of a dwarf to 2600, which is very high. -Other numbers can be passed as an argument: ``elevate-mental 100`` -for example would make the dwarf very stupid indeed. - -.. _elevate-physical: - -elevate-physical -================ -As for elevate-mental, but for physical traits. High is good for soldiers, -while having an ineffective hammerer can be useful too... - -.. _exportlegends: - -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 -Viewer utility and potentially compatible with others. - -Options: - -:info: Exports the world/gen info, the legends XML, and a custom XML with more information -:sites: Exports all available site maps -:maps: Exports all seventeen detailed maps -:all: Equivalent to calling all of the above, in that order - -exterminate -=========== -Kills any unit of a given race. - -With no argument, lists the available races and count eligible targets. - -With the special argument ``him``, targets only the selected creature. - -With the special argument ``undead``, targets all undeads on the map, -regardless of their race. - -When specifying a race, a caste can be specified to further restrict the -targeting. To do that, append and colon and the caste name after the race. - -Any non-dead non-caged unit of the specified race gets its ``blood_count`` -set to 0, which means immediate death at the next game tick. For creatures -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 recommended.) - -Will target any unit on a revealed tile of the map, including ambushers, -but ignore caged/chained creatures. - -Ex:: - - exterminate gob - exterminate gob:male - -To kill a single creature, select the unit with the 'v' cursor and:: - - exterminate him - -To purify all elves on the map with fire (may have side-effects):: - - exterminate elve magma - -fixnaked -======== -Removes all unhappy thoughts due to lack of clothing. - -.. _fix-ster: - -fix-ster -======== -Utilizes the orientation tag to either fix infertile creatures or inflict -infertility on creatures that you do not want to breed. Usage:: - - fix-ster [fert|ster] [all|animals|only:] - -``fert`` or ``ster`` is a required argument; whether to make the target fertile -or sterile. Optional arguments specify the target: no argument for the -selected unit, ``all`` for all units on the map, ``animals`` for all non-dwarf -creatures, or ``only:`` to only process matching creatures. - -.. _forum-dwarves: - -forum-dwarves -============= -Saves a copy of a text screen, formatted in bbcode for posting to the Bay12 Forums. -Use ``forum-dwarves help`` for more information. - -.. _full-heal: - -full-heal -========= -Attempts to fully heal the selected unit. ``full-heal -r`` attempts to resurrect the unit. - -.. _gaydar: - -gaydar -====== -Shows the sexual orientation of units, useful for social engineering or checking -the viability of livestock breeding programs. Use ``gaydar -help`` for information -on available filters for orientation, citizenship, species, etc. - -growcrops -========= -Instantly grow seeds inside farming plots. - -With no argument, this command list the various seed types currently in -use in your farming plots. -With a seed type, the script will grow 100 of these seeds, ready to be -harvested. You can change the number with a 2nd argument. - -For example, to grow 40 plump helmet spawn:: - - growcrops plump 40 - -.. _hfs-pit: - -hfs-pit -======= -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.:: - - hfs-pit 4 0 1 - hfs-pit 2 1 0 - -First example is a four-across pit with stairs but no walls; second is a -two-across pit with stairs but no walls. - -.. _hotkey-notes: - -hotkey-notes -============ -Lists the key, name, and jump position of your hotkeys in the DFHack console. - -item-descriptions -================= -Exports a table with custom description text for every item in the game. -Used by `view-item-info`. - -lever -===== -Allow manipulation of in-game levers from the dfhack console. - -Can list levers, including state and links, with:: - - lever list - -To queue a job so that a dwarf will pull the lever 42, use ``lever pull 42``. -This is the same as 'q'uerying the building and queue a 'P'ull request. - -To magically toggle the lever immediately, use:: - - lever pull 42 --now - -locate-ore -========== -Scan the map for metal ores. - -Finds and designate for digging one tile of a specific metal ore. -Only works for native metal ores, does not handle reaction stuff (eg STEEL). - -When invoked with the ``list`` argument, lists metal ores available on the map. - -Examples:: - - locate-ore list - locate-ore hematite - locate-ore iron - -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. - -lua -=== -There are the following ways to invoke this command: - -1. ``lua`` (without any parameters) - - This starts an interactive lua interpreter. - -2. ``lua -f "filename"`` or ``lua --file "filename"`` - - This loads and runs the file indicated by filename. - -3. ``lua -s ["filename"]`` or ``lua --save ["filename"]`` - - This loads and runs the file indicated by filename from the save - directory. If the filename is not supplied, it loads "dfhack.lua". - -4. ``:lua`` *lua statement...* - - Parses and executes the lua statement like the interactive interpreter would. - -make-legendary -============== -Makes the selected dwarf legendary in one skill, a group of skills, or all -skills. View groups with ``make-legendary classes``, or all skills with -``make-legendary list``. Use ``make-legendary MINING`` when you need something -dug up, or ``make-legendary all`` when only perfection will do. - -make-monarch -============ -Make the selected unit King or Queen of your civilisation. - -.. _markdown: - -markdown -======== -Save a copy of a text screen in markdown (for reddit among others). -Use ``markdown help`` for more details. - -masspit -======= -Designate all creatures in cages on top of a pit/pond activity zone for pitting. -Works best with an animal stockpile on top of the zone. - -Works with a zone number as argument (eg ``Activity Zone #6`` -> ``masspit 6``) -or with the game cursor on top of the area. - -multicmd -======== -Run multiple dfhack commands. The argument is split around the -character ; and all parts are run sequentially as independent -dfhack commands. Useful for hotkeys. - -Example:: - - multicmd locate-ore iron ; digv - -points -====== -Sets available points at the embark screen to the specified number. Eg. -``points 1000000`` would allow you to buy everything, or ``points 0`` would -make life quite difficult. - -.. _position: - -position -======== -Reports the current time: date, clock time, month, and season. Also reports -location: z-level, cursor position, window size, and mouse location. - -pref-adjust -=========== -A two-stage script: ``pref-adjust clear`` removes preferences from all dwarves, -and ``pref-adjust`` inserts an 'ideal' set which is easy to satisfy:: - - Feb Idashzefon likes wild strawberries for their vivid red color, fisher berries - for their round shape, prickle berries for their precise thorns, plump helmets - for their rounded tops, prepared meals, plants, drinks, doors, thrones, tables and - beds. When possible, she prefers to consume wild strawberries, fisher berries, - prickle berries, plump helmets, strawberry wine, fisher berry wine, prickle berry - wine, and dwarven wine. - -.. _putontable: - -putontable -========== -Makes item appear on the table, like in adventure mode shops. Arguments: '-a' -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. - -region-pops -=========== -Show or modify the populations of animals in the region. - -Usage: - -:region-pops list [pattern]: - Lists encountered populations of the region, possibly restricted by pattern. -:region-pops list-all [pattern]: - Lists all populations of the region. -:region-pops boost : - Multiply all populations of TOKEN by factor. - If the factor is greater than one, increases the - population, otherwise decreases it. -:region-pops boost-all : - Same as above, but match using a pattern acceptable to list. -:region-pops incr : - Augment (or diminish) all populations of TOKEN by factor (additive). -:region-pops incr-all : - Same as above, but match using a pattern acceptable to list. - -.. _rejuvenate: - -rejuvenate -========== -Set the age of the selected dwarf to 20 years. Useful if valuable citizens are -getting old, or there are too many babies around... - -.. _remove-stress: - -remove-stress -============= -Sets stress to -1,000,000; the normal range is 0 to 500,000 with very stable or -very stressed dwarves taking on negative or greater values respectively. -Applies to the selected unit, or use "remove-stress -all" to apply to all units. - -remove-wear -=========== -Sets the wear on all items in your fort to zero. - -.. _repeat: - -repeat -====== -Repeatedly calls a lua script at the specified interval. - -This allows neat background changes to the function of the game, especially when -invoked from an init file. For detailed usage instructions, use ``repeat -help``. - -Usage examples:: - - repeat -name jim -time delay -timeUnits units -printResult true -command [ printArgs 3 1 2 ] - repeat -time 1 -timeUnits months -command [ multicmd cleanowned scattered x; clean all ] -name clean - -The first example is abstract; the second will regularly remove all contaminants -and worn items from the game. - -``-name`` sets the name for the purposes of cancelling and making sure you don't schedule the -same repeating event twice. If not specified, it's set to the first argument after ``-command``. -``-time delay -timeUnits units``; delay is some positive integer, and units is some valid time -unit for ``dfhack.timeout(delay,timeUnits,function)``. ``-command [ ... ]`` specifies the -command to be run. - -setfps -====== -Run ``setfps `` to set the FPS cap at runtime, in case you want to watch -combat in slow motion or something :) - -.. _show-unit-syndromes: - -show-unit-syndromes -=================== -Show syndromes affecting units and the remaining and maximum duration, along -with (optionally) substantial detail on the effects. - -Use one or more of the following options: - -:showall: Show units even if not affected by any syndrome -:showeffects: Show detailed effects of each syndrome -:showdisplayeffects: Show effects that only change the look of the unit -:ignorehiddencurse: Hide syndromes the user should not be able to know about (TODO) -:selected: Show selected unit -:dwarves: Show dwarves -:livestock: Show livestock -:wildanimals: Show wild animals -:hostile: Show hostiles (e.g. invaders, thieves, forgotten beasts etc) -:world: Show all defined syndromes in the world -:export: ``export:`` sends output to the given file, showing all - syndromes affecting each unit with the maximum and present duration. - -.. _siren: - -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 -breaks will go on break again a lot sooner. The script is intended for -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. - -This script registers a hook that prints the appropriate string -to gamelog.txt on every map load to fix this. For best results -call the script from ``dfhack.init``. - -source -====== -Create an infinite magma or water source or drain on a tile. - -This script registers a map tile as a liquid source, and every 12 game ticks -that tile receives or remove 1 new unit of flow based on the configuration. - -Place the game cursor where you want to create the source (must be a -flow-passable tile, and not too high in the sky) and call:: - - source add [magma|water] [0-7] - -The number argument is the target liquid level (0 = drain, 7 = source). - -To add more than 1 unit everytime, call the command again on the same spot. - -To delete one source, place the cursor over its tile and use ``source delete``. -To remove all existing sources, call ``source clear``. - -The ``list`` argument shows all existing sources. - -Examples:: - - source add water - water source - source add magma 7 - magma source - source add water 0 - water drain - -startdwarf -========== -Use at the embark screen to embark with the specified number of dwarves. Eg. -``startdwarf 500`` would lead to a severe food shortage and FPS issues, while -``startdwarf 10`` would just allow a few more warm bodies to dig in. -The number must be 7 or greater. - -stripcaged -========== -For dumping items inside cages. Will mark selected items for dumping, then -a dwarf may come and actually dump it. See also `autodump`. - -With the ``items`` argument, only dumps items laying in the cage, excluding -stuff worn by caged creatures. ``weapons`` will dump worn weapons, ``armor`` -will dump everything worn by caged creatures (including armor and clothing), -and ``all`` will dump everything, on a creature or not. - -``stripcaged list`` will display on the dfhack console the list of all cages -and their item content. - -Without further arguments, all commands work on all cages and animal traps on -the map. With the ``here`` argument, considers only the in-game selected cage -(or the cage under the game cursor). To target only specific cages, you can -alternatively pass cage IDs as arguments:: - - stripcaged weapons 25321 34228 - -.. _superdwarf: - -superdwarf -========== -Similar to `fastdwarf`, per-creature. - -To make any creature superfast, target it ingame using 'v' and:: - - superdwarf add - -Other options available: ``del``, ``clear``, ``list``. - -This script also shortens the 'sleeping' and 'on break' periods of targets. - -.. _teleport: - -teleport -======== -Teleports a unit to given coordinates. - -Examples:: - - teleport -showunitid - prints unitid beneath cursor - teleport -showpos - prints coordinates beneath cursor - teleport -unit 1234 -x 56 -y 115 -z 26 - teleports unit 1234 to 56,115,26 - -undump-buildings -================ -Undesignates building base materials for dumping. - -.. _unsuspend: - -unsuspend -========= -Unsuspend jobs in workshops, on a one-off basis. See `autounsuspend` -for regular use. - -.. _view-item-info: - -view-item-info -============== -A script to extend the item or unit viewscreen with additional information -including a custom description of each item (when available), and properties -such as material statistics, weapon attacks, armor effectiveness, and more. - -The associated script ``item-descriptions.lua`` supplies custom descriptions -of items. Individual descriptions can be added or overridden by a similar -script ``raw/scripts/more-item-descriptions.lua``. Both work as sparse lists, -so missing items simply go undescribed if not defined in the fallback. - -warn-starving -============= -If any (live) units are starving, very thirsty, or very drowsy, the game will -be paused and a warning shown and logged to the console. Use with the -`repeat` command for regular checks. - -Use ``warn-starving all`` to display a list of all problematic units. diff --git a/scripts/ban-cooking.rb b/scripts/ban-cooking.rb index 544447277e..906469ea5d 100644 --- a/scripts/ban-cooking.rb +++ b/scripts/ban-cooking.rb @@ -1,4 +1,13 @@ # convenient way to ban cooking categories of food +=begin + +ban-cooking +=========== +A more convenient way to ban cooking various categories of foods than the +kitchen interface. Usage: ``ban-cooking ``. Valid types are ``booze``, +``honey``, ``tallow``, ``oil``, and ``seeds`` (non-tree plants with seeds). + +=end already_banned = {} kitchen = df.ui.kitchen diff --git a/scripts/binpatch.lua b/scripts/binpatch.lua index b9a4cf0b17..ac77052508 100644 --- a/scripts/binpatch.lua +++ b/scripts/binpatch.lua @@ -1,4 +1,11 @@ -- Apply or remove binary patches at runtime. +--[[=begin + +binpatch +======== +Implements functions for in-memory binpatches. See `binpatches`. + +=end]] local bp = require('binpatch') diff --git a/scripts/brainwash.lua b/scripts/brainwash.lua index 717b0f221f..1950323a8c 100644 --- a/scripts/brainwash.lua +++ b/scripts/brainwash.lua @@ -1,6 +1,15 @@ -- This script will brainwash a dwarf, modifying their personality -- usage is: target a unit in DF, and execute this script in dfhack -- by vjek +--[[=begin + +brainwash +========= +Modify the personality traits of the selected dwarf to match an 'ideal' +personality - as stable and reliable as possible. This makes dwarves very +stable, preventing tantrums even after months of misery. + +=end]] function brainwash_unit(profile) local i,unit_name diff --git a/scripts/burial.lua b/scripts/burial.lua index b73ac93271..3023f91285 100644 --- a/scripts/burial.lua +++ b/scripts/burial.lua @@ -1,5 +1,13 @@ -- allows burial in unowned coffins -- by Putnam https://gist.github.com/Putnam3145/e7031588f4d9b24b9dda +--[[=begin + +burial +====== +Sets all unowned coffins to allow burial. ``burial -pets`` also allows burial +of pets. + +=end]] local utils=require('utils') diff --git a/scripts/create-items.rb b/scripts/create-items.rb index ea739f4e0a..544bd8ce0f 100644 --- a/scripts/create-items.rb +++ b/scripts/create-items.rb @@ -1,4 +1,34 @@ # create first necessity items under cursor +=begin + +create-items +============ +Spawn items under the cursor, to get your fortress started. + +The first argument gives the item category, the second gives the material, +and the optionnal third gives the number of items to create (defaults to 20). + +Currently supported item categories: ``boulder``, ``bar``, ``plant``, ``log``, +``web``. + +Instead of material, using ``list`` makes the script list eligible materials. + +The ``web`` item category will create an uncollected cobweb on the floor. + +Note that the script does not enforce anything, and will let you create +boulders of toad blood and stuff like that. +However the ``list`` mode will only show 'normal' materials. + +Examples:: + + create-items boulders COAL_BITUMINOUS 12 + create-items plant tail_pig + create-items log list + create-items web CREATURE:SPIDER_CAVE_GIANT:SILK + create-items bar CREATURE:CAT:SOAP + create-items bar adamantine + +=end category = $script_args[0] || 'help' mat_raw = $script_args[1] || 'list' diff --git a/scripts/deathcause.rb b/scripts/deathcause.rb index 4ba3d2388d..6b2f252c0e 100644 --- a/scripts/deathcause.rb +++ b/scripts/deathcause.rb @@ -1,4 +1,12 @@ # show death cause of a creature +=begin + +deathcause +========== +Select a body part ingame, or a unit from the :kbd:`u` unit list, and this +script will display the cause of death of the creature. + +=end def display_death_event(e) str = "The #{e.victim_hf_tg.race_tg.name[0]} #{e.victim_hf_tg.name} died in year #{e.year}" diff --git a/scripts/dfusion.lua b/scripts/dfusion.lua index 79f9fd9531..4bb93c212a 100644 --- a/scripts/dfusion.lua +++ b/scripts/dfusion.lua @@ -1,4 +1,12 @@ -- a collection of misc lua scripts +--[[=begin + +dfusion +======= +Interface to a lecacy script system. + +=end]] + local dfu=require("plugins.dfusion") local myos=dfhack.getOSType() args={...} diff --git a/scripts/digfort.rb b/scripts/digfort.rb index c129575009..0a0853cfde 100644 --- a/scripts/digfort.rb +++ b/scripts/digfort.rb @@ -1,4 +1,33 @@ # designate an area for digging according to a plan in csv format +=begin + +digfort +======= +A script to designate an area for digging according to a plan in csv format. + +This script, inspired from quickfort, can designate an area for digging. +Your plan should be stored in a .csv file like this:: + + # this is a comment + d;d;u;d;d;skip this tile;d + d;d;d;i + +Available tile shapes are named after the 'dig' menu shortcuts: +``d`` for dig, ``u`` for upstairs, ``d`` downstairs, ``i`` updown, +``h`` channel, ``r`` upward ramp, ``x`` remove designation. +Unrecognized characters are ignored (eg the 'skip this tile' in the sample). + +Empty lines and data after a ``#`` are ignored as comments. +To skip a row in your design, use a single ``;``. + +One comment in the file may contain the phrase ``start(3,5)``. It is interpreted +as an offset for the pattern: instead of starting at the cursor, it will start +3 tiles left and 5 tiles up from the cursor. + +The script takes the plan filename, starting from the root df folder (where +``Dwarf Fortress.exe`` is found). + +=end fname = $script_args[0].to_s diff --git a/scripts/drain-aquifer.lua b/scripts/drain-aquifer.lua index 4f7fd1616d..6a79017bf1 100644 --- a/scripts/drain-aquifer.lua +++ b/scripts/drain-aquifer.lua @@ -1,4 +1,11 @@ -- Remove all aquifers from the map +--[[=begin + +drain-aquifer +============= +Remove all 'aquifer' tag from the map blocks. Irreversible. + +=end]] local function drain() local layers = {} diff --git a/scripts/elevate-mental.lua b/scripts/elevate-mental.lua index b39303d4ce..ed4b6b026c 100644 --- a/scripts/elevate-mental.lua +++ b/scripts/elevate-mental.lua @@ -1,7 +1,14 @@ -- This script will elevate all the mental attributes of a unit --- usage is: target a unit in DF, and execute this script in dfhack --- all physical attributes will be set to whatever the max value is -- by vjek +--[[=begin + +elevate-mental +============== +Set all mental attributes of the selected dwarf to 2600, which is very high. +Numbers between 0 and 5000 can be passed as an argument: ``elevate-mental 100`` +for example would make the dwarf very stupid indeed. + +=end]] function ElevateMentalAttributes(value) unit=dfhack.gui.getSelectedUnit() diff --git a/scripts/elevate-physical.lua b/scripts/elevate-physical.lua index 05f23c67f1..f425473d12 100644 --- a/scripts/elevate-physical.lua +++ b/scripts/elevate-physical.lua @@ -1,7 +1,13 @@ -- This script will elevate all the physical attributes of a unit --- usage is: target a unit in DF, and execute this script in dfhack --- all physical attributes will be set to whatever the max value is -- by vjek +--[[=begin + +elevate-physical +================ +As for elevate-mental, but for physical traits. High is good for soldiers, +while having an ineffective hammerer can be useful too... + +=end]] function ElevatePhysicalAttributes(value) unit=dfhack.gui.getSelectedUnit() diff --git a/scripts/exportlegends.lua b/scripts/exportlegends.lua index 7b1277b3bf..42e70037b5 100644 --- a/scripts/exportlegends.lua +++ b/scripts/exportlegends.lua @@ -1,5 +1,23 @@ -- Export everything from legends mode --- Valid args: "all", "info", "maps", "sites" +--[[=begin + +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 +:file:`region-date-legends_plus.xml` file developed to extend the World +Viewer utility and potentially compatible with others. + +Options: + +:info: Exports the world/gen info, the legends XML, and a custom XML with more information +:sites: Exports all available site maps +:maps: Exports all seventeen detailed maps +:all: Equivalent to calling all of the above, in that order + +=end]] gui = require 'gui' local args = {...} diff --git a/scripts/exterminate.rb b/scripts/exterminate.rb index b2625428f9..bc25a95b8b 100644 --- a/scripts/exterminate.rb +++ b/scripts/exterminate.rb @@ -1,7 +1,48 @@ # exterminate creatures +=begin + +exterminate +=========== +Kills any unit of a given race. + +With no argument, lists the available races and count eligible targets. + +With the special argument ``him``, targets only the selected creature. + +With the special argument ``undead``, targets all undeads on the map, +regardless of their race. + +When specifying a race, a caste can be specified to further restrict the +targeting. To do that, append and colon and the caste name after the race. + +Any non-dead non-caged unit of the specified race gets its ``blood_count`` +set to 0, which means immediate death at the next game tick. For creatures +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 recommended.) The final alternate mode +is ``butcher``, which marks them for butchering but does not kill. + +Will target any unit on a revealed tile of the map, including ambushers, +but ignore caged/chained creatures. + +Ex:: + + exterminate gob + exterminate gob:male + +To kill a single creature, select the unit with the 'v' cursor and:: + + exterminate him + +To purify all elves on the map with fire (may have side-effects):: + + exterminate elve magma + +=end -# race = name of the race to eradicate, use 'him' to target only the selected creature -# use 'undead' to target all undeads race = $script_args[0] # if the 2nd parameter is 'magma', magma rain for the targets instead of instant death diff --git a/scripts/fix-ster.lua b/scripts/fix-ster.lua index bc5df8e0af..66b4f67652 100644 --- a/scripts/fix-ster.lua +++ b/scripts/fix-ster.lua @@ -3,20 +3,21 @@ -- original author: Tacomagic -- minor fixes by PeridexisErrant, Lethosor --@ module = true +--[[=begin ---[[ -This script utilizes the orientation tag to either fix infertile creatures -or inflict infertility on creatures that you do not want to breed +fix-ster +======== +Utilizes the orientation tag to either fix infertile creatures or inflict +infertility on creatures that you do not want to breed. Usage:: -Required arg: - fert: sets the flag to assure creature(s) are fertile - ster: sets the flag to assure creature(s) are sterile -Optional args: - the script will only process the currently selected creature - all: process all creatures currently on the map - animals: processes everything but dwarves on the map - only:: processes all of the creatures matching the specified creature on the map -]]-- + fix-ster [fert|ster] [all|animals|only:] + +``fert`` or ``ster`` is a required argument; whether to make the target fertile +or sterile. Optional arguments specify the target: no argument for the +selected unit, ``all`` for all units on the map, ``animals`` for all non-dwarf +creatures, or ``only:`` to only process matching creatures. + +=end]] function changeorient(unit, ori) --Sets the fertility flag based on gender. diff --git a/scripts/fixnaked.lua b/scripts/fixnaked.lua index 6e154440f8..39cfd2b77a 100644 --- a/scripts/fixnaked.lua +++ b/scripts/fixnaked.lua @@ -1,4 +1,11 @@ --removes unhappy thoughts due to lack of clothing +--[[=begin + +fixnaked +======== +Removes all unhappy thoughts due to lack of clothing. + +=end]] function fixnaked() local total_fixed = 0 diff --git a/scripts/forum-dwarves.lua b/scripts/forum-dwarves.lua index eb12b3baed..23402dd6f6 100644 --- a/scripts/forum-dwarves.lua +++ b/scripts/forum-dwarves.lua @@ -2,6 +2,14 @@ -- Save a copy of a text screen for the DF forums. Use 'forumdwarves help' for more details. -- original author: Caldfir -- edited by expwnent, Mchl +--[[=begin + +forum-dwarves +============= +Saves a copy of a text screen, formatted in bbcode for posting to the Bay12 Forums. +Use ``forum-dwarves help`` for more information. + +=end]] local args = {...} diff --git a/scripts/full-heal.lua b/scripts/full-heal.lua index 13a65852d9..4759e3e9ce 100644 --- a/scripts/full-heal.lua +++ b/scripts/full-heal.lua @@ -2,7 +2,13 @@ --author Kurik Amudnil, Urist DaVinci --edited by expwnent --- attempt to fully heal a selected unit, option -r to attempt to resurrect the unit +--[[=begin + +full-heal +========= +Attempts to fully heal the selected unit. ``full-heal -r`` attempts to resurrect the unit. + +=end]] local utils=require('utils') diff --git a/scripts/gaydar.lua b/scripts/gaydar.lua index 1aca8cdbed..51784181e1 100644 --- a/scripts/gaydar.lua +++ b/scripts/gaydar.lua @@ -1,4 +1,13 @@ local utils = require('utils') +--[[=begin + +gaydar +====== +Shows the sexual orientation of units, useful for social engineering or checking +the viability of livestock breeding programs. Use ``gaydar -help`` for information +on available filters for orientation, citizenship, species, etc. + +=end]] validArgs = utils.invert({ 'all', diff --git a/scripts/growcrops.rb b/scripts/growcrops.rb index c5ad717cc1..95bd7a81ab 100644 --- a/scripts/growcrops.rb +++ b/scripts/growcrops.rb @@ -1,4 +1,19 @@ # grow crops in farm plots. ex: growcrops helmet_plump 20 +=begin + +growcrops +========= +Instantly grow seeds inside farming plots. + +With no argument, this command list the various seed types currently in +use in your farming plots. With a seed type, the script will grow 100 of +these seeds, ready to be harvested. Set the number with a 2nd argument. + +For example, to grow 40 plump helmet spawn:: + + growcrops plump 40 + +=end material = $script_args[0] count_max = $script_args[1].to_i diff --git a/scripts/hfs-pit.lua b/scripts/hfs-pit.lua index e2caf77797..c335ae2be8 100644 --- a/scripts/hfs-pit.lua +++ b/scripts/hfs-pit.lua @@ -1,5 +1,22 @@ -- Creates a pit under the target leading straight to the Underworld. Type '?' for help. -- Based on script by IndigoFenix, @ https://gist.github.com/IndigoFenix/8776696 +--[[=begin + +hfs-pit +======= +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.:: + + hfs-pit 4 0 1 + hfs-pit 2 1 0 + +First example is a four-across pit with stairs but no walls; second is a +two-across pit with stairs but no walls. + +=end]] args={...} diff --git a/scripts/hotkey-notes.lua b/scripts/hotkey-notes.lua index 2b713e6bb1..428a02d640 100644 --- a/scripts/hotkey-notes.lua +++ b/scripts/hotkey-notes.lua @@ -1,4 +1,11 @@ -- prints info on assigned hotkeys to the console +--[[=begin + +hotkey-notes +============ +Lists the key, name, and jump position of your hotkeys in the DFHack console. + +=end]] for i=1, #df.global.ui.main.hotkeys do local hk = df.global.ui.main.hotkeys[i-1] diff --git a/scripts/item-descriptions.lua b/scripts/item-descriptions.lua index 9ce970c95b..fe7e7ac00f 100644 --- a/scripts/item-descriptions.lua +++ b/scripts/item-descriptions.lua @@ -1,5 +1,14 @@ -- Holds custom descriptions for view-item-info -- By PeridexisErrant +--[[=begin + +item-descriptions +================= +Exports a table with custom description text for every item in the game. +Used by `view-item-info`; see instructions there for how to override +for mods. + +=end]] -- Each line near the bottom has 53 characters of room until -- it starts clipping over the UI in an ugly fashion. diff --git a/scripts/lever.rb b/scripts/lever.rb index 6cbf38e6f2..05a159861c 100644 --- a/scripts/lever.rb +++ b/scripts/lever.rb @@ -1,4 +1,22 @@ # control your levers from the dfhack console +=begin + +lever +===== +Allow manipulation of in-game levers from the dfhack console. + +Can list levers, including state and links, with:: + + lever list + +To queue a job so that a dwarf will pull the lever 42, use ``lever pull 42``. +This is the same as :kbd:`q` querying the building and queue a :kbd:`P` pull request. + +To magically toggle the lever immediately, use:: + + lever pull 42 --now + +=end def lever_pull_job(bld) ref = DFHack::GeneralRefBuildingHolderst.cpp_new diff --git a/scripts/locate-ore.rb b/scripts/locate-ore.rb index 00ca8b87a0..1d204579ad 100644 --- a/scripts/locate-ore.rb +++ b/scripts/locate-ore.rb @@ -1,4 +1,22 @@ # scan the map for ore veins +=begin + +locate-ore +========== +Scan the map for metal ores. + +Finds and designate for digging one tile of a specific metal ore. +Only works for native metal ores, does not handle reaction stuff (eg STEEL). + +When invoked with the ``list`` argument, lists metal ores available on the map. + +Examples:: + + locate-ore list + locate-ore hematite + locate-ore iron + +=end target_ore = $script_args[0] diff --git a/scripts/log-region.lua b/scripts/log-region.lua index 31cdaf7824..733b2aea6d 100644 --- a/scripts/log-region.lua +++ b/scripts/log-region.lua @@ -1,5 +1,14 @@ -- On map load writes information about the loaded region to gamelog.txt -- By Kurik Amudnil and Warmist (http://www.bay12forums.com/smf/index.php?topic=91166.msg4467072#msg4467072) +--[[=begin + +log-region +========== +When enabled in :file:`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. + +=end]] local function write_gamelog(msg) local log = io.open('gamelog.txt', 'a') diff --git a/scripts/lua.lua b/scripts/lua.lua index a4a5dd22f2..2183eaaddc 100644 --- a/scripts/lua.lua +++ b/scripts/lua.lua @@ -1,4 +1,28 @@ -- Execute lua commands interactively or from files. +--[[=begin + +lua +=== +There are the following ways to invoke this command: + +1. ``lua`` (without any parameters) + + This starts an interactive lua interpreter. + +2. ``lua -f "filename"`` or ``lua --file "filename"`` + + This loads and runs the file indicated by filename. + +3. ``lua -s ["filename"]`` or ``lua --save ["filename"]`` + + This loads and runs the file indicated by filename from the save + directory. If the filename is not supplied, it loads "dfhack.lua". + +4. ``:lua`` *lua statement...* + + Parses and executes the lua statement like the interactive interpreter would. + +=end]] local args={...} local cmd = args[1] diff --git a/scripts/make-legendary.lua b/scripts/make-legendary.lua index a3dc6a9575..6dfc782771 100644 --- a/scripts/make-legendary.lua +++ b/scripts/make-legendary.lua @@ -1,8 +1,16 @@ -- This script will modify a skill or the skills of a single unit --- usage is: target a unit in DF, and execute this script in dfhack -- the skill will be increased to 20 (Legendary +5) --- arguments 'list', 'classes' and 'all' added -- by vjek +--[[=begin + +make-legendary +============== +Makes the selected dwarf legendary in one skill, a group of skills, or all +skills. View groups with ``make-legendary classes``, or all skills with +``make-legendary list``. Use ``make-legendary MINING`` when you need something +dug up, or ``make-legendary all`` when only perfection will do. + +=end]] -- this function will return the number of elements, starting at zero. -- useful for counting things where #foo doesn't work diff --git a/scripts/make-monarch.lua b/scripts/make-monarch.lua index 967225589e..1c8764367b 100644 --- a/scripts/make-monarch.lua +++ b/scripts/make-monarch.lua @@ -1,4 +1,12 @@ --set target unit as king/queen +--[[=begin + +make-monarch +============ +Make the selected unit King or Queen of your civilisation. + +=end]] + local unit=dfhack.gui.getSelectedUnit() if not unit then qerror("No unit selected") end local newfig=dfhack.units.getNemesis(unit).figure diff --git a/scripts/markdown.lua b/scripts/markdown.lua index e47e598623..8cd2255733 100644 --- a/scripts/markdown.lua +++ b/scripts/markdown.lua @@ -1,6 +1,14 @@ -- Save a copy of a text screen in markdown (for reddit among others). Use 'markdown help' for more details. -- This is a derivatiwe work based upon scripts/forum-dwarves.lua by Caldfir and expwnent -- Adapted for markdown by Mchl https://github.com/Mchl +--[[=begin + +markdown +======== +Save a copy of a text screen in markdown (for reddit among others). +Use ``markdown help`` for more details. + +=end]] local args = {...} diff --git a/scripts/masspit.rb b/scripts/masspit.rb index e391509fb8..9c276faf52 100644 --- a/scripts/masspit.rb +++ b/scripts/masspit.rb @@ -1,4 +1,15 @@ # pit all caged creatures in a zone +=begin + +masspit +======= +Designate all creatures in cages on top of a pit/pond activity zone for pitting. +Works best with an animal stockpile on top of the zone. + +Works with a zone number as argument (eg ``Activity Zone #6`` -> ``masspit 6``) +or with the game cursor on top of the area. + +=end case $script_args[0] when '?', 'help' diff --git a/scripts/multicmd.rb b/scripts/multicmd.rb index 593b0fa727..1481cc52c8 100644 --- a/scripts/multicmd.rb +++ b/scripts/multicmd.rb @@ -1,4 +1,16 @@ # run many dfhack commands separated by ; -# ex: multicmd locate-ore IRON ; digv ; digcircle 16 +=begin + +multicmd +======== +Run multiple dfhack commands. The argument is split around the +character ; and all parts are run sequentially as independent +dfhack commands. Useful for hotkeys. + +Example:: + + multicmd locate-ore IRON ; digv ; digcircle 16 + +=end $script_args.join(' ').split(/\s*;\s*/).each { |cmd| df.dfhack_run cmd } diff --git a/scripts/points.lua b/scripts/points.lua index 0bedd20747..1c3c2a99d9 100644 --- a/scripts/points.lua +++ b/scripts/points.lua @@ -1,3 +1,13 @@ -- by Meph -- http://www.bay12forums.com/smf/index.php?topic=135506.msg4925005#msg4925005 +--[[=begin + +points +====== +Sets available points at the embark screen to the specified number. Eg. +``points 1000000`` would allow you to buy everything, or ``points 0`` would +make life quite difficult. + +=end]] + df.global.world.worldgen.worldgen_parms.embark_points=tonumber(...) diff --git a/scripts/position.lua b/scripts/position.lua index ea824e15f4..2ff44c14a5 100644 --- a/scripts/position.lua +++ b/scripts/position.lua @@ -1,4 +1,12 @@ --prints current time and position +--[[=begin + +position +======== +Reports the current time: date, clock time, month, and season. Also reports +location: z-level, cursor position, window size, and mouse location. + +=end]] local months = { 'Granite, in early Spring.', diff --git a/scripts/pref-adjust.lua b/scripts/pref-adjust.lua index b4a3659adb..4b4807e087 100644 --- a/scripts/pref-adjust.lua +++ b/scripts/pref-adjust.lua @@ -1,7 +1,20 @@ -- Adjust all preferences of all dwarves in play --- all preferences are cleared, then set --- WARNING: USING THIS SCRIPT WILL ADJUST ALL DWARVES IN PLAY! -- by vjek +--[[=begin + +pref-adjust +=========== +A two-stage script: ``pref-adjust clear`` removes preferences from all dwarves, +and ``pref-adjust`` inserts an 'ideal' set which is easy to satisfy:: + + Feb Idashzefon likes wild strawberries for their vivid red color, fisher berries + for their round shape, prickle berries for their precise thorns, plump helmets + for their rounded tops, prepared meals, plants, drinks, doors, thrones, tables and + beds. When possible, she prefers to consume wild strawberries, fisher berries, + prickle berries, plump helmets, strawberry wine, fisher berry wine, prickle berry + wine, and dwarven wine. + +=end]] -- --------------------------------------------------------------------------- function brainwash_unit(unit) diff --git a/scripts/putontable.lua b/scripts/putontable.lua index 5002c8e6bb..daba8a46fc 100644 --- a/scripts/putontable.lua +++ b/scripts/putontable.lua @@ -1,4 +1,13 @@ --- Makes item appear on the table (just like in shops). '-a' or '--all' for all items. +-- Makes item appear on the table (just like in shops) +--[[=begin + +putontable +========== +Makes item appear on the table, like in adventure mode shops. +Arguments: ``-a`` or ``--all`` for all items. + +=end]] + local pos=df.global.cursor local args={...} local doall diff --git a/scripts/quicksave.lua b/scripts/quicksave.lua index 8617c6f4d0..a5733c7c37 100644 --- a/scripts/quicksave.lua +++ b/scripts/quicksave.lua @@ -1,4 +1,12 @@ -- Makes the game immediately save the state. +--[[=begin + +quicksave +========= +If called in dwarf mode, makes DF immediately auto-save the game by setting a flag +normally used in seasonal auto-save. + +=end]] if not dfhack.isMapLoaded() then qerror("World and map aren't loaded.") diff --git a/scripts/region-pops.lua b/scripts/region-pops.lua index 9a2cfd1fc1..af4d36bdeb 100644 --- a/scripts/region-pops.lua +++ b/scripts/region-pops.lua @@ -1,4 +1,28 @@ -- Shows populations of animals in the region, and allows tweaking them. +--[[=begin + +region-pops +=========== +Show or modify the populations of animals in the region. + +Usage: + +:region-pops list [pattern]: + Lists encountered populations of the region, possibly restricted by pattern. +:region-pops list-all [pattern]: + Lists all populations of the region. +:region-pops boost : + Multiply all populations of TOKEN by factor. + If the factor is greater than one, increases the + population, otherwise decreases it. +:region-pops boost-all : + Same as above, but match using a pattern acceptable to list. +:region-pops incr : + Augment (or diminish) all populations of TOKEN by factor (additive). +:region-pops incr-all : + Same as above, but match using a pattern acceptable to list. + +=end]] local utils = require 'utils' diff --git a/scripts/rejuvenate.lua b/scripts/rejuvenate.lua index 597bfd5288..fe19ad5455 100644 --- a/scripts/rejuvenate.lua +++ b/scripts/rejuvenate.lua @@ -1,7 +1,13 @@ --- This script will make any "old" dwarf 20 years old --- usage is: target a unit in DF, and execute this script in dfhack --- the target will be changed to 20 years old +-- make the selected dwarf 20 years old -- by vjek +--[[=begin + +rejuvenate +========== +Set the age of the selected dwarf to 20 years. Useful if valuable citizens are +getting old, or there are too many babies around... + +=end]] function rejuvenate() local current_year,newbirthyear diff --git a/scripts/remove-stress.lua b/scripts/remove-stress.lua index ea1eb7a603..56c8b14383 100644 --- a/scripts/remove-stress.lua +++ b/scripts/remove-stress.lua @@ -1,7 +1,14 @@ -- Sets stress to negative one million --- With unit selected, affects that unit. Use "remove-stress all" to affect all units. - --By Putnam; http://www.bay12forums.com/smf/index.php?topic=139553.msg5820486#msg5820486 +--[[=begin + +remove-stress +============= +Sets stress to -1,000,000; the normal range is 0 to 500,000 with very stable or +very stressed dwarves taking on negative or greater values respectively. +Applies to the selected unit, or use "remove-stress -all" to apply to all units. + +=end]] local utils = require 'utils' diff --git a/scripts/remove-wear.lua b/scripts/remove-wear.lua index 56fe42edcc..5e905e39f2 100644 --- a/scripts/remove-wear.lua +++ b/scripts/remove-wear.lua @@ -2,6 +2,13 @@ -- Resets all items in your fort to 0 wear -- original author: Laggy -- edited by expwnent +--[[=begin + +remove-wear +=========== +Sets the wear on all items in your fort to zero. + +=end]] local args = {...} diff --git a/scripts/repeat.lua b/scripts/repeat.lua index 0c08d8fa89..2dd84c012c 100644 --- a/scripts/repeat.lua +++ b/scripts/repeat.lua @@ -3,6 +3,30 @@ -- repeat -help for details -- author expwnent -- vaguely based on a script by Putnam +--[[=begin + +repeat +====== +Repeatedly calls a lua script at the specified interval. + +This allows neat background changes to the function of the game, especially when +invoked from an init file. For detailed usage instructions, use ``repeat -help``. + +Usage examples:: + + repeat -name jim -time delay -timeUnits units -printResult true -command [ printArgs 3 1 2 ] + repeat -time 1 -timeUnits months -command [ multicmd cleanowned scattered x; clean all ] -name clean + +The first example is abstract; the second will regularly remove all contaminants +and worn items from the game. + +``-name`` sets the name for the purposes of cancelling and making sure you don't schedule the +same repeating event twice. If not specified, it's set to the first argument after ``-command``. +``-time delay -timeUnits units``; delay is some positive integer, and units is some valid time +unit for ``dfhack.timeout(delay,timeUnits,function)``. ``-command [ ... ]`` specifies the +command to be run. + +=end]] local repeatUtil = require 'repeat-util' local utils = require 'utils' diff --git a/scripts/setfps.lua b/scripts/setfps.lua index 690f82702a..6deb68bb28 100644 --- a/scripts/setfps.lua +++ b/scripts/setfps.lua @@ -1,4 +1,12 @@ -- Set the FPS cap at runtime. +--[[=begin + +setfps +====== +Run ``setfps `` to set the FPS cap at runtime, in case you want to watch +combat in slow motion or something. + +=end]] local cap = ... local capnum = tonumber(cap) diff --git a/scripts/show-unit-syndromes.rb b/scripts/show-unit-syndromes.rb index f79a79e839..857ad84c01 100644 --- a/scripts/show-unit-syndromes.rb +++ b/scripts/show-unit-syndromes.rb @@ -1,6 +1,30 @@ -# Show syndromes affecting units and the remaining and maximum duration (v6). Call with help on the command line for further options. +# Show syndromes affecting units and the remaining and maximum duration # original author: drayath # edited by expwnent +=begin + +show-unit-syndromes +=================== +Show syndromes affecting units and the remaining and maximum duration, along +with (optionally) substantial detail on the effects. + +Use one or more of the following options: + +:help: Show the help message +:showall: Show units even if not affected by any syndrome +:showeffects: Show detailed effects of each syndrome +:showdisplayeffects: Show effects that only change the look of the unit +:ignorehiddencurse: Hide syndromes the user should not be able to know about (TODO) +:selected: Show selected unit +:dwarves: Show dwarves +:livestock: Show livestock +:wildanimals: Show wild animals +:hostile: Show hostiles (e.g. invaders, thieves, forgotten beasts etc) +:world: Show all defined syndromes in the world +:export: ``export:`` sends output to the given file, showing all + syndromes affecting each unit with the maximum and present duration. + +=end #TODO: When showing effects on a unit, show the actual change to the unit # E.g. if +150%, +500 strength show actual total bonus based on the unit stats. diff --git a/scripts/siren.lua b/scripts/siren.lua index 3a799c3e2d..053290a1c0 100644 --- a/scripts/siren.lua +++ b/scripts/siren.lua @@ -1,4 +1,15 @@ -- Wakes up the sleeping, breaks up parties and stops breaks. +--[[=begin + +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 +breaks will go on break again a lot sooner. The script is intended for +emergencies, e.g. when a siege appears, and all your military is partying. + +=end]] local utils = require 'utils' diff --git a/scripts/soundsense-season.lua b/scripts/soundsense-season.lua index 97e07903ed..da59205885 100644 --- a/scripts/soundsense-season.lua +++ b/scripts/soundsense-season.lua @@ -1,4 +1,17 @@ -- On map load writes the current season to gamelog.txt +--[[=begin + +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. + +This script registers a hook that prints the appropriate string +to :file:`gamelog.txt` on every map load to fix this. For best results +call the script from :file:`dfhack.init`. + +=end]] local seasons = { [-1] = 'Nothing', -- worldgen diff --git a/scripts/source.rb b/scripts/source.rb index 176cfbf2ba..647fc960a5 100644 --- a/scripts/source.rb +++ b/scripts/source.rb @@ -1,4 +1,34 @@ # create an infinite magma/water source/drain at the cursor +=begin + +source +====== +Create an infinite magma or water source or drain on a tile. + +This script registers a map tile as a liquid source, and every 12 game ticks +that tile receives or remove 1 new unit of flow based on the configuration. + +Place the game cursor where you want to create the source (must be a +flow-passable tile, and not too high in the sky) and call:: + + source add [magma|water] [0-7] + +The number argument is the target liquid level (0 = drain, 7 = source). + +To add more than 1 unit everytime, call the command again on the same spot. + +To delete one source, place the cursor over its tile and use ``source delete``. +To remove all existing sources, call ``source clear``. + +The ``list`` argument shows all existing sources. + +Examples:: + + source add water - water source + source add magma 7 - magma source + source add water 0 - water drain + +=end $sources ||= [] diff --git a/scripts/startdwarf.rb b/scripts/startdwarf.rb index 3da7c55e3d..4e7d01c07a 100644 --- a/scripts/startdwarf.rb +++ b/scripts/startdwarf.rb @@ -1,4 +1,14 @@ # patch start dwarf count +=begin + +startdwarf +========== +Use at the embark screen to embark with the specified number of dwarves. Eg. +``startdwarf 500`` would lead to a severe food shortage and FPS issues, while +``startdwarf 10`` would just allow a few more warm bodies to dig in. +The number must be 7 or greater. + +=end nr = $script_args[0].to_i diff --git a/scripts/stripcaged.rb b/scripts/stripcaged.rb index 07b8a7f22b..c3d2d3bb92 100644 --- a/scripts/stripcaged.rb +++ b/scripts/stripcaged.rb @@ -1,4 +1,27 @@ # mark stuff inside of cages for dumping. +=begin + +stripcaged +========== +For dumping items inside cages. Will mark selected items for dumping, then +a dwarf may come and actually dump it. See also `autodump`. + +With the ``items`` argument, only dumps items laying in the cage, excluding +stuff worn by caged creatures. ``weapons`` will dump worn weapons, ``armor`` +will dump everything worn by caged creatures (including armor and clothing), +and ``all`` will dump everything, on a creature or not. + +``stripcaged list`` will display on the dfhack console the list of all cages +and their item content. + +Without further arguments, all commands work on all cages and animal traps on +the map. With the ``here`` argument, considers only the in-game selected cage +(or the cage under the game cursor). To target only specific cages, you can +alternatively pass cage IDs as arguments:: + + stripcaged weapons 25321 34228 + +=end def plural(nr, name) # '1 cage' / '4 cages' diff --git a/scripts/superdwarf.rb b/scripts/superdwarf.rb index 7e3bff7007..8ea4609cbf 100644 --- a/scripts/superdwarf.rb +++ b/scripts/superdwarf.rb @@ -1,4 +1,19 @@ # give super-dwarven speed to an unit +=begin + +superdwarf +========== +Similar to `fastdwarf`, per-creature. + +To make any creature superfast, target it ingame using 'v' and:: + + superdwarf add + +Other options available: ``del``, ``clear``, ``list``. + +This script also shortens the 'sleeping' and 'on break' periods of targets. + +=end $superdwarf_onupdate ||= nil $superdwarf_ids ||= [] diff --git a/scripts/teleport.lua b/scripts/teleport.lua index cf4253ccf6..2efc0cbe41 100644 --- a/scripts/teleport.lua +++ b/scripts/teleport.lua @@ -2,6 +2,18 @@ -- teleports a unit to a location -- author Putnam -- edited by expwnent +--[[=begin + +teleport +======== +Teleports a unit to given coordinates. Examples: + +:teleport -showunitid: prints unitid beneath cursor +:teleport -showpos: prints coordinates beneath cursor +:teleport -unit 1234 -x 56 -y 115 -z 26: + teleports unit 1234 to 56,115,26 + +=end]] function teleport(unit,pos) local unitoccupancy = dfhack.maps.getTileBlock(unit.pos).occupancy[unit.pos.x%16][unit.pos.y%16] diff --git a/scripts/undump-buildings.lua b/scripts/undump-buildings.lua index 77e7fce5f6..f4cfe79094 100644 --- a/scripts/undump-buildings.lua +++ b/scripts/undump-buildings.lua @@ -1,4 +1,12 @@ -- Undesignates building base materials for dumping. +--[[=begin + +undump-buildings +================ +Undesignates building base materials for dumping. + +=end]] + function undump_buildings() local buildings = df.global.world.buildings.all local undumped = 0 diff --git a/scripts/unsuspend.rb b/scripts/unsuspend.rb index bd0c3ad78f..6669693598 100644 --- a/scripts/unsuspend.rb +++ b/scripts/unsuspend.rb @@ -1,5 +1,13 @@ # un-suspend construction jobs, one time only # same as "resume all" +=begin + +unsuspend +========= +Unsuspend jobs in workshops, on a one-off basis. See `autounsuspend` +for regular use. + +=end joblist = df.world.job_list.next count = 0 diff --git a/scripts/view-item-info.lua b/scripts/view-item-info.lua index acadb134c0..4729c8d3ce 100644 --- a/scripts/view-item-info.lua +++ b/scripts/view-item-info.lua @@ -2,14 +2,20 @@ -- Shows information on material properties, weapon or armour stats, and more. -- By PeridexisErrant, adapted from nb_item_info by Raidau --@ enable = true +local help = [[=begin -local help = [[Extended Item Viewscreen - +view-item-info +============== A script to extend the item or unit viewscreen with additional information -including properties such as material info, weapon and attack properties, -armor thickness and coverage, and more - including custom item descriptions.]] +including a custom description of each item (when available), and properties +such as material statistics, weapon attacks, armor effectiveness, and more. + +The associated script ``item-descriptions.lua`` supplies custom descriptions +of items. Individual descriptions can be added or overridden by a similar +script ``raw/scripts/more-item-descriptions.lua``. Both work as sparse lists, +so missing items simply go undescribed if not defined in the fallback. -vi_label = 'More information (DFHack):' +=end]] function isInList(list, item, helper) if not helper then @@ -372,6 +378,7 @@ function AddUsesString (viewscreen,line,indent) end function dfhack.onStateChange.item_info (code) + vi_label = 'More information (DFHack):' if not enabled then return end if code == SC_VIEWSCREEN_CHANGED and dfhack.isWorldLoaded() then standard = dfhack.matinfo.find("INORGANIC:IRON").material diff --git a/scripts/warn-starving.lua b/scripts/warn-starving.lua index 40d1ffa931..abf95f9ec8 100644 --- a/scripts/warn-starving.lua +++ b/scripts/warn-starving.lua @@ -1,6 +1,17 @@ -- Pauses the game with a warning if a creature is starving, dehydrated, or very drowsy. -- By Meneth32, PeridexisErrant, Lethosor --@ module = true +--[[=begin + +warn-starving +============= +If any (live) units are starving, very thirsty, or very drowsy, the game will +be paused and a warning shown and logged to the console. Use with the +`repeat` command for regular checks. + +Use ``warn-starving all`` to display a list of all problematic units. + +=end]] starvingUnits = starvingUnits or {} dehydratedUnits = dehydratedUnits or {} From 54f3c6a1383580274f3f9301e9dd81c1a8a040ff Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Sat, 24 Oct 2015 17:00:54 +1100 Subject: [PATCH 16/91] Updated docs linter for scripts Also made scripts toctree more explicit --- docs/Scripts.rst | 9 ++++-- travis/script-in-readme.py | 66 ++++++++++++++++++++++++-------------- 2 files changed, 48 insertions(+), 27 deletions(-) diff --git a/docs/Scripts.rst b/docs/Scripts.rst index 4d730d1423..88d2136332 100644 --- a/docs/Scripts.rst +++ b/docs/Scripts.rst @@ -48,10 +48,13 @@ The following pages document all the standard DFHack scripts. .. toctree:: - :glob: :maxdepth: 2 - /docs/_auto/* + /docs/_auto/base + /docs/_auto/devel + /docs/_auto/fix + /docs/_auto/gui + /docs/_auto/modtools .. warning:: @@ -66,5 +69,5 @@ The following pages document all the standard DFHack scripts. :glob: :maxdepth: 2 - /scripts/3rdparty/*/* + /scripts/3rdparty/*/README diff --git a/travis/script-in-readme.py b/travis/script-in-readme.py index f6b83bcd00..6b38a99f7c 100644 --- a/travis/script-in-readme.py +++ b/travis/script-in-readme.py @@ -1,30 +1,48 @@ -import os, sys +from io import open +import os +import sys -scriptdir = 'scripts' +scriptdirs = ( + 'scripts', + #'scripts/devel', # devel scripts don't have to be documented + 'scripts/fix', + 'scripts/gui', + 'scripts/modtools') + + +def check_file(fname): + doclines = [] + with open(fname, errors='ignore') as f: + for l in f.readlines(): + if doclines or l.strip().endswith('=begin'): + doclines.append(l.rstrip()) + if l.startswith('=end'): + break + else: + #print(doclines); sys.exit() + print('Error: docs start but not end:', fname) + return 1 + title, underline = doclines[2], doclines[3] + if underline != '=' * len(title): + print('Error: title/underline mismatch:', fname, title, underline) + return 1 + start = fname.split('/')[-2] + if start != 'scripts' and not title.startswith(start): + print('Error: title is missing start string:', fname, start, title) + return 1 + return 0 -def is_script(fname): - if not os.path.isfile(fname): - return False - return fname.endswith('.lua') or fname.endswith('.rb') def main(): - files = [] - for item in os.listdir(scriptdir): - path = os.path.join(scriptdir, item) - if is_script(path): - files.append(item) - elif os.path.isdir(path) and item not in ('devel', '3rdparty'): - files.extend([item + '/' + f for f in os.listdir(path) - if is_script(os.path.join(path, f))]) - with open('docs/Scripts.rst') as f: - text = f.read() - error = 0 - for f, _ in [os.path.splitext(p) for p in files]: - heading = '\n' + f + '\n' + '=' * len(f) + '\n' - if heading not in text: - print('WARNING: {:28} not documented in docs/Scripts'.format(f)) - error = 1 - sys.exit(error) + """Check that all DFHack scripts include documentation (not 3rdparty)""" + errors = 0 + for path in scriptdirs: + for f in os.listdir(path): + f = path + '/' + f + if os.path.isfile(f) and f[-3:] in {'.rb', 'lua'}: + errors += check_file(f) + return errors + if __name__ == '__main__': - main() + sys.exit(bool(main())) From 69090e114c217965ca653da1b1c484ee6d33f480 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Sat, 24 Oct 2015 17:41:21 +1100 Subject: [PATCH 17/91] Explain script type at top of listing Using an `about.txt` file in each directory. This is nice because it keeps the purpose notes in the actual script directories. --- docs/Scripts.rst | 32 +------------------------------- docs/conf.py | 6 ++++-- scripts/about.txt | 2 ++ scripts/devel/about.txt | 2 ++ scripts/fix/about.txt | 1 + scripts/gui/about.txt | 6 ++++++ scripts/modtools/about.txt | 17 +++++++++++++++++ 7 files changed, 33 insertions(+), 33 deletions(-) create mode 100644 scripts/about.txt create mode 100644 scripts/devel/about.txt create mode 100644 scripts/fix/about.txt create mode 100644 scripts/gui/about.txt create mode 100644 scripts/modtools/about.txt diff --git a/docs/Scripts.rst b/docs/Scripts.rst index 88d2136332..13b6ba4c13 100644 --- a/docs/Scripts.rst +++ b/docs/Scripts.rst @@ -9,44 +9,14 @@ of the ``ls`` command output. 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 -or from the init file. +or from the init file. See the page for each type for details. ``kill-lua`` stops any currently-running Lua scripts. By default, scripts can only be interrupted every 256 instructions. Use ``kill-lua force`` to interrupt the next instruction. - The following pages document all the standard DFHack scripts. -* Basic scripts are not stored in any subdirectory, and can be invoked directly. - They are generally useful tools for any player. -* ``devel/*`` scripts are intended for developers, or still substantially unfinished. - If you don't already know what they do, best to leave them alone. -* ``fix/*`` scripts fix various bugs and issues, some of them obscure. -* ``gui/*`` scripts implement dialogs in the main game window. - - In order to avoid user confusion, as a matter of policy all these tools - display the word "DFHack" on the screen somewhere while active. - When that is not appropriate because they merely add keybinding hints to - existing DF screens, they deliberately use red instead of green for the key. - -* ``modtools/*`` scripts provide tools for modders, often with changes - to the raw files, and are not intended to be called manually by end-users. - - 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. - - .. toctree:: :maxdepth: 2 diff --git a/docs/conf.py b/docs/conf.py index bb65f361ee..e13fcda56a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -75,8 +75,10 @@ def document_scripts(): 'gui': 'GUI Scripts', 'modtools': 'Scripts for Modders'} for k in head: - title = '.. _{k}:\n\n{l}\n{t}\n{l}\n\n.. contents::\n\n'.format( - k=k, t=head[k], l=len(head[k])*'#') + title = ('.. _{k}:\n\n{l}\n{t}\n{l}\n\n' + '.. include:: /scripts/{a}about.txt\n\n' + '.. contents::\n\n').format( + k=k, t=head[k], l=len(head[k])*'#', a=('' if k=='base' else k+'/')) mode = 'w' if sys.version_info.major > 2 else 'wb' with open('_auto/{}.rst'.format(k), mode) as outfile: outfile.write(title) diff --git a/scripts/about.txt b/scripts/about.txt new file mode 100644 index 0000000000..818891af5d --- /dev/null +++ b/scripts/about.txt @@ -0,0 +1,2 @@ +Basic scripts are not stored in any subdirectory, and can be invoked directly. +They are generally useful tools for any player. diff --git a/scripts/devel/about.txt b/scripts/devel/about.txt new file mode 100644 index 0000000000..cd97a88095 --- /dev/null +++ b/scripts/devel/about.txt @@ -0,0 +1,2 @@ +``devel/*`` scripts are intended for developers, or still substantially unfinished. +If you don't already know what they do, best to leave them alone. diff --git a/scripts/fix/about.txt b/scripts/fix/about.txt new file mode 100644 index 0000000000..6a2d35c7ed --- /dev/null +++ b/scripts/fix/about.txt @@ -0,0 +1 @@ +``fix/*`` scripts fix various bugs and issues, some of them obscure. diff --git a/scripts/gui/about.txt b/scripts/gui/about.txt new file mode 100644 index 0000000000..1c83e50b2c --- /dev/null +++ b/scripts/gui/about.txt @@ -0,0 +1,6 @@ +``gui/*`` scripts implement dialogs in the main game window. + +In order to avoid user confusion, as a matter of policy all these tools +display the word "DFHack" on the screen somewhere while active. +When that is not appropriate because they merely add keybinding hints to +existing DF screens, they deliberately use red instead of green for the key. diff --git a/scripts/modtools/about.txt b/scripts/modtools/about.txt new file mode 100644 index 0000000000..d2924b301f --- /dev/null +++ b/scripts/modtools/about.txt @@ -0,0 +1,17 @@ +``modtools/*`` scripts provide tools for modders, often with changes +to the raw files, and are not intended to be called manually by end-users. + +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. + +Any of these scripts can be called with ``-help`` for more information. From a3803d340eed87ddf9f7eb05f5f702d0eafdce36 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Sat, 24 Oct 2015 22:19:52 +1100 Subject: [PATCH 18/91] Build docs in place; copy inputs so users can build Building the docs now works the same way, no matter when it happens - in a cloned repo or distributed version. This means all the relative links keep working; and that users or downstream distributors can rebuild the docs with extra scripts or .rst files in place. Finally, it eliminates a large number of potential bugs which only occur in one build environment and are difficult to reproduce. Also add headings and this work to future news. --- CMakeLists.txt | 41 +++++++++++++------------------------- NEWS.rst | 53 ++++++++++++++++++++++++++++++++++++++++---------- docs/conf.py | 12 +++--------- 3 files changed, 59 insertions(+), 47 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 649580f9ea..c5d343ee4d 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -201,43 +201,30 @@ if (BUILD_DOCS) if (NOT SPHINX_FOUND) message(SEND_ERROR "Sphinx not found but BUILD_DOCS enabled") endif() - set(SPHINX_THEME_DIR) - set(SPHINX_BINARY_BUILD_DIR "${CMAKE_CURRENT_SOURCE_DIR}/docs/_build") - set(SPHINX_CACHE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/docs/_build/_doctrees") - set(SPHINX_HTML_DIR "${CMAKE_CURRENT_SOURCE_DIR}/docs/html/") - - configure_file( - "${CMAKE_CURRENT_SOURCE_DIR}/docs/conf.py" - "${SPHINX_BINARY_BUILD_DIR}/docs/conf.py" - @ONLY) file(GLOB SPHINX_DEPS "${CMAKE_CURRENT_SOURCE_DIR}/docs/*.rst" "${CMAKE_CURRENT_SOURCE_DIR}/docs/images/*.png" - "${CMAKE_CURRENT_SOURCE_DIR}/docs/styles*" + "${CMAKE_CURRENT_SOURCE_DIR}/docs/styles/*" "${CMAKE_CURRENT_SOURCE_DIR}/docs/conf.py" - "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*.lua" - "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*.lua" - "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*/*.lua" - "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*/*/*.lua" - "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*/*/*/*.lua" - "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*/*/*/*/*.lua" - "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*/*/*/*/*/*.lua" - "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*/*/*/*/*/*/*.lua" - "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*/*/*/*/*/*/*/*.lua" - "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/*/*/*/*/*/*/*/*/*.lua" + "${CMAKE_CURRENT_SOURCE_DIR}/scripts/about.txt" + "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/about.txt" + ) + file(GLOB_RECURSE SPHINX_SCRIPT_DEPS scripts "${CMAKE_CURRENT_SOURCE_DIR}" + "*.lua" + "*.rb" ) - set(SPHINX_DEPS ${SPHINX_DEPS} LICENSE.rst NEWS.rst README.rst) + set(SPHINX_DEPS ${SPHINX_DEPS} ${SPHINX_SCRIPT_DEPS} LICENSE.rst NEWS.rst README.rst) set(SPHINX_OUTPUT "${CMAKE_CURRENT_SOURCE_DIR}/docs/html/.buildinfo") set_source_files_properties(${SPHINX_OUTPUT} PROPERTIES GENERATED TRUE) add_custom_command(OUTPUT ${SPHINX_OUTPUT} COMMAND ${SPHINX_EXECUTABLE} -a -E -q -b html - -c "${SPHINX_BINARY_BUILD_DIR}/docs" - -d "${SPHINX_CACHE_DIR}" + -c "${CMAKE_CURRENT_SOURCE_DIR}/docs" "${CMAKE_CURRENT_SOURCE_DIR}" - "${SPHINX_HTML_DIR}" + "${CMAKE_CURRENT_SOURCE_DIR}/docs/html" + -w "${CMAKE_CURRENT_SOURCE_DIR}/docs/_build/sphinx-warnings.txt" DEPENDS ${SPHINX_DEPS} COMMENT "Building HTML documentation with Sphinx" ) @@ -250,12 +237,10 @@ if (BUILD_DOCS) add_custom_command(TARGET dfhack_docs POST_BUILD COMMAND ${CMAKE_COMMAND} -E touch ${SPHINX_OUTPUT}) - install(DIRECTORY ${dfhack_SOURCE_DIR}/docs/html + install(DIRECTORY ${dfhack_SOURCE_DIR}/docs DESTINATION ${DFHACK_USERDOC_DESTINATION} - #FILES_MATCHING PATTERN "*.lua" - # PATTERN "*.rb" - # PATTERN "3rdparty" EXCLUDE ) + install(FILES "README.html" DESTINATION "${DFHACK_DATA_DESTINATION}") endif() # Packaging with CPack! diff --git a/NEWS.rst b/NEWS.rst index 304150e130..e0a6639e09 100644 --- a/NEWS.rst +++ b/NEWS.rst @@ -29,9 +29,11 @@ Changelog DFHack Future ============= + +Internals +========= :: - Internals A method for caching screen output is now available to Lua (and C++) Developer plugins can be ignored on startup by setting the DFHACK_NO_DEV_PLUGINS environment variable The console on Linux and OS X now recognizes keyboard input between prompts @@ -44,18 +46,34 @@ DFHack Future Keybindings can now use F10-F12 and 0-9 Plugin system is no longer restricted to plugins that exist on startup dfhack.init file locations significantly generalized - Lua + +Lua +=== +:: + Scripts can be enabled with the built-in enable/disable commands A new function, reqscript(), is available as a safer alternative to script_environment() Lua viewscreens can choose not to intercept the OPTIONS keybinding - New internal commands + +New internal commands +===================== +:: + kill-lua: Interrupt running Lua scripts type: Show where a command is implemented - New plugins + +New plugins +=========== +:: + confirm: Adds confirmation dialogs for several potentially dangerous actions fix-unit-occupancy: Fixes issues with unit occupancy, such as faulty "unit blocking tile" messages (bug 3499) title-version (formerly vshook): Display DFHack version on title screen - New scripts + +New scripts +=========== +:: + burial: sets all unowned coffins to allow burial ("-pets" to allow pets too) fix-ster: changes fertility/sterility of animals or dwarves view-item-info: adds information and customisable descriptions to item viewscreens @@ -71,12 +89,20 @@ DFHack Future - make-legendary: modify skill(s) of a single unit - pref-adjust: Adjust all preferences of all dwarves in play - rejuvenate: make any "old" dwarf 20 years old - New tweaks + +New tweaks +========== +:: + embark-profile-name: Allows the use of lowercase letters when saving embark profiles kitchen-keys: Fixes DF kitchen meal keybindings kitchen-prefs-color: Changes color of enabled items to green in kitchen preferences kitchen-prefs-empty: Fixes a layout issue with empty kitchen tabs - Fixes + +Fixes +===== +:: + Plugins with vmethod hooks can now be reloaded on OS X Lua's os.system() now works on OS X Fixed default arguments in Lua gametype detection functions @@ -103,13 +129,18 @@ DFHack Future workflow: Fixed some issues with stuck jobs - Note: Existing stuck jobs must be cancelled and re-added zone: Fixed a crash when using "zone set" (and a few other potential crashes) - Misc Improvements + +Misc Improvements +================= +:: + DFHack documentation: - massively reorganised, into files of more readable size - added many missing entries - indexes, internal links, offline search all documents - includes documentation of linked projects (df-structures, 3rdparty scripts) - better HTML generation with Sphinx + - documentation for scripts now located in source files autolabor: - Stopped modification of labors that shouldn't be modified for brokers/diplomats - Prioritize skilled dwarves more efficiently @@ -149,8 +180,10 @@ DFHack Future - debug output now logged to stderr.log instead of console - makes DFHack start faster - farm-plot-select: Fixed issues with selecting undiscovered crops workflow: Improved handling of plant reactions - Removed - embark-tools nano: 1x1 embarks are now possible in vanilla 0.40.24 + +Removed +======= +- `embark-tools` nano: 1x1 embarks are now possible in vanilla 0.40.24 DFHack 0.40.24-r3 ================= diff --git a/docs/conf.py b/docs/conf.py index e13fcda56a..0f608e30ef 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -141,7 +141,7 @@ def document_scripts(): # |version| and |release|, also used in various other places throughout the # built documents. -def get_version(default): +def get_version(): """Return the DFHack version string, from CMakeLists.txt""" version = release = '' try: @@ -153,20 +153,14 @@ def get_version(default): release = s.upper().replace('SET(DFHACK_RELEASE "', '').lower() return (version + '-' + release).replace('")\n', '') except IOError: - return default + return 'unknown' # The short X.Y version. -version = '@DFHACK_VERSION@' # The full version, including alpha/beta/rc tags. -release = '@DFHACK_VERSION@' - -if version == '@DFHACK_VERSION@': - # Not running through CMake... - version = release = get_version('@DFHACK_VERSION@') +version = release = get_version() # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -# # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. language = None From c113d9b579059e4b492a5942b41a111d88bdd319 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Sat, 24 Oct 2015 22:57:08 +1100 Subject: [PATCH 19/91] Format future news --- NEWS.rst | 259 ++++++++++++++++++++++------------------------- docs/Plugins.rst | 9 +- 2 files changed, 131 insertions(+), 137 deletions(-) diff --git a/NEWS.rst b/NEWS.rst index e0a6639e09..17f337c7a0 100644 --- a/NEWS.rst +++ b/NEWS.rst @@ -31,158 +31,145 @@ DFHack Future ============= Internals -========= -:: - - A method for caching screen output is now available to Lua (and C++) - Developer plugins can be ignored on startup by setting the DFHACK_NO_DEV_PLUGINS environment variable - The console on Linux and OS X now recognizes keyboard input between prompts - JSON libraries available (C++ and Lua) - More DFHack build information used in plugin version checks and available to plugins and lua scripts - Fixed a rare overflow issue that could cause crashes on Linux and OS X - Stopped DF window from receiving input when unfocused on OS X - Fixed issues with keybindings involving Ctrl-A and Ctrl-Z, as well as Alt-E/U/N on OS X - Multiple contexts can now be specified when adding keybindings - Keybindings can now use F10-F12 and 0-9 - Plugin system is no longer restricted to plugins that exist on startup - dfhack.init file locations significantly generalized +--------- +- A method for caching screen output is now available to Lua (and C++) +- Developer plugins can be ignored on startup by setting the DFHACK_NO_DEV_PLUGINS environment variable +- The console on Linux and OS X now recognizes keyboard input between prompts +- JSON libraries available (C++ and Lua) +- More DFHack build information used in plugin version checks and available to plugins and lua scripts +- Fixed a rare overflow issue that could cause crashes on Linux and OS X +- Stopped DF window from receiving input when unfocused on OS X +- Fixed issues with keybindings involving Ctrl-A and Ctrl-Z, as well as Alt-E/U/N on OS X +- Multiple contexts can now be specified when adding keybindings +- Keybindings can now use F10-F12 and 0-9 +- Plugin system is no longer restricted to plugins that exist on startup +- :file:`dfhack.init` file locations significantly generalized Lua -=== -:: - - Scripts can be enabled with the built-in enable/disable commands - A new function, reqscript(), is available as a safer alternative to script_environment() - Lua viewscreens can choose not to intercept the OPTIONS keybinding +--- +- Scripts can be enabled with the built-in enable/disable commands +- A new function, reqscript(), is available as a safer alternative to script_environment() +- Lua viewscreens can choose not to intercept the OPTIONS keybinding New internal commands -===================== -:: - - kill-lua: Interrupt running Lua scripts - type: Show where a command is implemented +--------------------- +- kill-lua: Interrupt running Lua scripts +- type: Show where a command is implemented New plugins -=========== -:: - - confirm: Adds confirmation dialogs for several potentially dangerous actions - fix-unit-occupancy: Fixes issues with unit occupancy, such as faulty "unit blocking tile" messages (bug 3499) - title-version (formerly vshook): Display DFHack version on title screen +----------- +- `confirm`: Adds confirmation dialogs for several potentially dangerous actions +- `fix-unit-occupancy`: Fixes issues with unit occupancy, such as faulty "unit blocking tile" messages (:bug:`3499`) +- title-version (formerly vshook): Display DFHack version on title screen New scripts -=========== -:: - - burial: sets all unowned coffins to allow burial ("-pets" to allow pets too) - fix-ster: changes fertility/sterility of animals or dwarves - view-item-info: adds information and customisable descriptions to item viewscreens - warn-starving: check for starving, thirsty, or very drowsy units and pause with warning if any are found - modtools/create-unit: create new units from nothing - modtools/equip-item: a script to equip items on units - points: set number of points available at embark screen - Vjek's script collection: - - armoks-blessing: Adjust all attributes, personality, age and skills of all dwarves in play - - brainwash: brainwash a dwarf (modifying their personality) - - elevate-mental: elevate all the mental attributes of a unit - - elevate-physical: elevate all the physical attributes of a unit - - make-legendary: modify skill(s) of a single unit - - pref-adjust: Adjust all preferences of all dwarves in play - - rejuvenate: make any "old" dwarf 20 years old +----------- +- `burial`: sets all unowned coffins to allow burial ("-pets" to allow pets too) +- `fix-ster`: changes fertility/sterility of animals or dwarves +- `view-item-info`: adds information and customisable descriptions to item viewscreens +- `warn-starving`: check for starving, thirsty, or very drowsy units and pause with warning if any are found +- `modtools/create-unit`: create new units from nothing +- `modtools/equip-item`: a script to equip items on units +- `points`: set number of points available at embark screen +- `armoks-blessing`: Adjust all attributes, personality, age and skills of all dwarves in play +- `brainwash`: brainwash a dwarf (modifying their personality) +- `elevate-mental`: elevate all the mental attributes of a unit +- `elevate-physical`: elevate all the physical attributes of a unit +- `make-legendary`: modify skill(s) of a single unit +- `pref-adjust`: Adjust all preferences of all dwarves in play +- `rejuvenate`: make any "old" dwarf 20 years old New tweaks -========== -:: - - embark-profile-name: Allows the use of lowercase letters when saving embark profiles - kitchen-keys: Fixes DF kitchen meal keybindings - kitchen-prefs-color: Changes color of enabled items to green in kitchen preferences - kitchen-prefs-empty: Fixes a layout issue with empty kitchen tabs +---------- +- embark-profile-name: Allows the use of lowercase letters when saving embark profiles +- kitchen-keys: Fixes DF kitchen meal keybindings +- kitchen-prefs-color: Changes color of enabled items to green in kitchen preferences +- kitchen-prefs-empty: Fixes a layout issue with empty kitchen tabs Fixes -===== -:: - - Plugins with vmethod hooks can now be reloaded on OS X - Lua's os.system() now works on OS X - Fixed default arguments in Lua gametype detection functions - Circular lua dependencies (reqscript/script_environment) fixed - Prevented crash in Items::createItem() - buildingplan: Now supports hatch covers - gui/create-item: - - fixed assigning quality to items - - made "esc" work properly - gui/gm-editor handles lua tables properly - help: now recognizes built-in commands, like "help" - manipulator: fixed crash when selecting custom professions when none are found - remotefortressreader: fixed crash when attempting to send map info when no map was loaded - search: - - fixed crash in unit list after cancelling a job - - fixed crash when disabling stockpile category after searching in a subcategory - stockpiles: now checks/sanitizes filenames when saving - stocks: fixed a crash when right-clicking - steam-engine: - - fixed a crash on arena load - - number keys (e.g. 2/8) take priority over cursor keys when applicable - tweak fps-min fixed - tweak farm-plot-select: Stopped controls from appearing when plots weren't fully built - workflow: Fixed some issues with stuck jobs - - Note: Existing stuck jobs must be cancelled and re-added - zone: Fixed a crash when using "zone set" (and a few other potential crashes) +----- +- Plugins with vmethod hooks can now be reloaded on OS X +- Lua's ``os.system()`` now works on OS X +- Fixed default arguments in Lua gametype detection functions +- Circular lua dependencies (reqscript/script_environment) fixed +- Prevented crash in ``Items::createItem()`` +- `buildingplan`: Now supports hatch covers +- `gui/create-item`: fixed assigning quality to items, made :kbd:`Esc` work properly +- `gui/gm-editor`: handles lua tables properly +- help: now recognizes built-in commands, like "help" +- `manipulator`: fixed crash when selecting custom professions when none are found +- `remotefortressreader`: fixed crash when attempting to send map info when no map was loaded +- `search`: fixed crash in unit list after cancelling a job; fixed crash when disabling stockpile category after searching in a subcategory +- `stockpiles`: now checks/sanitizes filenames when saving +- `stocks`: fixed a crash when right-clicking +- `steam-engine`: fixed a crash on arena load; number keys (e.g. 2/8) take priority over cursor keys when applicable +- tweak fps-min fixed +- tweak farm-plot-select: Stopped controls from appearing when plots weren't fully built +- `workflow`: Fixed some issues with stuck jobs. Existing stuck jobs must be cancelled and re-added +- `zone`: Fixed a crash when using ``zone set`` (and a few other potential crashes) Misc Improvements -================= -:: - - DFHack documentation: - - massively reorganised, into files of more readable size - - added many missing entries - - indexes, internal links, offline search all documents - - includes documentation of linked projects (df-structures, 3rdparty scripts) - - better HTML generation with Sphinx - - documentation for scripts now located in source files - autolabor: - - Stopped modification of labors that shouldn't be modified for brokers/diplomats - - Prioritize skilled dwarves more efficiently - - Prevent dwarves from running away with tools from previous jobs - dwarfmonitor: - - widgets' positions, formats, etc. are now customizable (see Readme) - - weather display now separated from the date display - - New mouse cursor widget - dfstatus: Can enable/disable individual categories and customize metal bar list - full-heal: "-r" option removes corpses - gui/gm-editor - - Pointers can now be displaced - - Added some useful aliases: "item" for the selected item, "screen" for the current screen, etc. - - Now avoids errors with unrecognized types - gui/hack-wish: renamed to gui/create-item - "keybinding list" accepts a context - lever: - - Lists lever names - - "lever pull" can be used to pull the currently-selected lever - memview: Fixed display issue - modtools/create-item: arguments are named more clearly, and you can specify the creator to be - the unit with id df.global.unit_next_id-1 (useful in conjunction with modtools/create-unit) - nyan: Can now be stopped with dfhack-run - plug: - - lists all plugins - - shows state and number of commands in plugins - prospect: works from within command-prompt - quicksave: Restricted to fortress mode - remotefortressreader: Exposes more information - search: - - Supports noble suggestion screen (e.g. suggesting a baron) - - Supports fortress mode loo[k] menu - - Recognizes ? and ; keys - stocks: can now match beginning and end of item names - teleport: Fixed cursor recognition - tweak: - - debug output now logged to stderr.log instead of console - makes DFHack start faster - - farm-plot-select: Fixed issues with selecting undiscovered crops - workflow: Improved handling of plant reactions +----------------- +- DFHack documentation: + + - massively reorganised, into files of more readable size + - added many missing entries + - indexes, internal links, offline search all documents + - includes documentation of linked projects (df-structures, 3rdparty scripts) + - better HTML generation with Sphinx + - documentation for scripts now located in source files + +- `autolabor`: + + - Stopped modification of labors that shouldn't be modified for brokers/diplomats + - Prioritize skilled dwarves more efficiently + - Prevent dwarves from running away with tools from previous jobs + +- `dwarfmonitor`: + + - widgets' positions, formats, etc. are now customizable (see Readme) + - weather display now separated from the date display + - New mouse cursor widget + +- `gui/dfstatus`: Can enable/disable individual categories and customize metal bar list +- `full-heal`: "-r" option removes corpses +- `gui/gm-editor` + + - Pointers can now be displaced + - Added some useful aliases: "item" for the selected item, "screen" for the current screen, etc. + - Now avoids errors with unrecognized types + +- `gui/hack-wish`: renamed to `gui/create-item` +- "keybinding list" accepts a context +- `lever`: + + - Lists lever names + - "lever pull" can be used to pull the currently-selected lever + +- memview: Fixed display issue +- `modtools/create-item`: arguments are named more clearly, and you can specify the creator to be the unit with id ``df.global.unit_next_id-1`` (useful in conjunction with `modtools/create-unit`) +- nyan: Can now be stopped with dfhack-run +- plug: lists all plugins; shows state and number of commands in plugins +- `prospect`: works from within command-prompt +- `quicksave`: Restricted to fortress mode +- `remotefortressreader`: Exposes more information +- `search`: + + - Supports noble suggestion screen (e.g. suggesting a baron) + - Supports fortress mode loo[k] menu + - Recognizes ? and ; keys + +- `stocks`: can now match beginning and end of item names +- `teleport`: Fixed cursor recognition +- `tweak`: + + - debug output now logged to stderr.log instead of console - makes DFHack start faster + - farm-plot-select: Fixed issues with selecting undiscovered crops + +- `workflow`: Improved handling of plant reactions Removed -======= +------- - `embark-tools` nano: 1x1 embarks are now possible in vanilla 0.40.24 DFHack 0.40.24-r3 diff --git a/docs/Plugins.rst b/docs/Plugins.rst index 5891f4494f..f00ceee9e2 100644 --- a/docs/Plugins.rst +++ b/docs/Plugins.rst @@ -215,6 +215,8 @@ This command adds the Guild Representative position to all Human civilizations, allowing them to make trade agreements (just as they did back in 0.28.181.40d and earlier) in case you haven't already modified your raws accordingly. +.. _fix-unit-occupancy: + fix-unit-occupancy ================== This plugin fixes issues with unit occupancy, notably issues with phantom @@ -526,6 +528,8 @@ to always have one or two doors/beds/tables/chairs/etc available, and place as many as you like. The plugins then take over and fulfill the orders, with minimal space dedicated to stockpiles. +.. _confirm: + confirm ------- Implements several confirmation dialogs for potentially destructive actions @@ -597,6 +601,7 @@ stockpile management -------------------- .. _stocksettings: +.. _stockpiles: import/export ~~~~~~~~~~~~~ @@ -2335,7 +2340,9 @@ 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 +.. _steam-engine: + +steam-engine ------------ The steam-engine plugin detects custom workshops with STEAM_ENGINE in their token, and turns them into real steam engines. From 413a61423a712871c9025e00eef40f590b5eb0e4 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Sun, 25 Oct 2015 10:14:09 +1100 Subject: [PATCH 20/91] Tweak docs building Trying to save the warnings to a file only works if the directory exists. Also fix digfort docs error. --- .gitignore | 2 +- CMakeLists.txt | 2 +- scripts/digfort.rb | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.gitignore b/.gitignore index 63bd079c36..70ccb04455 100644 --- a/.gitignore +++ b/.gitignore @@ -21,7 +21,7 @@ buntu build/VC2010 # Sphinx generated documentation -docs/_*/ +docs/_* docs/html/ #except for the real one diff --git a/CMakeLists.txt b/CMakeLists.txt index c5d343ee4d..20a964998a 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -224,7 +224,7 @@ if (BUILD_DOCS) -c "${CMAKE_CURRENT_SOURCE_DIR}/docs" "${CMAKE_CURRENT_SOURCE_DIR}" "${CMAKE_CURRENT_SOURCE_DIR}/docs/html" - -w "${CMAKE_CURRENT_SOURCE_DIR}/docs/_build/sphinx-warnings.txt" + -w "${CMAKE_CURRENT_SOURCE_DIR}/docs/_sphinx-warnings.txt" DEPENDS ${SPHINX_DEPS} COMMENT "Building HTML documentation with Sphinx" ) diff --git a/scripts/digfort.rb b/scripts/digfort.rb index 0a0853cfde..4803e22c8b 100644 --- a/scripts/digfort.rb +++ b/scripts/digfort.rb @@ -10,10 +10,10 @@ # this is a comment d;d;u;d;d;skip this tile;d - d;d;d;i + d;d;d;j Available tile shapes are named after the 'dig' menu shortcuts: -``d`` for dig, ``u`` for upstairs, ``d`` downstairs, ``i`` updown, +``d`` for dig, ``u`` for upstairs, ``d`` downstairs, ``j`` updown, ``h`` channel, ``r`` upward ramp, ``x`` remove designation. Unrecognized characters are ignored (eg the 'skip this tile' in the sample). From 4be9e13d743f24d799582e681cc42c4f1d4f0acc Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Mon, 26 Oct 2015 11:06:57 +1100 Subject: [PATCH 21/91] Fix digfort docs I'm sure this isn't the only error in the docs. Hopefully having them in the scripts will make spotting issues easier. --- scripts/digfort.rb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/scripts/digfort.rb b/scripts/digfort.rb index 4803e22c8b..4ae48671e1 100644 --- a/scripts/digfort.rb +++ b/scripts/digfort.rb @@ -10,10 +10,10 @@ # this is a comment d;d;u;d;d;skip this tile;d - d;d;d;j + d;d;d;i Available tile shapes are named after the 'dig' menu shortcuts: -``d`` for dig, ``u`` for upstairs, ``d`` downstairs, ``j`` updown, +``d`` for dig, ``u`` for upstairs, ``j`` downstairs, ``i`` updown, ``h`` channel, ``r`` upward ramp, ``x`` remove designation. Unrecognized characters are ignored (eg the 'skip this tile' in the sample). From 5efea525e08568d46877183463180f55130061be Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Wed, 28 Oct 2015 10:06:28 +1100 Subject: [PATCH 22/91] Split GitHub README from Sphinx index The root of the documentation tree has a different function to the short readme we want to display on GitHub, which now links to the main docs (or Bay12 thread, or IRC). It also renders properly on GitHub, and can use live-updating status badges because we don't expect it to work offline. --- CMakeLists.txt | 2 +- README.html | 6 +++--- README.md | 24 ++++++++++++++++++++++++ docs/conf.py | 2 +- README.rst => index.rst | 19 ++++++++----------- 5 files changed, 37 insertions(+), 16 deletions(-) create mode 100644 README.md rename README.rst => index.rst (83%) diff --git a/CMakeLists.txt b/CMakeLists.txt index 20a964998a..715744239c 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -214,7 +214,7 @@ if (BUILD_DOCS) "*.lua" "*.rb" ) - set(SPHINX_DEPS ${SPHINX_DEPS} ${SPHINX_SCRIPT_DEPS} LICENSE.rst NEWS.rst README.rst) + set(SPHINX_DEPS ${SPHINX_DEPS} ${SPHINX_SCRIPT_DEPS} LICENSE.rst NEWS.rst index.rst) set(SPHINX_OUTPUT "${CMAKE_CURRENT_SOURCE_DIR}/docs/html/.buildinfo") set_source_files_properties(${SPHINX_OUTPUT} PROPERTIES GENERATED TRUE) diff --git a/README.html b/README.html index 481058eb4a..325cd66f60 100644 --- a/README.html +++ b/README.html @@ -4,13 +4,13 @@ - + Page Redirection - If you are not redirected automatically, follow the link to the documentation. + Follow this link to the documentation. \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000000..50769e0c50 --- /dev/null +++ b/README.md @@ -0,0 +1,24 @@ +#DFHack Readme + +[![Build Status](https://travis-ci.org/DFHack/dfhack.svg?branch=develop)] +(https://travis-ci.org/DFHack/dfhack) +[![Documentation Status](https://readthedocs.org/projects/dfhack/badge)] +(https://dfhack.readthedocs.org) +[![License](https://img.shields.io/badge/license-ZLib-blue.svg)] +(https://en.wikipedia.org/wiki/Zlib_License) +[![Github Issues](http://githubbadges.herokuapp.com/DFHack/dfhack/issues)] +(https://github.com/DFHack/dfhack/issues) +[![Open Pulls](http://githubbadges.herokuapp.com/DFHack/dfhack/pulls)] +(https://github.com/DFHack/dfhack/pulls) + +DFHack is a Dwarf Fortress memory access library, distributed with scripts +and plugins implementing a wide variety of useful functions and tools. + +The full documentation [is available online here](https://dfhack.readthedocs.org), +from the README.html page in the DFHack distribution, or as raw text in the `./docs` folder. +If you're an end-user, modder, or interested in contributing to DFHack - +go read those docs. + +If that's unclear or you need more help, try [the Bay12 forums thread] +(http://www.bay12forums.com/smf/index.php?topic=139553) or the #dfhack IRC +channel on freenode. diff --git a/docs/conf.py b/docs/conf.py index 0f608e30ef..546f843c81 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -130,7 +130,7 @@ def document_scripts(): #source_encoding = 'utf-8-sig' # The master toctree document. -master_doc = 'README' +master_doc = 'index' # General information about the project. project = 'DFHack' diff --git a/README.rst b/index.rst similarity index 83% rename from README.rst rename to index.rst index dcf3fb9059..a93660db3b 100644 --- a/README.rst +++ b/index.rst @@ -1,5 +1,6 @@ +################################## Welcome to DFHack's documentation! -================================== +################################## Introduction ============ @@ -22,14 +23,8 @@ allows easier development of new tools. As an open-source project under `various copyleft licences `, contributions are welcome. -Documentation -============= -DFHack documentation is generated by Sphinx. Check out the table of contents -below, or the sources in the `docs folder`_! - -.. _`docs folder`: ./docs - -User Manual: +User Manual +=========== .. toctree:: :maxdepth: 2 @@ -38,7 +33,8 @@ User Manual: docs/Plugins docs/Scripts -Other Contents: +Other Contents +============== .. toctree:: :maxdepth: 1 @@ -47,7 +43,8 @@ Other Contents: LICENSE NEWS -For Developers: +For Developers +============== .. toctree:: :maxdepth: 1 From a37ae8dbd2ee4b7047d3a7eb64b1fc7bfc762f76 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Wed, 28 Oct 2015 10:07:02 +1100 Subject: [PATCH 23/91] Improve travis checks for branch, script docs The change to pr-check-base avoids failing builds which should pass because the GH API is limited. It'll still work almost all of the time, but no longer fail builds which previously passed and then pushed more commits. Closes #694. --- travis/pr-check-base.py | 2 +- travis/script-in-readme.py | 8 +++++--- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/travis/pr-check-base.py b/travis/pr-check-base.py index f3cbab18ce..74196cd166 100644 --- a/travis/pr-check-base.py +++ b/travis/pr-check-base.py @@ -21,7 +21,7 @@ pass except HTTPError as e: print('Failed to retrieve PR information from API: %s' % e) - sys.exit(2) + sys.exit(0) if 'base' not in res or 'ref' not in res['base']: print('Invalid JSON returned from API') sys.exit(2) diff --git a/travis/script-in-readme.py b/travis/script-in-readme.py index 6b38a99f7c..b7d0577f39 100644 --- a/travis/script-in-readme.py +++ b/travis/script-in-readme.py @@ -19,8 +19,10 @@ def check_file(fname): if l.startswith('=end'): break else: - #print(doclines); sys.exit() - print('Error: docs start but not end:', fname) + if doclines: + print('Error: docs start but not end: ' + fname) + else: + print('Error: no documentation in: ' + fname) return 1 title, underline = doclines[2], doclines[3] if underline != '=' * len(title): @@ -28,7 +30,7 @@ def check_file(fname): return 1 start = fname.split('/')[-2] if start != 'scripts' and not title.startswith(start): - print('Error: title is missing start string:', fname, start, title) + print('Error: title is missing start string: {} {} {}'.format(fname, start, title)) return 1 return 0 From 056c1bcb2dcf580135638e271a3a897eb8deb2d7 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Wed, 28 Oct 2015 10:18:44 +1100 Subject: [PATCH 24/91] Document new scripts --- scripts/migrants-now.lua | 9 +++++++++ scripts/spawnunit.lua | 8 ++++++++ 2 files changed, 17 insertions(+) diff --git a/scripts/migrants-now.lua b/scripts/migrants-now.lua index 22719be199..b2f08e9f92 100644 --- a/scripts/migrants-now.lua +++ b/scripts/migrants-now.lua @@ -1,2 +1,11 @@ -- Force a migrant wave (only works after hardcoded waves) --@alias = 'devel/migrants-now' +--[[=begin + +migrants-now +============ +Forces an immediate migrant wave. Only works after migrants have +arrived naturally. Alias for ``devel/migrants-now``; equivalent to +`modtools/force` ``-eventType migrants`` + +=end]] diff --git a/scripts/spawnunit.lua b/scripts/spawnunit.lua index 1c29649360..348c0984eb 100644 --- a/scripts/spawnunit.lua +++ b/scripts/spawnunit.lua @@ -1,5 +1,13 @@ -- create unit at pointer or given location -- wraps modtools/create-unit.lua +--[[=begin + +spawnunit +========= +``spawnunit RACE CASTE`` creates a unit of the given race and caste at the cursor, by +wrapping `modtools/create-unit`. Run ``spawnunit help`` for more options. + +=end]] usage = [[Usage: - spawnunit RACE CASTE From 92cd313776402f39a8548fded4edbe056978ce8f Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Thu, 29 Oct 2015 12:44:49 +1100 Subject: [PATCH 25/91] Improve markup in scripts documentation Plus minor changes for clarification. --- scripts/exportlegends.lua | 4 ++-- scripts/fix/fat-dwarves.lua | 2 ++ scripts/fix/stable-temp.lua | 9 +++------ scripts/gui/advfort.lua | 2 +- scripts/gui/gm-editor.lua | 10 ++++------ scripts/gui/liquids.lua | 2 +- scripts/gui/mod-manager.lua | 2 +- scripts/gui/workflow.lua | 3 +-- scripts/modtools/create-item.lua | 2 +- scripts/pref-adjust.lua | 13 +++++++------ scripts/quicksave.lua | 2 +- scripts/remove-stress.lua | 2 +- scripts/show-unit-syndromes.rb | 1 - scripts/stripcaged.rb | 14 +++++++------- scripts/view-item-info.lua | 4 ++-- 15 files changed, 34 insertions(+), 38 deletions(-) diff --git a/scripts/exportlegends.lua b/scripts/exportlegends.lua index 42e70037b5..3c2999412b 100644 --- a/scripts/exportlegends.lua +++ b/scripts/exportlegends.lua @@ -7,8 +7,8 @@ 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 -:file:`region-date-legends_plus.xml` file developed to extend the World -Viewer utility and potentially compatible with others. +:file:`region-date-legends_plus.xml` file developed to extend +:forums:`World Viewer <128932>` and other legends utilities. Options: diff --git a/scripts/fix/fat-dwarves.lua b/scripts/fix/fat-dwarves.lua index 5c450513e9..09b5eb28e3 100644 --- a/scripts/fix/fat-dwarves.lua +++ b/scripts/fix/fat-dwarves.lua @@ -8,6 +8,8 @@ fix/fat-dwarves =============== Avoids 5-10% FPS loss due to constant recalculation of insulation for dwarves at maximum fatness, by reducing the cap from 1,000,000 to 999,999. +Recalculation is triggered in steps of 250 units, and very fat dwarves +constantly bounce off the maximum value while eating. =end]] local num_fat = 0 diff --git a/scripts/fix/stable-temp.lua b/scripts/fix/stable-temp.lua index a67bc7658f..7238d88d99 100644 --- a/scripts/fix/stable-temp.lua +++ b/scripts/fix/stable-temp.lua @@ -4,8 +4,8 @@ fix/stable-temp =============== Instantly sets the temperature of all free-lying items to be in equilibrium with -the environment and stops temperature updates. In order to maintain this efficient -state however, use `tweak` ``stable-temp`` and `tweak` ``fast-heat``. +the environment, which stops temperature updates until something changes. +To maintain this efficient state, use `tweak fast-heat `. =end]] local args = {...} @@ -59,6 +59,7 @@ end if apply then print('Items updated: '..count) else + print("Use 'fix/stable-temp apply' to force-change temperature.") print('Items not in equilibrium: '..count) end @@ -68,7 +69,3 @@ table.sort(tlist, function(a,b) return types[a] > types[b] end) for _,k in ipairs(tlist) do print(' '..df.item_type[k]..':', types[k]) end - -if not apply then - print("Use 'fix/stable-temp apply' to force-change temperature.") -end diff --git a/scripts/gui/advfort.lua b/scripts/gui/advfort.lua index 6a15750e8e..70d4bc083b 100644 --- a/scripts/gui/advfort.lua +++ b/scripts/gui/advfort.lua @@ -17,7 +17,7 @@ An example of player digging in adventure mode: .. image:: /docs/images/advfort.png -**WANRING:** changes only persist in non procedural sites, namely: player forts, caves, and camps. +**WARNING:** changes only persist in non procedural sites, namely: player forts, caves, and camps. =end]] diff --git a/scripts/gui/gm-editor.lua b/scripts/gui/gm-editor.lua index 6314c310c7..c2d371525a 100644 --- a/scripts/gui/gm-editor.lua +++ b/scripts/gui/gm-editor.lua @@ -4,10 +4,11 @@ gui/gm-editor ============= -There are three ways to open this editor: +This editor allows to change and modify almost anything in df. Press :kbd:`?` for +in-game help. There are three ways to open this editor: -* using gui/gm-editor command/keybinding - opens editor on what is selected - or viewed (e.g. unit/item description screen) +* Callling ``gui/gm-editor`` from a command or keybinding opens the editor + on whatever is selected or viewed (e.g. unit/item description screen) * using gui/gm-editor - executes lua command and opens editor on its results (e.g. ``gui/gm-editor "df.global.world.items.all"`` shows all items) @@ -17,9 +18,6 @@ There are three ways to open this editor: .. image:: /docs/images/gm-editor.png -This editor allows to change and modify almost anything in df. Press :kbd:`?` for -in-game help. - =end]] local gui = require 'gui' local dialog = require 'gui.dialogs' diff --git a/scripts/gui/liquids.lua b/scripts/gui/liquids.lua index 27c454f9eb..51ebca4bf0 100644 --- a/scripts/gui/liquids.lua +++ b/scripts/gui/liquids.lua @@ -15,7 +15,7 @@ allowing you to add or remove water & magma, and create obsidian walls & floors. There is **no undo support**. Bugs in this plugin have been known to create pathfinding problems and heat traps. -The :kbd:`b` key changes how the affected area is selected. The default *Rectangle* +The :kbd:`b` key changes how the affected area is selected. The default :guilabel:`Rectangle` mode works by selecting two corners like any ordinary designation. The :kbd:`p` key chooses between adding water, magma, obsidian walls & floors, or just tweaking flags. diff --git a/scripts/gui/mod-manager.lua b/scripts/gui/mod-manager.lua index 3ff46525ea..692deeb621 100644 --- a/scripts/gui/mod-manager.lua +++ b/scripts/gui/mod-manager.lua @@ -7,7 +7,7 @@ gui/mod-manager =============== A simple way to install and remove small mods. -It looks for specially formatted mods in df subfolder 'mods'. Mods are not +It looks for specially formatted mods in :file:`{}/mods/`. Mods are not included, but some examples are `available here`_. .. _`available here`: https://github.com/warmist/df-mini-mods diff --git a/scripts/gui/workflow.lua b/scripts/gui/workflow.lua index 67b7477fc8..6dda9e7648 100644 --- a/scripts/gui/workflow.lua +++ b/scripts/gui/workflow.lua @@ -41,8 +41,7 @@ suit your need, and set the item count range. .. image:: /docs/images/workflow-new2.png Pressing :kbd:`s` (or, with the example config, Alt-W in the :kbd:`z` stocks screen) -opens the overall status screen, which was copied from the C++ implementation -by falconne for better integration with the rest of the lua script: +opens the overall status screen: .. image:: /docs/images/workflow-status.png diff --git a/scripts/modtools/create-item.lua b/scripts/modtools/create-item.lua index 0f38eafa0b..92d8e25a7e 100644 --- a/scripts/modtools/create-item.lua +++ b/scripts/modtools/create-item.lua @@ -5,7 +5,7 @@ modtools/create-item ==================== -This is mostly the same as the other create item tools, but it uses standard +Replaces the `createitem` plugin, with standard arguments. The other versions will be phased out in a later version. =end]] diff --git a/scripts/pref-adjust.lua b/scripts/pref-adjust.lua index 4b4807e087..a43ee8712e 100644 --- a/scripts/pref-adjust.lua +++ b/scripts/pref-adjust.lua @@ -7,12 +7,13 @@ pref-adjust A two-stage script: ``pref-adjust clear`` removes preferences from all dwarves, and ``pref-adjust`` inserts an 'ideal' set which is easy to satisfy:: - Feb Idashzefon likes wild strawberries for their vivid red color, fisher berries - for their round shape, prickle berries for their precise thorns, plump helmets - for their rounded tops, prepared meals, plants, drinks, doors, thrones, tables and - beds. When possible, she prefers to consume wild strawberries, fisher berries, - prickle berries, plump helmets, strawberry wine, fisher berry wine, prickle berry - wine, and dwarven wine. + Feb Idashzefon likes wild strawberries for their vivid red color, + fisher berries for their round shape, prickle berries for their + precise thorns, plump helmets for their rounded tops, prepared meals, + plants, drinks, doors, thrones, tables and beds. When possible, she + prefers to consume wild strawberries, fisher berries, prickle + berries, plump helmets, strawberry wine, fisher berry wine, prickle + berry wine, and dwarven wine. =end]] diff --git a/scripts/quicksave.lua b/scripts/quicksave.lua index a5733c7c37..3f4cc3954a 100644 --- a/scripts/quicksave.lua +++ b/scripts/quicksave.lua @@ -3,7 +3,7 @@ quicksave ========= -If called in dwarf mode, makes DF immediately auto-save the game by setting a flag +If called in dwarf mode, makes DF immediately saves the game by setting a flag normally used in seasonal auto-save. =end]] diff --git a/scripts/remove-stress.lua b/scripts/remove-stress.lua index 56c8b14383..d384129fd8 100644 --- a/scripts/remove-stress.lua +++ b/scripts/remove-stress.lua @@ -6,7 +6,7 @@ remove-stress ============= Sets stress to -1,000,000; the normal range is 0 to 500,000 with very stable or very stressed dwarves taking on negative or greater values respectively. -Applies to the selected unit, or use "remove-stress -all" to apply to all units. +Applies to the selected unit, or use ``remove-stress -all`` to apply to all units. =end]] diff --git a/scripts/show-unit-syndromes.rb b/scripts/show-unit-syndromes.rb index 857ad84c01..70e72cba75 100644 --- a/scripts/show-unit-syndromes.rb +++ b/scripts/show-unit-syndromes.rb @@ -14,7 +14,6 @@ :showall: Show units even if not affected by any syndrome :showeffects: Show detailed effects of each syndrome :showdisplayeffects: Show effects that only change the look of the unit -:ignorehiddencurse: Hide syndromes the user should not be able to know about (TODO) :selected: Show selected unit :dwarves: Show dwarves :livestock: Show livestock diff --git a/scripts/stripcaged.rb b/scripts/stripcaged.rb index c3d2d3bb92..8cb1a0fa40 100644 --- a/scripts/stripcaged.rb +++ b/scripts/stripcaged.rb @@ -4,15 +4,15 @@ stripcaged ========== For dumping items inside cages. Will mark selected items for dumping, then -a dwarf may come and actually dump it. See also `autodump`. +a dwarf may come and actually dump them (or you can use `autodump`). -With the ``items`` argument, only dumps items laying in the cage, excluding -stuff worn by caged creatures. ``weapons`` will dump worn weapons, ``armor`` -will dump everything worn by caged creatures (including armor and clothing), -and ``all`` will dump everything, on a creature or not. +Arguments: -``stripcaged list`` will display on the dfhack console the list of all cages -and their item content. +:list: display the list of all cages and their item content on the console +:items: dump items in the cage, excluding stuff worn by caged creatures +:weapons: dump equipped weapons +:armor: dump everything worn by caged creatures (including armor and clothing) +:all: dump everything in the cage, on a creature or not Without further arguments, all commands work on all cages and animal traps on the map. With the ``here`` argument, considers only the in-game selected cage diff --git a/scripts/view-item-info.lua b/scripts/view-item-info.lua index 4729c8d3ce..be8e14b9e2 100644 --- a/scripts/view-item-info.lua +++ b/scripts/view-item-info.lua @@ -10,9 +10,9 @@ A script to extend the item or unit viewscreen with additional information including a custom description of each item (when available), and properties such as material statistics, weapon attacks, armor effectiveness, and more. -The associated script ``item-descriptions.lua`` supplies custom descriptions +The associated script `item-descriptions`.lua supplies custom descriptions of items. Individual descriptions can be added or overridden by a similar -script ``raw/scripts/more-item-descriptions.lua``. Both work as sparse lists, +script :file:`raw/scripts/more-item-descriptions.lua`. Both work as sparse lists, so missing items simply go undescribed if not defined in the fallback. =end]] From a8ab595428fc9e31e4432010507fe37442460f5e Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Thu, 29 Oct 2015 12:46:31 +1100 Subject: [PATCH 26/91] Tweak plugins docs - Minor updates and clarifying edits - Better use of markup throughout the document - linked references to bugs and other things - moved gui/siege-engine docs to the script --- docs/Plugins.rst | 297 +++++++++++++++-------------------- scripts/gui/siege-engine.lua | 31 ++++ 2 files changed, 155 insertions(+), 173 deletions(-) diff --git a/docs/Plugins.rst b/docs/Plugins.rst index f00ceee9e2..3f491f1546 100644 --- a/docs/Plugins.rst +++ b/docs/Plugins.rst @@ -11,45 +11,44 @@ Most are listed here, hopefully organised in a way you will find useful. .. contents:: :depth: 4 -=================== -Informative Plugins -=================== - -Visualizer and data export -========================== +=========================== +Visualizers and data export +=========================== .. _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). Invoked with ``stonesense``, or alias ``ssense``. +down DF). Usage: -For detailed information, see the `stonesense readme`_, the `wiki page`_, -or the `Bay12 forum thread`_. +:stonesense: Open the visualiser in a new window. Alias ``ssense``. +:ssense overlay: Overlay DF window, replacing the map area. + ``PRINT_MODE:2D`` strongly recommended for stability. -.. _`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 +Stonesense can be configured by editing the :file:`stonesense/init.txt` +and :file:`stonesense/keybinds.txt` files. Additional content, such as sprites +for modded creatures, is available from the content repository on the wiki. + +For detailed information, see the `stonesense readme`_, the :wiki:`wiki page +`, or the :forums:`Bay12 forums thread <106497>`. -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. +.. _`stonesense readme`: https://github.com/DFHack/stonesense/blob/master/README.md mapexport ---------- +========= Export the current loaded map as a file. This was used by visualizers for DF 0.34.11, but is now basically obsolete. dwarfexport ------------ +=========== Export dwarves to RuneSmith-compatible XML; also unused by modern tools. .. _blueprint: blueprint ---------- +========= Exports a portion of your fortress into QuickFort style blueprint files.:: blueprint [dig] [build] [place] [query] @@ -70,13 +69,15 @@ Goes very well with `fortplan`, for re-importing. remotefortressreader ==================== An in-development plugin for realtime fortress visualisation. +See :forums:`Armok Vision <146473>`. +============== Map inspection ============== cursecheck ----------- +========== Checks a single map tile or the whole map/world for cursed creatures (ghosts, vampires, necromancers, werebeasts, zombies). @@ -111,27 +112,26 @@ Examples: .. note:: - If you do a full search (with the option "all") former ghosts will show up - with the cursetype "unknown" because their ghostly flag is not set - anymore. But if you happen to find a living/active creature with cursetype - "unknown" please report that in the dfhack thread on the modding forum or - per irc. This is likely to happen with mods which introduce new types - of curses, for example. + If you do a full search (with the option "all") former ghosts will show up + with the cursetype "unknown" because their ghostly flag is not set. + + Please report any living/active creatures with cursetype "unknown" - + this is most likely with mods which introduce new types of curses. flows ------ +===== A tool for checking how many tiles contain flowing liquids. If you suspect that your magma sea leaks into HFS, you can use this tool to be sure without revealing the map. probe ------ +===== Can be used to determine tile properties like temperature. .. _prospect: prospect --------- +======== Prints a big list of all the present minerals and plants. By default, only the visible part of the map is scanned. @@ -157,9 +157,13 @@ Options: :all: Also estimate vein mineral amounts. .. _reveal: +.. _unreveal: +.. _revtoggle: +.. _revflood: +.. _revforget: reveal ------- +====== This reveals the map. By default, HFS will remain hidden so that the demons don't spawn. You can use ``reveal hell`` to reveal everything. With hell revealed, you won't be able to unpause until you hide the map again. If you really want @@ -168,28 +172,21 @@ to unpause with hell revealed, use ``reveal demons``. Reveal also works in adventure mode, but any of its effects are negated once you move. When you use it this way, you don't need to run ``unreveal``. -unreveal -~~~~~~~~ -Reverts the effects of ``reveal``. - -revtoggle -~~~~~~~~~ -Switches between ``reveal`` and ``unreveal``. - -revflood -~~~~~~~~ -This command will hide the whole map and then reveal all the tiles that have -a path to the in-game cursor. +Usage and related commands: -revforget -~~~~~~~~~ -When you use reveal, it saves information about what was/wasn't visible before -revealing everything. Unreveal uses this information to hide things again. -This command throws away the information. For example, use in cases where -you abandoned with the fort revealed and no longer want the data. +:reveal: Reveal the whole map, except for HFS to avoid demons spawning +:reveal hell: Also show hell, but requires ``unreveal`` before unpausing +:reveal demons: Reveals everything and allows unpausing - good luck! +:unreveal: Reverts the effects of ``reveal`` +:revtoggle: Switches between ``reveal`` and ``unreveal`` +:revflood: Hide everything, then reveal tiles with a path to the cursor + (useful to make walled-off rooms vanish) +:revforget: Discard info about what was visible before revealing the map. + Only useful where (eg) you abandoned with the fort revealed + and no longer want the data. showmood --------- +======== Shows all items needed for the currently active strange mood. @@ -199,28 +196,26 @@ Bugfixes drybuckets ========== -This utility removes water from all buckets in your fortress, allowing them to be safely used for making lye. +Removes water from all buckets in your fortress, allowing them to be used for making lye. 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 you to -violate them and start wars. +Adds a Diplomat position to all Elven civilizations, allowing them to negotiate +tree cutting quotas - and you to violate them and start wars. +This was vanilla behaviour until ``0.31.12``, in which the "bug" was "fixed". fixmerchants ============ -This command adds the Guild Representative position to all Human civilizations, -allowing them to make trade agreements (just as they did back in 0.28.181.40d -and earlier) in case you haven't already modified your raws accordingly. +Adds the Guild Representative position to all Human civilizations, +allowing them to make trade agreements. This was the default behaviour in +``0.28.181.40d`` and earlier. .. _fix-unit-occupancy: fix-unit-occupancy ================== This plugin fixes issues with unit occupancy, notably issues with phantom -"unit blocking tile" messages (`Bug 3499`_). It can be run manually, or +"unit blocking tile" messages (:bug:`3499`). It can be run manually, or periodically when enabled with the built-in enable/disable commands: :(no argument): Run the plugin once immediately, for the whole map. @@ -230,21 +225,19 @@ periodically when enabled with the built-in enable/disable commands: The default is 1200 ticks, or 1 day. Ticks are only counted when the game is unpaused. -.. _`Bug 3499`: http://bay12games.com/dwarves/mantisbt/view.php?id=3499 - fixveins ======== Removes invalid references to mineral inclusions and restores missing ones. -Use this if you broke your embark with tools like tiletypes, or if you +Use this if you broke your embark with tools like `tiletypes`, or if you accidentally placed a construction on top of a valuable mineral floor. petcapRemover ============= -This plugin allows you to remove or raise the pet population cap. In vanilla +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 +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 @@ -297,12 +290,12 @@ One-shot subcommands: Subcommands that persist until disabled or DF quits: :adamantine-cloth-wear: Prevents adamantine clothing from wearing out while being worn (bug 6481). -:advmode-contained: Works around bug 6202, i.e. custom reactions with container inputs +:advmode-contained: Works around :bug:`6202`, custom reactions with container inputs in advmode. The issue is that the screen tries to force you to select the contents separately from the container. This forcefully skips child reagents. :civ-view-agreement: Fixes overlapping text on the "view agreement" screen -:craft-age-wear: Fixes the behavior of crafted items wearing out over time (bug 6003). +:craft-age-wear: Fixes the behavior of crafted items wearing out over time (:bug:`6003`). With this tweak, items made from cloth and leather will gain a level of wear every 20 years. :embark-profile-name: Allows the use of lowercase letters when saving embark profiles @@ -318,9 +311,9 @@ Subcommands that persist until disabled or DF quits: :import-priority-category: Allows changing the priority of all goods in a category when discussing an import agreement with the liaison -:kitchen-keys: Fixes DF kitchen meal keybindings (bug 614) +:kitchen-keys: Fixes DF kitchen meal keybindings (:bug:`614`) :kitchen-prefs-color: Changes color of enabled items to green in kitchen preferences -:kitchen-prefs-empty: Fixes a layout issue with empty kitchen tabs (bug 9000) +:kitchen-prefs-empty: Fixes a layout issue with empty kitchen tabs (:bug:`9000`) :manager-quantity: Removes the limit of 30 jobs per manager order :max-wheelbarrow: Allows assigning more than 3 wheelbarrows to a stockpile :military-color-assigned: @@ -334,7 +327,7 @@ Subcommands that persist until disabled or DF quits: i.e. stop the rightmost list of the Positions page of the military screen from constantly resetting to the top. :nestbox-color: Fixes the color of built nestboxes -:shift-8-scroll: Gives Shift-8 (or ``*``) priority when scrolling menus, instead of scrolling the map +:shift-8-scroll: Gives Shift-8 (or :kbd:`*`) priority when scrolling menus, instead of scrolling the map :stable-cursor: Saves the exact cursor position between t/q/k/d/b/etc menus of fortress mode. :tradereq-pet-gender: Displays pet genders on the trade request screen @@ -353,7 +346,7 @@ UI Upgrades .. note:: In order to avoid user confusion, as a matter of policy all these tools - display the word "DFHack" on the screen somewhere while active. + display the word :guilabel:`DFHack` on the screen somewhere while active. When that is not appropriate because they merely add keybinding hints to existing DF screens, they deliberately use red instead of green for the key. @@ -465,14 +458,10 @@ Game interface embark-tools ------------ -A collection of embark-related tools. - -Usage:: +A collection of embark-related tools. Usage and available tools:: embark-tools enable/disable tool [tool]... -Tools: - :anywhere: Allows embarking anywhere (including sites, mountain-only biomes, and oceans). Use with caution. :mouse: Implements mouse controls (currently in the local embark region only) @@ -537,11 +526,11 @@ Implements several confirmation dialogs for potentially destructive actions Usage: -:enable confirm, confirm enable all: - Enable all confirmations (replace with ``disable`` to disable) +:enable confirm: Enable all confirmations; alias ``confirm enable all`. + Replace with ``disable`` to disable. +:confirm help: List available confirmation dialogues. :confirm enable option1 [option2...]: - Enable (or disable) specific confirmations. Run ``confirm help`` - for a complete list of options. + Enable (or disable) specific confirmation dialogues. follow ------ @@ -737,33 +726,16 @@ dig --- This plugin makes many automated or complicated dig patterns easy. -digv -~~~~ -Designates a whole vein for digging. Requires an active in-game cursor placed -over a vein tile. With the 'x' option, it will traverse z-levels (putting stairs -between the same-material tiles). - -digvx -~~~~~ -A permanent alias for 'digv x'. +Basic commands: -digl -~~~~ -Designates layer stone for digging. Requires an active in-game cursor placed -over a layer stone tile. With the 'x' option, it will traverse z-levels -(putting stairs between the same-material tiles). With the 'undo' option it -will remove the dig designation instead (if you realize that digging out a 50 -z-level deep layer was not such a good idea after all). - -diglx -~~~~~ -A permanent alias for 'digl x'. +:digv: Designate all of the selected vein for digging. +:digvx: Also cross z-levels, diggning stairs as needed. Alias for ``digv x``. +:digl: Like ``digv [x]``, for layer stone. Also supports an ``undo`` + option to remove designations, for if you accidentally set 50 levels at once. digexp ~~~~~~ -This command is for `exploratory mining`_. - -.. _`exploratory mining`: http://dwarffortresswiki.org/index.php/cv:Exploratory_mining +This command is for :wiki:`exploratory mining `. There are two variables that can be set: pattern and filter. @@ -782,7 +754,7 @@ Filters: :hidden: designate only hidden tiles of z-level (default) :designated: Take current designation and apply pattern to it. -After you have a pattern set, you can use 'expdig' to apply it again. +After you have a pattern set, you can use ``expdig`` to apply it again. Examples: @@ -831,8 +803,13 @@ Examples: 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. -If an argument is given, the designation of the selected tile is ignored, and all appropriate tiles are set to the specified designation. +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. +If an argument is given, the designation of the selected tile is +ignored, and all appropriate tiles are set to the specified +designation. Options: @@ -1215,7 +1192,7 @@ Make sure there are always 80-100 units of dimple dye:: .. note:: In order for this to work, you have to set the material of the PLANT input - on the Mill Plants job to MUSHROOM_CUP_DIMPLE using the 'job item-material' + on the Mill Plants job to MUSHROOM_CUP_DIMPLE using the `job` ``item-material`` command. Otherwise the plugin won't be able to deduce the output material. Maintain 10-100 locally-made crafts of exceptional quality:: @@ -1271,7 +1248,7 @@ Options: autodump-destroy-item ~~~~~~~~~~~~~~~~~~~~~ -Destroy the selected item. The item may be selected in the ``k`` list, or inside +Destroy the selected item. The item may be selected in the :kbd:`k` list, or inside a container. If called again before the game is resumed, cancels destroy. cleanowned @@ -1316,7 +1293,7 @@ Options: Widget configuration: -The following types of widgets (defined in ``hack/lua/plugins/dwarfmonitor.lua``) +The following types of widgets (defined in :file:`hack/lua/plugins/dwarfmonitor.lua`) can be displayed on the main fortress mode screen: :date: Show the in-game date @@ -1324,7 +1301,7 @@ can be displayed on the main fortress mode screen: :weather: Show current weather (rain/snow) :cursor: Show the current mouse cursor position -The file ``dfhack-config/dwarfmonitor.json`` can be edited to control the +The file :file:`dfhack-config/dwarfmonitor.json` can be edited to control the positions and settings of all widgets displayed. This file should contain a JSON object with the key ``widgets`` containing an array of objects - see the included file in the ``dfhack-config`` folder for an example:: @@ -1362,7 +1339,7 @@ Some widgets support additional options: * ``D``: The current day, zero-padded if necessary * ``d``: The current day, *not* zero-padded - The default date format is ``Y-M-D``. + The default date format is ``Y-M-D``, per the ISO8601 standard. * ``cursor`` widget: @@ -1728,9 +1705,7 @@ 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. -.. warning:: - - There is no undo option other than restoring from backup. +The only undo option is to restore your save from backup. changelayer =========== @@ -1876,9 +1851,9 @@ Options: fortplan ======== -Usage: fortplan [filename] +Usage: ``fortplan [filename]`` -Designates furniture for building according to a .csv file with +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:: @@ -1904,7 +1879,7 @@ This section of a file would designate for construction a door and some furniture inside a bedroom: specifically, clockwise from top left, a cabinet, a table, a chair, a bed, and a statue. -All of the building designation uses Planning Mode, so you do not need to +All of the building designation uses `Planning Mode `, so you do not need to have the items available to construct all the buildings when you run fortplan with the .csv file. @@ -1920,12 +1895,9 @@ Usage: ``infiniteSky enable/disable`` Enables/disables monitoring of constructions. If you build anything in the second to highest z-level, it will allocate one more sky level. This is so you can continue to build stairs upward. - .. warning:: - - Bugs have been reported with this version of the plugin, so be careful. - It is possible that new z-levels will suddenly disappear and possibly - cause cave-ins. Saving and loading after creating new z-levels should - fix the problem. +`Sometimes `_ +new z-levels disappear and cause cave-ins. +Saving and loading after creating new z-levels should fix the problem. .. _liquids: @@ -1940,13 +1912,13 @@ See also `this issue. `_ .. note:: - Spawning and deleting liquids can F up pathing data and + Spawning and deleting liquids can mess up pathing data and temperatures (creating heat traps). You've been warned. -Settings will be remembered until you quit DF. You can call liquids-here to execute +Settings will be remembered until you quit DF. You can call `liquids-here` to execute the last configured action, which is useful in combination with keybindings. -Usage: point the DF cursor at a tile you want to modify and use the commands available :) +Usage: point the DF cursor at a tile you want to modify and use the commands Commands -------- @@ -1990,6 +1962,8 @@ Brush size and shape: :column: Column from cursor, up through free space :flood: Flood-fill water tiles from cursor (only makes sense with wclean) +.. _liquids-here: + liquids-here ------------ Run the liquid spawner with the current/last settings made in liquids (if no @@ -1997,10 +1971,12 @@ 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: + tiletypes ========= Can be used for painting map tiles and is an interactive command, much like -liquids. +`liquids`. The tool works with two set of options and a brush. The brush determines which tiles will be processed. First set of options is the filter, which can exclude @@ -2064,10 +2040,10 @@ Any paint or filter option (or the entire paint or filter) can be disabled entir You can use several different brushes for painting tiles: -* Point. (point) -* Rectangular range. (range) -* A column ranging from current cursor to the first solid tile above. (column) -* DF map block - 16x16 tiles, in a regular grid. (block) +:point: a single tile +:range: a rectangular range +:column: a column ranging from current cursor to the first solid tile above +:block: a DF map block - 16x16 tiles, in a regular grid Example:: @@ -2147,8 +2123,12 @@ catsplosion Makes cats just *multiply*. It is not a good idea to run this more than once or twice. +.. _createitem: + createitem ========== +Use `modtools/create-item` - this plugin is deprecated and will be removed soon. + Allows creating new items of arbitrary types and made of arbitrary materials. By default, items created are spawned at the feet of the selected unit. @@ -2156,7 +2136,8 @@ Specify the item and material information as you would indicate them in custom r * Separate the item and material with a space rather than a colon * If the item has no subtype, omit the :NONE -* If the item is REMAINS, FISH, FISH_RAW, VERMIN, PET, or EGG, specify a CREATURE:CASTE pair instead of a material token. +* If the item is REMAINS, FISH, FISH_RAW, VERMIN, PET, or EGG, + specify a CREATURE:CASTE pair instead of a material token. Corpses, body parts, and prepared meals cannot be created using this tool. @@ -2284,7 +2265,7 @@ objects to add features not otherwise present. .. _siege-engine: -Siege Engine +siege-engine ------------ 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 @@ -2296,37 +2277,11 @@ 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 just stones. -Configuration UI -~~~~~~~~~~~~~~~~ The configuration front-end to the plugin is implemented by `gui/siege-engine`. -Bind it to a key (the example config uses :kbd:`Alt`:kbd:`a`) and activate after selecting -a siege engine in :kbd:`q` mode. - -.. image:: images/siege-engine.png - -The main mode displays the current target, selected ammo item type, linked stockpiles and -the allowed operator skill range. The map tile color is changed to signify if it can be -hit by the selected engine: green for fully reachable, blue for out of range, red for blocked, -yellow for partially blocked. - -Pressing :kbd:`r` changes into the target selection mode, which works by highlighting two points -with :kbd:`Enter` like all designations. When a target area is set, the engine projectiles are -aimed at that area, or units within it (this doesn't actually change the original aiming -code, instead the projectile trajectory parameters are rewritten as soon as it appears). - -After setting the target in this way for one engine, you can 'paste' the same area into others -just by pressing :kbd:`p` in the main page of this script. The area to paste is kept until you quit -DF, or select another area manually. - -Pressing :kbd:`t` switches to a mode for selecting a stockpile to take ammo from. - -Exiting from the siege engine script via ESC reverts the view to the state prior to starting -the script. :kbd:`Shift`:kbd:`Esc` retains the current viewport, and also exits from the :kbd:`q` mode to main -menu. .. _power-meter: -Power Meter +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. @@ -2363,24 +2318,20 @@ 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. -.. admonition:: ISSUE - - Since this building is a machine, and machine collapse - code cannot be hooked, it would collapse over true open space. - As a loophole, down stair provides support to machines, while - being passable, so use them. +Since this building is a machine, and machine collapse +code cannot be hooked, it would collapse over true open space. +As a loophole, down stairs provide support to machines, while +being passable, so use them. After constructing the building itself, machines can be connected to the edge tiles that look like gear boxes. Their exact position is extracted from the workshop raws. -.. admonition:: ISSUE - - Like with collapse above, part of the code involved in - machine connection cannot be hooked. As a result, the workshop - can only immediately connect to machine components built AFTER it. - This also means that engines cannot be chained without intermediate - short axles that can be built later than both of the engines. +Like with collapse above, part of the code involved in +machine connection cannot be hooked. As a result, the workshop +can only immediately connect to machine components built AFTER it. +This also means that engines cannot be chained without intermediate +axles built after both engines. Operation ~~~~~~~~~ @@ -2448,6 +2399,6 @@ the `clean` ``items`` command. The plugin is intended to give some use to all those poisons that can be bought from caravans. :) -To be really useful this needs patches from bug 808, `tweak` +To be really useful this needs patches for :bug:`808`, ie `tweak` ``fix-dimensions`` and `tweak` ``advmode-contained``. diff --git a/scripts/gui/siege-engine.lua b/scripts/gui/siege-engine.lua index a880404706..8ebfe0dc49 100644 --- a/scripts/gui/siege-engine.lua +++ b/scripts/gui/siege-engine.lua @@ -5,6 +5,37 @@ gui/siege-engine ================ An in-game interface for `siege-engine`. +Bind it to a key (the example config uses :kbd:`Alt`:kbd:`a`) and +activate after selecting a siege engine in :kbd:`q` mode. + +.. image:: /docs/images/siege-engine.png + +The main mode displays the current target, selected ammo item +type, linked stockpiles and the allowed operator skill range. The +map tile color is changed to signify if it can be hit by the +selected engine: green for fully reachable, blue for out of +range, red for blocked, yellow for partially blocked. + +Pressing :kbd:`r` changes into the target selection mode, which +works by highlighting two points with :kbd:`Enter` like all +designations. When a target area is set, the engine projectiles +are aimed at that area, or units within it (this doesn't actually +change the original aiming code, instead the projectile +trajectory parameters are rewritten as soon as it appears). + +After setting the target in this way for one engine, you can +'paste' the same area into others just by pressing :kbd:`p` in +the main page of this script. The area to paste is kept until you +quit DF, or select another area manually. + +Pressing :kbd:`t` switches to a mode for selecting a stockpile to +take ammo from. + +Exiting from the siege engine script via :kbd:`Esc` reverts the +view to the state prior to starting the script. +:kbd:`Shift`:kbd:`Esc` retains the current viewport, and also +exits from the :kbd:`q` mode to main menu. + =end]] local utils = require 'utils' local gui = require 'gui' From 5643119c71814fe66526731580da3d7e05e347f7 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Thu, 29 Oct 2015 14:26:37 +1100 Subject: [PATCH 27/91] Get docs building online Readthedocs runs the build command in the directory conf.py is found, and to work correctly that has to be the root directory. --- docs/conf.py => conf.py | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) rename docs/conf.py => conf.py (97%) diff --git a/docs/conf.py b/conf.py similarity index 97% rename from docs/conf.py rename to conf.py index 546f843c81..1827d48834 100644 --- a/docs/conf.py +++ b/conf.py @@ -23,7 +23,7 @@ def doc_dir(dirname, files): """Yield (command, includepath) for each script in the directory.""" - sdir = os.path.relpath(dirname, '..').replace('\\', '/').replace('../', '') + sdir = os.path.relpath(dirname, '.').replace('\\', '/').replace('../', '') for f in files: if f[-3:] not in {'lua', '.rb'}: continue @@ -48,7 +48,7 @@ def document_scripts(): """ # First, we collect the commands and paths to include in our docs scripts = [] - for root, _, files in os.walk('../scripts'): + for root, _, files in os.walk('scripts'): scripts.extend(doc_dir(root, files)) # Next we split by type and create include directives sorted by command kinds = {'base': [], 'devel': [], 'fix': [], 'gui': [], 'modtools': []} @@ -66,8 +66,8 @@ def document_scripts(): kinds[key] = [template.format(x[0], x[1]) for x in sorted(value, key=lambda x: x[0])] # Finally, we write our _auto/* files for each kind of script - if not os.path.isdir('_auto'): - os.mkdir('_auto') + if not os.path.isdir('docs/_auto'): + os.mkdir('docs/_auto') head = { 'base': 'Basic Scripts', 'devel': 'Development Scripts', @@ -80,7 +80,7 @@ def document_scripts(): '.. contents::\n\n').format( k=k, t=head[k], l=len(head[k])*'#', a=('' if k=='base' else k+'/')) mode = 'w' if sys.version_info.major > 2 else 'wb' - with open('_auto/{}.rst'.format(k), mode) as outfile: + with open('docs/_auto/{}.rst'.format(k), mode) as outfile: outfile.write(title) outfile.write('\n\n'.join(kinds[k])) @@ -231,12 +231,12 @@ def get_version(): # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. -html_favicon = 'styles/dfhack-icon.ico' +html_favicon = 'docs/styles/dfhack-icon.ico' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['styles'] +html_static_path = ['docs/styles'] # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied From 4257940b224bffa623013a7657aa7dc370a4a4c5 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Fri, 30 Oct 2015 14:47:49 +1100 Subject: [PATCH 28/91] fix typo in dig docs --- docs/Plugins.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/Plugins.rst b/docs/Plugins.rst index 3f491f1546..8423672833 100644 --- a/docs/Plugins.rst +++ b/docs/Plugins.rst @@ -729,9 +729,10 @@ This plugin makes many automated or complicated dig patterns easy. Basic commands: :digv: Designate all of the selected vein for digging. -:digvx: Also cross z-levels, diggning stairs as needed. Alias for ``digv x``. -:digl: Like ``digv [x]``, for layer stone. Also supports an ``undo`` - option to remove designations, for if you accidentally set 50 levels at once. +:digvx: Also cross z-levels, digging stairs as needed. Alias for ``digv x``. +:digl: Like ``digv``, for layer stone. Also supports an ``undo`` option + to remove designations, for if you accidentally set 50 levels at once. +:diglx: Also cross z-levels, digging stairs as needed. Alias for ``digl x``. digexp ~~~~~~ From f080e42c228bf49cd11ff7ec28b296765ec8a8cf Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Sat, 31 Oct 2015 11:47:13 +1100 Subject: [PATCH 29/91] Add pull #717 changes to NEWS Since it didn't happen there due to merge issues. --- NEWS.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/NEWS.rst b/NEWS.rst index 17f337c7a0..e966eda6ac 100644 --- a/NEWS.rst +++ b/NEWS.rst @@ -65,6 +65,9 @@ New plugins New scripts ----------- - `burial`: sets all unowned coffins to allow burial ("-pets" to allow pets too) +- `deteriorateclothes`: make worn clothes on the ground wear far faster to boost FPS +- `deterioratecorpses`: make body parts wear away far faster to boost FPS +- `deterioratefood`: make food vanish after a few months if not used - `fix-ster`: changes fertility/sterility of animals or dwarves - `view-item-info`: adds information and customisable descriptions to item viewscreens - `warn-starving`: check for starving, thirsty, or very drowsy units and pause with warning if any are found @@ -78,6 +81,7 @@ New scripts - `make-legendary`: modify skill(s) of a single unit - `pref-adjust`: Adjust all preferences of all dwarves in play - `rejuvenate`: make any "old" dwarf 20 years old +- `starvingdead`: make undead weaken after one month on the map, and crumble after six New tweaks ---------- From 9b1d277ef57d682a5037fcc1fe1197e61ac71af1 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Sat, 31 Oct 2015 15:39:00 +1100 Subject: [PATCH 30/91] Finish updating sphinx-build changes Completes 5643119. --- CMakeLists.txt | 1 - docs/Contributing.rst | 2 +- 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 715744239c..0ac262dd58 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -221,7 +221,6 @@ if (BUILD_DOCS) add_custom_command(OUTPUT ${SPHINX_OUTPUT} COMMAND ${SPHINX_EXECUTABLE} -a -E -q -b html - -c "${CMAKE_CURRENT_SOURCE_DIR}/docs" "${CMAKE_CURRENT_SOURCE_DIR}" "${CMAKE_CURRENT_SOURCE_DIR}/docs/html" -w "${CMAKE_CURRENT_SOURCE_DIR}/docs/_sphinx-warnings.txt" diff --git a/docs/Contributing.rst b/docs/Contributing.rst index 343c2de7d2..5691fbcc0b 100644 --- a/docs/Contributing.rst +++ b/docs/Contributing.rst @@ -121,7 +121,7 @@ Documentation Standards DFHack documentation is built with Sphinx, and configured automatically through CMake. If you want to build the docs *only*, use this command:: - sphinx-build -a -c docs . docs/html + sphinx-build . docs/html Whether you're adding new code or just fixing old documentation (and there's plenty), there are a few important standards for completeness and consistent style. Treat From 28940b9b8a786dde4a1c90557ef420a62ecbde20 Mon Sep 17 00:00:00 2001 From: lethosor Date: Sun, 1 Nov 2015 17:25:33 -0500 Subject: [PATCH 31/91] Temporarily disable 3rdparty/roses See #712 --- scripts/CMakeLists.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/CMakeLists.txt b/scripts/CMakeLists.txt index 82edb19a9c..e9d8999707 100644 --- a/scripts/CMakeLists.txt +++ b/scripts/CMakeLists.txt @@ -4,7 +4,7 @@ DFHACK_3RDPARTY_SCRIPT_REPO(kane-t) DFHACK_3RDPARTY_SCRIPT_REPO(lethosor) DFHACK_3RDPARTY_SCRIPT_REPO(maienm) DFHACK_3RDPARTY_SCRIPT_REPO(maxthyme) -DFHACK_3RDPARTY_SCRIPT_REPO(roses) +# DFHACK_3RDPARTY_SCRIPT_REPO(roses) install(DIRECTORY ${dfhack_SOURCE_DIR}/scripts DESTINATION ${DFHACK_DATA_DESTINATION} From 6df0e26b05c5a526d39629e54e530f6a9e497fb6 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Mon, 2 Nov 2015 09:32:50 +1100 Subject: [PATCH 32/91] Require 3rdparty docs to be in script source files --- conf.py | 2 +- docs/Scripts.rst | 16 ---------------- 2 files changed, 1 insertion(+), 17 deletions(-) diff --git a/conf.py b/conf.py index 1827d48834..81cfb78eff 100644 --- a/conf.py +++ b/conf.py @@ -173,7 +173,7 @@ def get_version(): # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ['docs/_build/*', 'depends/*'] +exclude_patterns = ['docs/_build/*', 'depends/*', 'scripts/3rdparty/*'] # The reST default role (used for this markup: `text`) to use for all # documents. diff --git a/docs/Scripts.rst b/docs/Scripts.rst index 13b6ba4c13..87eeaf666e 100644 --- a/docs/Scripts.rst +++ b/docs/Scripts.rst @@ -25,19 +25,3 @@ The following pages document all the standard DFHack scripts. /docs/_auto/fix /docs/_auto/gui /docs/_auto/modtools - - -.. warning:: - - The following documentation is pulled in from external ``README`` files. - - - it may not match the DFHack docs style - - some scripts have incorrect names, or are documented but unavailable - - some scripts have entries here and are also included above - -.. toctree:: - :glob: - :maxdepth: 2 - - /scripts/3rdparty/*/README - From 092979f3624d9029c14d77688a85746aa1a245ad Mon Sep 17 00:00:00 2001 From: DoctorVanGogh Date: Mon, 2 Nov 2015 02:51:52 +0100 Subject: [PATCH 33/91] Prevent building floor on top of constructed floor (mostly) --- plugins/automaterial.cpp | 23 ++++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/plugins/automaterial.cpp b/plugins/automaterial.cpp index 56b94483b5..508831b777 100644 --- a/plugins/automaterial.cpp +++ b/plugins/automaterial.cpp @@ -32,6 +32,7 @@ #include "modules/Constructions.h" #include "modules/Buildings.h" #include "modules/Maps.h" +#include "modules/MapCache.h" #include "TileTypes.h" #include "df/job_item.h" @@ -459,20 +460,28 @@ static bool is_valid_building_site(building_site &site, bool orthogonal_check, b return false; if (material == tiletype_material::CONSTRUCTION) - { - // Can build on top of a wall, but not on a constructed floor + { + // Check this is not a 'constructed floor over X': + // those have something else than open space as *basic* tile types: stonefloor, smoothstonefloor, ... + MapExtras::MapCache mc; + auto btt = mc.baseTiletypeAt(site.pos); + auto bshape = tileShape(btt); + if (bshape != tiletype_shape_basic::Open) + return false; + + // Can build on top of a wall, but not on a constructed floor df::coord pos_below = site.pos; pos_below.z--; if (!Maps::isValidTilePos(pos_below)) return false; - auto ttype = Maps::getTileType(pos_below); - if (!ttype) + auto ttype_below = Maps::getTileType(pos_below); + if (!ttype_below) return false; - auto shape = tileShape(*ttype); - auto shapeBasic = tileShapeBasic(shape); - if (tileShapeBasic(shape) != tiletype_shape_basic::Wall) + auto shape_below = tileShape(*ttype_below); + auto shapeBasic_below = tileShapeBasic(shape_below); + if (tileShapeBasic(shape_below) != tiletype_shape_basic::Wall) return false; } From a7fe1d9d731d23f7d57c9c9068748c3f66c6b545 Mon Sep 17 00:00:00 2001 From: DoctorVanGogh Date: Mon, 2 Nov 2015 05:05:17 +0100 Subject: [PATCH 34/91] Formatting --- plugins/automaterial.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/automaterial.cpp b/plugins/automaterial.cpp index 508831b777..01b275eaf7 100644 --- a/plugins/automaterial.cpp +++ b/plugins/automaterial.cpp @@ -460,7 +460,7 @@ static bool is_valid_building_site(building_site &site, bool orthogonal_check, b return false; if (material == tiletype_material::CONSTRUCTION) - { + { // Check this is not a 'constructed floor over X': // those have something else than open space as *basic* tile types: stonefloor, smoothstonefloor, ... MapExtras::MapCache mc; From d692458038b75564434a6fc32d80b2a4e1f1b8c6 Mon Sep 17 00:00:00 2001 From: DoctorVanGogh Date: Tue, 3 Nov 2015 10:07:27 +0100 Subject: [PATCH 35/91] Formatting --- plugins/automaterial.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/automaterial.cpp b/plugins/automaterial.cpp index 01b275eaf7..cc38dc7630 100644 --- a/plugins/automaterial.cpp +++ b/plugins/automaterial.cpp @@ -469,7 +469,7 @@ static bool is_valid_building_site(building_site &site, bool orthogonal_check, b if (bshape != tiletype_shape_basic::Open) return false; - // Can build on top of a wall, but not on a constructed floor + // Can build on top of a wall, but not on a constructed floor df::coord pos_below = site.pos; pos_below.z--; if (!Maps::isValidTilePos(pos_below)) From a503e54484b73ce9d8a7dc68a3a6e2b627a731c4 Mon Sep 17 00:00:00 2001 From: Warmist Date: Tue, 3 Nov 2015 17:59:24 +0200 Subject: [PATCH 36/91] Add furnaces to sidebar fill event --- plugins/eventful.cpp | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/plugins/eventful.cpp b/plugins/eventful.cpp index 3a8b6da7ad..4c168ab89f 100644 --- a/plugins/eventful.cpp +++ b/plugins/eventful.cpp @@ -287,6 +287,22 @@ struct workshop_hook : df::building_workshopst{ } }; IMPLEMENT_VMETHOD_INTERPOSE(workshop_hook, fillSidebarMenu); + +struct furnace_hook : df::building_furnacest{ + typedef df::building_furnacest interpose_base; + DEFINE_VMETHOD_INTERPOSE(void,fillSidebarMenu,()) + { + CoreSuspendClaimer suspend; + color_ostream_proxy out(Core::getInstance().getConsole()); + bool call_native=true; + onWorkshopFillSidebarMenu(out,this,&call_native); + if(call_native) + INTERPOSE_NEXT(fillSidebarMenu)(); + postWorkshopFillSidebarMenu(out,this); + } +}; +IMPLEMENT_VMETHOD_INTERPOSE(furnace_hook, fillSidebarMenu); + struct product_hook : item_product { typedef item_product interpose_base; From 0fa35aef3cf3b44196542fe2ca466dd6cabe6f04 Mon Sep 17 00:00:00 2001 From: Warmist Date: Tue, 3 Nov 2015 18:01:41 +0200 Subject: [PATCH 37/91] Update eventful.cpp Fix furnace hook not being called. --- plugins/eventful.cpp | 1 + 1 file changed, 1 insertion(+) diff --git a/plugins/eventful.cpp b/plugins/eventful.cpp index 4c168ab89f..9c8819a488 100644 --- a/plugins/eventful.cpp +++ b/plugins/eventful.cpp @@ -446,6 +446,7 @@ static bool find_reactions(color_ostream &out) static void enable_hooks(bool enable) { INTERPOSE_HOOK(workshop_hook,fillSidebarMenu).apply(enable); + INTERPOSE_HOOK(furnace_hook,fillSidebarMenu).apply(enable); INTERPOSE_HOOK(item_hooks,contaminateWound).apply(enable); INTERPOSE_HOOK(proj_unit_hook,checkImpact).apply(enable); INTERPOSE_HOOK(proj_unit_hook,checkMovement).apply(enable); From 481d00433d22735ee7a5aa42b2e37f3f6d1a01c4 Mon Sep 17 00:00:00 2001 From: lethosor Date: Wed, 4 Nov 2015 19:53:46 -0500 Subject: [PATCH 38/91] Only search scripts directory with GLOB_RECURSE --- CMakeLists.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 0ac262dd58..fb6dd52bb6 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -210,9 +210,9 @@ if (BUILD_DOCS) "${CMAKE_CURRENT_SOURCE_DIR}/scripts/about.txt" "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/about.txt" ) - file(GLOB_RECURSE SPHINX_SCRIPT_DEPS scripts "${CMAKE_CURRENT_SOURCE_DIR}" - "*.lua" - "*.rb" + file(GLOB_RECURSE SPHINX_SCRIPT_DEPS + "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*.lua" + "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*.rb" ) set(SPHINX_DEPS ${SPHINX_DEPS} ${SPHINX_SCRIPT_DEPS} LICENSE.rst NEWS.rst index.rst) From ac8038fa79db03507ddf69623d1c7020d7da30ca Mon Sep 17 00:00:00 2001 From: lethosor Date: Wed, 4 Nov 2015 20:06:35 -0500 Subject: [PATCH 39/91] Update stonesense --- plugins/stonesense | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/stonesense b/plugins/stonesense index 8121de5571..a0966c0e17 160000 --- a/plugins/stonesense +++ b/plugins/stonesense @@ -1 +1 @@ -Subproject commit 8121de557102eb11cb805f8a25b43ba43077a967 +Subproject commit a0966c0e171de1ed2383b758a26d8250400ca93d From b01d79e50212ab22ff7cef550ba00e735653bdd8 Mon Sep 17 00:00:00 2001 From: lethosor Date: Wed, 4 Nov 2015 20:08:34 -0500 Subject: [PATCH 40/91] Update scripts/3rdparty submodules --- scripts/3rdparty/kane-t | 2 +- scripts/3rdparty/lethosor | 2 +- scripts/3rdparty/maienm | 2 +- scripts/3rdparty/maxthyme | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/scripts/3rdparty/kane-t b/scripts/3rdparty/kane-t index 8cf05cc897..0a75d5ff69 160000 --- a/scripts/3rdparty/kane-t +++ b/scripts/3rdparty/kane-t @@ -1 +1 @@ -Subproject commit 8cf05cc89782206235f4bef1b5ef98e1bc74e266 +Subproject commit 0a75d5ff69916cf9b3739f4b20d36ab4cfdcf824 diff --git a/scripts/3rdparty/lethosor b/scripts/3rdparty/lethosor index 38a8415ffc..8874945020 160000 --- a/scripts/3rdparty/lethosor +++ b/scripts/3rdparty/lethosor @@ -1 +1 @@ -Subproject commit 38a8415ffc23e89590260a4502fa6aeeac95146d +Subproject commit 8874945020869a3ff2383dfa06780d7495f177d2 diff --git a/scripts/3rdparty/maienm b/scripts/3rdparty/maienm index ac6dae2ff0..45c78449e7 160000 --- a/scripts/3rdparty/maienm +++ b/scripts/3rdparty/maienm @@ -1 +1 @@ -Subproject commit ac6dae2ff06d1576873b8e508017e8043e7aa701 +Subproject commit 45c78449e71d1ba263044fb00108509088ad0026 diff --git a/scripts/3rdparty/maxthyme b/scripts/3rdparty/maxthyme index 0c32075d22..6d0d35b689 160000 --- a/scripts/3rdparty/maxthyme +++ b/scripts/3rdparty/maxthyme @@ -1 +1 @@ -Subproject commit 0c32075d2205fe3aa80794fc45b2c49e3dace8dc +Subproject commit 6d0d35b6896d29bff5a487fb92b979a945ad23f7 From 45c3f145e58270cda73dd268a7f68e8709b62da5 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Thu, 5 Nov 2015 13:17:26 +1100 Subject: [PATCH 41/91] Add gui/family-affairs --- docs/images/family-affairs.png | Bin 0 -> 3961 bytes scripts/gui/family-affairs.lua | 296 +++++++++++++++++++++++++++++++++ 2 files changed, 296 insertions(+) create mode 100644 docs/images/family-affairs.png create mode 100644 scripts/gui/family-affairs.lua diff --git a/docs/images/family-affairs.png b/docs/images/family-affairs.png new file mode 100644 index 0000000000000000000000000000000000000000..faf59390eb85e5e8b3aca9a4633fc7315b1b3ade GIT binary patch literal 3961 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 literal 0 HcmV?d00001 diff --git a/scripts/gui/family-affairs.lua b/scripts/gui/family-affairs.lua new file mode 100644 index 0000000000..51525f36e1 --- /dev/null +++ b/scripts/gui/family-affairs.lua @@ -0,0 +1,296 @@ +-- gui/family-affairs +-- derived from v1.2 @ http://www.bay12forums.com/smf/index.php?topic=147779 +local help = [[=begin + +gui/family-affairs +================== +A user-friendly interface to view romantic relationships, +with the ability to add, remove, or otherwise change them at +your whim - fantastic for depressed dwarves with a dead spouse +(or matchmaking players...). + +The target/s must be alive, sane, and in fortress mode. + +.. image:: /docs/images/family-affairs.png + :align: center + +``gui/family-affairs [unitID]`` + shows GUI for the selected unit, or the specified unit ID + +``gui/family-affairs divorce [unitID]`` + removes all spouse and lover information from the unit + and it's partner, bypassing almost all checks. + +``gui/family-affairs [unitID] [unitID]`` + divorces the two specificed units and their partners, + then arranges for the two units to marry, bypassing + almost all checks. Use with caution. + +=end]] + +local dlg = require ('gui.dialogs') + +function ErrorPopup (msg,color) + if not tostring(msg) then msg = "Error" end + if not color then color = COLOR_LIGHTRED end + dlg.showMessage("Dwarven Family Affairs", msg, color, nil) +end + +function AnnounceAndGamelog (text,l) + if not l then l = true end + dfhack.gui.showAnnouncement(text, _G["COLOR_LIGHTMAGENTA"]) + if l then + local log = io.open('gamelog.txt', 'a') + log:write(text.."\n") + log:close() + end +end + +function ListPrompt (msg, choicelist, bool, yes_func) +dlg.showListPrompt( + "Dwarven Family Affairs", + msg, + COLOR_WHITE, + choicelist, + --called if choice is yes + yes_func, + --called on cancel + function() end, + 15, + bool + ) +end + +function GetMarriageSummary (source) + local familystate = "" + + if source.relations.spouse_id ~= -1 then + if dfhack.units.isSane(df.unit.find(source.relations.spouse_id)) then + familystate = dfhack.TranslateName(source.name).." has a spouse ("..dfhack.TranslateName(df.unit.find(source.relations.spouse_id).name)..")" + end + if dfhack.units.isSane(df.unit.find(source.relations.spouse_id)) == false then + familystate = dfhack.TranslateName(source.name).."'s spouse is dead or not sane, would you like to choose a new one?" + end + end + + if source.relations.spouse_id == -1 and source.relations.lover_id ~= -1 then + if dfhack.units.isSane(df.unit.find(source.relations.lover_id)) then + familystate = dfhack.TranslateName(source.name).." already has a lover ("..dfhack.TranslateName(df.unit.find(source.relations.spouse_id).name)..")" + end + if dfhack.units.isSane(df.unit.find(source.relations.lover_id)) == false then + familystate = dfhack.TranslateName(source.name).."'s lover is dead or not sane, would you like that love forgotten?" + end + end + + if source.relations.spouse_id == -1 and source.relations.lover_id == -1 then + familystate = dfhack.TranslateName(source.name).." is not involved in romantic relationships with anyone" + end + + if source.relations.pregnancy_timer > 0 then + familystate = familystate.."\nShe is pregnant." + local father = df.historical_figure.find(source.relations.pregnancy_spouse) + if father then + familystate = familystate.." The father is "..dfhack.TranslateName(father.name).."." + end + end + + return familystate +end + +function GetSpouseData (source) + local spouse = df.unit.find(source.relations.spouse_id) + local spouse_hf + if spouse then + spouse_hf = df.historical_figure.find (spouse.hist_figure_id) + end + return spouse,spouse_hf +end + +function GetLoverData (source) + local lover = df.unit.find(source.relations.spouse_id) + local lover_hf + if lover then + lover_hf = df.historical_figure.find (lover.hist_figure_id) + end + return lover,lover_hf +end + +function EraseHFLinksLoverSpouse (hf) + for i = #hf.histfig_links-1,0,-1 do + if hf.histfig_links[i]._type == df.histfig_hf_link_spousest or hf.histfig_links[i]._type == df.histfig_hf_link_loverst then + local todelete = hf.histfig_links[i] + hf.histfig_links:erase(i) + todelete:delete() + end + end +end + +function Divorce (source) + local source_hf = df.historical_figure.find(source.hist_figure_id) + local spouse,spouse_hf = GetSpouseData (source) + local lover,lover_hf = GetLoverData (source) + + source.relations.spouse_id = -1 + source.relations.lover_id = -1 + + if source_hf then + EraseHFLinksLoverSpouse (source_hf) + end + if spouse then + spouse.relations.spouse_id = -1 + spouse.relations.lover_id = -1 + end + if lover then + spouse.relations.spouse_id = -1 + spouse.relations.lover_id = -1 + end + if spouse_hf then + EraseHFLinksLoverSpouse (spouse_hf) + end + if lover_hf then + EraseHFLinksLoverSpouse (lover_hf) + end + + local partner = spouse or lover + if not partner then + AnnounceAndGamelog(dfhack.TranslateName(source.name).." is now single") + else + AnnounceAndGamelog(dfhack.TranslateName(source.name).." and "..dfhack.TranslateName(partner.name).." are now single") + end +end + +function Marriage (source,target) + local source_hf = df.historical_figure.find(source.hist_figure_id) + local target_hf = df.historical_figure.find(target.hist_figure_id) + source.relations.spouse_id = target.id + target.relations.spouse_id = source.id + + local new_link = df.histfig_hf_link_spousest:new() -- adding hf link to source + new_link.target_hf = target_hf.id + new_link.link_strength = 100 + source_hf.histfig_links:insert('#',new_link) + + new_link = df.histfig_hf_link_spousest:new() -- adding hf link to target + new_link.target_hf = source_hf.id + new_link.link_strength = 100 + target_hf.histfig_links:insert('#',new_link) +end + +function ChooseNewSpouse (source) + + if not source then + qerror("no unit") return + end + if (source.profession == 103 or source.profession == 104) then + ErrorPopup("target is too young") return + end + if not (source.relations.spouse_id == -1 and source.relations.lover_id == -1) then + ErrorPopup("target already has a spouse or a lover") + qerror("source already has a spouse or a lover") + return + end + + local choicelist = {} + targetlist = {} + + for k,v in pairs (df.global.world.units.active) do + if dfhack.units.isCitizen(v) + and v.race == source.race + and v.sex ~= source.sex + and v.relations.spouse_id == -1 + and v.relations.lover_id == -1 + and not (v.profession == 103 or v.profession == 104) + then + table.insert(choicelist,dfhack.TranslateName(v.name)..', '..dfhack.units.getProfessionName(v)) + table.insert(targetlist,v) + end + end + + if #choicelist > 0 then + ListPrompt( + "Assign new spouse for "..dfhack.TranslateName(source.name), + choicelist, + true, + function(a,b) + local target = targetlist[a] + Marriage (source,target) + AnnounceAndGamelog(dfhack.TranslateName(source.name).." and "..dfhack.TranslateName(target.name).." have married!") + end) + else + ErrorPopup("No suitable candidates") + end +end + +function MainDialog (source) + + local familystate = GetMarriageSummary(source) + + familystate = familystate.."\nSelect action:" + local choicelist = {} + local on_select = {} + + local child = (source.profession == 103 or source.profession == 104) + local is_single = source.relations.spouse_id == -1 and source.relations.lover_id == -1 + local ready_for_marriage = single and not child + + if not child then + table.insert(choicelist,"Remove romantic relationships (if any)") + table.insert(on_select, Divorce) + if ready_for_marriage then + table.insert(choicelist,"Assign a new spouse") + table.insert(on_select,ChooseNewSpouse) + end + if not ready_for_marriage then + table.insert(choicelist,"[Assign a new spouse]") + table.insert(on_select,function () ErrorPopup ("Existing relationships must be removed if you wish to assign a new spouse.") end) + end + else + table.insert(choicelist,"Leave this child alone") + table.insert(on_select,nil) + end + + ListPrompt(familystate, choicelist, false, + function(a,b) if on_select[a] then on_select[a](source) end end) +end + + +local args = {...} + +if args[1] == "help" or args[1] == "?" then print(helpstr) return end + +if not df.global.gamemode == 0 then + print (helpstr) qerror ("invalid gamemode") return +end + +if args[1] == "divorce" and tonumber(args[2]) then + local unit = df.unit.find(args[2]) + if unit then Divorce (unit) return end +end + +if tonumber(args[1]) and tonumber(args[2]) then + local unit1 = df.unit.find(args[1]) + local unit2 = df.unit.find(args[2]) + if unit1 and unit2 then + Divorce (unit1) + Divorce (unit2) + Marriage (unit1,unit2) + return + end +end + +local selected = dfhack.gui.getSelectedUnit(true) +if tonumber(args[1]) then + selected = df.unit.find(tonumber(args[1])) or selected +end + +if selected then + if dfhack.units.isCitizen(selected) and dfhack.units.isSane(selected) then + MainDialog(selected) + else + qerror("You must select sane fortress citizen.") + return + end +else + print (helpstr) + qerror("select a sane fortress dwarf") +end From e2a1658124c6a3bcb3ce3af7190fc3b7332e8a80 Mon Sep 17 00:00:00 2001 From: lethosor Date: Wed, 4 Nov 2015 21:38:39 -0500 Subject: [PATCH 42/91] Update xml --- library/xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/library/xml b/library/xml index dc76bf4247..ad869ba25b 160000 --- a/library/xml +++ b/library/xml @@ -1 +1 @@ -Subproject commit dc76bf4247b78cf2525bf60a62553dadd42ca696 +Subproject commit ad869ba25ba36cdf0c032fe325972508655b9b6f From 3623659a9b00a750561f83e2d8138d280cbbaa7a Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Thu, 5 Nov 2015 16:40:35 +1100 Subject: [PATCH 43/91] Add emigration script --- scripts/emigration.lua | 130 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100644 scripts/emigration.lua diff --git a/scripts/emigration.lua b/scripts/emigration.lua new file mode 100644 index 0000000000..d523177bf2 --- /dev/null +++ b/scripts/emigration.lua @@ -0,0 +1,130 @@ +--Allow stressed dwarves to emigrate from the fortress +-- For 34.11 by IndigoFenix; update and cleanup by PeridexisErrant +-- old version: http://dffd.bay12games.com/file.php?id=8404 +--[[=begin + +emigration +========== +Allows dwarves to emigrate from the fortress when stressed, +in proportion to how badly stressed they are and adjusted +for who they would have to leave with - a dwarven merchant +being more attractive than leaving alone (or with an elf). +The check is made monthly. + +A happy dwarf (ie with negative stress) will never emigrate. + +Usage: ``emigration enable|disable`` + +=end]] + +local args = {...} +if args[1] == "enable" then + enabled = true +elseif args[1] == "disable" then + enabled = false +end + +function desireToStay(unit,method,civ_id) + -- on a percentage scale + value = 100 - unit.status.current_soul.personality.stress_level / 5000 + if method == 'merchant' or method == 'diplomat' then + if civ_id ~= unit.civ_id then value = value*2 end end + if method == 'wild' then + value = value*5 end + return value +end + +function desert(u,method,civ) + u.relations.following = nil + local line = dfhack.TranslateName(dfhack.units.getVisibleName(u)) .. " has " + if method == 'merchant' then + line = line.."joined the merchants" + u.flags1.merchant = true + u.civ_id = civ + elseif method == 'diplomat' then + line = line.."followed the diplomat" + u.flags1.diplomat = true + u.civ_id = civ + else + line = line.."abandoned the settlement in search of a better life." + u.civ_id = -1 + u.flags1.forest = true + u.animal.leave_countdown = 2 + end + print(line) + dfhack.gui.showAnnouncement(line, COLOR_WHITE) +end + +function canLeave(unit) + for _, skill in pairs(unit.status.current_soul.skills) do + if skill.rating > 14 then return false end + end + if unit.flags1.caged + or u.race ~= df.global.ui.race_id + or u.civ_id ~= df.global.ui.civ_id + or dfhack.units.isDead(u) + or dfhack.units.isOpposedToLife(u) + or u.flags1.merchant + or u.flags1.diplomat + or unit.flags1.chained + or dfhack.units.getNoblePositions(unit) ~= nil + or unit.military.squad_id ~= -1 + or dfhack.units.isCitizen(unit) + or dfhack.units.isSane(unit) + or unit.profession ~= 103 + or not dfhack.units.isDead(unit) + then return false end + return true +end + +function checkForDeserters(method,civ_id) + local allUnits = df.global.world.units.active + for i=#allUnits-1,0,-1 do -- search list in reverse + local u = allUnits[i] + if canLeave(u) and math.random(100) < desireToStay(u,method,civ_id) then + desert(u,method,civ_id) + end + end +end + +function checkmigrationnow() + local merchant_civ_ids = {} + local diplomat_civ_ids = {} + local allUnits = df.global.world.units.active + for i=0, #allUnits-1 do + local unit = allUnits[i] + if dfhack.units.isSane(unit) + and not dfhack.units.isDead(unit) + and not dfhack.units.isOpposedToLife(unit) + and not unit.flags1.tame + then + if unit.flags1.merchant then table.insert(merchant_civ_ids, unit.civ_id) end + if unit.flags1.diplomat then table.insert(diplomat_civ_ids, unit.civ_id) end + end + end + + for _, civ_id in pairs(merchant_civ_ids) do checkForDeserters('merchant', civ_id) end + for _, civ_id in pairs(diplomat_civ_ids) do checkForDeserters('diplomat', civ_id) end + checkForDeserters('wild', -1) +end + +local function event_loop() + checkmigrationnow() + dfhack.timeout(1, 'months', event_loop) +end + +dfhack.onStateChange.loadEmigration = function(code) + if code==SC_MAP_LOADED then + if enabled then + print("Emigration enabled.") + event_loop() + else + print("Emigration disabled.") + end + end +end + +if dfhack.isMapLoaded() then + dfhack.onStateChange.loadEmigration(SC_MAP_LOADED) +end + From efe945cfd91064203d1e8bb3b3c35a70cede666a Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Thu, 5 Nov 2015 21:54:45 +1100 Subject: [PATCH 44/91] Add new scripts to NEWS --- NEWS.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/NEWS.rst b/NEWS.rst index e966eda6ac..ee8c8a4bf0 100644 --- a/NEWS.rst +++ b/NEWS.rst @@ -82,6 +82,8 @@ New scripts - `pref-adjust`: Adjust all preferences of all dwarves in play - `rejuvenate`: make any "old" dwarf 20 years old - `starvingdead`: make undead weaken after one month on the map, and crumble after six +- `emigration`: stressed dwarves may leave your fortress if they see a chance +- `gui/family-affairs`: investigate and alter romantic relationships New tweaks ---------- From 23b02ebcf2698722557936410f86d97bd6b482bf Mon Sep 17 00:00:00 2001 From: lethosor Date: Thu, 5 Nov 2015 16:17:52 -0500 Subject: [PATCH 45/91] Update xml --- library/xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/library/xml b/library/xml index ad869ba25b..378a580f7e 160000 --- a/library/xml +++ b/library/xml @@ -1 +1 @@ -Subproject commit ad869ba25ba36cdf0c032fe325972508655b9b6f +Subproject commit 378a580f7e333607a64a301d598e3885954a5d9d From 58e6ef6524ca984d4acbaf8e613a8cc86d06b081 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Wed, 4 Nov 2015 23:13:52 +1100 Subject: [PATCH 46/91] De-alias migrants-now --- scripts/devel/migrants-now.lua | 9 --------- scripts/migrants-now.lua | 11 ++++++++--- 2 files changed, 8 insertions(+), 12 deletions(-) delete mode 100644 scripts/devel/migrants-now.lua diff --git a/scripts/devel/migrants-now.lua b/scripts/devel/migrants-now.lua deleted file mode 100644 index 8eb4b0c8f2..0000000000 --- a/scripts/devel/migrants-now.lua +++ /dev/null @@ -1,9 +0,0 @@ --- Force a migrants event in next 10 ticks. - -df.global.timed_events:insert('#',{ - new = true, - type = df.timed_event_type.Migrants, - season = df.global.cur_season, - season_ticks = df.global.cur_season_tick+1, - entity = df.historical_entity.find(df.global.ui.civ_id) -}) diff --git a/scripts/migrants-now.lua b/scripts/migrants-now.lua index b2f08e9f92..b38e381158 100644 --- a/scripts/migrants-now.lua +++ b/scripts/migrants-now.lua @@ -1,11 +1,16 @@ -- Force a migrant wave (only works after hardcoded waves) ---@alias = 'devel/migrants-now' --[[=begin migrants-now ============ Forces an immediate migrant wave. Only works after migrants have -arrived naturally. Alias for ``devel/migrants-now``; equivalent to -`modtools/force` ``-eventType migrants`` +arrived naturally. Equivalent to `modtools/force` ``-eventType migrants`` =end]] +df.global.timed_events:insert('#',{ + new = true, + type = df.timed_event_type.Migrants, + season = df.global.cur_season, + season_ticks = df.global.cur_season_tick+1, + entity = df.historical_entity.find(df.global.ui.civ_id) +}) From 5018af9a9e2644f951d7281644ee422d79e6dae4 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Wed, 4 Nov 2015 23:14:10 +1100 Subject: [PATCH 47/91] Document devel scripts --- scripts/devel/about.txt | 8 +++++-- scripts/devel/all-bob.lua | 10 +++++++- scripts/devel/cmptiles.lua | 10 +++++++- scripts/devel/export-dt-ini.lua | 7 ++++++ scripts/devel/find-offsets.lua | 38 +++++++++++++++++++++++------- scripts/devel/inject-raws.lua | 28 +++++++++++++++------- scripts/devel/inspect-screen.lua | 7 ++++++ scripts/devel/light.lua | 13 +++++++++- scripts/devel/list-filters.lua | 10 ++++++-- scripts/devel/lsmem.lua | 7 ++++++ scripts/devel/lua-example.lua | 6 ----- scripts/devel/nuke-items.lua | 10 ++++++-- scripts/devel/pop-screen.lua | 7 ++++++ scripts/devel/prepare-save.lua | 12 ++++++++++ scripts/devel/print-args.lua | 9 ++++++- scripts/devel/print-args2.lua | 9 ++++++- scripts/devel/scanitemother.rb | 8 ++++++- scripts/devel/spawn-unit-helper.rb | 22 ++++++++++------- scripts/devel/test-perlin.lua | 9 +++++++ scripts/devel/unforbidall.rb | 7 ++++++ scripts/devel/unit-path.lua | 7 ++++++ scripts/devel/watch-minecarts.lua | 9 +++++++ 22 files changed, 210 insertions(+), 43 deletions(-) delete mode 100644 scripts/devel/lua-example.lua diff --git a/scripts/devel/about.txt b/scripts/devel/about.txt index cd97a88095..12b1f18539 100644 --- a/scripts/devel/about.txt +++ b/scripts/devel/about.txt @@ -1,2 +1,6 @@ -``devel/*`` scripts are intended for developers, or still substantially unfinished. -If you don't already know what they do, best to leave them alone. +``devel/*`` scripts are intended for developer use, but many may +be of interest to anyone investigating odd phenomema or just messing +around. They are documented to encourage such inquiry. + +Some can PERMANENTLY DAMAGE YOUR SAVE if misused, so please be careful. +The warnings are real; if in doubt make backups before running the command. diff --git a/scripts/devel/all-bob.lua b/scripts/devel/all-bob.lua index 65c1ea2d67..08ab19fbb1 100644 --- a/scripts/devel/all-bob.lua +++ b/scripts/devel/all-bob.lua @@ -1,6 +1,14 @@ --all-bob.lua --author expwnent ---names all units bob. Useful for testing interaction trigger events +-- +--[[=begin + +devel/all-bob +============= +Changes the first name of all units to "Bob". +Useful for testing `modtools/interaction-trigger` events. + +=end]] for _,v in ipairs(df.global.world.units.all) do v.name.first_name = "Bob" diff --git a/scripts/devel/cmptiles.lua b/scripts/devel/cmptiles.lua index 8421038ebe..bb08710513 100644 --- a/scripts/devel/cmptiles.lua +++ b/scripts/devel/cmptiles.lua @@ -1,5 +1,13 @@ -- Lists and/or compares two tiletype material groups. --- Usage: devel/cmptiles material1 [material2] +--[[=begin + +devel/cmptiles +============== +Lists and/or compares two tiletype material groups. + +Usage: ``devel/cmptiles material1 [material2]`` + +=end]] local nmat1,nmat2=... local mat1 = df.tiletype_material[nmat1] diff --git a/scripts/devel/export-dt-ini.lua b/scripts/devel/export-dt-ini.lua index 41a2457ceb..1d99b2d556 100644 --- a/scripts/devel/export-dt-ini.lua +++ b/scripts/devel/export-dt-ini.lua @@ -1,4 +1,11 @@ -- Exports an ini file for Dwarf Therapist. +--[[=begin + +devel/export-dt-ini +=================== +Exports an ini file containing memory addresses for Dwarf Therapist. + +=end]] local utils = require 'utils' local ms = require 'memscan' diff --git a/scripts/devel/find-offsets.lua b/scripts/devel/find-offsets.lua index ae99adbca6..17bc4f6f91 100644 --- a/scripts/devel/find-offsets.lua +++ b/scripts/devel/find-offsets.lua @@ -1,19 +1,39 @@ -- Find some offsets for linux. +--[[=begin -local utils = require 'utils' -local ms = require 'memscan' -local gui = require 'gui' +devel/find-offsets +================== +WARNING: THIS SCRIPT IS STRICTLY FOR DFHACK DEVELOPERS. + +Running this script on a new DF version will NOT +MAKE IT RUN CORRECTLY if any data structures +changed, thus possibly leading to CRASHES AND/OR +PERMANENT SAVE CORRUPTION. + +Finding the first few globals requires this script to be +started immediately after loading the game, WITHOUT +first loading a world. The rest expect a loaded save, +not a fresh embark. Finding current_weather requires +a special save previously processed with `devel/prepare-save` +on a DF version with working dfhack. ---[[ +The script expects vanilla game configuration, without +any custom tilesets or init file changes. Never unpause +the game unless instructed. When done, quit the game +without saving using 'die'. Arguments: - * global names to force finding them - * 'all' to force all globals - * 'nofeed' to block automated fake input searches - * 'nozoom' to disable neighboring object heuristics +* global names to force finding them +* ``all`` to force all globals +* ``nofeed`` to block automated fake input searches +* ``nozoom`` to disable neighboring object heuristics -]] +=end]] + +local utils = require 'utils' +local ms = require 'memscan' +local gui = require 'gui' local is_known = dfhack.internal.getAddress diff --git a/scripts/devel/inject-raws.lua b/scripts/devel/inject-raws.lua index 1450d1179c..cea69eb618 100644 --- a/scripts/devel/inject-raws.lua +++ b/scripts/devel/inject-raws.lua @@ -1,14 +1,26 @@ -- Injects new reaction, item and building defs into the world. +--[[=begin --- The savegame contains a list of the relevant definition tokens in --- the right order, but all details are read from raws every time. --- This allows just adding stub definitions, and simply saving and --- reloading the game. +devel/inject-raws +================= +WARNING: THIS SCRIPT CAN PERMANENLY DAMAGE YOUR SAVE. --- Usage example: ---[[ -devel/inject-raws trapcomp ITEM_TRAPCOMP_STEAM_PISTON workshop STEAM_ENGINE MAGMA_STEAM_ENGINE reaction STOKE_BOILER -]] +This script attempts to inject new raw objects into your +world. If the injected references do not match the actual +edited raws, your save will refuse to load, or load but crash. + +The savegame contains a list of the relevant definition tokens in +the right order, but all details are read from raws every time. +This allows just adding stub definitions, and simply saving and +reloading the game. + +This is useful enough for modders and some users to justify the danger. + +Usage example:: + + devel/inject-raws trapcomp ITEM_TRAPCOMP_STEAM_PISTON workshop STEAM_ENGINE MAGMA_STEAM_ENGINE reaction STOKE_BOILER + +=end]] local utils = require 'utils' diff --git a/scripts/devel/inspect-screen.lua b/scripts/devel/inspect-screen.lua index ae8334ad7a..9de6b25326 100644 --- a/scripts/devel/inspect-screen.lua +++ b/scripts/devel/inspect-screen.lua @@ -1,4 +1,11 @@ -- Read the tiles from the screen and display info about them. +--[[=begin + +devel/inspect-screen +==================== +Read the tiles from the screen and display info about them. + +=end]] local utils = require 'utils' local gui = require 'gui' diff --git a/scripts/devel/light.lua b/scripts/devel/light.lua index 532a3a4f50..e19591e11c 100644 --- a/scripts/devel/light.lua +++ b/scripts/devel/light.lua @@ -1,4 +1,15 @@ --- an experimental lighting engine for df. param: "static" to not recalc when in game. press "~" to recalculate. "`" to exit +-- an experimental lighting engine +--[[=begin + +devel/light +=========== +An experimental lighting engine for DF, using the `rendermax` plugin. + +Call ``devel/light static`` to not recalculate lighting when in game. +Press :kbd:`~` to recalculate lighting. Press :kbd:`\`` to exit. + +=end]] + local gui = require 'gui' local guidm = require 'gui.dwarfmode' local render = require 'plugins.rendermax' diff --git a/scripts/devel/list-filters.lua b/scripts/devel/list-filters.lua index 87b9f24b1c..5666315fc0 100644 --- a/scripts/devel/list-filters.lua +++ b/scripts/devel/list-filters.lua @@ -1,6 +1,12 @@ -- List input items for the building currently being built. --- --- This is where the filters in lua/dfhack/buildings.lua come from. +--[[=begin + +devel/list-filters +================== +List input items for the building currently being built. +This is where the filters in lua/dfhack/buildings.lua come from. + +=end]] local dumper = require 'dumper' local utils = require 'utils' diff --git a/scripts/devel/lsmem.lua b/scripts/devel/lsmem.lua index 75586324d9..b390adc5c4 100644 --- a/scripts/devel/lsmem.lua +++ b/scripts/devel/lsmem.lua @@ -1,4 +1,11 @@ -- Prints memory ranges of the process. +--[[=begin + +devel/lsmem +=========== +Prints memory ranges of the process. + +=end]] for _,v in ipairs(dfhack.internal.getMemRanges()) do local access = { '-', '-', '-', 'p' } diff --git a/scripts/devel/lua-example.lua b/scripts/devel/lua-example.lua deleted file mode 100644 index 044849ed77..0000000000 --- a/scripts/devel/lua-example.lua +++ /dev/null @@ -1,6 +0,0 @@ --- Example of a lua script. - -run_count = (run_count or 0) + 1 - -print('Arguments: ',...) -print('Command called '..run_count..' times.') diff --git a/scripts/devel/nuke-items.lua b/scripts/devel/nuke-items.lua index aa3f5b840d..d98901142b 100644 --- a/scripts/devel/nuke-items.lua +++ b/scripts/devel/nuke-items.lua @@ -1,6 +1,12 @@ -- Deletes ALL items not held by units, buildings or jobs. --- --- Intended solely for lag investigation. +--[[=begin + +devel/nuke-items +================ +Deletes ALL items not held by units, buildings or jobs. +Intended solely for lag investigation. + +=end]] local count = 0 diff --git a/scripts/devel/pop-screen.lua b/scripts/devel/pop-screen.lua index f1ee072c59..8bc5e45c6f 100644 --- a/scripts/devel/pop-screen.lua +++ b/scripts/devel/pop-screen.lua @@ -1,3 +1,10 @@ -- For killing bugged out gui script screens. +--[[=begin + +devel/pop-screen +================ +For killing bugged out gui script screens. + +=end]] dfhack.screen.dismiss(dfhack.gui.getCurViewscreen()) diff --git a/scripts/devel/prepare-save.lua b/scripts/devel/prepare-save.lua index c282c8a437..dd1f81e453 100644 --- a/scripts/devel/prepare-save.lua +++ b/scripts/devel/prepare-save.lua @@ -1,4 +1,16 @@ -- Prepare the current save for use with devel/find-offsets. +--[[=begin + +devel/prepare-save +================== +WARNING: THIS SCRIPT IS STRICTLY FOR DFHACK DEVELOPERS. + +This script prepares the current savegame to be used +with `devel/find-offsets`. It CHANGES THE GAME STATE +to predefined values, and initiates an immediate +`quicksave`, thus PERMANENTLY MODIFYING the save. + +=end]] local utils = require 'utils' diff --git a/scripts/devel/print-args.lua b/scripts/devel/print-args.lua index 199a20e7fd..46024eaa42 100644 --- a/scripts/devel/print-args.lua +++ b/scripts/devel/print-args.lua @@ -1,6 +1,13 @@ --print-args.lua --author expwnent ---prints all the arguments on their own line. useful for debugging +--[[=begin + +devel/print-args +================ +Prints all the arguments you supply to the script on their own line. +Useful for debugging other scripts. + +=end]] local args = {...} for _,arg in ipairs(args) do diff --git a/scripts/devel/print-args2.lua b/scripts/devel/print-args2.lua index 873b403119..ad870623d9 100644 --- a/scripts/devel/print-args2.lua +++ b/scripts/devel/print-args2.lua @@ -1,6 +1,13 @@ --print-args2.lua --author expwnent ---prints all the arguments on their own line with quotes around them. useful for debugging +--[[=begin + +devel/print-args2 +================= +Prints all the arguments you supply to the script on their own line +with quotes around them. + +=end]] local args = {...} print("print-args") diff --git a/scripts/devel/scanitemother.rb b/scripts/devel/scanitemother.rb index 00b093a28c..1f130603ff 100644 --- a/scripts/devel/scanitemother.rb +++ b/scripts/devel/scanitemother.rb @@ -1,5 +1,11 @@ -# list indexes in world.item.other[] where current selected item appears +# list indices in world.item.other[] where current selected item appears +=begin +devel/scanitemother +=================== +List indices in ``world.item.other[]`` where current selected item appears. + +=end tg = df.item_find raise 'select an item' if not tg diff --git a/scripts/devel/spawn-unit-helper.rb b/scripts/devel/spawn-unit-helper.rb index a7d4f610d1..437eb81db1 100644 --- a/scripts/devel/spawn-unit-helper.rb +++ b/scripts/devel/spawn-unit-helper.rb @@ -13,17 +13,23 @@ df.world.arena_spawn.creature_cnt[df.world.arena_spawn.race.length-1] = 0 puts < Date: Thu, 5 Nov 2015 00:23:45 +1100 Subject: [PATCH 48/91] Linting: improve script docs check, work off Travis Expands coverage of scripts linting, and improves checks for a correct title. Various fixes to make 'python travis/all.py' work for offline users; when the TRAVIS envvar is not set it now fails without an error. Minor cleanup in conf.py --- conf.py | 49 +++++++------------------------------- travis/lint.py | 5 +++- travis/script-in-readme.py | 43 +++++++++++++++++---------------- travis/script-syntax.py | 23 +++++++++++------- 4 files changed, 50 insertions(+), 70 deletions(-) diff --git a/conf.py b/conf.py index 81cfb78eff..5eb2c81772 100644 --- a/conf.py +++ b/conf.py @@ -1,8 +1,7 @@ #!/usr/bin/env python3 # -*- coding: utf-8 -*- # -# DFHack documentation build configuration file, created by -# sphinx-quickstart on Tue Sep 22 17:34:54 2015. +# DFHack documentation build configuration file # # This file is execfile()d with the current directory set to its # containing dir. @@ -18,25 +17,24 @@ import os import shlex import sys -import shutil +# -- Autodoc for DFhack scripts ------------------------------------------- + def doc_dir(dirname, files): """Yield (command, includepath) for each script in the directory.""" sdir = os.path.relpath(dirname, '.').replace('\\', '/').replace('../', '') for f in files: - if f[-3:] not in {'lua', '.rb'}: + if f[-3:] not in ('lua', '.rb'): continue with open(os.path.join(dirname, f), 'r', encoding='utf8') as fstream: text = [l.rstrip() for l in fstream.readlines() if l.strip()] command = None for line in text: - if line == len(line) * '=': - if command is not None: - yield command, sdir + '/' + f + if command and line == len(line) * '=': + yield command, sdir + '/' + f break command = line - # later, print an error for missing docs here def document_scripts(): @@ -89,11 +87,6 @@ def document_scripts(): document_scripts() -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.insert(0, os.path.abspath('.')) - # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. @@ -115,15 +108,12 @@ def document_scripts(): 'bug': ('http://www.bay12games.com/dwarves/mantisbt/view.php?id=%s', 'Bug ') } -# some aliases for link directives -extlinks['forum'] = extlinks['forums'] # Add any paths that contain templates here, relative to this directory. templates_path = [] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: -# source_suffix = ['.rst', '.md'] source_suffix = '.rst' # The encoding of source files. @@ -145,7 +135,7 @@ def get_version(): """Return the DFHack version string, from CMakeLists.txt""" version = release = '' try: - with open('../CMakeLists.txt') as f: + with open('CMakeLists.txt') as f: for s in f.readlines(): if fnmatch.fnmatch(s.upper(), 'SET(DF_VERSION "?.??.??")\n'): version = s.upper().replace('SET(DF_VERSION "', '') @@ -179,19 +169,9 @@ def get_version(): # documents. default_role = 'ref' -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' -# If true, keep warnings as "system message" paragraphs in the built documents. -#keep_warnings = False - # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = False @@ -245,7 +225,7 @@ def get_version(): # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' +html_last_updated_fmt = '%Y-%m-%d' # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. @@ -288,19 +268,6 @@ def get_version(): # base URL from which the finished HTML is served. #html_use_opensearch = '' -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Language to be used for generating the HTML full-text search index. -# Sphinx supports the following languages: -# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja' -# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr' -#html_search_language = 'en' - -# The name of a javascript file (relative to the configuration directory) that -# implements a search results scorer. If empty, the default will be used. -#html_search_scorer = 'scorer.js' - # Output file base name for HTML help builder. htmlhelp_basename = 'DFHackdoc' diff --git a/travis/lint.py b/travis/lint.py index ce28f4be36..9b39f01499 100644 --- a/travis/lint.py +++ b/travis/lint.py @@ -65,8 +65,11 @@ def display_lines(self, lines, total): class NewlineLinter(Linter): msg = 'Contains DOS-style newlines' + def __init__(self): + # git supports newline conversion. Catch in CI, ignore on Windows. + self.ignore = sys.platform == 'win32' and not os.environ.get('TRAVIS') def check_line(self, line): - return '\r' not in line + return self.ignore or '\r' not in line def fix_line(self, line): return line.replace('\r', '') diff --git a/travis/script-in-readme.py b/travis/script-in-readme.py index b7d0577f39..a6804fb00d 100644 --- a/travis/script-in-readme.py +++ b/travis/script-in-readme.py @@ -1,17 +1,19 @@ from io import open import os +from os.path import basename, dirname, join, splitext import sys -scriptdirs = ( - 'scripts', - #'scripts/devel', # devel scripts don't have to be documented - 'scripts/fix', - 'scripts/gui', - 'scripts/modtools') + +def expected_cmd(path): + """Get the command from the name of a script.""" + dname, fname = basename(dirname(path)), splitext(basename(path))[0] + if dname in ('devel', 'fix', 'gui', 'modtools'): + return dname + '/' + fname + return fname def check_file(fname): - doclines = [] + errors, doclines = 0, [] with open(fname, errors='ignore') as f: for l in f.readlines(): if doclines or l.strip().endswith('=begin'): @@ -27,23 +29,24 @@ def check_file(fname): title, underline = doclines[2], doclines[3] if underline != '=' * len(title): print('Error: title/underline mismatch:', fname, title, underline) - return 1 - start = fname.split('/')[-2] - if start != 'scripts' and not title.startswith(start): - print('Error: title is missing start string: {} {} {}'.format(fname, start, title)) - return 1 - return 0 + errors += 1 + if title != expected_cmd(fname): + print('Warning: expected script title {}, got {}'.format( + expected_cmd(fname), title)) + errors += 1 + return errors def main(): """Check that all DFHack scripts include documentation (not 3rdparty)""" - errors = 0 - for path in scriptdirs: - for f in os.listdir(path): - f = path + '/' + f - if os.path.isfile(f) and f[-3:] in {'.rb', 'lua'}: - errors += check_file(f) - return errors + err = 0 + for root, _, files in os.walk('scripts'): + for f in files: + # TODO: remove 3rdparty exemptions from checks + # Requires reading their CMakeLists to only apply to used scripts + if f[-3:] in {'.rb', 'lua'} and '3rdparty' not in root: + err += check_file(join(root, f)) + return err if __name__ == '__main__': diff --git a/travis/script-syntax.py b/travis/script-syntax.py index 984ff1755a..0b977f59d6 100644 --- a/travis/script-syntax.py +++ b/travis/script-syntax.py @@ -1,15 +1,12 @@ -import argparse, os, sys, subprocess +import argparse +import os +import subprocess +import sys -parser = argparse.ArgumentParser() -parser.add_argument('--path', default='.', help='Root directory') -parser.add_argument('--ext', help='Script extension', required=True) -parser.add_argument('--cmd', help='Command', required=True) -args = parser.parse_args() def main(): root_path = os.path.abspath(args.path) cmd = args.cmd.split(' ') - ext = '.' + args.ext if not os.path.exists(root_path): print('Nonexistent path: %s' % root_path) sys.exit(2) @@ -19,14 +16,24 @@ def main(): if '.git' in parts or 'depends' in parts: continue for filename in filenames: - if not filename.endswith(ext): + if not filename.endswith(args.ext): continue full_path = os.path.join(cur, filename) try: subprocess.check_output(cmd + [full_path]) except subprocess.CalledProcessError: err = True + except IOError: + # catch error if not in Travis and Lua/Ruby is not available + if os.environ.get('TRAVIS', False): + raise sys.exit(int(err)) + if __name__ == '__main__': + parser = argparse.ArgumentParser() + parser.add_argument('--path', default='.', help='Root directory') + parser.add_argument('--ext', help='Script extension', required=True) + parser.add_argument('--cmd', help='Command', required=True) + args = parser.parse_args() main() From 8aafcec0c8292fc27edeb40b000e4759ca7c2f16 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Thu, 5 Nov 2015 11:56:42 +1100 Subject: [PATCH 49/91] Add unacknowledged contributors Mostly authors of scripts which have been added. --- docs/Authors.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/Authors.rst b/docs/Authors.rst index 5661e6132c..05997b3d66 100644 --- a/docs/Authors.rst +++ b/docs/Authors.rst @@ -21,15 +21,18 @@ Caldfir caldfir Chris Dombroski cdombroski Clayton Hughes David Corbett dscorbett +Deon DoctorVanGogh DoctorVanGogh Donald Ruegsegger hashaash doomchild doomchild +enjia2000 Eric Wald eswald Erik Youngren Artanis Espen Wiborg expwnent expwnent Feng Harlan Playford playfordh +IndigoFenix James Logsdon jlogsdon Japa JapaMala Jared Adams @@ -40,11 +43,14 @@ Jonas Ask kane-t kane-t Kelly Martin ab9rf Kris Parker kaypy +Kurik Amudnil Lethosor lethosor Mason11987 Mason11987 Matthew Cline Max maxthyme Max^TM melkor217 melkor217 +Meneth32 +Meph Michon van Dooren MaienM miffedmap miffedmap Mike Stewart thewonderidiot @@ -53,6 +59,7 @@ MithrilTuxedo MithrilTuxedo mizipzor mizipzor Neil Little nmlittle Nick Rart nickrart comestible +Omniclasm PeridexisErrant PeridexisErrant Petr Mrázek peterix potato @@ -64,6 +71,7 @@ rampaging-poet Raoul van Putten Raoul XQ raoulxq reverb +Raidau Raidau Rinin Rinin Robert Heinrich rh73 rofl0r rofl0r @@ -78,6 +86,7 @@ scamtank scamtank Seth Woodworth sethwoodworth simon Simon Jackson sizeak +Tacomagic Tim Walberg twalberg Timothy Collett danaris Tom Prince From 4fbf9ce233f26f94dbd9ca4e09062b1441d36eeb Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Thu, 5 Nov 2015 13:01:06 +1100 Subject: [PATCH 50/91] Clarify LICENSE.rst, deduplicate, add links A simple list of components with the full text each time is not particularly useful, or required. The table lists components in alphabetical order (except DFhack, first), with license and copyright. Component names are hyperlinked to the source project, which was not the case previously. Licenses which are required to be included are, but once only - an improvement over four zlib, 3 BSD and five (!) MIT blocks. This and the table satisfies the requirements while remaining readable. --- LICENSE.rst | 380 +++++++++++----------------------------------------- 1 file changed, 78 insertions(+), 302 deletions(-) diff --git a/LICENSE.rst b/LICENSE.rst index 490b07a6e7..782c77bf55 100644 --- a/LICENSE.rst +++ b/LICENSE.rst @@ -4,14 +4,53 @@ Licenses ######## -DFHack is distributed under a range of permissive and weakly copyleft licenses. - -The core uses the ZLib license; the others are described below. - -License of DFHack -================= -https://github.com/peterix/dfhack -Copyright (c) 2009-2012 Petr Mrázek (peterix@gmail.com) +DFHack is distributed under the Zlib license, with some MIT- +and BSD-licensed components. These licenses protect your right +to use DFhack for any purpose, distribute copies, and so on. + +The core, plugins, scripts, and other DFHack code all use the +ZLib license unless noted otherwise. By contributing to DFHack, +authors release the contributed work under this license. + +DFHack also draws on several external packages. +Their licenses are summarised here and reproduced below. + +=============== ============= ================================================= +Component License Copyright +=============== ============= ================================================= +DFHack_ Zlib (c) 2009-2012, Petr Mrázek +clsocket_ BSD 3-clause (c) 2007-2009, CarrierLabs, LLC. +dirent_ MIT (c) 2006, Toni Ronkko +JSON.lua_ CC-BY-SA_ (c) 2010-2014, Jeffrey Friedl +jsoncpp_ MIT (c) 2007-2010, Baptiste Lepilleur +linenoise_ BSD 2-clause (c) 2010, Salvatore Sanfilippo & Pieter Noordhuis +lua_ MIT (c) 1994-2008, Lua.org, PUC-Rio. +luafilesystem_ MIT (c) 2003-2014, Kepler Project +protobuf_ BSD 3-clause (c) 2008, Google Inc. +tinythread_ Zlib (c) 2010, Marcus Geelnard +tinyxml_ Zlib (c) 2000-2006, Lee Thomason +UTF-8-decoder_ MIT (c) 2008-2010, Bjoern Hoehrmann +=============== ============= ================================================= + +.. _DFHack: https://github.com/DFHack/dfhack +.. _clsocket: https://github.com/DFHack/clsocket +.. _dirent: https://github.com/tronkko/dirent +.. _JSON.lua: http://regex.info/blog/lua/json +.. _jsoncpp: https://github.com/open-source-parsers/jsoncpp +.. _linenoise: http://github.com/antirez/linenoise +.. _lua: http://www.lua.org +.. _luafilesystem: https://github.com/keplerproject/luafilesystem +.. _protobuf: https://github.com/google/protobuf +.. _tinythread: http://tinythreadpp.bitsnbites.eu/ +.. _tinyxml: http://www.sourceforge.net/projects/tinyxml +.. _UTF-8-decoder: http://bjoern.hoehrmann.de/utf-8/decoder/dfa + +.. _CC-BY-SA: http://creativecommons.org/licenses/by/3.0/deed.en_US + + +Zlib License +============ +See https://en.wikipedia.org/wiki/Zlib_License :: This software is provided 'as-is', without any express or implied @@ -23,206 +62,21 @@ Copyright (c) 2009-2012 Petr Mrázek (peterix@gmail.com) redistribute it freely, subject to the following restrictions: 1. The origin of this software must not be misrepresented; you must - not claim that you wrote the original software. If you use this - software in a product, an acknowledgment in the product documentation - would be appreciated but is not required. + not claim that you wrote the original software. If you use this + software in a product, an acknowledgment in the product + documentation would be appreciated but is not required. 2. Altered source versions must be plainly marked as such, and - must not be misrepresented as being the original software. + must not be misrepresented as being the original software. 3. This notice may not be removed or altered from any source - distribution. - -clsocket license -================ -:: - - Copyright (c) 2007-2009 CarrierLabs, LLC. All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - - 2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the distribution. - 3. The name of the author may not be used to endorse or promote products - derived from this software without specific prior written permission. - - 4. The name "CarrierLabs" must not be used to - endorse or promote products derived from this software without - prior written permission. For written permission, please contact - mark@carrierlabs.com. - - THIS SOFTWARE IS PROVIDED BY MARK CARRIER ``AS IS'' AND ANY - EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR - PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL MARK CARRIER OR - ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT - NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; - LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) - ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED - OF THE POSSIBILITY OF SUCH DAMAGE. - -Lua license +MIT License =========== - -Lua is licensed under the terms of the MIT license reproduced below. -This means that Lua is free software and can be used for both academic -and commercial purposes at absolutely no cost. - -For details and rationale, see http://www.lua.org/license.html . - -:: - - Copyright (C) 1994-2008 Lua.org, PUC-Rio. - - Permission is hereby granted, free of charge, to any person obtaining a copy - of this software and associated documentation files (the "Software"), to deal - in the Software without restriction, including without limitation the rights - to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - copies of the Software, and to permit persons to whom the Software is - furnished to do so, subject to the following conditions: - - The above copyright notice and this permission notice shall be included in - all copies or substantial portions of the Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN - THE SOFTWARE. - -Protobuf license -================ -:: - - Copyright 2008, Google Inc. - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions are - met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above - copyright notice, this list of conditions and the following disclaimer - in the documentation and/or other materials provided with the - distribution. - * Neither the name of Google Inc. nor the names of its - contributors may be used to endorse or promote products derived from - this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - - Code generated by the Protocol Buffer compiler is owned by the owner - of the input file used when generating it. This code is not - standalone and requires a support library to be linked with it. This - support library is itself covered by the above license. - - -License of tinyxml (XML reader library) -======================================= -http://www.sourceforge.net/projects/tinyxml - -Original code, 2.0 and earlier, copyright 2000-2006 Lee Thomason (http://www.grinninglizard.com) -:: - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any - damages arising from the use of this software. - - Permission is granted to anyone to use this software for any - purpose, including commercial applications, and to alter it and - redistribute it freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must - not claim that you wrote the original software. If you use this - software in a product, an acknowledgment in the product documentation - would be appreciated but is not required. - - 2. Altered source versions must be plainly marked as such, and - must not be misrepresented as being the original software. - - 3. This notice may not be removed or altered from any source - distribution. - -tinythread license -================== -:: - - Copyright (c) 2010 Marcus Geelnard - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - - 3. This notice may not be removed or altered from any source - distribution. - -zlib license -============ - -:: - - Copyright (C) 1995-2010 Jean-loup Gailly and Mark Adler - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. - - -dirent.h - dirent API for Microsoft Visual Studio -================================================= +See https://en.wikipedia.org/wiki/MIT_License :: - Copyright (C) 2006 Toni Ronkko - Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including @@ -237,35 +91,27 @@ dirent.h - dirent API for Microsoft Visual Studio THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. - IN NO EVENT SHALL TONI RONKKO BE LIABLE FOR ANY CLAIM, DAMAGES OR - OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, - ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR - OTHER DEALINGS IN THE SOFTWARE. - - -linenoise.c -=========== -Parts of dfhack are based on linenoise: a line editing library against the -idea that a line editing lib needs to be 20,000 lines of C code. + IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY + CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, + TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE + SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -You can find the latest source code at http://github.com/antirez/linenoise +BSD Licenses +============ +See https://en.wikipedia.org/wiki/BSD_licenses :: - Copyright (c) 2010, Salvatore Sanfilippo - Copyright (c) 2010, Pieter Noordhuis - - All rights reserved. - Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: - * Redistributions of source code must retain the above copyright + 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. + 2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in + the documentation and/or other materials provided with the + distribution. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT @@ -279,91 +125,21 @@ You can find the latest source code at http://github.com/antirez/linenoise (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +``linenoise`` adds no further clauses. -UTF-8 Decoder -============= -See http://bjoern.hoehrmann.de/utf-8/decoder/dfa/ for details. -:: - - Copyright (c) 2008-2010 Bjoern Hoehrmann - - Permission is hereby granted, free of charge, to any person obtaining a copy - of this software and associated documentation files (the "Software"), to deal - in the Software without restriction, including without limitation the rights - to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - copies of the Software, and to permit persons to whom the Software is - furnished to do so, subject to the following conditions: - - The above copyright notice and this permission notice shall be included in all - copies or substantial portions of the Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, - WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN - CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - - -luafilesystem -============= -Parts of dfhack are based on luafilesystem: -:: - - Copyright (c) 2003-2014 Kepler Project. - - Permission is hereby granted, free of charge, to any person - obtaining a copy of this software and associated documentation - files (the "Software"), to deal in the Software without - restriction, including without limitation the rights to use, copy, - modify, merge, publish, distribute, sublicense, and/or sell copies - of the Software, and to permit persons to whom the Software is - furnished to do so, subject to the following conditions: - - The above copyright notice and this permission notice shall be - included in all copies or substantial portions of the Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, - EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF - MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND - NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS - BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN - ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN - CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - SOFTWARE. - -jsoncpp -======== -:: - - Copyright (c) 2007-2010 Baptiste Lepilleur - - Permission is hereby granted, free of charge, to any person - obtaining a copy of this software and associated documentation - files (the "Software"), to deal in the Software without - restriction, including without limitation the rights to use, copy, - modify, merge, publish, distribute, sublicense, and/or sell copies - of the Software, and to permit persons to whom the Software is - furnished to do so, subject to the following conditions: - - The above copyright notice and this permission notice shall be - included in all copies or substantial portions of the Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, - EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF - MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND - NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS - BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN - ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN - CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - SOFTWARE. +``protobuf`` adds the following clause:: + 3. Neither the name of Google Inc. nor the names of its + contributors may be used to endorse or promote products derived + from this software without specific prior written permission. -JSON.lua -======== -Copyright 2010-2014 Jeffrey Friedl, http://regex.info/blog/ +``clsocket`` adds the following clauses:: -Latest version: http://regex.info/blog/lua/json + 3. The name of the author may not be used to endorse or promote + products derived from this software without specific prior + written permission. -This code is released under a Creative Commons CC-BY "Attribution" License: -http://creativecommons.org/licenses/by/3.0/deed.en_US + 4. The name "CarrierLabs" must not be used to endorse or promote + products derived from this software without prior written + permission. For written permission, please contact + mark@carrierlabs.com From 3d9ba5712195d91de870bdd56975deead3fa5f6f Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Thu, 5 Nov 2015 21:40:09 +1100 Subject: [PATCH 51/91] Tidy and update Compile.rst Eg removed workarounds for closed OSX bug, etc. --- docs/Compile.rst | 142 +++++++++++++++++++++-------------------------- 1 file changed, 64 insertions(+), 78 deletions(-) diff --git a/docs/Compile.rst b/docs/Compile.rst index a55c2d44db..4a72f0dc45 100644 --- a/docs/Compile.rst +++ b/docs/Compile.rst @@ -2,14 +2,15 @@ Compiling DFHack ################ -.. important:: - You don't need to compile DFHack unless you're developing plugins or working on the core. - For users, modders, and authors of scripts it's better to download the latest release instead. +You don't need to compile DFHack unless you're developing plugins or working on the core. + +For users, modders, and authors of scripts it's better to download +and `install the latest release instead `. .. contents:: - :depth: 2 + :depth: 2 + -=================== How to get the code =================== DFHack doesn't have any kind of system of code snapshots in place, so you will have to @@ -33,22 +34,16 @@ To get the code:: If your version of git does not support the ``--recursive`` flag, you will need to omit it and run ``git submodule update --init`` after entering the dfhack directory. -If you just want to compile DFHack or work on it by contributing patches, it's quite -enough to clone from the read-only address instead:: - - git clone --recursive git://github.com/DFHack/dfhack.git - cd dfhack - If you want to get really involved with the development, create an account on Github, make a clone there and then use that as your remote repository instead. Detailed instructions are beyond the scope of this document. If you need help, join us on IRC (#dfhack channel on freenode). -=========== + Build types =========== -``cmake`` allows you to pick a build type by changing this -variable: ``CMAKE_BUILD_TYPE`` :: +``cmake`` allows you to pick a build type by changing the +``CMAKE_BUILD_TYPE`` environment variable:: cmake .. -DCMAKE_BUILD_TYPE:string=BUILD_TYPE @@ -58,19 +53,19 @@ Without specifying a build type or 'None', cmake uses the Valid and useful build types include 'Release', 'Debug' and 'RelWithDebInfo'. 'Debug' is not available on Windows. -===== + Linux ===== On Linux, DFHack acts as a library that shadows parts of the SDL API using LD_PRELOAD. Dependencies -============ +------------ DFHack is meant to be installed into an existing DF folder, so get one ready. For building, you need a 32-bit version of GCC. For example, to build DFHack on a 64-bit distribution like Arch, you'll need the multilib development tools and libraries. Alternatively, you might be able to use ``lxc`` to -`create a virtual 32-bit environment `_. +:forums:`create a virtual 32-bit environment <139553.msg5435310#msg5435310>`. Before you can build anything, you'll also need ``cmake``. It is advisable to also get ``ccmake`` on distributions that split the cmake package into multiple parts. @@ -81,11 +76,13 @@ You should be able to find them in your distro repositories (on Arch linux To build Stonesense, you'll also need OpenGL headers. -Some additional dependencies for other distros are listed on the -`wiki `_. +On 64-bit Ubuntu, ``apt-get install zlib1g-dev:i386 libxml-libxml-perl libxml-libxslt-perl``. +On 32-bit Ubuntu, ``apt-get install zlib1g-dev libxml-libxml-perl libxml-libxslt-perl``. +Debian-derived distros should have similar requirements. + Build -===== +----- Building is fairly straightforward. Enter the ``build`` folder (or create an empty folder in the DFHack directory to use instead) and start the build like this:: @@ -108,9 +105,9 @@ extra options. You can also use a cmake-friendly IDE like KDevelop 4 or the cmake-gui program. -Fixing the libstdc++ version bug -================================ +The libstdc++ version bug +~~~~~~~~~~~~~~~~~~~~~~~~~ When compiling dfhack yourself, it builds against your system libc. When Dwarf Fortress runs, it uses a libstdc++ shipped with the binary, which comes from GCC 4.5 and is incompatible with code compiled with newer GCC versions. @@ -127,66 +124,69 @@ to your system lib and everything will work fine:: Alternatively, this issue can be avoided by compiling DFHack with GCC 4.5. -======== + Mac OS X ======== - DFHack functions similarly on OS X and Linux, and the majority of the information above regarding the build process (cmake and make) applies here as well. -* If you are building on 10.6, please read the subsection below titled "Snow Leopard Changes" FIRST. -* If you are building on 10.10+, read the "Yosemite Changes" subsection before building. +If you have issues building on OS X Yosemite (or above), try definining the +following environment variable:: -1. Download and unpack a copy of the latest DF -2. Install Xcode from Mac App Store -3. Open Xcode, go to Preferences > Downloads, and install the Command Line Tools. -4. Install dependencies + export MACOSX_DEPLOYMENT_TARGET=10.9 + +#. Download and unpack a copy of the latest DF +#. Install Xcode from Mac App Store +#. Open Xcode, go to Preferences > Downloads, and install the Command Line Tools. +#. Install dependencies - Option 1: Using Homebrew: + Using `Homebrew `_:: - * `Install Homebrew `_ and run: - * ``brew tap homebrew/versions`` - * ``brew install git`` - * ``brew install cmake`` - * ``brew install gcc45`` + brew tap homebrew/versions + brew install git + brew install cmake + brew install gcc45 - Option 2: Using MacPorts: + Using `MacPorts `_:: - * `Install MacPorts `_ - * Run ``sudo port install gcc45 +universal cmake +universal git-core +universal`` - This will take some time—maybe hours, depending on your machine. + sudo port install gcc45 +universal cmake +universal git-core +universal - At some point during this process, it may ask you to install a Java environment; let it do so. + Macports will take some time - maybe hours. At some point it may ask + you to install a Java environment; let it do so. -5. Install perl dependencies +#. Install perl dependencies 1. ``sudo cpan`` If this is the first time you've run cpan, you will need to go through the setup process. Just stick with the defaults for everything and you'll be fine. + If you are running Snow Leopard or later, open a separate Terminal window and run:: + + sudo ln -s /usr/include/libxml2/libxml /usr/include/libxml + 2. ``install XML::LibXML`` 3. ``install XML::LibXSLT`` -6. Get the dfhack source:: +#. Get the dfhack source:: git clone --recursive https://github.com/DFHack/dfhack.git cd dfhack -7. Set environment variables: +#. Set environment variables: - Homebrew (if installed elsewhere, replace /usr/local with ``$(brew --prefix)``):: + Homebrew (if installed elsewhere, replace /usr/local with ``$(brew --prefix)``):: export CC=/usr/local/bin/gcc-4.5 export CXX=/usr/local/bin/g++-4.5 - Macports:: + Macports:: export CC=/opt/local/bin/gcc-mp-4.5 export CXX=/opt/local/bin/g++-mp-4.5 -8. Build dfhack:: +#. Build dfhack:: mkdir build-osx cd build-osx @@ -195,34 +195,14 @@ as well. make install -Snow Leopard Changes -==================== - -1. Add a step 6.2a (before Install XML::LibXSLT):: - In a separate Terminal window or tab, run: - ``sudo ln -s /usr/include/libxml2/libxml /usr/include/libxml`` - -2. Add a step 7a (before building):: - In /library/LuaTypes.cpp, change line 467 to - ``int len = strlen((char*)ptr);`` - -Yosemite Changes -================ - -If you have issues building on OS X Yosemite (or above), try definining the -following environment variable:: - - export MACOSX_DEPLOYMENT_TARGET=10.9 - -======= Windows ======= On Windows, DFHack replaces the SDL library distributed with DF. Dependencies -============ -First, you need ``cmake``. Get the win32 installer version from the official -site: http://www.cmake.org/cmake/resources/software.html +------------ +First, you need ``cmake``. Get the win32 installer version from +`the official site `_. It has the usual installer wizard. Make sure you let it add its binary folder to your binary search PATH so the tool can be later run from anywhere. @@ -241,24 +221,30 @@ install libxml and libxslt for it instead. Strawberry perl works though and has all the required packages. Build -===== -There are several different batch files in the ``build`` folder along with a script that's used for picking the DF path. +----- +There are several different batch files in the ``build`` folder along +with a script that's used for picking the DF path. -First, run set_df_path.vbs and point the dialog that pops up at your DF folder that you want to use for development. +First, run set_df_path.vbs and point the dialog that pops up at your +DF folder that you want to use for development. Next, run one of the scripts with ``generate`` prefix. These create the MSVC solution file(s): * ``all`` will create a solution with everything enabled (and the kitchen sink). -* ``gui`` will pop up the cmake gui and let you pick and choose what to build. This is probably what you want most of the time. Set the options you are interested in, then hit configure, then generate. More options can appear after the configure step. -* ``minimal`` will create a minimal solution with just the bare necessities - the main library and standard plugins. +* ``gui`` will pop up the cmake gui and let you pick and choose what to build. + This is probably what you want most of the time. Set the options you are interested + in, then hit configure, then generate. More options can appear after the configure step. +* ``minimal`` will create a minimal solution with just the bare necessities - + the main library and standard plugins. Then you can either open the solution with MSVC or use one of the msbuild scripts: -* Scripts with ``build`` prefix will only build. +* Scripts with ``build`` prefix will only build DFHack. * Scripts with ``install`` prefix will build DFHack and install it to the previously selected DF path. * Scripts with ``package`` prefix will build and create a .zip package of DFHack. When you open the solution in MSVC, make sure you never use the Debug builds. Those aren't binary-compatible with DF. If you try to use a debug build with DF, you'll only get crashes. -So pick either Release or RelWithDebInfo build and build the INSTALL target. -The ``debug`` scripts actually do RelWithDebInfo builds. +For this reason the Windows "debug" scripts actually do RelWithDebInfo builds, +so pick either Release or RelWithDebInfo build and build the INSTALL target. + From 0ba6f73dcd5944dd7f9d80252b9e2a4d4a01466c Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Fri, 6 Nov 2015 00:58:18 +1100 Subject: [PATCH 52/91] Add Introduction.rst, list builtins in Core.rst The Introduction is the first page to read, and thus explains what DFHack is, installation, basic use, and troubleshooting. This frees up Core.rst for a detailed list of builtin commands (meant to be complete, but I might have missed some), some other key commands, and a discussion of init files. I also put the random notes that don't fit anywhere at the bottom of this file. --- docs/Core.rst | 529 ++++++++++++++++++++++++------------------ docs/Introduction.rst | 107 +++++++++ 2 files changed, 414 insertions(+), 222 deletions(-) create mode 100644 docs/Introduction.rst diff --git a/docs/Core.rst b/docs/Core.rst index 2ad51db702..fda08b6764 100644 --- a/docs/Core.rst +++ b/docs/Core.rst @@ -1,152 +1,197 @@ +.. _dfhack-core: + ########### DFHack Core ########### +DFHack commands can be implemented in three ways, all of which +are used in the same way: + +:builtin: commands are implemented by the core of DFHack, and quite rare. + +:plugins: are stored in ``hack/plugins/`` and must be compiled with the + same version of DFHack. They are less flexible than scripts, + but used for complex or ongoing tasks becasue they run faster. + +:scripts: are Ruby or Lua scripts stored in ``hack/scripts/``. + Because they don't need to be compiled, scripts are + more flexible about versions, and easier to distribute. + Most third-party DFHack addons are scripts. + + .. contents:: -============== -Getting DFHack -============== -The project is currently hosted at http://www.github.com/ +Built-in Commands +================= +The following commands are provided by the 'core' components +of DFhack, rather than plugins or scripts. + + +.. _cls: + +cls +--- +Clear the terminal. Does not delete command history. + + +.. _die: + +die +--- +Instantly kills DF without saving. + + +.. _disable: + +.. _enable: + +enable +------ +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 +number of them have to be enabled globally, and the init file is the +right place to do it. + +Most such plugins or scripts support the built-in ``enable`` and ``disable`` +commands. Calling them at any time without arguments prints a list +of enabled and disabled plugins, and shows whether that can be changed +through the same commands. -Recent releases are available in source and binary formats `on the releases -page`_, while the binaries for releases 0.40.15-r1 to 0.34.11-r4 are on DFFD_. -Even older versions are available here_. +To enable or disable plugins that support this, use their names as +arguments for the command:: -.. _`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 + enable manipulator search -All new releases are announced in `the bay12 forums thread`_, which is also a -good place for discussion and questions. -.. _`the Bay12 DFHack thread`: -.. _`the bay12 forums thread`: http://www.bay12forums.com/smf/index.php?topic=139553 +.. _fpause: -If this sounds too complicated, you might prefer to `get a Starter Pack`_. -These are packages for new players or those who don't want to set up everything -themselves, and are available - with DFHack configured - for all OSes. +fpause +------ +Forces DF to pause. This is useful when your FPS drops below 1 and you lose +control of the game. -.. _`get a Starter Pack`: http://dwarffortresswiki.org/index.php/Utility:Lazy_Newb_Pack -Compatibility -============= -DFHack is available for Windows (XP or later), Linux (any modern distribution), -or OS X (10.6.8 to 10.9). +.. _help: -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. +help +---- +Most commands support using the ``help `` built-in command +to retrieve further help without having to look at this document. +``? `` and ``man `` are aliases. -On Windows, DFHack is compatible with the SDL version of DF, but not the legacy version. +Some commands (including many scripts) instead take ``help`` or ``?`` +as an option on their command line - ie `` help``. -It is also possible to use the Windows DFHack with Wine under Linux and OS X. -Installation/Removal -==================== -Installing DFhack involves copying files into your DF folder. -Copy the files from a release archive so that: +.. _hide: -* On Windows, ``SDL.dll`` is replaced -* On Linux or OSX, the ``dfhack`` script is placed in the same folder as the ``df`` script +hide +---- +Hides the DFHack terminal window. Only available on Windows. -Uninstalling is basically the same, in reverse: -* On Windows, first delete ``SDL.dll`` and rename ``SDLreal.dll`` to ``SDL.dll``, - then remove the other DFHack files -* On Linux, remove the DFHack files. +.. _keybinding: -The stonesense plugin might require some additional libraries on Linux. +keybinding +---------- +To set keybindings, use the built-in ``keybinding`` command. Like any other +command it can be used at any time from the console, but bindings are not +remembered between runs of the game unless re-created in `dfhack.init`. -If any of the plugins or dfhack itself refuses to load, check the ``stderr.log`` -file created in your DF folder. +Currently, any combinations of Ctrl/Alt/Shift with A-Z, 0-9, or F1-F12 are supported. +Possible ways to call the command: -=============== -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 -the console. +``keybinding list `` + List bindings active for the key combination. +``keybinding clear ...`` + Remove bindings for the specified keys. +``keybinding add "cmdline" "cmdline"...`` + Add bindings for the specified key. +``keybinding set "cmdline" "cmdline"...`` + Clear, and then add bindings for the specified key. -**NOTE**: The ``dfhack-run`` executable is there for calling DFHack commands in -an already running DF+DFHack instance from external OS scripts and programs, -and is *not* the way how you use DFHack normally. +The ```` parameter above has the following *case-sensitive* syntax:: -DFHack has a lot of features, which can be accessed by typing commands in the -console, or by mapping them to keyboard shortcuts. Most of the newer and more -user-friendly tools are designed to be at least partially used via the latter -way. + [Ctrl-][Alt-][Shift-]KEY[@context[|context...]] -In order to set keybindings, you have to create a text configuration file -called ``dfhack.init``; the installation comes with an example version called -``dfhack.init-example``, which is fully functional, covers all of the recent -features and can be simply renamed to ``dfhack.init``. You are encouraged to look -through it to learn which features it makes available under which key combinations. +where the *KEY* part can be any recognized key and [] denote optional parts. -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 -(so, make sure you start from a terminal). Basic interaction with dfhack -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. +When multiple commands are bound to the same key combination, DFHack selects +the first applicable one. Later ``add`` commands, and earlier entries within one +``add`` command have priority. Commands that are not specifically intended for use +as a hotkey are always considered applicable. -The command line has some nice line editing capabilities, including history -that's preserved between different runs of DF (use up/down keys to go through -the history). +The ``context`` part in the key specifier above can be used to explicitly restrict +the UI state where the binding would be applicable. If called without parameters, +the ``keybinding`` command among other things prints the current context string. -The second way to interact with DFHack is to bind the available commands -to in-game hotkeys. The old way to do this is via the hotkey/zoom menu (normally -opened with the ``h`` key). Binding the commands is done by assigning a command as -a hotkey name (with ``n``). +Only bindings with a ``context`` tag that either matches the current context fully, +or is a prefix ending at a ``/`` boundary would be considered for execution, i.e. +when in context ``foo/bar/baz``, keybindings restricted to any of ``@foo/bar/baz``, +``@foo/bar``, ``@foo`` or none will be active. -A new and more flexible way is the keybinding command in the dfhack console. -However, bindings created this way are not automatically remembered between runs -of the game, so it becomes necessary to use the dfhack.init file to ensure that -they are re-created every time it is loaded. +Multiple contexts can be specified by separating them with a +pipe (``|``) - for example, ``@foo|bar|baz/foo`` would match +anything under ``@foo``, ``@bar``, or ``@baz/foo``. Interactive commands like `liquids` cannot be used as hotkeys. -Many commands come from plugins, which are stored in ``hack/plugins/`` -and must be compiled with the same version of DFHack. Others come -from scripts, which are stored in ``hack/scripts``. Scripts are much -more flexible about versions, and easier to distribute - so most third-party -DFHack addons are scripts. -Something doesn't work, help! -============================= -First, don't panic :) +.. _kill-lua: -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. +kill-lua +-------- +Stops any currently-running Lua scripts. By default, scripts can +only be interrupted every 256 instructions. Use ``kill-lua force`` +to interrupt the next instruction. -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 -`_. -============= -Core 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. +.. _load: +.. _unload: +.. _reload: -If the first non-whitespace character of a line is ``#``, the line is treated -as a comment, i.e. a silent no-op command. +load +---- +``load``, ``unload``, and ``reload`` control whether a plugin is loaded +into memory - note that plugins are loaded but disabled unless you do +something. Usage:: -When reading commands from dfhack.init or with the ``script`` command, if the final -character on a line is a backslash then the next uncommented line is considered a -continuation of that line, with the backslash deleted. Commented lines are skipped, -so it is possible to comment out parts of a command with the ``#`` character. + load|unload|reload PLUGIN|all + +Allows dealing with plugins individually by name, or all at once. + + +.. _ls: + +ls +-- +``ls`` does not list files like the Unix command, but rather +available commands - first built in commands, then plugins, +and scripts at the end. Usage: + +:ls -a: Also list scripts in subdirectories of ``hack/scripts/``, + which are generally not intended for direct use. +:ls : List subcommands for the given plugin. + + +.. _plug: + +plug +---- +Lists available plugins (*not* commands implemented by plugins). + +``plug [PLUGIN|v]`` - list plugin state and detailed description. + + +.. _rb_eval: + +rb_eval +------- +Evaluate the following arguments as a ruby string. Best used as +``:rb_eval [string]``, for the special parsing mode: If the first non-whitespace character is ``:``, the command is parsed in a special alternative mode: first, non-whitespace characters immediately following the ``:`` @@ -157,160 +202,200 @@ The following two command lines are exactly equivalent:: :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. -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`` or ``?`` as an option on their command line. +.. _sc-script: -.. note:: +sc-script +--------- +Allows additional scripts to be run when certain events occur +(similar to onLoad*.init scripts) - Some tools work by displaying dialogs or overlays in the game window. - In order to avoid confusion, these tools display the word "DFHack" while active. If they - merely add keybinding hints to existing screens, they use red instead of green for the key. +.. _script: +script +------ +Reads a text file, and runs each line as a DFHack command +as if it had been typed in by the user - treating the +input like `an init file `. -Init files -========== -DFHack allows users to automatically run commonly-used DFHack commands when DF is first -loaded, when a game is loaded, and when a game is unloaded. +Some other tools, such as `autobutcher` and `workflow`, export +their settings as the commands to create them - which are later +loaded with ``script`` -Init scripts function the same way they would if the user manually typed in their contents, -but are much more convenient. If your DF folder contains at least one file with a name -following the format ``dfhack*.init`` where ``*`` is a placeholder for any string (including -the empty string), then all such files are executed in alphabetical order as init scripts when -DF is first loaded. -If your DF folder does not contain any such files, then DFHack will execute ``dfhack.init-example`` -as an example of useful commands to be run automatically. If you want DFHack to do nothing on -its own, then create an empty ``dfhack.init`` file in the main DF directory, or delete ``dfhack.init-example``. +.. _show: -The file ``dfhack.init-example`` is included as an example for users to follow if they need DFHack -command executed automatically. We recommend modifying or deleting ``dfhack.init-example`` as -its settings will not be optimal for all players. +show +---- +Shows the terminal window after it has been `hidden `. +Only available on Windows. You'll need to use it from a +`keybinding` set beforehand, or the in-game `command-prompt`. -In order to facilitate savegave portability, mod merging, and general organization of init files, -DFHack supports multiple init files both in the main DF directory and save-specific init files in -the save folders. -DFHack looks for init files in three places. -It will look for them in the main DF directory, and in ``data/save/_____/raw`` and -``data/save/_____/raw/objects`` where ``_____`` is the name of the current savegame. +.. important-commands: -When a game is loaded, DFHack looks for files of the form ``onLoad*.init``, where -``*`` can be any string, including the empty string. +Other Important Commands +======================== -When a game is unloaded, DFHack looks for files of the form ``onUnload*.init``. Again, -these files may be in any of the above three places. All matching init files will be -executed in alphebetical order. +.. _command-prompt: -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 most useful -in the DFHack init file. +command-prompt +-------------- +An in-game DFHack terminal, where you can enter other commands. +Best used from a keybinding; by default :kbd:`Ctrl`:kbd:`Shift`:kbd:`P`. -Currently, any combinations of Ctrl/Alt/Shift with A-Z, 0-9, or F1-F12 are supported. +Usage: ``command-prompt [entry]`` -Possible ways to call the command: +If called with an entry, it starts with that text filled in. +Most useful for developers, who can set a keybinding to open +a laungage interpreter for lua or Ruby by starting with the +`:lua ` or `:rb_eval ` commands. -``keybinding list `` - List bindings active for the key combination. -``keybinding clear ...`` - Remove bindings for the specified keys. -``keybinding add "cmdline" "cmdline"...`` - Add bindings for the specified key. -``keybinding set "cmdline" "cmdline"...`` - Clear, and then add bindings for the specified key. +Otherwise somewhat similar to `gui/quickcmd`. -The ```` parameter above has the following *case-sensitive* syntax:: +.. image:: images/command-prompt.png - [Ctrl-][Alt-][Shift-]KEY[@context[|context...]] -where the *KEY* part can be any recognized key and [] denote optional parts. +.. _hotkeys: -When multiple commands are bound to the same key combination, DFHack selects -the first applicable one. Later ``add`` commands, and earlier entries within one -``add`` command have priority. Commands that are not specifically intended for use -as a hotkey are always considered applicable. +hotkeys +------- +Opens an in-game screen showing which DFHack keybindings are +active in the current context. -The ``context`` part in the key specifier above can be used to explicitly restrict -the UI state where the binding would be applicable. If called without parameters, -the ``keybinding`` command among other things prints the current context string. -Only bindings with a ``context`` tag that either matches the current context fully, -or is a prefix ending at a ``/`` boundary would be considered for execution, i.e. -for context ``foo/bar/baz``, possible matches are any of ``@foo/bar/baz``, ``@foo/bar``, -``@foo`` or none. Multiple contexts can be specified by separating them with a -pipe (``|``) - for example, ``@foo|bar|baz/foo``. +.. image:: images/hotkeys.png -Hotkeys -======= -Opens an in-game screen showing DFHack keybindings that are active in the current context. +Type ``hotkeys`` into the DFHack console to open the screen, +or bind the command to a globally active hotkey. The default +keybinding is :kbd:`Ctrl`:kbd:`F1`. See also `hotkey-notes`. -.. image:: images/hotkeys.png +lua +--- +The `lua` script provides an interactive interpreter, allows +loading and saving of lua files, or runs a single line of code. -Type ``hotkeys`` into the DFHack console to open the screen, or bind the command to a -globally active hotkey. The default keybinding is ``Ctrl-F1``. +multicmd +-------- +The `multicmd` script calls many commands in one line. -.. _command-prompt: +.. _nopause: -In-game command prompt -====================== -The ``command-prompt`` plugin adds an in-game DFHack terminal, where you -can enter other commands. It's default keybinding is Ctrl-Shift-P. +nopause +------- +Disables pausing (both manual and automatic) with the exception of pause forced +by `reveal` ``hell``. This is nice for digging under rivers. -A one line command prompt in df. Same as entering command into dfhack console. Best -used as a keybinding. Can be called with optional "entry" that will start prompt with -that pre-filled. +quicksave +--------- +The `quicksave` script saves the game immediately without exiting. -.. image:: images/command-prompt.png +repeat +------ +The `repeat` script sets a command to be called regularly. -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 -number of them have to be enabled globally, and the init file is the -right place to do it. -Most such plugins or scripts support the built-in ``enable`` and ``disable`` -commands. Calling them at any time without arguments prints a list -of enabled and disabled plugins, and shows whether that can be changed -through the same commands. +.. _init-files: -To enable or disable plugins that support this, use their names as -arguments for the command:: +Init Files +========== +DFHack allows users to automatically run commonly-used DFHack commands +when DF is first loaded, when a game is loaded, and when a game is unloaded. - enable manipulator search +Init scripts function the same way they would if the user manually typed +in their contents, but are much more convenient. In order to facilitate +savegave portability, mod merging, and general organization of init files, +DFHack supports multiple init files both in the main DF directory and +save-specific init files in the save folders. +DFHack looks for init files in three places each time they could be run: -Game progress -============= +#. The main DF directory +#. :file:`data/save/{world}/raw`, where ``world`` is the current save, and +#. :file:`data/save/{world}/raw/objects` -die ---- -Instantly kills DF without saving. +When reading commands from dfhack.init or with the `script` command, if the final +character on a line is a backslash then the next uncommented line is considered a +continuation of that line, with the backslash deleted. Commented lines are skipped, +so it is possible to comment out parts of a command with the ``#`` character. -quicksave ---------- -Save immediately, without exiting. Only available in fortress mode. -forcepause ----------- -Forces DF to pause. This is useful when your FPS drops below 1 and you lose -control of the game. Activate with ``forcepause 1``; deactivate with ``forcepause 0``. +.. _dfhack.init: -.. _`hide, show`: +dfhack*.init +------------ +If your DF folder contains at least one file named ``dfhack*.init`` +(where ``*`` is a placeholder for any string), then all such files +are executed in alphabetical order when DF is first started. -hide / show ------------ -Hides or shows the DFHack terminal window, respectively. To use ``show``, use -the in-game console (default keybinding ``Ctrl-Shift-P``). Only available on Windows. +DFHack is distributed with :download:`/dfhack.init-example` as an example +with an up-to-date collection of basic commands; mostly setting standard +keybindings and `enabling ` plugins. You are encouraged to look +through this file to learn which features it makes available under which +key combinations. You may also customise it and rename it to ``dfhack.init``. -nopause -------- -Disables pausing (both manual and automatic) with the exception of pause forced -by 'reveal hell'. This is nice for digging under rivers. +If your DF folder does not contain any ``dfhack*.init`` files, the example +will be run as a fallback. + +These files are best used for keybindings and enabling persistent plugins +which do not require a world to be loaded. + + +.. _onLoad.init: + +onLoad*.init +------------ +When a world is loaded, DFHack looks for files of the form ``onLoad*.init``, +where ``*`` can be any string, including the empty string. + +All matching init files will be executed in alphebetical order. +A world being loaded can mean a fortress, an adventurer, or legends mode. + +These files are best used for non-persistent commands, such as setting +a `fix ` script to run on `repeat`. + + +.. _onUnload.init: + +onUnload*.init +-------------- +When a world is unloaded, DFHack looks for files of the form ``onUnload*.init``. +Again, these files may be in any of the above three places. +All matching init files will be executed in alphebetical order. + +Modders often use such scripts to disable tools which should not affect +an unmodded save. + + +Other init files +---------------- +* Any lua script named ``raw/init.d/*.lua``, in the save or main DF + directory, will be run when any world or that save is loaded. + + +Miscellaneous Notes +=================== +This section is for odd but important notes that don't fit anywhere else. + +* The ``dfhack-run`` executable is there for calling DFHack commands in + an already running DF+DFHack instance from external OS scripts and programs, + and is *not* the way how you use DFHack normally. + +* If a DF hotkey (:kbd:`H`) is named with a DFHack command, pressing + the corresponding :kbd:`Fx` button will run that command, instead of + zooming to the set location. + +* The command line has some nice line editing capabilities, including history + that's preserved between different runs of DF (use up/down keys to go through + the history). + +* To include whitespace in the argument/s to some command, quote it in + double quotes. To include a double quote character, use ``\"``. + +* The binaries for 0.40.15-r1 to 0.34.11-r4 are on DFFD_. + Older versions are available here_. + + .. _DFFD: http://dffd.bay12games.com/search.php?string=DFHack&id=15&limit=1000 + .. _here: http://dethware.org/dfhack/download diff --git a/docs/Introduction.rst b/docs/Introduction.rst new file mode 100644 index 0000000000..f0fc0a0bf3 --- /dev/null +++ b/docs/Introduction.rst @@ -0,0 +1,107 @@ +.. _introduction: + +######################### +Introduction and Overview +######################### + +DFHack is a Dwarf Fortress memory access library, distributed with +a wide variety of useful scripts and plugins. + +The project is currently hosted at https://www.github.com/DFHack/dfhack, +and can be downloaded from `the releases page +`_. + +All new releases are announced in :forums:`the bay12 forums thread <139553>`, +which is also a good place for discussion and questions. + +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 `modtools` +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:: + + +.. _installing: + +Installing DFHack +================= +New players are encouraged to :wiki:`get a pack with DFHack preinstalled +`. + +DFHack is available for the SDL version of Dwarf Frtress on Windows, +any modern Linux distribution, and OS X (10.6.8 to 10.9). +It is possible to use Windows DF+DFHack under Wine on Linux or OS X. + +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 +of DFHack built for the target version of DF. + +Installing DFhack involves copying files from a release archive +into your DF folder, so that: + +* On Windows, ``SDL.dll`` is replaced +* On Linux or OSX, the ``dfhack`` script is placed in the same folder as the ``df`` script + +Uninstalling is basically the same, in reverse: + +* On Windows, replace ``SDL.dll`` with ``SDLreal.dll``, then remove the DFHack files. +* On Linux or OSX, remove the DFHack files. + + +Getting started +=============== +DFHack basically extends DF with something similar to the +console found in many PC games. + +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 +the console. + +* Basic interaction with dfhack involves entering commands into the console. + To learn what commands are available, you can keep reading this documentation + or skip ahead and use the `ls` and `help` commands. + +* Another way to interact with DFHack is to set in-game `keybindings ` + for certain commands. Many of the newer and user-friendly tools are designed + to be used this way. + +* Commands can also run at startup via `init files `, + on in batches at other times with the `script` command. + +* Finally, some commands are persistent once enabled, and will sit in the + background managing or changing some aspect of the game if you `enable` them. + + +.. _troubleshooting: + +Troubleshooting +=============== +Don't panic! Even if you need this section, it'll be OK :) + +If something goes wrong, check the log files in DF's folder +(``stderr.log`` and ``stdout.log``). Looking at these might help you - +or someone else - solve the problem. Take screenshots of any weird +error messages, and take notes on what you did to cause them. + +If the search function in this documentation isn't enough and +:wiki:`the DF Wiki <>` hasn't helped, try asking in: + +- the `#dfhack IRC channel on freenode `_ +- the :forums:`Bay12 DFHack thread <139553>` +- the `/r/dwarffortress `_ questions thread +- the thread for the mod or Starter Pack you're using (if any) + From 3cc0b34d73d280f1bdef2cb45a642e40adc858f5 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Fri, 6 Nov 2015 00:59:48 +1100 Subject: [PATCH 53/91] Clean up other docs to match Some deduplication in Scripts and Plugins, links in NEWS, add content and link to files in index. --- NEWS.rst | 4 ++-- docs/Plugins.rst | 8 ++------ docs/Scripts.rst | 16 +++------------- index.rst | 13 +++++++++++-- 4 files changed, 18 insertions(+), 23 deletions(-) diff --git a/NEWS.rst b/NEWS.rst index e966eda6ac..53be4c1490 100644 --- a/NEWS.rst +++ b/NEWS.rst @@ -197,8 +197,8 @@ Lua New Internal Commands --------------------- -- `hide, show`: hide and show the console on Windows -- sc-script: Allows additional scripts to be run when certain events occur (similar to onLoad*.init scripts) +- `hide`, `show`: hide and show the console on Windows +- `sc-script`: Allows additional scripts to be run when certain events occur (similar to onLoad*.init scripts) New Plugins ----------- diff --git a/docs/Plugins.rst b/docs/Plugins.rst index 8423672833..192bbb36db 100644 --- a/docs/Plugins.rst +++ b/docs/Plugins.rst @@ -6,7 +6,8 @@ DFHack plugins are the commands, that are compiled with a specific version. They can provide anything from a small keybinding, to a complete overhaul of game subsystems or the entire renderer. -Most are listed here, hopefully organised in a way you will find useful. +Most commands offered by plugins are listed here, +hopefully organised in a way you will find useful. .. contents:: :depth: 4 @@ -351,11 +352,6 @@ UI Upgrades When that is not appropriate because they merely add keybinding hints to existing DF screens, they deliberately use red instead of green for the key. -.. _hotkeys: - -hotkeys -======= -Shows the DFHack keybindings active on the current screen. .. _manipulator: diff --git a/docs/Scripts.rst b/docs/Scripts.rst index 87eeaf666e..0e6ef415c7 100644 --- a/docs/Scripts.rst +++ b/docs/Scripts.rst @@ -2,20 +2,10 @@ DFHack Scripts ############## -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. +Lua or ruby scripts placed in the :file:`hack/scripts/` directory +are considered for execution as if they were native DFHack commands. -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 -or from the init file. See the page for each type for details. - -``kill-lua`` stops any currently-running Lua scripts. By default, scripts can -only be interrupted every 256 instructions. Use ``kill-lua force`` to interrupt -the next instruction. - -The following pages document all the standard DFHack scripts. +The following pages document all the scripts in the DFHack standard library. .. toctree:: :maxdepth: 2 diff --git a/index.rst b/index.rst index a93660db3b..7f3e815a31 100644 --- a/index.rst +++ b/index.rst @@ -4,8 +4,15 @@ Welcome to DFHack's documentation! Introduction ============ -DFHack is a Dwarf Fortress memory access library, distributed with scripts -and plugins implementing a wide variety of useful functions and tools. +DFHack is a Dwarf Fortress memory access library, distributed with +a wide variety of useful scripts and plugins. + +The project is currently hosted at https://www.github.com/DFHack/dfhack, +and can be downloaded from `the releases page +`_. + +All new releases are announced in :forums:`the bay12 forums thread <139553>`, +which is also a good place for discussion and questions. For users, it provides a significant suite of bugfixes and interface enhancements by default, and more can be enabled. There are also many tools @@ -29,6 +36,7 @@ User Manual .. toctree:: :maxdepth: 2 + docs/Introduction docs/Core docs/Plugins docs/Scripts @@ -53,4 +61,5 @@ For Developers docs/Compile docs/Lua API library/xml/SYNTAX + library/xml/how-to-update docs/Binpatches From 8412a496dd4377a68bdc7c4572f9327c8888a217 Mon Sep 17 00:00:00 2001 From: lethosor Date: Thu, 5 Nov 2015 19:09:14 -0500 Subject: [PATCH 54/91] Remove extra check for "type" command --- library/Core.cpp | 1 - 1 file changed, 1 deletion(-) diff --git a/library/Core.cpp b/library/Core.cpp index 2d537c1b35..130ec222db 100644 --- a/library/Core.cpp +++ b/library/Core.cpp @@ -553,7 +553,6 @@ string getBuiltinCommand(std::string cmd) cmd == "enable" || cmd == "disable" || cmd == "plug" || - cmd == "type" || cmd == "keybinding" || cmd == "fpause" || cmd == "cls" || From 5c4e28dbffceba0f7e8e3eb4d315274216eda1c0 Mon Sep 17 00:00:00 2001 From: lethosor Date: Thu, 5 Nov 2015 19:09:35 -0500 Subject: [PATCH 55/91] Fix initial cursor position with initial entry --- plugins/command-prompt.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/command-prompt.cpp b/plugins/command-prompt.cpp index f762ed713a..2ac4d3af95 100644 --- a/plugins/command-prompt.cpp +++ b/plugins/command-prompt.cpp @@ -60,7 +60,7 @@ class viewscreen_commandpromptst : public dfhack_viewscreen { { show_fps=gps->display_frames; gps->display_frames=0; - cursor_pos = 0; + cursor_pos = entry.size(); frame = 0; history_idx = command_history.size(); if (history_idx > 0) From 8a0f54aef3c4f74425aa62a53e84fc62756534e8 Mon Sep 17 00:00:00 2001 From: lethosor Date: Thu, 5 Nov 2015 19:37:37 -0500 Subject: [PATCH 56/91] Only install HTML docs --- CMakeLists.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index fb6dd52bb6..08962a4d3a 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -236,8 +236,8 @@ if (BUILD_DOCS) add_custom_command(TARGET dfhack_docs POST_BUILD COMMAND ${CMAKE_COMMAND} -E touch ${SPHINX_OUTPUT}) - install(DIRECTORY ${dfhack_SOURCE_DIR}/docs - DESTINATION ${DFHACK_USERDOC_DESTINATION} + install(DIRECTORY ${dfhack_SOURCE_DIR}/docs/html/ + DESTINATION ${DFHACK_USERDOC_DESTINATION}/docs ) install(FILES "README.html" DESTINATION "${DFHACK_DATA_DESTINATION}") endif() From 7fc2a226da6a2862094f4bd881550c68501d69b7 Mon Sep 17 00:00:00 2001 From: lethosor Date: Thu, 5 Nov 2015 19:37:51 -0500 Subject: [PATCH 57/91] Add missing backtick --- docs/Plugins.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Plugins.rst b/docs/Plugins.rst index 8423672833..9ea4b309fd 100644 --- a/docs/Plugins.rst +++ b/docs/Plugins.rst @@ -526,7 +526,7 @@ Implements several confirmation dialogs for potentially destructive actions Usage: -:enable confirm: Enable all confirmations; alias ``confirm enable all`. +:enable confirm: Enable all confirmations; alias ``confirm enable all``. Replace with ``disable`` to disable. :confirm help: List available confirmation dialogues. :confirm enable option1 [option2...]: From ac4927d40973d950e41446b83a0f59c141906794 Mon Sep 17 00:00:00 2001 From: lethosor Date: Thu, 5 Nov 2015 19:38:47 -0500 Subject: [PATCH 58/91] Update scripts/3rdparty/* (docs) --- scripts/3rdparty/lethosor | 2 +- scripts/3rdparty/maxthyme | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/scripts/3rdparty/lethosor b/scripts/3rdparty/lethosor index 8874945020..0b8303f6b0 160000 --- a/scripts/3rdparty/lethosor +++ b/scripts/3rdparty/lethosor @@ -1 +1 @@ -Subproject commit 8874945020869a3ff2383dfa06780d7495f177d2 +Subproject commit 0b8303f6b03d574e3a0b3fd8b17b7ff0014af47f diff --git a/scripts/3rdparty/maxthyme b/scripts/3rdparty/maxthyme index 6d0d35b689..b337e931b8 160000 --- a/scripts/3rdparty/maxthyme +++ b/scripts/3rdparty/maxthyme @@ -1 +1 @@ -Subproject commit 6d0d35b6896d29bff5a487fb92b979a945ad23f7 +Subproject commit b337e931b8b7a167ee5ce1ac6b5c3155c291f260 From 18a921baef41f4addd205572a287c8029ed2da8b Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Fri, 6 Nov 2015 11:44:43 +1100 Subject: [PATCH 59/91] Further clarify Core; move plugins out; other fixes - Fix formatting of (c) in license - Avoid possible issues with script linting - Move plugin docs out of Core.rst - Fix some builtin docs, tweak other bits --- .travis.yml | 4 +- LICENSE.rst | 24 +++++------ docs/Core.rst | 110 +++++++++++++---------------------------------- docs/Plugins.rst | 61 +++++++++++++++++++++++++- 4 files changed, 104 insertions(+), 95 deletions(-) diff --git a/.travis.yml b/.travis.yml index 1863835f1e..058a95a18c 100644 --- a/.travis.yml +++ b/.travis.yml @@ -17,8 +17,8 @@ script: - python travis/pr-check-base.py - python travis/lint.py - python travis/script-in-readme.py -- python travis/script-syntax.py --ext=lua --cmd="luac5.2 -p" -- python travis/script-syntax.py --ext=rb --cmd="ruby -c" +- python travis/script-syntax.py --ext=.lua --cmd="luac5.2 -p" +- python travis/script-syntax.py --ext=.rb --cmd="ruby -c" - mkdir build-travis - cd build-travis - cmake .. && make -j3 diff --git a/LICENSE.rst b/LICENSE.rst index 782c77bf55..e6a643e3d9 100644 --- a/LICENSE.rst +++ b/LICENSE.rst @@ -18,18 +18,18 @@ Their licenses are summarised here and reproduced below. =============== ============= ================================================= Component License Copyright =============== ============= ================================================= -DFHack_ Zlib (c) 2009-2012, Petr Mrázek -clsocket_ BSD 3-clause (c) 2007-2009, CarrierLabs, LLC. -dirent_ MIT (c) 2006, Toni Ronkko -JSON.lua_ CC-BY-SA_ (c) 2010-2014, Jeffrey Friedl -jsoncpp_ MIT (c) 2007-2010, Baptiste Lepilleur -linenoise_ BSD 2-clause (c) 2010, Salvatore Sanfilippo & Pieter Noordhuis -lua_ MIT (c) 1994-2008, Lua.org, PUC-Rio. -luafilesystem_ MIT (c) 2003-2014, Kepler Project -protobuf_ BSD 3-clause (c) 2008, Google Inc. -tinythread_ Zlib (c) 2010, Marcus Geelnard -tinyxml_ Zlib (c) 2000-2006, Lee Thomason -UTF-8-decoder_ MIT (c) 2008-2010, Bjoern Hoehrmann +DFHack_ Zlib \(c\) 2009-2012, Petr Mrázek +clsocket_ BSD 3-clause \(c\) 2007-2009, CarrierLabs, LLC. +dirent_ MIT \(c\) 2006, Toni Ronkko +JSON.lua_ CC-BY-SA_ \(c\) 2010-2014, Jeffrey Friedl +jsoncpp_ MIT \(c\) 2007-2010, Baptiste Lepilleur +linenoise_ BSD 2-clause \(c\) 2010, Salvatore Sanfilippo & Pieter Noordhuis +lua_ MIT \(c\) 1994-2008, Lua.org, PUC-Rio. +luafilesystem_ MIT \(c\) 2003-2014, Kepler Project +protobuf_ BSD 3-clause \(c\) 2008, Google Inc. +tinythread_ Zlib \(c\) 2010, Marcus Geelnard +tinyxml_ Zlib \(c\) 2000-2006, Lee Thomason +UTF-8-decoder_ MIT \(c\) 2008-2010, Bjoern Hoehrmann =============== ============= ================================================= .. _DFHack: https://github.com/DFHack/dfhack diff --git a/docs/Core.rst b/docs/Core.rst index fda08b6764..6ff1c8935a 100644 --- a/docs/Core.rst +++ b/docs/Core.rst @@ -7,7 +7,9 @@ DFHack Core DFHack commands can be implemented in three ways, all of which are used in the same way: -:builtin: commands are implemented by the core of DFHack, and quite rare. +:builtin: commands are implemented by the core of DFHack. They manage + other DFhack tools, interpret commands, and control basic + aspects of DF (force pause or quit). :plugins: are stored in ``hack/plugins/`` and must be compiled with the same version of DFHack. They are less flexible than scripts, @@ -159,7 +161,7 @@ load into memory - note that plugins are loaded but disabled unless you do something. Usage:: - load|unload|reload PLUGIN|all + load|unload|reload PLUGIN|(-a|--all) Allows dealing with plugins individually by name, or all at once. @@ -181,26 +183,13 @@ and scripts at the end. Usage: plug ---- -Lists available plugins (*not* commands implemented by plugins). +Lists available plugins, including their state and detailed description. -``plug [PLUGIN|v]`` - list plugin state and detailed description. - - -.. _rb_eval: - -rb_eval -------- -Evaluate the following arguments as a ruby string. Best used as -``:rb_eval [string]``, for the special parsing mode: - -If the first non-whitespace character is ``:``, the command is parsed in a special -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:: - - :foo a b "c d" e f - foo "a b \"c d\" e f" +``plug`` + Lists available plugins (*not* commands implemented by plugins) +``plug [PLUGIN] [PLUGIN] ...`` + List state and detailed description of the given plugins, + including commands implemented by the plugin. .. _sc-script: @@ -232,68 +221,24 @@ Shows the terminal window after it has been `hidden `. Only available on Windows. You'll need to use it from a `keybinding` set beforehand, or the in-game `command-prompt`. +.. _type: +type +---- +``type command`` shows where ``command`` is implemented. -.. important-commands: - -Other Important Commands -======================== - -.. _command-prompt: - -command-prompt +Other Commands -------------- -An in-game DFHack terminal, where you can enter other commands. -Best used from a keybinding; by default :kbd:`Ctrl`:kbd:`Shift`:kbd:`P`. - -Usage: ``command-prompt [entry]`` - -If called with an entry, it starts with that text filled in. -Most useful for developers, who can set a keybinding to open -a laungage interpreter for lua or Ruby by starting with the -`:lua ` or `:rb_eval ` commands. - -Otherwise somewhat similar to `gui/quickcmd`. - -.. image:: images/command-prompt.png - - -.. _hotkeys: +The following commands are *not* built-in, but offer similarly useful functions. -hotkeys -------- -Opens an in-game screen showing which DFHack keybindings are -active in the current context. - -.. image:: images/hotkeys.png - -Type ``hotkeys`` into the DFHack console to open the screen, -or bind the command to a globally active hotkey. The default -keybinding is :kbd:`Ctrl`:kbd:`F1`. See also `hotkey-notes`. - -lua ---- -The `lua` script provides an interactive interpreter, allows -loading and saving of lua files, or runs a single line of code. - -multicmd --------- -The `multicmd` script calls many commands in one line. - -.. _nopause: - -nopause -------- -Disables pausing (both manual and automatic) with the exception of pause forced -by `reveal` ``hell``. This is nice for digging under rivers. - -quicksave ---------- -The `quicksave` script saves the game immediately without exiting. - -repeat ------- -The `repeat` script sets a command to be called regularly. +* `command-prompt` +* `hotkeys` +* `lua` +* `multicmd` +* `nopause` +* `quicksave` +* `rb_eval` +* `repeat` .. _init-files: @@ -370,6 +315,11 @@ an unmodded save. Other init files ---------------- + +* ``onMapLoad*.init`` and ``onMapUnload*.init`` are run when a map, + distinct from a world, is loaded. This is good for map-affecting + commands (eg `clean`), or avoiding issues in Legends mode. + * Any lua script named ``raw/init.d/*.lua``, in the save or main DF directory, will be run when any world or that save is loaded. @@ -382,7 +332,7 @@ This section is for odd but important notes that don't fit anywhere else. an already running DF+DFHack instance from external OS scripts and programs, and is *not* the way how you use DFHack normally. -* If a DF hotkey (:kbd:`H`) is named with a DFHack command, pressing +* If a DF :kbd:`H` hotkey is named with a DFHack command, pressing the corresponding :kbd:`Fx` button will run that command, instead of zooming to the set location. diff --git a/docs/Plugins.rst b/docs/Plugins.rst index 192bbb36db..ddb60316be 100644 --- a/docs/Plugins.rst +++ b/docs/Plugins.rst @@ -346,13 +346,65 @@ UI Upgrades .. note:: - In order to avoid user confusion, as a matter of policy all these tools + In order to avoid user confusion, as a matter of policy all GUI tools display the word :guilabel:`DFHack` on the screen somewhere while active. When that is not appropriate because they merely add keybinding hints to existing DF screens, they deliberately use red instead of green for the key. +DFHack Interface +================ + +.. _command-prompt: + +command-prompt +-------------- +An in-game DFHack terminal, where you can enter other commands. +Best used from a keybinding; by default :kbd:`Ctrl`:kbd:`Shift`:kbd:`P`. + +Usage: ``command-prompt [entry]`` + +If called with an entry, it starts with that text filled in. +Most useful for developers, who can set a keybinding to open +a laungage interpreter for lua or Ruby by starting with the +`:lua ` or `:rb_eval ` commands. + +Otherwise somewhat similar to `gui/quickcmd`. + +.. image:: images/command-prompt.png + + +.. _hotkeys: + +hotkeys +------- +Opens an in-game screen showing which DFHack keybindings are +active in the current context. + +.. image:: images/hotkeys.png + +Type ``hotkeys`` into the DFHack console to open the screen, +or bind the command to a globally active hotkey. The default +keybinding is :kbd:`Ctrl`:kbd:`F1`. See also `hotkey-notes`. + +.. _rb_eval: + +rb_eval +------- +Evaluate the following arguments as a ruby string. Best used as +``:rb_eval [string]``, for the special parsing mode: + +If the first non-whitespace character is ``:``, the command is parsed in a special +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:: + + :foo a b "c d" e f + foo "a b \"c d\" e f" + + .. _manipulator: manipulator @@ -450,6 +502,13 @@ using Permit Fats again while the list is filtered. Game interface ============== +.. _nopause: + +nopause +------- +Disables pausing (both manual and automatic) with the exception of pause forced +by `reveal` ``hell``. This is nice for digging under rivers. + .. _embark-tools: embark-tools From bc91928f8d35236bf9962955453f8e6db3110223 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Fri, 6 Nov 2015 11:58:33 +1100 Subject: [PATCH 60/91] Explain ":foo" parsing mode in Core notes --- docs/Core.rst | 16 +++++++++++++--- docs/Plugins.rst | 12 +----------- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/Core.rst b/docs/Core.rst index 6ff1c8935a..17b6d3174a 100644 --- a/docs/Core.rst +++ b/docs/Core.rst @@ -340,12 +340,22 @@ This section is for odd but important notes that don't fit anywhere else. that's preserved between different runs of DF (use up/down keys to go through the history). -* To include whitespace in the argument/s to some command, quote it in - double quotes. To include a double quote character, use ``\"``. - * The binaries for 0.40.15-r1 to 0.34.11-r4 are on DFFD_. Older versions are available here_. .. _DFFD: http://dffd.bay12games.com/search.php?string=DFHack&id=15&limit=1000 .. _here: http://dethware.org/dfhack/download +* To include whitespace in the argument/s to some command, quote it in + double quotes. To include a double quote character, use ``\"``. + +* If the first non-whitespace character is ``:``, the command is parsed in + an alternative mode which is very useful for the `lua` and `rb_eval` commands. + The following two command lines are exactly equivalent:: + + :foo a b "c d" e f + foo "a b \"c d\" e f" + + * non-whitespace characters following the ``:`` are the command name + * the remaining part of the line is used verbatim as the first argument + diff --git a/docs/Plugins.rst b/docs/Plugins.rst index ddb60316be..4486d11cba 100644 --- a/docs/Plugins.rst +++ b/docs/Plugins.rst @@ -393,17 +393,7 @@ keybinding is :kbd:`Ctrl`:kbd:`F1`. See also `hotkey-notes`. rb_eval ------- Evaluate the following arguments as a ruby string. Best used as -``:rb_eval [string]``, for the special parsing mode: - -If the first non-whitespace character is ``:``, the command is parsed in a special -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:: - - :foo a b "c d" e f - foo "a b \"c d\" e f" - +``:rb_eval [string]``, for the special parsing mode. .. _manipulator: From 867b733a0456cb12b9e47215b37a5bf252f4f661 Mon Sep 17 00:00:00 2001 From: lethosor Date: Thu, 5 Nov 2015 21:48:13 -0500 Subject: [PATCH 61/91] Fix a few GCC warnings on Linux (GCC 4.6) --- depends/protobuf/CMakeLists.txt | 2 +- library/Hooks-linux.cpp | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/depends/protobuf/CMakeLists.txt b/depends/protobuf/CMakeLists.txt index ffad350edc..b175b7744d 100644 --- a/depends/protobuf/CMakeLists.txt +++ b/depends/protobuf/CMakeLists.txt @@ -201,7 +201,7 @@ google/protobuf/compiler/zip_writer.cc LIST(APPEND LIBPROTOBUF_FULL_SRCS ${LIBPROTOBUF_LITE_SRCS}) IF(CMAKE_COMPILER_IS_GNUCC) - SET(CMAKE_CXX_FLAGS_RELWITHDEBINFO "${CMAKE_CXX_FLAGS_RELWITHDEBINFO} -Wno-sign-compare") + SET(CMAKE_CXX_FLAGS_RELWITHDEBINFO "${CMAKE_CXX_FLAGS_RELWITHDEBINFO} -Wno-sign-compare -Wno-unused-result") ENDIF() INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR}) diff --git a/library/Hooks-linux.cpp b/library/Hooks-linux.cpp index 31c0323f6c..b0bf5a7817 100644 --- a/library/Hooks-linux.cpp +++ b/library/Hooks-linux.cpp @@ -114,7 +114,8 @@ static int (*_SDL_Init)(uint32_t flags) = 0; DFhackCExport int SDL_Init(uint32_t flags) { // reroute stderr - freopen("stderr.log", "w", stderr); + if (!freopen("stderr.log", "w", stderr)) + fprintf(stderr, "dfhack: failed to reroute stderr\n"); // we don't reroute stdout until we figure out if this should be done at all // See: Console-linux.cpp From e15dcfd72ae33ac51e34c2d18f8714eff971aa74 Mon Sep 17 00:00:00 2001 From: lethosor Date: Thu, 5 Nov 2015 21:52:04 -0500 Subject: [PATCH 62/91] protobuf: Disable unused-result warnings in release mode --- depends/protobuf/CMakeLists.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/depends/protobuf/CMakeLists.txt b/depends/protobuf/CMakeLists.txt index b175b7744d..9ec13e6ca8 100644 --- a/depends/protobuf/CMakeLists.txt +++ b/depends/protobuf/CMakeLists.txt @@ -201,7 +201,8 @@ google/protobuf/compiler/zip_writer.cc LIST(APPEND LIBPROTOBUF_FULL_SRCS ${LIBPROTOBUF_LITE_SRCS}) IF(CMAKE_COMPILER_IS_GNUCC) - SET(CMAKE_CXX_FLAGS_RELWITHDEBINFO "${CMAKE_CXX_FLAGS_RELWITHDEBINFO} -Wno-sign-compare -Wno-unused-result") + SET(CMAKE_CXX_FLAGS_RELWITHDEBINFO "${CMAKE_CXX_FLAGS_RELWITHDEBINFO} -Wno-sign-compare") + SET(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wno-unused-result") ENDIF() INCLUDE_DIRECTORIES(${CMAKE_CURRENT_SOURCE_DIR}) From 29533f1f081cc9bcb401f5b8568eabdc0ad73547 Mon Sep 17 00:00:00 2001 From: lethosor Date: Thu, 5 Nov 2015 22:57:09 -0500 Subject: [PATCH 63/91] Minor sphinx fixes * Exclude build directories (rst files are copied into them by CPack) * Fix CMake dependency path to conf.py * Build in parallel --- CMakeLists.txt | 3 ++- conf.py | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 08962a4d3a..e283fb706d 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -206,7 +206,7 @@ if (BUILD_DOCS) "${CMAKE_CURRENT_SOURCE_DIR}/docs/*.rst" "${CMAKE_CURRENT_SOURCE_DIR}/docs/images/*.png" "${CMAKE_CURRENT_SOURCE_DIR}/docs/styles/*" - "${CMAKE_CURRENT_SOURCE_DIR}/docs/conf.py" + "${CMAKE_CURRENT_SOURCE_DIR}/conf.py" "${CMAKE_CURRENT_SOURCE_DIR}/scripts/about.txt" "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/about.txt" ) @@ -224,6 +224,7 @@ if (BUILD_DOCS) "${CMAKE_CURRENT_SOURCE_DIR}" "${CMAKE_CURRENT_SOURCE_DIR}/docs/html" -w "${CMAKE_CURRENT_SOURCE_DIR}/docs/_sphinx-warnings.txt" + -j 2 DEPENDS ${SPHINX_DEPS} COMMENT "Building HTML documentation with Sphinx" ) diff --git a/conf.py b/conf.py index 81cfb78eff..17df22ee45 100644 --- a/conf.py +++ b/conf.py @@ -173,7 +173,7 @@ def get_version(): # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ['docs/_build/*', 'depends/*', 'scripts/3rdparty/*'] +exclude_patterns = ['docs/_build/*', 'depends/*', 'scripts/3rdparty/*', 'build*'] # The reST default role (used for this markup: `text`) to use for all # documents. From 193e71793a3a0bf3e72b936a65059eec17c3f669 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Fri, 6 Nov 2015 16:58:58 +1100 Subject: [PATCH 64/91] Fix compile, intro, scripts - script-syntax.py now exits with 1 instead of silently catching the error if lua or ruby are missing - index paths are absolute (from the repo root) - less strong suggestion for third-party packs - re-added lua-example and test-perlin doc - corrected and clarified Compile some more --- docs/Compile.rst | 69 +++++++++++++++-------------------- docs/Introduction.rst | 6 +-- index.rst | 26 ++++++------- scripts/devel/lua-example.lua | 14 +++++++ scripts/devel/test-perlin.lua | 2 - travis/script-syntax.py | 6 +-- 6 files changed, 62 insertions(+), 61 deletions(-) create mode 100644 scripts/devel/lua-example.lua diff --git a/docs/Compile.rst b/docs/Compile.rst index 4a72f0dc45..752b9b5fd9 100644 --- a/docs/Compile.rst +++ b/docs/Compile.rst @@ -14,17 +14,8 @@ and `install the latest release instead `. How to get the code =================== DFHack doesn't have any kind of system of code snapshots in place, so you will have to -get code from the github repository using git. -The code resides at https://github.com/DFHack/dfhack - -On Linux and OS X, having a ``git`` package installed is the minimal requirement (see below for OS X instructions), -but some sort of git gui or git integration for your favorite text editor/IDE will certainly help. - -On Windows, you will need some sort of Windows port of git, or a GUI. Some examples: - - * http://msysgit.github.io - this is a command line version of git for windows. - Most tutorials on git usage will apply. - * http://code.google.com/p/tortoisegit - this puts a pretty, graphical face on top of msysgit +get code from the github repository using git. How to get git is described under +the instructions for each platform. To get the code:: @@ -34,16 +25,14 @@ To get the code:: If your version of git does not support the ``--recursive`` flag, you will need to omit it and run ``git submodule update --init`` after entering the dfhack directory. -If you want to get really involved with the development, create an account on +If you want to get involved with the development, create an account on Github, make a clone there and then use that as your remote repository instead. -Detailed instructions are beyond the scope of this document. If you need help, -join us on IRC (#dfhack channel on freenode). +We'd love that; join us on IRC (#dfhack channel on freenode) if you need help. Build types =========== -``cmake`` allows you to pick a build type by changing the -``CMAKE_BUILD_TYPE`` environment variable:: +``cmake`` allows you to pick a build type by changing the ``CMAKE_BUILD_TYPE`` variable:: cmake .. -DCMAKE_BUILD_TYPE:string=BUILD_TYPE @@ -62,23 +51,25 @@ Dependencies ------------ DFHack is meant to be installed into an existing DF folder, so get one ready. -For building, you need a 32-bit version of GCC. For example, to build DFHack on -a 64-bit distribution like Arch, you'll need the multilib development tools and libraries. -Alternatively, you might be able to use ``lxc`` to +We assume that any Linux platform will have ``git`` available. + +To build DFHack you need a 32-bit version of GCC. On 64-bit distributions +(which is most of them), this means you'll need the multilib development tools +and libraries. Alternatively, you might be able to use ``lxc`` to :forums:`create a virtual 32-bit environment <139553.msg5435310#msg5435310>`. Before you can build anything, you'll also need ``cmake``. It is advisable to also get ``ccmake`` on distributions that split the cmake package into multiple parts. You also need perl and the XML::LibXML and XML::LibXSLT perl packages (for the code generation parts). -You should be able to find them in your distro repositories (on Arch linux -``perl-xml-libxml`` and ``perl-xml-libxslt``) or through ``cpan``. +You should be able to find them in your distro repositories. -To build Stonesense, you'll also need OpenGL headers. +* On Arch linux, ``perl-xml-libxml`` and ``perl-xml-libxslt`` (or through ``cpan``) +* On 64-bit Ubuntu, ``apt-get install zlib1g-dev:i386 libxml-libxml-perl libxml-libxslt-perl``. +* On 32-bit Ubuntu, ``apt-get install zlib1g-dev libxml-libxml-perl libxml-libxslt-perl``. +* Debian-derived distros should have similar requirements. -On 64-bit Ubuntu, ``apt-get install zlib1g-dev:i386 libxml-libxml-perl libxml-libxslt-perl``. -On 32-bit Ubuntu, ``apt-get install zlib1g-dev libxml-libxml-perl libxml-libxslt-perl``. -Debian-derived distros should have similar requirements. +To build Stonesense, you'll also need OpenGL headers. Build @@ -100,14 +91,12 @@ Alternatively, you can use ccmake instead of cmake:: make install This will show a curses-based interface that lets you set all of the -extra options. +extra options. You can also use a cmake-friendly IDE like KDevelop 4 +or the cmake-gui program. -You can also use a cmake-friendly IDE like KDevelop 4 or the cmake-gui -program. - -The libstdc++ version bug -~~~~~~~~~~~~~~~~~~~~~~~~~ +Incompatible libstdc++ +~~~~~~~~~~~~~~~~~~~~~~ When compiling dfhack yourself, it builds against your system libc. When Dwarf Fortress runs, it uses a libstdc++ shipped with the binary, which comes from GCC 4.5 and is incompatible with code compiled with newer GCC versions. @@ -116,14 +105,12 @@ This manifests itself with the error message:: ./libs/Dwarf_Fortress: /pathToDF/libs/libstdc++.so.6: version `GLIBCXX_3.4.15' not found (required by ./hack/libdfhack.so) -To fix this, simply remove the libstdc++ shipped with DF, it will fall back -to your system lib and everything will work fine:: +To fix this, you can compile DFHack with GCC 4.5 - or simply remove the +libstdc++ shipped with DF, and it will fall back to your system lib:: cd /path/to/DF/ rm libs/libstdc++.so.6 -Alternatively, this issue can be avoided by compiling DFHack with GCC 4.5. - Mac OS X ======== @@ -201,16 +188,18 @@ On Windows, DFHack replaces the SDL library distributed with DF. Dependencies ------------ -First, you need ``cmake``. Get the win32 installer version from -`the official site `_. +You will need some sort of Windows port of git, or a GUI. Some examples: +* `Git for Windows `_ (command-line and GUI) +* `tortoisegit `_ (GUI and File Explorer integration) + +You need ``cmake``. Get the win32 installer version from +`the official site `_. It has the usual installer wizard. Make sure you let it add its binary folder to your binary search PATH so the tool can be later run from anywhere. You'll need a copy of Microsoft Visual C++ 2010. The Express version is sufficient. -Grab it from Microsoft's site. - -You'll also need the Visual Studio 2010 SP1 update. +Grab it from Microsoft's site. You'll also need the Visual Studio 2010 SP1 update. For the code generation parts, you'll need perl with XML::LibXML and XML::LibXSLT. `Strawberry Perl `_ works nicely for this. diff --git a/docs/Introduction.rst b/docs/Introduction.rst index f0fc0a0bf3..8a82e0f10d 100644 --- a/docs/Introduction.rst +++ b/docs/Introduction.rst @@ -37,9 +37,6 @@ allows easier development of new tools. As an open-source project under Installing DFHack ================= -New players are encouraged to :wiki:`get a pack with DFHack preinstalled -`. - DFHack is available for the SDL version of Dwarf Frtress on Windows, any modern Linux distribution, and OS X (10.6.8 to 10.9). It is possible to use Windows DF+DFHack under Wine on Linux or OS X. @@ -60,6 +57,9 @@ Uninstalling is basically the same, in reverse: * On Windows, replace ``SDL.dll`` with ``SDLreal.dll``, then remove the DFHack files. * On Linux or OSX, remove the DFHack files. +New players may wish to :wiki:`get a pack ` +with DFHack preinstalled. + Getting started =============== diff --git a/index.rst b/index.rst index 7f3e815a31..de587e95af 100644 --- a/index.rst +++ b/index.rst @@ -36,10 +36,10 @@ User Manual .. toctree:: :maxdepth: 2 - docs/Introduction - docs/Core - docs/Plugins - docs/Scripts + /docs/Introduction + /docs/Core + /docs/Plugins + /docs/Scripts Other Contents ============== @@ -47,9 +47,9 @@ Other Contents .. toctree:: :maxdepth: 1 - docs/Authors - LICENSE - NEWS + /docs/Authors + /LICENSE + /NEWS For Developers ============== @@ -57,9 +57,9 @@ For Developers .. toctree:: :maxdepth: 1 - docs/Contributing - docs/Compile - docs/Lua API - library/xml/SYNTAX - library/xml/how-to-update - docs/Binpatches + /docs/Contributing + /docs/Compile + /docs/Lua API + /library/xml/SYNTAX + /library/xml/how-to-update + /docs/Binpatches diff --git a/scripts/devel/lua-example.lua b/scripts/devel/lua-example.lua new file mode 100644 index 0000000000..bbdb04ed6c --- /dev/null +++ b/scripts/devel/lua-example.lua @@ -0,0 +1,14 @@ +-- Example of a lua script. +--[[=begin + +devel/lua-example +================= +An example lua script, which reports the number of times it has +been called. Useful for testing environment persistence. + +=end]] + +run_count = (run_count or 0) + 1 + +print('Arguments: ',...) +print('Command called '..run_count..' times.') diff --git a/scripts/devel/test-perlin.lua b/scripts/devel/test-perlin.lua index 2759d70855..3b3a6a11a8 100644 --- a/scripts/devel/test-perlin.lua +++ b/scripts/devel/test-perlin.lua @@ -5,8 +5,6 @@ devel/test-perlin ================= Generates an image using multiple octaves of perlin noise. -Used by `3dveins`? - =end]] local args = {...} diff --git a/travis/script-syntax.py b/travis/script-syntax.py index 0b977f59d6..c4454d7bef 100644 --- a/travis/script-syntax.py +++ b/travis/script-syntax.py @@ -24,9 +24,9 @@ def main(): except subprocess.CalledProcessError: err = True except IOError: - # catch error if not in Travis and Lua/Ruby is not available - if os.environ.get('TRAVIS', False): - raise + if not err: + print('Warning: cannot check %s script syntax' % args.ext) + err = True sys.exit(int(err)) From 5826b49d09f12ebc16cc6937234b1e56aa39a559 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Fri, 6 Nov 2015 17:09:56 +1100 Subject: [PATCH 65/91] Move index.rst to docs directory Having the docs index in the repo root was a holdover from when it was the README file. Now that it's not much use without being built, it's better to leave the root to README, NEWS, and LICENSE - especially when one is a html shortcut to the docs index. --- CMakeLists.txt | 2 +- README.html | 6 +++--- conf.py | 2 +- index.rst => docs/index.rst | 0 4 files changed, 5 insertions(+), 5 deletions(-) rename index.rst => docs/index.rst (100%) diff --git a/CMakeLists.txt b/CMakeLists.txt index fb6dd52bb6..c7ab44fd5f 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -214,7 +214,7 @@ if (BUILD_DOCS) "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*.lua" "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*.rb" ) - set(SPHINX_DEPS ${SPHINX_DEPS} ${SPHINX_SCRIPT_DEPS} LICENSE.rst NEWS.rst index.rst) + set(SPHINX_DEPS ${SPHINX_DEPS} ${SPHINX_SCRIPT_DEPS} LICENSE.rst NEWS.rst) set(SPHINX_OUTPUT "${CMAKE_CURRENT_SOURCE_DIR}/docs/html/.buildinfo") set_source_files_properties(${SPHINX_OUTPUT} PROPERTIES GENERATED TRUE) diff --git a/README.html b/README.html index 325cd66f60..660ea2b5b6 100644 --- a/README.html +++ b/README.html @@ -4,13 +4,13 @@ - + Page Redirection - Follow this link to the documentation. + Follow this link to the documentation. \ No newline at end of file diff --git a/conf.py b/conf.py index 5eb2c81772..7b0a7c4c5c 100644 --- a/conf.py +++ b/conf.py @@ -120,7 +120,7 @@ def document_scripts(): #source_encoding = 'utf-8-sig' # The master toctree document. -master_doc = 'index' +master_doc = 'docs/index' # General information about the project. project = 'DFHack' diff --git a/index.rst b/docs/index.rst similarity index 100% rename from index.rst rename to docs/index.rst From e9be1aa657596ea8bab31b89700ca0fc5a7f8d1a Mon Sep 17 00:00:00 2001 From: DoctorVanGogh Date: Fri, 6 Nov 2015 19:00:43 +0100 Subject: [PATCH 66/91] Fix for construction over existing construction & on top of walls Fix to allow constructions on top of (natural) down stairs --- library/include/modules/Constructions.h | 1 + library/modules/Constructions.cpp | 9 ++++++++ plugins/automaterial.cpp | 30 +++++-------------------- 3 files changed, 16 insertions(+), 24 deletions(-) diff --git a/library/include/modules/Constructions.h b/library/include/modules/Constructions.h index 41959b2d72..3831d4bb18 100644 --- a/library/include/modules/Constructions.h +++ b/library/include/modules/Constructions.h @@ -59,6 +59,7 @@ DFHACK_EXPORT bool isValid(); DFHACK_EXPORT uint32_t getCount(); DFHACK_EXPORT bool copyConstruction (const int32_t index, t_construction &out); DFHACK_EXPORT df::construction * getConstruction (const int32_t index); +DFHACK_EXPORT df::construction * findAtTile(df::coord pos); DFHACK_EXPORT bool designateNew(df::coord pos, df::construction_type type, df::item_type item = df::item_type::NONE, int mat_index = -1); diff --git a/library/modules/Constructions.cpp b/library/modules/Constructions.cpp index 16c1f1b892..a60059b5c4 100644 --- a/library/modules/Constructions.cpp +++ b/library/modules/Constructions.cpp @@ -68,6 +68,15 @@ df::construction * Constructions::getConstruction(const int32_t index) return world->constructions[index]; } +df::construction * Constructions::findAtTile(df::coord pos) +{ + for (auto it = begin (world->constructions); it != end (world->constructions); ++it) { + if ((*it)->pos == pos) + return *it; + } + return NULL; +} + bool Constructions::copyConstruction(const int32_t index, t_construction &out) { if (uint32_t(index) >= getCount()) diff --git a/plugins/automaterial.cpp b/plugins/automaterial.cpp index cc38dc7630..83573b9fbf 100644 --- a/plugins/automaterial.cpp +++ b/plugins/automaterial.cpp @@ -456,35 +456,17 @@ static bool is_valid_building_site(building_site &site, bool orthogonal_check, b } else { - if (shape_basic != tiletype_shape_basic::Floor) + if (shape != tiletype_shape::STAIR_DOWN && shape_basic != tiletype_shape_basic::Floor) return false; - if (material == tiletype_material::CONSTRUCTION) + // Can build on top of a wall, but not on other construction + auto construction = Constructions::findAtTile(site.pos); + if (construction) { - // Check this is not a 'constructed floor over X': - // those have something else than open space as *basic* tile types: stonefloor, smoothstonefloor, ... - MapExtras::MapCache mc; - auto btt = mc.baseTiletypeAt(site.pos); - auto bshape = tileShape(btt); - if (bshape != tiletype_shape_basic::Open) - return false; - - // Can build on top of a wall, but not on a constructed floor - df::coord pos_below = site.pos; - pos_below.z--; - if (!Maps::isValidTilePos(pos_below)) - return false; - - auto ttype_below = Maps::getTileType(pos_below); - if (!ttype_below) - return false; - - auto shape_below = tileShape(*ttype_below); - auto shapeBasic_below = tileShapeBasic(shape_below); - if (tileShapeBasic(shape_below) != tiletype_shape_basic::Wall) + if (construction->flags.bits.top_of_wall==0) return false; } - + if (material == tiletype_material::FIRE || material == tiletype_material::POOL || material == tiletype_material::BROOK || From 7f212178ca756922d28d8e9e17a2db68fa5c047b Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Sat, 7 Nov 2015 10:13:21 +1100 Subject: [PATCH 67/91] Move unused docs to plugin source files This way they can easily be restored when the plugins are reactivated, but don't confuse users until then. --- docs/Plugins.rst | 80 +++++------------------------ plugins/advtools.cpp | 11 ++++ plugins/dwarfexport/dwarfexport.cpp | 5 ++ plugins/mapexport/mapexport.cpp | 6 +++ plugins/misery.cpp | 15 ++++++ plugins/treefarm.cpp | 18 +++++++ 6 files changed, 69 insertions(+), 66 deletions(-) diff --git a/docs/Plugins.rst b/docs/Plugins.rst index 4486d11cba..baa336cbdc 100644 --- a/docs/Plugins.rst +++ b/docs/Plugins.rst @@ -10,7 +10,7 @@ Most commands offered by plugins are listed here, hopefully organised in a way you will find useful. .. contents:: - :depth: 4 + :depth: 3 =========================== Visualizers and data export @@ -37,15 +37,6 @@ For detailed information, see the `stonesense readme`_, the :wiki:`wiki page .. _`stonesense readme`: https://github.com/DFHack/stonesense/blob/master/README.md -mapexport -========= -Export the current loaded map as a file. This was used by visualizers for -DF 0.34.11, but is now basically obsolete. - -dwarfexport -=========== -Export dwarves to RuneSmith-compatible XML; also unused by modern tools. - .. _blueprint: blueprint @@ -1689,48 +1680,6 @@ cycle runs once every in game day. If you add ``enable getplants`` to your dfhack.init there will be a hotkey to open the dashboard from the chop designation menu. -treefarm --------- -Automatically manages special burrows and regularly schedules tree chopping -and digging when appropriate. - -Every time the plugin runs, it checks for burrows with a name containing the -string ``"treefarm"``. For each such burrow, it checks every tile in it for -fully-grown trees and for diggable walls. For each fully-grown tree it finds, -it designates the tree to be chopped, and for each natural wall it finds, it -designates the wall to be dug. - -Usage: - -:treefarm: Enables treefarm monitoring, starting next frame -:treefarm n: Enables treefarm monitoring, starting next frame, and sets - interval to n frames. If n is less than one, disables monitoring. - - -============== -Adventure mode -============== - -adv-bodyswap -============ -This allows taking control over your followers and other creatures in adventure -mode. For example, you can make them pick up new arms and armor and equip them -properly. - -Usage: - -* When viewing unit details, body-swaps into that unit. -* In the main adventure mode screen, reverts transient swap. - -advtools -======== -A package of different adventure mode tools. Usage: - -:list-equipped [all]: List armor and weapons equipped by your companions. - If all is specified, also lists non-metal clothing. -:metal-detector [all-types] [non-trader]: - Reveal metal armor and weapons in shops. The options - disable the checks on item type and being in shop. ================ Map modification @@ -2162,6 +2111,19 @@ or 'snow', with those words as commands (eg ``weather rain``). Mods and Cheating ================= +.. _adv-bodyswap: + +adv-bodyswap +============ +This allows taking control over your followers and other creatures in adventure +mode. For example, you can make them pick up new arms and armor and equip them +properly. + +Usage: + +* When viewing unit details, body-swaps into that unit. +* In the main adventure mode screen, reverts transient swap. + .. _catsplosion: catsplosion @@ -2243,20 +2205,6 @@ Options: :lair: Mark the map as monster lair :lair reset: Mark the map as ordinary (not lair) -misery -====== -When enabled, every new negative dwarven thought will be multiplied by a factor (2 by default). - -Usage: - -:misery enable n: enable misery with optional magnitude n. If specified, n must be positive. -:misery n: same as "misery enable n" -:misery enable: same as "misery enable 2" -:misery disable: stop adding new negative thoughts. This will not remove existing - duplicated thoughts. Equivalent to "misery 1" -:misery clear: remove fake thoughts added in this session of DF. Saving makes them - permanent! Does not change factor. - mode ==== This command lets you see and change the game mode directly. diff --git a/plugins/advtools.cpp b/plugins/advtools.cpp index 8f613d1cc9..77cc029340 100644 --- a/plugins/advtools.cpp +++ b/plugins/advtools.cpp @@ -41,6 +41,17 @@ using df::nemesis_record; using df::historical_figure; using namespace DFHack::Translation; +/* +advtools +======== +A package of different adventure mode tools. Usage: + +:list-equipped [all]: List armor and weapons equipped by your companions. + If all is specified, also lists non-metal clothing. +:metal-detector [all-types] [non-trader]: + Reveal metal armor and weapons in shops. The options + disable the checks on item type and being in shop. +*/ DFHACK_PLUGIN("advtools"); REQUIRE_GLOBAL(world); diff --git a/plugins/dwarfexport/dwarfexport.cpp b/plugins/dwarfexport/dwarfexport.cpp index 8355573be8..666601b79f 100644 --- a/plugins/dwarfexport/dwarfexport.cpp +++ b/plugins/dwarfexport/dwarfexport.cpp @@ -20,6 +20,11 @@ using namespace std; #include #include #include +/* +dwarfexport +=========== +Export dwarves to RuneSmith-compatible XML; also unused by modern tools. +*/ using namespace DFHack; using df::global::ui; diff --git a/plugins/mapexport/mapexport.cpp b/plugins/mapexport/mapexport.cpp index 0c69eeb68f..ceb03196ac 100644 --- a/plugins/mapexport/mapexport.cpp +++ b/plugins/mapexport/mapexport.cpp @@ -21,6 +21,12 @@ using namespace google::protobuf::io; using namespace DFHack; using df::global::world; +/* +mapexport +========= +Export the current loaded map as a file. This was used by visualizers for +DF 0.34.11, but is now basically obsolete. +*/ typedef std::vector PlantList; diff --git a/plugins/misery.cpp b/plugins/misery.cpp index 00c844f1d5..a4468079c7 100644 --- a/plugins/misery.cpp +++ b/plugins/misery.cpp @@ -14,6 +14,21 @@ using namespace std; using namespace DFHack; +/* +misery +====== +When enabled, every new negative dwarven thought will be multiplied by a factor (2 by default). + +Usage: + +:misery enable n: enable misery with optional magnitude n. If specified, n must be positive. +:misery n: same as "misery enable n" +:misery enable: same as "misery enable 2" +:misery disable: stop adding new negative thoughts. This will not remove existing + duplicated thoughts. Equivalent to "misery 1" +:misery clear: remove fake thoughts added in this session of DF. Saving makes them + permanent! Does not change factor. +*/ DFHACK_PLUGIN("misery"); DFHACK_PLUGIN_IS_ENABLED(is_enabled); diff --git a/plugins/treefarm.cpp b/plugins/treefarm.cpp index 68429dd93f..0e24ad28f8 100644 --- a/plugins/treefarm.cpp +++ b/plugins/treefarm.cpp @@ -20,6 +20,24 @@ //#include "df/world.h" using namespace DFHack; +/* +treefarm +======== +Automatically manages special burrows and regularly schedules tree chopping +and digging when appropriate. + +Every time the plugin runs, it checks for burrows with a name containing the +string ``"treefarm"``. For each such burrow, it checks every tile in it for +fully-grown trees and for diggable walls. For each fully-grown tree it finds, +it designates the tree to be chopped, and for each natural wall it finds, it +designates the wall to be dug. + +Usage: + +:treefarm: Enables treefarm monitoring, starting next frame +:treefarm n: Enables treefarm monitoring, starting next frame, and sets + interval to n frames. If n is less than one, disables monitoring. +*/ DFHACK_PLUGIN("treefarm"); DFHACK_PLUGIN_IS_ENABLED(enabled); From 35069214479dc9074b0a9227aef87020bf365232 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Sat, 7 Nov 2015 10:53:12 +1100 Subject: [PATCH 68/91] Add cross-links for similar commands --- docs/Plugins.rst | 9 ++++++--- scripts/source.rb | 1 + 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/Plugins.rst b/docs/Plugins.rst index baa336cbdc..8e36de8619 100644 --- a/docs/Plugins.rst +++ b/docs/Plugins.rst @@ -206,7 +206,7 @@ allowing them to make trade agreements. This was the default behaviour in fix-unit-occupancy ================== -This plugin fixes issues with unit occupancy, notably issues with phantom +This plugin fixes issues with unit occupancy, notably phantom "unit blocking tile" messages (:bug:`3499`). It can be run manually, or periodically when enabled with the built-in enable/disable commands: @@ -1913,7 +1913,10 @@ See also `this issue. `_ Settings will be remembered until you quit DF. You can call `liquids-here` to execute the last configured action, which is useful in combination with keybindings. -Usage: point the DF cursor at a tile you want to modify and use the commands +Usage: point the DF cursor at a tile you want to modify and use the commands. + +If you only want to add or remove water or magma from one tile, +`source` may be easier to use. Commands -------- @@ -1971,7 +1974,7 @@ 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 -`liquids`. +`liquids`. If something goes wrong, `fixveins` may help. The tool works with two set of options and a brush. The brush determines which tiles will be processed. First set of options is the filter, which can exclude diff --git a/scripts/source.rb b/scripts/source.rb index 647fc960a5..92f1a47a69 100644 --- a/scripts/source.rb +++ b/scripts/source.rb @@ -4,6 +4,7 @@ source ====== Create an infinite magma or water source or drain on a tile. +For more complex commands, try the `liquids` plugin. This script registers a map tile as a liquid source, and every 12 game ticks that tile receives or remove 1 new unit of flow based on the configuration. From a1110b36e8015a78a58130c727de67b850d40acc Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Sat, 7 Nov 2015 11:35:44 +1100 Subject: [PATCH 69/91] Add shortlink for issues, update links Also moved search above local table of contents in sidebar, which can get very long. --- conf.py | 5 +++-- docs/Binpatches.rst | 13 +++++-------- docs/Compile.rst | 7 ++++--- docs/Contributing.rst | 24 ++++++++++++++---------- docs/Plugins.rst | 9 ++++----- 5 files changed, 30 insertions(+), 28 deletions(-) diff --git a/conf.py b/conf.py index 7b0a7c4c5c..6c4f768dbe 100644 --- a/conf.py +++ b/conf.py @@ -106,7 +106,8 @@ def document_scripts(): 'Bay12 forums thread '), 'dffd': ('http://dffd.bay12games.com/file.php?id=%s', 'DFFD file '), 'bug': ('http://www.bay12games.com/dwarves/mantisbt/view.php?id=%s', - 'Bug ') + 'Bug '), + 'issue': ('https://github.com/DFHack/dfhack/issues/%s', 'Issue '), } # Add any paths that contain templates here, relative to this directory. @@ -235,9 +236,9 @@ def get_version(): html_sidebars = { '**': [ 'about.html', - 'localtoc.html', 'relations.html', 'searchbox.html', + 'localtoc.html', ] } diff --git a/docs/Binpatches.rst b/docs/Binpatches.rst index 145dead898..e1ae1c0eff 100644 --- a/docs/Binpatches.rst +++ b/docs/Binpatches.rst @@ -32,8 +32,7 @@ decent skill in `memory research `. * See `this commit `_, when the 0.34.11 patches were discarded, for example patches. -* `Issue #546 `_ is about the - future of the binpatches, and may be useful reading. +* :issue:`546` is about the future of the binpatches, and may be useful reading. If you want to write a patch, the armory patches discussed here and documented below would probably be the best place to start. @@ -56,7 +55,7 @@ the version appropriate for the currently loaded executable. This is the preferred method; it's easier to debug, does not cause persistent problems, and leaves file checksums alone. As with many other commands, users -can simply add it to ``dfhack.init`` to reapply the patch every time DF is run. +can simply add it to `dfhack.init` to reapply the patch every time DF is run. Patching on disk @@ -152,8 +151,8 @@ these rules is intended by Toady; the rest are invented by this plugin. gui/assign-rack --------------- -Bind to a key (the example config uses P), and activate when viewing a weapon -rack in the ``q`` mode. +Bind to a key (the example config uses :kbd:`P`), and activate when viewing a weapon +rack in the :kbd:`q` mode. .. image:: images/assign-rack.png @@ -166,9 +165,7 @@ 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 has not been updated since 0.34.11. See `the bug report`_ for more info. - -.. _`the bug report`: http://www.bay12games.com/dwarves/mantisbt/view.php?id=1445 + and has not been updated since 0.34.11. See :bug:`1445` for more info. * Haulers still take equipment stored in the armory away to the stockpiles, unless `fix-armory` is used. diff --git a/docs/Compile.rst b/docs/Compile.rst index 752b9b5fd9..e140c6b280 100644 --- a/docs/Compile.rst +++ b/docs/Compile.rst @@ -135,7 +135,7 @@ following environment variable:: brew install cmake brew install gcc45 - Using `MacPorts `_:: + Using `MacPorts `_:: sudo port install gcc45 +universal cmake +universal git-core +universal @@ -149,7 +149,8 @@ following environment variable:: If this is the first time you've run cpan, you will need to go through the setup process. Just stick with the defaults for everything and you'll be fine. - If you are running Snow Leopard or later, open a separate Terminal window and run:: + If you are running Snow Leopard (ie 10.6 or earlier), good luck! + You'll need to open a separate Terminal window and run:: sudo ln -s /usr/include/libxml2/libxml /usr/include/libxml @@ -214,7 +215,7 @@ Build There are several different batch files in the ``build`` folder along with a script that's used for picking the DF path. -First, run set_df_path.vbs and point the dialog that pops up at your +First, run ``set_df_path.vbs`` and point the dialog that pops up at your DF folder that you want to use for development. Next, run one of the scripts with ``generate`` prefix. These create the MSVC solution file(s): diff --git a/docs/Contributing.rst b/docs/Contributing.rst index 5691fbcc0b..cd2495922b 100644 --- a/docs/Contributing.rst +++ b/docs/Contributing.rst @@ -11,7 +11,6 @@ Several things should be kept in mind when contributing code to DFHack. Code Format ----------- - * Four space indents for C++. Never use tabs for indentation in any language. * LF (Unix style) line terminators * Avoid trailing whitespace @@ -25,14 +24,18 @@ Code Format How to get new code into DFHack ------------------------------- - -* Submit pull requests to the ``develop`` branch, not the master branch. The master branch always points at the most recent release. -* Use new branches for each feature/fix so that your changes can be merged independently (i.e. not the master or develop branch of your fork). +* Submit pull requests to the ``develop`` branch, not the ``master`` branch. + (The ``master`` branch always points at the most recent release) +* Use a new branch for each feature or bugfix so that your changes can be merged independently + (i.e. not the master or develop branch of your fork). * If possible, compile on multiple platforms when changing anything that compiles -* Update ``NEWS`` and ``docs/Authors.rst`` when applicable +* It must pass CI - run ``python travis/all.py`` to check this. +* Update ``NEWS.rst`` and ``docs/Authors.rst`` when applicable. * Create a GitHub pull request once finished -* Work done against GitHub issues tagged "bug" get priority -* Submit ideas and bug reports as issues on GitHub. Posts in the forum thread can easily get missed or forgotten. +* Submit ideas and bug reports as :issue:`issues on GitHub <>`. + Posts in the forum thread can easily get missed or forgotten. +* Work on :issue:`reported problems ` + will take priority over ideas or suggestions. .. _contributing-memory-research: @@ -62,7 +65,8 @@ All the plugins can be found in the 'plugins' folder. There's no in-depth docume on how to write one yet, but it should be easy enough to copy one and just follow the pattern. ``plugins/skeleton/skeleton.cpp`` is provided for this purpose. -Other than through plugins, it is possible to use DFHack via remote access interface, or by writing Lua scripts. +Other than through plugins, it is possible to use DFHack via remote access interface, +or by writing scripts in Lua or Ruby. There are plenty of examples in the scripts folder. The most important parts of DFHack are the Core, Console, Modules and Plugins. @@ -164,10 +168,10 @@ text. Use double-backticks to put commands in monospaced font, like this:: You can use ``cleanowned scattered x`` to dump tattered or abandoned items. If the command takes more than three arguments, format the list as a table -called Options. The table *only* lists arguments, not full commands. +called Usage. The table *only* lists arguments, not full commands. Input values are specified in angle brackets. Example:: - Options: + Usage: :arg1: A simple argument. :arg2 : Does something based on the input value. diff --git a/docs/Plugins.rst b/docs/Plugins.rst index 8e36de8619..3434233fd7 100644 --- a/docs/Plugins.rst +++ b/docs/Plugins.rst @@ -217,6 +217,8 @@ periodically when enabled with the built-in enable/disable commands: The default is 1200 ticks, or 1 day. Ticks are only counted when the game is unpaused. +.. _fixveins: + fixveins ======== Removes invalid references to mineral inclusions and restores missing ones. @@ -1890,8 +1892,7 @@ Usage: ``infiniteSky enable/disable`` Enables/disables monitoring of constructions. If you build anything in the second to highest z-level, it will allocate one more sky level. This is so you can continue to build stairs upward. -`Sometimes `_ -new z-levels disappear and cause cave-ins. +:issue:`Sometimes <254>` new z-levels disappear and cause cave-ins. Saving and loading after creating new z-levels should fix the problem. .. _liquids: @@ -1901,9 +1902,7 @@ liquids Allows adding magma, water and obsidian to the game. It replaces the normal dfhack command line and can't be used from a hotkey. Settings will be remembered as long as dfhack runs. Intended for use in combination with the command -``liquids-here`` (which can be bound to a hotkey). - -See also `this issue. `_ +``liquids-here`` (which can be bound to a hotkey). See also :issue:`80`. .. note:: From 3ebe59859b73222d9dd1e7433b976b672ad2ba64 Mon Sep 17 00:00:00 2001 From: lethosor Date: Fri, 6 Nov 2015 20:04:32 -0500 Subject: [PATCH 70/91] box-select: Fix "tiles to fill" count --- plugins/automaterial.cpp | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/automaterial.cpp b/plugins/automaterial.cpp index 83573b9fbf..60ccdd52a7 100644 --- a/plugins/automaterial.cpp +++ b/plugins/automaterial.cpp @@ -466,7 +466,7 @@ static bool is_valid_building_site(building_site &site, bool orthogonal_check, b if (construction->flags.bits.top_of_wall==0) return false; } - + if (material == tiletype_material::FIRE || material == tiletype_material::POOL || material == tiletype_material::BROOK || @@ -1120,7 +1120,7 @@ struct jobutils_hook : public df::viewscreen_dwarfmodest { ++y; OutputString(COLOR_BROWN, x, y, "Construction:", true, left_margin); - OutputString(COLOR_WHITE, x, y, int_to_string(valid_building_sites.size() + 1) + " tiles to fill", true, left_margin); + OutputString(COLOR_WHITE, x, y, int_to_string(valid_building_sites.size()) + " tiles to fill", true, left_margin); } } } From 051244c8d6f84a60cd33e2ddc02ed3944ae11343 Mon Sep 17 00:00:00 2001 From: lethosor Date: Fri, 6 Nov 2015 20:05:14 -0500 Subject: [PATCH 71/91] Fix GCC compile error --- library/modules/Constructions.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/library/modules/Constructions.cpp b/library/modules/Constructions.cpp index a60059b5c4..98410c3310 100644 --- a/library/modules/Constructions.cpp +++ b/library/modules/Constructions.cpp @@ -70,7 +70,7 @@ df::construction * Constructions::getConstruction(const int32_t index) df::construction * Constructions::findAtTile(df::coord pos) { - for (auto it = begin (world->constructions); it != end (world->constructions); ++it) { + for (auto it = world->constructions.begin(); it != world->constructions.end(); ++it) { if ((*it)->pos == pos) return *it; } From 19716a5f3cff8515bc2d6684f1237dfb78d19704 Mon Sep 17 00:00:00 2001 From: lethosor Date: Fri, 6 Nov 2015 20:17:52 -0500 Subject: [PATCH 72/91] Update NEWS --- NEWS.rst | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/NEWS.rst b/NEWS.rst index ee8c8a4bf0..316be43ed1 100644 --- a/NEWS.rst +++ b/NEWS.rst @@ -33,7 +33,7 @@ DFHack Future Internals --------- - A method for caching screen output is now available to Lua (and C++) -- Developer plugins can be ignored on startup by setting the DFHACK_NO_DEV_PLUGINS environment variable +- Developer plugins can be ignored on startup by setting the ``DFHACK_NO_DEV_PLUGINS`` environment variable - The console on Linux and OS X now recognizes keyboard input between prompts - JSON libraries available (C++ and Lua) - More DFHack build information used in plugin version checks and available to plugins and lua scripts @@ -48,7 +48,7 @@ Internals Lua --- - Scripts can be enabled with the built-in enable/disable commands -- A new function, reqscript(), is available as a safer alternative to script_environment() +- A new function, ``reqscript()``, is available as a safer alternative to ``script_environment()`` - Lua viewscreens can choose not to intercept the OPTIONS keybinding New internal commands @@ -121,7 +121,7 @@ Misc Improvements - massively reorganised, into files of more readable size - added many missing entries - indexes, internal links, offline search all documents - - includes documentation of linked projects (df-structures, 3rdparty scripts) + - includes documentation of linked projects (df-structures, third-party scripts) - better HTML generation with Sphinx - documentation for scripts now located in source files @@ -131,6 +131,7 @@ Misc Improvements - Prioritize skilled dwarves more efficiently - Prevent dwarves from running away with tools from previous jobs +- `automaterial`: Fixed several issues with constructions being allowed/disallowed incorrectly when using box-select - `dwarfmonitor`: - widgets' positions, formats, etc. are now customizable (see Readme) @@ -138,7 +139,7 @@ Misc Improvements - New mouse cursor widget - `gui/dfstatus`: Can enable/disable individual categories and customize metal bar list -- `full-heal`: "-r" option removes corpses +- `full-heal`: ``-r`` option removes corpses - `gui/gm-editor` - Pointers can now be displaced @@ -183,11 +184,11 @@ DFHack 0.40.24-r3 Internals --------- -- Ruby library now included on OSX - ruby scripts should work on OSX 10.10 +- Ruby library now included on OS X - Ruby scripts should work on OS X 10.10 - libstdc++ should work with older versions of OS X - Added support for ``onLoadMap.init``/``onUnloadMap.init`` scripts - game type detection functions are now available in the World module -- The DFHACK_LOG_MEM_RANGES environment variable can be used to log information to ``stderr.log`` on OS X +- The ``DFHACK_LOG_MEM_RANGES`` environment variable can be used to log information to ``stderr.log`` on OS X - Fixed adventure mode menu names - Fixed command usage information for some commands @@ -330,7 +331,7 @@ Internals Fixes ----- -``dfhack.sh`` can now be run from other directories on OSX +``dfhack.sh`` can now be run from other directories on OS X New Plugins ----------- @@ -653,7 +654,7 @@ Internals - Lua API for running arbitrary DFHack commands - support for multiple ``raw/init.d/*.lua`` init scripts in one save. - eventful now has a more friendly way of making custom sidebars -- on Linux and OSX the console now supports moving the cursor back and forward by a whole word. +- on Linux and OS X the console now supports moving the cursor back and forward by a whole word. New scripts ----------- @@ -777,13 +778,13 @@ Internals - Maps::canStepBetween: returns whether you can walk between two tiles in one step. - EventManager: monitors various in game events centrally so that individual plugins don't have to monitor the same things redundantly. -- Now works with OSX 10.6.8 +- Now works with OS X 10.6.8 Notable bugfixes ---------------- - autobutcher can be re-enabled again after being stopped. - stopped Dwarf Manipulator from unmasking vampires. -- Stonesense is now fixed on OSX +- Stonesense is now fixed on OS X Misc improvements ----------------- From f8ece1463c968faca5b056a9346e5205d14792fe Mon Sep 17 00:00:00 2001 From: lethosor Date: Fri, 6 Nov 2015 20:18:38 -0500 Subject: [PATCH 73/91] Sort new scripts --- NEWS.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/NEWS.rst b/NEWS.rst index 316be43ed1..4c804d1f38 100644 --- a/NEWS.rst +++ b/NEWS.rst @@ -64,26 +64,26 @@ New plugins New scripts ----------- +- `armoks-blessing`: Adjust all attributes, personality, age and skills of all dwarves in play +- `brainwash`: brainwash a dwarf (modifying their personality) - `burial`: sets all unowned coffins to allow burial ("-pets" to allow pets too) - `deteriorateclothes`: make worn clothes on the ground wear far faster to boost FPS - `deterioratecorpses`: make body parts wear away far faster to boost FPS - `deterioratefood`: make food vanish after a few months if not used +- `elevate-mental`: elevate all the mental attributes of a unit +- `elevate-physical`: elevate all the physical attributes of a unit +- `emigration`: stressed dwarves may leave your fortress if they see a chance - `fix-ster`: changes fertility/sterility of animals or dwarves -- `view-item-info`: adds information and customisable descriptions to item viewscreens -- `warn-starving`: check for starving, thirsty, or very drowsy units and pause with warning if any are found +- `gui/family-affairs`: investigate and alter romantic relationships +- `make-legendary`: modify skill(s) of a single unit - `modtools/create-unit`: create new units from nothing - `modtools/equip-item`: a script to equip items on units - `points`: set number of points available at embark screen -- `armoks-blessing`: Adjust all attributes, personality, age and skills of all dwarves in play -- `brainwash`: brainwash a dwarf (modifying their personality) -- `elevate-mental`: elevate all the mental attributes of a unit -- `elevate-physical`: elevate all the physical attributes of a unit -- `make-legendary`: modify skill(s) of a single unit - `pref-adjust`: Adjust all preferences of all dwarves in play - `rejuvenate`: make any "old" dwarf 20 years old - `starvingdead`: make undead weaken after one month on the map, and crumble after six -- `emigration`: stressed dwarves may leave your fortress if they see a chance -- `gui/family-affairs`: investigate and alter romantic relationships +- `view-item-info`: adds information and customisable descriptions to item viewscreens +- `warn-starving`: check for starving, thirsty, or very drowsy units and pause with warning if any are found New tweaks ---------- From 1c25f8f1a366789d1740316a93ac81da392ca101 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Sat, 7 Nov 2015 13:03:17 +1100 Subject: [PATCH 74/91] Unify docs for designation and map-mod plugins Plus some cleanup and flattening of the behaviour mod plugin docs --- docs/Plugins.rst | 576 +++++++++++++++++------------------- scripts/gui/power-meter.lua | 9 + 2 files changed, 287 insertions(+), 298 deletions(-) diff --git a/docs/Plugins.rst b/docs/Plugins.rst index 3434233fd7..91835cd352 100644 --- a/docs/Plugins.rst +++ b/docs/Plugins.rst @@ -718,232 +718,6 @@ materials that color the light etc... .. image:: images/rendermax.png -Designations -============ - -burrow ------- -Miscellaneous burrow control. Allows manipulating burrows and automated burrow -expansion while digging. - -Options: - -:enable feature ...: - Enable features of the plugin. -:disable feature ...: - Disable features of the plugin. -:clear-unit burrow burrow ...: - Remove all units from the burrows. -:clear-tiles burrow burrow ...: - Remove all tiles from the burrows. -:set-units target-burrow src-burrow ...: - Clear target, and adds units from source burrows. -:add-units target-burrow src-burrow ...: - Add units from the source burrows to the target. -:remove-units target-burrow src-burrow ...: - Remove units in source burrows from the target. -:set-tiles target-burrow src-burrow ...: - Clear target and adds tiles from the source burrows. -:add-tiles target-burrow src-burrow ...: - Add tiles from the source burrows to the target. -:remove-tiles target-burrow src-burrow ...: - Remove tiles in source burrows from the target. - - For these three options, in place of a source burrow it is - possible to use one of the following keywords: ABOVE_GROUND, - SUBTERRANEAN, INSIDE, OUTSIDE, LIGHT, DARK, HIDDEN, REVEALED - -Features: - -:auto-grow: When a wall inside a burrow with a name ending in '+' is dug - out, the burrow is extended to newly-revealed adjacent walls. - This final '+' may be omitted in burrow name args of commands above. - Digging 1-wide corridors with the miner inside the burrow is SLOW. - -dig ---- -This plugin makes many automated or complicated dig patterns easy. - -Basic commands: - -:digv: Designate all of the selected vein for digging. -:digvx: Also cross z-levels, digging stairs as needed. Alias for ``digv x``. -:digl: Like ``digv``, for layer stone. Also supports an ``undo`` option - to remove designations, for if you accidentally set 50 levels at once. -:diglx: Also cross z-levels, digging stairs as needed. Alias for ``digl x``. - -digexp -~~~~~~ -This command is for :wiki:`exploratory mining `. - -There are two variables that can be set: pattern and filter. - -Patterns: - -:diag5: diagonals separated by 5 tiles -:diag5r: diag5 rotated 90 degrees -:ladder: A 'ladder' pattern -:ladderr: ladder rotated 90 degrees -:clear: Just remove all dig designations -:cross: A cross, exactly in the middle of the map. - -Filters: - -:all: designate whole z-level -:hidden: designate only hidden tiles of z-level (default) -:designated: Take current designation and apply pattern to it. - -After you have a pattern set, you can use ``expdig`` to apply it again. - -Examples: - -``expdig diag5 hidden`` - Designate the diagonal 5 patter over all hidden tiles -``expdig`` - Apply last used pattern and filter -``expdig ladder designated`` - Take current designations and replace them with the ladder pattern - -digcircle -~~~~~~~~~ -A command for easy designation of filled and hollow circles. -It has several types of options. - -Shape: - -:hollow: Set the circle to hollow (default) -:filled: Set the circle to filled -:#: Diameter in tiles (default = 0, does nothing) - -Action: - -:set: Set designation (default) -:unset: Unset current designation -:invert: Invert designations already present - -Designation types: - -:dig: Normal digging designation (default) -:ramp: Ramp digging -:ustair: Staircase up -:dstair: Staircase down -:xstair: Staircase up/down -:chan: Dig channel - -After you have set the options, the command called with no options -repeats with the last selected parameters. - -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. -If an argument is given, the designation of the selected tile is -ignored, and all appropriate tiles are set to the specified -designation. - -Options: - -:dig: -:channel: -:ramp: -:updown: up/down stairs -:up: up stairs -:down: down stairs -:clear: clear designation - -digFlood --------- -Automatically digs out specified veins as they are discovered. It runs once -every time a dwarf finishes a dig job. It will only dig out appropriate tiles -that are adjacent to the finished dig job. To add a vein type, use ``digFlood 1 [type]``. -This will also enable the plugin. To remove a vein type, use ``digFlood 0 [type] 1`` -to disable, then remove, then re-enable. - -Usage: - -:help digflood: detailed help message -:digFlood 0: disable the plugin -:digFlood 1: enable the plugin -:digFlood 0 MICROCLINE COAL_BITUMINOUS 1: - disable plugin, remove microcline and bituminous coal from monitoring, then re-enable the plugin -:digFlood CLEAR: remove all inorganics from monitoring -:digFlood digAll1: ignore the monitor list and dig any vein -:digFlood digAll0: disable digAll mode - -filltraffic ------------ -Set traffic designations using flood-fill starting at the cursor. - -Traffic Type Codes: - -:H: High Traffic -:N: Normal Traffic -:L: Low Traffic -:R: Restricted Traffic - -Other Options: - -:X: Fill across z-levels. -:B: Include buildings and stockpiles. -:P: Include empty space. - -Example: - -``filltraffic H`` - When used in a room with doors, it will set traffic to HIGH in just that room. - -alltraffic ----------- -Set traffic designations for every single tile of the map (useful for resetting traffic designations). - -Traffic Type Codes: - -:H: High Traffic -:N: Normal Traffic -:L: Low Traffic -:R: Restricted Traffic - -Example: - -``alltraffic N`` - Set traffic to 'normal' for all tiles. - -restrictliquid --------------- -Restrict traffic on all visible tiles with liquid. - -restrictice ------------ -Restrict traffic on all tiles on top of visible ice. - -getplants ---------- -This tool allows plant gathering and tree cutting by RAW ID. Specify the types -of trees to cut down and/or shrubs to gather by their plant names, separated -by spaces. - -Options: - -:-t: Select trees only (exclude shrubs) -:-s: Select shrubs only (exclude trees) -:-c: Clear designations instead of setting them -:-x: Apply selected action to all plants except those specified (invert - selection) -:-a: Select every type of plant (obeys ``-t``/``-s``) - -Specifying both ``-t`` and ``-s`` will have no effect. If no plant IDs are specified, -all valid plant IDs will be listed. - - =========================== Job and Fortress management =========================== @@ -1006,7 +780,7 @@ Advanced usage: :autolabor list: List current status of all labors. :autolabor status: Show basic status information. -See `autolabor-artisans` for a differently-tunde setup. +See `autolabor-artisans` for a differently-tuned setup. Examples: @@ -1704,6 +1478,62 @@ if vein mass shifts between Z layers. The only undo option is to restore your save from backup. +.. _alltraffic: + +alltraffic +========== +Set traffic designations for every single tile of the map - useful for resetting +traffic designations. See also `filltraffic`, `restrictice`, and `restrictliquid`. + +Options: + +:H: High Traffic +:N: Normal Traffic +:L: Low Traffic +:R: Restricted Traffic + +.. _burrow: + +burrow +====== +Miscellaneous burrow control. Allows manipulating burrows and automated burrow +expansion while digging. + +Options: + +:enable feature ...: + Enable features of the plugin. +:disable feature ...: + Disable features of the plugin. +:clear-unit burrow burrow ...: + Remove all units from the burrows. +:clear-tiles burrow burrow ...: + Remove all tiles from the burrows. +:set-units target-burrow src-burrow ...: + Clear target, and adds units from source burrows. +:add-units target-burrow src-burrow ...: + Add units from the source burrows to the target. +:remove-units target-burrow src-burrow ...: + Remove units in source burrows from the target. +:set-tiles target-burrow src-burrow ...: + Clear target and adds tiles from the source burrows. +:add-tiles target-burrow src-burrow ...: + Add tiles from the source burrows to the target. +:remove-tiles target-burrow src-burrow ...: + Remove tiles in source burrows from the target. + + For these three options, in place of a source burrow it is + possible to use one of the following keywords: ABOVE_GROUND, + SUBTERRANEAN, INSIDE, OUTSIDE, LIGHT, DARK, HIDDEN, REVEALED + +Features: + +:auto-grow: When a wall inside a burrow with a name ending in '+' is dug + out, the burrow is extended to newly-revealed adjacent walls. + This final '+' may be omitted in burrow name args of commands above. + Digging 1-wide corridors with the miner inside the burrow is SLOW. + + changelayer =========== Changes material of the geology layer under cursor to the specified inorganic @@ -1829,6 +1659,129 @@ 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). +.. _dig: + +dig +=== +This plugin makes many automated or complicated dig patterns easy. + +Basic commands: + +:digv: Designate all of the selected vein for digging. +:digvx: Also cross z-levels, digging stairs as needed. Alias for ``digv x``. +:digl: Like ``digv``, for layer stone. Also supports an ``undo`` option + to remove designations, for if you accidentally set 50 levels at once. +:diglx: Also cross z-levels, digging stairs as needed. Alias for ``digl x``. + +digexp +------ +This command is for :wiki:`exploratory mining `. + +There are two variables that can be set: pattern and filter. + +Patterns: + +:diag5: diagonals separated by 5 tiles +:diag5r: diag5 rotated 90 degrees +:ladder: A 'ladder' pattern +:ladderr: ladder rotated 90 degrees +:clear: Just remove all dig designations +:cross: A cross, exactly in the middle of the map. + +Filters: + +:all: designate whole z-level +:hidden: designate only hidden tiles of z-level (default) +:designated: Take current designation and apply pattern to it. + +After you have a pattern set, you can use ``expdig`` to apply it again. + +Examples: + +``expdig diag5 hidden`` + Designate the diagonal 5 patter over all hidden tiles +``expdig`` + Apply last used pattern and filter +``expdig ladder designated`` + Take current designations and replace them with the ladder pattern + +digcircle +--------- +A command for easy designation of filled and hollow circles. +It has several types of options. + +Shape: + +:hollow: Set the circle to hollow (default) +:filled: Set the circle to filled +:#: Diameter in tiles (default = 0, does nothing) + +Action: + +:set: Set designation (default) +:unset: Unset current designation +:invert: Invert designations already present + +Designation types: + +:dig: Normal digging designation (default) +:ramp: Ramp digging +:ustair: Staircase up +:dstair: Staircase down +:xstair: Staircase up/down +:chan: Dig channel + +After you have set the options, the command called with no options +repeats with the last selected parameters. + +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. +If an argument is given, the designation of the selected tile is +ignored, and all appropriate tiles are set to the specified +designation. + +Options: + +:dig: +:channel: +:ramp: +:updown: up/down stairs +:up: up stairs +:down: down stairs +:clear: clear designation + +digFlood +======== +Automatically digs out specified veins as they are discovered. It runs once +every time a dwarf finishes a dig job. It will only dig out appropriate tiles +that are adjacent to the finished dig job. To add a vein type, use ``digFlood 1 [type]``. +This will also enable the plugin. To remove a vein type, use ``digFlood 0 [type] 1`` +to disable, then remove, then re-enable. + +Usage: + +:help digflood: detailed help message +:digFlood 0: disable the plugin +:digFlood 1: enable the plugin +:digFlood 0 MICROCLINE COAL_BITUMINOUS 1: + disable plugin, remove microcline and bituminous coal from monitoring, then re-enable the plugin +:digFlood CLEAR: remove all inorganics from monitoring +:digFlood digAll1: ignore the monitor list and dig any vein +:digFlood digAll0: disable digAll mode + +.. _feature: + feature ======= Enables management of map features. @@ -1844,6 +1797,26 @@ Options: :show X: Marks the selected map feature as discovered. :hide X: Marks the selected map feature as undiscovered. +.. _filltraffic: + +filltraffic +=========== +Set traffic designations using flood-fill starting at the cursor. +See also `alltraffic`, `restrictice`, and `restrictliquid`. Options: + +:H: High Traffic +:N: Normal Traffic +:L: Low Traffic +:R: Restricted Traffic +:X: Fill across z-levels. +:B: Include buildings and stockpiles. +:P: Include empty space. + +Example: + +``filltraffic H`` + When used in a room with doors, it will set traffic to HIGH in just that room. + .. _fortplan: fortplan @@ -1880,6 +1853,24 @@ All of the building designation uses `Planning Mode `, so you do n have the items available to construct all the buildings when you run fortplan with the .csv file. +getplants +========= +This tool allows plant gathering and tree cutting by RAW ID. Specify the types +of trees to cut down and/or shrubs to gather by their plant names, separated +by spaces. + +Options: + +:-t: Select trees only (exclude shrubs) +:-s: Select shrubs only (exclude trees) +:-c: Clear designations instead of setting them +:-x: Apply selected action to all plants except those specified (invert + selection) +:-a: Select every type of plant (obeys ``-t``/``-s``) + +Specifying both ``-t`` and ``-s`` will have no effect. If no plant IDs are specified, +all valid plant IDs will be listed. + infiniteSky =========== Automatically allocates new z-levels of sky at the top of the map as you build up, @@ -1968,6 +1959,43 @@ 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. +plant +===== +A tool for creating shrubs, growing, or getting rid of them. + +Subcommands: + +:create: Creates a new sapling under the cursor. Takes a raw ID as argument + (e.g. TOWER_CAP). The cursor must be located on a dirt or grass floor tile. +:grow: Turns saplings into trees; under the cursor if a sapling is selected, + or every sapling on the map if the cursor is hidden. +:extirpate: Kills the tree or shrub under the cursor, instantly turning them to ashes. +:immolate: Sets the plants on fire instead. The fires can and *will* spread ;) + +For mass effects, use one of the additional options: + +:shrubs: affect all shrubs on the map +:trees: affect all trees on the map +:all: affect every plant! + +regrass +======= +Regrows all the grass. Not much to it ;) + +.. _restrictice: + +restrictice +=========== +Restrict traffic on all tiles on top of visible ice. +See also `alltraffic`, `filltraffic`, and `restrictliquid`. + +.. _restrictliquid: + +restrictliquid +============== +Restrict traffic on all visible tiles with liquid. +See also `alltraffic`, `filltraffic`, and `restrictice`. + .. _tiletypes: tiletypes @@ -2079,29 +2107,6 @@ Options: Beware that filling in hollow veins will trigger a demon invasion on top of your miner when you dig into the region that used to be hollow. -plant -===== -A tool for creating shrubs, growing, or getting rid of them. - -Subcommands: - -:create: Creates a new sapling under the cursor. Takes a raw ID as argument - (e.g. TOWER_CAP). The cursor must be located on a dirt or grass floor tile. -:grow: Turns saplings into trees; under the cursor if a sapling is selected, - or every sapling on the map if the cursor is hidden. -:extirpate: Kills the tree or shrub under the cursor, instantly turning them to ashes. -:immolate: Sets the plants on fire instead. The fires can and *will* spread ;) - -For mass effects, use one of the additional options: - -:shrubs: affect all shrubs on the map -:trees: affect all trees on the map -:all: affect every plant! - -regrass -======= -Regrows all the grass. Not much to it ;) - weather ======= Prints the current weather, and lets you change the weather to 'clear', 'rain' @@ -2252,49 +2257,32 @@ Options: Known limitations: if the selected unit is currently performing a job, the mood will not be started. - -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. - .. _siege-engine: siege-engine ------------- -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, -e.g. like making siegers bring their own, are something only Toady can do. +============ +Siege engines in DF haven't been updated since the game was 2D, and can +only aim in four directions. This plugin allows you to: -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 -just stones. +* link siege engines to stockpiles +* load any object into a catapult, not just stones +* aim at a rectangular area in any direction, and across Z-levels -The configuration front-end to the plugin is implemented by `gui/siege-engine`. +The front-end is implemented by `gui/siege-engine`. .. _power-meter: 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. -The configuration front-end is implemented by `gui/power-meter`. Bind it to a -key (the example config uses :kbd:`Ctrl`:kbd:`Shift`:kbd:`M`) and activate after selecting Pressure Plate -in the build menu. - -.. image:: images/power-meter.png - -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. +The configuration front-end is implemented by `gui/power-meter`. .. _steam-engine: steam-engine ------------- +============ The steam-engine plugin detects custom workshops with STEAM_ENGINE in their token, and turns them into real steam engines. @@ -2303,34 +2291,29 @@ power, but windmills give relatively little power, and water wheels require flowing water, which must either be a real river and thus immovable and limited in supply, or actually flowing and thus laggy. -Steam engines are an alternative to water reactors that actually makes -sense, and hopefully doesn't lag. Also, unlike e.g. animal treadmills, -it can be done just by combining existing features of the game engine -in a new way with some glue code and a bit of custom logic. +Compared to the :wiki:`water reactor ` +exploit, steam engines make a lot of sense! 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. -Since this building is a machine, and machine collapse -code cannot be hooked, it would collapse over true open space. -As a loophole, down stairs provide support to machines, while -being passable, so use them. +Due to DFHack limits, the workshop will collapse over true open space. +However down stairs are passable but support machines, so you can use them. After constructing the building itself, machines can be connected to the edge tiles that look like gear boxes. Their exact position is extracted from the workshop raws. -Like with collapse above, part of the code involved in -machine connection cannot be hooked. As a result, the workshop +Like with collapse above, due to DFHack limits the workshop can only immediately connect to machine components built AFTER it. This also means that engines cannot be chained without intermediate axles built after both engines. 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 @@ -2364,7 +2347,7 @@ decrease it by further 4%, and also decrease the whole steam 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. @@ -2374,7 +2357,7 @@ toppled during operation by a building destroyer, or a 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 @@ -2386,15 +2369,12 @@ being generated. .. _add-spatter: 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 -the `clean` ``items`` command. +contaminants are immune to being washed away by water or destroyed by `clean`. The plugin is intended to give some use to all those poisons that can -be bought from caravans. :) - -To be really useful this needs patches for :bug:`808`, ie `tweak` -``fix-dimensions`` and `tweak` ``advmode-contained``. +be bought from caravans. It's most useful when combined with +`tweak` ``fix-dimensions`` and ``advmode-contained`` to patch :bug:`808`. diff --git a/scripts/gui/power-meter.lua b/scripts/gui/power-meter.lua index 51908bd0fc..ac10e5dc7e 100644 --- a/scripts/gui/power-meter.lua +++ b/scripts/gui/power-meter.lua @@ -5,6 +5,15 @@ gui/power-meter =============== An in-game interface for `power-meter`. +Bind it to a key (default :kbd:`Ctrl`:kbd:`Shift`:kbd:`M`) and activate +after selecting Pressure Plate in the build menu. + +.. image:: /docs/images/power-meter.png + +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. + =end]] local utils = require 'utils' local gui = require 'gui' From 3d801d45c6b2a1390271565c5acc775642e585fa Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Sat, 7 Nov 2015 13:52:21 +1100 Subject: [PATCH 75/91] Flatten plugin documentation The obvious solution to not knowing how to categories plugins well is to do so a little less. This commit does not rearrange them though, since I thought that counterproductive without a better idea of what to do. - removed many headings that are not commands - fixed a few links and added some - clarified stockpiles plugins --- NEWS.rst | 20 ++--- docs/Plugins.rst | 205 +++++++++++++++++++++-------------------------- 2 files changed, 103 insertions(+), 122 deletions(-) diff --git a/NEWS.rst b/NEWS.rst index 53be4c1490..96412f6715 100644 --- a/NEWS.rst +++ b/NEWS.rst @@ -103,7 +103,7 @@ Fixes - help: now recognizes built-in commands, like "help" - `manipulator`: fixed crash when selecting custom professions when none are found - `remotefortressreader`: fixed crash when attempting to send map info when no map was loaded -- `search`: fixed crash in unit list after cancelling a job; fixed crash when disabling stockpile category after searching in a subcategory +- `search-plugin`: fixed crash in unit list after cancelling a job; fixed crash when disabling stockpile category after searching in a subcategory - `stockpiles`: now checks/sanitizes filenames when saving - `stocks`: fixed a crash when right-clicking - `steam-engine`: fixed a crash on arena load; number keys (e.g. 2/8) take priority over cursor keys when applicable @@ -157,7 +157,7 @@ Misc Improvements - `prospect`: works from within command-prompt - `quicksave`: Restricted to fortress mode - `remotefortressreader`: Exposes more information -- `search`: +- `search-plugin`: - Supports noble suggestion screen (e.g. suggesting a baron) - Supports fortress mode loo[k] menu @@ -470,8 +470,8 @@ Misc Improvements - `EventManager`: deals with frame_counter getting reset properly now. - `modtools/item-trigger`: fixed equip/unequip bug and corrected minor documentation error - `teleport`: Updated with proper argument handling and proper unit-at-destination handling. -- `autotrade `: Removed the newly obsolete :guilabel:`Mark all` functionality. -- `search`: Adapts to the new trade screen column width +- `autotrade`: Removed the newly obsolete :guilabel:`Mark all` functionality. +- `search-plugin`: Adapts to the new trade screen column width - `tweak fast-trade `: Switching the fast-trade keybinding to Shift-Up/Shift-Down, due to Select All conflict @@ -486,8 +486,8 @@ Fixes ----- - Stopped duplicate load/unload events when unloading a world - Stopped ``-e`` from being echoed when DFHack quits on Linux -- `automelt `: now uses a faster method to locate items -- `autotrade `: "Mark all" no longer double-marks bin contents +- `automelt`: now uses a faster method to locate items +- `autotrade`: "Mark all" no longer double-marks bin contents - `drain-aquifer`: new script replaces the buggy plugin - `embark-tools`: no longer conflicts with keys on the notes screen - `fastdwarf`: Fixed problems with combat/attacks @@ -537,18 +537,18 @@ Internals New Plugins ----------- - `hotkeys`: Shows ingame viewscreen with all dfhack keybindings active in current mode. -- `automelt `: allows marking stockpiles so any items placed in them will be designated for melting +- `automelt`: allows marking stockpiles so any items placed in them will be designated for melting Fixes ----- - possible crash fixed for `gui/hack-wish` -- `search`: updated to not conflict with BUILDJOB_SUSPEND +- `search-plugin`: updated to not conflict with BUILDJOB_SUSPEND - `workflow`: job_material_category -> dfhack_material_category Misc Improvements ----------------- - now you can use ``@`` to print things in interactive Lua with subtley different semantics -- optimizations for stockpiles for `autotrade ` and `stockflow` +- optimizations for stockpiles for `autotrade` and `stockflow` - updated `exportlegends` to work with new maps, dfhack 40.11 r1+ @@ -561,7 +561,7 @@ Internals Fixes ----- - `3dveins`: should no longer hang/crash on specific maps -- `autotrade `, `search`: fixed some layout issues +- `autotrade`, `search-plugin`: fixed some layout issues - `deathcause`: updated - `gui/hack-wish`: should work now - `reveal`: no longer allocates data for nonexistent map blocks diff --git a/docs/Plugins.rst b/docs/Plugins.rst index 91835cd352..7df79e6251 100644 --- a/docs/Plugins.rst +++ b/docs/Plugins.rst @@ -12,9 +12,9 @@ hopefully organised in a way you will find useful. .. contents:: :depth: 3 -=========================== -Visualizers and data export -=========================== +=============================== +Data inspection and visualizers +=============================== .. _stonesense: @@ -64,10 +64,6 @@ An in-development plugin for realtime fortress visualisation. See :forums:`Armok Vision <146473>`. -============== -Map inspection -============== - cursecheck ========== Checks a single map tile or the whole map/world for cursed creatures (ghosts, @@ -346,13 +342,26 @@ UI Upgrades existing DF screens, they deliberately use red instead of green for the key. -DFHack Interface -================ +.. _automelt: + +automelt +======== +When automelt is enabled for a stockpile, any meltable items placed +in it will be designated to be melted. +This plugin adds an option to the :kbd:`q` menu when `enabled `. + +.. _autotrade: + +autotrade +========= +When autotrade is enabled for a stockpile, any items placed in it will be +designated to be taken to the Trade Depot whenever merchants are on the map. +This plugin adds an option to the :kbd:`q` menu when `enabled `. .. _command-prompt: command-prompt --------------- +============== An in-game DFHack terminal, where you can enter other commands. Best used from a keybinding; by default :kbd:`Ctrl`:kbd:`Shift`:kbd:`P`. @@ -371,7 +380,7 @@ Otherwise somewhat similar to `gui/quickcmd`. .. _hotkeys: hotkeys -------- +======= Opens an in-game screen showing which DFHack keybindings are active in the current context. @@ -384,7 +393,7 @@ keybinding is :kbd:`Ctrl`:kbd:`F1`. See also `hotkey-notes`. .. _rb_eval: rb_eval -------- +======= Evaluate the following arguments as a ruby string. Best used as ``:rb_eval [string]``, for the special parsing mode. @@ -443,6 +452,9 @@ The following mouse shortcuts are also available: Pressing :kbd:`Esc` normally returns to the unit screen, but :kbd:`Shift`:kbd:`Esc` would exit directly to the main dwarf mode screen. +.. comment - the link target "search" is reserved for the Sphinx search page +.. _search-plugin: + search ====== The search plugin adds search to the Stocks, Animals, Trading, Stockpile, @@ -482,20 +494,17 @@ only fat or tallow by forbidding fats, then searching for fat/tallow, and using Permit Fats again while the list is filtered. -Game interface -============== - .. _nopause: nopause -------- +======= Disables pausing (both manual and automatic) with the exception of pause forced by `reveal` ``hell``. This is nice for digging under rivers. .. _embark-tools: embark-tools ------------- +============ A collection of embark-related tools. Usage and available tools:: embark-tools enable/disable tool [tool]... @@ -508,7 +517,7 @@ A collection of embark-related tools. Usage and available tools:: :sticky: Maintains the selected local area while navigating the world map automaterial ------------- +============ This makes building constructions (walls, floors, fortifications, etc) a little bit easier by saving you from having to trawl through long lists of materials each time you place one. @@ -544,7 +553,7 @@ enabled materials, you should be able to place complex constructions more conven .. _buildingplan: buildingplan ------------- +============ When active (via ``enable buildingplan``), this plugin adds a planning mode for furniture placement. You can then place furniture and other buildings before the required materials are available, and the job will be unsuspended when @@ -558,7 +567,7 @@ with minimal space dedicated to stockpiles. .. _confirm: confirm -------- +======= Implements several confirmation dialogs for potentially destructive actions (for example, seizing goods from traders or deleting hauling routes). @@ -571,7 +580,7 @@ Usage: Enable (or disable) specific confirmation dialogues. follow ------- +====== Makes the game view follow the currently highlighted unit after you exit from the current menu or cursor mode. Handy for watching dwarves running around. Deactivated by moving the view manually. @@ -579,7 +588,7 @@ by moving the view manually. .. _mousequery: mousequery ----------- +========== Adds mouse controls to the DF interface, eg click-and-drag designations. Options: @@ -598,41 +607,38 @@ Usage:: .. _resume: resume ------- +====== Allows automatic resumption of suspended constructions, along with colored UI hints for construction status. tidlers -------- +======= Toggle between all possible positions where the idlers count can be placed. .. _trackstop: trackstop ---------- +========= Adds a :kbd:`q` menu for track stops, which is completely blank by default. This allows you to view and/or change the track stop's friction and dump direction settings, using the keybindings from the track stop building interface. twaterlvl ---------- +========= Toggle between displaying/not displaying liquid depth as numbers. .. _stocks: stocks ------- -An improved stocks screen. - -stockpile management --------------------- +====== +Replaces the DF stocks screen with an improved version. .. _stocksettings: .. _stockpiles: -import/export -~~~~~~~~~~~~~ -The following commands allow you to save and load stockpile settings. +stocksettings +============= +Offers the following commands to save and load stockpile settings. See `gui/stockpiles` for an in-game interface. :copystock: Copies the parameters of the currently highlighted stockpile to the custom @@ -656,27 +662,10 @@ Note that files are relative to the DF folder, so put your files there or in a subfolder for easy access. Filenames should not have spaces. Generated materials, divine metals, etc are not saved as they are different in every world. -.. _`Stockpile automation`: - -Stockpile automation -~~~~~~~~~~~~~~~~~~~~ - -Enable the autodump, automelt and autotrade plugins in your dfhack.init with:: - - enable autodump automelt autotrade - -When querying a stockpile, options will appear to toggle automation settings for this stockpile. - -When automelt is enabled for a stockpile, any meltable items placed in it will be designated -to be melted. When autotrade is enabled for a stockpile, any items placed in it will be -designated to be taken to the Trade Depot whenever merchants are on the map. -When autodump is enabled for a stockpile, any items placed in this stockpile will -automatically be designated to be dumped. - .. _rename: rename ------- +====== Allows renaming various things. Use `gui/rename` for an in-game interface. Options: @@ -698,10 +687,9 @@ Options: .. _rendermax: 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 -`the Bay12 Rendermax thread `_. +black color in palette to non totally black. See :forums:`128487` for more info. Options: @@ -798,7 +786,9 @@ Examples: .. _autohauler: autohauler ----------- +========== +Autohauler is an autolabor fork. + Rather than the all-of-the-above means of autolabor, autohauler will instead only manage hauling labors and leave skilled labors entirely to the user, who will probably use Dwarf Therapist to do so. @@ -817,13 +807,10 @@ being assigned when the skill is present. By default this is the unused ALCHEMIST labor but can be changed by the user. -Job management -============== - .. _job: job ---- +=== Command for general job query and manipulation. Options: @@ -839,8 +826,8 @@ Options: Replace the exact item type id in the job item. job-material ------------- -Alter the material of the selected job. +============ +Alter the material of the selected job. Similar to ``job item-material ...`` Invoked as:: @@ -855,19 +842,19 @@ Intended to be used as a keybinding: over the first available choice with the matching material. job-duplicate -------------- -Duplicate the selected job in a workshop: - -* In :kbd:`q` mode, when a job is highlighted within a workshop or furnace building, - instantly duplicates the job. +============= +In :kbd:`q` mode, when a job is highlighted within a workshop or furnace +building, calling ``job-duplicate`` instantly duplicates the job. .. _stockflow: stockflow ---------- +========= Allows the fortress bookkeeper to queue jobs through the manager, based on space or items available in stockpiles. +Inspired by `workflow`. + Usage: ``stockflow enable`` @@ -896,11 +883,9 @@ waiting for the bookkeeper. .. _workflow: workflow --------- -Manage control of repeat jobs. - -Check out `gui/workflow` for a simple front-end integrated -in the game UI. +======== +Manage control of repeat jobs. `gui/workflow` provides a simple +front-end integrated in the game UI. Usage: @@ -928,7 +913,7 @@ Usage: Delete all constraints. Function -~~~~~~~~ +-------- When the plugin is enabled, it protects all repeat jobs from removal. If they do disappear due to any cause, they are immediately re-added to their workshop and suspended. @@ -940,15 +925,14 @@ the amount has to drop before jobs are resumed; this is intended to reduce the frequency of jobs being toggled. Constraint format -~~~~~~~~~~~~~~~~~ +----------------- The constraint spec consists of 4 parts, separated with ``/`` characters:: ITEM[:SUBTYPE]/[GENERIC_MAT,...]/[SPECIFIC_MAT:...]/[LOCAL,] The first part is mandatory and specifies the item type and subtype, -using the raw tokens for items, in the same syntax you would e.g. use -for a custom reaction input. For more information, see -`this page. `_ +using the raw tokens for items (the same syntax used custom reaction inputs). +For more information, see :wiki:`this wiki page `. The subsequent parts are optional: @@ -967,7 +951,7 @@ The subsequent parts are optional: be used to ignore imported items or items below a certain quality. Constraint examples -~~~~~~~~~~~~~~~~~~~ +------------------- Keep metal bolts within 900-1000, and wood/bone within 150-200:: workflow amount AMMO:ITEM_AMMO_BOLTS/METAL 1000 100 @@ -1005,7 +989,7 @@ Make sure there are always 80-100 units of dimple dye:: .. note:: In order for this to work, you have to set the material of the PLANT input - on the Mill Plants job to MUSHROOM_CUP_DIMPLE using the `job` ``item-material`` + on the Mill Plants job to MUSHROOM_CUP_DIMPLE using the `job item-material ` command. Otherwise the plugin won't be able to deduce the output material. Maintain 10-100 locally-made crafts of exceptional quality:: @@ -1013,13 +997,10 @@ Maintain 10-100 locally-made crafts of exceptional quality:: workflow count CRAFTS///LOCAL,EXCEPTIONAL 100 90 -Cleanup and garbage disposal -============================ - .. _clean: clean ------ +===== Cleans all the splatter that get scattered all over the map, items and creatures. In an old fortress, this can significantly reduce FPS lag. It can also spoil your !!FUN!!, so think before you use it. @@ -1036,15 +1017,19 @@ Extra options for ``map``: :snow: Also remove snow coverings. spotclean ---------- +========= Works like ``clean map snow mud``, but only for the tile under the cursor. Ideal if you want to keep that bloody entrance ``clean map`` would clean up. .. _autodump: autodump --------- -This utility lets you quickly move all items designated to be dumped. +======== +This plugin adds an option to the :kbd:`q` menu for stckpiles when `enabled `. +When autodump is enabled for a stockpile, any items placed in the stockpile will +automatically be designated to be dumped. + +ALternatively, you can use it to quickly move all items designated to be dumped. Items are instantly moved to the cursor position, the dump flag is unset, and the forbid flag is set, as if it had been dumped normally. Be aware that any active dump item tasks still point at the item. @@ -1054,18 +1039,17 @@ 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. Alias ``autodump-destroy-here``, for keybindings. + If called again before the game is resumed, cancels destroy. +:destroy-here: As ``destroy``, but only the selected item in the :kbd:`k` list, + or inside a container. + 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-item -~~~~~~~~~~~~~~~~~~~~~ -Destroy the selected item. The item may be selected in the :kbd:`k` list, or inside -a container. If called again before the game is resumed, cancels destroy. cleanowned ----------- +========== Confiscates items owned by dwarfs. By default, owned food on the floor and rotten items are confistacted and dumped. @@ -1085,13 +1069,10 @@ Example: worn items with 'X' damage and above. -Fortress activity management -============================ - .. _dwarfmonitor: dwarfmonitor ------------- +============ Records dwarf activity to measure fort efficiency. Options: @@ -1164,13 +1145,13 @@ Some widgets support additional options: nothing will be displayed. workNow -------- +======= Force all dwarves to look for a job immediately, or as soon as the game is unpaused. .. _seedwatch: seedwatch ---------- +========= Watches the numbers of seeds available and enables/disables seed and plant cooking. Each plant type can be assigned a limit. If their number falls below that limit, @@ -1200,7 +1181,7 @@ Examples: .. _zone: zone ----- +==== Helps a bit with managing activity zones (pens, pastures and pits) and cages. Options: @@ -1256,7 +1237,7 @@ Filters: :milkable: Race is milkable. Negatable. 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 @@ -1265,7 +1246,7 @@ and use 'zone assign' to assign them to their new home. Allows pitting your 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 @@ -1286,14 +1267,14 @@ are not properly added to your own stocks; slaughtering them should work). 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 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 @@ -1304,7 +1285,7 @@ would make no sense, but can be used together with 'nick' or 'remnick' and all 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. @@ -1327,7 +1308,7 @@ Examples on the current default zone. autonestbox ------------ +=========== Assigns unpastured female egg-layers to nestbox zones. Requires that you create pen/pasture zones above nestboxes. If the pen is bigger than 1x1 the nestbox must be in the top left corner. Only 1 unit will be assigned per pen, regardless @@ -1349,7 +1330,7 @@ Options: .. _autobutcher: 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. @@ -1441,7 +1422,7 @@ add some new races with 'watch'. If you simply want to stop it completely use autobutcher unwatch ALPACA CAT autochop ---------- +======== Automatically manage tree cutting designation to keep available logs withing given quotas. @@ -1674,7 +1655,7 @@ Basic commands: :diglx: Also cross z-levels, digging stairs as needed. Alias for ``digl x``. digexp ------- +====== This command is for :wiki:`exploratory mining `. There are two variables that can be set: pattern and filter. @@ -1706,7 +1687,7 @@ Examples: Take current designations and replace them with the ladder pattern digcircle ---------- +========= A command for easy designation of filled and hollow circles. It has several types of options. @@ -1742,7 +1723,7 @@ Examples: 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 @@ -2291,7 +2272,7 @@ power, but windmills give relatively little power, and water wheels require flowing water, which must either be a real river and thus immovable and limited in supply, or actually flowing and thus laggy. -Compared to the :wiki:`water reactor ` +Compared to the :wiki:`water reactor ` exploit, steam engines make a lot of sense! Construction From 6dacbe3d9f4401e1b4affacd9403fca0f6fbcfc6 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Sat, 7 Nov 2015 16:59:11 +1100 Subject: [PATCH 76/91] Add docs for "sort" and "diggingInvaders" plugins I don't know how these were missed, but I've now checked everything listed by "plug" but not (previously) a heading in Plugins.rst --- docs/Core.rst | 4 +- docs/Plugins.rst | 101 ++++++++++++++++++++++++++++++++++++++--------- 2 files changed, 85 insertions(+), 20 deletions(-) diff --git a/docs/Core.rst b/docs/Core.rst index 17b6d3174a..51d0ec9556 100644 --- a/docs/Core.rst +++ b/docs/Core.rst @@ -237,7 +237,7 @@ The following commands are *not* built-in, but offer similarly useful functions. * `multicmd` * `nopause` * `quicksave` -* `rb_eval` +* `rb` * `repeat` @@ -350,7 +350,7 @@ This section is for odd but important notes that don't fit anywhere else. double quotes. To include a double quote character, use ``\"``. * If the first non-whitespace character is ``:``, the command is parsed in - an alternative mode which is very useful for the `lua` and `rb_eval` commands. + an alternative mode which is very useful for the `lua` and `rb` commands. The following two command lines are exactly equivalent:: :foo a b "c d" e f diff --git a/docs/Plugins.rst b/docs/Plugins.rst index 7df79e6251..3b8b7d132e 100644 --- a/docs/Plugins.rst +++ b/docs/Plugins.rst @@ -370,7 +370,7 @@ Usage: ``command-prompt [entry]`` If called with an entry, it starts with that text filled in. Most useful for developers, who can set a keybinding to open a laungage interpreter for lua or Ruby by starting with the -`:lua ` or `:rb_eval ` commands. +`:lua ` or `:rb ` commands. Otherwise somewhat similar to `gui/quickcmd`. @@ -390,12 +390,12 @@ Type ``hotkeys`` into the DFHack console to open the screen, or bind the command to a globally active hotkey. The default keybinding is :kbd:`Ctrl`:kbd:`F1`. See also `hotkey-notes`. -.. _rb_eval: +.. _rb: -rb_eval -======= -Evaluate the following arguments as a ruby string. Best used as -``:rb_eval [string]``, for the special parsing mode. +rb +== +Ruby language plugin, which evaluates the following arguments as a ruby string. +Best used as ``:rb [string]``, for the special parsing mode. Alias ``rb_eval``. .. _manipulator: @@ -627,6 +627,42 @@ twaterlvl ========= Toggle between displaying/not displaying liquid depth as numbers. +.. _sort-items: + +sort-items +========== +Sort the visible item list:: + + sort-items order [order...] + +Sort the item list using the given sequence of comparisons. +The ``<`` prefix for an order makes undefined values sort first. +The ``>`` prefix reverses the sort order for defined values. + +Item order examples:: + + description material wear type quality + +The orderings are defined in ``hack/lua/plugins/sort/*.lua`` + +.. _sort-units: + +sort-units +========== +Sort the visible unit list:: + + sort-units order [order...] + +Sort the unit list using the given sequence of comparisons. +The ``<`` prefix for an order makes undefined values sort first. +The ``>`` prefix reverses the sort order for defined values. + +Unit order examples:: + + name age arrival squad squad_position profession + +The orderings are defined in ``hack/lua/plugins/sort/*.lua`` + .. _stocks: stocks @@ -2099,6 +2135,15 @@ or 'snow', with those words as commands (eg ``weather rain``). Mods and Cheating ================= +.. _add-spatter: + +add-spatter +=========== +This plugin makes reactions with names starting with ``SPATTER_ADD_`` +produce contaminants on the items instead of improvements. The plugin is +intended to give some use to all those poisons that can be bought from caravans, +so they're immune to being washed away by water or destroyed by `clean`. + .. _adv-bodyswap: adv-bodyswap @@ -2153,6 +2198,38 @@ Options: :building: Subsequent items will become part of the currently selected building. Good for loading traps; do not use with workshops (or deconstruct to use the item). +.. _diggingInvaders: + +diggingInvaders +=============== +Makes invaders dig or destroy constructions to get to your dwarves. + +To enable/disable the pluging, use: ``diggingInvaders (1|enable)|(0|disable)`` + +Basic usage: + +:add GOBLIN: registers the race GOBLIN as a digging invader. Case-sensitive. +:remove GOBLIN: unregisters the race GOBLIN as a digging invader. Case-sensitive. +:now: makes invaders try to dig now, if plugin is enabled +:clear: clears all digging invader races +:edgesPerTick n: makes the pathfinding algorithm work on at most n edges per tick. + Set to 0 or lower to make it unlimited. + +You can also use ``diggingInvaders setCost (race) (action) n`` to set the +pathing cost of particular action, or ``setDelay`` to set how long it takes. +Costs and delays are per-tile, and the table shows default values. + +============================== ======= ====== ================================= +Action Cost Delay Notes +============================== ======= ====== ================================= +``walk`` 1 0 base cost in the path algorithm +``destroyBuilding`` 2 1,000 delay adds to the job_completion_timer of destroy building jobs that are assigned to invaders +``dig`` 10,000 1,000 digging soil or natural stone +``destroyRoughConstruction`` 1,000 1,000 constructions made from boulders +``destroySmoothConstruction`` 100 100 constructions made from blocks or bars +============================== ======= ====== ================================= + + .. _fastdwarf: fastdwarf @@ -2347,15 +2424,3 @@ 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: - -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 `clean`. - -The plugin is intended to give some use to all those poisons that can -be bought from caravans. It's most useful when combined with -`tweak` ``fix-dimensions`` and ``advmode-contained`` to patch :bug:`808`. - From 0bb203e7c96fd072db03de45cf3ed888202764e6 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Sat, 7 Nov 2015 23:42:14 +1100 Subject: [PATCH 77/91] Replace initflags plugin with scripts Progress towards #722 --- NEWS.rst | 1 + docs/Plugins.rst | 8 ------- plugins/CMakeLists.txt | 1 - plugins/initflags.cpp | 51 ------------------------------------------ scripts/tidlers.lua | 17 ++++++++++++++ scripts/twaterlvl.lua | 11 +++++++++ 6 files changed, 29 insertions(+), 60 deletions(-) delete mode 100644 plugins/initflags.cpp create mode 100644 scripts/tidlers.lua create mode 100644 scripts/twaterlvl.lua diff --git a/NEWS.rst b/NEWS.rst index ee8c8a4bf0..325126bc00 100644 --- a/NEWS.rst +++ b/NEWS.rst @@ -167,6 +167,7 @@ Misc Improvements - `stocks`: can now match beginning and end of item names - `teleport`: Fixed cursor recognition +- `tidlers`, `twaterlvl`: now implemented by scripts instead of a plugin - `tweak`: - debug output now logged to stderr.log instead of console - makes DFHack start faster diff --git a/docs/Plugins.rst b/docs/Plugins.rst index 9ea4b309fd..20a54279e9 100644 --- a/docs/Plugins.rst +++ b/docs/Plugins.rst @@ -564,10 +564,6 @@ resume Allows automatic resumption of suspended constructions, along with colored UI hints for construction status. -tidlers -------- -Toggle between all possible positions where the idlers count can be placed. - .. _trackstop: trackstop @@ -576,10 +572,6 @@ Adds a :kbd:`q` menu for track stops, which is completely blank by default. This allows you to view and/or change the track stop's friction and dump direction settings, using the keybindings from the track stop building interface. -twaterlvl ---------- -Toggle between displaying/not displaying liquid depth as numbers. - .. _stocks: stocks diff --git a/plugins/CMakeLists.txt b/plugins/CMakeLists.txt index 0cb8b6df29..115f6196e1 100644 --- a/plugins/CMakeLists.txt +++ b/plugins/CMakeLists.txt @@ -133,7 +133,6 @@ if (BUILD_SUPPORTED) DFHACK_PLUGIN(getplants getplants.cpp) DFHACK_PLUGIN(hotkeys hotkeys.cpp) DFHACK_PLUGIN(infiniteSky infiniteSky.cpp) - DFHACK_PLUGIN(initflags initflags.cpp) DFHACK_PLUGIN(isoworldremote isoworldremote.cpp PROTOBUFS isoworldremote) DFHACK_PLUGIN(jobutils jobutils.cpp) DFHACK_PLUGIN(lair lair.cpp) diff --git a/plugins/initflags.cpp b/plugins/initflags.cpp deleted file mode 100644 index 7a4ad30b02..0000000000 --- a/plugins/initflags.cpp +++ /dev/null @@ -1,51 +0,0 @@ -#include "Core.h" -#include "Console.h" -#include "Export.h" -#include "PluginManager.h" - -#include "DataDefs.h" -#include "df/d_init.h" - -using std::vector; -using std::string; -using std::endl; -using namespace DFHack; -using namespace df::enums; - -DFHACK_PLUGIN("initflags"); -REQUIRE_GLOBAL(d_init); - -command_result twaterlvl(color_ostream &out, vector & parameters); -command_result tidlers(color_ostream &out, vector & parameters); - -DFhackCExport command_result plugin_init (color_ostream &out, std::vector &commands) -{ - if (d_init) { - commands.push_back(PluginCommand("twaterlvl", "Toggle display of water/magma depth.", - twaterlvl, Gui::dwarfmode_hotkey)); - commands.push_back(PluginCommand("tidlers", "Toggle display of idlers.", - tidlers, Gui::dwarfmode_hotkey)); - } - return CR_OK; -} - -DFhackCExport command_result plugin_shutdown ( color_ostream &out ) -{ - return CR_OK; -} - -command_result twaterlvl(color_ostream &out, vector & parameters) -{ - // HOTKEY COMMAND: CORE ALREADY SUSPENDED - d_init->flags1.toggle(d_init_flags1::SHOW_FLOW_AMOUNTS); - out << "Toggled the display of water/magma depth." << endl; - return CR_OK; -} - -command_result tidlers(color_ostream &out, vector & parameters) -{ - // HOTKEY COMMAND: CORE ALREADY SUSPENDED - d_init->idlers = ENUM_NEXT_ITEM(d_init_idlers, d_init->idlers); - out << "Toggled the display of idlers to " << ENUM_KEY_STR(d_init_idlers, d_init->idlers) << endl; - return CR_OK; -} diff --git a/scripts/tidlers.lua b/scripts/tidlers.lua new file mode 100644 index 0000000000..5d450f6312 --- /dev/null +++ b/scripts/tidlers.lua @@ -0,0 +1,17 @@ +--Toggle idlers count +--[[=begin + +tidlers +======= +Toggle between all possible positions where the idlers count can be placed. + +=end]] +-- see also the enum: df.d_init_idlers +if df.global.d_init.idlers == 0 then + df.global.d_init.idlers = 1 +elseif df.global.d_init.idlers == 1 then + df.global.d_init.idlers = -1 +else + df.global.d_init.idlers = 0 +end +print('Toggled the display of idlers.') diff --git a/scripts/twaterlvl.lua b/scripts/twaterlvl.lua new file mode 100644 index 0000000000..50f4876863 --- /dev/null +++ b/scripts/twaterlvl.lua @@ -0,0 +1,11 @@ +-- Toggle display of water depth +--[[=begin + +twaterlvl +========= +Toggle between displaying/not displaying liquid depth as numbers. + +=end]] + +df.global.d_init.flags1.SHOW_FLOW_AMOUNTS = not df.global.d_init.flags1.SHOW_FLOW_AMOUNTS +print('Water level display toggled.') From 3fb262892164b670e845db05b3110b90080c7fed Mon Sep 17 00:00:00 2001 From: lethosor Date: Sat, 7 Nov 2015 15:22:30 -0500 Subject: [PATCH 78/91] Add a Lua implementation of next_enum_item() --- library/LuaWrapper.cpp | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/library/LuaWrapper.cpp b/library/LuaWrapper.cpp index 1ce405c297..214caa4cd0 100644 --- a/library/LuaWrapper.cpp +++ b/library/LuaWrapper.cpp @@ -1310,6 +1310,18 @@ static int wtype_ipairs(lua_State *state) return 3; } +static int wtype_next_item(lua_State *state) +{ + int first = lua_tointeger(state, lua_upvalueindex(1)), + last = lua_tointeger(state, lua_upvalueindex(2)), + cur = luaL_checkint(state, lua_gettop(state) > 1 ? 2 : 1); // 'self' optional + if (cur < last) + lua_pushinteger(state, cur + 1); + else + lua_pushinteger(state, first); + return 1; +} + static void RenderTypeChildren(lua_State *state, const std::vector &children); void LuaWrapper::AssociateId(lua_State *state, int table, int val, const char *name) @@ -1347,6 +1359,11 @@ static void FillEnumKeys(lua_State *state, int ix_meta, int ftable, enum_identit lua_pushcclosure(state, wtype_ipairs, 3); lua_setfield(state, ix_meta, "__ipairs"); + lua_pushinteger(state, eid->getFirstItem()); + lua_pushinteger(state, eid->getLastItem()); + lua_pushcclosure(state, wtype_next_item, 2); + lua_setfield(state, ftable, "next_item"); + lua_pushinteger(state, eid->getFirstItem()); lua_setfield(state, ftable, "_first_item"); From 3ae0b1703181e5e2189c03021351f917821a75d6 Mon Sep 17 00:00:00 2001 From: lethosor Date: Sat, 7 Nov 2015 15:24:57 -0500 Subject: [PATCH 79/91] tidlers: Use next_item() --- scripts/tidlers.lua | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/scripts/tidlers.lua b/scripts/tidlers.lua index 5d450f6312..7df5091390 100644 --- a/scripts/tidlers.lua +++ b/scripts/tidlers.lua @@ -6,12 +6,5 @@ tidlers Toggle between all possible positions where the idlers count can be placed. =end]] --- see also the enum: df.d_init_idlers -if df.global.d_init.idlers == 0 then - df.global.d_init.idlers = 1 -elseif df.global.d_init.idlers == 1 then - df.global.d_init.idlers = -1 -else - df.global.d_init.idlers = 0 -end +df.global.d_init.idlers = df.d_init_idlers:next_item(df.global.d_init.idlers) print('Toggled the display of idlers.') From 1da42c911503fa5e05653d5ad9949af7c0b0a400 Mon Sep 17 00:00:00 2001 From: lethosor Date: Sat, 7 Nov 2015 15:55:21 -0500 Subject: [PATCH 80/91] Add automaterial label --- docs/Plugins.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/Plugins.rst b/docs/Plugins.rst index 24ef19d0c3..0cd16a0754 100644 --- a/docs/Plugins.rst +++ b/docs/Plugins.rst @@ -516,6 +516,8 @@ A collection of embark-related tools. Usage and available tools:: area, similar to the default clay/stone indicators. :sticky: Maintains the selected local area while navigating the world map +.. _automaterial: + automaterial ============ This makes building constructions (walls, floors, fortifications, etc) a little bit From 047168b70291c97636c226ed981e92fe734f15fb Mon Sep 17 00:00:00 2001 From: lethosor Date: Sat, 7 Nov 2015 16:15:37 -0500 Subject: [PATCH 81/91] Fix workshop/furnace sidebar events --- plugins/eventful.cpp | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/plugins/eventful.cpp b/plugins/eventful.cpp index 9c8819a488..1b9d228bcc 100644 --- a/plugins/eventful.cpp +++ b/plugins/eventful.cpp @@ -8,6 +8,7 @@ #include "VTableInterpose.h" #include "df/building.h" +#include "df/building_furnacest.h" #include "df/building_workshopst.h" #include "df/construction.h" #include "df/item.h" @@ -91,8 +92,8 @@ static bool is_lua_hook(const std::string &name) /* * Hooks */ -static void handle_fillsidebar(color_ostream &out,df::building_workshopst*,bool *call_native){}; -static void handle_postfillsidebar(color_ostream &out,df::building_workshopst*){}; +static void handle_fillsidebar(color_ostream &out,df::building_actual*,bool *call_native){}; +static void handle_postfillsidebar(color_ostream &out,df::building_actual*){}; static void handle_reaction_done(color_ostream &out,df::reaction*, df::reaction_product_itemst*, df::unit *unit, std::vector *in_items,std::vector *in_reag , std::vector *out_items,bool *call_native){}; @@ -102,8 +103,8 @@ static void handle_projitem_cm(color_ostream &out,df::proj_itemst*){}; static void handle_projunit_ci(color_ostream &out,df::proj_unitst*,bool){}; static void handle_projunit_cm(color_ostream &out,df::proj_unitst*){}; -DEFINE_LUA_EVENT_2(onWorkshopFillSidebarMenu, handle_fillsidebar, df::building_workshopst*,bool* ); -DEFINE_LUA_EVENT_1(postWorkshopFillSidebarMenu, handle_postfillsidebar, df::building_workshopst*); +DEFINE_LUA_EVENT_2(onWorkshopFillSidebarMenu, handle_fillsidebar, df::building_actual*,bool* ); +DEFINE_LUA_EVENT_1(postWorkshopFillSidebarMenu, handle_postfillsidebar, df::building_actual*); DEFINE_LUA_EVENT_7(onReactionComplete, handle_reaction_done,df::reaction*, df::reaction_product_itemst*, df::unit *, std::vector *,std::vector *,std::vector *,bool *); DEFINE_LUA_EVENT_5(onItemContaminateWound, handle_contaminate_wound, df::item_actual*,df::unit* , df::unit_wound* , uint8_t , int16_t ); From 6e8936faa7d0039406546dd0bce078d696110dd3 Mon Sep 17 00:00:00 2001 From: lethosor Date: Sat, 7 Nov 2015 16:48:00 -0500 Subject: [PATCH 82/91] Link to VS2010 Thanks to @TheBloke http://stackoverflow.com/questions/3061811 --- docs/Compile.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/Compile.rst b/docs/Compile.rst index e140c6b280..6fb1183bc4 100644 --- a/docs/Compile.rst +++ b/docs/Compile.rst @@ -200,7 +200,8 @@ It has the usual installer wizard. Make sure you let it add its binary folder to your binary search PATH so the tool can be later run from anywhere. You'll need a copy of Microsoft Visual C++ 2010. The Express version is sufficient. -Grab it from Microsoft's site. You'll also need the Visual Studio 2010 SP1 update. +Grab it from `Microsoft's site `_. +You'll also need the Visual Studio 2010 SP1 update. For the code generation parts, you'll need perl with XML::LibXML and XML::LibXSLT. `Strawberry Perl `_ works nicely for this. From 52989ab40ac854ab093b31b7dd8e5e2ce8fbd54f Mon Sep 17 00:00:00 2001 From: lethosor Date: Sat, 7 Nov 2015 17:18:50 -0500 Subject: [PATCH 83/91] Update Compile.rst --- docs/Compile.rst | 31 +++++++++++++++++++------------ 1 file changed, 19 insertions(+), 12 deletions(-) diff --git a/docs/Compile.rst b/docs/Compile.rst index 6fb1183bc4..f4655d8bf4 100644 --- a/docs/Compile.rst +++ b/docs/Compile.rst @@ -53,9 +53,13 @@ DFHack is meant to be installed into an existing DF folder, so get one ready. We assume that any Linux platform will have ``git`` available. -To build DFHack you need a 32-bit version of GCC. On 64-bit distributions -(which is most of them), this means you'll need the multilib development tools -and libraries. Alternatively, you might be able to use ``lxc`` to +To build DFHack you need a 32-bit version of GCC. GCC 4.5 is easiest to work +with due to avoiding libstdc++ issues (see below), but any later 4.x version +should work as well. GCC 5.x may work but is discouraged for releases because it +won't work on systems without GCC 5.x installed. On 64-bit distributions, you'll +need the multilib development tools and libraries (``gcc-multilib`` or +``gcc-4.x-multilib`` on Debian). Alternatively, you might be able to use ``lxc`` +to :forums:`create a virtual 32-bit environment <139553.msg5435310#msg5435310>`. Before you can build anything, you'll also need ``cmake``. It is advisable to also get @@ -97,7 +101,7 @@ or the cmake-gui program. Incompatible libstdc++ ~~~~~~~~~~~~~~~~~~~~~~ -When compiling dfhack yourself, it builds against your system libc. +When compiling dfhack yourself, it builds against your system libstdc++. When Dwarf Fortress runs, it uses a libstdc++ shipped with the binary, which comes from GCC 4.5 and is incompatible with code compiled with newer GCC versions. This manifests itself with the error message:: @@ -105,12 +109,16 @@ This manifests itself with the error message:: ./libs/Dwarf_Fortress: /pathToDF/libs/libstdc++.so.6: version `GLIBCXX_3.4.15' not found (required by ./hack/libdfhack.so) -To fix this, you can compile DFHack with GCC 4.5 - or simply remove the -libstdc++ shipped with DF, and it will fall back to your system lib:: +To fix this, you can compile with GCC 4.5 or remove the libstdc++ shipped with +DF, which causes DF to use your system libstdc++ instead:: cd /path/to/DF/ rm libs/libstdc++.so.6 +Note that distributing binaries compiled with newer GCC versions requires end- +users to delete libstdc++ themselves and have a libstdc++ on their system from +the same GCC version or newer. For this reason, distributing anything compiled +with GCC versions newer than 4.8 is discouraged. Mac OS X ======== @@ -118,7 +126,7 @@ DFHack functions similarly on OS X and Linux, and the majority of the information above regarding the build process (cmake and make) applies here as well. -If you have issues building on OS X Yosemite (or above), try definining the +If you have issues building on OS X 10.10 (Yosemite) or above, try definining the following environment variable:: export MACOSX_DEPLOYMENT_TARGET=10.9 @@ -149,7 +157,7 @@ following environment variable:: If this is the first time you've run cpan, you will need to go through the setup process. Just stick with the defaults for everything and you'll be fine. - If you are running Snow Leopard (ie 10.6 or earlier), good luck! + If you are running OS X 10.6 (Snow Leopard) or earlier, good luck! You'll need to open a separate Terminal window and run:: sudo ln -s /usr/include/libxml2/libxml /usr/include/libxml @@ -204,12 +212,12 @@ Grab it from `Microsoft's site `_ works nicely for this. +`Strawberry Perl `_ works nicely for this and includes +all of the required packages. If you already have a different version of perl (for example the one from cygwin), you can run into some trouble. Either remove the other perl install from PATH, or -install libxml and libxslt for it instead. Strawberry perl works though and has -all the required packages. +install libxml and libxslt for it instead. Build ----- @@ -235,7 +243,6 @@ Then you can either open the solution with MSVC or use one of the msbuild script When you open the solution in MSVC, make sure you never use the Debug builds. Those aren't binary-compatible with DF. If you try to use a debug build with DF, you'll only get crashes. - For this reason the Windows "debug" scripts actually do RelWithDebInfo builds, so pick either Release or RelWithDebInfo build and build the INSTALL target. From d276d4d46be8083c77aaf6ecf6c9664cb723dc8d Mon Sep 17 00:00:00 2001 From: lethosor Date: Sat, 7 Nov 2015 17:36:42 -0500 Subject: [PATCH 84/91] Add devel/clear-script-env --- scripts/devel/clear-script-env.lua | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 scripts/devel/clear-script-env.lua diff --git a/scripts/devel/clear-script-env.lua b/scripts/devel/clear-script-env.lua new file mode 100644 index 0000000000..90c8db0ed2 --- /dev/null +++ b/scripts/devel/clear-script-env.lua @@ -0,0 +1,26 @@ +-- Clear script environment +--[[=begin + +devel/clear-script-env +====================== +Clears the environment of the specified lua script(s). + +=end]] +args = {...} +if #args < 1 then qerror("script name(s) required") end +for _, name in pairs(args) do + local file = dfhack.findScript(name) + if file then + local script = dfhack.internal.scripts[file] + if script then + local env = script.env + while next(env) do + env[next(env)] = nil + end + else + dfhack.printerr("Script not loaded: " .. name) + end + else + dfhack.printerr("Can't find script: " .. name) + end +end From 91d5b74c3b4486c4668e026a7ecc7a00e9bced58 Mon Sep 17 00:00:00 2001 From: lethosor Date: Sat, 7 Nov 2015 18:07:12 -0500 Subject: [PATCH 85/91] sphinx: Depend on CMakeLists.txt --- CMakeLists.txt | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 9c3b428021..9f56c6817a 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -214,7 +214,11 @@ if (BUILD_DOCS) "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*.lua" "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*.rb" ) - set(SPHINX_DEPS ${SPHINX_DEPS} ${SPHINX_SCRIPT_DEPS} LICENSE.rst NEWS.rst) + set(SPHINX_DEPS ${SPHINX_DEPS} ${SPHINX_SCRIPT_DEPS} + "${CMAKE_CURRENT_SOURCE_DIR}/LICENSE.rst" + "${CMAKE_CURRENT_SOURCE_DIR}/NEWS.rst" + "${CMAKE_CURRENT_SOURCE_DIR}/CMakeLists.txt" + ) set(SPHINX_OUTPUT "${CMAKE_CURRENT_SOURCE_DIR}/docs/html/.buildinfo") set_source_files_properties(${SPHINX_OUTPUT} PROPERTIES GENERATED TRUE) From 178811af43c4d6edbf5b85b2ec9b5621826d5c2b Mon Sep 17 00:00:00 2001 From: lethosor Date: Sat, 7 Nov 2015 18:07:48 -0500 Subject: [PATCH 86/91] Add GCC version to package filename on Linux --- CMakeLists.txt | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 9f56c6817a..e0c70c1dbb 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -248,11 +248,14 @@ if (BUILD_DOCS) endif() # Packaging with CPack! +SET(DFHACK_PACKAGE_SUFFIX "") IF(UNIX) if(APPLE) SET(CPACK_GENERATOR "ZIP;TBZ2") else() SET(CPACK_GENERATOR "TBZ2") + execute_process(COMMAND ${CMAKE_CXX_COMPILER} -dumpversion OUTPUT_VARIABLE GCC_VERSION) + SET(DFHACK_PACKAGE_SUFFIX "-gcc-${GCC_VERSION}") endif() ELSEIF(WIN32) SET(CPACK_GENERATOR "ZIP") @@ -263,7 +266,7 @@ IF(APPLE) ELSE() set(DFHACK_PACKAGE_PLATFORM_NAME ${CMAKE_SYSTEM_NAME}) ENDIF() -set(CPACK_PACKAGE_FILE_NAME "dfhack-${DFHACK_VERSION}-${DFHACK_PACKAGE_PLATFORM_NAME}") +set(CPACK_PACKAGE_FILE_NAME "dfhack-${DFHACK_VERSION}-${DFHACK_PACKAGE_PLATFORM_NAME}${DFHACK_PACKAGE_SUFFIX}") INCLUDE(CPack) #INCLUDE(FindSphinx.cmake) From f7a768f3494ffc231bff2d922933b36d3cdbab48 Mon Sep 17 00:00:00 2001 From: lethosor Date: Sat, 7 Nov 2015 18:46:26 -0500 Subject: [PATCH 87/91] Update conf.py --- conf.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/conf.py b/conf.py index 585052cb66..81b9b8f6d8 100644 --- a/conf.py +++ b/conf.py @@ -90,7 +90,7 @@ def document_scripts(): # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' +needs_sphinx = '1.3' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom @@ -115,7 +115,7 @@ def document_scripts(): # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: -source_suffix = '.rst' +source_suffix = ['.rst'] # The encoding of source files. #source_encoding = 'utf-8-sig' @@ -164,7 +164,7 @@ def get_version(): # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ['docs/_build/*', 'depends/*', 'scripts/3rdparty/*', 'build*'] +exclude_patterns = ['README.md', 'docs/_build/*', 'depends/*', 'scripts/3rdparty/*', 'build*'] # The reST default role (used for this markup: `text`) to use for all # documents. From 99b93ecd11db16751edd049c45f681b4127d758d Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Sun, 8 Nov 2015 11:37:09 +1100 Subject: [PATCH 88/91] Move index back to root --- README.html | 6 +++--- conf.py | 10 ++++++++-- docs/index.rst => index.rst | 0 3 files changed, 11 insertions(+), 5 deletions(-) rename docs/index.rst => index.rst (100%) diff --git a/README.html b/README.html index 660ea2b5b6..325cd66f60 100644 --- a/README.html +++ b/README.html @@ -4,13 +4,13 @@ - + Page Redirection - Follow this link to the documentation. + Follow this link to the documentation. \ No newline at end of file diff --git a/conf.py b/conf.py index 81b9b8f6d8..cb06d32dd7 100644 --- a/conf.py +++ b/conf.py @@ -121,7 +121,7 @@ def document_scripts(): #source_encoding = 'utf-8-sig' # The master toctree document. -master_doc = 'docs/index' +master_doc = 'index' # General information about the project. project = 'DFHack' @@ -164,7 +164,13 @@ def get_version(): # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ['README.md', 'docs/_build/*', 'depends/*', 'scripts/3rdparty/*', 'build*'] +exclude_patterns = [ + 'README.md', + 'docs/html*', + 'depends/*', + 'scripts/3rdparty/*', + 'build*', + ] # The reST default role (used for this markup: `text`) to use for all # documents. diff --git a/docs/index.rst b/index.rst similarity index 100% rename from docs/index.rst rename to index.rst From 1e42f97e76575a98cf6b3567c54fa76ff3da2516 Mon Sep 17 00:00:00 2001 From: lethosor Date: Sat, 7 Nov 2015 20:27:48 -0500 Subject: [PATCH 89/91] Add GCC version to OS X package names and remove trailing newlines --- CMakeLists.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index e0c70c1dbb..159db42f98 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -250,12 +250,13 @@ endif() # Packaging with CPack! SET(DFHACK_PACKAGE_SUFFIX "") IF(UNIX) + execute_process(COMMAND ${CMAKE_CXX_COMPILER} -dumpversion OUTPUT_VARIABLE GCC_VERSION) + string(STRIP ${GCC_VERSION} GCC_VERSION) + SET(DFHACK_PACKAGE_SUFFIX "-gcc-${GCC_VERSION}") if(APPLE) SET(CPACK_GENERATOR "ZIP;TBZ2") else() SET(CPACK_GENERATOR "TBZ2") - execute_process(COMMAND ${CMAKE_CXX_COMPILER} -dumpversion OUTPUT_VARIABLE GCC_VERSION) - SET(DFHACK_PACKAGE_SUFFIX "-gcc-${GCC_VERSION}") endif() ELSEIF(WIN32) SET(CPACK_GENERATOR "ZIP") From 36b280338108fdb44843368e3ac8fbb8d2e5215d Mon Sep 17 00:00:00 2001 From: lethosor Date: Sat, 7 Nov 2015 20:28:16 -0500 Subject: [PATCH 90/91] Add note about updating NEWS.rst --- NEWS.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/NEWS.rst b/NEWS.rst index 177108106c..0de43cc009 100644 --- a/NEWS.rst +++ b/NEWS.rst @@ -18,6 +18,9 @@ create a link to the relevant documentation - and check that the docs are still up to date! + When adding a new release, change "DFHack future" to the appropriate title + before releasing, and then add a new "DFHack future" section after releasing. + ######### Changelog From 7b483a4461854390097dfedd03673147957e3fef Mon Sep 17 00:00:00 2001 From: lethosor Date: Sat, 7 Nov 2015 20:28:37 -0500 Subject: [PATCH 91/91] Update version to r4 Ref #737 --- CMakeLists.txt | 2 +- NEWS.rst | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 159db42f98..b6228a9e1f 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -93,7 +93,7 @@ endif() # set up versioning. set(DF_VERSION "0.40.24") -SET(DFHACK_RELEASE "r3") +SET(DFHACK_RELEASE "r4") set(DFHACK_VERSION "${DF_VERSION}-${DFHACK_RELEASE}") diff --git a/NEWS.rst b/NEWS.rst index 0de43cc009..fb16ab3f8b 100644 --- a/NEWS.rst +++ b/NEWS.rst @@ -30,8 +30,8 @@ Changelog :depth: 2 -DFHack Future -============= +DFHack 0.40.24-r4 +================= Internals ---------