Перейти к содержимому
Mineforgian

HomePlugin

A lightweight and efficient plugin to manage player homes and world spawns, featuring optional caching and powerful synchronization tools.

Загрузки
17K
Подписчики
21
Обновлён
30 мая 2026 г.
Лицензия
Apache-2.0

Опубликован 12 декабря 2023 г.

Исходный кодСообщить об ошибке

🏡 HomePlugin

A lightweight, flexible home & teleport management plugin for Paper/Spigot servers

sponsor Discord License

Stable • Fast • Modular • API-Driven

FeaturesInstallationCommandsConfigurationAPI Documentation

Usage


✨ 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.command.renamehome Rename home true
homeplugin.command.relocatehome Relocate home 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

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

Bypass Permissions

Permission Description
HomePlugin.home.bypass Ignore home limits

⚙️ 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

📦 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 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 📝 Beta
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.


Made with ❤️ by fuzeblocks

If you find this plugin useful, consider sponsoring to support development!

Ченджлог

0.8.7-warps_dev-SNAPSHOTБета1.21.9, 1.21.10, 1.21.11 · 17 марта 2026 г.

🚀 The Warps Update (warps-dev)

A massive overhaul introducing full Warp capabilities, GUI integration, and warp customization!

  • Warp Management: Create, delete, and manage server warps with dedicated command autocompletion.
  • Advanced Warp GUI: Manage warps visually with intuitive items for changing expiration, lore, permissions, renaming, and custom icons.
  • Economy System Integration: Set usage pricing and manage costs (increase, decrease, delete) for warp modifications directly in the GUI.
  • Localization: Added extensive translation support for teleportation messages, warp commands, and GUI items (French, Turkish, and more).
  • Expiration & Permissions: Fine-tune who can use warps and how long they last.

✨ New Features & Improvements

✅ Offline Home Management

  • Manage player homes while players are offline.
  • Supports both SQL and YAML storage systems.

✅ Major Manager Refactor

  • Refactored the following managers to improve code structure, readability, and maintainability:
    • Home
    • Spawn
    • Status
    • Task
    • Teleportation
    • Permission management

✅ Localization & Telemetry

  • Fixed missing language keys and added Turkish translation.
  • Added GUI not supported message to multiple language files.
  • New telemetry to collect used language metrics to help us better understand user demographics and improve localization.

✅ System & GUI Improvements

  • Upgraded JDK version from 17 to 21.
  • Added update checking and automated download tools.
  • Added priority handling in GUIs.
  • Clear message displayed when GUI is not supported.

🛠️ What's Changed

  • Warps System: Merge of the warps-dev branch functionalities!
  • Refactor Home, Spawn, Status, Task, and Teleportation managers → PR #43
  • Fix missing lang keys and add Turkish translation → PR #46
  • Implement offline home management with SQL and YAML support → PR #47
  • Add GUI not supported message to multiple language files and priority handling → PR #48
  • Collect used language → PR #50

🔗 Full Changelog

0.8.5...0.8.7

👤 Contributors

@fuzeblocks

0.8.6-main-SNAPSHOTРелиз1.21.9, 1.21.10, 1.21.11 · 10 января 2026 г.

✨ HomePlugin 0.8.6 – Refactor, Offline Homes & Localization Update

✨ New Features & Improvements

Offline Home Management

  • Manage player homes while players are offline
  • Supports both SQL and YAML storage systems

Major Manager Refactor

  • Refactored the following managers to improve code structure, readability, and maintainability:
    • Home
    • Spawn
    • Status
    • Task
    • Teleportation

Localization Improvements

  • Fixed missing language keys
  • Added Turkish translation
  • Added GUI not supported message to multiple language files

GUI Improvements

  • Added priority handling
  • Clear message displayed when GUI is not supported

🛠️ What's Changed

  • Refactor Home, Spawn, Status, Task, and Teleportation managers
    → PR #43
  • Fix missing lang keys and add Turkish translation
    → PR #46
  • Implement offline home management with SQL and YAML support
    → PR #47
  • Add GUI not supported message to multiple language files and priority handling
    → PR #48

🔗 Full Changelog

https://github.com/fuzeblocks/HomePlugin/compare/0.8.5...0.8.6

👤 Contributors

  • @fuzeblocks
0.8.5-main-SNAPSHOTРелиз1.21.8, 1.21.9, 1.21.10 · 4 декабря 2025 г.
0.8.4-main-SNAPSHOTРелиз1.21.8, 1.21.9, 1.21.10 · 29 ноября 2025 г.

Improve stability and bug fix

What's Changed

New Contributors

Full Changelog: https://github.com/fuzeblocks/HomePlugin/compare/0.8.3...0.8.4

0.8.3-main-SNAPSHOTБета1.21.8, 1.21.9, 1.21.10 · 19 ноября 2025 г.

✨ New Features & Enhancements

Clickable Messages (Interactive Chat Features)

Commands now support clickable and hoverable chat messages, improving player interaction. Includes:

  • Click suggestions in chat
  • Interactive teleportation messages
  • Improved UX for /home, /sethome, /tpa, and more
CacheUsage

Integrated from the clickable-messages-dev branch.


🌍 Extended Language Support

Additional built-in languages have been added. Documentation and generated files were updated accordingly.


🔧 RTP Improvements

  • Fixed case sensitivity issues in the RTP event handler
  • maxY is now automatically determined based on the world environment
  • Safer random teleportation logic
  • RTP refined as part of recent refactoring

🔐 New Config Option: Skip-If-Op

Admins can now bypass certain limits if they are OP:

  Skip-If-Op: true

📊 bStats Integration

The plugin now includes bStats to anonymously collect usage metrics, helping improve future updates. Added via PR #28.


📝 Documentation & Javadoc Updates

  • Updated all generated Javadoc files
  • Cleaned timestamps
  • Updated event package structure
  • Improved GitHub Pages deployment preparation

What's Changed

Full Changelog: https://github.com/fuzeblocks/HomePlugin/compare/0.8.2...0.8.3

0.8.2-main-SNAPSHOTАльфа1.21.8, 1.21.9, 1.21.10 · 22 октября 2025 г.

✨ New Features & Enhancements

✅ Add /renamehome command – allows players to rename their existing homes

✅ Add /relocatehome command – allows players to change the location of an existing home

✅ Add economy configuration options in config.yml:

Economy:
  UseEconomy: false            # Enable or disable economy features (default: false)
  HomeCreationCost: 100.0      # Cost to create a new home (0 to disable)
  Home-Teleport-Price: 50.0    # Cost to teleport to a home (0 to disable)
  Tpa-Request-Price: 20.0      # Cost to send a /tpa request (0 to disable)
  Rtp-Price: 150.0             # Cost to use /rtp command (0 to disable)

✅ Add Javadoc comments to classes and methods for improved code documentation

✅ Add Maven Shade and Javadoc plugins to pom.xml for packaging and documentation generation

✅ Generate Javadoc HTML files in docs/ for GitHub Pages deployment

✅ Add VaultAPI dependency to pom.xml

✅ /back implemented

✅ Minor fixes: remove debug logging, update timestamps in generated Javadoc, and resolve merge issues

0.8.0-main-SNAPSHOTРелиз1.21.6, 1.21.7, 1.21.8 · 31 августа 2025 г.

New Features & Enhancements

  • ✅ Added /rtp command (Random Teleportation)
    • Teleports players to a safe random location.
    • Always places player at the highest safe block.
    • Prevents unsafe teleportation (lava, void, unsafe blocks).
  • ⏳ Added RTP cooldown system:
    • Configurable cooldown per player in config.yml.
    • Players receive a message if they must wait before teleporting again.
  • 🌐 Added localization support:
    • New language entries in french.yml, english.yml, spanish.yml.
    • Fully translatable messages for teleportation in progress, success, failure, and cooldown.

🧼 Refactoring & Internal Changes

  • Unified RTP request handling with RtpRequestStore (supports Redis & Local storage).

📌 Notes

  • ⚙️ Configure RTP cooldown in Config.Rtp.Cooldown.
  • 🔁 All changes are backward-compatible.
  • 🌐 To update language files, use /lang update.

What's Changed

Full Changelog: https://github.com/fuzeblocks/HomePlugin/compare/0.7.9...0.8

0.7.9-main-SNAPSHOTРелиз1.21.6, 1.21.7, 1.21.8 · 30 августа 2025 г.

✨ New Features & Enhancements

New TPA System (Teleport Requests)

  • Added /tpa, /tpaccept, /tpdeny with full tab-completion support.
  • Requests are now stored via an abstraction TpaRequestStore with two implementations:
    • LocalTpaRequestStore (in-memory, fast for single-server setups)
    • RedisTpaRequestStore (shared across multiple servers, ideal for networks)
  • Players can only teleport once the target accepts the request.
  • Added configurable TPA timeout (Config.Tpa.Tpa-duration, default: 30 seconds).

Improved Tab Completion

  • /tpaccept <player> and /tpdeny <player> now suggest only valid requesters.
  • Dynamically pulls data from cache/Redis for real-time accuracy.

CacheManager Integration

  • Centralized access for all active TPA requests.
  • Supports both Redis and Local modes seamlessly.

🔧 Internal Changes

  • Refactored TpaRequestStore to unify Redis & Local implementations.
  • Added getAllTpaSenders() + getTpaTarget(UUID) to simplify request lookups.
  • Safer cleanup of expired or invalid TPA requests.
  • Enhanced Redis handling with UUID-safe storage and retrieval.

🌐 Language Updates

Added new language entries in french.yml, english.yml, and custom.yml:

  • Tpa.Request-Sent → "You have sent a teleport request to {player}"
  • Tpa.Request-Received → "{player} has sent you a teleport request. Use /tpaccept or /tpdeny."
  • Tpa.Request-Expired → "Your teleport request to {player} has expired."
  • Tpa.No-Pending → "You have no pending TPA requests."

📌 Notes

  • ⚙️ If running in a networked setup, enable Redis in config.yml.
  • 🔁 All changes remain backward-compatible.
  • 🌐 Update language files manually with /lang update.

Full Changelog: https://github.com/fuzeblocks/HomePlugin/compare/0.7.8...0.7.9

Комментарии

Загружаем…