Team-HomeGUI Plugin

<div align="center">

<img src="https://cdn.modrinth.com/data/team-homegui-plugin/icon.png" width="120" alt="Team HomeGUI Icon"/>

Team HomeGUI Plugin

A lightweight team system with team homes, private team chat, personal homes, and a clean home GUI for Paper 1.21+

Modrinth

Paper

Java

License

*Create teams, set shared team homes, manage private team chat, and let players use personal homes through a simple GUI.*

📥 Download • 🐛 Report a Bug • 📄 Changelog

</div>

---

📖 Table of Contents

* ✨ Features * 📦 Requirements * 🚀 Installation * ⌨️ Commands & Permissions * 🔧 Configuration * 🧩 PlaceholderAPI Integration * 🔍 Troubleshooting * ❓ FAQ * 📄 Credits

---

✨ Features

👥 Team System

Create and manage player teams directly in-game.

| Feature | Description | | ------- | ----------- | | Team creation | Players create one team with validated name | | Invitations | Owners and permitted members can invite | | Join flow | Accept or deny pending invites | | Roles | Owner, Admin, and Member roles | | Team list | Browse existing teams with pagination | | Team info | View owner, color, settings, member count | | Member list | View all members with role labels |

---

🏠 Team Homes

Teams can set a shared home location for all members.

| Command | Description | | ------- | ----------- | | `/team sethome` | Set current location as team home | | `/team home` | Teleport to team home |

⚠️ Fixed in 1.0.1: Paper 1.21.11 API compatibility for GUI items.

✔️ New in 1.0.3:

* Disabled world check - teleport blocked in configured worlds * Warmup cancellation on death/disconnect * Friendly fire toggle between team members

---

🏡 Personal Homes + GUI

Players can create personal homes and open a GUI menu.

| Feature | Description | | ------- | ----------- | | Multiple homes | Configurable default limit | | Permission limits | Grant 3, 4, or 5 homes with permissions | | GUI menu | `/home` opens clickable home menu | | Named homes | `/sethome <name>`, `/home <name>`, `/delhome <name>` | | Safe names | Letters, numbers, underscores only (1-16 chars) | | Cooldown | Configurable teleport cooldown | | Economy | Optional Vault integration for costs |

✔️ New in 1.0.3:

* Improved GUI appearance with black beds/banners * Sethome buttons for homes without permission (shows error) * Tab completion suggests default home names

---

💬 Team Chat

Communicate privately with your team.

| Command | Description | | ------- | ----------- | | `/team msg <message>` | Send private team message | | `/team chat enable` | Enable persistent team chat mode | | `/team chat disable` | Return to global chat |

Global chat can show team prefix via configured format.

---

🎨 Team Customization

Team owners can customize display settings.

| Setting | Command | | ------- | ------- | | Display name | `/team settings name <new-name>` | | Team color | `/team settings color <color>` | | Member invites | `/team settings members-can-invite <on|off>` | | Promote member | `/team settings promote <player>` | | Demote admin | `/team settings demote <player>` | | Transfer ownership | `/team settings transfer <player>` |

✔️ New in 1.0.1: GUI rows, filler material, and sound toggles configurable.

✔️ New in 1.0.3:

* Economy integration - optional costs for team creation and home operations * Enhanced team name validation with offensive word filtering * Cannot promote/demote/transfer to self

---

🛠️ Admin Tools

Manage teams and admin access in-game.

| Feature | Command | Permission | | ------- | ------- | ---------- | | Create admin team | `/team admin create <password>` | `teamplugin.admin` | | Add to admin team | `/team admin add <player>` | `teamplugin.admin` | | Ban from admin | `/team admin ban <player>` | `teamplugin.admin` | | Unban from admin | `/team admin unban <player>` | `teamplugin.admin` | | Manage a team | `/team admin manage <teamId>` | `teamplugin.admin` | | Remove a team | `/team admin remove <teamId>` | `teamplugin.admin` | | Edit team settings | `/team admin settings <teamId> <option> [value]` | `teamplugin.admin` |

---

📦 Requirements

| Component | Version | Notes | | -------------- | ------- | -------- | | Java | 21+ | Required | | Paper | 1.21+ | Required | | Vault | Optional| Enables economy integration | | PlaceholderAPI | Optional| Enables placeholders | | DiscordSRV | Optional| Chat compatibility |

> Spigot/Folia support not guaranteed. Built for Paper API 1.21+.

---

🚀 Installation

1. Download the `.jar` from Modrinth 2. Place it in `plugins/` 3. Start the server 4. Edit configs 5. Restart server

Generated files:

| File | Purpose | | ---- | ------- | | `team-config.yml` | Team messages, chat formats, admin settings | | `home-config.yml` | Home limits, cooldown, GUI settings | | `teams.yml` | Runtime team data | | `homes.yml` | Runtime personal home data |

> ⚠️ Avoid `/reload`. Restart server fully after updates.

---

⌨️ Commands

Player Commands

| Command | Description | | ------- | ----------- | | `/team` | Show help menu | | `/team create <name>` | Create new team | | `/team invite <player>` | Invite player | | `/team invite accept` | Accept pending invite | | `/team invite deny` | Deny pending invite | | `/team leave` | Leave current team | | `/team list [page]` | List teams | | `/team info [team]` | Show team info | | `/team members [team]` | Show members | | `/team msg <message>` | Send team message | | `/team chat <enable|disable>` | Toggle team chat | | `/team sethome` | Set team home | | `/team home` | Teleport to team home | | `/team menu` | Open home GUI | | `/team color <color>` | Change team color | | `/team settings` | Show settings | | `/team settings name <name>` | Rename team | | `/team settings color <color>` | Change color | | `/team settings members-can-invite <on|off>` | Toggle invites | | `/team settings promote <player>` | Promote to admin | | `/team settings demote <player>` | Demote to member | | `/team settings transfer <player>` | Transfer ownership | | `/team kick <player>` | Kick member |

Alias: `/t`

Personal Home Commands

| Command | Description | | ------- | ----------- | | `/home` | Open home GUI | | `/home <name>` | Teleport to named home | | `/sethome <name>` | Create/update named home | | `/delhome <name>` | Delete named home |

---

🔐 Permissions

| Permission | Description | Default | | ---------- | ----------- | ------- | | `teamplugin.player` | Basic player access | `true` | | `teamplugin.admin` | Admin commands | `op` | | `teamplugin.homes.3` | Up to 3 homes | `false` | | `teamplugin.homes.4` | Up to 4 homes | `false` | | `teamplugin.homes.5` | Up to 5 homes | `false` | | `teamplugin.home.nocooldown` | Bypass cooldown | `op` |

Home limit priority:

```text teamplugin.homes.5 > teamplugin.homes.4 > teamplugin.homes.3 > default-max-homes ```

---

🔧 Configuration

`home-config.yml`

```yaml default-max-homes: 2

gui: title: "&0Home &8- &0Menu" rows: 5 filler-material: "GRAY_STAINED_GLASS_PANE"

teleport: cooldown: 3 warmup: 0 freeze-on-warmup: true cancel-on-move: true

features: personal-homes: true team-homes: true sounds: true

disabled-worlds: - "world_nether" - "world_the_end"

economy: enabled: false sethome-cost: 0 teleport-cost: 0 create-cost: 0 ```

`team-config.yml`

```yaml admin: password: "admin123" # ⚠️ SECURITY WARNING: Change this immediately! team-name: "Admin"

settings: max-team-name-length: 16 min-team-name-length: 3 max-members: 20 global-format: "[{team}&r] {player}: {message}" chat-format: "&8[TC]&r [{team}&r] &7{player}&r: {message}" invite-timeout-seconds: 60

features: team-chat: true global-chat-prefix: true team-homes: true sounds: true

damage: disable-pvp-between-members: false disable-pvp-between-allies: false

creation: require-password: false default-invite-only: true default-members-can-invite: false

economy: enabled: false create-cost: 0 ```

---

🧩 PlaceholderAPI Integration

👉 https://placeholderapi.com

Optional integration exposes team-related placeholders.

| Placeholder | Description | | ----------- | ----------- | | `%team_name%` | Team display name | | `%team_colored_name%` | Team name with color codes | | `%team_color%` | Team color code | | `%team_role%` | Owner/Admin/Member | | `%team_count%` | Number of members |

---

🔍 Troubleshooting

---

❓ FAQ

Does this support Paper 1.21+?

Yes. Targets Paper API 1.21+ and Java 21+.

Does it support DiscordSRV?

DiscordSRV is soft dependency. Team chat stays private; global chat can show prefixes.

Can members invite players?

Yes, if owner enables it:

```text /team settings members-can-invite on ```

Can players have multiple homes?

Yes. Default in `default-max-homes`; higher limits via permissions.

Can team owners rename their team?

Yes:

```text /team settings name <new-name> ```

Is the plugin open source?

Yes. Apache License 2.0.

---

📄 Changelog

Version 1.0.6

Performance * Performance - Eliminated God Class pattern in TeamCommand.java * Performance - Created HomeService, CooldownManager, TeamValidator for better separation of concerns * Performance - Moved chat, color, and list logic from TeamCommand to dedicated handlers * Performance - Unified cooldown and home management logic * Performance - Created GUISlots enum to eliminate magic numbers * Performance - Improved code structure following SOLID principles * Performance - Better memory management and cleaner code organization

GUI Color Improvements * GUI Color Improvements - Team owners can now set shared team homes with `/team sethome` * GUI Color Improvements - Team owners can disband teams by using `/team leave` * GUI Color Improvements - Added comprehensive placeholders for teams and homes * GUI Color Improvements - Ready homes now show as cyan, unset homes as gray

Fixed Placeholder Conflicts * Fixed Placeholder Conflicts - All placeholders now work correctly with proper config separation * Fixed Placeholder Conflicts - `/sethome` now shows correct personal home messages instead of team messages * Fixed Placeholder Conflicts - Added missing messages like "owner-cannot-leave" and "team-sethome-success" * Fixed Placeholder Conflicts - Personal homes use home-config, team messages use team-config

GUI Visual Distinction * GUI Visual Distinction - Set to 5 seconds instead of 0 for better teleport experience * GUI Visual Distinction - Clear color coding: cyan (ready), gray (unset), black (no permission)

Version 1.0.5

Bug Fixes: * Fixed tab completion for /home and /sethome - now only shows actual homes instead of default home1,2,3 * Fixed EssentialX compatibility - removed blocking check that prevented /sethome <name> from working * Fixed missing "admin-help-list" message that caused errors in admin command help * Changed plugin prefix from "[Teams]" to "[Team-Home]" for better branding

Version 1.0.4

Bug Fixes: * Fixed command routing - created separate HomeCommand for home/sethome/delhome * Fixed /sethome command now correctly sets personal home instead of team home * Fixed /team command now correctly shows team help instead of opening home GUI * Fixed tab completion for /home and /sethome now shows home names instead of team commands * Fixed MenuListener banner color check (WHITE_BANNER vs BLACK_BANNER) for team home teleport

Version 1.0.3

New Features: * Economy integration with Vault - optional costs for team creation and home operations * Friendly fire toggle between team members * Disabled world check for teleportation * Warmup cancellation on player death/disconnect * Enhanced team name validation with offensive word filtering * Improved tab completion for home commands * GUI appearance improvements with black beds/banners

Improvements: * Cannot promote/demote/transfer to self * Sethome buttons for homes without permission (shows error) * Strong security warning for default admin password * Better code organization and reduced duplication

Bug Fixes: * Fixed handleDemote logic to check isAdmin() instead of getMembers() * Removed dead code (isTakenName method) * Removed unused RESERVED_NAMES constant

Version 1.0.2

Bug Fixes: * Fixed Paper 1.21.11 API compatibility for GUI items * Improved setItemMeta() usage

Version 1.0.1

New Features: * GUI rows, filler material, and sound toggles configurable * Economy messages in configuration files

Bug Fixes: * Fixed GUI not opening on /home command

---

📄 Credits

Modrinth: Duong2012G Modrinth: Apache 2.0 Modrinth: https://modrinth.com/plugin/team-homegui-plugin

*Open source — contributions welcome.*