> 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/variables.md).

# Variables

BetterHud Extension provides a comprehensive set of variables that you can use in your layouts to create dynamic and interactive dialogues. All variables are accessed using the `[custom_variable:variable_name]` placeholder format in your BetterHud layouts.

### Variable Naming Convention

Each variable is available in two formats:

* Short format: `variable_name` (e.g., `speaker`, `text`)
* Prefixed format: `typewriter_variable_name` (e.g., `typewriter_speaker`, `typewriter_text`)

Both formats work identically - use whichever naming convention you prefer or fits your existing setup better.

***

### Spoken Variables

These variables are available for both BetterHudSpoken and BetterHudDialogueCinematic entries.

#### Basic Variables

| Variable                         | Description                                               | Example Value                   |
| -------------------------------- | --------------------------------------------------------- | ------------------------------- |
| `speaker` / `typewriter_speaker` | The display name of the speaker                           | `"Guard"`, `"Mysterious Voice"` |
| `text` / `typewriter_text`       | The current visible dialogue text (with typing animation) | `"Hello, trav"`                 |
| `raw_text`                       | The complete dialogue text without animation              | `"Hello, traveler!"`            |

#### Animation & Progress

| Variable                                 | Description                                             | Example Value             |
| ---------------------------------------- | ------------------------------------------------------- | ------------------------- |
| `progress` / `typewriter_progress`       | Typing animation progress as integer percentage (0-100) | `"75"`                    |
| `percentage`                             | Typing animation progress as decimal (0.00-1.00)        | `"0.75"`                  |
| `is_complete`                            | Whether the typing animation has finished               | `"true"` / `"false"`      |
| `instruction` / `typewriter_instruction` | Current player instruction state                        | `"continue"` / `"finish"` |

***

### Option Variables

These variables are available for BetterHudOption entries. Option entries include all Spoken variables plus additional option-specific variables.

#### Option Selection

| Variable                                         | Description                                                     | Example Value        |
| ------------------------------------------------ | --------------------------------------------------------------- | -------------------- |
| `options_count` / `typewriter_options_count`     | Total number of available options                               | `"3"`                |
| `selected_index` / `typewriter_selected_index`   | Index of currently selected option (-1 if animation incomplete) | `"0"`, `"1"`, `"-1"` |
| `selected_option` / `typewriter_selected_option` | Text of the currently selected option                           | `"Accept the quest"` |
| `has_options`                                    | Whether any options are available                               | `"true"` / `"false"` |

#### Navigation

| Variable                                                                   | Description                               | Example Value            |
| -------------------------------------------------------------------------- | ----------------------------------------- | ------------------------ |
| `previous_option` / `typewriter_previous_option`                           | Text of the option above the selected one | `"Decline"`              |
| `next_option` / `typewriter_next_option`                                   | Text of the option below the selected one | `"Ask for more details"` |
| `previous_index` / `typewriter_previous_index`                             | Index of the previous option (-1 if none) | `"0"`, `"-1"`            |
| <p><code>next\_index</code> / <code>typewriter\_next\_index</code><br></p> | Index of the next option (-1 if none)     | `"2"`, `"-1"`            |

#### Individual Option Information

For each option in your dialogue, you can access specific information using indexed variables:

| Variable Pattern          | Description                               | Example Value        |
| ------------------------- | ----------------------------------------- | -------------------- |
| `option_{index}_text`     | Text of the option at specific index      | `"Accept the quest"` |
| `option_{index}_selected` | Whether this option is currently selected | `"true"` / `"false"` |

Example usage:

* `option_0_text` - Text of the first option
* `option_1_selected` - Whether the second option is selected

***

### Custom Variables

You can also define your own custom variables in the Typewriter entry settings. Custom variables support placeholders and are automatically available in both formats:

* `your_variable_name`
* `typewriter_your_variable_name`

This allows you to add dynamic content like player names, quest progress, or any other custom data to your dialogues.

***

### Usage Examples

#### Basic Spoken Layout

```yaml
speaker:
  pattern: "<yellow>[custom_variable:speaker]"
text:
  pattern: "<white>[custom_variable:text]"
```

#### Progress Indicator

```yaml
progress_bar:
  pattern: "Progress: [custom_variable:progress]%"
completion_status:
  pattern: "Complete: [custom_variable:is_complete]"
```

Combining variables with BetterHud conditions allows you to create unique dialogue systems that are tailored to your server's needs.