# Game Integration Plan

This document inventories the current game entry points and defines the metadata and rollout plan for ByteLift API integration.

## Shared Completion Contract

All games should follow the same high-level contract:

- call `startGame()` from `connection/start_game.js` on document ready
- keep the returned session token for completion
- call `submitAnswer(payload)` from `connection/submit_answer.js` only once at the true end of the run
- let `submit_answer.js` handle redirect or React Native WebView postMessage

Recommended payload shape:

```js
{
  token: "SESSION_TOKEN_HERE",
  score: 95,
  metadata: {
    time_spent_seconds: 132,
    level: 3,
    correct_answers: 19,
    rounds_total: 20,
    rounds_completed: 20,
    game_mode: "rectangle"
  }
}
```

## Game Inventory

### 1. `adventure_time/index.html`

- Type: vanilla JS
- Status: already integrated
- Rules: 3 modes, 5 rounds total, player builds shapes and/or solves for area
- Score model: raw correct answers out of 5, currently submitted as percentage
- Completion trigger: `showScore()`
- Metadata baseline:
  - `time_spent_seconds`
  - `level: 5`
  - `correct_answers`
  - `rounds_total: 5`
  - `rounds_completed: 5`
  - `game_mode`

### 2. `grade_03_lesson_01_adventure_time/index.html`

- Type: React-in-browser single file
- Rules: same family as `adventure_time`, with `rectangle`, `square`, and `area` modes
- Score model: correct answers out of 5
- Completion trigger: when `next()` moves screen to `end`
- Metadata baseline:
  - `time_spent_seconds`
  - `level: 5`
  - `correct_answers`
  - `rounds_total: 5`
  - `rounds_completed: 5`
  - `game_mode`
- Notes: React state version, so integration should be done with `useEffect` on mount and a completion handler when screen becomes `end`

### 3. `grade_03_lesson_02_house_ranger_game/index.html`

- Type: vanilla JS, rendered through `root.innerHTML`
- Rules: 10 houses, each house is a rectangle or square area problem
- Score model: completed houses out of 10
- Completion trigger: `showFinalScore()`
- Metadata baseline:
  - `time_spent_seconds`
  - `level: completedHouses.length`
  - `correct_answers: completedHouses.length`
  - `rounds_total: 10`
  - `rounds_completed: completedHouses.length`
  - `game_mode: "house_ranger"`
- Notes: game is hub-based, so do not submit when a single house ends; submit only from final score screen

### 4. `grade_03_lesson_03_trip_down_memory_line/index.html`

- Type: vanilla JS
- Rules: 5 rounds, memorize 2 lines on a 5x5 dot grid and redraw them
- Score model: correct rounds out of 5
- Completion trigger: final score render after round 5
- Metadata baseline:
  - `time_spent_seconds`
  - `level: 5`
  - `correct_answers`
  - `rounds_total: 5`
  - `rounds_completed: 5`
  - `game_mode: "memory_lines"`

### 5. `grade_03_lesson_04_The_10000_Challenge/index.html`

- Type: vanilla JS
- Rules: 10 rounds, convert number words to numerals
- Score model: correct answers out of 10
- Completion trigger: `showFinalScore()`
- Metadata baseline:
  - `time_spent_seconds`
  - `level: 10`
  - `correct_answers`
  - `rounds_total: 10`
  - `rounds_completed: 10`
  - `game_mode: "number_words_to_numerals"`

### 6. `grade_03_lesson_5_The_Magic_Hat/index.html`

- Type: vanilla JS
- Rules: memorize 5 bunny positions among hats, then answer 5 color-to-position prompts
- Score model: correct selections out of 5
- Completion trigger: `showFinalScore()`
- Metadata baseline:
  - `time_spent_seconds`
  - `level: selectedRange`
  - `correct_answers`
  - `rounds_total: 5`
  - `rounds_completed: 5`
  - `game_mode: "magic_hat_memory"`
- Notes: preserve chosen range in metadata because it changes the position labels used in the game

### 7. `grade_03_lesson_06_Valuable_Jackpot/index.html`

- Type: vanilla JS
- Rules: 10-round timed card / jackpot game
- Score model: correct answers out of 10
- Completion trigger: final score render after round 10
- Metadata baseline:
  - `time_spent_seconds`
  - `level: 10`
  - `correct_answers`
  - `rounds_total: 10`
  - `rounds_completed: 10`
  - `game_mode: "valuable_jackpot"`
- Notes: logic appears nearly identical to `grade_03_lesson_08_Slot_of_Fun_Machine`, so these should be integrated as a pair

### 8. `grade_03_lesson_07_Bee_Near_To_You/index.html`

- Type: vanilla JS
- Rules: 10 rounds, drag the bee to the correct rounded number target
- Score model: correct answers out of 10
- Completion trigger: final score render after round 10
- Metadata baseline:
  - `time_spent_seconds`
  - `level: 10`
  - `correct_answers`
  - `rounds_total: 10`
  - `rounds_completed: 10`
  - `game_mode: "rounding"`

### 9. `grade_03_lesson_08_Slot_of_Fun_Machine/index.html`

- Type: vanilla JS
- Rules: 10-round timed card / slot-style game
- Score model: correct answers out of 10
- Completion trigger: final score render after round 10
- Metadata baseline:
  - `time_spent_seconds`
  - `level: 10`
  - `correct_answers`
  - `rounds_total: 10`
  - `rounds_completed: 10`
  - `game_mode: "slot_of_fun_machine"`
- Notes: likely same integration work as `grade_03_lesson_06_Valuable_Jackpot`

### 10. `house_ranger_game/index.html`

- Type: vanilla JS, multi-screen DOM
- Rules: 10 houses, solve area of each floor after revealing dimensions
- Score model: completed houses out of 10
- Completion trigger: `showModal('finish')`
- Metadata baseline:
  - `time_spent_seconds`
  - `level: completed_houses`
  - `correct_answers: completed_houses`
  - `rounds_total: 10`
  - `rounds_completed: completed_houses`
  - `game_mode: "house_ranger"`
- Notes: final state is modal-based instead of a dedicated score screen

### 11. `temple_run/index.html`

- Type: ES module / Three.js
- Rules: endless runner, player dodges obstacles and survives for score
- Score model: continuous score, no fixed rounds
- Completion trigger: run end state when overlay reopens and final hint is updated
- Metadata baseline:
  - `time_spent_seconds`
  - `score_value`
  - `max_speed`
  - `distance_score` or raw `game.score`
  - `game_mode: "endless_runner"`
- Notes: this one is structurally different and should be handled last because it uses module scripts, CDN imports, and no quiz-style correctness model

## Rollout Order

Recommended order:

1. `grade_03_lesson_03_trip_down_memory_line`
2. `grade_03_lesson_04_The_10000_Challenge`
3. `grade_03_lesson_07_Bee_Near_To_You`
4. `grade_03_lesson_5_The_Magic_Hat`
5. `grade_03_lesson_02_house_ranger_game`
6. `house_ranger_game`
7. `grade_03_lesson_06_Valuable_Jackpot`
8. `grade_03_lesson_08_Slot_of_Fun_Machine`
9. `grade_03_lesson_01_adventure_time`
10. `temple_run`

Reasoning:

- start with simpler vanilla-JS score-screen games
- then handle hub-style house games
- then duplicate-pair jackpot / slot games
- leave the React version and the Three.js module game for last because they require different integration patterns

## Implementation Pattern Per Game

For each game, the work should be:

1. add `env.js`, `start_game.js`, and `submit_answer.js` script includes
2. preserve helper references before local `startGame()` / `submitAnswer()` naming collisions
3. initialize API session on page ready
4. store launch start time and resolved session token
5. submit one completion payload at the final game-over state
6. verify the page still renders and no helper name collisions remain

## Open Questions Before Full Rollout

- whether `score` should always be percentage-based for every quiz-style game or whether some games should send raw score
- whether `metadata.level` should mean final round count, difficulty/range, or current sub-mode across all titles
- whether `temple_run` should submit raw endless-run score directly or a normalized value