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

Drop the jar in plugins/, start the server once, then stop it.
Look in plugins/MagDialogGUIs/guis/ — four example files were extracted for you: example.mg, nickname.mg, chat-colour.mg and settings-menu.mg.
Start the server again and run /example, /nickname, /chatcolour or /settings in-game.
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).

No gallery available for this project.

Version	Minecraft	Loader	Download
MagDialogGUIs 1.0.0 (26.2) 1.0.0-purpur-26.2	26.2	purpur	Download
MagDialogGUIs 1.0.0 (26.1.2) 1.0.0-purpur-26.1.2	26.1.2	purpur	Download
MagDialogGUIs 1.0.0 (26.1.1) 1.0.0-purpur-26.1.1	26.1.1	purpur	Download
MagDialogGUIs 1.0.0 (26.1) 1.0.0-purpur-26.1	26.1	purpur	Download
MagDialogGUIs 1.0.0 (26.2) 1.0.0-paper-26.2	26.2	paper	Download
MagDialogGUIs 1.0.0 (26.1.2) 1.0.0-paper-26.1.2	26.1.2	paper	Download
MagDialogGUIs 1.0.0 (26.1.1) 1.0.0-paper-26.1.1	26.1.1	paper	Download
MagDialogGUIs 1.0.0 (26.1) 1.0.0-paper-26.1	26.1	paper	Download
MagDialogGUIs 1.0.0 (1.21.11) 1.0.0-purpur-1.21.11	1.21.11	purpur	Download
MagDialogGUIs 1.0.0 (1.21.10) 1.0.0-purpur-1.21.10	1.21.10	purpur	Download
MagDialogGUIs 1.0.0 (1.21.9) 1.0.0-purpur-1.21.9	1.21.9	purpur	Download
MagDialogGUIs 1.0.0 (1.21.8) 1.0.0-purpur-1.21.8	1.21.8	purpur	Download
MagDialogGUIs 1.0.0 (1.21.7) 1.0.0-purpur-1.21.7	1.21.7	purpur	Download
MagDialogGUIs 1.0.0 (1.21.11) 1.0.0-paper-1.21.11	1.21.11	paper	Download
MagDialogGUIs 1.0.0 (1.21.10) 1.0.0-paper-1.21.10	1.21.10	paper	Download
MagDialogGUIs 1.0.0 (1.21.9) 1.0.0-paper-1.21.9	1.21.9	paper	Download
MagDialogGUIs 1.0.0 (1.21.8) 1.0.0-paper-1.21.8	1.21.8	paper	Download
MagDialogGUIs 1.0.0 (1.21.7) 1.0.0-paper-1.21.7	1.21.7	paper	Download

Mag GUIs

MagDialogGUIs

Quick start

`.mg` format

`command`

Body

Inputs

Actions

Placeholders

Cmds & perms

config.yml

Limitations

Available downloads

MagDialogGUIs

Quick start

.mg format

command

Body

Inputs

Actions

Placeholders

Cmds & perms

config.yml

Limitations

`.mg` format

`command`