# 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:quests) guide.

## Turn it on

```text
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

<!-- test: kits/game_engine/host/tests/parity.rs::rust_host_matches_the_typescript_traces (fixture dialogue.voice.playback) -->
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.

```json
{ "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.