From cd3535cd63f074941e4c1772eb531f8bc3f1b99b Mon Sep 17 00:00:00 2001
From: uramer <antonuramer@gmail.com>
Date: Sun, 1 May 2022 16:57:33 +0200
Subject: [PATCH] Document Settings interface, add scripts to CMakeLists
---
docs/source/generate_luadoc.sh | 1 +
docs/source/reference/lua-scripting/api.rst | 24 ++--
.../lua-scripting/interface_settings.rst | 6 +
.../reference/lua-scripting/overview.rst | 23 ++--
files/builtin_scripts/CMakeLists.txt | 4 +
.../scripts/omw/settings/common.lua | 9 +-
.../scripts/omw/settings/player.lua | 125 ++++++++++++++++++
7 files changed, 171 insertions(+), 21 deletions(-)
create mode 100644 docs/source/reference/lua-scripting/interface_settings.rst
diff --git a/docs/source/generate_luadoc.sh b/docs/source/generate_luadoc.sh
index 5376aa0ab9..d6bbbe3634 100755
--- a/docs/source/generate_luadoc.sh
+++ b/docs/source/generate_luadoc.sh
@@ -68,3 +68,4 @@ $DOCUMENTOR_PATH -f doc -d $OUTPUT_DIR openmw_aux/*lua
$DOCUMENTOR_PATH -f doc -d $OUTPUT_DIR scripts/omw/ai.lua
$DOCUMENTOR_PATH -f doc -d $OUTPUT_DIR scripts/omw/camera.lua
$DOCUMENTOR_PATH -f doc -d $OUTPUT_DIR scripts/omw/mwui/init.lua
+$DOCUMENTOR_PATH -f doc -d $OUTPUT_DIR scripts/omw/settings/player.lua
diff --git a/docs/source/reference/lua-scripting/api.rst b/docs/source/reference/lua-scripting/api.rst
index 110771fbcf..a6009edf1a 100644
--- a/docs/source/reference/lua-scripting/api.rst
+++ b/docs/source/reference/lua-scripting/api.rst
@@ -27,6 +27,7 @@ Lua API reference
interface_ai
interface_camera
interface_mwui
+ interface_settings
iterables
@@ -94,12 +95,19 @@ Sources can be found in ``resources/vfs/openmw_aux``. In theory mods can overrid
**Interfaces of built-in scripts**
-+---------------------------------------------------------+--------------------+---------------------------------------------------------------+
-| Interface | Can be used | Description |
-+=========================================================+====================+===============================================================+
-|:ref:`AI <Interface AI>` | by local scripts | | Control basic AI of NPCs and creatures. |
-+---------------------------------------------------------+--------------------+---------------------------------------------------------------+
-|:ref:`Camera <Interface Camera>` | by player scripts | | Allows to alter behavior of the built-in camera script |
-| | | | without overriding the script completely. |
-+---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+.. list-table::
+ :widths: 20 20 60
+ * - Interface
+ - Can be used
+ - Description
+ * - :ref:`AI <Interface AI>`
+ - by local scripts
+ - Control basic AI of NPCs and creatures.
+ * - :ref:`Camera <Interface Camera>`
+ - by player scripts
+ - | Allows to alter behavior of the built-in camera script
+ | without overriding the script completely.
+ * - :ref:`Settings <Interface Settings>`
+ - by player and global scripts
+ - Save, display and track changes of setting values.
diff --git a/docs/source/reference/lua-scripting/interface_settings.rst b/docs/source/reference/lua-scripting/interface_settings.rst
new file mode 100644
index 0000000000..cd1994ccfa
--- /dev/null
+++ b/docs/source/reference/lua-scripting/interface_settings.rst
@@ -0,0 +1,6 @@
+Interface Settings
+==================
+
+.. raw:: html
+ :file: generated_html/scripts_omw_settings_player.html
+
diff --git a/docs/source/reference/lua-scripting/overview.rst b/docs/source/reference/lua-scripting/overview.rst
index 91c0a071e0..e21469a53f 100644
--- a/docs/source/reference/lua-scripting/overview.rst
+++ b/docs/source/reference/lua-scripting/overview.rst
@@ -460,15 +460,22 @@ The order in which the scripts are started is important. So if one mod should ov
**Interfaces of built-in scripts**
-+---------------------------------------------------------+--------------------+---------------------------------------------------------------+
-| Interface | Can be used | Description |
-+=========================================================+====================+===============================================================+
-|:ref:`AI <Interface AI>` | by local scripts | | Control basic AI of NPCs and creatures. |
-+---------------------------------------------------------+--------------------+---------------------------------------------------------------+
-|:ref:`Camera <Interface Camera>` | by player scripts | | Allows to alter behavior of the built-in camera script |
-| | | | without overriding the script completely. |
-+---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+.. list-table::
+ :widths: 20 20 60
+ * - Interface
+ - Can be used
+ - Description
+ * - :ref:`AI <Interface AI>`
+ - by local scripts
+ - Control basic AI of NPCs and creatures.
+ * - :ref:`Camera <Interface Camera>`
+ - by player scripts
+ - | Allows to alter behavior of the built-in camera script
+ | without overriding the script completely.
+ * - :ref:`Settings <Interface Settings>`
+ - by player and global scripts
+ - Save, display and track changes of setting values.
Event system
============
diff --git a/files/builtin_scripts/CMakeLists.txt b/files/builtin_scripts/CMakeLists.txt
index a3ba1f5149..318e389585 100644
--- a/files/builtin_scripts/CMakeLists.txt
+++ b/files/builtin_scripts/CMakeLists.txt
@@ -17,6 +17,10 @@ set(LUA_BUILTIN_FILES
scripts/omw/console/player.lua
scripts/omw/console/global.lua
scripts/omw/console/local.lua
+ scripts/omw/settings/player.lua
+ scripts/omw/settings/global.lua
+ scripts/omw/settings/common.lua
+ scripts/omw/settings/render.lua
l10n/Calendar/en.yaml
diff --git a/files/builtin_scripts/scripts/omw/settings/common.lua b/files/builtin_scripts/scripts/omw/settings/common.lua
index 51e22b4465..1e87dfd62b 100644
--- a/files/builtin_scripts/scripts/omw/settings/common.lua
+++ b/files/builtin_scripts/scripts/omw/settings/common.lua
@@ -12,8 +12,8 @@ local function validateSettingOptions(options)
if type(options.key) ~= 'string' then
error('Setting must have a key')
end
- if type(options.saveOnly) ~= 'boolean' then
- error('Setting must be save only or not')
+ if type(options.permanentStorage) ~= 'boolean' then
+ error('Setting must have a permanentStorage flag')
end
if type(options.renderer) ~= 'string' then
error('Setting must have a renderer')
@@ -63,7 +63,7 @@ end
local function registerSetting(options)
return {
key = options.key,
- saveOnly = options.saveOnly,
+ permanentStorage = options.permanentStorage,
default = options.default,
renderer = options.renderer,
argument = options.argument,
@@ -123,7 +123,7 @@ return {
local section = contextSection(groupKey)
saved[groupKey] = {}
for key, value in pairs(section:asTable()) do
- if group.settings[key].saveOnly then
+ if not group.settings[key].permanentStorage then
saved[groupKey][key] = value
end
end
@@ -132,5 +132,4 @@ return {
return saved
end,
registerGroup = registerGroup,
- validateGroupOptions = validateGroupOptions,
}
\ No newline at end of file
diff --git a/files/builtin_scripts/scripts/omw/settings/player.lua b/files/builtin_scripts/scripts/omw/settings/player.lua
index 434f7b69c5..612ba3ec7b 100644
--- a/files/builtin_scripts/scripts/omw/settings/player.lua
+++ b/files/builtin_scripts/scripts/omw/settings/player.lua
@@ -21,11 +21,136 @@ render.registerRenderer('text', function(value, set, arg)
}
end)
+---
+-- @type PageOptions
+-- @field #string key A unique key
+-- @field #string l10n A localization context (an argument of core.l10n)
+-- @field #string name A key from the localization context
+-- @field #string description A key from the localization context
+
+---
+-- @type GroupOptions
+-- @field #string key A unique key, starts with "Settings" by convention
+-- @field #string l10n A localization context (an argument of core.l10n)
+-- @field #string name A key from the localization context
+-- @field #string description A key from the localization context
+-- @field #string page Key of a page which will contain this group
+-- @field #number order Groups within the same page are sorted by this number, or their key for equal values.
+-- Defaults to 0.
+-- @field #list<#SettingOptions> settings A [iterables#List](iterables.html#List) of #SettingOptions
+
+---
+-- @type SettingOptions
+-- @field #string key A unique key
+-- @field #string name A key from the localization context
+-- @field #string description A key from the localization context
+-- @field default A default value
+-- @field #string renderer A renderer key
+-- @field argument An argument for the renderer
+-- @field #boolean permanentStorage Whether the setting should is stored in permanent storage, or in the save file
+
return {
interfaceName = 'Settings',
+ ---
+ -- @module Settings
+ -- @usage
+ -- -- In a player script
+ -- local storage = require('openmw.storage')
+ -- local I = require('openmw.interfaces')
+ -- I.Settings.registerGroup({
+ -- key = 'SettingsPlayerMyMod',
+ -- page = 'MyPage',
+ -- l10n = 'mymod',
+ -- name = 'modName',
+ -- description = 'modDescription',
+ -- settings = {
+ -- {
+ -- key = 'Greeting',
+ -- renderer = 'text',
+ -- name = 'greetingName',
+ -- description = 'greetingDescription',
+ -- default = 'Hello, world!',
+ -- argument = {
+ -- size = 200,
+ -- },
+ -- },
+ -- },
+ -- })
+ -- local playerSettings = storage.playerSection('SettingsPlayerMyMod')
+ -- -- access a setting page registered by a global script
+ -- local globalSettings = storage.globalSection('SettingsGlobalMyMod')
interface = {
+ ---
+ -- @field [parent=#Settings] #string version
+ version = 0,
+ ---
+ -- @function [parent=#Settings] registerPage Register a page to be displayed in the settings menu,
+ -- only available in player scripts
+ -- @param #PageOptions options
+ -- @usage
+ -- I.Settings.registerPage({
+ -- key = 'MyModName',
+ -- l10n = 'MyModName',
+ -- name = 'MyModName',
+ -- description = 'MyModDescription',
+ -- })---
registerPage = render.registerPage,
+ ---
+ -- @function [parent=#Settings] registerRenderer Register a renderer,
+ -- only avaialable in player scripts
+ -- @param #string key
+ -- @param #function renderer A renderer function, receives setting's value,
+ -- a function to change it and an argument from the setting options
+ -- @usage
+ -- I.Settings.registerRenderer('text', function(value, set, arg)
+ -- return {
+ -- type = ui.TYPE.TextEdit,
+ -- props = {
+ -- size = util.vector2(arg and arg.size or 150, 30),
+ -- text = value,
+ -- textColor = util.color.rgb(1, 1, 1),
+ -- textSize = 15,
+ -- textAlignV = ui.ALIGNMENT.End,
+ -- },
+ -- events = {
+ -- textChanged = async:callback(function(s) set(s) end),
+ -- },
+ -- }
+ -- end)
registerRenderer = render.registerRenderer,
+ ---
+ -- @function [parent=#Settings] registerGroup Register a group to be attached to a page,
+ -- available both in player and global scripts
+ -- @param #GroupOptions options
+ -- @usage
+ -- I.Settings.registerGroup {
+ -- key = 'SettingsTest',
+ -- page = 'test',
+ -- l10n = 'test',
+ -- name = 'Player',
+ -- description = 'Player settings group',
+ -- settings = {
+ -- {
+ -- key = 'Greeting',
+ -- saveOnly = true,
+ -- default = 'Hi',
+ -- renderer = 'text',
+ -- argument = {
+ -- size = 200,
+ -- },
+ -- name = 'Text Input',
+ -- description = 'Short text input',
+ -- },
+ -- {
+ -- key = 'Key',
+ -- saveOnly = false,
+ -- default = input.KEY.LeftAlt,
+ -- renderer = 'keybind',
+ -- name = 'Key',
+ -- description = 'Bind Key',
+ -- },
+ -- }
+ -- }
registerGroup = common.registerGroup,
},
engineHandlers = {