Team-HomeGUI-Plugin

🌐 English

Version: 1.4.0 | API: Paper 26.1 – 26.3 (Java 25) | Author: Duong2012G

A team system with a GUI home manager for Paper servers: teams with roles, team chat, a team home, up to 5 personal homes in an inventory menu, cooldowns and warmups, optional Vault charges, PlaceholderAPI placeholders and an EssentialsX override for /home.

---

Features

Category	Feature
Teams	Create, invite (accept / deny), leave, kick, disband, rename, colour, list, info
Roles	Owner / Admin / Member. Owners and admins invite, kick members, set the team home and change settings; only the owner can kick or demote an admin, transfer ownership or disband. Offline members can be kicked, promoted, demoted and given ownership.
Team chat	/team chat enable|disable (all your messages go to the team) and /team msg <text>; an optional [team] prefix in global chat. Chat text is never colour-translated.
Team home	/team sethome (owner / admin) and /team home or the banner in the GUI
Personal homes	Up to 5 in the GUI (more by name, with /sethome <name>); the limit comes from default-max-homes and teamplugin.homes.<n> permissions
Home GUI	Bed icons to teleport, lime / red dye to set / delete, a confirmation menu before deleting; all inventories are locked against clicks and drags
Safe data	Positions are stored with the world's key and name and resolved only when you teleport, so a home is never lost because its world is not loaded. Files are written atomically on a background thread.
Cooldown & warmup	Cooldown per player; a warmup with an action-bar countdown, optional freeze, cancel on move / teleport / death. A cancelled warmup costs nothing.
Economy	Vault charges for setting a home, teleporting, creating a team and setting the team home (all off by default)
Friendly fire	Blocks damage between team members from every source: melee, arrows, tridents, potions, TNT. You can still hurt yourself.
PlaceholderAPI	%team_*% placeholders
EssentialsX	/home, /sethome and /delhome (also as /essentials:home ...) always reach this plugin
Admin tools	/team admin ... for people with teamplugin.admin, with an admin ban list

---

Requirements

Dependency	Required
Paper 26.3 (compiled against the 26.3 API; api-version: 26.1, so 26.1 / 26.2 may load it, only 26.3 was targeted)	✅
Java 25	✅
Vault + an economy plugin	Optional (charges)
PlaceholderAPI	Optional
EssentialsX	Optional (the /home override)

Servers on 1.21.x must stay on 1.3.3. Paper API only (no Spigot); Folia is not declared supported.

Installation

1. Put teamhomegui-1.4.0.jar into plugins/.
2. Start the server; plugins/Team-HomeGUI-Plugin/team-config.yml and home-config.yml are created.
3. Edit them and apply with /team reload (no restart needed; the admin team name needs a restart).

Upgrading from 1.3.x: see Data and upgrading below.

---

Commands

Players

Command	Description
/team create <name>	Create a team (3–16 letters, digits, underscores)
/team invite <player>	Invite a player (owner, admins, and members if allowed)
/team invite accept / deny	Answer the invite you received (expires after 60 s)
/team leave	Leave; the owner must repeat it within 30 s to disband the team
/team kick <player>	Kick a member (owner or admin; only the owner can kick an admin)
/team info [team], /team members [team], /team list [page]	Look at teams
/team sethome	Set the team home (owner / admin)
/team home	Teleport to the team home
/team menu	Open the home GUI
/team chat enable|disable	Send everything to team chat, or stop
/team msg <message>	One team message
/team color <color>	Change the team colour (owner)
/team settings name <name>	Rename the team
/team settings color <color>	Change the colour
/team settings members-can-invite <on|off>	Let members invite
/team settings promote <player> / demote <player>	Make / remove an admin (demote: owner only)
/team settings transfer <player>	Give the team to another member (owner)
/home · /sethome	Open the home GUI
/home <name> · /sethome <name> · /delhome <name>	Teleport to / set / delete a home by name

Alias: /t for /team.

Server admins (teamplugin.admin)

Command	Description
/team admin create	Create the admin team (name: admin.team-name, default Admin)
/team admin add <player>	Move a player into the admin team (not possible while they own another team)
/team admin ban <player> / unban <player>	Ban from / allow the admin commands (operators cannot be banned)
/team admin manage <team>	Show a team's details
/team admin remove <team>	Disband a team (not the admin team)
/team admin list [page]	List all teams
/team admin settings <team> <option> [value]	Change any team's name, colour, invite rule or roles
/team reload or /team admin reload	Reload both config files (the console can use /team reload)

---

Permissions

Permission	Description	Default
teamplugin.admin	/team admin ... and /team reload	op
teamplugin.homes.<n>	Allows <n> personal homes (the highest wins; teamplugin.homes.3/4/5 are declared)	false
teamplugin.home.nocooldown	Skip the home teleport cooldown	op
teamplugin.team.nocooldown	Skip the team home cooldown	op
teamplugin.player	Declared for compatibility; the commands do not require it	true

All other commands are available to everybody.

---

Home GUI

Row 1: [ ][ ][ ][ ][T][ ][ ][ ][ ]    T = Team home (banner)
Row 2: [ ][ ][1][2][3][4][5][ ][ ]    personal homes (bed icons)
Row 3: [ ][ ][S][S][S][S][S][ ][ ]    S = set (lime dye) / delete (red dye) for the home above
Row 4: filler
Row 5: filler

(The exact slots are 4, 11–15 and 20–24; the menu has 5 rows by default, gui.rows accepts 3–6.) The delete confirmation has a red No, the bed, and a green Yes in the middle row of a 3-row menu.

---

Configuration

Both files are plain YAML; keys that are missing fall back to the defaults bundled in the jar.

home-config.yml

Key	Default	Description
default-max-homes	5	Homes everybody may have (raised by teamplugin.homes.<n>)
gui.title, gui.rows, gui.filler-material, gui.show-coordinates	&0Home &8- &0Menu, 5, GRAY_STAINED_GLASS_PANE, false	Look of the menu
teleport.cooldown	3	Seconds between teleports (starts when you teleport)
teleport.warmup	5	Countdown in seconds (0 = instant)
teleport.freeze-on-warmup	true	Hold the player in place during the warmup
teleport.cancel-on-move	true	Cancel on movement (when frozen: on jumping or falling)
features.personal-homes, features.team-homes, features.sounds	true	Switch a feature off
disabled-worlds	world_nether, world_the_end	Worlds (name or key) where homes cannot be set or used
economy.enabled, economy.sethome-cost, economy.teleport-cost	false, 100, 0	Vault charges
messages.*		All home messages

team-config.yml

Key	Default	Description
admin.team-name	Admin	Name of the admin team
settings.min-team-name-length / max-team-name-length	3 / 16	Name length
settings.max-members	20	Members per team
settings.invite-timeout-seconds	60	How long an invite lasts
settings.chat-format, settings.global-format	see file	Chat layouts ({team} {player} {message})
features.team-chat, features.global-chat-prefix, features.team-homes	true	Switch a feature off
features.friendly-fire	false	true allows friendly fire
damage.disable-pvp-between-members	true	Friendly fire is blocked when this is true and features.friendly-fire is false
creation.default-invite-only, creation.default-members-can-invite	true, false	Settings of new teams
teleport.cooldown	3	Team home cooldown
economy.enabled, economy.create-cost, economy.sethome-cost	false, 500, 100	Vault charges (a team home teleport uses home-config.yml's teleport-cost)
disabled-worlds	[]	Extra worlds where the team home is unavailable
messages.*		All team messages (& colours, &#rrggbb hex colours, {placeholders})

If charging is enabled but no Vault economy exists, nobody is charged and a warning is logged once.

---

PlaceholderAPI

Placeholder	Returns
%team_name%, %team_colored_name%, %team_color%	Team name, coloured name, colour code
%team_role%	Owner / Admin / Member
%team_count%, %team_owner%	Member count, owner name
%team_has_team%, %team_is_owner%, %team_is_admin%	yes / no
%team_has_home%, %team_home_world%, %team_home_x% / _y / _z	Team home information (the world is given by name, even if not loaded)
%team_homes_count%, %team_homes_max%, %team_homes_list%, %team_has_homes%	Personal homes

---

Data and upgrading

• Data lives in homes.yml and teams.yml. From 1.4.0 positions are stored as world-key, world, x, y, z, yaw, pitch.
• From 1.3.x: on first start the old files are converted. The original file is first copied to homes.yml.legacy-backup / teams.yml.legacy-backup. Positions in worlds that are not loaded at that moment stay in the backup and are imported automatically as soon as the world loads; then the backup is renamed *.legacy-imported-<time>.
• Files converted by 1.4.0 cannot be read by 1.3.3 or older. Keep the backups if you might go back.
• A data file that cannot be parsed is copied to *.corrupted-<time> instead of being loaded as empty.

Known limitations

• One warmup per player: a second teleport request during a warmup is refused.
• Folia is not supported (the plugin uses the regular Bukkit scheduler).
• Vault and PlaceholderAPI are optional integrations that were built against their public APIs; test them on your server version.
• /reload is not supported by Paper plugins in general; use /team reload for the configs.

Changelog

See CHANGELOG.md.