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.

:::note 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.