From d0ab562b1fb22490799f42f3f90b61f01b593bab Mon Sep 17 00:00:00 2001 From: wm4 Date: Wed, 5 Aug 2020 22:58:19 +0200 Subject: lua: make hook processing more flexible This can now opt to not continue a hook after the hook callback returns. This makes it easier for scripts, and may make it unnecessary to run reentrant event loops etc. for scripts that want to wait before continuing while still running the event loop. --- DOCS/man/lua.rst | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) (limited to 'DOCS/man') diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst index 88fb4cb7ce..3fdb0b2f42 100644 --- a/DOCS/man/lua.rst +++ b/DOCS/man/lua.rst @@ -889,8 +889,22 @@ guarantee a stable interface. their result (normally, the Lua scripting interface is asynchronous from the point of view of the player core). ``priority`` is an arbitrary integer that allows ordering among hooks of the same kind. Using the value 50 is - recommended as neutral default value. ``fn`` is the function that will be - called during execution of the hook. + recommended as neutral default value. + + ``fn(hook)`` is the function that will be called during execution of the + hook. The parameter passed to it (``hook``) is a Lua object that can control + further aspects about the currently invoked hook. It provides the following + methods: + + ``defer()`` + Returning from the hook function should not automatically continue + the hook. Instead, the API user wants to call ``hook:cont()`` on its + own at a later point in time (before or after the function has + returned). + + ``cont()`` + Continue the hook. Doesn't need to be called unless ``defer()`` was + called. See `Hooks`_ for currently existing hooks and what they do - only the hook list is interesting; handling hook execution is done by the Lua script -- cgit v1.2.3