# 🏡 HomePlugin **A lightweight, flexible home & teleport management plugin for Paper/Spigot servers** [![](https://jitpack.io/v/fuzeblocks/HomePlugin.svg)](https://jitpack.io/#fuzeblocks/HomePlugin) [![sponsor](https://img.shields.io/badge/Sponsor-Support%20Development-blue)](https://client.pristis.fr/aff.php?aff=2) [![Discord](https://img.shields.io/discord/1394947383560900618?color=5865F2&logo=discord&logoColor=white&label=Discord)](https://discord.gg/5zJyKz6Nfm) [![License](https://img.shields.io/badge/license-Apache--2.0-orange.svg)](https://github.com/fuzeblocks/HomePlugin?tab=Apache-2.0-1-ov-file) **Stable • Fast • Modular • API-Driven** [Features](#-features) • [Installation](#%EF%B8%8F-installation) • [Commands](#-commands) • [Configuration](#%EF%B8%8F-configuration) • [API Documentation](https://fuzeblocks.github.io/HomePlugin/) ![Usage](https://bstats.org/signatures/bukkit/HomePlugin.svg)

--- ## ✨ 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!

fuzeblocks

Pinned plugins

HomePlugin-by-fuzeblocks

Organizations

Stars

Watching