Speech Bubbles

Speech bubbles carry dialogue, thoughts, and narration inside a panel. Each bubble is a SpeechBubble object in a panel's speechBubbles array. Bubbles are positioned with normalized coordinates, hold localized text, and are styled through a four-level balloon configuration cascade rendered by the player's ComicBalloon SVG engine (see Balloon Renderer).

SpeechBubble

Defined as $defs/SpeechBubble. Lives in chapters[].panels.<panelId>.speechBubbles[] (and in variant overrides).

BoundingBox

Axis-aligned bounding box using normalized coordinates (0–1), relative to the panel.

The implicit speech toggle

Since schema 1.3, every speech bubble is inherently subject to the reader's global speech toggle. The toggle's initial state comes from settings.ui.speechDefault (default: on), and the player ANDs it on top of any visibleIf — a bubble renders only when both the toggle is on and its visibleIf (if any) is truthy.

The styling cascade

Balloon styling merges four levels, most specific wins:

1. Work defaults — a complete BalloonConfig at settings.typography.balloon_config (see Settings). Anything unset falls back to the schema defaults below.
2. Character override — a partial BalloonConfigOverride on the character (meta.characters[].balloonConfig), merged onto the work defaults for every bubble spoken by that character.
3. Named preset (schema 1.3+) — the BalloonConfigOverride from settings.typography.balloonPresets that the bubble references via styleRef. Lets many bubbles share one editable definition instead of repeating identical overrides.
4. Per-bubble override — a partial BalloonConfigOverride on the bubble itself, merged last. With a preset in play this is only needed for true one-offs (e.g. a single whisper on top of a shared tail preset).

The merge is field-by-field, and the nested tail and hideBorder objects merge field-by-field too (a character can set tail.curve without losing the work-level tail.length). The player implements this in mergeBalloonConfig.

BalloonConfig

Complete balloon styling configuration, used at the work level as defaults ($defs/BalloonConfig).

The 10 balloon types

balloonType accepts exactly these enum values:

BalloonConfigOverride

Partial styling for character-level or bubble-level overrides ($defs/BalloonConfigOverride). It has the same fields as BalloonConfig, all optional and without defaults — only fields you specify override the parent level. Its nested tail and hideBorder objects are likewise partial:

• tail override fields: enabled, position, length, curve, curveAmount
• hideBorder override fields: enabled, angle, arc

TailConfig

The balloon tail — the pointer from the balloon toward the speaker ($defs/TailConfig).

HideBorderConfig

Hides a segment of the balloon border, useful when stacking balloons so they appear joined ($defs/HideBorderConfig).

Example

A work-level default, a named preset, a character override, and a bubble combining all of them:

{
  "settings": {
    "typography": {
      "balloon_config": {
        "balloonType": "normal",
        "cornerRadius": 0.5,
        "fontFamily": "'Ames Italic', sans-serif",
        "fontSize": 12,
        "strokeWidth": 2,
        "strokeColor": "#000000",
        "fillColor": "#ffffff",
        "tail": { "enabled": true, "position": 180, "length": 45 }
      },
      "balloonPresets": {
        "speech-down-right": { "tail": { "position": 150, "length": 50 } }
      }
    }
  },
  "meta": {
    "id": "work-demo",
    "title": { "en-US": "Demo" },
    "locales": ["en-US", "de-DE"],
    "default_locale": "en-US",
    "characters": [
      {
        "id": "char-villain",
        "name": { "en-US": "The Villain" },
        "balloonConfig": {
          "balloonType": "shout",
          "fillColor": "#ffe0e0",
          "tail": { "curve": "right", "curveAmount": 0.6 }
        }
      }
    ]
  },
  "chapters": [
    {
      "id": "ch-1",
      "panels": {
        "p1": {
          "speechBubbles": [
            {
              "id": "sb-1",
              "characterId": "char-villain",
              "text": {
                "en-US": "You will never escape!",
                "de-DE": "Du wirst niemals entkommen!"
              },
              "shape": { "x": 0.55, "y": 0.1, "w": 0.35, "h": 0.2 },
              "styleRef": "speech-down-right",
              "balloonConfig": { "fontSize": 16 }
            }
          ]
        }
      },
      "graph": { "entry": "p1", "edges": [{ "from": "p1", "to": "p1" }] }
    }
  ],
  "panelwave": {
    "version": "1.3.0",
    "schema": "https://panelwave.org/schema/1.0/panelwave.schema.json"
  }
}

The bubble renders as a shout balloon (character), light red (character), 16 px text (bubble), with the preset's tail direction/length on top of the character's right curve — and it disappears automatically whenever the reader turns speech off. No visibleIf needed for that.

Related pages

• Panels — where speechBubbles lives
• Settings — settings.typography.balloon_config
• Meta — characters and their balloonConfig
• Player balloon renderer — how the SVG engine draws each type