Creating a Leaderboard for Your Word Prediction Game

Welcome back! In the last lesson, you learned how to make your word prediction game smarter by scoring guesses based on how close their meaning is to the correct answer. Now, let’s take your game to the next level by adding a leaderboard.

A leaderboard is a simple but powerful feature. It lets players see how their scores compare to others, which makes the game more exciting and competitive. In this lesson, you’ll learn how to store player scores and display the top results for each day. By the end, you’ll have the foundation for a daily leaderboard that updates as people play.

Before we dive in, let’s quickly remind ourselves what a model is in Flask. In web development, a model is a way to represent and store data in your application. In Flask, we often use a library called SQLAlchemy to help us manage this data.

A model is like a blueprint for a table in a database. For example, if you want to keep track of high scores, you need a model that describes what information you want to save for each score — such as the player’s name, their score, and the date.

You might remember seeing something like this before:

from flask_sqlalchemy import SQLAlchemy

db = SQLAlchemy()

class ExampleModel(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String(80), nullable=False)

Here, ExampleModel is a model with two fields: id and name. Each time you add a new entry, it creates a new row in the database.

Now, let’s build a model for our leaderboard. We want to store each player’s name, their score, and the date they played. Let’s start step by step.

First, we need to import the right tools and set up our database connection:

from flask_sqlalchemy import SQLAlchemy
from datetime import date

db = SQLAlchemy()

Next, let’s define our HighScore model:

class HighScore(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String(80), nullable=False)
    score = db.Column(db.Integer, nullable=False)
    date = db.Column(db.Date, default=date.today, nullable=False)

Let’s break down what each part does:

• id: This is a unique number for each score entry. It helps us keep track of each row.
• name: This stores the player’s name. It’s a string and cannot be empty.
• score: This is the player’s score. It must be a number and cannot be empty.
• date: This records the date the score was achieved. By default, it uses today’s date.

To make it easy to display scores, let’s add a method to turn a score into a dictionary:

def to_dict(self):
    return {
        "id": self.id,
        "name": self.name,
        "score": self.score,
        "date": self.date.isoformat()
    }

This method helps us convert a score entry into a format that’s easy to use in our app or send to the frontend.

Now that we have a model, let’s see how to save a new score and fetch the top scores for a given day.

To save a score, we need a function that takes the player’s name, their score, and the date. Here’s how you can do it:

from datetime import datetime, date

def submit_score(name: str, score: int, date_str: str = None):
    score_date = datetime.strptime(date_str, "%Y-%m-%d").date() if date_str else date.today()
    entry = HighScore(name=name, score=score, date=score_date)
    db.session.add(entry)
    db.session.commit()

Let’s break this down:

• name and score are the player’s name and score.
• date_str is an optional string like "2025-06-01". If it’s not given, we use today’s date.
• We create a new HighScore entry with this data.
• db.session.add(entry) prepares the entry to be saved.
• db.session.commit() actually saves it to the database.

To show the leaderboard for a specific day, we need to get all scores for that date and sort them from highest to lowest. Here’s how:

def get_leaderboard(date_str: str = None):
    score_date = datetime.strptime(date_str, "%Y-%m-%d").date() if date_str else date.today()
    scores = (HighScore.query
              .filter_by(date=score_date)
              .order_by(HighScore.score.desc())
              .all())
    return [s.to_dict() for s in scores]

Here’s what’s happening:

• We figure out which date to use (either the one given or today).
• We ask the database for all HighScore entries with that date.
• We sort them so the highest scores come first.
• We turn each score into a dictionary for easy use.

Example Output

Suppose we have three scores for today:

If we call get_leaderboard(), we’ll get:

[
    {"id": 1, "name": "Alice", "score": 90, "date": "2025-06-01"},
    {"id": 3, "name": "Carol", "score": 85, "date": "2025-06-01"},
    {"id": 2, "name": "Bob", "score": 75, "date": "2025-06-01"}
]

This list is ready to be shown on your game’s leaderboard!

In this lesson, you learned how to create a leaderboard for your word prediction game. You built a HighScore model to store player names, scores, and dates. You also wrote functions to save new scores and fetch the top scores for any day.

These are the building blocks for a daily leaderboard that updates as people play. Up next, you’ll get to practice these skills by working with the leaderboard code yourself. This hands-on practice will help you get comfortable with saving and displaying scores in your own game. Good luck!