bubbles/lib.rs
1//! Lightweight, engine-agnostic dialogue runtime for Rust games.
2//!
3//! Write branching dialogue in `.bub` scripts, compile them once, then drive
4//! the dialogue from any game loop via a pull-based event API.
5//!
6//! # Quick start
7//!
8//! ```rust
9//! use bubbles::{compile, DialogueEvent, HashMapStorage, Runner};
10//!
11//! let source = "title: Greet\n---\nHello!\n===\n";
12//! let prog = compile(source).unwrap();
13//! let mut runner = Runner::new(prog, HashMapStorage::new());
14//! runner.start("Greet").unwrap();
15//!
16//! assert!(matches!(
17//! runner.next_event().unwrap(),
18//! Some(DialogueEvent::NodeStarted(_))
19//! ));
20//! assert!(matches!(
21//! runner.next_event().unwrap(),
22//! Some(DialogueEvent::Line { .. })
23//! ));
24//! assert!(matches!(
25//! runner.next_event().unwrap(),
26//! Some(DialogueEvent::NodeComplete(_))
27//! ));
28//! assert!(matches!(
29//! runner.next_event().unwrap(),
30//! Some(DialogueEvent::DialogueComplete)
31//! ));
32//! ```
33//!
34//! # Modules
35//!
36//! | Module | Contents |
37//! |--------|----------|
38//! | [`value`] | [`Value`], [`VariableStorage`], [`HashMapStorage`] |
39//! | [`compiler`] | [`compile`], [`compile_many`], [`validate`], [`Program`], [`VariableDecl`] |
40//! | [`runtime`] | [`Runner`], [`DialogueEvent`], [`LineProvider`], [`line_id_from_tags`], `RunnerSnapshot` (serde) |
41//! | [`library`] | [`FunctionLibrary`] and built-in functions |
42//! | [`saliency`] | [`SaliencyStrategy`], [`FirstAvailable`], [`BestLeastRecentlyViewed`], `RandomAvailable` (`rand` feature) |
43//!
44//! Lint policy is defined once in `Cargo.toml` under `[lints.rust]` /
45//! `[lints.clippy]`; we deliberately do not duplicate it here.
46
47pub mod compiler;
48pub mod error;
49pub mod library;
50pub mod runtime;
51pub mod saliency;
52pub mod value;
53
54pub use compiler::{Program, VariableDecl, compile, compile_many, validate};
55pub use error::{DialogueError, Result};
56pub use library::FunctionLibrary;
57#[cfg(feature = "serde")]
58pub use runtime::RunnerSnapshot;
59pub use runtime::{
60 DialogueEvent, DialogueOption, HashMapProvider, LineProvider, PassthroughProvider, Runner,
61 line_id_from_tags,
62};
63#[cfg(feature = "rand")]
64pub use saliency::RandomAvailable;
65pub use saliency::{BestLeastRecentlyViewed, Candidate, FirstAvailable, SaliencyStrategy};
66pub use value::{HashMapStorage, Value, VariableStorage};