# PRD — HARDWARE BATTLE TOUCHSCREEN
> **Tagline:** *Pikir Cepat. Sentuh Tepat. Jadi Juara!*  
> *(Think Fast. Touch Faster. Reach the Finish.)*

---

## 1. Ringkasan Produk
**HARDWARE BATTLE** adalah permainan edukasi interaktif berbasis web seputar perangkat keras (*hardware*) komputer. Permainan ini dirancang khusus untuk dimainkan oleh **2 hingga 4 pemain secara simultan di 1 layar sentuh besar (*Interactive Flat Panel / Smart Board / Touchscreen Display*)**.

Pemain beradu kecepatan dan ketepatan dalam menjawab pertanyaan perangkat keras. Setiap jawaban yang benar akan memacu kendaraan/avatar karakter pemain bergerak maju di lintasan balapan (*race track*). Pemain yang pertama kali mencapai garis finish atau menyelesaikan seluruh target soal dinyatakan sebagai juara balapan.

---

## 2. Target Pengguna & Spesifikasi Perangkat
* **Target Pengguna**: Siswa SMK jurusan TKJ / TJKT / RPL, siswa SMP/SMA kelas Informatika, mahasiswa komputer, serta peserta pelatihan laboratorium.
* **Perangkat Layar**: Layar touchscreen monitor besar, Interactive Flat Panel (IFP), atau Smart Board berukuran 55–86 inci.
* **Orientasi Layar**: Landscape 16:9 (Resolusi 1280×720, 1366×768, 1920×1080 Full HD, hingga 3840×2160 4K).
* **Mode Pemain**: 2, 3, atau 4 pemain di 1 layar fisik yang sama.

---

## 3. Prinsip Desain Utama
1. **THIS IS A GAME, NOT A QUIZ FORM**: Antarmuka bergaya *cyber-arcade* modern yang memicu adrenalin kompetitif, bukan form ujian kertas yang kaku.
2. **Prioritas Alur**: `Fun` → `Fast` → `Visual` → `Competitive` → `Educational` → `Simple`.
3. **Gameplay Loop**: `SEE` → `THINK` → `TOUCH` → `RESULT` → `MOVE` → `NEXT QUESTION` → `RACE` → `FINISH`.
4. **Touchscreen Native**:
   * Seluruh navigasi dan pemilihan jawaban menggunakan sentuhan (*Pointer Events*).
   * **Tidak bergantung pada mouse hover**.
   * Area sentuh (*touch target*) ekstra besar (120–220 px) dengan jarak aman antar-tombol.
   * Mendukung multi-touch simultan (2–4 pemain dapat menekan layar di milidetik yang sama tanpa saling mengunci).

---

## 4. Platform & Arsitektur (Laravel 13, MySQL 8.4 & Offline Fallback)
* **Frontend**: Pure HTML5, CSS3, dan Vanilla JavaScript Modular (Pointer Events Native).
* **Backend & Database**: Terintegrasi penuh dengan **Laravel 13 REST API** dan database **MySQL 8.4** (`table: hardware_questions, game_matches, match_scores`).
* **Content Management**: Dilengkapi antarmuka kelola & input soal baru di `/manage` untuk guru/admin.
* **100% Offline-First Fallback**: Seluruh aset gambar komponen hardware (39 foto lokal beresolusi tajam) dan avatar pemain disimpan secara lokal di dalam folder `assets/hardware/`. Jika jaringan/server terputus, frontend otomatis beralih ke bank soal lokal tanpa error. Efek suara di-generate langsung menggunakan Web Audio API peramban.
* **Bank Soal**: Berisi **46+ Soal Hardware Komputer** lengkap dengan kategori, gambar visual, 4 opsi acak, dan pembahasan edukatif.

---

## 5. Layout & Tampilan Layar Sentuh
* **Top Header — Shared Race Track**: Lintasan balap bersama yang memperlihatkan laju avatar masing-masing pemain menuju garis finish secara real-time.
* **Area Arena Pemain**:
  * **2 Pemain**: Split screen (Player 1 di kiri, Player 2 di kanan).
  * **3 Pemain**: 3 Kolom simetris.
  * **4 Pemain**: Grid 2×2 (masing-masing sudut memiliki panel kendali sendiri).
* Setiap panel pemain memiliki:
  * Avatar & Nama Pemain (Badge P1–P4).
  * Nomor urut soal berjalan.
  * Skor XP & Indikator Combo Streak.
  * Bar Hitung Mundur Timer & Nilai Detik.
  * Kotak Gambar Perangkat Keras & Pertanyaan.
  * 4 Tombol Pilihan Jawaban (A, B, C, D).
  * Banner Umpan Balik / Pembahasan Singkat.

---

## 6. Mekanisme Pengacakan & Anti-Contek (Fair Play System)
1. **Kumpulan Soal Sama (*Fair Pool*)**:
   Jika memilih 10, 20, atau 30 soal, sistem memilih sejumlah soal tersebut dari bank soal master untuk dijadikan *pool pertandingan*. Seluruh pemain akan menyelesaikan himpunan soal yang sama persis.
2. **Urutan Kemunculan Diacak & Digeser (*Non-Overlapping*)**:
   Urutan keluarnya soal ke masing-masing pemain diacak dan dirotasi (*circular shift*).
   * **Tidak ada 2 pemain yang memegang soal yang sama di nomor soal yang sama**.
   * Pemain yang berdiri berdampingan tidak dapat melirik/mencontek layar lawan karena materi yang tampil di detik pertama dan seterusnya berbeda.
3. **Opsi Jawaban (A, B, C, D) Diacak Mandiri**:
   Setiap soal yang tampil pada seorang pemain akan memiliki urutan opsi A, B, C, D yang diacak secara independen. Posisi kunci jawaban selalu berbeda antar pemain.

---

## 7. Sistem Skor, Combo Streak, & Penalti
* **Jawaban Benar**:
  * `+100 XP` (Base XP).
  * `+0 s/d +50 XP` (*Speed Bonus*, proporsional dengan sisa waktu saat tombol ditekan).
* **Sistem Combo Streak (Dapat Dikonfigurasi di Menu Setup)**:
  * **AKTIF (Default)**: Menjawab benar berturut-turut memicu pengali combo:
    * `Combo x2`: +20 XP ekstra
    * `Combo x3`: +40 XP ekstra
    * `Combo x4`: +70 XP ekstra
    * `Combo x5+`: +100 XP ekstra
  * **NONAKTIF**: Mode skor datar tanpa streak untuk sesi belajar santai.
* **Penalti Jawaban Salah (Dapat Dikonfigurasi di Menu Setup)**:
  * Pilihan penalti: `0 XP` (bebas penalti), `-15 XP` (ringan), `-25 XP` (standar PRD), atau `-50 XP` (hardcore).
  * Jawaban salah atau waktu habis akan mereset hitungan combo kembali ke 0.
  * Nilai total skor pemain tidak akan minus (minimum 0 XP).

---

## 8. Pengaturan Permainan (Setup Screen)
Sebelum balapan dimulai, operator/guru dapat mengatur parameter pertandingan:
1. **Jumlah Pemain**: 2 Pemain (Split L-R), 3 Pemain (3 Kolom), atau 4 Pemain (Grid 2×2).
2. **Target Soal**: 10 Soal (Sprint), 20 Soal (Standar), atau 30 Soal (Grand Prix).
3. **Durasi Waktu per Soal**: 5 Detik (Kilat ⚡), 10 Detik (Standar ★), 15 Detik (Santai 🍃), atau 20 Detik (Latihan 🎯).
4. **Sistem Combo Streak**: AKTIF: ON 🔥 vs NONAKTIF: OFF ❌.
5. **Penalti Salah Jawab**: 0 XP, -15 XP, -25 XP, atau -50 XP.
6. **Fitur Audio & Efek**: Toggle Sound ON/OFF dan Efek Partikel ON/OFF.
7. **Identitas Racer**: Kustomisasi nama pemain (Player 1–4).

---

## 9. Struktur File Modul Permainan
Seluruh file game ini terisolasi sepenuhnya di dalam folder `hardware-battle/`:
```text
hardware-battle/
├── PRD.md                       # Dokumen spesifikasi teknis lengkap game ini
├── index.html                   # Entry point aplikasi game
├── css/
│   └── game.css                 # Style arcade touchscreen & layout responsif
├── js/
│   ├── questions.js             # Bank 46 soal & QuestionManager (Hybrid API + Offline)
│   ├── touch.js                 # Pointer events & multi-touch handler
│   ├── timer.js                 # Timer per-pemain presisi performance.now()
│   ├── scoring.js               # Kalkulasi skor, bonus kecepatan, combo, penalti
│   ├── sound.js                 # Web Audio API Sound Synthesizer offline
│   ├── animation.js             # Engine partikel confetti & floating feedback
│   ├── player.js                # State model & UI controller per-pemain
│   └── game.js                  # Game Engine state machine, race controller, & API sync
└── assets/
    ├── hardware/                # Foto aset 39 komponen hardware lokal resolusi tinggi
    └── avatars/                 # 4 Vektor SVG karakter racer (P1 s/d P4)
```

---

## 10. Integrasi Laravel 13, MySQL 8.4, & CMS Input Soal
Game terintegrasi penuh dengan ekosistem Laravel & MySQL platform:
* **Database Table**: `hardware_questions` menyimpan bank soal (pertanyaan, gambar hardware, 4 opsi A/B/C/D, kunci jawaban benar, tingkat kesulitan, dan penjelasan materi).
* **REST API Endpoints**:
  * `GET /api/hardware-questions`: Mengambil seluruh koleksi soal dari MySQL secara dinamis.
  * `POST /api/hardware-questions`: Menambahkan soal baru dari form CMS.
  * `DELETE /api/hardware-questions/{id}`: Menghapus soal.
  * `POST /api/match/finish`: Menyimpan statistik rekor balapan.
* **Input Interface / CMS**: `/manage` (Tab Hardware Battle) dengan antarmuka formulir, image selector, radio button kunci jawaban, filter pencarian, dan live preview.
* **Offline-Ready Resilience**: Jika server web atau MySQL mati, game otomatis fallback ke 46 bank soal lokal di `questions.js`.

---

## 11. Panduan Isolasi Multi-Game di Proyek `game-pelajaran`
Folder root `game-pelajaran/` disiapkan sebagai wadah koleksi beragam game edukasi:
* Setiap game ditempatkan di direktori mandiri masing-masing (contoh: `hardware-battle/`, `cable-connect/`, `game-jaringan/`, dll).
* Setiap folder game memiliki file `PRD.md`, `index.html`, `css/`, `js/`, dan `assets/` sendiri.
* Halaman root `game-pelajaran/index.html` dan route Laravel `/` bertindak sebagai **Portal / Launcher Menu Utama** untuk memilih game yang ingin dimainkan.