Skip to main content

​
Hop-On/Off Tournament Format

Hop-on/off tournaments are created by the Game Platform on-demand when players join a lobby. Tournaments start when a minimum player threshold is reached, providing continuous availability and instant gratification for players.

​
Key Characteristics

This format requires minimal new API development - only tournament creation and refund logic are format-specific. All gameplay functionality is shared with scheduled tournaments.
  • On-demand Creation: Game Platform creates tournaments when first player joins lobby
  • Player-count Start: Tournament starts when minimum players reached
  • Lobby-based Registration: Players join lobby first, then buy-in through Casino System
  • Continuous Cycle: Late joiners automatically create new tournaments
  • Refund Logic: Players can leave and get refunds before tournament starts

​
Architecture Overview

Key Principle: Game Platform creates tournament upfront via internal API. Tournament starts when MIN_PLAYERS reached instead of specific time.

​
Format-Specific Features

  • On-demand Creation: Game Platform creates tournaments when first player joins
  • Player-count Start: Tournament starts when minimum players reached
  • Lobby-based Registration: Players join via lobby, then buy-in through Casino System
  • Continuous Cycle: Late joiners create new tournaments automatically

​
Tournament Flow

​
Format-Specific APIs

​
Tournament Creation (New API)

Internal API - Game Platform creates tournaments: 
POST /internal/tournaments
Header: Authorization: Bearer {internal_api_key}  
Content-Type: application/json

{
  "name": "Crash #1642089600",
  "type": "hop_on_off",
  "gameSlug": "crash-classic",
  "minPlayers": 5,
  "maxPlayers": 50, 
  "startCondition": "min_players_reached",
  "entryFee": 5.00,
  "prizePool": {
    "type": "percentage", 
    "distribution": [60, 25, 15]
  },
  "rebuyEnabled": true,
  "rebuyFee": 5.00,
  "maxEntriesPerPlayer": 2
}
Response: 
{
  "tournamentId": 12346,
  "status": "scheduled",
  "minPlayers": 5,
  "currentPlayers": 0,
  "startCondition": "min_players_reached"
}

​
Player Refund Logic (New API)

Internal API - Remove players with refund: 
DELETE /internal/tournaments/12346/players/tp_player_456
Header: Authorization: Bearer {internal_api_key}
Content-Type: application/json

{
  "reason": "left_before_start"
}
External API - Process refund via Casino System: 
POST /api/operators/{operatorId}/players/{userId}/refund
Header: X-API-Key: {operator_key}
Content-Type: application/json

{
  "transactionId": "tx_12345",
  "amount": 5.00,
  "reason": "left_before_start"
}

​
Player Experience Flow

​
1. Joining the Lobby

1

Player Clicks Join Game

Player clicks game link or join button in Casino UI
2

Connect to Game Lobby

Casino UI connects to Game Platform lobby via WebSocket/postMessage
3

Tournament Availability Check

Game Platform checks if tournament exists waiting for players
4

Create New Tournament (if needed)

If no tournament waiting, Game Platform creates new tournament via internal API
5

Show Buy-in Interface

Casino UI displays tournament details and buy-in option

​
2. Player Registration & Tournament Start

1

Player Buys In

Player confirms buy-in through Casino System standard registration flow
2

JWT Token Generated

Tournament System generates JWT token and returns game URL
3

Waiting for Players

Player waits in lobby for minimum player count to be reached
4

Auto-start When Ready

Tournament starts automatically when playerCount >= minPlayers
5

Game Room Connection

Players connected to game room using shared common flow

​
3. Late Joiner Handling

1

Tournament Already Active

New player tries to join but current tournament is already running
2

Create Next Tournament

Game Platform automatically creates new tournament for next round
3

Seamless Registration

Player registers for next tournament using same flow
4

Continuous Availability

Always a tournament available for immediate play

​
Format-Specific Features

​
Tournament Creation Logic

When no tournament exists:
  • Game Platform creates new tournament via POST /internal/tournaments
  • Tournament status set to scheduled with startCondition: 'min_players_reached'
  • Lobby displays tournament info and buy-in interface
  • Players can register immediately via standard external APIs

​
Auto-start Logic

Unlike scheduled tournaments that start at a specific time, hop-on/off tournaments start when playerCount >= minPlayers.
Start Trigger Process:
  1. Player Count Check: After each registration, check if playerCount >= minPlayers
  2. Auto-start Tournament: Change status from scheduled to active
  3. Create Game Room: Request room creation from Game Platform
  4. Notify Players: Send SQS events and postMessage notifications
  5. Begin Gameplay: Use shared common flows for game management

​
Refund System

Players can leave before tournament starts and receive full refunds:
Important: Refunds are only available before tournament starts (status: 'scheduled'). Once tournament is active, standard leave policies apply.
Refund Process:
  1. Player Leaves Lobby: Disconnects before tournament starts
  2. Internal API Call: Game Platform notifies Tournament System
  3. Refund Request: Tournament System requests refund from Casino System
  4. Player Removal: Player removed from tournament registration
  5. Tournament Check: If last player left, tournament is cancelled

​
Continuous Tournament Cycle

Late Joiner Flow:
  • Player tries to join when tournament is already active
  • Game Platform creates next tournament immediately
  • Player registers for next tournament while current one runs
  • Ensures continuous availability without waiting

​
Shared Common Flows

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

Player Registration

Standard JWT generation and player session management.

Game Configuration

Tournament config delivery and real-time status sync.

Real-time Gameplay

Room management, postMessage events, SQS reporting.

Results & Completion

Prize calculation, distribution, and tournament cleanup.

​
Architecture Benefits

​
Player-count Reliability

  • Tournaments only start when enough players ready
  • No empty or under-populated tournaments
  • Guaranteed competitive experience

​
Continuous Availability

  • Always a tournament available for players to join
  • No waiting for scheduled times
  • Instant gratification for casual players

​
Minimal Development Requirements

  • Shared Functionality: 90% of code reused from scheduled tournaments
  • New APIs: Only tournament creation and refund logic
  • Proven Infrastructure: All gameplay and event systems already exist

​
Use Cases

Ideal for:
  • 🎮 Casual Gaming: Players wanting immediate tournament action
  • 🔄 Continuous Play: Games with steady player flow throughout the day
  • 📱 Mobile Games: Quick tournament rounds for mobile users
  • 🌐 Global Audiences: Different time zones, always someone ready to play
Example Scenarios:
  • Crash game tournaments starting every 5-10 minutes
  • Quick poker tournaments with 5-player minimum
  • Arcade-style competitions with instant starts
  • Practice tournaments for learning game mechanics

​
Implementation Timeline

1

Phase 1: Internal Tournament Creation API

Implement POST /internal/tournaments for Game Platform tournament creation
2

Phase 2: Player-count Start Logic

Add auto-start logic when minimum players reached
3

Phase 3: Refund System

Implement player removal and Casino System refund integration
4

Phase 4: Continuous Cycle Logic

Add late joiner detection and automatic next tournament creation

​
Next Steps

Casino Integration APIs

Learn about the external APIs used by both tournament formats for operator integration.