Game Engine

Game Engine

Manages the game lifecycle from lobby to completion — state transitions, question progression, answer tracking, scoring, iframe communication, and real-time coordination between host and players.

Overview

• State Machine: lobby → playing → question → results → complete
• Host Controls: Start game, next question, show results
• Player Flow: Join lobby, play AI-generated game in sandboxed iframe, see feedback, view leaderboard
• Iframe Architecture: Parent owns game state, iframe is a dumb renderer, communication via MessageChannel
• Scoring: Points based on correctness + speed (validated server-side, not in iframe)
• Real-time: All state changes sync instantly via Convex

When to Use This Skill

• Building or modifying the game state machine
• Implementing host controls (start, next, results)
• Building the iframe sandbox and MessageChannel communication
• Building the player answer flow (iframe → parent → Convex)
• Implementing scoring logic (server-side validation)
• Handling edge cases (disconnects, late joins, timeouts, iframe errors)

Key Concepts

State Machine

lobby → playing → question ←→ results → complete
                     ↑              |
                     └──────────────┘ (next question)

• lobby: Players joining, host waiting to start
• playing: Transitional state when game starts
• question: Active question, players submitting answers
• results: Showing answer results + leaderboard for current question
• complete: All questions done, final results displayed

State Transitions

Scoring Formula

Points = correctness_points + speed_bonus
correctness_points = correct ? 1000 : 0
speed_bonus = correct ? max(0, 500 * (1 - timeMs / timerDuration)) : 0

Max points per question: 1500 (correct + fastest possible)

Timer

• Default: 30 seconds per question
• Timer runs in the parent app (authoritative), not in the iframe
• iframe can display a visual countdown, but parent enforces the actual limit
• When timer expires, parent sends TIME_UP to iframe via MessageChannel

Iframe Communication

Parent and iframe communicate via a private MessageChannel:

1. Parent creates MessageChannel, transfers one port to iframe via initial postMessage
2. All subsequent communication flows through the private channel port
3. Never combine allow-scripts + allow-same-origin in sandbox

Parent as Source of Truth

• Parent owns game state — iframe is a rendering engine
• Scoring happens server-side (Convex), not in the iframe
• If iframe crashes, parent still has game state and can recover
• iframe cannot be trusted for authoritative state (it runs AI-generated code)

Related Files

• convex/games.ts — Game state mutations
• convex/answers.ts — Answer submission and scoring
• convex/players.ts — Player management and scores
• components/GameIframe.tsx — Sandboxed iframe wrapper with MessageChannel

Reference Files

• reference.md — Code patterns for state management and iframe communication