GUI Reference

GUI Reference & Customization Mastery

The BeaconPlus GUI system is designed for maximum flexibility. You can redesign every menu, change every item, and control the visual flow of information. This document provides a deep, proactive guide for server owners to build the perfect interface.

---

1. The Layout Grid System

BeaconPlus uses a character-based grid to define inventory layouts.

How it Works

• Rows: Each line in the Layout list in gui.yml represents one row of the inventory (9 slots).
• Columns: Each character in the line corresponds to one slot (1-9).
• Mapping: The plugin scans the Items section for a Layout Key that matches the character used in the grid.

Grid Math

• Standard Minecraft inventories have rows of 9.
• If you provide 3 lines of layout, the inventory will be 27 slots (chest size).
• If you provide 6 lines, it will be 54 slots (double chest).

Proactive Design Tip:

Use "Filler" items (like glass panes) to create clean layouts. By using characters like G and mapping them to a simple glass pane, you can "bridge" the gaps between functional buttons.

YAML Example:

Menus:
  Beacon:
    Layout:
      - GGGGGGGGG
      - G  B  B G  # Two effects separated by space
      - GGGGGGGGG

---

2. Menu Transitions & Visual Flow

Transitions add flavor but can impact the player experience.

Animation Modes

• SLIDE: Items move from one side to the other.
• DISSOLVE: Items are replaced in a "pixelated" pattern.
• EXPAND: Items grow from the center.
• RANDOM: Picks one of the above.

Performance Precautions:

• Client Lag: Players with very old computers or slow internet might experience "flickering" during complex transitions (DISSOLVE).
• Server Processing: Transitions are handled by the plugin's internal GUI manager. While highly optimized, opening a 54-slot menu with a RANDOM animation every single second (by many players) adds a small overhead.
• Recommended: Keep transitions Enabled: true for a premium feel, but use Animation: SLIDE or EXPAND for the best balance of looks and performance.

---

3. The Functional Key Lexicon

These keys in gui.yml -> Items are "Magic". They are hardcoded to specific functions.

Key	Menu	Core Function
B	Beacon	The Effect Item. Displays the current level and status of a registered effect.
A	Upgrade	Activate/Toggle. The main button to turn an effect level ON or OFF.
E	Upgrade	Level Upgrade. Standard button to purchase the next tier using Vanilla Levels.
D	Upgrade	Vault Upgrade. Purchase button for Money.
F	Upgrade	Item Upgrade. Purchase button for specialized items (e.g. Emeralds).
O	Upgrade	Mode Selection. Opens the menu to choose between modes in a tier.
M	Modes	Mode Entry. Individual buttons for each selectable mode.
S	Beacon	Settings. Shortcut to the Beacon Settings sub-menu.
L	Beacon	Language. Shortcut to choose a different UI language.
V	Beacon	Access List. Opens the Whitelist/Blacklist manager.
Z	Access	List Entry. Displays a player or team on the list for removal.
W	Access	Mode Toggle. Switches between Whitelist and Blacklist.
N / Y	Access	Add Player / Add Team. Triggers the input prompts for additions.
J	All	Back. Returns to the parent menu.
I / P	Pageable	Navigation. Next Page / Previous Page buttons.

---

4. Multi-State Item Configuration

Many functional items change their look based on the beacon's state.

• Activated / Deactivated: For B and A keys.
• Enabled / Disabled: For purchase buttons (based on if the player has enough currency).
• Level Too Low: Shown if a player tries to activate a tier they haven't bought yet.
• Player / Team / Empty: For the access list entries.

Proactive Advice: Always ensure your Deactivated or Disabled states are visually distinct (e.g., using GRAY_DYE instead of LIME_DYE) so players understand why a click might not be working.

---

5. Exhaustive Placeholder Lexicon

Placeholders can be used in Title, Name, or Lore.

Global & Player Context

• {player}: Name of the person looking at the GUI.
• {language.name}: Name of the currently selected language.

Beacon Context (Main Menu)

• {beacon_title}: The custom name of the beacon.
• {beacon_power}: Total power generated by the pyramid.
• {beacon_free_power}: Power remaining after subtracting active costs.
• {beacon_used_power}: Total power consumed by active effects.
• {beacon_range}: The effective radius in blocks.
• {power_source_list}: A formatted list of blocks and their power contributions.

Effect & Level Context (Upgrade/Mode Menus)

• {effect_name}: Display name of the effect being viewed.
• {effect_description}: General effect description.
• {effect_level}: The highest level the player has reached.
• {effect_selected_level}: The level currently toggled active.
• {effect_max_tier}: Maximum possible level for this effect.
• {level_description}: The specific description of the level tier.
• {level_power_consumption}: How much power this level costs to run.
• {upgrade_cost_list}: Formatted breakdown of requirements for the next level.
• {not_affected_reason_list}: If a player isn't receiving the effect, this lists why (e.g. "No Permission", "Not Whitelisted").

Access List Context

• {access_list_mode}: "Whitelist" or "Blacklist".
• {access_entry_name}: Name of the entry being displayed.
• {access_entry_type}: "Player" or "Team".
• {access_entry_provider}: The source (e.g. WorldGuard, Factions).