HorizonsHomes

HorizonsHomes is a modern, feature-rich home teleportation plugin built for Paper, Purpur, and Spigot 1.21+. It gives your players a seamless home management experience with a beautiful GUI, flexible economy support, and deep configurability -- all backed by robust SQLite or MySQL storage.

Whether you run a small survival server or a large network, HorizonsHomes adapts to your needs with permission-based home limits, cross-world teleportation, warmup and cooldown systems, and full multilingual support.

---

Features at a Glance

• Multiple homes per player with permission-based limits
• Beautiful GUI for managing homes (teleport, rename, change icon, delete)
• Safe location detection -- prevents setting homes in dangerous locations
• Warmup and cooldown systems with multiple display modes
• Economy integration with five currency backends
• Custom item support from eight external item plugins
• Cross-world teleportation with per-world configuration
• Respawn at home on death
• Full HEX color support including gradients and rainbow text
• SQLite and MySQL database backends via HikariCP
• PlaceholderAPI integration
• Multilingual -- English and German out of the box

---

Home Management

Multiple Homes with Limits

Every player can set multiple homes. The number of allowed homes is controlled through permissions:

• horizonshomes.limit.<n> -- Grants the player exactly <n> homes (e.g., horizonshomes.limit.5)
• horizonshomes.unlimited -- Grants unlimited homes

The plugin automatically resolves the highest limit a player has. A sensible default limit can also be configured for players without any specific limit permission.

Home Naming

Home names are validated against a configurable regex pattern to keep things clean and consistent. Names are capped at a maximum length of 32 characters. Players can rename existing homes at any time, either through commands or the GUI.

Safe Location Detection

When a player sets a home, HorizonsHomes checks the surrounding environment for hazards. The plugin prevents homes from being set in:

• Lava or fire
• The void (below the world)
• Suffocating blocks (inside solid materials)

This keeps players safe and avoids frustrating deaths on teleport.

---

Teleportation System

Cross-World Teleportation

Players can teleport to homes in any world on the server. This feature is fully configurable:

• Enable or disable cross-world teleportation globally
• Disable teleportation to or from specific worlds individually

Warmup System

Teleportation can require a warmup delay before the player is moved. The warmup is fully configurable:

• Configurable delay in seconds
• Cancel on move -- the warmup is interrupted if the player moves
• Cancel on damage -- the warmup is interrupted 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 configurable characters, length, and HEX colors
Title	Displays a title and subtitle countdown on screen
Both	Combines ActionBar progress bar and Title display simultaneously
Chat	Sends countdown messages in chat

The progress bar is highly customizable:

• Configurable bar length (number of characters)
• Custom filled and unfilled characters
• Full HEX color support for both filled and unfilled portions

Cooldown System

After teleporting, a cooldown period can be enforced before the player can teleport again. This prevents teleport spam and can be bypassed with the appropriate permission.

Sound Effects

HorizonsHomes supports two configurable sound events:

• Teleport sound -- played when the player arrives at their home
• Countdown tick sound -- played on each second of the warmup countdown

Both sounds have configurable volume and pitch values, giving you full control over the audio experience.

Particle Effects

A configurable particle effect is displayed at the teleport destination when a player arrives, adding a visual flair to each teleport.

---

Economy Integration

HorizonsHomes supports charging players for home-related actions. Each action can have an independent cost:

Action	Description
Set Home	Charge players when they create a new home
Teleport	Charge players each time they teleport to a home
Delete Home	Charge players when they remove a home
Rename Home	Charge players when they rename an existing home

Supported Currencies

The plugin supports five different currency backends:

Currency	Description
Vault	Standard economy integration via Vault-compatible plugins
PlayerPoints	Uses PlayerPoints as the currency
CoinsEngine	Integrates with CoinsEngine for custom 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 (configurable material)

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

---

GUI System

HorizonsHomes includes a polished graphical interface for managing homes. Players open the GUI with /homes and can perform all home management tasks visually.

GUI Features

• Browse all homes in a paginated, easy-to-navigate layout
• Teleport to any home with a single click
• Change the icon of a home to any item or custom item
• Rename a home directly from the GUI
• Delete a home with confirmation

Custom Item Support

Home 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

These integrations are detected automatically -- just install the plugin and it works.

---

Respawn at Home

When enabled, players who have a default home set will respawn there upon death instead of at the world spawn. This is toggled by a dedicated permission and provides a convenient survival experience.

---

Commands

Player Commands

Command	Description	Permission
/home [name]	Teleport to a home. If no name is given, teleports to the default home.	horizonshomes.home
/sethome [name]	Set a new home at your current location. If no name is given, a default name is used.	horizonshomes.sethome
/delhome <name>	Delete an existing home.	horizonshomes.delhome
/homes	Open the home management GUI.	horizonshomes.homes

Admin Commands

All admin commands are subcommands of /homeadmin and require the horizonshomes.admin permission.

Command	Description
/homeadmin reload	Reload the plugin configuration and language files.
/homeadmin list <player>	List all homes of a specific player.
/homeadmin tp <player> <home>	Teleport to a specific home of another player.
/homeadmin delete <player> <home>	Delete a specific home of another player.
/homeadmin deleteall <player>	Delete all homes of a specific player.
/homeadmin info <player> <home>	View detailed information about a specific home.
/homeadmin clearcooldown <player>	Clear the teleport cooldown for a specific player.

---

Permissions

Player Permissions

Permission	Description	Default
horizonshomes.home	Allows teleporting to homes	true
horizonshomes.sethome	Allows setting homes	true
horizonshomes.delhome	Allows deleting homes	true
horizonshomes.homes	Allows opening the home GUI	true
horizonshomes.respawn	Respawn at default home on death	false

Limit Permissions

Permission	Description
horizonshomes.limit.<n>	Sets the player's home limit to <n> (e.g., horizonshomes.limit.3)
horizonshomes.unlimited	Grants unlimited homes

Bypass Permissions

Permission	Description
horizonshomes.bypass.warmup	Skip the teleport warmup delay
horizonshomes.bypass.cooldown	Skip the teleport cooldown
horizonshomes.bypass.economy	Bypass all economy costs
horizonshomes.bypass.world	Bypass cross-world teleportation restrictions

Admin Permissions

Permission	Description
horizonshomes.admin	Access to all /homeadmin commands

---

Getting Started

1. Download HorizonsHomes 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. Configure home limits by assigning horizonshomes.limit.<n> permissions to your permission groups.
4. Adjust the configuration in config.yml to set warmup delays, cooldowns, economy costs, and display preferences.
5. Customize messages by editing the language files. HorizonsHomes ships with English and German translations.
6. Players can immediately start using /sethome and /home to manage their homes.

---

Configuration

HorizonsHomes 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 for optimal performance.
• Teleportation -- Set warmup delays, cooldown durations, and cross-world restrictions. Configure which worlds to disable.
• Warmup Display -- Choose the display mode (ActionBar, Title, Both, Chat) and customize the progress bar appearance with HEX colors.
• Sound Effects -- Configure teleport and countdown sounds with volume and pitch.
• Particle Effects -- Set the particle type displayed on teleport.
• Economy -- Select a currency backend and set costs for each action (sethome, teleport, delhome, rename).
• Home Naming -- Define a regex validation pattern and maximum name length.
• Safe Location -- Toggle safety checks for dangerous locations.
• GUI -- Customize the home management interface layout and behavior.
• Respawn -- Enable or disable respawning at the default home on death.

All changes can be applied at runtime using /homeadmin reload.

---

Text Formatting

HorizonsHomes fully supports modern Minecraft text formatting:

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

---

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. HorizonsHomes 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 item icons
Oraxen	Custom GUI item icons
HeadDatabase	Custom head icons
MMOItems	Custom GUI item icons
Slimefun	Custom GUI item icons
Nexo	Custom GUI item icons
ExecutableItems	Custom GUI item icons
EcoItems	Custom GUI item icons

Metrics

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

---

PlaceholderAPI

HorizonsHomes provides the following placeholders (requires PlaceholderAPI):

General Placeholders

Placeholder	Description
%horizonshomes_count%	Number of homes owned by the player
%horizonshomes_max%	Maximum homes allowed (displays "∞" if unlimited)
%horizonshomes_remaining%	Remaining homes the player can create (displays "∞" if unlimited)
%horizonshomes_list%	Comma-separated list of all home names
%horizonshomes_has_home%	Whether the player has at least one home (true/false)
%horizonshomes_cooldown%	Remaining teleport cooldown in milliseconds
%horizonshomes_has_cooldown%	Whether the player is on cooldown (true/false)

Per-Home Placeholders

Replace <name> with the home name:

Placeholder	Description
%horizonshomes_home_<name>_world%	World name of the specified home
%horizonshomes_home_<name>_x%	X coordinate of the specified home
%horizonshomes_home_<name>_y%	Y coordinate of the specified home
%horizonshomes_home_<name>_z%	Z coordinate of the specified home
%horizonshomes_home_<name>_coords%	Formatted coordinates string (e.g., "100, 64, -200")
%horizonshomes_home_<name>_exists%	Whether the specified home exists (true/false)

---

Database

HorizonsHomes 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 under 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 HorizonsHomes updated and reliable.