caption

The band a staged beat speaks over.

A beat holds the camera and takes the HUD out of the frame, so the caption band the HUD carries goes with it. This is the band the beats carry themselves: the speaker, the line, and the prompt that says the beat can be left.

local Caption = require("game.staging.caption")
Caption.setPrompt("SKIP  ·  SPACE")
Caption.show("The Old Henter", "Lantern up, henter.", 5)
Caption.tick(dt, 0.10)   -- the letterbox fraction the beat is running at
Caption.hide()

• show(speaker, text, seconds?) — put a line up. Without seconds it stays for readingTime(text), long enough to read aloud and floored so a short line does not flash.
• tick(dt, letterbox) — run the line's clock down and refresh the band.
• setPrompt(text?) / hide() / clear() / isShowing().

Two things it will not do

It is not laid out in pixels. The card's measure, its type sizes and its distance from the bottom edge are fractions of the live ui.screenSize(), so it reads the same on a 3:4 phone and on a 16:9 monitor.

It never lands under a letterbox band. The bands and the fade are a post-process drawn over the UI, so a caption inside one is invisible while looking perfectly correct in the widget tree. The band's bottom inset is derived from the letterbox fraction the caller passes.

Its own render layer

The screen draws on StagingCaption (M.LAYER) rather than on ui, which is what lets a beat's camera leave the whole HUD out of the frame and still carry these words. Shots.BEAT_LAYERS is the matching spec on the cutscene camera.