Effect File Structure

Effect File Structure (Advanced Reference)

This document is the Comprehensive Technical Reference for BeaconPlus effect configuration. It details every supported key, data type, and parsing rule found in the plugin source code.

Key Rule: Configuration keys are Confirmtory Case-Sensitive. Follow the casing exactly as shown below.

---

1. Root Structure

The root of the file (effects/name.yml) defines the effect's identity and global settings.

Key	Type	Required	Description
Display Name	String	Yes	The title of the effect in the GUI. Supports legacy (&) color codes.
Description	List<String>	No	The lore description shown in the GUI.
Enabled	Boolean	No	Defaults to true. If false, the effect is completely disabled and hidden.
Item	Map	Yes	Defines the icon item (Material, Meta, etc.).
Levels	List<Map>	Yes	The list of upgrade tiers. Index 0 is Level 1.

---

2. Item Configuration

Used in the root Item field and any Cost that uses physical items. Note: Keys in this section are lowercase.

Key	Type	Description
type	String	Material name (e.g. DIAMOND_SWORD). Supports legacy ID:Data but modern names are preferred.
amount	Integer	Stack size. Defaults to 1.
meta	Map	Standard Bukkit ItemMeta serialization.

Meta Configuration

The meta map supports standard Bukkit serialization keys:

• display-name: String (Color codes supported).
• lore: List<String>.
• custom-model-data: Integer (1.14+).
• ItemFlags: List<String> (e.g. HIDE_ATTRIBUTES, HIDE_ENCHANTS).
• Enchantments: Map<Enchantment, Level> (e.g. DURABILITY: 3).
• Potion: (For potions) Color (RGB) or PotionType.

---

3. Level Configuration (BeaconTier)

Each entry in the Levels list represents one tier of the effect.

Key	Type	Description
Description	String	A specific description for this level's icon in the menu.
Power Consumption	Integer	The amount of "Energy" this level consumes from the beacon's capacity.
Cost	Map	The price to unlock this level permanently.
Condition	EntityCondition	Requirements to ACTIVATE the effect (e.g., specific world, time, holding item).
Upgrade Condition	EntityCondition	Requirements to PURCHASE the upgrade (e.g., permission, experience level).
Max Active Modes	Integer	(Advanced) If using Modes, how many can be active at once. Default: 1.
Default Mode	String	(Advanced) The ID of the mode enabled by default.
Default Modes	List<String>	(Advanced) List of IDs enabled by default (for multi-mode).
Effects	List<Effect>	Simple Mode (Legacy): The list of effects to apply.
Modes	Map<String, Mode>	Advanced Mode: A map of selectable sub-effects.

3.1 Cost Map

The Cost map supports dynamic keys registered by Economy Services.

• Vault: Money (Requires Vault plugin).
• Exp: XP Levels.
• Emerald: Custom Item Economy (if configured in main config).
• Item: Physical Items (Uses specific Item parsing).
• Any other key registered in config.yml under Economy.

3.2 Conditions (EntityCondition)

Both Condition and Upgrade Condition support these keys. See proper Conditions List for types.

• Type: The condition ID (e.g. HAS_PERMISSION, POWER_REQUIREMENT).
• Negate: Boolean (Default: false). Inverts the logic.
• Specific Fields: Each type has its own fields (e.g. Permission string).

---

4. Modes vs. Effects

A Level can operate in one of two ways.

A. Simple Mode (Standard)

The effect just "works". It has one set of logic. Use the Effects list directly in the Level.

Effects:
  - Type: POTION_EFFECT
    Effect: SPEED

B. Advanced Modes (Selectable)

The player must choose a specific sub-variation (e.g., Particle Color). Use the Modes map. Keys are arbitrary IDs (e.g. RED_MODE, BLUE_MODE). Each Mode entry supports:

• Description: Shown in the selection GUI.
• Power Consumption: Overrides the tier consumption if set.
• Condition: Specific condition for this mode.
• Effects: The list of effects for this mode.

Modes:
  RED:
    Description: "Red Particles"
    Effects:
      - Type: PARTICLE
        Particular: REDSTONE
        Color: "255,0,0"
  BLUE:
    Description: "Blue Particles"
    Effects:
      - Type: PARTICLE
        Particular: REDSTONE
        Color: "0,0,255"

---

5. Example: Exhaustive Configuration

This standard "Furnace" level demonstrates all major features working together.

  - Description: "&7Super Furnace I"
    Power Consumption: 10
    
    # COST SYSTEM
    Cost:
      Vault: 1000.0
      Exp: 5
      Emerald: 10  # Custom Economy
      
    # PURCHASE REQUIREMENT
    Upgrade Condition:
      Type: HAS_PERMISSION
      Permission: "beaconplus.furnace.1"
      
    # ACTIVATION REQUIREMENT (Must have 10+ Power)
    Condition:
      Type: POWER_REQUIREMENT
      Minimum: 10
      
    # LOGIC
    Effects:
      - Type: FURNACE_BOOST
        Speed Up Time: 20  # Ticks to remove
        Fuel Speed Up Time: 5