Leaderboards

RetiPie enables leaderboard UI automatically when your game declares leaderboard support through the SDK. You don't configure this during upload; your game code is the source of truth.

Declare support

Call retipie.game.configure() once when your game starts.

retipie.game.configure({
  leaderboards: {
    default: { order: 'desc', unit: 'points', precision: 0 },
  },
});

During upload analysis, RetiPie opens your game in the same sandbox players use and listens for this declaration. If it is present, the current release gets scoring.status = 'active' and the feed shows the leaderboard button. A game that submits a score while players are playing it is also marked active, so a missing declaration doesn't stop scores from counting.

Submit a score

Submit once per completed run.

function gameOver() {
  retipie.leaderboards.submitScore(Math.floor(score));
}

V1 leaderboards are all-time high score boards. Higher is better, and the unit is points. Scores must be greater than zero and at most 1,000,000,000.

Release updates

If version 1 declares a leaderboard and version 2 removes it, RetiPie keeps old scores but changes the current game capability to legacy. The feed leaderboard button is hidden until the current release declares leaderboard support again.

Dashboard states:

• active — current release declares or emits valid score support
• legacy — an older release had a leaderboard, but the current release does not
• disabled — creator or admin intentionally turned the leaderboard off

Analytics is separate

Use analytics for creator telemetry, not score state.

retipie.analytics.trackEvent('level_failed', {
  level: 4,
  reason: 'spikes',
});

Scores create user-facing ranking data, so they belong to retipie.leaderboards, not retipie.analytics. Custom analytics events aren't reported yet; see Analytics.