Effect File Structure

Effect File Structure (Advanced Reference)

This guide details every supported key, data type, and parsing rule for BeaconPlus effect configuration.

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. Configuration Blueprint

Copy this template to create new effects. Every field is explained in the comments.

# ==========================================
# BEACONPLUS EFFECT CONFIGURATION BLUEPRINT
# ==========================================

# [Required] The name shown in the GUI. Supports color codes (&).
Display Name: "&bEffect Name"

# [Optional] The lore description in the GUI.
Description:
  - "&7Description Line 1"
  - "&7Description Line 2"

# [Optional] Set to false to hide this effect entirely.
Enabled: true

# [Required] The icon used in the main menu.
Item:
  type: DIAMOND_SWORD
  meta:
    display-name: "&bEffect Name"
    item-flags:
      - HIDE_ATTRIBUTES

# [Required] The list of upgrade levels (Tiers).
Levels:

  # ----------------------------------------
  # LEVEL 1 configuration
  # ----------------------------------------
  - Description: "&7Level I"  # Shown on the icon for this level
    Power Consumption: 10     # How much beacon power this uses
    
    # [Optional] Cost to UNLOCK this level
    Cost:
      vault: 1000.0   # Money
      exp: 5          # XP Levels
      # item: ...     # Physical items (see Item Config)

    # [Optional] Requirements to ACTIVATE the effect (e.g. must be night time)
    Condition:
      Type: WORLD_WHITELIST
      World List:
        - "world"
    
    # [Optional] Requirements to BUY this level (e.g. permission)
    Upgrade Condition:
      Type: HAS_PERMISSION
      Permission: "beaconplus.effect.1"

    # [Standard Mode] The logic to run
    Effects:
      - Type: POTION_EFFECT
        Effect: SPEED
        Amplifier: 0  # Speed I

  # ----------------------------------------
  # LEVEL 2 (Advanced Mode Example)
  # ----------------------------------------
  - Description: "&bLevel II"
    Power Consumption: 30
    Cost:
      vault: 5000.0
    
    # [Advanced] Mode Selection System
    # Users pick 'RED' or 'BLUE' instead of just getting an effect.
    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"