Update Lua docs

docs/source/generate_luadoc.sh

@@ -65,4 +65,5 @@ $DOCUMENTOR_PATH -f doc -d $OUTPUT_DIR openmw/*lua
 
 cd $FILES_DIR/builtin_scripts
 $DOCUMENTOR_PATH -f doc -d $OUTPUT_DIR openmw_aux/*lua
+$DOCUMENTOR_PATH -f doc -d $OUTPUT_DIR scripts/omw/camera.lua
 

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

@@ -17,7 +17,9 @@ Lua API reference
     openmw_nearby
     openmw_input
     openmw_ui
+    openmw_camera
     openmw_aux_util
+    interface_camera
 
 
 - :ref:`Engine handlers reference`
@@ -56,11 +58,11 @@ Player scripts are local scripts that are attached to a player.
 +---------------------------------------------------------+--------------------+---------------------------------------------------------------+
 |:ref:`openmw.nearby <Package openmw.nearby>`             | by local scripts   | | Read-only access to the nearest area of the game world.     |
 +---------------------------------------------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw.input <Package openmw.input>`               | by player scripts  | | User input                                                  |
+|:ref:`openmw.input <Package openmw.input>`               | by player scripts  | | User input.                                                 |
 +---------------------------------------------------------+--------------------+---------------------------------------------------------------+
-|:ref:`openmw.ui <Package openmw.ui>`                     | by player scripts  | | Controls :ref:`user interface <User interface reference>`   |
+|:ref:`openmw.ui <Package openmw.ui>`                     | by player scripts  | | Controls :ref:`user interface <User interface reference>`.  |
 +---------------------------------------------------------+--------------------+---------------------------------------------------------------+
-|openmw.camera                                            | by player scripts  | | Controls camera (not implemented)                           |
+|:ref:`openmw.camera <Package openmw.camera>`             | by player scripts  | | Controls camera.                                            |
 +---------------------------------------------------------+--------------------+---------------------------------------------------------------+
 
 **openmw_aux**
@@ -73,3 +75,13 @@ Sources can be found in ``resources/vfs/openmw_aux``. In theory mods can overrid
 +=========================================================+====================+===============================================================+
 |:ref:`openmw_aux.util <Package openmw_aux.util>`         | everywhere         | | Miscellaneous utils                                         |
 +---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+
+**Interfaces of built-in scripts**
+
++---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+| Interface                                               | Can be used        | Description                                                   |
++=========================================================+====================+===============================================================+
+|:ref:`Camera <Interface Camera>`                         | by player scripts  | | Allows to alter behavior of the built-in camera script      |
+|                                                         |                    | | without overriding the script completely.                   |
++---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+

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

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

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

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

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

@@ -352,7 +352,7 @@ Player scripts are local scripts that are attached to a player.
 +---------------------------------------------------------+--------------------+---------------------------------------------------------------+
 |:ref:`openmw.ui <Package openmw.ui>`                     | by player scripts  | | Controls :ref:`user interface <User interface reference>`   |
 +---------------------------------------------------------+--------------------+---------------------------------------------------------------+
-|openmw.camera                                            | by player scripts  | | Controls camera (not implemented)                           |
+|:ref:`openmw.camera <Package openmw.camera>`             | by player scripts  | | Controls camera                                             |
 +---------------------------------------------------------+--------------------+---------------------------------------------------------------+
 
 openmw_aux
@@ -439,6 +439,15 @@ Using the interface:
 
 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.
 
+**Interfaces of built-in scripts**
+
++---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+| Interface                                               | Can be used        | Description                                                   |
++=========================================================+====================+===============================================================+
+|:ref:`Camera <Interface Camera>`                         | by player scripts  | | Allows to alter behavior of the built-in camera script      |
+|                                                         |                    | | without overriding the script completely.                   |
++---------------------------------------------------------+--------------------+---------------------------------------------------------------+
+
 
 Event system
 ============
@@ -719,8 +728,7 @@ you can import these files to get code autocompletion and integrated OpenMW API
 .. 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.
+- Specify there paths to ``resources/lua_api`` and ``resources/vfs`` 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
 
@@ -749,4 +757,17 @@ You can add special hints to give LDT more information:
 
 .. image:: https://gitlab.com/OpenMW/openmw-docs/raw/master/docs/source/reference/lua-scripting/_static/lua-ide-code-completion2.png
 
+In order to have autocompletion for script interfaces the information where to find these interfaces should be provided.
+For example for the camera interface (defined in ``resources/vfs/scripts/omw/camera.lua``):
+
+.. code-block:: Lua
+
+    --- @type Interfaces
+    -- @field scripts.omw.camera#Interface Camera
+    -- ... other interfaces here
+    --- @field #Interfaces I
+    local I = require('openmw.interfaces')
+
+    I.Camera.disableZoom()
+
 See `LDT Documentation Language <https://wiki.eclipse.org/LDT/User_Area/Documentation_Language>`__ for more details.

files/builtin_scripts/scripts/omw/camera.lua

@@ -19,7 +19,7 @@ local noStandingPreview = 0
 local noHeadBobbing = 0
 local noZoom = 0
 
-function init()
+local function init()
     camera.allowCharacterDeferredRotation(settings._getBoolFromSettingsCfg('Camera', 'deferred preview rotation'))
     if camera.getMode() == MODE.FirstPerson then
         primaryMode = MODE.FirstPerson
@@ -171,32 +171,54 @@ end
 
 return {
     interfaceName = 'Camera',
+    --- @module Camera
+    -- @usage require('openmw.interfaces').Camera
     interface = {
+        --- @field [parent=#Camera] #number version Interface version
         version = 0,
 
+        --- @function [parent=#Camera] getPrimaryMode Returns primary mode (MODE.FirstPerson or MODE.ThirdPerson).
         getPrimaryMode = function() return primaryMode end,
+        --- @function [parent=#Camera] getBaseThirdPersonDistance
         getBaseThirdPersonDistance = function() return third_person.baseDistance end,
+        --- @function [parent=#Camera] setBaseThirdPersonDistance
         setBaseThirdPersonDistance = function(v) third_person.baseDistance = v end,
+        --- @function [parent=#Camera] getTargetThirdPersonDistance
         getTargetThirdPersonDistance = function() return third_person.preferredDistance end,
 
+        --- @function [parent=#Camera] isModeControlEnabled
         isModeControlEnabled = function() return noModeControl == 0 end,
+        --- @function [parent=#Camera] disableModeControl
         disableModeControl = function() noModeControl = noModeControl + 1 end,
+        --- @function [parent=#Camera] enableModeControl
         enableModeControl = function() noModeControl = math.max(0, noModeControl - 1) end,
 
+        --- @function [parent=#Camera] isStandingPreviewEnabled
         isStandingPreviewEnabled = function() return previewIfStandSill and noStandingPreview == 0 end,
+        --- @function [parent=#Camera] disableStandingPreview
         disableStandingPreview = function() noStandingPreview = noStandingPreview + 1 end,
+        --- @function [parent=#Camera] enableStandingPreview
         enableStandingPreview = function() noStandingPreview = math.max(0, noStandingPreview - 1) end,
 
+        --- @function [parent=#Camera] isHeadBobbingEnabled
         isHeadBobbingEnabled = function() return head_bobbing.enabled and noHeadBobbing == 0 end,
+        --- @function [parent=#Camera] disableHeadBobbing
         disableHeadBobbing = function() noHeadBobbing = noHeadBobbing + 1 end,
+        --- @function [parent=#Camera] enableHeadBobbing
         enableHeadBobbing = function() noHeadBobbing = math.max(0, noHeadBobbing - 1) end,
 
+        --- @function [parent=#Camera] isZoomEnabled
         isZoomEnabled = function() return noZoom == 0 end,
+        --- @function [parent=#Camera] disableZoom
         disableZoom = function() noZoom = noZoom + 1 end,
+        --- @function [parent=#Camera] enableZoom
         enableZoom = function() noZoom = math.max(0, noZoom - 1) end,
 
+        --- @function [parent=#Camera] isThirdPersonOffsetControlEnabled
         isThirdPersonOffsetControlEnabled = function() return third_person.noOffsetControl == 0 end,
+        --- @function [parent=#Camera] disableThirdPersonOffsetControl
         disableThirdPersonOffsetControl = function() third_person.noOffsetControl = third_person.noOffsetControl + 1 end,
+        --- @function [parent=#Camera] enableThirdPersonOffsetControl
         enableThirdPersonOffsetControl = function() third_person.noOffsetControl = math.max(0, third_person.noOffsetControl - 1) end,
     },
     engineHandlers = {

files/lua_api/openmw/camera.lua

@@ -0,0 +1,171 @@
+-------------------------------------------------------------------------------
+-- `openmw.camera` controls camera.
+-- Can be used only by player scripts.
+-- @module camera
+-- @usage local camera = require('openmw.camera')
+
+
+-------------------------------------------------------------------------------
+-- @type MODE Camera modes.
+-- @field #number Static Camera doesn't track player; player inputs doesn't affect camera; use `setStaticPosition` to move the camera.
+-- @field #number FirstPerson First person mode.
+-- @field #number ThirdPerson Third person mode; player character turns to the view direction.
+-- @field #number Vanity Similar to Preview; camera slowly moves around the player.
+-- @field #number Preview Third person mode, but player character doesn't turn to the view direction.
+
+-------------------------------------------------------------------------------
+-- Camera modes.
+-- @field [parent=#camera] #MODE MODE
+
+-------------------------------------------------------------------------------
+-- Return the current @{openmw.camera#MODE}.
+-- @function [parent=#camera] getMode
+-- @return #MODE
+
+-------------------------------------------------------------------------------
+-- Return the mode the camera will switch to after the end of the current animation. Can be nil.
+-- @function [parent=#camera] getQueuedMode
+-- @return #MODE
+
+-------------------------------------------------------------------------------
+-- Change @{openmw.camera#MODE}; if the second (optional, true by default) argument is set to false, the switching can be delayed (see `getQueuedMode`).
+-- @function [parent=#camera] setMode
+-- @param #MODE mode
+-- @param #boolean force
+
+-------------------------------------------------------------------------------
+-- If set to true then after switching from Preview to ThirdPerson the player character turns to the camera view direction. Otherwise the camera turns to the character view direction.
+-- @function [parent=#camera] allowCharacterDeferredRotation
+-- @param #boolean boolValue
+
+-------------------------------------------------------------------------------
+-- Show/hide crosshair.
+-- @function [parent=#camera] showCrosshair
+-- @param #boolean boolValue
+
+-------------------------------------------------------------------------------
+-- Current position of the tracked object (the characters head if there is no animation).
+-- @function [parent=#camera] getTrackedPosition
+-- @return openmw.util#Vector3
+
+-------------------------------------------------------------------------------
+-- Current position of the camera.
+-- @function [parent=#camera] getPosition
+-- @return openmw.util#Vector3
+
+-------------------------------------------------------------------------------
+-- Camera pitch angle (radians) without taking extraPitch into account.
+-- Full pitch is `getPitch()+getExtraPitch()`.
+-- @function [parent=#camera] getPitch
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Force the pitch angle to the given value (radians); player input on this axis is ignored in this frame.
+-- @function [parent=#camera] setPitch
+-- @param #number value
+
+-------------------------------------------------------------------------------
+-- Camera yaw angle (radians) without taking extraYaw into account.
+-- Full yaw is `getYaw()+getExtraYaw()`.
+-- @function [parent=#camera] getYaw
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Force the yaw angle to the given value (radians); player input on this axis is ignored in this frame.
+-- @function [parent=#camera] setYaw
+-- @param #number value
+
+-------------------------------------------------------------------------------
+-- Get camera roll angle (radians).
+-- @function [parent=#camera] getRoll
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Set camera roll angle (radians).
+-- @function [parent=#camera] setRoll
+-- @param #number value
+
+-------------------------------------------------------------------------------
+-- Additional summand for the pitch angle that is not affected by player input.
+-- Full pitch is `getPitch()+getExtraPitch()`.
+-- @function [parent=#camera] getExtraPitch
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Additional summand for the pitch angle; useful for camera shaking effects.
+-- Setting extra pitch doesn't block player input.
+-- Full pitch is `getPitch()+getExtraPitch()`.
+-- @function [parent=#camera] setExtraPitch
+-- @param #number value
+
+-------------------------------------------------------------------------------
+-- Additional summand for the yaw angle that is not affected by player input.
+-- Full yaw is `getYaw()+getExtraYaw()`.
+-- @function [parent=#camera] getExtraYaw
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Additional summand for the yaw angle; useful for camera shaking effects.
+-- Setting extra pitch doesn't block player input.
+-- Full yaw is `getYaw()+getExtraYaw()`.
+-- @function [parent=#camera] setExtraYaw
+-- @param #number value
+
+-------------------------------------------------------------------------------
+-- Set camera position; can be used only if camera is in Static mode.
+-- @function [parent=#camera] setStaticPosition
+-- @param openmw.util#Vector3 pos
+
+-------------------------------------------------------------------------------
+-- The offset between the characters head and the camera in first person mode (3d vector).
+-- @function [parent=#camera] getFirstPersonOffset
+-- @return openmw.util#Vector3
+
+-------------------------------------------------------------------------------
+-- Set the offset between the characters head and the camera in first person mode (3d vector).
+-- @function [parent=#camera] setFirstPersonOffset
+-- @param openmw.util#Vector3 offset
+
+-------------------------------------------------------------------------------
+-- Preferred offset between tracked position (see `getTrackedPosition`) and the camera focal point (the center of the screen) in third person mode.
+-- See `setFocalPreferredOffset`.
+-- @function [parent=#camera] getFocalPreferredOffset
+-- @return openmw.util#Vector2
+
+-------------------------------------------------------------------------------
+-- Set preferred offset between tracked position (see `getTrackedPosition`) and the camera focal point (the center of the screen) in third person mode.
+-- The offset is a 2d vector (X, Y) where X is horizontal (to the right from the character) and Y component is vertical (upward).
+-- The real offset can differ from the preferred one during smooth transition of if blocked by an obstacle.
+-- Smooth transition happens by default every time when the preferred offset was changed. Use `instantTransition()` to skip the current transition.
+-- @function [parent=#camera] setFocalPreferredOffset
+-- @param openmw.util#Vector2 offset
+
+-------------------------------------------------------------------------------
+-- The actual distance between the camera and the character in third person mode; can differ from the preferred one if there is an obstacle.
+-- @function [parent=#camera] getThirdPersonDistance
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Set preferred distance between the camera and the character in third person mode.
+-- @function [parent=#camera] setPreferredThirdPersonDistance
+-- @param #number distance
+
+-------------------------------------------------------------------------------
+-- The current speed coefficient of focal point (the center of the screen in third person mode) smooth transition.
+-- @function [parent=#camera] getFocalTransitionSpeed
+-- @return #number
+
+-------------------------------------------------------------------------------
+-- Set the speed coefficient of focal point (the center of the screen in third person mode) smooth transition.
+-- Smooth transition happens by default every time when the preferred offset was changed. Use `instantTransition()` to skip the current transition.
+-- @function [parent=#camera] setFocalTransitionSpeed
+-- Set the speed coefficient 
+-- @param #number speed
+
+-------------------------------------------------------------------------------
+-- Make instant the current transition of camera focal point and the current deferred rotation (see `allowCharacterDeferredRotation`).
+-- @function [parent=#camera] instantTransition
+
+
+return nil
+