AnarchistGamers/openmw
1
0
Fork 0
mirror of https://gitlab.com/OpenMW/openmw.git synced 2025-08-03 15:27:13 -04:00
Code Issues Packages Projects Releases Wiki Activity

docs - begin restructing docs

Browse Source
This commit is contained in:
Cody Glassman 2025-06-16 15:36:43 -07:00
parent e7305e7c97
commit 302d92561d
57 changed files with 732 additions and 485 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
apps/openmw/mwlua/README.md
View File

@ -3,7 +3,7 @@
This folder contains the C++ implementation of the Lua scripting system.
For user-facing documentation, see
[OpenMW Lua scripting](https://openmw.readthedocs.io/en/latest/reference/lua-scripting/index.html).
[Lua scripting](https://openmw.readthedocs.io/en/latest/reference/lua-scripting/index.html).
The documentation is generated from
[/docs/source/reference/lua-scripting](/docs/source/reference/lua-scripting).
You can find instructions for generating the documentation at the

3
docs/requirements.txt
View File

@ -3,3 +3,6 @@ sphinx==7.1.2
docutils==0.18.1
jinja2==3.1.6
sphinx_rtd_theme==3.0.1
sphinx-design==0.6.1
furo==2024.8.6
sphinx-copybutton==0.5.2

60
docs/source/_static/luadoc.css
View File

@ -1,10 +1,9 @@
#luadoc tt { font-family: monospace; }
#luadoc p,
/* #luadoc p,
#luadoc td,
#luadoc th { font-size: .95em; line-height: 1.2em;}
#luadoc p,
#luadoc ul
{ margin: 10px 0 0 10px;}
@ -109,5 +108,60 @@
#luadoc dl,
#luadoc dd {margin: 0px; line-height: 1.2em;}
#luadoc li {list-style: bullet;}
#luadoc li {list-style: bullet;} */
#luadoc pre.example {
background-color: #eeffcc;
border: 1px solid #e1e4e5;
padding: 10px;
margin: 10px 0 10px 0;
overflow-x: auto;
}
#luadoc pre.example code {
color: var(--color-content-foreground);
background-color: #eeffcc;
border: none;
white-space: pre;
padding: 0px;
}
#luadoc code {
/* background-color: inherit;
color: inherit;
border: none; */
font-family: monospace;
}
body[data-theme="dark"] #luadoc pre.example {
background-color: #eeffcc;
}
@media (prefers-color-scheme: dark) {
body:not([data-theme="light"]) #luadoc pre.example {
background-color: #eeffcc;
}
}
#luadoc a:not(:link) {
font-weight: bold;
color: var(--color-content-foreground);
text-decoration: none;
cursor: inherit;
}
#luadoc p em { font-family: 'monospace';}
#luadoc a:link { font-weight: bold; color: var(--color-link);; text-decoration: none; }
#luadoc a:visited { font-weight: bold; color: var(--color-link--hover); text-decoration: none; }
#luadoc a:link:hover { text-decoration: underline; }
.context-wrapper {
display: flex;
gap: 4px;
}
table.docutils {
width: 100%;
}

11
docs/source/_static/theme.css Normal file
View File

@ -0,0 +1,11 @@
.content {
width: 60em;
}
a.next-page, a.prev-page {
color: var(--color-link);
}
a.next-page:hover, a.prev-page:hover {
text-decoration: underline;
}

29
docs/source/conf.py
View File

@ -37,6 +37,8 @@ extensions = [
'sphinx.ext.coverage',
'sphinx.ext.viewcode',
'sphinx.ext.autosectionlabel',
'sphinx_design',
'sphinx_copybutton',
]
#autosectionlabel_prefix_document = True
@ -91,7 +93,14 @@ except Exception as ex:
rst_prolog = f"""
.. |luaApiRevision| replace:: {luaApiRevision}
.. |luaApiRevisionBadge| replace:: :bdg-link-info-line:`API v{luaApiRevision} <openmw_core.html##(core).API_REVISION>`
.. |ppApiRevision| replace:: {ppApiRevision}
.. |bdg-ctx-menu| replace:: :bdg-warning:`menu`
.. |bdg-ctx-global| replace:: :bdg-danger:`global`
.. |bdg-ctx-player| replace:: :bdg-secondary:`local:player`
.. |bdg-ctx-local| replace:: :bdg-info:`local`
.. |bdg-ctx-all| replace:: :bdg-danger:`global` :bdg-warning:`menu` :bdg-info:`local`
"""
# The language for content autogenerated by Sphinx. Refer to documentation
@ -138,7 +147,7 @@ primary_domain = 'c'
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'sphinx_rtd_theme'
html_theme = 'furo'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
@ -146,14 +155,20 @@ html_theme = 'sphinx_rtd_theme'
html_theme_options = {
'navigation_with_keys': True,
'flyout_display': 'attached',
'sidebar_hide_name': False,
'top_of_page_buttons': [],
}
html_css_files = [
"theme.css",
"luadoc.css",
"figures.css"
]
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
def setup(app):
app.add_css_file('figures.css')
app.add_css_file('luadoc.css')
try:
subprocess.call(['bash', project_root + '/docs/source/generate_luadoc.sh'])
except Exception as e:
@ -161,19 +176,19 @@ def setup(app):
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
html_title = 'OpenMW'
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = 'OpenMW Documentation'
# html_short_title = 'OpenMW Documentation'
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = 'https://gitlab.com/OpenMW/openmw-docs/raw/master/docs/source/_static/images/openmw.png'
html_logo = 'https://gitlab.com/OpenMW/openmw-docs/raw/master/docs/source/_static/images/openmw.png'
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = 'https://gitlab.com/OpenMW/openmw-docs/raw/master/docs/source/_static/images/favicon.png'
html_favicon = 'https://gitlab.com/OpenMW/openmw-docs/raw/master/docs/source/_static/images/favicon.png'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,

36
docs/source/reference/lua-scripting/ai/combat.rst Normal file
View File

@ -0,0 +1,36 @@
Combat
======
.. include:: ../version.rst
Attack another actor.
**Arguments**
.. list-table::
:header-rows: 1
:widths: 20 20 60
* - name
- type
- description
* - type
- string [required]
- the name of the package (see packages listed below)
* - cancelOther
- boolean [default=true]
- whether to cancel all other AI packages
* - target
- `GameObject <../openmw_core.html##(GameObject)>`_ [required]
- the actor to attack
**Examples**
.. code-block:: Lua
-- from local script add package to self
local AI = require('openmw.interfaces').AI
AI.startPackage({type='Combat', target=anotherActor})
-- via event to any actor
actor:sendEvent('StartAIPackage', {type='Combat', target=anotherActor})

49
docs/source/reference/lua-scripting/ai/escort.rst Normal file
View File

@ -0,0 +1,49 @@
Escort
======
.. include:: ../version.rst
Escort another actor to the given location.
**Arguments**
.. list-table::
:header-rows: 1
:widths: 20 20 60
* - name
- type
- description
* - type
- string [required]
- the name of the package (see packages listed below)
* - cancelOther
- boolean [default=true]
- whether to cancel all other AI packages
* - target
- `GameObject <../openmw_core.html##(GameObject)>`_ [required]
- the actor to follow
* - destPosition
- `3d vector <../openmw_util.html##(Vector3)>`_ [required]
- the destination point
* - destCell
- Cell [optional]
- the destination cell
* - duration
- number [optional]
- duration in game time (will be rounded up to the next hour)
* - isRepeat
- boolean [optional]
- Will the package repeat (true or false)
**Example**
.. code-block:: Lua
actor:sendEvent('StartAIPackage', {
type = 'Escort',
target = object.self,
destPosition = util.vector3(x, y, z),
duration = 3 * time.hour,
isRepeat = true
})

37
docs/source/reference/lua-scripting/ai/follow.rst Normal file
View File

@ -0,0 +1,37 @@
Follow
======
.. include:: ../version.rst
Follow another actor.
**Arguments**
.. list-table::
:header-rows: 1
:widths: 20 20 60
* - name
- type
- description
* - type
- string [required]
- the name of the package (see packages listed below)
* - cancelOther
- boolean [default=true]
- whether to cancel all other AI packages
* - target
- `GameObject <../openmw_core.html##(GameObject)>`_ [required]
- the actor to follow
* - destCell
- Cell [optional]
- the destination cell
* - duration
- number [optional]
- duration in game time (will be rounded up to the next hour)
* - destPosition
- `3d vector <../openmw_util.html##(Vector3)>`_ [optional]
- the destination point
* - isRepeat
- boolean [optional]
- Will the package repeat (true or false)

25
docs/source/reference/lua-scripting/ai/pursue.rst Normal file
View File

@ -0,0 +1,25 @@
Pursue
======
.. include:: ../version.rst
Pursue another actor.
**Arguments**
.. list-table::
:header-rows: 1
:widths: 20 20 60
* - name
- type
- description
* - type
- string [required]
- the name of the package (see packages listed below)
* - cancelOther
- boolean [default=true]
- whether to cancel all other AI packages
* - target
- `GameObject <../openmw_core.html##(GameObject)>`_ [required]
- the actor to pursue

28
docs/source/reference/lua-scripting/ai/travel.rst Normal file
View File

@ -0,0 +1,28 @@
Travel
======
.. include:: ../version.rst
Go to given location.
**Arguments**
.. list-table::
:header-rows: 1
:widths: 20 20 60
* - name
- type
- description
* - type
- string [required]
- the name of the package (see packages listed below)
* - cancelOther
- boolean [default=true]
- whether to cancel all other AI packages
* - destPosition
- `3d vector <../openmw_util.html##(Vector3)>`_ [required]
- the point to travel to
* - isRepeat
- boolean [optional]
- Will the package repeat (true or false)

53
docs/source/reference/lua-scripting/ai/wander.rst Normal file
View File

@ -0,0 +1,53 @@
Wander
======
.. include:: ../version.rst
Wander nearby current position.
**Arguments**
.. list-table::
:header-rows: 1
:widths: 20 20 60
* - name
- type
- description
* - type
- string [required]
- the name of the package (see packages listed below)
* - distance
- float [default=0]
- the actor to follow
* - duration
- number [optional]
- duration in game time (will be rounded up to the next hour)
* - idle
- table [optional]
- Idle chance values, up to 8
* - isRepeat
- boolean [optional]
- Will the package repeat (true or false)
**Example**
.. code-block:: Lua
local idleTable = {
idle2 = 60,
idle3 = 50,
idle4 = 40,
idle5 = 30,
idle6 = 20,
idle7 = 10,
idle8 = 0,
idle9 = 25
}
actor:sendEvent('StartAIPackage', {
type = 'Wander',
distance = 5000,
duration = 5 * time.hour,
idle = idleTable,
isRepeat = true
})

225
docs/source/reference/lua-scripting/aipackages.rst
View File

@ -1,225 +0,0 @@
Built-in AI packages
====================
.. include:: version.rst
Starting an AI package
----------------------
There are two ways to start AI package:
.. code-block:: Lua
-- from local script add package to self
local AI = require('openmw.interfaces').AI
AI.startPackage(options)
-- via event to any actor
actor:sendEvent('StartAIPackage', options)
``options`` is Lua table with arguments of the AI package.
**Common arguments that can be used with any AI package**
.. list-table::
:header-rows: 1
:widths: 20 20 60
* - name
- type
- description
* - type
- string [required]
- the name of the package (see packages listed below)
* - cancelOther
- boolean [default=true]
- whether to cancel all other AI packages
Combat
------
Attack another actor.
**Arguments**
.. list-table::
:header-rows: 1
:widths: 20 20 60
* - name
- type
- description
* - target
- `GameObject <openmw_core.html##(GameObject)>`_ [required]
- the actor to attack
**Examples**
.. code-block:: Lua
-- from local script add package to self
local AI = require('openmw.interfaces').AI
AI.startPackage({type='Combat', target=anotherActor})
-- via event to any actor
actor:sendEvent('StartAIPackage', {type='Combat', target=anotherActor})
Pursue
------
Pursue another actor.
**Arguments**
.. list-table::
:header-rows: 1
:widths: 20 20 60
* - name
- type
- description
* - target
- `GameObject <openmw_core.html##(GameObject)>`_ [required]
- the actor to pursue
Follow
------
Follow another actor.
**Arguments**
.. list-table::
:header-rows: 1
:widths: 20 20 60
* - name
- type
- description
* - target
- `GameObject <openmw_core.html##(GameObject)>`_ [required]
- the actor to follow
* - destCell
- Cell [optional]
- the destination cell
* - duration
- number [optional]
- duration in game time (will be rounded up to the next hour)
* - destPosition
- `3d vector <openmw_util.html##(Vector3)>`_ [optional]
- the destination point
* - isRepeat
- boolean [optional]
- Will the package repeat (true or false)
Escort
------
Escort another actor to the given location.
**Arguments**
.. list-table::
:header-rows: 1
:widths: 20 20 60
* - name
- type
- description
* - target
- `GameObject <openmw_core.html##(GameObject)>`_ [required]
- the actor to follow
* - destPosition
- `3d vector <openmw_util.html##(Vector3)>`_ [required]
- the destination point
* - destCell
- Cell [optional]
- the destination cell
* - duration
- number [optional]
- duration in game time (will be rounded up to the next hour)
* - isRepeat
- boolean [optional]
- Will the package repeat (true or false)
**Example**
.. code-block:: Lua
actor:sendEvent('StartAIPackage', {
type = 'Escort',
target = object.self,
destPosition = util.vector3(x, y, z),
duration = 3 * time.hour,
isRepeat = true
})
Wander
------
Wander nearby current position.
**Arguments**
.. list-table::
:header-rows: 1
:widths: 20 20 60
* - name
- type
- description
* - distance
- float [default=0]
- the actor to follow
* - duration
- number [optional]
- duration in game time (will be rounded up to the next hour)
* - idle
- table [optional]
- Idle chance values, up to 8
* - isRepeat
- boolean [optional]
- Will the package repeat (true or false)
**Example**
.. code-block:: Lua
local idleTable = {
idle2 = 60,
idle3 = 50,
idle4 = 40,
idle5 = 30,
idle6 = 20,
idle7 = 10,
idle8 = 0,
idle9 = 25
}
actor:sendEvent('StartAIPackage', {
type = 'Wander',
distance = 5000,
duration = 5 * time.hour,
idle = idleTable,
isRepeat = true
})
Travel
------
Go to given location.
**Arguments**
.. list-table::
:header-rows: 1
:widths: 20 20 60
* - name
- type
- description
* - destPosition
- `3d vector <openmw_util.html##(Vector3)>`_ [required]
- the point to travel to
* - isRepeat
- boolean [optional]
- Will the package repeat (true or false)

55
docs/source/reference/lua-scripting/api.rst
View File

@ -7,54 +7,15 @@ Lua API reference
.. toctree::
:hidden:
engine_handlers
user_interface
aipackages
index_packages
index_auxpackages
index_aipackages
index_interfaces
UI <user_interface>
setting_renderers
Engine Handlers <engine_handlers>
events
openmw_ambient
openmw_animation
openmw_async
openmw_camera
openmw_core
openmw_debug
openmw_input
openmw_markup
openmw_menu
openmw_nearby
openmw_postprocessing
openmw_self
openmw_storage
openmw_types
openmw_ui
openmw_util
openmw_vfs
openmw_world
openmw_aux_calendar
openmw_aux_time
openmw_aux_ui
openmw_aux_util
interface_activation
interface_ai
interface_animation
interface_camera
interface_controls
interface_gamepadcontrols
interface_item_usage
interface_mwui
interface_settings
interface_skill_progression
interface_ui
interface_crimes
iterables
- :ref:`Engine handlers reference`
- :ref:`User interface reference <User interface reference>`
- `Game object reference <openmw_core.html##(GameObject)>`_
- `Cell reference <openmw_core.html##(Cell)>`_
- :ref:`Built-in AI packages`
- :ref:`Built-in events`
Iterables <iterables>
**API packages**
@ -66,7 +27,7 @@ Player scripts are local scripts that are attached to a player.
.. include:: tables/packages.rst
**openmw_aux**
**Auxiliary packages**
``openmw_aux.*`` are built-in libraries that are itself implemented in Lua. They can not do anything that is not possible with the basic API, they only make it more convenient.
Sources can be found in ``resources/vfs/openmw_aux``. In theory mods can override them, but it is not recommended.

14
docs/source/reference/lua-scripting/engine_handlers.rst
View File

@ -7,6 +7,8 @@ Engine handler is a function defined by a script, that can be called by the engi
**Can be defined by any script**
|bdg-ctx-all|
.. list-table::
:widths: 20 80
@ -16,6 +18,8 @@ Engine handler is a function defined by a script, that can be called by the engi
**Can be defined by any non-menu script**
|bdg-ctx-global| |bdg-ctx-local|
.. list-table::
:widths: 20 80
@ -39,6 +43,8 @@ Engine handler is a function defined by a script, that can be called by the engi
**Only for global scripts**
|bdg-ctx-global|
.. list-table::
:widths: 20 80
@ -61,6 +67,8 @@ Engine handler is a function defined by a script, that can be called by the engi
**Only for local scripts**
|bdg-ctx-local|
.. list-table::
:widths: 20 80
@ -86,6 +94,8 @@ Engine handler is a function defined by a script, that can be called by the engi
**Only menu scripts and local scripts attached to a player**
|bdg-ctx-menu| |bdg-ctx-player|
.. list-table::
:widths: 20 80
@ -140,6 +150,8 @@ Engine handler is a function defined by a script, that can be called by the engi
**Only for local scripts attached to a player**
|bdg-ctx-player|
.. list-table::
:widths: 20 80
@ -152,6 +164,8 @@ Engine handler is a function defined by a script, that can be called by the engi
**Only for menu scripts**
|bdg-ctx-menu|
.. list-table::
:widths: 20 80

4
docs/source/reference/lua-scripting/events.rst
View File

@ -1,5 +1,5 @@
Built-in events
===============
Events
======
.. include:: version.rst

6
docs/source/reference/lua-scripting/index.rst
View File

@ -1,6 +1,6 @@
####################
OpenMW Lua scripting
####################
#############
Lua scripting
#############
.. note::
OpenMW Lua is not compatible with MWSE.

24
docs/source/reference/lua-scripting/index_aipackages.rst Normal file
View File

@ -0,0 +1,24 @@
AI packages
============
.. include:: version.rst
.. toctree::
:hidden:
:glob:
ai/*
Starting an AI package
----------------------
There are two ways to start AI package:
.. code-block:: Lua
-- from local script add package to self
local AI = require('openmw.interfaces').AI
AI.startPackage(options)
-- via event to any actor
actor:sendEvent('StartAIPackage', options)

21
docs/source/reference/lua-scripting/index_auxpackages.rst Normal file
View File

@ -0,0 +1,21 @@
##################
Auxiliary Packages
##################
.. include:: version.rst
.. toctree::
:hidden:
aux_calendar <openmw_aux_calendar>
aux_time <openmw_aux_time>
aux_ui <openmw_aux_ui>
aux_util <openmw_aux_util>
**Auxiliary packages**
``openmw_aux.*`` are built-in libraries that are itself implemented in Lua. They can not do anything that is not possible with the basic API, they only make it more convenient.
Sources can be found in ``resources/vfs/openmw_aux``. In theory mods can override them, but it is not recommended.
.. include:: tables/aux_packages.rst

25
docs/source/reference/lua-scripting/index_interfaces.rst Normal file
View File

@ -0,0 +1,25 @@
##########
Interfaces
##########
.. include:: version.rst
.. toctree::
:hidden:
activation <interface_activation>
ai <interface_ai>
animation <interface_animation>
camera <interface_camera>
controls <interface_controls>
gamepadcontrols <interface_gamepadcontrols>
item_usage <interface_item_usage>
mwui <interface_mwui>
settings <interface_settings>
skill_progression <interface_skill_progression>
ui <interface_ui>
crimes <interface_crimes>
**Interfaces of built-in scripts**
.. include:: tables/interfaces.rst

37
docs/source/reference/lua-scripting/index_packages.rst Normal file
View File

@ -0,0 +1,37 @@
########
Packages
########
.. include:: version.rst
.. toctree::
:hidden:
ambient <openmw_ambient>
animation <openmw_animation>
async <openmw_async>
camera <openmw_camera>
core <openmw_core>
debug <openmw_debug>
input <openmw_input>
markup <openmw_markup>
menu <openmw_menu>
nearby <openmw_nearby>
postprocessing <openmw_postprocessing>
self <openmw_self>
storage <openmw_storage>
types <openmw_types>
ui <openmw_ui>
util <openmw_util>
vfs <openmw_vfs>
world <openmw_world>
**API packages**
API packages provide functions that can be called by scripts. I.e. it is a script-to-engine interaction.
A package can be loaded with ``require('<package name>')``.
It can not be overloaded even if there is a lua file with the same name.
The list of available packages is different for global and for local scripts.
Player scripts are local scripts that are attached to a player.
.. include:: tables/packages.rst

8
docs/source/reference/lua-scripting/overview.rst
View File

@ -384,8 +384,8 @@ Player scripts are local scripts that are attached to a player.
.. include:: tables/packages.rst
openmw_aux
----------
Auxiliary packages
------------------
``openmw_aux.*`` are built-in libraries that are themselves implemented in Lua. They can not do anything that is not possible with the basic API, they only make it more convenient.
Sources can be found in ``resources/vfs/openmw_aux``. In theory mods can override them, but it is not recommended.
@ -544,7 +544,7 @@ The protection mod attaches an additional local script to every actor. The scrip
In order to be able to intercept the event, the protection script should be placed in the load order below the original script.
See :ref:`the list of events <Built-in events>` that are used by built-in scripts.
See :ref:`the list of events <Events>` that are used by built-in scripts.
Timers
@ -618,7 +618,7 @@ An example:
}
}
Also in `openmw_aux`_ is the helper function ``runRepeatedly``, it is implemented on top of unsavable timers:
Also in `Auxiliary packages`_ is the helper function ``runRepeatedly``, it is implemented on top of unsavable timers:
.. code-block:: Lua

4
docs/source/reference/lua-scripting/setting_renderers.rst
View File

@ -1,5 +1,5 @@
Built-in Setting Renderers
==========================
Setting Renderers
=================
.. include:: version.rst

31
docs/source/reference/lua-scripting/tables/aux_packages.rst
View File

@ -1,12 +1,19 @@
+---------------------------------------------------------+--------------------+---------------------------------------------------------------+
| Built-in library | Can be used | Description |
+=========================================================+====================+===============================================================+
|:ref:`openmw_aux.calendar <Package openmw_aux.calendar>` | everywhere | | Game time calendar |
+---------------------------------------------------------+--------------------+---------------------------------------------------------------+
|:ref:`openmw_aux.util <Package openmw_aux.util>` | everywhere | | Miscellaneous utils |
+---------------------------------------------------------+--------------------+---------------------------------------------------------------+
|:ref:`openmw_aux.time <Package openmw_aux.time>` | everywhere | | Timers and game time utils |
+---------------------------------------------------------+--------------------+---------------------------------------------------------------+
|:ref:`openmw_aux.ui <Package openmw_aux.ui>` | by player and menu | | User interface utils |
| | scripts | |
+---------------------------------------------------------+--------------------+---------------------------------------------------------------+
.. list-table::
:widths: 30 40 60
:header-rows: 1
* - Module
- Context
- Description
* - :doc:`calendar </reference/lua-scripting/openmw_aux_calendar>`
- |bdg-ctx-all|
- Game time calendar
* - :doc:`util </reference/lua-scripting/openmw_aux_util>`
- |bdg-ctx-all|
- Miscellaneous utils
* - :doc:`time </reference/lua-scripting/openmw_aux_time>`
- |bdg-ctx-all|
- Timers and game time utils
* - :doc:`ui </reference/lua-scripting/openmw_aux_ui>`
- |bdg-ctx-menu| |bdg-ctx-player|
- User interface utils

79
docs/source/reference/lua-scripting/tables/interfaces.rst
View File

@ -1,48 +1,43 @@
.. list-table::
:widths: 20 20 60
:widths: 30 40 60
:header-rows: 1
* - Interface
- Can be used
- Context
- Description
* - :ref:`Activation <Interface Activation>`
- by global scripts
* - :doc:`Activation </reference/lua-scripting/interface_activation>`
- |bdg-ctx-global|
- Allows to extend or override built-in activation mechanics.
* - :ref:`AI <Interface AI>`
- by local scripts
- Control basic AI of NPCs and creatures.
* - :ref:`AnimationController <Interface AnimationController>`
- by local scripts
- Control animations 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:`Controls <Interface Controls>`
- by player scripts
- | Allows to alter behavior of the built-in script
| that handles player controls.
* - :ref:`GamepadControls <Interface GamepadControls>`
- by player scripts
- | Allows to alter behavior of the built-in script
| that handles player gamepad controls.
* - :ref:`ItemUsage <Interface ItemUsage>`
- by global scripts
- | Allows to extend or override built-in item usage
| mechanics.
* - :ref:`SkillProgression <Interface SkillProgression>`
- by local scripts
- | Control, extend, and override skill progression of the
| player.
* - :ref:`Settings <Interface Settings>`
- by player, menu, and global scripts
- Save, display and track changes of setting values.
* - :ref:`MWUI <Interface MWUI>`
- by player and menu scripts
- Morrowind-style UI templates.
* - :ref:`UI <Interface UI>`
- by player scripts
- | High-level UI modes interface. Allows to override parts
| of the interface.
* - :ref:`Crimes <Interface Crimes>`
- by global scripts
* - :doc:`ItemUsage </reference/lua-scripting/interface_item_usage>`
- |bdg-ctx-global|
- Allows to extend or override built-in item usage mechanics.
* - :doc:`Crimes </reference/lua-scripting/interface_crimes>`
- |bdg-ctx-global|
- Commit crimes.
* - :doc:`AI </reference/lua-scripting/interface_ai>`
- |bdg-ctx-local|
- Control basic AI of NPCs and creatures.
* - :doc:`AnimationController </reference/lua-scripting/interface_animation>`
- |bdg-ctx-local|
- Control animations of NPCs and creatures.
* - :doc:`SkillProgression </reference/lua-scripting/interface_skill_progression>`
- |bdg-ctx-local|
- Control, extend, and override skill progression of the player.
* - :doc:`Camera </reference/lua-scripting/interface_camera>`
- |bdg-ctx-player|
- Allows to alter behavior of the built-in camera script without overriding the script completely.
* - :doc:`Controls </reference/lua-scripting/interface_controls>`
- |bdg-ctx-player|
- Allows to alter behavior of the built-in script that handles player controls.
* - :doc:`GamepadControls </reference/lua-scripting/interface_gamepadcontrols>`
- |bdg-ctx-player|
- Allows to alter behavior of the built-in script that handles player gamepad controls.
* - :doc:`UI </reference/lua-scripting/interface_ui>`
- |bdg-ctx-player|
- High-level UI modes interface. Allows to override parts of the interface.
* - :doc:`Settings </reference/lua-scripting/interface_settings>`
- |bdg-ctx-global| |bdg-ctx-menu| |bdg-ctx-player|
- Save, display and track changes of setting values.
* - :doc:`MWUI </reference/lua-scripting/interface_mwui>`
- |bdg-ctx-menu| |bdg-ctx-player|
- Morrowind-style UI templates.

113
docs/source/reference/lua-scripting/tables/packages.rst
View File

@ -1,49 +1,64 @@
+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
| Package | Can be used | Description |
+============================================================+====================+===============================================================+
|:ref:`openmw.ambient <Package openmw.ambient>` | by player and menu | | Controls background sounds for given player. |
| | scripts | |
+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
|:ref:`openmw.animation <Package openmw.animation>` | by local and | | Animation controls |
| | player scripts | |
+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
|:ref:`openmw.async <Package openmw.async>` | everywhere | | Timers and callbacks. |
+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
|:ref:`openmw.camera <Package openmw.camera>` | by player scripts | | Controls camera. |
+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
|:ref:`openmw.core <Package openmw.core>` | everywhere | | Functions that are common for both global and local scripts |
+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
|:ref:`openmw.debug <Package openmw.debug>` | by player scripts | | Collection of debug utils. |
+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
|:ref:`openmw.input <Package openmw.input>` | by player and menu | | User input. |
| | scripts | |
+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
|:ref:`openmw.interfaces <Script interfaces>` | everywhere | | Public interfaces of other scripts. |
+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
|:ref:`openmw.markup <Package openmw.markup>` | everywhere | | API to work with markup languages. |
+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
|:ref:`openmw.menu <Package openmw.menu>` | by menu scripts | | Main menu functionality, such as managing game saves |
+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
|:ref:`openmw.nearby <Package openmw.nearby>` | by local and | | Read-only access to the nearest area of the game world. |
| | player scripts | |
+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
|:ref:`openmw.postprocessing <Package openmw.postprocessing>`| by player scripts | | Controls post-process shaders. |
+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
|:ref:`openmw.self <Package openmw.self>` | by local and | | Full access to the object the script is attached to. |
| | player scripts | |
+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
|:ref:`openmw.storage <Package openmw.storage>` | everywhere | | Storage API. In particular can be used to store data |
| | | | between game sessions. |
+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
|:ref:`openmw.types <Package openmw.types>` | everywhere | | Functions for specific types of game objects. |
+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
|:ref:`openmw.ui <Package openmw.ui>` | by player and menu | | Controls :ref:`user interface <User interface reference>`. |
| | scripts | |
+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
|:ref:`openmw.util <Package openmw.util>` | everywhere | | Defines utility functions and classes like 3D vectors, |
| | | | that don't depend on the game world. |
+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
|:ref:`openmw.vfs <Package openmw.vfs>` | everywhere | | Read-only access to data directories via VFS. |
+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
|:ref:`openmw.world <Package openmw.world>` | by global scripts | | Read-write access to the game world. |
+------------------------------------------------------------+--------------------+---------------------------------------------------------------+
.. list-table::
:widths: 30 40 60
:header-rows: 1
* - Package
- Context
- Description
* - :doc:`core </reference/lua-scripting/openmw_core>`
- |bdg-ctx-all|
- Functions that are common for both global and local scripts
* - :doc:`async </reference/lua-scripting/openmw_async>`
- |bdg-ctx-all|
- Timers and callbacks.
* - :ref:`interfaces <Script interfaces>`
- |bdg-ctx-all|
- Public interfaces of other scripts.
* - :doc:`markup </reference/lua-scripting/openmw_markup>`
- |bdg-ctx-all|
- API to work with markup languages.
* - :doc:`storage </reference/lua-scripting/openmw_storage>`
- |bdg-ctx-all|
- Storage API. In particular can be used to store data between game sessions.
* - :doc:`types </reference/lua-scripting/openmw_types>`
- |bdg-ctx-all|
- Functions for specific types of game objects.
* - :doc:`util </reference/lua-scripting/openmw_util>`
- |bdg-ctx-all|
- Defines utility functions and classes like 3D vectors, that don't depend on the game world.
* - :doc:`vfs </reference/lua-scripting/openmw_vfs>`
- |bdg-ctx-all|
- Read-only access to data directories via VFS.
* - :doc:`world </reference/lua-scripting/openmw_world>`
- |bdg-ctx-global|
- Read-write access to the game world.
* - :doc:`menu </reference/lua-scripting/openmw_menu>`
- |bdg-ctx-menu|
- Main menu functionality, such as managing game saves
* - :doc:`animation </reference/lua-scripting/openmw_animation>`
- |bdg-ctx-local|
- Animation controls
* - :doc:`nearby </reference/lua-scripting/openmw_nearby>`
- |bdg-ctx-local|
- Read-only access to the nearest area of the game world.
* - :doc:`self </reference/lua-scripting/openmw_self>`
- |bdg-ctx-local|
- Full access to the object the script is attached to.
* - :doc:`camera </reference/lua-scripting/openmw_camera>`
- |bdg-ctx-player|
- Controls camera.
* - :doc:`debug </reference/lua-scripting/openmw_debug>`
- |bdg-ctx-player|
- Collection of debug utils.
* - :doc:`postprocessing </reference/lua-scripting/openmw_postprocessing>`
- |bdg-ctx-player|
- Controls post-process shaders.
* - :doc:`ambient </reference/lua-scripting/openmw_ambient>`
- |bdg-ctx-menu| |bdg-ctx-player|
- Controls background sounds for given player.
* - :doc:`input </reference/lua-scripting/openmw_input>`
- |bdg-ctx-menu| |bdg-ctx-player|
- User input.
* - :doc:`ui </reference/lua-scripting/openmw_ui>`
- |bdg-ctx-menu| |bdg-ctx-player|
- Controls :ref:`user interface <UI reference>`.

96
docs/source/reference/lua-scripting/user_interface.rst
View File

@ -1,5 +1,5 @@
User interface reference
========================
UI reference
============
.. include:: version.rst
@ -73,63 +73,65 @@ Events
an event-specific value, and that widget's layout table.
| See the Widget type pages for information on what events exist, and which first argument they pass.
Widget types
------------
.. toctree::
:maxdepth: 1
:hidden:
Widget: Base widget type, all the other widgets inherit its properties and events. <widgets/widget>
Text: Displays text. <widgets/text>
TextEdit: Accepts text input from the user. <widgets/textedit>
Image: Renders a texture. <widgets/image>
Flex: Aligns children in a column/row <widgets/flex>
Container: Wraps around its children <widgets/container>
Widget <widgets/widget>
Text <widgets/text>
TextEdit <widgets/textedit>
Image <widgets/image>
Flex <widgets/flex>
Container <widgets/container>
Example
-------
*scripts/clock.lua*
.. tab-set::
.. code-block:: Lua
.. tab-item:: scripts/clock.lua
local ui = require('openmw.ui')
local util = require('openmw.util')
local calendar = require('openmw_aux.calendar')
local time = require('openmw_aux.time')
.. code-block:: lua
local element = ui.create {
-- important not to forget the layer
-- by default widgets are not attached to any layer and are not visible
layer = 'HUD',
type = ui.TYPE.Text,
props = {
-- position in the top right corner
relativePosition = util.vector2(1, 0),
-- position is for the top left corner of the widget by default
-- change it to align exactly to the top right corner of the screen
anchor = util.vector2(1, 0),
text = calendar.formatGameTime('%H:%M'),
textSize = 24,
-- default black text color isn't always visible
textColor = util.color.rgb(0, 1, 0),
},
}
local ui = require('openmw.ui')
local util = require('openmw.util')
local calendar = require('openmw_aux.calendar')
local time = require('openmw_aux.time')
local function updateTime()
-- formatGameTime uses current time by default
-- otherwise we could get it by calling `core.getGameTime()`
element.layout.props.text = calendar.formatGameTime('%H:%M')
-- the layout changes won't affect the widget unless we request an update
element:update()
end
local element = ui.create {
-- important not to forget the layer
-- by default widgets are not attached to any layer and are not visible
layer = 'HUD',
type = ui.TYPE.Text,
props = {
-- position in the top right corner
relativePosition = util.vector2(1, 0),
-- position is for the top left corner of the widget by default
-- change it to align exactly to the top right corner of the screen
anchor = util.vector2(1, 0),
text = calendar.formatGameTime('%H:%M'),
textSize = 24,
-- default black text color isn't always visible
textColor = util.color.rgb(0, 1, 0),
},
}
-- we are showing game time in hours and minutes
-- so no need to update more often than once a game minute
time.runRepeatedly(updateTime, 1 * time.minute, { type = time.GameTime })
local function updateTime()
-- formatGameTime uses current time by default
-- otherwise we could get it by calling `core.getGameTime()`
element.layout.props.text = calendar.formatGameTime('%H:%M')
-- the layout changes won't affect the widget unless we request an update
element:update()
end
*clock.omwscripts*
-- we are showing game time in hours and minutes
-- so no need to update more often than once a game minute
time.runRepeatedly(updateTime, 1 * time.minute, { type = time.GameTime })
::
PLAYER: scripts/clock.lua
.. tab-item:: clock.omwscripts
.. code-block::
PLAYER: scripts/clock.lua

3
docs/source/reference/lua-scripting/version.rst
View File

@ -1,2 +1 @@
| `OpenMW version:` |version|
| `core.API_REVISION:` |luaApiRevision| `* <openmw_core.html##(core).API_REVISION>`_
| |luaApiRevisionBadge|

45
docs/source/reference/lua-scripting/widgets/container.rst
View File

@ -5,4 +5,47 @@ Wraps around its children. Convenient for creating border-type templates.
Relative size and position don't work for children.
For template children, relative size and position depend on the children's combined size.
For template children, relative size and position depend on the children's combined size.
Properties
----------
.. list-table::
:header-rows: 1
:widths: 20 20 60
* - name
- type (default value)
- description
* - position
- util.vector2 (0, 0)
- | Offsets the position of the widget from its parent's
| top-left corner in pixels.
* - size
- util.vector2 (0, 0)
- Increases the widget's size in pixels.
* - relativePosition
- util.vector2 (0, 0)
- | Offsets the position of the widget from its parent's
| top-left corner as a fraction of the parent's size.
* - relativeSize
- util.vector2 (0, 0)
- Increases the widget's size by a fraction of its parent's size.
* - anchor
- util.vector2 (0, 0)
- | Offsets the widget's position by a fraction of its size.
| Useful for centering or aligning to a corner.
* - visible
- boolean (true)
- Defines if the widget is visible
* - propagateEvents
- boolean (true)
- Allows base widget events to propagate to the widget's parent.
* - alpha
- number (1.0)
- | Set the opacity of the widget and its contents.
| If `inheritAlpha` is set to `true`, this becomes the maximum alpha value the widget can take.
* - inheritAlpha
- boolean (true)
- | Modulate `alpha` with parents `alpha`.
| If the parent has `inheritAlpha` set to `true`, the value after modulating is passed to the child.

2
docs/source/reference/lua-scripting/widgets/image.rst
View File

@ -1,6 +1,8 @@
Image Widget
============
Renders a texture.
Properties
----------

2
docs/source/reference/lua-scripting/widgets/text.rst
View File

@ -1,6 +1,8 @@
Text Widget
===========
Displays text.
Properties
----------

2
docs/source/reference/lua-scripting/widgets/textedit.rst
View File

@ -1,6 +1,8 @@
TextEdit Widget
===============
Accepts text input from the user.
Properties
----------

2
docs/source/reference/lua-scripting/widgets/widget.rst
View File

@ -1,6 +1,8 @@
Widget
======
Base widget type, all the other widgets inherit its properties and events.
Properties
----------

2
docs/source/reference/modding/extended.rst
View File

@ -338,7 +338,7 @@ Also groundcover detection should be enabled via settings.cfg:
Lua scripting
-------------
OpenMW supports Lua scripts. See :ref:`Lua scripting documentation <OpenMW Lua scripting>`.
OpenMW supports Lua scripts. See :ref:`Lua scripting documentation <Lua scripting>`.
It is not compatible with MWSE. A mod with Lua scripts will work only if it was developed specifically for OpenMW.
Installation of a Lua mod is the same as of any other mod: add ``data=`` and ``content=`` entries to ``openmw.cfg``.

4
docs/source/reference/modding/index.rst
View File

@ -1,5 +1,5 @@
OpenMW Modding Reference
########################
Modding Reference
#################
The following document is the complete reference guide to modifying, or
modding, your OpenMW setup. It does not cover content creation itself,

6
docs/source/reference/modding/texture-modding/index.rst
View File

@ -1,6 +1,6 @@
######################
OpenMW Texture Modding
######################
###############
Texture Modding
###############
Although texture modding requires external tools not supported by the OpenMW team,
adding and modifying textures is an important part of content creation.

6
docs/source/reference/postprocessing/index.rst
View File

@ -1,6 +1,6 @@
######################
OpenMW Post Processing
######################
###############
Post Processing
###############
.. toctree::
:caption: Table of Contents

2
files/data/scripts/omw/ai.lua
View File

@ -87,7 +87,7 @@ return {
--- Start new AI package.
-- @function [parent=#AI] startPackage
-- @param #table options See the "Built-in AI packages" page.
-- @param #table options See the "AI packages" page.
startPackage = startPackage,
--- Iterate over all packages starting from the active one and remove those where `filterCallback` returns false.

2
files/data/scripts/omw/settings/player.lua
View File

@ -33,7 +33,7 @@ end
-- @field #string name A key from the localization context
-- @field #string description A key from the localization context (optional, can be `nil`)
-- @field default A default value
-- @field #string renderer A renderer key (see the "Built-in Setting Renderers" page)
-- @field #string renderer A renderer key (see the "Setting Renderers" page)
-- @field argument An argument for the renderer
return {

4
files/lua_api/openmw/ambient.lua
View File

@ -1,6 +1,6 @@
---
-- `openmw.ambient` controls background 2D sounds specific to a given player.
-- Can be used only by menu scripts and local scripts that are attached to a player.
-- Controls background 2D sounds specific to a given player.
-- @context menu|player
-- @module ambient
-- @usage local ambient = require('openmw.ambient')

3
files/lua_api/openmw/animation.lua
View File

@ -1,7 +1,8 @@
---
-- `openmw.animation` defines functions that allow control of character animations.
-- Defines functions that allow control of character animations.
-- Note that for some methods, such as @{openmw.animation#playBlended} you should use the associated methods on the
-- [AnimationController](interface_animation.html) interface rather than invoking this API directly.
-- @context local
-- @module animation
-- @usage local anim = require('openmw.animation')

3
files/lua_api/openmw/async.lua
View File

@ -1,6 +1,7 @@
---
-- `openmw.async` contains timers and coroutine utilities. All functions require
-- Contains timers and coroutine utilities. All functions require
-- the package itself as a first argument.
-- @context global|menu|local|player
-- @module async
-- @usage local async = require('openmw.async')

4
files/lua_api/openmw/camera.lua
View File

@ -1,6 +1,6 @@
---
-- `openmw.camera` controls camera.
-- Can be used only by player scripts.
-- Controls camera.
-- @context player
-- @module camera
-- @usage local camera = require('openmw.camera')

4
files/lua_api/openmw/core.lua
View File

@ -1,6 +1,6 @@
---
-- `openmw.core` defines functions and types that are available in local,
-- global and menu scripts.
-- Defines functions and types that are available in local, global and menu scripts.
-- @context global|menu|local|player
-- @module core
-- @usage local core = require('openmw.core')

4
files/lua_api/openmw/debug.lua
View File

@ -1,6 +1,6 @@
---
-- `openmw.debug` is an interface to the engine debug utils.
-- Can be used only by local scripts, that are attached to a player.
-- Provides an interface to the engine debug utils.
-- @context player
-- @module Debug
-- @usage local debug = require('openmw.debug')

2
files/lua_api/openmw/input.lua
View File

@ -1,9 +1,9 @@
---
-- `openmw.input` can be used only in menu scripts and scripts attached to a player.
-- Most mods should prefer to use the actions/triggers API over the direct input device methods.
-- Actions have one value on each frame (resolved just before the `onFrame` engine handler),
-- while Triggers don't have a value, but can occur multiple times on each frame.
-- Prefer to use built-in methods of binding actions, such as the [inputBinding setting renderer](setting_renderers.html#inputbinding)
-- @context menu|player
-- @module input
-- @usage local input = require('openmw.input')
-- -- Example of Action usage

1
files/lua_api/openmw/interfaces.lua
View File

@ -1,4 +1,5 @@
---
-- @context global|menu|local|player
-- @module interfaces
-- @usage local I = require('openmw.interfaces')

3
files/lua_api/openmw/markup.lua
View File

@ -1,5 +1,6 @@
---
-- `openmw.markup` allows to work with markup languages.
-- Allows to work with markup languages.
-- @context global|menu|local|player
-- @module markup
-- @usage local markup = require('openmw.markup')

3
files/lua_api/openmw/menu.lua
View File

@ -1,5 +1,6 @@
---
-- `openmw.menu` can be used only in menu scripts.
-- Provides interfaces to interact with menu elements.
-- @context menu
-- @module menu
-- @usage local menu = require('openmw.menu')

4
files/lua_api/openmw/nearby.lua
View File

@ -1,6 +1,6 @@
---
-- `openmw.nearby` provides read-only access to the nearest area of the game world.
-- Can be used only from local scripts.
-- Provides read-only access to the nearest area of the game world.
-- @context local
-- @module nearby
-- @usage local nearby = require('openmw.nearby')

4
files/lua_api/openmw/postprocessing.lua
View File

@ -1,6 +1,6 @@
---
-- `openmw.postprocessing` is an interface to postprocessing shaders.
-- Can be used only by local scripts, that are attached to a player.
-- Provides an interface to postprocessing shaders.
-- @context player
-- @module postprocessing
-- @usage local postprocessing = require('openmw.postprocessing')

5
files/lua_api/openmw/self.lua
View File

@ -1,6 +1,7 @@
---
-- `openmw.self` provides full access to the object the script is attached to.
-- Can be used only from local scripts. All fields and function of `GameObject` are also available for `openmw.self`.
-- Provides full access to the object the script is attached to.
-- All fields and function of `GameObject` are also available for `openmw.self`.
-- @context local
-- @module Self
-- @extends openmw.core#GameObject
-- @usage local self = require('openmw.self')

3
files/lua_api/openmw/storage.lua
View File

@ -1,5 +1,6 @@
---
-- `openmw.storage` contains functions to work with permanent Lua storage.
-- Contains functions to work with permanent Lua storage.
-- @context global|menu|local|player
-- @module storage
-- @usage
-- local storage = require('openmw.storage')

3
files/lua_api/openmw/types.lua
View File

@ -1,5 +1,6 @@
---
-- `openmw.types` defines functions for specific types of game objects.
-- Defines functions for specific types of game objects.
-- @context global|menu|local|player
-- @module types
-- @usage local types = require('openmw.types')

4
files/lua_api/openmw/ui.lua
View File

@ -1,6 +1,6 @@
---
-- `openmw.ui` controls user interface.
-- Can be used only by menu scripts and local scripts, that are attached to a player.
-- Controls user interface.
-- @context menu|player
-- @module ui
-- @usage
-- local ui = require('openmw.ui')

3
files/lua_api/openmw/util.lua
View File

@ -1,5 +1,6 @@
---
-- `openmw.util` defines utility functions and classes like 3D vectors, that don't depend on the game world.
-- Defines utility functions and classes like 3D vectors, that don't depend on the game world.
-- @context global|menu|local|player
-- @module util
-- @usage local util = require('openmw.util')

3
files/lua_api/openmw/vfs.lua
View File

@ -1,6 +1,7 @@
---
-- `openmw.vfs` provides read-only access to data directories via VFS.
-- Provides read-only access to data directories via VFS.
-- Interface is very similar to "io" library.
-- @context global|menu|local|player
-- @module vfs
-- @usage local vfs = require('openmw.vfs')

4
files/lua_api/openmw/world.lua
View File

@ -1,6 +1,6 @@
---
-- `openmw.world` is an interface to the game world for global scripts.
-- Can not be used from local scripts.
-- Provides an interface to the game world for global scripts.
-- @context global
-- @module world
-- @usage local world = require('openmw.world')