# Multi-Player Teams Implementation

## Overview

The game now supports **up to 4 players per team**, allowing multiple people to log in as the same team and contribute to shared team progress.

## Login System

### Team Selection
Players select from 4 teams:
- **Crocks**
- **Hipps**
- **Buffs**
- **Tusks**

### Player Management
- Each team can have **up to 4 active players** simultaneously
- Players are automatically numbered: "Crocks Player 1", "Crocks Player 2", etc.
- Each player gets a unique session and JWT token
- If a 5th player attempts to join a full team, they receive an error: "Team is full"

## Example Scenarios

### Scenario 1: Uneven Team Distribution
**Valid Configuration:**
- 2 players log in as Crocks → "Crocks Player 1", "Crocks Player 2"
- 2 players log in as Hipps → "Hipps Player 1", "Hipps Player 2"
- 2 players log in as Tusks → "Tusks Player 1", "Tusks Player 2"
- 3 players log in as Buffs → "Buffs Player 1", "Buffs Player 2", "Buffs Player 3"

**Total: 9 active players across 4 teams** ✅

### Scenario 2: Maximum Capacity
**Valid Configuration:**
- 4 players log in as Crocks
- 4 players log in as Hipps
- 4 players log in as Buffs
- 4 players log in as Tusks

**Total: 16 active players (maximum capacity)** ✅

### Scenario 3: Team Full
If 4 players are already logged in as Buffs, a 5th player attempting to join Buffs will be rejected:
```json
{
  "error": "Team is full",
  "message": "Team Buffs already has 4 active players. Maximum reached."
}
```

## Team Progress Tracking

### Shared Progress
- All players on a team contribute to the **same team progress**
- Win counts are **shared across all team members**
- When any team member completes a challenge, the team's win count increases

### Fixed Win Requirements
Each challenge has a **fixed number of required wins** (not based on active session count):

| Challenge | Required Wins |
|-----------|---------------|
| GetToTheTemple | 4 |
| Mastermind | 1 |
| Anaconda2 | 3 |
| Hangman | 4 |

### Example: GetToTheTemple (4 wins required)
**Team Crocks has 3 players:**
1. Crocks Player 1 completes GetToTheTemple → Team wins: 1/4
2. Crocks Player 2 completes GetToTheTemple → Team wins: 2/4
3. Crocks Player 1 completes GetToTheTemple again → Team wins: 3/4
4. Crocks Player 3 completes GetToTheTemple → Team wins: 4/4 ✅ **Challenge Complete!**

Once the challenge is complete, **all 3 Crocks players** can advance to the next game.

## Team-Specific Codes

Each team receives unique codes when completing challenges:

### Hipps
- **CASE** (GetToTheTemple): `45678`
- **FLOATIES** (Mastermind): `2956`
- **STUNGUN** (Anaconda): `1352`
- **ROPE** (Hangman): `CARE`

### Crocks
- **CASE** (GetToTheTemple): `34568`
- **FLOATIES** (Mastermind): `8623`
- **STUNGUN** (Anaconda): `4653`
- **ROPE** (Hangman): `CROX1`

### Buffs
- **CASE** (GetToTheTemple): `23780`
- **FLOATIES** (Mastermind): `2435`
- **STUNGUN** (Anaconda): `6411`
- **ROPE** (Hangman): `B00KS`

### Tusks
- **CASE** (GetToTheTemple): `12345`
- **FLOATIES** (Mastermind): `6789`
- **STUNGUN** (Anaconda): `9876`
- **ROPE** (Hangman): `TUSKS`

## Database Structure

### team_sessions Table
Tracks each active player session:
```sql
id | team_id | player_name      | logged_in_at        | is_active
---|---------|------------------|---------------------|----------
1  | 2       | Crocks Player 1  | 2026-02-05 22:24:05 | 1
2  | 2       | Crocks Player 2  | 2026-02-05 22:24:05 | 1
3  | 1       | Hipps Player 1   | 2026-02-05 22:24:05 | 1
```

### team_progress Table
Tracks shared team progress:
```sql
team_id | challenge_name  | win_count | required_wins | completed
--------|-----------------|-----------|---------------|----------
2       | GetToTheTemple  | 2         | 4             | 0
2       | Mastermind      | 0         | 1             | 0
```

## Technical Implementation

### Modified Files
- **`/server/routes/auth.js`**
  - Added `MAX_PLAYERS_PER_TEAM = 4` constant
  - Changed session check to allow multiple players per team
  - Auto-generates unique player names ("Team Player 1", "Team Player 2", etc.)
  - Returns `playerName` and `playerNumber` in JWT token

### JWT Token Payload
```json
{
  "teamId": 2,
  "teamName": "Crocks",
  "sessionId": 3,
  "playerName": "Crocks Player 1"
}
```

## Testing

### Test Multiple Logins
```bash
# Test script included at: /tmp/test-multi-login.sh
./test-multi-login.sh
```

### Verify Active Sessions
```bash
sqlite3 game.db "SELECT team_id, player_name FROM team_sessions WHERE is_active = 1;"
```

## Admin Reset

To reset all progress between game sessions:
```bash
sqlite3 game.db "DELETE FROM team_sessions; DELETE FROM team_progress; DELETE FROM win_contributions; DELETE FROM team_collected_codes;"
```

Or restart the server (which will reset the database automatically on startup).