All Beacon Effects

Beacon Effects Configuration Manual

This document provides an exhaustive technical reference for the configuration, behavior, and implementation of all beacon effects available within the BeaconPlus ecosystem. It is intended for server administrators and system integrators who require precise control over effect mechanics. Be advised that this document serves strictly as a configuration manual; it does not offer gameplay advice or strategic consulting.

1. Potion Effect Configuration

Type Identifier: POTION_EFFECT

The Potion Effect module serves as the primary mechanism for applying vanilla Minecraft status effects to entities. It operates by interfacing directly with the server's internal potion registry, allowing for the application of any registered effect type to valid targets within the beacon's radius.

Functional Description

The beacon operates on a scheduled tick cycle. During each cycle, the system performs a spatial scan of the defined radius to identify all entities that match the beacon's target criteria (e.g., players, specific mobs).

Upon identifying a valid target, the system retrieves the entity's current active potion effects. It compares the configured effect with the entity's existing state.

Absence Check: If the entity does not currently possess the effect, the beacon applies it immediately using the configured Amplifier and Duration.
Intensity Check: If the entity already possesses the effect, the system compares the Amplifier (level) of the existing effect against the beacon's configured level. If the beacon's level is lower than or equal to the existing level, the application is skipped to prevent overriding a more potent buff (e.g., a Potion of Strength II drank by the player).
Duration Check: If the beacon's level is higher, or if the logic permits extension, the effect is re-applied to refresh its duration.

This logic ensures that beacons act as endless sources of effects without disrupting the utility of consumable potions that might offer superior, albeit temporary, benefits.

Configuration Parameters

Effect

Defines the specific potion type to be applied. The value acts as a key to lookup the effect in the server's registry.

Status: Required
Format: String (Case-Insensitive)
Scope: Accepts all vanilla potion types. Common examples include SPEED (movement speed), FAST_DIGGING (mining speed), INCREASE_DAMAGE (melee damage), HEAL (instant health), JUMP (jump height), REGENERATION (health recovery), FIRE_RESISTANCE (fire immunity), WATER_BREATHING (oxygen preservation), INVISIBILITY (rendering suppression), NIGHT_VISION (gamma correction), WEAKNESS (damage reduction), POISON (periodic damage), WITHER (periodic decay damage), SLOW (movement reduction), SLOW_FALLING (gravity reduction), LEVITATION (upward velocity), LUCK (loot table modifier), DOLPHINS_GRACE (swim speed), CONDUIT_POWER (underwater vision/speed).
Validation: Invalid names will result in a console error and the effect failing to load.

Amplifier

Defines the intensity level of the potion effect. Minecraft uses a zero-indexed integer system for levels.

Status: Optional
Default: 0 (Level I)
Format: Integer
Zero (0): Corresponds to "Level I" in gameplay terms.
One (1): Corresponds to "Level II".
Two (2): Corresponds to "Level III".
Mechanics: Higher amplifiers linearly or exponentially increase the potency of the effect depending on the specific potion type. For example, JUMP level 1 allows jumping 1.5 blocks, while level 2 allows 2.5 blocks. FAST_DIGGING increases mining speed by 20% per level.

Duration

Defines the length of time the effect remains active on the entity after each application cycle. This does not determine how long the beacon runs, but rather how long the effect lingers on the player.

Status: Optional
Default: 320 ticks (16 seconds)
Format: Time String (e.g., "15s" for 15 seconds, "200t" for 200 ticks).
Continuity: To achieve a seamless experience where the effect never flickers, the Duration must be significantly longer than the beacon's update interval. If the beacon updates every 2 seconds, a duration of "5s" provides a 3-second safety buffer against server lag.
Flickering: A duration set exactly equal to the update interval will cause the effect to visually disappear for one tick before reappearing, causing screen flashing.

Hidden Effect

Defines a nested potion effect that is applied implicitly without showing particles or icons.

Status: Optional
Format: Nested Configuration Section (Same structure: Effect, Amplifier, Duration...)
Usage: Useful for stacking effects where only one should be visible to the client.

Ambient

Toggles the rendering style of the potion particles.

Status: Optional
Default: true
Format: Boolean (true / false)
True: Particles are rendered as "Ambient". In the Minecraft client, ambient particles are more translucent and less obtrusive. This is the default state for effects provided by vanilla beacons.
False: Particles are rendered as "Normal". These are opaque and vibrant, identical to the particles emitted when a player drinks a potion or is splashed.

Particles

Controls the network transmission of particle packets.

Status: Optional
Default: true
Format: Boolean (true / false)
True: The server sends particle packets to the client. The client renders swirls around the affected entity.
False: The server suppresses particle packets. The effect is applied "silently". Note that other players will not see that the target is buffed unless they check the entity's health or speed.

Icon

Controls the visibility of the effect icon in the player's Heads-Up Display (HUD).

Status: Optional
Default: true
Format: Boolean (true / false)
True: The square buff icon is displayed in the top-right corner of the screen (or inventory screen).
False: The icon is suppressed. This allows for "Invisible" buffs that affect gameplay mechanics without alerting the player via the UI.

Remove On Leave

Determines the behavior when an entity exits the beacon's effective radius.

Status: Optional
Default: false
Format: Boolean (true / false)
True: The system intercepts the entity's exit event (or calculates it during the tick) and programmatically removes the specific potion effect. The removal is instant.
False: The system takes no action upon exit. The effect remains on the entity and persists until its remaining Duration expires naturally. This allows for "Charge Up" zones where players can stand to gain a 30-second buff and then leave to use it.

Behavioral Constraints & Edge Cases

Milk Buckets: Drinking milk clears all potion effects. The beacon will re-apply the effect on the next update tick (e.g., within 1-2 seconds).
Death: Upon death, all potion effects are cleared. The beacon will re-apply the effect when the player respawns or returns to the zone.
Max Amplifier: The Minecraft engine limits potion amplifiers to 255. Values higher than this may overflow to negative numbers or cause unintended behavior.
Incompatible Effects: Some effects override others (e.g., Night Vision vs Blindness). The beacon applies the effect regardless of conflicting effects; the client handles the visual priority.

Configuration Examples

Example A: Standard Haste Configures a standard mining buff with seamless duration and ambient particles.

- Type: POTION_EFFECT
  Effect: FAST_DIGGING
  Amplifier: 1
  Duration: "15s"
  Ambient: true
  Particles: false
  Icon: true
  Remove On Leave: true

Example B: Hidden Resistance Configures a defensive buff with absolutely no visual indicators (no particles, no icon).

- Type: POTION_EFFECT
  Effect: DAMAGE_RESISTANCE
  Amplifier: 0
  Duration: "10s"
  Ambient: true
  Particles: false
  Icon: false
  Remove On Leave: false

Example C: Environmental Wither Configures a zone that applies a detrimental effect to intruders. Usage of particles ensures the hazard is visible.

- Type: POTION_EFFECT
  Effect: WITHER
  Amplifier: 1
  Duration: "5s"
  Ambient: false
  Particles: true
  Icon: true
  Remove On Leave: false

Example D: Charging Station Configures a mechanism where players enter to gain 60 seconds of Speed, which they can take with them outside the zone.

- Type: POTION_EFFECT
  Effect: SPEED
  Amplifier: 1
  Duration: "60s"
  Ambient: true
  Particles: true
  Icon: true
  Remove On Leave: false

Example E: High-Grav Zone Configures a heavy levitation effect (Levitation 128 usually prevents movement or pulls down depending on version quirks) or generic Slowness.

- Type: POTION_EFFECT
  Effect: SLOW
  Amplifier: 3
  Duration: "5s"
  Ambient: false
  Particles: true
  Icon: true
  Remove On Leave: true

2. Immortality Field Configuration

Type Identifier: IMMORTALITY_FIELD

The Immortality Field is an event-driven protection module. Unlike periodic effects that apply buffs, this module sits dormant monitoring the Event Bus for specific conditions related to entity mortality.

Functional Description

The system registers a high-priority listener for EntityDamageEvent. When an entity within the beacon's radius takes damage, the module performs a simulation:

Damage Calculation: It calculates the final damage amount after armor, enchantments, and potion effects are processed.
Mortality Check: It compares this final damage against the entity's current health.
Intervention: If the damage is sufficient to reduce the entity's health to zero or below, the intervention protocol is initiated.
Cancellation: The damage event is cancelled (set to 0 damage).
State Reset: The entity's health is explicitly set to the configured Min Health value.

This sequence occurs within a single server tick, ensuring that the entity never actually "dies" in the engine's perspective. The "You Died" screen is never presented to the client, and inventory is not dropped.

Configuration Parameters

Min Health

Defines the exact health value set on the entity immediately after a fatal damage event is intercepted.

Status: Optional
Default: 1.0 (Half heart)
Format: Double (Floating Point Number)
Value Scale: 20.0 represents full health (standard 10 hearts). 1.0 represents half a heart.
Effect: This value is absolute. If configured to 20.0, the player instantly heals to full health upon "dying". If configured to 1.0, the player survives but is left in a critical state.

Survival Chance

Defines the probability that the intervention logic will successfully execute.

Status: Optional
Default: 100.0 (Guaranteed)
Format: Double (0.0 to 100.0)
Deterministic Logic: When a fatal event is detected, the system generates a pseudo-random number between 0.0 and 100.0. If the number is less than or equal to Survival Chance, the entity is saved. If the number is greater, the system yields, allowing the fatal damage to proceed normally.
Usage: setting this to 100.0 ensures total reliability. Lower values introduce RNG elements.

Behavioral Constraints & Edge Cases

Void Damage: Damage from the Void (Y < -64) is treated as standard damage. If the Min Health is configured, players falling into the void will repeatedly "die" and heal, effectively becoming trapped in a loop until they are teleported out or the beacon is disabled.
Kill Command: The /kill command applies damage equal to 3.4028235E38 (Max Float). The Immortality Field intercepts this damage event, effectively preventing administrative kills unless the plugin is bypassed.
Other Plugins: If another plugin cancels the damage event before the BeaconPlus listener (due to priority settings), the Immortality Field logic is skipped. Beacons act on the final calculated damage.
One-Shot Protection: Logic triggers only if FinalDamage >= CurrentHealth. It does not trigger for non-fatal damage (e.g. taking 5 hearts of damage while at 10 hearts).

Configuration Examples

Example A: Guaranteed Safety Configures a reliable safe zone where death is mathematically impossible.

- Type: IMMORTALITY_FIELD
  Min Health: 20.0
  Survival Chance: 100.0

Example B: Last Stand Configures a zone where players survive fatal damage but are left with only half a heart, emphasizing the danger.

- Type: IMMORTALITY_FIELD
  Min Health: 1.0
  Survival Chance: 100.0

Example C: Unreliable Shield Configures a zone where the protection matrix fails 50% of the time.

- Type: IMMORTALITY_FIELD
  Min Health: 10.0
  Survival Chance: 50.0

Example D: Full Restore Configures a zone that acts as an instant-resurrection point, fully healing the player.

- Type: IMMORTALITY_FIELD
  Min Health: 20.0
  Survival Chance: 100.0

3. Potion Duration Boost Configuration

Type Identifier: POTION_DURATION_BOOST

The Potion Duration Boost effect functions as a maintenance module for existing status effects. It does not generate new effects but rather detects and modifies specific effects already present on the entity.

Functional Description

On every update tick (usually once per second), the system retrieves the list of active potion effects on the target entity. It checks this list against the configured Potion Effect Type. If a match is found:

The system determines the current remaining duration of the effect in ticks.
The system adds the Duration Boost Tick value to this current duration.
The modified duration is written back to the entity.

This creates a dynamic equilibrium. If the Duration Boost Tick matches the tick rate of the beacon (e.g., adding 20 ticks every 20 ticks), the effect duration freezes. If the boost is higher, the duration grows. If lower, the duration decays slower than normal.

Configuration Parameters

Potion Effect Type

Defines the specific effect type to target for boosting.

Status: Required
Format: String
Scope: Must match a valid Minecraft potion name (e.g., NIGHT_VISION, WATER_BREATHING).
Limitation: The module targets a single effect type. To boost multiple types (e.g., Strength and Speed), multiple instances of this effect module must be configured in the beacon.

Duration Boost Tick

Defines the integer amount of ticks added to the effect's duration per cycle.

Status: Optional
Default: 0
Format: Integer
Time Scale: 20 ticks equals 1 second.
Threshold: To achieve a net increase in duration, this value must exceed the update interval of the beacon. If the beacon updates every 2 seconds (40 ticks), a value of 41 or higher is required to "charge" the potion.

Behavioral Constraints & Edge Cases

Duration Cap: The Minecraft engine caps potion duration at 32767 ticks (approx 27 minutes) in some versions, or infinite (-1) in others. The boost module respects these internal integer limits.
Missing Effects: If the target entity does not have the specified effect active, this module performs no action. It cannot create an effect, only extend an existing one.
Source Independence: The module boosts effects regardless of their source (Beacon, Potion Bottle, Suspicious Stew, Command).
Negative Boosts: It is possible to configure a negative value (e.g., -20). This causes the effect to expire faster than normal, effectively functioning as a "Cleanse" or dampening field.

Configuration Examples

Example A: Night Vision Extender Configures infinite extension for Night Vision, assuming a 1-second update cycle.

- Type: POTION_DURATION_BOOST
  Potion Effect Type: NIGHT_VISION
  Duration Boost Tick: 40

Example B: Resistance Stabilizer Configures a value ensuring Resistance potions do not expire.

- Type: POTION_DURATION_BOOST
  Potion Effect Type: DAMAGE_RESISTANCE
  Duration Boost Tick: 25

Example C: Slow Decay Water Breathing Configures an extension that slows down the expiry of Water Breathing by 50%.

- Type: POTION_DURATION_BOOST
  Potion Effect Type: WATER_BREATHING
  Duration Boost Tick: 10

Example D: Invisibility Sustainer Configures infinite extension for Invisibility.

- Type: POTION_DURATION_BOOST
  Potion Effect Type: INVISIBILITY
  Duration Boost Tick: 30

4. Flight Configuration

Type Identifier: FLY

The Flight module manipulates the player's allowFlight capability flag. This is the boolean flag used by Creative Mode to enable double-tap flight.

Functional Description

Upon every scan cycle, the beacon validates if the player is within the radius.

Entry Logic: If the player enters the radius and matches the criteria, player.setAllowFlight(true) is invoked.
Exit Logic: When the player exits the radius, or if the beacon is destroyed, the system performs a cleanup safety check. It verifies if the player is in Creative or Spectator mode. If the player is in Survival or Adventure mode, player.setAllowFlight(false) and player.setFlying(false) are invoked immediately.

The system includes an optional height delimiter to create "Ceilings" for flight within the zone.

Configuration Parameters

Height

Defines a vertical boundary relative to the beacon core's Y-coordinate.

Status: Optional
Default: -1 (Infinite Vertical Range)
Format: Integer
Negative Values: A value of -1 disables the height check logic entirely. Flight is valid at any Y-level within the horizontal radius.
Positive Values: Defines a ceiling relative to the beacon. If set to 50 and the beacon is at Y=64, flight is disabled if the player exceeds Y=114.
Enforcement: Players exceeding the height are considered "Out of Range" and will immediately lose flight capability, causing them to fall.

Behavioral Constraints & Edge Cases

Gamemode Precedence: Creative Mode and Spectator Mode grant flight intrinsically. The beacon logic respects this; it will not disable flight for Creative players upon exit, nor will it attempt to enforce flight rules on them.
Fall Damage: If a player flying high in the air exits the zone (or the beacon breaks), flight is disabled. The player falls. Standard fall damage rules apply upon impact unless other protections ( Feather Falling, Immortality Field) are present.
Velocity Retention: Players flying at high speed who exit the zone retain their momentum. They become a projectile subject to gravity.
Relogging: The flight state persistence across logout/login depends on server configuration (allow-flight=true in server.properties). The beacon re-evaluates eligibility immediately upon player login.

Configuration Examples

Example A: Unrestricted Flight Configures flight with no vertical limitations.

- Type: FLY
  Height: -1

Example B: Low Altitude Hover Configures flight limited to 10 blocks above the beacon.

- Type: FLY
  Height: 10

Example C: Skyscraper Zone Configures flight allowing access to tall structures up to 100 blocks.

- Type: FLY
  Height: 100

Example D: Ground Effect Configures flight limited to 2 blocks, effectively allowing high jumps/hovering but not true flight.

- Type: FLY
  Height: 2

5. Magnet Configuration

Type Identifier: MAGNET

The Magnet module applies a physics vector to entities within the radius, altering their trajectory. It supports both attraction and repulsion mechanics.

Functional Description

The system calculates a 3D vector from the entity's current position to the beacon's center. Vector direction = beaconLocation.toVector().subtract(entity.getLocation().toVector()).normalize(); This normalized direction vector is then multiplied by the configured Magnitude scalar. The resulting velocity is added to the entity's current velocity. This process repeats every tick, creating a smooth, continuous force.

Configuration Parameters

Magnitude

Defines the scalar strength of the velocity vector applied to the entity.

Status: Optional
Default: 0.0
Format: Double
Direction - Attraction: Positive values (e.g., 0.2) create a force pulling the entity towards the source.
Direction - Repulsion: Negative values (e.g., -0.5) create a force pushing the entity away from the source.
Intensity:
- 0.1: Gentle drift, easily resisted by walking.
- 0.5: Strong current, difficult to walk against.
- 1.0+: Extreme force, likely to launch entities violently.

Behavioral Constraints & Edge Cases

Block Collision: Entities pushed into blocks do not clip through them; they collide. Strong repulsion in a confined space can pin entities against walls, potentially causing suffocation damage if the wall logic allows it.
No-Clip Mode: Spectators and players in "No-Clip" mode are immune to velocity updates and will not be affected by the magnet.
Anticheat: Some Anti-Cheat plugins may interpret the forced velocity changes (especially "Black Hole" attraction) as movement hacks (Fly/Speed) and rubber-band the player. Configuration of the Anti-Cheat is typically required to whitelist these zones.
Item Merging: Strong attraction fields clump dropped items together into a single location. This facilitates item merging logic (optimizing performance) but may make sorting difficult.

Configuration Examples

Example A: Gentle Collection Configures a subtle pull for items.

- Type: MAGNET
  Magnitude: 0.2

Example B: Strong Defense Configures a powerful repulsion field to keep mobs away.

- Type: MAGNET
  Magnitude: -0.8

Example C: Static Field Configures a zero-magnitude field (functionally inert, possibly for visual testing).

- Type: MAGNET
  Magnitude: 0.0

Example D: Black Hole Configures an inescapable gravity well.

- Type: MAGNET
  Magnitude: 1.5

6. Spawner Boost Configuration

Type Identifier: SPAWNER_BOOST

The Spawner Boost module scans the local environment for CreatureSpawner tile entities (Mob Spawners). It directly manipulates the NBT data of these tiles to accelerate their spawn cycles.

Functional Description

Upon identifying a Spawner Tile Entity within the beacon's range, the system reads its current delay variables: SpawnDelay, MinSpawnDelay, and MaxSpawnDelay. It applies a reduction formula to these integers: NewDelay = CurrentDelay * (1.0 - (Percentage / 100.0)) If the Speed Up Percentage is 50%, a delay of 800 ticks (40 seconds) is reduced to 400 ticks (20 seconds). The system essentially compresses the timeline for the spawner logic.

Configuration Parameters

Speed Up Percentage

Defines the percentage of time removed from the vanilla spawn delay cycle.

Status: Optional
Default: 0.0
Format: Double (0.0 to 100.0)
Linear Scale:
- 10.0: 10% faster (1.11x rate).
- 50.0: 50% faster (2.0x rate).
- 75.0: 75% faster (4.0x rate).
- 90.0: 90% faster (10.0x rate).
Safety: Values approaching 100.0 result in delay values of 0 or 1, causing the spawner to attempt a spawn event on every single update tick if conditions allow.

Behavioral Constraints & Edge Cases

Spawn Cap: This module does not override the world's mob cap. If the chunk or world has reached the limit for that mob category (Monster/Animal), the spawner will attempt to spawn and fail, even if boosted.
Light Levels: The module does not override vanilla light level requirements. A Zombie spawner will not spawn if the light level is too high, regardless of how fast the tick delay is.
Player Range: Vanilla spawners require a player to be within 16 blocks to activate. The BeaconPlus boost does NOT bypass this requirement. The spawner itself must be active (spinning) for the boost to be applied.
Tile Integrity: If the spawner block is broken, the effect ceases immediately. The boost is transient and does not permanently modify the block data file; it modifies the runtime NBT of the tile.

Configuration Examples

Example A: Moderate Boost Configures a 25% reduction, providing a noticeable but safe increase.

- Type: SPAWNER_BOOST
  Speed Up Percentage: 25.0

Example B: Double Speed Configures a 50% reduction, effectively doubling the mob output.

- Type: SPAWNER_BOOST
  Speed Up Percentage: 50.0

Example C: Extreme Overclock Configures a 90% reduction.

- Type: SPAWNER_BOOST
  Speed Up Percentage: 90.0

Example D: Minimum Viable Boost Configures a 5% reduction.

- Type: SPAWNER_BOOST
  Speed Up Percentage: 5.0

7. Crops Boost Configuration

Type Identifier: CROPS_BOOST

The Crops Boost module interacts with organic blocks implementing the Ageable data interface. This includes most crops (Wheat, Carrots, Potatoes, Beetroots) and some growth blocks (Nether Wart, Cocoa, Cactus, Sugar Cane, Kelp, Bamboo).

Functional Description

The system performs a block scan of the radius. When it encounters a valid Ageable block, it retrieves its current Age integer. It increments this integer by the configured Speed Up Stage. NewAge = CurrentAge + StageIncrement If the new age exceeds the maximum age for that block type (e.g., 7 for Wheat), the age is clamped to the maximum. This simulates the effect of Bone Meal application without requiring the item.

Configuration Parameters

Speed Up Stage

Defines the integer quantity added to the crop's Age property per update interval.

Status: Optional
Default: 0
Format: Integer
Value 1: The crop advances by one growth stage.
Value 7: The crop instantly advances to maturity (if maximum is 7).

Crops Whitelist

Defines a specific list of Material types to target.

Status: Optional
Default: Empty List (Target All)
Format: String List
Filter Logic:
- If the list is Empty, the system targets ALL blocks that are Ageable.
- If the list is Populated, the system checks block.getType() against the list. Non-matching blocks are ignored.

Crops Blacklist

Defines a specific list of Material types to ignore.

Status: Optional
Default: Empty List
Format: String List
Prioritization: Blacklist is checked after Whitelist. If a crop is in both (technically impossible if logic is sound), it is ignored.

Prevent Instant Growth

Toggles safety logic for instant-break crops. Some crops rely on the specialized mechanics of growing into the block AIR above them (Sugar Cane, Cactus, Bamboo, Kelp). Force-setting their age data when they are already grown can cause the block to recognize an invalid state and break (drop as an item).

Status: Optional
Default: true
Format: Boolean (true / false)
True: The system acts conservatively. It checks if the crop is already at max age or height limit. If so, it skips the boost.
False: The system applies the boost blindly. This is aggressive and may cause automated harvesting by breaking the plant.

Growth Boost

Toggles an alternative boosting mechanism.

Status: Optional
Default: false
Format: Boolean (true / false)
Function: If enabled, the effect may utilize specific applyBoneMeal logic instead of raw data manipulation, depending on the internal implementation version. Use this if standard boosting is not working for modded crops.

Behavioral Constraints & Edge Cases

Light Requirements: Crops require light level 9+ to grow. The boost forces an age increment, but without light, the crop may "pop" (break) on the next block update.
Bonemeal Events: This effect fires StructureGrowEvent or BlockGrowEvent (depending on implementation). Other plugins protecting crops (e.g., GriefPrevention) may cancel these events if they interpret the beacon as a "FakePlayer" without permissions.
Unload Chunks: Growth logic cannot be applied to unloaded chunks. If the beacon radius extends into an unloaded area, those crops are ignored to prevent chunk thrashing.
Modded Crops: The system relies on the Bukkit Ageable interface. Modded crops that do not adhere to this standard API will not be recognized or boosted.

Configuration Examples

Example A: Wheat Specialist Configures conservative growth logic strictly for Wheat.

- Type: CROPS_BOOST
  Speed Up Stage: 1
  Prevent Instant Growth: true
  Crops Whitelist:
    - WHEAT

Example B: General Agriculture Configures rapid growth for standard food crops.

- Type: CROPS_BOOST
  Speed Up Stage: 2
  Prevent Instant Growth: true
  Crops Whitelist:
    - CARROTS
    - POTATOES
    - BEETROOTS

Example C: Industrial Bamboo Configures aggressive growth for a bamboo farm, potentially causing breaks.

- Type: CROPS_BOOST
  Speed Up Stage: 1
  Prevent Instant Growth: false
  Crops Whitelist:
    - BAMBOO

Example D: Nether Wart Farm Configures specific targeting for Nether Wart.

- Type: CROPS_BOOST
  Speed Up Stage: 1
  Prevent Instant Growth: true
  Crops Whitelist:
    - NETHER_WART

8. Keep Chunk Loaded Configuration

Type Identifier: KEEP_CHUNK_LOADED

The Keep Chunk Loaded module interacts with the server's chunk provider and ticket manager.

Functional Description

By default, Minecraft unloads chunks (segments of the world) to save memory when no players are nearby. This pauses all logic within that chunk (redstone, furnaces, growth). This module registers a persistent ticket with the server for the specified chunks. This forces the server to maintain the chunk in the memory heap and continue processing its tick logic (Redstone, Entity AI, Tile Entity logic) even in the absence of players.

Configuration Parameters

Single Chunk

Scope selector for the loading logic.

Status: Optional
Default: false
Format: Boolean (true / false)
True: The logic is applied strictly to the single 16x16 chunk containing the beacon block. This is a minimal-impact mode.
False: The logic is applied to every chunk intersected by the calculated radius of the beacon. For a large radius, this can encompass dozens or hundreds of chunks.

Load Chunk

Behavior selector for currently unloaded chunks.

Status: Optional
Default: false
Format: Boolean (true / false)
True (Active Load): If the system detects a target chunk is currently unloaded, it issues a command to load it immediately from disk.
False (Passive Sustain): The system only registers tickets for chunks that are already loaded. It keeps them loaded, but will not "wake up" a region that is currently dormant.

Behavioral Constraints & Edge Cases

Server Performance: Forcing chunks to remain loaded consumes RAM and CPU. A radius of 100 blocks contains ~169 chunks. Actively loading all of them can severely degrade server tps.
View Distance: This effect loads chunks logically for processing, but does not necessarily send them to the client if they are outside the player's view distance.
Restart Persistence: Tickets are re-applied when the plugin enables on server startup. However, there is a brief window during the boot process where chunks may be unloaded before the beacon initializes.
Plugin Conflicts: Some "Clearlag" or optimization plugins forcefully unload unused chunks. This creates a "tug of war" where the beacon loads the chunk and the optimizer unloads it, causing rapid load/unload (thrasing). BeaconPlus uses a rigid Ticket system to try and prevent this.

Configuration Examples

Example A: Local Persistence Configures persistence for the beacon's chunk only.

- Type: KEEP_CHUNK_LOADED
  Single Chunk: true
  Load Chunk: false

Example B: Area Persistence Configures persistence for the entire radius, actively loading the area.

- Type: KEEP_CHUNK_LOADED
  Single Chunk: false
  Load Chunk: true

Example C: Passive Area Hold Configures persistence for the area, but only if a player visits first to load it.

- Type: KEEP_CHUNK_LOADED
  Single Chunk: false
  Load Chunk: false

Example D: Critical Chunk Configures aggressive loading for a single critical chunk.

- Type: KEEP_CHUNK_LOADED
  Single Chunk: true
  Load Chunk: true

9. Apply Mending Configuration

Type Identifier: APPLY_MENDING

The Apply Mending module serves as an automated equipment repair station. It emulates the behavior of the "Mending" enchantment absorbing XP orbs, but uses the beacon's operation as the fuel source.

Functional Description

On every update cycle, the system iterates over the target player's inventory contents. The iteration order typically prioritizes: Main Hand -> Offhand -> Armor Slots -> Main Inventory. For each item stack encountered:

Enchantment Check: The system verifies if the item contains the Mending enchantment.
Damage Check: The system verifies if the item has current durability damage (durability > 0).
Repair Action: If both checks pass, the system reduces the damage value by the configured Mending Repair Amount. The process repeats until the repair amount for the cycle is exhausted or all items are fully repaired.

Configuration Parameters

Mending Repair Amount

Defines the quantity of durability points restored per update cycle.

Status: Optional
Default: 0
Format: Integer
Unit: 1 unit equals 1 point of durability.
Impact: Higher values result in faster repair. A Diamond Pickaxe has 1561 durability. A rate of 10 would repair it fully in roughly 156 seconds.

Behavioral Constraints & Edge Cases

XP Orbs: This effect does not consume XP orbs from the ground. It is an "Infinite Mending" source powered by the beacon.
Conflicts: If a player is wearing full Mending armor and taking damage, vanilla mechanics repair the armor using picked-up XP. The beacon repair runs in parallel to this.
Inventory Scan: Large inventories (e.g., modded backpacks) are not scanned. Only the vanilla inventory slots (0-40) are processed.
Unbreakable Items: Items tagged as Unbreakable are skipped to save processing time.

Configuration Examples

Example A: Standard Repair Configures a moderate repair rate.

- Type: APPLY_MENDING
  Mending Repair Amount: 5

Example B: Fast Repair Configures a rapid repair rate.

- Type: APPLY_MENDING
  Mending Repair Amount: 20

Example C: Trickle Repair Configures a very slow repair rate.

- Type: APPLY_MENDING
  Mending Repair Amount: 1

Example D: Instant Fix Configures a rate likely to fully repair items in one or two cycles.

- Type: APPLY_MENDING
  Mending Repair Amount: 500

10. Command Executor Configuration

Type Identifier: COMMAND_EXECUTOR

The Command Executor module acts as a trigger for server commands. This allows the beacon to interface with other plugins, scripts, or vanilla command logic.

Functional Description

When the effect is triggered (on tick), the system takes the configured command string.

Parsing: It scans the string for variables (placeholders).
Substitution: It replaces {player} with the name of the target entity.
Dispatch: It sends the final string to the server's Command Map for execution.

Configuration Parameters

Command

Defines the command syntax to be executed.

Status: Optional
Default: "" (Empty String)
Format: String
Syntax: Standard Minecraft command syntax (excluding the leading / in some contexts, though typically supported).
Placeholders:
- {player}: Resolves to the player's username.
- {uuid}: Resolves to the player's unique ID.

Console

Defines the identity of the command sender.

Status: Optional
Default: false
Format: Boolean (true / false)
True: The command is executed as the ConsoleSender. This grants the command full Operator (OP) privileges. It bypasses all permission checks.
False: The command is executed as the Player themselves. The player attempting to run the command must have the necessary permissions (e.g., if the command is gamemode creative, the player needs minecraft.command.gamemode).

Passive Command

Defines a command string executed by the beacon itself, regardless of player presence.

Status: Optional
Default: null
Format: String
Context: This command runs on every beacon tick cycle. It supports location placeholders {beacon_x}, {beacon_y}, {beacon_z}, {beacon_world}. It does NOT support {player} placeholders as it is not triggered by a player.
Executor: Always executed by Console.

Behavioral Constraints & Edge Cases

Command Spam: The effect triggers on every configured interval. Setting a command like /give on a 1-second interval will fill the player's inventory rapidly and spam the chat.
Asynchronous Safety: Commands are dispatched on the main server thread. Heavy commands (like world edits or database queries) runs on the main thread and will lag the server.
Security Risk: Granting Console: true combined with user-configurable command strings (if exposed) allows players to run /op or /stop. Ensure this effect is strictly controlled by administrators.
Target Validity: If {player} is offline (e.g., logged out exactly when the tick fired), the command will likely fail or return "Player not found".

Configuration Examples

Example A: Economy Integration Configures a monetary reward using an economy plugin command.

- Type: COMMAND_EXECUTOR
  Command: "eco give {player} 5"
  Console: true

Example B: Messaging Configures a title message sent to the player.

- Type: COMMAND_EXECUTOR
  Command: "title {player} title {\"text\":\"Welcome to the Zone\"}"
  Console: true

Example C: Teleportation Configures a forced teleport command.

- Type: COMMAND_EXECUTOR
  Command: "tp {player} 0 100 0"
  Console: true

Example D: User Action Configures the player to say something in chat.

- Type: COMMAND_EXECUTOR
  Command: "say I am at the beacon!"
  Console: false

11. Glow Configuration

Type Identifier: GLOW

The Glow module applies the GLOWING status effect/metadata to the entity. This creates a spectral outline around the entity's model, visible through solid blocks.

Functional Description

The system interacts with the entity's metadata or utilizes packet-based rendering (depending on the method) to flag the entity as glowing. This instructs the client-side renderer to draw the outline.

Configuration Parameters

Method

Defines the technical implementation for rendering the glow.

Status: Optional
Default: AUTO
Format: String (Enum)
AUTO: The system detects the server version and selects the most appropriate method.
BLOCK_DISPLAY: Utilizes BlockDisplay entities (Available in Minecraft 1.19.4+). This method provides a sharp, stable outline.
SHULKER: Utilizes legacy invisible Shulker entities riding the target. This is a workaround for older versions (1.9 - 1.12).

Behavioral Constraints & Edge Cases

Client Settings: Players can disable the "Glowing" effect in their Minecraft client accessibility settings. The beacon cannot override this preference.
Invisibility: Glowing entities that are also Invisible (Potion Effect) will show only the outline. This is standard Minecraft behavior (spectral effect).
Performance: The BLOCK_DISPLAY method spawns a packet-based entity that follows the player. While efficient, having 100+ glowing players in one area may cause client-side FPS drops.

Configuration Examples

Example A: Standard Glow Configures a standard outline using automatic detection.

- Type: GLOW
  Method: AUTO

Example B: Sharp Glow Configures a high-fidelity outline using Block Displays.

- Type: GLOW
  Method: BLOCK_DISPLAY

12. Attribute Modifier Configuration

Type Identifier: ATTRIBUTE_MODIFIER

The Attribute Modifier module temporarily alters the core attributes of players within the beacon's radius. This allows for changes to max health, attack speed, movement speed, and other generic attributes, similar to holding a powerful item.

Functional Description

Upon entering the zone, the system calculates and applies a set of AttributeModifier objects to the player. These modifiers are "Transient", meaning they are not saved to the player file and disappear on logout or when the modifier is explicitly removed (on exit).

Configuration Parameters

Modifiers

Defines the map of attributes to modify.

Status: Required
Format: Map (Key: Attribute Name, Value: List of Modifiers)
Keys: Standard Bukkit/Minecraft Attribute names (e.g., minecraft:scale, generic.max_health).

Modifier Structure

Each attribute key accepts a list containing: * Amount (Double): The value of the change. * Operation (Enum): How the math is applied. * ADD_NUMBER (Default): Adds X to base. * ADD_SCALAR: Adds X * Base to current value. * MULTIPLY_SCALAR_1: Multiplies total by (1 + X).

Behavioral Constraints & Edge Cases

Health Scaling: Increasing generic.max_health does not instantly heal the player to the new max. They will need to regenerate the empty hearts.
Speed Limits: Extremely high generic.movement_speed values can cause chunk loading issues or kick the player for flying.
Stacking: This module adds a specific UUID-based modifier. It stacks with armor and potions, but does not stack with itself (the beacon ensures only one instance of its modifier exists on the player).

Configuration Examples

Example A: Scale (Size Modification) Configures a zone that makes the player larger or smaller.

- Type: ATTRIBUTE_MODIFIER
  Modifiers:
    minecraft:scale:
      - Amount: 0.5
        Operation: ADD_NUMBER

Example B: Super Soldier Configures a zone with increased attack damage and speed.

- Type: ATTRIBUTE_MODIFIER
  Modifiers:
    minecraft:generic.attack_damage:
      - Amount: 5.0
        Operation: ADD_NUMBER
    minecraft:generic.movement_speed:
      - Amount: 0.1
        Operation: ADD_NUMBER

13. Cooldown Reduction Configuration

Type Identifier: COOLDOWN_REDUCTION

The Cooldown Reduction module intercepts item cooldown events (triggered by Ender Pearls, Chorus Fruit, Shields, etc.) and reduces the wait time.

Functional Description

When a player uses an item that triggers a cooldown, the server fires a PlayerItemCooldownEvent. This module listens for that event. If the player is in range, it calculates a new, shorter cooldown based on the configured percentage and overrides the event data.

Configuration Parameters

Cooldown Reduction Percentage

Defines the fraction of time removed from the cooldown.

Status: Optional
Default: 0.0
Format: Double (0.0 to 1.0)
Scale: 0.2 = 20% reduction. 0.5 = 50% reduction.

Behavioral Constraints & Edge Cases

Minimum: The effect guarantees a minimum cooldown of 1 tick to prevent logic errors.
Plugin Compatibility: This relies on the Paper/Spigot API event. Custom cooldown systems implemented by other plugins (using variable map storage) are NOT affected.

Configuration Examples

Example A: Rapid Fire Configures a 50% reduction for all item cooldowns.

- Type: COOLDOWN_REDUCTION
  Cooldown Reduction Percentage: 0.5

14. EXP Boost Configuration

Type Identifier: EXP_BOOST

The EXP Boost module multiplies experience orbs collected by the player.

Functional Description

This effect attaches metadata to the player. When the player picks up an Experience Orb, the event handling logic (handled elsewhere in the plugin or server) checks for this metadata and multiplies the value of the orb before it is added to the player's bar.

Configuration Parameters

Multiplier

Defines the additive multiplier factor.

Status: Optional
Default: 1.0
Format: Double
Logic: The formula is Total = Original + (Original * Multiplier).
- 0.5: Adds 50% XP (1.5x total).
- 1.0: Adds 100% XP (Double XP).
- 2.0: Adds 200% XP (Triple XP).

Behavioral Constraints & Edge Cases

Bottles of Enchantment: This effect explicitly ignores XP orbs spawned from Bottles (EXP_BOTTLE). It only boosts natural orb drops (mobs, mining).
Mending: If the player has Mending gear, the XP is used for repair first. The multiplier applies to the repair value as well.

Configuration Examples

Example A: Double XP

- Type: EXP_BOOST
  Multiplier: 1.0

15. EXP Gain Configuration

Type Identifier: EXP_GAIN

The EXP Gain module purely generates experience points for the player periodically.

Functional Description

On every update tick, the system grants the player a specific amount of Experience. It features an internal "Stash" system to handle decimal values (e.g., giving 0.5 XP/sec results in 1 XP every 2 seconds).

Configuration Parameters

Exp

Defines the amount of experience points to give per tick.

Status: Optional
Default: 0.0
Format: Double
Scale: This is raw XP points, not Levels. (Collecting one orb usually gives 1-3 points).

Behavioral Constraints & Edge Cases

AFK Farming: This effect allows for fully passive leveling. Server owners should balance this carefully.

Configuration Examples

16. Extra Power Configuration

Type Identifier: EXTRA_POWER

The Extra Power module passively increases the "Free Power" value reported by the beacon API and placeholders.

Functional Description

This effect adds a flat amount to the value returned by BeaconData#getPower(). Important Note: In the current implementation, this does not increase the beacon's Range or Fuel Buffer. It primarily serves as a way to boost the number shown in the {beacon_free_power} placeholder, which can be useful for roleplay servers or custom plugin integrations that listen to the API.

Configuration Parameters

Power

Defines the amount of power added to the calculation.

Status: Optional
Default: 10.0
Format: Double
Logic: getPower() = BasePower + EffectPower.

Configuration Examples

Example A: API Boost Adds 100 extra power units to the display value.

- Type: EXTRA_POWER
  Power: 100.0

17. Extra Range Configuration

Type Identifier: EXTRA_RANGE

The Extra Range module extends the effective radius of the beacon.

Functional Description

This effect modifies the beacon's spatial scan logic. When the beacon calculates its coverage area, it adds this configured value to its base range (determined by pyramid tier).

Configuration Parameters

Range

Defines the number of blocks added to the radius.

Status: Optional
Default: 10.0
Format: Double
Logic: FinalRadius = BaseRadius + ExtraRange.

Behavioral Constraints & Edge Cases

Chunk Loading: Significantly increasing the range will force the beacon to scan more chunks. If Keep Chunk Loaded is active, this can lead to massive performance overhead.

Configuration Examples

Example A: Long Range Broadcaster Adds 50 blocks to the radius.

- Type: EXTRA_RANGE
  Range: 50.0

18. Fire Control Configuration

Type Identifier: FIRE_CONTROL

The Fire Control module manipulates the combustion state of entities. It can be used to extinguish fires (safety) or incubate them (traps).

Functional Description

On every tick, the system modifies the entity's FireTicks property. The logic uses an additive formula: NewFireTicks = CurrentFireTicks + ConfiguredTick.

Configuration Parameters

Fire Tick

Defines the integer amount of fire ticks added per update.

Status: Optional
Default: 0
Format: Integer
Extinguish Logic: Use a negative number (e.g., -20) to reduce fire ticks. Since 20 ticks = 1 second, -20 extinguishes 1 second of fire per second.
Ignition Logic: Use a positive number to set the entity on fire or keep them burning.

Behavioral Constraints & Edge Cases

Lava: If a player is swimming in lava, the lava source constantly reapplies fire. A negative Fire Control effect effectively neutralizes the burn damage but not the lava contact damage.

Configuration Examples

Example A: Fire Suppression System Rapidly extinguishes any entities on fire.

- Type: FIRE_CONTROL
  Fire Tick: -100

Example B: Incinerator Keeps entities burning indefinitely.

- Type: FIRE_CONTROL
  Fire Tick: 20

19. Furnace Boost Configuration

Type Identifier: FURNACE_BOOST

The Furnace Boost module accelerates the operation of Furnace, Blast Furnace, and Smoker tiles within the radius.

Functional Description

The system scans for furnace tiles. When found, it manually advances the CookTime (progress bar) and BurnTime (fuel bar) forward, simulating time passing faster.

Configuration Parameters

Speed Up Time

Defines the percentage speed increase for the smelting progress.

Status: Optional
Default: 0.0
Format: Double (0.0 to 100.0)
Logic: AdvancedTime = CurrentTime + (TotalTime * (Percentage / 100)). 10.0 means the furnace completes 10% of its operation every tick.

Fuel Speed Up Time

Defines the percentage acceleration for fuel consumption.

Status: Optional
Default: Same as Speed Up Time
Format: Double
Logic: Typically, if you speed up cooking, you also speed up fuel burn to maintain balance. Setting this to 0.0 while Speed Up Time is high creates "Free Smelting" (items cook fast, fuel barely burns).

Block Type Whitelist

Defines specific furnace types to target.

Status: Optional
Default: Empty List (Target All)
Format: List of Materials (FURNACE, BLAST_FURNACE, SMOKER).

Configuration Examples

Example A: Industrial Smeltery Speeds up smelting by 5% per tick (extremely fast).

- Type: FURNACE_BOOST
  Speed Up Time: 5.0

Example B: Efficient Smelting Speeds up smelting but keeps fuel consumption normal (magic efficiency).

20. Permission Configuration

Type Identifier: PERMISSION

The Permission module temporarily grants permission nodes to players within range.

Functional Description

This effect utilizes the Bukkit Permissible system to inject "Permission Attachments" into the player's session. This allows players to access restricted features (like /fly, specialized kits, or VIP areas) only while standing near the beacon.

Configuration Parameters

Permissions

Defines the list or map of permissions to grant.

Status: Required
Format: List (String) OR Map (String -> Boolean)
List Format: ["my.node.one", "my.node.two"]. Implies true.
Map Format: {"my.node": true, "blacklist.node": false}. Allows explicitly negating a permission.

Behavioral Constraints & Edge Cases

Plugin Compatibility: Works with LuckPerms, PermissionsEx, and standard permission systems.
Security: Be careful granting admin nodes (op, *).

Configuration Examples

Example A: VIP Lounge Grants access to a region or cosmetic feature.

- Type: PERMISSION
  Permissions:
    - "essentials.fly"
    - "custom.vip.access"

21. Prevent Mob Spawning Configuration

Type Identifier: PREVENT_MOB_SPAWNING

The Prevent Mob Spawning module acts as a localized "Mega Torch", stopping natural mob spawns.

Functional Description

The system listens for EntitySpawnEvent. If the spawn location is within the beacon's radius and the entity is a LivingEntity, the event is cancelled. CRITICAL: This effect is a "Nuclear Option". It prevents ALL living entity spawns, regardless of reason. This includes:

Natural Spawns (Zombies at night)
Spawner Blocks (Dungeon Spawners)
Spawn Eggs
Commands (/summon)
Plugin Spawns (Custom Bosses)

Configuration Parameters

None: This effect has no configurable parameters.

Behavioral Constraints & Edge Cases

Non-Living: Item Frames, Armor Stands, and Dropped Items are not affected.
Existing Mobs: Mobs that walked into the zone after spawning are not removed. This only prevents new spawns.

Configuration Examples

Example A: Dead Zone Completely sterilizes the area of new biological life.

- Type: PREVENT_MOB_SPAWNING

22. Saturation Configuration

Type Identifier: SATURATION

The Saturation module maintains the player's food saturation level, effectively preventing hunger usage.

Functional Description

Saturation is a hidden float value that buffers the visible Food Bar. This effect sets that value directly.

Configuration Parameters

Saturation

Defines the saturation level to apply.

Status: Optional
Default: 0.0
Format: Double
Mechanics: High saturation results in rapid health regeneration.

Configuration Examples

Example A: Infinite Food Keeps the player fully saturated.

- Type: SATURATION
  Saturation: 20.0

23. Stupid AI Configuration (Mob Pacifier)

Type Identifier: STUPID_AI

The Stupid AI module (internally known as Mob Pacifier) disables the artificial intelligence targeting logic of creatures.

Functional Description

When active, this effect clears the "Target" of nearby mobs (Zombies, Skeletons, etc.). They will wander aimlessly but will not aggro onto players. It effectively neuters hostile mobs.

Configuration Parameters

None: This effect has no configurable parameters.

Behavioral Constraints & Edge Cases

Aggro: Mobs may briefly look at a player before "forgetting" them on the next tick.
Attacks: If a player bumps into the mob, the mob might still attack once before losing interest.

Configuration Examples

Example A: Pacifist Run

- Type: STUPID_AI