> 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/betterhud-extension/dialogues.md).

# Dialogues

BetterHud Extension provides dialogue entries that use BetterHud popups instead of Typewriter's standard chat presentation.

### Overview

The extension provides three entry types:

| Dialogue type | Entry ID                       | Description                        |
| ------------- | ------------------------------ | ---------------------------------- |
| Spoken        | `betterhud_spoken`             | NPC dialogue and narration         |
| Option        | `betterhud_option`             | Dialogue with scroll-wheel choices |
| Cinematic     | `betterhud_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 three components:

1. **A BetterHud layout** defining the appearance and position.
2. **A BetterHud popup** displaying the layout.
3. **A Typewriter dialogue entry** defining the content and behavior.

The extension opens the selected popup when the dialogue starts, updates its custom variables during the typewriter animation, and removes it when the dialogue ends.

***

#### Step 1: Create a BetterHud Layout

First, create a layout file in BetterHud's `layouts` folder. This defines the visual appearance of your dialogue.

We'll create a basic layout with 2 text elements: `speaker` for the speaker's name and `text` for the dialogue text.

```yaml
example_dialogue:
  texts:
    speaker:
      name: dialogue
      pattern: "[custom_variable:speaker]"
      align: left
      x: 0
      y: 0
      space: 0
      scale: 0.5
      color: "white"
      outline: true
      layer: 2
    text:
      name: dialogue
      pattern: |
        [custom_variable:typewriter_text]
      line: 6
      line-align: left
      split-width: 166
      line-width: 10
      align: left
      x: 0
      y: 10
      space: 0
      scale: 0.5
      color: "white"
      outline: true
      layer: 2
```

*This layout structure works for all dialogue types. For Option dialogues, you'll use additional* [Variables](/docs/betterhud-extension/variables.md)

I won't explain exactly how everything works here, as I expect you're already familiar with BetterHud. However, I'll explain what `[custom_variable:*]` does - BetterHud has its own placeholder system, and through its API we can add our own custom placeholders.

**You can view the full list of all available placeholders here:** [Variables](/docs/betterhud-extension/variables.md)

#### Step 2: Create a BetterHud Popup

Now that we have a layout, we need to define a popup for it. The popup controls layout behavior, position, and other important properties.

```yaml
spoken:
  layouts:
    1:
      name: example_dialogue
      gui:
        x: 50
        y: 100
      pixel:
        x: 0
        y: -140
```

*Use the same popup structure for all dialogue types.*

#### Step 3: Link Everything Together

Now that we've configured BetterHud, we can move to Typewriter and link everything together.

First, create a `SimpleSpeaker` (or any other Speaker type) and configure it. After that, create a `BetterHudSpoken` entry. Then configure the basic fields. Here's how your entry should look:

<figure><img src="https://4256033447-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOOK4vSXnoZV5vcomvELY%2Fuploads%2FEAZYdGhyt45WmxlnOxN6%2Fbetterhud_spoken_1.png?alt=media&amp;token=048cf7fc-d416-46dc-9547-7232c16ce16a" alt="" width="216"><figcaption></figcaption></figure>

Now after everything is set up, we can test how it looks in-game using `/tw trigger betterhud_spoken`

<figure><img src="https://4256033447-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOOK4vSXnoZV5vcomvELY%2Fuploads%2FAi1LpcZuxgyjlYwrl6EB%2Fbetterhud_spoken_2.png?alt=media&amp;token=56920654-9202-433f-a94e-926a538d1964" alt="" width="563"><figcaption></figcaption></figure>

***

### Dialogue Types

Now that you understand the basic setup, let's explore each dialogue type and their unique features.

#### Spoken

The most basic and common dialogue type.

Works almost identically to the standard Typewriter Spoken entry, with additional features like sound effects, typing sounds, and custom variables. After reading to this point you'll probably understand how everything works, so there's not much more to describe here.

***

#### Option

With BetterHud Extension, Option dialogues greatly evolve and the only limit is your imagination. I'll provide a very simple and basic setup, but you can make almost any option system from any game you want.

Here's an example layout for options to work:

```yaml
example_option_dialogue:
  texts:
    speaker:
      name: dialogue
      pattern: "[custom_variable:speaker]"
      align: left
      x: 0
      y: 0
      space: 0
      scale: 0.5
      color: "white"
      outline: true
      layer: 2
    text:
      name: dialogue
      pattern: |
        [custom_variable:typewriter_text]
      line: 6
      line-align: left
      split-width: 166
      line-width: 10
      align: left
      x: 0
      y: 10
      space: 0
      scale: 0.5
      color: "white"
      outline: true
      layer: 2
    options:
      name: dialogue
      pattern: |
        <white>[custom_variable:previous_option]
        <green>[custom_variable:selected_option]
        <white>[custom_variable:next_option]
      line: 3
      line-align: right
      split-width: 166
      line-width: 10
      align: right
      x: 50
      y: -30
      space: 0
      scale: 0.5
      color: "white"
      outline: true
      layer: 2
```

With this layout you can configure your entry and try everything in-game. To scroll through options use the **scroll wheel**.

***

#### Cinematic

This is basically a Spoken dialogue but with a few changes for automated cinematic sequences.

\[ Coming soon... ]

***

### 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.
```