dfhack/docs/plugins/spectate.rst

spectate
========

.. dfhack-tool::
    :summary: Automatically follow productive dwarves.
    :tags: fort interface

Usage
-----

::

    enable spectate
    spectate set <setting> <value>
    spectate enable|disable <feature>


When enabled, the plugin will automatically switch which dwarf is being
followed periodically, preferring dwarves on z-levels with the highest
job activity.

Changes to plugin settings will be saved per world. Whether the plugin itself
is enabled or not is not saved.

Examples
--------

``spectate``
    The plugin reports its configured status.

``spectate enable auto-unpause``
    Enable the spectate plugin to automatically dismiss pause events caused
    by the game. Siege events are one example of such a game event.

``spectate set tick-threshold 50``
    Set the tick interval the followed dwarf can be changed at back to its
    default value.

Features
--------
:focus-jobs:     Toggle whether the plugin should always be following a job. (default: disabled)
:auto-unpause:   Toggle auto-dismissal of game pause events. (default: disabled)
:auto-disengage: Toggle auto-disengagement of plugin through player intervention while unpaused. (default: disabled)

Settings
--------
:tick-threshold: Set the plugin's tick interval for changing the followed dwarf.
                 Acts as a maximum follow time when used with focus-jobs enabled. (default: 50)
split the plugin docs into individual files 2022-07-10 00:01:46 -06:00			`spectate`
			`========`
update docs for spectate 2022-07-31 14:29:18 -06:00
migrate all docs to the new directives add a summary option for tools and commands so we can output them with their tags and keybindings at the top of the file. 2022-08-09 23:37:24 -06:00			`.. dfhack-tool::`
Adds more features to spectate 2022-09-03 12:18:46 -06:00			`:summary: Automatically follow productive dwarves.`
revise tag list and assignments 2022-08-12 00:34:37 -06:00			`:tags: fort interface`
update docs for spectate 2022-07-31 14:29:18 -06:00
make Usage a proper header 2022-08-17 23:42:02 -06:00			`Usage`
			`-----`

			`::`
update docs for spectate 2022-07-31 14:29:18 -06:00
Adds more features to spectate 2022-09-03 12:18:46 -06:00			`enable spectate`
Updates spectate.rst 2022-10-23 11:40:23 -06:00			`spectate set <setting> <value>`
Finalizes spectate update - Fixes for state transitions that were found broken. eg. plugin disabled -> enable auto-unpause feature -> enable plugin (auto-unpause will not truly be enabled; similar transitions were broken) - Adds a commented out lock for if the pause code is ever adopted into the core API, as to enable many mods to use the `World::SetPauseState()` without walking over each other, and in the case of `reveal hell` also be able to avoid needing to set the state every tick in onupdate - Revises the usage docs with `enable\|disable\|set` syntax 2022-10-14 18:02:43 -06:00			`spectate enable\|disable <feature>`
Updates spectate.rst 2022-09-01 18:14:10 -06:00
update docs for spectate 2022-07-31 14:29:18 -06:00
Adds more features to spectate 2022-09-03 12:18:46 -06:00			`When enabled, the plugin will automatically switch which dwarf is being`
			`followed periodically, preferring dwarves on z-levels with the highest`
			`job activity.`

Updated documentation/changelog 2022-10-12 15:40:21 -06:00			`Changes to plugin settings will be saved per world. Whether the plugin itself`
			`is enabled or not is not saved.`

Updates spectate.rst 2022-09-01 18:14:10 -06:00			`Examples`
			`--------`

			``spectate``
Updates spectate.rst 2022-10-23 11:40:23 -06:00			`The plugin reports its configured status.`
Updates spectate.rst 2022-09-01 18:14:10 -06:00
Implements change requests - removes redundant `if (df::global::ui)` checks; and tested to ensure no segfaults cropped up like in the past times I've removed these - removes useless `if (pause_lock)` pause lock is set when plugin initializes, even if pause lock was left null (since we technically don't need it, and that was the point of the null check) it still would be a useless check (actually an impediment preventing functionality) - removes disabled interpose code - removes lua linkage - updates doc extra: - surrounds user input for tick frequency with `std::abs()` not that we would have ended up with a negative value, but it was probably a typo and this is easier than printing an error or letting it underflow past max int (on most systems) 2022-10-21 00:52:30 -06:00			``spectate enable auto-unpause``
Updates spectate.rst 2022-09-01 18:14:10 -06:00			`Enable the spectate plugin to automatically dismiss pause events caused`
			`by the game. Siege events are one example of such a game event.`

Update docs/plugins/spectate.rst 2022-10-24 18:50:21 -06:00			``spectate set tick-threshold 50``
Adds more features to spectate 2022-09-03 12:18:46 -06:00			`Set the tick interval the followed dwarf can be changed at back to its`
			`default value.`

Updates spectate.rst 2022-10-23 11:40:23 -06:00			`Features`
			`--------`
			`:focus-jobs: Toggle whether the plugin should always be following a job. (default: disabled)`
			`:auto-unpause: Toggle auto-dismissal of game pause events. (default: disabled)`
			`:auto-disengage: Toggle auto-disengagement of plugin through player intervention while unpaused. (default: disabled)`
Updates spectate.rst 2022-09-01 18:14:10 -06:00
Updates spectate.rst 2022-10-23 11:40:23 -06:00			`Settings`
Fixes underline in spectate.rst 2022-10-23 11:45:23 -06:00			`--------`
Reorders spectate code blocks, and adds persisting configuration 2022-09-03 18:02:57 -06:00			`:tick-threshold: Set the plugin's tick interval for changing the followed dwarf.`
Updated documentation/changelog 2022-10-12 15:40:21 -06:00			`Acts as a maximum follow time when used with focus-jobs enabled. (default: 50)`