# Research Findings — Easy-Multiplayer

Compiled 2026-03-12 from 4 parallel research spikes.

---

## 1. API Design

**Recommendation: Callback/loop pattern with plain-object state.**

```javascript
const mp = new EasyMultiplayer({
  initialState: { players: {}, ball: { x: 0, y: 0 } },
  tick(state, inputs, rng) { /* game logic */ return state; },
  getInput() { return { left: keys.has('ArrowLeft') }; },
  render(state) { /* visual update */ },
});
```

- State is a plain JSON object → auto serialize/deserialize via JSON.parse/stringify
- `tick` receives `rng` as parameter → `Math.random()` obviously wrong
- Lowest ceremony for hello-world games
- Optional `serialize`/`deserialize` overrides for advanced use

**Surveyed**: GGPO, NetplayJS, Telegraph, Lance.gg, Colyseus, Rune.ai, Photon Quantum, Mirror, Croquet, Bevy GGRS.

**Novel ideas**: Proxy-based state mutation tracking (from Rune), lockstep-to-rollback adoption path, structural sharing for efficient snapshots.

---

## 2. Determinism Enforcement

**Immediate fixes needed in codebase:**
- Line 279: `localeCompare` → replaced with string comparison ✓
- Line 1713: `localeCompare` in `HasAuthorityOver` → replaced ✓
- Line 1482: RNG seed=0 fallback → fixed ✓
- Line 1585: `abra: Math.random()` → removed ✓

**Recommended layered strategy:**
1. Override `Math.random`/`Date.now` during tick execution (throw in dev, seeded fallback in prod)
2. Use `Math.fround()` at state entry points for float32 precision
3. Double-run determinism test (same ticks twice, compare hashes)
4. Long-term: LUT-based trig (also 3x faster than native `Math.sin/cos`)

**Sources of non-determinism in JS** (by severity):
- CRITICAL: `Math.random()`, `Math.sin/cos` cross-browser, `Date.now()`, `localeCompare`
- HIGH: Float accumulation across engines, `for...in` on mixed-key objects, `JSON.stringify` key ordering
- MEDIUM: `Map/Set` insertion-order dependent on code path, `Array.sort` equal-element ordering
- LOW: Promise timing, `WeakMap` GC timing, JIT tier-up behavior

---

## 3. Scaling & Spectator Model

**Architecture: Two-tier topology**
- **Tier 1 (Active)**: Full mesh among active players (max ~8-12). Standard rollback.
- **Tier 2 (Spectators)**: Star topology via relay peer. Spectators receive confirmed-input stream, run simulation forward-only with 1-2s delay. No rollback needed.

**Key concepts:**
- **Peers** = connected entities (attendance at 500ms, timeout at 3s)
- **Input slots** = active participants in simulation
- **Spectators** = peers without input slots
- Silence = "no input change" (not disconnect)
- Disconnect detected via attendance timeout, not input silence

**Dynamic promotion** (spectator → active): Authority assigns `promotionTick`, all peers accept, triggers targeted rollback at that tick.

**Trystero approach**: Two rooms — active player room (full mesh) + spectator room (relay broadcasts). Relay peer bridges both.

**Bandwidth improvement**: ~50x reduction (300K→5.7K messages/sec for 10 active + 90 spectators).

---

## 4. Input Query System

**The system is novel** — no published netcode engine does predicate-based input comparison.

**Design:**
```javascript
// Register predicates at setup
engine.registerPredicate("pressed", v => v > 0.5);

// In tick — conditional queries
if (player.grounded) {
    engine.query(playerId, "jump_button", "pressed");
}
```

- Queries recorded per tick: {inputName, predicateId, result}
- On input correction: re-evaluate queries with corrected input
- If all results match → skip rollback
- If any result differs → rollback needed (stop at first divergence)

**Performance**: ~0.1-0.3μs to check 10 predicates vs 2.5-25ms for a 5-tick rollback.
**Memory**: ~180KB for 60 ticks × 10 queries × 2 players.
**Estimated rollback elimination**: 40-70%.

**Edge cases resolved:**
- Branching logic: stop-at-first-diverging-query handles correctly
- No queries on tick: entire tick is rollback-free
- Stale records: overwritten during re-simulation
- Direct input bypass: dev-mode warning on `GetInputForPlayer()`

**Existing stub**: `PlayerInput.crucial` at line 805 (unimplemented) — predecessor of this concept.