- v50 information can now be added to pages in the main namespace. v0.47 information can still be found in the DF2014 namespace. See here for more details on the new versioning policy.
- Use this page to report any issues related to the migration.
Difference between revisions of "Utility:DFHack"
m (update) |
|||
| (26 intermediate revisions by 8 users not shown) | |||
| Line 1: | Line 1: | ||
{{Quality|Superior|13:02, 2 May 2014 (UTC)}} | {{Quality|Superior|13:02, 2 May 2014 (UTC)}} | ||
| + | {{Utility:DFHack/sidebar}} | ||
{{uv|multiple}} | {{uv|multiple}} | ||
| − | '''DFHack''' is an extensive standardized memory access library, packaged alongside a suite of basic tools that use it. Currently tools come in the form of plugins, as well as Lua and Ruby scripts. For developers, DFHack is a comprehensive, standardized memory access package that unites the various ways tools access the Dwarf Fortress memory space, allowing for easier development of new tools. For users, it is a very useful utility complex that allows users to tweak their games in numerous ways in-game. This is probably one of the most useful | + | [[File:dfhack_cmd.png|thumb|300px|right|Command ready!]]'''DFHack''' is an extensive standardized memory access library, packaged alongside a suite of basic tools that use it. Currently, tools come in the form of plugins, as well as Lua and Ruby scripts. For developers, DFHack is a comprehensive, standardized memory access package that unites the various ways tools access the ''Dwarf Fortress'' memory space, allowing for easier development of new tools. For users, it is a very useful utility complex that allows users to tweak their games in numerous ways in-game. This is probably one of the most useful utilities for DF, acting as an advanced expansion that fixes, improves and adds to the game in many ways, and is usually included in recent versions of the [[Utility:Lazy Newb Pack|Lazy Newb Pack]] on all platforms. |
| − | For an exhaustive list of and manual on the commands in the utility, see the [https:// | + | All new releases are announced in a [http://www.bay12forums.com/smf/index.php?topic=164123.0 thread on the Bay12 forums]. Downloads for all releases can be found on [https://github.com/dfhack/dfhack/releases GitHub]. DFHack is currently available as a stable release for 0.44.12. Stable releases are also available for 0.42.06, 0.40.24, 0.34.11, 0.31.25, and other intermediate versions of DF. DFHack is currently also being ported to versions 0.28.181.40d and 0.23.130.23a - more information can be found [[User:Quietust#DFHack-40d|here]] and [[User:Quietust#DFHack-23a|here]], respectively. For an exhaustive list of and manual on the commands in the utility, see the [https://dfhack.readthedocs.org/en/stable/#user-manual documentation]. This wiki also has a [[Utility:DFHack/Programming|DFHack programming page]]. |
| − | If you are using DFHack, | + | {{TipBox2|float=center|titlebg=red|Bug reports| |
| − | + | <small>If you are using DFHack (or other utilities), do not report bugs on the ''Dwarf Fortress'' bug tracker unless you can prove that the bug is not being caused by DFHack or one of its plugins. On Linux and OS X, DFHack can be bypassed by running the "df" script. On Windows, DFHack can be temporarily disabled by renaming SDL.dll to a temporary name, then renaming SDLreal.dll to SDL.dll.</small> | |
| − | + | }} | |
| − | |||
| − | |||
| − | |||
| + | == Documentation == | ||
| + | * [[/Installation|Installation and uninstallation]] | ||
| + | * [[/Compiling|Compiling from source]] | ||
==Common Uses== | ==Common Uses== | ||
| − | DFHack is often used to automate some aspects of | + | DFHack is often used to automate some aspects of the game, add features, fix bugs, or to make a specific one-off change. |
===Automation=== | ===Automation=== | ||
| Line 25: | Line 26: | ||
===Stonesense=== | ===Stonesense=== | ||
| − | DFHack | + | Recent DFHack builds come with [[Stonesense]] by default |
| + | |||
| + | ===Isoworld=== | ||
| + | DFHack also has [[Isoworld]] integration. | ||
| + | |||
| + | ===Adventure mode=== | ||
| + | See: [https://dfhack.readthedocs.io/en/stable/docs/_auto/gui.html#gui-advfort advfort], [https://dfhack.readthedocs.io/en/stable/docs/_auto/gui.html#gui-companion-order companion-order]. | ||
| + | |||
| + | ==Scripts and Plugins== | ||
| + | |||
| + | Originally a simple memory hacking tool, DFHack has grown to become a full-fledged unofficial extension of the game itself, adding in functionality where official development has lacked. One of the best features of DFHack is its extensibility - anyone can create scripts or plugins. Due to its open-source and collaborative nature, anyone can add their own contribution to this tool. There are different kinds of contributions: | ||
| − | + | *Binpatches are raw memory edits that alter the game's behavior, which is usually deduced from disassembling. Their main use is bugfixing or the removal of cumbersome, easily alterable constraints. | |
| − | + | *Plugins are snippets of C++ code that uses DFHack's library to fix bugs or add functionality. They must be compiled before use and are thus platform and dfhack-version dependent. They can be found in the hack/plugins folder. | |
| + | *Scripts are files written in a scripting language DFHack provides bindings for (usually Lua or Ruby) that when loaded by DFHack fix bugs or add functionality. Contrary to plugins, they are not compiled and can be transferred between any platform. However any change within the DFHack data structures (i.e. between versions) may break some of these scripts. | ||
| + | |||
| + | Some of the more notable are listed below; feel free to add to the list. | ||
=== User Interface === | === User Interface === | ||
| Line 37: | Line 51: | ||
=== Bugfixing === | === Bugfixing === | ||
| − | Many bugfixes are included with DFHack, but not enabled by default - check dfhack.init to see if the tweak | + | Many bugfixes are included with DFHack, but not enabled by default - check dfhack.init to see if the "tweak *" and "fix/*" lines are commented out. The [[Utility:Lazy_Newb_Pack|Starter Packs]] enable all bugfixes by default. |
| − | |||
| − | |||
=== Features === | === Features === | ||
| − | These plugins and scripts add features to the game | + | These plugins and scripts add features to the game that enhance the user's gameplay. |
* [http://www.bay12forums.com/smf/index.php?topic=127116 Digging invaders], a plugin that allows hostiles to dig and deconstruct walls to path to one's fortress. | * [http://www.bay12forums.com/smf/index.php?topic=127116 Digging invaders], a plugin that allows hostiles to dig and deconstruct walls to path to one's fortress. | ||
* [http://www.bay12forums.com/smf/index.php?topic=128487 Rendermax], a plugin that implements a lighting system at the graphics level. | * [http://www.bay12forums.com/smf/index.php?topic=128487 Rendermax], a plugin that implements a lighting system at the graphics level. | ||
* [http://www.bay12forums.com/smf/index.php?topic=136155 Dwarven Emigration], a plugin that allows unhappy dwarves to emigrate with their families. | * [http://www.bay12forums.com/smf/index.php?topic=136155 Dwarven Emigration], a plugin that allows unhappy dwarves to emigrate with their families. | ||
| + | |||
| + | === Modding tools === | ||
| + | These plugins and scripts add features to the game that enhance modding possibilities. | ||
* [http://www.bay12forums.com/smf/index.php?topic=135597 DFHack scripts designed for use in interactions as "spells"] | * [http://www.bay12forums.com/smf/index.php?topic=135597 DFHack scripts designed for use in interactions as "spells"] | ||
* [http://www.bay12forums.com/smf/index.php?topic=135506 Miscellaneous DFHack script collection] | * [http://www.bay12forums.com/smf/index.php?topic=135506 Miscellaneous DFHack script collection] | ||
| − | |||
| − | |||
| − | |||
| − | |||
Revision as of 09:29, 11 November 2019
| Getting started |
|---|
| Documentation |
| This utility page applies to multiple versions of DF. |
DFHack is an extensive standardized memory access library, packaged alongside a suite of basic tools that use it. Currently, tools come in the form of plugins, as well as Lua and Ruby scripts. For developers, DFHack is a comprehensive, standardized memory access package that unites the various ways tools access the Dwarf Fortress memory space, allowing for easier development of new tools. For users, it is a very useful utility complex that allows users to tweak their games in numerous ways in-game. This is probably one of the most useful utilities for DF, acting as an advanced expansion that fixes, improves and adds to the game in many ways, and is usually included in recent versions of the Lazy Newb Pack on all platforms.
All new releases are announced in a thread on the Bay12 forums. Downloads for all releases can be found on GitHub. DFHack is currently available as a stable release for 0.44.12. Stable releases are also available for 0.42.06, 0.40.24, 0.34.11, 0.31.25, and other intermediate versions of DF. DFHack is currently also being ported to versions 0.28.181.40d and 0.23.130.23a - more information can be found here and here, respectively. For an exhaustive list of and manual on the commands in the utility, see the documentation. This wiki also has a DFHack programming page.
If you are using DFHack (or other utilities), do not report bugs on the Dwarf Fortress bug tracker unless you can prove that the bug is not being caused by DFHack or one of its plugins. On Linux and OS X, DFHack can be bypassed by running the "df" script. On Windows, DFHack can be temporarily disabled by renaming SDL.dll to a temporary name, then renaming SDLreal.dll to SDL.dll.
Documentation
Common Uses
DFHack is often used to automate some aspects of the game, add features, fix bugs, or to make a specific one-off change.
Automation
See: workflow, autolabor, autobutcher, autochop, autonestbox, seedwatch, df-ai, dwarf manipulator.
One-off changes
Includes commands like "cleanowned scattered x" or "reveal".
Additional features
Steam engines, power meter, improved siege engines.
Stonesense
Recent DFHack builds come with Stonesense by default
Isoworld
DFHack also has Isoworld integration.
Adventure mode
See: advfort, companion-order.
Scripts and Plugins
Originally a simple memory hacking tool, DFHack has grown to become a full-fledged unofficial extension of the game itself, adding in functionality where official development has lacked. One of the best features of DFHack is its extensibility - anyone can create scripts or plugins. Due to its open-source and collaborative nature, anyone can add their own contribution to this tool. There are different kinds of contributions:
- Binpatches are raw memory edits that alter the game's behavior, which is usually deduced from disassembling. Their main use is bugfixing or the removal of cumbersome, easily alterable constraints.
- Plugins are snippets of C++ code that uses DFHack's library to fix bugs or add functionality. They must be compiled before use and are thus platform and dfhack-version dependent. They can be found in the hack/plugins folder.
- Scripts are files written in a scripting language DFHack provides bindings for (usually Lua or Ruby) that when loaded by DFHack fix bugs or add functionality. Contrary to plugins, they are not compiled and can be transferred between any platform. However any change within the DFHack data structures (i.e. between versions) may break some of these scripts.
Some of the more notable are listed below; feel free to add to the list.
User Interface
The best-known are Falconne's UI Plugins, a collection which improves the in-game interface with features such as search functions in screens with big lists, the ability to place furniture before it's built and have it automatically allocated when available, box-select constructions(like laying designations) - including easier material selection and open space placement, easier pasturing, live happiness monitor, mouse support, and an enhanced stocks screen. The plugins make existing tasks significantly easier, and also add new functions to the game which greatly enhance the experience - such as the autochop log quotas, or the ability (with buildingplanner) to lay out rooms with Quickfort before creating the required furniture.
There is also a GUI for the Autobutcher plugin.
Bugfixing
Many bugfixes are included with DFHack, but not enabled by default - check dfhack.init to see if the "tweak *" and "fix/*" lines are commented out. The Starter Packs enable all bugfixes by default.
Features
These plugins and scripts add features to the game that enhance the user's gameplay.
- Digging invaders, a plugin that allows hostiles to dig and deconstruct walls to path to one's fortress.
- Rendermax, a plugin that implements a lighting system at the graphics level.
- Dwarven Emigration, a plugin that allows unhappy dwarves to emigrate with their families.
Modding tools
These plugins and scripts add features to the game that enhance modding possibilities.