Chat Bubbles

Chat Bubbles

Chat bubbles turn dialogue into a messaging-style exchange inside chapter prose. Use the left and right sides to make a conversation easy to follow without creating a separate image or another chapter.

Preview

Alice's question appears on the left and Bob's reply appears on the right:

The first message appears on the left with Alice as its speaker. The reply appears on the right with Bob as its speaker.

Copy the syntax

Put the opening tag, message, and closing tag on separate lines:

{chat Alice}
Did you find the key?
{endchat}

{chat:right Bob}
Yes. Meet me at the gate.
{endchat}

{chat Alice} creates a left-side bubble. Use {chat:left Alice} when you want to state the left side explicitly, or {chat:right Bob} for a right-side bubble. The colon in :left or :right is required.

Choose the speaker and side

The speaker name is optional:

{chat}
Unknown sender: Do not trust the lights.
{endchat}

{chat:right}
Who is this?
{endchat}

Without :right, a bubble appears on the left. Speaker names are authored display text. Keep them short and do not put chapter tags, braces, or angle brackets in the opening tag.

Alternating left and right usually makes a two-person exchange easiest to scan. For a group conversation, keep each character on a consistent side when possible and include the speaker name whenever the side alone would be ambiguous.

Add color for a group conversation

An optional named color can help readers distinguish characters who share the same side. In this working three-person exchange, Alice and Cara both speak from the left but keep different bubble colors:

To create it, write:

{chat:blue Alice}
The north entrance is clear.
{endchat}

{chat:right:purple Bob}
I will watch the courtyard.
{endchat}

{chat:green Cara}
Then I will take the archive stairs.
{endchat}

Put the color directly after chat for a left-side bubble, as in {chat:blue Alice}. For a right-side bubble, put it after :right, as in {chat:right:purple Bob}.

The available colors are red, orange, yellow, green, teal, blue, purple, pink, and gray. These names select theme-aware color treatments rather than exact fixed shades. The bubble and its text adapt to the story's Element Theme and the reader's White, Black, or Sepia appearance. White and Sepia use dark text on lighter colored bubbles, while Black uses light text on deeper colors. Omit the color to use the coordinated default pair: a neutral left-side bubble and a blue right-side bubble, both adapted by the active Element Theme.

Keep the visible speaker name even when every character has a different color. Color should reinforce the speaker name, not replace it, because readers may not perceive every color in the same way.

Format the message

Ordinary Markdown works inside a bubble. For example:

{chat Mara}
I found **two** clues. Read the [archive note](https://example.com/archive) first.
{endchat}

The reader sees the emphasis and link inside Mara's bubble. A message may contain more than one paragraph, but short messages usually preserve the feeling of a conversation better than a large wall of text.

Chat bubbles do not send messages, notify another user, or create a CHYOA conversation.

Show a conversation one message at a time

A chat stream plays two or more complete bubbles one message at a time. The working example below begins when it reaches the visible part of the page:

To create the same effect, put {stream} and {endstream} on their own lines around two or more complete chat bubbles:

{stream}
{chat Mara}
The east gate is open.
{endchat}

{chat:right Ivo}
I am on my way.
{endchat}
{endstream}

The bubbles appear in the order they are written. A typing placeholder shows the pending bubble's side and optional speaker name before the message appears. The conversation continues automatically, with a longer delay for longer messages. During a pause, the reader can select the placeholder to reveal only that pending bubble; automatic pacing then continues.

During playback, Show all messages at the top right reveals every remaining bubble. When the sequence finishes or the reader shows everything early, that control becomes Replay messages. A stream does not loop or restart when the reader scrolls away and returns. Its timing is automatic and cannot be set by the author. With this bare form, readers who request reduced motion see the complete conversation when it reaches the page and can still choose to replay it without motion.

Add a start button to a chat stream

Add one non-empty quoted label after stream when the conversation should wait for the reader. This working example does not start when it enters or passes through the visible part of the page. Select Open messages to begin it:

To create that start control, write:

{stream "Open messages"}
{chat Mara}
I saved the last transmission.
{endchat}

{chat:right Ivo}
Play it from the beginning.
{endchat}
{endstream}

The reader first sees Open messages inside the empty conversation area. Selecting it hides that start control, begins the same paced sequence, and shows Show all messages at the top right above the transcript. When every bubble has appeared, that top-right control becomes Replay messages. Scrolling to, away from, or past a labeled stream never starts it; only the reader's start selection does.

The authored start button is used only for the first playback. Replay uses the standard Replay messages button, and reloading the chapter makes the authored start button available again.

The label is plain authored display text. Keep it short, put visible text between matching straight quotation marks, and do not place chapter tags in it. The label chooses how the first playback starts; it does not change the message timing.

For readers who request reduced motion, a bare stream shows the complete conversation when it reaches the page. A labeled stream still waits for its start control. Starting or replaying it keeps the messages in order without animated typing dots, movement, or fades.

A chat stream is only for chat bubbles. Keep it as a top-level chapter block and place at least two complete {chat ...} blocks inside it. Use bare {stream} for automatic viewport playback or {stream "Label"} for a reader-started stream. Between the stream tags, use only those chat blocks and blank lines—no standalone prose or other chapter blocks. Inside each streamed bubble, use only ordinary Markdown and supported reader or Game State values. Place other chapter tags and elements before or after the stream.

Named bubble colors work inside a chat stream too. A pending typing placeholder follows that bubble's side, speaker, and chosen color before the complete message appears.

Chat streams play complete bubbles one at a time. When {stream} fills a fictional terminal, it reveals individual output lines instead.

Game State

A chat bubble is a visual block. Opening the chapter does not make the bubble change Game State or add a saved game step.

Use ordinary supported chapter values in the message when the dialogue needs to reflect the reader or current game. Keep the speaker name itself as plain authored text rather than placing variable syntax in the opening tag.

Limits and combinations

• Put {chat ...} and {endchat} on their own lines.
• Close every bubble with {endchat} before starting the next one.
• Chat bubbles cannot be nested inside other chat bubbles.
• Chat bubbles and email cards cannot contain each other.
• Chat bubbles and fictional terminals cannot contain each other.
• Random Draw blocks cannot cross or contain chat blocks, and chat blocks cannot contain a Random Draw.
• Ordering puzzles cannot be placed inside chat bubbles.
• Chat streams must contain only two or more complete chat bubbles and must remain top-level. Their opening tag may have one non-empty quoted start label and no other options. A terminal output stream follows the separate Fictional Terminals rules.

Place incompatible elements before or after the chat exchange instead. Adjacent blocks can still read as one scene.

To show chat or stream tags as literal text in a chapter, put them in backticks or a fenced block.

Before publishing

Save a draft and check that:

1. every opening tag and {endchat} is on its own line;
2. each speaker's side and optional color remain consistent throughout the exchange;
3. every speaker name is short, clear, and plain text, including when color also identifies the speaker;
4. Markdown emphasis and links render inside the intended bubble;
5. long messages wrap cleanly without obscuring who is speaking;
6. adjacent prose still reads naturally before and after the exchange;
7. a bare stream begins when it reaches the visible page, plays its bubbles in order, keeps its controls at the top right, and does not restart after scrolling away;
8. a labeled stream waits with its start control inside the empty conversation area even when scrolled into or past view, then hides that start control and uses the top-right control for Show all messages and finally Replay messages;
9. the bubbles and stream controls remain readable in White, Black, and Sepia appearance and on a narrow screen.