menu_bookDocumentation
Stats Service: Recording and Reading Player Statistics in s&box
Games can record per-player stats using Sandbox.Services.Stats. Stats can be queried individually, per-player, or globally.
Recording Stats
Increment a counter:
CSHARP
public void OnZombieKilled()
{
Sandbox.Services.Stats.Increment( "zombies-killed", 1 );
}Set a value directly:
CSHARP
public void OnGameFinished()
{
Sandbox.Services.Stats.Increment( "wins", 1 );
Sandbox.Services.Stats.SetValue( "win-time", SecondsTaken );
}Stats are batched internally and sent when ready — call these APIs as often as needed.
You can also attach additional data as a Dictionary<string, object> when calling SetValue, which is available when querying leaderboards.
Reading Global Stats
CSHARP
var zombies = Sandbox.Services.Stats.Global.Get( "zombies_killed" );
Log.Info( $"Total: {zombies.Sum} zombies killed by {zombies.Players} players" );Reading Local Player Stats
CSHARP
var zombies = Sandbox.Services.Stats.LocalPlayer.Get( "zombies_killed" );
Log.Info( $"You killed {zombies.Sum} zombies" );Reading Another Player's Stats
CSHARP
var stats = Sandbox.Services.Stats.GetPlayerStats( "facepunch.ss1", 76561197960279927 );
await stats.Refresh();
var zombies = stats.Get( "zombies_killed" );
Log.Info( $"Garry killed {zombies.Sum} zombies" );Stats integrate with Leaderboards (stats aggregated and ordered) and Achievements (stat-based auto-unlock).
Was this helpful?