Dialogue Box

branching NPC dialogue with selectable choices.

▶ Run in browser

Tags: ui dialogue branching game-ui

A bottom-anchored dialogue panel driven by a small dialogue graph. Each passage names a speaker and a line of text; a passage either flows on linearly through the familiar Continue button, or offers 2-3 choices rendered as selectable options. Choices are picked with the keyboard (Up/Down or W/S to highlight, Enter or Space to confirm) or by clicking; hovering a choice moves the highlight with it. One branch loops back to the question, others end the conversation. A choice can set a conversation variable (here, how the guide addresses you) that later passages substitute into their text.

What it demonstrates

• A dialogue graph as plain data: passage id -> speaker, text, and either a next id (linear, Continue button) or a list of (label, next_id, sets) choices.

• Choice buttons driven by one shared row pool, highlighted via Button.set_visual_state_override, activated by keyboard or click.

• Input actions on the root’s input_actions class attribute polled with Input.is_action_just_pressed in on_update.

• Conversation variables: a choice stores {"title": ...} and later text references {title} via str.format.

Controls: Up/Down or W/S - Move the choice highlight Enter / Space - Confirm the highlighted choice, or advance linear text Mouse - Hover to highlight, click to choose / continue

Run: uv run python examples/features/ui/dialog.py Headless self-check: uv run python examples/features/ui/dialog.py –test

Source

"""Dialogue Box: branching NPC dialogue with selectable choices.

A bottom-anchored dialogue panel driven by a small dialogue graph. Each passage
names a speaker and a line of text; a passage either flows on linearly through
the familiar Continue button, or offers 2-3 choices rendered as selectable
options. Choices are picked with the keyboard (Up/Down or W/S to highlight,
Enter or Space to confirm) or by clicking; hovering a choice moves the
highlight with it. One branch loops back to the question, others end the
conversation. A choice can set a conversation variable (here, how the guide
addresses you) that later passages substitute into their text.

# /// simvx
# tags = ["ui", "dialogue", "branching", "game-ui"]
# web = { root = "DialogueDemo", width = 800, height = 600, responsive = true }
# ///

## What it demonstrates

- A dialogue graph as plain data: passage id -> speaker, text, and either a
  `next` id (linear, Continue button) or a list of `(label, next_id, sets)`
  choices.
- Choice buttons driven by one shared row pool, highlighted via
  `Button.set_visual_state_override`, activated by keyboard or click.
- Input actions on the root's `input_actions` class attribute polled with
  `Input.is_action_just_pressed` in `on_update`.
- Conversation variables: a choice stores `{"title": ...}` and later text
  references `{title}` via `str.format`.

Controls:
  Up/Down or W/S - Move the choice highlight
  Enter / Space  - Confirm the highlighted choice, or advance linear text
  Mouse          - Hover to highlight, click to choose / continue

Run: uv run python examples/features/ui/dialog.py
Headless self-check: uv run python examples/features/ui/dialog.py --test
"""

from simvx.core import AnchorPreset, Button, Colour, Input, Key, Label, Node, Panel
from simvx.graphics import App

# The conversation as a graph. Each passage has a speaker and text; text may
# reference conversation variables with {name} placeholders. A passage then
# carries either "next" (linear: the Continue button advances) or "choices"
# (a list of (label, next_id, sets) where sets is an optional dict of
# variables the choice stores). A passage with neither is an ending: the
# button reads Close and dismisses the panel.
GRAPH = {
    "greet": {
        "speaker": "Guide",
        "text": "Welcome to the village, traveller. Who do I have the honour of addressing?",
        "choices": [
            ("A knight errant", "brief", {"title": "sir knight"}),
            ("A travelling scholar", "brief", {"title": "learned one"}),
        ],
    },
    "brief": {
        "speaker": "Guide",
        "text": "Well met, {title}. The old mine to the north has been overrun.",
        "next": "ask",
    },
    "ask": {
        "speaker": "Guide",
        "text": "Will you take up the task and clear it out?",
        "choices": [
            ("What happened down there?", "rumour", None),
            ("I will go at once.", "accept", None),
            ("Not today.", "decline", None),
        ],
    },
    # Loops back to the question, so the player can ask and then still decide.
    "rumour": {
        "speaker": "Guide",
        "text": "The miners heard scratching behind the walls. Nobody has gone back down.",
        "next": "ask",
    },
    "accept": {
        "speaker": "Guide",
        "text": "Take this lantern, {title}. You will need its light.",
        "next": "farewell",
    },
    "farewell": {
        "speaker": "Guide",
        "text": "Good luck out there. Come back safe.",
    },
    "decline": {
        "speaker": "Guide",
        "text": "A pity, {title}. The offer stands should you change your mind.",
    },
}

START = "greet"
MAX_CHOICES = 3
ROW_HEIGHT = 32
ROW_GAP = 6


class DialogueDemo(Node):
    """Root node: a bottom-anchored branching dialogue box."""

    input_actions = {
        "choice_up": [Key.UP, Key.W],
        "choice_down": [Key.DOWN, Key.S],
        "choice_accept": [Key.ENTER, Key.SPACE],
    }

    def on_ready(self):
        self._id = START
        self._vars: dict[str, str] = {}
        self._selected = 0

        # Bottom-anchored dialogue panel: full width, fixed height at the
        # bottom edge. Two margin conventions meet here. On a stretching axis
        # (left anchor 0, right anchor 1) the right/bottom margins are positive
        # insets from that edge. On a collapsed axis (both anchors at 1, as the
        # vertical axis is here) the margin pair encodes offset and size, so
        # -240 / -20 means "220px tall, 20px up from the bottom".
        panel = Panel(name="DialoguePanel")
        panel.set_anchor_preset(AnchorPreset.BOTTOM_WIDE)
        panel.margin_left = 20
        panel.margin_right = 20
        panel.margin_top = -240
        panel.margin_bottom = -20
        panel.bg_colour = Colour.hex("#15171F")
        self.add_child(panel)

        # Speaker name, top-left inside the panel.
        self._speaker = Label(name="Speaker")
        self._speaker.font_size = 18.0
        self._speaker.text_colour = Colour.hex("#FFCC66")
        # TOP_WIDE collapses the vertical axis, so the top/bottom margin pair
        # (not size_y) sets the band: 14..38 is a 24px-tall line of text.
        self._speaker.set_anchor_preset(AnchorPreset.TOP_WIDE)
        self._speaker.margin_left = 20
        self._speaker.margin_right = 20
        self._speaker.margin_top = 14
        self._speaker.margin_bottom = 38
        panel.add_child(self._speaker)

        # Body text: the band between the speaker line and the choice rows.
        self._body = Label(name="Body")
        self._body.font_size = 15.0
        self._body.text_colour = Colour.LIGHT_GRAY
        self._body.set_anchor_preset(AnchorPreset.FULL_RECT)
        self._body.margin_left = 20
        self._body.margin_right = 20
        self._body.margin_top = 48
        self._body.margin_bottom = 132
        panel.add_child(self._body)

        # Continue button, bottom-right of the panel, shown on linear passages.
        # BOTTOM_RIGHT collapses both axes, so the margin pairs alone give a
        # 140x32 box inset 20px from the right edge and 12px from the bottom.
        self._continue = Button("Continue", name="ContinueButton", on_press=self._advance)
        self._continue.set_anchor_preset(AnchorPreset.BOTTOM_RIGHT)
        self._continue.margin_left = -160
        self._continue.margin_top = -44
        self._continue.margin_right = -20
        self._continue.margin_bottom = -12
        panel.add_child(self._continue)

        # One shared pool of choice rows, re-labelled and re-stacked per
        # passage; unused rows are hidden. Hovering a row moves the keyboard
        # highlight onto it so the two input routes never fight.
        self._choice_buttons: list[Button] = []
        for i in range(MAX_CHOICES):
            btn = Button("", name=f"Choice{i}", on_press=lambda i=i: self._choose(i))
            btn.set_anchor_preset(AnchorPreset.BOTTOM_WIDE)
            btn.mouse_entered.connect(lambda i=i: self._set_selected(i))
            btn.visible = False
            panel.add_child(btn)
            self._choice_buttons.append(btn)

        self._panel = panel
        self._show_current()

    # ------------------------------------------------------------------ state

    @property
    def _passage(self) -> dict:
        return GRAPH[self._id]

    def _choices(self) -> list:
        return self._passage.get("choices", [])

    def _show_current(self):
        """Render the current passage: text, and either choices or Continue."""
        passage = self._passage
        self._speaker.text = passage["speaker"]
        self._body.text = passage["text"].format(**self._vars)

        choices = self._choices()
        self._continue.visible = not choices
        terminal = not choices and "next" not in passage
        self._continue.text = "Close" if terminal else "Continue"

        # Stack the visible rows upward from the bottom of the panel: row j
        # (counted from the bottom) sits ROW_HEIGHT tall, j full pitches up
        # from a 12px inset. BOTTOM_WIDE stretches each row across the panel.
        for i, btn in enumerate(self._choice_buttons):
            btn.visible = i < len(choices)
            # A row keeps focus after a click; drop it so a later Enter fires
            # the highlighted choice through the action, never a stale focus.
            btn.release_focus()
            if i < len(choices):
                btn.text = choices[i][0]
                j = len(choices) - 1 - i
                bottom = 12 + j * (ROW_HEIGHT + ROW_GAP)
                btn.margin_left = 20
                btn.margin_right = 20
                btn.margin_top = -(bottom + ROW_HEIGHT)
                btn.margin_bottom = -bottom
        self._set_selected(self._row_under_cursor(len(choices)))

    def _row_under_cursor(self, count: int) -> int:
        """The freshly laid-out row the mouse already rests on, else row 0.

        `mouse_entered` fires on motion, so when a choice swaps the layout
        under a stationary cursor no enter event arrives for the new row; the
        highlight would stay wherever it was while the cursor visibly sits on
        another row. One hit-test after each relayout keeps the two honest.
        """
        pos = Input.mouse_position
        for i, btn in enumerate(self._choice_buttons[:count]):
            rect = btn.get_global_rect()
            if rect[0] <= pos.x <= rect[0] + rect[2] and rect[1] <= pos.y <= rect[1] + rect[3]:
                return i
        return 0

    def _set_selected(self, index: int):
        """Move the keyboard highlight, shown via the hover visual state."""
        choices = self._choices()
        if not choices:
            return
        self._selected = index % len(choices)
        for i, btn in enumerate(self._choice_buttons[: len(choices)]):
            btn.set_visual_state_override("hover" if i == self._selected else None)

    # ------------------------------------------------------------ progression

    def _choose(self, index: int):
        """Take choice *index*: store its variables, jump to its passage."""
        label, next_id, sets = self._choices()[index]
        if sets:
            self._vars.update(sets)
        self._id = next_id
        self._show_current()

    def _advance(self):
        """Linear step: follow "next", or close the box on an ending."""
        next_id = self._passage.get("next")
        if next_id is None:
            self._panel.visible = False
            return
        self._id = next_id
        self._show_current()

    def on_update(self, dt: float):
        if not self._panel.visible:
            return
        if self._choices():
            if Input.is_action_just_pressed("choice_up"):
                self._set_selected(self._selected - 1)
            if Input.is_action_just_pressed("choice_down"):
                self._set_selected(self._selected + 1)
            if Input.is_action_just_pressed("choice_accept"):
                self._choose(self._selected)
        elif Input.is_action_just_pressed("choice_accept"):
            self._advance()


def _selftest() -> bool:
    """Headless: play the conversation by the routes a player uses.

    Every step lands as a click on a button's own rectangle or as a key
    through the action map, so the anchors, the row stacking, the highlight,
    the loop-back branch and the variable substitution are all exercised the
    way the screen exercises them.
    """
    from simvx.core.testing import InputSimulator
    from simvx.core.ui.testing import UITestHarness

    harness = UITestHarness(DialogueDemo(name="DialogueDemo"), screen_size=(800, 600))
    scene = harness.tree.root
    sim = InputSimulator(tree=harness.tree)
    ok = True

    def check(label: str, passed: bool, detail: str) -> None:
        nonlocal ok
        ok = ok and passed
        print(f"{'ok  ' if passed else 'FAIL'} {label}: {detail}")

    def tap(key: Key) -> None:
        sim.press_key(key)
        harness.tick()
        sim.release_key(key)
        harness.tick()

    harness.tick()

    # BOTTOM_WIDE with a collapsed vertical axis: the panel should be 220px
    # tall, 20px up from the bottom of an 800x600 screen, full width less its
    # insets.
    box = scene._panel
    px, py, pw, ph = (round(v) for v in box.get_global_rect())
    check(
        "the panel sits across the bottom of the screen",
        (pw, ph) == (760, 220) and (px, py) == (20, 600 - 240),
        f"{pw}x{ph} at ({px}, {py}) on an 800x600 screen",
    )

    rows = scene._choice_buttons
    check(
        "the opening passage offers two choices and no Continue",
        [b.visible for b in rows] == [True, True, False] and not scene._continue.visible,
        f"visible rows = {[b.text for b in rows if b.visible]}",
    )

    # Click the second choice: it stores the title variable, and the next
    # passage's text substitutes it.
    harness.click(rows[1])
    harness.tick()
    check(
        "a clicked choice sets a variable the next line references",
        scene._vars.get("title") == "learned one" and "learned one" in scene._body.text,
        f"vars = {scene._vars}, body = {scene._body.text!r}",
    )
    check(
        "a linear passage keeps the Continue flow",
        scene._continue.visible and scene._continue.text == "Continue",
        f"button = {scene._continue.text!r}",
    )

    harness.click(scene._continue)
    harness.tick()
    check(
        "Continue reaches the question with three stacked choices",
        scene._id == "ask" and [b.visible for b in rows] == [True, True, True],
        f"at {scene._id!r}, rows = {[b.text for b in rows]}",
    )
    r0 = rows[0].get_global_rect()
    r1 = rows[1].get_global_rect()
    check(
        "choice rows stack downward inside the panel",
        round(r1[1] - r0[1]) == 38 and round(r0[2]) == 720,
        f"row pitch = {r1[1] - r0[1]:.0f}px, row width = {r0[2]:.0f}px",
    )

    # The cursor still rests where the Continue click left it, which overlaps
    # the bottom row, and a relayout hands the highlight to the row under the
    # cursor (the hover/keyboard handoff a stationary mouse would otherwise
    # break).
    check(
        "a relayout hands the highlight to the row under the cursor",
        scene._selected == 2,
        f"selected = {scene._selected} with the cursor parked on the bottom row",
    )

    # Keyboard: Down twice then Up leaves the highlight on the middle row. The
    # cursor is parked off the panel first so no row re-claims the highlight.
    harness.mouse_move((5.0, 5.0))
    harness.tick()
    scene._set_selected(0)
    tap(Key.DOWN)
    tap(Key.DOWN)
    tap(Key.UP)
    check(
        "Up/Down move the highlight through the rows",
        scene._selected == 1 and rows[1].visual_state_override == Button.VisualState.HOVER,
        f"selected = {scene._selected}",
    )

    # Highlight the first choice and confirm with Enter: that branch loops
    # back to the same question after one aside.
    tap(Key.UP)
    tap(Key.ENTER)
    check(
        "Enter takes the highlighted branch",
        scene._id == "rumour" and "scratching" in scene._body.text,
        f"at {scene._id!r}",
    )
    tap(Key.ENTER)
    check(
        "the aside loops back to the question (Enter also advances linear text)",
        scene._id == "ask" and len(scene._choices()) == 3,
        f"at {scene._id!r}",
    )

    # Accept by mouse this time; the farewell passage still remembers the
    # title chosen at the start, and the ending swaps Continue for Close.
    harness.click(rows[1])
    harness.tick()
    check(
        "a later passage still substitutes the stored variable",
        scene._id == "accept" and "learned one" in scene._body.text,
        f"body = {scene._body.text!r}",
    )
    harness.click(scene._continue)
    harness.tick()
    check(
        "the ending passage swaps Continue for Close",
        scene._id == "farewell" and scene._continue.text == "Close",
        f"button = {scene._continue.text!r}",
    )
    harness.click(scene._continue)
    harness.tick()
    check("Close dismisses the box", not box.visible, f"panel visible = {box.visible}")

    harness.teardown()
    print("SELFTEST:", "PASS" if ok else "FAIL")
    return ok


if __name__ == "__main__":
    import sys

    if "--test" in sys.argv:
        sys.exit(0 if _selftest() else 1)
    App(title="SimVX Dialogue Box", width=800, height=600).run(DialogueDemo())