[Lua] Update documentation

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 <Package openmw.core>`                 | everywhere         | | Functions that are common for both global and local scripts |
 +---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+|:ref:`openmw.types <Package openmw.types>`               | everywhere         | | Functions for specific types of game objects.               |
++---------------------------------------------------------+--------------------+---------------------------------------------------------------+
 |: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.    |

docs/source/reference/lua-scripting/openmw_types.rst

@@ -0,0 +1,5 @@
+Package openmw.types
+====================
+
+.. raw:: html
+   :file: generated_html/openmw_types.html

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 <Package openmw.core>`                 | everywhere         | | Functions that are common for both global and local scripts |
 +---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+|:ref:`openmw.types <Package openmw.types>`               | everywhere         | | Functions for specific types of game objects.               |
++---------------------------------------------------------+--------------------+---------------------------------------------------------------+
 |: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.    |

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})

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 #table type Type of the object (one of the tables from the package @{openmw.types#types}).
--- @field #number count Count (makes sense if holded in a container).
+-- @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).
+-- Get all objects of given type from the cell.
--- Returns an empty list if the cell is not loaded.
+-- @function [parent=#Cell] getAll
--- @function [parent=#Cell] selectObjects
 -- @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()
+-- @usage
--- local weapons = inventory:getAll(core.OBJECT_TYPE.Weapon)
+-- local type = require('openmw.types')
+-- local all = inventory:getAll()
+-- local weapons = inventory:getAll(types.Weapon)
 
 
 return nil

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
+