Magical Merchant

Last Updated: November 7, 2025

A Flutter idle game where you collect ingredients over time, craft magical items, and sell them for profit to unlock new content and expand your shop.

🎮 Game Features

Core Gameplay Loop

1. Collect Ingredients - Assign ingredients to collection slots that generate resources over time
2. Craft Items - Combine ingredients using recipes to create magical items
3. Sell Products - Sell both ingredients and crafted items for gold
4. Unlock & Expand - Purchase new ingredients, recipes, and slot upgrades

Key Systems

Collection System

• 6 Collection Slots - Unlock progressively (200, 800, 1500, 3000, 5000, 10000 gold)
• Time-Based Generation - Each ingredient has unique collection times
• Real-time Timers - Visual progress bars with rarity-based colors
• Ingredient Types - 5 types with unique icons (herbs, mushrooms, minerals, essences, flowers)
• Passive Income - Continue collecting even when app is closed

Crafting System

• 4 Crafting Slots - Unlock additional slots (200, 800, 2000, 5000 gold)
• Parallel Crafting - Work on multiple recipes simultaneously
• Recipe Collection - Unlock new recipes as you progress (orange/amber gradient cards)
• Ingredient Consumption - Uses ingredients from your inventory
• Color-Coded Progress - Visual feedback with state-based colors

Shop & Economy

• Sell Ingredients - Blue gradient cards with elevated styling
• Sell Crafted Items - Purple/pink gradient cards with craft badge
• Smart Pricing - Different sell prices based on rarity and complexity
• Recipe Unlocks - Purchase new crafting recipes (orange/amber styling)
• Ingredient Unlocks - Purchase new ingredients (blue/cyan styling)
• Animated Currency - Smooth counting animations with flash effects

Visual Polish

• Rarity System - Color-coded progress indicators (grey, green, blue, purple, amber)
• Gradient Backgrounds - Themed cards for different item types
• Type Icons - Visual indicators for ingredient categories
• Animated Feedback - Currency changes, glow effects, particle celebrations
• High Contrast - White text on colored backgrounds for readability

Tutorial System

• Interactive 12-Step Tutorial - Guides new players through all core mechanics
• Hands-On Learning - Real purchases, collections, and crafting
• One-Time Experience - Only shown on first launch
• Starting Resources - 500 gold to begin your journey

🛠️ Technical Stack

• Framework: Flutter 3+ (stable)
• Language: Dart
• State Management: Riverpod (FutureProvider, StreamProvider, StateNotifierProvider)
• Architecture: Clean Architecture + MVVM
• Persistence: Local JSON storage with SharedPreferences backup
• Animations: flutter_animate 4.5.0 for UI polish
• Platform: iOS, Android

📁 Project Structure

lib/
├── core/           # Utilities, services, constants, theme
│   ├── constants/  # Ingredient icons, progress colors
│   └── storage/    # Local storage implementation
├── data/           # Repository implementations, persistence
├── domain/         # Business entities, repository interfaces
├── presentation/   # UI pages, widgets, providers, theme
│   ├── pages/      # Shop, collection, crafting pages
│   ├── widgets/    # Reusable UI components
│   ├── providers/  # Riverpod state management
│   └── theme/      # Rarity colors, app theme
└── main.dart       # App entry point

🚀 Getting Started

Prerequisites

• Flutter SDK 3.0 or higher
• Dart 3.0 or higher
• iOS Simulator or Android Emulator

Installation

# Clone the repository
git clone https://github.com/yourusername/MagicalMerchant.git

# Navigate to project
cd MagicalMerchant

# Install dependencies
flutter pub get

# Run the app
flutter run

Reset Game Data (for testing)

# Use the provided script
./reset_game_data.sh

# Fix corrupted save files (if needed)
dart run fix_player_progress.dart <path_to_player_progress.json>
dart run fix_ingredients_save.dart <path_to_ingredients.json>

📖 Documentation

• Library Overview - Complete architecture documentation
• Domain Layer - Business entities and logic
• Data Layer - Repositories and persistence
• Presentation Layer - UI components and state
• Core Layer - Utilities and services
• UI Polish Spec - Phase 1 visual enhancements (complete)

🎯 Roadmap

Current Features (v0.2 - November 2025)

• ✅ Collection system with 6 slots
• ✅ Crafting system with 4 slots
• ✅ Shop with ingredient/recipe unlocks
• ✅ Selling ingredients and crafted items
• ✅ Interactive tutorial
• ✅ Real-time timers and progress tracking
• ✅ Data persistence
• ✅ NEW: Rarity-based visual system
• ✅ NEW: Ingredient type icons and colors
• ✅ NEW: Gradient card styling (shop items)
• ✅ NEW: Animated currency displays
• ✅ NEW: Color-coded progress indicators
• ✅ NEW: High-contrast UI with themed gradients

In Progress (Phase 2)

• 🔄 Enhanced recipe cards with efficiency ratings
• 🔄 Unlock animation sequences
• 🔄 Contextual particle effects
• 🔄 Themed page backgrounds

Planned Features (Phase 3)

• 📋 Achievement system with milestones
• 📋 Day/night cycle theming
• 🔄 Prestige/reset mechanics
• 🔄 Visual effects and animations
• 🔄 Sound effects and music
• 🔄 Cloud save support

🤝 Contributing

This is a personal learning project. Suggestions and feedback are welcome!

📄 License

This project is licensed under the MIT License.

---

Built with ❤️ using Flutter