## Features

### Team Management

- Create and disband teams

- Invite players to your team, with configurable expiry and optional economy cost

- Kick players, promote/demote members, and transfer leadership

- Rename your team with optional cost and cooldown

- Set a team message of the day (MOTD)

- View team info in a GUI (level, members, homes, warps, MOTD)

- List all teams and see online team members

- Check team level progress with `/team level`

### Team Levels and Limits

- Team level is based on member-count thresholds

- Level-based limits for homes, alliances, and vault size

- Role daily withdrawal limits can scale by team level

### Team Homes

- Set, teleport to, and delete named team homes

- `/team home` lists homes when no name is provided

- Base max homes with optional level-based overrides

- Per-world toggles for homes

- Per-player teleport cooldown (shared with warps)

### Team Warps

- Shared warps that are separate from homes

- `/team warp` lists warps when no name is provided

- Uses the same world toggle and teleport cooldown as homes

- By default, only the team owner can set or delete warps, while members can use and list them

### Team Vault

- Shared storage with size based on config and team level

- Permission-based access for open, deposit, and withdraw

- Role daily withdrawal limits with team-level multipliers

- Per-world vault toggle

- Auto-saves vault contents

### Team Chat

- Toggle team-only chat and ally chat

- Mute or unmute members in team chat

- Optional role prefix display in player name tags and tab list (`/team showrole`)

- Per-world chat toggles

### Alliance System

- Invite, accept, decline, break, and list alliances

- Ally chat for cross-team communication

- Friendly-fire protection when enabled

- Configurable max alliances with level-based overrides

- Configurable cooldown after breaking an alliance

### Role System

- Default roles with configurable permissions and priorities

- Custom roles per team

- Starting role for new members is configurable

- Role priority enforces promotion, demotion, and management rules

- Internal permissions are not server permissions

### Team Colors

- 15 available team colors

- Random color on creation or default green

- Team colors show in chat, player list, and name tags

- `/team color` to change color and `/team colors` to list options

### Trust System

- Toggle a trusted flag for members

- Stored with team data (no extra permissions by default)

### Economy Integration

- Invite cost and rename cost use Vault economy if enabled

---

## Commands

### Team Commands

| Command | Description |

|---------|-------------|

| `/team create <name>` | Create a new team |

| `/team disband` | Disband your team |

| `/team invite <player>` | Invite a player to your team |

| `/team accept` | Accept a team invitation |

| `/team leave` | Leave your current team |

| `/team kick <player>` | Kick a player from the team |

| `/team promote <player>` | Promote a player to a higher role |

| `/team demote <player>` | Demote a player to a lower role |

| `/team transfer <player>` | Transfer leadership to another member |

| `/team info` | View team information in a GUI |

| `/team level` | Show team level and progress to next level |

| `/team list` | List all teams on the server |

| `/team online` | List online team members |

| `/team sethome <name>` | Set a named team home |

| `/team home [name]` | Teleport to a team home or list homes |

| `/team delhome <name>` | Delete a team home |

| `/team setwarp <name>` | Set a named team warp |

| `/team warp [name]` | Teleport to a team warp or list warps |

| `/team delwarp <name>` | Delete a team warp |

| `/team warplist` | List all team warps |

| `/team rename <name>` | Rename your team |

| `/team motd <message>` | Set the team message of the day |

| `/team chat` | Toggle team-only chat |

| `/team vault` | Open the team vault |

| `/team trust <player>` | Toggle trusted status for a player |

| `/team mute <player>` | Mute or unmute a player in team chat |

| `/team showrole` | Toggle role prefix display in name tags and tab list |

| `/team role` | Role management subcommands |

| `/team color <color>` | Change your team's display color |

| `/team colors` | List available team colors |

| `/team reload` | Reload config and save data (requires `teams999.reload`) |

### Role Commands

| Command | Description |

|---------|-------------|

| `/team role create <name>` | Create a custom role |

| `/team role delete <name>` | Delete a custom role |

| `/team role list` | List all roles in your team |

| `/team role info <name>` | View details about a role |

| `/team role assign <player> <role>` | Assign a role to a player |

| `/team role perm add <role> <perm>` | Add a permission to a custom role |

| `/team role perm remove <role> <perm>` | Remove a permission from a custom role |

### Alliance Commands

| Command | Description |

|---------|-------------|

| `/ally invite <team>` | Invite a team to form an alliance |

| `/ally accept` | Accept an alliance invitation |

| `/ally decline` | Decline an alliance invitation |

| `/ally break <team>` | Break an alliance with a team |

| `/ally chat` | Toggle alliance-only chat |

| `/ally list` | List your team's alliances |

### Command Aliases

- `/team` can also be used as `/t`

- `/ally` can also be used as `/a`

---

## Internal Permissions

These permissions control what team members can do based on their role. They are NOT server permissions and do not work with permission plugins like LuckPerms.

### Member Management

| Permission | Description |

|------------|-------------|

| `team.invite` | Invite players to the team |

| `team.kick` | Kick players from the team |

| `team.promote` | Promote players to higher roles |

| `team.demote` | Demote players to lower roles |

| `team.role.assign` | Assign roles to players |

| `team.role.create` | Create custom roles |

| `team.role.delete` | Delete custom roles |

### Team Settings

| Permission | Description |

|------------|-------------|

| `team.motd.set` | Set the message of the day |

| `team.name.change` | Rename the team |

| `team.color.change` | Change the team's display color |

| `team.disband` | Disband the team |

| `team.transfer` | Transfer leadership to another player |

### Vault

| Permission | Description |

|------------|-------------|

| `team.vault.open` | Open the team vault |

| `team.vault.deposit` | Put items into the vault |

| `team.vault.withdraw` | Take items from the vault |

### Chat

| Permission | Description |

|------------|-------------|

| `team.chat.toggle` | Toggle between chat modes |

| `team.chat.team` | Send messages in team chat |

| `team.chat.ally` | Send messages in ally chat |

| `team.chat.moderate` | Mute and unmute team members |

### Alliances

| Permission | Description |

|------------|-------------|

| `team.ally.invite` | Send alliance invitations |

| `team.ally.accept` | Accept alliance invitations |

| `team.ally.break` | Break alliances |

### Homes

| Permission | Description |

|------------|-------------|

| `team.home.set` | Set team home locations |

| `team.home.delete` | Delete team home locations |

| `team.home.use` | Teleport to team homes |

### Warps

| Permission | Description |

|------------|-------------|

| `team.warp.set` | Set team warp locations |

| `team.warp.delete` | Delete team warp locations |

| `team.warp.use` | Teleport to team warps and list them |

### Other

| Permission | Description |

|------------|-------------|

| `team.info.view` | View team information |

| `team.trust` | Toggle trusted status for members |

### Reserved (No Effect Yet)

| Permission | Description |

|------------|-------------|

| `team.vault.lockedSlots` | Reserved for future vault slot locking |

| `team.claim` | Reserved for future land claim features |

| `team.unclaim` | Reserved for future land claim features |

| `team.war.start` | Reserved for future war features |

| `team.war.accept` | Reserved for future war features |

---

## Role Permission Matrix

This table reflects the default role permissions from `config.yml`. The Leader has all internal permissions.

|------------|--------|-----------|---------|--------|---------|

| `team.invite` | Yes | Yes | Yes | No | No |

| `team.kick` | Yes | Yes | Yes | No | No |

| `team.promote` | Yes | Yes | No | No | No |

| `team.demote` | Yes | Yes | No | No | No |

| `team.role.assign` | Yes | Yes | No | No | No |

| `team.role.create` | Yes | Yes | No | No | No |

| `team.role.delete` | Yes | Yes | No | No | No |

| `team.motd.set` | Yes | Yes | No | No | No |

| `team.name.change` | Yes | No | No | No | No |

| `team.color.change` | Yes | No | No | No | No |

| `team.disband` | Yes | No | No | No | No |

| `team.transfer` | Yes | No | No | No | No |

| `team.vault.open` | Yes | Yes | Yes | Yes | No |

| `team.vault.deposit` | Yes | Yes | Yes | Yes | No |

| `team.vault.withdraw` | Yes | Yes | Yes | No | No |

| `team.chat.toggle` | Yes | Yes | Yes | Yes | No |

| `team.chat.team` | Yes | Yes | Yes | Yes | Yes |

| `team.chat.ally` | Yes | Yes | Yes | Yes | No |

| `team.chat.moderate` | Yes | Yes | Yes | No | No |

| `team.ally.invite` | Yes | Yes | No | No | No |

| `team.ally.accept` | Yes | Yes | No | No | No |

| `team.ally.break` | Yes | Yes | No | No | No |

| `team.home.set` | Yes | Yes | Yes | No | No |

| `team.home.delete` | Yes | Yes | Yes | No | No |

| `team.home.use` | Yes | Yes | Yes | Yes | No |

| `team.warp.set` | Yes | No | No | No | No |

| `team.warp.delete` | Yes | No | No | No | No |

| `team.warp.use` | Yes | Yes | Yes | Yes | No |

| `team.info.view` | Yes | Yes | Yes | Yes | Yes |

| `team.trust` | Yes | Yes | No | No | No |

---

## Configuration

### Team Settings

| Setting | Default | Description |

|---------|---------|-------------|

| `team.max-size` | 10 | Maximum players allowed in a team (minimum 2 enforced) |

| `team.invite-expiry` | 5 | Minutes before an invitation expires |

| `team.invite-cost` | 0 | Economy cost to send a team invitation (Vault required) |

| `team.max-homes` | 3 | Base maximum team homes if no level override applies |

| `team.rename-cost` | 1000 | Economy cost to rename a team (Vault required) |

| `team.rename-cooldown` | 60 | Minutes between team renames |

| `team.home-teleport-cooldown-seconds` | 0 | Per-player cooldown for home and warp teleports |

| `team.name-format` | `^[a-zA-Z0-9_]{3,16}$` | Regex for valid team names |

| `team.random-colors` | true | Assign random colors to new teams |

### Alliance Settings

| Setting | Default | Description |

|---------|---------|-------------|

| `alliances.friendly-fire` | false | If false, allies cannot damage each other where PvP protection is enabled |

| `alliances.max-alliances` | 3 | Base maximum alliances if no level override applies |

| `alliances.break-cooldown-minutes` | 0 | Minutes before a team can break another alliance |

### Vault Settings

| Setting | Default | Description |

|---------|---------|-------------|

| `vault.base-size` | 54 | Base vault size (multiple of 9, min 9, max 54) |

### Role Defaults

| Setting | Description |

|---------|-------------|

| `roles.starting-role` | Role assigned to new members when they accept an invite |

| `roles.defaults.<role>.display-name` | Display name shown in GUI and chat |

| `roles.defaults.<role>.color` | ChatColor name for the role prefix |

| `roles.defaults.<role>.priority` | Role priority (higher can manage lower) |

| `roles.defaults.<role>.can-be-kicked` | Whether members with this role can be kicked |

| `roles.defaults.<role>.can-be-modified` | Whether this role can be modified |

| `roles.defaults.<role>.daily-withdraw-limit` | Base daily vault withdrawal limit (-1 for unlimited) |

| `roles.defaults.<role>.permissions` | Internal permissions list, `*` grants all |

### Team Levels

| Setting | Default | Description |

|---------|---------|-------------|

| `team-levels.member-thresholds` | map | Member count thresholds for each team level |

### Level-Based Limits

| Setting | Default | Description |

|---------|---------|-------------|

| `limits.homes.by-level` | map | Max homes by team level |

| `limits.alliances.by-level` | map | Max alliances by team level |

| `limits.vault-size.by-level` | map | Vault size by team level |

| `limits.daily-withdrawals.team-level-multiplier` | map | Multiplier applied to role daily withdrawal limits |

### World Toggles

| Setting | Default | Description |

|---------|---------|-------------|

| `world-toggles.team-chat-disabled-worlds` | [] | Worlds where team and ally chat are disabled |

| `world-toggles.homes-disabled-worlds` | [] | Worlds where homes and warps are disabled |

| `world-toggles.vault-disabled-worlds` | [] | Worlds where team vault is disabled |

| `world-toggles.pvp-protection-disabled-worlds` | [] | Worlds where allied PvP protection is disabled |

---

## Available Team Colors

- RED

- BLUE

- GREEN

- YELLOW

- GOLD

- AQUA

- LIGHT_PURPLE

- WHITE

- DARK_RED

- DARK_BLUE

- DARK_GREEN

- DARK_AQUA

- DARK_PURPLE

- DARK_GRAY

- GRAY

---

## Custom Roles

You can create custom roles for your team with specific permissions.

### Creating a Custom Role

1. Create the role: `/team role create Builder`

2. Add permissions: `/team role perm add Builder team.home.set`

3. Add more permissions: `/team role perm add Builder team.warp.use`

4. Assign to a player: `/team role assign PlayerName Builder`

### Managing Custom Roles

- View all roles: `/team role list`

- View role details: `/team role info Builder`

- Remove a permission: `/team role perm remove Builder team.home.set`

- Delete a role: `/team role delete Builder`

### Custom Role Notes

- Custom roles have priority 40 by default

- Custom roles can be modified, default roles cannot

- When a custom role is deleted, members with that role become Members

- You can only assign roles with lower priority than your own

---

## How Role Hierarchy Works

- Each role has a priority number

- Higher priority roles can manage lower priority roles

- You cannot kick, promote, demote, or assign roles to someone with equal or higher priority

- Leader and Co-Leader cannot be kicked from the team

- Only the Leader can transfer leadership or disband the team

---

## Data Storage

- Team data (members, roles, homes, warps, MOTD, trust list) is saved to `data.yml`

- Vault contents are saved to `teamvaults.yml`

- Data auto-saves periodically

- Data saves when the server stops

Teams999