bubbles/runtime/
event.rs

1//! [`DialogueEvent`], [`DialogueOption`], and [`MarkupSpan`] - the output types of the runner.
2
3/// How a [`DialogueEvent::Line`] should be treated for display or logging.
4///
5/// The runner sets this from trailing `#tag` metadata on the source line:
6/// `#debug` yields [`LineMode::Debug`], `#narration` yields [`LineMode::Narration`].
7/// If both are present, [`LineMode::Debug`] wins. All other lines use [`LineMode::Normal`].
8///
9/// Tags that only exist to set the mode remain in [`DialogueEvent::Line::tags`]; your
10/// host can ignore them once you branch on [`LineMode`].
11#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
12pub enum LineMode {
13    /// Ordinary character or narrator line.
14    #[default]
15    Normal,
16    /// System or omniscient narration (subtitle style, VO bus, etc.).
17    Narration,
18    /// Developer or QA line you may want to hide in release builds.
19    Debug,
20}
21
22/// Derives [`LineMode`] from trailing `#tag` strings (without the `#` prefix).
23#[must_use]
24pub fn line_mode_from_tags(tags: &[String]) -> LineMode {
25    if tags.iter().any(|t| t == "debug") {
26        LineMode::Debug
27    } else if tags.iter().any(|t| t == "narration") {
28        LineMode::Narration
29    } else {
30        LineMode::Normal
31    }
32}
33
34/// A resolved inline markup span: a named annotation over a byte range in the
35/// stripped display text.
36///
37/// Spans are produced at runtime, after expression substitution, so [`start`]
38/// and [`length`] are byte offsets into the final [`DialogueEvent::Line::text`]
39/// / [`DialogueOption::text`] string.
40///
41/// The runtime assigns no meaning to span names or properties. Your game
42/// decides what `[wave]`, `[color value=red]`, or `[pause /]` means and how
43/// to render it.
44///
45/// [`start`]: MarkupSpan::start
46/// [`length`]: MarkupSpan::length
47#[derive(Debug, Clone, PartialEq, Eq)]
48pub struct MarkupSpan {
49    /// The markup tag name, e.g. `wave` for `[wave]text[/wave]`.
50    pub name: String,
51    /// Byte offset of the first character of the spanned text in the display string.
52    pub start: usize,
53    /// Byte length of the spanned text. Zero for self-closing tags.
54    pub length: usize,
55    /// Zero or more `(key, value)` pairs from the tag, e.g. `[("value", "red")]`
56    /// for `[color value=red]`.
57    pub properties: Vec<(String, String)>,
58}
59
60/// Returns the id from a `#line:<id>` tag in `tags`, if any (first match wins).
61///
62/// This matches the id passed to [`crate::LineProvider`]. Use it to key voice-over or analytics
63/// without re-parsing [`DialogueEvent::Line::tags`] or [`DialogueOption::tags`].
64#[must_use]
65pub fn line_id_from_tags(tags: &[String]) -> Option<String> {
66    tags.iter()
67        .find_map(|t| t.strip_prefix("line:"))
68        .map(str::to_owned)
69        .filter(|s| !s.is_empty())
70}
71
72/// An option presented to the player.
73#[derive(Debug, Clone, PartialEq, Eq)]
74pub struct DialogueOption {
75    /// Display text of the option (markup tags stripped, expressions evaluated).
76    pub text: String,
77    /// Whether this option is currently available (guards that evaluate to false make it unavailable).
78    pub available: bool,
79    /// If the option text was tagged with `#line:<id>`, the stable id (no `line:` prefix).
80    pub line_id: Option<String>,
81    /// Trailing `#tag` metadata.
82    pub tags: Vec<String>,
83    /// Inline markup spans over [`text`](DialogueOption::text), in source order.
84    /// Empty when the option text contains no markup tags.
85    pub spans: Vec<MarkupSpan>,
86}
87
88/// Events emitted by [`crate::Runner`] one at a time via [`crate::Runner::next_event`].
89#[non_exhaustive]
90#[derive(Debug, Clone, PartialEq)]
91pub enum DialogueEvent {
92    /// A node has started executing.
93    NodeStarted(String),
94    /// A line of dialogue ready to display.
95    Line {
96        /// Optional speaker name.
97        speaker: Option<String>,
98        /// Display text with all `{expr}` fragments evaluated and markup tags stripped.
99        text: String,
100        /// If the line was tagged with `#line:<id>`, the stable id (no `line:` prefix).
101        line_id: Option<String>,
102        /// Trailing `#tag` metadata.
103        tags: Vec<String>,
104        /// Hint for filtering or routing (from `#narration` / `#debug` when present).
105        line_mode: LineMode,
106        /// Inline markup spans over [`text`](DialogueEvent::Line::text), in source order.
107        /// Empty when the line contains no markup tags.
108        spans: Vec<MarkupSpan>,
109    },
110    /// A set of options for the player to choose from.
111    Options(Vec<DialogueOption>),
112    /// A host command to execute.
113    Command {
114        /// Command name.
115        name: String,
116        /// Arguments with `{expr}` substituted.
117        args: Vec<String>,
118        /// Trailing tags.
119        tags: Vec<String>,
120    },
121    /// The current node has finished.
122    NodeComplete(String),
123    /// All dialogue has finished.
124    DialogueComplete,
125}
126
127#[cfg(test)]
128#[path = "event_tests.rs"]
129mod tests;
bubbles/runtime/event.rs

bubbles/runtime/
event.rs
