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

# menu types

DialogMaster supports four distinct dialog types natively rendered by the client. Set these via the `type:` property inside a menu's YAML file.

***

## Menu File Structure

Each menu lives in its own `.yml` file inside `plugins/DialogMaster/menus/`. The file must contain a top-level key that matches the filename (without `.yml`):

```yaml
# File: menus/my-menu.yml
my-menu:
  title: "..."
  type: ...
```

### Default field values

These fields are optional — if omitted, they use the defaults shown:

| Field              | Default  | Notes                                                |
| ------------------ | -------- | ---------------------------------------------------- |
| `can-close-escape` | `true`   | Whether Escape closes the dialog                     |
| `after-action`     | `CLOSE`  | What happens after a button is clicked               |
| `columns`          | `1`      | Grid columns (multiAction only)                      |
| `command`          | *(none)* | Optional slash command that opens this menu directly |

### Per-menu commands

Any menu can register its own slash command by adding a `command:` field. The plugin registers it dynamically on startup and on `/ydm reload` — no plugin.yml entry needed.

```yaml
leaderboard-hub:
  title: "<gold><bold>🏆 Leaderboards"
  type: multiAction
  command: "/leaderboards"   # Players can now run /leaderboards to open this menu
  ...
```

The leading `/` is optional. The command requires the `dialogmaster.open` permission, same as `/menu`.

***

{% stepper %}
{% step %}

## Notice Type (`notice`)

An informational prompt with a title, body, and a single OK button.

```yaml
my-notice:
  title: "<yellow>Announcement"
  type: notice
  body:
    - type: plain-message
      content: "<gray>Maintenance will begin in 10 minutes!"
      width: 250
  ok-button:
    label: "Understood"
    width: 100
    action: close
```

{% endstep %}

{% step %}

## Confirmation Type (`confirmation`)

A binary decision screen with a confirm and a deny button. Used for purchases, rules gates, and destructive actions.

```yaml
my-confirm:
  title: "<red>Confirm Purchase"
  type: confirmation
  body:
    - type: plain-message
      content: "<gray>This costs <gold>$100<gray>."
  confirm-button:
    label: "<green>Confirm"
    width: 120
    action: static-run-command
    command: "/buy item"
    action-key: "dm:confirm"
  deny-button:
    label: "<gray>Cancel"
    width: 100
    action: close
    action-key: "dm:cancel"
```

{% endstep %}

{% step %}

## Multi-Action Type (`multiAction`)

A grid of custom buttons. Used for navigators, game selectors, and settings hubs.

```yaml
my-hub:
  title: "<aqua>Server Menu"
  type: multiAction
  columns: 2
  body:
    - type: plain-message
      content: "<gray>Choose a destination."
  buttons:
    - label: "<green>Spawn"
      width: 150
      action: static-run-command
      command: "/spawn"
    - label: "<red>PvP Arena"
      width: 150
      action: static-run-command
      command: "/warp pvp"
```

### Footer buttons

Use `footer-buttons` to pin buttons at the bottom of the grid (e.g. a Back button) separately from the main `buttons` list:

```yaml
  footer-buttons:
    - label: "<gray>← Back"
      width: 100
      action: back
      action-key: "dm:back"
```

{% endstep %}

{% step %}

## Server Links Type (`serverlinks`)

Displays the server links registered in `config.yml` under `server-links.links`.

```yaml
server-links-menu:
  title: "<gold><bold>Server Links"
  type: serverlinks
  columns: 2
  ok-button:
    label: "<gray>Close"
    width: 100
    action: close
```

{% endstep %}
{% endstepper %}

## Item Icons in Labels

Any text field that supports MiniMessage (button labels, tooltips, body content, titles) can display a vanilla Minecraft item icon using the `<item:material_name>` tag:

```yaml
buttons:
  - label: "<item:gold_ingot> <gold>Money"
  - label: "<item:iron_sword> <red>Kills"
  - label: "<item:clock> <aqua>Playtime"
  - label: "<item:oak_door> <gray>← Back"
```

The icon renders client-side using Minecraft's built-in item atlas — **no resource pack required**. The tag is resolved before MiniMessage parsing, so it works everywhere: button labels, tooltips, body text, stats lines, leaderboard entries, anything.

Material names are the standard Bukkit/Minecraft snake\_case names (e.g. `diamond_pickaxe`, `ender_pearl`, `grass_block`). You can find the full list at [minecraft.wiki/w/Java\_Edition\_data\_values/Items](https://minecraft.wiki/w/Java_Edition_data_values/Items).

{% hint style="info" %}
**Version note:** The sprite atlas used (`minecraft:items`) is correct for Minecraft 1.21.11+. Earlier 1.21.x builds (1.21.9–1.21.10) used `minecraft:blocks` for some items. DialogMaster targets 1.21.11+.
{% endhint %}

| Action               | Description                                            | Required fields                   |
| -------------------- | ------------------------------------------------------ | --------------------------------- |
| `open-menu`          | Navigate to another menu                               | `target: <menu-id>`               |
| `open-lb`            | Open a leaderboard dialog                              | `target: <leaderboard-id>`        |
| `back`               | Go to the previous menu (or close if none)             | —                                 |
| `close`              | Close the dialog immediately                           | —                                 |
| `static-run-command` | Run a command as the player (no inputs)                | `command: "/cmd"`                 |
| `static-open-url`    | Open a URL in the browser                              | `target: "https://..."`           |
| `static-copy`        | Copy text to clipboard                                 | `target: "text"`                  |
| `static-suggest`     | Pre-fill the chat bar                                  | `command: "/cmd "`                |
| `command-template`   | Run a command with `$(key)` input substitution         | `command-template: "/cmd $(key)"` |
| `custom-click`       | Fire a custom event key for other plugins to listen to | `action-key: "ns:key"`            |

### Sounds on buttons

Add `action-key` to any button and define a matching entry under `sounds:` in `config.yml` to play a sound when that button is clicked:

```yaml
    action-key: "dm:confirm"    # Must match a key under sounds: in config.yml
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://yowsef-development.gitbook.io/yowsef-development-docs/menus/menu-types.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.