dwarfmonitor
============

Tags: fort | inspection | jobs | units

Command: "dwarfmonitor"

  Measure fort happiness and efficiency.

Keybinding: [Alt][M] -> ""dwarfmonitor prefs"" in "dwarfmode/Default"

Keybinding: [Ctrl][F] -> ""dwarfmonitor stats"" in "dwarfmode/Default"

It can also show heads-up display widgets with live fort statistics.


Usage
-----

"enable dwarfmonitor"
   Enable the plugin.

"dwarfmonitor enable <mode>"
   Start tracking a specific facet of fortress life. The "mode" can be "work", "misery", "date", "weather", or "all".  This will show the corresponding on-screen widgets, if applicable.

"dwarfmonitor disable <mode>"
   Stop monitoring "mode" and disable corresponding widgets.

"dwarfmonitor stats"
   Show statistics summary.

"dwarfmonitor prefs"
   Show summary of dwarf preferences.

"dwarfmonitor reload"
   Reload the widget configuration file ("dfhack-config/dwarfmonitor.json").


Widget configuration
--------------------

The following types of widgets (defined in "hack/lua/plugins/dwarfmonitor.lua") can be displayed on the main fortress mode screen:

"misery"
   Show overall happiness levels of all dwarves.

"date"
   Show the in-game date.

"weather"
   Show current weather (e.g. rain/snow).

"cursor"
   Show the current mouse cursor position.

The file "dfhack-config/dwarfmonitor.json" can be edited to control the positions and settings of all widgets. This file should contain a JSON object with the key "widgets" containing an array of objects:

   {
       "widgets": [
           {
               "type": "widget type (weather, misery, etc.)",
               "x": X coordinate,
               "y": Y coordinate
               <...additional options...>
           }
       ]
   }

X and Y coordinates begin at zero (in the upper left corner of the screen). Negative coordinates will be treated as distances from the lower right corner, beginning at 1 - e.g. an x coordinate of 0 is the leftmost column, while an x coordinate of -1 is the rightmost column.

By default, the x and y coordinates given correspond to the leftmost tile of the widget. Including an "anchor" option set to "right" will cause the rightmost tile of the widget to be located at this position instead.

Some widgets support additional options:

* "date" widget:

  * "format": specifies the format of the date. The following characters are replaced (all others, such as punctuation, are not modified)

    * "Y" or "y": The current year

    * "M": The current month, zero-padded if necessary

    * "m": The current month, *not* zero-padded

    * "D": The current day, zero-padded if necessary

    * "d": The current day, *not* zero-padded

    The default date format is "Y-M-D", per the ISO8601 standard.

* "cursor" widget:

  * "format": Specifies the format. "X", "x", "Y", and "y" are replaced with the corresponding cursor coordinates, while all other characters are unmodified.

  * "show_invalid": If set to "true", the mouse coordinates will both be displayed as "-1" when the cursor is outside of the DF window; otherwise, nothing will be displayed.
