FacerCam

The camera behaviour of First Light: Resown, on the PlayerPrototype's CameraRig. It stands behind and above the Facer, at the shrine's side of the hill, looking down the terraces toward the valley where the sun rises — and it never rotates. The hill is the picture, the dawn at the top of it is where every frame points, and the terraces stack up the screen.

The framing rule

Framing is stated as an AREA of hillside the frame must contain, at the subject's depth: frameWidth metres across it and frameHeight metres up it. The distance is solved every frame so both fit at the live viewport aspect — the larger of the two solutions wins.

That is what makes one camera work on every screen. A tall phone is width-limited, sits far back and sees a great deal of hill above and below the Facer; a wide monitor is height-limited, sits closer and sees the same run of terraces with room to either side. A width-only solve would pull the camera in the moment the frame got wide and crop the hill out of its own game.

pitch, fov, lookAhead and damping shape the shot. lookAhead pushes the look-at point down the hill from the Facer, which is what puts them in the lower part of the picture with the terraces beyond filling the rest; it is a FRACTION of the solved distance, so the Facer holds the same place in the frame whatever shape the screen is. pitch and fov together decide how much sky the frame carries: the top edge sits at pitch - fov/2 relative to the horizon, so a steep pitch with a narrow lens fills the upper half of every frame with distant valley floor. The camera also rides up over the shrine rather than standing inside it, keeping its distance from the pivot so the Facer does not swell as it lifts.

aspectOverride solves the framing for a stated width/height ratio instead of the live viewport's, so the shape a phone or a television sees can be framed and captured on an engine running at one fixed size. 0 uses the live viewport, which is what ships.

Handing the camera to a staged moment

game.stage.Stage drives the rig through these, and nothing else should:

local cam = entity(camera.main()).component.get("game.core.FacerCam")
local pose = cam:followPose()                 -- what the follow wants this frame, or nil
cam:stageTake()                               -- the follow stops solving
cam:stagePose(cx, cy, cz, px, py, pz, fovDeg) -- one frame of a scripted move
cam:isStaged()                                -- is a move holding it?
cam:stageRelease()                            -- give it back

A staged pose is written through the same damper the follow uses, so releasing glides home from wherever the move ended rather than snapping back to where the follow was standing when the move began. followPose() is how a move starts from the live framing and lands exactly on it.

Owned by the staging slice. Consumed by the scene's CameraRig through Camera.behavior.