🏁 WikiRace

WikiRace is a multiplayer game where participants navigate from a random Wikipedia page to a target Wikipedia page, using only internal links. The project provides a seamless lobby system, real-time game updates, hints using ChatGPT and embeddings, and post-game statistics.

---

🌟 Features

• Lobby System: Create or join lobbies with a unique game code to play with friends.
• Customizable Gameplay: Specify or randomly generate starting and target Wikipedia pages.
• Interactive Hints: Players can request hints using ChatGPT and LLM-powered embeddings.
• Post-Game Stats: View you and your components' performance.

---

🔄 How It Works

1. Lobby:

• Players create or join lobbies.
• The host sets up or randomizes the start and target Wikipedia pages.
• Once ready, the host starts the game, transitioning to the "Game Phase."

2. In-Game:

• Players navigate from the starting page to the target page by clicking internal links.
• The frontend:
  • Polls game status every second to check for updates.
  • Sends API calls to log player paths.

3. Post-Game:

• The game concludes when the first player reaches the target page.
• Players can view stats like total time taken and navigation paths.
• The host can reset the game for a new round.

---

☁️ Using MongoDB Atlas

This project utilizes MongoDB Atlas, a fully-managed cloud database, to handle all backend storage needs. The database is used to persist game data, player details, and game states in real time, ensuring a robust and scalable gaming experience.

1. Game Management

• Create Game: Saves a new game instance in the games collection.
• Join Game: Updates the list of players in an existing game document.
• Start Game: Updates the state of a game to playing, and populates start and target articles.
• Reset Game: Resets game states while retaining players.
• Delete Game: Removes a game when all players leave.

2. Player Management

• Adds or removes players dynamically during gameplay.
• Tracks individual player paths (navigation through Wikipedia links).
• Identifies the winning player when the target page is reached.

🗂️ Example Database Schema

Below are the primary components of the database schema used for storing game and player information:

Game Document Schema

Field	Type	Description
code	string	Unique game code for identifying lobbies.
players	Array	List of players in the game (see Player Schema).
state	string	Current state of the game (waiting, playing, finished).
startArticle	string	The starting Wikipedia article.
targetArticle	string	The target Wikipedia article.
startTime	time	Timestamp indicating when the game started.
endTime	time	Timestamp indicating when the game ended.
expiresAfter	time	Timestamp after which the game data should expire.

Player Subdocument Schema

Field	Type	Description
ID	string	Unique player identifier.
name	string	Display name of the player.
isLeader	boolean	Indicates if the player is the host/leader.
isWinner	boolean	Indicates if the player won the game.
paths	Array	List of Wikipedia articles visited during play.

---

📚 API Documentation

The backend API returns consistent responses with the format below. Errors have non-zero codes:

{
  "code": 0,
  "msg": "OK",
  "data": {
    ...
  }
}

• code: 0 indicates success. Errors will include msg.
• data: Contains response-specific information.

📦 GameObject Structure

The GameObject outlines the structure of the game data.

Field	Type	Required	Description
code	string	Yes	Unique game code generated by the backend.
state	string	Yes	Game state (waiting, playing, or finished).
startArticle	string	No	The starting Wikipedia article (may be empty in the lobby).
targetArticle	string	No	The target Wikipedia article (may be empty in the lobby).
players	List	Yes	List of players in the game.
startTime	time	No	Timestamp when the game starts.
endTime	time	No	Timestamp when the game ends.

---

👤 PlayerObject Structure

The PlayerObject outlines the structure of a player in the game.

Field	Type	Required	Description
id	string	Yes	Unique identifier for the player.
name	string	Yes	Player's chosen display name.
isLeader	boolean	Yes	Indicates if the player is the host.
isWinner	boolean	Yes	Indicates if the player won the game.
paths	List	Yes	List of Wikipedia articles visited.

---

API Endpoints and Usage

1. Create a Game

Method	POST
URI	/api/v1/games/create
Action	Creates a new game (lobby).

Request Parameters:

Parameter	Type	Required	Description
leaderName	string	Yes	Name of the player creating the game.
playerID	string	Yes	Unique player identifier (generated by frontend).

Response:

Field	Type	Description
game	GameObject	Details of the created game.

2. Join a Game

Method	POST
URI	/api/v1/games/join
Action	Join an existing game using a game code.

Request Parameters:

Parameter	Type	Required	Description
playerName	string	Yes	Name of the player joining the game.
playerID	string	Yes	Unique player identifier (generated by frontend).
gameCode	string	Yes	Unique code of the game to join.

Response:

Field	Type	Description
game	GameObject	Details of the joined game.

3. Get Game Info

Method	GET
URI	/api/v1/games/info
Action	Retrieve the current state of the game.

Request Parameters:

Parameter	Type	Required	Description
gameCode	string	Yes	Game code to fetch information.
playerID	string	Yes	Identifies the requesting player.

Response:

Field	Type	Description
game	GameObject	Current state and metadata of the game.

---

⏯️ Gameplay API

1. Start Game

Method	POST
URI	/api/v1/games/start
Action	Start a game with specified start and target articles.

Request Parameters:

Parameter	Type	Required	Description
gameCode	string	Yes	Game code to start the game.
startArticle	string	Yes	The starting Wikipedia page.
targetArticle	string	Yes	The target Wikipedia page.

Response:

Field	Type	Description
game	GameObject	Game details after starting.

2. Add Path

Method	POST
URI	/api/v1/games/addpath
Action	Record a user's navigation through Wikipedia pages.

Request Parameters:

Parameter	Type	Required	Description
gameCode	string	Yes	Game code of the current game.
playerID	string	Yes	ID of the player for tracking.
articleName	string	Yes	Name of the Wikipedia page visited.

Response:

Field	Type	Description
game	GameObject	Updated game data with navigation path.

3. Reset Game

Method	POST
URI	/api/v1/games/reset
Action	Reset a game, returning all players to the lobby. Only the host can reset games.

Request Parameters:

Parameter	Type	Required	Description
gameCode	string	Yes	Game code of the current game.

Response:

Field	Type	Description
game	GameObject	Game state after reset.

4. Leave Game

Method	POST
URI	/api/v1/games/leave
Action	Remove a player from the game (called when a user leaves).

Request Parameters:

Parameter	Type	Required	Description
gameCode	string	Yes	Code of the current game.
playerID	string	Yes	ID of the player leaving.

Response:

Field	Type	Description
game	GameObject	Updated game state without the leaving player.

---

🛠️ Error Handling

The API gracefully handles errors with informative msg fields:

Code	Message	Description
10009	Game not found.	Invalid or expired game code.
10010	Player not found.	Invalid or missing player ID.

---

💻 Step-by-Step Flow

The frontend interacts with the backend through periodic polling and API calls to ensure real-time synchronization of the game state. Here's a step-by-step overview of the process:

1. Lobby Phase:

   • After creating or joining a game, the frontend polls the get game info endpoint every second to monitor and update the game state, any updates (player joining, article changes) will be reflected.
   • If the game state is waiting (players are still in the lobby):
     • Display game details such as the list of players, starting article, and target article.
     • When the host selects or updates the starting or target article, the frontend calls the update game API to save the changes.

2. Game Phase:

   • When the game state changes to playing:
     • The frontend enters the game and continues polling get game info every second to track progress.
     • Each time a player navigates to a new Wikipedia page (by clicking on a link), the frontend calls the add path API to log the player’s actions.

3. Post-Game (Stats Phase):

   • Once the game state changes to finished, the frontend transitions to the stats page.
   • On the stats page, the frontend calls get game info to display the winner and the paths taken by all players.
   • Polling continues every second to check if the host resets the game.

4. Reset Phase:

   • The host can click "Reset Game" to bring all players back to the lobby. When this happens, the game state changes back to waiting, allowing players to prepare for the next round.

5. Player Disconnection:

   • If a player closes the browser tab or window while in the lobby or in a game:
     • The frontend makes a leave API call to notify the backend to remove the player from the game.

This workflow ensures a smooth and real-time gaming experience, managing state transitions and player activity effectively.

---

📊 Example Response

{
  "code": 0,
  "msg": "OK",
  "data": {
    "code": "BALU5X",
    "players": [
      {
        "id": "234et",
        "name": "tes2t",
        "isLeader": true,
        "isWinner": false,
        "paths": null
      }
    ],
    "state": "waiting",
    "startArticle": "",
    "targetArticle": "",
    "startTime": "0001-01-01T00:00:00Z",
    "endTime": "0001-01-01T00:00:00Z"
  }
}

---

🚀 Contribute

We welcome contributions! Please feel free to fork this repository, submit issues, or create pull requests.

---

🎉 Happy WikiRacing!