🎯 Difficulty Levels

Firefly Mahjong features 50 carefully crafted levels that gradually increase in complexity:

• Levels 1-10: Beginner (14-140 tiles) - Perfect for learning the rules
• Levels 11-20: Intermediate (158-308 tiles) - Build your skills
• Levels 21-30: Advanced (340+ tiles) - Challenge yourself
• Levels 31-40: Expert - Complex layouts
• Levels 41-50: Master - Maximum difficulty
• Endless Mode: Infinite random boards after completing Level 50

Power-Ups & Tools

• 💡 Hint (5 uses): Highlights a matching pair when you're stuck
• 🔀 Shuffle (3 uses): Rearranges remaining tiles into a new solvable layout
• ↩️ Undo: Revert your last move (unlimited uses)

🏆 Scoring System

• Base Points: 100 points per match
• Combo Bonus: Match tiles quickly to build combos (up to 8x multiplier!)
• Star Rating: Earn 1-3 stars per level based on speed and efficiency
• Best Score Tracking: Your highest score and best time saved for each level

🎨 Visual & Audio Settings

• 🔊 Sound Effects: Toggle wooden tile clacks and match sounds
• 🎵 Ambient Music: Procedurally generated relaxing soundscape (Cmaj7-Am7-Fmaj7-G7 progression)
• Responsive Design: Automatically adapts to any screen size

🎲 Basic Rules

1. Select Tiles: Click or tap on a free tile to select it (it will glow)
2. Match Pairs: Click on another free tile with the same design to remove both
3. Clear the Board: Remove all tile pairs to complete the level

✅ What Makes a Tile "Free"?

A tile can only be selected if BOTH conditions are met:

1. No tiles on top: The tile must not be covered by any tile from a higher layer
2. Side is open: At least one side (left OR right) must have no adjacent tile on the same layer

💡 Tip: Free tiles are slightly elevated and have a subtle glow when you hover over them.

Tile Types

The game features 42 unique tile designs across 6 categories:

• Dots (Circles): Numbers 1-9 with colored dots
• Bamboo: Green bamboo sticks (1-9)
• Characters: Chinese numerals 萬 (1-9)
• Winds: East (E), South (S), West (W), North (N)
• Dragons: Red (中), Green (發), White
• Flowers: Plum, Orchid, Bamboo, Chrysanthemum, Spring, Summer, Autumn, Winter

⏱️ Strategy Tips

• Work from the top: Always prioritize removing tiles from higher layers first
• Plan ahead: Don't just match the first pair you see - think about what tiles you'll unlock
• Build combos: Match tiles quickly (within 3.2 seconds) to earn combo multipliers
• Use hints wisely: Save your hints for when you're truly stuck
• Watch the edges: Edge tiles are often the key to unlocking the board

Earning 3 Stars

To achieve the maximum 3-star rating on each level:

• Complete the level quickly (under 4 seconds per tile pair)
• Use fewer than 3 hints
• Maintain high combos throughout the game

💻 Technology

• Built With: Pure HTML5 Canvas + Vanilla JavaScript (ES6)
• No External Dependencies: Zero libraries - lightweight and fast
• File Size: Under 50KB (incredibly lightweight!)
• Instant Loading: No downloads, no installations

🎨 Procedural Graphics

All tiles are drawn dynamically using Canvas API - no image files needed:

• Vector-Based: Perfect quality on any screen resolution (Retina/4K support)
• 3D Effects: Realistic tile depth with shadows and highlights
• Smooth Animations: 60 FPS particle effects and tile movements
• Adaptive Sizing: Tiles automatically resize from 28px to 96px based on screen

🎵 Procedural Audio

Web Audio API generates all sounds in real-time:

• Sound Effects: Wooden percussion, marimba tones, match celebrations
• Ambient Music: Dreamy chord progressions with sparse bell notes
• Zero Bandwidth: No MP3 files to download
• Smooth Transitions: Cross-fading chords for seamless loops

💾 Smart Save System

• LocalStorage: Progress automatically saved in browser
• What's Saved: Highest unlocked level, best scores, times, stars, settings
• Privacy: All data stored locally - no servers, no tracking
• Cross-Session: Close browser and return anytime - your progress is safe

📱 Responsive Design

• Mobile-First: Touch-optimized controls
• Orientation Support: Works in portrait and landscape
• Safe Areas: Properly handles notches and home indicators
• Breakpoints: Optimized layouts for 320px to 1920px+ screens

♿ Accessibility

• Keyboard Navigation: Full keyboard support for desktop users
• Visual Clarity: High contrast, clear tile designs
• Reduced Motion: Respects system preferences for animations
• Color Blind Friendly: Tiles distinguished by patterns, not just colors