Nexal Homes

Advanced home management system with GUI, categories, sharing, permission-based limits, and economy integration.

Features

1. Named Homes - Set homes with custom names at your current location
2. Teleport via Command or GUI - Teleport to homes with /home \<name> or through the interactive GUI, and add a home from the GUI with Add a new home (type the name in chat, cancel to stop; same checks as /sethome)
3. Delete & Rename Homes - Manage your homes with /home delete and /home rename
4. Home Categories - Organize homes into categories (defaults from config + player-created). Deleting a category automatically removes it from all homes assigned to it.
5. Home Sharing - Share homes with specific players who can teleport to them
6. Permission-Based Limits - Control max homes per player with nexalhomes.limit.\<N> and max custom categories with nexalhomes.categories.\<N>
7. Custom Home Icons - Choose from 56 materials to represent each home in the GUI
8. Teleport Warmup - Configurable warmup with spiral particle effects and an action bar countdown
9. Teleport Cooldown - Prevent spam teleporting with configurable cooldown
10. Economy Integration - Charge players for setting homes and teleporting (Vault)
11. Default Home Marker - Mark your main home as default; it is starred in the GUI and available through %nexalhomes_default%
12. Admin GUI - /home admin opens a hub with the Configuration screen, the importers and the admin tools
13. Home Importers - Import homes from EssentialsX, CMI and zHomes, skipping names a player already has
14. Admin Tools - Statistics, purge homes in unloaded worlds, purge players inactive for 90 days, purge everything, export and import
15. Dual JSON/SQL Storage - Choose between JSON file or MySQL database storage; writes happen in the background
16. PlaceholderAPI Integration - Display home stats in scoreboards and chat
17. Root-Level Aliases - Convenient /sethome, /delhome, /homes aliases
18. Customizable Text - Every chat message and every player menu title, name and lore line is in messages.yml
19. World Controls - Allow homes in every world but a blacklist, or only in a whitelist (homes in other worlds cannot be set or teleported to), and show worlds with your own names (world: Overworld)

Technologies

• Spigot or Paper 1.20 to 26.3 - Minecraft server API
• Utilizer - Configuration, messages, items, GUIs, tasks
• ACF - Command framework
• nexal-core - JSON and SQL persistence (MariaDB/MySQL), help menus
• Vault - Economy costs (optional)
• PlaceholderAPI - Placeholder integration (optional)

Commands

Player Commands

Command	Description	Permission
/home	Open homes GUI	nexalhomes.use
/home \<name>	Teleport to a home	nexalhomes.use
/home help [page]	Show the command help	nexalhomes.use
/home set \<name>	Set a home at current location	nexalhomes.use
/home delete \<name>	Delete a home	nexalhomes.use
/home rename \<old> \<new>	Rename a home	nexalhomes.use
/home icon \<name>	Open icon picker GUI	nexalhomes.use
/home category \<name> [cat]	Set/remove home category	nexalhomes.use
/home createcategory \<name>	Create a custom category	nexalhomes.use
/home deletecategory \<name>	Delete a custom category	nexalhomes.use
/home share \<name> \<player>	Share a home with a player	nexalhomes.share
/home unshare \<name> \<player>	Stop sharing with a player	nexalhomes.share
/home shared	View homes shared with you	nexalhomes.use
/home list	List homes in chat	nexalhomes.use
/home setdefault \<name>	Mark your default home	nexalhomes.use
/sethome \<name>	Alias for /home set	nexalhomes.use
/delhome \<name>	Alias for /home delete	nexalhomes.use
/homes	Alias for /home (opens GUI)	nexalhomes.use

Sharing from the GUI (Quick Share, removing a shared player) needs nexalhomes.share too.

Admin Commands

Command	Description	Permission
/home admin	Open the admin GUI (players); show the admin help (console)	nexalhomes.admin
/home admin help [page]	Show the admin help	nexalhomes.admin
/home admin reload	Reload config.yml and messages.yml	nexalhomes.admin
/home admin export	Export data to export/*.json	nexalhomes.admin
/home admin import	Import data from export/*.json	nexalhomes.admin
/home admin list \<player>	List a player's homes	nexalhomes.admin
/home admin delete \<player> \<name>	Delete a player's home	nexalhomes.admin
/home admin teleport \<player> \<name>	Teleport to a player's home (alias: /home admin tp)	nexalhomes.admin

Admin GUI

/home admin opens a hub with three areas:

• Configuration - toggles (cancel warmup on damage or move, particles, cross-world teleports, economy), warmup delay, cooldown, default home limit, custom category limit, set and teleport costs, warmup particle, default icon and home worlds (blacklist or whitelist mode, and which worlds). Changes are saved to config.yml straight away.
• Import Homes - importers for EssentialsX (plugins/Essentials/userdata), CMI (plugins/CMI/cmi.sqlite.db) and zHomes (SQLite or MySQL, read from its config). Shift click a detected source to import; homes whose name the player already has are skipped, and imported homes get the configured default-icon.
• Admin Tools - statistics, purge homes in unloaded worlds, purge players who have not played for 90 days (going by the server's last-played record; players the server has no record of are kept), purge everything, export and import.

Permissions

Permission	Description	Default
nexalhomes.use	Basic home commands	true
nexalhomes.share	Share homes with other players	true
nexalhomes.admin	Admin commands and the admin GUI	op
nexalhomes.limit.\<N>	Set max home count to N (1 to 100)	none
nexalhomes.limit.unlimited	Unlimited homes	op
nexalhomes.categories.\<N>	Set max custom categories to N (0 to 100)	none
nexalhomes.categories.unlimited	Unlimited custom categories	op
nexalhomes.bypass.cooldown	Bypass teleport cooldown	op
nexalhomes.bypass.warmup	Bypass warmup delay	op
nexalhomes.bypass.cost	Bypass economy costs	op

PlaceholderAPI

Placeholder	Description
%nexalhomes_count%	Number of homes
%nexalhomes_limit%	Home limit
%nexalhomes_default%	Default home name
%nexalhomes_shared_count%	Number of homes shared with player
%nexalhomes_list%	Comma-separated list of home names

Configuration

config.yml

# Set by the plugin, which uses it to update older files (backed up as config.yml.v\<N>.bak). Do not change it.
config-version: 2

# Default home limit (overridden by nexalhomes.limit.\<N>)
default-home-limit: 3

# Default icon for new homes
default-icon: RED_BED

# Default categories
default-categories:
  - "General"
  - "Farms"
  - "Bases"

# Max custom categories per player (overridden by nexalhomes.categories.\<N>)
max-custom-categories: 5

# Teleport warmup in seconds (0 = instant)
warmup-delay: 3

# Cooldown between teleports in seconds
cooldown: 10

# Cancel warmup on damage/move
warmup-cancel-on-damage: true
warmup-cancel-on-move: true

# Warmup particle effects
warmup-particles:
  enabled: true
  type: PORTAL
  count: 15
  radius: 0.8
  update-interval: 2

# Which worlds allow homes: blacklist (all but disabled-worlds) or whitelist (only enabled-worlds)
world-mode: blacklist
disabled-worlds: []
enabled-worlds: []

# Names worlds are shown with in messages and menus (%world%)
world-names:
  world: Overworld
  world_the_end: End

# Cross-world teleporting
allow-cross-world: true

# Economy (requires Vault)
economy:
  enabled: false
  set-cost: 100.0
  teleport-cost: 25.0

# Storage: json or sql. Changing it needs a server restart.
storage:
  type: json
  sql:
    host: localhost
    port: 3306
    database: minecraft
    username: root
    password: ""

config.yml and messages.yml reload by themselves when saved; /home admin reload reloads them on demand. The storage type is read once at startup: to switch between JSON and SQL, run /home admin export, change storage.type, restart the server, then run /home admin import.

messages.yml

All chat messages are fully customizable with MiniMessage formatting, sounds, titles and action bars. The gui section holds the titles, item names and lore of every player menu, so they can be translated or restyled; the placeholders section holds the plain words (Unlimited, None) returned by the PlaceholderAPI placeholders. Keys added in an update are used from the plugin's built-in copy until you add them to your file.

Database Schema

When using SQL storage, the plugin creates the following tables:

homes

Column	Type	Key	Description
id	VARCHAR(36)	PK	Unique home UUID
owner_uuid	VARCHAR(36)		Owner player UUID
name	VARCHAR(32)		Home name
category	VARCHAR(32)		Category (nullable)
icon	VARCHAR(64)		Material name
world	VARCHAR(64)		World name
x, y, z	DOUBLE		Coordinates
yaw, pitch	FLOAT		Direction
shared_with_json	TEXT		JSON array of shared player UUIDs
created_at	BIGINT		Creation timestamp
last_visited	BIGINT		Last teleport timestamp

homes_users

Column	Type	Key	Description
id	VARCHAR(36)	PK	Player UUID
default_home_id	VARCHAR(36)		Default home UUID
categories_json	TEXT		JSON array of custom categories
last_teleport	BIGINT		Last teleport time

Key Legend: PK = Primary Key

Installation

1. Download the plugin JAR
2. Place it in the /plugins folder (add Vault and an economy plugin for costs, PlaceholderAPI for placeholders)
3. Start or restart the server
4. Adjust config.yml, or use /home admin → Configuration in game
5. For SQL storage, set storage.type: sql and the connection details, then restart

Dependencies

• Spigot or Paper 1.20 to 26.3
• Vault (optional, for economy)
• PlaceholderAPI (optional, for placeholders)