HomePlugin-by-fuzeblocks

--- ## ✨ 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](https://github.com/fuzeblocks/HomePlugin/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 ` | Delete a home | `homeplugin.command.delhome` | | `/listhome` (`/homes`) | List all your homes | `homeplugin.command.listhome` | | `/renamehome ` | Rename an existing home | `homeplugin.command.renamehome` | | `/relocatehome ` | 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 ` | Request to teleport to a player | `homeplugin.command.tpa.use` | | `/tpaccept ` | Accept a teleport request | `homeplugin.command.tpa.use` | | `/tpdeny ` | Deny a teleport request | `homeplugin.command.tpa.use` | | `/rtp` | Random teleport (if enabled) | `homeplugin.command.rtp` | | `/warp ` | 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 ` | 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 ` | Clear cache for a specific player | `homeplugin.admin` (or `homeplugin.admin.cache.player`) | | `/lang set ` | 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.` (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_%` | Formatted location | | `%homeplugin_home_exists_%` | Check if home exists | | `%homeplugin_home_world_%` | Home world name | | `%homeplugin_home_coordinates_%` | 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 ` in-game. --- ## 🧑‍💻 Developer API HomePlugin provides a comprehensive API for developers to integrate and extend functionality. ### 📚 Documentation - **[JavaDocs](https://fuzeblocks.github.io/HomePlugin/)** - Complete API reference - **[Wiki](https://github.com/fuzeblocks/HomePlugin/wiki)** - Usage guides and examples - [Events](https://github.com/fuzeblocks/HomePlugin/wiki/Events) - [Home Managers](https://github.com/fuzeblocks/HomePlugin/wiki/Home-API-usage) - [Spawn Managers](https://github.com/fuzeblocks/HomePlugin/wiki/Spawn-API-usage) ### 📦 Dependency Management Add HomePlugin as a dependency via JitPack: **Maven:** ```xml jitpack.io https://jitpack.io com.github.fuzeblocks HomePlugin Tag ``` **Gradle (Groovy):** ```groovy repositories { maven { url 'https://jitpack.io' } } dependencies { implementation 'com.github.fuzeblocks:HomePlugin:Tag' } ``` **Gradle (Kotlin DSL):** ```kotlin 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](https://github.com/fuzeblocks/HomePlugin/discussions) or join our [Discord](https://discord.gg/5zJyKz6Nfm)! --- ## 🤝 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](https://github.com/fuzeblocks/HomePlugin/wiki)** - Documentation and guides - 🐛 **[Issues](https://github.com/fuzeblocks/HomePlugin/issues)** - Bug reports and feature requests - 💬 **[Discord](https://discord.gg/5zJyKz6Nfm)** - Community support and discussion - 📧 **[Discussions](https://github.com/fuzeblocks/HomePlugin/discussions)** - General questions and ideas --- ## 📄 License HomePlugin is licensed under the [Apache License 2.0](https://github.com/fuzeblocks/HomePlugin?tab=Apache-2.0-1-ov-file). ---

**Made with ❤️ by [fuzeblocks](https://github.com/fuzeblocks)** If you find this plugin useful, consider [sponsoring](https://client.pristis.fr/aff.php?aff=2) to support development!