Appending text
Lives in: story moment fields and the panel command (text_mode)
By default each new moment replaces what was in the panel. Append keeps earlier text and adds this moment’s text — useful for a running log, a chat-style beat, or a sticky side panel that accumulates notes.
A moment is one click-through step of the story (also called a node in tools and data) — Words used in these docs.
Replace vs append vs plates
text_mode | Effect |
|---|---|
replace (default) | This moment’s text becomes the whole panel contents |
append | This moment’s text is added to what is already there (one label) |
plates | Each beat is a separate plate from the preset’s plates map — Theme: panel → Plates |
Per-plate transition_in / transition_duration animate the live plate chrome inside the body scroll on each new beat (see Theme: panel → Plates).
plates uses the same append_direction, append_gap_px, append_push_duration, and clear_append keys as append.
Not mid-line typing: while one moment’s text is revealing, that is still one block. Append decides what happens when the next moment writes to the same panel.
{
"id": "log_1",
"panel_id": "side",
"text_mode": "append",
"talking": ["system"],
"text": "Door unlocked."
}
For a lasting chat, prefer a sticky command so later moments keep appending:
{ "type": "panel", "panel_id": "side", "text_mode": "append", "max_height": "full" }
[panel panel_id side text_mode append]
[panel clear_append]
Direction and gaps
| Field | Values | Default | Effect |
|---|---|---|---|
append_direction | down, up | down | New text below or above the existing block |
append_gap_lines | number ≥ 0 | 0 | Blank lines between old and new |
append_gap_px | number ≥ 0 | 0 | Extra pixel gap |
When append fills past the panel height ceiling, the body scrolls and keeps the newest edge in view (down → bottom, up → top). Set the ceiling with theme max_height or a sticky panel max_height — How a panel looks.
Changing append_direction on a panel that already has a thread keeps that history and re-pins it for the new direction (newest at the bottom for down, at the top for up). It does not start a fresh log — use clear_append when you want a wipe.
Editing the script in author mode while you are mid-thread re-reads sticky panel keys (append_direction, text_mode, gaps) along the moments you already played — including the moment that opened the thread — then reorients the live thread. You do not need to be on the same moment as the sticky command. Going back after that keeps the rehydrated direction (it does not restore the pre-edit value).
Sticky vs one moment
| Surface | Effect |
|---|---|
Moment fields text_mode / append_* | This moment only |
{ "type": "panel", "text_mode": "append", … } | Stays for later moments on that panel until you change it |
A moment’s text_mode overrides a sticky panel setting for that moment only.
| Situation | What happens |
|---|---|
| That panel was replace, then this moment is append | Starts a new append log from this moment |
| That panel was sticky append, even while another panel was talking | Keeps collecting when you write to it again |
Sticky text_mode: replace, clear_append, or panel reset | Clears the log on that panel |
| One moment uses replace while sticky is still append | Shows that line alone; the log stays for later append moments |
| Only a moment field sets append (no sticky command) | That one moment appends; lasting chat needs the sticky command |
Clear the thread, keep the mode
clear_append wipes history on that panel but keeps sticky append mode, direction, preset, and policy. Use it for a fresh chat on the same box without a full reset.
[panel panel_id side clear_append]
Same-moment clear_append applies before that moment’s first paint.
Script sugar for everyday append is limited — use the direction file / moment data, or a panel command before the stretch of moments ([panel … text_mode append] / [panel clear_append] exist).
With several panels
Append is per panel id. main can stay on replace while side or a phone panel appends. A quiet append panel keeps its history until you write to it again. Presence / readonly on quiet panels is separate — Presence and quiet panels. Tall log recipe: Several panels.
Usually you need
| Want | Do |
|---|---|
| Normal dialogue | Leave text_mode off (replace) |
| One log panel | Sticky panel with "text_mode": "append" (+ max_height if it should fill the side) |
| Chat-style thread | Sticky panel with "text_mode": "plates" + preset plates / character ui.default_plate |
| Fresh thread, same mode | clear_append |
| Single appended beat | "text_mode": "append" only on that moment |