<div align="center">

<a name="readme-top"></a>

Minesweeper Engine

A zero-dependency, high-performance Minesweeper engine implementing recursive QuadTree spatial partitioning and bit-packed state management for deterministic 1,000,000+ (One Million+) node grid simulation.

Source Code  ·  Technical Specification  ·  Architectural Research  ·  Live Demo

<br> <a href="https://amey-thakur.github.io/MINESWEEPER/"> <img src="screenshots/grid_simulation_1m.png" alt="Minesweeper Engine" width="90%"> </a> </div>

---

<div align="center">

Author  ·  Overview  ·  Features  ·  Structure  ·  Results  ·  Quick Start  ·  Usage Guidelines  ·  License  ·  About

</div>

---

<!-- AUTHOR --> <div align="center">

<a name="author"></a>

Author

| <a href="https://github.com/Amey-Thakur"><img src="https://github.com/Amey-Thakur.png" width="150" height="150" alt="Amey Thakur"></a><br>Amey Thakur<br><br> | | :---: |

</div>

---

<!-- OVERVIEW -->

<a name="overview"></a>

Overview

Minesweeper Engine is a technical study in optimized spatial simulation, built to handle extremely large grid systems while guaranteeing that every generated board is logically solvable. Instead of standard 2D arrays, this engine uses a recursive QuadTree structure to index millions of cells, allowing a stateless Canvas renderer to draw only the visible portion of the grid at high frame rates.

[!IMPORTANT]

📑 Architectural Research and Analysis

For a comprehensive technical analysis covering recursive spatial partitioning, bit-packed state management, and coordinate virtualization, refer to the RESEARCH.md document. This report provides a granular examination of the engine's core innovations and architectural performance.

[!NOTE]

💣 Defining Minesweeper Engine Architecture

In this project, "high-performance" refers to the ability to simulate millions of interactive elements without being limited by the browser's DOM performance. By using bit-packed data structures and a QuadTree for spatial indexing, the engine can manage a 1,000,000+ (One Million+) cell grid. This approach keeps the interface responsive and ensures that rendering performance remains stable, regardless of the total board size.

The repository serves as a practical implementation of spatial partitioning and constraint logic, delivered as a Progressive Web App (PWA) for native-like performance in the browser.

Simulation Heuristics

The engine follows specific system design patterns to maintain stability:

• Spatial Partitioning: The engine uses a QuadTree to filter grid data, processing only the cells near the user's viewport.
• CSP Logic: To avoid "guessing," the system includes a Constraint Satisfaction Problem (CSP) solver that checks the board during generation and ensures a logical path to completion exists.
• Decoupled Rendering: The logic engine and the drawing pipeline are separated, ensuring that complex calculations don't block the visual updates.

[!TIP]

Performance and Logic Synchronization

To maintain high execution speeds, the engine uses a multi-stage logic pipeline. Latent filters refine the state stream before it reaches the renderer, and bitwise weights are used to manage cell states and visualize the board's logic. This ensures that the user's interactions are processed instantly and remain synchronized with the underlying simulation, even when the grid is massive.

---

<!-- FEATURES -->

<a name="features"></a>

Features

| Feature | Description | |---------|-------------| | QuadTree Core | Combines Recursive Partitioning with Viewport Culling for comprehensive grid management. | | PWA Architecture | Implements a robust standalone installable interface for immediate spatial simulation study. | | Academic Clarity | In-depth and detailed comments integrated throughout the codebase for transparent logic study. | | Technical Library | Seamlessly integrated in-app documentation providing immediate access to algorithmic and architectural insights. | | Neural Topology | Efficient Decoupled Engine execution via Bit-Packed TypedArrays for native high-performance access. | | Inference Pipeline | Asynchronous architecture ensuring stability and responsiveness on local clients. | | Visual Feedback | Interactive Status Monitors that trigger on state events for sensory reward. | | State Feedback | Bitmask-Based Indicators and waveform effects for high-impact retro feel. | | Social Persistence | Interactive Footer Integration bridging the analysis to the source repository. |

[!NOTE]

Interactive Polish: The Procedural Singularity

We have engineered a Logic-Driven State Manager that calibrates board scores across multiple vectors to simulate human-like difficulty scaling. Beyond pure simulation, a Technical Library is integrated directly within the desktop environment to provide quick, in-situ documentation of the engine's recursive architecture and spatial logic.

Tech Stack

• Language: Vanilla JavaScript (ES6 Modules)
• Logic: Neural-Level Spatial Pipelines (QuadTree & BFS)
• Data Structures: Bit-Packed TypedArrays (Uint8Array & Uint32Array)
• UI System: Modern Design System (Win95 Aesthetics & Custom CSS)
• Deployment: Local execution / GitHub Pages
• Architecture: Progressive Web App (PWA)

---

<!-- STRUCTURE -->

<a name="project-structure"></a>

Project Structure

MINESWEEPER/
│
├── .github/                            # Global GitHub configuration & workflows
├── docs/                               # Formal academic & technical documentation
│   └── SPECIFICATION.md                # System engineering & architectural roadmap
│
├── screenshots/                        # High-fidelity visual verification gallery
│   ├── grid_simulation_1m.png          # 1,000,000+ (One Million+) node spatial visualization
│   ├── desktop_interface.png           # Pixel-perfect Windows 95 shell landing
│   ├── about_engine_dialog.png         # Technical engine specification oversight
│   ├── quadtree_docs_notepad.png       # Recursive spatial partitioning theory
│   ├── complexity_analysis_notepad.png # Algorithmic complexity benchmarks
│   ├── seed_manager_sharing.png        # Deterministic board state sharing
│   ├── shutdown_screen.png             # OS termination & shutdown sequence
│   ├── gameplay_initial.png            # Initial engine state verification
│   ├── game_menu_options.png           # Difficulty & utility menu overview
│   └── ...                             # Supplemental UI/UX state screenshots
│
├── Source Code/                        # Integrated simulation application layer
│   ├── assets/                         # Global system resources & static icons
│   ├── css/                            # Thematic design & Win95 styling indices
│   │   ├── win95.css                   # Core shell aesthetic & layout tokens
│   │   ├── game.css                    # Engine-specific interactive styles
│   │   └── reset.css                   # Low-level browser normalization
│   ├── img/                            # High-resolution visual foundation assets
│   ├── js/                             # Decoupled ES6 modular logic engine
│   │   ├── engine/                     # Backend computational logic & state
│   │   │   ├── QuadTree.js             # Spatial partitioning core engine
│   │   │   ├── CSPSolver.js            # Constraint Satisfaction Problem logic
│   │   │   ├── BoardEngine.js          # Bit-packed state & memory management
│   │   │   ├── FloodFill.js            # Iterative BFS traversal logic
│   │   │   └── SeedRNG.js              # Deterministic Mulberry32 generator
│   │   ├── renderer/                   # Hardware-accelerated Canvas pipelines
│   │   │   ├── GameRenderer.js         # Stateless frame reconstruction logic
│   │   │   ├── Camera.js               # Viewport virtualization bridge
│   │   │   └── SpriteSheet.js          # Pixel-perfect unit memory buffers
│   │   ├── ui/                         # Interaction & shell control system
│   │   │   ├── UIController.js         # System window & taskbar orchestrator
│   │   │   ├── DocController.js        # Integrated library logic manager
│   │   │   ├── MenuController.js       # Global menu & routing logic
│   │   │   ├── ScoreController.js      # Stat tracking & scoreboard management
│   │   │   ├── SeedController.js       # Board seed & PRNG configuration
│   │   │   ├── TimerController.js      # Performance-safe system timing
│   │   │   ├── ConsoleBranding.js      # Developer attribution & signature
│   │   │   └── WindowDragger.js        # Desktop interaction management
│   │   └── main.js                     # Root entry-point & system bootloader
│   ├── index.html                      # System entrance & PWA bootstrap index
│   ├── manifest.json                   # Web Applicatio