mirror of
https://gitlab.com/OpenMW/openmw.git
synced 2025-01-15 22:49:48 +00:00
Update Lua docs
This commit is contained in:
parent
ded8997362
commit
73821ace94
@ -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
|
||||
|
||||
|
@ -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. |
|
||||
+---------------------------------------------------------+--------------------+---------------------------------------------------------------+
|
||||
|
||||
|
6
docs/source/reference/lua-scripting/interface_camera.rst
Normal file
6
docs/source/reference/lua-scripting/interface_camera.rst
Normal file
@ -0,0 +1,6 @@
|
||||
Interface Camera
|
||||
================
|
||||
|
||||
.. raw:: html
|
||||
:file: generated_html/scripts_omw_camera.html
|
||||
|
5
docs/source/reference/lua-scripting/openmw_camera.rst
Normal file
5
docs/source/reference/lua-scripting/openmw_camera.rst
Normal file
@ -0,0 +1,5 @@
|
||||
Package openmw.camera
|
||||
=====================
|
||||
|
||||
.. raw:: html
|
||||
:file: generated_html/openmw_camera.html
|
@ -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.
|
||||
- If you use `openmw_aux`_, add ``resources/vfs`` as an additional external source folder.
|
||||
- Specify there paths to ``resources/lua_api`` and ``resources/vfs`` in your OpenMW installation.
|
||||
|
||||
.. 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.
|
||||
|
@ -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 = {
|
||||
|
171
files/lua_api/openmw/camera.lua
Normal file
171
files/lua_api/openmw/camera.lua
Normal file
@ -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
|
||||
|
Loading…
Reference in New Issue
Block a user