Config yml

Config.yml Reference Guide

The config.yml file handles the global environment for BeaconPlus. This includes how currency is handled across your network, how old data is migrated, and how menus are presented to players.

---

1. Global Plugin Environment

Default Language

Sets the fallback language for your server.

• Proactive Note: Players can change their individual language in the Beacon Settings GUI. The Default Language is only used if the player hasn't made a choice yet.
• Available Codes: See the plugins/BeaconPlus/languages/ folder for valid codes (e.g., en_us).

World Aliases

Allows you to map technical world names to human-readable names.

• Technical Importance: Many placeholders ({world}) will output the raw folder name (e.g., world_nether). Aliases ensure your GUIs look professional.
• YAML Example:

  World Alias:
    world: "Overworld"
    world_the_end: "The End"
    prison_spawn_A: "Sector A"

---

2. Economy Integration Deep Dive

BeaconPlus supports multiple primary economies and unlimited custom item-based economies.

Global Properties

• Currency: The symbol or unit suffix (e.g., $, Coins, Points).
• Display Name: How the currency is labeled in the "Upgrade Cost" section of the GUI.
• Format: A template for the cost display. Supports {amount} and {economy_currency}.

Economy Providers

1. Vault (Standard Money):
   • Requirements: Needs Vault and an economy plugin (like EssentialsX or Treasury).
   • Precautions: If Vault is present but no economy plugin is found, BeaconPlus will disable this provider automatically.
2. PlayerPoints:
   • Requirements: Needs the PlayerPoints plugin.
   • Use Case: Ideal for "premium" currency integration.
3. Level & Exp:
   • Mechanics: Uses the player's vanilla experience. Level consumes whole levels; Exp consumes raw experience points.
4. Item (Material-based):
   • Mechanics: Consumes physical items from the player's inventory.
   • YAML Example (Custom Emerald Currency):

     Item:
       Emerald:
         Currency: "Emerald(s)"
         Display Name: "&aEmeralds"
         Format: "{amount}x {economy_currency}"
         Item:
           type: EMERALD

---

3. Legacy Migration Safety Protocol

If you are upgrading from BeaconPlus v2 to v3, this section is critical.

The Conversion Process

When Enable is set to true, the plugin will attempt to read your old FlatDB files and convert them into the new v3 storage format.

Precautions for Server Owners:

1. Backup Everything: Before enabling migration, ZIP your entire plugins/BeaconPlus folder.
2. Effect Mapping: v3 uses different internal IDs for effects. Use the Effect Mapping section to "translate" your old progress.
   • Example: experience: "exp_boost" tells the plugin that anyone who had the "experience" effect in v2 should now have "exp_boost" in v3.
3. One-Time Process: Migration usually runs once per player. Once a player is converted, their v2 data is essentially ignored by v3.

---

4. UI Rendering & Animations

This section controls the "fancy" visual effects when opening and navigating menus.

• Animation Types: SLIDE, DISSOLVE, EXPAND, RANDOM.
• Performance Note: These animations are purely client-side rendering (filling inventory slots with items). While extremely low impact, they can be disabled in gui.yml if your players prefer "instant" menus.
• Covers: When a menu "slides", the plugin fills the empty slots with "Cover" items. You can customize these in config.yml.

YAML Example:

Animations:
  Slide:
    Cover 1:
      type: GRAY_STAINED_GLASS_PANE
      meta:
        display-name: " "
    Cover 2:
      type: BLACK_STAINED_GLASS_PANE

---

5. Proactive FAQ Answered via Documentation

• "Can I use multiple economies for one upgrade?": No, an individual Level upgrade must be purchased with one currency type (e.g., just Emeralds). However, different effects or tiers can use different currencies.
• "What happens if a world isn't in World Aliases?": The plugin will just use the raw folder name. It won't crash or cause errors.
• "Is migration required?": No. If you are starting a fresh server, set Legacy Conversion.Enable: false to save a tiny amount of startup time.