How It Works

Rollback netcode, the query system, and deterministic simulation.

Rollback Netcode

Easy Multiplayer uses rollback netcode, the same approach used in competitive fighting games. The core idea:

1. Predict — Every peer runs the full game simulation locally. For remote players whose inputs haven't arrived yet, the engine predicts their input (usually: same as last known input).
2. Verify — When the real input arrives over the network, compare it to the prediction.
3. Rollback — If the prediction was wrong, rewind the game state to the point of error and resimulate forward with the correct inputs.

This means the game always feels responsive for the local player — there's no "waiting for the server" lag. The tradeoff is that remote players may occasionally snap to corrected positions when a prediction was wrong.

Frame Lifecycle

Every tick follows this cycle:

PreTick      // Increment frame, check player joins/leaves
TakeInputs   // Sample local input, send over network
Tick         // Your game logic (the 'tick' callback)
PostTick     // Snapshot state, compute hash, check for desyncs
  ...
Draw         // Your rendering (the 'draw' callback), runs at display FPS

State History

The engine keeps a buffer of recent state snapshots (one per frame). When a rollback is needed, it restores the snapshot at the error frame and resimulates all frames from there to the present. Your tick callback runs again for each resimulated frame — this is why it must be deterministic.

The Query System

Traditional rollback compares raw input values: if the predicted input was "none" and the real input is "left", a rollback always happens. But many input changes don't actually affect the game.

Easy Multiplayer introduces predicate-based input queries. Instead of reading raw input, you ask questions:

// "Does the player want to go left (and not also right)?"
var goLeft = query(pid, inputs => inputs.left && !inputs.right); // returns true or false

The predicate receives the full input object and returns a boolean. The engine records each query: the player ID, predicate function, and the boolean result. When corrected input arrives, the engine re-evaluates the predicates with the new input values. Rollback only occurs if a query's result changes.

Why This Matters

Consider a Pac-Man game. The player is moving right through a corridor with walls above and below:

In 3 out of 4 cases, the query system avoids a rollback that traditional netcode would perform. Fewer rollbacks means smoother gameplay.

Best Practices

• Only query when it matters. If the player is in the air, don't query the jump button — it can't do anything.
• Use compound predicates in a single query. query(pid, i => i.left && !i.right) captures "wants left and not also right" as one recorded result. Don't split this into two separate queries.
• Skip queries for defaults. If the player is going right and right is an available direction, don't query right — it's the default continuation.

Determinism

Every peer must produce the exact same game state from the same inputs. If two peers diverge, the game desyncs. This requires:

Rules for Deterministic Code

• Use random() from the tick context, never Math.random(). The library provides a seeded LCG random number generator whose state is part of the snapshot.
• No Date.now() or new Date() in tick logic. Use time from the tick context.
• No floating-point traps. Avoid operations that can produce different results on different machines (e.g., Math.sin with extreme values). Integer math is safest.
• Iteration order. for...in on objects is technically not guaranteed to be ordered, though modern engines are consistent. Arrays are safe.
• Keep draw logic separate. The draw callback runs at display FPS and is not deterministic. Never modify game state during draw.

Networking

Easy Multiplayer uses WebTorrent (via the Trystero library) for peer-to-peer connections. No server is needed beyond the WebTorrent tracker for initial peer discovery.

What Gets Sent

• Inputs — each player's input data (from defineInput) for each frame.
• State hashes — periodic MurmurHash3 of the serialized state, used to detect desyncs.
• Clock sync pings — to synchronize time across peers.
• Full state (on demand) — when a new player joins or a desync is detected.

Topology

All peers connect to all other peers (full mesh). This works well for 2-8 players. Beyond ~20 peers, bandwidth becomes a bottleneck and a relay server would be needed.

State Snapshots

Every tick, the engine calls JSON.stringify on your state object and stores the snapshot in a history buffer. During rollback, it calls JSON.parse to restore.

For complex games that need custom serialization, use manageState(exportFn, importFn) to provide your own snapshot/restore functions.

Three Types of Data

Multiplayer games produce three distinct types of data, each handled differently by the framework:

Events

Events are transient signals produced during tick: "an explosion happened", "play this sound", "show a score popup". They are NOT part of game state. The framework tracks them by frame number and uses a confirm/cancel protocol during rollback:

1. Normal play: emit('explosion', {x, y}) records the event and notifies subscribers
2. Rollback starts: events after the rollback frame are marked unconfirmed
3. Resimulation: if the same event is re-emitted (same type + frame + data), it's confirmed. Subscribers are NOT fired again.
4. Rollback finishes: unconfirmed events are cancelled. onEventCancelled fires for each.

This means a sound that plays during a rolled-back-and-resimulated frame keeps playing (confirmed). A sound from a frame that played differently after rollback gets stopped (cancelled) and the new sound plays instead.

Presentation Hints

Presentation hints are continuous data for smooth rendering — e.g., a trail of positions that Draw interpolates through. They're produced during Tick and consumed during Draw. They're not state (never snapshotted) and don't need the confirm/cancel protocol because they self-correct:

// In tick: record entity positions with timestamps
hints.trail('pacman', { x: 10, y: 5, sprite: 'walk' }, time);
hints.trail('pacman', { x: 10, y: 4, sprite: 'walk' }, time + moveTime);

// In draw: get smooth interpolated position
var pos = hints.sample('pacman', drawTime);
drawSprite(pos.sprite, pos.x, pos.y);

On the first trail() call per entity per tick, entries at or after the tick's start time are truncated. During rollback resimulation, this automatically removes stale data from the invalidated simulation and rebuilds it from the correct one.

Desync Detection

Periodically, peers exchange state hashes for confirmed frames (frames where all player inputs have been received). If hashes don't match, a desync has occurred. The engine logs the mismatch and can generate detailed incompatibility reports showing exactly which fields diverged.

The visual test suite provides tools for detecting and debugging desyncs.