Better Pearls - Fix Ender Pearl Exploit v1.1

BetterPearls 1.1.0
Released May 10, 2026
​

What's New

15 New Optional Features

Every feature below is disabled by default and can be enabled independently in config.yml.

• Cross-pearl - pearls landing on thin blocks (slabs, stairs, fences) carry the player through to the far side. Block categories are fully configurable.
• Entity teleport - a pearl that hits a living entity teleports the thrower directly to that entity's location.
• Pearl reflection - blocked pearls reflect the player back toward their origin instead of issuing a plain cancel.
• Surface pearl - players with betterpearls.surface permission are teleported to the surface. Can be restricted to underground throws only.
• Teleport warmup - configurable delay before the teleport fires; cancelled if the player moves or takes damage.
• Cooldown action bar - alternative to the BossBar; shows remaining cooldown inline in the action bar with a configurable format.
• Velocity multiplier - scales the pearl's launch speed (1.0 = normal, 2.0 = double range).
• Max pearls in flight - limits how many active pearls a single player can have airborne simultaneously.
• Explosion refund - returns the pearl to the shooter if it is destroyed by TNT or a creeper explosion.
• Pearl trail - spawns configurable particles along the flight path.
• Block while gliding - prevents pearl throws while using elytra.
• Block while in vehicle - prevents pearl throws from inside a minecart, boat, or rideable mob.
• Cooldown on respawn - applies a cooldown the moment a player respawns, preventing instant post-death escapes.
• Pearl throw sound - plays a configurable sound at the thrower's location on launch, separate from the arrival sound.
• Anti-cannon - cancels pearls whose launch velocity exceeds a configurable threshold, blocking cannon-boosted pearls while allowing normal throws.

New Placeholders (PlaceholderAPI)

Five new placeholders added alongside the original four:

• %betterpearls_cooldown% - remaining cooldown in seconds for this player (0 when ready)
• %betterpearls_cooldown_remaining% - alias of the above
• %betterpearls_cooldown_max% - maximum cooldown for this player (respects permission tiers)
• %betterpearls_is_on_cooldown% - true or false
• %betterpearls_pearls_in_flight% - number of active ender pearls currently airborne for this player

4 New Languages

• lang_de.yml - German (Deutsch)
• lang_fr.yml - French (Francais)
• lang_es.yml - Spanish (Espanol)
• lang_ru.yml - Russian (Русский)

(lang_pl.yml was already included in 1.0 - Polish characters fully corrected in this release.)

New Permissions

• betterpearls.surface - enables surface pearl teleport for the player
• betterpearls.bypass.ydistance - bypasses the max-y-distance limit independently from the horizontal bypass

Bug Fixes

• Pearl-damage-self suppressed by immunity. pearl-immunity-ticks was incorrectly blocking the thrower's own landing damage. The immunity check now only applies when the damage source is another player's pearl.
• Invalid sound warning on startup. The default pearl-sound value used the Bukkit enum format (ENTITY_ENDERMAN_TELEPORT). Changed to Minecraft dot-notation (entity.enderman.teleport) to match the Registry lookup used internally.
• BossBar ConcurrentModificationException. Calling cancelAll() during reload or shutdown could throw a CME when iterating and removing from the active bars map. Fixed by copying the key set before iteration.
• Infinite warmup loop. WarmupManager was scheduling the teleport with TeleportCause.ENDER_PEARL, which re-triggered PlayerTeleportEvent and caused the warmup to fire again indefinitely. Changed to TeleportCause.PLUGIN.

Deprecated API Fixes

• ChatColor.translateAlternateColorCodes() - replaced with a direct & to § substitution in LangManager.
• player.sendActionBar(String) - replaced with the Adventure Component-based overload via LegacyComponentSerializer.
• getDescription().getVersion() - replaced with getPluginMeta().getVersion().
• Sound.valueOf() - replaced with Registry.SOUNDS.get(NamespacedKey) using Minecraft dot-notation format.

Upgrade Notes

• If you have an existing config.yml, update pearl-sound from ENTITY_ENDERMAN_TELEPORT to entity.enderman.teleport to avoid a startup warning. All other existing config keys are fully backwards-compatible.
• New config sections for all 15 advanced features are appended automatically on first load - existing files are not overwritten.
• The /bp reload command picks up all new config sections and language files without a restart.