# Cinema The staged frame: two cinema bands and a wash veil. It is a **UI screen**, laid out from the live `ui.screenSize()` — the one place in the engine welded to the picture. A band expressed as a share of the screen is exactly that share at 3:4, at 16:9 and at 21:9, with no lens arithmetic and no frame of lag behind a fast pan. That was learned the hard way. Hung in front of the lens as geometry — first parented to the camera rig, then placed in world space from the pose the camera had just taken — the bands slid away from the edges they are meant to be welded to whenever the shot moved quickly, because a mesh transform is composed against the camera's from the frame before. On a crane travelling two metres a second that is most of the frame height. In screen space the question does not arise. ## Using it ```lua local Cinema = require("game.stage.Cinema") Cinema.attach() -- once, when the camera wakes Cinema.bars(0.085, 0.7) -- one band = 8.5% of the frame, over 0.7 s Cinema.veil(0, 0, 0, 1, 0) -- wash the frame black, instantly Cinema.clear(0.8) -- bands out and wash off together Cinema.tick(dt) -- every frame; it paints itself Cinema.state() -- { bars, veil, shown } ``` `CrowCamera` drives all of it, so a beat reaches it through `CF.camera.bars` / `CF.camera.veil` / `CF.camera.clearFrame` rather than requiring this directly. ## Layering The screen sits at **layer 120** — the always-on-top band — so the bands cover the HUD while a moment is staged and stay under the menu depth (1000+) a card lives at. It is registered only while something is staged and unregistered the moment the frame is clear, so nothing of it stands between a player and a button. Each ending's shot lifts its own wash as the end card comes up, so a card is never read through a veil. Owned by the staging slice. Design: `/zero/source/design/spec.md`.

# CF The blackboard of *First Light: Crowfeet*. One module every part of the game requires: ```luau local CF = require("game.CF") ``` ## What is in it | | | |---|---| | `CF.RULES` | every number the game is tuned by | | `CF.PALETTE` | the colours everything composes to | | `CF.FILMED` | the shape the run films at (1080x1440) | | `CF.layout` | the cliff: `ledges`, `food`, `summitY`, `top`, `halfWidth`, `apex` | | `CF.state` | what is true right now | | `CF.landing` / `CF.grabbable` | the two ledging tests | | `CF.on` / `CF.off` / `CF.emit` | the event bus | | `CF.setPhase` / `CF.reset` / `CF.say` / `CF.progress` / `CF.sz` | | | `CF.camera` | filled in by the camera: `panTo` `zoomTo` `release` `kick` | ## The cliff `CF.layout.ledges` is 28 shelves from the strand at y 0 to the roost at `summitY`, each `{ id, x, y, w, kind, fallen }` with `kind` one of `strand` `rock` `crumble` `roost`. A shelf's TOP is at `y` and it spans `x ± w/2`. `CF.layout.food` is `{ id, ledge, kind, x, y, eaten }` with `kind` one of `grub` `limpet` `crowfoot`. It is built deterministically, so every peer and every slice sees the same cliff. Two numbers shape it. `CF.layout.apex` is how high one hop rises. Every SHORT gap is under it and is landed on; every TALL gap is over it, so the only way up is to catch the lip. And the shelf above a crumble shelf is placed back over the shelf below it, so a crumble that has given way never seals the climb. ## The two ledging tests - `CF.landing(x, yFrom, yTo)` — the shelf whose top the crow's feet crossed going down this frame, highest first. Returns nil, or the ledge. - `CF.grabbable(x, feetY, facing)` — the shelf whose near lip is within reach of an airborne crow's crown, in the direction it is facing. Returns nil, or the ledge and the x of that lip. Both ignore a shelf whose `fallen` is set. ## The state `phase` (`title` `opening` `climb` `won` `lost`) · `hunger` · `dawn` 0..1 · `time` · `crow { x, y, vx, vy, facing, grounded, hanging, ledge }` · `altitude` · `eaten` · `hops` · `crumbled` · `lostReason` (`starved` `sea` `late`) · `paused`. The climb slice writes it; everyone else reads it. `CF.reset()` puts a round back — the state, the food and the fallen shelves — and `restart` is answered here, so a round can always be put back. ## The events `start` `restart` `reset` `phase` `pause` · `hop` `land` `grab` `pullup` `drop` `peck` `eat` `tooWeak` `crumble` `crumbled` `fall` · `hungerLow` `firstLight` · `line` `ui`. `crumble` fires when the crow's weight first lands on a crumble shelf, and it has `RULES.crumbleDelay` left to stand. `crumbled` fires when it goes. ## Laying out for any screen `CF.sz(fraction)` is a fraction of the SHORTER screen edge, read live from `ui.screenSize()`, so one number lays out the same on a phone held either way and on a television.