# Game Engine

> Game state machine, lobby system, question flow, scoring, and real-time game coordination

- Skill: `seanchiuai/game-engine` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add seanchiuai/game-engine`
- Raw SKILL.md: https://api.skillmd.com/api/skills/seanchiuai/game-engine/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: seanchiuai (https://skillmd.com/u/seanchiuai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/seanchiuai/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

| From | To | Trigger |
|------|----|---------|
| lobby | question | Host clicks "Start Game" |
| question | results | Host clicks "Show Results" OR timer expires |
| results | question | Host clicks "Next Question" (if questions remain) |
| results | complete | Host clicks "Next Question" on last question |

### 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](reference.md) — Code patterns for state management and iframe communication