# Teams

Teams group players with their own name, free rank system, bank, score/level, team home, warps, shared ender chest, chest claims and diplomacy (alliances, team/ally chat). Operated via `/team`, the team GUI (`/team` without arguments) and the [web interface](web-interface.html).

Important concept: the Bukkit permission (e.g. `team.invite`) decides whether a player may use the feature at all. The **rank right** (e.g. `INVITE_MEMBERS`) decides whether their rank inside the team may perform the action. The owner rank (weight 0) always has all rights.

## Commands

| Command | Syntax | Permission | Default | Rank right | Description |
|---|---|---|---|---|---|
| Create | `/team create <name>` | `team.create` | `true` | - | Creates a team, creator becomes owner |
| Disband | `/team disband` | `team.disband` | `true` | `DISBAND_TEAM` | Disbands after chat confirmation |
| Rename | `/team name <name>` | `team.manage` | `true` | `EDIT_NAME` | One word, all data is kept |
| Description | `/team description [text]` | `team.manage` | `true` | `EDIT_DESCRIPTION` | Sets/clears the description |
| Color | `/team color <color>` | `team.manage` | `true` | `EDIT_COLOR` | Named or hex |
| Tag | `/team tag [tag]` | `team.manage` | `true` | `EDIT_TAG` | Sets/removes the tag |
| Info | `/team info [team\|player]` | `team.info` | `true` | - | Details of a team |
| Menu | `/team menu` | `team.menu` | `true` | - | Opens the team GUI |
| Invite | `/team invite <player>` | `team.invite` | `true` | `INVITE_MEMBERS` | Max one open invite per target, expires after `invite-timeout` |
| Join | `/team join [team]` | `team.join` | `true` | - | Accepts an invite or joins an open team |
| Deny | `/team deny` | `team.deny` | `true` | - | Denies your pending invite |
| Leave | `/team leave` | `team.leave` | `true` | - | Owner must transfer or disband first |
| Open/closed | `/team open` | `team.open` | `true` | `TOGGLE_OPEN` | Toggles free joining |
| Kick | `/team kick <player>` | `team.kick` | `true` | `KICK_MEMBERS` | Only with strictly higher rank |
| Ban | `/team ban <player>` / `unban` | `team.ban` | `true` | `BAN_MEMBERS` | Bans (kicks first) or unbans |
| Ranks | `/team ranks <list\|create\|rename\|delete\|perms\|moveup\|movedown>` | `team.rank.manage` | `true` | `MANAGE_RANKS` | Manages the rank list |
| Assign rank | `/team ranks assign <player> <rank>` | `team.rank.assign` | `true` | `PROMOTE_MEMBERS` or `DEMOTE_MEMBERS` | Only ranks below your own |
| Balance | `/team bal` | `team.bal` | `true` | `VIEW_BALANCE` | Shows the team bank |
| Deposit | `/team deposit <amount>` | `team.deposit` | `true` | `DEPOSIT` | Player money into the bank |
| Withdraw | `/team withdraw <amount>` | `team.withdraw` | `true` | `WITHDRAW` | Bank to the player |
| Bank top | `/team baltop [page]` | `team.baltop` | `true` | - | Teams by balance (30 s cache) |
| Level info | `/team rank` | `team.rank` | `true` | - | Current level and requirements |
| Level up | `/team rankup` | `team.rankup` | `true` | `RANKUP_TEAM` | Ranks up when score and bank suffice |
| Score top | `/team top [page]` | `team.top` | `true` | - | Teams by score (30 s cache) |
| Home | `/team sethome` / `home` / `delhome` | `team.home` | `true` | `SET_HOME` / `USE_HOME` | Team home (warmup/cooldown/cost via `teamhome`) |
| Warps | `/team setwarp <name>` / `warp [name]` / `delwarp <name>` | `team.warp` | `true` | `MANAGE_WARPS` / `USE_WARPS` | Team warps in the unified warp system, details on the [warps page](warps.html) |
| Ender chest | `/team echest` | `team.echest` | `true` | `USE_ECHEST` | Shared 27-slot ender chest in real time |
| Chests | `/team chest <claim\|remove\|removeall>` | `team.chest` | `true` | `MANAGE_CHEST_CLAIMS` | Claim chests/barrels for the team |
| Convert shop | `/team shop` (look at shop) | `team.shop` | `true` | `EDIT_TEAM_SHOPS` | Turn your own chest shop into a team shop |
| Alliance | `/team ally <team>` / `neutral <team>` | `team.ally` | `true` | `MANAGE_ALLIES` | Mutual confirmation; neutral acts one-sided |
| Team chat | `/team chat [text]` | `team.chat` | `true` | `USE_TEAM_CHAT` | Without text: persistent toggle |
| Ally chat | `/team allychat [text]` | `team.allychat` | `true` | `USE_ALLY_CHAT` | Team + allies; excludes team chat |
| PvP | `/team pvp` | `team.pvp` | `true` | `TOGGLE_PVP` | Internal friendly fire on/off |
| Transfer owner | `/team setowner <player>` | `team.setowner` | `true` | `TRANSFER_OWNERSHIP` | Transfers ownership |

## Additional permissions

| Permission | Default | Description |
|---|---|---|
| `team.bypass.createcost` | `false` | Team creation free |
| `team.bypass.changecost` | `false` | Bypass change costs (name, tag, color, ...) |
| `team.bypass.friendlyfire` / `team.bypass.allyfriendlyfire` | `false` | Damages team/ally members despite protection |
| `team.bypass.chestclaim` | `false` | Opens/breaks foreign team chests |
| `team.bypass.depositcooldown` / `team.bypass.withdrawcooldown` | `false` | Bypass bank cooldowns |
| `team.bypass.limit` | `false` | Bypass warp/rank limits |

## Rank rights

Every right is grantable per rank individually (`/team ranks perms` or GUI). Ranks have an ID, display name (3 to 24 characters), weight (0 = owner, higher = lower), icon and rights. Rank limit: 3 preset ranks + `max-ranks` + level bonus, hard capped at 16.

| Category | Rights |
|---|---|
| Members | `INVITE_MEMBERS`, `KICK_MEMBERS`, `BAN_MEMBERS`, `PROMOTE_MEMBERS`, `DEMOTE_MEMBERS`, `MANAGE_RANKS` |
| Identity | `EDIT_NAME`, `EDIT_TAG`, `EDIT_DESCRIPTION`, `EDIT_COLOR`, `TOGGLE_OPEN`, `TOGGLE_PVP` |
| Diplomacy | `MANAGE_ALLIES`, `USE_ALLY_CHAT`, `USE_TEAM_CHAT` |
| Economy | `VIEW_BALANCE`, `DEPOSIT`, `WITHDRAW`, `RANKUP_TEAM` |
| Places | `USE_HOME`, `SET_HOME`, `USE_WARPS`, `MANAGE_WARPS` |
| Storage | `USE_ECHEST`, `MANAGE_CHEST_CLAIMS` |
| Danger zone | `DISBAND_TEAM`, `TRANSFER_OWNERSHIP` |
| Claims & shops | `BUILD_IN_TEAM_SUBDIVISIONS`, `BUILD_IN_ALLY_SUBDIVISIONS`, `MANAGE_TEAM_CLAIM_FLAGS` (used by [CoreEngineClaim](../claim/index.html)), `EDIT_TEAM_SHOPS` (shop system + web) |

Preset rights: owner everything; admin everything except `EDIT_NAME`, `DISBAND_TEAM`, `TRANSFER_OWNERSHIP`, `RANKUP_TEAM`; member `USE_TEAM_CHAT`, `USE_ALLY_CHAT`, `VIEW_BALANCE`, `DEPOSIT`, `USE_HOME`, `USE_WARPS`, `USE_ECHEST`, `BUILD_IN_TEAM_SUBDIVISIONS`.

> **Note:** Kick, ban, promote, demote and rank assignment additionally check the hierarchy (only a strictly higher rank may act, the owner outranks everyone). Rights are enforced identically everywhere: commands, GUI and web interface, for team/ally chat even per message.

## Score and levels

PvP kills between different teams give the killer team `per-kill` points and subtract `per-death` from the victim team (never below 0). Two protections: identical killer/victim IP is ignored entirely (`ip-check`), and after `spam-kill-max-kills` kills of the same victim within `spam-kill-window` seconds no more score is given.

`/team rankup` first checks the required score, then charges the level price from the team bank. Each level's bonus values add to the base limits; `bonus-shops` raises `max-shops-per-team` from the [shop module](shop.html).

> **Note:** In the default config `required-score` is 0 everywhere, so ranking up is only limited by money. To gate progression by PvP score, raise `required-score` per level.

## Chest claims

Claimable are chests, trapped chests and barrels (double chests always as a whole). They are protected against opening by outsiders, breaking (only with `MANAGE_CHEST_CLAIMS`), hoppers (own team's too) and explosions. Chest shops and team chests are mutually exclusive. With [CoreEngineClaim](../claim/index.html) installed, the chest must be inside a team claim of your team. Limit: `max-chest-claims` + level bonus.

## Admin commands (/teama)

All with permission `team.admin.<subcommand>`, default `false`.

| Command | Syntax | Description |
|---|---|---|
| `/teama disband\|name\|description\|color\|tag` | `/teama <sub> <team> [value]` | Force-manage any team |
| `/teama join` / `leave` | `/teama join <team> <player>` / `/teama leave <player>` | Force a player into/out of a team |
| `/teama promote` / `demote` / `setowner` | `/teama <sub> <player>` | Rank step up/down or force ownership |
| `/teama rank` | `/teama rank <team> <create\|delete\|rename\|list\|perms\|assign\|moveup\|movedown\|reset>` | Full access to the rank system, `reset` = back to the 3 default ranks |
| `/teama score` / `money` | `/teama <sub> <set\|add\|remove> <team> <value>` | Change score/bank directly |
| `/teama home` / `echest` / `chest` | `/teama <sub> <team> [...]` | Visit home, open ender chest, manage chest claims |
| `/teama purge` | `/teama purge` | Reset ALL team scores to 0 |
| `/teama chatspy` | `/teama chatspy` | Read team/ally chat |
| `/teama reload` | `/teama reload` | Reload team config |

## Configuration (modules/team.yml)

```yaml
# Enables or disables the team module.
enabled: true

team:
  # Base limits, level bonuses are added on top.
  max-team-size: 20
  min-name-length: 3
  max-name-length: 8
  # Allow MiniMessage in team names (then the visible length counts).
  allow-minimessage-names: false
  min-tag-length: 2
  max-tag-length: 4
  max-description-length: 100
  max-warps: 1
  # Custom rank slots at level 1, ON TOP of the 3 preset ranks.
  # Effective = 3 + max-ranks + bonus-ranks of the level, capped at 16.
  max-ranks: 2
  # Base chest claims, plus bonus-claims of the level.
  max-chest-claims: 25
  max-allies: 3
  # Team creation price. 0 = free.
  create-cost: 5000.0
  # Price per change; removing tag/description is always free,
  # charged only after a successful change.
  change-costs:
    rename: 0.0
    tag: 0.0
    color: 0.0
    description: 0.0
    sethome: 0.0
  # Caps for bank and score.
  max-balance: 1000000000.0
  max-score: 1000000
  # PvP default of new teams, server-wide ally friendly fire switch
  # and collision disabling between members.
  friendly-fire-default: false
  ally-friendly-fire: false
  collision-disabled: false
  # Forbidden name parts (substring filter).
  blocked-names: ["admin", "server", "staff", "moderator", "console", "system"]
  # Seconds until an invite expires.
  invite-timeout: 60
  score:
    per-kill: 10
    per-death: 5
    spam-kill-window: 300
    spam-kill-max-kills: 3
    ip-check: true
  # Levels: required-score and cost apply for ranking up TO that level,
  # bonus-* adds to the base limits.
  levels:
    1: { name: "Bronze",  required-score: 0, cost: 0,      bonus-members: 0,  bonus-warps: 0, bonus-claims: 0,   bonus-ranks: 0, bonus-shops: 0 }
    2: { name: "Silver",  required-score: 0, cost: 5000,   bonus-members: 5,  bonus-warps: 1, bonus-claims: 25,  bonus-ranks: 2, bonus-shops: 5 }
    3: { name: "Gold",    required-score: 0, cost: 25000,  bonus-members: 10, bonus-warps: 2, bonus-claims: 50,  bonus-ranks: 4, bonus-shops: 10 }
    4: { name: "Diamond", required-score: 0, cost: 100000, bonus-members: 20, bonus-warps: 3, bonus-claims: 75,  bonus-ranks: 6, bonus-shops: 20 }
    5: { name: "Emerald", required-score: 0, cost: 500000, bonus-members: 30, bonus-warps: 5, bonus-claims: 100, bonus-ranks: 8, bonus-shops: 40 }
  ranks:
    min-name-length: 3
    max-name-length: 24
    name-blacklist: ["owner"]
    # Material picker for rank icons. Empty = built-in list.
    icon-picker-materials: []
  gui:
    members-per-page: 28
    # /team without arguments opens the GUI.
    open-on-empty-command: true
    # Double confirmation for destructive actions.
    danger-double-confirm: true
  integrations:
    coreprotect:
      # Logs chest claim breaking (#teamclaim-<player>).
      chest-claim-logging: true

cooldown:
  commands:
    teamhome: 10
    teamwarp: 10
    teamdeposit: 5
    teamwithdraw: 10
    teamcreate: 5
    teamrankup: 5

cost:
  commands:
    teamhome: 0
    teamwarp: 0

warmup:
  commands:
    teamhome:
      duration: 5
    teamwarp:
      duration: 5
```

## Complete example config

```yaml
enabled: true

team:
  max-team-size: 10
  min-name-length: 3
  max-name-length: 12
  allow-minimessage-names: false
  min-tag-length: 2
  max-tag-length: 5
  max-description-length: 80
  max-warps: 2
  max-ranks: 3
  max-chest-claims: 15
  max-allies: 2
  create-cost: 10000.0
  change-costs:
    rename: 2500.0
    tag: 1000.0
    color: 500.0
    description: 0.0
    sethome: 500.0
  max-balance: 50000000.0
  max-score: 100000
  friendly-fire-default: false
  ally-friendly-fire: false
  collision-disabled: true
  blocked-names: ["admin", "server", "staff", "mod"]
  invite-timeout: 120
  score:
    per-kill: 15
    per-death: 10
    spam-kill-window: 600
    spam-kill-max-kills: 2
    ip-check: true
  levels:
    1: { name: "Recruit", required-score: 0,    cost: 0,      bonus-members: 0,  bonus-warps: 0, bonus-claims: 0,  bonus-ranks: 0, bonus-shops: 0 }
    2: { name: "Veteran", required-score: 500,  cost: 20000,  bonus-members: 5,  bonus-warps: 1, bonus-claims: 10, bonus-ranks: 2, bonus-shops: 5 }
    3: { name: "Elite",   required-score: 2500, cost: 100000, bonus-members: 10, bonus-warps: 2, bonus-claims: 25, bonus-ranks: 4, bonus-shops: 10 }
  ranks:
    min-name-length: 3
    max-name-length: 16
    name-blacklist: ["owner", "admin"]
    icon-picker-materials: []
  gui:
    members-per-page: 28
    open-on-empty-command: true
    danger-double-confirm: true
  integrations:
    coreprotect:
      chest-claim-logging: true

cooldown:
  commands:
    teamhome: 30
    teamwarp: 30
    teamdeposit: 5
    teamwithdraw: 30
    teamcreate: 60
    teamrankup: 10

cost:
  commands:
    teamhome: 10.0
    teamwarp: 10.0

warmup:
  commands:
    teamhome:
      duration: 5
    teamwarp:
      duration: 5
```