# Minecraft Dialogue

> Minecraft Dialog Definition 对话定义：Invocation 调用方式（/dialog、文本组件点击事件、服务器消息、其他对话）、Special Dialog Tags 特殊对话标签（#pause_screen_additions 暂停屏幕替换、#quick_actions 快捷操作 G 键）、Layout 布局（header 标题+警告按钮、content 内容+输入面板、footer 页脚）、Definition Format 定义格式（DIALOG 注册表、data/<namespace>/dialog/ 数据包路径、tags/dialog/ 标签、common fields after_action/pause/can_close_with_escape/body/inputs/external_title/title/type）、After-action Behavior 后操作行为（none 无操作、close 关闭对话、wait_for_response 等待服务器响应）、Dialog Types 对话类型（confirmation 确认对话 yes/no、dialog_list 对话列表 跳转按钮、multi_action 多操作网格、notice 通知单确认按钮、server_links 服务器链接）、Body Elements 主体元素（item 物品栈渲染+描述、plain_message 纯文本）、Input Controls 输入控件（boolean 复选框、number_range 滑块、single_option 选择按钮、text 文本框）、Actions 操作（Static Actions 静态操作：open_url/run_command/suggest_command/change_page/copy_to_clipboard/show_dialog/custom、Dynamic Actions 动态操作：dynamic/custom 自定义负载 input values、dynamic/run_command 模板命令 $(name) 占位符）。

- Skill: `zmjjkk123-hub/minecraft-dialogue` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zmjjkk123-hub/minecraft-dialogue`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zmjjkk123-hub/minecraft-dialogue/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ZMJJKK123-hub (https://skillmd.com/u/zmjjkk123-hub)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/zmjjkk123-hub/minecraft-dialogue

---


# Dialog Definition

Dialogs are a data-driven way to present interactive UIs to players: fixed information, events, and input submission to the server. Java Edition only.

## Invocation

Dialogs open via `/dialog`, text component click events, server messages, or other dialogs. Two special dialog tags control built-in entry points:

- `#pause_screen_additions` — replaces the pause screen's "Report Bugs" / "Provide Feedback" buttons. With exactly one registered dialog: the "Custom Options…" button becomes its display name and opens it directly. With several: the report-bug button opens the `custom_options` dialog listing jump buttons. With none, but with server link data (from the `server_links` packet): the `server_links` dialog replaces the button. Otherwise unchanged.
- `#quick_actions` — opened by the quick-actions key (default G); multiple entries open the `quick_actions` dialog with jump buttons.

## Layout

Dialogs have a header (33 px: title + a fixed warning button with a disconnect/exit option, 10 px apart), content (body elements + input panel; scrolls if too tall), and a footer (≥33 px, type-dependent). Everything is centered.

## Definition Format

Registry `DIALOG`, data pack path `dialog` (files in `data/<namespace>/dialog/`; tags in `tags/dialog/`).

Common fields:

- `after_action` (default `close`) — see below.
- `pause` (default true) — pause the game in single-player; must be false when `after_action` is `none`.
- `can_close_with_escape` (default true).
- `body` (default empty) — body elements (element or list).
- `inputs` (default empty) — input controls.
- `external_title` (default `title`) — text for buttons opening this dialog elsewhere.
- `title` (required) — dialog title text component.
- `type` (required) — dialog type.

Definitions load once at server startup; `/reload` does not reload them.

### After-action Behavior

- `none` — nothing; player stays in the dialog (requires `pause: false`).
- `close` — closes the dialog (always the behavior when exiting with Esc).
- `wait_for_response` — closes and shows the "waiting for server response" screen (does not pause; a return button appears after 5 s).

Effective click events inside dialogs: `copy_to_clipboard`, `custom`, `open_url`, `run_command`, `show_dialog` (`run_command` unavailable in configuration-phase dialogs).

## Dialog Types

- `confirmation` — yes/no confirmation: `yes` / `no` actions (the `no` action is also the Esc default).
- `dialog_list` — jump buttons to other dialogs: `button_width` (1–1024, default 150), `columns` (default 2), `dialogs` (required: tag/ID/inline/list), `exit_action` (return button; absent = no button).
- `multi_action` — multiple actions in a grid: `columns` (default 2), `actions` (required, non-empty), `exit_action`.
- `notice` — announcement with one confirm button: `action` (default: 150 px wide, closes the dialog).
- `server_links` — buttons from the `server_links` packet (text fixed by link `type`, click opens `url`; vanilla: empty or one `report_bug` link from `bug-report-link` in server.properties): `button_width`, `columns`, `exit_action`.

## Body Elements

Between the header and input panel (10 px gaps). Their text's click/hover events work normally.

- `item` — renders an item stack and optional description: `item` (item template), `description` (text component; item on the left, 4-px-padded centered multiline text on the right, 2 px apart), `show_decorations` (default true — durability bar/cooldown/count), `show_tooltip` (default true), `width`/`height` (1–256, default 16 — layout only), and a text `width` (default 200).
- `plain_message` — text: `contents` (text component), `width` (1–1024, default 200); 4 px padding, centered, wraps.

## Input Controls

Common: `key` (required; letters/digits/underscore only) + `type`. Types:

- `boolean` — checkbox + label (4 px apart): `label`, `initial` (default false), `on_false` / `on_true` (default "false"/"true"; string form submits these, NBT form submits `0b`/`1b`).
- `number_range` — slider (20 px high): `label`, `label_format` (default `options.generic_value`; first arg = label, second = current value), `width` (default 200), `start`/`end` (required doubles; end may be < start), `step` (>0; discrete values `initial + n×step` only), `initial` (default middle). String submission emits integers as integers ("5" not "5.0"); NBT submission appends `f`.
- `single_option` — selection button (20 px): `label`, `label_visible` (default true), `options` (non-empty list of `{id (real value), display (default id), initial}`; shorthand strings = id only; at most one initial, first option default), `width` (default 200).
- `text` — text box (20 px, label above with 4 px gap): `label`, `label_visible`, `initial` (default ""), `max_length` (default 32), `multiline` ({max_lines, height (1–512, default from max_lines)})`, `width` (default 200). Special characters are escaped on submission.

## Actions

Common: `label` (required text component), `tooltip`, `width` (1–1024, default 150), `action` object.

### Static Actions

- `open_url` — `url` (http/https only).
- `run_command` — `command`.
- `suggest_command` — has no effect in dialogs.
- `change_page` — has no effect in dialogs.
- `copy_to_clipboard` — `value`.
- `show_dialog` — `dialog` (ID or inline).
- `custom` — `id` (payload namespace ID), `payload` (≤16 nesting levels, ≤32768 bytes); no effect on the vanilla server.

### Dynamic Actions

- `dynamic/custom` — builds a `custom` payload from input values: `id`, optional `additions` (static compound merged first), then one key-value pair per input control (key = control `key`, value = input content), sent via the `custom_click_action` packet. Over-limit payloads cause a disconnect (or world exit in single-player).
- `dynamic/run_command` — builds a command from a `template`: `$(name)` placeholders (letters/digits/underscore; unknown names → empty string; at least one placeholder required). No `/` or `$` prefix allowed (parse failure if present). The executor defaults to the submitting player. Checks before sending: configuration-phase dialogs never send (log warning); unparseable → warning dialog; signature-requiring arguments (chat messages) → confirmation screen; permission level > 0 → permission warning dialog.