# ui.theme — the game's visual language ```luau local T = require("ui.theme") ``` The palette as CSS strings, the type scale, the woodblock ornament, and the composed primitives every screen is assembled from. Colours come from `ST.PALETTE`, so the screens and the world are the same game. ## Colour `T.C` — `sumi` `indigo` `vermillion` `gold` `bone` `magenta` `cyan` `acid` `violet`, plus the working greys (`ink` `panel` `panelHi` `line` `lineSoft` `dim` `dimmer`). `T.LANE[1..4]` is the lane accent; `T.JUDGE[id]` is `{ hex, label, english }` per judgement. `T.pal(name, alpha?, scale?)` mixes one on the fly. ## Type `T.FONT` — `display` (Anton), `heavy` (ArchivoBlack), `grot` (BricolageGrotesque), `body` (PTSerif), `mono` (BerkeleyMono). **Latin only.** No font available to this engine carries CJK glyphs, so a kanji renders as an empty box. The screens are set in the romaji the design already carries and the Japanese reads through the ornament. ## Ornament `T.ART` names the baked marks under `/source/ui/art/`: `torii` `toriiGold` `oni` `mon` `rays` `raysEmber` `waves` `seal` `fan`. Draw one with `T.art(name, w, h, style?)`. They are authored as `.svg` **files**, which the importer bakes into `.texture` assets. Colour is baked in, so a mark needed in two colours is two files, and a changed mark goes to a **new filename** — a re-import over an existing `.texture` keeps the old image. ## Primitives `T.kicker` `T.rule` `T.gap` `T.panel` `T.heading` `T.button` `T.keycap` `T.meter` `T.dataRow` `T.body` `T.backdrop` `T.enter`. `T.body(text, opts)` is the one to reach for for paragraph text: it breaks the line in Luau and emits one label per line. Do not set `props.wrap = true` on a label — a wrapping label stops every widget after it in the screen from painting. `T.setAnimated(bool)` gates the entrance animations. They advance in play and freeze in edit, and because an entrance holds its first keyframe a screen authored with motion is invisible in the mode an author captures in — so the HUD slice turns them on only when the engine is actually running them.

# game.core — the shared contract of SENGOKU TRANCE Everything every slice of the game agrees on. The screen shape, the rules, the three duels, the **beat clock**, the event bus, the shared state, and the scene anchors. ```luau local ST = require("game.core") ``` A bare dotted identity in the world root. `@world::game.core` does not resolve. ## Exports - `ST.VIEW` — the screen is **1080 x 1440, 3:4 portrait**, and `VIEW.band` divides it into stage / highway / hud strips. Lay out inside your band. - `ST.WORLD` — the metres: lane positions, the receptor plane, where the stage is, where each duellist stands, and the fixed gameplay camera. - `ST.RULES` — judgement windows, damage, scoring, keys, and the measured latency constants. - `ST.PALETTE` / `ST.LANE_COLOR` — the blacklight-ukiyo-e colours. Draw from these so the three duels read as one game. - `ST.STAGES` / `ST.stage(id)` — the three duels, each with a **fixed BPM** and a psytrance section map. - `ST.clock` — the beat clock. `songTime()`, `beat()`, `beatPhase()`, `beatToTime(beat)`. - `ST.bus` — `on(topic, fn) -> off`, `emit(topic, payload)`, `clear()`. `ST.TOPICS` lists the contract topics. - `ST.state` — the live duel numbers. The conductor writes; everyone reads. - `ST.anchor(name)` / `ST.clearAnchor(name)` — where a slice hangs its entities. **No slice edits the scene file.** - `ST.provide(id, api)` / `ST.need(id)` — the slice registry. - `ST.lerp`, `ST.clamp`, `ST.color`, `ST.accuracy`, `ST.meanOffset`, `ST.phaseAt`, `ST.resetDuel`. ## The beat clock — measured, not assumed The engine **does** report playback position: `audio.voice(id).positionSeconds`. Measured on this build, over 90 consecutive frames: | quantity | measured | |---|---| | distinct positions in 90 frames | 90 — it advances every frame | | quantum | **11.6 ms** (steps are exact multiples of 11604 us) | | frame time | **21.7 ms** — the audio clock is finer than the frame | | lag behind a wall clock started at `:play()` | **20-23 ms**, steady | | drift over the window | none measurable | So the clock is **driven by the engine**, not free-running. But an 11.6 ms quantum read on a 21.7 ms frame makes notes judder, so `ST.clock` runs a hybrid: it free-runs on the wall clock between raw samples and re-locks to every fresh one (nudging 18% a frame, snapping past 80 ms of error). Read `songTime()` and never `audio.voice()` directly. `ST.clock.tick(now)` is called once a frame by the scene entrypoint. **A slice never calls it.** ## Latency, and what we do about it Input is sampled once a frame, so timing resolution can never beat ±11 ms. The windows are sized for that: KIWAMI ±45 ms, SHIN ±90 ms, KA ±140 ms. The residual output latency is measured **from the player** by the calibration step, which writes `ST.RULES.calibrationSeconds`; the conductor keeps a running mean offset (`ST.meanOffset()`) so a systematic bias is visible in data rather than guessed at. ## Notes - The three tracks are generated **to** the BPM in `ST.STAGES`, never the other way round. A chart is authored in **beats**; `ST.clock.beatToTime` resolves it. That is why a chart can never disagree with its track. - `ST.need(id)` returns nil for a slice that is not built yet. **Always handle nil** — that is what lets the slices build in parallel.