Horizons Homes

Modern home teleportation for Paper/Spigot 1.21

---

✨ Features

• Beautiful GUI - Manage all your homes through an intuitive chest-based interface
• Fully Customizable Icons - 57+ pre-configured icons with custom names & descriptions
• Custom Item Support - HeadDatabase, ItemsAdder, and Oraxen integration
• Multi-Language - English and German included, easily add more
• Economy Support - Optional costs for setting homes and teleporting (Vault)
• PlaceholderAPI - Full placeholder support for scoreboards, holograms, etc.
• SQLite & MySQL - Choose your preferred database
• Warmup & Cooldown - Configurable teleport delays with bypass permissions
• Safe Teleportation - Detects dangerous locations (lava, void, etc.)
• Permission-based Limits - Fine-grained control over home amounts per rank
• Admin Tools - Manage player homes, clear cooldowns, teleport to any home
• Respawn at Home - Optional respawn at default home on death
• Cross-World Teleportation - Enable or disable per your preference
• World Blacklist - Disable homes in specific worlds
• Hex Color Support - Full RGB color codes and gradients

---

📋 Commands

Command	Description	Permission
/home [name]	Teleport to a home (opens GUI if no name given)	horizonshomes.home
/sethome [name]	Set a home at your current location	horizonshomes.sethome
/delhome <name>	Delete a home	horizonshomes.delhome
/homes	List all your homes / Open GUI	horizonshomes.homes

Admin Commands

Command	Description
/homeadmin reload	Reload all configuration files
/homeadmin list <player>	View a player's homes
/homeadmin tp <player> <home>	Teleport to a player's home
/homeadmin delete <player> <home>	Delete a player's home
/homeadmin deleteall <player>	Delete all homes of a player
/homeadmin info <player>	View player info (homes, cooldown)
/homeadmin clearcooldown <player>	Clear a player's teleport cooldown

Command Aliases

• /home → /h
• /sethome → /createhome
• /delhome → /removehome, /deletehome
• /homes → /homelist, /listhomes
• /homeadmin → /hadmin, /homeadm

---

🔑 Permissions

Basic Permissions

Permission	Description	Default
horizonshomes.home	Teleport to homes	Everyone
horizonshomes.sethome	Set homes	Everyone
horizonshomes.delhome	Delete homes	Everyone
horizonshomes.homes	List homes	Everyone
horizonshomes.respawn	Respawn at default home	Everyone
horizonshomes.admin	Access admin commands	OP
horizonshomes.*	All permissions	OP

Limit Permissions

Control how many homes players can have:

Permission	Homes Allowed
horizonshomes.limit.3	3 homes
horizonshomes.limit.5	5 homes
horizonshomes.limit.10	10 homes
horizonshomes.limit.50	50 homes
horizonshomes.unlimited	Unlimited homes

The highest limit permission takes priority.

Bypass Permissions

Permission	Description
horizonshomes.bypass.warmup	Skip teleport warmup
horizonshomes.bypass.cooldown	Skip teleport cooldown
horizonshomes.bypass.economy	Free teleports and home creation
horizonshomes.bypass.*	All bypass permissions

---

🎨 GUI Features

Home List

• View all your homes at a glance
• Left-click: Teleport to home
• Right-click: Open home settings
• Shift+Left: Quick delete (with confirmation)
• Shift+Right: View home info (coordinates, creation date, safety status)
• Pagination for many homes

Home Settings

• Teleport - Quick teleport button
• Change Icon - Choose from 57+ customizable icons
• Rename - Rename your home via chat input
• Delete - Delete with confirmation

Icon Selection

• All icons have custom names and descriptions
• Support for custom items (HeadDatabase, ItemsAdder, Oraxen)
• Current icon highlighted with enchantment glint
• Paginated for large icon lists

---

⚙️ Configuration

config.yml

# Language: de_DE or en_US (add your own in messages/ and gui/ folders)
language: en_US

# Database: sqlite or mysql
database:
  type: sqlite
  table-prefix: "hh_"
  mysql:
    host: localhost
    port: 3306
    database: horizonshomes
    username: root
    password: ""

# Home Settings
homes:
  default-max-homes: 3        # Default limit (override with permissions)
  default-home-name: "home"   # Name when /sethome is used without argument
  case-sensitive-names: false
  max-name-length: 32
  block-unsafe-locations: true
  respawn-at-default-home: false
  allow-cross-world: true
  disabled-worlds:
    - "example_world"

# Teleport Settings
teleport:
  warmup-seconds: 3           # 0 = instant teleport
  cooldown-seconds: 30        # 0 = no cooldown
  cancel-on-move: true
  cancel-on-damage: true
  show-countdown: true
  sound: ENTITY_ENDERMAN_TELEPORT
  show-particles: true

# Economy (requires Vault)
economy:
  enabled: false
  sethome-cost: 100
  teleport-cost: 50
  delhome-cost: 0

Custom Icons

Each icon can be fully customized in gui/gui_en_US.yml:

icons:
  # Simple format (auto-generated name)
  - RED_BED
  
  # Full format with custom name and lore
  - material: RED_BED
    name: "&cRed Bed"
    lore:
      - "&7The classic home icon"
      - "&7Cozy and comfortable"
  
  # Custom items from other plugins
  - material: "hdb:12345"
    name: "&6Special Head"
    lore:
      - "&7A unique HeadDatabase icon"
      
  - material: "itemsadder:furniture:home_sign"
    name: "&aCustom Sign"
    lore:
      - "&7ItemsAdder custom item"
      
  - material: "oraxen:custom_bed"
    name: "&bOraxen Bed"
    lore:
      - "&7Special Oraxen icon"

---

📊 PlaceholderAPI

HorizonsHomes provides the following placeholders:

Placeholder	Description	Example
%horizonshomes_count%	Number of homes	3
%horizonshomes_max%	Maximum homes allowed	5 or ∞
%horizonshomes_remaining%	Homes left to create	2 or ∞
%horizonshomes_list%	Comma-separated home names	home, base, farm
%horizonshomes_has_home%	Has at least one home	true / false
%horizonshomes_cooldown%	Remaining cooldown in seconds	15
%horizonshomes_has_cooldown%	Is on cooldown	true / false

Home Placeholders

Placeholder	Description
%horizonshomes_home_<name>_world%	World name of specific home
%horizonshomes_home_<name>_x%	X coordinate
%horizonshomes_home_<name>_y%	Y coordinate
%horizonshomes_home_<name>_z%	Z coordinate
%horizonshomes_home_<name>_coords%	Formatted coordinates
%horizonshomes_home_<name>_exists%	Home exists

Replace <name> with the home name, e.g., %horizonshomes_home_base_world%

---

🔌 Soft Dependencies

HorizonsHomes integrates seamlessly with:

Plugin	Integration
Vault	Economy support for home costs
PlaceholderAPI	Placeholders for other plugins
HeadDatabase	Custom head icons (hdb:12345)
ItemsAdder	Custom item icons (itemsadder:namespace:item)
Oraxen	Custom item icons (oraxen:item_id)

All dependencies are optional - the plugin works perfectly without them!

---

📥 Installation

1. Download the latest version
2. Place HorizonsHomes.jar in your plugins/ folder
3. Restart your server
4. Edit configuration files in plugins/HorizonsHomes/
5. Use /homeadmin reload to apply changes

Requirements

• Server: Paper, Spigot, or any fork (1.21+)
• Java: 21 or higher

---

🌍 Adding Languages

1. Copy messages/messages_en_US.yml to messages/messages_xx_XX.yml
2. Copy gui/gui_en_US.yml to gui/gui_xx_XX.yml
3. Translate all strings
4. Set language: xx_XX in config.yml
5. Reload with /homeadmin reload

---

🎨 Color Codes

HorizonsHomes supports:

• Legacy codes: &a, &b, &c, etc.
• Hex colors: &#FF5555 or &x&F&F&5&5&5&5
• Gradients: <gradient:FF5555:5555FF>Text</gradient>
• MiniMessage: Full MiniMessage format support

---

🐛 Support

Found a bug or have a suggestion?

• Discord: Join our Discord

---

📄 License

This plugin is proprietary software. All rights reserved.

---

💝 Support Development

If you enjoy HorizonsHomes, please consider:

• ⭐ Leaving a review
• 🐛 Reporting bugs
• 💡 Suggesting features

---