more script enablement docs

develop
myk002 2022-12-06 16:42:14 -08:00 committed by Myk Taylor
parent 70ad8a2260
commit 107be0a4a6
No known key found for this signature in database
3 changed files with 44 additions and 0 deletions

@ -16,6 +16,9 @@ and disabled plugins, and shows whether that can be changed through the same
commands. Passing plugin names to these commands will enable or disable the commands. Passing plugin names to these commands will enable or disable the
specified plugins. specified plugins.
If you are a script developer, see `script-enable-api` for how to expose whether
your script is currently enabled or disabled.
Usage Usage
----- -----

@ -5532,6 +5532,8 @@ Importing scripts
not declare support as described above, although it is preferred to update not declare support as described above, although it is preferred to update
such scripts so that ``reqscript()`` can be used instead. such scripts so that ``reqscript()`` can be used instead.
.. _script-enable-api:
Enabling and disabling scripts Enabling and disabling scripts
============================== ==============================
@ -5546,18 +5548,55 @@ table passed to the script will have the following fields set:
* ``enable``: Always ``true`` if the script is being enabled *or* disabled * ``enable``: Always ``true`` if the script is being enabled *or* disabled
* ``enable_state``: ``true`` if the script is being enabled, ``false`` otherwise * ``enable_state``: ``true`` if the script is being enabled, ``false`` otherwise
If you declare a global function named ``isEnabled`` that returns a boolean
indicating whether your script is enabled, then your script will be listed among
the other enableable scripts and plugins when the player runs the `enable`
command.
Example usage:: Example usage::
--@ enable = true --@ enable = true
enabled = enabled or false
function isEnabled()
return enabled
end
-- (function definitions...) -- (function definitions...)
if dfhack_flags.enable then if dfhack_flags.enable then
if dfhack_flags.enable_state then if dfhack_flags.enable_state then
start() start()
enabled = true
else else
stop() stop()
enabled = false
end
end end
If the state of your script is tied to the active savegame, then your script
should hook the appropriate events to load persisted state when the savegame is
reloaded. For example::
local json = require('json')
local persist = require('persist-table')
local GLOBAL_KEY = 'my-script-name'
g_state = g_state or {}
dfhack.onStateChange[GLOBAL_KEY] = function(sc)
if sc ~= SC_MAP_LOADED or df.global.gamemode ~= df.game_mode.DWARF then
return
end
local state = json.decode(persist.GlobalTable[GLOBAL_KEY] or '')
g_state = state or {}
end end
The attachment to ``dfhack.onStateChange`` should appear in your script code
outside of any function. The `script-manager` will load your script as a module
when DFHack is initialized, giving this code an opportunity to run and attach
hooks before a game is loaded.
Save init script Save init script
================ ================

@ -10,3 +10,5 @@ This plugin loads all scripts that are declared as modules so that they can
put state change hooks in place for loading persistent data. It also scans for put state change hooks in place for loading persistent data. It also scans for
global ``isEnabled()`` functions and gathers them for script enabled state global ``isEnabled()`` functions and gathers them for script enabled state
tracking and reporting for the `enable` command. tracking and reporting for the `enable` command.
Please see `script-enable-api` for more details.