# Reel Royale – Multi-Slot Casino-Plattform

Modulare Browser-Slot-Plattform mit **6 themenbasierten Spielautomaten**, gemeinsamer
Casino-Lobby, serverautoritativer Spiel-Engine und vollständig synthetischen Assets
(Emoji-Symbole, Web-Audio-Sounds, CSS/Canvas-Grafik) – **keine urheberrechtlich
geschützten Inhalte**.

Die Spiele orientieren sich mechanisch/optisch an bekannten Klassikern, nutzen aber
ausschließlich eigene Namen, Symbole und Grafiken.

---

## 1. Schnellstart

* Aufruf: `…/slots/` (leitet zu `login.php`, falls nicht eingeloggt)
* Login/Registrierung teilen sich Datenbank & Spielerkonten mit der Alt-Installation
  unter `/slot` (Tabellen `users`, `spins`, `jackpots` in `arni_shopping`).
* Voraussetzungen: PHP 7.3+, MySQL/MariaDB, moderner Browser (ES-Module, Web Audio,
  Canvas, `aspect-ratio`).

---

## 2. Architektur

```
slots/
├── index.php              SPA-Shell: Lobby + Spiel (eine Seite, kein Reload-Wechsel)
├── login/register/logout/highscores.php
├── config.php             DB- & App-Konfiguration
├── includes/
│   ├── bootstrap.php       lädt db, functions, auth, engine, registry
│   ├── db.php  auth.php  functions.php
│   └── engine.php          generische Slot-Engine (Multi-Game-Mathematik)
├── games/
│   ├── registry.php        Spielregister + Symbol-Builder + Monte-Carlo-Simulator
│   ├── ancient_explorer.php … phoenix_ascent.php   (6 Spiel-Definitionen)
│   └── _tune.php           CLI-RTP-Tuner (nicht öffentlich)
├── api/
│   ├── spin.php            serverautoritativer Spin (CSRF, Transaktion)
│   └── daily_bonus.php
├── css/  core.css · themes.css · animations.css
└── js/
    ├── main.js             Bootstrap / Verdrahtung
    ├── util.js
    ├── engine/
    │   ├── GameEngine.js        Ablauf-Orchestrator
    │   ├── ReelEngine.js        Walzen (Accel, Blur, Bounce, Klick-Stopp)
    │   ├── AnimationEngine.js   Gewinnlinien, Highlights, Counter, Win-Stufen
    │   ├── AudioEngine.js       synth. SFX + Musik pro Spiel, Lautstärke
    │   ├── ParticleEngine.js    Canvas: Sand/Funken/Feuer/Wasser/Konfetti/Coins
    │   ├── BonusEngine.js       animiertes Bonusrad
    │   ├── FreeSpinEngine.js    Freispiel-Flow & Overlays
    │   └── StatisticsEngine.js  Sitzungsstatistik (Dev-Panel)
    └── ui/
        ├── Lobby.js  GameUI.js  DevPanel.js
```

**Serverautorität:** Jeder Spin wird komplett in `api/spin.php` berechnet (Grid,
Gewinne, Freispiele, Features, Balance) – inkl. CSRF-Token und DB-Transaktion mit
`SELECT … FOR UPDATE`. Der Client animiert nur das gelieferte Ergebnis. Walzengewichte
werden **nicht** an den Client gesendet (Anti-Cheat).

**Eine Engine, sechs Spiele:** `includes/engine.php` ist vollständig konfigurationsgetrieben.
Ein Spiel ist nur ein Daten-Array (Symbole, Gewichte, Auszahlungen, Paylines, Feature).
Dieselbe Engine versorgt Live-Spin und RTP-Simulator – garantiert konsistente Mathematik.

---

## 3. Die 6 Spiele

| # | Spiel | Vorbild-Stil | Feature | Volatilität |
|---|-------|--------------|---------|-------------|
| 1 | **Ancient Explorer** | Book of Ra | Expandierendes Spezialsymbol in Freispielen | Hoch |
| 2 | **El Matador** | El Torero | Zufalls-Multiplikatoren + Bonusrad | Mittel-Hoch |
| 3 | **River Fishing** | Fishing Frenzy | Geldfische + Angler-Sammler | Mittel |
| 4 | **Big Lake Bonanza** | Big Bass Bonanza | Sammler + steigender Multiplikator (×2/×3/×10) | Hoch |
| 5 | **Totem Spirit** | Totem Chief | Wild-Transformation + Multiplikator | Mittel-Hoch |
| 6 | **Phoenix Ascent** | Wings of Phoenix | Walking Wilds + steigender Multiplikator | Hoch |

Alle: 5 Walzen × 3 Reihen, 10 Gewinnlinien, eigenes Theme (Farben, Szene,
Partikel, Musik), eigene Symbolwelt, eigene Paytable.

---

## 4. Mathematik / RTP

Ziel-RTP **96 %**. Jedes Spiel hat einen einzigen Tuning-Regler `pay_scale`
(Skalierung der gesamten Auszahlungstabelle), der per Monte-Carlo-Binärsuche auf den
Ziel-RTP eingestellt wurde.

Simulierte Werte (≥400 000 Spins; hochvolatile Spiele schwanken ±1–2 %):

| Spiel | gemessene RTP | Hit-Frequency | Freispiel-Rate | Ø Freispiele |
|-------|--------------:|--------------:|---------------:|-------------:|
| Ancient Explorer | ~95,6 % | 16 % | 1 / 311 | 10,2 |
| El Matador       | ~97,6 % | 21 % | 1 / 518 | 8,2 |
| River Fishing    | ~95,3 % | 29 % | 1 / 508 | 10,4 |
| Big Lake Bonanza | ~95,7 % | 29 % | 1 / 481 | 10,4 |
| Totem Spirit     | ~94,4 % | 22 % | 1 / 524 | 10,2 |
| Phoenix Ascent   | ~97,2 % | 22 % | 1 / 474 | 8,3 |

Neu tunen (CLI):

```bash
php games/_tune.php ancient_explorer 0.96 200000
```

schreibt den optimalen `pay_scale` direkt in die Spieldatei zurück.

---

## 5. Features

* **Casino-Lobby** mit animierten Spielkarten (Vorschau, RTP, Volatilität, Feature-Tags).
* **Spielwechsel ohne Neuladen** (Single-Page).
* **Walzen-Engine**: Beschleunigung, Bremskurve, Motion-Blur, Bounce, GPU-Transform,
  Klick-auf-Walze-Stopp.
* **Gewinnstufen**: Small · Nice · Big · Mega · Epic mit Counter-Animation,
  Goldregen, Konfetti, Lichtblitzen.
* **Audio** pro Spiel: synthetische Hintergrundmusik + 9 SFX, Mute & Lautstärkeregler.
* **Partikel** (Canvas) je Theme: Sand, Glut, Blasen, Blätter, Funken, Feuer + Coins/Konfetti.
* **Auto-Spin** 10/25/50/100/250/500 mit Auto-Stopp bei Freispiel, Bonus, Big Win.
* **Freispiele** mit Pflicht-Overlays (Start, Retrigger, Ende) und Feature je Spiel.
* **Bonusrad** (El Matador) – serverbestimmtes Ergebnis, clientseitig animiert.
* **Responsive** für Desktop/Tablet/Smartphone, Touch-optimiert, kein H-Scroll.
* **Dev-Panel** (`Strg`+`Shift`+`D`): Spins, Freispiele, Trigger, Hit-Frequency,
  Live-RTP, Auszahlungen – pro Spiel, in `localStorage` gespeichert.

---

## 6. Roulette (Europäisch, Single Zero)

Vollständig integrierter Roulette-Bereich, erreichbar über die Lobby-Kategorie
„🎲 Tische". Serverautoritäre Mathematik, modulare ES-Module, geteiltes Guthaben mit
den Slots.

### 6.1 Geänderte Dateien
- `index.php` – Roulette-Screen-Markup, `css/roulette.css`-Link, `boot.roulette`
- `includes/bootstrap.php` – lädt `roulette.php`
- `js/main.js` – Roulette-Module instanziiert & verdrahtet
- `js/ui/Lobby.js` – Kategorien + Roulette-Karte (`onRoulette`)
- `js/ui/GameUI.js` – `showRoulette()`, Navigation, geteiltes Guthaben
- `js/engine/AudioEngine.js` – Sounds: `chip`, `chipOff`, `rlStart`, `ballRoll`, `ballDrop`
- `js/util.js` – gemeinsamer `toast()`
- `css/core.css` – Lobby-Kategorie-Überschriften

### 6.2 Neue Dateien
- `includes/roulette.php` – Rad, Farben, 157 legale Wetten, Resolver, RNG
- `api/roulette.php` – serverautoritärer Dreh (CSRF, Transaktion)
- `css/roulette.css` – Tisch, Kessel, Chips, Statistik
- `js/engine/RouletteEngine.js` – Ablauf-Orchestrator
- `js/engine/WheelEngine.js` – animierter Kessel + Kugel (Canvas)
- `js/engine/ChipManager.js` – Jeton-System (1–1000)
- `js/engine/BetManager.js` – Einsatzverwaltung (place/undo/double/repeat/clear)
- `js/engine/StatisticsManager.js` – Historie, Verteilungen, Heatmap
- `js/ui/RouletteUI.js` – Tischaufbau, Hit-Zonen, Chips, Controls, Statistik

### 6.3 Roulette-Regeln
- Einzel-Null-Rad mit 37 Fächern, korrekte europäische Reihenfolge
  (`0,32,15,19,4,21,2,25,17,34,…,26`).
- Farben: 18 Rot, 18 Schwarz, 0 = Grün (korrekte Zuordnung).
- 0 lässt alle einfachen Chancen, Dutzende und Kolonnen verlieren (echte Regel).
- Wettarten: Straight, Split, Street, Corner, Six Line, Column, Dozen, Red/Black,
  Even/Odd, Low(1–18)/High(19–36) + 0-Sonderwetten (Splits 0/1·0/2·0/3, Trios
  0-1-2 & 0-2-3, First Four 0-1-2-3).

### 6.4 Auszahlungslogik
Auszahlung = `Einsatz × (Ratio + 1)` bei Treffer (Einsatz + Gewinn), sonst 0.

| Wette | Ratio | Zahlen | Wette | Ratio | Zahlen |
|---|---|---|---|---|---|
| Straight | 35:1 | 1 | Six Line | 5:1 | 6 |
| Split | 17:1 | 2 | Column | 2:1 | 12 |
| Street | 11:1 | 3 | Dozen | 2:1 | 12 |
| Corner | 8:1 | 4 | Red/Black/Even/Odd/Low/High | 1:1 | 18 |

**RTP = 36/37 = 97,30 %** für jede Wettart (faire Single-Zero-Auszahlung) –
per Monte-Carlo bestätigt. Berechnung vollständig serverautoritär: der Client
sendet nur `[{betId, amount}]`, der Server schlägt die Wette in der kanonischen
Liste nach (kein Forgen von Zahlen-Sets möglich).

### 6.5 Architektur
Server (`includes/roulette.php`) ist die *einzige Wahrheit* für Rad, Farben,
legale Wetten und Auszahlungen und emittiert eine gewichtsfreie Client-Config.
Module exakt wie gefordert: `RouletteEngine`, `WheelEngine`, `ChipManager`,
`BetManager`, `StatisticsManager`, `RouletteUI`. Die Auto-/Wiederhol-Logik liegt
im `BetManager` (Einsätze) bzw. `RouletteEngine` (Ablauf) – sauber getrennt.
Die Slot-Architektur ist unverändert.

### 6.6 Mobile-Optimierungen
- Kessel über der Tabelle gestapelt (`@media ≤880px`), Wheel skaliert per
  `aspect-ratio` + `clientWidth`.
- Tisch in horizontal scrollbarem Container (`overflow-x:auto`) – nur die Tabelle
  scrollt, nie die Seite; Touch-optimiert (`-webkit-overflow-scrolling`).
- Kleinere Chips/Buttons unter 560px; Hit-Zonen als Touch-Targets.
- Canvas mit DPR-Begrenzung (≤2) für scharfe, performante Darstellung.

### 6.7 Bekannte Schwachstellen
- Inside-Hit-Zonen sind 22 px – auf sehr kleinen Displays fummelig (Touch-Genauigkeit).
- Geteiltes Guthaben Slot↔Roulette wird beim Screen-Wechsel synchronisiert; bei
  gleichzeitigen Tabs ist der Server maßgeblich (jede Antwort liefert die
  autoritative Balance), kurzzeitige Anzeige-Divergenz möglich.
- Kessel-Animation ist *visuell* glaubwürdig, nicht physikalisch exakt
  (Ergebnis steht serverseitig vorher fest).
- Roulette-Runden teilen sich die `spins`-Tabelle (`mode_name='roulette'`,
  Gewinnzahl in `scatter_count`) – kein eigenes Schema.
- Bei Font-Nachladen werden Zonen via `document.fonts.ready` neu vermessen; in
  sehr seltenen Fällen kann ein erster Klick vor dem Re-Layout minimal daneben liegen.

---

## 7. Administrationsbereich (`admin.php`)

Geschützter Bereich, erreichbar nur für Benutzer in `config.php → admins`
(aktuell `nicomanhattan`). Link erscheint als ⚙ in der Top-Bar nur für Admins.

**Funktionen:**
- **Guthaben bearbeiten** – absolut setzen oder Betrag gutschreiben/abziehen (`± Buchen`).
- **Freispiele setzen** – pro Spieler.
- **Spieler sperren/entsperren** – `banned`-Flag; gesperrte Spieler können sich nicht
  einloggen und Spin-/Roulette-API werden serverseitig abgewiesen. Selbstsperre verhindert.
- **Spielwahrscheinlichkeiten (allgemein)** – globaler Faktor + Faktor je Slot (0,50–1,30),
  der den `pay_scale` und damit direkt die RTP skaliert (live als „effektive RTP" angezeigt).
  Gespeichert in Tabelle `slot_settings`, zur Laufzeit in `all_games()` angewandt.
- **Gewinnfaktor je Spieler** – spielerindividuelle Gewinnwahrscheinlichkeit (Spalte
  `users.rtp_factor`, Standard 1,00 für alle, Bereich 0,20–2,00). Wirkt auf **Slots**
  (`pay_scale` in `api/spin.php`) **und Roulette** (Auszahlung in `api/roulette.php`),
  multipliziert mit den allgemeinen Faktoren. Roulette ist bei Faktor 1,00 fair (97,3 %).

**Technik:**
- Auth: `is_admin()` / `require_admin()` (Benutzername-Whitelist).
- Alle Aktionen serverseitig per **POST mit CSRF-Token** + **PRG-Pattern** (kein Resubmit).
- DB: Spalte `users.banned TINYINT`, Tabelle `slot_settings (skey, sval)`.
- Helfer in `includes/admin.php`, Ban-Enforcement in `require_login()`, `login.php`,
  `api/spin.php`, `api/roulette.php`.

**Bekannte Schwachstellen:** Admin-Rolle per Benutzernamen-Whitelist (kein Rollen-System);
RTP-Faktor wirkt erst beim nächsten Request (Static-Cache pro Request); kein Audit-Log der
Admin-Aktionen.

---

## 8. Sicherheit / Hinweise

* CSRF-Token für alle schreibenden API-Aufrufe.
* Einsatz, Linien und Spiel-ID werden serverseitig validiert.
* Freispiele sind an ihr Spiel gebunden (kein Wechsel mit offenen Freispielen).
* Reine Spielgeld-Anwendung (Coins), keine Echtgeld-Funktion.