Leaderboards API (BETA)

Competitive leaderboards with three security levels. Choose based on your game's requirements.

---

Setup

Leaderboard behavior is driven by your project's config.json file. Add a leaderboard key to enable and configure leaderboards:

my-game/
├── config.json                      ← add "leaderboard" key here
├── src/
├── dist/
├── game.config.json                 ← game ID + build settings only (separate file)
└── package.json

{
  "leaderboard": {
    "requiresToken": false
  }
}

This is the same config.json used for other server config (rooms, simulation, etc.). It is uploaded with your game when you rundot deploy. The server reads it to determine security mode, score bounds, time periods, and anti-cheat rules. If you omit the leaderboard key entirely, leaderboards still work with sensible defaults (simple mode, no tokens, alltime + daily periods).

game.config.json is a separate file for local CLI metadata (gameId, relativePathToDistFolder). Leaderboard config does not go there.

---

🟢 Simple Mode (Default - Casual Games)

Submit scores directly without tokens:

// One call - no token needed!
const result = await RundotGameAPI.leaderboard.submitScore({
  score: 1500,
  duration: 120,
  metadata: {
    levelCompleted: 10,
    powerUpsUsed: 3
  }
})

console.log(`Your rank: ${result.rank}`)

Configuration:

{
  "leaderboard": {
    "requiresToken": false
  }
}

Or just rely on defaults - server auto-resolves mode/period from config!

Security provided:

• ✅ Score/duration bounds validation

• ✅ Rate limiting (60 second cooldown per player)

• ✅ Trust scores & shadow banning for repeat offenders

• ❌ No session replay protection

• ❌ No tamper protection

Best for: Simple integration

---

🟡 Token Mode (Competitive Games)

Add session validation for replay protection:

// Step 1: Create score token
const scoreToken = await RundotGameAPI.leaderboard.createScoreToken()
// Returns: { token, startTime, expiresAt, mode }

// Step 2: Play game...

// Step 3: Submit with token
const result = await RundotGameAPI.leaderboard.submitScore({
  token: scoreToken.token,
  score: 1500,
  duration: 120
})

Configuration:

{
  "leaderboard": {
    "requiresToken": true
  }
}

Additional security:

• ✅ All simple mode security

• ✅ Session validation (tokens expire in 1 hour)

• ✅ Replay attack prevention (one-time use)

• ✅ Mode locking (token locks game mode)

• ❌ No tamper protection

Best for: Preventing replay attacks

---

🔴 Score Sealing Mode (High-Stakes Games)

Add cryptographic tamper protection:

// Step 1: Create score token (sealing data included automatically if enabled)
const scoreToken = await RundotGameAPI.leaderboard.createScoreToken()
// Returns: { token, sealingNonce, sealingSecret, ... }

// Step 2: Play game...

// Step 3: Submit score - SDK auto-computes hash internally!
const result = await RundotGameAPI.leaderboard.submitScore({
  token: scoreToken.token,
  score: 1500,
  duration: 120
})

Configuration:

{
  "leaderboard": {
    "requiresToken": true,
    "enableScoreSealing": true,
    "scoreSealingSecret": "your-secret-key-change-in-production"
  }
}

Note: Hash computation is handled internally by the SDK using Web Crypto API (HMAC-SHA256). Games never need to implement cryptographic hashing manually. The hash always includes: score, duration, and token.

Maximum security:

• ✅ All token mode security

• ✅ Tamper-proof scores (HMAC-SHA256 verification)

• ✅ Client-side cheat detection

• ✅ Automatic hash computation (no crypto code needed in games)

Best for: Reduced hacking

---

Score Ordering

By default, leaderboards rank higher scores first (best for points-based games). For time trials, golf, or any game where lower is better, set scoreOrder to "lowest":

{
  "leaderboard": {
    "scoreOrder": "lowest"
  }
}

Value	Ranking	Example use cases
"highest" (default)	Higher scores rank better	Points, combos, distance
"lowest"	Lower scores rank better	Speed runs, time trials, golf

This is purely a server-side config option — the SDK calls (submitScore, getPagedScores, etc.) work identically regardless of ordering.

---

Query Methods (Same for All Modes)

All query methods work identically regardless of security mode:

// Get paginated scores
const pagedScores = await RundotGameAPI.leaderboard.getPagedScores({
  limit: 50,
  cursor: nextCursor
})

// Get podium + player context
const podiumScores = await RundotGameAPI.leaderboard.getPodiumScores({
  topCount: 3,
  contextAhead: 4,
  contextBehind: 2
})

// Get my rank
const rank = await RundotGameAPI.leaderboard.getMyRank()

Note: Mode and period are automatically resolved from your config. For games with single mode/period, no need to specify them!

---

Advanced: Multiple Modes or Periods

For games with multiple leaderboards:

Config with multiple modes:

{
  "leaderboard": {
    "modes": {
      "casual": { "displayName": "Casual" },
      "competitive": { "displayName": "Competitive" }
    }
  }
}

Explicitly specify mode in submissions/queries:

// Submit to specific mode
await RundotGameAPI.leaderboard.submitScore({
  score: 1500,
  duration: 120,
  mode: 'competitive'  // Override default
})

// Query specific mode
const scores = await RundotGameAPI.leaderboard.getPodiumScores({
  mode: 'competitive',
  topCount: 10
})

Same pattern for periods:

// Query specific time period
const dailyScores = await RundotGameAPI.leaderboard.getPagedScores({
  period: 'daily',
  limit: 50
})

---

Configuration Reference

Minimal Config (Casual Games):

{
  "leaderboard": {
    "requiresToken": false
  }
}

Uses defaults:

• Mode: "default"

• Periods: "alltime" and "daily"

• Score ordering: highest first

• Rate limiting: 60s between submissions

---

Full Config (Advanced Games):

{
  "leaderboard": {
    // Security (progressive levels)
    "requiresToken": false,           // Simple mode (default)
    "enableScoreSealing": false,      // Requires requiresToken=true
    "scoreSealingSecret": "secret",   // Required if enableScoreSealing=true
    
    // Score ordering
    "scoreOrder": "highest",          // "highest" (default) or "lowest" (for time trials, golf, etc.)
    
    // Score bounds
    "minScore": 0,
    "maxScore": 999999999,
    "minDurationSec": 10,
    "maxDurationSec": 3600,
    
    // Game modes (optional - omit for single default mode)
    "modes": {
      "default": { "displayName": "Normal" },
      "hard": { "displayName": "Hard Mode" }
    },
    
    // Time periods (optional - omit for alltime + daily default)
    "periods": {
      "alltime": { "displayName": "All Time", "type": "alltime" },
      "daily": { "displayName": "Daily", "type": "daily" }
    },
    
    // Anti-cheat
    "antiCheat": {
      "enableRateLimit": true,
      "minTimeBetweenSubmissionsSec": 60,
      "trustScoreDecayPerFlag": 10,
      "shadowBanThreshold": 20,
      "enableZScoreDetection": false,
      "zScoreThreshold": 3
    },
    
    // Display
    "displaySettings": {
      "maxEntriesPerPage": 50
    },
    
    // Seed data (optional)
    "seedEntries": {
      "default": {
        "alltime": [
          {
            "score": 18500,
            "username": "ProPlayer",
            "duration": 180
          }
        ]
      }
    }
  }
}

Smart Defaults:

• If you configure only ONE mode/period, it's auto-selected (no need to specify in SDK calls)

• If you configure MULTIPLE modes: defaults to "default" mode if present, otherwise first configured

• If you configure MULTIPLE periods: defaults to "alltime" > "daily" > others (prefers permanent leaderboards)

---

Best Practices

• Configure score bounds, durations, and anti-cheat settings in your game.config.json.

• Use token or score-sealing modes for competitive or high-value rewards.

• Log submissions and responses for customer support audits.

• Treat this API as BETA; monitor release notes for schema or validation changes.

• Seed leaderboards with NPC entries via seedEntries to avoid empty boards on launch.

• UTC-based daily/weekly/monthly periods ensure global fairness; show countdowns using the Time API.

---

Features

• Three Security Levels: Simple, Token, Sealed - choose based on game stakes

• Score Ordering: Highest-first (default) or lowest-first for time trials and golf

• Multiple Modes: Support different game modes (classic, hard, etc.)

• Time Periods: Daily, weekly, monthly, and all-time leaderboards

• Anti-Cheat: Rate limiting, trust scores, shadow banning, optional session validation & sealing

• Seed Entries: Pre-populate leaderboards with NPC scores

• Pagination: Cursor-based pagination for large leaderboards

• UTC-Based Periods: All players globally compete in same daily/weekly/monthly periods