Better Pearl's v1.1

Vanilla ender pearls do not check whether the destination is inside a solid block. That single omission is the root of every pearl glitch your players are using right now. Wall-clipping, ceiling-warping, door-phase, stasis-chamber exploits, cannon-boosted bypass, and a dozen other techniques that require zero client modifications.

BetterPearls replaces that missing infrastructure with a production-grade ender pearl management system. Every teleport is validated against the actual collision geometry. Every exploit path is closed. Every mechanic is configurable, per-world overridable, and hot-reloadable - all from a single YAML file.



◆ Anti-Glitch Engine

• Full BoundingBox collision check at the teleport destination - rejects any overlap with solid geometry
• Ceiling exploit raycast traces the full flight path from eye level, not just the impact point
• Small-hitbox fallback catches carpet, pressure plates, tripwire hooks, and similar thin blocks
• Stasis chamber detection removes pearls that haven't moved for N consecutive ticks

◆ Pearl Behavior Control

• Configurable self-damage and entity-damage independently, with post-teleport immunity ticks
• Permission-based cooldown tiers - each player gets the lowest value they qualify for
• Horizontal and vertical distance limits, each with an independent bypass permission
• Endermite spawning fully disabled or set to a configurable percentage chance

◆ Cross-Pearl System

• Pearls landing on slabs, stairs, chests, fences, and other partial blocks teleport through to the far side
• Configurable block lists for crit-blocks, diagonal-blocks, cross-pearl-blocks, and pass-through blocks
• Safe landing detection with optional refund when no destination is found

◆ Anti-Cannon System

• Cancels pearls whose launch velocity exceeds a configurable threshold
• Normal player throw: ~1.5 blocks/tick. Cannon-boosted: 10+ blocks/tick. Set the line anywhere.
• Optional refund keeps the pearl in inventory when blocked

◆ Liquid & Safety Handling

• Cancel teleport when pearl lands in water and/or lava - configured independently
• Cross-world teleport prevention and world border enforcement
• Pearl refund on any safety cancel - returns the item to inventory
• Max lifetime hard cap (default 600 ticks) acts as a universal safety net

◆ HUD & Feedback

• Animated BossBar cooldown with configurable color and style - counts down in real time
• Action bar cooldown display as an alternative - customizable format with {time} placeholder
• Configurable particle burst at destination (any Bukkit Particle type and count)
• Separate arrival sound and throw sound, each independently configurable
• Pearl trail particles along the flight path - choose type, count, and interval

◆ Advanced Mechanics

• Entity teleport: pearl that hits a living entity teleports thrower directly to its location
• Pearl reflection: blocked pearls reflect the player back toward their origin instead of a plain cancel
• Surface pearl: players with permission auto-teleport to the surface (optionally only from underground)
• Teleport warmup: configurable delay before teleport, cancellable on move or damage
• Velocity multiplier: scale pearl launch speed globally (0.5x, 1.0x, 2.0x, etc.)
• Max pearls in flight: limit active pearls per player - prevents spam
• Block while gliding and block while in vehicle - two independent restrictions
• Cooldown on respawn: applies a pearl cooldown the moment a player respawns
• Refund on explosion: returns pearl if destroyed by TNT or creeper blast

◆ Data & Persistence

• Per-player statistics: pearls thrown, total damage dealt - auto-saved every 5 minutes
• Pearl audit log: every teleport logged with timestamp, player, and exact coordinates
• Whitelist system: bypass all restrictions - persists across restarts
• bStats analytics, fully optional, toggle in config.yml

◆ Multi-Language Support

• 6 built-in languages: English, German, Spanish, French, Polish, Russian
• All messages support & color codes via MiniMessage-compatible formatting
• Language switch is a single line in config.yml - /bp reload picks it up instantly

◆ PlaceholderAPI Integration

• 9 per-player placeholders: thrown, damage, cooldown, cooldown max, cooldown remaining, is on cooldown, pearls in flight, damage dealt, damage self
• Optional hook - enable or disable in config.yml

• PvP servers Glitch-free pearl combat. No wall-clips, no ceiling-warps, no door-phases. Anti-cannon keeps cannon-boosted pearls under control. Cross-pearl adds skill-based through-block shots.
• Survival and SMP Prevent base-raiding via pearl glitches. Stasis chamber detection stops infinite pearl hover exploits. World border enforcement keeps players inside the map.
• Anarchy and semi-anarchy Choose your own rules. Disable all restrictions for a true anarchy world, enable everything for a moderated one. Per-world overrides let you run both from one config.
• Network owners Drop BetterPearls into any game mode running Paper 1.21. Single-command install, full reload support, no restarts needed for config changes. Per-world overrides work across all your worlds.

◆ Commands


◆ Permissions