# fl <!-- zero:scaffolded-readme --> <!-- Replace the line below with what this module provides and who consumes it, then delete both comment lines. --> TODO: describe this module.

# game.staging.beats The four moments the camera of *First Light: Goura* takes itself away from Tawpy for. `FloorCam.component` runs them; this module holds their shape. ```luau local Beats = require("game.staging.beats") cutscene.play(Beats.opening(ctx, narratorLine)) -- the opening local pose = Beats.seen(t, ctx) -- t runs 0 → 1 ``` ## The opening — a cutscene The opening is a real `cutscene`: a shot list, letterbox bands, a fade up out of the night's own colour, and the narrator's line as a subtitle. It ends by giving the game back, however it ended — played out, skipped, or stopped. Three shots, continuous: 1. **The crown.** A station under the canopy, looking up the lane at the head of the roost tree, rising and pushing slowly in. It sits under the canopy on purpose: the shot has to read at every light the run can open on, and a station out above the canopy is a legible silhouette at dawn and a dark mass at night. Under it there are always trunks, shafts and canopy. 2. **Down the lane.** The camera falls out of the canopy and retreats the whole length of the lane, past her, while the aim comes off the crown and settles on the floor ahead. **Every look anchor sits further up the lane than the camera does** — that one rule is what keeps the aim from swinging across the frame, and it is the difference between a descent and a whip. She arrives in the last second of it, tiny, at the bottom of the lane. 3. **The settle.** The camera comes down onto exactly the pose the chase camera takes over, with her in frame the whole way, so the hand-off is a continuation and not a cut. `Beats.replayShots` is the short form — the settle alone, 2.6 s, no line. The first night gets the whole opening; every retry after it gets this, because eleven seconds between two attempts is a wall rather than a beat. Escape is deliberately not a skip key here (`SKIP_KEYS`), and `staging.inputMap` leaves it off too: Escape is the pause control, and a key that both ends the opening and opens the pause card lands the player on a menu they did not ask for. ## The three pose beats `Beats.seen`, `Beats.won` and `Beats.lost` are functions of a normalised clock and a `ctx` of live readings. They return `{ px, py, pz, ax, ay, az, fov }`. | Beat | What it does | |---|---| | `seen` | 1.7 s. Drops to the floor behind her and looks past her INTO the sweep, so the shot is her small in the near frame and the eagle's shadow coming on beyond her. Then pushes in twice, a beat apart: the heartbeat. | | `won` | 7.0 s. Leaves her at the foot of the tree and rises with the flock's boom, out to where the crown stands against the sun that has just cleared it. | | `lost` | 5.4 s. Does not look away. Climbs and widens until she is a small dark thing on a floor the light has filled. | `seen` hands the camera straight back; the two end beats hold their last frame under the end card until the phase moves on. ## No state Nothing here reads the world — every beat is handed its `ctx` — so the module holds nothing a hot reload can lose, and any beat can be evaluated without playing it. That is how the filmstrips were taken: ```luau local eye, at, fov = cutscene.evaluate(Beats.openingShots(ctx), 5.8) ``` then `capture` from that station. It is much faster than watching the shot forty times, and it does not disturb anyone else playing in the world. ## What it needs from the other slices `ctx.crown` is where the roost tree's head is. `FloorCam` reads it from `FL.get("roost")` when the floor slice publishes one, and otherwise from its own `crownHeight` / `crownBeyond` fields against `FL.LANE`. **A published `roost.crown()` would be the better contract** — the opening and the win are both aimed at a landmark the floor slice owns and moves.

# game.staging.follow The solver behind the chase camera of *First Light: Goura*. `FloorCam.component` owns the state and the fields; this module owns the maths. ```luau local Follow = require("game.staging.follow") local cam = Follow.new() Follow.advance(cam, tuning, player.state(), dt) local pose = Follow.solve(cam, tuning, subject, dt) ``` ## What it solves The camera stands a fixed distance **behind** and **above** Tawpy — those are metres and they do not change with the screen. What *does* change with the screen is where it aims: the pitch is solved every frame so she lands at `subjectScreenY` down the frame under the **live** field of view. That is the whole reason the framing survives a change of shape. A wide screen gets a shorter vertical fov (`Follow.fov()` blends `FL.CAMERA.fovTall` at 3:4 into `FL.CAMERA.fovWide` at 16:10 and holds outside that range), and a shorter fov with a fixed aim point would slide her down and off the bottom. Solving the pitch from the fraction instead keeps her in the lower third at every aspect, and hands whatever room is left over to the lane ahead. `Follow.fov()` reads `ui.screenSize()` through `FL.screen()`, so it answers to the live viewport rather than to the one this was authored on. ## What it feels like | Behaviour | How | |---|---| | Lead | The aim leans `lateralLead` metres the way she is heading, smoothed. | | Lag | Sideways the camera chases at `lateralChase`, up the lane at `chase`. The difference is what makes a side-step read. | | Breath | While she gathers a flurry the rig eases in and the lens tightens; the release throws it back and opens up. | | Push | A boom dollies in and narrows the lens, then springs home. | | Drift | A hand-held sway proportional to her speed, small enough to feel and not to notice. | The breath and the push are three critically-damped springs — a dolly, a lift and a lens — plus a per-state bias the springs sit on. `Follow.impulse(st, kind, power)` kicks them; the kinds are `boom`, `flurry`, `step`, `seen`, `answered` and `heartbeat`. ## State `Follow.new()` returns the state table; the module holds none of its own, so a hot reload of this file costs nothing. `Follow.unseat(st)` forgets where the camera was, so the next solve seats it outright — what a beat or a cutscene calls when it hands the view back, instead of gliding in from wherever the cutscene left the rig.

# game.staging.moments What the forest floor does when something happens in *First Light: Goura*. ```luau local Moments = require("game.staging.moments") Moments.boom({ x = 0, y = 0, z = -40 }) ``` `FloorCam.component` subscribes to the `FL` bus and calls these; nothing else needs to. | Call | Event | What is on the floor | |---|---|---| | `boom` | `FL.EVENTS.boom` | A close, pale ring that runs out fast and is gone. This is the one that fires most, so it is the smallest. | | `answered` | `FL.EVENTS.answered` | A wide gold ring under her, and a second under the caller at the lane's edge a beat later — so the answer reads as having carried. | | `failance` | `FL.EVENTS.failance` | One ember ring, low and slow, dying where it started. The failance has a shape too. | | `flurry` | `FL.EVENTS.flurry` | The scuff a flurry kicks off the litter, scaled by how much she gathered. | | `caught` | `FL.EVENTS.caught` | A pair of builtin bursts standing in for the body feathers and the down, `fl_feather_burst` beside them, over a fast maroon ring where she was standing. | | `roost` | `FL.EVENTS.roost` | A slow, wide gold ring at the foot of the roost tree. | The rings are `@builtin::systems.effects.combat.shockwaveRing`, recoloured from `FL.PALETTE` and laid flat on the floor plane. The scuff and the throw are the builtin impact on its `dirt` surface. The feather burst is this slice's own effect asset, `fl_feather_burst.effect`, resolved once and cached. That asset lives at the **root** of `/source` rather than beside these files, and it is currently **drawn by nothing** — two engine defects, both recorded in its own README and filed as OrigoZero/zero#11944 and #10047. `caught` therefore throws a pair of builtin bursts to carry the moment and plays the authored one beside them, so the real feather burst appears of its own accord the day the runtime steps it. Everything is played through the pooled `effects` runtime, so firing them repeatedly costs what the first one did and nothing survives the play they were fired in. ## Reading them back Particles advance on the **play** clock: in edit mode a play holds live particles and submits nothing, which is why these read as silent there and not as broken. `effects.observe()` answers what is live, leased and silent, and `handle:whySilent()` names the reason from a closed set. A ring runs out in about a third of a second, which is shorter than the gap between two tool calls — so to see one, slow the clock rather than trying to time the shutter: ```luau engine.timeScale = 0.12 -- the ring now takes ~3 s of wall time FL.emit(FL.EVENTS.boom, { position = p }) -- capture engine.timeScale = 1 ```