Puzzle

CONTROLS: - Desktop: - Mouse Drag: Click and drag puzzle pieces from drawer to board or table - Mouse Click: Click menu buttons, puzzle selection, and UI elements - V Key: Toggle preview mode (show complete image) - P Key / Escape Key: Pause/Resume game - M Key: Mute/Unmute sound effects - B Key / A Key: Toggle border-only mode (show only edge pieces) - S Key / J Key: Toggle drawer split view (one or two piece areas) - E Key / Q Key: Exit to puzzle selection screen - Slider Navigation: Click prev/next buttons or arrows to navigate puzzle selection - Mobile/Tablet: - Touch and Drag: Touch and drag puzzle pieces - Touch: Tap menu buttons and UI elements - Touch gestures supported through mouse event conversion - Menu Buttons: - Preview Button: View complete puzzle image - Pause Button: Pause/continue gameplay - Mute Button: Toggle sound on/off - Exit Button: Return to puzzle selection - Borders Button: Show only border pieces - Split Button: Toggle drawer layout BASIC MECHANICS: 1. Puzzle Selection: - 8 puzzle categories: Art, Apple, Animal, Car, City, Gradient, Street, Wonder - 10 puzzles per category (80 total puzzles) - 4 difficulty levels per puzzle: 50, 100, 250, 500 pieces - Total 320 puzzle configurations (80 puzzles × 4 difficulties) - Category tabs for easy navigation - Slider interface to browse puzzles - Completion tracking per puzzle and difficulty 2. Piece System: - Pieces generated from puzzle images - Each piece has unique shape and borders - Border pieces identified (edge pieces of puzzle) - Pieces positioned in grid (rows × columns) - Piece size scaled based on difficulty level - Scale factors: 50 pieces = 1.0, 100 = 0.75, 250 = 0.5, 500 = 0.5 3. Piece Drawing: - Pieces rendered on HTML5 Canvas - Each piece has jagged borders (top, right, bottom, left) - Border type: 0 = straight edge, non-zero = jagged connector - Pieces include image portion from original puzzle - Pieces sized based on difficulty and image dimensions 4. Drag and Drop: - Click and drag pieces from drawer to board - Mouse button 0 (left click) for dragging - Touch events converted to mouse events for mobile - Pieces follow cursor/touch during drag - Visual feedback during dragging 5. Auto-Snap System: - Pieces automatically snap when placed near correct position - Snap detection: Distance check (< delta threshold) - Snap to board position if close enough - Snap to neighboring pieces if compatible - Snap tolerance: scalePadding distance (delta) - Pieces align to grid when snapped 6. Piece Fitting: - Pieces fit with neighbors when borders match - Border compatibility checked between adjacent pieces - Top border of piece matches bottom border of piece above - Right border of piece matches left border of piece to right - Compatible pieces join into "Set" (connected group) - Sets can contain multiple connected pieces 7. Set System: - Connected pieces form Sets - Sets behave as single unit during dragging - Adding piece to set expands set boundaries - Sets positioned by top-left corner - Sets can snap to board or other sets - Sets merge when connected pieces placed correctly 8. Drawer System: - Pieces start in drawer (primary/secondary areas) - Drawer shows unplaced pieces - Border-only mode: Shows only edge pieces - Split mode: Shows pieces in two areas (primary/secondary) - Single mode: Shows all pieces in one area - Pieces removed from drawer when placed on board 9. Board System: - Main assembly area where pieces are placed - Board sized based on puzzle dimensions - Board padding for playable area - Pieces positioned on board grid - Board tracks placed pieces in matrix - Completed pieces locked in position 10. Table System: - Temporary area for working on piece groups - Pieces can be placed on table - Table allows piece manipulation before board placement - Table supports scrolling for large puzzles - Pieces on table can snap together - Table useful for assembling sets before placing on board 11. Progress Tracking: - Placed pieces counter: Shows pieces placed / total pieces - Completion percentage: Calculated as (placed / total × 100) - Timer: Tracks elapsed time in MM:SS format - Timer starts when puzzle begins - Timer pauses when game paused - Progress saved automatically 12. Scoring System: - Score based on pieces placed - Completion status tracked per puzzle/difficulty - Puzzles marked as completed when all pieces placed - Completion saved to localStorage - Progress persists between sessions 13. Preview Mode: - Toggle preview to see complete puzzle image - Preview shows final assembled image - Helpful for understanding puzzle layout - Toggle with V key or preview button - Click outside preview image to close - Preview overlay displayed over game 14. Border-Only Mode: - Filter drawer to show only edge pieces - Helps focus on assembling puzzle border first - Toggle with B key or borders button - Useful strategy for puzzle assembly - Shows pieces with straight edges (top, right, bottom, or left = 0) 15. Drawer Split Mode: - Toggle between single and split drawer views - Split view: Two areas (primary/secondary) - Single view: All pieces in one area - Toggle with S key or split button - Helps organize pieces during assembly 16. Pause System: - Pause game at any time - Timer stops during pause - Game state preserved - Pause overlay displayed - Resume to continue from pause point - Toggle with P key, Escape key, or pause button 17. Sound System: - Sound effects for game actions - Drop sound: When piece placed - Snap sound: When piece snaps into place - Fireworks sound: When puzzle completed - Sound toggle with M key or mute button - Sound state persisted 18. Completion Detection: - Puzzle complete when all pieces placed on board - Completion checked: placedPieces === totalPieces - Congratulations screen displayed on completion - Timer stops on completion - Completion saved to storage - Fireworks sound plays on completion 19. Save System: - Game state saved automatically - Board pieces positions saved - Timer elapsed time saved - Progress saved to localStorage - Puzzle selection state saved - Completion status saved per puzzle/difficulty 20. Puzzle Categories: - Art: Artistic images and paintings - Apple: Apple-themed images - Animal: Animal photographs - Car: Car images - City: Cityscapes and urban scenes - Gradient: Gradient and abstract images - Street: Street scenes and urban photography - Wonder: Wonder-themed images - Each category contains 10 different puzzles 21. Difficulty Levels: - 50 pieces: Easy difficulty, scale 1.0 - 100 pieces: Medium difficulty, scale 0.75 - 250 pieces: Hard difficulty, scale 0.5 - 500 pieces: Expert difficulty, scale 0.5 - Scale affects piece size and board dimensions - Higher piece count = smaller pieces = greater challenge 22. Grid Calculation: - Grid size calculated from image aspect ratio - Columns and rows calculated to match piece count - Formula: y = sqrt(pieceCount / ratio), cols = ratio × y, rows = y - Grid dimensions adapt to image proportions - Ensures pieces fit image dimensions correctly 23. Piece Positioning: - Pieces positioned on board grid - Grid coordinates: row, column - Position calculation: top = row × scaleSize, left = col × scaleSize - Pieces snap to grid positions - Grid ensures correct piece alignment 24. Border Detection: - Border pieces identified by edge borders - Border piece: top OR right OR bottom OR left = 0 (straight edge) - Border pieces marked with "border" class - Border-only mode filters to show only border pieces - Useful for assembling puzzle frame first 25. Neighbor Finding: - System finds neighboring pieces for snapping - Checks adjacent positions (top, right, bottom, left) - Compatible neighbors identified by position - Pieces snap to neighbors when borders match - Neighbor finding enables automatic grouping 26. Completion Tracking: - Tracks completed puzzles per category - Shows completion count (e.g., "5/40 completed") - Completion percentage per category pack - Visual indicators for completed puzzles - Completion badges on puzzle selection 27. Image Loading: - Puzzle images loaded from images folder - Image path: images/{category}/{number}.jpg - Images loaded when puzzle selected - Preview uses same image source - Error handling for missing images 28. UI Elements: - Header: MysticByte Studios logo, menu buttons, score display - Score display: Placed pieces, total pieces, percentage, timer - Selection screen: Category tabs, puzzle slider, difficulty selection - Game board: Main assembly area - Drawer: Piece storage areas (primary/secondary) - Preview overlay: Complete image display - Pause overlay: Pause dialog - Congratulations overlay: Completion dialog STRATEGIC TIPS: - Border First Strategy: Use border-only mode to assemble puzzle frame first. Starting with edges provides structure and makes interior easier. - Preview Reference: Use preview mode to understand puzzle layout. Referencing complete image helps identify piece locations. - Group Assembly: Assemble smaller groups on table before placing on board. Connecting pieces into sets speeds up assembly. - Color Matching: Look for color and pattern matches when placing pieces. Visual cues help identify correct piece positions. - Split View Organization: Use split drawer to organize pieces. Separate areas help categorize pieces by region or color. - Neighbor Awareness: Pay attention to piece borders. Understanding border shapes helps identify compatible neighbors. - Progress Tracking: Monitor completion percentage. Tracking progress motivates completion and helps plan strategy. - Pause for Breaks: Use pause feature for breaks. Pausing prevents timer from continuing and preserves progress. - Difficulty Progression: Start with 50 pieces to learn mechanics. Progress to higher difficulties as skill improves. - Piece Identification: Study piece shapes and images. Familiarity with piece characteristics improves placement speed. ADVANCED TECHNIQUES: - Set Building: Master building large sets before board placement. Efficient set creation accelerates puzzle completion. - Pattern Recognition: Develop pattern recognition for piece matching. Recognizing common patterns speeds up assembly. - Strategic Pausing: Pause strategically to plan assembly. Brief pauses help organize thoughts and plan next moves. - Border Assembly Mastery: Perfect edge assembly technique. Fast border completion establishes puzzle foundation. - Visual Memory: Develop visual memory for piece locations. Remembering piece positions enables faster placement. - Efficient Dragging: Minimize unnecessary piece movements. Efficient dragging reduces time and effort. - Split Organization: Master split drawer organization techniques. Effective organization improves piece access speed. - Completion Optimization: Optimize completion time through strategy. Efficient techniques reduce total completion time. - Multi-Puzzle Strategy: Develop strategies across different categories. Category-specific approaches improve performance. - Expert Difficulty Mastery: Master 500-piece puzzles through practice. Expert puzzles test advanced skills and patience. WINNING AND PROGRESSION: - Puzzle Completion: Complete individual puzzles to mark as done. Each completed puzzle unlocks progress tracking. - Category Completion: Complete all puzzles in a category. Category completion demonstrates mastery of puzzle type. - Difficulty Mastery: Complete puzzles at all difficulty levels. Difficulty mastery shows skill progression. - Perfect Completion: Complete puzzles with optimal time. Fast completion demonstrates efficient strategy. - Achievement Collection: Complete all 320 puzzle configurations. Full completion represents ultimate achievement. - Progress Tracking: Monitor completion percentage across all puzzles. Progress tracking motivates continued play. - Time Improvement: Improve completion times through practice. Time improvement demonstrates skill development. - Strategy Development: Develop personal puzzle-solving strategies. Effective strategies improve performance. - Pattern Mastery: Master recognizing patterns across puzzle types. Pattern mastery accelerates assembly. - Ultimate Challenge: Complete all puzzles at expert (500 piece) difficulty. Expert completion represents highest achievement level. Enjoy assembling beautiful jigsaw puzzles and mastering the art of puzzle completion!