# dialogueKit 1.0.4
Conversations for any Zero game: characters who talk, players who pick answers, and choices the game remembers. Conversations are **data files**, not code. Put a `Talker` on any character, point it at a conversation, and players get a **Talk** prompt when they walk up and a conversation that types out letter by letter: tap or press confirm to finish the line, hold it to fast-forward.
- **8 presentations × 7 styles**, all behind one field, so a world changes its whole look by changing one setting.
- **Conditions and effects** in a tiny language: `"helped_baker && coins >= 2"`, `"set": { "helped_baker": true, "coins": "+2" }`.
- **Story flags per player**, saved in the player's own saveKit save: still there after they leave and come back.
- **Shared conversations** (a town crier for everyone nearby) show the same line and the same answers on every screen; the game that owns the character runs them.
- **Every word is translatable**: all text comes from the world's translation catalogs (English and Brazilian Portuguese ship with the samples).
- **Keyboard, gamepad and touch**, with answers at least 48 points tall so a thumb hits them.
- **Voices**: lines spoken aloud with the engine's voice generation, cosy "babble" blips, or silent.
- **Camera framing** on the engine's own cutscene camera, optional per character.
Version **1.0.4** (`Dialogue.VERSION`). The showcase world is **Chatterbox Square**: one character per presentation on a grid, a shared town crier, and a board of your story flags.
## Install
Install `dialogueKit.package` from ZeroMind into `/source` (search for "dialogueKit", or `zeromind_install` with its guid). One install brings everything it needs: **interactKit** (the Talk prompt), **soundstage** (UI sounds, the voice channel, music ducking), **saveKit** (story flags and XP) and **Narrative** (the brain that runs each conversation graph).
## First example: a choice the game remembers
A five-node conversation with one choice. Saying yes sets the flag `helped_ada`; talking to Ada again reads that flag and goes down a different branch.
**1. The conversation**, `/source/conversations/firewood.json`:
```json
{
"strings": "firewood",
"speakers": { "ada": { "name": "name", "color": "#f0a35e", "voice": { "pitch": 1.2 } } },
"start": "hello",
"nodes": {
"hello": { "if": "helped_ada", "then": "again", "else": "ask" },
"ask": { "say": "ada", "choices": [
{ "id": "yes", "next": "thanks", "set": { "helped_ada": true } },
{ "id": "no", "next": "bye" } ] },
"thanks": { "say": "ada" },
"bye": { "say": "ada" },
"again": { "say": "ada" }
}
}
```
**2. Its words**, `/source/locales/en/firewood.json` (every key is `<node>`, or `<node>_<choice>` for an answer):
```json
{
"name": "Ada the Baker",
"ask": "My oven's gone cold and the festival bread is due at noon. Could you fetch me some firewood?",
"ask_yes": "Of course, I'll help.",
"ask_no": "Sorry, I'm busy.",
"thanks": "You're a treasure! The first loaf is yours.",
"bye": "Ah well. Off you go, then.",
"again": "There's my firewood hero! Your loaf is on the windowsill."
}
```
**3. Put it on a character.** In `scenes/main.scene/build.luau`, at the end of `function content()`:
```lua
local ada = entity.spawn("Ada", { position = { 0, 0, 5 } })
ada.component.add("Model", { model = "capsule" })
ada.component.add(asset.resolve("dialogueKit.Talker", "component"), { conversation = "firewood" })
```
**4. Press play**, walk up to Ada and press **E** (pad: west button; phone: the on-screen Talk button). Answer "Of course, I'll help." Talk to her again: she greets you as her firewood hero. Leave the world and come back: she still remembers.
To react from code (in `entrypoint.luau` or a component that runs in play):
```lua
local Dialogue = require("~dialogueKit.api")
Dialogue.on("end", function(ev) print(ev.conversation, "ended:", ev.reason) end)
print(Dialogue.flags.get("helped_ada"))
```
## What you get
| piece | what it is |
|---|---|
| `dialogueKit.api` | the one interface: `local Dialogue = require("~dialogueKit.api")` |
| `Talker` component | makes a character talk: conversation, private or shared, and its own look (or `default`) |
| `DialogueSettings` component | the whole world's look, one field each (put it on any one entity) |
| `DialogueHUD` component | draws the conversation and takes its taps; spawned for you, never placed |
| `talk` input map | advance / fast-forward, navigate, pick 1-4, back on keyboard, pad and touch; holds the player still |
| `dialogue` toolbox | `zero dialogue voice <conversation>` speaks every line; `zero dialogue voiceIndex` registers the clips |
| `conversations/` | nine sample conversations (one per presentation, plus the shared crier) |
| `locales/en`, `locales/pt-BR` | their words in English and Brazilian Portuguese, and the kit's own UI words |
| `portraits/` | nine painted visual-novel portraits for the samples |
| `dialogueKitTests` test suite | proves the main things (see Tests) |
## Presentations
`Talker.presentation`, `DialogueSettings.presentation` or `Dialogue.setPresentation(name)`.
| id | label | what it looks like | default answer layout |
|---|---|---|---|
| `box` | Classic RPG box | a text box along the bottom with a name tab and a bouncing "next" hint | list |
| `bubbles` | Speech bubbles | a bubble with a tail floating over whoever speaks (the player too), answers at the bottom | list |
| `vn` | Visual novel | dimmed scene, a big character portrait, a wide box, answers above | list |
| `cinematic` | Cinematic subtitles | letterbox bars and centred movie subtitles | list |
| `wheel` | Choice wheel | a subtitle strip and a radial answer wheel, like big action RPGs | wheel |
| `comic` | Comic panels | the last lines as small tilted panels, the current one big, halftone and ink | list |
| `retro` | Retro pixel box | a chunky bordered pixel box, upper-case text, blinking ▶ cursor | list |
| `phone` | Phone chat | a text-message thread on a phone, typing dots, your replies on the right | list |
## Styles
`Talker.style`, `DialogueSettings.style` or `Dialogue.setStyle(name)`. Every presentation reads the same palette, fonts and frame, so **any presentation works in any style** (8 × 7 = 56 looks).
| id | label | look |
|---|---|---|
| `scifi` | Sci-fi | dark glass, cyan glow, monospace, upper case |
| `fantasy` | Fantasy | parchment, serif, oxblood name plate |
| `cartoon` | Cartoon | white panels, thick black outlines, hard drop shadow, comic font |
| `pixel` | Pixel | navy box, white 4 px border, no rounding, upper case |
| `minimal` | Minimal | quiet dark gradient, sans serif, thin border |
| `horror` | Horror | near-black, blood red, words drifting gently |
| `cozy` | Cozy | cream and terracotta, round corners, soft shadow |
The showcase uses: box/fantasy, bubbles/cartoon, vn/cozy, cinematic/horror, wheel/scifi, comic/cartoon, retro/pixel, phone/minimal and box/cozy (the crier). `Dialogue.styles.define("mine", { base = "cozy", accent = "#3a7" })` adds your own.
## Text reveal, answer layouts, voices
| field | values |
|---|---|
| reveal | `letter` (typewriter), `word`, `fade` (words drift in), `shake` (letters slam in and tremble: shouting) |
| choiceLayout | `auto` (the presentation's own), `list`, `wheel`, `timed` (a draining bar; the `default` answer is picked when it runs out) |
| voice | `speech` (generated clips, see Voices), `babble` (synthesized blips per character), `silent` |
| camera | `default`, `on`, `off` |
Any line can override its reveal (`"reveal": "shake"`), its camera shot (`"camera": "close"`) and its speed (`"speed": 0.6`); any choice node can be timed (`"timeout": 8, "default": "run"`) or force a layout (`"layout": "wheel"`).
**Which setting wins:** options passed to `Dialogue.start` > the world's settings when `force` is on > the Talker's own field > the world's `DialogueSettings` > the conversation file's `presentation` / `style` > the built-in default (box, fantasy, letter, auto, babble).
**Changing the look of an open conversation:** a conversation already on screen follows any change on the next frame, without starting again: set a Talker's `presentation` to `bubbles` mid-line and the line carries on in a bubble; then call `Dialogue.setPresentation("vn")` (or change `DialogueSettings.presentation`) and it turns into the visual-novel look straight away. The same goes for `style`, `reveal`, `choiceLayout`, `voice` and `camera`. For the open conversation the latest change wins; the next conversation picks its look in the order above again. The `look` event fires on each change.
**Screen layer:** the conversation draws on UI layer 950, above saveKit's HUD (900), so the level / XP panel in the corner never covers a line's last words in any look.
## Data format
A conversation is one file, `conversations/<id>.json`, in the world's `/source/conversations/` (or the package's own, for the samples). Adding a conversation is adding a file. `Dialogue.register(id, table)` adds one from code; `Dialogue.validate(id)` checks one and names the node at fault.
```json
{
"strings": "dk_baker",
"presentation": "box", "style": "fantasy",
"speakers": {
"mira": { "name": "name", "color": "#f0a35e", "portrait": "mira",
"voice": { "pitch": 1.2, "babble": "blip", "rate": 2 }, "side": "left" }
},
"start": "hello",
"nodes": { "...": {} }
}
```
| top-level key | meaning |
|---|---|
| `strings` | translation namespace: words live in `locales/<language>/<strings>.json` (default: the id) |
| `speakers` | per speaker: `name` (a key), `color`, `portrait` (a texture name, path or guid), `voice` (`pitch`, `babble` = blip / soft / chirp / low / robot), `side`, `entity` (a scene entity name the camera frames) |
| `start` | the first node |
| `presentation`, `style` | the conversation's own look, used when nothing above it decides |
Node kinds, decided by their keys:
| node | keys | what happens |
|---|---|---|
| line | `say`, optional `text`, `next` | the speaker says `text` (key, default `<node>`); no `next` ends the conversation |
| choice | `say`, `choices: [ ... ]`, optional `timeout`, `default`, `layout` | the speaker asks, the player answers |
| branch | `if`, `then`, `else`, or `branch: [ { if, next } ]`, `else` | goes the first way whose condition holds |
| action | `set` / `emit` / `xp`, `next`, and no `say` | changes flags without saying anything |
| end | `"end": true` | stops |
A choice: `{ "id": "yes", "next": "thanks", "if": "coins >= 2", "locked": "too_poor", "set": { ... }, "emit": "topic", "xp": 10 }`. Its words are the key `<node>_<id>` unless it has `text`. With `if` false it is hidden; with `locked` as well it is shown greyed out with that text instead. Speaker `"player"` is the player (their bubble floats over their own head; their texts sit on the right of the phone).
**Conditions** (`if`): flag names, `!` / `not`, `&&` / `and`, `||` / `or`, `== != < <= > >=`, numbers, `'words'`, `true` / `false`, parentheses. A flag never set reads as false, 0 or "". Example: `"helped_baker && (coins > 2 || vip)"`.
**Effects** on any node or choice:
- `"set": { "helped_baker": true, "mood": "happy", "coins": "+2", "lives": "-1" }` sets a flag, or adds to a number with `"+N"` / `"-N"`.
- `"emit": "door_opened"` (or a list) fires `Dialogue.onEmit("door_opened", fn)` in your game code.
- `"xp": 25` grants saveKit XP (turn off with `DialogueSettings.xp = false`).
**Text keys**: a key without a dot is inside the conversation's namespace, so `"text": "hello"` reads `<strings>.hello`; a key with a dot is used as written. Lines can show flags: `"You have {{ coins }} coins."`.
## Controls
| action | keyboard | gamepad | touch |
|---|---|---|---|
| finish the line / next / confirm the highlighted answer | Space, Enter, E | south (A), west (X) | tap anywhere on the conversation |
| fast-forward | hold any of those | hold | press and hold |
| move the highlight | arrows, WASD | left stick, d-pad | - |
| pick answer 1-4 directly | 1-4 | - | tap the answer |
| choose on the answer wheel | press on the wheel, drag toward an answer, release (mouse) | push the stick toward it, then confirm | put a finger on the wheel, slide toward an answer, lift |
| leave (when allowed) | Escape | east (B) | - |
While a conversation is open its `talk` input map stands the player's movement down. On a narrow or portrait screen everything is sized to the screen's width, and every answer is at least 48 points tall.
## Multiplayer and saving
Worlds are always multiplayer and players come from the scene's player prototype; dialogueKit needs nothing extra.
- **Private** (`Talker.mode = "private"`, the default): the conversation runs on the screen of the player who talked, and nobody else sees it.
- **Shared** (`mode = "shared"`): put the Talker on a **synced** entity (`entity.spawnSynced`). The peer that owns that entity runs the conversation through Narrative and writes a handful of plain synced values on the Talker: run number, node, kind, answers on offer (`"hear,festival,!locked"`), a step counter, the last pick, and the flags the step changed (JSON). Every player within `hearRange` (12 m) draws the same line and the same answers from them. Anyone taking part can **ask** to start, advance or pick (channel `dk:req`); only the owner **decides**, and each request carries the step it was made at, so two players pressing at once move it one step. `autoAdvance` lets a shared line move on by itself; a timed choice picks its default on the owner when time runs out. Shared state uses plain numbers and strings on purpose: synced entity references and synced tables don't reach other players today (#21241, #21242).
- **Story flags are per player.** Each player's flags live in their own saveKit save under `dialogueKit_flags`, keyed to their account, so they survive leaving and coming back. The effects of a shared step are applied to each listener's own flags. `Dialogue.flags.get / set / all / reset / onChange`. Outside play, or with `Dialogue.setMemoryOnly(true)`, flags stay in memory.
- XP from `xp` effects goes to saveKit's XP and levels.
## Voices
- **babble** (default): a short synthesized syllable every couple of letters, pitched and timbred per speaker (`voice.pitch`, `voice.babble`), on the `voice` mixer channel, with the music ducked a little.
- **speech**: run `zero dialogue voice <conversation> [en,pt-BR]` (2 credits a line per language). It generates every line a character says, in each language, with the engine's voice generation, into `voices/<conversation>/<language>/<node>.soundClip`. When those finish, run `zero dialogue voiceIndex` to rewrite `dialogueKit.voices`, which the kit plays from. Each character sounds different through its `voice.pitch`; soundstage ducks the music and ambience while a line plays. A line with no clip yet babbles. The showcase's scholar, Elowen, is voiced in both languages.
- **silent**.
## Camera framing
With camera framing on (`Talker.camera = "on"`, or `DialogueSettings.camera`), the conversation plays **one** engine cutscene (`cutscene.play`) for its whole length, whose single shot follows two invisible marker entities. Each line eases the markers to a new shot (`speaker` over the listener's shoulder, `player`, `wide`, `close`), so the shot changes without starting another cutscene (a cutscene can only play once, #10455). The cutscene holds the player still and hands the camera back when the conversation ends.
## Translations
Every word a player reads comes from translation catalogs: the conversations' namespaces (`dk_baker`, ...) and the kit's own `dialoguekit` namespace (Talk, Listen, You, Locked, typing…). Add a language by adding `locales/<tag>/<namespace>.json` with the same keys; `i18n.choose("pt-BR")` switches it live (the showcase board's 🌐 button does exactly that). Labels you build yourself should read their text with `i18n.t(key)` too.
## API (`local Dialogue = require("~dialogueKit.api")`)
| call | what it does |
|---|---|
| `Dialogue.start(id, opts?) -> boolean` | open a private conversation for the local player. opts: `npc`, `presentation`, `style`, `reveal`, `layout`, `voice`, `camera`, `onEnd` |
| `Dialogue.talkTo(entityOrName) -> boolean` | what pressing a Talker's prompt does (private or shared) |
| `Dialogue.stop()`, `Dialogue.isTalking()`, `Dialogue.current()` | leave, ask, or read what is on screen (`conversation, node, speaker, text, choices, chars, total, presentation, style`) |
| `Dialogue.on(event, fn) -> unsubscribe` | events `start`, `line`, `choices`, `pick`, `end`, `flag`, `emit`, `look` (the open conversation changed presentation or style) |
| `Dialogue.onEmit(topic, fn)` | a conversation's `emit` effect (`"*"` for all) |
| `Dialogue.setPresentation / setStyle / setReveal / setChoiceLayout / setVoice / setCamera / setSpeed / setForce / setXp / setMemoryOnly` | the world's settings (what `DialogueSettings` calls) |
| `Dialogue.settings()`, `Dialogue.catalog()` | the current settings; every option with its label |
| `Dialogue.register(id, data)`, `list()`, `validate(id)`, `reload(id?)` | conversations from code, every id found, check one, re-read files |
| `Dialogue.flags` | `get, set, setMany, all, reset, ready, onChange, memoryOnly` |
| `Dialogue.present.define(name, fn)`, `Dialogue.styles.define(name, t)` | add your own presentation or style |
| `Dialogue.PRESENTATIONS, STYLES, REVEALS, LAYOUTS, VOICES, EVENTS, VERSION` | the lists |
### Talker fields
`conversation`, `mode` (private / shared), `presentation`, `style`, `reveal`, `choiceLayout`, `voice`, `camera` (each `default` = follow the world), `label` (prompt text; empty = "Talk" / "Listen" translated), `range` (2.8 m), `hearRange` (12 m, shared), `headHeight` (where bubbles float, 2.1 m), `autoAdvance` (shared: seconds a shown line waits, 0 = wait for a press), `promptStyle` (interactKit's prompt look).
## Tests
`dialogueKitTests.testSuite` runs headless (no play needed). The suite is selected by its asset name:
```lua
tools.use("tests", "run", "dialogueKitTests")
```
(from the shell: `zero tests run dialogueKitTests`). Its 13 tests prove:
1. the version in `package.yaml` matches `Dialogue.VERSION`;
2. every sample conversation compiles and starts;
3. a link to a missing node is an error naming the node at fault;
4. the condition language: and / or / not, comparisons, words, parentheses, unset flags;
5. a choice's `set` writes the flag and the next talk takes the other branch (the first example's loop);
6. `"+N"` adds, hidden vs locked answers, `xp` and `emit` effects reach their listeners;
7. a timed choice carries its timeout and default, and a default naming no choice is an error;
8. reveal lengths and word boundaries for every reveal mode;
9. all 8 presentations build in all 7 styles with every answer layout, at desktop and phone sizes;
10. an open conversation changes presentation and style on the next frame, without leaving its line;
11. the answer wheel maps a drag direction to the answer it points at, with a dead zone in the middle;
12. answers are at least 48 points tall on a phone;
13. every text key of every sample resolves in English and Brazilian Portuguese with the same keys.
## Performance (measured)
- **Desktop editor** (this machine, 2097×1409 viewport, the whole of Chatterbox Square): about **25 fps idle, 21 fps with a conversation open**. The frame is GPU-bound on the renderer's deferred resolve, which costs the same with every light off, so this is the machine's GPU at that size, not the kit.
- **Web build:** about **28 to 29 fps** in the square, measured by the world's owner in a browser (the agent that built the kit runs inside the desktop engine and cannot open a browser). The web gallery frame rate is known to be low on multiplayer worlds (#20750). In 1.0.1 opening a conversation in the showcase dropped the web build to about 4 fps under a flood of errors from the square's name labels, which faded their 3D text when a conversation opened. Since 1.0.2 the square's labels are screen nameplates and nothing changes a 3D text label at runtime, so a conversation should open as smoothly as on desktop; that has not yet been re-measured in a browser.
- **The kit's own cost** is `DialogueHUD` at about 0.3 ms a frame with a conversation on screen; Narrative steps only on a press, and nothing in the kit edits 3D text.
- **Phone shape** (390×844) checked in the engine for every presentation's layout, touch target sizes, the answer wheel and the showcase nameplates.
## Known limits
- **#21241 / #21242**: synced entity references and synced tables don't arrive on other players' engines, so shared conversations use plain synced numbers and strings.
- **#10455**: a cutscene can only play once, so framing uses one long cutscene per conversation whose markers move.
- **#7781 / #19402**: changing a floating 3D text label's string or colour can keep the old text or cost a few ms (and on the web it flooded errors), so speech bubbles and the showcase's nameplates are screen UI anchored over the character, and nothing edits 3D text at runtime.
- **#14448**: two engines signed in as the same account collide as one player, so two players keeping separate saves can only be shown with two accounts.
- **#19843**: a fresh install needs the release published first.
- **#21333**: a write to the world source during play lands on the play copy; author conversations in edit mode.
- **#20750**: the web gallery frame rate is low on multiplayer worlds.
## Changelog
- **1.0.4**: built against interactKit 1.6.4, saveKit 1.3.13 (with menusKit 1.3.19 and controlsKit 1.3.2) and soundstage 2.1.3, so a world that installs dialogueKit beside questKit, economyKit or arpgKit holds one release of each; package.yaml states those versions; current engine library. No dialogueKit code changed.
- **1.0.3**: inline words. A conversation can carry its own words: any `text`, choice `text`, `locked`, `title` or speaker `name` that is not a translation key (it holds a space or capitals) is shown as written, and a table `{ en = "...", ["pt-BR"] = "..." }` picks the player's language (falling back to en). `{{ flag }}` fills in as in catalogs. For games whose words live with their story data instead of `/source/locales`. Keys work exactly as before.
- **1.0.2**: an open conversation follows a change of look (presentation, style, reveal, answer layout, voice, camera) on the next frame, with a new `look` event; drag to choose on the answer wheel with mouse or finger; the conversation draws above saveKit's level panel, so no look loses a line's last words; the README's test command names the suite as the runner knows it; no em dashes in the kit's text. Showcase: readable screen nameplates over every character (no overlaps, drawn over the houses, edge arrows on a phone), and a phone story board that starts folded and opens below the level ring.
- **1.0.1**: the number badge on a highlighted answer no longer takes a gradient as its text colour (fantasy style showed a UI validation error and an unstyled badge).
- **1.0.0**: first release. 8 presentations, 7 styles, 4 reveals, 3 answer layouts, conditions and effects on Narrative, saveKit flags, shared conversations, speech / babble / silent voices, cutscene framing, English and Brazilian Portuguese, nine samples, portraits, voice tool, tests.