MagDialogGUIs
适用于 Paper 和 Purpur 的原生 Minecraft 对话 GUI 框架。MagDialogGUIs 不使用箱子库存来构建菜单,而是利用 Mojang 的 Dialog API(Minecraft 1.21.6 新增,Paper 开发者 API 自 1.21.7 起支持)向玩家展示真正的原生对话窗口——包含文本字段、复选框、滑块、单选按钮以及可执行命令的按钮。
每个对话框都在简单的 YAML 文件(.mg)中定义,只需将其放入 plugins/MagDialogGUIs/guis/ 即可。无需编写代码。
支持:Paper 和 Purpur,Minecraft 1.21.7 至 26.2(有关单个源码树如何覆盖整个版本范围,请参阅下方的 构建)。
快速开始
- 将 jar 包放入
plugins/,启动服务器一次,然后停止它。
- 查看
plugins/MagDialogGUIs/guis/ —— 为你提取了四个示例文件:example.mg、nickname.mg、chat-colour.mg 和 settings-menu.mg。
- 再次启动服务器,并在游戏中运行
/example、/nickname、/chatcolour 或 /settings。
- 编辑
.mg 文件,然后运行 /magdialogguis reload。
.mg 格式
.mg 文件是纯 YAML 格式。顶层键如下:
| 键 |
类型 |
默认值 |
描述 |
name |
string |
文件名 |
内部标识符。用于 open: 动作和 /magdialogguis open。 |
title |
string |
name |
MiniMessage 格式。对话框的标题。 |
external-title |
string |
(无) |
MiniMessage 格式。如果你使用了链接到本对话框的按钮,则显示在按钮上。 |
permission |
string |
(无) |
打开此 GUI 所需的权限,无论是通过命令、/magdialogguis open 还是 open: 动作。 |
escape |
boolean |
dialogs.default-escape (位于 config.yml) |
按 Escape 键是否关闭对话框。 |
columns |
int |
自动 (1 或 2) |
操作按钮布局的列数。 |
command |
map |
(无) |
见下文。省略此项可使 GUI 仅通过 open: 或 /magdialogguis open 访问。 |
body |
list |
空 |
参见 主体。 |
inputs |
map |
空 |
参见 输入项。 |
actions |
map |
空 (显示一个“关闭”按钮) |
参见 动作。 |
所有文本值(title、label、主体 text、动作 label/tooltip 等)均作为 MiniMessage 进行解析,因此 <red>、<bold>、<gradient:...> 等均有效。所有文本值也会先解析 %占位符% —— 参见 占位符。
command
command:
name: example # 注册 /example
aliases:
- testdialog # 以及 /testdialog
如果已存在同名命令,则跳过注册(并记录日志),除非 config.yml 中的 commands.protect-existing: false。
Body(主体)
条目列表,每个条目要么是文本消息,要么是物品图标。
body:
- text: "<white>欢迎, <yellow>%player%</yellow>!"
width: 300
- type: item
material: WRITABLE_BOOK # 任何 Bukkit Material 名称
description: "<gray>物品可用于说明你的对话框。"
width: 32
height: 32
show-decorations: true
show-tooltip: true
省略 type(或设置 type: text)即表示为文本条目。
Inputs(输入项)
inputs: 是一个映射,从 键(用于 %占位符% 并在 DialogResponseView 中显示)到其定义。支持四种类型,与 Minecraft 自身的对话框输入类型完全匹配。
text —— 文本字段。
inputs:
NAME:
type: text
label: "<green>你的名字"
width: 300 # 1-1024
max-length: 32
initial: "%player%"
label-visible: true
boolean —— 复选框。
inputs:
AGREE:
type: boolean
label: "<green>我同意"
initial: false
on-true: "true" # 勾选时替换到 %AGREE% 的值
on-false: "false" # 未勾选时替换到 %AGREE% 的值
number —— 滑块。
inputs:
LEVEL:
type: number
label: "<green>等级"
min: 0
max: 100
step: 1 # 省略则为连续滑块
initial: 50
label-format: "%s: %s" # 第一个 %s = 标签,第二个 = 当前值
option —— 单选 / 单选输入。
inputs:
COLOUR:
type: option
label: "<green>颜色"
width: 200
label-visible: true
options:
- id: "red"
display: "<red>红色"
initial: false
- id: "green"
display: "<green>绿色"
initial: true # 最多只能有一个选项设为初始选中
options 也接受纯字符串列表(例如 - "red"),在这种情况下,该字符串同时用作 id 和显示文本。
Actions(动作)
actions: 是一个从按钮 ID 到其定义的映射。每个条目成为对话框上的一个按钮。如果完全省略 actions:,对话框将获得一个默认的“关闭”按钮(一种 notice-type 对话框)。
actions:
submit:
type: player # 见下表
label: "<green>提交"
tooltip: "<gray>可选的悬停文本"
width: 150
command: "say Hello %NAME%"
after: CLOSE # CLOSE 或 NONE —— 每种类型的默认值见下文
type |
有效载荷键 |
作用 |
默认 after |
player |
command |
以点击玩家的身份运行命令(前导 / 可选)。 |
配置默认值 |
console |
command |
以控制台身份运行命令。 |
配置默认值 |
message |
message |
向玩家发送一条聊天消息。 |
配置默认值 |
open |
gui |
关闭当前对话框并通过 name 打开另一个 GUI。 |
CLOSE |
close |
(无) |
仅关闭对话框。 |
CLOSE |
none |
(无) |
不执行任何操作——可用作静态/装饰性按钮。 |
NONE |
“config default”(配置默认值)对应 config.yml 中的 dialogs.default-after-action(开箱即用为 CLOSE)。可在任意动作上设置 after: 以覆盖此默认值。
占位符
在 MiniMessage 解析之前,所有文本值中均会解析以下占位符:
%player%、%uuid%、%world%、%x%、%y%、%z% — 始终可用。
%<input-key>% — 每个输入提交的值,在 actions: 中可用(布尔值解析为 on-true/on-false,数字以纯文本格式显示)。
- 任何
%...% PlaceholderAPI 占位符,前提是已安装 PlaceholderAPI 且 config.yml 中设置了 placeholders.papi: true(此为默认设置)。
命令与权限
| 命令 |
权限 |
描述 |
/magdialogguis reload |
magdialogguis.admin |
重新加载配置文件和所有 .mg 文件。 |
/magdialogguis list |
magdialogguis.admin |
列出已加载的 GUI。 |
/magdialogguis open <gui> [player] |
magdialogguis.admin |
为自己或其他玩家打开一个 GUI。 |
每个 GUI 自身的 command:(如果已设置) |
该 GUI 的 permission: |
打开该 GUI。 |
config.yml
请参阅随附的 config.yml 以了解所有选项,包括调试日志记录、严格验证(在遇到未知类型时使 .mg 文件整体失败,而非仅跳过该项)、默认的转义/操作后行为以及消息自定义。
限制
- 按 Escape 键会在客户端关闭对话框,而不会向服务器发送往返请求,因此会话跟踪(类似
/magdialogguis list 的账目记录)无法检测到该操作——只有点击按钮、退出游戏或打开其他 GUI 才会更新状态。
- 文本输入框始终为单行;多行文本区域尚未暴露(底层 API 对多行的支持在受支持的版本范围内各不相同)。
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).
评论 0
登录后参与评分
还没有评论,来抢沙发吧