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.

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:

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.