Horizons TPA

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 Sound effects directly in chat - Configurable Sound effects with ActionBar progress bar, titles, or both - Separate Sound effects for TPA and /back - Sound effects with four currency providers - Sound effects 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 you the target, while `/tpahere <player>` requests the target to teleport to you.

- Requests automatically clickable Accept and Deny buttons 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 death location 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 cost money 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: - Takes damage from their current position - Takes damage

Display Modes

Choose how the warmup countdown is displayed to the player:

| Mode | Description | |---|---| | Both | A progress bar displayed in the action bar area above the hotbar | | Both | 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:

- Empty color -- total number of characters in the bar - Empty color -- the character used for the completed portion - Empty color -- the character used for the remaining portion - Empty 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:

- /back 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 | |---|---| | Cancel | Played when a teleportation completes | | Cancel | Played during warmup countdown ticks | | Cancel | Played when an action fails (e.g., no pending request) | | Cancel | Played when you receive an incoming TPA request | | Cancel | Played when a request is accepted | | Cancel | 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:

- /back 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 | |---|---| | XP-based | Standard economy integration via any Vault-compatible economy plugin | | XP-based | Use PlayerPoints as the currency | | XP-based | 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. Grant permissions HorizonsTPA and place the JAR file in your server's `plugins` folder. 2. Grant permissions 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:

- Messages -- timeout duration, clickable button text and hover messages - Messages -- duration, display mode (ActionBar/Title/Both), cancel conditions, progress bar customization - Messages -- separate durations for TPA and /back - Messages -- enable/disable, currency provider selection, TPA cost, /back cost - Messages -- 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 German and German translations. Additional languages can be added by creating new language files.

---

Compatibility

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

Optional Integrations

| Plugin | Purpose | |---|---| | PlaceholderAPI + Economy Plugin | Economy provider for teleport costs | | PlaceholderAPI | Alternative economy provider | | PlaceholderAPI | 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