Supermarket Rush 🛒⚡

A fast-paced time-management arcade game built with Flutter and Flame. Race against the clock to fulfill online orders in a busy supermarket, master efficient routes, and become the ultimate order picker!

🎮 Game Overview

Supermarket Rush combines the thrill of time-management gameplay with strategic route planning. Players navigate a bustling supermarket, collecting products to fulfill diverse customer orders while managing stamina, capacity limits, and tight deadlines.

Core Fantasy

Become the fastest and smartest order picker in a busy supermarket, racing against time to fulfill online orders and maximize profit through speed, accuracy, and strategic decision-making.

✨ Features

Gameplay Mechanics

• Dynamic Movement System: Smooth WASD/Arrow key controls with sprint mechanic and stamina management
• Intelligent Order System: Five distinct order types with varying complexity and rewards
  • 📦 Standard Orders: Balanced time and reward
  • ⚡ Express Orders: Short timer, high payout
  • 📊 Bulk Orders: Many items, strategic route planning required
  • 🔸 Fragile Orders: Careful handling needed, penalties for collisions
  • ❄️ Frozen Orders: Time-sensitive cold items
• Priority Levels: Normal, Express, and VIP orders with multiplier bonuses
• Progressive Difficulty: Order frequency and complexity increase over time

Game Systems

• Time Management: 5-minute shift timer with individual order countdowns
• Scoring & Progression:
  • Money rewards based on speed, accuracy, and order type
  • Combo multipliers for completing multiple orders rapidly
  • Performance ranking system (S/A/B/C/D grades)
• Player Stats:
  • Movement speed with sprint burst capability
  • Stamina system (drains during sprint, regenerates when walking)
  • Carry capacity limits affecting movement speed
  • Pickup progress with visual feedback

Supermarket Environment

• 12 Product Types across multiple categories (Fresh, Frozen, Fragile, Standard)
• Multi-aisle Layout with organized shelving systems
• Visual Product Categories: Frozen items marked with snowflakes, fragile items with warning symbols
• Dedicated Delivery Zone for order completion

User Interface

• Comprehensive HUD:
  • Real-time money counter
  • Shift timer with urgency indicators
  • Performance rank display
  • Active order cards showing progress, time remaining, and rewards
  • Player stats (carry capacity, stamina bar)
  • Combo streak indicator
  • On-screen control hints
• End-Game Summary: Detailed statistics and performance breakdown with replay option

📸 Screenshots

Screenshots coming soon

🚀 Getting Started

Prerequisites

• Flutter SDK (3.10 or higher)
• Dart SDK (included with Flutter)
• A code editor (VS Code or Android Studio recommended)

Installation

1. Clone the repository

   git clone https://github.com/krlz-dev/supermarket_rush.git
   cd supermarket_rush

2. Install dependencies

   flutter pub get

3. Run the app

   # Desktop (macOS/Windows/Linux)
   flutter run -d macos  # or windows, linux
   
   # Mobile
   flutter run -d ios    # iOS
   flutter run -d android # Android
   
   # Web
   flutter run -d chrome

Building for Release

# Android APK
flutter build apk --release

# iOS
flutter build ios --release

# Web
flutter build web --release

# Desktop
flutter build macos --release  # or windows, linux

🎯 How to Play

Controls

• WASD or Arrow Keys: Move player
• Shift: Sprint (consumes stamina)
• Space: Pick up product / Deliver completed orders

Objective

1. Receive Orders: Orders appear on the left side with product lists and time limits
2. Navigate: Move through the supermarket to locate required products
3. Collect Items: Approach products and press Space to pick them up
4. Complete Orders: Gather all items for an order
5. Deliver: Return to the green delivery zone and press Space
6. Maximize Earnings: Complete orders quickly for speed bonuses and combo multipliers
7. Beat the Clock: Finish as many orders as possible within the 5-minute shift

Strategy Tips

• Plan efficient routes to minimize backtracking
• Prioritize high-value Express and VIP orders
• Watch your stamina—sprinting strategically is key
• Complete multiple orders simultaneously for combo bonuses
• Keep an eye on order timers to avoid penalties

🏗️ Project Architecture

lib/
├── models/               # Data models
│   ├── product.dart      # Product definitions and categories
│   ├── order.dart        # Order system and logic
│   └── player_stats.dart # Player stats and progression
├── game/
│   ├── components/       # Game entities
│   │   ├── player.dart   # Player component with movement and pickup
│   │   └── supermarket.dart # Store layout, aisles, and products
│   ├── systems/          # Game logic systems
│   │   └── order_manager.dart # Order generation and tracking
│   ├── ui/               # UI overlays
│   │   └── game_hud.dart # HUD with stats, orders, and controls
│   └── supermarket_rush_game.dart # Main game engine
└── main.dart             # Application entry point

Technology Stack

• Flutter: Cross-platform UI framework
• Flame: 2D game engine for Flutter
• Dart: Programming language
• Architecture Pattern: Component-based architecture with separation of concerns
• State Management: Built-in Flame game loop and component lifecycle

🔮 Future Enhancements

Phase 1: Mobile Optimization

• Touch Controls: Virtual joystick and action buttons for mobile devices
• Haptic Feedback: Vibration on pickup, delivery, and important events
• Responsive UI: Dynamic scaling for different screen sizes and orientations
• Performance Optimizations: Improved rendering for mobile GPUs

Phase 2: Enhanced Gameplay

• Dynamic Obstacles:
  • AI-controlled shoppers with pathfinding
  • Spills causing slip hazards and slowdown
  • Restocking staff blocking aisles
  • Dynamic aisle closures during peak times
• Advanced Order Types:
  • Combo orders requiring specific product combinations
  • Temperature-controlled zones for frozen items
  • Customer special requests with bonus rewards
• Environmental Challenges:
  • Rush hour events with increased difficulty
  • Black Friday special events
  • System outages affecting certain product categories

Phase 3: Progression & Customization

• Upgrade System:
  • Movement speed upgrades
  • Stamina capacity and regeneration boosts
  • Pickup speed improvements
  • Carry capacity expansions
  • Smart scanner highlighting products
• Equipment Shop:
  • Faster shopping carts
  • Ergonomic baskets
  • Auto-stacking items
  • Route optimization tools
• Player Customization:
  • Character skins and uniforms
  • Visual effects and trails
  • Custom name tags

Phase 4: Content Expansion

• Store Evolution:
  • Unlock larger supermarket layouts
  • Multi-floor stores with elevators
  • Specialized departments (Bakery, Deli, Pharmacy)
  • Warehouse-style bulk stores
• Product Variety:
  • Expand to 50+ unique products
  • Seasonal items with limited availability
  • Rare products with premium rewards
• Career Mode:
  • Story-driven progression
  • Contract system with delivery platforms
  • Reputation system affecting order difficulty
  • Unlock new stores and locations

Phase 5: Social & Competitive Features

• Leaderboards:
  • Global rankings by earnings, speed, and efficiency
  • Daily/weekly challenges
  • Friend leaderboards
• Multiplayer:
  • Cooperative mode: Team up to fulfill orders
  • Competitive mode: Race against other players
  • Asynchronous challenges
• Achievements & Rewards:
  • 50+ achievements to unlock
  • Special badges for milestones
  • Reward system for consistent play

Phase 6: Polish & Quality of Life

• Audio System:
  • Background music with dynamic intensity
  • Sound effects for pickups, deliveries, and timers
  • Audio cues for urgent orders
  • Customizable volume controls
• Visual Enhancements:
  • Particle effects for pickups and deliveries
  • Smooth camera transitions
  • Improved product sprites and animations
  • Environmental details and decorations
• Accessibility:
  • Colorblind mode support
  • Adjustable game speed
  • Text-to-speech for orders
  • Customizable control schemes
  • High contrast mode

Phase 7: Meta Features

• Save System:
  • Cloud save synchronization
  • Multiple save slots
  • Progress backup and restore
• Analytics Dashboard:
  • Personal statistics tracking
  • Performance graphs over time
  • Efficiency metrics and insights
• Tutorial & Onboarding:
  • Interactive tutorial mode
  • Tooltips and hints system
  • Practice mode with no time pressure

Long-term Vision

• Content Creator Tools: Replay system, screenshot mode
• Modding Support: Custom supermarket layouts and products
• Cross-platform Progress: Seamless play across mobile, web, and desktop
• Seasonal Events: Holiday-themed content and limited-time challenges
• Localization: Support for multiple languages

🤝 Contributing

Contributions are welcome! Whether it's bug fixes, feature additions, or documentation improvements:

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

Development Guidelines

• Follow Flutter style guide
• Write clear commit messages
• Add tests for new features
• Update documentation as needed

📝 License

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

🙏 Acknowledgments

• Built with Flutter and Flame
• Inspired by real-world supermarket order fulfillment experiences
• Game design based on time-management and arcade game mechanics

📧 Contact

Project Link: https://github.com/krlz-dev/supermarket_rush

---

Supermarket Rush - Master the rush, maximize the profit! 🛒⚡