Final Report 2025 ‐ Game Management - uchicago-cs/chigame GitHub Wiki

CMSC 22000 Final report

Quarter: Spring 2025

Feature: Game Management

Design and Implementation

Our primary contributions this quarter were to several Game Management Tools, focusing on enabling users to better manage and track their games through Game Lists, a Game Queue, Game History, Game Statistics, Create and Join Match functionality, Recommendation system, Embedded game infrastructure, and many Front-end improvements.

I. Game Lists

This feature allows users to create personalized collections of games, such as a "Favorites" list or custom-named lists.

  • Core Model (GameList): We introduced the GameList model, which links a user (created_by) to a collection of games (ManyToManyField) and includes fields like name and description.

    # src/chigame/games/models.py
class GameList(models.Model):
    name = models.CharField(max_length=255)
    created_by = models.ForeignKey(User, ...)
    games = models.ManyToManyField(Game, ...)
    # ... other fields and methods ...

  • "Favorites" by Default: A key feature is that a "Favorites" GameList list is automatically created when signing up as a user. This was implemented using a Django signal (post_save on the User model) in chigame.users.signals.

  • Functionality & UI:

    • Implemented views (add_to_favorites, remove_from_favorites, add_to_gamelist, remove_from_gamelist in chigame/games/views.py) and URL routes to manage games within these lists.
    • Integrated buttons on the game_detail.html page for adding/removing games from "Favorites" and, later, a dropdown for managing games across any user-created list.
    • Developed FavoriteListView and GameListDetailView to display these lists, enhancing the gamelist_detail.html page with a card layout for better visual presentation.
    • Improved accessibility by adding a "My Game Lists" dropdown on the main game_grid.html and linking lists from the user's profile page (userprofile_detail.html).

II. Game Queue

The Game Queue allows users to create an ordered list of games they intend to play.

  • Core Models (GameQueue, GameQueueEntry): We designed and implemented the GameQueue model (a OneToOneField to the User) and the GameQueueEntry model (linking a GameQueue to a Game with a position).

    # src/chigame/games/models.py
class GameQueue(models.Model):
    user = models.OneToOneField(User, ...)
    # ... methods for add, remove, move, duplicate ...

class GameQueueEntry(models.Model):
    queue = models.ForeignKey(GameQueue, ...)
    game = models.ForeignKey(Game, ...)
    position = models.PositiveIntegerField()

  • Queue Management: Added methods to the GameQueue model for add_game, remove_game (with re-ordering), get_next_game, move_game to a new position, and duplicate_game.

  • UI: Implemented QueueListView and the games/queue_list.html template for users to view their queued games and remove items.

III. Game History

For the Game History implementation, we introduced a feature that allows users to view a record of their past games:

  • We created a GameHistory model that tracks details about each game session, including the user who played, the match reference, the date, the result (win, draw, lose, or incomplete), and whether the match was completed.
  • We also populated the history data using fixtures for testing, so we had example matches ready for display (to test them, load game-history-simulation-fixture.json).
  • Subsequently, we designed a Game History page where all past games are listed for each user with the match details. If a user has no game history, then they see a friendly message inviting them to start playing.

The model and UI were built in those files: 'src/chigame/games/models.py', 'src/chigame/games/urls.py', 'src/chigame/games/views.py', 'src/templates/games/game_detail.html', and 'src/templates/games/game_history.html.'

IV. Enhanced Game Statistics

To provide better gameplay insights, we worked on improving the game history feature.

  • Time-Period Filtering & Stats: Enhanced the GameHistoryView (chigame/games/views.py) to allow filtering of a user's game history for a specific game by time periods (e.g., "Last 7 Days," "All Time").
  • The view now calculates and displays statistics like total played, wins, losses, draws, and win rate for the selected period on games/game_history.html.
  • Improved the clarity of result badges in the history table.

These features were integrated into ChiGame by leveraging Django's ORM, views, templates, and signals, and by ensuring they worked with existing User and Game models.

V. Create and Join Match functionality

This component introduces a match creation and joining feature that allows users to create and coordinate matches independent of tournament structures. It provides a work flow for initiating games, inviting players by sharing a join_code and managing match participation:

  • We modified the existing Lobby model by adding invited_members and join_code as attributes. A unique six-character code is generated upon lobby creation inside the model.
  • To create a match, users can go to the game page of their choice and click "Create Match" to start. They are going to be redirected to a match creation form where they select a match date using a calendar picker and select email addresses of invited players. On submission, a lobby is created and the join_code is shown to a match creator, so that they can share it with the invited members.
  • Invited players go to the game page and then click "Join Match" to enter their join code. This page features a six-cell input where each character is automatically capitalized and the cursor advances as the user types. This was designed similarly to familiar join-code UIs seen in multiplayer games like GeoGuessr.

Backend logic:

  • Only invited users can join.
  • Each user can only join once.
  • The lobby becomes locked once all invited users have joined.
  • Clear error/success messages are displayed for invalid codes, already-joined users, full lobbies, and unauthorized access attempts.

VI. Recommendation system

We implemented a recommendation algorithm in the get_recommended_games function within chigame/games/views.py that evaluates games based on five key factors:

pythondef get_recommended_games(game, user=None, limit=5):
    # Uses weighted scoring based on:
    # - Game categories (default 40% weight)
    # - Game mechanics (default 30% weight) 
    # - Game designers/artists (default 15% weight)
    # - Similar complexity ratings (default 10% weight)
    # - Similar playtime (default 5% weight)

The algorithm annotates games with scores for each factor and combines them into a total recommendation score, while applying a penalty for games the user has already played. User Preference Customization

RecommendationPreferences Model: We introduced a new model to store user-specific weights for each recommendation factor:

python# src/chigame/users/models.py
class RecommendationPreferences(models.Model):
    user = models.OneToOneField(User, ...)
    category_weight = models.IntegerField(default=40) 
    mechanics_weight = models.IntegerField(default=30) 
    designers_weight = models.IntegerField(default=15) 
    complexity_weight = models.IntegerField(default=10) 
    playtime_weight = models.IntegerField(default=5)

Dynamic Algorithm Adaptation: The recommendation algorithm dynamically adjusts its weights based on individual user preferences, normalizing the custom weights and applying them to the scoring calculations. User Interface & Experience Preference Management Interface: Created an intuitive settings page (templates/users/recommendation_preferences.html) featuring: Interactive sliders for adjusting each recommendation factor (0-100%) Real-time percentage feedback as users move sliders Clear descriptions explaining what each preference weight controls Responsive design with helpful tooltips

  • Profile Integration: Added seamless access through a "Recommendation Preferences" button in user profiles, making preference management easily discoverable.
  • Visual Recommendation Display: Enhanced the game detail pages to showcase recommended games in an attractive card layout, with the recommendations dynamically updating based on user preferences.
  • Testing & Validation
  • Implemented comprehensive test coverage to ensure:

Preference changes directly impact recommendation rankings

  • Edge cases (all weights at 0%, single factor at 100%) work correctly
  • Algorithm maintains backward compatibility for users without custom preferences
  • UI validation prevents invalid input ranges

The system successfully demonstrates personalization - for example, setting complexity weight to 100% while viewing a simple party game will move complex strategy games like Chess to the bottom of recommendations, confirming that user preferences meaningfully alter the recommendation algorithm.

VII. Embedded game infrastructure

This feature creates a standardized system for integrating external web games directly into the ChiGame platform, allowing users to play games without leaving the site. Core Infrastructure (Game Model Enhancement): We extended the existing Game model by adding a game_url field to store external game URLs, enabling seamless integration of web-based games.

python# src/chigame/games/models.py
class Game(models.Model):
    # ... existing fields ...
    game_url = models.URLField(blank=True, null=True, 
                              help_text="URL for embedded games")

Generic Embedded Game Player: Developed a universal play_embedded_game view that handles any external game URL, with special authentication handling for games requiring JWT tokens (like Wordle integration). python# src/chigame/games/views.py

@login_required
def play_embedded_game(request, pk):
    game = get_object_or_404(Game, pk=pk)
    # Handle JWT token generation for authenticated games
    # Render game in iframe with security considerations

User Interface & Experience:

  • We made a responsive embedded_game.html template featuring iframe-based game rendering with fullscreen support, navigation controls, and consistent site branding
  • Integrated "Play Game" buttons on game detail pages that conditionally appear for games with embedded URLs
  • Implemented security measures including trusted origin validation and cross-frame communication handling
  • Added debugging capabilities and user feedback for development and testing phases

Testing Framework: Built comprehensive testing infrastructure with the test_embedded_games management command that creates multiple test scenarios:

Working embedded games (Wordle with JWT authentication) Generic external games (2048, Tetris) to test URL flexibility Non-embedded games to verify proper error handling Network connectivity testing to validate external game accessibility

VIII. Front-end improvements (game grid and game detail changes)

  • We added basic statistics like the average rating, displayed using a 5-star front-end system on each game card. Users can see a review only if there’s at least one review.

  • Another feature that we also implemented is pop-ups for the game grid, which display additional information about a game such as the number of players, complexity, and description whenever a user hovers over a game card.

  • For user functionality, we also introduced an accessible “Write a Review” page. Previously, this feature was combined with the rules and game descriptions in the same frame, but now users can simply click the “Write a Review” button to open a separate page dedicated to sharing their thoughts on a game.

Next Steps

  1. Full UI for Game List Management: Allow users to create, edit (names/descriptions), and delete their game lists directly through the UI, beyond just managing the games within them.
  2. Interactive Game Queue UI: Enhance the /games/queue/ page with drag-and-drop reordering and easier ways to add games to the queue.
  3. Game List Sharing: Enable users to share their lists with friends or make them public, fostering community interaction.
  4. Centralized User Statistics Dashboard: Create a comprehensive dashboard aggregating play statistics across all games, offering richer visualizations and insights.
  5. Customizable Game Outcomes for Developers: Give game developers the ability to define custom outcome types (e.g., "the score used had when finished game" or "number of puzzles solved") that integrate into the game history and user statistics, enhancing flexibility and accuracy in representing game results which is helpful, for instance, when a game is a single mode.
  6. In-App Code Sharing via Inbox and Search Bar to invite: Allow users to share the join code directly with teammates through Inbox. Improve the match creation form by adding a search bar to allow users to quickly find and invite teammates by username/email instead of scrolling through a long list.