Better Pearl's v1.0

BetterPearls

Ender pearl control - engineered to the last block.





Your players are glitching through walls right now.
While you read this, someone on your server is pearling through a door, a fence, or a glass pane.
BetterPearls closes every one of those gaps - without compromise.

◆ The Problem Every Server Owner Knows

Vanilla ender pearls are a design relic. The teleport logic does not check whether the destination is inside a solid block - it trusts that it isn't. That trust is exactly what griefers, duelists and base-raiders exploit every day.

You've seen it: a player pearls into a base through the wall. A raider pearls through a locked iron door. A duelist one-shots from behind cover because the pearl warped them through geometry. Chat fills with "admin this is broken" - and they're right.

These are not edge cases. They are standard techniques, well-documented in PvP communities, that require zero client modifications to execute. Every server running vanilla pearl behavior is vulnerable to all of them simultaneously.

The problem isn't your rules. It's missing infrastructure.

BetterPearls replaces that missing infrastructure with a complete, production-tested ender pearl management system. Anti-glitch geometry checks, permission-based cooldown tiers, stasis chamber detection, per-world rule inheritance, PlaceholderAPI statistics, and a full audit log - all in one plugin, all configurable from a single YAML file.



◆ What BetterPearls Delivers

◈ Anti-Glitch Engine

The most thorough ender pearl collision system available for Paper servers. Three independent checks fire in sequence at the moment of teleport - if any one of them triggers, the teleport is cancelled, the player is notified, and (if configured) the pearl is refunded.

1. Full BoundingBox collision check. At the exact moment of teleport, BetterPearls queries the precise collision shape of every block at the destination using Paper's native BoundingBox API - not a simple block type check. If the player's body overlaps any solid geometry, the teleport is rejected cleanly, instantly, and without server-side desync.
2. Ceiling exploit raycast fix. The infamous "ceiling clip" - where a pearl lands on top of a block and warps the player through it from below - is caught by tracing the flight path from the player's eye level rather than only the impact point. The destination is redirected to a safe position before the teleport fires.
3. Small-hitbox passable-block coverage. A secondary raycast handles edge cases involving blocks with passable geometry: carpet, pressure plates, tripwire hooks, and similar thin blocks. These blocks do not have a full bounding box but can still create inconsistent teleport destinations. Nothing slips through.

◈ Pearl Behavior Control

Full control over every aspect of how ender pearls behave on your server. Each setting is per-world overridable - survival and PvP arenas can run completely different rules from one config file.

1. Configurable damage - self and others independently. pearl-damage-self controls how many HP the thrower loses on landing (default 5.0, i.e. 2.5 hearts). pearl-damage-other controls damage dealt to entities the pearl passes through (default 2.0). Set either to 0 to disable entirely. pearl-immunity-ticks grants brief post-teleport immunity to prevent instant re-damage.
2. Permission-based cooldown tiers. The default cooldown is set in pearl-cooldown (seconds). Additional tiers are defined under permission-cooldowns - each entry maps a permission node to a cooldown value. The player always receives the lowest value they qualify for. VIP: 0.25s. Staff: 0s. No extra code required.
3. Distance limits - horizontal and vertical separately. max-distance caps the horizontal throw range in blocks. max-y-distance caps the vertical (Y-axis) component independently. Stops sky-bridge pearling and cliff-drop cheese in one config line each. Set to 0 to disable the limit.
4. Endermite control. Set disable-endermites: true to suppress endermite spawning completely. Or set disable-endermites: false with a custom endermite-chance percentage (0-100) for a configurable spawn rate.
5. Cross-world block. prevent-cross-world: true cancels pearls that would carry a player between dimensions via portals. Pearl travel stays within the world it was thrown in.
6. World border enforcement. prevent-outside-border: true automatically cancels any pearl landing outside the world border. Players cannot use pearls to bypass border restrictions.
7. Pearl refund on cancel. When refund-on-cancel: true, any pearl cancelled by a safety check (glitch prevention, distance limit, WorldGuard, border) is returned to the player's inventory. Non-creative players never lose the item unfairly.

◈ Cooldown BossBar

The BossBar cooldown display is one of the features players notice most. It appears immediately above the health bar when a pearl is thrown and counts down in real time - no chat messages, no action bar clutter, no guessing how long is left.

1. Animated progress bar. The bar empties smoothly over the cooldown duration using scheduled ticks. The visual fill is proportional to remaining time.
2. Fully configurable appearance. Choose any BarColor (PINK, BLUE, RED, GREEN, YELLOW, PURPLE, WHITE) and any BarStyle (SOLID, SEGMENTED_6, SEGMENTED_10, SEGMENTED_12, SEGMENTED_20). The bar automatically disappears when the cooldown expires.
3. Enable or disable globally. Set cooldown-bossbar.enabled: false to revert to chat-message cooldown notifications.

◈ Liquid & Stasis Handling

Two categories of pearl exploit that most plugins ignore entirely: liquid destinations and stasis chambers.

1. Water cancel. cancel-on-water: true blocks teleportation when the pearl lands in water. Prevents players from using water bodies as guaranteed-safe landing zones that bypass glitch checks. Configurable per world.
2. Lava cancel. cancel-on-lava: true blocks teleportation into lava. Prevents pearl-into-lava exploits on PvP servers. Default enabled.
3. Stasis chamber detection. A "pearl stasis chamber" is a contraption that keeps a pearl alive indefinitely, allowing instant long-distance teleportation on demand. BetterPearls detects stasis by tracking velocity over consecutive ticks: if a pearl's velocity magnitude drops below stasis-velocity-threshold for stasis-still-ticks consecutive ticks while its owner is online, the pearl is automatically removed. No permanently floating entities. No lag machines. No exploit.
4. Max lifetime hard cap. max-ticks-alive sets an absolute ceiling on how long any pearl can exist (default 600 ticks = 30 seconds). This fires independently of stasis detection and acts as a universal safety net. Set to 0 to disable.

◈ Teleport Particles & Sound

Every successful ender pearl teleport triggers a configurable visual and audio event at the destination.

1. Particle burst. Controlled by teleport-particle.type (any Bukkit Particle enum name, e.g. PORTAL, FLAME, WITCH) and teleport-particle.count. Set enabled: false to disable.
2. Teleport sound. pearl-sound accepts any Bukkit Sound enum name. Defaults to ENTITY_ENDERMAN_TELEPORT. Use NONE to disable audio entirely.

◈ Administration & Moderation

1. Per-world configuration with full inheritance. Global settings are defined at the top level of config.yml. Any setting can be overridden for a specific world under world-overrides - only the keys that differ need to be listed. No duplication. A survival world and a PvP arena can run completely different cooldowns, distances, and damage values from a single file.
2. World disable list. disabled-worlds is a list of world names where the plugin is completely inactive. Useful for creative or event worlds.
3. Pearl log. When pearl-log.enabled: true, every successful teleport is appended to plugins/BetterPearls/logs/pearl-teleport.log with a timestamp, player name, and exact from/to coordinates. The file is written append-only and is thread-safe. Full moderation audit trail with zero configuration overhead.
4. Whitelist bypass. Players on the BetterPearls whitelist bypass all plugin restrictions - cooldown, distance limits, glitch checks, liquid checks, and WorldGuard. Add players via /bp whitelist add or grant the betterpearls.whitelist.manage permission. Whitelist state persists across restarts.
5. Thread-safe per-player statistics. BetterPearls tracks pearls thrown, total damage dealt, and damage received per player. Stats are persisted to stats.yml and auto-saved every 5 minutes. Viewable in-game with /bp stats or /bp stats (requires betterpearls.stats.others).
6. WorldGuard integration. BetterPearls reads WorldGuard's native ENDERPEARL region flag automatically when WorldGuard is installed. Regions with the flag set to DENY block pearl entry without any additional configuration. Enable or disable the hook with hooks.worldguard: true/false.
7. Hot-reload. /bp reload reloads the config file, the active language file, the whitelist, and all manager state without restarting the server. Changes take effect immediately.

◈ PlaceholderAPI Integration

When PlaceholderAPI is installed, BetterPearls exposes per-player placeholders for use in scoreboards, tab lists, chat formats, holograms, and HUD plugins.

1. %betterpearls_thrown% — total pearls thrown by the player
2. %betterpearls_damage_dealt% — total pearl damage dealt to others
3. %betterpearls_damage_self% — total pearl self-damage received
4. %betterpearls_cooldown% — remaining cooldown in seconds (0 when ready)

All values are thread-safe and updated in real time. Enable or disable the hook with hooks.placeholderapi: true/false.

◈ Language Support

BetterPearls ships with full translations in English (lang_en.yml) and Polish (lang_pl.yml). Every player-facing message - cooldown notifications, block messages, stat displays, command output - is defined in the language file and supports color codes.

To add a custom language: drop a lang_xx.yml file in the lang/ folder and set language: xx in config.yml. Hot-reload picks it up without restart.



◆ Commands

All commands use the /betterpearls root with the alias /bp.

1. /bp help — shows the help menu with all available subcommands
2. /bp reload — reloads config, language file, whitelist and all state · requires betterpearls.reload (default: op)
3. /bp stats — view your own pearl statistics (thrown, damage dealt, active cooldown) · requires betterpearls.stats (default: all players)
4. /bp stats — view another player's statistics · requires betterpearls.stats.others (default: op)
5. /bp whitelist add — add a player to the bypass whitelist · requires betterpearls.whitelist.manage (default: op)
6. /bp whitelist remove — remove a player from the whitelist
7. /bp whitelist list — list all whitelisted players

Tab-completion is supported for all subcommands and player name arguments.



◆ Permissions

1. betterpearls.reload — reload the plugin · default: op
2. betterpearls.stats — view own pearl stats · default: true
3. betterpearls.stats.others — view other players' stats · default: op
4. betterpearls.bypass.cooldown — bypass the pearl cooldown entirely · default: false
5. betterpearls.bypass.distance — bypass the max-distance limit · default: false
6. betterpearls.whitelist.manage — add or remove players from the whitelist · default: op
7. betterpearls.cooldown.vip — example permission-based cooldown tier (configurable in config.yml) · default: false
8. betterpearls.cooldown.staff — example permission-based cooldown tier (0s by default) · default: false

◆ Configuration Overview

The full config.yml is generated on first run with inline comments on every option. Key sections:

[SPOILER=config.yml (abbreviated)]

# Language: en or pl (or your custom lang_xx.yml)
language: en

# Worlds where BetterPearls is fully disabled
disabled-worlds: []

# Per-world overrides - any top-level key can be overridden here
world-overrides:
  world_pvp:
    pearl-cooldown: 1.0
    max-distance: 80
    cancel-on-water: true

# Endermites
disable-endermites: true
endermite-chance: 0          # Used when disable-endermites: false

# Damage
pearl-damage-self: 5.0       # HP (2.0 = 1 heart)
pearl-damage-other: 2.0
pearl-immunity-ticks: 10     # Post-teleport damage immunity

# Cooldown
pearl-cooldown: 0.5          # Seconds
permission-cooldowns:
  betterpearls.cooldown.vip: 0.25
  betterpearls.cooldown.staff: 0.0

# Anti-glitch / safety
max-distance: 0              # 0 = unlimited
max-y-distance: 0            # 0 = unlimited
max-ticks-alive: 600         # Pearl lifetime cap (ticks)
prevent-cross-world: true
prevent-outside-border: true
refund-on-cancel: true

# Stasis chamber detection
stasis-still-ticks: 40
stasis-velocity-threshold: 0.001

# Liquid handling
cancel-on-water: false
cancel-on-lava: true

# Particles
teleport-particle:
  enabled: true
  type: PORTAL
  count: 20

# BossBar cooldown display
cooldown-bossbar:
  enabled: true
  color: PURPLE            # PINK BLUE RED GREEN YELLOW PURPLE WHITE
  style: SOLID             # SOLID SEGMENTED_6 SEGMENTED_10 SEGMENTED_12 SEGMENTED_20

# Pearl audit log
pearl-log:
  enabled: false           # Writes to logs/pearl-teleport.log

# Soft dependency hooks
hooks:
  worldguard: true
  placeholderapi: true

[/SPOILER]



◆ Installation

[LIST=1]Ensure your server runs Paper 1.21+ and Java 21.Drop BetterPearls.jar into your plugins/ folder.Start or restart the server. config.yml, stats.yml and the lang/ folder are generated automatically.(Optional) Install WorldGuard 7.x for region-based pearl blocking.(Optional) Install PlaceholderAPI 2.11+ for scoreboard and HUD placeholders.Edit plugins/BetterPearls/config.yml to match your server's rules.Run /bp reload to apply changes without restarting.
[/LIST]

No database setup. No API keys. No external dependencies beyond the optional soft-deps.



◆ How It Compares

Most pearl plugins fix one thing - usually the cooldown - and call it done.

1. Anti-glitch (BoundingBox)? Most plugins reject the teleport via event cancel with no geometry check. BetterPearls checks the exact collision shape of every block at the destination. ✔
2. Ceiling exploit? Virtually no other plugin addresses this. BetterPearls raycasts from eye level and redirects. ✔
3. Per-world rules? Full inheritance model - define once, override what you need. Most plugins offer global config only. ✔
4. Cooldown display? Chat messages. BetterPearls uses an animated BossBar. ✔
5. Stasis detection? Not handled elsewhere. Velocity threshold + consecutive tick tracking, configurable. ✔
6. Stats + PlaceholderAPI? Thread-safe, persistent, complete. ✔
7. Audit trail? Timestamped log file with full location data on every teleport. ✔
8. Language support? Drop-in lang files, Polish and English included. ✔
9. Pearl refund on block? Player always gets the item back when the safety check fires. ✔

◆ Who This Is Built For

BetterPearls is the right fit if you operate:

1. Survival or Semi-Vanilla servers where pearl exploits break immersion and economy
2. PvP or Faction servers where a single glitch translates directly to unfair kills and player loss
3. RPG or Economy servers where base integrity depends on physics being honest
4. Networks running multiple gamemodes under one umbrella - per-world config was designed for you

This is not a plugin for mini-game servers that replace vanilla pearls with custom item mechanics. If you need full item replacement, look elsewhere. Honesty is part of the product.



◆ Frequently Asked Questions

Does this work on Spigot?
No. BetterPearls uses Paper-exclusive APIs for BoundingBox collision and scheduling. Paper 1.21+ is required.

Does it work on Folia?
Folia support is handled through a FoliaUtil compatibility layer bundled in the plugin. Basic functionality works; please report any issues via the discussion tab.

Can I add my own language?
Yes. Create lang_xx.yml in the lang/ folder using the existing files as a template, set language: xx in config.yml, and run /bp reload.

Will the whitelist survive a restart?
Yes. The whitelist is persisted to disk and loaded on startup.

Does the pearl log affect performance?
The log writer is asynchronous and append-only. File I/O does not occur on the main thread.

What happens if WorldGuard is not installed?
The WorldGuard hook is soft-dependent. If WorldGuard is absent, the hook is silently disabled and all other features function normally.

Can different worlds have different cooldowns?
Yes. Use world-overrides in config.yml to set any per-world value, including pearl-cooldown.