# Team Configuration

# Team Configuration

**File:** `team/team.json`

Displays the server team with online status and avatars.

## Complete Example

```json
{
  "description": "Meet our team!",
  "showOnlineStatus": true,
  "showContactInfo": true,
  "showAvatars": true,
  "settings": {
    "showOnlineStatus": true,
    "groupByRank": true,
    "itemsPerPage": 8
  },
  "ranks": [
    {
      "id": "owner",
      "name": "Owner",
      "icon": "Ore_Gold",
      "color": "#FF5555",
      "priority": 1,
      "description": "Server Owner"
    },
    {
      "id": "admin",
      "name": "Administrator",
      "icon": "Weapon_Sword_Iron",
      "color": "#FF5555",
      "priority": 2,
      "description": "Server Administration"
    },
    {
      "id": "moderator",
      "name": "Moderator",
      "icon": "Weapon_Longsword_Iron",
      "color": "#55FF55",
      "priority": 3,
      "description": "Chat & Player Moderation"
    },
    {
      "id": "helper",
      "name": "Helper",
      "icon": "Deco_Scroll",
      "color": "#55FFFF",
      "priority": 4,
      "description": "Player Support"
    },
    {
      "id": "builder",
      "name": "Builder",
      "icon": "Tool_Pickaxe_Iron",
      "color": "#FFAA00",
      "priority": 5,
      "description": "Build Team"
    }
  ],
  "members": [
    {
      "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "name": "Kyuubi",
      "rank": "owner",
      "role": "Server Owner",
      "joinedAt": "2024-01-01",
      "description": "Founder & Developer",
      "contact": "Discord: Kyuubi#0001"
    },
    {
      "uuid": "",
      "name": "AdminPlayer",
      "rank": "admin",
      "role": "Senior Administrator",
      "description": "Handles major issues and appeals"
    },
    {
      "uuid": "",
      "name": "ModPlayer1",
      "rank": "moderator",
      "role": "Chat Moderator"
    }
  ]
}
```

---

## Settings

```json
"settings": {
  "showOnlineStatus": true,
  "groupByRank": true,
  "itemsPerPage": 8
}
```

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `showOnlineStatus` | Boolean | `true` | Show online/offline status indicator |
| `groupByRank` | Boolean | `true` | Group members by their rank |
| `itemsPerPage` | Integer | `8` | Members per page in the list view |

---

## General Settings (Top-Level)

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `description` | String | - | Description text shown at the top of the team page |
| `showOnlineStatus` | Boolean | `true` | Show online/offline status |
| `showContactInfo` | Boolean | `true` | Show contact information |
| `showAvatars` | Boolean | `true` | Load and display player avatars from hyvatar.io |

---

## Rank Structure

Ranks and members are stored in **separate arrays**. Each member references a rank by its `id`.

```json
{
  "id": "rank-id",
  "name": "Rank Name",
  "icon": "Item_Id",
  "color": "#hexcolor",
  "priority": 1,
  "description": "Rank description"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | String | Unique rank ID (referenced by members) |
| `name` | String | Display name |
| `icon` | String | Item ID for rank icon |
| `color` | String | Hex color code (default: `#FFFFFF`) |
| `priority` | Integer | Sort order (lower = higher, default: `99`) |
| `description` | String | Rank description |

---

## Member Structure

Members are defined in a separate `members` array and linked to ranks via the `rank` field.

```json
{
  "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "name": "PlayerName",
  "rank": "rank-id",
  "role": "Role/Position",
  "icon": "Item_Id",
  "joinedAt": "2024-01-01",
  "description": "Short description",
  "contact": "contact@example.com"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | String | Yes | Player name |
| `rank` | String | Yes | Rank ID (must match a rank's `id`) |
| `uuid` | String | No | Player UUID (for online status and avatar display) |
| `role` | String | No | Role/Position title |
| `icon` | String | No | Custom item icon (falls back to rank icon if null) |
| `joinedAt` | String | No | Join date (e.g., `"2024-01-01"`) |
| `description` | String | No | Short description |
| `contact` | String | No | Contact info (only shown if `showContactInfo` is enabled) |
| `group` | String | No | Optional group name, used when `settings.groupByRank` is `false` |
| `i18n` | Object | No | Optional role / description / group per language |

The Team tab shows the groups with "n of m online" and member cards with avatar (or the initial in the rank colour), an online marker, rank, role and contact. Online status is detected by UUID and by player name. When `showOnlineStatus` is off, the counts and markers are hidden too. Downloaded avatars are checked (PNG, max 128 px, size limit) before they reach players. In the admin window, the **Team** board has an online player picker for new members.

---

## Common Rank Colors

| Rank | Color | Hex |
|------|-------|-----|
| Owner | Red | `#FF5555` |
| Admin | Red | `#FF5555` |
| Developer | Purple | `#9b59b6` |
| Moderator | Green | `#55FF55` |
| Helper | Cyan | `#55FFFF` |
| Builder | Orange | `#FFAA00` |
| VIP | Gold | `#f1c40f` |

---

## Examples

### Minimal Team

```json
{
  "description": "Our staff team",
  "showOnlineStatus": true,
  "showContactInfo": false,
  "ranks": [
    {
      "id": "staff",
      "name": "Staff",
      "icon": "Weapon_Sword_Iron",
      "color": "#3498db",
      "priority": 1
    }
  ],
  "members": [
    { "name": "Admin1", "rank": "staff", "role": "Admin" },
    { "name": "Mod1", "rank": "staff", "role": "Moderator" }
  ]
}
```

### With Specialized Roles

```json
{
  "ranks": [
    {
      "id": "management",
      "name": "Management",
      "icon": "Ore_Gold",
      "color": "#e74c3c",
      "priority": 1
    },
    {
      "id": "developer",
      "name": "Developers",
      "icon": "Deco_Inkwell",
      "color": "#9b59b6",
      "priority": 2
    }
  ],
  "members": [
    {
      "name": "Owner",
      "rank": "management",
      "role": "Server Owner",
      "description": "Server management and development"
    },
    {
      "name": "CoOwner",
      "rank": "management",
      "role": "Co-Owner",
      "description": "Operations and community management"
    },
    {
      "name": "Dev1",
      "rank": "developer",
      "role": "Lead Developer",
      "description": "Plugin development"
    }
  ]
}
```

### With Contact Info Enabled

```json
{
  "showContactInfo": true,
  "ranks": [
    {
      "id": "support",
      "name": "Support Team",
      "icon": "Deco_Scroll",
      "color": "#2ecc71",
      "priority": 1
    }
  ],
  "members": [
    {
      "name": "Support1",
      "rank": "support",
      "role": "Support Lead",
      "contact": "support@example.com"
    }
  ]
}
```

---

## Best Practices

1. **Keep the list current** - Remove inactive members
2. **Use descriptive roles** - "Chat Moderator" not just "Mod"
3. **Enable online status** - Players see who's available
4. **Limit contact info** - Only show if necessary
5. **Order by hierarchy** - Higher ranks first (lower priority number)
6. **Provide UUIDs** - Enables online status checks and avatar display