> ## Documentation Index
> Fetch the complete documentation index at: https://docs-ts.playservices.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Scheduled Tournaments

> Time-based tournaments created in advance with specific start times

# Scheduled Tournament Format

Scheduled tournaments are created by the Casino System with a specific start time and start automatically when that time arrives, regardless of player count. This format is ideal for planned events, marketing campaigns, and fixed-time competitions.

## Key Characteristics

<Info>
  Scheduled tournaments use **100% existing APIs** - no new development required. All functionality is already implemented and tested.
</Info>

* **Pre-creation**: Tournament created before players register
* **Time-based Start**: Tournament starts at scheduled time regardless of player count
* **Standard Registration**: Players register in advance using standard external APIs
* **Immediate or Scheduled**: Can start immediately if `startTime <= now()` or be scheduled for future

## Architecture Overview

**Key Principle**: Casino System creates tournament with specific startTime. Tournament System starts tournament automatically when scheduled time arrives.

### Format-Specific Features

* **Pre-creation**: Tournament created before players register
* **Time-based Start**: Tournament starts at scheduled time regardless of player count
* **Standard Registration**: Players register in advance using standard APIs

## Tournament Flow

```mermaid theme={null}
sequenceDiagram
    participant CS as Casino System
    participant TS as Tournament System  
    participant GP as Game Platform
    participant SQS as AWS SQS

    Note over CS,SQS: 1. Tournament Creation (Format-Specific)
    CS->>TS: POST /api/tournaments<br/>Header: X-API-Key: operator_key<br/>Body: {name, startTime, endTime, gameConfig}
    TS->>TS: Validate operator permissions<br/>(tournaments.write)
    TS->>TS: Create tournament record<br/>status: 'scheduled'
    TS->>CS: 201 Created {tournamentId, status: 'scheduled'}

    Note over CS,SQS: 2. Tournament Start Scheduling (Format-Specific)
    TS->>TS: Check: startTime <= now()?

    alt Immediate Start (startTime <= now())
        TS->>TS: Start tournament immediately<br/>Set status: 'active'
        TS->>GP: POST /api/rooms/create<br/>Body: {tournamentId, gameConfig, maxPlayers}
        GP->>GP: Create game room instance
        GP->>TS: 201 Created {roomId, roomUrl}
        TS->>TS: Store roomId in tournament record
        TS->>SQS: Send event: tournament.started<br/>{tournamentId, status: 'active'}
        SQS->>CS: Tournament started notification
    else Scheduled Start
        TS->>TS: Schedule tournament start job

        Note over CS,SQS: Wait for scheduled time...
        TS->>TS: Scheduled job triggers tournament start<br/>Set status: 'active'
        TS->>GP: POST /api/rooms/create<br/>Body: {tournamentId, gameConfig, maxPlayers}
        GP->>GP: Create game room instance
        GP->>TS: 201 Created {roomId, roomUrl}
        TS->>TS: Store roomId in tournament record
        TS->>SQS: Send event: tournament.started<br/>{tournamentId, status: 'active'}
        SQS->>CS: Tournament started notification
    end

    Note over CS,SQS: [COMMON FLOWS - Shared with Hop-On/Off]
    Note over CS,SQS: 3. Player Registration & Authentication → Common Flow
    Note over CS,SQS: 4. Game Platform Configuration Exchange → Common Flow
    Note over CS,SQS: 5. Game Launch & Room Connection → Common Flow
    Note over CS,SQS: 6. Tournament Gameplay & Event Reporting → Common Flow
    Note over CS,SQS: 7. Player Management (Rebuy/Leave) → Common Flow  
    Note over CS,SQS: 8. Tournament Completion & Cleanup → Common Flow
    Note over CS,SQS: 9. Results & Leaderboard Access → Common Flow
```

## Format-Specific APIs

### Tournament Creation

```http theme={null}
POST /api/tournaments
Header: X-API-Key: {operator_key}
Content-Type: application/json

{
  "name": "Daily Championship", 
  "startTime": "2024-01-15T20:00:00Z",
  "endTime": "2024-01-15T21:30:00Z", 
  "gameSlug": "crash-classic",
  "maxPlayers": 100,
  "minPlayers": 10,
  "entryFee": 10.00,
  "prizePool": {
    "type": "percentage",
    "distribution": [50, 30, 20]
  },
  "rebuyEnabled": true,
  "rebuyFee": 10.00,
  "maxEntriesPerPlayer": 3
}
```

**Response:**

```json theme={null}
{
  "tournamentId": 12345,
  "status": "scheduled", 
  "scheduledStart": "2024-01-15T20:00:00Z",
  "roomId": null,
  "gameUrl": null
}
```

### Tournament Start Logic

The Tournament System handles start logic automatically:

<Tabs>
  <Tab title="Immediate Start">
    **When `startTime <= now()`:**

    1. Tournament starts immediately upon creation
    2. Status set to `active`
    3. Game room created via Game Platform
    4. SQS event `tournament.started` sent
    5. Players can register and join immediately
  </Tab>

  <Tab title="Scheduled Start">
    **When `startTime > now()`:**

    1. Tournament created with status `scheduled`
    2. Background job scheduled for `startTime`
    3. Players can register in advance
    4. At scheduled time:
       * Status changed to `active`
       * Game room created
       * SQS event `tournament.started` sent
       * Registered players can join game
  </Tab>
</Tabs>

## Player Registration Flow

Players register using the standard external API flow:

### 1. Player Registration

```http theme={null}
POST /api/tournaments/12345/players
Header: X-API-Key: {operator_key}
Content-Type: application/json

{
  "userId": "player_123",
  "displayName": "PlayerName",
  "buyInAmount": 10.00
}
```

### 2. JWT Token & Game URL

```json theme={null}
{
  "playerId": "tp_player_456",
  "jwtToken": "eyJ0eXAi...",
  "gameUrl": "https://game.platform.com/room/abc123?token=eyJ0eXAi...",
  "roomUrl": "https://game.platform.com/room/abc123",
  "tournamentStatus": "scheduled|active"
}
```

### 3. Game Launch

* **If tournament is `scheduled`**: Player waits for scheduled start time
* **If tournament is `active`**: Player can join game room immediately
* **Game Platform**: Validates JWT and connects player to tournament room

## Shared Common Flows

After tournament creation and start logic, scheduled tournaments use identical flows as hop-on/off tournaments:

<CardGroup cols={2}>
  <Card title="Player Registration & Authentication" icon="user-plus" href="/casino-integration/player-management#registration-flow">
    JWT generation, validation, and player session management.
  </Card>

  <Card title="Game Platform Configuration" icon="gear" href="/game-platform-integration/internal-apis#tournament-configuration">
    Tournament config delivery and real-time status updates.
  </Card>

  <Card title="Real-time Gameplay & Events" icon="bolt" href="/game-platform-integration/real-time-communication">
    Room connections, postMessage communication, SQS event reporting.
  </Card>

  <Card title="Tournament Completion" icon="trophy" href="/casino-integration/results-leaderboards">
    Results calculation, prize distribution, and final cleanup.
  </Card>
</CardGroup>

## Architecture Benefits

<Columns cols={2}>
  <div>
    ### Time-based Reliability

    * Tournaments start precisely at scheduled time
    * Consistent experience for planned events
    * Marketing campaigns can rely on exact timing
  </div>

  <div>
    ### Pre-registration Support

    * Players can register before tournament starts
    * Build anticipation and ensure participation
    * Better capacity planning and resource allocation
  </div>
</Columns>

### Proven Infrastructure

* **100% existing APIs**: Uses current scheduled tournament system
* **Comprehensive Testing**: All functionality already tested and proven
* **Shared Functionality**: All gameplay, events, and player management uses common flows
* **No New Development**: Ready to deploy immediately

## Use Cases

**Ideal for:**

* 🎯 **Marketing Events**: Promotional tournaments with specific timing
* 📅 **Regular Schedules**: Daily/weekly tournaments at consistent times
* 🏆 **Championship Events**: High-stakes tournaments requiring coordination
* 📈 **Capacity Planning**: Predictable load patterns for infrastructure scaling

**Example Scenarios:**

* Daily 8 PM championships with email notifications
* Weekend special events with increased prize pools
* Seasonal tournaments aligned with game releases
* Corporate events with specific timing requirements

## Next Steps

<Card title="Hop-On/Off Tournaments" icon="users" href="/tournament-types/hop-on-off-tournaments" horizontal>
  Learn about the player-count based tournament format for continuous availability.
</Card>