DOCSEARCHbyAlgolia
Submit Docs

DFHack Documentation

repository·develop·Indexed 24 days ago

https://github.com/dfhack/dfhack

A memory access library and toolset for Dwarf Fortress that provides developers and modders with scripts and plugins to extend and manipulate the game. Includes documentation on built-in commands like quickfort, alias, and keybinding, as well as guides for adding custom Lua scripts, managing blueprints, and using the C++ and Lua map data interfaces.

Tokens
119.9K
Snippets
275
Records
674
Agent score
84%

What's inside DFHack

  2. Overview of DFHack

    develop
    DFHack is a memory editing library for Dwarf Fortress that provides a unified, cross-platform environment for developing tools to extend the game. The default distribution includes various tools such as bugfixes, interface improvements, automation tools, and modding tools. It also supports third-party tools.

  3. Overview of DFHack Build Dependencies

    develop

    DFHack requires several system-level dependencies to build successfully. Some libraries are included as Git submodules and require no action, but the following must be installed on your system:

    • Build System: CMake (v3.21+ recommended) and a build tool like ninja (recommended) or make.
    • Compiler:
      • Linux: GCC 10 or newer.
      • Windows: Microsoft Visual C++ 2022 toolchain (MSVC v143).
      • macOS: GCC 4.8 or 7 is recommended.
    • Perl 5: Required for code generation (converts XML memory structures into C++ headers and Lua wrappers). Requires XML::LibXML and XML::LibXSLT.
    • Python 3: Required for building documentation via Sphinx.
    • Git: Required for contributions.
    • Optional Dependencies:
      • ccache: Strongly recommended to improve build times.
      • OpenGL headers: Required to build stonesense.
      • zlib: Used for xlsxreader-api -> quickfort.

  4. Overview of the DFHack Lua API

    develop

    DFHack provides extensive support for the Lua scripting language, allowing developers to interact with the game and DFHack itself. The API provides access to:

    1. Raw data structures used by Dwarf Fortress.
    2. High-level C++ functions for accessing these structures and interacting with DFHack.
    3. Functions exported by C++ plugins.

    Lua code can be used in two primary ways:

    • As scripts: Executed via the DFHack command line prompt, behaving similarly to native C++ commands.
    • Via C++ plugins: Invoked directly by plugins written in C++.

    Note: This documentation refers specifically to the DFHack Lua API. For information regarding the native Dwarf Fortress Lua API, refer to the Dwarf Fortress Wiki.

  5. Manage buildings with dfhack.buildings

    develop
    The dfhack.buildings module provides functions for querying, creating, and manipulating building instances in the game world. It includes high-level functions for checking placement validity, managing stockpile contents, and low-level functions for manual building allocation and construction.

  6. Understand the DFHack documentation system

    develop

    DFHack documentation is written in reStructuredText (reST) format and compiled using Sphinx. The documentation is rendered in two ways:

    1. HTML: For viewing in a web browser (available online at docs.dfhack.org).
    2. Text: For in-game viewing via the help and ls commands. In-game help text is read from the installed location in hack/docs under the DF directory.

    Note that documentation compilation is disabled by default in the build process due to Python and Sphinx dependencies. If you are using a downloaded release binary, you only need to build the docs if you are modifying them and want to see changes reflected in-game.

  7. Understand DFHack CI and Release Workflows

    develop

    DFHack uses GitHub workflows to manage continuous integration (CI) validation and release automation. These workflows are defined in YAML files located in the .github/workflows/ directory.

    Key characteristics:

    • Inheritance: Submodules (like scripts and df-structures) can inherit CI logic from the main DFHack/dfhack repository to maintain consistency across the organization.
    • Caching: The project uses GitHub's 10GB cache per repository to speed up builds. Caches are namespaced by key prefixes (e.g., gcc-11-release vs gcc-11-test) to prevent collisions and ensure build speed.

  9. Configure stockpile settings for stockpiles and quickfort

    develop

    The data/dfhack-config/stockpiles/ directory contains configuration settings used by the stockpiles and quickfort tools. These settings allow you to define how items are organized and stored within your fortress.

    To customize your stockpile behavior, place your configuration files in this directory. For detailed usage instructions, refer to the official documentation for each tool:

    • stockpiles: For managing item stockpiles and organization.
    • quickfort: For automated fortress construction and resource management.

  10. Use the jobutils plugin to manage workshop jobs

    develop

    The jobutils plugin provides commands to inspect and modify details of workshop jobs, such as changing the materials or item types of specific components within a job.

    Key commands include:

    • job: Inspect the current job.
    • job list: List all jobs in the selected workshop.
    • job-duplicate: Duplicate the highlighted job (requires being in q mode with a workshop or furnace selected).
    • job-material <inorganic-token>: Change the material of a selected job (in q mode) or jump to a material when choosing building components (in b mode). This only works for inorganic materials.
    • job item-material <item-idx> <material[:subtoken]>: Replace the material ID of a specific item within a job.
    • job item-type <item-idx> <type[:subtype]>: Replace the item type ID of a specific item within a job.

  11. Use the sort tool to search and sort interface lists

    develop

    The sort tool provides search and sorting functionality for various lists within the Dwarf Fortress interface. This functionality is implemented via overlay widgets.

    To manage these overlays:

    • Move widgets: Use the gui/overlay command.
    • Enable/Disable widgets: Use the gui/control-panel command.

  12. Reverse engineering tools for DF memory

    develop

    Several third-party tools can be used to analyze DF memory across different platforms:

    Cross-platform

    • Ghidra: A Java-based framework. Custom DFHack Ghidra scripts (.java files) are available in the df_misc repository.
    • IDA Freeware 7.0: Supports 32-bit and 64-bit executables. Some .idc scripts are available in the df_misc repository.
    • Hopper: Available on macOS and some Linux distributions.

    Windows-specific

    • Cheat Engine: Historically used for research.