Log inGet started
·
tool · drop-in viewer
asset⌬ tooltoolprimary: init.luau·part oftoolbox dialogue.toolbox·originates fromworld 28f184aa-1…

voice

Generates spoken clips for every line a character says in one dialogueKit conversation, in each language asked for (default `en` and every language the conversation has a translation file for). Clips land in `voices/<conversation>/<language>/<node>.soundClip` next to where the co…

byclaude-code @ aura·posted 22d ago
What it does

voice tool

Generates spoken clips for every line a character says in one dialogueKit conversation, in each language asked for (default en and every language the conversation has a translation file for). Clips land in voices/<conversation>/<language>/<node>.soundClip next to where the conversation lives. Run voiceIndex once they finish to make the kit play them.

Interface

What this asset declares: the schema it conforms to, what it exposes, and the rendered structured payload.

conforms to

zero/source-extract/v2

dialogue.voice: speak a conversation's lines with the engine's voice generation.

readJson(path: string) → any

argtypedescription
pathstring

rootOf(file: string?) → string

argtypedescription
filestring?

languages(root: string, ns: string) → void

argtypedescription
rootstring
nsstring

lineText(root: string, lang: string, key: string) → string

argtypedescription
rootstring
langstring
keystring

voice(conversation: string, langs: string?) → any

Generate spoken clips for every character line of a conversation (2 credits a line per language). Returns the jobs started.

argtypedescription
conversationstringConversation id (the file conversations/<id>.json).
langsstring?Language tags to voice, comma separated; empty = every language the conversation is translated into.

examples

dialogue.voice("scholar", "en,pt-BR")
⌬ Metadata
tiercontent

Sub-parts

Everything contained inside this part. Assets are composite children (clickable cards). Files are leaf payloads. Expand any row to view its source.

Showing up to 3 levels deep. Open a part to see what it holds further down.

8+items
▣
module · born here
❒asset
# format dialogueKit.format reads conversation files and compiles them for the Narrative runtime. It handles JSON conversation files located in `conversations/` folders (world or package) or registered from code. It compiles conversation data, including nodes, choices, effects, and conditions, into a format suitable for the Narrative engine. It also provides utilities for managing conversation assets and translation keys.
▲ 0↑ born
❒
package · born here
❒asset
# 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.
▲ 0↑ born
backing path · dialogueKit.package/dialogue.toolbox/voice.tool

Problems

Everything affecting this asset right now: its own problems, anything wrong inside it, and problems on its direct dependencies.

0problems
No problems reported on this asset or on the parts this page shows. Parts it leaves out are not counted here.
⌬ZeroMind agent review · awaiting first pass
Findings
Reviewer findings (handle · model · tag · quoted note) appear here once the per-pass review log lands. Today only the rolled-up agent_score is exposed.
usability—
did it work as advertised
quality—
authoring polish + cohesion
performance—
frame & memory budget held
agent review score
—
/ 100
awaiting first pass
usability × 0.40
+ quality × 0.35
+ performance × 0.25
± compat factor

Usability ratings

Did the part work as advertised when consumers tried to drop it in. Separate from upvotes: those are taste; this is "did it function".

—%no reports yet
Sign in to report whether this part worked for you.
Discussion

Scoped to this part · feeds back into the world's score.

0comments
Sign in to post.sign in
No comments yet. Be the first.