PearlPuller

PearlPuller is a server-side Paper/Purpur plugin for ender pearl stasis chambers. It lets a player suspend a thrown ender pearl indefinitely and later teleport to it on demand by casting a specially named fishing rod — no redstone clock or flowing-water trick required.

• Minecraft: 1.21.11 (Paper API 1.21)
• Java: 21
• Author: Anderson Wang (GitHub)

How it works

PearlPuller tracks a pearl in two phases: a short candidate phase to confirm the throw has settled into a real chamber, then a confirmed phase where the pearl is held until pulled.

1. Launch. When a player throws an ender pearl, the plugin starts tracking it as a candidate and scans it once per tick.
2. Candidate confirmation. A candidate is promoted to a confirmed chamber pearl once all of these hold:
   • it has been alive for at least candidate-min-age-ticks (it has stopped flying),
   • it has not drifted more than candidate-max-drift-distance blocks from where it settled, and
   • a trapdoor is found nearby (the chamber). This rejects ordinary travel pearls and only saves pearls that come to rest inside a chamber. Candidates that never settle are discarded after candidate-timeout-seconds.
3. Trapdoor detection. The chamber trapdoor is the closest trapdoor in a column around the pearl — a horizontal square of radius chamber-horizontal-radius (default 3×3) searched up to chamber-vertical-range blocks above the pearl first, then the same range below.
4. Chunk loading. While confirmed, the pearl's chunk is held open with a plugin chunk ticket (keep-pearl-chunk-loaded) so the pearl entity is never unloaded.
5. Pull. When the same player casts a fishing rod named Pearl Puller (configurable), the plugin verifies the saved pearl still exists and its chunk is loaded, then toggles the saved trapdoor.
6. Teleport. Vanilla Minecraft handles the pearl collision and teleport — PearlPuller only opens the trapdoor.
7. Cleanup. After the ender pearl teleport completes (matched to the saved pearl by time and distance), the saved pearl data and chunk ticket are released.

Persistence

Active confirmed pearls are written to plugins/PearlPuller/data.yml when the plugin disables. On startup, PearlPuller reloads each saved entry whose ender pearl entity still exists and resumes tracking it; entries whose pearl is gone are pruned.

Commands

Command	Permission	Notes
/pearlpuller debug	pearlpuller.debug	Players only. Shows technical info about your tracked pearl: UUIDs, validity, chunk load state, world, trapdoor location, and age.
/pearlpuller details	pearlpuller.details	Also runnable from console. Shows plugin version, author, server info, and runtime counts.

Both permissions default to op.

Configuration

The default config is generated at plugins/PearlPuller/config.yml on first run.

Key	Default	Description
keep-pearl-chunk-loaded	true	Hold the tracked pearl's chunk open with a plugin chunk ticket.
load-chunk-on-pull	true	If the chunk unloaded anyway, load it when the rod is cast.
candidate-min-age-ticks	40	Minimum ticks a pearl must live before it can be confirmed (i.e. it has stopped moving).
candidate-max-drift-distance	2.0	Max blocks a candidate may drift from where it settled and still be confirmed.
candidate-timeout-seconds	600	Discard an unconfirmed candidate after this long.
chamber-horizontal-radius	1	Horizontal search radius for the chamber trapdoor (1 = a 3×3 column).
chamber-vertical-range	10	Blocks above/below the pearl to search for the trapdoor.
trapdoor-search-ticks	200	How long after confirmation to keep scanning for a trapdoor if none was found yet.
trigger-rod-name	"Pearl Puller"	Display name of the fishing rod that triggers a pull.
teleport-match-timeout-millis	5000	Window after a pearl hit in which a teleport is matched to it for cleanup.
teleport-match-radius	4.0	Max distance between teleport destination and saved pearl for cleanup matching.
send-messages	true	Send short status messages to players on pull success/failure.

max-pearl-age-seconds is a legacy key kept for old configs. New installs should use candidate-timeout-seconds.

Usage in-game

1. Build a stasis chamber (a trapdoor above flowing water, etc.) within the configured search range.
2. Name a fishing rod Pearl Puller on an anvil.
3. Throw an ender pearl into the chamber and let it settle — the plugin confirms and holds it.
4. When you want to teleport, cast the named rod. The trapdoor toggles, the pearl drops, and vanilla teleports you.

Build

.\gradlew.bat build

The plugin jar is produced in build/libs/.

Project layout

src/main/java/io/github/andxanderson/pearlpuller/PearlPullerPlugin.java   Plugin logic (tracking, pulling, persistence)
src/main/resources/config.yml                                 Default configuration
src/main/resources/plugin.yml                                 Plugin descriptor, commands, permissions
build.gradle.kts                                              Gradle build (Paper API, Java 21)