TeamsX

TeamX

A simple but effective team plugin for Paper 1.21+.

Create teams, give them a custom hex color, set a shared home and ender chest, talk in team chat, form alliances, and run it all from a clean GUI panel. Lightweight, configurable, and plays nice with TAB + PlaceholderAPI for tab-list and above-head nametag colors.

---

Features

• Teams — create, invite (clickable Accept/Deny in chat), accept/deny, kick, leave, disband
• Roles — Owner, Officer, Member with /team promote & /team demote
• Customization — hex team colors, rename, description, friendly-fire toggle
• Team home — /team sethome + /team home with an action-bar warmup countdown (cancels on move, damage, or quit)
• Shared ender chest — configurable size (9–54 slots); overflow is safely dropped to the owner when the chest shrinks
• Team chat — /tc, toggleable, with a [Team] prefix (kept separate from the tab/nametag tag)
• Announce — broadcast to your team, with an optional BossBar
• Alliances — request/accept/deny/break, PVP blocked between allies, configurable max
• Tab list + above-head nametag — integrates with TAB via PlaceholderAPI (%teamx_tag% and more). TeamX detects TAB and defers rendering to it automatically
• GUI panel — /team opens a clickable menu; disband has a confirmation page
• /team list — paginated, sortable (sort:members / sort:name), searchable, with clickable prev/next navigation
• Sounds — invites, promotions/demotions, team creation, ally events
• Per-team YAML persistence — atomic saves + .tmp crash recovery
• Configurable messages — MiniMessage + legacy & color support, multi-locale ready
• Admin tools — read-only echest inspection, item scanning, /team reload

---

Commands

Aliases: /teams, /t

Command	Description
/team	Open the team GUI panel
/team create <name>	Create a new team
/team disband	Permanently delete your team
/team invite <player>	Invite a player (they get a clickable Accept/Deny)
/team accept	Accept a pending invite
/team deny	Deny a pending invite
/team leave	Leave your current team
/team kick <player>	Kick a member (works offline by name)
/team promote <player>	Promote a member to Officer
/team demote <player>	Demote an Officer back to Member
/team sethome	Set the team home to your location
/team home	Teleport to team home (warmup countdown)
/team delhome	Remove the team home
/team echest	Open the shared ender chest
/team chat [message]	Send to team chat, or toggle team-chat mode with no message
/team announce <message>	Broadcast a message to your team (+ BossBar)
/team info [team]	Show info about your team, or another team
/team list [page] [sort:name|members] [search:term]	Browse all teams
/team rename <name>	Rename your team
/team color <#hex|name>	Set your team's color
/team description <text>	Set your team's description
/team settings	Open the settings GUI (owner only)
/team ally [request|accept|deny|break|list] [team]	Manage alliances
/team unally <team>	Shortcut for /team ally break <team>
/team friendlyfire	Toggle same-team PVP (alias /team pvp)
/team help	Show the command reference

Team chat

Command	Description
/tc <message>	Send a message to team chat (aliases /teamchat, /tchat)

Admin commands — requires teamx.admin

Command	Description
/team admin echest <team>	Open a read-only snapshot of a team's shared chest
/team admin echest scan <item>	Scan every team's chest for an item (material or name)
/team reload	Reload config + messages + teams

---

Permissions

Permission	Default	Description
teamx.use	true	Base access — use /team, /tc, and the GUI panel
teamx.create	true	Create a new team
teamx.admin	op	Admin powers — /team reload and /team admin echest tools
teamx.*	op	Parent node — grants all of the above

Suggested LuckPerms setup

Give every player the base nodes, and reserve admin for staff:

/lp group default permission set teamx.use true
/lp group default permission set teamx.create true
/lp group admin permission set teamx.admin true

Want donator-only teams? Just withhold teamx.create from default and grant it to a donor group:

/lp group default permission set teamx.create false
/lp group vip permission set teamx.create true

teamx.* is a parent that grants teamx.use, teamx.create, and teamx.admin, so you usually only need it on owners/admins.

---

Placeholders (PlaceholderAPI)

Placeholder	Output
%teamx_tag% / %teamx_prefix%	Colorized [Team] bracket (ready for tab/nametag)
%teamx_team%	Team display name
%teamx_color%	Team color as &#rrggbb
%teamx_role%	Your role — Owner / Officer / Member
%teamx_owner%	Team owner's name
%teamx_members%	Current member count
%teamx_has_team%	yes / no (useful for conditions)

All placeholders return empty / 0 / no for teamless players, so nothing shows for players who aren't in a team.

Using them with TAB

Add %teamx_tag% to your groups.yml under _DEFAULT_ (and any group that overrides it):

_DEFAULT_:
  tabprefix: "%teamx_tag%%luckperms-prefix%"
  tagprefix: "%teamx_tag%%luckperms-prefix%"

tabprefix = tab list, tagprefix = above-head nametag. TeamX detects TAB and stands down its own scoreboard nametag logic so the two don't conflict.

---

Configuration highlights (config.yml)

• teams.max-members, teams.name-min/max-length, teams.name-regex
• teams.default-color + teams.allowed-colors (empty = any hex allowed)
• home.warmup, home.cancel-on-move, home.cancel-on-damage, home.warmup-actionbar
• echest.size (9–54, multiple of 9)
• announce.bossbar, announce.bossbar-seconds, announce.bossbar-color
• sounds.enabled + per-event sound keys
• list.page-size
• tab / nametag format strings (used when TAB is not present)
• settings.locale, settings.legacy-color-codes

Messages live in messages.yml (MiniMessage + legacy & codes supported).

---

Setup

1. Drop TeamX.jar into your server's plugins/ folder.
2. Restart the server (a full restart, not just /reload, so the soft-depend load order resolves).
3. (Optional, for tab + above-head nametag colors) Install PlaceholderAPI and TAB, then add %teamx_tag% to TAB's groups.yml as shown above.
4. Tweak config.yml / messages.yml to taste, then /team reload.

---

Requirements & compatibility

• Server: Paper 1.21+ (Purpur works). Not compatible with Spigot (uses Paper's Adventure/MiniMessage text components).
• Java: 21 or newer.
• Optional: PlaceholderAPI (for %teamx_*% placeholders), TAB (for tab list + above-head nametag rendering). Both are soft-dependencies — TeamX runs fine without them, and falls back to its own scoreboard-based nametag when TAB isn't present.

---

FAQ

Will it work without TAB / PlaceholderAPI? Yes. Without them, TeamX uses its own scoreboard teams for the above-head tag and playerListName for the tab list. The PAPI/TAB integration is just the recommended path when you already run a tab plugin.

Can a player be in multiple teams? No — one team per player by default (teams.one-per-player: true). Set it to false to allow more.

How are teams saved? One YAML file per team in plugins/TeamX/data/, written atomically. A leftover .tmp from a crash is recovered on the next load.

Does it support MySQL? Not yet — file-based persistence only, by design (keeps it lightweight).

---

TeamX is open-source and MIT-licensed.