126 lines
6.3 KiB
Markdown
126 lines
6.3 KiB
Markdown
# Quartiles — Daily Word Fragment Puzzle Game
|
||
|
||
A sleek, Apple News+ inspired webapp clone of the addictive word puzzle game **Quartiles**. Combine letter tiles into words, discover the 5 hidden 4-tile Quartiles, claim the massive 40-point completion bonus, and climb the ranks from Novice to Expert!
|
||
|
||
|
||
|
||
|
||
|
||
---
|
||
|
||
## 🎮 How to Play
|
||
|
||
1. **The Board**: You are presented with a **4×5 grid of 20 letter tiles**. Each tile contains a 2 to 4 letter fragment (morpheme, syllable, or root).
|
||
2. **Build Words**: Tap 1, 2, 3, or 4 tiles in sequence to construct valid English words.
|
||
3. **Submit**: Tap the **✓ ENTER** button (or press `Enter` on your keyboard) to validate.
|
||
4. **Tile Reusability**: Tiles stay on the board and can be reused to form as many different words as possible!
|
||
|
||
### 🏆 Points System
|
||
|
||
| Tile Count | Type | Points |
|
||
| :---: | :---: | :---: |
|
||
| **1 Tile** | Single-fragment word | **1 pt** |
|
||
| **2 Tiles** | Compound word | **2 pts** |
|
||
| **3 Tiles** | Multi-part word | **4 pts** |
|
||
| **4 Tiles** | **"Quartile"** (Target word) | **8 pts** |
|
||
|
||
### ✨ The 40-Point Quartiles Bonus
|
||
Every puzzle contains **5 target 4-tile Quartiles**. Finding all 5 target Quartiles awards an instant **40-point completion bonus** with celebratory confetti!
|
||
|
||
### 📈 Ranks & Tiers
|
||
- **Novice**: 0 – 24 pts
|
||
- **Apprentice**: 25 – 49 pts
|
||
- **Builder**: 50 – 69 pts
|
||
- **Artisan**: 70 – 84 pts
|
||
- **Wordsmith**: 85 – 99 pts
|
||
- **Expert**: **100+ pts** *(The primary daily milestone!)*
|
||
- **Perfect**: 100% of all constructible words found on the board!
|
||
|
||
---
|
||
|
||
## 🌟 Key Features
|
||
|
||
- **Apple News+ Inspired Aesthetics**: Crisp typography, frosted glass (`backdrop-filter: blur`), curated color palettes, tactile tile presses, and smooth animations.
|
||
- **Dark Mode & Light Mode**: Seamless toggle matching iOS system styling.
|
||
- **Auto-Lock Solved Quartiles**: Toggle locking to automatically pin found 4-tile Quartiles in neat rows at the top of the grid with padlock badges, while allowing remaining tiles to shuffle freely.
|
||
- **Shuffle & Sort A-Z**: Reorder unlocked tiles to spot new combinations or sort them alphabetically.
|
||
- **Interactive Words Found Drawer**: Filter solved words by tile count (*All, Quartiles, 3-Tiles, 2-Tiles, 1-Tile*), view point values, and tile fragment breakdowns.
|
||
- **Progressive Hint System**: Contextual hints guiding you to unfound Quartiles and words without spoiling the puzzle.
|
||
- **Daily Puzzles & Archive**: A new generated puzzle every day (seeded by date, so everyone gets the same board), with the last three weeks available in the calendar.
|
||
- **Unlimited Random Mode**: Instant on-the-fly puzzle generator yielding infinite unique playable boards.
|
||
- **Custom Puzzle Creator & Sharing**: Create your own puzzle using 5 custom four-tile words and share with friends via URL hash.
|
||
- **Tactile Web Audio Feedback**: Realistic acoustic clicks, pops, harmonious chords, and celebratory fanfare built using the native Web Audio API (0 external sound files needed).
|
||
- **Canvas Confetti**: High-performance canvas particle system for Quartile and Expert victories.
|
||
- **Keyboard Shortcuts**:
|
||
- `Enter`: Submit constructed word
|
||
- `Backspace`: Remove last tile from tray
|
||
- `Escape`: Clear active tray
|
||
- `Spacebar`: Shuffle board tiles
|
||
- **Progress Persistence**: Automatically saves your game progress, score, and solved words in `localStorage`.
|
||
|
||
---
|
||
|
||
## 🚀 Getting Started
|
||
|
||
### Prerequisites
|
||
- Node.js (v18+)
|
||
- npm
|
||
|
||
### Installation & Local Run
|
||
```bash
|
||
# Install dependencies
|
||
npm install
|
||
|
||
# Start development server
|
||
npm run dev
|
||
|
||
# Open your browser at http://localhost:5173
|
||
```
|
||
|
||
### Production Build
|
||
```bash
|
||
npm run build
|
||
npm run preview
|
||
```
|
||
|
||
---
|
||
|
||
## 📁 Project Structure
|
||
|
||
```
|
||
quartiles/
|
||
├── index.html # App shell with SEO and viewport configuration
|
||
├── package.json # Scripts and dependencies (Vite)
|
||
├── src/
|
||
│ ├── main.js # App bootstrap, event wiring, keyboard handlers
|
||
│ ├── styles/
|
||
│ │ ├── main.css # Design tokens, variables, typography, reset
|
||
│ │ ├── board.css # 4x5 grid layout, tactile tiles, active builder
|
||
│ │ └── components.css # Score bar, action buttons, drawer, modals
|
||
│ ├── components/
|
||
│ │ ├── Header.js # Brand title, date badge, utility controls
|
||
│ │ ├── ScoreRankBar.js # Score, rank progression, 5-segment Quartiles tracker
|
||
│ │ ├── WordBuilder.js # Construction tray with drag & drop reorder
|
||
│ │ ├── TileGrid.js # 20-tile responsive board with locked rows
|
||
│ │ ├── ActionBar.js # Shuffle, Sort A-Z, Lock Quartiles, Hint
|
||
│ │ ├── WordsDrawer.js # Categorized found words bottom sheet
|
||
│ │ ├── Modals.js # How to Play, Calendar, Builder, Stats, Settings
|
||
│ │ ├── Toast.js # Spring floating notifications
|
||
│ │ └── UpdateBanner.js # "New version available" reload prompt
|
||
│ ├── data/
|
||
│ │ ├── puzzles.js # Target word pool (all puzzles are generated from it)
|
||
│ │ └── lexicon.js # SCOWL recognized English vocabulary set
|
||
│ ├── version.json # App version (bumped by the pre-commit hook)
|
||
│ └── engine/
|
||
│ ├── solver.js # Tree-pruning word solver and rank calculator
|
||
│ ├── generator.js # Daily (seeded), unlimited and custom puzzle generator
|
||
│ ├── daily.js # Daily puzzle lookup and calendar list
|
||
│ ├── version.js # Polls /version.json for new deploys
|
||
│ ├── audio.js # Web Audio API acoustic synthesizer
|
||
│ └── confetti.js # Canvas particle confetti engine
|
||
└── scripts/
|
||
├── build-all-data.mjs # Builds the target word pool (src/data/puzzles.js)
|
||
├── build-client-lexicon.mjs
|
||
└── bump-version.mjs # Version bump (run by .githooks/pre-commit)
|
||
```
|