Document menu scripts

docs/source/reference/lua-scripting/engine_handlers.rst

@@ -127,3 +127,14 @@ Engine handler is a function defined by a script, that can be called by the engi
     - | User entered `command` in in-game console. Called if either
       | `mode` is not default or `command` starts with prefix `lua`.
 
+**Only for menu scripts**
+
+.. list-table::
+  :widths: 20 80
+  * - onStateChanged()
+    - | Called whenever the current game changes
+      | (i. e. the result of `getState <openmw_menu.html##(getState)>`_ changes)
+  * - | onConsoleCommand(
+      |     mode, command, selectedObject)
+    - | User entered `command` in in-game console. Called if either
+      | `mode` is not default or `command` starts with prefix `lua`.

docs/source/reference/lua-scripting/openmw_menu.rst

@@ -0,0 +1,7 @@
+Package openmw.menu
+======================
+
+.. include:: version.rst
+
+.. raw:: html
+   :file: generated_html/openmw_ambient.html

docs/source/reference/lua-scripting/overview.rst

@@ -70,6 +70,9 @@ Cell
 Global scripts
     Lua scripts that are not attached to any game object and are always active. Global scripts can not be started or stopped during a game session. Lists of global scripts are defined by `omwscripts` files, which should be :ref:`registered <Lua scripting>` in `openmw.cfg`.
 
+Menu scripts
+    Lua scripts that are ran regardless of a game being loaded. They can be used to add features to the main menu and manage save files. 
+
 Local scripts
     Lua scripts that are attached to some game object. A local script is active only if the object it is attached to is in an active cell. There are no limitations to the number of local scripts on one object. Local scripts can be attached to (or detached from) any object at any moment by a global script. In some cases inactive local scripts still can run code (for example during saving and loading), but while inactive they can not see nearby objects.
 
@@ -173,6 +176,7 @@ The order of lines determines the script load order (i.e. script priorities).
 Possible flags are:
 
 - ``GLOBAL`` - a global script; always active, can not be stopped;
+- ``MENU`` - a menu script; always active, even before a game is loaded
 - ``CUSTOM`` - dynamic local script that can be started or stopped by a global script;
 - ``PLAYER`` - an auto started player script;
 - ``ACTIVATOR`` - a local script that will be automatically attached to any activator;
@@ -474,6 +478,12 @@ This is another kind of script-to-script interactions. The differences:
 - Event handlers can not return any data to the sender.
 - Event handlers have a single argument `eventData` (must be :ref:`serializable <Serializable data>`)
 
+There are a few methods for sending events:
+
+- `core.sendGlovalEvent <openmw_core.html##(sendGlovalEvent)>`_ to send events to global scripts
+- `GameObject:sendEvent <openmw_core.html##(GameObject).sendEvent>`_ to send events to local scripts attached to a game object
+- `types.Player.sendMenuEvent <openmw_menu.html##(Player).sendMenuEvent>`_ to send events to menu scripts of the given player
+
 Events are the main way of interacting between local and global scripts.
 They are not recommended for interactions between two global scripts, because in this case interfaces are more convenient.
 

files/lua_api/CMakeLists.txt

@@ -21,6 +21,7 @@ set(LUA_API_FILES
     openmw/util.lua
     openmw/vfs.lua
     openmw/world.lua
+    openmw/menu.lua
 )
 
 foreach (f ${LUA_API_FILES})

files/lua_api/openmw/menu.lua

@@ -0,0 +1,65 @@
+---
+-- `openmw.menu` can be used only in menu scripts.
+-- @module menu
+-- @usage local menu = require('openmw.menu')
+
+---
+-- @type STATE
+-- @field [parent=#STATE] NoGame
+-- @field [parent=#STATE] Running
+-- @field [parent=#STATE] Ended
+
+
+---
+-- Current game state
+-- @function [parent=#menu] getState
+-- @return #STATE
+
+---
+-- Start a new game
+-- @function [parent=#menu] newGame
+
+---
+-- Load the game from a save slot
+-- @function [parent=#menu] loadGame
+-- @param #string directory name of the save directory (e. g. character)
+-- @param #string slotName name of the save slot
+
+---
+-- Delete a saved game
+-- @function [parent=#menu] deleteGame
+-- @param #string directory name of the save directory (e. g. character)
+-- @param #string slotName name of the save slot
+
+---
+-- Current save directory
+-- @function [parent=#menu] getCurrentSaveDir
+-- @return #string
+
+---
+-- Save the game
+-- @function [parent=#menu] saveGame
+-- @param #string description human readable description of the save
+-- @param #string slotName name of the save slot
+
+---
+-- @type SaveInfo
+-- @field #string description
+-- @field #string playerName
+-- @field #string playerLevel
+-- @field #list<#string> contentFiles
+
+---
+-- List of all saves for the given directory
+-- @function [parent=#menu] getSaves
+-- @param #string directory name of the save directory (e. g. character)
+-- @return #list<#SaveInfo>
+
+---
+-- List of all available saves
+-- @function [parent=#menu] getAllSaves
+-- @return #list<#SaveInfo>
+
+---
+-- Exit the game
+-- @function [parent=#menu] quit

files/lua_api/openmw/types.lua

@@ -1035,6 +1035,12 @@
 -- Values that can be used with getControlSwitch/setControlSwitch.
 -- @field [parent=#Player] #CONTROL_SWITCH CONTROL_SWITCH
 
+---
+-- Send an event to menu scripts.
+-- @function [parent=#core] sendMenuEvent
+-- @param openmw.core#GameObject player
+-- @param #string eventName
+-- @param eventData
 
 --------------------------------------------------------------------------------
 -- @{#Armor} functions