GUI Reference

Customizing Menus (GUI.yml)

BeaconPlus allows you to completely redesign every menu in the plugin. You are not stuck with a hardcoded layout. You can move buttons, change their icons, add decorative glass, or even shrink the menu to a single row.

---

1. How to Design a Menu (The Layout System)

We use a "Draw it yourself" system. You literally draw the shape of the inventory using characters in the gui.yml file.

The Possibilities

• Make it compact: Use 3 rows for a clean, simple look.
• Make it grand: Use 6 rows (Double Chest size) to fit tons of information.
• The Catch: You cannot create "Scrollable" menus or exceed 6 rows (54 slots), as that is a physical limit of the Minecraft client.

Visual Example

In gui.yml, you will see a Layout section. Each character represents one slot.

Menus:
  Beacon:
    Layout:
      - "         "  # Row 1: Empty air (Space character)
      - " GGGGGGG "  # Row 2: 'G' (Glass Panes) bordering the middle
      - " G  B  G "  # Row 3: 'B' (The Beacon Effect button) in the center
      - " GGGGGGG "  # Row 4: Border
      - "         "  # Row 5: Air

In this example, the menu is 5 rows tall, with a glass box floating in the middle.

---

2. Slot Configuration Types

Each character is linked to a specific function in the Items section. Below are the verified default keys used in the plugin.

Main Menu Keys

• B Upgrade Icon: Displays the current effect. Clicking it opens the Upgrade Menu.
• S Change Language: Opens the Language Selection Menu.
• V Access List: Opens the Whitelist/Blacklist manager.
• K Info: Displays Beacon Location & Range.
• L Power Info: Displays Power usage and sources.

Upgrade Menu Keys

• A Toggle Activate: Toggles the effect ON or OFF.
• D Money Upgrade: Purchase using Server Economy (Vault).
• E XP Upgrade: Purchase using XP Levels.
• F Item Upgrade: Purchase using Items (e.g., Emeralds).
• C Upgrade Info: Displays detailed stats (Next Level, Costs).
• J Back Button: Returns to the previous menu.

Navigation Keys

• P Previous Page: Navigates left in paginated menus.
• I Next Page: Navigates right in paginated menus.

Access List Keys

• N Add Player: Prompts to type a player name to add.
• Y Add Team: Prompts to add a Party/Team (if supported).
• W Mode Toggle: Switches list between "Whitelist" and "Blacklist".
• Z The Entry: Represents a player/team currently on the list.

---

3. Customizing Button Looks

Every button is configured using a standard Item format.

Standard Item Format

You can use type, amount (default 1), and meta (display name, lore, flags, etc).

  MyButton:
    type: DIAMOND_SWORD
    amount: 1
    meta:
      display-name: "&bCool Sword"
      lore:
        - "&7Line 1"
        - "&7Line 2"
      # Optional: Hide attributes like "Attack Damage"
      ItemFlags:
        - HIDE_ATTRIBUTES
      # Optional: Custom Model Data for resource packs
      custom-model-data: 12345

Dynamic Buttons (Toggles & Upgrades)

Some buttons change based on logic. These do not use a "States" list; instead, the plugin looks for specific keys defined for that item purpose.

Toggle Buttons (e.g. Items.Toggle Activate)

• Activated: The item shown when the setting is ON.
• Deactivated: The item shown when the setting is OFF.

Upgrade Buttons (e.g. Items.Upgrade Button.Economy)

• Display: The normal item shown.
• Disabled: The item shown if the player cannot afford the upgrade.

Upgrade Info

• Display: The normal stats book.
• Maxed Display: The book shown when the effect is at max level.

---

4. Placeholders (Complete List)

You can use these placeholders in the Name or Lore of any item to display dynamic info. Note: PlaceholderAPI is also supported if installed!

General Beacon Info

Placeholder	Description
{player_name}	Name of the player viewing the menu
{player_display_name}	Display name of the player
{beacon_world}	Name of the world the beacon is in
{beacon_x}, {beacon_y}, {beacon_z}	Coordinates of the beacon block
{beacon_range}	Current effective range (e.g. "50")
{beacon_power}	Total Pyramid Power available
{beacon_used_power}	Power currently being used by effects
{beacon_free_power}	Remaining power available
{beacon_title}	The title of the beacon (Custom or Default)
{beacon_custom_name}	The custom name given to the beacon (if any)
{mode_name}	Name of the current Beacon Mode (e.g. "Public")

Effect & Level Info

Available in Upgrade Menus or Effect Icons

Placeholder	Description
{effect_name}	Display name of the effect (e.g. "Speed")
{effect_description}	Description of the effect
{effect_level}	Current level number (e.g. "1")
{effect_level_roman}	Current level in Roman numerals (e.g. "I")
{level_status}	"Activated", "Deactivated", or "Level too low"
{level_power_consumption}	How much power the current level uses
{level_description}	Description of the current level

Upgrade & Cost Info

Available in Upgrade Buttons

Placeholder	Description
{level_next_tier}	The level number you are upgrading to
{level_next_cost}	The cost amount required for the next level
{level_next_power_consumption}	Power usage of the next level
{cost}	Formatted cost string (e.g. "$500")
{economy_name}	Name of the currency/economy used (e.g. "Vault")
{economy_currency}	Currency symbol/name
{upgrade_cost_list}	List of all costs required (multi-line)

Access List & Teams

Available in Access List Menus

Placeholder	Description
{access_list_mode}	"Whitelist" or "Blacklist"
{whitelist_count}	Number of entries on the whitelist
{blacklist_count}	Number of entries on the blacklist
{access_entry_name}	Name of the player or team on the list card
{access_entry_type}	"PLAYER" or "TEAM"
{access_entry_provider}	The plugin providing the team (e.g. "Factions")

Power Sources

Available in Power Info items

Placeholder	Description
{power_source_list}	Formatted list of all power sources fueling the beacon
{beacon_power_source_name}	Name of the specific block providing power
{beacon_power_source_amount}	Number of blocks of this type
{beacon_power_source_value}	Power value per block

---

6. Item Configuration Reference

Here is the dictionary of all available Item types and how to configure them. Note: Config Keys refer to sections under Items.[ItemName]

Back Button

• Function: Returns to the previous menu.
• Config Keys:
  • Display: The item to show.

Access List Entry

• Function: Represents a player or team on the list.
• Config Keys:
  • Player: Item shown for player entries.
  • Team: Item shown for team entries (if supported).
  • Empty: Item shown for empty slots.

Access List Mode Toggle

• Function: Switches between Whitelist and Blacklist modes.
• Config Keys:
  • Whitelist: Item shown when in Whitelist mode.
  • Blacklist: Item shown when in Blacklist mode.

Add Player Button

• Function: Opens a text input to add a player to the list.
• Config Keys:
  • Display: The button item.

Add Team Button

• Function: Opens text input/selection to add a team.
• Config Keys:
  • Display: The button item.

Blacklist/Whitelist Tab

• Function: Switch tabs in the Access List GUI.
• Config Keys:
  • Active: Item shown when this tab is selected.
  • Inactive: Item shown when this tab is NOT selected.

Change Language

• Function: Opens the Language Selection Menu.
• Config Keys:
  • Display: The button item.

Configure Modes

• Function: Opens mode selection for tier-based effects.
• Config Keys:
  • Display: The button item.

Effect Entry

• Function: Represents a Beacon Effect in the selection menu.
• Config Keys:
  • Display: The item shown for available effects.
  • Not Affected: Item shown if the player doesn't have permission/conditions met.

Language Entry

• Function: Represents a language choice.
• Config Keys:
  • Display: The item (usually a flag head).

Mode Entry

• Function: Represents a mode limit (e.g. Public vs Private) for an effect.
• Config Keys:
  • Active: Item shown when this mode is ON.
  • Inactive: Item shown when this mode is OFF.

Next / Previous Page

• Function: Pagination controls.
• Config Keys:
  • Display: The arrow button.
  • No More: (Optional) Item shown when there are no more pages.

Static Item

• Function: Decorative item (like Glass Panes).
• Config Keys:
  • Display: The item.

Toggle Activate

• Function: Turns the selected effect ON or OFF.
• Config Keys:
  • Activated: Shown when effect is ON.
  • Deactivated: Shown when effect is OFF.
  • Level Too Low: Shown if beacon level is 0.

Toggle Show Animation

• Function: Toggles visual beam animations for the player.
• Config Keys:
  • Enabled: Shown when animations are ON.
  • Disabled: Shown when animations are OFF.

Toggle Beacon Particles

• Function: Toggles particles around the physical beacon block.
• Config Keys:
  • Enabled: Shown when particles are ON.
  • Disabled: Shown when particles are OFF.

Toggle Show Particles

• Function: Toggles visual effects for the player.
• Config Keys:
  • Enabled: Shown when effects are ON.
  • Disabled: Shown when effects are OFF.

Upgrade Button

• Function: Purchases a tier upgrade.
• Config Keys:
  • Display: Shown when the upgrade is affordable/available.
  • Disabled: Shown when the upgrade is too expensive or unavailable.
  • Note: These keys are nested under Items.Upgrade Button.Economy.[Provider].

Open Access List Button

• Function: Opens the Access List management GUI.
• Config Keys:
  • Display: The button item.

Upgrade Info

• Function: Displays details about the next tier.
• Config Keys:
  • Display: Shown when there is a next tier available.
  • Maxed Display: Shown when the effect is at maximum level.

---

7. Configuration Blueprint

Copy this template to your gui.yml.

# ==========================================
# MENU LAYOUT CONFIGURATION BLUEPRINT
# ==========================================

Menus:
  # ----------------------------------------
  # MAIN BEACON MENU
  # ----------------------------------------
  Beacon:
    Title: "&1{beacon_title}"
    Transition:
      Enable: true
      Animation: RANDOM
      
    # Layout Keys (Default):
    # B = Effect Icon (Items.Upgrade)
    # V = Open Access List (Items.Other Items.V)
    # K = Range/Location Info (Items.Other Items.K)
    # L = Power Info (Items.Other Items.L)
    # G = Glass (Items.Other Items.G)
    Layout:
      - " GGGGGGGGG "
      - " G       G "
      - " G K B L G "
      - " G       G "
      - " G   V   G "

  # ----------------------------------------
  # UPGRADE MENU
  # ----------------------------------------
  Upgrade:
    Title: "&1Upgrade {effect_name}"
    
    # Layout Keys (Default):
    # A = Toggle Active
    # C = Upgrade Info (Stats)
    # D = Money Upgrade
    # E = XP Upgrade
    # J = Back Button
    Layout:
      - " GGGGGGGGG "
      - " G   A   G "
      - " G C B D G "
      - " G   E   G "
      - " G   J   G "
      
# ==========================================
# ITEM DEFINITIONS
# ==========================================
Items:

  # ----------------------------------------
  # 1. NAVIGATION & FUNCTIONALITY
  # ----------------------------------------
  
  # [J] Back Button
  Back:
    Layout Key: J
    Display:
      type: ARROW
      meta:
        display-name: "&cGo Back"

  # ----------------------------------------
  # 2. UPGRADE SYSTEM
  # ----------------------------------------
  
  # [B] Effect Icon (The Icon in Main Menu)
  Upgrade:
    Layout Key: B
    Display:
      type: NETHER_STAR
      meta:
        display-name: "&b{effect_name}"
        lore:
          - "&7Level: {effect_level}"
    Not Affected:
      type: BARRIER
      meta:
         display-name: "&c{effect_name} (Locked)"

  # [A] Toggle Activate (On/Off)
  Toggle Activate:
    Layout Key: A
    Activated:
      type: LIME_DYE
      meta:
        display-name: "&a&lENABLED"
    Deactivated:
      type: GRAY_DYE
      meta:
        display-name: "&c&lDISABLED"
    Level Too Low:
      type: GRAY_DYE
      meta:
        display-name: "&cLevel too low"

  # [D, E] Upgrade Cost Buttons
  Upgrade Button:
    Economy:
      # Requires Vault
      Vault:
        Layout Key: D
        Display: 
          type: GOLD_INGOT
          meta:
            display-name: "&eUpgrade with Money"
            lore:
              - "&7Cost: {cost}"
        Disabled:
          type: BARRIER
          meta:
            display-name: "&cCannot Afford: {cost}"
      
      # Requires XP
      Level:
        Layout Key: E
        Display:
          type: EXPERIENCE_BOTTLE
          meta:
            display-name: "&aUpgrade with XP"

  # [C] Upgrade Info (Stats)
  Upgrade Info:
    Layout Key: C
    Display:
      type: BOOK
      meta:
        display-name: "&6Stats"
        lore:
          - "&7Current Range: {beacon_range}"
    Maxed Display:
      type: BOOK
      meta:
        display-name: "&6Stats (Maxed)"

  # ----------------------------------------
  # 3. ACCESS LIST (Special)
  # ----------------------------------------
  # [V] Open Access List
  # Configured in 'Other Items'
  Other Items:
    V:
      Display:
        type: WRITABLE_BOOK
        meta:
           display-name: "&dAccess List"

    # [K] Info
    K:
      Display:
        type: BOOK
        meta:
          display-name: "&eLocation Info"
          lore:
             - "Range: {beacon_range}"

    # [L] Power
    L:
      Display:
        type: BLAZE_POWDER
        meta:
          display-name: "&6Power Info"
          lore:
             - "Power: {beacon_power}"

    # [G] Glass Border
    G: 
      Display:
        type: BLACK_STAINED_GLASS_PANE
        meta:
          display-name: " "