WikiRace - A Desktop Wikipedia Race Application

Support Wikipedia: If you enjoy using this app, please consider donating to Wikipedia to help keep this valuable resource free and accessible to everyone.

Project Information

• Author: Ian Wagers
• Date Created: February 13, 2023
• Language: Python

Note: This is an AI Driven (personal python project), the majority of the code was generated by ChatGPT to start, with additional support from Visual Studio's CoPilot

Overview

WikiRace is a fun and educational game that challenges you to navigate from one Wikipedia page to another using only the links within the articles. Test your knowledge and strategy as you race against time to find the shortest path between two seemingly unrelated topics.

Features

• Solo Game Mode: Race against the clock to reach the target page as quickly as possible
• Real-time Multiplayer: Compete with up to 10 friends in live Wikipedia races
• Room-based Gaming: Create or join game rooms with 4-letter codes
• Live Progress Tracking: See other players' current pages and progress in real-time
• Modern GUI: Built with PyQt6 for a smooth and responsive user experience
• Flexible Page Selection: Choose from categories or set custom start/end pages
• Comprehensive Results: View detailed race results and navigation paths
• Theme Support: Dark and light mode themes with consistent styling
• Automatic Reconnection: Robust network handling with automatic reconnection
• External Server Support: Connect to servers outside your local network
• Persistent Settings: Settings and server configurations saved to AppData
• Application Branding: Custom icons and professional appearance

Screenshots

Home Page

Solo Race Game

Multiplayer Page

How to Use

Getting Started

1. Installation: Follow the setup instructions in the docs/ folder to install all dependencies
2. Running the App: Execute python bin/main.py or use the provided executable
3. Choose Your Mode: Select between Solo Game or Multiplayer from the main menu

Solo Game Mode

1. Start a New Game: Click "Solo Game" from the main menu
2. Set Your Target: The app will randomly select a target Wikipedia page
3. Begin Navigation: Start from the current page and click links to navigate
4. Race Against Time: Try to reach the target page in as few clicks as possible
5. Track Your Progress: Monitor your path and time as you navigate

Multiplayer Mode

1. Start the Server: Run the multiplayer server using python server/start_server.py
2. Host a Game: Enter your name and click "Create Room" to generate a 4-letter room code
3. Invite Friends: Share the room code with friends who can join using "Join Room"
4. Configure Game: As host, select page categories or set custom start/end pages
5. Start Racing: Begin the race - all players start simultaneously with identical conditions
6. Track Progress: See other players' current pages and link counts in real-time
7. View Results: When someone reaches the target, see complete rankings and paths

Game Tips

• Think Strategically: Look for pages that might be conceptually related to your target
• Use Categories: Wikipedia categories can help you find related topics
• Explore Connections: Sometimes the most efficient path isn't the most obvious one
• Learn as You Play: Each game teaches you about new topics and connections

Current Status (v1.0.0)

• ✅ Solo games fully functional and polished
• ✅ Multiplayer server infrastructure complete
• ✅ Real-time room management and player communication
• ✅ Room creation/joining with 4-letter codes
• ✅ Complete multiplayer game flow with countdown and synchronization
• ✅ Navigation history tracking and visualization
• ✅ Automatic reconnection logic
• ✅ Client configuration UI
• ✅ Docker deployment ready
• ✅ Dark/Light theme support with consistent theming
• ✅ Application icon and branding
• ✅ AppData storage for persistent settings
• ✅ External server connectivity
• 🔄 EXE/Installer build (in progress)

Technical Details

Client Application

• Framework: PyQt6 for the GUI with PyQt6-WebEngine for Wikipedia display
• Python Version: 3.13 (strict requirement)
• Architecture: Modular design with separate logic and GUI components
• Networking: Socket.IO client for real-time multiplayer communication

Multiplayer Server

• Framework: FastAPI with Socket.IO for real-time events
• Data Models: Pydantic for validation and serialization
• Storage: In-memory with Redis planned for persistence
• Deployment: Self-hosted server (Docker support planned)

Dependencies

See pyproject.toml for complete requirements including:

• PyQt6 6.7.0+ (GUI framework)
• PyQt6-WebEngine 6.7.0+ (Wikipedia display)
• python-socketio[client] 5.8.0+ (real-time communication)
• requests 2.32.0+ (HTTP API calls)
• beautifulsoup4 4.12.0+ (HTML parsing)

Project Structure

• src/ - Main application code (GUI and logic)
• server/ - Multiplayer server infrastructure
• docs/ - Comprehensive documentation
• scripts/ - Utility scripts and automation tools
• tests/ - Test files and validation scripts

Documentation Automation

This project includes automated documentation updates:

• Global Context: .cursorrules file provides comprehensive project context for Cursor AI
• Auto-Updates: Git hooks automatically update documentation when changes are committed
• Manual Updates: Run python scripts/update_context.py to manually refresh documentation