# staging.Beats The moments THE EIGHTH KETYL is remembered by, as camera data. Each function returns a `cutscene` definition built against the live screen and the live state of the run — the column's geometry out of `Still`, the framing solver out of `staging.Frame`, and the ketyl wherever it is standing. There is no literal camera position anywhere in this module. ```lua local Beats = require("staging.Beats") cutscene.play(Beats.opening(ketylBody, playSound)) cutscene.play(Beats.plateClear(3)) ``` ## The moments **`opening(body, onSound)`** — three shots. The shaft from below with the plates stacking up a tall frame; a drift across the plate you are about to play; a settle that ENDS on the pose the playing camera holds, so the handover is a continuation rather than a cut. Cut to `introSeconds()` — the core slice's own intro clock — because that slice hands the player their hands back on it whether or not a camera has finished. Cues `v_open_1..3`. **`plateClear(n, onSound)`** — 2.7 s. The frame leaves the ketyl, pushes onto the riser as it lights, holds long enough to be read, and gives the plate back. Short on purpose: it happens seven times. Cues `v_clear`. **`ascend(from, to, body, onSound)`** — 2.6 s in two shots: up through the mouth of the riser from the plate being left, then a rise onto the plate above as the ketyl arrives on it. Cues that plate's `v_plate_n`. **`sealed(body, onSound)`** — 11.6 s, and the only time the whole column is seen at once: in on the radical, a long crane down every plate it burned clean, then a held look back up the sealed still, fading to a dark violet. Cues `v_seal_1` and `v_seal_2`. **`quenched(body, plate, onSound)`** — 6.6 s. Close while there is still something to see, then away and down until the still is standing there without it. Fades to black. Cues `v_quench`. ## Stations `Beats.station(px, pz, dist, delta, y)` places an eye `dist` from a point on a plate, `delta` radians off directly-across-the-column, at height `y`. It solves the radius through `Frame.eyeRadius`, so a cinematic camera is never outside the sealed still looking at the outside of black glass. `Frame.ring(angle, y, radiusFrac)` is the same idea for a shot that orbits the axis rather than a subject. ## Anchors are ids, not proxies Every shot that follows the ketyl names it by **id string**. A cutscene anchor reads a value as a position before it reads it as an entity, and an entity proxy raises when it is indexed that way — so a proxy anchor refuses the whole cutscene. An id is the same subject, tracked the same way, through a path that works.

# Still One-paragraph description of what this module provides and who consumes it. ## Exports - `M.exampleFn(arg) -> result` — what it does and when to call it. - `M.exampleValue: type` — what value it carries. ## Usage Replace `<identity>` with the string `asset.create` returned — this module's source path with `/` written as `.` and each segment's type suffix dropped, the way a module at `/source/lib/thing.module` is `lib.thing` and one at `/source/kit.package/thing.module` is `kit.thing`. ```luau local M = require("<identity>") M.exampleFn("foo") ``` ## Notes - Anything callers need to know about THIS module: required runtime ordering, state ownership, side effects.

# stg_frame The sound of the camera taking the frame: a sub dropping from 100 Hz to 38, a breath of dark air, and one faint brass partial at 312 Hz. 0.85 s, mono, 48 kHz, synthesised from raw PCM. Played by the `Staging` component under the opening, the plate-clear beat and the quench, below whatever the sound slice plays on the same moment.

# console The controls a CARD answers to: the title, the how-to-play handbill, the interval between two acts, the pause card and the two end cards. It is live exactly while a card is up — `game.ui.Screens` activates it the instant one goes up and releases it the instant the last one comes down. Its group is `ui`, and it stands down `player` and `table`, so nothing behind a card answers while the card has the player. | Control | Keyboard | Pad | Touch | |---|---|---|---| | `navigate` | Arrows or WASD | Left stick | — the rows | | `confirm` | Space or Enter | South (A / Cross) | — the rows | | `back` | Backspace | East (B / Circle) | — the row that says so | | `resume` | Escape | Start | — the Resume row | `navigate` binds each direction to two keys at once — the WASD key and the arrow key beside it — because a player reaching for a menu uses whichever is already under their hand. ## Why no touch class Every row of every card is a button under a finger: tapping one moves the focus there and acts on it in the same gesture. A finger does not walk a menu to reach a row and then confirm it — it puts itself on the row. So each of these four declares `touch = false` rather than adding an on-screen stick and three unlabelled circles that would each be a second, worse way to do what the card already is. Backing out is the how-to's Back row and the pause card's Resume row; leaving the table is the pause glyph the Table draws.

# KetylCam The playing camera of THE EIGHTH KETYL. A camera `behavior`, installed by the `Staging` component on the player's `CameraRig` in place of the orbital rig the scene ships with. ## The shot The ketyl drifts on a disc eighteen units across inside a glass column twenty-three across, so a camera standing *behind* it at any readable distance would be outside the still, looking in through black glass. Instead the eye stands **across the column** from the ketyl and solves its own distance from the axis so the subject is always the same size: ``` glass wall glass wall ────┬───────────────────────────────────────────────────────────┬──── │ eye ●──────────── dist ────────────▶ ● ketyl │ │ (radius solved) axis│ │ ``` The shaft, the plate the ketyl is on and the plate above it are therefore always behind the subject — plate edges receding upward, which is the composition the whole game is built on. `staging.Frame` solves `dist` and the lens from the LIVE screen, so a tall screen and a wide one both hold the play; on a screen taller than 3:4 the eye stops at the wall and opens the lens instead of retreating through it. ## Looking The pilot aims nothing. It forwards the look control as `Still.emit("look", v, dt, active)` and this consumes it: horizontal swings the eye around the column, stopped short of the angle at which it would have to pass through the glass, and vertical raises and lowers it between looking up the shaft and looking down on the plate. Let go and the shot walks itself back across the column after `recentreDelay`. ## Two modes `mode` is `"auto"` by default, which reads the run's phase: the title gets a slow attract orbit of the still with the shaft up the middle of a tall frame, and everything else gets the playing shot. `"play"` and `"attract"` force one. ## Fields | Field | Default | What it does | |---|---|---| | `follow` | — | The ketyl. Empty, it reads `Camera.follow`. | | `mode` | `"auto"` | `"auto"` · `"play"` · `"attract"`. | | `yawRange` | 1.75 rad | How far round the column the player may swing the shot, on top of the limit the geometry imposes. | | `lookSpeedX` / `lookSpeedY` | 0.0042 / 0.0090 | Look sensitivity. | | `dampPos` / `dampYaw` | 0.14 / 0.22 s | How far behind the subject the shot trails. | | `recentreDelay` / `recentreRate` | 2.6 s / 0.55 | When and how fast an unattended shot returns to across-the-column. | | `clearance` | 0.35 | The sphere swept from the aim point out to the eye; anything it meets brings the eye in. Zero leaves the shot alone. | ## Methods ```lua local cam = entity(rigId).component.get("KetylCam") cam:snap() -- land on the solved pose with no damping cam:recentre() -- undo whatever the player swung it to cam:report() -- mode, eye radius, yaw, climb, distance, lens, aspect ```

# staging.Frame How THE EIGHTH KETYL is framed, at any screen shape. A shot is authored here as a **world box it has to hold** — so many units tall, so many units wide — and the distance and the lens are solved for the screen as it is right now. Nothing in this module is a pixel and nothing in it is a number picked while looking at one viewport. The game films at 1080x1440, so the vertical extent usually decides the shot: a wider screen holding the same vertical box simply gains margin at the sides. On a screen TALLER than 3:4 the horizontal extent takes over, and past `DISTANCE_CAP` the camera opens the lens rather than backing out through the glass wall of the still. ```lua local Frame = require("staging.Frame") local shot = Frame.play(ketylRadius) -- dist, fov, orbitLimit, aspect, portrait local R = Frame.eyeRadius(r, shot.dist, 0) -- where the eye stands, from the axis local p = Frame.ring(angle, y, 0.85) -- a point just inside the glass ``` ## The gameplay box | | | | |---|---|---| | `PLAY_V` | 12.0 | World units of height the playing shot holds — the plate you are on to the underside of the plate above. | | `PLAY_H` | 9.4 | World units of width — the room the ketyl is read moving in, not the whole plate. | | `FOV_BASE` / `FOV_MAX` | 58° / 78° | The lens it prefers, and how wide it may open on a very tall screen. | | `AIM_RISE` / `EYE_RISE` | 2.3 / 3.3 | The aim point above the plate floor, and the eye above that — a look down of about seventeen degrees. | | `EYE_MAX_RADIUS` | `COLUMN_RADIUS - 0.4` | The eye never leaves the still. | ## Solving the orbit `Frame.play(r)` returns `orbitLimit`, the angle the eye may be swung off "directly across the column" before its solved radius would reach the wall: ``` R(d) = r·cos d + sqrt(dist² − r²·sin² d) ≤ Rmax ⟺ cos d ≤ (Rmax² − dist² + r²) / (2·Rmax·r) ``` `Frame.eyeRadius(r, dist, delta)` is that solve, clamped inside the still. The cinematics in `staging.Beats` place every one of their stations with it, so a beat filmed on a phone and the same beat on a television are the same shot.

# staging.Bus One armed set of listeners on the shared event bus, for the staging slice. ```lua local Bus = require("staging.Bus") Bus.arm({ plateCleared = function(n) ... end, sealed = function() ... end }) Bus.disarm() Bus.count() -- how many are armed right now ``` A component's `init.luau` is re-executed on every hot reload, and the reload does not fire `onDestroy`: the previous chunk's module-level locals come back empty while its closures are still subscribed. Left alone, the staging director would end up with two of every listener after two edits, and a plate going clean would play its beat twice. Holding the subscriptions here fixes that. This module is edited far less often than the director it serves, so its state survives the director's reloads, and `arm` drops whatever it was holding before it takes the new set.

# staging.Voice Cueing the spoken lines of THE EIGHTH KETYL. Staging decides WHEN a line is heard and WHO says it. It never writes the words: the sound slice owns the script and the audio. This module is the join between the two. ```lua local Voice = require("staging.Voice") Voice.say("v_clear") -- announce it, and end it when it is over Voice.speakerOf("v_low") -- "column" Voice.ids() -- every id staging knows how to cue ``` `say` announces `line(id, text, speaker)` on the shared bus and `lineEnd(id)` when the line is finished. The sound slice speaks it; a screen prints it. The written form travels with the announcement when the sound slice's clip library (`audio.Clips`) can supply one, and the line is still announced by id when it cannot — a line with no audio is a quiet line, not a lost one. A second cue closes the first, so a caption is never stranded on screen. ## Who says what | id | speaker | |---|---| | `v_open_1` `v_open_2` `v_open_3` | the chemist, over the opening | | `v_plate_2` … `v_plate_8` | the column, arriving on that plate | | `v_clear` | the chemist, a plate goes clean | | `v_low` | the column, charge critical | | `v_wet` | the chemist, wetness critical | | `v_quench` | the chemist, the loss | | `v_seal_1` `v_seal_2` | the chemist, the win |

# stg_rise The ascent: air and a tone climbing the shaft together — a sweep from 130 Hz up past 670 with a band of noise opening behind it, both swelling and falling away inside 1.7 s. Mono, 48 kHz, synthesised from raw PCM. Played by the `Staging` component when the camera follows the ketyl up through a riser.

# stg_reveal The seal: a slow swell under the whole column being seen at once — a stack of partials on 58 Hz coming up over a second and a half, a shimmer on 880 and 1319 crossing the middle of it, and a long fall away. 3.4 s, mono, 48 kHz, synthesised from raw PCM. Played by the `Staging` component when the resolution shot begins.

# back The 'Back' control.

# confirm The 'Confirm' control.

# navigate Walking the rows of a card: one flick is one step, a held stick repeats. Each keyboard direction answers to TWO keys — the WASD key and the arrow key beside it — because a player reaching for a menu uses whichever is already under their hand. An axis takes one binding per device class, so each direction is itself a vector of the two keys that mean it. On a pad it is the left stick; under a thumb it is the on-screen stick in the left zone.

# resume The 'Resume' control.