From 4eb5841c60afdb8a12602a93e2e68ffdec19bac4 Mon Sep 17 00:00:00 2001
From: Petr Mikheev <ptmikheev@gmail.com>
Date: Fri, 2 Apr 2021 19:42:19 +0200
Subject: [PATCH] Update OpenMW Lua documentation

---
 docs/source/conf.py                           |   2 +-
 docs/source/reference/lua-scripting/api.rst   | 455 ++----------------
 .../reference/lua-scripting/overview.rst      | 446 ++++++++++++++---
 files/CMakeLists.txt                          |   1 +
 files/lua_api/CMakeLists.txt                  |  21 +
 files/lua_api/README.md                       |  13 +
 files/lua_api/coroutine.doclua                |  71 +++
 files/lua_api/global.doclua                   | 269 +++++++++++
 files/lua_api/math.doclua                     | 200 ++++++++
 files/lua_api/openmw/README.md                |  14 +
 files/lua_api/openmw/async.lua                |  52 ++
 files/lua_api/openmw/core.lua                 | 328 +++++++++++++
 files/lua_api/openmw/generate_luadoc.sh       |   4 +
 files/lua_api/openmw/nearby.lua               |  36 ++
 files/lua_api/openmw/query.lua                | 116 +++++
 files/lua_api/openmw/self.lua                 |  68 +++
 files/lua_api/openmw/ui.lua                   |  15 +
 files/lua_api/openmw/util.lua                 | 150 ++++++
 files/lua_api/openmw/world.lua                |  34 ++
 files/lua_api/string.doclua                   | 231 +++++++++
 files/lua_api/table.doclua                    |  66 +++
 21 files changed, 2111 insertions(+), 481 deletions(-)
 create mode 100644 files/lua_api/CMakeLists.txt
 create mode 100644 files/lua_api/README.md
 create mode 100644 files/lua_api/coroutine.doclua
 create mode 100644 files/lua_api/global.doclua
 create mode 100644 files/lua_api/math.doclua
 create mode 100644 files/lua_api/openmw/README.md
 create mode 100644 files/lua_api/openmw/async.lua
 create mode 100644 files/lua_api/openmw/core.lua
 create mode 100755 files/lua_api/openmw/generate_luadoc.sh
 create mode 100644 files/lua_api/openmw/nearby.lua
 create mode 100644 files/lua_api/openmw/query.lua
 create mode 100644 files/lua_api/openmw/self.lua
 create mode 100644 files/lua_api/openmw/ui.lua
 create mode 100644 files/lua_api/openmw/util.lua
 create mode 100644 files/lua_api/openmw/world.lua
 create mode 100644 files/lua_api/string.doclua
 create mode 100644 files/lua_api/table.doclua

diff --git a/docs/source/conf.py b/docs/source/conf.py
index 7653b94edf..72bb17adbb 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -176,7 +176,7 @@ html_static_path = [
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
 # directly to the root of the documentation.
-#html_extra_path = []
+html_extra_path = ['generated-luadoc']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
diff --git a/docs/source/reference/lua-scripting/api.rst b/docs/source/reference/lua-scripting/api.rst
index a7b153c039..f98d4ef074 100644
--- a/docs/source/reference/lua-scripting/api.rst
+++ b/docs/source/reference/lua-scripting/api.rst
@@ -17,426 +17,69 @@ Engine handler is a function defined by a script, that can be called by the engi
 | onUpdate(dt)                     | | Called every frame if game not paused. `dt` is the time   |
 |                                  | | from the last update in seconds.                          |
 +----------------------------------+-------------------------------------------------------------+
-| onSave() -> data                 | Called when the game is saving.                             |
+| onSave() -> data                 | | Called when the game is saving. May be called in inactive |
+|                                  | | state, so it shouldn't use `openmw.nearby`.               |
 +----------------------------------+-------------------------------------------------------------+
-| onLoad(data)                     | Called on loading with the data previosly returned by onSave|
+| onLoad(data)                     | | Called on loading with the data previosly returned by     |
+|                                  | | onSave. During loading the object is always in inactive.  |
 +----------------------------------+-------------------------------------------------------------+
 | **Only for global scripts**                                                                    |
 +----------------------------------+-------------------------------------------------------------+
 | onNewGame()                      | New game is started                                         |
 +----------------------------------+-------------------------------------------------------------+
-| onPlayerAdded(player)            |Player added to game world. The argument is a `Game object`_.|
+| onPlayerAdded(player)            |Player added to game world. The argument is a `Game object`. |
 +----------------------------------+-------------------------------------------------------------+
 | onActorActive(actor)             | Actor (NPC or Creature) becomes active.                     |
 +----------------------------------+-------------------------------------------------------------+
+| **Only for local scripts**                                                                     |
++----------------------------------+-------------------------------------------------------------+
+| onActive()                       | | Called when the object becomes active (either a player    |
+|                                  | | came to this cell again, or a save was loaded).           |
++----------------------------------+-------------------------------------------------------------+
+| onInactive()                     | | Object became inactive. Since it is inactive the handler  |
+|                                  | | can not access anything nearby, but it is possible to send|
+|                                  | | an event to global scripts.                               |
++----------------------------------+-------------------------------------------------------------+
+| onConsume(recordId)              | | Called if `recordId` (e.g. a potion) is consumed.         |
++----------------------------------+-------------------------------------------------------------+
 | **Only for local scripts attached to a player**                                                |
 +----------------------------------+-------------------------------------------------------------+
 | onKeyPress(symbol, modifiers)    | | Key pressed. `Symbol` is an ASCII code, `modifiers` is    |
 |                                  | | a binary OR of flags of special keys (ctrl, shift, alt).  |
 +----------------------------------+-------------------------------------------------------------+
 
-.. _Game object:
-
-Game object reference
-=====================
-
-Game object is a universal reference to an object in the game world. Anything that has a reference number.
-
-**Can be used on any object:**
-
-+---------------------------------------------+--------------------------------------------------+
-| Function                                    | Description                                      |
-+=============================================+==================================================+
-| object:isValid()                            | | Returns true if the object exists and loaded,  |
-|                                             | | and false otherwise. If false, then every      |
-|                                             | | access to the object will raise an error.      |
-+---------------------------------------------+--------------------------------------------------+
-| object:sendEvent(eventName, eventData)      | Sends local event to the object.                 |
-+---------------------------------------------+--------------------------------------------------+
-| object:isEquipped(item)                     | Returns true if `item` is equipped on `object`.  |
-+---------------------------------------------+--------------------------------------------------+
-| object:getEquipment() -> table              | | Returns a table `slot` -> `object` of currently|
-|                                             | | equipped items. See `core.EQUIPMENT_SLOT`.     |
-|                                             | | Returns empty table if `object` doesn't have   |
-|                                             | | equipment slots.                               |
-+---------------------------------------------+--------------------------------------------------+
-| object:setEquipment(table)                  | | Sets equipment. Keys in the table are equipment|
-|                                             | | slots (see `core.EQUIPMENT_SLOT`). Each value  |
-|                                             | | can be either an object or `recordId`. Raises  |
-|                                             | | an error if `object` doesn't have equipment    |
-|                                             | | slots and `table` is not empty. Can be called  |
-|                                             | | only on `self` or from a global script.        |
-+---------------------------------------------+--------------------------------------------------+
-| object:addScript(scriptPath)                | | Adds new script to the object.                 |
-|                                             | | Can be called only from a global script.       |
-+---------------------------------------------+--------------------------------------------------+
-| object:teleport(cell, pos, [rot])           | | Moves object to given cell and position.       |
-|                                             | | The effect is not immediate: the position will |
-|                                             | | be updated only in the next frame.             |
-|                                             | | Can be called only from a global script.       |
-+---------------------------------------------+--------------------------------------------------+
-
-+-----------------------+---------------------+--------------------------------------------------+
-| Field                 | Type                | Description                                      |
-+=======================+=====================+==================================================+
-| object.position       | vector3_            | Position                                         |
-+-----------------------+---------------------+--------------------------------------------------+
-| object.rotation       | vector3_            | Rotation                                         |
-+-----------------------+---------------------+--------------------------------------------------+
-| object.cell           | string              | Cell                                             |
-+-----------------------+---------------------+--------------------------------------------------+
-| object.type           | string              | :ref:`Type <Object type>` of the object          |
-+-----------------------+---------------------+--------------------------------------------------+
-| object.count          | integer             | Count (makes sense if holded in a container)     |
-+-----------------------+---------------------+--------------------------------------------------+
-| object.recordId       | string              | Record ID                                        |
-+-----------------------+---------------------+--------------------------------------------------+
-| object.inventory      | Inventory           | Inventory of an actor or content of a container  |
-+-----------------------+---------------------+--------------------------------------------------+
-
-**Can be used if object.type == 'Door':**
-
-+-----------------------+---------------------+--------------------------------------------------+
-| Field                 | Type                | Description                                      |
-+=======================+=====================+==================================================+
-| object.isTeleport     | boolean             | True if it is a teleport door                    |
-+-----------------------+---------------------+--------------------------------------------------+
-| object.destPosition   | vector3_            | Destination (only if a teleport door)            |
-+-----------------------+---------------------+--------------------------------------------------+
-| object.destRotation   | vector3_            | Destination rotation (only if a teleport door)   |
-+-----------------------+---------------------+--------------------------------------------------+
-| object.destCell       | string              | Destination cell (only if a teleport door)       |
-+-----------------------+---------------------+--------------------------------------------------+
-
-Object type
------------
-
-Type is represented as a string. Can be one of:
-
-- "Activator"
-- "Armor"
-- "Book"
-- "Clothing"
-- "Container"
-- "Creature"
-- "Door"
-- "Ingredient"
-- "Light"
-- "Miscellaneous"
-- "NPC"
-- "Player"
-- "Potion"
-- "Static"
-- "Weapon"
-
-ObjectList
-----------
-
-List of game objects. Can't be created or modified by a script.
-
-.. code-block:: Lua
-
-    -- Iteration by index
-    for i = 1, #someList do
-        doSomething(someList[i])
-    end
-
-    -- Generic for (equivalent to iteration by index)
-    for i, item in someList:ipairs() do
-        doSomething(item)
-    end
-
-    -- WRONG: for i, item in ipairs(someList) do
-    -- It doesn't work because Lua 5.1 doesn't allow to overload ipairs for userdata.
-
-+---------------------------------------------+--------------------------------------------------+
-| Function                                    | Description                                      |
-+=============================================+==================================================+
-| list:ipairs()                               | Returns an iterator                              |
-+---------------------------------------------+--------------------------------------------------+
-| list:select(query) -> ObjectList            | Returns a filtered list                          |
-+---------------------------------------------+--------------------------------------------------+
-
-Object inventory
-----------------
-
-+---------------------------------------------+--------------------------------------------------+
-| Function                                    | Description                                      |
-+=============================================+==================================================+
-| inv:countOf(recordId) -> int                | The number of items with given recordId          |
-+---------------------------------------------+--------------------------------------------------+
-| inv:getAll(recordId) -> ObjectList_         | All contained items                              |
-+---------------------------------------------+--------------------------------------------------+
-| inv:getPotions() -> ObjectList_             | All potions from the inventory                   |
-+---------------------------------------------+--------------------------------------------------+
-| inv:getApparatuses() -> ObjectList_         | All apparatuses from the inventory               |
-+---------------------------------------------+--------------------------------------------------+
-| inv:getArmors() -> ObjectList_              | All armors from the inventory                    |
-+---------------------------------------------+--------------------------------------------------+
-| inv:getBooks() -> ObjectList_               | All books from the inventory                     |
-+---------------------------------------------+--------------------------------------------------+
-| inv:getClothing() -> ObjectList_            | All clothing from the inventory                  |
-+---------------------------------------------+--------------------------------------------------+
-| inv:getIngredients() -> ObjectList_         | All ingredients from the inventory               |
-+---------------------------------------------+--------------------------------------------------+
-| inv:getLights() -> ObjectList_              | All lights from the inventory                    |
-+---------------------------------------------+--------------------------------------------------+
-| inv:getLockpicks() -> ObjectList_           | All lockpicks from the inventory                 |
-+---------------------------------------------+--------------------------------------------------+
-| inv:getMiscellaneous() -> ObjectList_       | All miscellaneous items from the inventory       |
-+---------------------------------------------+--------------------------------------------------+
-| inv:getProbes() -> ObjectList_              | All probes from the inventory                    |
-+---------------------------------------------+--------------------------------------------------+
-| inv:getRepairKits() -> ObjectList_          | All repair kits from the inventory               |
-+---------------------------------------------+--------------------------------------------------+
-| inv:getWeapons() -> ObjectList_             | All weapon from the inventory                    |
-+---------------------------------------------+--------------------------------------------------+
-
-openmw.util
-===========
-
-+---------------------------------------------+--------------------------------------------------+
-| Function                                    | Description                                      |
-+=============================================+==================================================+
-| vector2(x, y) -> vector2_                   | Creates 2D vector                                |
-+---------------------------------------------+--------------------------------------------------+
-| vector3(x, y, z) -> vector3_                | Creates 3D vector                                |
-+---------------------------------------------+--------------------------------------------------+
-| clamp(value, from, to) -> number            | Limits given value to the interval [from, to]    |
-+---------------------------------------------+--------------------------------------------------+
-| normalizeAngle(radians) -> number           | Adds 2pi*k and puts the angle in range [-pi, pi] |
-+---------------------------------------------+--------------------------------------------------+
-
-vector2
--------
-
-Immutable 2D vector.
-
-.. code-block:: Lua
-
-    v = vector2(3, 4)
-    v.x, v.y       -- 3.0, 4.0
-    str(v)         -- "(3.0, 4.0)"
-    v:length()     -- 5.0    length
-    v:length2()    -- 25.0   square of the length
-    v:normalize()  -- vector2(3/5, 4/5)
-    v:rotate(radians)    -- rotate clockwise (returns rotated vector)
-    v1:dot(v2)     -- dot product (returns a number)
-    v1 * v2        -- dot product
-    v1 + v2        -- vector addition
-    v1 - v2        -- vector subtraction
-    v1 * x         -- multiplication by a number
-    v1 / x         -- division by a number
-
-vector3
--------
-
-.. code-block:: Lua
-
-    v = vector3(3, 4, 5)
-    v.x, v.y, v.z  -- 3.0, 4.0, 5.0
-    str(v)         -- "(3.0, 4.0, 4.5)"
-    v:length()     -- length
-    v:length2()    -- square of the length
-    v:normalize()  -- normalized vector
-    v1:dot(v2)     -- dot product (returns a number)
-    v1 * v2        -- dot product (returns a number)
-    v1:cross(v2)   -- cross product (returns a vector)
-    v1 ^ v2        -- cross product (returns a vector)
-    v1 + v2        -- vector addition
-    v1 - v2        -- vector subtraction
-    v1 * x         -- multiplication by a number
-    v1 / x         -- division by a number
-
-openmw.core
-===========
-
-+-----------------------+---------------------+---------------------------------------------------+
-| Field                 | Type                | Description                                       |
-+=======================+=====================+===================================================+
-| OBJECT_TYPE           | Readonly table      | Possible :ref:`object type <Object type>` values  |
-+-----------------------+---------------------+---------------------------------------------------+
-| EQUIPMENT_SLOTS       | Readonly table      | | Contains keys that can be used in               |
-|                       |                     | | `object:getEquipment` and `object:setEquipment`.|
-+-----------------------+---------------------+---------------------------------------------------+
-
-``EQUIPMENT_SLOTS`` contains fields: "Helmet", "Cuirass", "Greaves", "LeftPauldron", "RightPauldron",
-"LeftGauntlet", "RightGauntlet", "Boots", "Shirt", "Pants", "Skirt", "Robe", "LeftRing", "RightRing",
-"Amulet", "Belt", "CarriedRight", "CarriedLeft", "Ammunition".
-
-+---------------------------------------------+--------------------------------------------------+
-| Function                                    | Description                                      |
-+=============================================+==================================================+
-| sendGlobalEvent(eventName, eventData)       | Sends an event to global scripts                 |
-+---------------------------------------------+--------------------------------------------------+
-| getRealTime()                               | | The number of seconds (with floating point)    |
-|                                             | | passed from 00:00 UTC 1 Januar 1970 (unix time)|
-+---------------------------------------------+--------------------------------------------------+
-| getGameTimeInSeconds()                      | | The number of seconds in the game world, passed|
-|                                             | | from starting a new game.                      |
-+---------------------------------------------+--------------------------------------------------+
-| getGameTimeInHours()                        | | Current time of the game world in hours.       |
-|                                             | | Note that the number of game seconds in a game |
-|                                             | | hour is not guaranteed to be fixed.            |
-+---------------------------------------------+--------------------------------------------------+
-
-openmw.async
-============
-
-Timers and coroutine utils.
-All functions require the package itself as a first argument.
-I.e. functions should be called with ``:`` rather than with ``.``.
-
-+-----------------------------------------------------+--------------------------------------------------+
-| Function                                            | Description                                      |
-+=====================================================+==================================================+
-| async:registerTimerCallback(name, func) -> Callback | Registers a function as a timer callback         |
-+-----------------------------------------------------+--------------------------------------------------+
-| async:newTimerInSeconds(delay, Callback, arg)       | | Calls `Callback(arg)` in `delay` seconds.      |
-|                                                     | | `Callback` must be registered in advance.      |
-+-----------------------------------------------------+--------------------------------------------------+
-| async:newTimerInHours(delay, Callback, arg)         | | Calls `Callback(arg)` in `delay` game hours.   |
-|                                                     | | `Callback` must be registered in advance.      |
-+-----------------------------------------------------+--------------------------------------------------+
-| async:newUnsavableTimerInSeconds(delay, func)       | | Call `func()` in `delay` seconds. The timer    |
-|                                                     | | will be lost if the game is saved and loaded.  |
-+-----------------------------------------------------+--------------------------------------------------+
-| async:newUnsavableTimerInHours(delay, func)         | | Call `func()` in `delay` game hours. The timer |
-|                                                     | | will be lost if the game is saved and loaded.  |
-+-----------------------------------------------------+--------------------------------------------------+
-
-openmw.query
-============
-
-**TODO**
-
-openmw.world
-============
-
-Interface to the game world. Can be used only by global scripts.
-
-+-----------------------+---------------------+--------------------------------------------------+
-| Field                 | Type                | Description                                      |
-+=======================+=====================+==================================================+
-| activeActors          | ObjectList_         | List of currently active actors                  |
-+-----------------------+---------------------+--------------------------------------------------+
-
-+---------------------------------------------+--------------------------------------------------+
-| Function                                    | Description                                      |
-+=============================================+==================================================+
-| selectObjects(query) -> ObjectList_         | Evaluates a query                                |
-+---------------------------------------------+--------------------------------------------------+
-
-openmw.nearby
-=============
-
-Can be used only by local scripts.
-Read-only access to the nearest area of the game world.
-
-+-----------------------+---------------------+--------------------------------------------------+
-| Field                 | Type                | Description                                      |
-+=======================+=====================+==================================================+
-| activators            | ObjectList_         | List of nearby activators                        |
-+-----------------------+---------------------+--------------------------------------------------+
-| actors                | ObjectList_         | List of nearby actors                            |
-+-----------------------+---------------------+--------------------------------------------------+
-| containers            | ObjectList_         | List of nearby containers                        |
-+-----------------------+---------------------+--------------------------------------------------+
-| doors                 | ObjectList_         | List of nearby doors                             |
-+-----------------------+---------------------+--------------------------------------------------+
-| items                 | ObjectList_         | Everything that can be picked up in the nearby   |
-+-----------------------+---------------------+--------------------------------------------------+
-
-+---------------------------------------------+--------------------------------------------------+
-| Function                                    | Description                                      |
-+=============================================+==================================================+
-| selectObjects(query) -> ObjectList_         | Evaluates a query                                |
-+---------------------------------------------+--------------------------------------------------+
-
-openmw.self
-===========
-
-Can be used only by local scripts. Full access to the object the script is attached to.
-All fields and function of `Game object`_ are also available for `openmw.self`. For example:
-
-.. code-block:: Lua
-
-    local self = require('openmw.self')
-    if self.type == 'Player' then
-        self:sendEvent("something", self.position)
-    end
-
-Note that `self` is not a Game Object. If you need an actual object, use `self.object`:
-
-.. code-block:: Lua
-
-    if self == someObject then ...  -- Incorrect, this condition is always false
-    core.sendGlobalEvent('something', self)  -- Incorrect, will raise an error
-
-    if self.object == someObject then ... -- Correct
-    core.sendGlobalEvent('something', self.object)  -- Correct
-
-
-+-----------------------+---------------------+--------------------------------------------------+
-| Field                 | Type                | Description                                      |
-+=======================+=====================+==================================================+
-| self.object           | `Game object`_      | The object the script is attached to (readonly)  |
-+-----------------------+---------------------+--------------------------------------------------+
-| self.controls         | `Actor controls`_   | Movement controls (only for actors)              |
-+-----------------------+---------------------+--------------------------------------------------+
-
-+---------------------------------------------+--------------------------------------------------+
-| Function                                    | Description                                      |
-+=============================================+==================================================+
-| self:setDirectControl(bool)                 | Enables or disables direct movement control      |
-+---------------------------------------------+--------------------------------------------------+
-| self:setEquipment(table)                    | | Sets equipment. Keys in the table are equipment|
-|                                             | | slots (see `core.EQUIPMENT_SLOT`). Each value  |
-|                                             | | can be either an object or `recordId`. Raises  |
-|                                             | | an error if the object has no equipment        |
-|                                             | | slots and `table` is not empty.                |
-+---------------------------------------------+--------------------------------------------------+
-| self:getCombatTarget() -> `Game object`_    | Returns current target or nil if not in combat   |
-+---------------------------------------------+--------------------------------------------------+
-| self:stopCombat()                           | Removes all combat packages from the actor       |
-+---------------------------------------------+--------------------------------------------------+
-| self:startCombat(target)                    | Attack `target`                                  |
-+---------------------------------------------+--------------------------------------------------+
-
-
-Actor controls
---------------
-
-Allows to control movements of an actor. Makes an effect only if `setDirectControl(true)` was called.
-All fields are mutable.
-
-+-----------------------+---------------------+--------------------------------------------------+
-| Field                 | Type                | Description                                      |
-+=======================+=====================+==================================================+
-| movement              | float number        | +1 - move forward, -1 - move backward            |
-+-----------------------+---------------------+--------------------------------------------------+
-| sideMovement          | float number        | +1 - move right, -1 - move left                  |
-+-----------------------+---------------------+--------------------------------------------------+
-| turn                  | float number        | turn right (radians); if negative - turn left    |
-+-----------------------+---------------------+--------------------------------------------------+
-| run                   | boolean             | true - run, false - walk                         |
-+-----------------------+---------------------+--------------------------------------------------+
-| jump                  | boolean             | if true - initiate a jump                        |
-+-----------------------+---------------------+--------------------------------------------------+
-
-openmw.ui
-=========
-
-Can be used only by local scripts, that are attached to a player.
-
-+---------------------------------------------+--------------------------------------------------+
-| Function                                    | Description                                      |
-+=============================================+==================================================+
-| showMessage(string)                         | Shows given message at the bottom of the screen. |
-+---------------------------------------------+--------------------------------------------------+
 
-openmw.camera
-=============
+Packages reference
+==================
+
+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.
+
++---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+| Package                                                 | Can be used        | Description                                                   |
++=========================================================+====================+===============================================================+
+|:ref:`openmw.interfaces <Script interfaces>`             | everywhere         | | Public interfaces of other scripts.                         |
++---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+|`openmw.util <../../lua-api-reference/util.html>`_       | everywhere         | | Defines utility functions and classes like 3D vectors,      |
+|                                                         |                    | | that don't depend on the game world.                        |
++---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+|`openmw.core <../../lua-api-reference/core.html>`_       | everywhere         | | Functions that are common for both global and local scripts |
++---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+|`openmw.async <../../lua-api-reference/async.html>`_     | everywhere         | | Timers (implemented) and coroutine utils (not implemented)  |
++---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+|`openmw.query <../../lua-api-reference/query.html>`_     | everywhere         | | Tools for constructing queries: base queries and fields.    |
++---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+|`openmw.world <../../lua-api-reference/world.html>`_     | by global scripts  | | Read-write access to the game world.                        |
++---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+|`openmw.self <../../lua-api-reference/self.html>`_       | by local scripts   | | Full access to the object the script is attached to.        |
++---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+|`openmw.nearby <../../lua-api-reference/nearby.html>`_   | by local scripts   | | Read-only access to the nearest area of the game world.     |
++---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+|`openmw.ui <../../lua-api-reference/ui.html>`_           | by player scripts  | | Controls user interface                                     |
++---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+|openmw.camera                                            | by player scripts  | | Controls camera (not implemented)                           |
++---------------------------------------------------------+--------------------+---------------------------------------------------------------+
 
-.. warning::
-    Not implemented yet.
diff --git a/docs/source/reference/lua-scripting/overview.rst b/docs/source/reference/lua-scripting/overview.rst
index f941c190a8..635aeef462 100644
--- a/docs/source/reference/lua-scripting/overview.rst
+++ b/docs/source/reference/lua-scripting/overview.rst
@@ -12,8 +12,8 @@ Here are starting points for learning Lua:
 - `Programing in Lua <https://www.lua.org/pil/contents.html>`__ (first edition, aimed at Lua 5.0)
 - `Lua 5.1 Reference Manual <https://www.lua.org/manual/5.1/>`__
 
-Each script works in a separate sandbox and doesn't have any access to operation system.
-Only limited list of allowed standard libraries can be used:
+Each script works in a separate sandbox and doesn't have any access to the underlying operating system.
+Only a limited list of allowed standard libraries can be used:
 `coroutine <https://www.lua.org/manual/5.1/manual.html#5.2>`__,
 `math <https://www.lua.org/manual/5.1/manual.html#5.6>`__,
 `string <https://www.lua.org/manual/5.1/manual.html#5.4>`__,
@@ -21,7 +21,7 @@ Only limited list of allowed standard libraries can be used:
 These libraries are loaded automatically and are always available (except the function `math.randomseed` -- it is called by the engine on startup and not available from scripts).
 
 Allowed `basic functions <https://www.lua.org/manual/5.1/manual.html#5.1>`__:
-``assert``, ``error``, ``ipairs``, ``next``, ``pairs``, ``pcall``, ``print``, ``tonumber``, ``tostring``, ``type``, ``unpack``, ``xpcall``, ``rawequal``, ``rawget``, ``rawset``, ``setmetatable``.
+``assert``, ``error``, ``ipairs``, ``next``, ``pairs``, ``pcall``, ``print``, ``select``, ``tonumber``, ``tostring``, ``type``, ``unpack``, ``xpcall``, ``rawequal``, ``rawget``, ``rawset``, ``getmetatable``, ``setmetatable``.
 
 Loading libraries with ``require('library_name')`` is allowed, but limited. It works this way:
 
@@ -29,7 +29,7 @@ Loading libraries with ``require('library_name')`` is allowed, but limited. It w
 2. If `library_name` is one of the built-in `API packages`_, then return the package.
 3. Otherwise search for a Lua source file with such name in :ref:`data folders <Multiple data folders>`. For example ``require('my_lua_library.something')`` will try to open the file ``my_lua_library/something.lua``.
 
-Loading DLLs and precompiled Lua files is intentionally prohibited for reasons of safety and compatibility between different platforms.
+Loading DLLs and precompiled Lua files is intentionally prohibited for compatibility and security reasons.
 
 Basic concepts
 ==============
@@ -44,21 +44,21 @@ Record
     Don't be confused with MWSE terminology. In MWSE game objects are "references" and records are "objects".
 
 Cell
-    An area of the game world. A position in the world is a link to a cell and coordinates X, Y, Z in the cell. At a specific moment in time each cell can be active or inactive. Inactive cells don't perform physics updates.
+    An area of the game world. A position in the world is a link to a cell and X, Y, Z coordinates in the cell. At a specific moment in time each cell can be active or inactive. Inactive cells don't perform physics updates.
 
 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. List of global scripts is defined by `omwscripts` files, that should be :ref:`registered <Lua scripting>` in `openmw.cfg`.
+    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`.
 
 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.
+    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.
 
 Player scripts
-    It is a specific case of local scripts. *Player script* is a local script that is attached to a player. It can do everything that a normal local script can do, plus some player-specific functionality (e.g. control UI and camera).
+    A specific kind of local scripts; *player script* is a local script that is attached to a player. It can do everything that a normal local script can do, plus some player-specific functionality (e.g. control UI and camera).
 
-Scripting API was developed to be conceptually compatible with `multiplayer <https://github.com/TES3MP/openmw-tes3mp>`__. In multiplayer the server is lightweight and delegates most of the work to clients. Each client processes some part of the game world. Global scripts are server-side and local scripts are client-side. It leads to several rules of Lua scripting API:
+This scripting API was developed to be conceptually compatible with `multiplayer <https://github.com/TES3MP/openmw-tes3mp>`__. In multiplayer the server is lightweight and delegates most of the work to clients. Each client processes some part of the game world. Global scripts are server-side and local scripts are client-side. Because of this, there are several rules for the Lua scripting API:
 
 1. A local script can see only some area of the game world (cells that are active on a specific client). Any data from inactive cells can't be used, as they are not synchronized and could be already changed on another client.
-2. A local script can modify only the object it is attached to. Other objects can theoretically be processed by another client. To prevent synchronization problems the access to them is read only.
+2. A local script can only modify the object it is attached to. Other objects can theoretically be processed by another client. To prevent synchronization problems the access to them is read-only.
 3. Global scripts can access and modify the whole game world including unloaded areas, but the global scripts API is different from the local scripts API and in some aspects limited, because it is not always possible to have all game assets in memory at the same time.
 4. Though the scripting system doesn't actually work with multiplayer yet, the API assumes that there can be several players. That's why any command related to UI, camera, and everything else that is player-specific can be used only by player scripts.
 
@@ -76,8 +76,8 @@ Let's write a simple example of a `Player script`:
 
     return {
         engineHandlers = {
-            onKeyPress = function(code, modifiers)
-                if code == string.byte('x') then
+            onKeyPress = function(key)
+                if key.symbol == 'x' then
                     ui.showMessage('You have pressed "X"')
                 end
             end
@@ -117,14 +117,14 @@ Now every time the player presses "X" on a keyboard, a message is shown.
 Hot reloading
 =============
 
-It is possible to modify a script without restarting OpenMW. To apply changes open in-game console and run the command ``reloadlua``.
-It will restart all Lua scripts using `onSave and onLoad`_ handlers the same way as if the game was saved and loaded.
+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 works only with existing ``*.lua`` files that are not packed to any archives. Adding new scripts or modifying ``*.omwscripts`` files always requires restarting the game.
 
 Script structure
 ================
 
-Each script is a separate file in game assets.
+Each script is a separate file in the game assets.
 `Starting a script` means that the engine runs the file, parses the table it returns, and registers its interface, event handlers, and engine handlers. The handlers are permanent and exist until the script is stopped (if it is a local script, because global scripts can not be stopped).
 
 Here is an example of a basic script structure:
@@ -155,7 +155,7 @@ Here is an example of a basic script structure:
     end
 
     return {
-        name = 'MyScriptInterface',
+        interfaceName = 'MyScriptInterface',
         interface = {
             somePublicFunction = somePublicFunction,
         },
@@ -192,7 +192,7 @@ Engine handlers
 ===============
 
 An engine handler is a function defined by a script, that can be called by the engine. I.e. it is an engine-to-script interaction.
-Not visible for other scripts. If several scripts register an engine handler with the same name,
+Not visible to other scripts. If several scripts register an engine handler with the same name,
 the engine calls all of them in the same order as the scripts were started.
 
 Some engine handlers are allowed only for global, or only for local/player scripts. Some are universal.
@@ -202,17 +202,61 @@ See :ref:`Engine handlers reference`.
 onSave and onLoad
 =================
 
-When game is saved or loaded, the engine calls engine handlers `onSave` or `onLoad` for every script.
+When a game is saved or loaded, the engine calls the engine handlers `onSave` or `onLoad` for every script.
 The value that `onSave` returns will be passed to `onLoad` when the game is loaded.
-It is the only way to save internal state of a script. All other script vatiables will be lost after closing the game.
+It is the only way to save the internal state of a script. All other script variables will be lost after closing the game.
 The saved state must be :ref:`serializable <Serializable data>`.
 
-`onSave` and `onLoad` are special:
+The list of active global scripts is controlled by ``*.omwscripts`` files. Loading a save doesn't synchronize
+the list of global scripts with those that were active previously, it only calls `onLoad` for those currently active.
 
-- Unlike all other engine handlers it is called even for objects in inactive cells.
-- During saving and loading the environment may be not fully initialized, so these handlers shouldn't use any API calls.
+For local scripts the situation is different. When a save is loading, it tries to run all local scripts that were saved.
+So if ``lua-scripts=`` entries of some mod are removed, but ``data=`` entries are still enabled, then local scripts from the mod may still run.
 
-TODO: example, explain how global scripts are loading
+`onSave` and `onLoad` can be called even for objects in inactive state, so it shouldn't use `openmw.nearby`.
+
+An example:
+
+.. code-block:: Lua
+
+    ...
+
+    local scriptVersion = 3  -- increase it every time when `onSave` is changed
+
+    local function onSave()
+        return {
+            version = scriptVersion
+            some = someVariable,
+            someOther = someOtherVariable
+        }
+    end
+
+    local function onLoad(data)
+        if not data or not data.version or data.version < 2 then
+            print('Was saved with an old version of the script, initializing to default')
+            someVariable = 'some value'
+            someOtherVariable = 42
+            return
+        end
+        if data.version > scriptVersion then
+            error('Required update to a new version of the script')
+        end
+        someVariable = data.some
+        if data.version == scriptVersion then
+            someOtherVariable = data.someOther
+        else
+            print(string.format('Updating from version %d to %d', data.version, scriptVersion))
+            someOtherVariable = 42
+        end
+    end
+
+    return {
+        engineHandlers = {
+            onUpdate = update,
+            onSave = onSave,
+            onLoad = onLoad,
+        }
+    }
 
 Serializable data
 -----------------
@@ -225,7 +269,7 @@ Serializable value is one of:
 - a number
 - a string
 - a game object
-- a value of a type, defined by :ref:`openmw.util`
+- a value of a type, defined by :ref:`openmw.util <Package openmw.util>`
 - a table whith serializable keys and values
 
 Serializable data can not contain:
@@ -244,70 +288,277 @@ 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.
 
-+----------------------+--------------------+---------------------------------------------------------------+
-| Package              | Can be used        | Description                                                   |
-+======================+====================+===============================================================+
-|:ref:`openmw.util`    | everywhere         | | Defines utility functions and classes like 3D vectors,      |
-|                      |                    | | that don't depend on the game world.                        |
-+----------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw.core`    | everywhere         | | Functions that are common for both global and local scripts |
-+----------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw.async`   | everywhere         | | Timers (implemented) and coroutine utils (not implemented)  |
-+----------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw.query`   | everywhere         | | Tools for constructing queries: base queries and fields.    |
-+----------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw.world`   | by global scripts  | | Read-write access to the game world.                        |
-+----------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw.self`    | by local scripts   | | Full access to the object the script is attached to.        |
-+----------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw.nearby`  | by local scripts   | | Read-only access to the nearest area of the game world.     |
-+----------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw.ui`      | by player scripts  | | Controls user interface                                     |
-+----------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw.camera`  | by player scripts  | | Controls camera (not implemented)                           |
-+----------------------+--------------------+---------------------------------------------------------------+
++---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+| Package                                                 | Can be used        | Description                                                   |
++=========================================================+====================+===============================================================+
+|:ref:`openmw.interfaces <Script interfaces>`             | everywhere         | | Public interfaces of other 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.core <Package openmw.core>`                 | everywhere         | | Functions that are common for both global and local scripts |
++---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+|:ref:`openmw.async <Package openmw.async>`               | everywhere         | | Timers (implemented) and coroutine utils (not implemented)  |
++---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+|:ref:`openmw.query <Package openmw.query>`               | everywhere         | | Tools for constructing queries: base queries and fields.    |
++---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+|:ref:`openmw.world <Package openmw.world>`               | by global scripts  | | Read-write access to the game world.                        |
++---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+|:ref:`openmw.self <Package openmw.self>`                 | by local scripts   | | Full access to the object the script is attached to.        |
++---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+|:ref:`openmw.nearby <Package openmw.nearby>`             | by local scripts   | | Read-only access to the nearest area of the game world.     |
++---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+|:ref:`openmw.ui <Package openmw.ui>`                     | by player scripts  | | Controls user interface                                     |
++---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+|openmw.camera                                            | by player scripts  | | Controls camera (not implemented)                           |
++---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+
+openmw_aux
+----------
+
+``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.
+
++---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+| Built-in library                                        | Can be used        | Description                                                   |
++=========================================================+====================+===============================================================+
+|:ref:`openmw_aux.util <Package openmw_aux.util>`         | everywhere         | | Miscellaneous utils                                         |
++---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+
+They can be loaded with ``require`` the same as API packages. For example:
+
+.. code-block:: Lua
+
+    local aux_util = require('openmw_aux.util')
+    aux_util.runEveryNSeconds(15, doSomething)  -- run `doSomething()` every 15 seconds
 
 
 Script interfaces
 =================
 
-.. warning::
-    Not implemented yet.
-
 Each script can provide a named interface for other scripts.
 It is a script-to-script interaction. This mechanism is not used by the engine itself.
 
-A script can use an interface of another script only if either both a global scripts, or both are local scripts on the same object.
+A script can use an interface of another script either if both are global scripts, or both are local scripts on the same object.
 In other cases events should be used.
 
-TODO: example, overloading
+Defining an interface:
+
+.. code-block:: Lua
+
+    return {
+        interfaceName = "SomeUtils"
+        interface = {
+            version = 1,
+            doSomething = function(x, y) ... end,
+        }
+    }
+
+Overriding the interface and adding a debug output:
+
+.. code-block:: Lua
+
+    local interfaces = require('openmw.interfaces')
+
+    -- it is important to save it before returning the new interface
+    local orig = interfaces.SomeUtils
+
+    return {
+        interfaceName = "SomeUtils"
+        interface = {
+            version = orig.version,
+            doSomething = function(x, y)
+                print(string.format('SomeUtils.doSomething(%d, %d)', x, y))
+                orig.doSomething(x, y)  -- calls the original `doSomething`
+
+                -- WRONG! Would lead to an infinite recursion.
+                -- interfaces.SomeUtils.doSomething(x, y)
+            end,
+        }
+    }
+
+A general recomendation about overriding is that the new interface should be fully compatible with the old one.
+So it is fine to change the behaviour of `SomeUtils.doSomething`, but if you want to add a completely new function, it would be
+better to create a new interface for it. For example `SomeUtilsExtended` with an additional function `doSomethingElse`.
+
+Using the interface:
+
+.. code-block:: Lua
+
+    local interfaces = require('openmw.interfaces')
+
+    local function onUpdate()
+        interfaces.SomeUtils.doSomething(2, 3)
+    end
+
+    return { engineHandlers = {onUpdate = onUpdate} }
+
+The order in which the scripts are started is important. So if one mod should override an interface provided by another mod, make sure that load order (i.e. the sequence of `lua-scripts=...` in `openmw.cfg`) is correct.
 
 
 Event system
 ============
 
-It is another way of script-to-script interactions. The differences:
+This is another kind of script-to-script interactions. The differences:
 
 - Any script can send an event to any object or a global event to global scripts.
-- Events are always delivered with a delay.
-- Event handlers can not return any data to a sender.
+- Events are delivered with a small delay (in single player the delay is always one frame).
+- Event handlers can not return any data to the sender.
 - Event handlers have a single argument `eventData` (must be :ref:`serializable <Serializable data>`)
 
-Events are the main way of interactions between local and global scripts.
-It is not recommended to use for interactions between two global scripts, because in this case interfaces are more convenient.
+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.
 
-If several scripts register handlers for the same event, it will be called in the reversed order (opposite to engine handlers).
-I.e. handler from the last attached script will be called first.
-Return value 'false' in a handler means "skip all other handlers for this event".
+If several scripts register handlers for the same event, the handlers will be called in reverse order (opposite to engine handlers).
+I.e. the handler from the last attached script will be called first.
+Return value 'false' means "skip all other handlers for this event".
 Any other return value (including nil) means nothing.
 
-TODO: example
+An example. Imagine we are working on a mod that adds some "dark power" with special effects.
+We attach a local script to an item that can explode.
+At some moment it will send the 'DamagedByDarkPower' event to all nearby actors:
+
+.. code-block:: Lua
+
+    local self = require('openmw.self')
+    local nearby = require('openmw.nearby')
+
+    local function onActivate()
+        for i, actor in nearby.actors:ipairs() do
+            local dist = (self.position - actor.position):length()
+            if dist < 500 then
+                local damage = (1 - dist / 500) * 200
+                actor:sendEvent('DamagedByDarkPower', {source=self.object, damage=damage})
+            end
+        end
+    end
+
+    return { engineHandlers = { ... } }
+
+And every actor should have a local script that processes this event:
+
+.. code-block:: Lua
+
+    local function damagedByDarkPower(data)
+        ...  -- apply `data.damage` to stats / run custom animation / etc
+    end
+
+    return {
+        eventHandlers = { DamagedByDarkPower = damagedByDarkPower },
+    }
+
+Someone may create an additional mod that adds a protection from the dark power.
+The protection mod attaches an additional local script to every actor. The script intercepts and modifies the event:
+
+.. code-block:: Lua
+
+    local protectionLevel = ...
+
+    local function reduceDarkDamage(data)
+        data.damage = data.damage - protectionLevel  -- reduce the damage
+        return data.damage > 0  -- it skips the original handler if the damage becomes <= 0
+    end
+
+    return {
+        eventHandlers = { DamagedByDarkPower = reduceDarkDamage },
+    }
+
+In order to be able to intercept the event, the protection script should be attached after the original script (i.e. below in the load order).
 
 
 Timers
 ======
 
-**TODO**
+Timers are in the :ref:`openmw.async <Package openmw.async>` package.
+They can be set either in game seconds or in game hours.
+
+- `Game seconds`: the number of seconds in the game world (i.e. seconds when the game is not paused), passed from starting a new game.
+- `Game hours`: current time of the game world in hours. The number of seconds in a game hour is not guaranteed to be fixed.
+
+When the game is paused, all timers are paused as well.
+
+When an object becomes inactive, timers on this object are not paused, but callbacks are called only when the object becomes active again.
+For example if there were 3 timers with delays 30, 50, 90 seconds, and from the 15-th to the 65-th second the object was inactive, then the first two callbacks are both evaluated on the 65-th second and the third one -- on the 90-th second.
+
+There are two types: *reliable* and *unsavable* timers.
+
+Reliable timer
+--------------
+
+Reliable timers are automatically saved and restored when the game is saved or loaded.
+When the game is saved each timer record contains only name of a callback, the time when the callback should be called, and an argument that should be passed to the callback.
+The callback itself is not stored. That's why callbacks must be registered when the script is initialized with a function ``async:registerTimerCallback(name, func)``.
+`Name` is an arbitrary string.
+
+An example:
+
+.. code-block:: Lua
+
+    local async = require('openmw.async')
+
+    local teleportWithDelayCallback = async:registerTimerCallback('teleport',
+    function(data)
+        data.actor:teleport(data.destCellName, data.destPos)
+    end)
+
+    local function teleportWithDelay(delay, actor, cellName, pos)
+        async:newTimerInSeconds(delay, teleportWithDelayCallback, {
+            actor = actor,
+            destCellName = cellName,
+            destPos = pos,
+        })
+    end
+
+Unsavable timer
+---------------
+
+Unsavable timers can be created from any function without registering a callback in advance, but they can not be saved.
+If the player saves the game when an unsavable timer is running, then the timer will be lost after reloading.
+So be careful with unsavable timers and don't use them if there is a risk of leaving the game world in an inconsistent state.
+
+An example:
+
+.. code-block:: Lua
+
+    local async = require('openmw.async')
+    local ui = require('openmw.ui')
+
+    return {
+        engineHandlers = {
+            onKeyPress = function(key)
+                if key.symbol == 'x' then
+                    async:newUnsavableTimerInSeconds(
+                        10,
+                        function()
+                            ui.showMessage('You have pressed "X" 10 seconds ago')
+                        end)
+                end
+            end,
+        }
+    }
+
+Also in `openmw_aux`_ are the helper functions ``runEveryNSeconds`` and ``runEveryNHours``, they are implemented on top of unsavable timers:
+
+.. code-block:: Lua
+
+    local async = require('openmw.async')
+    local core = require('openmw.core')
+
+    -- call `doSomething()` at the end of every game day.
+    -- `timeBeforeMidnight` is a delay before the first call. `24` is an interval.
+    -- the periodical evaluation can be stopped at any moment by calling `stopFn()`
+    local timeBeforeMidnight = 24 - math.fmod(core.getGameTimeInHours(), 24)
+    local stopFn = aux_util.runEveryNHours(24, doSomething, timeBeforeMidnight)
+
+    return {
+        engineHandlers = {
+            onLoad = function()
+                -- the timer is unsavable, so we need to restart it in `onLoad`.
+                timeBeforeMidnight = 24 - math.fmod(core.getGameTimeInHours(), 24)
+                stopFn = aux_util.runEveryNHours(24, doSomething, timeBeforeMidnight)
+            end,
+        }
+    }
 
 
 Queries
@@ -318,7 +569,7 @@ Queries
 `openmw.world.selectObjects` and `openmw.nearby.selectObjects` both accept a query and return objects that match it. However, `nearby.selectObjects` is only available in local scripts, and returns only objects from currently active cells, while `world.selectObjects` is only available in global scripts, and returns objects regardless of them being in active cells.
 **TODO:** describe how to filter out inactive objects from world queries
 
-A minimal example of an object query:
+An example of an object query:
 
 .. code-block:: Lua
 
@@ -326,10 +577,8 @@ A minimal example of an object query:
     local nearby = require('openmw.nearby')
     local ui = require('openmw.ui')
 
-    local doorQuery = query.doors:orderBy(query.DOOR.destPosition.x)
-
     local function selectDoors(namePattern)
-        local query = doorQuery:where(query.DOOR.destCell:like(namePattern))
+        local query = query.doors:where(query.DOOR.destCell.name:like(namePattern))
         return nearby.selectObjects(query)
     end
 
@@ -344,8 +593,8 @@ A minimal example of an object query:
 
     return {
         engineHandlers = {
-            onKeyPress = function(code, modifiers)
-                if code == string.byte('e') then
+            onKeyPress = function(key)
+                if key.symbol == 'e' then
                     showGuildDoors()
                 end
             end
@@ -360,10 +609,10 @@ A minimal example of an object query:
 Queries are constructed through the following method calls: (if you've used SQL before, you will find them familiar)
 
 - `:where(filter)` - filters the results to match the combination of conditions passed as the argument
-- `:orderBy(field)` and `:orderByDesc(field)` sort the result by the `field` argument. Sorts in descending order in case of `:orderByDesc`. Multiple calls can be chained, with the first call having priority. (i. e. if the first field is equal, objects are sorted by the second one...)
-- `:groupBy(field)` returns only one result for each value of the `field` argument. The choice of the result is arbitrary. Useful for counting only unique objects, or checking if certain objects exist.
+- `:orderBy(field)` and `:orderByDesc(field)` sort the result by the `field` argument. Sorts in descending order in case of `:orderByDesc`. Multiple calls can be chained, with the first call having priority. (i. e. if the first field is equal, objects are sorted by the second one...) **(not implemented yet)**
+- `:groupBy(field)` returns only one result for each value of the `field` argument. The choice of the result is arbitrary. Useful for counting only unique objects, or checking if certain objects exist. **(not implemented yet)**
 - `:limit(number)` will only return `number` of results (or fewer)
-- `:offset(number)` skips the first `number` results. Particularly useful in combination with `:limit`
+- `:offset(number)` skips the first `number` results. Particularly useful in combination with `:limit` **(not implemented yet)**
 
 Filters consist of conditions, which are combined with "and" (operator `*`), "or" (operator `+`), "not" (operator `-`) and braces `()`.
 
@@ -375,7 +624,7 @@ To make a condition, take a field from the `openmw.query` package and call any o
 - `:gte` greater or equal to
 - `:lt` less than
 - `:lte` less or equal to
-- `:like` matches a pattern. Only applicable to text (strings)
+- `:like` matches a pattern. Only applicable to text (strings) **(not implemented yet)**
 
 **TODO:** describe the pattern format
 
@@ -401,12 +650,61 @@ A few examples of filters:
 
     local DOOR = query.DOOR
 
-    local interestingDoors = -DOOR.name:eq("") * DOOR.isTeleport:eq(true) * Door.destCell:neq("")
+    local interestingDoors = -DOOR.name:eq("") * DOOR.isTeleport:eq(true) * Door.destCell.isExterior:eq(false)
 
 
 Using IDE for Lua scripting
 ===========================
 
-.. warning::
-    This section is not written yet. Later it will explain how to setup Lua Development Tools (eclipse-based IDE) with code autocompletion and integrated OpenMW API reference.
+Find the directory ``resources/lua_api`` in your installation of OpenMW.
+It describes OpenMW LuaAPI in
+`LDT Documentation Language <https://wiki.eclipse.org/LDT/User_Area/Documentation_Language>`__.
+It is the source from which the :ref:`API reference <Lua API reference>` is generated.
+
+If you write scripts using `Lua Development Tools <https://www.eclipse.org/ldt/>`__ (eclipse-based IDE),
+you can import these files to get code autocompletion and integrated OpenMW API reference. Here are the steps:
+
+- Install and run `LDT <https://www.eclipse.org/ldt/#installation>`__.
+- Press `File` / `New` / `Lua Project` in menu.
+
+.. image:: https://gitlab.com/OpenMW/openmw-docs/raw/master/docs/source/reference/lua-scripting/_static/lua-ide-create-project.png
+
+- Specify project name (for example the title of your omwaddon)
+- Set `Targeted Execution Environment` to `No Execution Environment`, and `Target Grammar` to `lua-5.1`.
+
+.. image:: https://gitlab.com/OpenMW/openmw-docs/raw/master/docs/source/reference/lua-scripting/_static/lua-ide-project-settings.png
+
+- Press `Next`, choose the `Libraries` tab, and click `Add External Source Folder`.
+- Specify there the path to ``resources/lua_api`` in your OpenMW installation.
+- If you use `openmw_aux`_, add ``resources/vfs`` as an additional external source folder.
+
+.. image:: https://gitlab.com/OpenMW/openmw-docs/raw/master/docs/source/reference/lua-scripting/_static/lua-ide-import-api.png
+
+- Press `Finish`. Create a new Lua file.
+- Now you have code completion! Press ``Ctrl+Space`` in any place to see the variants.
+
+.. image:: https://gitlab.com/OpenMW/openmw-docs/raw/master/docs/source/reference/lua-scripting/_static/lua-ide-code-completion1.png
+
+In some cases LDT can deduce types automatically, but it is not always possible.
+You can add special hints to give LDT more information:
+
+- Before function definition: ``--- @param TYPE argName``
+- Before variable definition: ``--- @field TYPE variableName``
+
+.. code-block:: Lua
+
+    --- @param openmw.core#GameObject obj
+    local function doSomething(obj)
+        -- autocompletion now works with `obj`
+    end
+
+    --- @field openmw.util#Vector3 c
+    local c
+
+    -- autocompletion now works with `c`
+
+.. image:: https://gitlab.com/OpenMW/openmw-docs/raw/master/docs/source/reference/lua-scripting/_static/lua-ide-code-completion2.png
+
+See `LDT Documentation Language <https://wiki.eclipse.org/LDT/User_Area/Documentation_Language>`__ for more details.
+
 
diff --git a/files/CMakeLists.txt b/files/CMakeLists.txt
index 7e1e9059bd..cea33f0f40 100644
--- a/files/CMakeLists.txt
+++ b/files/CMakeLists.txt
@@ -2,3 +2,4 @@ add_subdirectory(mygui)
 add_subdirectory(shaders)
 add_subdirectory(vfs)
 add_subdirectory(builtin_scripts)
+add_subdirectory(lua_api)
diff --git a/files/lua_api/CMakeLists.txt b/files/lua_api/CMakeLists.txt
new file mode 100644
index 0000000000..8c5b46e8db
--- /dev/null
+++ b/files/lua_api/CMakeLists.txt
@@ -0,0 +1,21 @@
+set(LUA_API_FILES
+    README.md
+    coroutine.doclua
+    global.doclua
+    math.doclua
+    string.doclua
+    table.doclua
+    openmw/async.lua
+    openmw/core.lua
+    openmw/nearby.lua
+    openmw/query.lua
+    openmw/self.lua
+    openmw/ui.lua
+    openmw/util.lua
+    openmw/world.lua
+)
+
+foreach (f ${LUA_API_FILES})
+    copy_resource_file("${CMAKE_CURRENT_SOURCE_DIR}/${f}" "${OpenMW_BINARY_DIR}" "resources/lua_api/${f}")
+endforeach (f)
+
diff --git a/files/lua_api/README.md b/files/lua_api/README.md
new file mode 100644
index 0000000000..72f819734c
--- /dev/null
+++ b/files/lua_api/README.md
@@ -0,0 +1,13 @@
+Files in this directory describe OpenMW API for [Lua Development Tools](https://www.eclipse.org/ldt/) (LDT).
+
+`*.doclua` files are taken (with some modifications) from LDT distribution and are distributed under `MIT` license.
+Openmw-specific docs (`openmw/*.lua`) are under `GPLv3` license.
+
+To get a Lua IDE with integrated OpenMW documentation and code autocompletion do the following:
+
+1. Install and run [LDT](https://www.eclipse.org/ldt/#installation).
+2. Press `File` / `New` / `Lua Project` in menu.
+3. Specify project name (for example the title of your omwaddon)
+4. Set `Targeted Execution Environment` to `No Execution Environment`, and `Target Grammar` to `lua-5.1`.
+5. Press `Next`, choose the `Libraries` tab, and click `Add External Source Folder`. Then specify there the path to this directory.
+6. Press `Finish`.
diff --git a/files/lua_api/coroutine.doclua b/files/lua_api/coroutine.doclua
new file mode 100644
index 0000000000..3bd0358ea4
--- /dev/null
+++ b/files/lua_api/coroutine.doclua
@@ -0,0 +1,71 @@
+-------------------------------------------------------------------------------
+-- Coroutine Manipulation.
+-- The operations related to coroutines comprise a sub-library of the basic library 
+-- and come inside the table coroutine.
+-- See http://www.lua.org/manual/5.1/manual.html#2.11 for a general description of coroutines.
+-- @module coroutine
+
+
+
+-------------------------------------------------------------------------------
+-- Creates a new coroutine, with body `f`. `f` must be a Lua
+-- function. Returns this new coroutine, an object with type `"thread"`.
+-- @function [parent=#coroutine] create
+-- @param f a function used as coroutine body.  
+-- @return #thread a new coroutine.
+
+-------------------------------------------------------------------------------
+-- Starts or continues the execution of coroutine `co`. The first time
+-- you resume a coroutine, it starts running its body. The values `val1`,
+-- ... are passed as the arguments to the body function. If the coroutine
+-- has yielded, `resume` restarts it; the values `val1`, ... are passed
+-- as the results from the yield.
+-- 
+-- If the coroutine runs without any errors, `resume` returns true plus any
+-- values passed to `yield` (if the coroutine yields) or any values returned
+-- by the body function (if the coroutine terminates). If there is any error,
+-- `resume` returns false plus the error message.
+-- @function [parent=#coroutine] resume
+-- @param #thread co coroutine to start or resume.
+-- @param ... arguments passed to the body function or as result of yield call.
+-- @return #boolean true plus any values passed to `yield` (if the coroutine yields) or any values returned
+-- by the body function (if the coroutine terminates)
+-- @return #boolean false plus an error message.
+
+-------------------------------------------------------------------------------
+-- Returns the running coroutine, or nil when called by the main thread.
+-- @function [parent=#coroutine] running
+-- @return #thread the running coroutine, or nil when called by the main thread.
+
+-------------------------------------------------------------------------------
+-- Returns the status of coroutine `co`, as a string: `"running"`, if
+-- the coroutine is running (that is, it called `status`); `"suspended"`, if
+-- the coroutine is suspended in a call to `yield`, or if it has not started
+-- running yet; `"normal"` if the coroutine is active but not running (that
+-- is, it has resumed another coroutine); and `"dead"` if the coroutine has
+-- finished its body function, or if it has stopped with an error.
+-- @function [parent=#coroutine] status
+-- @param #thread co a coroutine
+-- @return #string the status : `"running"`, `"suspended"`, `"normal"` or `"dead"`.
+
+-------------------------------------------------------------------------------
+-- Creates a new coroutine, with body `f`. `f` must be a Lua
+-- function. Returns a function that resumes the coroutine each time it is
+-- called. Any arguments passed to the function behave as the extra arguments to
+-- `resume`. Returns the same values returned by `resume`, except the first
+-- boolean. In case of error, propagates the error.
+-- @function [parent=#coroutine] wrap
+-- @param f a function used as coroutine body. 
+-- @param ... arguments passed to the body function or as result of yield call.
+-- @return Any values passed to `yield` (if the coroutine yields) or any values returned
+-- by the body function (if the coroutine terminates).
+
+-------------------------------------------------------------------------------
+-- Suspends the execution of the calling coroutine. The coroutine cannot
+-- be running a C function, a metamethod, or an iterator. Any arguments to
+-- `yield` are passed as extra results to `resume`.
+-- @function [parent=#coroutine] yield
+-- @param ... arguments passed as extra results to `resume` function.
+-- @return Any values passed to the `resume` function.
+
+return nil
diff --git a/files/lua_api/global.doclua b/files/lua_api/global.doclua
new file mode 100644
index 0000000000..04f917980f
--- /dev/null
+++ b/files/lua_api/global.doclua
@@ -0,0 +1,269 @@
+-------------------------------------------------------------------------------
+-- Lua global variables.
+-- The basic library provides some core functions to Lua.
+-- All the preloaded module of Lua are declared here.
+-- @module global
+
+------------------------------------------------------------------------------
+-- This library provides generic functions for coroutine manipulation.
+-- This is a global variable which hold the preloaded @{coroutine} module.
+-- @field[parent = #global] coroutine#coroutine coroutine preloaded module
+
+------------------------------------------------------------------------------
+-- This library provides generic functions for string manipulation.
+-- This is a global variable which hold the preloaded @{string} module.
+-- @field[parent = #global] string#string string preloaded module
+
+------------------------------------------------------------------------------
+-- This library provides generic functions for table manipulation.
+-- This is a global variable which hold the preloaded @{table} module.
+-- @field[parent = #global] table#table table preloaded module
+
+------------------------------------------------------------------------------
+-- This library is an interface to the standard C math library.
+-- This is a global variable which hold the preloaded @{math} module.
+-- @field[parent = #global] math#math math preloaded module
+
+------------------------------------------------------------------------------
+-- This library is an interface to the standard C math library.
+-- This is a global variable which hold the preloaded @{omwutil} module.
+-- @field[parent = #global] omwutil#omwutil ou preloaded module
+
+-------------------------------------------------------------------------------
+-- Issues an error when the value of its argument `v` is false (i.e.,
+-- **nil** or **false**); otherwise, returns all its arguments. `message` is an error
+-- message; when absent, it defaults to *"assertion failed!"*.
+-- @function [parent=#global] assert
+-- @param v if this argument is false an error is issued.
+-- @param #string message an error message. defaults value is *"assertion failed"*.
+-- @return All its arguments.
+
+-------------------------------------------------------------------------------
+-- Terminates the last protected function called and returns `message`
+-- as the error message. Function `error` never returns.
+--
+-- Usually, `error` adds some information about the error position at the
+-- beginning of the message. The `level` argument specifies how to get the
+-- error position.  
+-- With level 1 (the default), the error position is where the
+-- `error` function was called.  
+-- Level 2 points the error to where the function
+-- that called `error` was called; and so on.  
+-- Passing a level 0 avoids the addition of error position information to the message.
+-- @function [parent=#global] error
+-- @param #string message an error message.
+-- @param #number level specifies how to get the error position, default value is `1`.
+
+-------------------------------------------------------------------------------
+-- If `object` does not have a metatable, returns nil. Otherwise, if the
+-- object's metatable has a `"__metatable"` field, returns the associated
+-- value. Otherwise, returns the metatable of the given object.
+-- @function [parent=#global] getmetatable
+-- @param object
+-- @return #table the metatable of object.
+
+-------------------------------------------------------------------------------
+-- Use to iterate over a table by index.
+-- Returns three values: an iterator function, the table `t`, and 0,
+-- so that the construction :
+-- 
+--     for i,v in ipairs(t) do *body* end
+-- will iterate over the pairs (`1,t[1]`), (`2,t[2]`), ..., up to the
+-- first integer key absent from the table.
+-- @function [parent=#global] ipairs
+-- @param #table t a table by index.
+
+-------------------------------------------------------------------------------
+-- Allows a program to traverse all fields of a table. Its first argument is
+-- a table and its second argument is an index in this table. `next` returns
+-- the next index of the table and its associated value.
+--
+-- When called with nil
+-- as its second argument, `next` returns an initial index and its associated
+-- value. When called with the last index, or with nil in an empty table, `next`
+-- returns nil.
+--
+-- If the second argument is absent, then it is interpreted as
+-- nil. In particular, you can use `next(t)` to check whether a table is empty.
+-- The order in which the indices are enumerated is not specified, *even for
+-- numeric indices*. (To traverse a table in numeric order, use a numerical
+-- for or the `ipairs` function.)
+--
+-- The behavior of `next` is *undefined* if, during the traversal, you assign
+-- any value to a non-existent field in the table. You may however modify
+-- existing fields. In particular, you may clear existing fields.
+-- @function [parent=#global] next
+-- @param #table table table to traverse.
+-- @param index initial index.
+
+-------------------------------------------------------------------------------
+-- Use to iterate over a table.
+-- Returns three values: the `next` function, the table `t`, and nil,
+-- so that the construction :
+-- 
+--     for k,v in pairs(t) do *body* end
+-- will iterate over all key-value pairs of table `t`.
+-- 
+-- See function `next` for the caveats of modifying the table during its
+-- traversal.
+-- @function [parent=#global] pairs
+-- @param #table t table to traverse.
+
+-------------------------------------------------------------------------------
+-- Calls function `f` with the given arguments in *protected mode*. This
+-- means that any error inside `f` is not propagated; instead, `pcall` catches
+-- the error and returns a status code. Its first result is the status code (a
+-- boolean), which is true if the call succeeds without errors. In such case,
+-- `pcall` also returns all results from the call, after this first result. In
+-- case of any error, `pcall` returns false plus the error message.
+-- @function [parent=#global] pcall
+-- @param f function to be call in *protected mode*.
+-- @param ... function arguments.
+-- @return #boolean true plus the result of `f` function if its call succeeds without errors.
+-- @return #boolean,#string  false plus the error message in case of any error.
+
+-------------------------------------------------------------------------------
+-- Receives any number of arguments, and prints their values to OpenMW log,
+-- using the `tostring` function to convert them to strings. `print` is not
+-- intended for formatted output, but only as a quick way to show a value,
+-- typically for debugging. For formatted output, use `string.format`.
+-- 
+-- @function [parent=#global] print
+-- @param ... values to print to `stdout`.
+
+-------------------------------------------------------------------------------
+-- Checks whether `v1` is equal to `v2`, without invoking any
+-- metamethod. Returns a boolean.
+-- @function [parent=#global] rawequal
+-- @param v1
+-- @param v2
+-- @return #boolean true if `v1` is equal to `v2`. 
+
+-------------------------------------------------------------------------------
+-- Gets the real value of `table[index]`, without invoking any
+-- metamethod. `table` must be a table; `index` may be any value.
+-- @function [parent=#global] rawget
+-- @param #table table
+-- @param index may be any value.
+-- @return The real value of `table[index]`, without invoking any
+-- metamethod.
+
+-------------------------------------------------------------------------------
+-- Sets the real value of `table[index]` to `value`, without invoking any
+-- metamethod. `table` must be a table, `index` any value different from nil,
+-- and `value` any Lua value.  
+-- This function returns `table`.
+-- @function [parent=#global] rawset
+-- @param #table table
+-- @param index any value different from nil.
+-- @param value any Lua value.
+
+-------------------------------------------------------------------------------
+-- If `index` is a number, returns all arguments after argument number
+-- `index`. Otherwise, `index` must be the string `"#"`, and `select` returns
+-- the total number of extra arguments it received.
+-- @function [parent=#global] select
+-- @param index a number or the string `"#"`
+-- @param ...
+
+-------------------------------------------------------------------------------
+-- Sets the metatable for the given table. (You cannot change the metatable
+-- of other types from Lua, only from C.) If `metatable` is nil, removes the
+-- metatable of the given table. If the original metatable has a `"__metatable"`
+-- field, raises an error.  
+-- This function returns `table`.
+-- @function [parent=#global] setmetatable
+-- @param #table table 
+-- @param #table metatable
+-- @return The first argument `table`. 
+
+-------------------------------------------------------------------------------
+-- Tries to convert its argument to a number. If the argument is already
+-- a number or a string convertible to a number, then `tonumber` returns this
+-- number; otherwise, it returns **nil.**
+--
+-- An optional argument specifies the base to interpret the numeral. The base
+-- may be any integer between 2 and 36, inclusive. In bases above 10, the
+-- letter '`A`' (in either upper or lower case) represents 10, '`B`' represents
+-- 11, and so forth, with '`Z`' representing 35. In base 10 (the default),
+-- the number can have a decimal part, as well as an optional exponent part.
+-- In other bases, only unsigned integers are accepted.
+-- @function [parent=#global] tonumber
+-- @param e a number or string to convert to a number.
+-- @param #number base the base to interpret the numeral, any integer between 2 and 36.(default is 10).
+-- @return #number a number if conversion succeeds else **nil**.
+
+-------------------------------------------------------------------------------
+-- Receives an argument of any type and converts it to a string in a
+-- reasonable format. For complete control of how numbers are converted, use
+-- `string.format`.
+--
+-- If the metatable of `e` has a `"__tostring"` field, then `tostring` calls
+-- the corresponding value with `e` as argument, and uses the result of the
+-- call as its result.
+-- @function [parent=#global] tostring
+-- @param e an argument of any type.
+-- @return #string a string in a reasonable format.
+
+-------------------------------------------------------------------------------
+-- Returns the type of its only argument, coded as a string. The possible
+-- results of this function are "
+-- `nil`" (a string, not the value nil), "`number`", "`string`", "`boolean`",
+-- "`table`", "`function`", "`thread`", and "`userdata`".
+-- @function [parent=#global] type
+-- @param v any value.
+-- @return #string the type of `v`.
+
+-------------------------------------------------------------------------------
+-- Returns the elements from the given table. This function is equivalent to
+-- 
+--     return list[i], list[i+1], ..., list[j]
+-- except that the above code can be written only for a fixed number of
+-- elements. By default, `i` is 1 and `j` is the length of the list, as
+-- defined by the length operator.
+-- @function [parent=#global] unpack
+-- @param #table list a table by index
+-- @param i index of first value.
+-- @param j index of last value.
+
+-------------------------------------------------------------------------------
+-- A global variable (not a function) that holds a string containing the
+-- current interpreter version. The current contents of this variable is
+-- "`Lua 5.1`".
+-- @field [parent = #global] #string _VERSION
+
+-------------------------------------------------------------------------------
+-- This function is similar to `pcall`, except that you can set a new
+-- error handler.
+--
+-- `xpcall` calls function `f` in protected mode, using `err` as the error
+-- handler. Any error inside `f` is not propagated; instead, `xpcall` catches
+-- the error, calls the `err` function with the original error object, and
+-- returns a status code. Its first result is the status code (a boolean),
+-- which is true if the call succeeds without errors. In this case, `xpcall`
+-- also returns all results from the call, after this first result. In case
+-- of any error, `xpcall` returns false plus the result from `err`.
+-- @function [parent=#global] xpcall
+-- @param f function to be call in *protected mode*.
+-- @param err function used as error handler.
+-- @return #boolean true plus the result of `f` function if its call succeeds without errors.
+-- @return #boolean,#string  false plus the result of `err` function. 
+
+-------------------------------------------------------------------------------
+-- Loads the given module. 
+-- If the requested module is one of the allowed standard libraries
+-- (`coroutine`, `math`, `string`, `table`), then returns the library.
+-- If it is one of the built-in OpenMW API packages, then returns the package.
+-- Otherwise it searches for a Lua source file with such name in OpenMW data folders.
+-- For example `require('my_lua_library.something')` will try to open the file
+-- `my_lua_library/something.lua`.
+--
+-- Loading DLLs and precompiled Lua files is intentionally prohibited for reasons
+-- of safety and compatibility between different platforms.
+--
+-- If there is any error loading or running the module, or if it cannot find
+-- any loader for the module, then `require` signals an error.
+-- @function [parent=#global] require
+-- @param #string modname name of module to load.
+
+return nil
diff --git a/files/lua_api/math.doclua b/files/lua_api/math.doclua
new file mode 100644
index 0000000000..7601c4d8b7
--- /dev/null
+++ b/files/lua_api/math.doclua
@@ -0,0 +1,200 @@
+-------------------------------------------------------------------------------
+-- Mathematical Functions.
+-- This library is an interface to the standard C math library.
+-- It provides all its functions inside the table math.
+-- @module math
+
+
+
+-------------------------------------------------------------------------------
+-- Returns the absolute value of `x`.
+-- @function [parent=#math] abs
+-- @param #number x
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Returns the arc cosine of `x` (in radians).
+-- @function [parent=#math] acos
+-- @param #number x
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Returns the arc sine of `x` (in radians).
+-- @function [parent=#math] asin
+-- @param #number x
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Returns the arc tangent of `x` (in radians).
+-- @function [parent=#math] atan
+-- @param #number x
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Returns the arc tangent of `y/x` (in radians), but uses the signs
+-- of both parameters to find the quadrant of the result. (It also handles
+-- correctly the case of `x` being zero.)
+-- @function [parent=#math] atan2
+-- @param #number y
+-- @param #number x
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Returns the smallest integer larger than or equal to `x`.
+-- @function [parent=#math] ceil
+-- @param #number x
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Returns the cosine of `x` (assumed to be in radians).
+-- @function [parent=#math] cos
+-- @param #number x
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Returns the hyperbolic cosine of `x`.
+-- @function [parent=#math] cosh
+-- @param #number x
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Returns the angle `x` (given in radians) in degrees.
+-- @function [parent=#math] deg
+-- @param #number x
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Returns the value *e^x*.
+-- @function [parent=#math] exp
+-- @param #number x
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Returns the largest integer smaller than or equal to `x`.
+-- @function [parent=#math] floor
+-- @param #number x
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Returns the remainder of the division of `x` by `y` that rounds the
+-- quotient towards zero.
+-- @function [parent=#math] fmod
+-- @param #number x
+-- @param #number y
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Returns `m` and `e` such that *x = m2^e*, `e` is an integer and the
+-- absolute value of `m` is in the range *[0.5, 1)* (or zero when `x` is zero).
+-- @function [parent=#math] frexp
+-- @param #number x
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- The value `HUGE_VAL`, a value larger than or equal to any other
+-- numerical value.
+-- @field [parent=#math] #number huge
+
+-------------------------------------------------------------------------------
+-- Returns *m2^e* (`e` should be an integer).
+-- @function [parent=#math] ldexp
+-- @param #number m
+-- @param #number e
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Returns the natural logarithm of `x`.
+-- @function [parent=#math] log
+-- @param #number x
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Returns the base-10 logarithm of `x`.
+-- @function [parent=#math] log10
+-- @param #number x
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Returns the maximum value among its arguments.
+-- @function [parent=#math] max
+-- @param #number x
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Returns the minimum value among its arguments.
+-- @function [parent=#math] min
+-- @param #number x
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Returns two numbers, the integral part of `x` and the fractional part of
+-- `x`.
+-- @function [parent=#math] modf
+-- @param #number x
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- The value of *pi*.
+-- @field [parent=#math] #number pi
+
+-------------------------------------------------------------------------------
+-- Returns *x^y*. (You can also use the expression `x^y` to compute this
+-- value.)
+-- @function [parent=#math] pow
+-- @param #number x
+-- @param #number y
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Returns the angle `x` (given in degrees) in radians.
+-- @function [parent=#math] rad
+-- @param #number x
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- This function is an interface to the simple pseudo-random generator
+-- function `rand` provided by ANSI C. (No guarantees can be given for its
+-- statistical properties.)
+-- 
+-- When called without arguments, returns a uniform pseudo-random real
+-- number in the range *[0,1)*. When called with an integer number `m`,
+-- `math.random` returns a uniform pseudo-random integer in the range *[1,
+-- m]*. When called with two integer numbers `m` and `n`, `math.random`
+-- returns a uniform pseudo-random integer in the range *[m, n]*.
+-- @function [parent=#math] random
+-- @param #number m
+-- @param #number n
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Returns the sine of `x` (assumed to be in radians).
+-- @function [parent=#math] sin
+-- @param #number x
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Returns the hyperbolic sine of `x`.
+-- @function [parent=#math] sinh
+-- @param #number x
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Returns the square root of `x`. (You can also use the expression `x^0.5`
+-- to compute this value.)
+-- @function [parent=#math] sqrt
+-- @param #number x
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Returns the tangent of `x` (assumed to be in radians).
+-- @function [parent=#math] tan
+-- @param #number x
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Returns the hyperbolic tangent of `x`.
+-- @function [parent=#math] tanh
+-- @param #number x
+-- @return #number
+
+return nil
diff --git a/files/lua_api/openmw/README.md b/files/lua_api/openmw/README.md
new file mode 100644
index 0000000000..4af9922b79
--- /dev/null
+++ b/files/lua_api/openmw/README.md
@@ -0,0 +1,14 @@
+`*.lua` files from this dir are also used to generate html documentation.
+
+After every change run the following commands to update it:
+
+```
+luadocumentor -f doc -d ../../../docs/source/generated-luadoc/lua-api-reference *.lua
+sed -i 's/openmw\.\(\w*\)\(\#\|\.html\)/\1\2/g' ../../../docs/source/generated-luadoc/lua-api-reference/*.html
+```
+
+`luadocumentor` can be installed via `luarocks`:
+
+```
+luarocks install luadocumentor
+```
diff --git a/files/lua_api/openmw/async.lua b/files/lua_api/openmw/async.lua
new file mode 100644
index 0000000000..68f63b5193
--- /dev/null
+++ b/files/lua_api/openmw/async.lua
@@ -0,0 +1,52 @@
+-------------------------------------------------------------------------------
+-- `openmw.async` contains timers and coroutine utils. All functions require
+-- the package itself as a first argument.
+-- @module async
+-- @usage local async = require('openmw.async')
+
+
+
+-------------------------------------------------------------------------------
+-- Register a function as a timer callback.
+-- @function [parent=#async] registerTimerCallback
+-- @param self
+-- @param #string name
+-- @param #function func
+-- @return #TimerCallback
+
+-------------------------------------------------------------------------------
+-- Calls callback(arg) in `delay` seconds.
+-- Callback must be registered in advance.
+-- @function [parent=#async] newTimerInSeconds
+-- @param self
+-- @param #number delay
+-- @param #TimerCallback callback A callback returned by `registerTimerCallback`
+-- @param arg An argument for `callback`; can be `nil`.
+
+-------------------------------------------------------------------------------
+-- Calls callback(arg) in `delay` game hours.
+-- Callback must be registered in advance.
+-- @function [parent=#async] newTimerInHours
+-- @param self
+-- @param #number delay
+-- @param #TimerCallback callback A callback returned by `registerTimerCallback`
+-- @param arg An argument for `callback`; can be `nil`.
+
+-------------------------------------------------------------------------------
+-- Calls `func()` in `delay` seconds.
+-- The timer will be lost if the game is saved and loaded.
+-- @function [parent=#async] newUnsavableTimerInSeconds
+-- @param self
+-- @param #number delay
+-- @param #function func
+
+-------------------------------------------------------------------------------
+-- Calls `func()` in `delay` game hours.
+-- The timer will be lost if the game is saved and loaded.
+-- @function [parent=#async] newUnsavableTimerInHours
+-- @param self
+-- @param #number delay
+-- @param #function func
+
+return nil
+
diff --git a/files/lua_api/openmw/core.lua b/files/lua_api/openmw/core.lua
new file mode 100644
index 0000000000..6b38fc20e1
--- /dev/null
+++ b/files/lua_api/openmw/core.lua
@@ -0,0 +1,328 @@
+-------------------------------------------------------------------------------
+-- `openmw.core` defines functions and types that are available in both local
+-- and global scripts.
+-- @module core
+-- @usage local core = require('openmw.core')
+
+
+
+-------------------------------------------------------------------------------
+-- The version of OpenMW Lua API. It is an integer that is incremented every time the API is changed.
+-- @field [parent=#core] #number API_VERSION
+
+-------------------------------------------------------------------------------
+-- Send an event to global scripts.
+-- @function [parent=#core] sendGlobalEvent
+-- @param #string eventName
+-- @param eventData
+
+-------------------------------------------------------------------------------
+-- Game time in seconds.
+-- The number of seconds in the game world, passed from starting a new game.
+-- @function [parent=#core] getGameTimeInSeconds
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Current time of the game world in hours.
+-- Note that the number of game seconds in a game hour is not guaranteed to be fixed.
+-- @function [parent=#core] getGameTimeInHours
+-- @return #number
+
+
+-------------------------------------------------------------------------------
+-- @type OBJECT_TYPE
+-- @field [parent=#OBJECT_TYPE] #string Activator "Activator"
+-- @field [parent=#OBJECT_TYPE] #string Armor "Armor"
+-- @field [parent=#OBJECT_TYPE] #string Book "Book"
+-- @field [parent=#OBJECT_TYPE] #string Clothing "Clothing"
+-- @field [parent=#OBJECT_TYPE] #string Container "Container"
+-- @field [parent=#OBJECT_TYPE] #string Creature "Creature"
+-- @field [parent=#OBJECT_TYPE] #string Door "Door"
+-- @field [parent=#OBJECT_TYPE] #string Ingredient "Ingredient"
+-- @field [parent=#OBJECT_TYPE] #string Light "Light"
+-- @field [parent=#OBJECT_TYPE] #string Miscellaneous "Miscellaneous"
+-- @field [parent=#OBJECT_TYPE] #string NPC "NPC"
+-- @field [parent=#OBJECT_TYPE] #string Player "Player"
+-- @field [parent=#OBJECT_TYPE] #string Potion "Potion"
+-- @field [parent=#OBJECT_TYPE] #string Static "Static"
+-- @field [parent=#OBJECT_TYPE] #string Weapon "Weapon"
+
+-------------------------------------------------------------------------------
+-- Possible `object.type` values.
+-- @field [parent=#core] #OBJECT_TYPE OBJECT_TYPE
+
+
+-------------------------------------------------------------------------------
+-- @type EQUIPMENT_SLOT
+-- @field [parent=#EQUIPMENT_SLOT] #number Helmet
+-- @field [parent=#EQUIPMENT_SLOT] #number Cuirass
+-- @field [parent=#EQUIPMENT_SLOT] #number Greaves
+-- @field [parent=#EQUIPMENT_SLOT] #number LeftPauldron
+-- @field [parent=#EQUIPMENT_SLOT] #number RightPauldron
+-- @field [parent=#EQUIPMENT_SLOT] #number LeftGauntlet
+-- @field [parent=#EQUIPMENT_SLOT] #number RightGauntlet
+-- @field [parent=#EQUIPMENT_SLOT] #number Boots
+-- @field [parent=#EQUIPMENT_SLOT] #number Shirt
+-- @field [parent=#EQUIPMENT_SLOT] #number Pants
+-- @field [parent=#EQUIPMENT_SLOT] #number Skirt
+-- @field [parent=#EQUIPMENT_SLOT] #number Robe
+-- @field [parent=#EQUIPMENT_SLOT] #number LeftRing
+-- @field [parent=#EQUIPMENT_SLOT] #number RightRing
+-- @field [parent=#EQUIPMENT_SLOT] #number Amulet
+-- @field [parent=#EQUIPMENT_SLOT] #number Belt
+-- @field [parent=#EQUIPMENT_SLOT] #number CarriedRight
+-- @field [parent=#EQUIPMENT_SLOT] #number CarriedLeft
+-- @field [parent=#EQUIPMENT_SLOT] #number Ammunition
+
+-------------------------------------------------------------------------------
+-- Available equipment slots. Used in `object:getEquipment` and `object:setEquipment`.
+-- @field [parent=#core] #EQUIPMENT_SLOT EQUIPMENT_SLOT
+
+
+-------------------------------------------------------------------------------
+-- Any object that exists in the game world and has a specific location.
+-- Player, actors, items, and statics are game objects.
+-- @type GameObject
+-- @field [parent=#GameObject] openmw.util#Vector3 position Object position.
+-- @field [parent=#GameObject] openmw.util#Vector3 rotation Object rotation (ZXY order).
+-- @field [parent=#GameObject] #Cell cell The cell where the object currently is. During loading a game and for objects in an inventory or a container `cell` is nil.
+-- @field [parent=#GameObject] #string type Type of the object (see @{openmw.core#OBJECT_TYPE}).
+-- @field [parent=#GameObject] #number count Count (makes sense if holded in a container).
+-- @field [parent=#GameObject] #string recordId Record ID.
+-- @field [parent=#GameObject] #Inventory inventory Inventory of an Player/NPC or content of an container.
+-- @field [parent=#GameObject] #boolean isTeleport `True` if it is a teleport door (only if `object.type` == "Door").
+-- @field [parent=#GameObject] openmw.util#Vector3 destPosition Destination (only if a teleport door).
+-- @field [parent=#GameObject] openmw.util#Vector3 destRotation Destination rotation (only if a teleport door).
+-- @field [parent=#GameObject] #string destCell Destination cell (only if a teleport door).
+
+-------------------------------------------------------------------------------
+-- Is the object still exists/available.
+-- Returns true if the object exists and loaded, and false otherwise. If false, then every
+-- access to the object will raise an error.
+-- @function [parent=#GameObject] isValid
+-- @param self
+-- @return #boolean
+
+-------------------------------------------------------------------------------
+-- Returns true if the object is an actor and is able to move. For dead, paralized,
+-- or knocked down actors in returns false.
+-- access to the object will raise an error.
+-- @function [parent=#GameObject] canMove
+-- @param self
+-- @return #boolean
+
+-------------------------------------------------------------------------------
+-- Speed of running. Returns 0 if not an actor, but for dead actors it still returns a positive value.
+-- @function [parent=#GameObject] getRunSpeed
+-- @param self
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Speed of walking. Returns 0 if not an actor, but for dead actors it still returns a positive value.
+-- @function [parent=#GameObject] getWalkSpeed
+-- @param self
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Send local event to the object.
+-- @function [parent=#GameObject] sendEvent
+-- @param self
+-- @param #string eventName
+-- @param eventData
+
+-------------------------------------------------------------------------------
+-- Returns `true` if the item is equipped on the object.
+-- @function [parent=#GameObject] isEquipped
+-- @param self
+-- @param #GameObject item
+-- @return #boolean
+
+-------------------------------------------------------------------------------
+-- Get equipment.
+-- Returns a table `slot` -> `GameObject` of currently equipped items.
+-- See @{openmw.core#EQUIPMENT_SLOT}. Returns empty table if the object doesn't have
+-- equipment slots.
+-- @function [parent=#GameObject] getEquipment
+-- @param self
+-- @return #map<#number,#GameObject>
+
+-------------------------------------------------------------------------------
+-- Set equipment.
+-- Keys in the table are equipment slots (see @{openmw.core#EQUIPMENT_SLOT}). Each
+-- value can be either a `GameObject` or recordId. Raises an error if
+-- the object doesn't have equipment slots and table is not empty. Can be
+-- called only on self or from a global script.
+-- @function [parent=#GameObject] setEquipment
+-- @param self
+-- @param equipment
+
+-------------------------------------------------------------------------------
+-- Add new local script to the object.
+-- Can be called only from a global script.
+-- @function [parent=#GameObject] addScript
+-- @param self
+-- @param #string scriptPath Path to the script in OpenMW virtual filesystem
+
+-------------------------------------------------------------------------------
+-- Moves object to given cell and position.
+-- The effect is not immediate: the position will be updated only in the next
+-- frame. Can be called only from a global script.
+-- @function [parent=#GameObject] teleport
+-- @param self
+-- @param #string cellName Name of the cell to teleport into. For exteriors can be empty.
+-- @param openmw.util#Vector3 position New position
+-- @param openmw.util#Vector3 rotation New rotation. Optional argument. If missed, then the current rotation is used.
+
+
+-------------------------------------------------------------------------------
+-- List of GameObjects.
+-- @type ObjectList
+-- @extends #list<#GameObject>
+
+-------------------------------------------------------------------------------
+-- Create iterator.
+-- @function [parent=#ObjectList] ipairs
+-- @param self
+
+-------------------------------------------------------------------------------
+-- Filter list with a Query.
+-- @function [parent=#ObjectList] select
+-- @param self
+-- @param openmw.query#Query query
+-- @return #ObjectList
+
+
+-------------------------------------------------------------------------------
+-- A cell of the game world.
+-- @type Cell
+-- @field [parent=#Cell] #string name Name of the cell (can be empty string).
+-- @field [parent=#Cell] #string region Region of the cell.
+-- @field [parent=#Cell] #boolean isExterior Is it exterior or interior.
+-- @field [parent=#Cell] #number gridX Index of the cell by X (only for exteriors).
+-- @field [parent=#Cell] #number gridY Index of the cell by Y (only for exteriors).
+-- @field [parent=#Cell] #boolean hasWater True if the cell contains water.
+
+-------------------------------------------------------------------------------
+-- Returns true either if the cell contains the object or if the cell is an exterior and the object is also in an exterior.
+-- @function [parent=#Cell] isInSameSpace
+-- @param self
+-- @param #GameObject object
+-- @return #boolean
+-- @usage
+-- if obj1.cell:isInSameSpace(obj2) then
+--     dist = (obj1.position - obj2.position):length()
+-- else
+--     -- the distance can't be calculated because the coordinates are in different spaces
+-- end
+
+-------------------------------------------------------------------------------
+-- Select objects from the cell with a Query (only in global scripts).
+-- Returns an empty list if the cell is not loaded.
+-- @function [parent=#Cell] selectObjects
+-- @param self
+-- @param openmw.query#Query query
+-- @return #ObjectList
+
+
+-------------------------------------------------------------------------------
+-- Inventory of a player/NPC or a content of a container.
+-- @type Inventory
+
+-------------------------------------------------------------------------------
+-- The number of items with given recordId.
+-- @function [parent=#Inventory] countOf
+-- @param self
+-- @param #string recordId
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Get all content of the inventory.
+-- @function [parent=#Inventory] getAll
+-- @param self
+-- @return #ObjectList
+
+-------------------------------------------------------------------------------
+-- Get all potions.
+-- @function [parent=#Inventory] getPotions
+-- @param self
+-- @return #ObjectList
+
+-------------------------------------------------------------------------------
+-- Get all apparatuses.
+-- @function [parent=#Inventory] getApparatuses
+-- @param self
+-- @return #ObjectList
+
+-------------------------------------------------------------------------------
+-- Get all armor.
+-- @function [parent=#Inventory] getArmor
+-- @param self
+-- @return #ObjectList
+
+-------------------------------------------------------------------------------
+-- Get all books.
+-- @function [parent=#Inventory] getBooks
+-- @param self
+-- @return #ObjectList
+
+-------------------------------------------------------------------------------
+-- Get all clothing.
+-- @function [parent=#Inventory] getClothing
+-- @param self
+-- @return #ObjectList
+
+-------------------------------------------------------------------------------
+-- Get all ingredients.
+-- @function [parent=#Inventory] getIngredients
+-- @param self
+-- @return #ObjectList
+
+-------------------------------------------------------------------------------
+-- Get all lights.
+-- @function [parent=#Inventory] getLights
+-- @param self
+-- @return #ObjectList
+
+-------------------------------------------------------------------------------
+-- Get all lockpicks.
+-- @function [parent=#Inventory] getLockpicks
+-- @param self
+-- @return #ObjectList
+
+-------------------------------------------------------------------------------
+-- Get all miscellaneous items.
+-- @function [parent=#Inventory] getMiscellaneous
+-- @param self
+-- @return #ObjectList
+
+-------------------------------------------------------------------------------
+-- Get all probes.
+-- @function [parent=#Inventory] getProbes
+-- @param self
+-- @return #ObjectList
+
+-------------------------------------------------------------------------------
+-- Get all repair kits.
+-- @function [parent=#Inventory] getRepairKits
+-- @param self
+-- @return #ObjectList
+
+-------------------------------------------------------------------------------
+-- Get all weapon.
+-- @function [parent=#Inventory] getWeapons
+-- @param self
+-- @return #ObjectList
+
+
+-------------------------------------------------------------------------------
+-- Argument of `onKeyPress` engine handler
+-- @type KeyboardEvent
+-- @field [parent=#KeyboardEvent] #string symbol The pressed symbol (1-symbol string).
+-- @field [parent=#KeyboardEvent] #string code Key code.
+-- @field [parent=#KeyboardEvent] #boolean withShift Is `Shift` key pressed.
+-- @field [parent=#KeyboardEvent] #boolean withCtrl Is `Control` key pressed.
+-- @field [parent=#KeyboardEvent] #boolean withAlt Is `Alt` key pressed.
+-- @field [parent=#KeyboardEvent] #boolean withSuper Is `Super`/`Win` key pressed.
+
+return nil
+
diff --git a/files/lua_api/openmw/generate_luadoc.sh b/files/lua_api/openmw/generate_luadoc.sh
new file mode 100755
index 0000000000..2eacf30f9f
--- /dev/null
+++ b/files/lua_api/openmw/generate_luadoc.sh
@@ -0,0 +1,4 @@
+#!/bin/bash
+
+luadocumentor -f doc -d ../../../docs/source/generated-luadoc/lua-api-reference *.lua
+sed -i 's/openmw\.\(\w*\)\(\#\|\.html\)/\1\2/g' ../../../docs/source/generated-luadoc/lua-api-reference/*.html
diff --git a/files/lua_api/openmw/nearby.lua b/files/lua_api/openmw/nearby.lua
new file mode 100644
index 0000000000..c24d5e3d10
--- /dev/null
+++ b/files/lua_api/openmw/nearby.lua
@@ -0,0 +1,36 @@
+-------------------------------------------------------------------------------
+-- `openmw.nearby` provides read-only access to the nearest area of the game world.
+-- Can be used only from local scripts.
+-- @module nearby
+-- @usage local nearby = require('openmw.nearby')
+
+
+
+-------------------------------------------------------------------------------
+-- List of nearby activators.
+-- @field [parent=#nearby] openmw.core#ObjectList activators
+
+-------------------------------------------------------------------------------
+-- List of nearby actors.
+-- @field [parent=#nearby] openmw.core#ObjectList actors
+
+-------------------------------------------------------------------------------
+-- List of nearby containers.
+-- @field [parent=#nearby] openmw.core#ObjectList containers
+
+-------------------------------------------------------------------------------
+-- List of nearby doors.
+-- @field [parent=#nearby] openmw.core#ObjectList doors
+
+-------------------------------------------------------------------------------
+-- Everything that can be picked up in the nearby.
+-- @field [parent=#nearby] openmw.core#ObjectList items
+
+-------------------------------------------------------------------------------
+-- Evaluates a Query.
+-- @function [parent=#nearby] selectObjects
+-- @param openmw.query#Query query
+-- @return openmw.core#ObjectList
+
+return nil
+
diff --git a/files/lua_api/openmw/query.lua b/files/lua_api/openmw/query.lua
new file mode 100644
index 0000000000..9684fb372c
--- /dev/null
+++ b/files/lua_api/openmw/query.lua
@@ -0,0 +1,116 @@
+-------------------------------------------------------------------------------
+-- `openmw.query` constructs queries that can be used in `world.selectObjects` and `nearby.selectObjects`.
+-- @module query
+-- @usage local query = require('openmw.query')
+
+
+
+-------------------------------------------------------------------------------
+-- Query. A Query itself can no return objects. It only holds search conditions.
+-- @type Query
+
+-------------------------------------------------------------------------------
+-- Add condition.
+-- @function [parent=#Query] where
+-- @param self
+-- @param condition
+-- @return #Query
+
+-------------------------------------------------------------------------------
+-- Limit result size.
+-- @function [parent=#Query] limit
+-- @param self
+-- @param #number maxCount
+-- @return #Query
+
+
+-------------------------------------------------------------------------------
+-- A field that can be used in a condition
+-- @type Field
+
+-------------------------------------------------------------------------------
+-- Equal
+-- @function [parent=#Field] eq
+-- @param self
+-- @param value
+
+-------------------------------------------------------------------------------
+-- Not equal
+-- @function [parent=#Field] neq
+-- @param self
+-- @param value
+
+-------------------------------------------------------------------------------
+-- Lesser
+-- @function [parent=#Field] lt
+-- @param self
+-- @param value
+
+-------------------------------------------------------------------------------
+-- Lesser or equal
+-- @function [parent=#Field] lte
+-- @param self
+-- @param value
+
+-------------------------------------------------------------------------------
+-- Greater
+-- @function [parent=#Field] gt
+-- @param self
+-- @param value
+
+-------------------------------------------------------------------------------
+-- Greater or equal
+-- @function [parent=#Field] gte
+-- @param self
+-- @param value
+
+
+-------------------------------------------------------------------------------
+-- @type OBJECT
+-- @field [parent=#OBJECT] #Field type
+-- @field [parent=#OBJECT] #Field recordId
+-- @field [parent=#OBJECT] #Field count
+-- @field [parent=#OBJECT] #CellFields cell
+
+-------------------------------------------------------------------------------
+-- Fields that can be used with any object.
+-- @field [parent=#query] #OBJECT OBJECT
+
+-------------------------------------------------------------------------------
+-- @type DOOR
+-- @field [parent=#DOOR] #Field isTeleport
+-- @field [parent=#DOOR] #CellFields destCell
+
+-------------------------------------------------------------------------------
+-- Fields that can be used only when search for doors.
+-- @field [parent=#query] #DOOR DOOR
+
+-------------------------------------------------------------------------------
+-- @type CellFields
+-- @field [parent=#CellFields] #Field name
+-- @field [parent=#CellFields] #Field region
+-- @field [parent=#CellFields] #Field isExterior
+
+
+-------------------------------------------------------------------------------
+-- Base Query to select activators.
+-- @field [parent=#query] #Query activators
+
+-------------------------------------------------------------------------------
+-- Base Query to select actors.
+-- @field [parent=#query] #Query actors
+
+-------------------------------------------------------------------------------
+-- Base Query to select containers.
+-- @field [parent=#query] #Query containers
+
+-------------------------------------------------------------------------------
+-- Base Query to select doors.
+-- @field [parent=#query] #Query doors
+
+-------------------------------------------------------------------------------
+-- Base Query to select items.
+-- @field [parent=#query] #Query items
+
+return nil
+
diff --git a/files/lua_api/openmw/self.lua b/files/lua_api/openmw/self.lua
new file mode 100644
index 0000000000..b65b20bab2
--- /dev/null
+++ b/files/lua_api/openmw/self.lua
@@ -0,0 +1,68 @@
+-------------------------------------------------------------------------------
+-- `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`.
+-- @module self
+-- @extends openmw.core#GameObject
+-- @usage local self = require('openmw.self')
+-- if self.type == 'Player' then  -- All fields and functions of `GameObject` are available.
+--     self:sendEvent("something", self.position)
+-- end
+
+
+
+-------------------------------------------------------------------------------
+-- Returns true if the script isActive (the object it is attached to is in an active cell).
+-- If it is not active, then `openmw.nearby` can not be used.
+-- @function [parent=#self] isActive
+-- @param self
+-- @return #boolean
+
+-------------------------------------------------------------------------------
+-- The object the script is attached to (readonly)
+-- @field [parent=#self] openmw.core#GameObject object
+
+-------------------------------------------------------------------------------
+-- Movement controls (only for actors)
+-- @field [parent=#self] #ActorControls controls
+
+-------------------------------------------------------------------------------
+-- Allows to view and/or modify controls of an actor. Makes an effect only if
+-- `setDirectControl(true)` was called. All fields are mutable.
+-- @type ActorControls
+-- @field [parent=#ActorControls] #number movement +1 - move forward, -1 - move backward
+-- @field [parent=#ActorControls] #number sideMovement +1 - move right, -1 - move left
+-- @field [parent=#ActorControls] #number turn Turn right (radians); if negative - turn left
+-- @field [parent=#ActorControls] #boolean run true - run, false - walk
+-- @field [parent=#ActorControls] #boolean jump If true - initiate a jump
+
+-------------------------------------------------------------------------------
+-- Enables or disables direct movement control (disabled by default).
+-- @function [parent=#self] setDirectControl
+-- @param self
+-- @param #boolean control
+
+-------------------------------------------------------------------------------
+-- Enables or disables standart AI (enabled by default).
+-- @function [parent=#self] enableAI
+-- @param self
+-- @param #boolean v
+
+-------------------------------------------------------------------------------
+-- Returns current target or nil if not in combat
+-- @function [parent=#self] getCombatTarget
+-- @param self
+-- @return openmw.core#GameObject
+
+-------------------------------------------------------------------------------
+-- Remove all combat packages from the actor.
+-- @function [parent=#self] stopCombat
+-- @param self
+
+-------------------------------------------------------------------------------
+-- Attack `target`.
+-- @function [parent=#self] startCombat
+-- @param self
+-- @param openmw.core#GameObject target
+
+return nil
+
diff --git a/files/lua_api/openmw/ui.lua b/files/lua_api/openmw/ui.lua
new file mode 100644
index 0000000000..bf6976c76b
--- /dev/null
+++ b/files/lua_api/openmw/ui.lua
@@ -0,0 +1,15 @@
+-------------------------------------------------------------------------------
+-- `openmw.ui` controls user interface.
+-- Can be used only by local scripts, that are attached to a player.
+-- @module ui
+-- @usage local ui = require('openmw.ui')
+
+
+
+-------------------------------------------------------------------------------
+-- Shows given message at the bottom of the screen.
+-- @function [parent=#ui] showMessage
+-- @param #string msg
+
+return nil
+
diff --git a/files/lua_api/openmw/util.lua b/files/lua_api/openmw/util.lua
new file mode 100644
index 0000000000..7d31ced408
--- /dev/null
+++ b/files/lua_api/openmw/util.lua
@@ -0,0 +1,150 @@
+-------------------------------------------------------------------------------
+-- `openmw.util` defines utility functions and classes like 3D vectors, that don't depend on the game world.
+-- @module util
+-- @usage local util = require('openmw.util')
+
+
+
+-------------------------------------------------------------------------------
+-- Limits given value to the interval [`from`, `to`]
+-- @function [parent=#util] clamp
+-- @param #number value
+-- @param #number from
+-- @param #number to
+-- @return #number min(max(value, from), to)
+
+-------------------------------------------------------------------------------
+-- Adds `2pi*k` and puts the angle in range `[-pi, pi]`
+-- @function [parent=#util] normalizeAngle
+-- @param #number angle Angle in radians
+-- @return #number Angle in range `[-pi, pi]`
+
+
+-------------------------------------------------------------------------------
+-- Immutable 2D vector
+-- @type Vector2
+-- @field #number x
+-- @field #number y
+-- @usage
+-- v = util.vector2(3, 4)
+-- v.x, v.y       -- 3.0, 4.0
+-- str(v)         -- "(3.0, 4.0)"
+-- v:length()     -- 5.0    length
+-- v:length2()    -- 25.0   square of the length
+-- v:normalize()  -- vector2(3/5, 4/5)
+-- v:rotate(radians)    -- rotate clockwise (returns rotated vector)
+-- v1:dot(v2)     -- dot product (returns a number)
+-- v1 * v2        -- dot product
+-- v1 + v2        -- vector addition
+-- v1 - v2        -- vector subtraction
+-- v1 * x         -- multiplication by a number
+-- v1 / x         -- division by a number
+
+-------------------------------------------------------------------------------
+-- Creates a new 2D vector. Vectors are immutable and can not be changed after creation.
+-- @function [parent=#util] vector2
+-- @param #number x.
+-- @param #number y.
+-- @return #Vector2.
+
+-------------------------------------------------------------------------------
+-- Length of the vector
+-- @function [parent=#Vector2] length
+-- @param self
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Square of the length of the vector
+-- @function [parent=#Vector2] length2
+-- @param self
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Normalizes vector.
+-- Returns two values: normalized vector and the length of the original vector.
+-- It doesn't change the original vector. 
+-- @function [parent=#Vector2] normalize
+-- @param self
+-- @return #Vector2, #number
+
+-------------------------------------------------------------------------------
+-- Rotates 2D vector clockwise.
+-- @function [parent=#Vector2] rotate
+-- @param self
+-- @param #number angle Angle in radians
+-- @return #Vector2 Rotated vector.
+
+-------------------------------------------------------------------------------
+-- Dot product.
+-- @function [parent=#Vector2] dot
+-- @param self
+-- @param #Vector2 v
+-- @return #number
+
+
+-------------------------------------------------------------------------------
+-- Immutable 3D vector
+-- @type Vector3
+-- @field #number x
+-- @field #number y
+-- @field #number z
+-- @usage
+-- v = util.vector3(3, 4, 5)
+-- v.x, v.y, v.z  -- 3.0, 4.0, 5.0
+-- str(v)         -- "(3.0, 4.0, 4.5)"
+-- v:length()     -- length
+-- v:length2()    -- square of the length
+-- v:normalize()  -- normalized vector
+-- v1:dot(v2)     -- dot product (returns a number)
+-- v1 * v2        -- dot product (returns a number)
+-- v1:cross(v2)   -- cross product (returns a vector)
+-- v1 ^ v2        -- cross product (returns a vector)
+-- v1 + v2        -- vector addition
+-- v1 - v2        -- vector subtraction
+-- v1 * x         -- multiplication by a number
+-- v1 / x         -- division by a number
+
+-------------------------------------------------------------------------------
+-- Creates a new 3D vector. Vectors are immutable and can not be changed after creation.
+-- @function [parent=#util] vector3
+-- @param #number x.
+-- @param #number y.
+-- @param #number z.
+-- @return #Vector3.
+
+-------------------------------------------------------------------------------
+-- Length of the vector
+-- @function [parent=#Vector3] length
+-- @param self
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Square of the length of the vector
+-- @function [parent=#Vector3] length2
+-- @param self
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Normalizes vector.
+-- Returns two values: normalized vector and the length of the original vector.
+-- It doesn't change the original vector. 
+-- @function [parent=#Vector3] normalize
+-- @param self
+-- @return #Vector3, #number
+
+-------------------------------------------------------------------------------
+-- Dot product.
+-- @function [parent=#Vector3] dot
+-- @param self
+-- @param #Vector3 v
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Cross product.
+-- @function [parent=#Vector3] cross
+-- @param self
+-- @param #Vector3 v
+-- @return #Vector3
+
+return nil
+
diff --git a/files/lua_api/openmw/world.lua b/files/lua_api/openmw/world.lua
new file mode 100644
index 0000000000..90ea23b4f5
--- /dev/null
+++ b/files/lua_api/openmw/world.lua
@@ -0,0 +1,34 @@
+-------------------------------------------------------------------------------
+-- `openmw.world` is an interface to the game world for global scripts.
+-- Can not be used from local scripts.
+-- @module world
+-- @usage local world = require('openmw.world')
+
+
+
+-------------------------------------------------------------------------------
+-- List of currently active actors.
+-- @field [parent=#world] openmw.core#ObjectList activeActors
+
+-------------------------------------------------------------------------------
+-- Evaluates a Query.
+-- @function [parent=#world] selectObjects
+-- @param openmw.query#Query query
+-- @return openmw.core#ObjectList
+
+-------------------------------------------------------------------------------
+-- Loads a named cell
+-- @function [parent=#world] getCellByName
+-- @param #string cellName
+-- @return openmw.core#Cell
+
+-------------------------------------------------------------------------------
+-- Loads an exterior cell by grid indices
+-- @function [parent=#world] getExteriorCell
+-- @param #number gridX
+-- @param #number gridY
+-- @return openmw.core#Cell
+
+
+return nil
+
diff --git a/files/lua_api/string.doclua b/files/lua_api/string.doclua
new file mode 100644
index 0000000000..47a056dd9d
--- /dev/null
+++ b/files/lua_api/string.doclua
@@ -0,0 +1,231 @@
+-------------------------------------------------------------------------------
+-- String Manipulation. 
+-- This library provides generic functions for string manipulation,
+-- such as finding and extracting substrings, and pattern matching.
+-- When indexing a string in Lua, the first character is at position 1 (not at 0, as in C). 
+-- Indices are allowed to be negative and are interpreted as indexing backwards, from the end of the string.
+-- Thus, the last character is at position -1, and so on.
+--
+-- The string library provides all its functions inside the table string. It also sets a metatable for strings where the __index field points to the string table. Therefore, you can use the string functions in object-oriented style.
+-- For instance, string.byte(s, i) can be written as s:byte(i).
+--
+-- The string library assumes one-byte character encodings.
+-- @module string
+
+-------------------------------------------------------------------------------
+-- Returns the internal numerical codes of the characters `s[i]`, `s[i+1]`,
+-- ..., `s[j]`. The default value for `i` is 1; the default value for `j`
+-- is `i`.
+-- Note that numerical codes are not necessarily portable across platforms.
+-- @function [parent=#string] byte
+-- @param #string s string to handle.
+-- @param #number i start index, default value is 1.
+-- @param #number j end index, default value is `i`.
+-- @return the internal numerical codes of the characters `s[i]`, `s[i+1]`,..., `s[j]`
+
+-------------------------------------------------------------------------------
+-- Receives zero or more integers. Returns a string with length equal to
+-- the number of arguments, in which each character has the internal numerical
+-- code equal to its corresponding argument.
+-- 
+-- Note that numerical codes are not necessarily portable across platforms.
+-- @function [parent=#string] char
+-- @param ... zero or more integers.
+-- @return #string a string with length equal to
+-- the number of arguments, in which each character has the internal numerical
+-- code equal to its corresponding argument.
+
+-------------------------------------------------------------------------------
+-- Returns a string containing a binary representation of the given
+-- function, so that a later `loadstring` on this string returns a copy of
+-- the function. `function` must be a Lua function without upvalues.
+-- @function [parent=#string] dump
+-- @param f the function to dump.
+-- @return #string a string representation of the given function.
+
+-------------------------------------------------------------------------------
+-- Looks for the first match of `pattern` in the string `s`. If it finds a
+-- match, then `find` returns the indices of `s` where this occurrence starts
+-- and ends; otherwise, it returns nil.A third, optional numerical argument
+-- `init` specifies where to start the search; its default value is 1 and
+-- can be negative. A value of true as a fourth, optional argument `plain`
+-- turns off the pattern matching facilities, so the function does a plain
+-- "find substring" operation, with no characters in `pattern` being considered
+-- "magic". 
+-- 
+-- Note that if `plain` is given, then `init` must be given as well.
+-- If the pattern has captures, then in a successful match the captured values
+-- are also returned, after the two indices.
+-- @function [parent=#string] find
+-- @param #string s string to handle.
+-- @param #string pattern pattern to search. 
+-- @param #number init index where to start the search. (default value is 1)
+-- @param #boolean plain set to true to search without pattern matching. (default value is false)
+-- @return #number, #number start and end indices of first occurence.
+-- @return #nil if pattern not found.
+
+-------------------------------------------------------------------------------
+-- Returns a formatted version of its variable number of arguments following
+-- the description given in its first argument (which must be a string). The
+-- format string follows the same rules as the `printf` family of standard C
+-- functions. The only differences are that the options/modifiers `*`, `l`,
+-- `L`, `n`, `p`, and `h` are not supported and that there is an extra option,
+-- `q`. The `q` option formats a string in a form suitable to be safely read
+-- back by the Lua interpreter: the string is written between double quotes,
+-- and all double quotes, newlines, embedded zeros, and backslashes in the
+-- string are correctly escaped when written. For instance, the call
+--
+--     string.format('%q', 'a string with "quotes" and \n new line')
+--
+-- will produce the string:
+--
+--     "a string with \"quotes\" and \
+--         new line"
+--
+-- The options `c`, `d`, `E`, `e`, `f`, `g`, `G`, `i`, `o`, `u`, `X`, and
+-- `x` all expect a number as argument, whereas `q` and `s` expect a string.
+-- This function does not accept string values containing embedded zeros,
+-- except as arguments to the `q` option.
+-- @function [parent=#string] format
+-- @param #string formatstring the string template. 
+-- @param ... arguments could be strings or numbers.
+-- @return #string the formatted string.
+
+-------------------------------------------------------------------------------
+-- Returns an iterator function that, each time it is called, returns the
+-- next captures from `pattern` over string `s`. If `pattern` specifies no
+-- captures, then the whole match is produced in each call.
+-- As an example, the following loop
+--
+--     s = "hello world from Lua"
+--     for w in string.gmatch(s, "%a+") do
+--       print(w)
+--     end
+--
+-- will iterate over all the words from string `s`, printing one per line. The
+-- next example collects all pairs `key=value` from the given string into
+-- a table:
+--
+--     t = {}
+--     s = "from=world, to=Lua"
+--     for k, v in string.gmatch(s, "(%w+)=(%w+)") do
+--       t[k] = v
+--     end
+--
+-- For this function, a '`^`' at the start of a pattern does not work as an
+-- anchor, as this would prevent the iteration.
+-- @function [parent=#string] gmatch
+-- @param #string s string to handle.
+-- @param #string pattern pattern to search.
+
+-------------------------------------------------------------------------------
+-- Returns a copy of `s` in which all (or the first `n`, if given)
+-- occurrences of the `pattern` have been replaced by a replacement string
+-- specified by `repl`, which can be a string, a table, or a function. `gsub`
+-- also returns, as its second value, the total number of matches that occurred.
+--
+-- If `repl` is a string, then its value is used for replacement. The character
+-- `%` works as an escape character: any sequence in `repl` of the form `%n`,
+-- with *n* between 1 and 9, stands for the value of the *n*-th captured
+-- substring (see below). The sequence `%0` stands for the whole match. The
+-- sequence `%%` stands for a single `%`.
+--
+-- If `repl` is a table, then the table is queried for every match, using
+-- the first capture as the key; if the pattern specifies no captures, then
+-- the whole match is used as the key.
+--
+-- If `repl` is a function, then this function is called every time a match
+-- occurs, with all captured substrings passed as arguments, in order; if
+-- the pattern specifies no captures, then the whole match is passed as a
+-- sole argument.
+--
+-- If the value returned by the table query or by the function call is a
+-- string or a number, then it is used as the replacement string; otherwise,
+-- if it is false or nil, then there is no replacement (that is, the original
+-- match is kept in the string).
+--
+-- Here are some examples:
+-- 
+--     x = string.gsub("hello world", "(%w+)", "%1 %1")
+--     --> x="hello hello world world"
+--     x = string.gsub("hello world", "%w+", "%0 %0", 1)
+--     --> x="hello hello world"
+--     x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1")
+--     --> x="world hello Lua from"
+--     x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)
+--     --> x="home = /home/roberto, user = roberto"
+--     x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)
+--           return loadstring(s)()
+--         end)
+--     --> x="4+5 = 9"
+--     local t = {name="lua", version="5.1"}
+--     x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t)
+--     --> x="lua-5.1.tar.gz"
+-- @function [parent=#string] gsub
+-- @param #string s string to handle.
+-- @param #string pattern pattern to search. 
+-- @param repl replacement could be a string, a table or a function.
+-- @param #number n number of occurences to replace, default is nil which means all occurences. 
+-- @return #string a modified copy of `s`.
+
+-------------------------------------------------------------------------------
+-- Receives a string and returns its length. The empty string `""` has
+-- length 0. Embedded zeros are counted, so `"a\000bc\000"` has length 5.
+-- @function [parent=#string] len
+-- @param #string s string to handle.
+-- @return #number the lenght of `s`.
+
+-------------------------------------------------------------------------------
+-- Receives a string and returns a copy of this string with all uppercase
+-- letters changed to lowercase. All other characters are left unchanged. The
+-- definition of what an uppercase letter is depends on the current locale.
+-- @function [parent=#string] lower
+-- @param #string s string to handle.
+-- @return #string a lower case version of `s`.
+
+-------------------------------------------------------------------------------
+-- Looks for the first *match* of `pattern` in the string `s`. If it
+-- finds one, then `match` returns the captures from the pattern; otherwise
+-- it returns nil. If `pattern` specifies no captures, then the whole match
+-- is returned. A third, optional numerical argument `init` specifies where
+-- to start the search; its default value is 1 and can be negative.
+-- @function [parent=#string] match
+-- @param #string s string to handle.
+-- @param #string pattern pattern to search. 
+-- @param #number init index where to start the search. (default value is 1)
+-- @return #string the captures from the pattern; otherwise it returns nil. If pattern specifies no captures, then the whole match is returned. 
+
+-------------------------------------------------------------------------------
+-- Returns a string that is the concatenation of `n` copies of the string `s`.
+-- @function [parent=#string] rep
+-- @param #string s string to handle.
+-- @param #number n number of repetition.
+-- @return #string the concatenation of `n` copies of the string `s`.
+
+-------------------------------------------------------------------------------
+-- Returns a string that is the string `s` reversed.
+-- @function [parent=#string] reverse
+-- @param #string s string to handle.
+-- @return #string the string `s` reversed.
+
+-------------------------------------------------------------------------------
+-- Returns the substring of `s` that starts at `i` and continues until
+-- `j`; `i` and `j` can be negative. If `j` is absent, then it is assumed to
+-- be equal to -1 (which is the same as the string length). In particular,
+-- the call `string.sub(s,1,j)` returns a prefix of `s` with length `j`, and
+-- `string.sub(s, -i)` returns a suffix of `s` with length `i`.
+-- @function [parent=#string] sub
+-- @param #string s string to handle.
+-- @param #number i start index.
+-- @param #number j end index. (default value is -1, which is the same as the string lenght)
+-- @return #string the substring of `s` that starts at `i` and continues until `j`. 
+
+-------------------------------------------------------------------------------
+-- Receives a string and returns a copy of this string with all lowercase
+-- letters changed to uppercase. All other characters are left unchanged. The
+-- definition of what a lowercase letter is depends on the current locale.
+-- @function [parent=#string] upper
+-- @param #string s string to handle.
+-- @return #string a upper case version of `s`.
+
+return nil
diff --git a/files/lua_api/table.doclua b/files/lua_api/table.doclua
new file mode 100644
index 0000000000..f8561e97a8
--- /dev/null
+++ b/files/lua_api/table.doclua
@@ -0,0 +1,66 @@
+-------------------------------------------------------------------------------
+-- Table Manipulation
+-- This library provides generic functions for table manipulation.
+-- It provides all its functions inside the table table.
+--
+-- Most functions in the table library assume that the table represents an array or a list.
+-- For these functions, when we talk about the "length" of a table we mean the result of the length operator.
+-- @module table
+
+
+
+-------------------------------------------------------------------------------
+-- Given an array where all elements are strings or numbers, returns
+-- `table[i]..sep..table[i+1]...sep..table[j]`. The default value for
+-- `sep` is the empty string, the default for `i` is 1, and the default for
+-- `j` is the length of the table. If `i` is greater than `j`, returns the
+-- empty string.
+-- @function [parent=#table] concat
+-- @param #table table table to handle.
+-- @param #string sep the separator, default value is an empty string. 
+-- @param #number i start index, default value is 1.
+-- @param #number j end index, default value is lenght of the table.
+-- @return #string the concatenated table.
+
+-------------------------------------------------------------------------------
+-- Inserts element `value` at position `pos` in `table`, shifting up
+-- other elements to open space, if necessary. The default value for `pos` is
+-- `n+1`, where `n` is the length of the table, so that a call
+-- `table.insert(t,x)` inserts `x` at the end of table `t`.
+-- @function [parent=#table] insert
+-- @param #table table table to modify.
+-- @param #number pos index of insertion.
+-- @param value value to insert.
+
+-------------------------------------------------------------------------------
+-- Returns the largest positive numerical index of the given table, or
+-- zero if the table has no positive numerical indices. (To do its job this
+-- function does a linear traversal of the whole table.)
+-- @function [parent=#table] maxn
+-- @param #table table table to traverse.
+-- @return #number the largest positive numerical index of the given table, or
+-- zero if the table has no positive numerical indices.
+
+-------------------------------------------------------------------------------
+-- Removes from `table` the element at position `pos`, shifting down other
+-- elements to close the space, if necessary. Returns the value of the removed
+-- element. The default value for `pos` is `n`, where `n` is the length of the
+-- table, so that a call `table.remove(t)` removes the last element of table
+-- `t`.
+-- @function [parent=#table] remove
+-- @param #table table table to modify.
+-- @param #number pos index of deletion. (default value is the lenght of the table)
+
+-------------------------------------------------------------------------------
+-- Sorts table elements in a given order,
+-- *in-place*, from `table[1]` to `table[n]`, where `n` is the length of the
+-- table. If `comp` is given, then it must be a function that receives two
+-- table elements, and returns true when the first is less than the second
+-- (so that `not comp(a[i+1],a[i])` will be true after the sort). Lua operator < is used instead.
+-- 
+-- The sort algorithm is not stable; that is, elements considered equal by the given order may have their relative positions changed by the sort.
+-- @function [parent=#table] sort
+-- @param #table table table to sort.
+-- @param comp a function which take to table and returns true when the first is less than the second.
+
+return nil