MagDialogGUIs

A native Minecraft Dialog GUI framework for Paper and Purpur. Instead of building menus out of chest inventories, MagDialogGUIs uses Mojang's Dialog API (added in Minecraft 1.21.6, with Paper developer API since 1.21.7) to show players real, native dialog windows — with text fields, checkboxes, sliders, radio buttons and buttons that run commands.

Every dialog is defined in a simple YAML file (.mg) dropped into plugins/MagDialogGUIs/guis/. No coding required.

Supported: Paper and Purpur, Minecraft 1.21.7 through 26.2 (see Building below for how one source tree targets that whole range).

Quick start

1. Drop the jar in plugins/, start the server once, then stop it.
2. Look in plugins/MagDialogGUIs/guis/ — four example files were extracted for you: example.mg, nickname.mg, chat-colour.mg and settings-menu.mg.
3. Start the server again and run /example, /nickname, /chatcolour or /settings in-game.
4. Edit the .mg files, then run /magdialogguis reload.

.mg format

A .mg file is plain YAML. Top level keys:

Key	Type	Default	Description
name	string	filename	Internal identifier. Used by open: actions and /magdialogguis open.
title	string	name	MiniMessage. The dialog's title.
external-title	string	(none)	MiniMessage. Shown on buttons that link to this dialog, if you use those.
permission	string	(none)	Required to open this GUI, whether via command, /magdialogguis open, or an open: action.
escape	boolean	dialogs.default-escape in config.yml	Whether Escape closes the dialog.
columns	int	auto (1 or 2)	How many columns the action buttons are laid out in.
command	map	(none)	See below. Omit to make a GUI only reachable via open: or /magdialogguis open.
body	list	empty	See Body.
inputs	map	empty	See Inputs.
actions	map	empty (shows a single "Close" button)	See Actions.

Every text value (title, label, body text, action label/tooltip, etc.) is parsed as MiniMessage, so <red>, <bold>, <gradient:...> and friends all work. Every text value also has %placeholders% resolved first — see Placeholders.

command

command:
  name: example      # registers /example
  aliases:
    - testdialog      # and /testdialog

If a command with that name already exists, registration is skipped (and logged) unless commands.protect-existing: false in config.yml.

Body

A list of entries, each either a text message or an item icon.

body:
  - text: "<white>Welcome, <yellow>%player%</yellow>!"
    width: 300

  - type: item
    material: WRITABLE_BOOK       # any Bukkit Material name
    description: "<gray>An item can illustrate your dialog."
    width: 32
    height: 32
    show-decorations: true
    show-tooltip: true

Omitting type (or setting type: text) makes it a text entry.

Inputs

inputs: is a map from a key (used in %placeholders% and shown in DialogResponseView) to its definition. Four types are supported, matching Minecraft's own dialog input types exactly.

text — a text field.

inputs:
  NAME:
    type: text
    label: "<green>Your name"
    width: 300          # 1-1024
    max-length: 32
    initial: "%player%"
    label-visible: true

boolean — a checkbox.

inputs:
  AGREE:
    type: boolean
    label: "<green>I agree"
    initial: false
    on-true: "true"    # value substituted into %AGREE% when checked
    on-false: "false"  # value substituted into %AGREE% when unchecked

number — a slider.

inputs:
  LEVEL:
    type: number
    label: "<green>Level"
    min: 0
    max: 100
    step: 1              # omit for a continuous slider
    initial: 50
    label-format: "%s: %s"   # first %s = label, second = current value

option — a single-choice / radio input.

inputs:
  COLOUR:
    type: option
    label: "<green>Colour"
    width: 200
    label-visible: true
    options:
      - id: "red"
        display: "<red>Red"
        initial: false
      - id: "green"
        display: "<green>Green"
        initial: true     # at most one option may be initial

options also accepts a plain list of strings (- "red"), in which case the string is used as both the id and the display text.

Actions

actions: is a map from a button id to its definition. Each entry becomes one button on the dialog. If actions: is omitted entirely, the dialog gets a single default "Close" button (a notice-type dialog).

actions:
  submit:
    type: player            # see table below
    label: "<green>Submit"
    tooltip: "<gray>Optional hover text"
    width: 150
    command: "say Hello %NAME%"
    after: CLOSE             # CLOSE or NONE — defaults per type, see below

type	Payload key	What it does	Default after
player	command	Runs the command as the clicking player (leading / optional).	config default
console	command	Runs the command as console.	config default
message	message	Sends the player a chat message.	config default
open	gui	Closes this dialog and opens another GUI by name.	CLOSE
close	(none)	Just closes the dialog.	CLOSE
none	(none)	Does nothing — useful as a static/decorative button.	NONE

"config default" is dialogs.default-after-action in config.yml (CLOSE out of the box). Set after: on any action to override it.

Placeholders

Resolved in every text value before MiniMessage parsing:

• %player%, %uuid%, %world%, %x%, %y%, %z% — always available.
• %<input-key>% — every input's submitted value, available in actions: (booleans resolve to on-true/on-false, numbers are formatted plainly).
• Any %...% PlaceholderAPI placeholder, if PlaceholderAPI is installed and placeholders.papi: true in config.yml (the default).

Cmds & perms

Command	Permission	Description
/magdialogguis reload	magdialogguis.admin	Reloads config and every .mg file.
/magdialogguis list	magdialogguis.admin	Lists loaded GUIs.
/magdialogguis open <gui> [player]	magdialogguis.admin	Opens a GUI for yourself or another player.
Each GUI's own command: (if set)	that GUI's permission:	Opens that GUI.

config.yml

See the bundled config.yml for every option, including debug logging, strict validation (fail a .mg file on unknown types vs. skip just that entry), default escape/after-action behaviour, and message customisation.

Limitations

• Pressing Escape closes a dialog client-side with no server round-trip, so session tracking (/magdialogguis list style bookkeeping) doesn't observe it — only clicking a button, quitting, or opening another GUI updates it.
• Text inputs are always single-line; multiline text areas aren't exposed yet (the underlying API support for it varies across the supported version range).