terminalCode Example

Leaderboards API

calendar_today May 3, 2026 schedule ~1 min read person patrickjr verified 50

Implement leaderboards using s&box Services API.

Submitting Scores

CSHARP
using Sandbox.Services;

// Submit a score
await Leaderboards.Submit("high_score", playerScore);

// Submit with additional data
await Leaderboards.Submit("level_times", timeSeconds, new Dictionary<string, string>
{
    ["level"] = currentLevel,
    ["character"] = playerClass
});

Reading Leaderboards

CSHARP
// Get top 10 players
var leaderboard = await Leaderboards.Get("high_score", 10);

foreach (var entry in leaderboard.Entries)
{
    Log.Info($"{entry.Rank}. {entry.DisplayName}: {entry.Score}");
}

// Get around a specific rank
var aroundMe = await Leaderboards.GetAround("high_score", myRank, 5);

Leaderboard Entry Properties

PropertyDescription
RankPosition on leaderboard
DisplayNamePlayer name
ScoreThe score value
SteamIdPlayer's Steam ID
TimestampWhen score was submitted

Web API Access

Query leaderboards from external services:

CODE
GET https://services.facepunch.com/sbox/leaderboard/v1/{appid}/{leaderboard_name}

Response:

JSON
{
  "entries": [
    {
      "rank": 1,
      "steam_id": 76561197991348132,
      "score": 999999,
      "display_name": "ProGamer"
    }
  ]
}

Real-time Updates

CSHARP
// Subscribe to leaderboard changes
Leaderboards.OnUpdated += (leaderboard) =>
{
    if (leaderboard.Name == "high_score")
    {
        UpdateUI(leaderboard.Entries);
    }
};

Setup Requirements

  1. Define leaderboards in Project SettingsServices
  2. Set score type (integer, float, time)
  3. Configure sort order (higher/lower is better)
Was this helpful?