Skip to content
BattleStudio

Information

OptimalTeams features, roles, commands, permissions, placeholders, tokens and formatting in one reference.

BattleStudio plugin

OptimalTeams

Player teams with a four-role ladder, team chat, friendly-fire toggle, a team home and a points leaderboard fed by kills and KOTH captures, all run from menus.

Requires
Paper / FoliaMC 1.21.11+Java 21+OptimalLibraryPlaceholderAPI
Buy on BuiltByBitInstallation guideGet support

OptimalTeams lets players form teams. A player creates a team, invites others, and the team shares a role ladder (Leader, Co-Leader, Moderator, Member), a private team chat, a friendly-fire toggle, a team home and a points total that ranks it on the team leaderboard. Almost everything is done from menus; every action also has a command.

How it works

Section titled “How it works”
  • One team per player. A player can be in a single team at a time. Team names are unique, case-insensitively, and must pass the name rules in config.yml.
  • Joining. Members with the Invite role permission invite online players. An invite lasts Invite-Expiry seconds (default 5 minutes). A team that turns on Open Joining can be joined with /team join <team> without an invite. Every team has the same member cap, Max-Members (default 8).
  • Roles. Leader > Co-Leader > Moderator > Member. The leader can do everything; what the other roles can do is configured per role. Players can only manage members ranked below them. See Roles & Permissions.
  • Team chat. /tc toggles a mode where everything you type goes to your team only, or /tc <message> sends a single message.
  • Friendly fire. Off by default for new teams. While off, team members cannot hurt each other, by melee or with projectiles.
  • Team home. One home per team, with a warmup that cancels when you move and a per-player cooldown.
  • Points and ranking. Teams earn points from player kills and, with OptimalKoth installed, from KOTH captures. Admins can add, take or set points. Teams are ranked by points on the team top menu. See Points & Team Top.

Features

Section titled “Features”
  • Team creation, invites, open joining, leaving, kicking and disbanding, all from menus or commands
  • Four-step role ladder with configurable role names and per-role permissions
  • Leadership transfer (the old leader becomes Co-Leader)
  • Confirmation menu for disband, leave, kick and transfer
  • Team chat as a toggle or one-off message, routed through a chat block so it never leaks to public chat
  • Friendly-fire toggle per team, covering melee and projectiles
  • Team home with warmup, move cancel and cooldown
  • Points from player kills (with a per killer-and-victim cooldown) and OptimalKoth captures
  • Paginated team leaderboard with the team roster in each icon, plus a read-only info menu for any team
  • Chat, anvil, sign or dialog prompts for typing team names and player names
  • Menus refresh live while open
  • SQLite or MySQL storage
  • PlaceholderAPI expansion for scoreboards, tab and chat
  • Folia-ready

Commands

Section titled “Commands”

Player - /team (aliases /teams, /optimalteams) · all optimalteams.use:

  • /team - open your team menu, or the team hub if you are not in a team
  • /team help - show the help panel (also shown for an unknown subcommand)
  • /team create [name] - create a team. Without a name, a prompt asks for one.
  • /team disband - disband your team. Leader only, opens the confirm menu.
  • /team leave - leave your team. Opens the confirm menu. The leader cannot leave.
  • /team invite [player] - invite an online player. Without a name, a prompt asks for one.
  • /team accept [team] (alias /team join [team]) - accept an invite, or join an open team. Without a team, opens the invites menu.
  • /team deny [team] - decline an invite. Without a team, opens the invites menu.
  • /team kick <player> - remove a member ranked below you. Runs right away (the menu asks for confirmation, the command does not).
  • /team promote <player> / /team demote <player> - move a member one role up or down
  • /team transfer <player> - hand leadership to a member. Leader only, opens the confirm menu.
  • /team rename [name] - rename the team. Without a name, a prompt asks for one.
  • /team home - teleport to the team home
  • /team sethome - set the team home where you stand
  • /team delhome (alias /team deletehome) - delete the team home
  • /team chat [message] - toggle team chat, or send one message
  • /team info [team] - print the details and roster of your team, or of any team by name
  • /team top - open the team leaderboard
  • /team members - open the members menu
  • /team settings - open the settings menu
  • /team invites - open your pending invites

Team chat - /teamchat (alias /tc) · optimalteams.use:

  • /tc - toggle team chat mode
  • /tc <message> - send one message to your team

Admin - /teamadmin (aliases /tadmin, /teamsadmin, /optimalteamsadmin) · all optimalteams.admin:

  • /teamadmin disband <team> - disband any team
  • /teamadmin rename <team> <name> - rename any team. The name rules still apply.
  • /teamadmin points <team> <add|take|set> <amount> - change a team’s points. Amounts accept k, m, b, t and q suffixes (1.5k). Taking points never goes below 0.
  • /teamadmin reload - reload every config file

Admin commands work from console. /teamadmin is hidden from tab completion for players without optimalteams.admin.

Permissions

Section titled “Permissions”
  • optimalteams.use - /team, /teamchat and every menu (default: everyone)
  • optimalteams.admin - every /teamadmin command (default: op)

What a player can do inside their team is not a permission node. It comes from their team role, configured under Roles in config.yml. There are no member-limit permissions either: Max-Members applies to every team.

Placeholders

Section titled “Placeholders”

Requires PlaceholderAPI. The expansion is registered at startup when PlaceholderAPI is enabled.

Per player:

Placeholder Value
%optimalteams_has_team% true or false
%optimalteams_chat% true while the player has team chat mode on
%optimalteams_name% Team name (alias %optimalteams_team%)
%optimalteams_role% The player’s role display name
%optimalteams_leader% Leader’s name
%optimalteams_members% Member count
%optimalteams_online% Members online
%optimalteams_max_members% Max-Members
%optimalteams_points% Points, formatted with Number-Format
%optimalteams_points_raw% Points as a plain number
%optimalteams_rank% Leaderboard position
%optimalteams_friendly_fire% true or false
%optimalteams_open% true or false

For a player without a team, every placeholder in the table from name down returns Team-Format.No-Team (default No Team).

Global:

Placeholder Value
%optimalteams_teams% Number of teams on the server
%optimalteams_top_<rank>_name% Name of the team at that rank
%optimalteams_top_<rank>_points% Its points, formatted
%optimalteams_top_<rank>_points_raw% Its points as a plain number
%optimalteams_top_<rank>_leader% Its leader’s name
%optimalteams_top_<rank>_members% Its member count

<rank> starts at 1. A rank past the last team returns an empty string, so a top-10 hologram simply shows blank lines until ten teams exist.

With PlaceholderAPI installed, %...% placeholders from other plugins also resolve in messages, menu items and menu action arguments.

Tokens

Section titled “Tokens”

These are the plugin’s own {...} tokens. Which ones work where is listed per file in messages.yml and menus.

Team tokens (messages about a team, and every menu that shows one):

Token Value
{team} Team name
{leader} Leader’s name
{members} Member count
{max-members} Max-Members
{online} Members online
{points} Points, formatted with Number-Format
{points-raw} Points as a plain number
{rank} Leaderboard position
{friendly-fire} Team-Format.Enabled or Disabled
{open} Team-Format.Enabled or Disabled
{home} world x, y, z, or Team-Format.No-Home
{created} Creation date, dd/MM/yyyy HH:mm

Member tokens (member icons): {member}, {role}, {status} (Team-Format.Online / Offline), {joined} (dd/MM/yyyy HH:mm).

Durations ({time}, {expires}) are printed compactly, such as 5m or 1h, 30m.

Formatting

Section titled “Formatting”

Every text field supports legacy & codes, &#RRGGBB hex, MiniMessage (<gradient:a,b,c>, <rainbow>, <bold>, <#RRGGBB>, <solid:HEX>, …) and, with PlaceholderAPI, %...%. <gradient> accepts comma-separated hex stops.

Team names and team chat messages are inserted as plain text, so players cannot inject colors or MiniMessage tags through them.

Reference

Section titled “Reference”