# screens.frontend
Every authored screen in *The Hernsew Lingster*, and the one thing that decides
which of them is on the glass. It goes on the scene's `Screens` anchor.
The trees live in `screens.cards` (title, how-to, pause, both endings) and
`screens.hud` (the tide gauge, the yowe tally, the station ladder, the
phrasebook, the encounter panel, the caption band). This component owns
registration, visibility, and the callbacks the buttons raise.
Everything is laid out for **1080 × 1440** — a portrait frame. The tide gauge is
a column up the left edge, the ladder is a stack at the top right, and anything
that needs width is a band at the foot. There is no row of buttons anywhere.
## What it reads
Off the `game.rules` blackboard, all of it optional — a slice that has not
landed is a missing number, never a crash:
`PHASE` · `TIDE_T` · `YOWES` · `STATION` · `LEARNED` · `ENCOUNTER`
and, when they exist, `tongue.book` (the encounter model and the phrasebook
records, which carry each glyph's own drawing) and `sound.voice` (through the
caption signal below).
Until something writes `PHASE`, this component drives its own copy, so the game
opens on a title card rather than cold on gameplay. It stops the moment the
real owner writes the key.
## What it raises
`Rules.SIGNAL.UI_CLICK(kind)` on every press — `begin`, `open`, `close`,
`resume`, `pause`, `answer` — so the sound slice can answer a button.
Plus the five the run slice can act on:
| signal | when |
|---|---|
| `hernsew:uiBegin` | BEGIN THE CROSSING on the title |
| `hernsew:uiPause` / `hernsew:uiResume` | the run was held, or let go |
| `hernsew:uiRestart` | CROSS AGAIN on an end card |
| `hernsew:uiQuit` | the crossing was abandoned |
Answering a hernsew goes through `tongue.book.answer(optionId)`; the panel then
holds for a beat with the right option lit and the literal reading of the call
under it, and closes itself.
## Subtitles
`screens.captions` is the surface. Any slice with a spoken line calls
`Captions.say(text, who, seconds)` or emits `hernsew:say` — `sound.voice`
already does the latter for every line it speaks and every line it fails to
speak, so a failed generation is a quiet line rather than a lost one.
## Looking at a screen before its slice has landed
local c = entity.find("Screens").component.get("frontend")
c:setPhase("won")
c:previewEncounter(require("tongue.book").open("drownway"))
The run slice's own `PHASE` wins again the moment it writes one.
# interpreter — the Lingster's ear
Attached to the `Tongue` anchor by the scene build. It renders nothing: it
turns a heron's hail into an open encounter, speaks the line aloud if the sound
slice has landed, takes the player's reading, and raises `ANSWERED`.
## Wiring
| | |
|---|---|
| hears | `HAILED(stationId)` → opens the beat at that post |
| | `GATE_OPENED(stationId)` → closes it |
| | `PHASE("title" / "opening")` → a new run resets the phrasebook |
| raises | `ANSWERED(stationId, correct)` (through `tongue.book`) |
| writes | `Rules.state[KEY.ENCOUNTER]`, `Rules.state[KEY.LEARNED]` |
## Answering
```lua
entity.find("Tongue").component.get("interpreter"):answer("eelbank.1")
-- or, from anywhere:
require("tongue.book").answer("eelbank.1")
```
## Methods
| | |
|---|---|
| `:answer(optionId)` | give a reading; `true` when it is right |
| `:openAt(stationId)` | open a post by hand |
| `:hint()` | the hint for the open post, or `""` |
| `:resetRun()` | back to the starting phrasebook |
| `:pollHail()` | the proximity stand-in, below |
## Fields
`station`, `speaker`, `call`, `learnedCount`, `glyphCount`, `attempts` mirror
the book, so a screen or an inspector can read the beat without requiring the
module. `voiced` speaks the lines through `sound.voice` when that slice is
present. `autoHail` arms the proximity stand-in.
## The proximity stand-in
The heron slice owns the hail. Until it lands, `pollHail` raises `HAILED` for
whichever post the Lingster is standing at, reading `KEY.LINGSTER_Z` against
`Rules.HAIL_RADIUS`, so the beat is playable on its own. The first time a hail
arrives from anywhere else it switches itself off for good.
# rules
<!-- 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.
# stage.moments
The three moments *The Hernsew Lingster* earns, and the camera that attends to
them. Put it on the `Stage` anchor; it needs nothing else.
```lua
entity.find("Stage").component.add("stage.moments", {})
```
## The beats
| Beat | When | What it is |
|---|---|---|
| **opening** | `PHASE("opening")`, or by itself when nothing publishes a phase | Low across the black water in toward the Low Staithe, a rise that turns the causeway away up the tall axis of the 3:4 frame, then a settle onto the camera the player is about to be handed. Framed on wherever the Lingster stands, so at a real start these are the Staithe's own coordinates. |
| **crest** | `PHASE("crest")` | Plank height, with the tide sliding across the bottom of the frame; then a lift that answers how much causeway is left. Framed where she is standing when the water goes over. |
| **resolution** | `PHASE("won")` / `PHASE("lost")` | Won: the Fold from the fen side, a pull back and up, and a held shot under the gate lamp. Lost: eye-level with the water that took the run, then one long pull straight up until the causeway is a thread. |
A fourth, the **title drift**, plays under `PHASE("title")`: one slow move
across the fen with no bands and no lines, so the title card has weather behind
it instead of a still. It gives the camera back the moment the run leaves
`title`.
## What it also owns
- **The lantern.** A warm point light and a small lamp that follow the Lingster
the whole run, breathing slightly. The palette says the lantern and the
herons are the only bright things in the fen; this is the lantern.
- **The Fold lamp.** A lamp burning behind the High Fold's gate, so the end of
the causeway is a thing worth walking toward from a hundred metres down it.
- **Three synthesised one-shots** — `stage.open_drone`, `stage.crest_swell`,
`stage.fold_bell` — built from raw PCM in Luau at `awake`, so a beat is never
silent because a credit-metered service was busy.
## Speaking
Every line is in `stage.lines`. The director speaks them through
`sound.voice` — `Voice.line(id)` when the bake reached that id, `Voice.say`
otherwise — and both of those raise the caption signal the screens slice draws
its subtitle bar from, so the words are on screen whether or not they were
heard. With no `sound.voice` in the world at all, the director draws its own
caption instead, clear of the letterbox band.
## Fields
| Field | Default | What it does |
|---|---|---|
| `staging` | `true` | Whether it stages anything at all. |
| `autoOpen` | `true` | Open the game on the opening beat when nothing publishes a phase. |
| `lantern` | `true` | Carry the lantern. |
| `foldLamp` | `true` | Burn the lamp on the Fold. |
| `titleDrift` | `true` | Drift the camera behind the title card. |
## Methods
`playOpening()` · `playCrest()` · `playResolution("won" | "lost")` ·
`replay(beat)` · `isStaging()` · `report()`
The beats are once per run. `replay` is how one is watched, captured and tuned
without playing the whole game to reach it — `replay("opening")`,
`replay("crest")`, `replay("won")`, `replay("lost")`, `replay("title")`.
# flock.shepherd
The six yowes of Yowe Fen, and everything that happens to them.
Attached to the scene's `Flock` anchor. It builds the animals, drives them up
the causeway ahead of the Lingster, scatters them when a hernsew is answered
wrongly, and lets the tide take the ones that are caught by it.
## The verb
The flock stands **ahead** of the Lingster, not behind. Walking at their backs
pushes them on — that is what driving a flock is, and it is also the only
arrangement the game's camera can see, since the shot looks up-fen over the
player's shoulder.
Each animal holds a slot in a loose formation, keeps its distance from its
neighbours, and gives way when the Lingster's body comes inside its personal
space. A flock does not walk back to its shepherd: if the Lingster falls
behind, the yowes drift and graze rather than trotting down the causeway to be
near you.
## What barred, frightened and drowned look like
- **A gate** — while a hernsew is unanswered its gate bars the way, and the
flock crowds up against the rail, each animal stopping a slightly different
distance short of it.
- **A wrong answer** — the flock bolts sideways off the causeway, into the
marsh either side, and comes back over the next few seconds. There is a
leash on it; nothing runs out of frame.
- **The water** — the marsh drops away fast at the causeway's edge, so a yowe
that scattered is standing lower than one on the deck, and the tide reaches
it first. Wading is slow. An animal whose footing has been under water long
enough is taken: it goes down where it stands, `YOWE_LOST` is raised, and
the count drops. Each has its own nerve, so the fen takes them one at a time
rather than all on the same frame.
## What it publishes
| | |
|---|---|
| `YOWES` | how many are still with you |
| `LINGSTER_Z` | how far up the fen the Lingster stands |
| `YOWE_LOST(remaining)` | raised the moment the water takes one |
`flock.state` is the module the rest of the game reads it through —
`Flock.count()`, `Flock.leader()`, `Flock.members()`.
## Fields worth knowing
| field | what it does |
|---|---|
| `followDistance` | how far up-fen of the Lingster the front of the flock stands |
| `personalSpace` | how close the Lingster gets before an animal gives way |
| `separation` | how loosely they bunch |
| `drownSeconds` | how long a yowe survives with its footing under water |
| `tideOverride` | a water level used instead of the run's, while it is above -900 — for staging a beat, or for testing the drowning without advancing the run |
| `yowes` | read-only: the live count |
Two methods: `:scatter()` panics the flock without an answer having been given,
and `:takeYowe(i)` takes one for a scripted loss.
## Sound
The yowes own their own noises. Three clips under `/source/flock/audio`,
synthesised rather than recorded: an idle bleat, a frightened one, and the
sound of the fen closing over an animal. They play spatially from the animal
that makes them, so a bleat comes from a particular yowe standing in a
particular place.
# fen.marsh
Yowe Fen itself. Attach it to the `Fen` anchor and the place stands: causeway,
stage-posts, Staithe, Fold, reed beds, hags, drift, water and fog banks, built
as merged runtime meshes — about a hundred and thirteen thousand triangles in
roughly twenty draw calls, generated in about a fifth of a second.
It also owns the fen's LOOK: it tunes the scene's `ProceduralSky` and ambient
from night to dusk, sets the height fog, captures the sky into the environment
so the water has something to reflect, and hides `Fen/Greybox`.
Every frame it lifts the water to `Rules.KEY.TIDE_Y` — whatever the run slice
says the tide has reached — and drifts the fog banks across the fen with it.
| field | meaning |
|---|---|
| `seed` | the fen is generated from this; the same seed is the same fen |
| `tuneLook` | off leaves the scene's own sky, light and fog alone |
`:stats()` reports what it built — triangle counts per part, the water's height,
how many fog banks stand — which is the read that answers "did it build" without
looking at a picture.
# sound.mix
The fen's sound, running. One component, on the `Sound` anchor.
It builds every emitter the game speaks through as children of that anchor,
holds the score and the ambience, answers every signal the other slices raise,
and keeps the whole thing in proportion. Nothing else in the game creates an
`Audio` component for the bed, the voice or the shared one-shots — which is
what makes a *mix* possible instead of eight sources at full volume.
## What it builds
| Child | Holds |
|---|---|
| `BedFen` | the score at rest, looping |
| `BedPress` | the same drone with the tide in it, looping |
| `BedLament` | one reed pipe over the drone — the title and both endings |
| `BedCrest` | the crest cue, played once through |
| `AmbAir` | wind through the reed beds, with the far birds under it |
| `AmbWater` | brackish water against the posts |
| `VoiceHost` | every spoken line |
| `UiHost` | the interface answering |
| `WorldHost` | flat one-shots |
| `Emitter1..4` | spatial one-shots, moved to wherever the sound happens |
## The mix
```
voice 1.00 a spoken line is the loudest thing in the fen, always
sfx 0.52 what the world does — gates, water, a yowe going in
ui 0.50 the interface answering, under everything
music 0.42 the bed. It is a bed. It sits UNDER.
ambient 0.45 wind and water, the ground the rest stands on
master 0.82 headroom for two one-shots landing on the same frame
```
Under a spoken line the bed and the ambience drop to `voiceDuck` (0.45) of
where they were, because a game where the score and the dialogue are the same
size is a game where you can hear neither.
Measured at the bus: the bed and ambience together sit around 0.09 peak, one
one-shot reaches about 0.6, a spoken line lands between 0.6 and 0.8, and the
worst burst the game can produce — a wrong answer, a yowe taken and a tide
step inside a second — peaked at 0.69 and 0.59 over two runs. Nothing clips.
## The score follows the tide
`bed_fen` and `bed_press` are two loops crossfaded by `TIDE_T`, so the music
tightens across the run without anybody cueing it:
| `TIDE_T` | `BedFen` | `BedPress` | `AmbWater` |
|---|---|---|---|
| 0.00 | 1.00 | 0.00 | 0.30 |
| 0.35 | 0.70 | 0.11 | 0.44 |
| 0.70 | 0.00 | 0.68 | 0.72 |
| 1.00 | 0.00 | 0.90 | 0.91 |
## Signals it answers
`HAILED` · `ANSWERED` · `GATE_OPENED` · `YOWE_LOST` · `TIDE_STEP` ·
`UI_CLICK` · `PHASE`
Every subscription is kept and dropped in `onDestroy`, so a hot edit does not
leave a second copy of this component's ears behind.
## Fields and methods
`master`, `musicLevel`, `ambientLevel`, `sfxLevel`, `uiLevel`, `voiceLevel`,
`voiceDuck` — all live, all 0..1, so a settings screen can drive them and be
heard as the slider moves.
- `:playSfx(name, at?)` — a one-shot from the shared library; `at` puts it out
in the world instead of flat across the mix.
- `:speak(lineId)` — a written line, spoken. The text goes on screen either way.
- `:report()` — what the mix is actually doing: every layer's live gain, its
mixer state, whether it is audible, and why it is not when it is not.
# run.director
The run of The Hernsew Lingster: the phase the game is in, the tide coming
into Yowe Fen, and the five hurdles that bar the causeway until their heron
is answered.
Attach one to the scene's `Run` anchor. It builds the hurdles as children of
that anchor and publishes everything else on the shared blackboard in
`game.rules`, so no other slice has to find it.
## The phases
| phase | what it is | what leaves it |
|---|---|---|
| `title` | waiting to be started | `Run.begin()`, or a `UI_CLICK` of "start"; failing that, `autoStartSeconds` |
| `opening` | the staged arrival at the Low Staithe | `Run.openingDone()`, or `openingSoloSeconds` / `openingMaxSeconds` |
| `play` | the walk up the causeway; the tide runs | the deck going under, the Fold, or an empty flock |
| `crest` | the water is over the deck and the Fold is still ahead | the crest, or the Fold |
| `won` | the High Fold, with at least one yowe | `Run.restart()` |
| `lost` | the tide crested, or the last yowe was taken | `Run.restart()` |
## What it publishes
On `Rules.state`, every frame: `PHASE`, `TIDE_Y`, `TIDE_T`, `STATION`.
As signals: `PHASE(phase)`, `TIDE_STEP(step)` at each of the tide's ten
notches, and `GATE_OPENED(stationId)` when a hurdle stands aside.
It listens for `ANSWERED(stationId, correct)` — a wrong answer costs
`Rules.TIDE.PENALTY_SECONDS` of tide, a right one opens that post's gate and
moves the station on — and for `YOWE_LOST` and `UI_CLICK`.
## Fields
- `autoStartSeconds` — how long `title` waits when no screens slice is there
to press the button.
- `openingSoloSeconds` / `openingMaxSeconds` — how long the opening runs with
and without a stage slice driving it.
- `driveGreyboxWater` — move the placeholder water plane from `TIDE_Y` while
the greybox fen is still what is on screen. Stops by itself once the real
fen stands.
- `gateOpenSeconds` — how long a hurdle takes to swing aside.
## Methods
`begin()` · `openingDone()` · `restart()` · `phase()` · `tideT()` ·
`setTideT(t)` (put the tide at a point of the run, for a staged beat or a
test) · `answer(stationId, correct)` · `report()` (the whole run as one
readable table).
Prefer `require("run.state")`, which wraps all of these and answers before the
component has awoken.
# lingster
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this component provides and who
consumes it, then delete both comment lines. -->
TODO: describe this component.
# roost
<!-- zero:scaffolded-readme -->
<!-- Replace the line below with what this component provides and who
consumes it, then delete both comment lines. -->
TODO: describe this component.