mirror of https://github.com/OpenMW/openmw.git
Documentation for Lua scripting
Petr Mikheev
4 years ago
parent
f5722f9ba0
commit
9746800eed
@ -0,0 +1,442 @@
|
||||
#################
|
||||
Lua API reference
|
||||
#################
|
||||
|
||||
.. toctree::
|
||||
:caption: Table of Contents
|
||||
:maxdepth: 2
|
||||
|
||||
Engine handlers reference
|
||||
=========================
|
||||
|
||||
Engine handler is a function defined by a script, that can be called by the engine.
|
||||
|
||||
+------------------------------------------------------------------------------------------------+
|
||||
| **Can be defined by any script** |
|
||||
+----------------------------------+-------------------------------------------------------------+
|
||||
| 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. |
|
||||
+----------------------------------+-------------------------------------------------------------+
|
||||
| onLoad(data) | Called on loading with the data previosly returned by onSave|
|
||||
+----------------------------------+-------------------------------------------------------------+
|
||||
| **Only for global scripts** |
|
||||
+----------------------------------+-------------------------------------------------------------+
|
||||
| onNewGame() | New game is started |
|
||||
+----------------------------------+-------------------------------------------------------------+
|
||||
| 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 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
|
||||
=============
|
||||
|
||||
.. warning::
|
||||
Not implemented yet.
|
||||
@ -0,0 +1,14 @@
|
||||
####################
|
||||
OpenMW Lua scripting
|
||||
####################
|
||||
|
||||
.. warning::
|
||||
OpenMW Lua scripting is in early stage of development. Also note that OpenMW Lua is not compatible with MWSE.
|
||||
|
||||
.. toctree::
|
||||
:caption: Table of Contents
|
||||
:maxdepth: 2
|
||||
|
||||
overview
|
||||
api
|
||||
|
||||
@ -0,0 +1,317 @@
|
||||
Overview of Lua scripting
|
||||
#########################
|
||||
|
||||
Language and sandboxing
|
||||
=======================
|
||||
|
||||
OpenMW supports scripts written in Lua 5.1.
|
||||
There are no plans to switch to any newer version of the language, because newer versions are not supported by LuaJIT.
|
||||
|
||||
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:
|
||||
`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>`__,
|
||||
`table <https://www.lua.org/manual/5.1/manual.html#5.5>`__.
|
||||
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``.
|
||||
|
||||
Loading libraries with ``require('library_name')`` is allowed, but limited. It works this way:
|
||||
|
||||
1. If `library_name` is one of the standard libraries, then return the library.
|
||||
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.
|
||||
|
||||
Basic concepts
|
||||
==============
|
||||
|
||||
Game object
|
||||
Any object that exists in the game world and has a specific location. Player, actors, items, and statics are game objects.
|
||||
|
||||
Record
|
||||
Persistent information about an object. Includes starting stats and links to assets, but doesn't have a location. Game objects are instances of records. Some records (e.g. a unique NPC) have a single instance, some (e.g. a specific potion) may correspond to multiple objects.
|
||||
|
||||
.. note::
|
||||
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.
|
||||
|
||||
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`.
|
||||
|
||||
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.
|
||||
|
||||
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).
|
||||
|
||||
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:
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
|
||||
How to run a script
|
||||
===================
|
||||
|
||||
Let's write a simple example of a `Player script`:
|
||||
|
||||
.. code-block:: Lua
|
||||
|
||||
-- Saved to my_lua_mod/example/player.lua
|
||||
|
||||
local ui = require('openmw.ui')
|
||||
|
||||
return {
|
||||
engineHandlers = {
|
||||
onKeyPress = function(code, modifiers)
|
||||
if code == string.byte('x') then
|
||||
ui.showMessage('You have pressed "X"')
|
||||
end
|
||||
end
|
||||
}
|
||||
}
|
||||
|
||||
In order to attach it to the player we also need a global script:
|
||||
|
||||
.. code-block:: Lua
|
||||
|
||||
-- Saved to my_lua_mod/example/global.lua
|
||||
|
||||
return {
|
||||
engineHandlers = {
|
||||
onPlayerAdded = function(player) player:addScript('example/player.lua') end
|
||||
}
|
||||
}
|
||||
|
||||
And one more file -- to start the global script:
|
||||
|
||||
::
|
||||
|
||||
# Saved to my_lua_mod/my_lua_mod.omwscripts
|
||||
|
||||
# It is just a list of global scripts to run. Each file is on a separate line.
|
||||
example/global.lua
|
||||
|
||||
Finally :ref:`register <Lua scripting>` it in ``openmw.cfg``:
|
||||
|
||||
::
|
||||
|
||||
data=path/to/my_lua_mod
|
||||
lua-scripts=my_lua_mod.omwscripts
|
||||
|
||||
Now every time the player presses "X" on a keyboard, a message is shown.
|
||||
|
||||
Script structure
|
||||
================
|
||||
|
||||
Each script is a separate file in 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:
|
||||
|
||||
.. code-block:: Lua
|
||||
|
||||
local util = require('openmw.util')
|
||||
|
||||
local function onUpdate(dt)
|
||||
...
|
||||
end
|
||||
|
||||
local function onSave()
|
||||
...
|
||||
return data
|
||||
end
|
||||
|
||||
local function onLoad(data)
|
||||
...
|
||||
end
|
||||
|
||||
local function myEventHandler(eventData)
|
||||
...
|
||||
end
|
||||
|
||||
local function somePublicFunction(params, ...)
|
||||
...
|
||||
end
|
||||
|
||||
return {
|
||||
name = 'MyScriptInterface',
|
||||
interface = {
|
||||
somePublicFunction = somePublicFunction,
|
||||
},
|
||||
|
||||
eventHandlers = { MyEvent = myEventHandler },
|
||||
|
||||
engineHandlers = {
|
||||
onUpdate = onUpdate,
|
||||
onSave = onSave,
|
||||
onLoad = onLoad,
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
.. note::
|
||||
Every instance of every script works in a separate enviroment, so it is not necessary
|
||||
to make everything local. It's local just because it makes the code a bit faster.
|
||||
|
||||
All sections in the returned table are optional.
|
||||
If you just want to do something every frame, it is enough to write the following:
|
||||
|
||||
.. code-block:: Lua
|
||||
|
||||
return {
|
||||
engineHandlers = {
|
||||
onUpdate = function()
|
||||
print('Hello, World!')
|
||||
end
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
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,
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
The saved state must be :ref:`serializable <Serializable data>`.
|
||||
|
||||
`onSave` and `onLoad` are special:
|
||||
|
||||
- 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.
|
||||
|
||||
TODO: example, explain how global scripts are loading
|
||||
|
||||
Serializable data
|
||||
-----------------
|
||||
|
||||
`Serializable` value means that OpenMW is able to convert it to a sequence of bytes and then (probably on a different computer and with different OpenMW version) restore it back to the same form.
|
||||
|
||||
Serializable value is one of:
|
||||
|
||||
- `nil` value
|
||||
- a number
|
||||
- a string
|
||||
- a game object
|
||||
- a value of a type, defined by :ref:`openmw.util`
|
||||
- a table whith serializable keys and values
|
||||
|
||||
Serializable data can not contain:
|
||||
|
||||
- Functions
|
||||
- Tables with custom metatables
|
||||
- Several references to the same table. For example ``{ x = some_table, y = some_table }`` is not allowed.
|
||||
- Circular references (i.e. when some table contains itself).
|
||||
|
||||
API packages
|
||||
============
|
||||
|
||||
API packages provide functions that can be called by scripts. I.e. it is a script-to-engine interaction.
|
||||
A package can be loaded with ``require('<package name>')``.
|
||||
It can not be overloaded even if there is a lua file with the same name.
|
||||
The list of available packages is different for global and for local scripts.
|
||||
Player scripts are local scripts that are attached to a player.
|
||||
|
||||
+----------------------+--------------------+---------------------------------------------------------------+
|
||||
| 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 | **TODO: write description** |
|
||||
+----------------------+--------------------+---------------------------------------------------------------+
|
||||
|: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) |
|
||||
+----------------------+--------------------+---------------------------------------------------------------+
|
||||
|
||||
|
||||
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.
|
||||
In other cases events should be used.
|
||||
|
||||
TODO: example, overloading
|
||||
|
||||
|
||||
Event system
|
||||
============
|
||||
|
||||
It is another way 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.
|
||||
- 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.
|
||||
|
||||
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".
|
||||
Any other return value (including nil) means nothing.
|
||||
|
||||
TODO: example
|
||||
|
||||
|
||||
Timers
|
||||
======
|
||||
|
||||
**TODO**
|
||||
|
||||
|
||||
Queries
|
||||
=======
|
||||
|
||||
**TODO:** describe the concepts of `openmw.query` and `world.selectObjects`/`nearby.selectObjects`.
|
||||
|
||||
|
||||
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.
|
||||
|
||||
Loading…
Reference in New Issue