---

✨ 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 (/homes)	List all your homes	homeplugin.command.listhome
/renamehome <old> <new>	Rename an existing home	homeplugin.command.renamehome
/relocatehome <name>	Move a home to your current location	homeplugin.command.relocatehome
/back	Return to your previous location	homeplugin.command.back.use
/spawn	Teleport to server spawn	homeplugin.command.spawn
/tpa <player>	Request to teleport to a player	homeplugin.command.tpa.use
/tpaccept <player>	Accept a teleport request	homeplugin.command.tpa.use
/tpdeny <player>	Deny a teleport request	homeplugin.command.tpa.use
/rtp	Random teleport (if enabled)	homeplugin.command.rtp
/warp <name>	Teleport to a predefined warp	homeplugin.command.warp.use

Admin / Utility Commands

Command	Description	Permission
/setspawn	Set the global spawn point for the current world	homeplugin.admin (or homeplugin.admin.spawn.set)
/delspawn	Remove the global spawn point for the current world	homeplugin.admin (or homeplugin.admin.spawn.delete)
/homeadmin <player>	Manage another player's homes (create/delete/edit)	homeplugin.admin (or homeplugin.admin.home.manage)
/cache view	View cache statistics	homeplugin.admin (or homeplugin.admin.cache.view)
/cache clearall	Clear all plugin caches	homeplugin.admin (or homeplugin.admin.cache.clear)
/cache player <name>	Clear cache for a specific player	homeplugin.admin (or homeplugin.admin.cache.player)
/lang set <code>	Set the active language (e.g. en, fr)	homeplugin.command.lang
/lang update	Update/merge language files	homeplugin.command.lang
/modules / /plugins	List loaded HomePlugin modules/extensions	homeplugin.admin
/update	Trigger plugin update (may download/replace jar and restart/shutdown)	homeplugin.admin or OP

---

🔐 Permissions

Basic Permissions

Permission	Description	Default
homeplugin.command.home	Use /home and related home teleports	true
homeplugin.command.sethome	Create/set homes	true
homeplugin.command.delhome	Delete homes	true
homeplugin.command.listhome	List your homes	true
homeplugin.command.renamehome	Rename homes	true
homeplugin.command.relocatehome	Relocate homes	true
homeplugin.command.spawn	Use /spawn	true
homeplugin.command.tpa.use	Send/accept/deny TPA requests	true
homeplugin.command.rtp	Use RTP (when enabled)	true
homeplugin.command.back.use	Use /back	op
homeplugin.command.warp.use	Use /warp	true
homeplugin.command.warp.modify	Create/modify warps	op
homeplugin.command.lang	Manage language files (/lang set /lang update)	op
homeplugin.admin	Access admin features (cache, manage others, update, modules)	op

Note: some installations/README variants show more granular admin permissions (e.g. homeplugin.admin.cache.clear) — those are optional finer-grained permissions you can implement in your permission manager.

Dynamic Home Limits

Grant limits via permissions homeplugin.limit.<N> (plugin scans 1..100 and applies the highest matching value).

• Example: homeplugin.limit.5 → 5 homes

Bypass Permissions

Permission	Description
HomePlugin.home.bypass	Bypass home limits and some placement restrictions (value taken from language/custom config: "HomePlugin.home.bypass")
homeplugin.spawn.bypassworlds	(optional) Allow /spawn even in worlds listed in Disabled-Worlds

---

⚙️ Configuration

📄 config.yml location

plugins/HomePlugin/config.yml (created on first server start).
Full default: https://github.com/fuzeblocks/HomePlugin/blob/main/src/main/resources/config.yml

🔧 Key configuration options (overview)

General / Localization

• General.Language — FRENCH, ENGLISH, SPANISH, RUSSIAN, UKRAINIAN, GERMAN, TURKISH
• General.Default-Home-Limit — base number of homes if no homeplugin.limit.* permission

Storage

• Storage.TYPE — YAML (default) or MYSQL
• Storage.MYSQL — HOST, PORT, USERNAME, PASSWORD, DATABASE (when using MySQL)

Redis (optional)

• Redis.Use-Redis — true/false (enable cross-instance cache)
• Redis.Host, Redis.Port, Redis.UseSSL, Redis.Password

Home-related

• Config.Home.Prevent-Unfair-Location — block unfair placements (true/false)
• Disabled-Worlds — list of worlds where homes cannot be created

Teleport / Warmup

• Teleport.Task-Duration — warmup seconds before teleport
• Teleport.Use-Title, Teleport.Use-Message — show notifications
• Teleport.Particles-After-Teleport — show particles on arrival
• Teleport.Skip-If-Op — operators skip warmup

TPA

• Tpa.Enabled — enable TPA system
• Tpa.Tpa-Duration — seconds before a TPA request expires

RTP

• RTP.Enabled — enable random teleport
• RTP.Cooldown-Seconds — cooldown between uses
• RTP.Max-Radius — maximum radius from spawn

Economy (Vault)

• Economy.UseEconomy — enable economy integration
• Economy.Home-Creation-Price — cost to create a home
• Economy.Home-Teleport-Price — cost to teleport to home
• Economy.Tpa-Request-Price — cost to send TPA
• Economy.RTP-Price — cost to use RTP

Feature Toggles

• Features.Enable-Home, Features.Enable-TPA, Features.Enable-Spawn, Features.Enable-Warp — enable/disable features

---

If you want, I can:

• generate a ready-to-paste corrected README snippet with these exact keys,
• or scan the code/plugin.yml to produce a table that exactly matches declared permissions and defaults and fix any plugin.yml vs code mismatches (recommended).

---

🧩 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
• Permission-Driven - Flexible limits and restrictions via permissions

---

✅ Compatibility

• Minecraft: 1.14+ (declared api-version: 1.14)
• Server: Paper, Spigot, and derivatives
• Java: Java 11+
• 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	✅ Complete
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.

---