Log inGet started
World

Verdigris Cloister

Branchmain
Branchesmain
Commit65770846aa

README.md

game.cam.camrig

The tactical camera's maths, with no opinions about input.

A station is a target point on the board plus a yaw, a pitch, a distance and a field of view. newState() makes one sitting at HOME — the station the game is composed at — and everything else here turns a station into a world pose, holds it inside limits, or eases it.

local CamRig = require("game.cam.camrig")

local s = CamRig.newState()
s.yaw = s.yaw + 40
CamRig.clamp(s)          -- hold it where the frame can carry it
CamRig.ease(s, dt)       -- move the live values toward the asked-for ones
CamRig.apply(s, entity(camera.main()))

Why fitDistance exists

The screen is 1080x1440 — taller than it is wide — so horizontal room is the scarce resource. The board is 8 tiles wide and 10 deep, which means its projected width changes by a quarter as the camera swings: 16 units across at the composed yaw, 20 units across side-on. A fixed distance that frames it at one angle puts its edges off the sides at another.

fitDistance(yaw, fov) derives the closest the camera may stand at a given yaw and still hold the whole board, and clamp uses it as the distance floor. That is what makes the board legible at every angle rather than only the one it was composed at.

MARGIN is the room past a tight geometric fit, and it was measured against a capture rather than derived: perspective widens whatever is nearest the lens, so a mathematically exact fit still puts the board's near corners on the frame edge.

Surface

CallWhat it gives
HOMEThe composed station: yaw 196, pitch -47, dist 34, target (0.8, -5, 0), fov 55.
newState()A station at HOME with its eased copy in step.
clamp(s)Pitch, distance and target held inside what the frame carries.
ease(s, dt, rate?)Move the live values toward the asked-for ones.
snap(s)Cut instead of move.
eye(s)The world position the camera stands at.
quat(yaw, pitch)The rotation for a station.
forward(yaw, pitch)The unit forward vector.
rightXZ(yaw)Screen-right in the XZ plane.
fitDistance(yaw, fov)The closest the camera may stand at that yaw.
focusTile(s, x, y, k?)Lean the target toward a tile.

PITCH_MIN / PITCH_MAX / DIST_MAX / MARGIN are the limits, and they are readable and writable if a mission wants a different frame.