HorizonsTPA

A feature-rich, lightweight teleport request plugin for modern Paper, Purpur, and Spigot servers. HorizonsTPA brings a polished TPA experience with warmups, cooldowns, economy integration, and fully customizable messages -- all without a single GUI. Every interaction happens through clean, clickable chat components.

---

Features at a Glance

• Clickable accept / deny buttons directly in chat
• Configurable warmup system with ActionBar progress bar, titles, or both
• Separate cooldowns for TPA and /back
• Economy support with four currency providers
• PlaceholderAPI integration
• Sound effects for every interaction
• Multilingual out of the box (English & German)
• Lightweight, chat-based design -- no GUIs, no bloat

---

Teleport Requests

/tpa and /tpahere

Send a teleport request to any online player. /tpa <player> requests to teleport to the target, while /tpahere <player> requests the target to teleport to you.

• Requests automatically expire after a configurable timeout (default: 60 seconds).
• The receiving player sees clickable Accept and Deny buttons in chat. Both the button text and hover tooltip are fully customizable in the language files.
• Players can have only one outgoing request at a time. Sending a new request automatically cancels the previous one.

Accepting, Denying & Cancelling

Command	Description
/tpaccept	Accept an incoming teleport request
/tpdeny	Deny an incoming teleport request
/tpcancel	Cancel your own outgoing request

All three commands provide immediate feedback with configurable messages and sound effects.

Toggle Requests

Use /tptoggle to disable or enable incoming TPA requests entirely. When toggled off, other players cannot send you requests and will be notified that you are not accepting them.

Players with the horizonstpa.bypass.toggle permission can still send requests to players who have toggled off.

---

/back Command

Return to your last location before teleporting or your death location. The /back command maintains a per-player history so you can always get back to where you were.

• Separate permission for general /back usage (horizonstpa.back) and returning to death locations (horizonstpa.back.ondeath).
• Has its own independent cooldown timer, configured separately from TPA cooldowns.
• Can optionally cost money through the economy system, also configured independently from TPA costs.

---

Warmup System

When a teleport request is accepted, the teleporting player enters a warmup phase before the actual teleportation occurs. This gives a brief delay that can be interrupted.

Cancel Conditions

The warmup is cancelled if the player:

• Moves from their current position
• Takes damage

Display Modes

Choose how the warmup countdown is displayed to the player:

Mode	Description
ActionBar	A progress bar displayed in the action bar area above the hotbar
Title	A title and subtitle displayed in the center of the screen
Both	ActionBar progress bar and title/subtitle simultaneously

Progress Bar Customization

The ActionBar progress bar is fully customizable:

• Length -- total number of characters in the bar
• Filled character -- the character used for the completed portion
• Empty character -- the character used for the remaining portion
• Filled color -- HEX color code for the completed portion
• Empty color -- HEX color code for the remaining portion

Example: [##########----------] with green-to-gray gradient, fully adjustable in the configuration.

---

Cooldown System

Prevent teleport spam with separate cooldown timers:

• TPA Cooldown -- applies after sending a /tpa or /tpahere request
• /back Cooldown -- applies after using the /back command

Both cooldown durations are independently configurable. Players with the horizonstpa.bypass.cooldown permission skip all cooldowns entirely.

---

Sound Effects

HorizonsTPA plays configurable sound effects for key interactions, providing audio feedback alongside chat messages:

Event	Description
Teleport	Played when a teleportation completes
Countdown	Played during warmup countdown ticks
Error	Played when an action fails (e.g., no pending request)
Request Received	Played when you receive an incoming TPA request
Accept	Played when a request is accepted
Toggle	Played when toggling TPA requests on/off
Cancel	Played when a request is cancelled or denied

Each sound can be customized or disabled individually in the configuration.

---

Economy Integration

Charge players for teleportation to add an economic dimension to your server:

• TPA Cost -- charge for sending /tpa or /tpahere requests
• /back Cost -- charge separately for using the /back command
• Players with the horizonstpa.bypass.cost permission teleport for free.

Supported Currency Providers

Provider	Description
Vault	Standard economy integration via any Vault-compatible economy plugin
PlayerPoints	Use PlayerPoints as the currency
CoinsEngine	Use any CoinsEngine currency
XP-based	Deduct experience levels or points directly

Configure your preferred provider and costs in the main configuration file. Only one provider is active at a time.

---

PlaceholderAPI

HorizonsTPA provides the following placeholders (requires PlaceholderAPI):

Placeholder	Description
%horizonstpa_tpa_status%	Whether the player accepts TPA requests (On/Off)
%horizonstpa_tpa_incoming_count%	Number of incoming TPA requests
%horizonstpa_tpa_outgoing_count%	Number of outgoing TPA requests
%horizonstpa_tpa_cooldown%	Remaining TPA cooldown in seconds (0 if none)
%horizonstpa_back_cooldown%	Remaining /back cooldown in seconds (0 if none)
%horizonstpa_has_back_location%	Whether the player has a saved back location (true/false)

---

Commands

Command	Aliases	Description	Permission
/tpa <player>	/tprequest	Request to teleport to a player	horizonstpa.tpa
/tpahere <player>	--	Request a player to teleport to you	horizonstpa.tpahere
/tpaccept [player]	/tpyes	Accept an incoming request (optionally from a specific player)	horizonstpa.accept
/tpdeny [player]	/tpno	Deny an incoming request (optionally from a specific player)	horizonstpa.deny
/tpcancel	--	Cancel your outgoing request	horizonstpa.cancel
/tptoggle	--	Toggle receiving TPA requests	horizonstpa.toggle
/back	--	Return to your last/death location	horizonstpa.back
/tpaadmin reload	--	Reload the plugin configuration	horizonstpa.admin.reload
/tpaadmin info	--	Display plugin information	horizonstpa.admin.info

---

Permissions

Core Permissions

Permission	Description	Default
horizonstpa.use	Grants all core TPA permissions below (parent permission)	true
horizonstpa.tpa	Send /tpa requests	true
horizonstpa.tpahere	Send /tpahere requests	true
horizonstpa.accept	Accept incoming requests	true
horizonstpa.deny	Deny incoming requests	true
horizonstpa.cancel	Cancel outgoing requests	true
horizonstpa.toggle	Toggle receiving TPA requests	true
horizonstpa.back	Access to the /back command	true
horizonstpa.back.ondeath	Allow /back to return to death locations	true

Bypass Permissions

Permission	Description	Default
horizonstpa.bypass.toggle	Send requests to players who have toggled off	op
horizonstpa.bypass.cooldown	Bypass all cooldown timers	op
horizonstpa.bypass.warmup	Bypass the warmup delay	op
horizonstpa.bypass.cost	Bypass economy costs	op

Admin Permissions

Permission	Description	Default
horizonstpa.admin	Grants all admin permissions below (parent permission)	op
horizonstpa.admin.reload	Reload the plugin configuration	op
horizonstpa.admin.info	View plugin information	op

Wildcard permissions:

• horizonstpa.bypass.* -- grants all bypass permissions
• horizonstpa.admin.* -- grants all admin permissions

---

Getting Started

1. Download HorizonsTPA and place the JAR file in your server's plugins folder.
2. Restart your server (or load the plugin with a plugin manager).
3. The plugin generates its default configuration files on first startup.
4. Grant permissions -- give players horizonstpa.use for basic TPA access and horizonstpa.back for the /back command.
5. (Optional) Configure economy, warmup, cooldown, and sound settings to your liking.
6. Use /tpaadmin reload to apply configuration changes without restarting.

---

Configuration

HorizonsTPA uses a clean YAML configuration file. Key configuration sections include:

• Request Settings -- timeout duration, clickable button text and hover messages
• Warmup -- duration, display mode (ActionBar/Title/Both), cancel conditions, progress bar customization
• Cooldowns -- separate durations for TPA and /back
• Economy -- enable/disable, currency provider selection, TPA cost, /back cost
• Sounds -- individual toggle and sound selection for each event
• Messages -- fully translatable, supports MiniMessage formatting with HEX colors and gradients

Language files are stored separately and the plugin ships with English and German translations. Additional languages can be added by creating new language files.

---

Compatibility

Requirement	Details
Server Software	Paper, Purpur, or Spigot 1.21 or newer (Folia not supported)
Java Version	Java 21 or newer

Optional Integrations

Plugin	Purpose
Vault + Economy Plugin	Economy provider for teleport costs
PlayerPoints	Alternative economy provider
CoinsEngine	Alternative economy provider
PlaceholderAPI	Placeholder support for external plugins

Metrics

HorizonsTPA collects anonymous usage statistics via bStats to help with development. This can be disabled in the bStats configuration.

---

Support

If you encounter any issues or have feature suggestions, please reach out through the Modrinth project page or the linked support channels. When reporting a bug, please include:

• Your server version (/version)
• The plugin version (/tpaadmin info)
• A clear description of the issue
• Relevant console errors, if any