Line
The text-bearing beat: who speaks, what they say, and the options the schema allows.
A line beat is text the reader reads. With a speaker it is dialogue, drawn with that cast member's name and color. Without one it is narration. It is the only beat you can type into directly, and the only beat find and replace searches.
Fields
| Field | Type | Required | What it does |
|---|---|---|---|
id | string | yes | Stable beat id, minted by the editor. |
kind | "line" | yes | The discriminator. |
text | string | yes | What the reader sees, before token interpolation. |
speaker | cast id | no | Absent or empty means narration. |
voiceAsset | asset id | no | An audio asset played with the line. |
spans | array | no | Emphasis runs over text. |
text is the single source of truth. {token} interpolation reads text, so
a variable's value or a character's display name can sit inside a sentence: see
Tokens.
Speaker
The picker at the head of the line lists your cast members by display name and
stores the cast member's id. (none) is narration.
If the stored id names a cast member that no longer exists, the picker keeps
showing the raw id rather than quietly clearing it, and the compiler reports
UNKNOWN_CAST on that beat. Rebind it or delete the line.
A bound cast member (one whose face is chosen by a variable) resolves at scene entry, so the name and portrait the reader sees are the resolved member's. See Cast bindings.
Emphasis
spans is a flat list of { text, bold?, italic? } runs. You never write it by
hand: Mod B, Mod I, **bold** and
*italic* produce it. When spans is absent the player renders plain text.
Two rules are enforced at compile time, both reported as INVALID_LINE_SPANS:
- the spans must concatenate to exactly
text - a
{token}may not straddle a span boundary
You can hit the second one by bolding half a token. Bold the whole {gold} or
none of it.
The AI co-writer cannot write emphasis. Its line shape has no spans field on
purpose, so it can never hand back a line whose spans disagree with its text.
Emphasis is yours, applied in the editor.
Voice audio
voiceAsset points at an audio asset in the project library. The picker is
demoted: it fades in when you hover or focus the line, unless a voice is
already set, in which case it stays visible. An asset id that is not in the
library is MISSING_ASSET at compile time.
The picker only appears once the editor knows which project it is in, which is always the case in the studio.
How to write a two-hander
Name the first speaker
On an empty line, type @ and the character's name, then Enter. The
@ text disappears and the speaker picker fills in.
Write the line, then press Enter
The new line inherits the speaker, so keep typing to write a second line for the same character.
Switch speakers with @ again
@ works at the start of any line, so a reply is one keystroke plus a name. To
drop back to narration, set the speaker picker to (none).
What the reader gets
Lines reveal with a typewriter effect. Clicking mid-reveal finishes the current line rather than skipping to the next one, which is the convention readers expect; the next click advances. Auto-advance, when the reader turns it on, only runs on line beats, and only once the line is fully revealed.
A line with a voiceAsset plays it as the line reveals. A line whose speaker
has an avatar on stage is spoken by that avatar, with mouth movement if the
model supports it.
Common mistakes
- Bolding part of a token, which fails the span check. The fix is to select the whole chip.
- Leaving a speaker set on a line meant as narration after a split. Enter inherits the speaker deliberately; clear it on the line where the voice changes.
- Typing a character's name into
textas "Kai: hello". Nothing parses that. Use the speaker picker, or the reader sees the colon.