> For the complete documentation index, see [llms.txt](https://airdevelopment.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://airdevelopment.gitbook.io/docs/global-features/guis.md).

# GUIs

## General

### Shared settings

The `shared.yml` file defines shared behavior, reusable item templates, and aliases.

```yaml
defaults:
  trim-lore: true
  force-reopen: false
  refresh-interval: -1
  input-type: SIGN
  # Actions executed when any GUI opens or closes.
  open-actions: []
  close-actions: []

# Aliases - Named strings reusable anywhere on GUIs via $name.
aliases:
  close-sound: "ui.button.click 1 1"
  message: "<rainbow>Send a message!"

# Reusable item templates
templates:
  filler:
    material: GRAY_STAINED_GLASS_PANE
    hide-tooltip: true

  next-page:
    material: ARROW
    display-name: "<green>Next Page"
    actions:
      any:
        - "[page] next"
```

{% tabs %}
{% tab title="Using aliases" %}
Aliases are prefixed with `$` and are expanded anywhere on GUIs.

```yaml
actions:
  left:
    - "[sound] $close-sound"
    - "[close]"
```

{% endtab %}

{% tab title="Using templates" %}
Reference a template from any item config with the `template` key. Fields defined directly on the item override those inherited from the template.

```yaml
items:
  filler:
    slots: [0-8]
    template: filler

  navigation:
    slots: 26
    template: next-page
    display-name: "<aqua>Next page >"   # Overrides the template display-name
```

{% endtab %}
{% endtabs %}

### GUI settings

Each GUI file has a `settings` block that controls its core behavior.

```yaml
settings:
  title: "<gold>My GUI"
  rows: 6  # 1–6
  # Any other field can be override from shared.yml
  
  # trim-lore: true
  # force-reopen: false
  # refresh-interval: 20
  # input-type: DIALOG
  open-actions:
    - "[sound] block.note_block.pling 1 1"
  close-actions:
    - "[message] <gray>Goodbye!"
```

### Creating your own GUI

You can create your own GUIs by adding `.yml` files anywhere inside the `guis/` folder. Each file is automatically loaded and registered using its path as the ID.

```
guis/
├── shared.yml          < Shared defaults, action shortcuts and templates
├── my_menu.yml         < A GUI with id "my_menu"
└── example/
    └── my_menu_2.yml   < A GUI with id "example/my_menu_2"
```

## Items

### Fields

<table data-search="false"><thead><tr><th>Field</th><th>Description</th></tr></thead><tbody><tr><td><code>slots</code></td><td>Accepts a single number, a list, or a range string.</td></tr><tr><td><code>material</code></td><td>Accepts vanilla material name, namespaced key, custom hook id, or player head value.</td></tr><tr><td><code>display-name</code></td><td>Supports MiniMessage formatting and PlaceholderAPI.</td></tr><tr><td><code>lore</code></td><td>Supports MiniMessage formatting and PlaceholderAPI.</td></tr><tr><td><code>amount</code></td><td>The stack size of the item. Defaults to <code>1</code>.</td></tr><tr><td><code>glow</code></td><td>Applies an enchantment glow effect to the item without showing any enchantment in the tooltip.</td></tr><tr><td><code>hide-tooltip</code></td><td>Hides the item's tooltip entirely when hovering.</td></tr><tr><td><code>unbreakable</code></td><td>Marks the item as unbreakable.</td></tr><tr><td><code>custom-model-data</code></td><td>Sets a custom model data value on the item, used for resource pack overrides.</td></tr><tr><td><code>item-model</code></td><td>Sets the item model using a namespaced key.</td></tr><tr><td><code>tooltip-style</code></td><td>Sets a custom tooltip style using a namespaced key.</td></tr><tr><td><code>item-flags</code></td><td>A list of item flags to apply. <a href="https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/inventory/ItemFlag.html">Click here</a> to see all available flags.</td></tr><tr><td><code>enchants</code></td><td>A list of enchantments to apply in <code>enchant_id:level</code> format.</td></tr><tr><td><code>damage</code></td><td>Sets the durability damage on the item.</td></tr><tr><td><code>leather-color</code></td><td>Sets the dye color of leather armor using a hex color code.</td></tr><tr><td><code>potion-color</code></td><td>Sets the color of a potion bottle using a hex color code.</td></tr><tr><td><code>cooldown</code></td><td>Per-item click cooldown in seconds. Prevents the player from clicking the item again until the cooldown expires.</td></tr><tr><td><code>cooldown-message</code></td><td>Optional message sent to the player when they click an item with cooldown. Use <code>%timeout%</code> for the remaining time.</td></tr><tr><td><code>template</code></td><td>Inherits all fields from a shared template. Fields defined directly on the item override the template.</td></tr><tr><td><code>actions</code></td><td>Maps click types to a list of actions to run when the item is clicked. See <a href="#actions">Actions</a> for more information.</td></tr><tr><td><code>priority</code></td><td>Defines conditional overrides. See <a href="#priorities">Priorities</a> for more information.</td></tr><tr><td><code>animation</code></td><td>Defines a frame-based animation for the item. See <a href="#animations">Animations</a> for more information.</td></tr></tbody></table>

### Actions

#### Types

The `actions` map accepts the following click type keys:

<table data-search="false"><thead><tr><th>Key</th><th>Trigger</th></tr></thead><tbody><tr><td><code>left</code></td><td>Left click</td></tr><tr><td><code>right</code></td><td>Right click</td></tr><tr><td><code>left-shift</code></td><td>Shift + left click</td></tr><tr><td><code>right-shift</code></td><td>Shift + right click</td></tr><tr><td><code>shift</code></td><td>Either shift click (alias for both shift variants)</td></tr><tr><td><code>drop</code></td><td>Drop key (Q)</td></tr><tr><td><code>control-drop</code></td><td>Ctrl + drop</td></tr><tr><td><code>number</code></td><td>Number key</td></tr><tr><td><code>offhand</code></td><td>Swap to offhand</td></tr><tr><td><code>any</code></td><td>Fallback for any unmatched click type</td></tr></tbody></table>

#### References

<table data-search="false"><thead><tr><th>Action</th><th>Description</th></tr></thead><tbody><tr><td><code>[close]</code></td><td>Closes the current GUI.</td></tr><tr><td><code>[refresh]</code></td><td>Re-renders the current GUI for the player.</td></tr><tr><td><code>[message]</code> <code>message</code></td><td>Sends a MiniMessage-formatted chat message to the player.</td></tr><tr><td><code>[player]</code> <code>command</code></td><td>Runs a command as the player (without <code>/</code>).</td></tr><tr><td><code>[console]</code> <code>command</code></td><td>Runs a command from the console.</td></tr><tr><td><code>[broadcast]</code> <code>message</code></td><td>Broadcasts a MiniMessage-formatted message to all online players.</td></tr><tr><td><code>[sound]</code> <code>key</code> <code>volume</code> <code>pitch</code></td><td>Plays a sound to the player.</td></tr><tr><td><code>[actionbar]</code> <code>message</code></td><td>Sends a MiniMessage-formatted action bar message.</td></tr><tr><td><code>[title]</code> <code>'message'</code> <code>&#x3C;fadeIn:#></code> <code>&#x3C;stay:#></code> <code>&#x3C;fadeOut:#></code></td><td>Sends a MiniMessage-formatted title to the player.</td></tr><tr><td><code>[subtitle]</code> <code>message</code></td><td>Sends a MiniMessage-formatted subtitle to the player (inherits timings from <code>[title]</code>).</td></tr><tr><td><code>[bossbar]</code> <code>'message'</code> <code>&#x3C;duration:#></code> <code>&#x3C;color:TYPE></code> <code>&#x3C;overlay:TYPE></code> <code>&#x3C;progress:#></code> <code>&#x3C;countdown:BOOL></code></td><td>Displays a MiniMessage-formatted boss bar to the player. <a href="/pages/pGNnNzc6Y2199p4OzrUr#less-than-bossbar-greater-than">Click here</a> for more information.</td></tr><tr><td><code>[requirement]</code> <code>value</code> <code>operator</code> <code>value</code></td><td>Acts as a gatekeeper. If the requirement condition fails, all subsequent actions in the current click list are cancelled. <a href="/pages/Kc92kvvtBEvPDkyIJRGl#operators">Click here</a> for more information.</td></tr><tr><td><code>[delay]</code> <code>ticks</code> <code>action</code></td><td>Delays execution of the specified action by the given number of ticks (20 ticks = 1 second).</td></tr></tbody></table>

{% hint style="warning" %}
Additional action references may be available depending on the plugin. Refer to the specific plugin's documentation for the full list.
{% endhint %}

### Priorities

The priority system lets you define conditional visual and behavioral overrides for an item. Tiers are checked in ascending order; the first tier whose conditions all pass is applied.

If no priority matches, the item falls back to its base state.

Every field from an item config can be overridden inside a priority tier, including `material`, `display-name`, `lore`, `glow`, `animation`, `template`, `actions`, and more. Only fields explicitly set in the tier will override the base; everything else is inherited.

Conditions are evaluated as strings. See [Conditions](/docs/global-features/conditions.md) for more information.

```yaml
items:
  status-item:
    slots: [13]
    material: BARRIER
    display-name: "<red>Access Denied"

    priority:
      - conditions:
          - "%player_has_permission_myplugin.admin% == true"
        material: NETHER_STAR
        display-name: "<gold>Admin Panel"
        actions:
          left:
            - "[player] myplugin admin"

      - conditions:
          - "%player_has_permission_myplugin.vip% == true"
        material: EMERALD
        display-name: "<green>VIP Area"
        lore:
          - "<gray>Exclusive access."
```

### Animations

Items can cycle through a series of frames, each overriding specific fields. Animations are configured under the `animation` key of any item or priority tier.

```yaml
items:
  animated-icon:
    slots: [4]
    material: STONE
    glow: true
    animation:
      interval: 10      # Ticks between frame advances
      loop: true        # Loop back to frame 0 after the last frame
      frames:
        - material: RED_STAINED_GLASS_PANE
          display-name: "<red>Frame 1"
          # glow: false
        - material: YELLOW_STAINED_GLASS_PANE
          display-name: "<yellow>Frame 2"
        - material: GREEN_STAINED_GLASS_PANE
          display-name: "<green>Frame 3"
```

Each frame can override any field from base item. Unset fields are inherited from the item's resolved base state.

## Examples

{% tabs %}
{% tab title="Example 1" %}

```yaml
example-1:
  slots: 49
  material: BARRIER
  display-name: "<red>Close"
  lore:
    - "<gray>Click to close this menu."
  amount: 1
  glow: false
  hide-tooltip: false
  unbreakable: true
  custom-model-data: 1001
  item-model: "myserver:gui/close"
  tooltip-style: "myserver:default"
  item-flags:
    - HIDE_ATTRIBUTES
  enchants:
    - "sharpness:3"
  damage: 0
  cooldown: 2
  cooldown-message: "<red>Wait <white>%timeout% before clicking again."
  actions:
    left:
      - "[sound] ui.button.click 1 1"
      - "[close]"
    right:
      - "[sound] ui.button.click 1 1"
      - "[message] <gray>Left-click to close."
    any:
      - "[sound] ui.button.click 0.5 1"
```

{% endtab %}

{% tab title="Example 2" %}

```yaml
example-2:
  slots: [1, 2, 5-8]
  # Fallback shown when no priority matches.
  # If empty, item won't be rendered.
  
  # material: IRON_BARS
  # display-name: "<gray>Locked Feature"
  # lore:
  #   - ""
  #   - "<red>Requires VIP rank."
  #   - ""
  #   - "<dark_gray>Purchase VIP at store.myserver.com"
  # cooldown: 5
  # cooldown-message: "<red>Wait <white>%timeout%</white> before clicking again."
  priority:
    - conditions:
        - "%player_has_permission_myserver.vip% == true"
        - "%player_level% >= 10"
      material: NETHER_STAR
      display-name: "<gold>VIP Feature"
      lore:
        - ""
        - "<gray>Exclusive to VIP members."
        - ""
        - "<yellow>Left-click to use."
        - "<yellow>Shift-click for info."
      glow: true
      actions:
        left:
          - "[sound] ui.button.click 1 1"
          - "[player] vipfeature use"
          - "[message] <green>Feature activated!"
          - "[bossbar] '<green>VIP Feature activated!' <duration:100> <color:PINK> <overlay:NOTCHED_6> <progress:0.75> <countdown:true>"
          - "[actionbar] <gold>VIP Feature used!"
        left-shift:
          - "[sound] item.book.page_turn 1 1"
          - "[player] vipfeature info"
    - conditions:
        - "%player_has_permission_myserver.vip% == true"
      material: GOLD_INGOT
      display-name: "<yellow>Feature"
      lore:
        - ""
        - "<gray>Unlock more at Level 10."
        - ""
        - "<yellow>Click to use."
      actions:
        left:
          - "[sound] ui.button.click 1 1"
          - "[player] vipfeature use"
          - "[message] <green>Feature activated!"
        any:
          - "[sound] ui.button.click 0.5 1
```

{% endtab %}

{% tab title="Example 3" %}

```yaml
example-3:
  slots: [1, 3, 4-5, 9-15, 19]
  material: GRAY_DYE
  display-name: "<gray>Offline"
  lore:
    - ""
    - "<gray>Status: <red>Inactive"
    - "<gray>Balance: <white>$%vault_eco_balance_fixed%"
    - ""
    - "<dark_gray>Activate a rank to unlock."
  glow: false
  unbreakable: true
  item-flags:
    - HIDE_ATTRIBUTES
  custom-model-data: 2001
  item-model: "myserver:gui/status_orb"
  tooltip-style: "myserver:status"
  cooldown: 10.5
  cooldown-message: "<red>Wait <white>%timeout%</white> before clicking again."

  # Base animation - plays when no priority matches.
  # Each frame can override material, display-name, lore, glow, hide-tooltip,
  # custom-model-data, item-model, etc. Unset fields inherit from the item.
  animation:
    interval: 20  # Ticks between frames
    loop: true
    frames:
      - material: GRAY_DYE
        display-name: "<gray>Offline"
      - material: GRAY_DYE
        display-name: "<dark_gray>Offline"

  priority:
    - conditions:
        - "%player_has_permission_myserver.mvp% == true"
      material: MAGENTA_DYE
      display-name: "<light_purple>MVP Active"
      lore:
        - ""
        - "<gray>Status: <light_purple>MVP"
        - "<gray>Balance: <white>$%vault_eco_balance_fixed%"
        - ""
        - "<yellow>Click to claim daily reward."
      glow: true
      # Priorities can define their own animation, overriding the base one entirely
      animation:
        interval: 10
        loop: true
        frames:
          - material: MAGENTA_DYE
            display-name: "<light_purple>MVP Active"
          - material: PURPLE_DYE
            display-name: "<dark_purple>MVP Active"
      # Priorities can also define their own actions, overriding the base ones
      actions:
        left:
          - "[sound] entity.experience_orb.pickup 1 1"
          - "[requirement] %statistic_days_played% >= 1"  # Must have played at least a day
          - "[console] dailyreward claim %player_name%"
          - "[message] <green>Daily reward claimed!"
          - "[actionbar] <green>Reward added to your inventory!"
          - "[title] '<green>Reward Claimed' <fadeIn:20> <stay:40> <fadeOut: 20>"
          - "[subtitle] <gray>Come back tomorrow!"
          - "[broadcast] <gold>%player_name% <gray>claimed their daily reward!"
          - "[refresh]"
        right:
          - "[sound] ui.button.click 1 1"
          - "[player] rankinfo mvp"
        left-shift:
          - "[sound] ui.button.click 1 1"
          - "[player] rewards history"
    - conditions:
        - "%player_has_permission_myserver.vip% == true"  # Checked if tier 0 fails
      material: LIME_DYE
      display-name: "<green>✦ VIP Active"
      lore:
        - ""
        - "<gray>Status: <green>VIP"
        - "<gray>Balance: <white>$%vault_eco_balance_fixed%"
        - ""
        - "<yellow>Click to claim daily reward."
      glow: true
      animation:
        interval: 15
        loop: true
        frames:
          - material: LIME_DYE
            display-name: "<green>VIP Active"
          - material: GREEN_DYE
            display-name: "<dark_green>VIP Active"
      actions:
        left:
          - "[sound] entity.experience_orb.pickup 1 1"
          - "[requirement] %statistic_days_played% >= 1"  # Cancels further actions if fails
          - "[console] dailyreward claim %player_name%"
          - "[message] <green>Daily reward claimed!"
          - "[actionbar] <green>Reward added to your inventory!"
          - "[title] '<green>Reward Claimed' <fadeIn:20> <stay:40> <fadeOut: 20>"
          - "[subtitle] <gray>Come back tomorrow!"
          - "[refresh]"
        right:
          - "[sound] ui.button.click 1 1"
          - "[player] rankinfo vip"
        left-shift:
          - "[sound] ui.button.click 1 1"
          - "[player] rewards history"
        middle:
          - "[actionbar] <gray>Status: <green>VIP"
        drop:
          - "[message] <gray>Your rank: <white>%rank%"
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://airdevelopment.gitbook.io/docs/global-features/guis.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.