# flscreens Every screen of *First Light: Vagant*, as a widget tree. Each function is a pure builder: it takes a view model and returns a tree. It registers nothing, shows nothing, and writes no game state — `Screens.component` does all of that. ```luau local S = require("ui.flscreens") ui.registerScreen("fl-menu", S.title(model), 960) ``` ## The builders | Call | What it draws | |---|---| | `S.title(m)` | the title card: the mark, the name, the logline, the menu | | `S.howto(m)` | the how-to-play broadsheet and its control table | | `S.hud(m)` | dawn band, clock, pause pip, the seven standards, oil, wig | | `S.alert(m)` | the hunt vignette and the relight prompt | | `S.say(m)` | the subtitle line | | `S.pause(m)` | the pause card, with the night's figures on it | | `S.endCard(m)` | first light, or the entry in the minute-book | ## The view model ```luau { device = "kbm" | "pad" | "touch", -- which family is holding it focus = "fl:begin", -- the id carrying the focus ring items = { { id, label, hint?, danger? }, ... }, backId = "fl:back", line = { text = "...", speaker = "The Vagant" } | nil, playerPos = { x, y, z } | nil, -- for the relight prompt won = boolean, reason = "caught" | "dawn", where = "Middle Ditch", } ``` Everything else — the clock, the lamps, the oil, the wig, whether you are being hunted — is read live from `fl.state` and `fl.lamps`. ## Why the HUD is three screens `S.hud` carries the gauges and is rebuilt about once a second, whenever a figure on it changes. `S.alert` and `S.say` are separate because they are the parts that carry **looping and entrance motion**, and re-registering a screen restarts every animation on it — so they are rebuilt only when being hunted, standing at a dark lamp, or the spoken line actually changes. ## Portrait first The filmed frame is 3:4 and the portrait arrangement is the default: the dawn band along the very top, the standards down the left, the oil up the right, the words low and centred, nothing spanning the width. `flui.portrait()` picks the wide variant where a wide screen needs one — a narrower menu column, a smaller title mark, and less vertical padding, because a wide screen has to give its vertical room back to the stack.

# fl 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.

# flui The look of *First Light: Vagant*'s screens, in one module. `flscreens` builds the trees; this builds the pieces they are made of. ```luau local flui = require("ui.flui") ``` ## Measure — nothing here is a pixel Every size is a fraction of the **live short screen axis**, so the same tree composes on a phone held upright, on a laptop, and on a television. | Call | What it answers | |---|---| | `flui.size()` | the shape being laid out against | | `flui.u(f)` | `f` of the short axis, in logical points | | `flui.portrait()` | is the screen taller than it is wide | | `flui.cardWidth()` | how wide a reading column should be | | `flui.typeSize(scale)` | a type size, never below its floor | `flui.T` is the type scale as fractions; `flui.TMIN` is the floor in logical points beside it, because a reader's eye does not shrink with the screen — on a 390-point phone the fractions alone would land body text at 9 points. `flui.TAP` (48) is the smallest a thing a finger presses may be. `flui.previewSize` lays a build out against a **stated** shape instead of the live one. Set it, build a tree, read the numbers back, clear it: that is how screens authored in a tall frame are proved to hold in a wide one. ```luau flui.previewSize = { width = 1920, height = 1080 } local tree = require("ui.flscreens").title(model) flui.previewSize = nil ``` ## Colour `flui.C` carries `fl.PAL`'s four UI hexes plus this slice's own, derived from the same palette the fen and the lantern are painted from: `ink` `paper` `brass` `blood`, the panel steps `soot` `slate` `iron` `fog`, the light `flame` `lamp` `dawn`, `jasey` white, `water`, and the parchment set `vellum` / `vellumEdge` / `vellumInk`. ## Pieces - **Type** — `flui.text(str, scale, style)`, `flui.para(str, scale, style)` (a paragraph always ships inside a full-width box of its own; a wrapping label that carries its own width collapses to one glyph per line), and `flui.eyebrow(str, color)` for the letterspaced cap line over a heading. - **Ornament** — `flui.rule(opts)` (a hairline with a diamond set in it), `flui.diamond(size, color)`, `flui.svg(str, w, h, style)`. - **Surfaces** — `flui.plate(children, style)` for a panel on the dark page, `flui.vellum(children, style)` for a printed card, `flui.scrim(children, style)` for the ground a card sits on. - **Controls** — `flui.item(opts)` is the one menu line: a plate at thumb size carrying its own handler, with a brass ring, a lit edge marker and a diamond when `focused`. `flui.cap(str, kind)` draws a keycap, a pad button or a touch target as the thing it is. - **Glyphs** — `flui.lampGlyph(lit, height, onLight)`, `flui.wigGlyph(color, height)`, `flui.pauseGlyph(color, size)`, `flui.sunGlyph(color, size)`.