requirements

DialogMaster features a high-performance, strict condition evaluation engine that lets you dynamically control button visibility (view-requirements) and click execution (click-requirements) with PlaceholderAPI variables, native permissions, boolean shortcuts, and failure handling.

Requirement Types

View Requirements (view-requirements)

Evaluated when a menu or GUI is generated for a player. If any requirement fails, the button or item is completely hidden from the layout.

buttons:
  - label: "<red>Staff Panel"
    view-requirements:
      - "permission:server.staff"
    action: open-menu
    target: staff-menu

Click Requirements (click-requirements)

Evaluated when the player clicks the button. If any requirement fails:

• All click actions are blocked.
• Optional deny-message is sent to the player.
• Optional deny-actions are executed.
• Plays the dm:deny UI failure sound (ENTITY_VILLAGER_NO).

buttons:
  - label: "<gold>Purchase Speed Boost"
    click-requirements:
      - "%vault_eco_balance% >= 500"
    deny-message: "<red>You need <gold>$500</gold> to purchase this! (You have: <yellow>$%vault_eco_balance%</yellow>)"
    deny-actions:
      - "[sound] ENTITY_VILLAGER_NO 1.0 1.0"
    action: run-commands
    actions:
      - "[console] eco take %player_name% 500"
      - "[player] effect give %player_name% speed 30 1"
      - "[message] <green>Purchased 30s Speed Boost!"

Strict Comparison Operators

Expressions follow the format [Value A] [Operator] [Value B].

Operator	Type	Description	Example
==	Flexible	Case-insensitive string equality or numeric equality	"%player_name%" == "Steve"
!=	Flexible	Case-insensitive string inequality or numeric inequality	"%player_name%" != "Notch"
===	Strict String	Exact case-sensitive string equality	"%luckperms_primary_group%" === "Admin"
!==	Strict String	Exact case-sensitive string inequality	"%player_world%" !== "world_nether"
>	Numeric	Strictly greater than	"%vault_eco_balance% > 500"
>=	Numeric	Greater than or equal to	"%player_level% >= 30"
<	Numeric	Strictly less than	"%statistic_player_kills% < 100"
<=	Numeric	Less than or equal to	"%statistic_deaths% <= 5"
contains	Substring	Case-insensitive substring match	"%luckperms_prefix% contains Vip"
!contains	Substring	Negated case-insensitive substring match	"%player_world% !contains test"

Native Permissions & Boolean Shortcuts

DialogMaster allows concise boolean checks without requiring == true:

Native Permission Checks (Zero Dependencies)

Works directly with Bukkit/LuckPerms permissions without requiring PlaceholderAPI expansions:

• permission:<node>: Checks if player has the permission.
• !permission:<node>: Checks if player does NOT have the permission.
• has_permission:<node> / !has_permission:<node>

Boolean Shortcuts & Truthy Values

Placeholders returning boolean flags can be written directly:

• Truthy values (true, yes, enabled, on, 1, or numbers > 0) evaluate to true.
• Falsy values (false, no, disabled, off, 0, none, null, "") evaluate to false.
• Prefixing ! negates the check: !%player_is_flying%

view-requirements:
  - "!permission:admin.bypass"
  - "%essentials_is_afk%"
  - "!%vault_eco_balance%"

Strict Safety Guarantees

1. Unresolved Placeholder Protection
   • If a PlaceholderAPI expansion is missing or unresolved (e.g. %unknown_expansion_var%), the condition strictly evaluates to false rather than evaluating against the raw token string.
2. MiniMessage Tag Protection
   • Color tags (e.g. <gold>Admin</gold>) are safely parsed without being confused with math operators < or >.
3. Safe Numeric & Balance Comparisons
   • If an economy balance or numeric placeholder returns an empty string "" or non-numeric value, numeric comparisons (>=, <=, >, <) fail safely without throwing errors.
4. Quote Stripping
   • Surrounding double quotes ("...") or single quotes ('...') around string operands are automatically stripped.

Priority Groups

priority-groups lets you define multiple layouts for a single button slot. The engine checks each group top-to-bottom and renders the first one whose view-requirements all pass.

buttons:
  - label: "Starter Kit"
    priority-groups:
      # Group 1: shown only while the kit is on cooldown
      - label: "<red>Kit Locked"
        tooltip: "<gray>Cooldown: %essentials_kit_cooldown_starter%"
        view-requirements:
          - "!%essentials_kit_is_available_starter%"
        action: close

      # Group 2: default, kit is ready
      - label: "<green>Claim Starter Kit"
        tooltip: "<gray>Click to claim your daily kit!"
        action: run-command
        command: "/kit starter"