Wordle Clone using Python and PyQt5
A faithful recreation of the popular word puzzle game with advanced GUI implementation and sophisticated game mechanics.
This project demonstrates proficiency in desktop application development using Python and PyQt5, showcasing object-oriented programming principles, GUI design, and complex state management. The clone faithfully recreates Wordle's core gameplay while implementing additional features like persistent statistics tracking and daily play restrictions.
Project Overview
The Wordle Clone is a desktop application that replicates the popular web-based word puzzle game where players attempt to guess a five-letter word within six tries. Each guess provides visual feedback through color-coded tiles: green for correct letters in correct positions, yellow for correct letters in wrong positions, and gray for letters not in the target word.
Technical Architecture
Core Technologies
- Python 3.x - Primary programming language
- PyQt5 - GUI framework for cross-platform desktop application development
- Qt Designer - Visual UI design tool for creating professional interfaces
System Design
The application follows a modular architecture with clear separation of concerns:
Main Game Engine (main.py)
- MainWindow Class: Central hub managing all game functionality and UI interactions
- BaseGame() Function: Core game logic handling word validation, color feedback, and win/loss conditions
- Random Word Generation: Daily word selection using date-based seeding for consistency
Input Management (keyboard.py)
The application supports dual input methods:
- Physical Keyboard Integration:
keyPressEvent() captures hardware keyboard input
- Virtual Keyboard: Custom GUI buttons for mouse-based interaction
- Unified Letter Processing: Both input methods funnel through centralized letter handling functions
Game State Persistence
Statistics Tracking (scores.py)
- Maintains comprehensive player statistics in
scores.txt
- Tracks games played, wins, current streak, maximum streak, and win percentage
- Implements CRUD operations for score management:
create_file(): Initializes score file with default valuesread_scores(): Loads existing statistics into memoryupdate_scores(): Modifies statistics based on game outcomeswrite_scores(): Persists updated statistics to file
Daily Play Enforcement (played_checker.py)
- Prevents multiple plays per day to maintain game integrity
- Creates date-stamped log files in the
Logs directory
- Functions include:
check_if_played_today(): Verifies if user has already playedadd_record(): Creates play record upon game completionclear_logs(): Maintains log directory by removing old entries
Key Features and Innovations
Authentic Gameplay Experience
- Accurate Word Validation: Uses comprehensive English word dataset (
words_alpha.txt)
- Visual Feedback System: Implements Wordle's signature color-coding scheme
- Six-Attempt Limit: Maintains original game difficulty and structure
Enhanced User Interface
- Professional Design: Created using Qt Designer for pixel-perfect layouts
- Custom Typography: Includes dedicated fonts folder for consistent visual presentation
- Responsive Interactions: Smooth animations and visual feedback for user actions
Advanced State Management
- Global Settings System: Centralized configuration management through
settings.py
- Session Persistence: Maintains game state and user progress across application restarts
- Data Integrity: Robust file handling prevents data corruption and loss
Cross-Platform Compatibility
- Multi-OS Support: Runs natively on Windows, macOS, and Linux
- Font Management: Automatic font installation guidance for optimal display
- Resource Management: Efficient asset loading and memory usage
Development Highlights
Object-Oriented Design Principles
- Encapsulation: Clean separation between UI components and game logic
- Modularity: Independent modules for different game aspects
- Maintainability: Well-structured codebase for easy updates and extensions
Error Handling and User Experience
- Graceful Degradation: Handles missing resources and system limitations
- User Guidance: Clear instructions for font installation and troubleshooting
- Data Validation: Robust input validation prevents application crashes
Performance Optimization
- Efficient File I/O: Minimized disk operations for smooth gameplay
- Memory Management: Proper resource cleanup and garbage collection
- Event-Driven Architecture: Responsive UI through efficient event handling
Technical Challenges Solved
- Daily Word Consistency: Implemented date-based seeding to ensure all players get the same word each day
- Play Restriction Logic: Developed sophisticated logging system to prevent cheating
- Cross-Platform Font Handling: Created robust font management system for consistent appearance
- State Persistence: Implemented reliable data storage without external databases
- Dual Input Integration: Seamlessly merged physical and virtual keyboard inputs
Learning Outcomes
This project provided valuable experience in:
- GUI Development: Mastery of PyQt5 widgets, layouts, and event systems
- File System Operations: Advanced file handling for data persistence
- User Experience Design: Creating intuitive and engaging interfaces
- Software Architecture: Designing maintainable and extensible applications
- Cross-Platform Development: Ensuring consistent behavior across operating systems
Project Structure
Wordle-Clone/
├── Assets/
│ ├── Icons/ # UI icons and graphics
│ └── *.ui # Qt Designer interface files
├── Dataset/
│ └── words_alpha.txt # English word database
├── Fonts/ # Custom typography files
├── Logs/ # Daily play tracking (generated)
├── main.py # Application entry point
├── keyboard.py # Input handling logic
├── scores.py # Statistics management
├── played_checker.py # Daily play enforcement
└── settings.py # Global configuration
This Wordle clone represents a comprehensive exploration of desktop application development, demonstrating both technical proficiency and attention to user experience details that make software truly engaging and professional.
