> For the complete documentation index, see [llms.txt](https://ney.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ney.gitbook.io/docs/mythichud-extension/dialogues.md).

# Dialogues

MythicHUD Extension provides dialogue entries that use MythicHUD layouts instead of Typewriter's standard chat presentation.

### Overview

The extension provides three entry types:

| Dialogue type | Entry ID                       | Description                        |
| ------------- | ------------------------------ | ---------------------------------- |
| Spoken        | `mythichud_spoken`             | NPC dialogue and narration         |
| Option        | `mythichud_option`             | Dialogue with scroll-wheel choices |
| Cinematic     | `mythichud_dialogue_cinematic` | Timeline-driven dialogue segments  |

All dialogue types share the same basic setup process and work almost identically to their original Typewriter counterparts, but with additional functionality and custom variables.

***

### Creating a Dialogue

Every dialogue requires two components:

1. **A MythicHUD asset and layout** defining the appearance and position.
2. **A Typewriter dialogue entry** defining the content and behavior.

The extension adds the selected layout when the dialogue starts, updates it during the typewriter animation, and removes it when the dialogue ends.

***

### Step 1: Create a MythicHUD Asset

Create a YAML file under:

```
plugins/MythicHUD/hud_assets/hud/
```

The following asset displays a speaker and three dialogue lines:

```yaml
example-dialogue:
  layers:
    speaker:
      text: "<yellow>%typewriter_mythichud_speaker%"
      font: default
      align: right
      offset:
        x: 0
        y: 0

    text-line-1:
      text: "%typewriter_mythichud_text_line_1%"
      font: default
      align: right
      offset:
        x: 0
        y: -10

    text-line-2:
      text: "%typewriter_mythichud_text_line_2%"
      font: default
      align: right
      offset:
        x: 0
        y: -20

    text-line-3:
      text: "%typewriter_mythichud_text_line_3%"
      font: default
      align: right
      offset:
        x: 0
        y: -30
```

Dialogue text is automatically wrapped according to the `mythichud.dialogue.max_line_width` snippet.

***

### Step 2: Create a MythicHUD Layout

Create a YAML file under:

```
plugins/MythicHUD/layouts/
```

```yaml
example_dialogue:
  elements:
    dialogue:
      asset: example-dialogue
      align: center
      position:
        x: 50.0
        y: 50.0
      offset:
        x: 0
        y: 0
```

The top-level key, `example_dialogue`, is the value used in the Typewriter entry's `layoutId` field.

***

### Step 3: Configure Typewriter

1. Create and configure a Speaker entry.
2. Create `mythichud_spoken`, `mythichud_option`, or `mythichud_dialogue_cinematic`.
3. Select the speaker.
4. Enter the dialogue text.
5. Set `layoutId` to the MythicHUD layout key.
6. Configure sounds, triggers, modifiers.

You can test an entry with a Typewriter trigger command such as:

```
/tw trigger mythichud_spoken
```

***

### Spoken Dialogue

`mythichud_spoken` behaves like a standard Typewriter Spoken entry with MythicHUD rendering.

| Field             | Description                                                        | Default               |
| ----------------- | ------------------------------------------------------------------ | --------------------- |
| `speaker`         | Speaker entry used by the dialogue                                 | Empty                 |
| `text`            | Dialogue text; supports placeholders, MiniMessage, and line breaks | Empty                 |
| `duration`        | Typewriter animation duration                                      | 3 seconds             |
| `layoutId`        | MythicHUD layout to display                                        | `typewriter_dialogue` |
| `sound`           | Sound played when dialogue starts                                  | Empty                 |
| `typingSound`     | Replays the selected sound while characters appear                 | `false`               |
| `customVariables` | Custom values exposed to MythicHUD                                 | Empty                 |

***

### Option Dialogue

`mythichud_option` adds player choices. Players change the selected option with the scroll wheel.

| Field                   | Description                                        | Default                      |
| ----------------------- | -------------------------------------------------- | ---------------------------- |
| `speaker`               | Speaker entry used by the dialogue                 | Empty                        |
| `text`                  | Dialogue text displayed before the options         | Empty                        |
| `duration`              | Typewriter animation duration                      | 3 seconds                    |
| `layoutId`              | MythicHUD layout to display                        | `typewriter_dialogue_option` |
| `sound`                 | Sound played when dialogue starts                  | Empty                        |
| `typingSound`           | Replays the selected sound while characters appear | `false`                      |
| `disableInfiniteScroll` | Prevents wrapping from last option to first        | `false`                      |
| `options`               | Available dialogue choices                         | Empty                        |
| `customVariables`       | Custom values exposed to MythicHUD                 | Empty                        |

Create separate layers for `previous_option`, `selected_option`, and `next_option`. See Variables for alternative indexed option placeholders.

```yaml
previous-option:
  text: "%typewriter_mythichud_previous_option%"
  font: default
  align: right
  offset:
    x: 0
    y: 0
```

***

### Cinematic Dialogue

`mythichud_dialogue_cinematic` displays automatic dialogue segments on a Typewriter cinematic timeline.

The `cinematic.mythichud_dialogue.percentage` snippet controls how much of each segment is reserved for the typing animation.

***

### Delays

Dialogue text supports delay tags. The delay pauses the typewriter animation at its current character position:

```
Wait...<d:500> now continue.
```

The value is milliseconds. A value ending in `s` is interpreted as seconds:

```
This pauses for two seconds.<d:2s> Then continues.
```