DOCSEARCHbyAlgolia
Submit Docs

Stonesense Documentation

repository·master·Indexed 18 days ago

https://github.com/dfhack/stonesense

Stonesense is an isometric visualizer for Dwarf Fortress implemented as a plugin for the DFHack toolset. It provides a read-only isometric perspective of the game world, featuring mouse-based navigation, Z-depth adjustment, and screenshot capabilities. The plugin is launched via the 'stonesense' or 'ssense' commands in the DFHack console and can be configured through init.txt.

Tokens
887
Snippets
2
Records
8
Agent score
14%

What's inside Stonesense

  2. Use Stonesense mouse and view controls

    master

    Stonesense uses hard-coded mouse controls for navigation and depth adjustment:

    ControlAction
    Left clickMove debug cursor (if available)
    Right clickRecenter screen
    ScrollwheelMove up and down
    Ctrl + ScrollIncrease/decrease Z depth shown

    Follow Mode: When follow mode is enabled, the Stonesense view follows the Dwarf Fortress window. You can adjust the offset by holding Ctrl while using the keyboard window movement keys. If cursor follow mode is active, the Stonesense debug cursor will follow the DF keyboard cursor.

  3. Take screenshots in Stonesense

    master

    Screenshots are saved directly to your Dwarf Fortress directory. Use the following key combinations:

    Key CombinationAction
    F5Standard screenshot
    Ctrl + F5Larger screenshot
    Ctrl + Shift + F5Mega screenshot (full map at full resolution)

    Note: When taking very large screenshots, you may need to zoom out first. Feedback regarding the screenshot process is printed to the DFHack console.

  4. Launch Stonesense

    master

    To open the Stonesense isometric visualizer in a new window, run the following command from the DFHack console:

    stonesense

    Alternatively, you can use the shorthand command:

    ssense

    The viewer window provides read-only access to the game state and can either follow the game view or be moved independently.

    stonesense

  6. Troubleshoot Stonesense errors and performance

    master

    High-detail sprite error

    If you receive an error stating that Stonesense cannot load creatures/large_256/*.png, your video card may not support high-detail sprites. Solutions:

    1. Open creatures/init.txt and remove the line containing that folder.
    2. Use smaller sprites instead.

    Mega screenshot unresponsiveness

    Taking a mega screenshot (Ctrl + Shift + F5) puts the buffer into an invalid state. After a mega screenshot is written to disk, the Stonesense window will become unresponsive. You must close the window and re-run stonesense to continue.

    Hardware requirements

    • Graphics: Requires working graphics acceleration.
    • CPU: A dual-core CPU is recommended to prevent Stonesense from slowing down the main Dwarf Fortress game process.

  7. Plugin lifecycle and entrypoints

    master

    Stonesense is implemented as a DFHack plugin. It provides the following standard DFHack entrypoints:

    • plugin_init: Registers the stonesense and ssense commands.
    • plugin_onupdate: Called every frame by DFHack; currently returns CR_OK without performing actions.
    • plugin_shutdown: Cleans up the plugin by joining the Stonesense event thread and uninstalling the Allegro system.

  8. Use the stonesense DFHack command

    master

    The stonesense (or ssense) command launches the Stonesense isometric viewer. It initializes the Allegro graphics library and starts a dedicated event thread for the visualizer.

    If the command is called while Stonesense is already running, it will notify you and return without starting a new instance.

    Arguments:

    • overlay: (Currently unsupported/commented out in implementation) Intended to enable an overlay mode.
    • [other params]: If parameters other than overlay are provided, the plugin attempts to call DumpInfo with those parameters instead of launching the visualizer.
    stonesense
ssense