Merge remote-tracking branch 'PeridexisErrant/dev-docs' into develop

develop
lethosor 2016-04-10 23:18:19 -04:00
commit f18ebf120b
12 changed files with 918 additions and 783 deletions

@ -30,6 +30,7 @@ before_install:
script: script:
- git tag tmp-travis-build - git tag tmp-travis-build
- sh travis/git-info.sh - sh travis/git-info.sh
- sphinx-build -qW . docs/html
- python travis/pr-check-base.py - python travis/pr-check-base.py
- python travis/lint.py - python travis/lint.py
- python travis/authors-rst.py - python travis/authors-rst.py

@ -21,6 +21,7 @@
When adding a new release, change "DFHack future" to the appropriate title When adding a new release, change "DFHack future" to the appropriate title
before releasing, and then add a new "DFHack future" section after releasing. before releasing, and then add a new "DFHack future" section after releasing.
.. _changelog:
######### #########
Changelog Changelog
@ -161,28 +162,29 @@ Internals
- More DFHack build information used in plugin version checks and available to plugins and lua scripts - 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 - 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 - 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 - Fixed issues with keybindings involving :kbd:`Ctrl`:kbd:`A` and :kbd:`Ctrl`:kbd:`Z`,
as well as :kbd:`Alt`:kbd:`E`/:kbd:`U`/:kbd:`N` on OS X
- Multiple contexts can now be specified when adding keybindings - Multiple contexts can now be specified when adding keybindings
- Keybindings can now use F10-F12 and 0-9 - Keybindings can now use :kbd:`F10`-:kbd:`F12` and :kbd:`0`-:kbd:`9`
- Plugin system is no longer restricted to plugins that exist on startup - Plugin system is no longer restricted to plugins that exist on startup
- :file:`dfhack.init` file locations significantly generalized - :file:`dfhack.init` file locations significantly generalized
Lua Lua
--- ---
- Scripts can be enabled with the built-in enable/disable commands - Scripts can be enabled with the built-in `enable`/`disable <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 - Lua viewscreens can choose not to intercept the OPTIONS keybinding
New internal commands New internal commands
--------------------- ---------------------
- kill-lua: Interrupt running Lua scripts - `kill-lua`: Interrupt running Lua scripts
- type: Show where a command is implemented - `type`: Show where a command is implemented
New plugins New plugins
----------- -----------
- `confirm`: Adds confirmation dialogs for several potentially dangerous actions - `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`) - `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 - `title-version` (formerly ``vshook``): Display DFHack version on title screen
New scripts New scripts
----------- -----------
@ -224,7 +226,7 @@ Fixes
- `buildingplan`: Now supports hatch covers - `buildingplan`: Now supports hatch covers
- `gui/create-item`: fixed assigning quality to items, made :kbd:`Esc` work properly - `gui/create-item`: fixed assigning quality to items, made :kbd:`Esc` work properly
- `gui/gm-editor`: handles lua tables properly - `gui/gm-editor`: handles lua tables properly
- help: now recognizes built-in commands, like "help" - `help`: now recognizes built-in commands, like ``help``
- `manipulator`: fixed crash when selecting custom professions when none are found - `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 - `remotefortressreader`: fixed crash when attempting to send map info when no map was loaded
- `search-plugin`: 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
@ -256,7 +258,7 @@ Misc Improvements
- `automaterial`: Fixed several issues with constructions being allowed/disallowed incorrectly when using box-select - `automaterial`: Fixed several issues with constructions being allowed/disallowed incorrectly when using box-select
- `dwarfmonitor`: - `dwarfmonitor`:
- widgets' positions, formats, etc. are now customizable (see Readme) - widgets' positions, formats, etc. are now customizable
- weather display now separated from the date display - weather display now separated from the date display
- New mouse cursor widget - New mouse cursor widget
@ -269,16 +271,16 @@ Misc Improvements
- Now avoids errors with unrecognized types - Now avoids errors with unrecognized types
- `gui/hack-wish`: renamed to `gui/create-item` - `gui/hack-wish`: renamed to `gui/create-item`
- "keybinding list" accepts a context - `keybinding list <keybinding>` accepts a context
- `lever`: - `lever`:
- Lists lever names - Lists lever names
- "lever pull" can be used to pull the currently-selected lever - ``lever pull`` can be used to pull the currently-selected lever
- memview: Fixed display issue - ``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`) - `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 - ``nyan``: Can now be stopped with dfhack-run
- plug: lists all plugins; shows state and number of commands in plugins - `plug`: lists all plugins; shows state and number of commands in plugins
- `prospect`: works from within command-prompt - `prospect`: works from within command-prompt
- `quicksave`: Restricted to fortress mode - `quicksave`: Restricted to fortress mode
- `remotefortressreader`: Exposes more information - `remotefortressreader`: Exposes more information
@ -309,7 +311,7 @@ Internals
--------- ---------
- Ruby library now included on OS X - Ruby scripts should work on OS X 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 - libstdc++ should work with older versions of OS X
- Added support for ``onLoadMap.init``/``onUnloadMap.init`` scripts - Added support for `onMapLoad.init / onMapUnload.init <other_init_files>` scripts
- game type detection functions are now available in the World module - 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 adventure mode menu names
@ -324,7 +326,7 @@ Lua
New Internal Commands New Internal Commands
--------------------- ---------------------
- `hide`, `show`: hide and show the console on Windows - `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) - `sc-script`: Allows additional scripts to be run when certain events occur (similar to `onLoad.init` scripts)
New Plugins New Plugins
----------- -----------
@ -343,7 +345,7 @@ New Tweaks
Fixes Fixes
----- -----
- Fixed game type detection in `3dveins`, `gui/create-item`, `reveal`, `seedwatch` - Fixed game type detection in `3dveins`, `gui/create-item`, `reveal`, `seedwatch`
- PRELOAD_LIB: More extensible on Linux - ``PRELOAD_LIB``: More extensible on Linux
- `add-spatter`, `eventful`: Fixed crash on world load - `add-spatter`, `eventful`: Fixed crash on world load
- `add-thought`: Now has a proper subthought arg. - `add-thought`: Now has a proper subthought arg.
- `building-hacks`: Made buildings produce/consume correct amount of power - `building-hacks`: Made buildings produce/consume correct amount of power
@ -357,7 +359,7 @@ Fixes
- Fixed error message in Arena mode - Fixed error message in Arena mode
- no longer checks the DF version - no longer checks the DF version
- fixed ballistic arrow head orders - fixed ballistic arrow head orders
- convinces the bookkeeper to update records more often' - convinces the bookkeeper to update records more often
- `zone`: Stopped crash when scrolling cage owner list - `zone`: Stopped crash when scrolling cage owner list
@ -385,8 +387,8 @@ DFHack 0.40.24-r2
Internals Internals
--------- ---------
- Lua scripts can set environment variables of each other with dfhack.run_script_with_env. - 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). - 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 - `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) - Filesystem module now provides file access/modification times and can list directories (normally and recursively)
- Units Module: New functions:: - Units Module: New functions::
@ -429,7 +431,7 @@ Fixes
- `add-thought`: updated to properly affect stress. - `add-thought`: updated to properly affect stress.
- `hfs-pit`: should work now - `hfs-pit`: should work now
- `autobutcher`: takes gelding into account - `autobutcher`: takes gelding into account
- init.lua existence checks should be more reliable (notably when using non-English locales) - :file:`init.lua` existence checks should be more reliable (notably when using non-English locales)
Misc Improvements Misc Improvements
----------------- -----------------
@ -466,7 +468,6 @@ New Scripts
Removed Removed
------- -------
- embark.lua
- needs_porting/* - needs_porting/*
Misc Improvements Misc Improvements
@ -474,615 +475,8 @@ Misc Improvements
Added support for searching more lists Added support for searching more lists
DFHack 0.40.23-r1 Older Changelogs
================= ================
Are kept in a seperate file: `HISTORY`
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 <tweak>`: Displays an egg fertility indicator on nestboxes
- `max-wheelbarrow <tweak>`: 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
-----
- `modtools/reaction-trigger`: fixed typo
- `modtools/item-trigger`: should now work with item types
New plugins
-----------
- `savestock, loadstock <stocksettings>`: 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
=================
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
=================
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-plugin`: Adapts to the new trade screen column width
- `tweak fast-trade <tweak>`: 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
- `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`
DFHack 0.40.12-r1
=================
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`: 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-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`
- updated `exportlegends` to work with new maps, dfhack 40.11 r1+
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
- `autotrade`, `search-plugin`: 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
==================
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: 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
DFHack v0.40.08-r1
==================
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 OS X 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
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
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 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 OS X
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.
- 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.
- Autolabor plugin:
- can set nonidle hauler percentage.
- broker excluded from all labors when needed at depot.
- likewise, anybody with a scheduled diplomat meeting.
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.
.. that's ``docs/history.rst``, if you're reading the raw text.

@ -4,13 +4,13 @@
<html lang="en-US"> <html lang="en-US">
<head> <head>
<meta charset="UTF-8"> <meta charset="UTF-8">
<meta http-equiv="refresh" content="0;url=./docs/html/index.html"> <meta http-equiv="refresh" content="0;url=./docs/index.html">
<script type="text/javascript"> <script type="text/javascript">
window.location.href = "./docs/html/index.html" window.location.href = "./docs/index.html"
</script> </script>
<title>Page Redirection</title> <title>Page Redirection</title>
</head> </head>
<body> <body>
Follow this <a href='./docs/html/index.html'>link to the documentation.</a> Follow this <a href='./docs/index.html'>link to the documentation.</a>
</body> </body>
</html> </html>

@ -108,6 +108,7 @@ extlinks = {
'bug': ('http://www.bay12games.com/dwarves/mantisbt/view.php?id=%s', 'bug': ('http://www.bay12games.com/dwarves/mantisbt/view.php?id=%s',
'Bug '), 'Bug '),
'issue': ('https://github.com/DFHack/dfhack/issues/%s', 'Issue '), 'issue': ('https://github.com/DFHack/dfhack/issues/%s', 'Issue '),
'commit': ('https://github.com/DFHack/dfhack/commit/%s', 'Commit '),
} }
# Add any paths that contain templates here, relative to this directory. # Add any paths that contain templates here, relative to this directory.

@ -29,8 +29,7 @@ decent skill in `memory research <contributing-memory-research>`.
* The patches are expected to be encoded in text format used by IDA. * The patches are expected to be encoded in text format used by IDA.
* See `this commit <https://github.com/DFHack/dfhack/commit/8a9e3d1a728>`_, * See :commit:`8a9e3d1a728` for examples.
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.
@ -50,7 +49,7 @@ directly in memory at runtime::
binpatch [check|apply|remove] <patchname> binpatch [check|apply|remove] <patchname>
If the name of the patch has no extension or directory separators, the If the name of the patch has no extension or directory separators, the
script uses ``hack/patches/<df-version>/<name>.dif``, thus auto-selecting script uses :file:`hack/patches/<df-version>/<name>.dif`, thus auto-selecting
the version appropriate for the currently loaded executable. the version appropriate for the currently loaded executable.
This is the preferred method; it's easier to debug, does not cause persistent This is the preferred method; it's easier to debug, does not cause persistent

@ -42,9 +42,11 @@ Contributing to DFHack
If you want to get 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. GitHub, make a clone there and then use that as your remote repository instead.
We'd love that; join us on IRC (#dfhack channel on freenode) for discussion, We'd love that; join us on IRC_ (#dfhack channel on freenode) for discussion,
and whenever you need help. and whenever you need help.
.. _IRC: https://webchat.freenode.net/?channels=dfhack
For lots more details on contributing to DFHack, including pull requests, code format, For lots more details on contributing to DFHack, including pull requests, code format,
and more, please see `contributing-code`. and more, please see `contributing-code`.
@ -101,7 +103,7 @@ Before you can build anything, you'll also need ``cmake``. It is advisable to al
You also need perl and the XML::LibXML and XML::LibXSLT perl packages (for the code generation 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. You should be able to find them in your distro repositories.
To build Stonesense, you'll also need OpenGL headers. To build `stonesense`, you'll also need OpenGL headers.
Here are some package install commands for various platforms: Here are some package install commands for various platforms:
@ -109,15 +111,15 @@ Here are some package install commands for various platforms:
* For the required Perl modules: ``perl-xml-libxml`` and ``perl-xml-libxslt`` (or through ``cpan``) * For the required Perl modules: ``perl-xml-libxml`` and ``perl-xml-libxslt`` (or through ``cpan``)
* On 64-bit Ubuntu: * On 64-bit Ubuntu::
* ``apt-get install gcc cmake git gcc-multilib g++-multilib zlib1g-dev:i386 libxml-libxml-perl libxml-libxslt-perl``. apt-get install gcc cmake git gcc-multilib g++-multilib zlib1g-dev:i386 libxml-libxml-perl libxml-libxslt-perl
* On 32-bit Ubuntu: * On 32-bit Ubuntu::
* ``apt-get install gcc cmake git gcc-multilib g++-multilib zlib1g-dev libxml-libxml-perl libxml-libxslt-perl``. apt-get install gcc cmake git gcc-multilib g++-multilib zlib1g-dev libxml-libxml-perl libxml-libxslt-perl
* Debian-derived distros should have similar requirements. * Debian and derived distros should have similar requirements to Ubuntu.
Build Build
@ -505,9 +507,8 @@ or ``RelWithDebInfo``.
Then build the ``INSTALL`` target listed under ``CMakePredefinedTargets``. Then build the ``INSTALL`` target listed under ``CMakePredefinedTargets``.
##########################
Building the documentation Building the documentation
########################## ==========================
DFHack documentation, like the file you are reading now, is created as .rst files, DFHack documentation, like the file you are reading now, is created as .rst files,
which are in `reStructuredText (reST) <http://sphinx-doc.org/rest.html>`_ format. which are in `reStructuredText (reST) <http://sphinx-doc.org/rest.html>`_ format.
@ -530,7 +531,7 @@ The main thing you lose in plain text format is hyperlinking.)
Enabling documentation building Enabling documentation building
=============================== -------------------------------
First, make sure you have followed all the necessary steps for your platform as First, make sure you have followed all the necessary steps for your platform as
outlined in the rest of this document. outlined in the rest of this document.
@ -550,7 +551,7 @@ through the GUI, or else if you want to use an alternate file, such as
Or you could just run ``cmake`` on the command line like in other platforms. Or you could just run ``cmake`` on the command line like in other platforms.
Required dependencies Required dependencies
===================== ---------------------
In order to build the documentation, you must have Python with Sphinx In order to build the documentation, you must have Python with Sphinx
version 1.3.1 or later. Both Python 2.x and 3.x are supported. version 1.3.1 or later. Both Python 2.x and 3.x are supported.

@ -69,6 +69,7 @@ on how to write one yet, but it should be easy enough to copy one and just follo
Other than through plugins, it is possible to use DFHack via remote access interface, 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. or by writing scripts in Lua or Ruby. There are plenty of examples in the scripts folder.
The `lua-api` is quite well documented.
The most important parts of DFHack are the Core, Console, Modules and Plugins. The most important parts of DFHack are the Core, Console, Modules and Plugins.
@ -85,7 +86,9 @@ The most important parts of DFHack are the Core, Console, Modules and Plugins.
Rudimentary API documentation can be built using doxygen (see build options Rudimentary API documentation can be built using doxygen (see build options
in ``CMakeCache.txt`` or with ``ccmake`` or ``cmake-gui``). The full DFHack in ``CMakeCache.txt`` or with ``ccmake`` or ``cmake-gui``). The full DFHack
documentation is built with Sphinx, which runs automatically at compile time. documentation is built with Sphinx_, which runs automatically at compile time.
.. _Sphinx: http://www.sphinx-doc.org
DFHack consists of variously licensed code, but invariably weak copyleft. DFHack consists of variously licensed code, but invariably weak copyleft.
The main license is zlib/libpng, some bits are MIT licensed, and some are The main license is zlib/libpng, some bits are MIT licensed, and some are
@ -101,14 +104,14 @@ in the ``library/xml/`` submodule.
See https://github.com/DFHack/df-structures, and the documentation linked in the index. See https://github.com/DFHack/df-structures, and the documentation linked in the index.
Data structure layouts are described in files following the ``df.\*.xml`` name pattern. Data structure layouts are described in files following the ``df.*.xml`` name pattern.
This information is transformed by a perl script into C++ headers describing the This information is transformed by a perl script into C++ headers describing the
structures, and associated metadata for the Lua wrapper. These headers and data structures, and associated metadata for the Lua wrapper. These headers and data
are then compiled into the DFHack libraries, thus necessitating a compatibility are then compiled into the DFHack libraries, thus necessitating a compatibility
break every time layouts change; in return it significantly boosts the efficiency break every time layouts change; in return it significantly boosts the efficiency
and capabilities of DFHack code. and capabilities of DFHack code.
Global object addresses are stored in ``symbols.xml``, which is copied to the dfhack Global object addresses are stored in :file:`symbols.xml`, which is copied to the dfhack
release package and loaded as data at runtime. release package and loaded as data at runtime.
Remote access interface Remote access interface
@ -118,13 +121,13 @@ socket. Both the core and plugins can define remotely accessible methods. The
``dfhack-run`` command uses this interface to invoke ordinary console commands. ``dfhack-run`` command uses this interface to invoke ordinary console commands.
Currently the supported set of requests is limited, because the developers don't Currently the supported set of requests is limited, because the developers don't
know what exactly is most useful. ``remotefortressreader`` provides a fairly know what exactly is most useful. `remotefortressreader` provides a fairly
comprehensive interface for visualisers such as Armok Vision. comprehensive interface for visualisers such as :forums:`Armok Vision <146473>`.
Documentation Standards Documentation Standards
======================= =======================
DFHack documentation is built with Sphinx, and configured automatically DFHack documentation is built with Sphinx_, and configured automatically
through CMake. If you want to build the docs *only*, use this command:: through CMake. If you want to build the docs *only*, use this command::
sphinx-build . docs/html sphinx-build . docs/html
@ -134,10 +137,10 @@ 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 this section as a guide rather than iron law, match the surrounding text, and you'll
be fine. be fine.
Everything should be documented! For plugins, it's a work in progress - use Everything should be documented! If it's not clear *where* a particular
``docs/Plugins.rst`` for now. Core functions and general explanations should thing should be documented, ask on IRC or in the DFHack thread on Bay12 -
go in the documents for that component; if it's not clear add a new section as well as getting help, you'll be providing valuable feedback that
as some may be missing. makes it easier for future readers!
Scripts can use a custom autodoc function, based on the Sphinx ``include`` Scripts can use a custom autodoc function, based on the Sphinx ``include``
directive and Ruby docstring conventions - any lines between ``=begin`` and directive and Ruby docstring conventions - any lines between ``=begin`` and

@ -312,6 +312,7 @@ All matching init files will be executed in alphebetical order.
Modders often use such scripts to disable tools which should not affect Modders often use such scripts to disable tools which should not affect
an unmodded save. an unmodded save.
.. _other_init_files:
Other init files Other init files
---------------- ----------------

@ -0,0 +1,605 @@
:orphan:
.. _HISTORY:
########################
HISTORY - old changelogs
########################
This file is where old changelogs live, so the current `changelog`
in ``NEWS.rst`` doesn't get too long.
.. contents::
:depth: 2
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++
- :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 <tweak>`: Displays an egg fertility indicator on nestboxes
- `max-wheelbarrow <tweak>`: 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
-----
- `modtools/reaction-trigger`: fixed typo
- `modtools/item-trigger`: should now work with item types
New plugins
-----------
- `savestock, loadstock <stocksettings>`: 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
=================
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
=================
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-plugin`: Adapts to the new trade screen column width
- `tweak fast-trade <tweak>`: 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
- `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`
DFHack 0.40.12-r1
=================
Internals
---------
- support for global `onLoad.init` and `onUnload.init` files, called when loading and unloading a world
- Close file after loading a `binary patch <binpatches>`.
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-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`
- updated `exportlegends` to work with new maps, dfhack 40.11 r1+
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
- `autotrade`, `search-plugin`: 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
==================
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: 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
- invasionNow: `modtools/force` does it better
- autoSyndrome replaced with `modtools/reaction-trigger`
- syndromeTrigger replaced with `modtools/syndrome-trigger`
- devel/printArgs plugin converted to `devel/print-args`
- outsideOnly plugin replaced by `modtools/outside-only`
DFHack v0.40.08-r1
==================
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 `gui/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 OS X 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 <gui/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 <plant>`: 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; 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`:
- 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
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 <enable>` - Built-in commands that can be used to enable/disable many plugins.
- `restrictice` - Restrict traffic on squares above visible ice.
- `restrictliquids` - 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
- Add df.dfhack_run "somecommand" to Ruby
- 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 <lua_api_random>` 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 OS X 10.6.8
Notable bugfixes
----------------
- `autobutcher` can be re-enabled again after being stopped.
- stopped `Dwarf Manipulator <manipulator>` from unmasking vampires.
- `stonesense` is now fixed on OS X
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 <binpatches>`.
- 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.
- Auto syndrome plugin: A way of automatically applying boiling rock syndromes and calling dfhack commands controlled by raws.
- `infiniteSky` plugin: Create new z-levels automatically or on request.
- True transformation plugin: A better way of doing permanent transformations that allows later transformations.
- `workNow` 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 <rb>`.
- 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`:
- can set nonidle hauler percentage.
- broker excluded from all labors when needed at depot.
- likewise, anybody with a scheduled diplomat meeting.
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.
- `drain-aquifer`: 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
-----------
- `manipulator`: a Dwarf Therapist like UI in the game (:kbd:`u`:kbd:`l`)
- `steam-engine`: an alternative to Water Reactors which make more sense.
See ``hack/raw/*_steam_engine.txt`` for the necessary raw definitions.
- `power-meter`: a pressure plate modification to detect powered gear
boxes on adjacent tiles. `gui/power-meter` implements
the build configuration UI.
- `siege-engine`: massive overhaul for siege engines, configured via `gui/siege-engine`
- `add-spatter`: allows poison coatings via raw reactions, among other things.

@ -1,11 +1,13 @@
.. _lua-api:
############## ##############
DFHack Lua API DFHack Lua API
############## ##############
.. contents:: DFHack has extensive support for
the Lua_ scripting language, providing access to:
The current version of DFHack has extensive support for .. _Lua: http://www.lua.org
the Lua scripting language, providing access to:
1. Raw data structures used by the game. 1. Raw data structures used by the game.
2. Many C++ functions for high-level access to these 2. Many C++ functions for high-level access to these
@ -14,26 +16,36 @@ the Lua scripting language, providing access to:
Lua code can be used both for writing scripts, which Lua code can be used both for writing scripts, which
are treated by DFHack command line prompt almost as are treated by DFHack command line prompt almost as
native C++ commands, and invoked by plugins written in c++. native C++ commands, and invoked by plugins written in C++.
This document describes native API available to Lua in detail. This document describes native API available to Lua in detail.
It does not describe all of the utility functions It does not describe all of the utility functions
implemented by Lua files located in hack/lua/... implemented by Lua files located in :file:`hack/lua/*`
(:file:`library/lua/*` in the git repo).
.. contents::
:depth: 3
========================= =========================
DF data structure wrapper DF data structure wrapper
========================= =========================
Data structures of the game are defined in XML files located in library/xml .. contents::
(and online at http://github.com/DFHack/df-structures), and automatically exported :local:
Data structures of the game are defined in XML files located in :file:`library/xml`
(and `online <http://github.com/DFHack/df-structures>`_, and automatically exported
to lua code as a tree of objects and functions under the ``df`` global, which to lua code as a tree of objects and functions under the ``df`` global, which
also broadly maps to the ``df`` namespace in the headers generated for C++. also broadly maps to the ``df`` namespace in the headers generated for C++.
**WARNING**: The wrapper provides almost raw access to the memory .. warning::
of the game, so mistakes in manipulating objects are as likely to The wrapper provides almost raw access to the memory
crash the game as equivalent plain C++ code would be. E.g. NULL of the game, so mistakes in manipulating objects are as likely to
pointer access is safely detected, but dangling pointers aren't. crash the game as equivalent plain C++ code would be.
eg. NULL pointer access is safely detected, but dangling pointers aren't.
Objects managed by the wrapper can be broadly classified into the following groups: Objects managed by the wrapper can be broadly classified into the following groups:
@ -86,10 +98,11 @@ All typed objects have the following built-in features:
and values. Fields are enumerated in memory order. Methods and and values. Fields are enumerated in memory order. Methods and
lua wrapper properties are not included in the iteration. lua wrapper properties are not included in the iteration.
**WARNING**: a few of the data structures (like ui_look_list) .. warning::
contain unions with pointers to different types with vtables. a few of the data structures (like ui_look_list)
Using pairs on such structs is an almost sure way to crash with contain unions with pointers to different types with vtables.
an access violation. Using pairs on such structs is an almost sure way to crash with
an access violation.
* ``ref._kind`` * ``ref._kind``
@ -115,8 +128,9 @@ All typed objects have the following built-in features:
Destroys the object with the C++ ``delete`` operator. Destroys the object with the C++ ``delete`` operator.
If destructor is not available, returns *false*. If destructor is not available, returns *false*.
**WARNING**: the lua reference object remains as a dangling .. warning::
pointer, like a raw C++ pointer would. the lua reference object remains as a dangling
pointer, like a raw C++ pointer would.
* ``ref:assign(object)`` * ``ref:assign(object)``
@ -158,16 +172,18 @@ They implement the following features:
Primitive typed fields, i.e. numbers & strings, are converted Primitive typed fields, i.e. numbers & strings, are converted
to/from matching lua values. The value of a pointer is a reference to/from matching lua values. The value of a pointer is a reference
to the target, or nil/NULL. Complex types are represented by to the target, or ``nil``/NULL. Complex types are represented by
a reference to the field within the structure; unless recursive a reference to the field within the structure; unless recursive
lua table assignment is used, such fields can only be read. lua table assignment is used, such fields can only be read.
**NOTE:** In case of inheritance, *superclass* fields have precedence .. note::
over the subclass, but fields shadowed in this way can still In case of inheritance, *superclass* fields have precedence
be accessed as ``ref['subclasstype.field']``. over the subclass, but fields shadowed in this way can still
This shadowing order is necessary because vtable-based classes be accessed as ``ref['subclasstype.field']``.
are automatically exposed in their exact type, and the reverse
rule would make access to superclass fields unreliable. This shadowing order is necessary because vtable-based classes
are automatically exposed in their exact type, and the reverse
rule would make access to superclass fields unreliable.
* ``ref._field(field)`` * ``ref._field(field)``
@ -183,7 +199,7 @@ They implement the following features:
* ``pairs(ref)`` * ``pairs(ref)``
Enumerates all real fields (but not methods) in memory Enumerates all real fields (but not methods) in memory
(= declaration) order. order, which is the same as declaration order.
Container references Container references
-------------------- --------------------
@ -278,7 +294,7 @@ All types and the global object have the following features:
* ``type._identity`` * ``type._identity``
Contains a lightuserdata pointing to the underlying Contains a lightuserdata pointing to the underlying
DFHack::type_instance object. ``DFHack::type_instance`` object.
Types excluding the global object also support: Types excluding the global object also support:
@ -294,8 +310,8 @@ Types excluding the global object also support:
Returns true if object is same or subclass type, or a reference Returns true if object is same or subclass type, or a reference
to an object of same or subclass type. It is permissible to pass to an object of same or subclass type. It is permissible to pass
nil, NULL or non-wrapper value as object; in this case the ``nil``, NULL or non-wrapper value as object; in this case the
method returns nil. method returns ``nil``.
In addition to this, enum and bitfield types contain a In addition to this, enum and bitfield types contain a
bi-directional mapping between key strings and values, and bi-directional mapping between key strings and values, and
@ -362,6 +378,7 @@ The ``df`` table itself contains the following functions and values:
Returns *nil* if NULL, or a ref. Returns *nil* if NULL, or a ref.
.. _lua-api-table-assignment:
Recursive table assignment Recursive table assignment
========================== ==========================
@ -437,7 +454,7 @@ on the type of the field being assigned to:
{ resize=false, [idx]=value } { resize=false, [idx]=value }
Since nil inside a table is indistinguishable from missing key, Since ``nil`` inside a table is indistinguishable from missing key,
it is necessary to use ``df.NULL`` as a null pointer value. it is necessary to use ``df.NULL`` as a null pointer value.
This system is intended as a way to define a nested object This system is intended as a way to define a nested object
@ -452,6 +469,9 @@ cleanup.
DFHack API DFHack API
========== ==========
.. contents::
:local:
DFHack utility functions are placed in the ``dfhack`` global tree. DFHack utility functions are placed in the ``dfhack`` global tree.
Native utilities Native utilities
@ -722,6 +742,8 @@ Functions:
Checks if the material matches job_material_category or job_item. Checks if the material matches job_material_category or job_item.
Accept dfhack_material_category auto-assign table. Accept dfhack_material_category auto-assign table.
.. _lua_api_random:
Random number generation Random number generation
------------------------ ------------------------
@ -798,11 +820,12 @@ can be omitted.
Return information about the DFHack build in use. Return information about the DFHack build in use.
**Note:** ``getCompiledDFVersion()`` returns the DF version specified at compile time, .. note::
while ``getDFVersion()`` returns the version and typically the OS as well. ``getCompiledDFVersion()`` returns the DF version specified at compile time,
These do not necessarily match - for example, DFHack 0.34.11-r5 worked with while ``getDFVersion()`` returns the version and typically the OS as well.
DF 0.34.10 and 0.34.11, so the former function would always return ``0.34.11`` These do not necessarily match - for example, DFHack 0.34.11-r5 worked with
while the latter would return ``v0.34.10 <platform>`` or ``v0.34.11 <platform>``. DF 0.34.10 and 0.34.11, so the former function would always return ``0.34.11``
while the latter would return ``v0.34.10 <platform>`` or ``v0.34.11 <platform>``.
* ``dfhack.getDFPath()`` * ``dfhack.getDFPath()``
@ -875,7 +898,7 @@ Gui module
* ``dfhack.gui.getSelectedWorkshopJob([silent])`` * ``dfhack.gui.getSelectedWorkshopJob([silent])``
When a job is selected in *'q'* mode, returns the job, else When a job is selected in :kbd:`q` mode, returns the job, else
prints error unless silent and returns *nil*. prints error unless silent and returns *nil*.
* ``dfhack.gui.getSelectedJob([silent])`` * ``dfhack.gui.getSelectedJob([silent])``
@ -884,31 +907,31 @@ Gui module
* ``dfhack.gui.getSelectedUnit([silent])`` * ``dfhack.gui.getSelectedUnit([silent])``
Returns the unit selected via *'v'*, *'k'*, unit/jobs, or Returns the unit selected via :kbd:`v`, :kbd:`k`, unit/jobs, or
a full-screen item view of a cage or suchlike. a full-screen item view of a cage or suchlike.
* ``dfhack.gui.getSelectedItem([silent])`` * ``dfhack.gui.getSelectedItem([silent])``
Returns the item selected via *'v'* ->inventory, *'k'*, *'t'*, or Returns the item selected via :kbd:`v` ->inventory, :kbd:`k`, :kbd:`t`, or
a full-screen item view of a container. Note that in the a full-screen item view of a container. Note that in the
last case, the highlighted *contained item* is returned, not last case, the highlighted *contained item* is returned, not
the container itself. the container itself.
* ``dfhack.gui.getSelectedBuilding([silent])`` * ``dfhack.gui.getSelectedBuilding([silent])``
Returns the building selected via *'q'*, *'t'*, *'k'* or *'i'*. Returns the building selected via :kbd:`q`, :kbd:`t`, :kbd:`k` or :kbd:`i`.
* ``dfhack.gui.writeToGamelog(text)`` * ``dfhack.gui.writeToGamelog(text)``
Writes a string to gamelog.txt without doing an announcement. Writes a string to :file:`gamelog.txt` without doing an announcement.
* ``dfhack.gui.makeAnnouncement(type,flags,pos,text,color[,is_bright])`` * ``dfhack.gui.makeAnnouncement(type,flags,pos,text,color[,is_bright])``
Adds an announcement with given announcement_type, text, color, and brightness. Adds an announcement with given announcement_type, text, color, and brightness.
The is_bright boolean actually seems to invert the brightness. The is_bright boolean actually seems to invert the brightness.
The announcement is written to gamelog.txt. The announcement_flags The announcement is written to :file:`gamelog.txt`. The announcement_flags
argument provides a custom set of announcements.txt options, argument provides a custom set of :file:`announcements.txt` options,
which specify if the message should actually be displayed in the which specify if the message should actually be displayed in the
announcement list, and whether to recenter or show a popup. announcement list, and whether to recenter or show a popup.
@ -1003,7 +1026,7 @@ Job module
* ``dfhack.job.linkIntoWorld(job,new_id)`` * ``dfhack.job.linkIntoWorld(job,new_id)``
Adds job into ``df.global.job_list``, and if new_id Adds job into ``df.global.job_list``, and if new_id
is true, then also sets it's id and increases is true, then also sets its id and increases
``df.global.job_next_id`` ``df.global.job_next_id``
* ``dfhack.job.listNewlyCreated(first_id)`` * ``dfhack.job.listNewlyCreated(first_id)``
@ -1161,7 +1184,7 @@ Items module
* ``dfhack.items.getDescription(item, type[, decorate])`` * ``dfhack.items.getDescription(item, type[, decorate])``
Returns the string description of the item, as produced by the getItemDescription Returns the string description of the item, as produced by the ``getItemDescription``
method. If decorate is true, also adds markings for quality and improvements. method. If decorate is true, also adds markings for quality and improvements.
* ``dfhack.items.getGeneralRef(item, type)`` * ``dfhack.items.getGeneralRef(item, type)``
@ -1310,12 +1333,14 @@ Maps module
* ``dfhack.maps.canWalkBetween(pos1, pos2)`` * ``dfhack.maps.canWalkBetween(pos1, pos2)``
Checks if a dwarf may be able to walk between the two tiles, Checks if a dwarf may be able to walk between the two tiles,
using a pathfinding cache maintained by the game. Note that using a pathfinding cache maintained by the game.
this cache is only updated when the game is unpaused, and thus
can get out of date if doors are forbidden or unforbidden, or .. note::
tools like liquids or tiletypes are used. It also cannot possibly This cache is only updated when the game is unpaused, and thus
take into account anything that depends on the actual units, like can get out of date if doors are forbidden or unforbidden, or
burrows, or the presence of invaders. tools like `liquids` or `tiletypes` are used. It also cannot possibly
take into account anything that depends on the actual units, like
burrows, or the presence of invaders.
* ``dfhack.maps.hasTileAssignment(tilemask)`` * ``dfhack.maps.hasTileAssignment(tilemask)``
@ -1381,6 +1406,9 @@ Burrows module
Buildings module Buildings module
---------------- ----------------
General
~~~~~~~
* ``dfhack.buildings.getGeneralRef(building, type)`` * ``dfhack.buildings.getGeneralRef(building, type)``
Searches for a general_ref with the given type. Searches for a general_ref with the given type.
@ -1439,7 +1467,9 @@ Buildings module
Returns a list of items stored on the given stockpile. Returns a list of items stored on the given stockpile.
Ignores empty bins, barrels, and wheelbarrows assigned as storage and transport for that stockpile. Ignores empty bins, barrels, and wheelbarrows assigned as storage and transport for that stockpile.
Low-level building creation functions; Low-level
~~~~~~~~~
Low-level building creation functions:
* ``dfhack.buildings.allocInstance(pos, type, subtype, custom)`` * ``dfhack.buildings.allocInstance(pos, type, subtype, custom)``
@ -1482,6 +1512,8 @@ Low-level building creation functions;
Destroys the building, or queues a deconstruction job. Destroys the building, or queues a deconstruction job.
Returns *true* if the building was destroyed and deallocated immediately. Returns *true* if the building was destroyed and deallocated immediately.
High-level
~~~~~~~~~~
More high-level functions are implemented in lua and can be loaded by More high-level functions are implemented in lua and can be loaded by
``require('dfhack.buildings')``. See ``hack/lua/dfhack/buildings.lua``. ``require('dfhack.buildings')``. See ``hack/lua/dfhack/buildings.lua``.
@ -1508,12 +1540,13 @@ Among them are:
Creates a building in one call, using options contained Creates a building in one call, using options contained
in the argument table. Returns the building, or *nil, error*. in the argument table. Returns the building, or *nil, error*.
**NOTE:** Despite the name, unless the building is abstract, .. note::
the function creates it in an 'unconstructed' stage, with Despite the name, unless the building is abstract,
a queued in-game job that will actually construct it. I.e. the function creates it in an 'unconstructed' stage, with
the function replicates programmatically what can be done a queued in-game job that will actually construct it. I.e.
through the construct building menu in the game ui, except the function replicates programmatically what can be done
that it does less environment constraint checking. through the construct building menu in the game ui, except
that it does less environment constraint checking.
The following options can be used: The following options can be used:
@ -1712,8 +1745,9 @@ In order to actually be able to paint to the screen, it is necessary
to create and register a viewscreen (basically a modal dialog) with to create and register a viewscreen (basically a modal dialog) with
the game. the game.
**NOTE**: As a matter of policy, in order to avoid user confusion, all .. warning::
interface screens added by dfhack should bear the "DFHack" signature. As a matter of policy, in order to avoid user confusion, all
interface screens added by dfhack should bear the "DFHack" signature.
Screens are managed with the following functions: Screens are managed with the following functions:
@ -1735,7 +1769,7 @@ Apart from a native viewscreen object, these functions accept a table
as a screen. In this case, ``show`` creates a new native viewscreen as a screen. In this case, ``show`` creates a new native viewscreen
that delegates all processing to methods stored in that table. that delegates all processing to methods stored in that table.
**NOTE**: Lua-implemented screens are only supported in the core context. .. note:: Lua-implemented screens are only supported in the core context.
Supported callbacks and fields are: Supported callbacks and fields are:
@ -2022,8 +2056,9 @@ and are only documented here for completeness:
Searches script paths for the script ``name`` and returns the path of the first Searches script paths for the script ``name`` and returns the path of the first
file found, or ``nil`` on failure. file found, or ``nil`` on failure.
Note: This requires an extension to be specified (``.lua`` or ``.rb``) - .. note::
use ``dfhack.findScript()`` to include the ``.lua`` extension automatically. This requires an extension to be specified (``.lua`` or ``.rb``) - use
``dfhack.findScript()`` to include the ``.lua`` extension automatically.
Core interpreter context Core interpreter context
======================== ========================
@ -2083,8 +2118,9 @@ Features:
Sets the function as one of the listeners. Assign *nil* to remove it. Sets the function as one of the listeners. Assign *nil* to remove it.
**NOTE**: The ``df.NULL`` key is reserved for the use by .. note::
the C++ owner of the event; it is an error to try setting it. The ``df.NULL`` key is reserved for the use by
the C++ owner of the event; it is an error to try setting it.
* ``#event`` * ``#event``
@ -2104,8 +2140,11 @@ Features:
Lua Modules Lua Modules
=========== ===========
.. contents::
:local:
DFHack sets up the lua interpreter so that the built-in ``require`` DFHack sets up the lua interpreter so that the built-in ``require``
function can be used to load shared lua code from hack/lua/. function can be used to load shared lua code from :file:`hack/lua/`.
The ``dfhack`` namespace reference itself may be obtained via The ``dfhack`` namespace reference itself may be obtained via
``require('dfhack')``, although it is initially created as a ``require('dfhack')``, although it is initially created as a
global by C++ bootstrap code. global by C++ bootstrap code.
@ -2143,12 +2182,12 @@ environment by the mandatory init file dfhack.lua:
* Color constants * Color constants
These are applicable both for ``dfhack.color()`` and color fields These are applicable both for ``dfhack.color()`` and color fields
in DF functions or structures: in DF functions or structures::
COLOR_RESET, COLOR_BLACK, COLOR_BLUE, COLOR_GREEN, COLOR_CYAN, COLOR_RESET, COLOR_BLACK, COLOR_BLUE, COLOR_GREEN, COLOR_CYAN,
COLOR_RED, COLOR_MAGENTA, COLOR_BROWN, COLOR_GREY, COLOR_DARKGREY, COLOR_RED, COLOR_MAGENTA, COLOR_BROWN, COLOR_GREY, COLOR_DARKGREY,
COLOR_LIGHTBLUE, COLOR_LIGHTGREEN, COLOR_LIGHTCYAN, COLOR_LIGHTRED, COLOR_LIGHTBLUE, COLOR_LIGHTGREEN, COLOR_LIGHTCYAN, COLOR_LIGHTRED,
COLOR_LIGHTMAGENTA, COLOR_YELLOW, COLOR_WHITE COLOR_LIGHTMAGENTA, COLOR_YELLOW, COLOR_WHITE
* ``dfhack.onStateChange`` event codes * ``dfhack.onStateChange`` event codes
@ -2163,8 +2202,10 @@ environment by the mandatory init file dfhack.lua:
* Miscellaneous constants * Miscellaneous constants
:NEWLINE, COMMA, PERIOD: evaluate to the relevant character strings. ``NEWLINE``, ``COMMA``, ``PERIOD``
:DEFAULT_NIL: is an unspecified unique token used by the class module below. evaluate to the relevant character strings.
``DEFAULT_NIL``
is an unspecified unique token used by the class module below.
* ``printall(obj)`` * ``printall(obj)``
@ -2271,7 +2312,7 @@ utils
Performs a shallow, or semi-deep copy of the object as a lua table tree. Performs a shallow, or semi-deep copy of the object as a lua table tree.
The deep mode recurses into lua tables and subobjects, except pointers The deep mode recurses into lua tables and subobjects, except pointers
to other heap objects. to other heap objects.
Null pointers are represented as df.NULL. Zero-based native containers Null pointers are represented as ``df.NULL``. Zero-based native containers
are converted to 1-based lua sequences. are converted to 1-based lua sequences.
* ``utils.clone_with_default(obj, default, force)`` * ``utils.clone_with_default(obj, default, force)``
@ -2328,7 +2369,7 @@ utils
utils.insert_or_update(soul.skills, {new=true, id=..., rating=...}, 'id') utils.insert_or_update(soul.skills, {new=true, id=..., rating=...}, 'id')
(For an explanation of ``new=true``, see table assignment in the wrapper section) (For an explanation of ``new=true``, see `lua-api-table-assignment`)
* ``utils.erase_sorted_key(vector,key,field,cmpfun)`` * ``utils.erase_sorted_key(vector,key,field,cmpfun)``
@ -2490,6 +2531,9 @@ To avoid confusion, these methods cannot be redefined.
In-game UI Library In-game UI Library
================== ==================
.. contents::
:local:
A number of lua modules with names starting with ``gui`` are dedicated A number of lua modules with names starting with ``gui`` are dedicated
to wrapping the natives of the ``dfhack.screen`` module in a way that to wrapping the natives of the ``dfhack.screen`` module in a way that
is easy to use. This allows relatively easily and naturally creating is easy to use. This allows relatively easily and naturally creating
@ -3219,6 +3263,9 @@ The widget implements:
Plugins Plugins
======= =======
.. contents::
:local:
DFHack plugins may export native functions and events DFHack plugins may export native functions and events
to lua contexts. They are automatically imported by to lua contexts. They are automatically imported by
``mkmodule('plugins.<name>')``; this means that a lua ``mkmodule('plugins.<name>')``; this means that a lua
@ -3449,24 +3496,45 @@ Functions
--------- ---------
``registerBuilding(table)`` where table must contain name, as a workshop raw name, the rest are optional: ``registerBuilding(table)`` where table must contain name, as a workshop raw name, the rest are optional:
1. name -- custom workshop id e.g. ``SOAPMAKER``
2. fix_impassible -- if true make impassible tiles impassible to liquids too :name:
3. consume -- how much machine power is needed to work. Disables reactions if not supplied enough and needs_power=1 custom workshop id e.g. ``SOAPMAKER``
4. produce -- how much machine power is produced.
5. needs_power -- if produced in network < consumed stop working, default true .. note:: this is the only mandatory field.
6. gears -- a table or ``{x=?,y=?}`` of connection points for machines.
7. action -- a table of number (how much ticks to skip) and a function which gets called on shop update :fix_impassible:
8. animate -- a table of frames which can be a table of: if true make impassible tiles impassible to liquids too
:consume:
a. tables of 4 numbers ``{tile,fore,back,bright}`` OR how much machine power is needed to work.
b. empty table (tile not modified) OR Disables reactions if not supplied enough and ``needs_power==1``
c. ``{x=<number> y=<number> + 4 numbers like in first case}``, this generates full frame useful for animations that change little (1-2 tiles) :produce:
9. canBeRoomSubset -- a flag if this building can be counted in room. 1 means it can, 0 means it can't and -1 default building behaviour how much machine power is produced.
10. auto_gears -- a flag that automatically fills up gears and animate. It looks over building definition for gear icons and maps them. :needs_power:
if produced in network < consumed stop working, default true
Animate table also might contain: :gears:
1. frameLenght -- how many ticks does one frame take OR a table or ``{x=?,y=?}`` of connection points for machines.
2. isMechanical -- a bool that says to try to match to mechanical system (i.e. how gears are turning) :action:
a table of number (how much ticks to skip) and a function which
gets called on shop update
:animate:
a table of frames which can be a table of:
a. tables of 4 numbers ``{tile,fore,back,bright}`` OR
b. empty table (tile not modified) OR
c. ``{x=<number> y=<number> + 4 numbers like in first case}``,
this generates full frame useful for animations that change little (1-2 tiles)
:canBeRoomSubset:
a flag if this building can be counted in room. 1 means it can, 0 means it can't and -1 default building behaviour
:auto_gears:
a flag that automatically fills up gears and animate. It looks over building definition for gear icons and maps them.
Animate table also might contain:
:frameLength:
how many ticks does one frame take OR
:isMechanical:
a bool that says to try to match to mechanical system (i.e. how gears are turning)
``getPower(building)`` returns two number - produced and consumed power if building can be modified and returns nothing otherwise ``getPower(building)`` returns two number - produced and consumed power if building can be modified and returns nothing otherwise
@ -3481,7 +3549,7 @@ Simple mechanical workshop::
consume=15, consume=15,
gears={x=0,y=0}, --connection point gears={x=0,y=0}, --connection point
animate={ animate={
isMechanical=true, --animate the same connection point as vanilla gear isMechanical=true, --animate the same conn. point as vanilla gear
frames={ frames={
{{x=0,y=0,42,7,0,0}}, --first frame, 1 changed tile {{x=0,y=0,42,7,0,0}}, --first frame, 1 changed tile
{{x=0,y=0,15,7,0,0}} -- second frame, same {{x=0,y=0,15,7,0,0}} -- second frame, same
@ -3525,15 +3593,12 @@ from ``server:accept()``. It's a subclass of ``socket``.
* ``client:receive(pattern)`` * ``client:receive(pattern)``
Receives data. If ``pattern`` is a number, it receives that much data. Other supported patterns: Receives data. Pattern is one of:
* ``*a``
Read all available data.
* ``*l`` :``*l``: read one line (default, if pattern is *nil*)
:<number>: read specified number of bytes
:``*a``: read all available data
Read one line. This is the default mode (if pattern is nil).
* ``client:send(data)`` * ``client:send(data)``
Sends data. Data is a string. Sends data. Data is a string.
@ -3542,11 +3607,13 @@ from ``server:accept()``. It's a subclass of ``socket``.
Server class Server class
------------ ------------
Server is a socket that is waiting for clients. You can get this object from ``tcp:bind(address,port)``. Server is a socket that is waiting for clients.
You can get this object from ``tcp:bind(address,port)``.
* ``server:accept()`` * ``server:accept()``
Accepts an incoming connection if it exists. Returns a ``client`` object representing that socket. Accepts an incoming connection if it exists.
Returns a ``client`` object representing that socket.
Tcp class Tcp class
--------- ---------
@ -3566,19 +3633,25 @@ A class with all the tcp functionality.
Scripts Scripts
======= =======
Any files with the .lua extension placed into hack/scripts/* .. contents::
:local:
Any files with the .lua extension placed into :file:`hack/scripts/*`
are automatically used by the DFHack core as commands. The are automatically used by the DFHack core as commands. The
matching command name consists of the name of the file without matching command name consists of the name of the file without
the extension. First DFHack searches for the script in the save folder/raw/scripts folder. If it is not found there, it searches in the DF/raw/scripts folder. If it is not there, it searches in DF/hack/scripts. If it is not there, it gives up. the extension. First DFHack searches for the script in the :file:`<save_folder>/raw/scripts/` folder. If it is not found there, it searches in the :file:`<DF>/raw/scripts/` folder. If it is not there, it searches in
:file:`<DF>/hack/scripts/`. If it is not there, it gives up.
If the first line of the script is a one-line comment, it is If the first line of the script is a one-line comment, it is
used by the built-in ``ls`` and ``help`` commands. used by the built-in ``ls`` and ``help`` commands.
Such a comment is required for every script in the official DFHack repository.
**NOTE:** Scripts placed in subdirectories still can be accessed, but .. note::
do not clutter the ``ls`` command list; thus it is preferred Scripts placed in subdirectories still can be accessed, but
for obscure developer-oriented scripts and scripts used by tools. do not clutter the `ls` command list (unless ``ls -a``; thus it is preferred
When calling such scripts, always use '/' as the separator for for obscure developer-oriented scripts and scripts used by tools.
directories, e.g. ``devel/lua-example``. When calling such scripts, always use '/' as the separator for
directories, e.g. ``devel/lua-example``.
Scripts are re-read from disk if they have changed since the last time they were read. Scripts are re-read from disk if they have changed since the last time they were read.
Global variable values persist in memory between calls, unless the file has changed. Global variable values persist in memory between calls, unless the file has changed.
@ -3605,12 +3678,15 @@ Note that this function lets errors propagate to the caller.
Run an Lua script and return its environment. Run an Lua script and return its environment.
This command allows you to use scripts like modules for increased portability. This command allows you to use scripts like modules for increased portability.
It is highly recommended that if you are a modder you put your custom modules in ``raw/scripts`` and use ``script_environment`` instead of ``require`` so that saves with your mod installed will be self-contained and can be transferred to people who do have DFHack but do not have your mod installed. It is highly recommended that if you are a modder you put your custom modules in ``raw/scripts`` and use ``script_environment`` instead of ``require`` so that saves with your mod installed will be self-contained and can be transferred to people who do have DFHack but do not have your mod installed.
You can say ``dfhack.script_environment('add-thought').addEmotionToUnit([arguments go here])`` and it will have the desired effect. You can say ``dfhack.script_environment('add-thought').addEmotionToUnit([arguments go here])`` and it will have the desired effect.
It will call the script in question with the global ``moduleMode`` set to ``true`` so that the script can return early. It will call the script in question with the global ``moduleMode`` set to ``true`` so that the script can return early.
This is useful because if the script is called from the console it should deal with its console arguments and if it is called by ``script_environment`` it should only create its global functions and return. This is useful because if the script is called from the console it should deal with its console arguments and if it is called by ``script_environment`` it should only create its global functions and return.
You can also access global variables with, for example ``print(dfhack.script_environment('add-thought').validArgs)`` You can also access global variables with, for example ``print(dfhack.script_environment('add-thought').validArgs)``
The function ``script_environment`` is fast enough that it is recommended that you not store its result in a nonlocal variable, because your script might need to load a different version of that script if the save is unloaded and a save with a different mod that overrides the same script with a slightly different functionality is loaded. The function ``script_environment`` is fast enough that it is recommended that you not store its result in a nonlocal variable, because your script might need to load a different version of that script if the save is unloaded and a save with a different mod that overrides the same script with a slightly different functionality is loaded.
This will not be an issue in most cases. This will not be an issue in most cases.
This function also permits circular dependencies of scripts. This function also permits circular dependencies of scripts.
* ``dfhack.reqscript(name)`` or ``reqscript(name)`` * ``dfhack.reqscript(name)`` or ``reqscript(name)``

@ -10,32 +10,25 @@ Most commands offered by plugins are listed here,
hopefully organised in a way you will find useful. hopefully organised in a way you will find useful.
.. contents:: .. contents::
:depth: 3 :depth: 2
=============================== ===============================
Data inspection and visualizers Data inspection and visualizers
=============================== ===============================
.. _stonesense: .. contents::
:local:
.. _plugin-stonesense:
stonesense stonesense
========== ==========
An isometric visualizer that runs in a second window. This requires working An isometric visualizer that runs in a second window. Usage:
graphics acceleration and at least a dual core CPU (otherwise it will slow
down DF). Usage:
:stonesense: Open the visualiser in a new window. Alias ``ssense``. :stonesense: Open the visualiser in a new window. Alias ``ssense``.
:ssense overlay: Overlay DF window, replacing the map area. :ssense overlay: Overlay DF window, replacing the map area.
``PRINT_MODE:2D`` strongly recommended for stability.
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
<Utility:Stonesense>`, or the :forums:`Bay12 forums thread <106497>`.
.. _`stonesense readme`: https://github.com/DFHack/stonesense/blob/master/README.md For more information, see `the full Stonesense README <stonesense>`.
.. _blueprint: .. _blueprint:
@ -173,6 +166,8 @@ Usage and related commands:
Only useful where (eg) you abandoned with the fort revealed Only useful where (eg) you abandoned with the fort revealed
and no longer want the data. and no longer want the data.
.. _showmood:
showmood showmood
======== ========
Shows all items needed for the currently active strange mood. Shows all items needed for the currently active strange mood.
@ -182,6 +177,9 @@ Shows all items needed for the currently active strange mood.
Bugfixes Bugfixes
======== ========
.. contents::
:local:
fixdiplomats fixdiplomats
============ ============
Adds a Diplomat position to all Elven civilizations, allowing them to negotiate Adds a Diplomat position to all Elven civilizations, allowing them to negotiate
@ -217,6 +215,8 @@ 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. accidentally placed a construction on top of a valuable mineral floor.
.. _petcapRemover:
petcapRemover petcapRemover
============= =============
Allows you to remove or raise the pet population cap. In vanilla Allows you to remove or raise the pet population cap. In vanilla
@ -333,13 +333,15 @@ UI Upgrades
=========== ===========
.. note:: .. note::
In order to avoid user confusion, as a matter of policy all GUI 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. display the word :guilabel:`DFHack` on the screen somewhere while active.
When that is not appropriate because they merely add keybinding hints to 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. existing DF screens, they deliberately use red instead of green for the key.
.. contents::
:local:
.. _automelt: .. _automelt:
@ -612,6 +614,12 @@ resume
Allows automatic resumption of suspended constructions, along with colored Allows automatic resumption of suspended constructions, along with colored
UI hints for construction status. UI hints for construction status.
.. _title-version:
title-version
=============
Displays the DFHack version on DF's title screen when enabled.
.. _trackstop: .. _trackstop:
trackstop trackstop
@ -739,6 +747,9 @@ materials that color the light etc...
Job and Fortress management Job and Fortress management
=========================== ===========================
.. contents::
:local:
.. _autolabor: .. _autolabor:
autolabor autolabor
@ -1187,6 +1198,8 @@ Some widgets support additional options:
displayed as ``-1`` when the cursor is outside of the DF window; otherwise, displayed as ``-1`` when the cursor is outside of the DF window; otherwise,
nothing will be displayed. nothing will be displayed.
.. _workNow:
workNow workNow
======= =======
Force all dwarves to look for a job immediately, or as soon as the game is unpaused. Force all dwarves to look for a job immediately, or as soon as the game is unpaused.
@ -1485,6 +1498,9 @@ open the dashboard from the chop designation menu.
Map modification Map modification
================ ================
.. contents::
:local:
.. _3dveins: .. _3dveins:
3dveins 3dveins
@ -1756,6 +1772,8 @@ Examples:
``digcircle`` ``digcircle``
Do it again. Do it again.
.. _digtype:
digtype digtype
======= =======
For every tile on the map of the same vein type as the selected tile, For every tile on the map of the same vein type as the selected tile,
@ -1776,6 +1794,8 @@ Options:
:down: down stairs :down: down stairs
:clear: clear designation :clear: clear designation
.. _digFlood:
digFlood digFlood
======== ========
Automatically digs out specified veins as they are discovered. It runs once Automatically digs out specified veins as they are discovered. It runs once
@ -1851,6 +1871,8 @@ All of the building designation uses `Planning Mode <buildingplan>`, so you do n
have the items available to construct all the buildings when you run have the items available to construct all the buildings when you run
fortplan with the .csv file. fortplan with the .csv file.
.. _getplants:
getplants getplants
========= =========
This tool allows plant gathering and tree cutting by RAW ID. Specify the types This tool allows plant gathering and tree cutting by RAW ID. Specify the types
@ -1869,6 +1891,8 @@ Options:
Specifying both ``-t`` and ``-s`` will have no effect. If no plant IDs are specified, Specifying both ``-t`` and ``-s`` will have no effect. If no plant IDs are specified,
all valid plant IDs will be listed. all valid plant IDs will be listed.
.. _infiniteSky:
infiniteSky infiniteSky
=========== ===========
Automatically allocates new z-levels of sky at the top of the map as you build up, Automatically allocates new z-levels of sky at the top of the map as you build up,
@ -1957,6 +1981,8 @@ 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. Intended to be used as keybinding. Requires an active in-game cursor.
.. _plant:
plant plant
===== =====
A tool for creating shrubs, growing, or getting rid of them. A tool for creating shrubs, growing, or getting rid of them.
@ -2111,6 +2137,9 @@ your miner when you dig into the region that used to be hollow.
Mods and Cheating Mods and Cheating
================= =================
.. contents::
:local:
.. _add-spatter: .. _add-spatter:
add-spatter add-spatter
@ -2294,9 +2323,11 @@ Known limitations: if the selected unit is currently performing a job, the mood
siege-engine siege-engine
============ ============
Siege engines in DF haven't been updated since the game was 2D, and can 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: only aim in four directions. To make them useful above-ground,
this plugin allows you to:
* link siege engines to stockpiles * link siege engines to stockpiles
* restrict operator skill levels (like workshops)
* load any object into a catapult, not just stones * load any object into a catapult, not just stones
* aim at a rectangular area in any direction, and across Z-levels * aim at a rectangular area in any direction, and across Z-levels

@ -0,0 +1,23 @@
<!DOCTYPE HTML>
<!--
DO NOT CHANGE THIS FILE - it redirects to the actual documentation.
If the page is not found, you can read the raw docs in the docs folder.
This file is an additional redirect for users in the DFHack code repo
who are visiting from ../README.html
For end-users, the real index.html will be in this relative location.
-->
<html lang="en-US">
<head>
<meta charset="UTF-8">
<meta http-equiv="refresh" content="0;url=./html/index.html">
<script type="text/javascript">
window.location.href = "./html/index.html"
</script>
<title>Page Redirection</title>
</head>
<body>
Follow this <a href='./html/index.html'>link to the documentation.</a>
</body>
</html>