# art The drawn parts of the screens of *First Light: Nearside* — inline SVG documents the `svg` widget rasterizes at whatever size the layout gives them, so one string serves a phone and a television. ```lua local Art = require("game.screens.art") { type = "svg", props = { svg = Art.hero(), fit = "slice" }, style = { width = "100%", height = 288 } } ``` | | | |---|---| | `hero()` | The title card's key art: Earth over the lunar plain, the dawn line lying across the regolith as a copper band, and CINNAMON on it with the sun's glare at the bottom edge. | | `mark()` | The game's mark — a sun's first sliver over a curved horizon. | | `earth()` | A half-lit Earth on its own. | | `dome()` | Peary Station: the lit greenhouse dome with its beacon, the landmark the route points at. | | `can()` | A xylidine drum. | | `hop()` | A lunar arc off a crater lip with the nozzle lit. | | `bandGlyph()` | The strip of light the cargo lives in, with the line through it. | | `rover()` | The rover in profile, small enough for a row icon. | | `chevron(color, dir)` | A meter's travelling marker. | | `stars()` | A hairline star field. | The palette is the game's: cinnamon sun from the south, indigo earthlight from the north, black between them.

# ns The shared contract of *First Light: Nearside*. Every slice of the game requires this module and nothing else of each other's. ```luau local NS = require("game.ns") ``` ## What it carries - **Constants** — `NS.ROUTE` (the corridor: `startZ`, `finishZ`, `halfWidth`), `NS.DAWN` (the terminator's start, speed and the hot/cold distances), `NS.CARGO`, `NS.FUEL`, `NS.ROVER`, `NS.PALETTE`, `NS.AUDIO`, `NS.NAMES` (the entity names the scene authors) and `NS.COMPONENTS` (the component identities the entrypoint mounts). - **The light** — `NS.lightAt(dz)` and `NS.bandAt(dz)` read the sunlight at a distance from the dawn line, `dz = z - terminatorZ`. The rules and the lighting both read these, so the meter and the picture agree. - **The screen** — `NS.screen()` and `NS.unit(fraction)`: every layout is stated against the live screen size, never in pixels chosen for one frame. - **Events** — `NS.on(name, fn)` / `NS.emit(name, payload)`; the names are in `NS.EVENTS`. - **Phases** — `NS.phase()`, `NS.setPhase(p)`, `NS.resume()`, `NS.tick(dt)`, `NS.runTime()`. Phases: `title → howto → intro → playing ⇄ paused → won | lost`. - **Surfaces** — `NS.provide(name, table)` / `NS.get(name)` / `NS.whenProvided(name, fn)`. The shapes are in `/zero/source/design/spec.md`. - **Maths** — `clamp`, `lerp`, `smooth`, `approach`, `hash`, `rgb`. ## Notes - Module-local state (phase, surfaces, handlers) resets on hot reload of this file; components re-provide their surfaces in `awake`. - The route runs north, +Z. South of the terminator is sunlight.

# style The one place the screens of *First Light: Nearside* agree on colour, type and measure. ```lua local St = require("game.screens.style") local m = St.metrics() { type = "label", props = { text = "XYLIDINE" }, style = St.caption(m) } ``` ## Measure `metrics()` returns every length a screen tree needs, derived from the live screen size — or from a size you hand it, which is how a layout is checked at a shape the engine is not currently running at: ```lua St.metrics({ w = 1920, h = 1080 }) ``` Lengths come from `unit`, the smaller of the screen's short side and three quarters of its height. A card is a column, so what limits it on a wide screen is the height: 1080x1440 and 1920x1080 share a short side and have very different room to stack in. Every size carries a cap, so type stops growing on a large screen, and a floor, so words stay words on a phone held sideways. ## Type Four faces, each with a job: `ArchivoBlack` for the game's name, `Anton` for headings and instrument labels, `Arimo` for prose, `BerkeleyMono` for anything a player reads as a number. `title` / `heading` / `caption` / `text` / `readout` return fresh style tables, so a caller may add to what it gets back. `fit(family, text, track, avail, cap)` answers the largest size at which a line still fits the width it has. It estimates from the face's average advance, so it is there to **shrink** a line that would run past its box, never to choose a size on its own — every call passes the size it wants as the cap. ## Surface `panel(m)` is the raised card and instrument tile: a lit top edge over a step in lightness, then the shadow. `well(m)` is the recess every meter is filled inside. `row(m, focused)` is a card row and the focus ring it wears when a pad walks onto it. `enter(delay, lift)` and `pulse(period, from, to)` are the two animations the screens use — an entrance that staggers across siblings, and a slow breath for a live instrument. Colours are `NS.PALETTE` plus the UI's own mixes of it; `BAND` maps each of the four light bands to the colour every readout paints it in.