Better HuskHomes - GUI, RTP-Zones, Teams vV2.0-7

## Update Notes (Since v1.0 - Dec 10, 2025)

### New Features

Surface Pearl: Track player's pearl even when they are on a different server. Black-list worlds and prevent chunk loading.

Random Teleport (RTP) Improvements

• Death RTP now teleports instantly — removed the unnecessary 5-second warmup delay that existed on standard RTP
• OP/admin bypass for safety checks and world border restrictions during RTP

Static Home Slots
- Homes now stay in the exact GUI slot where they were placed — no more homes shifting around when you delete or add homes

Team System Enhancements

• Team names and tags now support spaces (e.g., /team create My Cool Team)
• Expired team invites are now visible in the GUI — click to delete them from the database
• Profanity filter for team tags with admin bypass commands
• Offline player support for team placeholders (PlaceholderAPI)
• Team Admin to allow server operators and admins to manually change team names and team tags.

Cross-Server Visual Masking
- Players are now hidden from others and given a brief blindness effect during cross-server teleports, preventing the visual "ghost" glitch where you briefly see other players at your old location

Custom Teleportation Sounds
- Configurable sound effects for teleportation events — customize the sounds for teleport complete, warmup, cancellation, and incoming TPA requests

Private Messaging

• /reply now works correctly for cross-server private messages
• New per-player ignore system: /ignore <player> and /ignorelist to manage blocked players

### Bug Fixes

• Async-first architecture overhaul — All database and Redis calls are now fully asynchronous, eliminating server lag spikes caused by blocking I/O on the main thread
• Data integrity on disconnect — Player position is now captured synchronously (from RAM) before async save, preventing data loss when players disconnect or switch servers quickly
• Team invite accept/decline — Fixed invites failing silently; added cache fallback for cross-server invite resolution
• Team names with spaces — Fixed /team join and /team decline failing when team names contained spaces
• Team PVP toggle — Fixed a race condition that caused team PVP protection to intermittently fail
• Team placeholders — Fixed a blocking database call in team placeholder resolution; now uses an async cache pattern
• Migration fix — Fixed empty SQL statement execution during database migrations
• Scheduler cleanup — Bukkit scheduler tasks are now properly cancelled on plugin disable

---

## Comprehensive Feature Reference

### All Commands

#### Home Commands
| Command | Aliases | Usage | Description |
|---------|---------|-------|-------------|
| /home | — | /home [name] | Teleport to a home. No args opens GUI; one home auto-teleports |
| /sethome | — | /sethome [name] | Set a home at current location |
| /delhome | — | /delhome [name] | Delete a home. /delhome all confirm deletes all |
| /edithome | — | /edithome <name> | Edit home description or open editor GUI |
| /homelist | — | /homelist [player] [page] | View paginated list of homes |
| /phome | /publichome | /phome [owner/name] | Teleport to a public home |
| /publichomelist | /phomelist | /publichomelist [player] | Browse all public homes |
| /setbed | — | /setbed | Set bed spawn at current location |

#### Warp Commands
| Command | Aliases | Usage | Description |
|---------|---------|-------|-------------|
| /warp | — | /warp [name] | Teleport to a warp. No args opens GUI |
| /setwarp | — | /setwarp <name> | Create a warp (staff) |
| /delwarp | — | /delwarp <name> | Delete a warp (staff) |
| /editwarp | — | /editwarp <name> | Edit warp metadata (staff) |
| /warplist | /warps | /warplist [page] | List available warps |
| /warpgui | /warpguiadmin | /warpgui | Open admin warp management GUI |
| /warpgroup | — | /warpgroup [group] | Navigate warp groups |

#### Teleport Commands
| Command | Aliases | Usage | Description |
|---------|---------|-------|-------------|
| /tpa | — | /tpa <player> | Request to teleport to a player |
| /tpahere | — | /tpahere <player> | Request a player to teleport to you |
| /tpaccept | /tpyes | /tpaccept [player\|gui] | Accept a teleport request or open GUI |
| /tpdecline | /tpno, /tpdeny | /tpdecline [player] | Decline a teleport request |
| /tpacancel | — | /tpacancel [player] | Cancel a sent teleport request |
| /tpaall | — | /tpaall <player> | Accept all requests from a player |
| /tpignore | — | /tpignore <player> | Block TPA requests from a player |
| /tpatoggle | /toggletpa | /tpatoggle | Toggle all incoming TPA requests |
| /tpahereToggle | — | /tpahereToggle | Toggle incoming TPA-here requests |
| /tpaauto | — | /tpaauto | Auto-accept all teleport requests |
| /tp | /tpo | /tp <player\|x y z> | Admin teleport to player or coords |
| /tphere | /tpohere | /tphere <player> | Teleport a player to you (admin) |
| /tpall | — | /tpall | Teleport all players to you (admin) |
| /tpoffline | — | /tpoffline <player> | Teleport to offline player's last location |
| /spawn | — | /spawn [player] | Teleport to server spawn |
| /setspawn | — | /setspawn | Set the server spawn (admin) |
| /back | — | /back | Return to last location before teleport/death |

#### RTP Commands
| Command | Usage | Description |
|---------|-------|-------------|
| /rtp | /rtp [region] | Random teleport. No args opens region GUI |
| /rtpzone | /rtpzone [zone] | RTP to a specific zone |

#### Team Commands
| Command | Usage | Description |
|---------|-------|-------------|
| /team create | /team create <name> | Create a new team |
| /team leave | /team leave | Leave your team |
| /team disband | /team disband | Disband your team (owner) |
| /team info | /team info [team] | View team information |
| /team invite | /team invite <player> | Invite a player |
| /team accept | /team accept <team> | Accept a team invite |
| /team decline | /team decline <team> | Decline a team invite |
| /team kick | /team kick <player> | Remove a member |
| /team promote | /team promote <player> | Promote member to admin |
| /team demote | /team demote <player> | Demote admin to member |
| /team transfer | /team transfer <player> | Transfer team ownership |
| /team home | /team home | Teleport to team home |
| /team sethome | /team sethome | Set team home location |
| /team delhome | /team delhome | Delete team home |
| /team chat | /team chat [on\|off\|toggle] | Toggle team chat mode |
| /team allow | /team allow <player> <perm> | Grant a permission to a member |
| /team disallow | /team disallow <player> <perm> | Revoke a permission from a member |
| /teammsg | — | /teammsg <message> | Send message to team members |
| /teamadmin | — | /teamadmin <subcommand> | Admin team management |

#### Chat & Messaging Commands
| Command | Aliases | Usage | Description |
|---------|---------|-------|-------------|
| /msg | /whisper, /tell, /w, /m | /msg <player> <message> | Private message (cross-server) |
| /reply | /r | /reply <message> | Reply to last message (cross-server) |
| /msgtoggle | — | /msgtoggle | Toggle private messages on/off |
| /ignore | /msgignore, /block | /ignore <player> | Ignore a player's messages |
| /ignorelist | — | /ignorelist [page] | View your ignore list |
| /publictoggle | /publicchat | /publictoggle | Toggle public chat visibility |
| /systemchat | /systemtoggle | /systemchat | Toggle system messages (join/leave) |

#### Admin Commands
| Command | Usage | Description |
|---------|-------|-------------|
| /huskhomes reload | /huskhomes reload | Reload plugin configuration |
| /huskhomes status | /huskhomes status | Display server status |
| /huskhomes homeslots | /huskhomes homeslots <player> [view\|set\|add\|remove] [value] | Manage home slots |
| /huskhomes delete | /huskhomes delete <player\|homes\|warps> | Bulk delete data |
| /huskhomes import | /huskhomes import <start\|list> | Import from other plugins |
| /huskhomes update | /huskhomes update | Check for updates |

---

### All GUI Screens

#### Home GUIs
| GUI | Description |
|-----|-------------|
| Home GUI | Paginated bed display with colored beds (yellow = public, red = private). Left-click to teleport, right-click to rename, shift-right to toggle public/private. Dye items below for delete/set primary. Star prefix + glow on primary bed. |
| Home Delete Confirmation | Cancel / Home Info / Confirm layout for safe deletion |
| Public Home GUI | 54-slot paginated list of all public homes with player head items showing owner, world, coordinates, and description |

#### Warp GUIs
| GUI | Description |
|-----|-------------|
| Warp Main GUI | Grouped warp menu with custom materials, slot positions, and warp counts per group. Single-warp groups auto-teleport. |
| Warp Sub GUI | Individual warps within a group. Shows server capacity, world name, descriptions. Red barrier if server is full. Auto-select button for load balancing. |
| Warp Admin Main GUI | Admin overview of all warp groups with type, visibility, auto-select mode, and permissions |
| Warp Admin Editor | Full editor for warp group settings: display name, material, slot, visibility, auto-select, permission, max capacity, cooldown, command alias |
| Material Picker | 54-slot paginated browser of all Minecraft materials for warp customization |
| Slot Picker | Visual slot layout with color-coded available/occupied/current positions |
| Warp Individual List | Browse and edit individual warps within a group |
| Warp Individual Editor | Edit single warp properties: name, type, priority weight, visibility |

#### Teleport GUIs
| GUI | Description |
|-----|-------------|
| TPA Accept GUI | Paginated incoming request list with glow effect items. Shows requester, type (TPA/TPAHERE), server, world, time remaining. Right-click accept, left-click decline. Auto-refreshes every second. Search functionality. |
| TPA Cancel GUI | Confirmation screen for cancelling outgoing requests |

#### Team GUIs
| GUI | Description |
|-----|-------------|
| Team List GUI | Browse all teams with banner items showing tag, member count, and owner |
| Team Main GUI | Central team hub with buttons for: info, members, team home, team chat toggle, PVP toggle, teleport permission, set home permission, rename, change tag, tag color, invite, transfer ownership, disband/leave |
| Team Members GUI | Paginated member list with player heads. Shows role (Owner/Admin/Member) with color coding and join date. Left-click to manage permissions, right-click to promote/demote. |
| Team Member Permissions | Per-member permission toggles |
| Team Color Picker | Dye color grid for selecting team tag color |
| Team Invites GUI | View and manage pending team invitations. Expired invites shown with click-to-delete. |
| Team Join GUI | Browse available teams to join |
| Team Settings GUI | Admin panel for team system configuration |
| Team Disband Confirmation | Confirmation with permanent deletion warning |
| Team Leave Confirmation | Confirmation before leaving team |
| Team Transfer Confirmation | Confirmation before transferring ownership |
| Team Kick Confirmation | Confirmation before kicking a member |
| Team Home Delete Confirmation | Confirmation before deleting team home |

#### RTP GUI
| GUI | Description |
|-----|-------------|
| RTP Region Selector | Configurable inventory with region items. Shows display name, description, server count. Permission-checked per region. Material and slot configurable per region. |

---

### All PlaceholderAPI Placeholders

Prefix: %huskhomes_<identifier>%

#### Home Placeholders
| Placeholder | Returns | Description |
|-------------|---------|-------------|
| %huskhomes_homes_count% | Integer | Number of homes set |
| %huskhomes_max_homes% | Integer | Maximum homes allowed |
| %huskhomes_max_public_homes% | Integer | Maximum public homes allowed |
| %huskhomes_free_home_slots% | Integer | Free home slots remaining (economy) |
| %huskhomes_home_slots% | Integer | Additional purchased home slots (economy) |
| %huskhomes_homes_list% | String | Comma-separated list of home names |
| %huskhomes_public_homes_count% | Integer | Number of public homes |
| %huskhomes_public_homes_list% | String | Comma-separated list of public home names |
| %huskhomes_primary_bed% | String | Name of primary bed home |
| %huskhomes_primary_bed_set% | Boolean | Whether a primary bed is set |

#### Toggle Placeholders
| Placeholder | Returns | Description |
|-------------|---------|-------------|
| %huskhomes_ignoring_tp_requests% | Boolean | Whether ignoring all TPA requests |
| %huskhomes_tpa_enabled% | Boolean | Whether TPA requests are enabled |
| %huskhomes_tpahere_enabled% | Boolean | Whether TPA-here requests are enabled |
| %huskhomes_tpauto_enabled% | Boolean | Whether auto-accept is enabled |
| %huskhomes_msg_enabled% | Boolean | Whether private messaging is enabled |
| %huskhomes_teamchat_enabled% | Boolean | Whether in team chat mode |
| %huskhomes_publicchat_enabled% | Boolean | Whether public chat is enabled |
| %huskhomes_systemchat_enabled% | Boolean | Whether system messages are enabled |

#### Team Placeholders (works offline)
| Placeholder | Returns | Description |
|-------------|---------|-------------|
| %huskhomes_team_name% | String | Team name ("None" if not in a team) |
| %huskhomes_team_tag% | String | Team tag/abbreviation |
| %huskhomes_team_tag_colored% | String | Team tag with color applied |
| %huskhomes_team_tag_formatted% | String | Team tag as [TAG] with color |

---

### Key Permission Nodes

#### Player Permissions
| Permission | Description |
|------------|-------------|
| huskhomes.command.home | Use /home |
| huskhomes.command.sethome | Use /sethome |
| huskhomes.command.delhome | Use /delhome |
| huskhomes.command.homelist | Use /homelist |
| huskhomes.command.publichome | Use /publichome |
| huskhomes.command.tpa | Use /tpa |
| huskhomes.command.tpahere | Use /tpahere |
| huskhomes.command.tpaccept | Use /tpaccept |
| huskhomes.command.back | Use /back |
| huskhomes.command.spawn | Use /spawn |
| huskhomes.command.rtp | Use /rtp |
| huskhomes.command.rtp.<region> | Access specific RTP region |
| huskhomes.command.team | Use /team |
| huskhomes.max_homes.<number> | Set max home slots |
| huskhomes.max_public_homes.<number> | Set max public home slots |

#### Staff Permissions
| Permission | Description |
|------------|-------------|
| huskhomes.command.tp | Admin teleport |
| huskhomes.command.tphere | Teleport player to you |
| huskhomes.command.tpall | Teleport all players |
| huskhomes.command.tpoffline | Teleport to offline player |
| huskhomes.command.setwarp | Create warps |
| huskhomes.command.delwarp | Delete warps |
| huskhomes.command.setspawn | Set spawn |
| huskhomes.command.warpguiadmin | Warp admin GUI |
| huskhomes.command.home.other | View other players' homes |

#### Bypass Permissions
| Permission | Description |
|------------|-------------|
| huskhomes.bypass_cooldowns | Skip all cooldowns |
| huskhomes.bypass_warmups | Skip teleport warmups |
| huskhomes.bypass_economy | Skip economy costs |
| huskhomes.bypass.rtp_cooldown | Skip RTP cooldown only |

---

### Major Systems Overview

| System | Description |
|--------|-------------|
| Homes | Private/public homes with GUI management, static slot positioning, primary bed designation |
| Warps | Grouped warp system with admin GUI, per-warp permissions, server load balancing |
| Teleport Requests | TPA/TPAHere with GUI management, auto-accept, ignore lists, cross-server support |
| Random Teleport | Multi-region RTP with GUI selector, pre-cached coordinates, death RTP |
| Teams | Full team system with roles (Owner/Admin/Member), team homes, team chat, PVP toggle, profanity filter |
| Chat | Cross-server private messaging, team chat, ignore system, @mentions |
| Combat Tagging | Prevents teleportation during combat with configurable duration |
| Safety Checks | Standing, clearance, floor safety, End void detection for TPA destinations |
| Cross-Server | Redis-backed teleportation, messaging, and team chat across networked servers |
| Visual Masking | Players hidden + blindness during cross-server teleports to prevent ghost glitches |
| Custom Sounds | Configurable sound effects for teleport complete, warmup, cancel, and TPA received |
| Economy | Vault integration for home slot purchases and teleport costs |
| Cooldowns | Per-action cooldown system with permission overrides |
| Ender Pearl Stasis | Cross-server ender pearl retrieval with chunk loading support |
| Map Hooks | Dynmap, BlueMap, and Pl3xMap integration for home/warp markers |
| Holograms | HolographicDisplays, DecentHolograms, and FancyHolograms support |

### Supported Databases
SQLite, H2, MySQL, MariaDB, PostgreSQL

### Cross-Server Broker
Plugin Messaging or Redis (with Sentinel support)

Too many things to mention in this update!

Config migration should be automatic. Be sure to deleteyour old jar before launching. (If you have a custom language implemented, your file's keys may not update automatically. Switch to en-gb.yml to confirm you have all keys. Add missing keys as needed)


Better HuskHomes - Recent Updates

New Features

* Global Chat & Chat Formatting: (Required if wanting to use team chat features. Team chat automatically disabled if chat system disabled)
* Implemented a comprehensive chat management system.
* Features:
* Chat Formatting: Configurable prefixes, suffixes, and name colors based on LuckPerms groups.
* Local/Global Chat: Support for separate local (per-server) and global chat channels.
* Chat Cooldown: Configurable cooldown to prevent spam.
* Blocked Words Filter: Added a profanity/blocked words filter.
* Link Filter: Added a regex-based filter to block unauthorized links.
* Caps Filter: Added a filter to prevent excessive capitalization.
* Anti-Flood: Added logic to prevent repeating the same message.
* Admin Bypass: Players with specific permissions (huskhomes.chat.bypass) can bypass chat filters.
* New Config Section: chat section added to config.yml with extensive settings.

* World Blacklisting for Homes:
* Added the ability to blacklist specific worlds where players cannot set homes.
* Features:
* Configurable list of blacklisted worlds in config.yml (under general.blacklisted_worlds).
* Checks against this list when a player attempts to set a home (/sethome).
* Added a locale message error_set_home_blacklisted_world to notify players.
* Implementation: Modified SetHomeCommand.java (and potentially HomeManager or EditHomeCommand logic) to enforce this check.

* Safe Teleport Logic Improvements (RTP):
* Enhanced the Random Teleport (RTP) logic to better handle unsafe blocks.
* Features:
* Added UnsafeBlocks utility to define blocks that are unsafe to land on/in (e.g., Lava, Magma, Powder Snow).
* Implemented a spiral search or vertical scan to find a safe landing spot if the initial random coordinate is unsafe.
* Improved RTP to prioritize solid ground.

Improvements & Refactoring

* Locale & Language System Overhaul:
* Significantly expanded the locale system to support GUI customization.
* GUI Locales: Added a dedicated locales section in en-gb.yml (and other lang files) for translating GUI titles, button names, and lore.
* Consolidated Messages: Merged various message files or ensured messages-en-gb.yml and en-gb.yml are consistent.
* Refactoring: Updated GuiLocales class to handle these new keys efficiently.

* Cross-Server Teleport Optimization:
* Refined the teleport logic to be smoother.
* Features:
* Better handling of "Teleport Warmup" cancellation (movement, damage).
* Improved synchronization with Redis for cross-server coordinate/server name resolution.

* Dependencies:
* Updated dependencies (Paper API, Adventure, etc.) to newer versions compatible with Minecraft 1.21+.

Configuration Changes (config.yml)

* New Sections:
* chat: Entire section for chat formatting, cooldowns, filters, and channels.
* general.blacklisted_worlds: List of worlds where setting homes is disabled.
* rtp: Enhanced configuration for RTP radius, cooldowns, and unsafe blocks.

**Switched to the more modern Lettuce for Redis and moved away from Jedis to imporove connectivity and lost-connection retries.

Bug Fixes

* Fixed issues where GUI titles or items wouldn't translate correctly if the locale file was missing specific keys (added fallback logic).
* Addressed potential NPEs in WarpMainGui related to locale loading.
* Fixed issues with Redis message parsing for certain cross-server events.

Home Gui allowed users without warmup bypass to instantly teleport to their home. The Home Gui now respects the config and permission settings to match the /home command.

Updated the language yaml to now allow customizing the text and lore of the teams gui. (Message definitions were added, but the team gui was still hard-coded to use the default text.)

Added enhanced search logic for end-dimension RTP. Now, instead of searching individual chunks for an island, the search logic is as follows, rtp will randomly select a column in a random chunk and search up/down for a solid block. If a block is not found, the search will continue outwards x/z until it finds a solid block. Once found, the search will search +y until the top of an island is found. I also added 3 cacheing positions so 3 rtps will always be ready to go to minimize player wait time.

Identified a race condition that creates erroneous data in logs. This is on new player join events only and doesn't affect the functionality of the plugin. Please update to newest version.

Now you can customize the plugin with different language files. Most files are currently placeholders and have not been translated. However, every single menu item, lore, and player message can now be customized!

● Better HuskHomes v1.0-5 Update

Death RTP - Players randomly teleport within configured regions on death instead of spawning at world spawn

Cross-Server Bed Spawns - Die on Server A, respawn at your bed on Server B seamlessly

Smart Bed Validation - Automatically detects broken/obstructed beds and falls back to RTP

Server Heartbeat System - Detects offline servers to prevent timeout delays during cross-server teleports

Instant Respawn Cache - Pre-generates RTP positions for lightning-fast death respawns

Automatic Retry Logic - If a server doesn't respond, automatically tries another server in the region