🏡 HomePlugin (by fuzeblocks)

A lightweight, flexible home/spawn/teleport management plugin for Paper/Spigot servers. HomePlugin supports named homes, global spawn, TPA requests, random teleport (RTP), optional Redis caching, YAML or MySQL storage backends, multilingual support, economy integration, and a modular extension API for internal plugin modules.

Stable • Fast • Modular • API‑Driven

✨ Features

Category	Highlights
Homes & Spawn	Named homes, GUI/list access, global spawn set/remove
Teleport Systems	TPA requests with timeout, RTP with cooldown & radius
Storage	YAML (default) or MySQL (config‑selectable)
Caching	Optional Redis layer (Jedis) when enabled
Limits	Per‑player home limits via permissions `homeplugin.limit.<n>`
Validation	Prevent unfair placements / block disabled worlds
Localization	Built‑in language system (French, English, Spanish) + editable YAML
PlaceholderAPI	Rich placeholders for homes, counts, and locations
Admin Tools	Manage other players’ homes, spawn, cache, language files
Modular Loader	Internal plugin loader to register HomePlugin modules
Tasks / Warmup	Delayed teleports with titles/messages/particles
Economy	Optional costs via Vault (create/teleport/TPA/RTP)

🧾 Commands

Command	Description	Notes
`/sethome [name] [info]`	Set (or overwrite) a home at your current position	`info` optional metadata
`/home [name]`	Teleport to a home; opens GUI if no name is provided	GUI depends on config
`/home`	Open homes GUI (if enabled)
`/delhome [name]`	Delete a named home
`/listhome`	List all your homes in chat	Text alternative to GUI
`/renamehome [name] [newname]`	Rename an existing home
`/relocatehome [name]`	Move an existing home to your current location
`/back`	Teleport back to your previous location
`/spawn`	Teleport to global spawn	Requires spawn set
`/setspawn`	Set global spawn at current location	Admin
`/delspawn`	Remove the current global spawn	Admin
`/tpa <player>`	Send a teleport request to a player	Times out via `Tpa-duration`
`/tpaccept [player]`	Accept pending TPA request	Player optional
`/tpdeny [player]`	Deny pending TPA request	Player optional
`/rtp`	Random teleport within configured radius	Cooldown applies
`/homeadmin <player>`	View/manage another player’s homes	Admin
`/cache view`	View cache status	Admin
`/cache clearall`	Clear all plugin caches	Admin
`/cache player <name>`	Clear cache for a specific player	Admin
`/plugins`	List loaded HomePlugin internal modules	Admin (not Bukkit `/plugins`)
`/lang update`	Update base language files (add‑only merge)	Admin
`/lang merge`	Merge new keys into language files	Admin
`/lang set <code>`	Switch active language (e.g., `FRENCH`)	Admin

🔐 Permissions

Permission	Purpose	Default
`homeplugin.command.home`	Use `/home` (teleport/GUI)	true
`homeplugin.command.sethome`	Use `/sethome`	true
`homeplugin.command.delhome`	Use `/delhome`	true
`homeplugin.command.listhome`	Use `/listhome`	true
`homeplugin.command.spawn`	Use `/spawn`	true
`homeplugin.command.tpa`	Send/accept/deny TPA	true
`homeplugin.admin`	Admin features (spawn, cache, manage others)	op
`homeplugin.lang.update`	Update language files	op
`homeplugin.back.use`	Use `/back`	op
`homeplugin.limit.<n>`	Override max homes (1..100 scanned)	permission‑based

Suggested extras (if implemented):

homeplugin.bypass.limit — ignore base limit
homeplugin.bypass.validation — ignore placement restrictions
homeplugin.bypass.cooldown — ignore RTP/teleport cooldowns

Dynamic limits: the plugin scans homeplugin.limit.1 … homeplugin.limit.100 and applies the highest held value.

🧩 PlaceholderAPI Integration

Placeholders (via HomePluginExpansion):

Placeholder	Description
`%homeplugin_homes%`	Comma‑separated home names (or fallback)
`%homeplugin_homes_numbers%`	Number of homes
`%homeplugin_has_homes%`	`true` if player has ≥ 1 home
`%homeplugin_home_location_<name>%`	Formatted location (language‑aware)
`%homeplugin_home_exists_<name>%`	`true` / `false`
`%homeplugin_home_world_<name>%`	World name
`%homeplugin_home_coordinates_<name>%`	Raw coordinates `X Y Z`
`%homeplugin_home_teleport_price%`	Teleport price
`%homeplugin_home_creation_price%`	Home creation price
`%homeplugin_tpa_request_price%`	TPA request price
`%homeplugin_rtp_price%`	RTP request price

Notes:

<name> is case‑insensitive.
The expansion registers automatically when PlaceholderAPI is present.

💰 Vault Integration

Economy features are handled by EconomyManager and use Vault to integrate with supported economy plugins. Configure costs per action (create home, teleport, TPA, RTP) in config.yml.

🌍 Languages

Configured via: Config.Language
Built‑in:

FRENCH
ENGLISH
SPANISH (Henri Topper)
RUSSIAN
UKRAINIAN
GERMAN
TURKISH (Xenetotyp3)

Language loading uses an enum (Language.valueOf(...)) and falls back to FRENCH if invalid. Customize by editing the shipped YAML files; use /lang update, /lang merge, and /lang set to manage versions and switch locales.

⬇️ Installation

Download: place the plugin JAR into your server’s plugins/ folder.
- Or build from source and place the resulting JAR into plugins/.
Start the server once to generate configuration and language files.
Adjust plugins/HomePlugin/config.yml (storage, Redis, economy, limits, etc.).
Reload/restart the server.

Quick check:

/sethome and /home should work immediately on YAML storage.
If using MySQL, verify credentials and connectivity before restarting.
If using Redis, set UseRedis: true and ensure the host is reachable.

⚙️ Configuration

Example structure (see src/main/resources/config.yml):

Config:

  # ----------------------------------------
  # Language / Localization
  # Available: FRENCH, ENGLISH, SPANISH, CUSTOM
  # ----------------------------------------
  Language: FRENCH

  # ----------------------------------------
  # Storage Connector
  # TYPE can be "YAML" or "MYSQL"
  # MySQL settings are used only when TYPE="MYSQL"
  # ----------------------------------------
  Storage:
    TYPE: "YAML"  # MYSQL or YAML

    # Optional (for MYSQL)
    HOST: "localhost"
    PORT: 3306
    USERNAME: "root"
    PASSWORD: ""
    DATABASE: "HomePlugin"

  # ----------------------------------------
  # Redis Cache (Optional)
  # Enable only if you need cross-instance cache/sync
  # ----------------------------------------
  Redis:
    Use-Redis: false
    HOST: "localhost"
    PORT: 6379
    SSL: false
    PASSWORD: ""

  # ----------------------------------------
  # Home Settings
  # Limits, validation, and disabled worlds
  # ----------------------------------------
  Home:
    Default-Home-Limit: 3
    Prevent-Unfair-Location: true
    Disabled-Worlds:
      - "world_nether"
      - "world_the_end"

  # ----------------------------------------
  # Teleport Task / Warmup & Effects
  # ----------------------------------------
  Task:
    Task-Duration: 3  # seconds
    Use-Title: true
    Use-Message: true
    Particles-After-Teleport: true
    Skip-If-Op: true


  # ----------------------------------------
  # TPA (Teleport Requests)
  # ----------------------------------------
  Tpa:
    Tpa-Duration: 30  # seconds

  # ----------------------------------------
  # RTP (Random Teleport)
  # ----------------------------------------
  RTP:
    Cooldown-Seconds: 1000  # seconds
    Max-Radius: 200
    Enabled: true

  # ----------------------------------------
  # Economy (Vault)
  # Toggle costs and set prices per action
  # ----------------------------------------
  Economy:
    UseEconomy: false
    Home-Creation-Price: 100.0
    Home-Teleport-Price: 50.0
    Tpa-Request-Price: 20.0
    RTP-Price: 150.0

  # ----------------------------------------
  # Features
  # Enable or disable specific features
  # ----------------------------------------
  Features:
    Enable-TPA: true
    Enable-Spawn: true
    Enable-Home: true

Key behaviors:

Base home limit via Config.Home.DefaultHomeLimit plus permission overrides.
TPA timeout uses Config.Tpa.Tpa-duration.
Redis initializes only when UseRedis: true.
Teleport warmup via Task-duration; titles/messages/particles are optional.
Worlds listed in DisabledWorlds cannot be used for homes/teleports (validation).

🧱 Architecture & Performance

Unified managers with storage abstraction:
- Homes: HomeManager → YAML (HomeYMLManager) or SQL (HomeSQLManager)
- Spawns: SpawnManager → YAML (SpawnYMLManager) or SQL (SpawnSQLManager)
Optional Redis (JedisPooled) caching/sync when enabled
MySQL path enabled by Config.Connector.TYPE=MYSQL
Extension system (PluginLoader / PluginManager) for internal modules
PlaceholderAPI soft‑dependency
Permission‑driven home limits (homeplugin.limit.<n>)
Teleport warmups and TPA expiration via Bukkit scheduler

🧑‍💻 Developer / Extension API

Events, managers, and language tools with documented APIs
Detect active backend:
- From events: SyncMethod getType()
- Globally: fr.fuzeblocks.homeplugin.HomePlugin.getRegistrationType()

Docs:

API Docs (Javadoc): HomePlugin JavaDoc
Developer Docs: Events • Home Managers • Spawn Managers • Language Management

Use JitPack to depend on the API (replace Tag with a release/tag):

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):

repositories { maven("https://jitpack.io") }
dependencies { implementation("com.github.fuzeblocks:HomePlugin:Tag") }

✅ Compatibility

Declared api-version: 1.14 (plugin.yml)
Built for modern Paper/Spigot derivatives
Soft‑dependency: PlaceholderAPI
Storage: YAML (default) or MySQL (when enabled)

🗺️ Roadmap

Feature	Status
Per‑home economy cost	✅ Complete
Offline player home editing	✅ Complete
Edit existing homes	✅ Complete
Public homes	📝 Planned
`/back` command	✅ Complete
Clickable chat messages	✅ Complete
Warps	📝 Planned
UI/style refresh	📝 Planned
BlueMap and Dynmap integration	📝 Planned

Suggestions welcome via Discussions or Discord.

🤝 Support & Contributions

Issues: Use GitHub Issues for bugs/feature requests
Discord: Join the server
Pull Requests: Use clear commit messages; discuss large changes beforehand

Contribution flow:

Fork
Create a feature branch
Commit changes
Open a PR referencing related issues

📄 License

Apache‑2.0

Usage

HomePlugin

📖About HomePlugin