From 9af49cfa687f775c561ff071d6c4be86de29c72c Mon Sep 17 00:00:00 2001 From: Petr Mikheev Date: Sun, 13 Mar 2022 00:38:36 +0100 Subject: [PATCH] [Lua] Update documentation --- docs/source/reference/lua-scripting/api.rst | 3 + .../reference/lua-scripting/openmw_types.rst | 5 + .../reference/lua-scripting/overview.rst | 2 + files/lua_api/CMakeLists.txt | 1 + files/lua_api/openmw/core.lua | 161 +------ files/lua_api/openmw/types.lua | 456 ++++++++++++++++++ 6 files changed, 483 insertions(+), 145 deletions(-) create mode 100644 docs/source/reference/lua-scripting/openmw_types.rst create mode 100644 files/lua_api/openmw/types.lua diff --git a/docs/source/reference/lua-scripting/api.rst b/docs/source/reference/lua-scripting/api.rst index 0681c63dea..4518028073 100644 --- a/docs/source/reference/lua-scripting/api.rst +++ b/docs/source/reference/lua-scripting/api.rst @@ -12,6 +12,7 @@ Lua API reference openmw_util openmw_storage openmw_core + openmw_types openmw_async openmw_query openmw_world @@ -56,6 +57,8 @@ Player scripts are local scripts that are attached to a player. +---------------------------------------------------------+--------------------+---------------------------------------------------------------+ |:ref:`openmw.core ` | everywhere | | Functions that are common for both global and local scripts | +---------------------------------------------------------+--------------------+---------------------------------------------------------------+ +|:ref:`openmw.types ` | everywhere | | Functions for specific types of game objects. | ++---------------------------------------------------------+--------------------+---------------------------------------------------------------+ |:ref:`openmw.async ` | everywhere | | Timers (implemented) and coroutine utils (not implemented) | +---------------------------------------------------------+--------------------+---------------------------------------------------------------+ |:ref:`openmw.query ` | everywhere | | Tools for constructing queries: base queries and fields. | diff --git a/docs/source/reference/lua-scripting/openmw_types.rst b/docs/source/reference/lua-scripting/openmw_types.rst new file mode 100644 index 0000000000..1819b1a6ce --- /dev/null +++ b/docs/source/reference/lua-scripting/openmw_types.rst @@ -0,0 +1,5 @@ +Package openmw.types +==================== + +.. raw:: html + :file: generated_html/openmw_types.html diff --git a/docs/source/reference/lua-scripting/overview.rst b/docs/source/reference/lua-scripting/overview.rst index 8fa255bac0..a819235e2a 100644 --- a/docs/source/reference/lua-scripting/overview.rst +++ b/docs/source/reference/lua-scripting/overview.rst @@ -353,6 +353,8 @@ Player scripts are local scripts that are attached to a player. +---------------------------------------------------------+--------------------+---------------------------------------------------------------+ |:ref:`openmw.core ` | everywhere | | Functions that are common for both global and local scripts | +---------------------------------------------------------+--------------------+---------------------------------------------------------------+ +|:ref:`openmw.types ` | everywhere | | Functions for specific types of game objects. | ++---------------------------------------------------------+--------------------+---------------------------------------------------------------+ |:ref:`openmw.async ` | everywhere | | Timers (implemented) and coroutine utils (not implemented) | +---------------------------------------------------------+--------------------+---------------------------------------------------------------+ |:ref:`openmw.query ` | everywhere | | Tools for constructing queries: base queries and fields. | diff --git a/files/lua_api/CMakeLists.txt b/files/lua_api/CMakeLists.txt index 8c5b46e8db..2988f38552 100644 --- a/files/lua_api/CMakeLists.txt +++ b/files/lua_api/CMakeLists.txt @@ -13,6 +13,7 @@ set(LUA_API_FILES openmw/ui.lua openmw/util.lua openmw/world.lua + openmw/types.lua ) foreach (f ${LUA_API_FILES}) diff --git a/files/lua_api/openmw/core.lua b/files/lua_api/openmw/core.lua index d57b6a405e..afb0d2f5bb 100644 --- a/files/lua_api/openmw/core.lua +++ b/files/lua_api/openmw/core.lua @@ -86,59 +86,6 @@ -- print( myMsg('Hello %{name}!', {name='World'}) ) ---- --- @type OBJECT_TYPE --- @field #string Activator "Activator" --- @field #string Armor "Armor" --- @field #string Book "Book" --- @field #string Clothing "Clothing" --- @field #string Container "Container" --- @field #string Creature "Creature" --- @field #string Door "Door" --- @field #string Ingredient "Ingredient" --- @field #string Light "Light" --- @field #string Miscellaneous "Miscellaneous" --- @field #string NPC "NPC" --- @field #string Player "Player" --- @field #string Potion "Potion" --- @field #string Static "Static" --- @field #string Apparatus "Apparatus" --- @field #string Lockpick "Lockpick" --- @field #string Probe "Probe" --- @field #string Repair "Repair" - ---- --- Possible `object.type` values. --- @field [parent=#core] #OBJECT_TYPE OBJECT_TYPE - - ---- --- @type EQUIPMENT_SLOT --- @field #number Helmet --- @field #number Cuirass --- @field #number Greaves --- @field #number LeftPauldron --- @field #number RightPauldron --- @field #number LeftGauntlet --- @field #number RightGauntlet --- @field #number Boots --- @field #number Shirt --- @field #number Pants --- @field #number Skirt --- @field #number Robe --- @field #number LeftRing --- @field #number RightRing --- @field #number Amulet --- @field #number Belt --- @field #number CarriedRight --- @field #number CarriedLeft --- @field #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. @@ -146,73 +93,18 @@ -- @field openmw.util#Vector3 position Object position. -- @field openmw.util#Vector3 rotation Object rotation (ZXY order). -- @field #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 #string type Type of the object (see @{openmw.core#OBJECT_TYPE}). --- @field #number count Count (makes sense if holded in a container). +-- @field #table type Type of the object (one of the tables from the package @{openmw.types#types}). +-- @field #number count Count (makes sense if stored in a container). -- @field #string recordId Record ID. --- @field #Inventory inventory Inventory of an Player/NPC or content of an container. --- @field #boolean isTeleport `True` if it is a teleport door (only if `object.type` == "Door"). --- @field openmw.util#Vector3 destPosition Destination (only if a teleport door). --- @field openmw.util#Vector3 destRotation Destination rotation (only if a teleport door). --- @field #string destCell Destination cell (only if a teleport door). --- --- Is the object still exists/available. +-- Does the object still exist and is 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 - ---- --- Current speed. Can be called only from a local script. --- @function [parent=#GameObject] getCurrentSpeed --- @param self --- @return #number - ---- --- Is the actor standing on ground. Can be called only from a local script. --- @function [parent=#GameObject] isOnGround --- @param self --- @return #boolean - ---- --- Is the actor in water. Can be called only from a local script. --- @function [parent=#GameObject] isSwimming --- @param self --- @return #boolean - ---- --- Is the actor in weapon stance. Can be called only from a local script. --- @function [parent=#GameObject] isInWeaponStance --- @param self --- @return #boolean - ---- --- Is the actor in magic stance. Can be called only from a local script. --- @function [parent=#GameObject] isInMagicStance --- @param self --- @return #boolean - --- -- Send local event to the object. -- @function [parent=#GameObject] sendEvent @@ -228,36 +120,10 @@ -- @usage local self = require('openmw.self') -- object:activateBy(self) ---- --- 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. Script should be specified in a content --- file (omwgame/omwaddon/omwscripts) with a CUSTOM flag. +-- file (omwgame/omwaddon/omwscripts) with a CUSTOM flag. Scripts can not be attached to Statics. -- @function [parent=#GameObject] addScript -- @param self -- @param #string scriptPath Path to the script in OpenMW virtual filesystem. @@ -325,12 +191,15 @@ -- 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 +-- Get all objects of given type from the cell. +-- @function [parent=#Cell] getAll -- @param self --- @param openmw.query#Query query +-- @param type (optional) object type (see @{openmw.types#types}) -- @return #ObjectList +-- @usage +-- local type = require('openmw.types') +-- local all = cell:getAll() +-- local weapons = cell:getAll(types.Weapon) --- @@ -348,10 +217,12 @@ -- Get all items of given type from the inventory. -- @function [parent=#Inventory] getAll -- @param self --- @param type (optional) items type (see @{openmw.core#OBJECT_TYPE}) +-- @param type (optional) items type (see @{openmw.types#types}) -- @return #ObjectList --- @usage local all = inventory:getAll() --- local weapons = inventory:getAll(core.OBJECT_TYPE.Weapon) +-- @usage +-- local type = require('openmw.types') +-- local all = inventory:getAll() +-- local weapons = inventory:getAll(types.Weapon) return nil diff --git a/files/lua_api/openmw/types.lua b/files/lua_api/openmw/types.lua new file mode 100644 index 0000000000..82dbded2e8 --- /dev/null +++ b/files/lua_api/openmw/types.lua @@ -0,0 +1,456 @@ +--- +-- `openmw.types` defines functions for specific types of game objects. +-- @module types +-- @usage local types = require('openmw.types') + +--- Common @{#Actor} functions for Creature, NPC, and Player. +-- @field [parent=#types] #Actor Actor + +--- Common functions for Creature, NPC, and Player. +-- @type Actor + +--- +-- Whether the object is an actor. +-- @function [parent=#Actor] objectIsInstance +-- @param openmw.core#GameObject object +-- @return #boolean + +--- +-- Actor inventory. +-- @function [parent=#Actor] inventory +-- @param openmw.core#GameObject actor +-- @return openmw.core#Inventory + +--- +-- @type EQUIPMENT_SLOT +-- @field #number Helmet +-- @field #number Cuirass +-- @field #number Greaves +-- @field #number LeftPauldron +-- @field #number RightPauldron +-- @field #number LeftGauntlet +-- @field #number RightGauntlet +-- @field #number Boots +-- @field #number Shirt +-- @field #number Pants +-- @field #number Skirt +-- @field #number Robe +-- @field #number LeftRing +-- @field #number RightRing +-- @field #number Amulet +-- @field #number Belt +-- @field #number CarriedRight +-- @field #number CarriedLeft +-- @field #number Ammunition + +--- +-- Available @{#EQUIPMENT_SLOT} values. Used in `Actor.equipment(obj)` and `Actor.setEquipment(obj, eqp)`. +-- @field [parent=#Actor] #EQUIPMENT_SLOT EQUIPMENT_SLOT + +--- +-- @type STANCE +-- @field #number Nothing Default stance +-- @field #number Weapon Weapon stance +-- @field #number Spell Magic stance + +--- @{#STANCE} +-- @field [parent=#Actor] #STANCE STANCE + +--- +-- Returns true if the object is an actor and is able to move. For dead, paralyzed, +-- or knocked down actors it returns false. +-- @function [parent=#Actor] canMove +-- @param openmw.core#GameObject object +-- @return #boolean + +--- +-- Speed of running. For dead actors it still returns a positive value. +-- @function [parent=#Actor] runSpeed +-- @param openmw.core#GameObject actor +-- @return #number + +--- +-- Speed of walking. For dead actors it still returns a positive value. +-- @function [parent=#Actor] walkSpeed +-- @param openmw.core#GameObject actor +-- @return #number + +--- +-- Current speed. +-- @function [parent=#Actor] currentSpeed +-- @param openmw.core#GameObject actor +-- @return #number + +--- +-- Is the actor standing on ground. Can be called only from a local script. +-- @function [parent=#Actor] isOnGround +-- @param openmw.core#GameObject actor +-- @return #boolean + +--- +-- Is the actor in water. Can be called only from a local script. +-- @function [parent=#Actor] isSwimming +-- @param openmw.core#GameObject actor +-- @return #boolean + +--- +-- Returns the current stance (whether a weapon/spell is readied), see the list of @{#STANCE} values. +-- @function [parent=#Actor] stance +-- @param openmw.core#GameObject actor +-- @return #number + +--- +-- Returns `true` if the item is equipped on the actor. +-- @function [parent=#Actor] isEquipped +-- @param openmw.core#GameObject actor +-- @param openmw.core#GameObject item +-- @return #boolean + +--- +-- Get equipment. +-- Returns a table `slot` -> @{openmw.core#GameObject} of currently equipped items. +-- See @{#EQUIPMENT_SLOT}. Returns empty table if the actor doesn't have +-- equipment slots. +-- @function [parent=#Actor] equipment +-- @param openmw.core#GameObject actor +-- @return #map<#number,openmw.core#GameObject> + +--- +-- Set equipment. +-- Keys in the table are equipment slots (see @{#EQUIPMENT_SLOT}). Each +-- value can be either a `GameObject` or recordId. Raises an error if +-- the actor doesn't have equipment slots and table is not empty. Can be +-- used only in local scripts and only on self. +-- @function [parent=#Actor] setEquipment +-- @param openmw.core#GameObject actor +-- @param equipment +-- @usage local self = require('openmw.self') +-- local Actor = require('openmw.types').Actor +-- Actor.setEquipment(self, {}) -- unequip all + + + +--- @{#Item} functions (all pickable items that can be placed to an inventory or container) +-- @field [parent=#types] #Item Item + +--- Functions for pickable items that can be placed to an inventory or container +-- @type Item + +--- +-- Whether the object is an item. +-- @function [parent=#Item] objectIsInstance +-- @param openmw.core#GameObject object +-- @return #boolean + + + +--- @{#Creature} functions +-- @field [parent=#types] #Creature Creature + +--- +-- @type Creature +-- @extends #Actor +-- @field #Actor baseType @{#Actor} + +--- +-- Whether the object is a creature. +-- @function [parent=#Creature] objectIsInstance +-- @param openmw.core#GameObject object +-- @return #boolean + + + +--- @{#NPC} functions +-- @field [parent=#types] #NPC NPC + +--- +-- @type NPC +-- @extends #Actor +-- @field #Actor baseType @{#Actor} + +--- +-- Whether the object is an NPC or a Player. +-- @function [parent=#NPC] objectIsInstance +-- @param openmw.core#GameObject object +-- @return #boolean + + + +--- @{#Player} functions +-- @field [parent=#types] #Player Player + +--- +-- @type Player +-- @extends #NPC +-- @field #NPC baseType @{#NPC} + +--- +-- Whether the object is a player. +-- @function [parent=#Player] objectIsInstance +-- @param openmw.core#GameObject object +-- @return #boolean + + + +--- @{#Armor} functions +-- @field [parent=#types] #Armor Armor + +--- +-- @type Armor +-- @extends #Item +-- @field #Item baseType @{#Item} + +--- +-- Whether the object is an Armor. +-- @function [parent=#Armor] objectIsInstance +-- @param openmw.core#GameObject object +-- @return #boolean + + + +--- @{#Book} functions +-- @field [parent=#types] #Book Book + +--- +-- @type Book +-- @extends #Item +-- @field #Item baseType @{#Item} + +--- +-- Whether the object is a Book. +-- @function [parent=#Book] objectIsInstance +-- @param openmw.core#GameObject object +-- @return #boolean + +--- @{#Clothing} functions + + +-- @field [parent=#types] #Clothing Clothing + +--- +-- @type Clothing +-- @extends #Item +-- @field #Item baseType @{#Item} + +--- +-- Whether the object is a Clothing. +-- @function [parent=#Clothing] objectIsInstance +-- @param openmw.core#GameObject object +-- @return #boolean + + + +--- @{#Ingredient} functions +-- @field [parent=#types] #Ingredient Ingredient + +--- +-- @type Ingredient +-- @extends #Item +-- @field #Item baseType @{#Item} + +--- +-- Whether the object is an Ingredient. +-- @function [parent=#Ingredient] objectIsInstance +-- @param openmw.core#GameObject object +-- @return #boolean + + + +--- @{#Light} functions +-- @field [parent=#types] #Light Light + +--- +-- @type Light +-- @extends #Item +-- @field #Item baseType @{#Item} + +--- +-- Whether the object is a Light. +-- @function [parent=#Light] objectIsInstance +-- @param openmw.core#GameObject object +-- @return #boolean + + + +--- Functions for @{#Miscellaneous} objects +-- @field [parent=#types] #Miscellaneous Miscellaneous + +--- +-- @type Miscellaneous +-- @extends #Item +-- @field #Item baseType @{#Item} + +--- +-- Whether the object is a Miscellaneous. +-- @function [parent=#Miscellaneous] objectIsInstance +-- @param openmw.core#GameObject object +-- @return #boolean + + + +--- @{#Potion} functions +-- @field [parent=#types] #Potion Potion + +--- +-- @type Potion +-- @extends #Item +-- @field #Item baseType @{#Item} + +--- +-- Whether the object is a Potion. +-- @function [parent=#Potion] objectIsInstance +-- @param openmw.core#GameObject object +-- @return #boolean + + + +--- @{#Weapon} functions +-- @field [parent=#types] #Weapon Weapon + +--- +-- @type Weapon +-- @extends #Item +-- @field #Item baseType @{#Item} + +--- +-- Whether the object is a Weapon. +-- @function [parent=#Weapon] objectIsInstance +-- @param openmw.core#GameObject object +-- @return #boolean + +--- @{#Apparatus} functions +-- @field [parent=#types] #Apparatus Apparatus + +--- +-- @type Apparatus +-- @extends #Item +-- @field #Item baseType @{#Item} + +--- +-- Whether the object is an Apparatus. +-- @function [parent=#Apparatus] objectIsInstance +-- @param openmw.core#GameObject object +-- @return #boolean + +--- @{#Lockpick} functions +-- @field [parent=#types] #Lockpick Lockpick + +--- +-- @type Lockpick +-- @extends #Item +-- @field #Item baseType @{#Item} + +--- +-- Whether the object is a Lockpick. +-- @function [parent=#Lockpick] objectIsInstance +-- @param openmw.core#GameObject object +-- @return #boolean + +--- @{#Probe} functions +-- @field [parent=#types] #Probe Probe + +--- +-- @type Probe +-- @extends #Item +-- @field #Item baseType @{#Item} + +--- +-- Whether the object is a Probe. +-- @function [parent=#Probe] objectIsInstance +-- @param openmw.core#GameObject object +-- @return #boolean + +--- @{#Repair} functions +-- @field [parent=#types] #Repair Repair + +--- +-- @type Repair +-- @extends #Item +-- @field #Item baseType @{#Item} + +--- +-- Whether the object is a Repair. +-- @function [parent=#Repair] objectIsInstance +-- @param openmw.core#GameObject object +-- @return #boolean + +--- @{#Activator} functions +-- @field [parent=#types] #Activator Activator + +--- +-- @type Activator + +--- +-- Whether the object is an Activator. +-- @function [parent=#Activator] objectIsInstance +-- @param openmw.core#GameObject object +-- @return #boolean + +--- @{#Container} functions +-- @field [parent=#types] #Container Container + +--- +-- @type Container + +--- +-- Container content. +-- @function [parent=#Container] content +-- @param openmw.core#GameObject object +-- @return openmw.core#Inventory + +--- +-- Whether the object is a Container. +-- @function [parent=#Container] objectIsInstance +-- @param openmw.core#GameObject object +-- @return #boolean + +--- @{#Door} functions +-- @field [parent=#types] #Door Door + +--- +-- @type Door + +--- +-- Whether the object is a Door. +-- @function [parent=#Door] objectIsInstance +-- @param openmw.core#GameObject object +-- @return #boolean + +--- +-- Whether the door is a teleport. +-- @function [parent=#Door] isTeleport +-- @param openmw.core#GameObject object +-- @return #boolean + +--- +-- Destination (only if a teleport door). +-- @function [parent=#Door] destPosition +-- @param openmw.core#GameObject object +-- @return openmw.util#Vector3 + +--- +-- Destination rotation (only if a teleport door). +-- @function [parent=#Door] destRotation +-- @param openmw.core#GameObject object +-- @return openmw.util#Vector3 + +--- +-- Destination cell (only if a teleport door). +-- @function [parent=#Door] destCell +-- @param openmw.core#GameObject object +-- @return openmw.core#Cell + +--- Functions for @{#Static} objects +-- @field [parent=#types] #Static Static + +--- +-- @type Static + +--- +-- Whether the object is a Static. +-- @function [parent=#Static] objectIsInstance +-- @param openmw.core#GameObject object +-- @return #boolean + +return nil +