# Breakout 3D (HTML5 / Three.js)

A modern 3D take on the classic Breakout, built with JavaScript, Three.js, and a lightweight PHP API for a persistent leaderboard.

## Features

- 3D gameplay (paddle, balls, bricks) with particles, trails, and camera effects
- Multiple difficulties: Easy, Normal, Hard (per-difficulty best score tracking)
- Level progression with descending brick rows and multi-hit bricks
- Power-ups (with timers and badges):
  - Enlarge, Multiball (5×), Slow Motion, Shield, Sticky, Laser
  - Extra Life, Magnet (pulls drops), Ghost (pass-through bricks), x2 Multiplier
  - Auto-Laser (auto fires while active)
- Combo scoring with decay
- Sound + optional haptics, light/dark theme
- Settings persistence (theme, sound, haptics, shake, difficulty, name, volume, speed/drop tuning)
- Autosave/restore game state and best score/time
- Leaderboard (Top 10) with medals and difficulty filter
  - Unique names enforced server-side; same device keeps name, different devices get numerical suffixes
  - One best entry per device per difficulty (updates instead of duplicates)
- Responsive/mobile-friendly UI: Stats drawer, touch controls (Left/Right/Fire), fullscreen

## Quick start

1. Make sure you have a PHP-capable server (e.g., Laragon/XAMPP/WAMP on Windows, MAMP on macOS, or PHP built-in server).
2. Place this folder under your web root, e.g. `C:\laragon\www\games\html5-games\breakout\game`.
3. Ensure the `data` directory is writable by PHP (for `data/scores.json`). On Linux/macOS you may need:
   - `chmod -R 0777 data` (or a more restrictive permission that allows webserver write)
4. Visit the game URL in your browser, e.g. `https://rskworld.in/games/html5-games/breakout/index.php`.

If you cannot run PHP, the game still runs, but server-backed leaderboard will not work.

## Controls

- Mouse/touch: Move the paddle horizontally
- Keyboard: `◀ / ▶` (Left/Right) to move, `Space` to pause, `F` to fire lasers
- Mobile: On-screen buttons (Left / Fire / Right)

## Tuning & Settings (saved locally)

Top bar controls:

- Difficulty: Easy / Normal / Hard
- Volume: 0–100%
- Speed: Global ball speed multiplier
- Drops: Power-up drop rate
- Haptics: Vibrations on supported devices
- Shake: Camera shake effect toggle
- Theme: Dark/Light
- Name: Player display name (used for leaderboard)

These persist to LocalStorage and are restored on reload.

## Leaderboard API

- Location: `api/scores.php`
- Storage: `data/scores.json` (JSON array)

### GET (Top N)

```
GET /api/scores.php?limit=10&difficulty=hard
```

- `limit` (optional): 1–100, default 10
- `difficulty` (optional): `easy|normal|hard` (filter)

Response: JSON array of entries:

```
[{"name":"Samser","score":198,"timeMs":24941,"difficulty":"easy","clientId":"...","ts":1757241770}, ...]
```

### POST (Submit score)

Body (JSON):

```
{
  "name": "Player",
  "score": 536,
  "timeMs": 73220,
  "difficulty": "hard",
  "clientId": "<persistent-client-id>"
}
```

Behavior:
- Enforces unique names across different devices (adds numeric suffix like `rima2` if needed)
- Same device/browser (same `clientId`) keeps the base name
- Keeps one best entry per device per difficulty (updates only if score is higher, or equal score with better time)

Response:

```
{"ok": true, "name": "FinalName", "updated": true}
```

## Project structure

```
game/
  index.php           # Main page and UI
  css/
    styles.css        # Styles (responsive, themes, HUD, drawer)
  js/
    main.js           # UI wiring, settings, leaderboard, start/pause
    engine.js         # Three.js engine, physics, collisions, power-ups
    powerups.js       # Power-up definitions & helpers
    audio.js          # WebAudio + haptics
    storage.js        # LocalStorage helpers
  api/
    scores.php        # PHP API for leaderboard (GET/POST)
  data/
    scores.json       # Leaderboard storage (JSON)
```

## Customization

- Contact/branding: update the footer in `index.php`
- Default difficulty: controlled by the Difficulty dropdown; it is passed into the engine
- Power-up drop rate / speed defaults: see the top bar sliders (and `engine.js` for defaults)

## Troubleshooting

- Leaderboard not saving: ensure PHP is running and `data/scores.json` is writable by the webserver
- Name suffix unexpectedly added: another device/browser already uses that name; this device will be suffixed to remain unique
- Colors look wrong after reload: click Reset to clear autosave (state/best are in LocalStorage)

## License

MIT (or your chosen license)

## Support / Business

For support, licensing, or custom development:

- Email: help@rskworld.in
- Phone/WhatsApp: +91 9330539277
- Website: https://rskworld.in