DS-PearlFix 7.0

Ender pearls are part of the adventure. Getting stuck inside a wall should not be. DS-PearlFix helps keep pearl landings in usable space and stops shortcuts through openings a player cannot fit through, with settings you can adapt to your server.

Two checks work together: one looks at where the player will land, and the other follows the pearl through narrow openings.

• Keep players outside blocks. Safe landing checks the player’s bounding box against collision shapes around the destination. Walls, corners, ceilings and partial blocks are checked; when possible, the landing moves just enough to fit.
• Close the narrow shortcuts. Gap checks follow the pearl’s path through openings around fences, panes, bars, slabs, doors and trapdoors. The check compares available space with the configured clearance.
• Handle impossible landings. If the search cannot find a safe fit, the teleport is cancelled. Optional pearl refunds return the item outside creative mode; a full inventory drops it at the player’s location.
• Keep normal throws in play. A destination that already fits stays unchanged. The rebuilt system does not apply the old fixed throw-distance restrictions.

Recorded with an earlier build; version 7 uses a rebuilt detection system.

• Choose the checks. Enable safe landing and narrow-gap detection separately. Set the global enabled switch or exclude selected worlds.
• Set the minimum opening. Choose a Gap-Height from 0.6 to 1.8 blocks. Safe landing uses the player’s actual pose dimensions; gap detection uses your configured minimum. Scaled player sizes are taken into account.
• Give staff useful feedback. Blocked-gap alerts include the player, world and coordinates. Enable personal chat debug when investigating a throw, or use console debug for a broader view.
• Control exemptions. Grant the configurable bypass permission only where you want it. Operators do not automatically bypass pearl checks.
• Make messages fit your server. Customize the prefix and every feedback message with MiniMessage styles or legacy color codes. Set a message to an empty string to hide it.

/pearlfix status reports the active block-shape reader and the counts of checked pearls, adjusted destinations, blocked gaps and no-room cancellations. These counters are kept in memory; a plugin restart resets them.

/pearlfix debug toggles details in the requesting player’s chat. It ends when that player logs out or toggles it off. Set Plugin-Config.Debug: true for console logging; running the command from the console shows this instruction.

Pearl-Checks.Alerts notifies the console and online staff with the configured Permissions.Staff node about blocked gaps. Alerts are throttled to one per player every two seconds. No-room cancellations use their player feedback and optional debug output.

Install one server plugin and configure it in Settings.yml. Its text libraries are bundled, so it does not download additional libraries at startup.

• Server support: Spigot and Paper, Minecraft 1.13–26.3. Install on the Minecraft server. Folia and proxy support are not claimed.
• Java: use the version required by your server software. The plugin targets Java 8 bytecode; newer server versions still require their own newer Java runtime.
• Dependencies: no additional plugin is required. There is no PlaceholderAPI dependency or integration.
• Other plugins: ender pearl teleport events already cancelled by another plugin are left alone. Test your own region, combat and teleport rules together before opening the server to players.

Minecraft 1.17 and newer use the server collision-shape API. Minecraft 1.13–1.16 use reflected block collision shapes, validated at runtime. If an exact shape reader is unavailable or fails, the plugin uses a conservative bounding-box fallback. Check /pearlfix status to see which mode is active.

Safe landing checks the player’s current bounding box, including pose dimensions where the server exposes them. Older 1.13 servers use standing-size dimensions. Modern scaled players are supported. Gap-Height remains a configurable minimum for the path check rather than automatically switching with the player’s pose.

Install & configure

1. Place DS-PearlFix-7.0.jar in your server’s plugins folder and start the server.
2. Open plugins/DS-PearlFix/Settings.yml. Choose the checks, minimum gap height, excluded worlds, refunds and alerts.
3. Grant staff the command and alert permissions they need. Assign pearlfix.bypass only to players who should be exempt.
4. Run /pearlfix reload, then /pearlfix status. Use /pearlfix debug and test a few throws around your server’s important builds.

Command: /pearlfix · Aliases: /dspearlfix and /pfix. Running it without arguments shows usage; tab completion suggests the subcommands you are allowed to use.

/pearlfix reload

Default permission: pearlfix.reload OR pearlfix.admin
Reload Settings.yml and messages. Invalid YAML keeps the previous working configuration. Available to players and the console.

/pearlfix status

Default permission: pearlfix.admin
Show the plugin and Minecraft versions, active collision-shape mode and counts of checked pearls, adjusted landings, blocked gaps and no-room cancellations. Available to players and the console.

/pearlfix debug

Default permission: pearlfix.admin
Toggle pearl-check messages in your own chat until you log out or run the command again. From the console, this command explains how to enable Plugin-Config.Debug; it does not toggle console logging.

Permission names are configurable under Permissions. Status and reload are available to the console; debug toggles personal chat output only for players.

pearlfix.admin — Operator by default. Grants status, personal debug and update notices. It also allows reload. The declared default node includes pearlfix.reload and pearlfix.alerts as children; it does not include bypass.
Configuration key: Permissions.Admin

pearlfix.reload — Operator by default. Allows configuration reloads. The configured admin node also permits this command.
Configuration key: Permissions.Reload

pearlfix.alerts — Operator by default. Receives alerts when a pearl is blocked at a narrow gap and Pearl-Checks.Alerts is enabled. This is not an alert for every cancelled pearl.
Configuration key: Permissions.Staff

pearlfix.bypass — Not granted by default, including to operators. Pearls thrown by players with this node are excluded from the checks.
Configuration key: Permissions.Bypass

The admin node grants management access and default alert/reload children, not bypass. If you rename permission nodes in Settings.yml, grant those new names through your permission manager; the declared default operator grants and child relationships apply to the original names.

When upgrading from version 6, an existing Permissions.Staff: pearlfix.message value is preserved. Continue granting the configured node, or change it deliberately to the new default pearlfix.alerts. pearlfix.message is a migrated value, not an additional default permission in version 7.

Merge these sections into your generated Settings.yml. The example uses the default protection settings and permission names.

# Merge these sections into the generated Settings.yml.
# Keep the generated Plugin-Version and Config-Version values.
Plugin-Config:
  Enabled: true
  Update-Checker: true
  Debug: false
  Disabled-Worlds: []

Pearl-Checks:
  Safe-Landing: true
  Block-Gaps: true
  Gap-Height: 0.6
  Refund-Pearl: true
  Alerts: true

Permissions:
  Bypass: "pearlfix.bypass"
  Staff: "pearlfix.alerts"
  Reload: "pearlfix.reload"
  Admin: "pearlfix.admin"

• Plugin-Config.Enabled. Default true. Enables or disables all pearl checks.
• Plugin-Config.Update-Checker. Default true. Checks Spigot asynchronously at startup and notifies the console and authorized admins about a newer version.
• Plugin-Config.Debug. Default false. Logs pearl-check details to the console. Personal chat debug is controlled separately with /pearlfix debug.
• Plugin-Config.Disabled-Worlds. Default []. World names are matched without case sensitivity; pearls in these worlds are not checked.
• Pearl-Checks.Safe-Landing. Default true. Uses the player’s actual bounding box to keep the landing outside block collision shapes; adjusts it locally or cancels when no safe fit is found.
• Pearl-Checks.Block-Gaps. Default true. Tracks the pearl’s path and blocks teleports through openings too narrow for the configured player clearance.
• Pearl-Checks.Gap-Height. Default 0.6; range 0.6–1.8 blocks. This is a configured minimum height, not a value automatically selected from the player’s current pose. 0.6 is a crawling-sized baseline, 1.5 a sneaking-sized baseline and 1.8 a standing-sized baseline. Scaled player dimensions are accounted for.
• Pearl-Checks.Refund-Pearl. Default true. Returns one ender pearl after a cancellation caused by these checks, outside creative mode. If the inventory is full, the pearl drops at the player’s location.
• Pearl-Checks.Alerts. Default true. Sends blocked-gap alerts to the console and staff with Permissions.Staff. Alerts are throttled to one per player every two seconds.
• Permissions. Four configurable nodes: Bypass, Staff, Reload and Admin. Blank values fall back to the default node names. Grant renamed nodes with your permission manager; the descriptor’s operator defaults and child links apply to the original names.
• Plugin-Version / Config-Version. Managed by the plugin. Leave them unchanged so configuration upgrades can run safely.

Messages support MiniMessage colors and styles, legacy & codes and HEX colors. Full RGB display requires Minecraft 1.16 or newer; older versions use the nearest legacy color. Message output is serialized to Bukkit text, so interactive click and hover components are not part of this plugin’s message system.

Set any message to "" to silence it. The plugin substitutes its own {...} variables; these do not require PlaceholderAPI. {player} is available for the player concerned in pearl and staff feedback.

• Messages.Prefix. Prefix used before plugin messages. Set to an empty string to remove it.
• Messages.No-Perms / Usage. Command permission feedback and command usage.
• Messages.Reload / Reload-Failed. Reload result. Reload-Failed supports {error}.
• Messages.Unsafe-Location. Player feedback when no safe landing can fit.
• Messages.Through-Gap. Player feedback when a narrow-gap check cancels a teleport.
• Messages.Pearl-Returned. Player feedback when the cancelled pearl is refunded.
• Messages.Block-Glitch-Message. Staff gap alert. Supports {player}, {world}, {x}, {y} and {z}.
• Messages.Debug-On / Debug-Off. Feedback for personal chat debug.
• Messages.Status. Supports {version}, {minecraft}, {shapes}, {checked}, {moved}, {gaps} and {room}.
• Messages.Update-Available. Supports {version} (available release) and {current} (installed release).

Messages:
  Prefix: "<color:#B09CAA><bold>PearlFix</bold></color> <dark_gray>» </dark_gray>"
  Through-Gap: "<gray>Your pearl passed through an opening too small for you.</gray>"
  Pearl-Returned: "<gray>Your pearl has been returned.</gray>"
  Block-Glitch-Message: "<gray>{player} was stopped at a gap in {world}: {x}, {y}, {z}.</gray>"

Version 7 rebuilds pearl detection around collision shapes and a shared tracker. Before upgrading, back up the plugin folder, stop the server, replace the old JAR and start the server again.

Configuration updates preserve supported user values and create a copy under old-configs/ before rewriting the file. The old Check-Distance, No-Corner and Very-Close settings are replaced by the two new checks. Legacy message tokens %player% and %coords% migrate to {player} and {x}, {y}, {z}.

Keep Plugin-Version and Config-Version unchanged. Existing staff permission names are preserved, including the older pearlfix.message value.

Invalid YAML is not overwritten. A failed reload reports the error and keeps the previous working settings. If startup configuration cannot be read, the plugin uses its bundled default protection settings until you fix the file and reload.

Need help with a setting or a throw that behaves unexpectedly? Share your server version, /pearlfix status output and the relevant debug details with the community.

Teramont is our hosting partner. Get 15% off your first month with code Byte.