68 lines
3.1 KiB
Markdown
68 lines
3.1 KiB
Markdown
|
# Jackbox Ecast API Reverse Engineering — Design
|
||
|
|
|
||
|
|
**Date:** 2026-03-20
|
||
|
|
**Goal:** Produce comprehensive documentation of the Jackbox ecast API (REST + WebSocket) through live traffic analysis.
|
||
|
|
**Deliverable:** `docs/jackbox-ecast-api.md`
|
||
|
|
|
||
|
|
## Scope
|
||
|
|
|
||
|
|
### In Scope
|
||
|
|
|
||
|
|
1. **Ecast REST API** — All discoverable endpoints at `ecast.jackboxgames.com`, including undocumented paths, multiple API versions, and different HTTP methods.
|
||
|
|
|
||
|
|
2. **Ecast WebSocket Protocol** — Full bidirectional message protocol between `jackbox.tv` and ecast servers: connection handshake, all opcodes/message types, entity model, and state transitions through the complete game lifecycle.
|
||
|
|
|
||
|
|
3. **Player & Room Management** — Join/leave detection, real-time player count, max players, lobby lock/game start signals, game completion signals, player and game stats/results.
|
||
|
|
|
||
|
|
### Out of Scope
|
||
|
|
|
||
|
|
- Kosmi integration (chrome extension)
|
||
|
|
- This application's own API
|
||
|
|
- Game-specific mechanics (drawing, voting within Drawful 2) unless they reveal useful metadata
|
||
|
|
|
||
|
|
## Approach
|
||
|
|
|
||
|
|
**Primary: REST probing + browser console WebSocket interception (Approach A)**
|
||
|
|
**Fallback: Puppeteer + CDP automated capture script (Approach B)**
|
||
|
|
|
||
|
|
### Phase 1 — REST API Probing
|
||
|
|
|
||
|
|
- Probe known endpoint `GET /api/v2/rooms/{code}` and document full response
|
||
|
|
- Discover new paths: `/players`, `/audience`, `/state`, etc.
|
||
|
|
- Try API versions `v1`, `v3`
|
||
|
|
- Check for discovery endpoints (`/api`, `/swagger`, `/openapi`, `/health`)
|
||
|
|
- Try different HTTP methods (POST, PUT, OPTIONS)
|
||
|
|
- Document all response schemas, headers, status codes
|
||
|
|
|
||
|
|
### Phase 2 — WebSocket Interception
|
||
|
|
|
||
|
|
- Navigate to `jackbox.tv` in browser
|
||
|
|
- Inject WebSocket interceptor (monkey-patch `WebSocket`) before joining room
|
||
|
|
- Join as player — capture full connection lifecycle
|
||
|
|
- Join as audience — capture audience-specific messages
|
||
|
|
- If injection races with connection, reload page after patching
|
||
|
|
|
||
|
|
### Phase 3 — Game Lifecycle Capture
|
||
|
|
|
||
|
|
Walk through entire Drawful 2 lifecycle with interceptor running:
|
||
|
|
- Lobby: join/leave messages, player list updates
|
||
|
|
- Game start: lock signal, round info
|
||
|
|
- Gameplay: state transitions, metadata
|
||
|
|
- Game end: results, stats, disconnection sequence
|
||
|
|
- Multiple players to observe multi-player messages
|
||
|
|
|
||
|
|
### Fallback (Approach B)
|
||
|
|
|
||
|
|
If browser console interception is unreliable, write a Node.js script using Puppeteer + CDP `Network.webSocketFrame*` events for automated structured capture.
|
||
|
|
|
||
|
|
## Documentation Structure
|
||
|
|
|
||
|
|
The deliverable (`docs/jackbox-ecast-api.md`) will contain:
|
||
|
|
|
||
|
|
1. **Overview** — What ecast is, base URLs, architecture
|
||
|
|
2. **REST API Reference** — Each endpoint with method, URL, params, response schema, notes
|
||
|
|
3. **WebSocket Protocol Reference** — Connection details, message format, message catalog (all opcodes), entity model
|
||
|
|
4. **Game Lifecycle** — Sequence diagram of message flow from room creation through completion
|
||
|
|
5. **Player & Room Management** — Answers to specific questions (join/leave detection, player count, max players, lock/start, completion, stats) with supporting evidence
|
||
|
|
6. **Appendix: Raw Captures** — Sanitized example payloads
|