Beacon yml

Beacon.yml Reference Guide

The beacon.yml file controls scanning mechanics, range calculations, and vanilla beacon overrides.

---

1. Beacon Scanning Mechanics

When a BeaconPlus beacon activates, it performs a search for blocks beneath it to determine its power level.

The Scanning Process

1. Vertical Search: The plugin scans layers starting from the block directly below the beacon down to the Max Scan Height.
2. Layer Analysis: For each layer L (where L=1 is the layer immediately below), it checks a square area of (2*L + 1) x (2*L + 1).
3. Power Accumulation: Every block found in this area is checked against the Power Sources list. If it matches, its assigned power value is added to the beacon's total.

Scanning Logic Flags:

• Perfect Pyramid Structure:
  • If Enabled: The plugin requires every single block in a layer to be a valid power source before it counts that layer toward the "Level" (for level-based conditions). If a single block is missing, the scan stops for that beacon.
  • If Disabled: The plugin simply tallies the power of every valid block it finds, regardless of holes in the pyramid.
• Beam Through Sky:
  • Requires the beacon block to have a clear line of sight to the sky.
• Ignore Beam In Nether:
  • Proactive Note: Since the Nether has a bedrock ceiling, this flag allows beacons to function despite having no sky access.

Caution

Performance Precaution: Setting Max Scan Height above 6 or 7 can lead to significant tick spikes whenever a pyramid is recalculated (such as when a block is placed or broken nearby). Most server owners should stick to 6.

---

2. Range Mathematics

BeaconPlus allows you to determine how "Radius" is derived from "Power". Choice of mode completely changes your server's meta.

Mode: EXPONENTIAL

Calculates range based on a power law.

• Formula: Range = (Power ^ Exponent) (clamped by Min/Max).
• Use Case: Best for servers where you want high-tier beacons to feel significantly larger than low-tier ones.
• YAML Example:

  Mode: EXPONENTIAL
  Exponential:
    Exponent: 0.5 # Square root of power
    Min Range: 10
    Max Range: 100

Mode: PERCENTILE

A simple linear multiplier.

• Formula: Range = (Power * (Percentage / 100)) (clamped by Min/Max).
• Use Case: Predictable, steady growth.
• YAML Example:

  Mode: PERCENTILE
  Percentile:
    Percentage: 100 # 1 power = 1 block radius
    Min Range: 20
    Max Range: 150

Mode: CLASSIFIED

A manual lookup table for specific power milestones.

• Mechanics: The plugin checks the current power against the defined classes and picks the highest one reached.
• YAML Example:

  Mode: CLASSIFIED
  Classified:
    "0": 10   # 0 power = 10 blocks
    "100": 50 # 100 power = 50 blocks
    "500": 200

---

3. Power Source Management

Power sources are the blocks used to build the beacon pyramid.

• Logic: The value provided is per block. A layer 1 pyramid has 9 blocks. An Iron Block with power: 1 provides 9 power total.
• Multiplier Strategy: You can encourage exploration by making rare blocks much more powerful.

YAML Example:

Power Sources:
  IRON_BLOCK: 1
  GOLD_BLOCK: 2
  DIAMOND_BLOCK: 4
  EMERALD_BLOCK: 5
  NETHERITE_BLOCK: 20 # Encourages high-effort pyramids

---

4. Beacon Item & Interaction

This section controls how physical beacon items are handled in the world.

Pick-Up & Breaking

• Auto Pick Up: Prevents "item entities" from dropping on the ground. The beacon goes directly into the inventory.
• Cancel If Inventory Full: A safeguard to prevent players from "losing" their expensive beacon if they break it with a full inventory.

Custom Recipes

You can override the vanilla beacon recipe or add your own.

YAML Example:

Beacon Item:
  Recipes:
    Main:
      Shape:
        - "GGG"
        - "GSG"
        - "OOO"
      Ingredient:
        G: GLASS
        S: NETHER_STAR
        O: OBSIDIAN

---

5. Vanilla Integration & Overrides

Proactively managing how BeaconPlus sits alongside vanilla Minecraft.

• Disable Vanilla:
  • If True: Vanilla beacons no longer show their default GUI or provide default effects. They effectively become BeaconPlus beacons.
• Disable Recipe: Removes the vanilla beacon recipe from the crafting table. Use this if you want players to obtain beacons through special means (shops, bosses).

---

6. Proactive Performance Precautions

1. Beacon Particles: While Beacon Particle looks cool, having 50 beacons in one area with dense particles can cause client-side FPS drops for your players.
2. Tracking: Enable Beacon Tracking is required for the /beacon list. If you have thousands of beacons, this tracking database can grow large over time.
3. Area Types: The Beacon Area Type (e.g., CYLINDER vs SPHERE) determines the math used for effect application. INFINITE_CYLINDER is the fastest because it ignores the Y-axis.
4. Lookup Offline Players: In the Access List section, keeping this true allows better user management but can cause minor delays if your server's connection to Mojang APIs is slow.

---

7. Configuration Blueprint

Copy this template to your beacon.yml.

# ==========================================
# BEACON MECHANICS CONFIGURATION BLUEPRINT
# ==========================================

# ----------------------------------------
# 1. SCANNING MECHANICS
# ----------------------------------------
# How many layers below the beacon to check?
Max Scan Height: 6

# Logic Flags
Perfect Pyramid Structure: true   # If true, layers must be full to count
Beam Through Sky: true            # If true, needs sky access
Ignore Beam In Nether: true       # Allow beacons under the nether roof

# ----------------------------------------
# 2. RANGE CALCULATOR
# ----------------------------------------
Range Calculator:
  # Power Source Strategy:
  # REMAINING_POWER (Budget) or TOTAL_POWER (Raw)
  Power Source: REMAINING_POWER
  
  # Mode: PERCENTILE, EXPONENTIAL, CLASSIFIED
  Mode: EXPONENTIAL

  # [PERCENTILE] Radius = Power * (Percentage / 100)
  Percentile:
    Min Range: 0
    Percentage: 100
    Max Range: 500

  # [EXPONENTIAL] Radius = Power ^ Exponent
  Exponential:
    Min Range: 0
    Exponent: 0.9
    Max Range: 500
    
  # [CLASSIFIED] Fixed range per power level
  Classified:
    '0': 10
    '100': 50

# ----------------------------------------
# 3. POWER SOURCES
# ----------------------------------------
# Block Material : Power Value provided
Power Sources:
  IRON_BLOCK: 1
  GOLD_BLOCK: 2
  DIAMOND_BLOCK: 4
  EMERALD_BLOCK: 5
  NETHERITE_BLOCK: 20

# ----------------------------------------
# 4. BEACON ITEM SETTINGS
# ----------------------------------------
Beacon Item:
  Auto Pick Up: true
  Cancel If Inventory Full: true
  Creative No Dupe: true

  # Custom Item Look
  Display:
    type: BEACON
    meta:
      display-name: "&a{beacon_title}"
      lore:
        - "&7A powerful beacon."

# ----------------------------------------
# 5. VANILLA OVERRIDES
# ----------------------------------------
Vanilla Beacon Item:
  Disable Vanilla: false   # Replaces vanilla GUI
  Disable Recipe: false    # Removes vanilla crafting recipe