Dialog YAML Reference

A fully annotated dialog blueprint. Only id and title are strictly required.

# Unique identifier used to open this dialog.
id: "confirm-purchase"

# Title displayed at the top of the dialog window (MiniMessage).
title: "<bold>Confirm Purchase"

# Optional: secondary title shown above the native dialog frame.
external-title: "<gray>AstralShop"

# Allow the player to close the dialog by pressing Escape.
close-with-escape: true

# Pause the game (single-player) while the dialog is open.
pause: false

# ── Body ────────────────────────────────────────────────────────────────────

body:
  description:
    type: text                      # "text" or "item"
    contents: "<gray>Are you sure you want to buy\n<white>%param.item%<gray>?"
    width: 200

  icon:
    type: item
    item: "DIAMOND"                 # material or namespace-key
    width: 64
    height: 64

# ── Inputs ──────────────────────────────────────────────────────────────────

inputs:
  message:
    type: text
    label: "Optional message"
    width: 200
    max-length: 100
    initial: ""
    label-visible: true
    multi-lines:
      max-lines: 3
      height: 60

  confirm:
    type: boolean
    label: "I agree to the terms"
    initial: false
    true-text: "Yes"
    false-text: "No"

  quantity:
    type: slider
    label: "Quantity"
    width: 200
    start: 1
    end: 64
    initial: 1
    step: 1

  payment:
    type: options
    label: "Payment method"
    width: 200
    label-visible: true
    options:
      coins:
        display: "Coins"
        initial: true
      gems:
        display: "Gems"
        initial: false

# ── Actions ──────────────────────────────────────────────────────────────────

open-actions:
  - "[sound] minecraft:block.note_block.pling"

close-actions: []

# ── Buttons ──────────────────────────────────────────────────────────────────

yes-button:
  label: "<green>Confirm"
  tooltip: "<gray>Finalise your purchase"
  width: 100
  actions:
    - "[console] shop buy %player.name% %param.item% %input.quantity%"
    - "[message] <green>Purchase confirmed!"
    - "[sound] minecraft:entity.player.levelup"

no-button:
  label: "<red>Cancel"
  width: 100
  actions:
    - "[message] <gray>Purchase cancelled."

Top-level Fields

Field	Type	Required	Description
`id`	String	Yes	Unique identifier.
`title`	String (MiniMessage)	Yes	Dialog title.
`external-title`	String (MiniMessage)	No	Secondary title above the native frame.
`close-with-escape`	boolean	No	Allow Escape to close. Default `true`.
`pause`	boolean	No	Pause the game while open (single-player only). Default `false`.
`body`	`Map<String, Body>`	No	Named body sections.
`inputs`	`Map<String, Input>`	No	Named input widgets.
`open-actions`	`List<Action>`	No	Actions executed when the dialog opens.
`close-actions`	`List<Action>`	No	Actions executed when the dialog closes.
`yes-button`	ActionButtonBlueprint	No	Primary (confirm) button.
`no-button`	ActionButtonBlueprint	No	Secondary (cancel) button.

Body Section Fields

Field	Type	Description
`type`	`text` or `item`	Body section type.
`contents`	String (text type)	MiniMessage text content. Supports `\n` for line breaks.
`item`	String (item type)	Item material or namespace-key for the displayed icon.
`width`	int	Width in pixels.
`height`	int (item type)	Height in pixels for the item display.

Button Fields

Field	Type	Description
`label`	String (MiniMessage)	Button label.
`tooltip`	String (MiniMessage)	Tooltip shown on hover. Optional.
`width`	int	Button width in pixels. `0` uses the default.
`actions`	`List<Action>`	Actions executed when this button is clicked. `%input.<id>%` placeholders are available here.

23 April 2026