BetterDialogs

Code Download

This is an addon for those who want to work with the new Dialog System, in BetterGUI’s style.

Requirement

Your server must meet one of the following requirements:

  • Is a PaperMC server in 1.21.7 or higher
  • Is a SpigotMC server in 1.21.6 or higher (Make sure to use the latest build)
  • Have installed PacketEvents

Limitation

  • SpigotMC: Does not support Item Body
  • PacketEvents: Item Body only displays the material and no components (See the pull request)

Getting Started

Subsections of BetterDialogs

Menu

Format

menu-settings:
  # The menu type of the dialog
  menu-type: action-dialog

  # The title of the dialog
  title: "Dialog Title"

  # Whether the menu will be closed when the player clicks a button
  can-close-with-action: true

  # The action to perform after the player clicks a button
  after-action: CLOSE

  # The actions when the player opens the dialog
  open-action:
  - action
  - action
  - action

  # The requirement before the player can open the dialog
  view-requirement:
    <requirement-set>
    <requirement-set>
    <requirement-set>
    ...

  # The permission required to open the dialog
  permission: bettergui.test

  # The command to open the dialog
  command:
  - command1
  - command2
  ...

  # The list of argument processors to process the arguments of the command to open the dialog
  argument-processor:
    <argument-processor>
    <argument-processor>

The type of the dialog

Available values:

  • confirmation-dialog: A confirmation dialog with 2 buttons
  • action-dialog: A dialog with multiple buttons
  • notice-dialog: A notice dialog with a single button
  • server-links-dialog: A dialog used to display server link
menu-settings:
  menu-type: server-links-dialog
menu-settings:
  menu-type: confirmation-dialog

can-close-with-action

Whether the menu will be closed when the player clicks a button

Available values:

  • true: The menu will be closed when the player clicks a button
  • false: The menu will not be closed when the player clicks a button
menu-settings:
  menu-type: confirmation-dialog
  can-close-with-action: true

after-action

The action to perform after the player clicks a button

Available values:

  • CLOSE: Close the menu
  • NONE: Do nothing
  • WAIT_FOR_RESPONSE: Wait for the server’s response
menu-settings:
  menu-type: confirmation-dialog
  after-action: CLOSE
menu-settings:
  menu-type: confirmation-dialog
  after-action: NONE

columns

The number of columns in the dialog

Only works when the menu-type is action-dialog or server-links-dialog

menu-settings:
  menu-type: action-dialog
  columns: 3

button-width

The width of the buttons in the dialog

Only works when the menu-type is server-links-dialog

menu-settings:
  menu-type: server-links-dialog
  button-width: 10

Example

menu-settings:
  menu-type: confirmation-dialog
  title: "&c&lTest Dialog for &e&lBetterDialogs"
  command: testconfirmdialog

welcome:
  text: "&7Hello, &e{player}"
  width: 100

text-body:
  text: "&fThis is a demo for for &e&lBetterDialogs"

item:
  type: item
  material: DIAMOND_SWORD
  name: "&e&lDiamond Sword"
  lore:
    - "&7This is a diamond sword."
    - "&7It's very sharp."
    - "&b&lClick to open the dialog."
  enchant:
    - "durability, 1"
  description:
    text: "&7This is a diamond sword. It's very sharp."

name:
  type: input
  label: "&aEnter your name"
  initial: "{player}"

male:
  type: "boolean"
  label: "&6Are you male?"
  on-true: "Male"
  on-false: "Female"

number:
  type: number
  label: "&bChoose a number"
  start: 0
  end: 100
  step: 1
  initial: 50

select:
  type: select
  label: "&cWhat do you prefer?"
  options:
    tea: "&eTea"
    coffee: "&eCoffee"
    water: "&eWater"
  initial: "tea"

yes:
  type: action
  label: "&e&lYes"
  command:
    - "tell: &eName: &f{dialog_name}"
    - "tell: &eGender: &f{dialog_male}"
    - "tell: &eNumber: &f{dialog_number}"
    - "tell: &eSelection: &f{dialog_select:display} &7({dialog_select})"

no:
  type: action
  label: "&c&lNo"
  command: "tell: &cNevermind"

example example

[!NOTE] The lines below menu-settings are called Component. Those are the pieces of the body of the dialog. Continue to the next section for more information about the dialog components.

Component

Documentation of the various components of a dialog

Subsections of Component

Text

This is a component to display text content.

Format

text-component-name:
  # The type of the component.
  type: text
  # The text to display.
  text: "Hello, world!"
  # The width of the component in pixels.
  # Optional and defaults to 150.
  width: 150

Example

menu-settings:
  menu-type: notice-dialog
  title: "Example Dialog"
  command: exampledialog

show-name:
  type: text
  text: "&e&lHello, &b{player}&r!"

show-info:
  type: text
  text: "&e&lWelcome to our server!"

Example Example

Item

This is a component to display an item in a dialog, with an optional text description.

Format

item-component-name:
  type: item

  # The description of the item
  # Optional. If not provided, the item will not have a description.
  description:
    # The text to display as the description of the item.
    text: "Item description"
    # The width of the description text in pixels.
    width: 150

  # Whether to show decorations
  show-decorations: true

  # Whether to show tooltip when hovering over the item.
  show-tooltip: true

  # The width of the item in pixels.
  width: 150

  # The height of the item in pixels.
  height: 150

  # The Item modifiers
  modifier1: value1
  modifier2: value2
  modifier3: value3

Example

menu-settings:
  menu-type: notice-dialog
  title: "Example Dialog"
  command: exampledialog

one-item:
  type: item
  description:
    text: "&bThis is a stone"
    width: 500

  id: stone
  name: "Stone"
  lore:
    - "A simple stone"
    - "Used for building"

item-no-description:
  type: item
  id: cobblestone
  name: "Cobblestone"
  lore:
    - "A simple stone"
    - "Used for building"

Example Example

Input

This is a component for inputs from the player. It allows the player to interact with the dialog and provide user input so that the dialog can send the information to the server.

The next sections will provide more information about each type of input component.

Get Input Value

For each input, you can retrieve the value using the {dialog_<name>} variable, where <name> is the name of the input component.

For example, if you have an dialog with an input component like this:

menu-settings:
  menu-type: notice-dialog
  title: "Example Dialog"
  command: exampledialog

name:
  type: input
  label: "Name"

hello:
  type: action
  command: "tell: &b&lHello, &f&l{dialog_name}"

You can retrieve the value of the name component using the {dialog_name} variable, as shown in the hello action.

Subsections of Input

Text

This is an input component that allows players to enter text.

Format

text-input-name:
  # The type of the input component.
  type: input

  # The label of the input component.
  # If not provided, the label will be hidden.
  label: "Text Input"

  # The width of the input component.
  # If not provided, the width will be 200px.
  width: 200

  # The initial value of the input component.
  # If not provided, the initial value will be empty.
  initial: "Hello World"

  # The maximum length of the input component.
  # If not provided, the length will be 32.
  max-length: 32

  # The maximum number of lines the input component can have.
  # Optional.
  max-lines: 5

  # The height of the input component.
  # Optional.
  height: 100

Example

menu-settings:
  menu-type: notice-dialog
  title: "Example Dialog"
  command: exampledialog

name:
  type: input
  label: "Name"

hello:
  type: action
  command: "tell: &b&lHello, &f&l{dialog_name}"

Example Example

Checkbox

This is an input component that allows players to check a box.

Format

checkbox-input-name:
  # The type of the input component
  type: checkbox

  # The label of the input component
  label: Checkbox Label

  # The initial state of the checkbox
  # If not specified, the checkbox will be unchecked by default
  initial: false

  # The value of the checkbox when checked
  # If not specified, the value will be "true"
  on-true: "Checked"

  # The value of the checkbox when unchecked
  # If not specified, the value will be "false"
  on-false: "Unchecked"

Example

menu-settings:
  menu-type: notice-dialog
  title: "Example Dialog"
  command: exampledialog

gender:
  type: checkbox
  label: "Are you male?"
  on-true: "Male"
  on-false: "Female"

hello:
  type: action
  command: "tell: &b&lYour gender is &f&l{dialog_gender}"

Example Example

Slider

This is an input component that allows players to select a value within a specified range using a slider.

Format

slider-input-component:
  # The type of the input component.
  type: slider

  # The label for the input component.
  label: "Slider Label"

  # The format for the label.
  # If not specified, the label will be displayed as is.
  label-format: "options.generic_value"

  # The start value of the slider.
  start: 0

  # The end value of the slider.
  end: 100

  # The step value of the slider.
  # If not specified, the step will be calculated automatically based on the range.
  step: 1

  # The initial value of the slider.
  # If not specified, the initial value will be at the start of the range.
  initial: 50

Value Format

You can define the display format for the slider value when using the variable by following the variable format {dialog_<variable_name>:<format>}

Example

menu-settings:
  menu-type: notice-dialog
  title: "Example Dialog"
  command: exampledialog

age:
  type: slider
  label: "Age"
  start: 0
  end: 100
  step: 1
  initial: 18

hello:
  type: action
  command:
    - "tell: &b&lYour age is &f&l{dialog_age}"
    - "tell: &b&lYour age is &f&l{dialog_age:000}"

Example Example

Select

This is an input component that allows the player to select an option from a list.

Format

select-input-name:
  # The type of the input component.
  type: select

  # The label of the input component.
  # If not specified, the label will be hidden
  label: "Select an option"

  # The width of the input component.
  # If not specified, the width will be 200 pixels.
  width: 200

  # The available options for the input component.
  # Each option is a key-value pair, where the key is the option's value and the value is the option's label.
  options:
    option1: "Option 1"
    option2: "Option 2"
    option3: "Option 3"

  # The key of the initial option for the input component.
  # If not specified, the first option will be selected by default.
  initial: option1

Variable

When you use the {dialog_<name>} variable, it will return the key of the selected option.

If you want to get the label of the selected option, you can use the {dialog_<name>:display} variable.

Example

menu-settings:
  menu-type: notice-dialog
  title: "Example Dialog"
  command: exampledialog

experience:
  type: select
  label: "&eYour Experience with the game"
  width: 300
  options:
    beginner: "&aBeginner"
    intermediate: "&eIntermediate"
    advanced: "&6Advanced"
    expert: "&cExpert"
  initial: beginner

hello:
  type: action
  command:
    - "tell: &bYour selected experience is &f{dialog_experience}"
    - "tell: &bYour selected experience is &f{dialog_experience:display}"

Example Example

Action

This is a button component, one that can be used to perform an action when clicked.

Common Format

action-name:
  # The label of the button
  label: "Click me!"

  # The tooltip of the button
  # If the tooltip is not provided, there will be no tooltip
  tooltip: "This is a tooltip"

  # The width of the button
  # If the width is not provided, it will default to 150
  width: 150

Button Types

Copy To Clipboard

This button copies the specified text to the clipboard.

Format

action-name:
  # The type of the button
  type: copy

  # The text to copy to the clipboard
  text: "Hello, world!"

Example

copy-command:
  type: copy
  label: "Click here to copy a command"
  tooltip: "Copy the command to your clipboard"
  text: "/kill {player}"

Open URL

This button will prompt the player to open a URL.

Format

action-name:
  # The type of the button
  type: url

  # The URL to open
  url: "https://example.com"

Example

open-url:
  type: url
  label: "Click here to open a URL"
  tooltip: "Open a URL in your browser"
  url: "https://bettergui-mc.github.io/Docs/"

Suggest Command

This button will suggest a command to the player.

Format

action-name:
  # The type of the button
  type: suggest

  # The command to suggest
  command: "/kill {player}"

Example

suggest-command:
  type: suggest
  label: "Click here to suggest a command"
  tooltip: "Suggest a command to your player"
  command: "/kill {player}"

Run Command

This button will control the player to execute a command.

Format

action-name:
  # The type of the button
  type: run

  # The command to execute
  command: "/kill {player}"

Example

run-command:
  type: run
  label: "Click here to run a command"
  tooltip: "Run a command on your player"
  command: "/kill {player}"

Custom Action

This button will execute custom actions on the server.

Format

action-name:
  # The type of the button
  type: action

  # The list of actions to execute
  command:
  - action1
  - action2

  # The requirement to check when clicking the button
  click-requirement:
    <requirement-set>
    <requirement-set>
    <requirement-set>

Check Action for more information about the available actions in command.

Check Requirement for more information about the available requirements in click-requirement.

Example

action-custom:
  type: action
  label: "Click here to execute custom actions"
  tooltip: "Execute custom actions on your player"
  command:
  - "tell: &aYou met the requirement"
  - "tell: &aHere is your reward"
  - "console: give {player} diamond 64"
  click-requirement:
    check-level:
      level:
        value: 10
        take: false
      fail-action: "tell: &cYou don't have enough level"

Full Example

menu-settings:
  menu-type: action-dialog
  title: "Example Dialog"
  command: exampledialog

copy-command:
  type: copy
  label: "Click here to copy a command"
  text: "/kill {player}"

open-url:
  type: url
  label: "Click here to open a URL"
  tooltip: "Open a URL in your browser"
  url: "https://bettergui-mc.github.io/Docs/"

suggest-command:
  type: suggest
  label: "Click here to suggest a command"
  tooltip: "Suggest a command to your player"
  command: "/kill {player}"

run-command:
  type: run
  label: "Click here to run a command"
  tooltip: "Run a command on your player"
  command: "/kill {player}"

action-custom:
  type: action
  label: "Click here to execute custom actions"
  tooltip: "Execute custom actions on your player"
  command:
    - "tell: &aYou met the requirement"
    - "tell: &aHere is your reward"
    - "console: give {player} diamond 64"
  click-requirement:
    check-level:
      level:
        value: 10
        take: false
      fail-action: "tell: &cYou don't have enough level"

Example Example

Adventure Component

For some components that display Text (label, title, etc.), there are variants that can be used for advanced purposes.

This page will provide the possible ways to use the Adventure Component.

MiniMessage

Support: PaperMC

You can use MiniMessage to format text in your components by wrapping the key option in either the prefix mini- or the postfix $. For example:

  • title will be mini-title or title$
  • label will be mini-label or label$
name:
  type: text
  text$: "Hello <rainbow>world</rainbow>, isn't <blue><u><click:open_url:'https://docs.advntr.dev/minimessage'>MiniMessage</click></u></blue> fun?"

MiniPlaceholders

You can use the placeholders provided by MiniPlaceholders to display dynamic information in your components.

ping:
  type: text
  text$: "<player_name>: <player_ping>"

JSON

Support: PaperMC, PacketEvents

You can use JSON to format text in your components by wrapping the key option in either the prefix json-. For example:

  • title will be json-title
  • label will be json-label
json:
  type: text
  json-text: '["",{"text":"Welcome "},{"text":"to","italic":true},{"text":" BetterDialogs","bold":true,"color":"yellow"}]'

Example

menu-settings:
  menu-type: notice-dialog
  title: "Example Dialog"
  command: exampledialog

name:
  type: text
  text$: "Hello <rainbow>world</rainbow>, isn't <blue><u><click:open_url:'https://docs.advntr.dev/minimessage'>MiniMessage</click></u></blue> fun?"

ping:
  type: text
  text$: "<player_name>: <player_ping>"

json:
  type: text
  json-text: '["",{"text":"Welcome "},{"text":"to","italic":true},{"text":" BetterDialogs","bold":true,"color":"yellow"}]'

Example Example