Module Team

Team Module

Config file: modules/team.yml — current version: 1.1 — view current default on GitHub Enable via config.yml → modules.team: true

Features

• Config-only team definitions. Teams (id, display name, color) can only be created/removed in modules/team.yml — nobody can create teams in-game. Everything else (membership, roles, invites, join requests) is runtime state.
• MiniMessage colors, including gradients and <rainbow> — used for the team's display name in chat, /team list/info, and placeholders.
• UUID-based storage. Membership, roles, invites and join requests are all stored by UUID under plugins/PlainBase/data/teams/, so renaming a Minecraft account never breaks a team.
• Two roles per team, independent per team if a player is in several: MEMBER and ADMIN.
  • Every server OP (and anyone with plainbase.admin / plainbase.team.admin) automatically acts as admin on every team, regardless of stored role.
  • Everyone else starts as MEMBER when joining a team. Members may only leave; admins can invite/add/kick/setrole/manage requests.
  • Promote/demote with /team setrole <team> <player> <member|admin> — only an existing admin (or console) can do this.
• Join flow, two ways:
  • /team invite <team> <player> → the player gets a message immediately (or a reminder on next join if offline) and must run /team accept [team] or /team deny [team].
  • /team add <team> <player> → adds the player directly, no confirmation needed.
  • /team request <team> → a player asks to join; every admin of that team who is online gets notified (and can check back later with /team requests <team>) and can /team add <team> <player> (accept) or /team reject <team> <player> (reject).
• max-teams-per-player (config, default 1) caps how many teams a single player can belong to at once. Invites, adds and requests are all blocked once the cap is hit.
• Vanilla scoreboard mirror. Every team is mirrored to a real scoreboard team named pb_<id> on the server's main scoreboard, so any vanilla command that accepts a target selector can target a PlainBase team, e.g.:

  /gamemode creative @a[team=pb_red]
  /tp @a[team=pb_red] 0 100 0
  

  Vanilla scoreboard teams only support one flat color for things like glow, so PlainBase maps your MiniMessage color to the closest vanilla color automatically — this is a small cosmetic accent only, it doesn't affect the selector.

  Vanilla limitation: a scoreboard entry (player name) can only be on one scoreboard team at a time. With the default max-teams-per-player: 1 this never matters. If you raise that limit, only a player's most-recently-joined team is mirrored for selector purposes — every other membership is still fully tracked by PlainBase (roles, /team info, placeholders), just not selector-visible at the same time. Folia: Folia currently considers all scoreboard API broken (unrelated to PlainBase). On Folia the scoreboard mirror is automatically disabled — team membership, roles, commands and placeholders all work exactly the same, you just can't use @a[team=pb_<id>] selectors there.

Commands

Grammar is always action first: /team <action> [team] [player] [role]. Run bare /team for a permission-aware help listing — it only shows the subcommands you can actually use.

Command	Description	Permission
/team list	List all configured teams with member counts.	plainbase.team.list
/team info [team]	No team given: your own teams + roles. With a team: that team's members.	plainbase.team.info
/team invites	List your own pending invites.	plainbase.team.invites
/team accept [team]	Accept a pending invite. Team is optional if you only have one pending invite.	plainbase.team.accept
/team deny [team]	Decline a pending invite.	plainbase.team.deny
/team leave [team]	Leave a team you're in. Team is optional if you're only in one.	plainbase.team.leave
/team request <team>	Ask to join a team — notifies its online admins.	plainbase.team.request
/team requests <team>	List a team's pending join requests. Admin-only.	plainbase.team.requests
/team invite <team> <player>	Invite a player (they must accept/deny). Admin-only.	plainbase.team.invite
/team add <team> <player>	Add a player directly, no confirmation. Also accepts a pending join request. Admin-only.	plainbase.team.add
/team kick <team> <player>	Remove a player from the team. Admin-only.	plainbase.team.kick
/team reject <team> <player>	Reject a pending join request. Admin-only.	plainbase.team.reject
/team setrole <team> <player> <member|admin>	Change a player's role in the team. Admin-only.	plainbase.team.setrole
(all Team commands)	Grants every permission of this module, and acts as admin on every team.	plainbase.team.admin

"Admin-only" above means: the sender needs the listed permission node and must pass as admin for that specific team — either an actual stored ADMIN role in it, or OP / plainbase.admin / plainbase.team.admin as a blanket bypass. Having only the permission node without the per-team admin role (or bypass) still gets "You must be a team admin of <team> to do this."

Like every PlainBase command, all of the above default to OP only — grant the ones you want regular players to self-serve (accept, deny, leave, request, requests, invites, list, info are the usual candidates) via your permissions plugin. Every subcommand also has its own team.commands.<name>.enabled toggle in modules/team.yml if you want to disable just one without touching permissions. See Permissions.

Placeholders (requires PlaceholderAPI)

Placeholder	Description
%plainbase_team_names%	Comma-separated list of the teams the viewing player is in.
%plainbase_team_count%	How many teams the viewing player is in.
%plainbase_team_primary%	The player's first/only team (empty if none).
%plainbase_team_pending_invites%	Number of pending invites the player has.
%plainbase_teams_count%	Total number of configured teams on the server.
%plainbase_team_role_<team>%	The player's role (member/admin/none) in a specific team.
%plainbase_team_members_<team>%	Member count of a specific team.

Configuration (modules/team.yml)

team:
  enabled: true
  max-teams-per-player: 1

  # Every subcommand has its own toggle here. "team" is the master switch
  # for the whole /team command tree — the rest are per-action fine control.
  commands:
    team: { enabled: true }
    list: { enabled: true }
    info: { enabled: true }
    invites: { enabled: true }
    accept: { enabled: true }
    deny: { enabled: true }
    leave: { enabled: true }
    request: { enabled: true }
    requests: { enabled: true }
    invite: { enabled: true }
    add: { enabled: true }
    kick: { enabled: true }
    reject: { enabled: true }
    setrole: { enabled: true }

teams:
  red:
    display-name: "<red>Red Team"
    color: "<red>"
  blue:
    display-name: "<blue>Blue Team"
    color: "<blue>"
  rainbow-example:
    display-name: "<rainbow>Rainbow Team"
    color: "<rainbow>"

messages:
  # every player-facing line — full MiniMessage, %player%/%team%/%role%/%staff% placeholders
  ...

Runtime data (membership/roles/invites/requests) lives in plugins/PlainBase/data/teams/*.yml — don't edit modules/team.yml's teams: section expecting it to change who's already a member; that only defines which teams exist.