Skip to content

Dialogue

Jump to bottom
13976_gamedev (Student) edited this page Jul 29, 2026 · 2 revisions

Dialogue

Starhelm never draws anything. It builds a SpeechRequest — speaker, title, text, category tag and timing — and hands it to your ISpeechSink, which decides whether that becomes a bubble, a subtitle, a chat log or text-to-speech. No sink means total silence, so dialogue stays entirely optional.

The fastest way in

Open Tools > Starhelm > Dashboard and press Set up next to Dialogue in the Overview. That single button creates a speech library, adds something to display the lines, adds the scheduler, and puts a trigger on every actor so spawn, death, selection and idle lines fire. Press Play and your AI talks.

To write the lines, open Tools > Starhelm > Dialogue.

The pieces

Piece What it is
Speech Library The asset holding your lines. Each entry is a cue.
Speech Cue One line (or several to pick from) plus its trigger and timing.
Speech Profile A character's voice: a display name and the libraries it speaks from.
Speech Service Drop-in component that owns the scheduler. Works with any game, no template needed.
ISpeechSink Your renderer. The template ships one that draws floating bubbles.

Triggers

A cue answers a trigger, which is just a tag. The usual moments have names in SpeechTriggers:

  • on.spawn — the actor enters the world
  • on.death — it dies (watch a health stat, or call Die())
  • on.select — the player selects it
  • on.idle — it has had nothing to do for a while
  • on.narration — a story beat with no speaker

Any gameplay event tag works too, and matching is hierarchical: a cue on combat also answers combat.hit.

Timing

Every cue carries its own timing, so lines behave rather than spam:

Setting Effect
Delay Wait before speaking — useful for a reaction.
Duration How long the line stays up.
Cooldown Minimum time between two firings of this cue.
Priority A stronger line interrupts a weaker one already showing.
Max times Cap the firings; 1 makes a line play once ever.

Three ways an action can talk

  1. Per phase — every Action Definition has a Dialogue block with lines for start, success, failure and blocked. One is picked at random.
  2. Mid-sequence — the SayEffect module speaks from anywhere in the effects list, so a line lands exactly after a resource is granted or a state flips.
  3. Reacting to events — a cue in the library answers any event an effect raises, without the action knowing dialogue exists.

Giving one AI its own voice

A Speech Profile is a character: a display name plus the libraries it draws from. Drop one on an actor's Speech Trigger and it speaks with that name and those lines. In the Dialogue window, drag an AI straight onto the binding card and its profile is created and wired for you.

An actor's profile is searched before the game-wide library, so personal lines and shared ones mix. For a single shared library, a cue's Only actors tagged field restricts who says it — actor.guard means only guards.

In your own game

Nothing above needs the template. Add a Speech Service, assign a library and a sink, then fire triggers from your own code over your own IActorContext:

speechService.Fire(SpeechTriggers.Spawn, myActor);
speechService.Narrate(new GameplayTag("story.act1"));

When nothing plays

Tick Log Dialogue on the Speech Service (or the Game Controller). Every trigger then reports what happened: no library set, no cue answers this trigger, cues matched but were held back by a speaker filter, cooldown or repeat limit, or how many lines played.

The Test in game button in the Dialogue window talks to the display directly, so it working while the game stays silent points at the scene wiring — open the Dashboard and check the Dialogue row.

Clone this wiki locally