inputs

Inputs let players fill in values directly inside a dialog or Chest GUI, replacing chat prompts or sign interactions. They are supported on modern Paper dialogs, Bedrock forms, and Chest GUIs (via virtual Anvil / Chat prompts).

Defining Input Fields

Input fields are defined under the inputs: key in a menu file.

Text Input (text)

A free-text field for names, reasons, or any string value.

inputs:
  - type: text
    key: "home_name"         # Used as $(home_name) in commands
    label: "<white>Home Name"
    initial: "home"          # Pre-filled value (optional)
    max-length: 24           # Max character limit
    width: 250               # Width in pixels
    multiline: false         # true = multi-line text area

Number Range Slider (number-range or number)

A numeric slider between a min and max value.

  - type: number-range
    key: "pay_amount"
    label: "<white>Amount"
    min: 1.0
    max: 1000000.0
    step: 1.0                # Snap increment
    initial: 100.0
    label-format: "Amount: $%s"  # %s is replaced with current value
    width: 300

Boolean Toggle (bool or toggle)

A toggle switch (on/off).

  - type: bool
    key: "pvp"
    label: "<red>PvP Enabled"
    initial: true

Single Option Dropdown (single-option or dropdown)

A dropdown where the player picks one value from a list.

  - type: single-option
    key: "language"
    label: "<yellow>Language"
    options:
      - value: "en"
        label: "English"
      - value: "ar"
        label: "العربية"
      - value: "es"
        label: "Español"
    initial: "en"            # Must match one of the option values

Interactive Real-Item Slots (type: item_slot)

Define physical item placement slots in Chest GUIs for custom blacksmithing, enchanting, trade stations, and recycling:

inputs:
  - key: "weapon"
    type: item_slot
    slot: 11
    accept: "*_SWORD, *_AXE"
    material: "ANVIL"
    name: "<yellow>Place Weapon Here</yellow>"
  - key: "catalyst"
    type: item_slot
    slot: 15
    accept: "DIAMOND, EMERALD"

Slot Context Variables

• $(<key>_material): Upper-case material name (e.g. DIAMOND_SWORD).
• $(<key>_amount): Number of items in slot.
• $(<key>_name): Custom display name of placed item.
• $(<key>_custom_model_data): CustomModelData integer if present.

Atomic Deduction Action

Use [consume-item-slot] <key> [amount] in your action chain to safely deduct the required amount upon confirmation:

actions:
  - "[consume-item-slot] catalyst 3"
  - "[sound] BLOCK_ANVIL_USE 1.0 1.0"
  - "[message] <green>Upgraded $(weapon_material) successfully!</green>"
  - "[refresh]"

Using Input Values in Commands & Actions

Input values are substituted into commands, action chains, button labels, and tooltips using $(key):

buttons:
  - label: "<green>Confirm Transfer</green>"
    actions:
      - "[player] pay $(target_player) $(pay_amount)"
      - "[sound] ENTITY_PLAYER_LEVELUP 1.0 1.0"
      - "[close]"

Default Fallbacks ($(key|default))

If an input is optional or not yet populated in the player context, provide a safe fallback value:

• $(amount|1): Uses the value of amount, or defaults to 1 if empty.
• $(target|%player_name%): Uses the target name, or defaults to the player's own name.
• $(category|all): Uses selected category or defaults to all.

Dynamic Mathematical Arithmetic ($(math:...) or $(calc:...))

DialogMaster includes a built-in arithmetic engine that calculates dynamic prices, quantities, and balances inside tooltips, action commands, and click requirements.

Supported Operations

• + Addition (e.g. $(math: $(base_cost) + 50))
• - Subtraction (e.g. $(math: $(price) - $(discount)))
• * Multiplication (e.g. $(math: 500 * $(amount|1)))
• / Division (e.g. $(math: $(total) / 2))
• % Modulo / Remainder (e.g. $(math: $(count) % 64))
• (...) Nested Parentheses (e.g. $(math: (100 + 25) * $(amount|1)))

Practical Shop Example

# In Menu YAML:
inputs:
  - key: "amount"
    type: "single-option"
    label: "Quantity"
    initial: "1"
    options:
      - value: "1"
        label: "<aqua>1x (Single)"
      - value: "16"
        label: "<yellow>16x (Pack)"
      - value: "64"
        label: "<gold>64x (Stack)"

buttons:
  - label: "<item:diamond_sword> <aqua>Diamond Sword</aqua>"
    tooltip: "<gray>Unit Price: <gold>$500</gold>\nTotal: <gold><bold>$$(math:500 * $(amount|1))</bold></gold></gray>"
    click-requirements:
      - "%vault_eco_balance% >= $(math:500 * $(amount|1))"
    deny-message: "<red>You need $$(math:500 * $(amount|1)) to buy $(amount|1)x items!</red>"
    actions:
      - "[console] eco take %player_name% $(math:500 * $(amount|1))"
      - "[console] give %player_name% diamond_sword $(amount|1)"
      - "[message] <green>Purchased $(amount|1)x Diamond Swords for $$(math:500 * $(amount|1))!</green>"

Live Search & Filter Input (key: "search" / key: "filter")

Adding a text input with key: "search", "filter", or "query" allows players to filter buttons and dynamic lists live:

inputs:
  - key: "search"
    type: "text"
    label: "Filter Catalog"
    max-length: 16

footer-buttons:
  - label: "<item:spyglass> <yellow>Search / Refresh</yellow>"
    action: open-menu
    target: "shop-menu"

Full Example: Bank Transfer Menu

id: "bank_transfer"
title: "<gold>Bank Transfer</gold>"
type: "confirmation"
inputs:
  - type: text
    key: "target"
    label: "<yellow>Target Player</yellow>"
    initial: "Steve"
  - type: number-range
    key: "amount"
    label: "<yellow>Amount ($)</yellow>"
    min: 10.0
    max: 50000.0
    step: 10.0
    initial: 100.0
    label-format: "$%s"
confirm-button:
  label: "<green>Send Money</green>"
  actions:
    - "[player] eco take $(amount)"
    - "[console] eco give $(target) $(amount)"
    - "[message] <green>Sent $$(amount) to $(target)!</green>"
    - "[close]"
deny-button:
  label: "<red>Cancel</red>"
  actions:
    - "[close]"