Files
claudeandClaude Opus 5.5 53e3d92496
Ashlar checks / tooling (push) Successful in 5s
Modern third-person camera defaults, collision ease-out and aim mode
- Shoulder view, auto shoulder switch, standing preview, deferred preview
  rotation, move 360, smooth view change and [Game] smooth movement are
  on by default.
- Collision ease-out: the camera still snaps in on collision but eases
  back out (0.15 s half-life, 60 u/s minimum speed).
- Aim mode: with a ranged weapon or a spell readied in third person the
  view stays over the shoulder, moves closer and narrows the FOV. Camera
  interface v2 adds getAimWeight and enable/disable functions.
- Pure math in camera/ease.lua with unit tests; SCENARIO=camera with
  PASS/FAIL checks; docs in docs/ashlar/CAMERA.md.
- ashlar-run.sh deletes stored Lua settings before each run so changed
  defaults are tested.

Closes #29

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 15:45:11 -05:00

232 lines
8.9 KiB
Lua

local camera = require('openmw.camera')
local util = require('openmw.util')
local self = require('openmw.self')
local nearby = require('openmw.nearby')
local async = require('openmw.async')
local storage = require('openmw.storage')
local types = require('openmw.types')
local Actor = types.Actor
local ease = require('scripts.omw.camera.ease')
local settings = storage.playerSection('SettingsOMWCameraThirdPerson')
local MODE = camera.MODE
local STATE = { RightShoulder = 0, LeftShoulder = 1, Combat = 2, Swimming = 3 }
local M = {
baseDistance = 192,
preferredDistance = 0,
standingPreview = false,
noOffsetControl = {},
-- Ashlar aim mode: 0 = normal framing, 1 = full aim framing. noAim holds tags from disableAimMode.
aimWeight = 0,
aiming = false,
noAim = {},
}
local AIM_HALF_LIFE = 0.08 -- seconds; the aim framing blend is quick but not instant
local MIN_RECOVERY_SPEED = 60 -- units per second; keeps the end of the collision ease-out from crawling
local viewOverShoulder, autoSwitchShoulder
local shoulderOffset
local zoomOutWhenMoveCoef
local collisionEaseOut, collisionEaseOutTime
local aimMode, aimDistance, aimFieldOfView
local defaultShoulder, rightShoulderOffset, leftShoulderOffset
local combatOffset = util.vector2(0, 15)
local noThirdPersonLastFrame = true
local function updateSettings()
viewOverShoulder = settings:get('viewOverShoulder')
autoSwitchShoulder = settings:get('autoSwitchShoulder')
shoulderOffset = util.vector2(settings:get('shoulderOffsetX'),
settings:get('shoulderOffsetY'))
zoomOutWhenMoveCoef = settings:get('zoomOutWhenMoveCoef')
collisionEaseOut = settings:get('collisionEaseOut')
collisionEaseOutTime = settings:get('collisionEaseOutTime')
aimMode = settings:get('aimMode')
aimDistance = util.clamp(settings:get('aimDistance'), 0.3, 1)
aimFieldOfView = util.clamp(settings:get('aimFieldOfView'), 0.5, 1)
defaultShoulder = (shoulderOffset.x > 0 and STATE.RightShoulder) or STATE.LeftShoulder
rightShoulderOffset = util.vector2(math.abs(shoulderOffset.x), shoulderOffset.y)
leftShoulderOffset = util.vector2(-math.abs(shoulderOffset.x), shoulderOffset.y)
noThirdPersonLastFrame = true
end
updateSettings()
settings:subscribe(async:callback(updateSettings))
local state = defaultShoulder
local function ray(from, angle, limit)
local to = from + util.transform.rotateZ(angle) * util.vector3(0, limit, 0)
local res = nearby.castRay(from, to, { collisionType = camera.getCollisionType() })
if res.hit then
return (res.hitPos - from):length()
else
return limit
end
end
local function trySwitchShoulder()
local limitToSwitch = 120 -- switch to other shoulder if wall is closer than this limit
local limitToSwitchBack = 300 -- switch back to default shoulder if there is no walls at this distance
local pos = camera.getTrackedPosition()
local rayRight = ray(pos, camera.getYaw() + math.rad(90), limitToSwitchBack + 1)
local rayLeft = ray(pos, camera.getYaw() - math.rad(90), limitToSwitchBack + 1)
local rayRightForward = ray(pos, camera.getYaw() + math.rad(30), limitToSwitchBack + 1)
local rayLeftForward = ray(pos, camera.getYaw() - math.rad(30), limitToSwitchBack + 1)
local distRight = math.min(rayRight, rayRightForward)
local distLeft = math.min(rayLeft, rayLeftForward)
if distLeft < limitToSwitch and distRight > limitToSwitchBack then
state = STATE.RightShoulder
elseif distRight < limitToSwitch and distLeft > limitToSwitchBack then
state = STATE.LeftShoulder
elseif distRight > limitToSwitchBack and distLeft > limitToSwitchBack then
state = defaultShoulder
end
end
local function calculateDistance(smoothedSpeed)
local smoothedSpeedSqr = smoothedSpeed * smoothedSpeed
local distance = (M.baseDistance + math.max(camera.getPitch(), 0) * 50
+ smoothedSpeedSqr / (smoothedSpeedSqr + 300 * 300) * zoomOutWhenMoveCoef)
return ease.aimDistance(distance, aimDistance, M.aimWeight)
end
local RANGED = {}
for _, t in ipairs({ 'MarksmanBow', 'MarksmanCrossbow', 'MarksmanThrown' }) do
if types.Weapon.TYPE[t] then RANGED[types.Weapon.TYPE[t]] = true end
end
-- True while a spell or a ranged weapon is readied.
local function isAimStance()
local stance = Actor.getStance(self)
if stance == Actor.STANCE.Spell then
return true
end
if stance ~= Actor.STANCE.Weapon then
return false
end
local weapon = Actor.getEquipment(self, Actor.EQUIPMENT_SLOT.CarriedRight)
return weapon ~= nil and types.Weapon.objectIsInstance(weapon) and RANGED[types.Weapon.record(weapon).type] == true
end
-- Preferred distance for this frame when the camera wants to be at `target`. Moving in is immediate (the engine
-- clamps on collision anyway); moving back out eases, or is rate limited as in upstream OpenMW when the ease-out is
-- off.
function M.recover(dt, target)
local current = camera.getThirdPersonDistance()
if collisionEaseOut then
return ease.recoverDistance(current, target, dt, collisionEaseOutTime, MIN_RECOVERY_SPEED)
end
return math.min(target, current + dt * (100 + M.baseDistance))
end
local fovApplied = false
-- Ashlar aim mode: blends the aim weight and applies the field of view. Called every frame, in every camera mode, so
-- the framing relaxes when leaving third person.
function M.updateAim(dt)
local mode = camera.getMode()
M.aiming = aimMode and not next(M.noAim) and (mode == MODE.ThirdPerson or mode == MODE.Preview)
and isAimStance()
M.aimWeight = ease.approach(M.aimWeight, M.aiming and 1 or 0, dt, AIM_HALF_LIFE)
if M.aimWeight > 0 then
camera.setFieldOfView(ease.aimFieldOfView(camera.getBaseFieldOfView(), aimFieldOfView, M.aimWeight))
fovApplied = true
elseif fovApplied then
camera.setFieldOfView(camera.getBaseFieldOfView())
fovApplied = false
end
end
local function updateState()
local mode = camera.getMode()
local oldState = state
if Actor.getStance(self) ~= Actor.STANCE.Nothing and mode == MODE.ThirdPerson and not M.aiming then
-- Melee: centre the view. Aiming a ranged weapon or a spell keeps the shoulder view (Ashlar aim mode).
state = STATE.Combat
elseif Actor.isSwimming(self) then
state = STATE.Swimming
elseif oldState == STATE.Combat or oldState == STATE.Swimming then
state = defaultShoulder
elseif not state then
state = defaultShoulder
end
if (mode == MODE.ThirdPerson or Actor.getCurrentSpeed(self) > 0 or state ~= oldState or noThirdPersonLastFrame)
and (state == STATE.LeftShoulder or state == STATE.RightShoulder) then
if autoSwitchShoulder then
trySwitchShoulder()
else
state = defaultShoulder
end
end
if oldState ~= state or noThirdPersonLastFrame then
-- State was changed, start focal point transition.
if mode == MODE.Vanity then
-- Player doesn't touch controls for a long time. Transition should be very slow.
camera.setFocalTransitionSpeed(0.2)
elseif (oldState == STATE.Combat or state == STATE.Combat) and
(mode ~= MODE.Preview or M.standingPreview) then
-- Transition to/from combat mode and we are not in preview mode. Should be fast.
camera.setFocalTransitionSpeed(5.0)
else
camera.setFocalTransitionSpeed(1.0) -- Default transition speed.
end
if state == STATE.RightShoulder then
camera.setFocalPreferredOffset(rightShoulderOffset)
elseif state == STATE.LeftShoulder then
camera.setFocalPreferredOffset(leftShoulderOffset)
else
camera.setFocalPreferredOffset(combatOffset)
end
end
end
function M.update(dt, smoothedSpeed)
local mode = camera.getMode()
if mode == MODE.FirstPerson or mode == MODE.Static then
noThirdPersonLastFrame = true
return
end
if not viewOverShoulder then
M.preferredDistance = ease.aimDistance(M.baseDistance, aimDistance, M.aimWeight)
if noThirdPersonLastFrame or not collisionEaseOut then
camera.setPreferredThirdPersonDistance(M.preferredDistance)
else
camera.setPreferredThirdPersonDistance(M.recover(dt, M.preferredDistance))
end
if noThirdPersonLastFrame then
camera.setFocalPreferredOffset(util.vector2(0, 0))
camera.instantTransition()
noThirdPersonLastFrame = false
end
return
end
if not next(M.noOffsetControl) then
updateState()
else
state = nil
end
M.preferredDistance = calculateDistance(smoothedSpeed)
if noThirdPersonLastFrame then -- just switched to third person view
camera.setPreferredThirdPersonDistance(M.preferredDistance)
camera.instantTransition()
noThirdPersonLastFrame = false
else
camera.setPreferredThirdPersonDistance(M.recover(dt, M.preferredDistance))
end
end
return M