How to Build Game Leaderboards

Design the Database Schema

A leaderboard needs a scores table with the right columns and indexes. The essential columns are: id (auto-incrementing primary key), player_id (the authenticated user's unique ID), display_name (the name shown on the leaderboard), score (the numeric value being ranked), game_mode (if the game has multiple modes or levels), created_at (timestamp of the score submission), and metadata (optional JSON field for additional context like level reached, time elapsed, or items collected).

The critical index is on score DESC for the global leaderboard query. A composite index on (game_mode, score DESC) speeds up per-mode leaderboards. If you offer daily or weekly leaderboards, add an index on (created_at, score DESC) for time-filtered queries.

The schema decision between "one row per submission" and "one row per player" affects both storage and query patterns. One row per submission stores every score the player ever achieves, enabling statistics, progress tracking, and personal best history. One row per player stores only their highest score, keeping the table compact and leaderboard queries fast. Most games use the one-row-per-player approach with an upsert on submission: insert a new row for new players, update the existing row only if the new score is higher.

PostgreSQL handles leaderboard queries efficiently for tables up to several million rows. The query SELECT display_name, score, created_at FROM scores WHERE game_mode = 'normal' ORDER BY score DESC LIMIT 100 returns the global top 100 in under 1 millisecond with a proper index. For leaderboards with tens of millions of entries, Redis sorted sets (ZADD, ZREVRANGE, ZREVRANK) provide O(log N) operations that scale to billions of entries.

Build the Score Submission API

The submission endpoint accepts a POST request with the player's score and an authentication token. The server validates the token (via JWT verification or session lookup), extracts the player ID, and upserts the score into the database. The response confirms the submission and returns the player's new rank.

The endpoint should enforce rate limiting to prevent abuse: one submission per second per player is reasonable for most games. It should validate the score value (reject negative numbers, reject values above a defined maximum, reject non-numeric input). It should also check that the game_mode parameter matches a valid mode defined by the game.

For games with personal best tracking, the upsert logic only updates the database row if the submitted score is higher than the existing record. This prevents a player from accidentally lowering their high score by submitting a weaker result. The SQL pattern is: INSERT INTO scores (player_id, score, ...) VALUES ($1, $2, ...) ON CONFLICT (player_id, game_mode) DO UPDATE SET score = GREATEST(scores.score, $2), created_at = NOW(). This atomic operation handles both new players and returning players in a single query.

Including the player's rank in the submission response gives instant feedback. Computing rank is a separate query: SELECT COUNT(*) + 1 FROM scores WHERE game_mode = $1 AND score > $2 tells you how many players have a higher score (plus one for the player's position). For large tables, this count query can be slow. Approximate ranking using Redis ZREVRANK or periodic rank caching trades precision for speed.

Build the Leaderboard Retrieval API

The retrieval endpoint returns a page of leaderboard entries. The basic query returns the top N scores globally. Pagination parameters (offset and limit, or cursor-based pagination) let the client request subsequent pages. A well-designed response includes each entry's rank, display name, score, timestamp, and any metadata (like the level reached).

Useful filters include: time period (all-time, this month, this week, today), game mode (normal, hard, challenge), and scope (global, friends-only, country). Time-filtered leaderboards create recurring competition cycles that re-engage players who have already topped the all-time board. Friends-only leaderboards require the player's friend list, which means the server needs a social graph or integration with an external social platform (Discord, Steam, Google Play Games).

The "around me" query is a player-centric view that shows the player's rank with a few entries above and below. This view motivates players who are not in the top 100 because they can see how close they are to the next rank. Implement it by querying the player's score, then fetching the 5 entries above and 5 entries below that score. The SQL uses a combination of queries: entries with score greater than the player's (ordered ascending, limited to 5) and entries with score less than or equal (ordered descending, limited to 5, offset 1 to skip the player themselves).

Add Anti-Cheat Validation

Client-side web games are inherently vulnerable to score fabrication. The player can open browser dev tools, modify JavaScript variables, intercept network requests, or craft a direct API call with any score value. No client-side protection (obfuscation, encryption, integrity checks) can prevent a determined cheater because the client code is fully accessible and modifiable.

Server-side validation is the only real defense. Heuristic checks catch most casual cheaters without requiring the server to replay the full game session. Common heuristics include: rejecting scores above a theoretical maximum (if the maximum possible score in level 1 is 10,000, reject any submission over 10,000), requiring a minimum play time (if a level takes at minimum 30 seconds to complete, reject scores submitted with a session duration under 30 seconds), and checking score progression (if a player jumps from a score of 500 to 5,000,000 in one session, flag the submission for review).

Session-based validation stores game events on the server. When the player starts a game session, the server creates a session record with a start timestamp. During gameplay, the client sends periodic heartbeat events (every 10-30 seconds) that record the player's state. When the score is submitted, the server verifies that the session duration matches the submission time, that the heartbeats are consistent with the claimed score, and that the session ID has not already been used for a previous submission. This approach makes casual cheating significantly harder without requiring full server-side game simulation.

For competitive games where leaderboard integrity is critical, the gold standard is server-authoritative gameplay: the game logic runs on the server, the client sends inputs, and the server computes the result. This eliminates client-side cheating entirely but requires significant server infrastructure. Most indie web games settle for heuristic validation, which catches 90% of cheaters with minimal server complexity.

Display the Leaderboard in the Game

The client fetches leaderboard data from the API and renders it as a scrollable list. Each entry shows the rank (1, 2, 3...), player name, score, and optionally the timestamp or metadata. Highlight the current player's entry with a different background color or border so they can find themselves quickly. If the player is not in the visible range, show a summary at the bottom ("Your rank: #847, Score: 4,250") with a button to jump to their position.

HTML and CSS handle leaderboard rendering well in web games. A simple ordered list or table with fixed-width columns for rank and score, and a flexible-width column for the player name, produces a clean layout. Use CSS grid or flexbox to align columns. Apply alternating row colors for readability. Limit the initial load to 20-50 entries and add a "Load More" button or infinite scroll for additional pages. This keeps the initial API response small and the DOM manageable.

Real-time leaderboard updates use WebSocket connections or Server-Sent Events to push new entries to the client as they are submitted. This creates an exciting live competition feel during game events or daily challenge periods. For most games, polling the API every 30-60 seconds is simpler and sufficient. The leaderboard data changes infrequently enough that real-time push adds complexity without meaningful benefit unless the game has hundreds of simultaneous players competing on the same board.