# 🎮 ClassVerse Quiz Arena — Konsep Gamifikasi

## Premis

ClassVerse sudah punya modul Game Pembelajaran di PRD (Fase 3) dengan 5 tipe game: multiple choice, true/false, jumbled word, matching, dan word search. Skor masuk nilai resmi.

Dokumen ini membahas **konsep pengalaman** — bagaimana quiz ini *terasa* bagi siswa, bukan sekadar "soal tampil, jawab, selesai." Kita mulai dari **quiz tipe Kahoot-like** sebagai fondasi.

---

## 1. Masalah dengan Quiz Konvensional

Quiz sekolah biasanya:
- Tampilan form biasa — radio button, submit, selesai
- Tidak ada elemen waktu, tidak ada tension
- Tidak ada feedback instan — siswa submit lalu menunggu
- Tidak ada perbandingan — siswa tidak tahu posisinya
- Membosankan — terasa seperti ujian, bukan permainan

**Hasilnya:** siswa mengerjakan seadanya, tidak termotivasi, dan tidak ada pengulangan belajar.

---

## 2. Filosofi Desain: "Belajar yang Terasa Main"

### Prinsip Inti

| # | Prinsip | Penjelasan |
|---|---------|------------|
| 1 | **Tension Loop** | Setiap soal punya timer visual yang menciptakan urgensi |
| 2 | **Instant Gratification** | Jawaban benar langsung diberi reward visual + suara |
| 3 | **Social Pressure** | Leaderboard real-time antar siswa satu kelas |
| 4 | **Streak Mechanics** | Jawab benar beruntun = bonus skor = motivasi konsistensi |
| 5 | **Progress Visibility** | Siswa selalu tahu posisi, skor, dan progresnya |
| 6 | **Low Shame** | Jawaban salah tidak dipermalukan — animasi lembut, encourage retry |

---

## 3. Konsep Utama: "Quiz Arena"

### Nama Fitur: **Arena**

Bukan sekadar "quiz" — siswa masuk ke **Arena**. Kata ini memberi kesan kompetitif tapi fun.

### Mode Bermain

#### 🏃 Mode 1: Solo Sprint
- Siswa bermain sendiri, lawan waktu
- Cocok untuk: latihan mandiri, remedial, pengayaan
- Kapan saja bisa diakses (jika guru mengizinkan)
- Skor tetap masuk nilai

#### 🏟️ Mode 2: Live Arena (Kahoot-like)
- Guru mengaktifkan sesi — semua siswa masuk bersamaan
- Real-time leaderboard via WebSocket (Laravel Reverb)
- Guru mengendalikan pace (kapan soal berikutnya muncul)
- Cocok untuk: formatif di kelas, kuis dadakan, review materi
- **Ini yang paling mirip Kahoot**

#### 📝 Mode 3: Challenge (Take-Home Quiz)
- Guru set window waktu (misal: Senin 08:00 - Selasa 23:59)
- Siswa bisa mulai kapan saja dalam window itu
- Sekali mulai, timer berjalan — tidak bisa pause
- Cocok untuk: PR formatif, ujian take-home

---

## 4. Mekanika Game Detail

### 4.1 Timer & Scoring

```
┌─────────────────────────────────────────┐
│  Skor per soal = Base × Speed × Streak  │
└─────────────────────────────────────────┘
```

| Komponen | Rumus | Contoh |
|----------|-------|--------|
| **Base Score** | 1000 poin jika benar, 0 jika salah | Benar = 1000 |
| **Speed Bonus** | `(sisa_waktu / total_waktu) × 500` | Jawab di detik ke-3 dari 15 detik → (12/15) × 500 = 400 |
| **Streak Multiplier** | `1.0 + (streak × 0.1)`, max 2.0 | 5 benar beruntun → 1.5× |
| **Total** | `base × streak_mult + speed_bonus` | 1000 × 1.5 + 400 = **1900** |

> **Kenapa penting:** Sistem ini memotivasi siswa untuk jawab *benar DAN cepat*, bukan asal cepat.

### 4.2 Streak System

```
🔥 Streak 0  → ×1.0  (normal)
🔥 Streak 3  → ×1.3  (warming up!)
🔥 Streak 5  → ×1.5  (on fire!)
🔥 Streak 7  → ×1.7  (unstoppable!)
🔥 Streak 10 → ×2.0  (LEGENDARY! — max cap)
```

Setiap level streak punya:
- Animasi fire yang makin besar
- Warna berubah (kuning → oranye → merah)
- Efek partikel di layar
- Sound effect yang escalate

Streak putus (jawab salah):
- Animasi "crack" lembut
- Reset ke ×1.0
- Pesan encourage: "Gapapa, coba lagi! 💪"

### 4.3 Power-Ups (Opsional — Fase Lanjut)

| Power-Up | Efek | Cara Dapat |
|----------|------|------------|
| ⏰ Time Freeze | +5 detik tambahan | Streak 5 pertama kali |
| 🛡️ Shield | Streak tidak putus walau salah 1× | Streak 10 pertama kali |
| 50/50 | Hapus 2 jawaban salah | Random reward tiap 7 soal |

> [!NOTE]
> Power-ups bisa dinonaktifkan guru untuk mode ujian serius. Guru punya kontrol penuh.

---

## 5. Visual & UX Flow

### 5.1 Alur Siswa Masuk Arena

```
Halaman Materi
    └── Tombol "🎮 Masuk Arena" 
            └── Lobby Screen (lihat info quiz)
                    └── Countdown 3-2-1-GO!
                            └── Soal 1/10
                                    └── Jawab → Feedback instant
                                            └── ... Soal 10/10
                                                    └── Result Screen
                                                            └── Leaderboard + Skor Final
```

### 5.2 Layar-Layar Utama

#### A. Lobby Screen
- Nama quiz + icon mapel
- Jumlah soal & estimasi waktu
- Daftar siswa yang sudah join (Live Arena)
- Tombol "Mulai!" yang gede dan inviting
- Background: gradient gelap dengan partikel melayang

#### B. Question Screen
- **Timer bar** di atas — bar horizontal yang menyusut + berubah warna (hijau → kuning → merah)
- **Nomor soal** & progres: "4/10"
- **Pertanyaan** di tengah — font besar, mudah dibaca
- **4 opsi jawaban** sebagai card besar warna-warni (bukan radio button!)
  - Setiap card punya warna + ikon unik (▲ ● ◆ ■)
  - Hover/tap: efek scale-up + glow
  - Selected: bounce animation
- **Streak indicator** di pojok: api + multiplier
- **Skor current** di pojok lain

#### C. Feedback Screen (per soal, 2-3 detik)
- ✅ **Benar:** Layar flash hijau + confetti + "+1400 🔥×1.3" 
- ❌ **Salah:** Layar flash merah lembut + jawaban benar ditampilkan + "Keep going!"
- Transisi smooth ke soal berikutnya

#### D. Result Screen
- **Podium animasi** untuk top 3 (Live Arena)
- Skor total + breakdown
- Statistik: akurasi %, rata-rata kecepatan, streak terpanjang
- Badge/achievement jika ada
- Tombol "Lihat Jawaban" — review mode
- Tombol "Main Lagi" (jika guru mengizinkan retry)

### 5.3 Palet Warna Quiz Arena

> [!IMPORTANT]
> Tidak menggunakan ungu/violet sesuai aturan desain.

| Elemen | Warna | Hex |
|--------|-------|-----|
| Background utama | Dark navy / charcoal | `#0f172a` → `#1e293b` |
| Opsi A | Merah coral | `#ef4444` |
| Opsi B | Biru ocean | `#3b82f6` |
| Opsi C | Kuning amber | `#f59e0b` |
| Opsi D | Hijau emerald | `#10b981` |
| Timer bar penuh | Emerald | `#10b981` |
| Timer bar habis | Merah | `#ef4444` |
| Streak fire | Gradient oranye-merah | `#f97316` → `#ef4444` |
| Skor text | Putih | `#ffffff` |
| Benar flash | Hijau semi-transparan | `#10b981` @ 20% |
| Salah flash | Merah semi-transparan | `#ef4444` @ 15% |

### 5.4 Animasi Kunci

| Momen | Animasi | Durasi |
|-------|---------|--------|
| Masuk soal | Slide-in dari bawah + fade | 400ms |
| Pilih jawaban | Scale-up card + ripple | 200ms |
| Jawaban benar | Confetti burst + score float-up | 800ms |
| Jawaban salah | Shake horizontal + fade merah | 400ms |
| Streak naik | Fire icon pulse + glow ring | 500ms |
| Timer warning (5 detik) | Bar blink + pulse | continuous |
| Transisi soal | Crossfade | 300ms |
| Result screen | Podium build-up dari bawah | 1200ms |

---

## 6. Perspektif Guru (Admin)

### 6.1 Membuat Quiz

```
Guru Dashboard
    └── Menu "Arena" (atau dari dalam Materi)
            └── "Buat Quiz Baru"
                    ├── Info Dasar: Judul, Mapel, Kelas, Materi terkait
                    ├── Pengaturan:
                    │   ├── Mode: Solo / Live / Challenge
                    │   ├── Timer per soal (5/10/15/20/30 detik)
                    │   ├── Shuffle soal: Ya/Tidak
                    │   ├── Shuffle opsi: Ya/Tidak
                    │   ├── Tampilkan jawaban benar: Ya/Tidak
                    │   ├── Izinkan retry: Ya/Tidak (+ berapa kali)
                    │   └── Power-ups: Aktif/Nonaktif
                    └── Soal-soal:
                        ├── Soal 1: [Teks] + 4 opsi + tandai jawaban benar
                        ├── Soal 2: ...
                        └── + Tambah Soal / Import dari Bank Soal
```

### 6.2 Live Arena Dashboard (Guru)

Saat Live Arena berjalan, guru melihat:
- Jumlah siswa yang sudah join
- Real-time progress: berapa siswa sudah jawab soal ke-N
- Leaderboard live
- Tombol "Next Question" (guru kontrol pace)
- Statistik per soal: % jawab benar, distribusi jawaban

### 6.3 Rekap & Nilai

- Skor arena otomatis masuk tabel `grades` (polymorphic)
- Guru bisa lihat: per siswa, per quiz, per kelas
- Export ke XLSX bersama nilai tugas lainnya
- Guru bisa override skor manual jika diperlukan

---

## 7. Model Data (Ekstensi dari PRD)

```
learning_games
├── id
├── title
├── subject_id (FK)
├── synced_class_id (FK)  
├── material_id (FK, nullable) — dikaitkan ke materi
├── game_type (enum: 'multiple_choice', 'true_false', 'jumbled_word', 'matching', 'word_search')
├── mode (enum: 'solo', 'live', 'challenge')
├── settings (JSON: timer_seconds, shuffle_questions, shuffle_options, show_correct, allow_retry, max_retries, powerups_enabled)
├── status (enum: 'draft', 'published', 'archived')
├── available_from (datetime, nullable — untuk Challenge mode)
├── available_until (datetime, nullable)
├── created_at
└── updated_at

game_items
├── id
├── learning_game_id (FK)
├── question_text
├── question_image (nullable — path gambar soal)
├── options (JSON array: [{text, is_correct, image?}])
├── explanation (nullable — penjelasan jawaban benar)
├── order
├── created_at
└── updated_at

game_sessions (BARU — untuk Live Arena)
├── id
├── learning_game_id (FK)
├── session_code (string unik — kode join)
├── status (enum: 'waiting', 'in_progress', 'completed')
├── current_question_index (int)
├── started_at
├── completed_at
├── created_at
└── updated_at

game_attempts
├── id
├── learning_game_id (FK)
├── game_session_id (FK, nullable — null jika Solo)
├── synced_student_id (FK)
├── total_score (int)
├── total_correct (int)
├── total_questions (int)
├── accuracy_percentage (decimal)
├── longest_streak (int)
├── average_speed_ms (int)
├── started_at
├── completed_at
├── created_at
└── updated_at

game_attempt_answers (BARU — detail per soal)
├── id
├── game_attempt_id (FK)
├── game_item_id (FK)
├── selected_option_index (int, nullable — null jika timeout)
├── is_correct (boolean)
├── time_taken_ms (int)
├── score_earned (int)
├── streak_at_time (int)
├── created_at
└── updated_at
```

---

## 8. Teknologi & Arsitektur

| Concern | Pendekatan |
|---------|------------|
| **Real-time (Live Arena)** | Laravel Reverb (WebSocket) — sudah disebut di PRD |
| **Timer accuracy** | Timer di client (React), validasi di server |
| **Anti-cheat dasar** | Server menyimpan waktu soal ditampilkan vs waktu jawaban diterima |
| **Animasi** | Framer Motion (React) — sudah cocok dengan stack |
| **Confetti** | `canvas-confetti` library (ringan, < 5KB) |
| **Sound** | Howler.js atau Web Audio API — preload saat masuk lobby |
| **State management** | Zustand atau React Context — state quiz di client |

---

## 9. Prioritas Implementasi (Rekomendasi)

### Sprint 1: Solo Multiple Choice
- [ ] Model data: `learning_games`, `game_items`, `game_attempts`, `game_attempt_answers`
- [ ] CRUD quiz di dashboard guru
- [ ] Layar quiz siswa: lobby → soal → feedback → result
- [ ] Timer + scoring system
- [ ] Streak mechanics
- [ ] Animasi dasar (transisi, feedback benar/salah)
- [ ] Skor masuk `grades`

### Sprint 2: Live Arena
- [ ] `game_sessions` + WebSocket channel
- [ ] Lobby real-time (siswa join, guru lihat)
- [ ] Guru kontrol pace soal
- [ ] Leaderboard real-time
- [ ] Podium result screen

### Sprint 3: Polish & Tipe Game Lain
- [ ] True/False (variasi ringan dari multiple choice)
- [ ] Sound effects
- [ ] Power-ups
- [ ] Challenge mode (time-window)
- [ ] Bank soal

### Sprint 4: Advanced Games
- [ ] Jumbled word
- [ ] Matching
- [ ] Word search

---

## 10. Pertanyaan Terbuka untuk Kamu

Sebelum implementasi, beberapa hal yang perlu keputusan:

1. **Retry policy:** Jika siswa boleh retry, skor yang diambil yang mana — tertinggi, terakhir, atau rata-rata?

2. **Sound:** Apakah sound effects diinginkan? (Bisa dimatikan siswa via toggle.) Sound sangat menambah "feel" game tapi perlu effort tambahan.

3. **Live Arena priority:** Apakah Live Arena (Kahoot-like real-time) mau langsung dari awal, atau Solo Sprint dulu yang stabil baru Live?

4. **Gambar di soal:** Apakah guru perlu bisa menambahkan gambar pada soal? (Misalnya: soal Informatika yang butuh screenshot.)

5. **Timer default:** Berapa detik per soal yang masuk akal untuk siswa MTs? Rekomendasi: 15 detik untuk multiple choice, 20 detik untuk soal yang butuh baca.

6. **Batasan soal:** Minimum dan maksimum soal per quiz? Rekomendasi: min 5, max 50.

7. **Mobile-first atau responsive?** Mengingat siswa banyak pakai HP, apakah layout quiz harus mobile-first?