Voices and lips

Usage guide of dialogue.voice: recorded voices with lip sync driven by the audio clock, rigs, settings and defaults, service, events and the voice.play hook.

Source: module-kits:kits/dialogue_voice/usage/en.mdView Markdown source

Also read offline — CLI: grip-forge docs dialogue-voiceMCP tool: gripforge_docs { "topic": "dialogue-voice" }

Voiced dialogue and lip sync (dialogue.voice) #

What it is for #

Pre-generated character voices with lip sync driven by the real audio playback clock. The kit follows the lines shown by npc.dialogue or plays an authored clip on any character, with one recording per language, rig mappings, interruption and offline playback. Nothing is generated while a game runs. It belongs to the quests and dialogue family: see the Quests, missions and dialogue guide.

Turn it on #

gripforge_gamekit_install   { project_id: "gkp_…", id: "dialogue.voice" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "dialogue.voice",
                              config: { "followDialogue": true, "volume": 1 } }

Needs audio.core, npc.dialogue, game.engine; installing the kit brings them along.

First example #

A character with a rig says a line; the recording names the mouth shape at each instant. While the sound plays, poses() returns the weights to blend on the character, read from the audio device clock.

{ "dialogue_voices": [{ "id": "hello_en", "dialogue": "elder", "line": 0, "language": "en", "text": "Hello.",
    "sound": "speech", "duration": 1.2,
    "cues": [{ "start": 0, "end": 0.4, "value": "X" }, { "start": 0.4, "end": 0.8, "value": "C" }] }],
  "voice_rigs": [{ "id": "face", "morphs": [{ "cue": "C", "target": "mouth_open" }] }] }

The character carries the component voice: { "rig": "face" }.

Settings and defaults #

Setting	Default	Meaning
`enabled`	`true`	Turns the kit on or off.
`followDialogue`	`true`	Plays the recording of each line shown by `npc.dialogue`.
`loadTimeoutSeconds`	20	Seconds to wait for a sound to load (1 to 120).
`volume`	1	Volume of the voices (0 to 1).
`blendSeconds`	0.04	Smoothing between two mouth shapes, in seconds (0 to 0.2).

Collections: dialogue_voices (the recordings: dialogue, line, language, text, sound, duration, cues), voice_rigs (cue to morph target, and an optional jaw bone), voice_cast and dialogue_voice_directions (casting and acting directions kept for offline generation). Mouth shapes are A to H and X (rest).

Services, events, variables #

Service dialogue.voice: play(entity, clip), stop(entity, reason), active(entity?), poses() (a list of { entity, weights, jaw }).
Events: voice.queued, voice.started, voice.ended (entity, clip, reason), voice.missing (entity, dialogue, line, language). It listens to dialogue.ended, entity.despawned, engine.scene.leaving.
Variables: voice.active (speaking characters).

Hooks and modding #

Hook	Meaning
`voice.play`	A character is about to start an authored clip; `volume` is mutable; cancelled, nothing plays.

Moddable: every setting and the collections dialogue_voices, voice_rigs, voice_cast, dialogue_voice_directions; recordings and rigs can be swapped while the game runs.

Limits #

A recording is bound to the exact translated text: when the text changes, the stale clip is not played. Without a recording the subtitles and choices carry on and one voice.missing is emitted per line. When the dialogue pauses the world, turn on voiceDuringPause in audio.core. Runs on the web player and the native player; Godot, Unity and Unreal have no native delivery of this kit.

Versions #

Kit 1.2.0; service dialogue.voice 1.1.0. It relies on audio.core ^1.1, dialogue.lines ^1.1 (from npc.dialogue) and game.engine ^1.