CMSC 22000 Final report

Quarter: Spring 2025

Feature: Leaderboards

Design and Implementation

Leaderboard Base Models:

The design of the models was based mainly on the user stories that we had come up with. The models that we decided to design and implement were Leaderboard, LeaderboardEntry, Metric, MetricScore, and Region. A LeaderboardEntry is a singular entry on a Leaderboard; the entry references a specific user and is also connected to a Leaderboard and MetricScore. The Leaderboard houses all of the LeaderboardEntries and is connected to a game. There can be multiple Metrics defined for a game, and each Metric will have a MetricScore that tracks how well the user is doing along the associated Metric. The Region model is basically a location region that was built for region-based filtering. There are dependencies to other models found in the Chigame code base; the UserProfile model from the users sub-app is referenced, and the Game and Match models from the games sub-app.

Privacy Setting Models / Views / Forms / Templates:

The design of this feature was based on the user story where someone wants to opt out entirely from a leaderboard or where they want to stay on the leaderboard but want to remain anonymous. In terms of models, there is only one new model, LeaderboardPrivacySetting. This tracks the opt-out and anonymous status associated with a user, leaderboard, and game. Obviously, it depends on the UserProfile model from the users subapp, and it depends on the Game model from the games subapp. This model also includes a method that gets a specific user’s setting where the associated game and leaderboard are optionally provided. This operates in a specific hierarchy from highest to lowest priority: Specific leaderboard setting -> Game-level setting -> Global setting. Basically, it looks for a leaderboard-specific setting, then a game-wide setting, then a setting for the entire site.
There is a form associated with the views to alter and set settings. Basically it allows the user to click a checkbox for the setting that they want to set, opt-out or anonymous. There are 3 new views for this feature: one for listing all settings, one for managing a setting, and one for deleting the setting. The “manage” view basically allows one to either set a new setting or alter an existing one. Found in the frontend, form, and model are a few protections for basically forcing the user to either opt-out or anonymous; it does not make any sense for the user to be both opted out and anonymous for the same leaderboard.

API IntegrationL

In collaboration with the API team, we began implementing the leaderboards API. Two endpoints were introduced in Django REST Framework: POST /api/games/{game_id}/scores/ stores a player’s MetricScore and updates the corresponding LeaderboardEntry, while GET /api/games/{game_id}/leaderboard/ returns the leaderboard for a game, ordered by its default metric. Both routes build on the existing Game, Match, and UserProfile models and leverage the new leaderboard models (Leaderboard, LeaderboardEntry, Metric, MetricScore).

Data Visualizations:

The data visualizations so far are designed as horizontal bar charts. There is a different bar chart for each scoring metric. There are also bar charts for each scoring metric for each game. Currently, the scoring metrics and games for which there are bar chart visualizations are based on the fixture data (scoring metrics: points earned, minutes played, games won; games: chess, checkers, backgammon). The structure of the bar charts implementation is by different views for each game and scoring metric. Within views.py, there is a separate function for displaying the bar charts for each scoring metric. The bar chart visualizations were implemented in a single bar chart HTML file using the chart.js library. This HTML file also implements the tiers, which were added for each type of scoring metric, with corresponding badges in the form of emojis. These badges are displayed alongside the players’ names as labels on the bar charts.

Landing Page View:

We created a view, leaderboards_landing, that loads the landing page (roughly laid out according to our Wireframes). In Chigame home (base.html), we added ‘Leaderboards’ to the nav bar, and it loads the landing page. The landing page shows an entry for each game, and the corresponding leader and leader region, that when clicked, redirects the user to the leaderboard for that game and metric (more on metric below). There are dropdowns for “Default view metric” (DVM) and “Anonymity”. The DVM dropdown will control which metric is used to rank the players for the selected game. The three DVMs that we implemented are “Points”, “Games Won”, and “Time Played”, as we felt that these are the only three metrics that could reasonably used to rank players across any game (assuming someone creates a standardized “Points” metric like ExP), whereas metrics like “Goals” or “Captures” are game specific, and would thus be implemented by the game devs (according to an API that the leaderboards team could help create). Note that we were unable to merge a small number of changes that are required for the DVM dropdown to work. To make it work, you MUST modify leaderboards/views.py according to PR 1578 (7 lines of code). The second dropdown, “Anonymity”, will be selectable when you apply the changes above, but it should be removed nonetheless because privacy settings eventually got implemented at leaderboards/privacy (our miscommunication). We also considered implementing a feature to show the rank and username of the logged in player in the landing page (when they are logged in) but never got around to it. The final note about our landing page is that we applied some light CSS styling, but it was somewhat last minute and can definitely be improved upon (and be made more in line with the rest of the website).

Filtering:

The filtering functionality for leaderboards was implemented to enhance the user experience by allowing customization and region-specific views. Key enhancements include filtering leaderboard entries based on regions, where users can specify a region parameter to view rankings relevant to a specific geographic area. Additionally, the filtering logic incorporates tier-based categorization of scores, providing visual representations like badges and tier names for metrics such as “Points,” “Games Won,” and “Time Played.” This not only adds an interactive visual appeal but also helps users understand their standings effectively.

Next Steps

Specific tasks:

Apply modifications to leaderboards/views.py from PR 1578 This should be task #1. Per the Landing Page View section in Design and Implementation above, these small changes are required to make the user able to load a game leaderboard ranked by different metrics (as opposed to being stuck on “Points”).

Connect the /leaderboards/privacy page to the landing page Add a button that links to the privacy settings (and a back button)

Open-ended tasks:

Connect games to leaderboards Currently, our leaderboards operate on our fixture data. Make it so that our leaderboards pull real data from games/matches and displays that. You may want to start with one of the Default View Metrics, such as “Games Won” or “Time Played” (since “Points” will require the implementation of a standardized “Points” metric). In conjunction with “Implement leaderboards from dev perspective” task below, implement custom metrics that users who play specific games can rank those games’ leaderboards by As you implement more metrics, you will have to consider “aggregation” – the ability for a user to rank by avg., max, or sum, for example (since e.g. the Chess -> avg. Time Played leaderboard is different from the Chess -> total Time Played). Also note that not all metrics can be aggregated all ways. Furthermore, many games will not be rankable by different metrics. As you add more functionality, you will have to handle more challenges that we thought about extensively (see both Wiki’s on User Stories) but never implemented.

Implement settings in leaderboards

Currently, the privacy settings we implemented at leaderboards/privacy do not propagate through the leaderboards (i.e. they don’t do anything). Connect the settings page to the leaderboards such that fully anonymous users have anonymous scores and names (to other uses) and name-anonymous users have anonymous names (to other uses), or implement the settings differently (e.g. only one anonymity option) and connect them.

Frontend development

Our templates are pretty barebones and basic. We applied moderate styling to the leaderboard and landing page templates to make them visually clear, but this styling can be improved upon and made more in line with the rest of the site. The styling for the visualizations is more visually appealing but also could be made more similar to other features of Chigame. For leaderboard privacy settings it also makes sense to improve upon the frontend template. Right now, the template for listing all of the settings that the user has set, at /leaderboards/privacy, is too visually crowded.

Implement leaderboards from dev perspective

We had ideas for this but never got around to implementing it – Reference our Wikipage on User Stories from Developer Perspective. We believe that fundamental leaderboard functionality for game developers would include: 1. Ability to create or use custom metrics, 2. Ability to seamlessly collect player data according to that metric, at the end of or during a game, and 3. Ability to choose different aggregations of their custom metric (e.g. Max, Avg.) that can be viewed on the leaderboards.

Implement group leaderboards

We had ideas about custom/group-based leaderboards (which you will see on our landing page Wireframes) but didn’t implement them. Our iteration of the User team has now created some sort of group feature, so you can work with that to create leaderboards that only rank players in a certain group.

Implement filtering

We considered allowing users to filter their leaderboards by region (e.g. NAM, or US). Instead, we implemented a region field in the global leaderboard. However, you can implement a filter that will only rank players in the filtered region (or any other filter you think is relevant). Filtering would be more significant as the player base grows, but it may not be necessary at all depending how you feel about the purpose of leaderboards.

Collaborations with User team

As the User Profile page gets fleshed out, consider linking ranked players in the leaderboards to their User Profile (so when you click on a ranked player in the leaderboard, you see their profile, and can go back). Additionally, a players leaderboard status might appear in their User Profile

Write more tests

Write tests for all the views, especially filtering and privacy settings.

Create more data visualizations

For the data visualizations, future teams could change how the tiers are displayed by using special images for the badges rather than the emojis that are being used currently, or by changing the values corresponding to each tier. The implementation of the tiers could also be modified so that the values of the badges are more easily changeable by making it so that the values that correspond to each tier can be more easily inputted. Additional visualizations can be added that graph historical leaderboard positions as well. The styling of the bar chart pages could also be modified to make colors, layout, etc. more visually pleasing. In addition, our fixtures data which our current bar charts are based off only includes data for three players. Future teams could experiment with the layout of the bar charts to display more players.