GemShell

Appearance

Steam Leaderboards ​

Global and friend leaderboards.

Methods ​

findLeaderboard(name) ​

Find a leaderboard by name.

javascript
const board = await steam.findLeaderboard('HighScores');

Returns: Leaderboard handle or null

uploadLeaderboardScore(board, score, method?) ​

Upload a score.

javascript
const board = await steam.findLeaderboard('HighScores');
if (board) {
  await steam.uploadLeaderboardScore(board, 12345);
}

Parameters:

  • board - Leaderboard handle
  • score - Score value (integer)
  • method - 'KeepBest' (default) or 'ForceUpdate'

downloadLeaderboardEntries(board, type, start, end) ​

Download leaderboard entries.

javascript
const board = await steam.findLeaderboard('HighScores');
const entries = await steam.downloadLeaderboardEntries(board, 'Global', 1, 10);

Types:

  • 'Global' - Top scores globally
  • 'Friends' - Friends only
  • 'AroundUser' - Scores around current user

Examples ​

Submit High Score ​

javascript
async function submitScore(score) {
  const board = await steam.findLeaderboard('HighScores');
  if (!board) {
    console.warn('Leaderboard not found');
    return false;
  }
  
  return await steam.uploadLeaderboardScore(board, Math.floor(score));
}

Show Top 10 ​

javascript
async function getTopScores() {
  const board = await steam.findLeaderboard('HighScores');
  if (!board) return [];
  
  const entries = await steam.downloadLeaderboardEntries(board, 'Global', 1, 10);
  return entries.map(e => ({
    rank: e.rank,
    name: e.name,
    score: e.score
  }));
}

Friend Leaderboard ​

javascript
async function getFriendScores() {
  const board = await steam.findLeaderboard('HighScores');
  if (!board) return [];
  
  const entries = await steam.downloadLeaderboardEntries(board, 'Friends', 1, 100);
  return entries;
}

Player Rank ​

javascript
async function getPlayerRank() {
  const board = await steam.findLeaderboard('HighScores');
  if (!board) return null;
  
  const entries = await steam.downloadLeaderboardEntries(board, 'AroundUser', -1, 1);
  if (entries.length > 0) {
    return entries.find(e => e.isCurrentUser);
  }
  return null;
}

Multiple Leaderboards ​

javascript
const LEADERBOARDS = {
  highScore: 'HighScores',
  fastestTime: 'SpeedRun',
  totalKills: 'KillCount'
};

async function submitAllScores(stats) {
  for (const [key, name] of Object.entries(LEADERBOARDS)) {
    const board = await steam.findLeaderboard(name);
    if (board && stats[key]) {
      await steam.uploadLeaderboardScore(board, stats[key]);
    }
  }
}

Steamworks Setup ​

Create leaderboards in Steamworks:

  1. Go to Steamworks Partner
  2. Select your app
  3. Navigate to Stats & Achievements > Leaderboards
  4. Add leaderboard with:
    • Name (API name)
    • Display name
    • Sort method (Ascending/Descending)
    • Display type (Numeric/Time/etc.)
  5. Publish changes