Team HomeGUI Plugin

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

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

📖 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.

🏠 Team Homes

Teams can set a shared home location for all members.

⚠️ 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.

✔️ 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.

Global chat can show team prefix via configured format.

🎨 Team Customization

Team owners can customize display settings.

✔️ 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.

📦 Requirements

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:

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

⌨️ Commands

Player Commands

Alias: /t

Personal Home Commands

🔐 Permissions

Home limit priority:

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

🔧 Configuration

home-config.yml

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

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.

🔍 Troubleshooting

teamplugin.homes.3
teamplugin.homes.4
teamplugin.homes.5

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

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

/team settings name <new-name>

Is the plugin open source?

Yes. Apache License 2.0.

📄 Changelog

Version 1.0.6

Major Code Quality Refactoring:

• Architecture Improvements - Eliminated God Class pattern in TeamCommand.java
• New Service Classes - Created HomeService, CooldownManager, TeamValidator for better separation of concerns
• Handler Refactoring - Moved chat, color, and list logic from TeamCommand to dedicated handlers
• Code Duplication Elimination - Unified cooldown and home management logic
• Type Safety - Created GUISlots enum to eliminate magic numbers
• Maintainability - Improved code structure following SOLID principles
• Performance - Better memory management and cleaner code organization

New Features:

• Team SetHome Command - Team owners can now set shared team homes with /team sethome
• Team Owner Disband - Team owners can disband teams by using /team leave
• Enhanced PlaceholderAPI - Added comprehensive placeholders for teams and homes
• GUI Color Improvements - Ready homes now show as cyan, unset homes as gray

Bug Fixes:

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

Config Changes:

• Default Warmup Time - 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 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

Author: Duong2012G
License: Apache 2.0
Modrinth: /plugins/team-homegui-plugin

Open source — contributions welcome.