Skip to main content

Variants

Variants allow an element to change its visual appearance (name, material, lore) or its executed command dynamically based on the viewing player's conditions.

Example: VIP Discount Override​

Show standard pricing ($1,000) to regular players, but display discounted VIP pricing ($500) and run a VIP-specific command for VIPs:

menu-items:
  - id: buy_diamond
    slot: 13
    material: DIAMOND
    name: "&bBuy Diamond"
    lore:
      - "&7Standard Price: &e$1,000"
    command: "shop buy diamond standard"

    # Variant overrides
    variants:
      - id: vip_discount
        when:
          permission: "myserver.vip"
        override:
          name: "&d&l[VIP] Buy Diamond (50% OFF!)"
          lore:
            - "&7VIP Price: &a$500"
            - "&dVIP perk active"
          glint: true
          command: "shop buy diamond vip"

Evaluation & Override Rules​

  1. Top-to-Bottom First Match: The variants list is evaluated sequentially; the first variant whose when condition holds is applied.
  2. Selective Key Overrides: Only keys specified inside override are replaced; unmentioned properties (slot, material, etc.) are inherited from the base element.
  3. Clean Action Replacement: If override specifies any of command, action, or actions, the base action definitions are completely replaced rather than merged.
  4. Session Binding: The selected variant is determined when the menu opens and stays fixed for that session, ensuring that what the player sees always matches what clicking will execute.
  5. Conditions can be overridden too: Writing visible-when / enabled-when / disabled-message / cooldown / input-refs in override replaces them only when that variant is selected. visible-when and enabled-when are evaluated with the selected variant's values.
  6. id is optional: When a variant's id is omitted it becomes variant-0, variant-1, ... by position. when is not required, but without it the variant always matches and later variants are never used. A missing override is an error (invalid-variant).
No Nesting

Variants cannot be nested inside other variants.

Validation at Reload​

All variant overrides are parsed and validated identically to base items during /menu reload.

If an override references an unknown material or invalid action, reload is rejected immediately. Errors never linger until a player meets the condition.