Cricket Clash 🏏

A modern Flutter-based cricket game where players engage in a strategic number-guessing battle. Built with Flutter, Flame engine, and optimized for performance using BLoC state management.

🎮 Game Overview

Cricket Clash is a turn-based cricket simulation game where players choose numbers (1-6) as batters and bowlers. The game combines strategy, luck, and cricket fundamentals in an engaging mobile experience.

🎯 Core Gameplay

• Number Selection: Both batter and bowler choose numbers between 1-6
• Scoring Rules:
  • If numbers match → Batter is OUT
  • If numbers don't match → Batter scores the chosen runs
• Role Switching: Players alternate between batting and bowling
• Victory Condition: Highest score after both innings wins

✨ Features

🎲 Game Mechanics

• Turn-Based Simulation: Strategic number selection for both batting and bowling
• Smart AI Opponent: Intelligent bot with adaptive difficulty
• Real-time Score Tracking: Live score updates and game statistics
• Innings Management: Proper cricket-style innings with role switching
• Rematch System: Quick replay functionality for continuous gameplay

🎨 User Experience

• Intuitive UI: Clean, cricket-themed interface design
• Timer-Based Decisions: Timed number selection for added excitement
• Visual Feedback: Immediate result display for each turn
• Progress Indicators: Clear game phase and turn information
• Responsive Design: Optimized for various screen sizes

🚀 Performance Features

• Optimized Rendering: Granular widget rebuilds prevent unnecessary re-renders
• Efficient State Management: BLoC pattern with Equatable for performance
• Memory Management: Optimized for smooth gameplay on all devices

🏗️ Architecture

Project Structure

lib/
├── main.dart              # App entry point
├── bloc/                  # State management (BLoC pattern)
├── events/                # Game events definition
├── models/                # Data models (Player, GameTurn, etc.)
├── screens/               # UI screens (GamePlay, Loading, etc.)
├── utils/                 # Utility functions and helpers
└── widgets/               # Reusable UI components

🛠️ Technology Stack

Technology	Version	Purpose
Flutter	3.7.2+	Cross-platform app framework
Flame	1.18.0	Game engine for Flutter
BLoC	8.1.6	State management pattern
Flame-BLoC	1.12.0	BLoC integration for Flame
Equatable	2.0.5	Value equality and performance

🎨 Design Guidelines

Visual Design

• Typography: Clean, readable sans-serif fonts
• Icons: Simple and recognizable cricket-themed icons
• Layout: Two-column player areas with central score display
• Animations: Subtle transitions during turn changes and score updates
• Color Scheme: Cricket-inspired color palette

UI/UX Reference

Refer to ./reference_screens/ directory for design mockups:

• 1_first_step_loading_game.PNG - Initial game loading
• 2_second_step_loading_game.PNG - Secondary loading phase
• 3_informing_current_player_bats_or_bowls.PNG - Role announcement
• 4_game_play_with_timer_to_choose_from_score_buttons.PNG - Main gameplay
• 5_game_play_score_selected_by_current_player.PNG - Selection feedback
• 6_game_play_round_score.PNG - Round results display

🚀 Getting Started

Prerequisites

• Flutter SDK 3.7.2 or higher
• Dart SDK (included with Flutter)
• Android Studio / VS Code with Flutter extensions

Installation

1. Clone the repository

   git clone <repository-url>
   cd cricket_clash

2. Install dependencies

   flutter pub get

3. Run the app

   flutter run

Build for Production

# Android APK
flutter build apk --release

# iOS (requires Xcode)
flutter build ios --release

# Web
flutter build web

🎯 Performance Optimizations

The app includes several performance optimizations documented in:

• OPTIMIZATION_SUMMARY.md - Complete optimization details
• PERFORMANCE_ANALYSIS.md - Performance analysis and strategies

Key Optimizations

• ✅ Equatable implementation for efficient state comparisons
• ✅ Granular BlocBuilder usage to minimize widget rebuilds
• ✅ Optimized rendering for complex UI components
• ✅ Memory-efficient game state management

🧪 Testing

# Run all tests
flutter test

# Run tests with coverage
flutter test --coverage

📱 Supported Platforms

• ✅ Android (API 21+)
• ✅ iOS (iOS 12.0+)
• ✅ Web (Progressive Web App)
• ✅ Windows (Desktop)
• ✅ macOS (Desktop)
• ✅ Linux (Desktop)

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Flutter team for the amazing framework
• Flame engine community for game development tools
• BLoC library contributors for clean state management