---

✨ Features

🏠 Core Functionality

• Named Homes - Set multiple homes with custom names and optional metadata
• Global Spawn - Server-wide spawn point management
• Teleport Requests (TPA) - Request to teleport to other players with configurable timeout
• Random Teleport (RTP) - Random teleport with cooldown and radius controls
• Back Command - Return to your previous location

🗄️ Flexible Storage

• YAML (default) - Simple file-based storage
• MySQL - Full database support for larger servers
• Redis Caching - Optional cross-instance cache synchronization

🎮 Player Experience

• Interactive GUI - Visual home management interface
• Multiple Languages - French, English, Spanish, Russian, Ukrainian, German, Turkish
• Teleport Warmup - Configurable delays with titles, messages, and particles
• Permission-Based Limits - Dynamic home limits via permissions

🔌 Integrations

• PlaceholderAPI - Rich placeholders for homes, counts, and locations
• Vault Economy - Optional costs for home creation, teleportation, TPA, and RTP

🛠️ Administration

• Admin Tools - Manage other players' homes, spawn points, and cache
• World Restrictions - Block home creation in specific worlds
• Location Validation - Prevent unfair placements
• Modular Architecture - Extensible plugin loader for custom modules

---

⬇️ Installation

1. Download the latest release from Releases or build from source
2. Place the JAR file into your server's plugins/ folder
3. Start your server to generate default configuration files
4. Configure plugins/HomePlugin/config.yml to your preferences
5. Restart or reload your server

Quick Configuration Tips

• ✅ Works out-of-the-box with YAML storage
• 🗄️ For MySQL: Configure credentials in config.yml before restarting
• 🚀 For Redis: Set Use-Redis: true and ensure Redis server is accessible

---

🧾 Commands

Player Commands

Command	Description	Permission
/sethome [name] [info]	Create or update a home	homeplugin.command.sethome
/home [name]	Teleport to a home (opens GUI if no name)	homeplugin.command.home
/delhome <name>	Delete a home	homeplugin.command.delhome
/listhome	List all your homes	homeplugin.command.listhome
/renamehome <old> <new>	Rename an existing home	homeplugin.command.home
/relocatehome <name>	Move a home to your current location	homeplugin.command.home
/back	Return to your previous location	homeplugin.back.use
/spawn	Teleport to server spawn	homeplugin.command.spawn
/tpa <player>	Request to teleport to a player	homeplugin.command.tpa
/tpaccept [player]	Accept a teleport request	homeplugin.command.tpa
/tpdeny [player]	Deny a teleport request	homeplugin.command.tpa
/rtp	Random teleport	homeplugin.command.rtp

Admin Commands

Command	Description	Permission
/setspawn	Set the global spawn point	homeplugin.admin
/delspawn	Remove the global spawn point	homeplugin.admin
/homeadmin <player>	Manage another player's homes	homeplugin.admin
/cache view	View cache statistics	homeplugin.admin
/cache clearall	Clear all plugin caches	homeplugin.admin
/cache player <name>	Clear cache for a specific player	homeplugin.admin
/lang set <code>	Set the active language	homeplugin.lang.update
/lang update	Update language files (merge new keys)	homeplugin.lang.update
/plugins	List loaded HomePlugin modules	homeplugin.admin

---

🔐 Permissions

Basic Permissions

Permission	Description	Default
homeplugin.command.home	Use home commands	true
homeplugin.command.sethome	Create homes	true
homeplugin.command.delhome	Delete homes	true
homeplugin.command.listhome	List homes	true
homeplugin.command.spawn	Use spawn	true
homeplugin.command.tpa	Use TPA system	true
homeplugin.command.rtp	Use random teleport	true
homeplugin.back.use	Use /back command	op
homeplugin.admin	Admin features	op
homeplugin.lang.update	Manage languages	op

Dynamic Home Limits

Set custom home limits using homeplugin.limit.<number>:

• homeplugin.limit.5 - 5 homes
• homeplugin.limit.10 - 10 homes
• homeplugin.limit.unlimited - No limit

The plugin scans from 1-100 and applies the highest value held by the player.

Bypass Permissions

Permission	Description
homeplugin.bypass.limit	Ignore home limits
homeplugin.bypass.validation	Bypass location restrictions
homeplugin.bypass.cooldown	Ignore teleport cooldowns

---

⚙️ Configuration

📄 Configuration File

The plugin's configuration is located at plugins/HomePlugin/config.yml after the first server start.

📖 View Full config.yml

🔧 Configuration Overview

Language & Localization

Set your preferred language from: FRENCH, ENGLISH, SPANISH, RUSSIAN, UKRAINIAN, GERMAN, TURKISH

Storage Backend

Choose between YAML (simple file-based) or MySQL (database) storage:

• TYPE: "YAML" - Default, no additional setup required
• TYPE: "MYSQL" - Configure HOST, PORT, USERNAME, PASSWORD, DATABASE

Redis Cache (Optional)

Enable Use-Redis: true for cross-instance synchronization. Configure host, port, SSL, and password as needed.

Home Settings

• Default-Home-Limit - Base home limit (override with permissions)
• Prevent-Unfair-Location - Block unsafe home placements
• Disabled-Worlds - List of worlds where homes cannot be created

Teleport Warmup & Effects

• Task-Duration - Delay before teleport (seconds)
• Use-Title / Use-Message - Show teleport notifications
• Particles-After-Teleport - Spawn particles on arrival
• Skip-If-Op - Instant teleport for operators

TPA System

• Tpa-Duration - Request expiration time (seconds)

Random Teleport (RTP)

• Enabled - Enable/disable RTP feature
• Cooldown-Seconds - Cooldown between uses
• Max-Radius - Maximum teleport distance from spawn

Economy (Vault Integration)

• UseEconomy - Enable economy features
• Home-Creation-Price - Cost to create a home
• Home-Teleport-Price - Cost to teleport to a home
• Tpa-Request-Price - Cost to send TPA request
• RTP-Price - Cost to use random teleport

Feature Toggles

Enable or disable specific features:

• Enable-TPA - TPA system
• Enable-Spawn - Spawn teleportation
• Enable-Home - Home system

---

🧩 Integrations

PlaceholderAPI

HomePlugin provides rich placeholders for use in other plugins:

Placeholder	Description
%homeplugin_homes%	Comma-separated list of home names
%homeplugin_homes_numbers%	Total number of homes
%homeplugin_has_homes%	true if player has homes
%homeplugin_home_location_<name>%	Formatted location
%homeplugin_home_exists_<name>%	Check if home exists
%homeplugin_home_world_<name>%	Home world name
%homeplugin_home_coordinates_<name>%	Raw coordinates (X Y Z)
%homeplugin_home_teleport_price%	Teleport cost
%homeplugin_home_creation_price%	Creation cost
%homeplugin_tpa_request_price%	TPA request cost
%homeplugin_rtp_price%	RTP cost

Vault Economy

Configure optional costs for various actions through Vault integration. Supports any Vault-compatible economy plugin.

---

🌍 Supported Languages

Built-in language support with fully customizable YAML files:

• 🇫🇷 French (FRENCH)
• 🇬🇧 English (ENGLISH)
• 🇪🇸 Spanish (SPANISH) - by Henri Topper
• 🇷🇺 Russian (RUSSIAN)
• ✨ Ukrainian (UKRAINIAN)
• 🇩🇪 German (GERMAN)
• 🇹🇷 Turkish (TURKISH) - by Xenetotyp3

Set your language in config.yml or use /lang set <LANGUAGE> in-game.

---

🧑‍💻 Developer API

HomePlugin provides a comprehensive API for developers to integrate and extend functionality.

📚 Documentation

• JavaDocs - Complete API reference
• Wiki - Usage guides and examples
  • Events
  • Home Managers
  • Spawn Managers

📦 Dependency Management

Add HomePlugin as a dependency via JitPack:

Maven:

<repository>
  <id>jitpack.io</id>
  <url>https://jitpack.io</url>
</repository>

<dependency>
  <groupId>com.github.fuzeblocks</groupId>
  <artifactId>HomePlugin</artifactId>
  <version>Tag</version>
</dependency>

Gradle (Groovy):

repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    implementation 'com.github.fuzeblocks:HomePlugin:Tag'
}

Gradle (Kotlin DSL):

repositories {
    maven("https://jitpack.io")
}

dependencies {
    implementation("com.github.fuzeblocks:HomePlugin:Tag")
}

Replace Tag with the desired version/release tag.

---

🧱 Architecture

HomePlugin features a modular, performance-focused architecture:

• Storage Abstraction - Unified interface for YAML and MySQL backends
• Optional Redis Layer - Cross-instance caching and synchronization
• Event System - Comprehensive events for all plugin actions
• Extension System - Internal module loader for custom functionality
• Async Operations - Database queries run asynchronously
• Permission-Driven - Flexible limits and restrictions via permissions

---

✅ Compatibility

• Minecraft: 1.14+ (declared api-version: 1.14)
• Server: Paper, Spigot, and derivatives
• Java: Java 8+
• Soft Dependencies: PlaceholderAPI, Vault

---

🗺️ Roadmap

Feature	Status
Per-home economy costs	✅ Complete
Offline player home editing	✅ Complete
Edit existing homes	✅ Complete
/back command	✅ Complete
Clickable chat messages	✅ Complete
Public homes	📝 Planned
Warps	📝 On the way
UI/style refresh	📝 Planned
BlueMap and Dynmap integration	📝 Planned

Have a suggestion? Open a Discussion or join our Discord!

---

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Guidelines

• Use clear, descriptive commit messages
• Follow existing code style and conventions
• Test your changes thoroughly
• Update documentation as needed
• Discuss major changes in Issues or Discord first

---

💬 Support

Need help? Have questions?

• 📖 Wiki - Documentation and guides
• 🐛 Issues - Bug reports and feature requests
• 💬 Discord - Community support and discussion
• 📧 Discussions - General questions and ideas

---

📄 License

HomePlugin is licensed under the Apache License 2.0.

---