DS-PearlFix

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

/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.

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.

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.