Merge branch 'camera_script' into 'master'

[Lua] Support tags in I.Camera.disable*, I.Camera.enable* in the same way as in world.pause Closes #6652 See merge request OpenMW/openmw!3419
2025-03-15 22:21:00 +00:00 · 2023-10-05 17:24:24 +00:00 · 2023-10-05 17:24:24 +00:00 · 68684d3d0d
commit 68684d3d0d
parent d9f8757f33 54cc1f25a2
3 changed files with 87 additions and 49 deletions
--- a/files/data/scripts/omw/camera/camera.lua
+++ b/files/data/scripts/omw/camera/camera.lua
@ -39,10 +39,10 @@ end

 local primaryMode

-local noModeControl = 0
-local noStandingPreview = 0
-local noHeadBobbing = 0
-local noZoom = 0
+local noModeControl = {}
+local noStandingPreview = {}
+local noHeadBobbing = {}
+local noZoom = {}

 local function init()
    camera.setFieldOfView(camera.getBaseFieldOfView())
@ -117,19 +117,19 @@ local maxDistance = 800
 local function zoom(delta)
    if not input.getControlSwitch(input.CONTROL_SWITCH.ViewMode) or
       not input.getControlSwitch(input.CONTROL_SWITCH.Controls) or
-       camera.getMode() == MODE.Static or noZoom > 0 then
+       camera.getMode() == MODE.Static or next(noZoom) then
        return
    end
    if camera.getMode() ~= MODE.FirstPerson then
        local obstacleDelta = third_person.preferredDistance - camera.getThirdPersonDistance()
        if delta > 0 and third_person.baseDistance == minDistance and
-           (camera.getMode() ~= MODE.Preview or third_person.standingPreview) and noModeControl == 0 then
+           (camera.getMode() ~= MODE.Preview or third_person.standingPreview) and not next(noModeControl) then
            primaryMode = MODE.FirstPerson
            camera.setMode(primaryMode)
        elseif delta > 0 or obstacleDelta < -delta then
            third_person.baseDistance = util.clamp(third_person.baseDistance - delta - obstacleDelta, minDistance, maxDistance)
        end
-    elseif delta < 0 and noModeControl == 0 then
+    elseif delta < 0 and not next(noModeControl) then
        primaryMode = MODE.ThirdPerson
        camera.setMode(primaryMode)
        third_person.baseDistance = minDistance
@ -149,7 +149,7 @@ end

 local function updateStandingPreview()
    local mode = camera.getMode()
-    if not previewIfStandStill or noStandingPreview > 0
+    if not previewIfStandStill or next(noStandingPreview)
       or mode == MODE.FirstPerson or mode == MODE.Static or mode == MODE.Vanity then
        third_person.standingPreview = false
        return
@ -197,7 +197,7 @@ local function onFrame(dt)
        primaryMode = mode
    end
    if mode ~= MODE.Static then
-        if noModeControl == 0 then
+        if not next(noModeControl) then
            updatePOV(dt)
            updateVanity(dt)
        end
@ -206,7 +206,7 @@ local function onFrame(dt)
    end
    applyControllerZoom(dt)
    third_person.update(dt, smoothedSpeed)
-    if noHeadBobbing == 0 then head_bobbing.update(dt, smoothedSpeed) end
+    if not next(noHeadBobbing) then head_bobbing.update(dt, smoothedSpeed) end
    if slowViewChange then
        local maxIncrease = dt * (100 + third_person.baseDistance)
        camera.setPreferredThirdPersonDistance(
@ -221,54 +221,92 @@ return {
    -- @module Camera
    -- @usage require('openmw.interfaces').Camera
    interface = {
-        --- Interface version
+        --- Interface version is 1
        -- @field [parent=#Camera] #number version
-        version = 0,
+        version = 1,

        --- Return primary mode (MODE.FirstPerson or MODE.ThirdPerson).
        -- @function [parent=#Camera] getPrimaryMode
+        -- @return #number @{openmw.camera#MODE}
        getPrimaryMode = function() return primaryMode end,
-        --- @function [parent=#Camera] getBaseThirdPersonDistance
+
+        --- Get base third person distance (without applying angle and speed modifiers).
+        -- @function [parent=#Camera] getBaseThirdPersonDistance
+        -- @return #number
        getBaseThirdPersonDistance = function() return third_person.baseDistance end,
-        --- @function [parent=#Camera] setBaseThirdPersonDistance
+        --- Set base third person distance
+        -- @function [parent=#Camera] setBaseThirdPersonDistance
+        -- @param #number value
        setBaseThirdPersonDistance = function(v) third_person.baseDistance = v end,
-        --- @function [parent=#Camera] getTargetThirdPersonDistance
+        --- Get the desired third person distance if there would be no obstacles (with angle and speed modifiers)
+        -- @function [parent=#Camera] getTargetThirdPersonDistance
+        -- @return #number
        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,
+        --- Whether the built-in mode control logic is enabled.
+        -- @function [parent=#Camera] isModeControlEnabled
+        -- @return #boolean
+        isModeControlEnabled = function() return not next(noModeControl) end,
+        --- Disable with (optional) tag until the corresponding enable function is called with the same tag.
+        -- @function [parent=#Camera] disableModeControl
+        -- @param #string tag (optional, empty string by default) Will be disabled until the enabling function is called with the same tag
+        disableModeControl = function(tag) noModeControl[tag or ''] = true end,
+        --- Undo disableModeControl
+        -- @function [parent=#Camera] enableModeControl
+        -- @param #string tag (optional, empty string by default)
+        enableModeControl = function(tag) noModeControl[tag or ''] = nil end,

-        --- @function [parent=#Camera] isStandingPreviewEnabled
-        isStandingPreviewEnabled = function() return previewIfStandStill 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,
+        --- Whether the built-in standing preview logic is enabled.
+        -- @function [parent=#Camera] isStandingPreviewEnabled
+        -- @return #boolean
+        isStandingPreviewEnabled = function() return previewIfStandStill and not next(noStandingPreview) end,
+        --- Disable with (optional) tag until the corresponding enable function is called with the same tag.
+        -- @function [parent=#Camera] disableStandingPreview
+        -- @param #string tag (optional, empty string by default) Will be disabled until the enabling function is called with the same tag
+        disableStandingPreview = function(tag) noStandingPreview[tag or ''] = true end,
+        --- Undo disableStandingPreview
+        -- @function [parent=#Camera] enableStandingPreview
+        -- @param #string tag (optional, empty string by default)
+        enableStandingPreview = function(tag) noStandingPreview[tag or ''] = nil 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,
+        --- Whether head bobbing is enabled.
+        -- @function [parent=#Camera] isHeadBobbingEnabled
+        -- @return #boolean
+        isHeadBobbingEnabled = function() return head_bobbing.enabled and not next(noHeadBobbing) end,
+        --- Disable with (optional) tag until the corresponding enable function is called with the same tag.
+        -- @function [parent=#Camera] disableHeadBobbing
+        -- @param #string tag (optional, empty string by default) Will be disabled until the enabling function is called with the same tag
+        disableHeadBobbing = function(tag) noHeadBobbing[tag or ''] = true end,
+        --- Undo disableHeadBobbing
+        -- @function [parent=#Camera] enableHeadBobbing
+        -- @param #string tag (optional, empty string by default)
+        enableHeadBobbing = function(tag) noHeadBobbing[tag or ''] = nil 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,
+        --- Whether the built-in zooming is enabled.
+        -- @function [parent=#Camera] isZoomEnabled
+        -- @return #boolean
+        isZoomEnabled = function() return not next(noZoom) end,
+        --- Disable with (optional) tag until the corresponding enable function is called with the same tag.
+        -- @function [parent=#Camera] disableZoom
+        -- @param #string tag (optional, empty string by default) Will be disabled until the enabling function is called with the same tag
+        disableZoom = function(tag) noZoom[tag or ''] = true end,
+        --- Undo disableZoom
+        -- @function [parent=#Camera] enableZoom
+        -- @param #string tag (optional, empty string by default)
+        enableZoom = function(tag) noZoom[tag or ''] = nil 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,
+        --- Whether the the third person offset can be changed by the built-in camera script.
+        -- @function [parent=#Camera] isThirdPersonOffsetControlEnabled
+        -- @return #boolean
+        isThirdPersonOffsetControlEnabled = function() return not next(third_person.noOffsetControl) end,
+        --- Disable with (optional) tag until the corresponding enable function is called with the same tag.
+        -- @function [parent=#Camera] disableThirdPersonOffsetControl
+        -- @param #string tag (optional, empty string by default) Will be disabled until the enabling function is called with the same tag
+        disableThirdPersonOffsetControl = function(tag) third_person.noOffsetControl[tag or ''] = true end,
+        --- Undo disableThirdPersonOffsetControl
+        -- @function [parent=#Camera] enableThirdPersonOffsetControl
+        -- @param #string tag (optional, empty string by default)
+        enableThirdPersonOffsetControl = function(tag) third_person.noOffsetControl[tag or ''] = nil end,
    },
    engineHandlers = {
        onUpdate = onUpdate,
--- a/files/data/scripts/omw/camera/third_person.lua
+++ b/files/data/scripts/omw/camera/third_person.lua
@ -15,7 +15,7 @@ local M = {
    baseDistance = 192,
    preferredDistance = 0,
    standingPreview = false,
-    noOffsetControl = 0,
+    noOffsetControl = {},
 }

 local viewOverShoulder, autoSwitchShoulder
@ -142,7 +142,7 @@ function M.update(dt, smoothedSpeed)
        return
    end

-    if M.noOffsetControl == 0 then
+    if not next(M.noOffsetControl) then
        updateState()
    else
        state = nil
--- a/files/lua_api/openmw/world.lua
+++ b/files/lua_api/openmw/world.lua
@ -109,12 +109,12 @@
 ---
 -- Pause the game starting from the next frame.
 -- @function [parent=#world] pause
-- @param #string tag (optional) The game will be paused until `unpause` is called with the same tag.
+-- @param #string tag (optional, empty string by default) The game will be paused until `unpause` is called with the same tag.

 ---
 -- Remove given tag from the list of pause tags. Resume the game starting from the next frame if the list became empty.
 -- @function [parent=#world] unpause
-- @param #string tag (optional) Needed to undo `pause` called with this tag.
+-- @param #string tag (optional, empty string by default) Needed to undo `pause` called with this tag.

 ---
 -- The tags that are currently pausing the game.