# Easy-Multiplayer — Bootstrap Document

**Last updated**: 2026-05-25

---

## Purpose

**Surface product:** Easy-Multiplayer — lets developers write singleplayer game code and get multiplayer for free.

**Underneath:** a *decentralized synchronized simulation system* — generic distributed simulation infrastructure that happens to be a great fit for games. Public API speaks "game / player / tick"; internal layers speak "simulation / participant / step". The library could conceivably power non-game collaborative simulations too, though games are the target use case.

## v2 Redesign — ACTIVE

The project is mid-pivot from "rollback with optimizations" to a **semantic distributed simulation architecture**. The canonical design is `easy_multiplayer_redesign_concretized_architecture.md`. The goal index is `GOALS.md`. The task tracker is `TASKS.md`. The current code partially implements v1; v2 is the target.

Key v2 ideas:

- **Silence is meaningful** — no packet means unchanged, not disconnected
- **Inputs only matter if queried** — `query()` predicates decide what rolls back
- **Semantic rollback invalidation** — rollback only when query *results* change, not when raw inputs change
- **Sparse input history** — change-only inputs, reconstructed continuous stream
- **Uncertainty-aware desync** — different hashes ≠ desync if unresolved input uncertainty exists
- **Context-aware intent construction** — local game state shapes input meaning before it enters simulation
- **Pluggable transport** — P2P and server-client share the same rollback layer
- **Bus-based rollback** (forthcoming, Phase C+) — re-simulation as parallel/sliced workers so the visible simulation never freezes

## Technology Stack

- **Language**: JavaScript (ES6 modules, no TypeScript)
- **3D Engine**: Three.js — optional; used by visualization modules only
- **Networking**: Trystero (P2P via WebTorrent) — current; will be one of several transports
- **Build System**: None — pure ES6 modules
- **Tests**: Vitest scaffold present (`package.json` + `vitest.config.js`); ~4 test files (rollback, query, events, hints). **Note:** does not run under Node 12 — Phase A6 fixes this.
- **CI/CD**: None

## Architecture Snapshot

See `ARCHITECTURE.md` for the full Layer 1/2/3 model and current-vs-target map.

**Core modules** (root level):

| Module | Lines | Role |
|--------|-------|------|
| `RollbackNetcode.js` | 2111 | Core simulation/rollback engine; `Query` API already partially implemented |
| `SyncedScene.js` | 558 | Extends RollbackNetcode; scene/component orchestration (v1) |
| `EasyMultiplayer.js` | 287 | Public callback-style facade; close to v2 recommended API shape |
| `EventSystem.js` | 179 | Rollback-aware events |
| `PresentationHints.js` | 139 | Trail/sample hints for smooth rendering |
| `SyncedClock.js` | 202 | Peer time sync |
| `WorldNetworkCommunicator.js` | 121 | Trystero P2P wrapper (Phase A1: refactor behind Transport interface) |
| `Utils.js` | ~240 | Helpers |
| `imurmurhash.js` | 136 | State hashing |

**Optional** (`optional/`): `SoundManager.js`, `VoiceChat/*`, `PlayerVisualization/*`.

## Current Phase

**Phase A — Foundation**. Doc refresh + GOALS.md created on 2026-05-25; next concrete implementation step is Goal A1 (formalize Transport interface). Awaiting user direction to begin implementation.

## Document Index

| Document | Purpose |
|----------|---------|
| `CLAUDE_BOOTSTRAP.md` | This file — compressed project snapshot |
| `easy_multiplayer_redesign_concretized_architecture.md` | Canonical v2 design vision |
| `PROJECT_OVERVIEW.md` | Goals, scope, terminology, success criteria |
| `ARCHITECTURE.md` | Layer 1/2/3 design + current-vs-target mapping |
| `GOALS.md` | Concrete goals with deliverables, success criteria, verification |
| `TASKS.md` | Phase A/B/C task breakdown |
| `DECISIONS.md` | Architectural decisions and rationale |
| `KNOWN_ISSUES.md` | Pre-redesign tech debt + open design questions |
| `PROGRESS_LOG.md` | Chronological progress updates |
| `TEST_SCENARIOS.md` | English scenario catalog (the test spec) |
| `TRANSPORT_SPEC.md` | Abstract Transport interface contract |
| `PROTOCOL_SPEC.md` | Wire format for v2 protocol messages |
| `RESEARCH_FINDINGS.md` | Notes from earlier research spikes (legacy) |