Beacon yml

Beacon.yml Reference Guide

The beacon.yml file is the core engine configuration for BeaconPlus. It dictates how beacons scan their surroundings, how their power is calculated, and how they interact with the vanilla game. This document provides a long-form, proactive guide for server owners to master their beacon networks.

---

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.