HorizonsWarps

HorizonsWarps is a modern, fully-featured warp teleportation plugin built for Paper, Purpur, and Spigot 1.21+. It provides server-wide warp points with a stunning paginated GUI, flexible per-warp permissions, category organization, and deep economy integration -- everything you need to build an intuitive teleportation network for your server.

From small survival servers to large communities, HorizonsWarps scales effortlessly with configurable warmup and cooldown systems, multiple layout patterns, and support for both SQLite and MySQL storage.

---

Features at a Glance

• Server-wide warp locations accessible to all players
• Per-warp permissions for fine-grained access control
• Category system for organized warp grouping
• Beautiful paginated GUI with seven layout patterns
• Custom display names and icons for every warp
• Warmup and cooldown systems with multiple display modes
• Economy integration with five currency backends
• Custom item support from eight external item plugins
• Cross-world warps with per-world configuration
• Sound effects and particle effects on teleport
• Configurable sort order per warp
• SQLite and MySQL database backends via HikariCP
• PlaceholderAPI integration
• Multilingual -- English and German included
• bStats metrics

---

Warp System

Server-Wide Warps

Warps are shared locations available to all players on the server (or restricted by permission). Admins create warps at key locations -- spawn, shops, arenas, farms, biomes -- and players can teleport to them instantly.

Per-Warp Permissions

Every warp can optionally require a specific permission to use. When a permission is set on a warp, only players with that permission will see it in the GUI and be able to teleport to it.

• Permission format: horizonswarps.warp.<name>
• Warps without a permission set are accessible to everyone with the base horizonswarps.warp permission

This makes it easy to create VIP warps, staff-only locations, or event-specific destinations.

Custom Display Names

Each warp can have a custom display name separate from its internal identifier. Display names support full HEX color formatting, gradients, and legacy color codes, letting you create visually distinct and descriptive warp labels in the GUI.

Custom Warp Icons

Every warp can have a custom icon displayed in the GUI. Icons can be any vanilla Minecraft item or a custom item from a supported external plugin. Change icons at any time with the /warpadmin seticon command.

Sort Order

Each warp has a configurable sort position that determines its placement in the GUI. This gives you full control over the order in which warps appear, regardless of when they were created.

Warp Categories

Warps can be organized into categories for logical grouping. Categories help players find warps quickly on servers with many destinations. Examples of categories might include Shops, Arenas, Farms, Biomes, or Events.

---

Teleportation System

Cross-World Warps

Players can warp to locations in any world on the server. Cross-world teleportation is configurable:

• Enable or disable cross-world warping globally
• Maintain a list of disabled worlds where warping is restricted

Warmup System

Teleportation can require a warmup delay before the player is moved. The warmup is interrupted if the player moves or takes damage, preventing abuse.

• Configurable delay in seconds
• Cancel on move -- warmup is cancelled if the player moves
• Cancel on damage -- warmup is cancelled if the player takes damage

Warmup Display Modes

Choose how the warmup countdown is presented to the player:

Mode	Description
ActionBar	Shows a progress bar in the action bar with customizable characters, length, and HEX colors
Title	Displays a title and subtitle countdown on screen
Both	Combines ActionBar progress bar and Title display simultaneously

The ActionBar progress bar is fully customizable:

• Configurable bar length
• Custom filled and unfilled characters
• HEX color support for both filled and unfilled segments

Cooldown System

After warping, a cooldown period is enforced before the player can warp again. This prevents teleport spam and ensures fair usage. Players with the bypass permission skip the cooldown entirely.

Sound Effects

HorizonsWarps supports configurable sound effects played during teleportation. Sounds have adjustable volume and pitch for full control over the audio experience.

Particle Effects

A particle effect is displayed at the destination when a player warps, providing visual feedback and flair.

---

Economy Integration

HorizonsWarps supports charging players for warp teleportation. Costs can be configured globally or individually per warp, allowing you to make certain warps free while charging for premium destinations.

Supported Currencies

The plugin supports five different currency backends:

Currency	Description
Vault	Standard economy integration via any Vault-compatible economy plugin
PlayerPoints	Uses PlayerPoints as the currency
CoinsEngine	Integrates with CoinsEngine for custom server currencies (configurable currency name)
XP-based	Uses the player's experience levels or points as currency (configurable mode)
Item-based	Requires specific items from the player's inventory as payment (configurable material)

Economy can also be disabled entirely in the configuration if no costs are desired.

---

GUI System

HorizonsWarps features a polished, paginated graphical interface that players open with /warps. The GUI is the primary way players browse and use warps.

Layout Patterns

The GUI supports seven different layout patterns that control how warp icons are arranged on each page:

Pattern	Description
Spaced	Warps evenly spaced with gaps between them
Wide	Warps spread across the full width of the inventory
Centered	Warps centered in the middle of each row
Diamond	Warps arranged in a diamond formation
Rows	Warps placed in clean horizontal rows
Compact	Maximum warps per page with minimal spacing
Custom	Fully custom slot positions defined in the configuration

Each pattern gives the GUI a different visual feel, letting you match the style of your server.

Warp Info Display

Players can view detailed information about a warp directly in the GUI. The info screen shows the warp name, display name, location, category, permission requirement, and teleport cost.

Custom Item Support

Warp icons in the GUI can use items from the following external plugins:

Plugin	Description
ItemsAdder	Custom items from ItemsAdder
Oraxen	Custom items from Oraxen
HeadDatabase	Custom player heads from HeadDatabase
MMOItems	Items from MMOItems
Slimefun	Items from Slimefun
Nexo	Custom items from Nexo
ExecutableItems	Items from ExecutableItems
EcoItems	Items from EcoItems

All integrations are detected automatically -- install the external plugin and HorizonsWarps will pick it up.

---

Commands

Player Commands

Command	Description	Permission
/warp [name]	Teleport to a warp. If no name is given, opens the warp GUI.	horizonswarps.warp
/warps	Open the warp GUI.	horizonswarps.warps
/setwarp <name>	Create a new warp at your current location.	horizonswarps.setwarp
/delwarp <name>	Delete an existing warp.	horizonswarps.delwarp

Admin Commands

All admin commands are subcommands of /warpadmin and require the horizonswarps.admin permission.

Command	Description
/warpadmin reload	Reload the plugin configuration and language files.
/warpadmin list	List all warps on the server.
/warpadmin info <warp>	View detailed information about a specific warp.
/warpadmin tp <warp>	Teleport directly to a warp, bypassing warmup and cooldown.
/warpadmin delete <warp>	Delete a specific warp.
/warpadmin seticon <warp>	Set the GUI icon for a warp to the item in your hand.
/warpadmin setperm <warp> <permission>	Set or update the permission required to use a warp.
/warpadmin setcat <warp> <category>	Assign a warp to a category.
/warpadmin setdisplay <warp> <name>	Set or change the display name of a warp.
/warpadmin clearcooldown <player>	Clear the warp cooldown for a specific player.
/warpadmin setslot <warp> <slot>	Set the sort order or GUI slot position for a warp.

---

Permissions

Player Permissions

Permission	Description	Default
horizonswarps.warp	Allows teleporting to warps	true
horizonswarps.warps	Allows opening the warp GUI	true
horizonswarps.setwarp	Allows creating new warps	op
horizonswarps.delwarp	Allows deleting warps	op

Per-Warp Permissions

Permission	Description
horizonswarps.warp.<name>	Grants access to a specific warp that has a permission requirement set

Bypass Permissions

Permission	Description
horizonswarps.bypass.warmup	Skip the warp warmup delay
horizonswarps.bypass.cooldown	Skip the warp cooldown
horizonswarps.bypass.economy	Bypass all economy costs
horizonswarps.bypass.permission	Access all warps regardless of per-warp permission requirements

Admin Permissions

Permission	Description
horizonswarps.admin	Access to all /warpadmin commands

---

Getting Started

1. Download HorizonsWarps and place the .jar file in your server's plugins folder.
2. Start or restart your server. The plugin will generate its default configuration files.
3. Create your first warp by standing at the desired location and running /setwarp <name>.
4. Customize the warp using admin commands -- set a display name, icon, category, and optional permission.
5. Adjust the configuration in config.yml to set warmup delays, cooldowns, economy costs, GUI layout, and display preferences.
6. Customize messages by editing the language files. HorizonsWarps ships with English and German translations.
7. Players can browse all available warps with /warps and teleport with /warp <name>.

---

Configuration

HorizonsWarps is configured through its config.yml file. Key configuration sections include:

• Database -- Choose between SQLite (file-based, zero setup) and MySQL (remote, scalable). Connection pooling is handled by HikariCP.
• Teleportation -- Set warmup delays, cooldown durations, and cross-world restrictions. Configure disabled worlds.
• Warmup Display -- Select the display mode (ActionBar, Title, Both) and customize the progress bar with HEX colors, custom characters, and adjustable length.
• Sound Effects -- Configure teleport sounds with volume and pitch control.
• Particle Effects -- Set the particle type displayed on warp arrival.
• Economy -- Select a currency backend and configure teleport costs globally or per warp.
• GUI Layout -- Choose from seven layout patterns (Spaced, Wide, Centered, Diamond, Rows, Compact, Custom) and configure pagination settings.
• Categories -- Define and manage warp categories for organization.

All configuration changes can be applied at runtime with /warpadmin reload -- no server restart required.

---

Text Formatting

HorizonsWarps fully supports modern Minecraft text formatting:

• HEX colors -- Use &#RRGGBB or <#RRGGBB> syntax for any color
• Gradients -- Apply smooth color transitions across text
• ✨ text -- Automatic ✨ coloring
• Legacy codes -- Standard & color codes remain supported

This applies to warp display names, GUI elements, and all configurable messages.

---

Compatibility

Requirements

Requirement	Version
Server Software	Paper, Purpur, or Spigot
Minecraft Version	1.21 or newer
Java Version	Java 21 or newer

Soft Dependencies

All soft dependencies are optional. HorizonsWarps detects them automatically at startup.

Plugin	Purpose
Vault	Economy integration
PlayerPoints	Alternative currency
CoinsEngine	Alternative currency
PlaceholderAPI	Placeholder support for other plugins
ItemsAdder	Custom GUI warp icons
Oraxen	Custom GUI warp icons
HeadDatabase	Custom head icons
MMOItems	Custom GUI warp icons
Slimefun	Custom GUI warp icons
Nexo	Custom GUI warp icons
ExecutableItems	Custom GUI warp icons
EcoItems	Custom GUI warp icons

Metrics

HorizonsWarps uses bStats to collect anonymous usage statistics. This helps the developer understand how the plugin is used and prioritize future development. You can opt out of bStats in the bStats configuration file.

---

PlaceholderAPI

HorizonsWarps provides the following placeholders (requires PlaceholderAPI):

General Placeholders

Placeholder	Description
%horizonswarps_count%	Total number of warps on the server
%horizonswarps_total%	Alias for count
%horizonswarps_accessible%	Number of warps the player can access
%horizonswarps_list%	Comma-separated list of accessible warp names
%horizonswarps_cooldown%	Remaining teleport cooldown in milliseconds
%horizonswarps_has_cooldown%	Whether the player is on cooldown (true/false)

Per-Warp Placeholders

Replace <name> with the warp name:

Placeholder	Description
%horizonswarps_warp_<name>_world%	World name of the specified warp
%horizonswarps_warp_<name>_x%	X coordinate of the specified warp
%horizonswarps_warp_<name>_y%	Y coordinate of the specified warp
%horizonswarps_warp_<name>_z%	Z coordinate of the specified warp
%horizonswarps_warp_<name>_coords%	Formatted coordinates string
%horizonswarps_warp_<name>_creator%	Name of the player who created the warp
%horizonswarps_warp_<name>_exists%	Whether the specified warp exists (true/false)

---

Database

HorizonsWarps supports two database backends:

Backend	Best For	Setup
SQLite	Small to medium servers, single-instance setups	Zero configuration -- works out of the box
MySQL	Large servers, multi-instance setups, networks	Requires connection details in the config

Both backends use HikariCP for efficient connection pooling, ensuring reliable and performant database access even under heavy load.

---

Support

If you encounter any issues, have feature requests, or need help with configuration, feel free to reach out through the following channels:

• Issue Tracker -- Report bugs or request features on the project's issue tracker
• Discord -- Join the community Discord server for real-time support and discussion
• Modrinth Comments -- Leave a comment on the Modrinth project page

We appreciate feedback and are committed to keeping HorizonsWarps updated and reliable.