Effect File Structure

How to Create Custom Effects

In BeaconPlus, every effect (like Speed, Flying, or Particle Trails) has its own file in the effects/ folder. You can create as many as you want. You could have a "Cheap Speed" effect and a separate "VIP Speed" effect.

This guide shows you exactly how to write these files.

---

The Blueprint (Full Example)

The best way to learn is to copy an existing file. Here is a complete example of a Super Speed effect. It has 2 Levels, costs money to upgrade, and even checks if you are a VIP.

Copy this into a new file called super_speed.yml:

# 1. VISUAL SETTINGS (How it looks in the menu)
Display Name: "&b&lSuper Speed"
Description:
  - "&7Run like the wind!"
  - "&7"
  - "&7Level 1: &fSpeed I"
  - "&7Level 2: &fSpeed II (VIP Only)"
  - "&7"
  - "&eClick to upgrade!"

# The icon shown in the GUI
Item:
  type: SUGAR
  meta:
    custom-model-data: 1

# 2. THE LEVELS (The progression path)
Levels:

  # --- LEVEL 1 ---
  - Description: "&7Basic fast walking."
    
    # how much "Energy" this drains from the beacon
    Power Consumption: 10
    
    # What it costs to buy this level
    Cost:
      vault: 1000.0  # $1000 money
      experience: 5  # 5 XP Levels
      
    # The actual magic powers given
    Effects:
      - Type: POTION_EFFECT
        Effect: SPEED
        Amplifier: 0    # Speed I
        Duration: "15s"

  # --- LEVEL 2 ---
  - Description: "&7Super fast sprinting!"
    
    Power Consumption: 20
    
    # Requirement to buy: Must have 'vip' permission
    Upgrade Condition:
      Type: HAS_PERMISSION
      Permission: "rank.vip"
      
    Cost:
      vault: 5000.0
      
    Effects:
      - Type: POTION_EFFECT
        Effect: SPEED
        Amplifier: 1    # Speed II
        Duration: "15s"

---

Breaking Down the Structure

1. The Header (Visuals)

This top section controls how the effect appears inside the Beacon Menu.

• Display Name: The big bold title. Use & color codes.
• Description: The lore text. You can add as many lines as you want.
• Item: The icon. You can use any Minecraft material (like DIAMOND_SWORD or SUGAR).

2. The Levels

An effect can have 1 level, or 100 levels. You list them in order.

• Power Consumption: Beacons have a "Budget". If a beacon has 100 Power (from a small pyramid) and this effect costs 20, the player has 80 left for other things. This prevents players from turning on every single effect at once.
• Cost: This is the price to unlock the level permanently.
  • vault: Costs server money.
  • experience: Costs XP Levels (not points).
  • item: Costs physical items (e.g. DIAMOND: 64).

3. The Powers (Effects List)

This is where the magic happens. Under Effects:, you list what the beacon actually does.

• Combinations: You can list multiple effects here! You could make a "Tank Level 1" that gives Resistance AND Fire Resistance at the same time.
• See the Guide: To know what to write here (like POTION_EFFECT or FLY), look at the All Beacon Effects guide.

---

Advanced: Modes (Selection Menus)

Sometimes, you want a level to offer a choice. For example, a "Particle Pack" effect where the player buys the pack, but then chooses which particle to show.

Instead of Effects:, you use Modes:.

Levels:
  - Description: "&7Unlock the Particle Pack!"
    Cost:
      vault: 500
      
    # Instead of "Effects", we define choices
    Modes:
    
      # Choice A: Love Hearts
      HEARTS:
        Description: "Show heart particles"
        Effects:
          - Type: GLOW
            Color: RED
            
      # Choice B: Stormy
      THUNDER:
        Description: "Show angry clouds"
        Effects:
          - Type: GLOW
            Color: DARK_GRAY

When a player upgrades to this level, they wont get an effect immediately. Instead, clicking the icon opens a Sub-Menu where they can toggle between "Hearts" and "Thunder".