Verdigris Cloister
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
| Call | What it gives |
|---|---|
HOME | The 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.