diff --git a/docs/source/conf.py b/docs/source/conf.py index 0b953a4275..cf6fb5fc4c 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -106,7 +106,9 @@ rst_prolog = f""" .. |bdg-ctx-global| replace:: :bdg-danger:`global` .. |bdg-ctx-player| replace:: :bdg-secondary:`player` .. |bdg-ctx-local| replace:: :bdg-info:`local` -.. |bdg-ctx-all| replace:: :bdg-danger:`global` :bdg-warning:`menu` :bdg-info:`local` +.. |bdg-ctx-load| replace:: :bdg-black:`load` +.. |bdg-ctx-non-load| replace:: :bdg-danger:`global` :bdg-warning:`menu` :bdg-info:`local` +.. |bdg-ctx-all| replace:: :bdg-danger:`global` :bdg-warning:`menu` :bdg-info:`local` :bdg-black:`load` """ # The language for content autogenerated by Sphinx. Refer to documentation diff --git a/docs/source/reference/lua-scripting/engine_handlers.rst b/docs/source/reference/lua-scripting/engine_handlers.rst index cc1e45403f..cb304dff93 100644 --- a/docs/source/reference/lua-scripting/engine_handlers.rst +++ b/docs/source/reference/lua-scripting/engine_handlers.rst @@ -172,3 +172,13 @@ Engine handler is a function defined by a script, that can be called by the engi * - onStateChanged() - | Called whenever the current game changes | (i. e. the result of `getState `_ changes) + +**Only for load scripts** + +|bdg-ctx-load| + +.. list-table:: + :widths: 20 80 + + * - onContentFilesLoaded() + - | Called after all content files have been parsed, but before the main menu. diff --git a/docs/source/reference/lua-scripting/index_packages.rst b/docs/source/reference/lua-scripting/index_packages.rst index 53a836519f..d73865e7db 100644 --- a/docs/source/reference/lua-scripting/index_packages.rst +++ b/docs/source/reference/lua-scripting/index_packages.rst @@ -11,6 +11,7 @@ Packages animation async camera + content core debug input diff --git a/docs/source/reference/lua-scripting/openmw_content.rst b/docs/source/reference/lua-scripting/openmw_content.rst new file mode 100644 index 0000000000..c904999b06 --- /dev/null +++ b/docs/source/reference/lua-scripting/openmw_content.rst @@ -0,0 +1,7 @@ +Package openmw.content +=================== + +.. include:: version.rst + +.. raw:: html + :file: generated_html/openmw_content.html diff --git a/docs/source/reference/lua-scripting/overview.rst b/docs/source/reference/lua-scripting/overview.rst index ae166f647a..e0bf0a9314 100644 --- a/docs/source/reference/lua-scripting/overview.rst +++ b/docs/source/reference/lua-scripting/overview.rst @@ -181,6 +181,7 @@ Possible flags are: - ``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; +- ``LOAD`` - a load script, active while content files are being loaded; - ``ACTIVATOR`` - a local script that will be automatically attached to any activator; - ``ARMOR`` - a local script that will be automatically attached to any armor; - ``BOOK`` - a local script that will be automatically attached to any book; @@ -207,6 +208,7 @@ Hot reloading It is possible to modify a script without restarting OpenMW. To apply changes, open the in-game console and run the command: ``reloadlua``. This will restart all Lua scripts using the `onSave and onLoad`_ handlers the same way as if the game was saved or loaded. It reloads all ``.omwscripts`` files and ``.lua`` files that are not packed to any archives. ``.omwaddon`` files and scripts packed to BSA can not be changed without restarting the game. +Load scripts will not run again until the game is restarted. Lua console =========== diff --git a/docs/source/reference/lua-scripting/tables/aux_packages.rst b/docs/source/reference/lua-scripting/tables/aux_packages.rst index 202f5219c2..80b81eb76f 100644 --- a/docs/source/reference/lua-scripting/tables/aux_packages.rst +++ b/docs/source/reference/lua-scripting/tables/aux_packages.rst @@ -6,10 +6,10 @@ - Context - Description * - :doc:`calendar ` - - |bdg-ctx-all| + - |bdg-ctx-non-load| - Game time calendar * - :doc:`time ` - - |bdg-ctx-all| + - |bdg-ctx-non-load| - Timers and game time utils * - :doc:`ui ` - |bdg-ctx-menu| |bdg-ctx-player| diff --git a/docs/source/reference/lua-scripting/tables/packages.rst b/docs/source/reference/lua-scripting/tables/packages.rst index 2485f2c0cd..ef1ab81499 100644 --- a/docs/source/reference/lua-scripting/tables/packages.rst +++ b/docs/source/reference/lua-scripting/tables/packages.rst @@ -10,13 +10,16 @@ - Controls background sounds for given player. * - :doc:`animation ` - |bdg-ctx-local| - - Animation controls + - Animation controls. * - :doc:`async ` - |bdg-ctx-all| - Timers and callbacks. * - :doc:`camera ` - |bdg-ctx-player| - Controls camera. + * - :doc:`content ` + - |bdg-ctx-load| + - Content manipulation. * - :doc:`core ` - |bdg-ctx-all| - Functions that are common for both global and local scripts @@ -48,7 +51,7 @@ - |bdg-ctx-all| - Storage API. In particular can be used to store data between game sessions. * - :doc:`types ` - - |bdg-ctx-all| + - |bdg-ctx-non-load| - Functions for specific types of game objects. * - :doc:`ui ` - |bdg-ctx-menu| |bdg-ctx-player| diff --git a/files/lua_api/CMakeLists.txt b/files/lua_api/CMakeLists.txt index 526ee90955..2327e89de1 100644 --- a/files/lua_api/CMakeLists.txt +++ b/files/lua_api/CMakeLists.txt @@ -13,6 +13,7 @@ set(LUA_API_FILES openmw/animation.lua openmw/async.lua openmw/camera.lua + openmw/content.lua openmw/core.lua openmw/debug.lua openmw/input.lua diff --git a/files/lua_api/openmw/async.lua b/files/lua_api/openmw/async.lua index c32c748f15..a8435c5d38 100644 --- a/files/lua_api/openmw/async.lua +++ b/files/lua_api/openmw/async.lua @@ -1,7 +1,7 @@ --- -- Contains timers and coroutine utilities. All functions require -- the package itself as a first argument. --- @context global|menu|local|player +-- @context global|menu|local|player|load -- @module async -- @usage local async = require('openmw.async') diff --git a/files/lua_api/openmw/content.lua b/files/lua_api/openmw/content.lua new file mode 100644 index 0000000000..5eb7ec9408 --- /dev/null +++ b/files/lua_api/openmw/content.lua @@ -0,0 +1,23 @@ +--- +-- Allows for manipulation of the data loaded from content files while the game is first started. +-- @context load +-- @module content +-- @usage local content = require('openmw.content') + +--- @{#GlobalContent}: Global variable manipulation. +-- @field [parent=#content] #GlobalContent globals + +--- +-- A mutable list of all global mwscript variables. +-- @field [parent=#GlobalContent] #map<#string, #number> records +-- @usage +-- content.globals.records.MyVariable = 42 + +--- @{#StaticContent}: Static manipulation. +-- @field [parent=#content] #StaticContent statics + +--- +-- A mutable list of all #{openmw.types#StaticRecord}s. +-- @field [parent=#GlobalContent] #list records +-- @usage +-- content.statics.records.MyStatic = { model = 'meshes/b/B_N_Wood Elf_M_Head_02.nif' } diff --git a/files/lua_api/openmw/core.lua b/files/lua_api/openmw/core.lua index 8f9487d139..c50a88a2bf 100644 --- a/files/lua_api/openmw/core.lua +++ b/files/lua_api/openmw/core.lua @@ -1,6 +1,6 @@ --- --- Defines functions and types that are available in local, global and menu scripts. --- @context global|menu|local|player +-- Defines functions and types that are available in local, global, menu, and load scripts. +-- @context global|menu|local|player|load -- @module core -- @usage local core = require('openmw.core') @@ -11,53 +11,53 @@ -- @field [parent=#core] #number API_REVISION --- --- Terminates the game and quits to the OS. Should be used only for testing purposes. +-- Terminates the game and quits to the OS. Should be used only for testing purposes. Not available in load scripts. -- @function [parent=#core] quit --- --- Send an event to global scripts. Note: in menu scripts, errors if the game is not running (check @{openmw.menu#menu.getState}) +-- Send an event to global scripts. Note: in menu scripts, errors if the game is not running (check @{openmw.menu#menu.getState}.) Not available in load scripts. -- @function [parent=#core] sendGlobalEvent -- @param #string eventName -- @param eventData --- -- Simulation time in seconds. --- The number of simulation seconds passed in the game world since starting a new game. +-- The number of simulation seconds passed in the game world since starting a new game. Not available in load scripts. -- @function [parent=#core] getSimulationTime -- @return #number --- --- The scale of simulation time relative to real time. +-- The scale of simulation time relative to real time. Not available in load scripts. -- @function [parent=#core] getSimulationTimeScale -- @return #number --- --- Game time in seconds. +-- Game time in seconds. Not available in load scripts. -- @function [parent=#core] getGameTime -- @return #number --- --- The scale of game time relative to simulation time. +-- The scale of game time relative to simulation time. Not available in load scripts. -- @function [parent=#core] getGameTimeScale -- @return #number --- --- Whether the world is paused. +-- Whether the world is paused. Not available in load scripts. -- @function [parent=#core] isWorldPaused -- @return #boolean --- --- Real time in seconds; starting point is not fixed (can be time since last reboot), use only for measuring intervals. For Unix time use `os.time()`. +-- Real time in seconds; starting point is not fixed (can be time since last reboot), use only for measuring intervals. For Unix time use `os.time()`. Not available in load scripts. -- @function [parent=#core] getRealTime -- @return #number --- --- Frame duration in seconds. Not available in global scripts. +-- Frame duration in seconds. Not available in global or load scripts. -- @function [parent=#core] getRealFrameDuration -- @return #number --- --- Get a game setting with given name (from GMST ESM records or from openmw.cfg). +-- Get a game setting with given name (from GMST ESM records or from openmw.cfg). Not available in load scripts. -- @function [parent=#core] getGMST -- @param #string setting Setting name -- @return #any @@ -478,7 +478,7 @@ -- @usage for _, item in ipairs(inventory:findAll('common_shirt_01')) do ... end ---- @{#Land}: Functions for interacting with land data +--- @{#Land}: Functions for interacting with land data. Not available in load scripts. -- @field [parent=#core] #Land land --- @@ -500,7 +500,7 @@ -- @return #nil, #string Plugin name or nil if failed to retrieve the texture ---- @{#Magic}: spells and spell effects +--- @{#Magic}: spells and spell effects. Not available in load scripts. -- @field [parent=#core] #Magic magic @@ -783,7 +783,7 @@ -- @field #number magnitudeBase -- @field #number magnitudeModifier ---- @{#Sound}: Sounds and Speech +--- @{#Sound}: Sounds and Speech. Not available in load scripts. -- @field [parent=#core] #Sound sound --- @@ -915,7 +915,7 @@ -- print(sound.fileName) -- end ---- @{#Stats}: stats +--- @{#Stats}: stats. Not available in load scripts. -- @field [parent=#core] #Stats stats @@ -978,7 +978,7 @@ -- @field #string failureSound VFS path to the failure sound -- @field #string hitSound VFS path to the hit sound ---- @{#Dialogue}: Dialogue +--- @{#Dialogue}: Dialogue. Not available in load scripts. -- @field [parent=#core] #Dialogue dialogue --- @@ -1283,7 +1283,7 @@ -- @field #number NotLocal A comparison to the speaker's @{#DialogueInfoCondition.variableName} local variable --- @{#Regions}: Regions --- @field [parent=#core] #Regions regions +-- @field [parent=#core] #Regions regions. Not available in load scripts. --- -- A read-only list of all @{#RegionRecord}s in the world database. @@ -1311,7 +1311,7 @@ -- @field #number chance Multiplicative percentage used to determine whether to play the sound --- @{#Factions}: Factions --- @field [parent=#core] #Factions factions +-- @field [parent=#core] #Factions factions. Not available in load scripts. --- -- A read-only list of all @{#FactionRecord}s in the world database. @@ -1341,7 +1341,7 @@ -- @field #number factionReaction (DEPRECATED) Returns the same as factionReputation. --- @{#MWScripts}: MWScripts --- @field [parent=#core] #MWScript mwscripts +-- @field [parent=#core] #MWScript mwscripts. Not available in load scripts. --- -- A read-only list of all @{#MWScriptRecord}s in the world database. @@ -1357,7 +1357,7 @@ --- @{#Weather}: Weather --- @field [parent=#core] #Weather weather +-- @field [parent=#core] #Weather weather. Not available in load scripts. --- List of all @{#WeatherRecord}s. -- @field [parent=#Weather] #list<#WeatherRecord> records A read-only list of all @{#WeatherRecord}s in the world database, may be indexed by recordId. diff --git a/files/lua_api/openmw/markup.lua b/files/lua_api/openmw/markup.lua index c610962126..ee940e5699 100644 --- a/files/lua_api/openmw/markup.lua +++ b/files/lua_api/openmw/markup.lua @@ -1,6 +1,6 @@ --- -- Allows to work with markup languages. --- @context global|menu|local|player +-- @context global|menu|local|player|load -- @module markup -- @usage local markup = require('openmw.markup') diff --git a/files/lua_api/openmw/storage.lua b/files/lua_api/openmw/storage.lua index 3805ad2dcc..fb46d733a5 100644 --- a/files/lua_api/openmw/storage.lua +++ b/files/lua_api/openmw/storage.lua @@ -1,6 +1,6 @@ --- -- Contains functions to work with permanent Lua storage. --- @context global|menu|local|player +-- @context global|menu|local|player|load -- @module storage -- @usage -- local storage = require('openmw.storage') diff --git a/files/lua_api/openmw/util.lua b/files/lua_api/openmw/util.lua index f04b24843d..50b7e97741 100644 --- a/files/lua_api/openmw/util.lua +++ b/files/lua_api/openmw/util.lua @@ -1,6 +1,6 @@ --- -- Defines utility functions and classes like 3D vectors, that don't depend on the game world. --- @context global|menu|local|player +-- @context global|menu|local|player|load -- @module util -- @usage local util = require('openmw.util') diff --git a/files/lua_api/openmw/vfs.lua b/files/lua_api/openmw/vfs.lua index f57305d4ab..017f798574 100644 --- a/files/lua_api/openmw/vfs.lua +++ b/files/lua_api/openmw/vfs.lua @@ -1,7 +1,7 @@ --- -- Provides read-only access to data directories via VFS. -- Interface is very similar to "io" library. --- @context global|menu|local|player +-- @context global|menu|local|player|load -- @module vfs -- @usage local vfs = require('openmw.vfs')