EGP Leaderboard Service v3.0

A scalable, real-time leaderboard service for game applications. This service provides APIs for managing leaderboards, submitting scores, and retrieving leaderboard data with real-time updates via WebSockets.

Features

Real-time Leaderboards: Get instant updates when scores change

Multiple Time Frames: Support for daily, weekly, monthly, and all-time leaderboards

Scalable Architecture: Built with Redis for real-time data and ScyllaDB for historical storage

WebSocket Support: Real-time notifications for leaderboard changes

Flexible Scoring: Support for different scoring strategies (highest, latest, cumulative)

Customizable Score Aggregation: Per-leaderboard mathematical formulas for score calculation

Advanced Math Operations: Integration with Math.js for complex statistical calculations

Custom Display IDs: Specify your own IDs when creating leaderboards, with per-owner uniqueness

Extensible Metadata System: Store custom configuration and UI settings with each leaderboard

Pagination: Efficient retrieval of large leaderboards

User History: Track a user's performance over time

Game-specific Leaderboards: Organize leaderboards by game

Comprehensive API: RESTful endpoints for all operations

User Management: Complete user management with authentication and authorization

Bulk Operations: Support for bulk creating leaderboards and adding entries

Robust Leaderboard Reset: Securely reset leaderboards with distributed locking to prevent race conditions

Historical Snapshots: Create snapshots before resetting leaderboards to preserve historical data

Role-Based Time Restrictions: Configurable time-based access controls based on user roles

Strategic Cache Invalidation: Sophisticated cache management to ensure data consistency

Implementation

Score aggregation is implemented at the service layer, ensuring consistent application regardless of how scores are submitted:

Each leaderboard's scoring rule is stored in its metadata in ScyllaDB

When a score is submitted, the rule is loaded and applied automatically

Calculations occur server-side, ensuring consistent application of rules

Optional metadata can track score history and calculation details

API

Leaderboard owners can manage scoring rules through the dedicated API endpoint:

PUT /api/leaderboards/:id/score-aggregation

This allows defining or updating the scoring formula for a specific leaderboard.

Examples

Basic examples of score aggregation rules:

// Accumulate scores (add new scores to current total)
{
  "type": "expression",
  "expression": "${current} + ${new}"
}

// Keep highest score
{
  "type": "expression",
  "expression": "Math.max(${current}, ${new})"
}

// Calculate statistical weighted average with Math.js
{
  "type": "expression",
  "engine": "mathjs",
  "expression": "0.7 * ${new} + 0.3 * ${current}"
}

For a complete reference, see the Score Aggregation API documentation.

Custom Display IDs

The Leaderboard Service allows clients to specify their own custom display IDs when creating leaderboards, making them easier to reference and integrate with external systems.

Key Features

Custom Identifiers: Specify your own IDs when creating leaderboards

Per-Owner Uniqueness: Different owners can use the same display ID

Public Access: Retrieve leaderboards by display ID without authentication

No Schema Changes: Uses existing metadata field, avoiding migrations

Example Usage

Benefits

Meaningful Identifiers: Use IDs that make sense for your application

Easier Integration: Simplify integration with other systems

User-Friendly URLs: Create cleaner, more readable URLs

Predictable References: Reference leaderboards with known IDs in your code

For more details and implementation specifics, see the Custom Display ID documentation.

Extensible Metadata System

The Leaderboard Service includes a powerful metadata system that allows storing custom configuration, UI settings, and game-specific information with each leaderboard and entry.

Key Features

Custom JSON Storage: Store any valid JSON data as metadata with leaderboards and entries

Schema-Free Design: Add custom fields without requiring database schema changes

Intelligent Merging: New metadata merges with existing values, preserving critical data

Dual Redis/ScyllaDB Storage: Metadata is stored in both databases for performance and reliability

UI Customization: Store display preferences, color schemes, and formatting options

Game-Specific Data: Include game modes, seasons, levels, and other contextual information

Administrative Tags: Add searchable tags and categories for organization

Client Configuration: Store client-side rendering options and behavior settings

Implementation

The metadata system is built into the core service layer:

Storage: Metadata is stored as a JSON string in both Redis and ScyllaDB

Validation: All metadata is validated to ensure it's proper JSON before storage

Merging: New metadata is intelligently merged with existing data

Preservation: Important data like score aggregation rules are preserved during updates

Cache Invalidation: Updates automatically invalidate Redis cache to ensure consistency

Blackjack Leaderboard Aggregator: A Case Study

This document provides a detailed explanation of the Blackjack Leaderboard Aggregator integration test, which demonstrates how score aggregation rules can be used to track complex game statistics.

Overview

The blackjack leaderboard aggregator test demonstrates a real-world implementation of our centralized score aggregation system. It simulates a blackjack tournament where multiple players compete against a dealer, with the leaderboard automatically tracking wins, losses, pushes, blackjacks, and calculating win rates.

Game Rules

Blackjack is played with the following rules in our implementation:

Basic Play: Players try to get a higher card total than the dealer without exceeding 21

Card Values:

Number cards (2-10) are worth their face value

Face cards (J, Q, K) are worth 10

Aces are worth 11 or 1, whichever creates the better hand

Outcomes:

Win: Player's hand beats dealer's hand, or dealer busts

Loss: Dealer's hand beats player's hand, or player busts

Push: Player and dealer have equal hand values

Blackjack: A natural 21 with first two cards (Ace + 10/Face card)

Betting:

Standard wins pay 1:1 ($50 in our test)

Blackjack pays 1.5:1 ($75 in our test)

Pushes return the original bet (no gain/loss)

Losses forfeit the bet

Implementation Flow

The test demonstrates the full integration between client and server components:

1. Setup Phase

Obtain JWT token

Generate API key

Create a leaderboard with score aggregation rules

2. Gameplay Phase

Deal cards to players and dealer

Players make decisions (hit/stand) based on basic strategy

Dealer plays according to house rules (hit until 17+)

Calculate outcomes (win/loss/push)

Update bankrolls

Send results to leaderboard service

3. Verification Phase

Get leaderboard entries

Verify statistics calculation

Validate ranking order

Client vs. Server Responsibilities

Component	Client Side	Server Side
Game Logic	✓ (Hit/stand decisions, card values)	✗
Outcome Determination	✓ (Win/loss/push)	✗
Bankroll Tracking	✓ (Starting $1000, modified each round)	✓ (Stored as score)
Raw Statistics	✓ (Basic counting)	✗
Score Aggregation	✗	✓ (Rules evaluation)
Statistical Calculations	✗	✓ (Hands, wins, losses, etc.)
Win Rate Calculation	✗	✓ (Wins / hands)
History Tracking	✗	✓ (Score changes over time)
Final Ranking	✗	✓ (Based on bankroll total)

Score Aggregation Rules

The leaderboard uses these rules to process scores:

Request-Response Flow

For each player's turn, the following data flow occurs:

Client Side:

Determine outcome (win/loss/push)

Update local bankroll

Send score update to server with outcome metadata

Server Side (LeaderboardService):

Receive score update

Load existing entry (if any)

Merge existing and new metadata

Pass to ExpressionService for calculation

Server Side (ExpressionService):

Apply main score rule (use new score)

Calculate all custom fields

Return results to LeaderboardService

Server Side (LeaderboardService):

Store updated score and metadata

Add to history if enabled

Return updated entry to client

Step-by-Step Example

Let's follow Alice's first three rounds to see how the system works:

Round 1

Client: Alice beats dealer with 21 vs 17

Local bankroll updated:

1000 \to

1050

Send score update with outcome: "win", hasBlackjack: false

Server:

No previous entry exists, so initialize counters

Apply score rule: set score to $1050

Calculate fields:

hands = 1 (first hand)

wins = 1 (first win)

winRate = 1.0 (1 win ÷ 1 hand)

Round 2

Client: Alice wins again with 21 vs 17

Local bankroll updated:

1050 \to

1100

Send score update with outcome: "win", hasBlackjack: false

Server:

Get existing entry with current metadata

Apply score rule: set score to $1100

Calculate fields:

hands = 2 (1 + 1)

wins = 2 (1 + 1)

winRate = 1.0 (2 wins ÷ 2 hands)

Round 3

Client: Alice ties dealer with 19 vs 19

Local bankroll unchanged: $1100

Send score update with outcome: "push", hasBlackjack: false

Server:

Get existing entry with current metadata

Apply score rule: score remains $1100

Calculate fields:

hands = 3 (2 + 1)

wins = 2 (unchanged from 2)

pushes = 1 (0 + 1)

winRate = 0.67 (2 wins ÷ 3 hands)

Formula Breakdown

Each statistic is calculated using expressions that:

Check if a previous value exists

Process conditionally based on outcome

Increment the appropriate counter

For example, the wins calculation:

context.mergedMetadata.outcome === 'win' ? 
  (context.mergedMetadata.wins ? context.mergedMetadata.wins + 1 : 1) : 
  (context.mergedMetadata.wins || 0)

This breaks down to:

IF outcome is 'win'

THEN IF we already have a wins count

THEN increment it

ELSE set it to 1

ELSE keep the existing wins count (or 0 if none)

Advantages of Server-Side Calculation

This approach offers several benefits:

Single Source of Truth: Statistics calculated in one place

Consistency: Rules applied uniformly across all entries

Reduced Client Complexity: Clients only need to send raw data

Cheat Prevention: Clients can't manipulate statistics directly

Extended Analytics: Complex metrics like winRate automatically calculated

History Tracking: Score and statistic changes preserved over time

Overview

EGP Leaderboard Service v3.0#

Features#

Implementation#

API#

Examples#

Custom Display IDs#

Key Features#

Example Usage#

Benefits#

Extensible Metadata System#

Key Features#

Implementation#

Blackjack Leaderboard Aggregator: A Case Study#

Overview#

Game Rules#

Implementation Flow#

1. Setup Phase#

2. Gameplay Phase#

3. Verification Phase#

Client vs. Server Responsibilities#

Score Aggregation Rules#

Request-Response Flow#

Step-by-Step Example#

Round 1#

Round 2#

Round 3#

Formula Breakdown#

Advantages of Server-Side Calculation#

EGP Leaderboard Service v3.0

Features

Implementation

API

Examples

Custom Display IDs

Key Features

Example Usage

Benefits

Extensible Metadata System

Key Features

Implementation

Blackjack Leaderboard Aggregator: A Case Study

Overview

Game Rules

Implementation Flow

1. Setup Phase

2. Gameplay Phase

3. Verification Phase

Client vs. Server Responsibilities

Score Aggregation Rules

Request-Response Flow

Step-by-Step Example

Round 1

Round 2

Round 3

Formula Breakdown

Advantages of Server-Side Calculation