Log inGet started
World

Chatterbox Square: Dialogue, Choices and Story Flags Kit

README.md

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:

{
  "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):

{
  "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():

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):

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

piecewhat it is
dialogueKit.apithe one interface: local Dialogue = require("~dialogueKit.api")
Talker componentmakes a character talk: conversation, private or shared, and its own look (or default)
DialogueSettings componentthe whole world's look, one field each (put it on any one entity)
DialogueHUD componentdraws the conversation and takes its taps; spawned for you, never placed
talk input mapadvance / fast-forward, navigate, pick 1-4, back on keyboard, pad and touch; holds the player still
dialogue toolboxzero 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-BRtheir words in English and Brazilian Portuguese, and the kit's own UI words
portraits/nine painted visual-novel portraits for the samples
dialogueKitTests test suiteproves the main things (see Tests)

Presentations

Talker.presentation, DialogueSettings.presentation or Dialogue.setPresentation(name).

idlabelwhat it looks likedefault answer layout
boxClassic RPG boxa text box along the bottom with a name tab and a bouncing "next" hintlist
bubblesSpeech bubblesa bubble with a tail floating over whoever speaks (the player too), answers at the bottomlist
vnVisual noveldimmed scene, a big character portrait, a wide box, answers abovelist
cinematicCinematic subtitlesletterbox bars and centred movie subtitleslist
wheelChoice wheela subtitle strip and a radial answer wheel, like big action RPGswheel
comicComic panelsthe last lines as small tilted panels, the current one big, halftone and inklist
retroRetro pixel boxa chunky bordered pixel box, upper-case text, blinking ▶ cursorlist
phonePhone chata text-message thread on a phone, typing dots, your replies on the rightlist

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).

idlabellook
scifiSci-fidark glass, cyan glow, monospace, upper case
fantasyFantasyparchment, serif, oxblood name plate
cartoonCartoonwhite panels, thick black outlines, hard drop shadow, comic font
pixelPixelnavy box, white 4 px border, no rounding, upper case
minimalMinimalquiet dark gradient, sans serif, thin border
horrorHorrornear-black, blood red, words drifting gently
cozyCozycream 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

fieldvalues
revealletter (typewriter), word, fade (words drift in), shake (letters slam in and tremble: shouting)
choiceLayoutauto (the presentation's own), list, wheel, timed (a draining bar; the default answer is picked when it runs out)
voicespeech (generated clips, see Voices), babble (synthesized blips per character), silent
cameradefault, 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.

{
  "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 keymeaning
stringstranslation namespace: words live in locales/<language>/<strings>.json (default: the id)
speakersper 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)
startthe first node
presentation, stylethe conversation's own look, used when nothing above it decides

Node kinds, decided by their keys:

nodekeyswhat happens
linesay, optional text, nextthe speaker says text (key, default <node>); no next ends the conversation
choicesay, choices: [ ... ], optional timeout, default, layoutthe speaker asks, the player answers
branchif, then, else, or branch: [ { if, next } ], elsegoes the first way whose condition holds
actionset / emit / xp, next, and no saychanges flags without saying anything
end"end": truestops

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

actionkeyboardgamepadtouch
finish the line / next / confirm the highlighted answerSpace, Enter, Esouth (A), west (X)tap anywhere on the conversation
fast-forwardhold any of thoseholdpress and hold
move the highlightarrows, WASDleft stick, d-pad-
pick answer 1-4 directly1-4-tap the answer
choose on the answer wheelpress on the wheel, drag toward an answer, release (mouse)push the stick toward it, then confirmput a finger on the wheel, slide toward an answer, lift
leave (when allowed)Escapeeast (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"))

callwhat it does
Dialogue.start(id, opts?) -> booleanopen a private conversation for the local player. opts: npc, presentation, style, reveal, layout, voice, camera, onEnd
Dialogue.talkTo(entityOrName) -> booleanwhat 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) -> unsubscribeevents 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 / setMemoryOnlythe 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.flagsget, 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, VERSIONthe 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:

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.