Dialog System

The dialog system wraps Paper 1.21's native dialog API, letting you define interactive overlay windows in YAML without writing Java code.

Concepts

Term	Description
DialogBlueprint	The parsed YAML definition. Immutable; shared across all players.
ComputedDialog	A per-player runtime instance. Holds the bound `Player` and parameter map.
Body	Text or item content displayed in the dialog window.
Input	Interactive widget (text field, toggle, slider, dropdown).
Button	Yes/No action buttons. Each has a label, optional tooltip, width, and action list.

File Layout

Place dialog YAML files in:

plugins/AstralCore/AstralDialogs/
├── confirm-purchase.yml
├── rename-item.yml
└── settings/
    └── graphics.yml

Sub-folders are scanned recursively. The file name is irrelevant; use the id field to reference dialogs.

Lifecycle

load()           ─── YAML → DialogBlueprint (once, async)
                               │
openMenu()                     ▼
   sync   ──────── ComputedDialog.compute()
                    ├── build body sections
                    ├── build input widgets
                    ├── build yes/no buttons with callbacks
                    └── show dialog to player
                               │
                    Player fills inputs & clicks Yes/No
                     └── button callback fires
                          ├── collect input values → bind as %input_<id>% placeholders
                          └── execute button.actions

Input Value Placeholders

After the player clicks a button, each input's current value is bound as a placeholder %input_<input-id>% and available to all actions inside that button:

inputs:
  username:
    type: text
    label: "Enter a username"

yes-button:
  label: "Confirm"
  actions:
    - "[console] rename %player_name% %input_username%"

Opening a Dialog

actions:
  LEFT:
    - "[open-dialog] confirm-purchase:item=%parameters_item%"

Parameters become available as %parameters_<key>% inside the dialog.

Via Java

AstralPaperAPI.getService(DialogService.class)
    .orElseThrow()
    .open(player, "confirm-purchase", Map.of("item", itemId));

Via command

/astraldialogs open <id>

open-actions / close-actions

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

close-actions:
  - "[message] <gray>Dialog closed."

These fire when the dialog is shown or dismissed (Escape or explicit close).

Last modified: 25 July 2026

Astral Realms Documentation Help