TpaPro
Secure, configurable teleport requests for modern Paper servers — done right.
TpaPro is a next‑generation /tpa plugin for Paper 1.21+ that replaces the messy, race‑prone request code most servers still ship. It's built around a race‑safe request lifecycle, permission‑tiered warmups, cooldowns, costs, and traps, plus SQL persistence (SQLite / MySQL / MariaDB / PostgreSQL), full Vault / PlaceholderAPI / WorldGuard / CombatLogX / PvPManager support, Adventure/MiniMessage localization, inventory GUIs, a public Bukkit API, and a complete event system — all in one dependency‑inclusive JAR.
If you've ever had a player accept the same /tpa twice, get scammed by /tpahere, or lose their location to a sloppy /back, TpaPro exists to make those bugs impossible.
![[IMG]](//proxy.spigotmc.org/537adec4a874b630f3ae31176fa6a1581fb68d23/68747470733a2f2f7261772e67697468756275736572636f6e74656e742e636f6d2f4d52737566666978782f54706150726f2f6d61696e2f696d672f62616e6e65722e706e67)
✨ Why TpaPro?
Most /tpa plugins are forks of forks: duplicated schedulers per request, double teleports, unsafe destinations, leaked economy charges, and zero protection against teleport traps. TpaPro was written from scratch with the lessons of those failures baked in:
️ Request Lifecycle & Safety
Requirement Version
Server Paper 1.21 or newer
Java Java 21 or newer (compiled for Java 21)
API Bukkit / Paper API 1.21
⚠️ TpaPro is a Paper plugin, not a Fabric/Forge mod. Modrinth hosts a wide range of Minecraft software — this project targets server administrators running Paper.
Optional Integrations (Soft Dependencies)
TpaPro detects and adapts to any combination of these — missing plugins never prevent startup:
Installation Steps
Command Purpose
/tpa <player> Ask to teleport to a player
/tpahere <player> Ask a player to teleport to you
/tpaccept [player] Accept the only request, or one sender's request
/tpdeny [player] Deny the only request, or one sender's request
/tpcancel [player] Cancel an outgoing request
/tpatoggle Toggle incoming requests on/off
/tpautaccept [player] Toggle global or per‑player auto‑accept
/tpblock, /tpunblock, /tpblocklist Manage blocked players
/tpatrust add|remove|list Manage trusted players
/tpalist View pending and sent requests
/tpasettings Open settings menu, or setting value via text
/tpback Return to your saved pre‑teleport location
/tphistory [page] View teleport history
/tpastats [player] View statistics (admin permission to inspect others)
/tpapro help Show help
/tpapro reload Atomically reload validated config + languages
/tpapro info Show safe runtime diagnostics
/tpapro debug Toggle runtime debug logging
/tpapro inspect <player> Inspect non‑secret player state
/tpapro requests clear <player> Invalidate active requests
/tpapro cooldown reset <player> Reset teleport cooldowns
/tpapro forceteleport <player> <target> Administrative teleport
Permissions (Highlights)
Player permissions default to true. Bypass and admin permissions default to operators.
Player
tpapro.use
tpapro.tpa · tpapro.tpahere
tpapro.accept · tpapro.deny · tpapro.cancel
tpapro.toggle · tpapro.autaccept · tpapro.block · tpapro.trust
tpapro.list · tpapro.settings · tpapro.back · tpapro.history · tpapro.stats
Bypass
tpapro.bypass.cooldown · tpapro.bypass.warmup · tpapro.bypass.cost
tpapro.bypass.combat · tpapro.bypass.world · tpapro.bypass.region
tpapro.bypass.safety · tpapro.bypass.move-cancel · tpapro.bypass.damage-cancel
Administration
tpapro.admin (grants the entire admin subtree)
tpapro.admin.help · tpapro.admin.reload · tpapro.admin.info
tpapro.admin.debug · tpapro.admin.inspect · tpapro.admin.clear-requests
tpapro.admin.reset-cooldown · tpapro.admin.force-teleport
For warmups, cooldowns, and costs the lowest matching non‑negative value wins. For request / history / trust limits the highest matching value wins.
⚙️ Configuration
TpaPro ships seven purpose‑built YAML files plus two language catalogs:
File Purpose
config.yml Requests, warmups, safety, traps, trust benefits, back/history/stats, language, and permission groups
storage.yml Database type, connection info, pool settings, shutdown behavior, cooldown persistence
restrictions.yml Worlds, cross‑world routes, combat, and regions
integrations.yml Economy stages/costs and optional plugin toggles
sounds.yml Validated namespaced or Bukkit sound names, volume, pitch
menus.yml Titles, sizes, materials, presentation
messages/en_US.yml, messages/tr_TR.yml Localized MiniMessage templates
Numeric values are bounded, invalid enum/value input falls back with a warning, and config-version: 1 is carried by every file — older versions are backed up before compatibility defaults are applied.
Example: enable Vault economy with safe ON_SUCCESS charges
economy:
enabled: true
charge-mode: ON_SUCCESS # safest default — charge only on success
costs:
tpa: 10
tpahere: 25
Example: restrict cross‑world teleports
worlds:
blacklist: ["pvp_world"]
cross-world:
enabled: true
blocked-routes:
- { from: "survival", to: "creative" }
️ Database Setup
SQLite is ready with zero config and creates plugins/TpaPro/tpapro.db automatically.
For MySQL, MariaDB, or PostgreSQL, set type, host, port, database, username, and password in storage.yml, then restart:
type: mysql # or: mariadb | postgresql | sqlite
host: db.example.com
port: 3306
database: tpapro
username: tpapro
password: "${DB_PASSWORD}" # interpolated by your secret manager
pool:
maximum-pool-size: 12
minimum-idle: 2
TpaPro never logs passwords. Schema migrations create unique relationship constraints and indexes for history and relationship lookup.
Integrations
Vault (Economy)
Install Vault + an economy provider, enable economy.enabled, select a charge mode, and configure costs. Bypass and refund rules are enforced exactly once per transaction ID.
WorldGuard (Regions)
TpaPro registers the tpapro-teleport state flag. Source and destination checks can be toggled in restrictions.yml. If flag registration conflicts or WorldGuard can't initialize, region integration disables safely.
PlaceholderAPI
Non‑blocking, memory‑cached placeholders:
%tpapro_enabled%
%tpapro_pending_requests%
%tpapro_outgoing_requests%
%tpapro_cooldown%
%tpapro_warmup%
%tpapro_last_target%
%tpapro_trusted_count%
%tpapro_blocked_count%
%tpapro_auto_accept%
%tpapro_privacy_mode%
%tpapro_successful_teleports%
Public API Example
TpaProApi api = Bukkit.getServicesManager().load(TpaProApi.class);
if (api != null) {
RequestOutcome result = api.sendRequest(senderUuid, targetUuid, RequestType.TPA);
if (result.isAccepted()) {
// request sent — listen for RequestAcceptedEvent / TeleportCompleteEvent
}
}
API request methods and events run on the server thread. Request snapshots and configuration models exposed by the API are immutable, and custom restrictions return a closeable registration handle.
❓ FAQ
Can I use TpaPro in my modpack? TpaPro is a Paper plugin, not a client mod — it lives entirely on the server. Modpacks can absolutely include Paper + TpaPro in the server bundle.
Will you backport to older Minecraft versions? TpaPro 1.0 targets Paper 1.21+ and is compiled for Java 21. Older MC versions require older Paper APIs and are not supported.
Is this server‑side only? Yes. No client installation is required.
Does it work with Folia? TpaPro 1.0 uses the Paper scheduler and does not claim Folia compatibility. Folia detection is logged but the plugin still loads with a warning.
Does it work with Velocity / BungeeCord / Redis? Not in 1.0. There is no proxy, no cross‑server teleport, and no Redis layer.
Is economy required? No. Economy is opt‑in. If economy.enabled: true is set but Vault is missing or no economy provider is installed, all economy actions fail safely — no NPEs, no silent charges.
Can I add my own language? Yes — drop a new messages/<locale>.yml alongside the bundled en_US.yml and tr_TR.yml. Locale identifiers are path‑safe validated before use.
Where can I see what's in the box? Run /tpapro info on the server for a safe runtime summary. Use /tpapro debug to toggle verbose logging.
Building from Source
.\gradlew.bat clean test build
The build uses the Java 21 toolchain, UTF‑8 compilation, JUnit 5, reproducible archives, and produces a dependency‑inclusive plugin JAR. Paper and optional server APIs are compileOnly and not bundled.
Core tests cover lifecycle transitions, duplicate policies, expiration, ambiguity, cooldown arithmetic, permission values, movement, warmup isolation, safety rules, privacy/trust/block logic, economy idempotency, message fallback, configuration validation, task reload idempotency, and SQLite uniqueness/persistence.
Support & Credits
When reporting a problem, please include:
Designed, built, and credited to MRsuffix.
Links
Secure, configurable teleport requests for modern Paper servers — done right.
TpaPro is a next‑generation /tpa plugin for Paper 1.21+ that replaces the messy, race‑prone request code most servers still ship. It's built around a race‑safe request lifecycle, permission‑tiered warmups, cooldowns, costs, and traps, plus SQL persistence (SQLite / MySQL / MariaDB / PostgreSQL), full Vault / PlaceholderAPI / WorldGuard / CombatLogX / PvPManager support, Adventure/MiniMessage localization, inventory GUIs, a public Bukkit API, and a complete event system — all in one dependency‑inclusive JAR.
If you've ever had a player accept the same /tpa twice, get scammed by /tpahere, or lose their location to a sloppy /back, TpaPro exists to make those bugs impossible.
✨ Why TpaPro?
Most /tpa plugins are forks of forks: duplicated schedulers per request, double teleports, unsafe destinations, leaked economy charges, and zero protection against teleport traps. TpaPro was written from scratch with the lessons of those failures baked in:
- Atomic state transitions — accept and teleport exactly once, every time, even under spam.
- One shared expiration task, one shared warmup ticker — no scheduler task per request, no lag spikes.
- Bounded deterministic safety search — destination blocks are validated against hazards, borders, void, fall damage, suffocation, and the Nether roof before the player ever moves.
- Trap analysis — destination‑bound, request‑bound, expiring confirmation tokens defeat teleport traps by design.
- Charge‑once semantics — Vault balances are checked, charged, and refunded exactly once per transaction.
- A real public API — Bukkit.getServicesManager().load(TpaProApi.class), cancellable pre‑events, and immutable post‑event snapshots.
️ Request Lifecycle & Safety
- /tpa and /tpahere with immutable identity and automatic expiration.
- Multiple pending requests at once with sender selection (/tpaccept <player>).
- Configurable duplicate policy: REJECT, REPLACE, or REFRESH.
- Atomic accept/teleport transitions — no double‑teleport, no double‑charge.
- Movement, damage, attack, world‑change, command, death, quit, and replacement cancellation controls.
- Warmup + cooldown system with per‑permission tiers (lowest matching non‑negative value wins).
- Trap analysis with expiring, request/destination‑bound confirmation tokens.
- World blacklist / whitelist, cross‑world controls, and blocked routes.
- WorldGuard tpapro-teleport state flag — deny teleports per region:
/rg flag <region> tpapro-teleport deny
- Combat tracking built‑in, plus runtime adapters for CombatLogX and PvPManager.
- Charge stages: ON_REQUEST, ON_ACCEPT, ON_SUCCESS (the safe default).
- Balance checks, charge‑once semantics, and failure refunds.
- Bypass permissions for donors, VIPs, and admins.
- Persistent privacy settings, notification preferences, and per‑player locale.
- One‑directional trust, per‑player auto‑accept, and block lists (/tpblock, /tpunblock, /tpblocklist).
- /tpatoggle to mute incoming requests when you need focus.
- /tpback — return to your saved pre‑teleport location.
- /tphistory [page] — paginated teleport history.
- /tpastats [player] — batched, non‑blocking statistics.
- Cached PlaceholderAPI values that never block on SQL.
- SQLite by default — zero setup, just drop the JAR in plugins/.
- MySQL, MariaDB, and PostgreSQL via HikariCP for multi‑server deployments.
- Async repository work on a dedicated executor — Bukkit objects are never touched from DB threads.
- Unique‑constraint schema migrations and indexed lookups.
- Full English (en_US) and Turkish (tr_TR) catalogs via Adventure + MiniMessage.
- Validated sounds (sounds.yml) with namespaced or Bukkit sound names.
- Inventory menus with pagination and protected click/drag handling — every feature also works through commands.
- Invalid input, ambiguous requests, offline players, console/player mismatches, and permission failures all return localized messages — no stack traces in chat.
- Public TpaProApi registered through Bukkit's ServicesManager.
- Cancellable pre‑events and immutable post‑event snapshots:
- RequestCreateEvent, RequestCreatedEvent
- RequestAcceptEvent, RequestAcceptedEvent
- RequestDenyEvent, RequestDeniedEvent
- RequestExpireEvent, RequestCancelEvent
- TeleportPrepareEvent, TeleportStartEvent, TeleportCompleteEvent, TeleportCancelEvent
- TeleportSafetyCheckEvent (per‑stage)
- Custom restriction API with closeable registration handles.
Requirement Version
Server Paper 1.21 or newer
Java Java 21 or newer (compiled for Java 21)
API Bukkit / Paper API 1.21
⚠️ TpaPro is a Paper plugin, not a Fabric/Forge mod. Modrinth hosts a wide range of Minecraft software — this project targets server administrators running Paper.
Optional Integrations (Soft Dependencies)
TpaPro detects and adapts to any combination of these — missing plugins never prevent startup:
- Vault + any economy provider (for charges)
- PlaceholderAPI (for placeholders)
- WorldGuard (for region flags)
- CombatLogX (for combat detection)
- PvPManager (for combat detection)
Installation Steps
- Stop your Paper server.
- Drop TpaPro-1.0.0-SNAPSHOT.jar into plugins/.
- Start the server. TpaPro copies all configuration and language resources without overwriting existing files.
- Review plugins/TpaPro/config.yml, storage.yml, restrictions.yml, and integrations.yml.
- Restart after changing storage type/credentials or optional integration availability. Most other settings and language content can be reloaded live with /tpapro reload.
- Server‑side only — no client mod is required.
- Async SQL on a dedicated executor; no per‑request scheduler tasks.
- Memory‑cached PlaceholderAPI values — no SQL lookups during resolution.
Command Purpose
/tpa <player> Ask to teleport to a player
/tpahere <player> Ask a player to teleport to you
/tpaccept [player] Accept the only request, or one sender's request
/tpdeny [player] Deny the only request, or one sender's request
/tpcancel [player] Cancel an outgoing request
/tpatoggle Toggle incoming requests on/off
/tpautaccept [player] Toggle global or per‑player auto‑accept
/tpblock, /tpunblock, /tpblocklist Manage blocked players
/tpatrust add|remove|list Manage trusted players
/tpalist View pending and sent requests
/tpasettings Open settings menu, or setting value via text
/tpback Return to your saved pre‑teleport location
/tphistory [page] View teleport history
/tpastats [player] View statistics (admin permission to inspect others)
/tpapro help Show help
/tpapro reload Atomically reload validated config + languages
/tpapro info Show safe runtime diagnostics
/tpapro debug Toggle runtime debug logging
/tpapro inspect <player> Inspect non‑secret player state
/tpapro requests clear <player> Invalidate active requests
/tpapro cooldown reset <player> Reset teleport cooldowns
/tpapro forceteleport <player> <target> Administrative teleport
Permissions (Highlights)
Player permissions default to true. Bypass and admin permissions default to operators.
Player
tpapro.use
tpapro.tpa · tpapro.tpahere
tpapro.accept · tpapro.deny · tpapro.cancel
tpapro.toggle · tpapro.autaccept · tpapro.block · tpapro.trust
tpapro.list · tpapro.settings · tpapro.back · tpapro.history · tpapro.stats
Bypass
tpapro.bypass.cooldown · tpapro.bypass.warmup · tpapro.bypass.cost
tpapro.bypass.combat · tpapro.bypass.world · tpapro.bypass.region
tpapro.bypass.safety · tpapro.bypass.move-cancel · tpapro.bypass.damage-cancel
Administration
tpapro.admin (grants the entire admin subtree)
tpapro.admin.help · tpapro.admin.reload · tpapro.admin.info
tpapro.admin.debug · tpapro.admin.inspect · tpapro.admin.clear-requests
tpapro.admin.reset-cooldown · tpapro.admin.force-teleport
For warmups, cooldowns, and costs the lowest matching non‑negative value wins. For request / history / trust limits the highest matching value wins.
⚙️ Configuration
TpaPro ships seven purpose‑built YAML files plus two language catalogs:
File Purpose
config.yml Requests, warmups, safety, traps, trust benefits, back/history/stats, language, and permission groups
storage.yml Database type, connection info, pool settings, shutdown behavior, cooldown persistence
restrictions.yml Worlds, cross‑world routes, combat, and regions
integrations.yml Economy stages/costs and optional plugin toggles
sounds.yml Validated namespaced or Bukkit sound names, volume, pitch
menus.yml Titles, sizes, materials, presentation
messages/en_US.yml, messages/tr_TR.yml Localized MiniMessage templates
Numeric values are bounded, invalid enum/value input falls back with a warning, and config-version: 1 is carried by every file — older versions are backed up before compatibility defaults are applied.
Example: enable Vault economy with safe ON_SUCCESS charges
economy:
enabled: true
charge-mode: ON_SUCCESS # safest default — charge only on success
costs:
tpa: 10
tpahere: 25
Example: restrict cross‑world teleports
worlds:
blacklist: ["pvp_world"]
cross-world:
enabled: true
blocked-routes:
- { from: "survival", to: "creative" }
️ Database Setup
SQLite is ready with zero config and creates plugins/TpaPro/tpapro.db automatically.
For MySQL, MariaDB, or PostgreSQL, set type, host, port, database, username, and password in storage.yml, then restart:
type: mysql # or: mariadb | postgresql | sqlite
host: db.example.com
port: 3306
database: tpapro
username: tpapro
password: "${DB_PASSWORD}" # interpolated by your secret manager
pool:
maximum-pool-size: 12
minimum-idle: 2
TpaPro never logs passwords. Schema migrations create unique relationship constraints and indexes for history and relationship lookup.
Integrations
Vault (Economy)
Install Vault + an economy provider, enable economy.enabled, select a charge mode, and configure costs. Bypass and refund rules are enforced exactly once per transaction ID.
WorldGuard (Regions)
TpaPro registers the tpapro-teleport state flag. Source and destination checks can be toggled in restrictions.yml. If flag registration conflicts or WorldGuard can't initialize, region integration disables safely.
PlaceholderAPI
Non‑blocking, memory‑cached placeholders:
%tpapro_enabled%
%tpapro_pending_requests%
%tpapro_outgoing_requests%
%tpapro_cooldown%
%tpapro_warmup%
%tpapro_last_target%
%tpapro_trusted_count%
%tpapro_blocked_count%
%tpapro_auto_accept%
%tpapro_privacy_mode%
%tpapro_successful_teleports%
Public API Example
TpaProApi api = Bukkit.getServicesManager().load(TpaProApi.class);
if (api != null) {
RequestOutcome result = api.sendRequest(senderUuid, targetUuid, RequestType.TPA);
if (result.isAccepted()) {
// request sent — listen for RequestAcceptedEvent / TeleportCompleteEvent
}
}
API request methods and events run on the server thread. Request snapshots and configuration models exposed by the API are immutable, and custom restrictions return a closeable registration handle.
❓ FAQ
Can I use TpaPro in my modpack? TpaPro is a Paper plugin, not a client mod — it lives entirely on the server. Modpacks can absolutely include Paper + TpaPro in the server bundle.
Will you backport to older Minecraft versions? TpaPro 1.0 targets Paper 1.21+ and is compiled for Java 21. Older MC versions require older Paper APIs and are not supported.
Is this server‑side only? Yes. No client installation is required.
Does it work with Folia? TpaPro 1.0 uses the Paper scheduler and does not claim Folia compatibility. Folia detection is logged but the plugin still loads with a warning.
Does it work with Velocity / BungeeCord / Redis? Not in 1.0. There is no proxy, no cross‑server teleport, and no Redis layer.
Is economy required? No. Economy is opt‑in. If economy.enabled: true is set but Vault is missing or no economy provider is installed, all economy actions fail safely — no NPEs, no silent charges.
Can I add my own language? Yes — drop a new messages/<locale>.yml alongside the bundled en_US.yml and tr_TR.yml. Locale identifiers are path‑safe validated before use.
Where can I see what's in the box? Run /tpapro info on the server for a safe runtime summary. Use /tpapro debug to toggle verbose logging.
Building from Source
.\gradlew.bat clean test build
The build uses the Java 21 toolchain, UTF‑8 compilation, JUnit 5, reproducible archives, and produces a dependency‑inclusive plugin JAR. Paper and optional server APIs are compileOnly and not bundled.
Core tests cover lifecycle transitions, duplicate policies, expiration, ambiguity, cooldown arithmetic, permission values, movement, warmup isolation, safety rules, privacy/trust/block logic, economy idempotency, message fallback, configuration validation, task reload idempotency, and SQLite uniqueness/persistence.
Support & Credits
When reporting a problem, please include:
- Output of /tpapro info
- Sanitized configuration (redact passwords!)
- Server log around the failure
- Reproduction steps
Designed, built, and credited to MRsuffix.
Links
- Website / Source: https://github.com/MRsuffixx/TpaPro
- Issue Tracker: https://github.com/MRsuffixx/TpaPro/issues
TpaPro is a free Minecraft Java mod. Compatible with Minecraft 1.21, 26.1, 26.2. Downloaded 25 times (via Spigot). Download it and open it directly in the game.