diff --git a/docs/source/reference/lua-scripting/engine_handlers.rst b/docs/source/reference/lua-scripting/engine_handlers.rst index 10ed3ee555..6ef9846d2e 100644 --- a/docs/source/reference/lua-scripting/engine_handlers.rst +++ b/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 `_ 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`. diff --git a/docs/source/reference/lua-scripting/openmw_menu.rst b/docs/source/reference/lua-scripting/openmw_menu.rst new file mode 100644 index 0000000000..587e4337e0 --- /dev/null +++ b/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 diff --git a/docs/source/reference/lua-scripting/overview.rst b/docs/source/reference/lua-scripting/overview.rst index 5515351e20..ec5ab7338c 100644 --- a/docs/source/reference/lua-scripting/overview.rst +++ b/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 ` 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 `) +There are a few methods for sending events: + +- `core.sendGlovalEvent `_ to send events to global scripts +- `GameObject:sendEvent `_ to send events to local scripts attached to a game object +- `types.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. diff --git a/files/lua_api/CMakeLists.txt b/files/lua_api/CMakeLists.txt index 96409e803e..06c90e4633 100644 --- a/files/lua_api/CMakeLists.txt +++ b/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}) diff --git a/files/lua_api/openmw/menu.lua b/files/lua_api/openmw/menu.lua new file mode 100644 index 0000000000..c1a1a65a62 --- /dev/null +++ b/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 diff --git a/files/lua_api/openmw/types.lua b/files/lua_api/openmw/types.lua index a350d4dbea..6abb209b2c 100644 --- a/files/lua_api/openmw/types.lua +++ b/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