Minecraft's dialog screens (the real menus the client draws since 1.21.6: text, items, text boxes, dropdowns, switches, sliders and buttons), written in YAML and driven from Java. One plugin that every other plugin can build its menus on.
- Server owners write dialogs in
plugins/DialogEngine/dialogs/and give them commands, permissions, conditions, lists and actions. No code. - Developers ship dialogs with their plugin, add their own actions, placeholders and lists, and hear every press of a YAML dialog's buttons as an event.
Runs on Spigot, Paper or Folia 1.21.7 or newer, one jar for all three, with players on a 1.21.6+ client. PlaceholderAPI is optional.
Download the jar from
SpigotMC, drop it in
plugins/ and restart. The first start writes config.yml, the sample
dialogs and AI-GUIDE.md into plugins/DialogEngine/.
Two things talk to the internet, and both can be turned off in config.yml:
update-check asks SpigotMC for the latest version, and telemetry sends an
anonymous count (a random id, the number of players online and the names of
plugins that depend on Dialog Engine) every 30 seconds. Drawn dialogs are the
third: /de edit, and a drawn dialog whose dialog.yml was edited by hand,
send that one dialog to the editor at edit.url to be drawn. Plain YAML
dialogs never leave the server.
| Command | Permission | |
|---|---|---|
/de list |
Every dialog, by namespace, with its command | dialogengine.list |
/de open <id> [player] [key=value ...] |
Open one, with values | dialogengine.open |
/de info <id> |
What a dialog is made of | dialogengine.info |
/de edit <id> |
Draw one in the browser editor, or make a new one | dialogengine.edit |
/de pack |
Write the drawn dialogs' resource pack to a file | dialogengine.pack |
/de reload |
Read everything again, and say what is wrong | dialogengine.reload |
/dialogengine and /dialogs are the same command.
Every node is op-only by default.
| Node | Allows |
|---|---|
dialogengine.list |
/de list |
dialogengine.open |
/de open on yourself. It opens any dialog, whatever permission: the dialog asks for |
dialogengine.open.others |
/de open <id> <player> on somebody else, on top of dialogengine.open |
dialogengine.info |
/de info |
dialogengine.edit |
/de edit. Pressing Send in the editor writes files into the server's dialog folder |
dialogengine.pack |
/de pack |
dialogengine.reload |
/de reload |
dialogengine.pack.notify |
Being told the address players download the drawn dialogs' pack from, when it fails to load for you |
dialogengine.samples |
Opening the sample dialogs |
dialogengine.update |
Being told on joining that a newer Dialog Engine is out |
dialogengine.admin |
All of the above, in one node |
A dialog's own permission: (who may open it with its command) and a
button's are whatever node you write there; Dialog Engine declares none of
them.
On the first start the plugin writes ten sample dialogs into
plugins/DialogEngine/dialogs/samples/, one file each: a welcome notice,
server rules, a shop, kits, warps, a player list, a profile, a report form and
a settings page, plus a menu of them all. Open the menu with
/dialog-samples. Only ops (dialogengine.samples) can open them. Set
samples: false in config.yml and they are never written.
Two more are drawn dialogs, shown with a resource pack, in
plugins/DialogEngine/drawn/samples/: a punishment panel
(/sample-punish <player>) and a six-page Social settings menu
(/sample-social). /de edit samples:punish opens one in the editor. Their
pack is sent when a player opens one, never on join, so the samples alone never
ask anybody to download anything.
In the browser: /de edit <namespace:id> draws a dialog in Studio's dialog
editor (no account), a new one or a drawn one you made there before, and Send
to server writes it into drawn/<namespace>/<id>/. A YAML dialog is edited in
its file, not in the browser. edit.url in config.yml says where the editor is, and must
be https (plain http only for one on the same machine).
With an AI: hand it plugins/DialogEngine/AI-GUIDE.md, which the plugin
writes on every start. It is this section plus the rules that catch the usual
mistakes.
Every folder in dialogs/ is a namespace, and every key in a .yml file in
it is a dialog: welcome in dialogs/samples/menus.yml is
samples:welcome. Files sitting directly in dialogs/ are in the namespace
server. Text is MiniMessage.
shop:
command: shop # /shop opens it (optional)
aliases: [store]
permission: myserver.shop # who may open it themselves (optional)
title: "<gold><bold>Shop"
columns: 2 # buttons side by side
escape: true # Escape closes it (default true)
after: seamless # seamless | wait | close | none, see config.yml
body:
- "<gray>You have <white>%vault_eco_balance%</white> coins." # text
- item: diamond # an item, with words beside it
name: "<aqua>Diamond"
description: "<gray>A coin each"
inputs:
- key: amount
type: slider
label: "How many"
min: 1
max: 64
step: 1
initial: 16
buttons:
- label: "<green>Buy"
tooltip: "Buy {amount} diamonds"
actions:
- "[if] %vault_eco_balance% >= {amount}" # stop unless they can pay (see Actions)
- "[console] eco take {player} {amount}"
- "[console] give {player} diamond {amount}"
- "[message] <green>Bought {amount} diamonds."
- "[close]"
exit: # the button Escape also presses
label: "Close"
quick-action: true # the Quick Actions key (G) opens it (optional)quick-action: puts a dialog on Minecraft's Quick Actions key (G, 1.21.6+).
true (or direct) has G open the dialog itself, drawn for each player as
they joined, so its values show what was true then until they join again (Paper
only). launcher has G open a one-button screen that asks the server for the
dialog, drawn fresh. A section takes mode: and label:, the name in the key's
list. The key is read from a datapack (world/datapacks/dialogengine_quick), so
a change takes a restart. A dialog with a permission:, a json: dialog, a
drawn dialog showing the player's own items and anything on Spigot use the
launcher.
A body entry is a string (text), or a map:
| Key | |
|---|---|
text: |
MiniMessage; a list is several lines. width: 1-1024, default 200 |
item: |
An item id, drawn with description: beside it. Also name:, lore:, amount:, model: (an item model id), custom-model-data:, glow:, tooltip: (hover shows it), decorations: (count and bar), width:/height: 1-256 |
head: |
A player's name: the item is their head (item: defaults to player_head) |
if: |
Only drawn when this holds (see Conditions) |
for-each: |
Drawn once per row of a list (see Lists) |
An item from your server's own resource pack (ItemsAdder, Nexo, Oraxen or a
pack of your own) is drawn as itself by model: and custom-model-data:, the
same components the plugin gives the real item:
body:
- item: paper
name: "<red>Ruby"
model: nexo:ruby # its item model
- item: paper
custom-model-data: 1001 # a plugin's custom model data number
- item: paper
custom-model-data: # or the game's own lists, by name
floats: [1001]
strings: ["{gem}"]
flags: [true]
colors: ["#ff5555"]A single value, or a list of them, becomes a float, a flag (true/false) or a
string by what it says. Placeholders are filled first, so one can pick the model
per player.
type: |
Keys | Value in {key} |
|---|---|---|
text |
max-length, lines + height for a text area, initial |
What was typed |
options |
options: a list of {id, text, initial} (or - id: Text), or a for-each |
The chosen id; {key.label} is its text |
toggle |
initial, on-true, on-false |
true / false; {key.text} is on-true/on-false |
slider |
min, max, step, initial, format (a translation key) |
The number |
All take label:, label-visible:, width: and if:.
Checks. A text input can have required: true, min-length:,
pattern: (a Java regex the whole value must match) and error: (the
message). A button press with a failing input draws the dialog again with what
was typed still in it and the message on top ({error}, which a dialog can
also print where it likes). A button with validate: false skips the checks.
The exit button never checks.
What a player typed is escaped wherever it is printed, so nobody can put a colour or a click into somebody else's screen, and a command takes it only as a name, a number or an id unless the dialog says otherwise (see Actions).
label:, tooltip:, width: (1-1024, default 150), permission: (hidden
without it), if:, for-each:, validate:, and actions:. Shorthands:
command:, console:, open:, url:, copy:, suggest:, message:,
close: true, back: true.
The layout follows the buttons: one is a notice, more are a grid of
columns:. Say type: confirmation with confirm: and cancel: buttons for
a yes/no, or type: links for the server links screen.
Run in order. A line without a [tag] is a command the player runs.
| Action | |
|---|---|
[player] cmd |
The player runs it, with their own permissions |
[console] cmd |
The console runs it |
[message] text / [broadcast] text / [actionbar] text |
MiniMessage |
[title] title | subtitle |
|
[sound] id [volume] [pitch] |
entity.experience_orb.pickup 1 1.4 |
[open] id [key=value ...] |
Another dialog, carrying this one's values (and what was typed) over |
[back] |
The dialog this one was opened from, as it was |
[refresh] |
This one again, with what was typed still in it |
[page] next|prev|first|last|N |
Turn the page of a paged list |
[set] key=value ... |
Set a value for the actions after, and any dialog opened |
[clear] [keys] |
Forget what was typed (all inputs, or the keys named) |
[close] |
|
[delay] ticks |
Wait before the rest |
[if] condition |
Stop here unless it holds |
[permission] node |
Stop here unless the player has it |
[url] link / [copy] text / [suggest] /cmd |
As a button's only action these are the client's own (open the link, copy, fill the chat box). The server never hears that such a button was pressed, so a dialog with one is shown as after: close even under wait |
[event] id |
Nothing by itself: names the click id for DialogClickEvent (see Events). Placeholders work |
[myplugin:tag] ... |
Whatever another plugin registered |
What a player typed, in a command. A [console] or [player] command
takes a typed value (a text input, a command's args:, values from
/de open, {player_display}) only when it is letters, digits, _, . and
-: a name, a number, an id. Anything else (@a, a space, a quote) and the
button runs nothing (or nothing more, for a value an earlier [set] made): a
text input is drawn again with the message unsafe-value on it, anything else
gets it in chat, and the console says which placeholder it was. Where more is
safe, say how the value is used:
{key|raw} |
As typed, on one line. For the last, free-text argument of a plugin's command: staffchat {player}: {details|raw}. Not for vanilla's say, msg or tell, which read @a in it. In a [player] command it is usually fine: the player could type that command themselves |
{key|json} |
Escaped for the inside of a quoted JSON string: tellraw @a {"text":"{msg|json}"} |
{key|snbt} |
Escaped for the inside of a quoted SNBT string: give {player} paper[custom_name='{name|snbt}'] |
Values from the dialog itself, from plugins and PlaceholderAPI, and from sliders, toggles and dropdowns (only options the dialog drew count) are not checked. A filter works on them too.
A command that fails stops the rest. When a [console] or [player]
command fails as far as the server can tell, the actions after it do not run,
and for [console] the player is told (command-failed) and the console
logs it. The server can only tell when the command does not exist (the plugin
behind it is missing, say) or throws an error. A command that ran and refused,
like an eco take without the money in the account, has succeeded as far as
the server knows, whatever it printed. So check before taking anything, as the
shop above does with [if] %vault_eco_balance% >= {amount} (PlaceholderAPI's
Vault expansion).
{name} anywhere: titles, text, labels, tooltips, actions, conditions.
- What the dialog was opened with (
/de open shop Steve coins=40, an API call, or a command'sargs:), and everything typed into its inputs. {player}{player_uuid}{player_display}{player_world}{player_x}{player_y}{player_z}{player_health}{player_level}{player_gamemode}{online}{max_players}{dialog}.- Whatever a plugin registered, and every PlaceholderAPI
%placeholder%. One in what a player typed is printed as typed, never filled. - A choice:
{mode?on:Enabled|off:Disabled|Unknown}prints the words for the valuemodehas, and the last entry when none matches. A*entry matches any value that is not empty.$valuein the words prints the value itself. - A filter:
{name|raw},{name|json},{name|snbt}, for putting what a player typed into a command (see Actions).
A name nothing knows is left as written.
A dialog can be about somebody: args: [target] makes /punish Steve
open it with {target} = Steve. The last argument takes the rest of the line.
if-missing: other_dialog opens another one when an argument is left out.
defaults: gives values the dialog starts with.
if: on a body entry, input or button, and the [if] action.
{muted} true unless empty, false, 0, no, off, null or unfilled
!{muted}
{warnings} >= 3 numbers compare as numbers, anything else as words
{rank} == admin && perm:server.staff
({page} > 1 || {mode} != "quiet mode")
for-each: name on a body entry, a button or an input's options: repeats it
once per row, with {row.field} for the row's fields (as: renames row),
{row.index}, {row.first} and {row.last}. per-page: N pages it:
{page}, {pages}, {has_next} and {has_prev} are set, and [page] next
turns. limit: N caps it.
Built in: online_players and other_players (name, uuid, world,
ping; vanished players stay hidden) and worlds. A dialog can declare its
own under lists:, and plugins register more.
warps:
title: Warps
lists:
places:
- { id: spawn, name: "Spawn" }
- { id: arena, name: "<red>Arena" }
buttons:
- for-each: places
label: "{row.name}"
actions: ["[player] warp {row.id}", "[close]"]json: file.json (beside the YAML) sends a minecraft:dialog object exactly
as written, with {placeholders} filled. Its buttons do whatever the JSON
says.
depend: [DialogEngine] (or softdepend), and compile against the jar.
DialogEngineAPI dialogs = DialogEngine.api();
// Ship your dialogs: copy defaults into your data folder, then hand it over.
// Server owners edit them there; /de reload reads them again.
saveResource("dialogs/menu.yml", false);
dialogs.registerFolder(this, "myplugin", new File(getDataFolder(), "dialogs"));
// Open one, with values for its {placeholders}.
dialogs.open(player, "myplugin:menu", Map.of("coins", "120"));
dialogs.refresh(player); // the player's current dialog, drawn again
dialogs.close(player);
// Change what an open dialog says, then draw it once.
dialogs.set(player, "coins", "95");
dialogs.refresh(player);
// A new action: [myplugin:give] diamond 3
dialogs.registerAction(this, "myplugin:give", (ctx, arg) -> {
String[] p = arg.split(" ");
ctx.viewer().getInventory().addItem(new ItemStack(Material.matchMaterial(p[0]), Integer.parseInt(p[1])));
ctx.refresh();
});
// {myplugin_coins}
dialogs.registerPlaceholders(this, "myplugin_", (viewer, ctx, key) ->
key.equals("coins") ? String.valueOf(economy.balance(viewer)) : null);
// for-each: myplugin_quests
dialogs.registerList(this, "myplugin_quests", (viewer, ctx) -> quests.of(viewer).stream()
.map(q -> Map.of("id", q.id(), "name", dialogs.escape(q.name()), "done", String.valueOf(q.done())))
.toList());A dialog built in code is a ConfigurationSection in the same format:
registerDialog(plugin, "myplugin:x", section).
A plugin can ship dialogs drawn in the browser editor inside its jar: put each
one's folder (as /de edit writes it) under drawn/<namespace>/ in your
resources, list every file in drawn/<namespace>/files.txt, and call
dialogs.installDrawn(this, "myplugin"); // then open "myplugin:<name>" as usualThey are copied into plugins/DialogEngine/drawn/myplugin/ the first time
each version of your plugin runs. One the server owner has changed since (with
/de edit or by hand) is kept as they made it. Their resource pack is sent
when a player first opens one, never on join.
A drawn dialog's switches, sliders and dropdowns are settings kept on the
player, which your plugin reads with dialogs.setting(player, "name") and
sets with dialogs.setSetting(player, "name", value) (null clears it; no
DialogSettingChangeEvent, which is for the player's own clicks), and
anything else reads through PlaceholderAPI as %dialogengine_setting_<name>%
(the dialog's default until the player sets it). The other placeholders:
%dialogengine_open%, %dialogengine_dialog% (the open dialog's id),
%dialogengine_value_<key>%, %dialogengine_can_open_<id>%,
%dialogengine_dialogs% and %dialogengine_version%. A
list's rows are values like any other: warps_3 is row three, warps_3_note
its note field and warps_count how many there are.
A drawn dialog's grid of item slots can show a container "from a plugin", by a name set in the editor. Register that name and the slots show what your inventory holds; if the grid lets items move, players move them between it and their own inventory:
dialogs.registerContainer(this, "bank", new DialogContainer() {
public Inventory inventory(Player viewer) { return banks.of(viewer); } // null: empty slots
public void changed(Player viewer) { banks.save(viewer); }
});mayTake and mayPlace refuse a move per slot, and DialogSlotMoveEvent
still fires for every one, with the slot named api.bank/0.
A drawn dialog's pieces fire DialogClickEvent too. A piece has no id:, so
name it in its command: in the editor, When clicked set to Run command,
with [event] claim. One listener then answers a whole menu, with the
player's settings in the event. Registering an action and naming it there,
[myplugin:claim] daily (or several, [a] ...; [b] ...), works as well. A
command with no brackets is run by the player, as on any dialog.
| Event | |
|---|---|
DialogOpenEvent |
A dialog is about to be drawn. Cancellable; getValues() can be changed |
DialogClickEvent |
A button was pressed, its inputs passed, its actions not yet run. Cancellable; getButtonId(), getInputs(), getSettings() (a drawn dialog's), getValues(), getActions() (changeable), isDrawn(), and getContext() to open, refresh or close |
DialogCloseEvent |
A dialog left the screen. getReason(): EXIT (the exit button, or Escape, which presses it), BUTTON, REPLACED (getNextDialogId()), SCREEN (a container, the death screen, another world), PLUGIN or QUIT; getButtonId(), getValues(), getSettings() |
DialogSettingChangeEvent |
A drawn dialog's switch, slider or dropdown is about to change a setting. Cancellable |
DialogSlotMoveEvent |
A stack is about to move between a drawn dialog's item slots. Cancellable |
DialogInputErrorEvent |
An input failed its check; the message can be changed |
DialogEngineReloadEvent |
Everything was read again |
A button with an id: and no actions is a button your plugin answers in
DialogClickEvent, and so is one whose actions say [event] <id>, which is
how a drawn dialog's pieces get one.
Escape reaches the server only as a press of the exit button, so a YAML dialog
with buttons and no exit: closes with Escape unheard: give it an exit:
when you need DialogCloseEvent. Folia tells plugins nothing about a move to
another world, so there that close is not reported either.
Values you pass are read as MiniMessage. Anything a player wrote goes through
dialogs.escape(...) first.
Everything a plugin registers is dropped when it disables.
Every button is a server callback bound to the drawing of the dialog the
player saw: the values it was drawn with, and its inputs. Nothing a player can
type in chat presses a button. Only the latest drawing can be pressed: a new
one (another dialog, a refresh, a failed check) retires the buttons of the one
before. A button's permission: and if: are asked again when it is pressed,
so one that has since stopped applying does nothing. Buttons stop working
click-lifetime-minutes after the dialog was drawn, and a player gets at most
ten clicks a second.
A drawn dialog's clicks (/de edit) are the same: each action click works
once per showing, only while that dialog is on the player's screen, and only
runs a command that is in its dialog.yml.
Under after: seamless (the default) a dialog stays on the screen exactly as it
is until the engine answers the click: the next dialog takes its place with
nothing in between, and when none follows, the engine closes it on the next
tick. There is no flash of the world and no waiting screen. A button that runs
a command closes the dialog before the command runs, unless one of its later
actions opens the next dialog itself, so a screen that command opens (another
plugin's dialog, a chest) is never closed after it arrives. A button the client
handles by itself ([url], [copy], [suggest]) never reaches the engine and
leaves the dialog open.
Under after: wait the client shows its "Waiting for Server" screen until the
engine answers: with the next dialog, or by closing the screen
close-delay-ticks after the button's actions have run. A dialog with a
client-only button is shown as after: close instead. A drawn dialog set to
wait in Studio is answered the same way.
JDK 21.
git clone https://github.com/resourcepack-ai/dialog-engine
cd dialog-engine
./gradlew buildThe plugin is build/libs/dialog-engine-<version>.jar. Dependencies come from
Maven Central, SpigotMC's repository and
repo.resourcepack.ai: ai.resourcepack:common,
a small shared library for the update check and usage count, and
ai.resourcepack:dialog-runtime, the code that runs drawn dialogs, which RP
Engine shades too.
Questions, bugs and ideas: the ResourcePack AI Discord.