137 lines
5.5 KiB
Markdown
137 lines
5.5 KiB
Markdown
# 🧩 PixelSlide — 15-Puzzle Image Game with PixiJS
|
||
|
||
> A premium sliding puzzle game built with **PixiJS v8**, Vanilla HTML5/CSS3/JavaScript, procedural canvas artwork, soundtrack integration, and a persistent local leaderboard.
|
||
|
||
|
||
|
||
|
||
|
||
|
||
---
|
||
|
||
## ✨ Features
|
||
|
||
- **🖼️ Custom Image Slicing**:
|
||
- Upload any image (PNG, JPG, WebP, GIF) via file picker or drag-and-drop.
|
||
- Automatically center-crops and slices into grid tiles.
|
||
- Comes with 4 built-in procedural gallery presets (*Neon City*, *Deep Galaxy*, *Hex Prism*, *Aurora Peak*) for instant offline play.
|
||
- **🎮 5 Difficulty Levels**:
|
||
- 🐛 **Debug Mode (3×3)**: Starts from solved state and performs 5 non-reversing valid moves (guaranteed solvable in **≤ 5 moves**).
|
||
- 🟢 **Easy (3×3)**: 8 tiles + 1 blank, 30 valid shuffle moves.
|
||
- 🔵 **Medium (4×4)**: Classic 15-puzzle (15 tiles + 1 blank), 100 valid shuffle moves.
|
||
- 🟣 **Hard (5×5)**: 24 tiles + 1 blank, 200 valid shuffle moves.
|
||
- 🔴 **Insane (6×6)**: 35 tiles + 1 blank, 400 valid shuffle moves.
|
||
- **⚡ 100% Solvability Guarantee**:
|
||
- Shuffling simulates valid legal moves from the solved board state to ensure the puzzle is always solvable without parity issues.
|
||
- **🎨 Ultra-Smooth PixiJS v8 Rendering**:
|
||
- High-DPI canvas rendering with hardware acceleration.
|
||
- 60FPS smooth lerp/easing tile sliding animations.
|
||
- **🎵 Sound System & Soundtracks**:
|
||
- Background music ([`assets/sounds/backsound.mp3`](assets/sounds/backsound.mp3)) with auto-looping and browser autoplay-policy handling.
|
||
- Victory fanfare ([`assets/sounds/winner.mp3`](assets/sounds/winner.mp3)) upon solving.
|
||
- Native Web Audio synthesizer for tile slides, clicks, and invalid move bumps.
|
||
- Persistent sound toggle (`🔊` / `🔇`).
|
||
- **🏆 Persistent Leaderboard**:
|
||
- High scores saved in browser `localStorage`.
|
||
- Filterable by difficulty (All, Debug, Easy, Medium, Hard, Insane).
|
||
- Sorted by fastest completion time and least moves made.
|
||
- **💡 Helper Tools & Accessibility**:
|
||
- `#️⃣` **Tile Numbers Toggle**: Overlay numbering (1 to N-1) for challenging abstract images.
|
||
- `👁️` **Ghost Image Hint**: Semi-transparent reference overlay of the full image.
|
||
- `⏱️` **Millisecond-Precision Timer**: Starts on the very first move.
|
||
- `🔄` **Quick Restart**: Re-shuffle the same image and reset stats with one click.
|
||
- `⏸️` **Pause Modal**: Stops the clock when taking a break.
|
||
- `🎉` **Confetti Burst**: Physics-based canvas confetti explosion on victory.
|
||
|
||
---
|
||
|
||
## 📁 Project Structure
|
||
|
||
```
|
||
eigen_vibe_code_competition/
|
||
├── index.html # Main HTML markup, HUD, modals, and screen containers
|
||
├── style.css # Cyber dark theme, glassmorphism, responsive grid, animations
|
||
├── game.js # PixiJS v8 setup, puzzle engine, Web Audio, leaderboard logic
|
||
├── assets/
|
||
│ └── sounds/
|
||
│ ├── backsound.mp3 # Looping background soundtrack
|
||
│ └── winner.mp3 # Victory celebration audio track
|
||
└── README.md # Project documentation
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 How to Run the Project
|
||
|
||
Since the project uses ES6 features and fetches audio assets / PixiJS canvas textures, it should be run through a local HTTP server.
|
||
|
||
### Option 1: Python (Recommended, no installation required)
|
||
|
||
If you have Python installed, run in your terminal:
|
||
|
||
```bash
|
||
# Python 3
|
||
python3 -m http.server 8080
|
||
```
|
||
|
||
Then open your browser at:
|
||
👉 **[http://localhost:8080](http://localhost:8080)**
|
||
|
||
---
|
||
|
||
### Option 2: Node.js (`npx serve` or `npx http-server`)
|
||
|
||
If you have Node.js installed:
|
||
|
||
```bash
|
||
npx serve . -p 8080
|
||
```
|
||
or
|
||
```bash
|
||
npx http-server -p 8080
|
||
```
|
||
|
||
Then open **[http://localhost:8080](http://localhost:8080)**.
|
||
|
||
---
|
||
|
||
### Option 3: VS Code Live Server
|
||
|
||
1. Open the project folder in **Visual Studio Code**.
|
||
2. Install the **Live Server** extension (by Ritwick Dey).
|
||
3. Right-click [`index.html`](index.html) and select **"Open with Live Server"**.
|
||
|
||
---
|
||
|
||
## 🎮 Controls & Shortcuts
|
||
|
||
| Input / Key | Action |
|
||
| :--- | :--- |
|
||
| **Mouse Click / Tap** | Slide adjacent tile into the blank slot |
|
||
| <kbd>↑</kbd> / <kbd>W</kbd> | Move tile below blank upwards |
|
||
| <kbd>↓</kbd> / <kbd>S</kbd> | Move tile above blank downwards |
|
||
| <kbd>←</kbd> / <kbd>A</kbd> | Move tile on right to the left |
|
||
| <kbd>→</kbd> / <kbd>D</kbd> | Move tile on left to the right |
|
||
| <kbd>N</kbd> | Toggle tile number overlays (`#️⃣`) |
|
||
| <kbd>H</kbd> | Toggle ghost image hint (`👁️`) |
|
||
| <kbd>R</kbd> | Quick restart level (`🔄`) |
|
||
| <kbd>M</kbd> | Toggle audio mute (`🔊`/`🔇`) |
|
||
| <kbd>Esc</kbd> | Pause / Resume game (`⏸️`) |
|
||
|
||
---
|
||
|
||
## 🛠️ Technology Stack
|
||
|
||
- **Rendering Engine**: [PixiJS v8.20.0](https://pixijs.com/) via CDN
|
||
- **Structure & Logic**: Vanilla HTML5, Vanilla JavaScript (ES6+ Classes)
|
||
- **Styling**: Vanilla CSS3 (Custom Properties, Glassmorphism `backdrop-filter`, Flexbox, CSS Grid)
|
||
- **Typography**: Google Fonts (*Outfit*, *Inter*)
|
||
- **Audio**: HTML5 Audio API & Web Audio API Synthesizer
|
||
- **Storage**: Browser `localStorage` API
|
||
|
||
---
|
||
|
||
## 📝 License
|
||
|
||
Distributed under the MIT License. Feel free to use and customize for your own projects!
|