Merge branch 'activate_and_use' into 'master'

Handle Use action in Lua in a similar way to Activate action

See merge request OpenMW/openmw!3354

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

@@ -34,6 +34,7 @@ Lua API reference
     interface_ai
     interface_camera
     interface_controls
+    interface_item_usage
     interface_mwui
     interface_settings
     interface_ui
@@ -64,36 +65,6 @@ Sources can be found in ``resources/vfs/openmw_aux``. In theory mods can overrid
 
 .. include:: tables/aux_packages.rst
 
-Interfaces of built-in scripts
-------------------------------
+**Interfaces of built-in scripts**
 
-.. list-table::
-  :widths: 20 20 60
-
-  * - Interface
-    - Can be used
-    - Description
-  * - :ref:`Activation <Interface Activation>`
-    - by global scripts
-    - Allows to extend or override built-in activation mechanics.
-  * - :ref:`AI <Interface AI>`
-    - by local scripts
-    - Control basic AI of NPCs and creatures.
-  * - :ref:`Camera <Interface Camera>`
-    - by player scripts
-    - | Allows to alter behavior of the built-in camera script
-      | without overriding the script completely.
-  * - :ref:`Controls <Interface Controls>`
-    - by player scripts
-    - | Allows to alter behavior of the built-in script
-      | that handles player controls.
-  * - :ref:`Settings <Interface Settings>`
-    - by player and global scripts
-    - Save, display and track changes of setting values.
-  * - :ref:`MWUI <Interface MWUI>`
-    - by player scripts
-    - Morrowind-style UI templates.
-  * - :ref:`UI <Interface UI>`
-    - by player scripts
-    - | High-level UI modes interface. Allows to override parts
-      | of the interface.
+.. include:: tables/interfaces.rst

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

@@ -6,6 +6,8 @@ Built-in events
 Actor events
 ------------
 
+**StartAIPackage, RemoveAIPackages**
+
 Any script can send to any actor (except player, for player will be ignored) events ``StartAIPackage`` and ``RemoveAIPackages``.
 The effect is equivalent to calling ``interfaces.AI.startPackage`` or ``interfaces.AI.removePackages`` in a local script on this actor.
 
@@ -16,6 +18,17 @@ Examples:
     actor:sendEvent('StartAIPackage', {type='Combat', target=self.object})
     actor:sendEvent('RemoveAIPackages', 'Pursue')
 
+**UseItem**
+
+Any script can send global event ``UseItem`` with arguments ``object`` and ``actor``.
+The actor will use (e.g. equip or consume) the object. The object should be in the actor's inventory.
+
+Example:
+
+.. code-block:: Lua
+
+    core.sendGlobalEvent('UseItem', {object = potion, actor = player})
+
 UI events
 ---------
 

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

@@ -0,0 +1,6 @@
+Interface ItemUsage
+===================
+
+.. raw:: html
+   :file: generated_html/scripts_omw_usehandlers.html
+

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

@@ -457,36 +457,7 @@ The order in which the scripts are started is important. So if one mod should ov
 
 **Interfaces of built-in scripts**
 
-.. list-table::
-  :widths: 20 20 60
-
-  * - Interface
-    - Can be used
-    - Description
-  * - :ref:`Activation <Interface Activation>`
-    - by global scripts
-    - Allows to extend or override built-in activation mechanics.
-  * - :ref:`AI <Interface AI>`
-    - by local scripts
-    - Control basic AI of NPCs and creatures.
-  * - :ref:`Camera <Interface Camera>`
-    - by player scripts
-    - | Allows to alter behavior of the built-in camera script
-      | without overriding the script completely.
-  * - :ref:`Controls <Interface Controls>`
-    - by player scripts
-    - | Allows to alter behavior of the built-in script
-      | that handles player controls.
-  * - :ref:`Settings <Interface Settings>`
-    - by player and global scripts
-    - Save, display and track changes of setting values.
-  * - :ref:`MWUI <Interface MWUI>`
-    - by player scripts
-    - Morrowind-style UI templates.
-  * - :ref:`UI <Interface UI>`
-    - by player scripts
-    - | High-level UI modes interface. Allows to override parts
-      | of the interface.
+.. include:: tables/interfaces.rst
 
 Event system
 ============

docs/source/reference/lua-scripting/tables/interfaces.rst

@@ -0,0 +1,34 @@
+.. list-table::
+  :widths: 20 20 60
+
+  * - Interface
+    - Can be used
+    - Description
+  * - :ref:`Activation <Interface Activation>`
+    - by global scripts
+    - Allows to extend or override built-in activation mechanics.
+  * - :ref:`AI <Interface AI>`
+    - by local scripts
+    - Control basic AI of NPCs and creatures.
+  * - :ref:`Camera <Interface Camera>`
+    - by player scripts
+    - | Allows to alter behavior of the built-in camera script
+      | without overriding the script completely.
+  * - :ref:`Controls <Interface Controls>`
+    - by player scripts
+    - | Allows to alter behavior of the built-in script
+      | that handles player controls.
+  * - :ref:`ItemUsage <Interface ItemUsage>`
+    - by global scripts
+    - | Allows to extend or override built-in item usage
+      | mechanics.
+  * - :ref:`Settings <Interface Settings>`
+    - by player and global scripts
+    - Save, display and track changes of setting values.
+  * - :ref:`MWUI <Interface MWUI>`
+    - by player scripts
+    - Morrowind-style UI templates.
+  * - :ref:`UI <Interface UI>`
+    - by player scripts
+    - | High-level UI modes interface. Allows to override parts
+      | of the interface.