# UbuntuPlay — Standardised Analytics & Scoring Schema
## Quiz Events (all games must fire these)

### quiz_attempt
Fired once when a question is first shown to the student.
```json
{
  "questionId":   "string — unique stable ID (e.g. p1_01, great_zimbabwe_s1_q0)",
  "questionText": "string — the question as shown to the student (max 120 chars)",
  "opts":         ["array", "of", "answer", "option", "strings"],
  "correctIdx":   2,           // index of the correct answer in opts
  "category":     "string",    // question category / topic
  "difficulty":   "easy|medium|hard",  // optional
  "zone":         "string",    // game section / zone / campaign
  "gameMode":     "string"     // game-specific mode (arcade, zen, etc.)
}
```

### quiz_correct
Fired when the student answers correctly.
```json
{
  "questionId":   "string",
  "questionText": "string",
  "opts":         ["array"],
  "chosenIdx":    2,           // index the student chose (same as correctIdx)
  "correctIdx":   2,
  "timeTaken":    4.2,         // seconds from question shown to answer
  "zone":         "string",
  "gameMode":     "string"
}
```

### quiz_wrong
Fired when the student answers incorrectly (including timeout).
```json
{
  "questionId":   "string",
  "questionText": "string",
  "opts":         ["array"],
  "chosenIdx":    1,           // index the student chose (wrong), -1 if timed out
  "correctIdx":   2,           // the correct answer
  "timedOut":     false,       // true if question expired
  "timeTaken":    8.1,
  "zone":         "string",
  "gameMode":     "string"
}
```

## Score Submission (POST /api/scores)

### Quiz games (Chenjela, Builder quiz)
```json
{
  "game": "chenjela",
  "score": 840,
  "metadata": {
    "scorePercent": 84,
    "grade": "B",
    "correct": 21,
    "total": 25,
    "mode": "arcade",
    "paper": 1,
    "timeSec": 180,
    "maxStreak": 8,
    "xpEarned": 420
  }
}
```

### Adventure/campaign games (Assegai)
```json
{
  "game": "assegai",
  "score": 850,
  "metadata": {
    "stars": 3,
    "campaignName": "Great Zimbabwe",
    "campaign": "great_zimbabwe",
    "gold": 120,
    "xp": 450,
    "kills": 22
  }
}
```

### Puzzle games (Nzelu)
```json
{
  "game": "nzelu",
  "score": 300,
  "metadata": {
    "stars": 3,
    "puzzleId": "lus1",
    "puzzleName": "Sort the Rubbish!",
    "zone": "lusaka",
    "timeSec": 42
  }
}
```

## scoreFormat values (in games manifest)
- `quiz`       — percentage-based quiz (Chenjela, Builder quiz)
- `stars`      — puzzle/zone star rating (Nzelu)
- `campaign`   — adventure campaign (Assegai)
- `match`      — matching game (Builder match)
- `memory`     — memory game (Builder memory)
- `sequence`   — sequence game (Builder sequence)
