01 / 03 Real-time state replication
WebTransport State Engine
Bypassing TCP limits. Zero-allocation frame loops. Bit-exact determinism.
The arena demo at 60 ms ± 15 ms each way and 20% datagram loss. The bright disc is predicted and runs ahead of the dashed server ghost. Hits from bumpers only the server knows about are corrected by fading, not snapping. Outside the view ring the browser holds nothing.
01 Benchmarks
Measured, not targeted. The steady state allocates nothing on either side of the wire, and CI fails the build if that ever changes.
- Server tick · 1k entities
- 14.2 µs
- Commit, publish and encode for one peer, 300 of 1,000 entities changed. About 589 B on the wire, 0 allocs/op.
- Frame-loop GC
- 0 collections
- 200,000 frames of
room.advance()and view iteration under the V8 GC profiler. One collection fails CI. - Correction replay
- 0.42 µs
- Rebase on the server’s row, replay 20 unacknowledged inputs, capture the visual error.
- Session resume
- ~17 ms
- Transport failure to resumed session, new QUIC handshake included. Every missed frame is replayed exactly once per lane. Loopback, Chromium.
Apple M5 Pro · Go 1.26.4 · Node 24. Server figures run every peer’s encode inline on one goroutine; in production the encoder pool spreads them across cores. Reproduce with make bench and make bench-ts.
02 Architecture
One goroutine per room owns the world and never takes a lock. Encoder workers turn immutable snapshots into per-peer datagrams. The browser interpolates everyone else and predicts itself. One schema file defines every bit between them.
-
01
wtsec
One
.wtsefile compiles to Go and TypeScript codecs, size proofs and a handshake hash. -
02
Room goroutine
Fixed tick, single writer. Inputs drain from lock-free rings; commit fills an immutable ring slot.
-
03
Encoder pool
Per-peer relevance from the slot’s spatial hash, delta-encoded against the last acknowledged tick.
-
04
QUIC
Snapshots and inputs as datagrams. RPCs and events on their own reliable streams.
-
05
Browser
A render clock interpolates the world, a prediction clock steps the local entity. Zero garbage.
A Compiler
The schema is the codec.
JSON ships field names and decimal text the schema already knows. Protobuf drops the names but stays byte-aligned, tags every field and has no notion of range: a float on a 1 cm grid still costs 32 bits plus its tag. WTSE uses neither. Every field in a .wtse file declares its range and precision, and the compiler turns that into bits.
package arena; component Body @predicted { pos: vec2 quant(-128, 128, 0.01); }component Player { hue: u16 range(0, 359); bot: bool; away: bool; }component Bumper { radius: f32 quant(0, 8, 0.05); }component Prop { kind: u8 range(0, 3); }component WorldInfo { entities: u16; players: u16; } input Steer { move: vec2 quant(-1, 1, 0.01); boost: bool; } message JoinArena { name: string(16); hue: u16 range(0, 359); }message ViewReq { radius: u16 range(0, 400); } event Bumped @unreliable { bumper: u16; player: u16; } room Arena { components: Body, Player, Bumper, Prop, WorldInfo; input: Steer; join: JoinArena; events: Bumped; rpc SetView(ViewReq) returns (ViewReq); // … SetNetwork, Drop: the demo's network controls}
wtsec proves the budget before anything runs. Every entity record must fit one datagram slice, wire IDs are assigned by name so reordering declarations never changes the protocol, and the canonical schema hash travels in the handshake: a client built from another schema is rejected at HELLO.
$ wtsec check arena.wtsearena.wtse (package arena, hash 47bfa1e545da9728, datagram budget 1100 B) component Body 2 lanes full 30 bits delta ≤ 34 bits component Bumper 1 lane full 8 bits delta ≤ 10 bits component Player 3 lanes full 11 bits delta ≤ 13 bits component Prop 1 lane full 2 bits delta ≤ 3 bits component WorldInfo 2 lanes full 32 bits delta ≤ 36 bits input Steer 17 bits … event Bumped 32 bits datagram room Arena entity ≤ 127 bits (1.5% of a snapshot slice), input redundancy 16
The output is straight-line code for both languages: no reflection, no struct tags, no generic dispatch. A changed field costs one mask bit plus a zig-zag delta. Inside the 5-bit window that is 6 bits instead of 15; outside it, a 1-bit flag and the full value. Go and TypeScript write identical bits, checked against frozen cross-language vectors.
// Code generated by wtsec from arena.wtse. DO NOT EDIT.// Schema hash: 47bfa1e545da9728 export const Body = { // … encodeDelta(w: BitWriter, q: Uint32Array, o: number, b: Uint32Array, bo: number): boolean { let m = 0; if (q[o] !== b[bo]) m |= 0x1; if (q[o + 1] !== b[bo + 1]) m |= 0x2; if (m === 0) return false; w.writeBits(m, 2); if (m & 0x1) w.writeRel(q[o]!, b[bo]!, 15, 5); if (m & 0x2) w.writeRel(q[o + 1]!, b[bo + 1]!, 15, 5); return true; },
- Body.pos per axis · 256 units at 0.01
- 15bits
- A delta inside the window
- 6bits
- 1,000 entities · 300 changed · one tick
- ~589B
B Transport
A lost packet costs one tick. Not every tick behind it.
A WebSocket is one ordered TCP stream. Lose one segment and every byte queued behind it waits at least one round trip for the retransmission, by which point the state it carries is stale. Real-time state wants the newest value, not every value. TCP guarantees the opposite.
WebSocket · one ordered TCP stream
- 41delivered
- 42lost
- 43held
- 44held
42, 43 and 44 reach the app together, at least one RTT late.
WTSE · WebTransport over QUIC
- 41delivered
- 42lost, never resent
- 43delta vs last ack
- 44delta vs last ack
43 and 44 apply on arrival. The next delta repairs the loss.
WTSE moves snapshots and inputs to unreliable QUIC datagrams and never retransmits them. Each snapshot is a delta against the newest tick that client has acknowledged, so loss cannot break the chain; it only widens the next delta. Inputs are sent redundantly instead of resent. Reliable traffic gets its own QUIC streams, RPCs on the control stream and event channels on theirs, so an ordered lane can only ever block itself.
Interest management without locks
At 10,000 entities and 64 peers, encoding the whole world for everyone is the cost. On every send tick, the room goroutine builds a spatial hash into the immutable ring slot it just committed. Encoder workers query that slot in parallel while the room simulates the next tick: no locks, no shared mutable state, and an atomic refcount keeps the slot alive until its last encoder lets go.
Distances are computed as float32(dx·dx) + float32(dy·dy), so the in/out decision is identical on every platform. A hysteresis band keeps an entity hovering at the view edge from flickering.
- Tick · 10,000 entities × 64 peers
- 5.66 to 0.31ms
- Per peer, per tick
- 2,290 to 43B
- Radius query · 0 allocs
- 79ns
Both runs put every encode inline on one goroutine. The 18× comes from sending each peer only what it can see, not from extra cores; the encoder pool spreads what remains across them.
// relevance computes into e.rel the entities j's peer receives at slot cur// (encoder worker; reads only the immutable slot and the job).func (r *Room) relevance(j *encodeJob, cur *snapSlot) { // … inner := radius * radius prev := e.prev var q spatial.Query for q.Start(&cur.space.grid, x, y, radius+in.Hysteresis); q.Next(); { // Inside the radius: in. In the hysteresis band: in only if the peer // already had it. if id := int(q.ID); q.Dist2 <= inner || prev.Has(id) { rel.Add(id) } } e.rel = rel}
C Client runtime
No garbage. No tolerance.
The browser runs two clocks off one estimate of the server’s timeline. The render clock trails it by an adaptive delay, two send intervals plus twice the measured jitter (RFC 3550), and draws remote entities between two received ticks. It closes gaps by running at 0.95–1.05× real time, never by jumping. The prediction clock leads by RTT/2 plus the server’s input buffer, so each input lands just before the tick that consumes it; the server reports its de-jitter error in every PONG, and the lead trims itself.
Floats never cross a call
V8 boxes a double passed to or returned from a call it does not inline. At 120 Hz those heap numbers become collections, and collections become dropped frames. So the frame loop passes no floats: per-frame times live in one shared FrameClock, results land in fields, entity state lives in Uint32Array rows, and a snapshot’s baseline copy is a single TypedArray.set.
/** Per-frame times, shared by reference with the clocks. */export class FrameClock { // Initialized with fractions so V8 gives the fields a double // representation from the start (no map transition on first use). now = 0.5; dt = 0.5; serverTick = 0.5;} // … /** Number of input steps due at f.serverTick. */due(f: FrameClock, clock: ClockSync): number { // lead(), written inline: a float returned from a call V8 does not // inline is boxed, and this runs every frame. const rtt = clock.rtt; const target = f.serverTick + (rtt === rtt ? rtt : 0) / 2 / this.tickMs + this.buffer + 1 + this.trim;
Bit-exact, not approximately right
The client compares the server’s quantized row with its own prediction lane by lane, with no epsilon. That only holds if both sides compute the same bits. @predicted makes the server snap its live state to the wire grid at every commit, and the step function is mirrored in float32 on both sides: Math.fround after every operation in TypeScript, an explicit conversion around every product in Go, so the compiler cannot fuse a multiply-add into an FMA that rounds once where JavaScript rounds twice.
func Step(b *arena.BodyData, in *arena.Steer, dt float32) { // … if l := float32(mx*mx) + float32(my*my); l > 1 { inv := float32(1 / math.Sqrt(float64(l))) mx, my = float32(mx*inv), float32(my*inv) } step := float32(speed * dt) b.Pos.X = clamp(b.Pos.X+float32(mx*step), -HalfWidth+Radius, HalfWidth-Radius)
export function stepBody(b: BodyValue, inp: Readonly<SteerValue>, ctx: Readonly<PredictContext>): void { // … const l = f(f(mx * mx) + f(my * my)); if (l > 1) { const inv = f(1 / Math.sqrt(l)); mx = f(mx * inv); my = f(my * inv); } const step = f(speed * ctx.dt); b.pos.x = clamp(f(b.pos.x + f(mx * step)), -HALF_WIDTH + RADIUS, HALF_WIDTH - RADIUS);
A match confirms the prediction in 9 ns. A mismatch, from a bumper only the server knows about or an input lost on the way, rebases on the server’s row, replays every unacknowledged input and fades the visual error out over a half-life instead of snapping: 0.42 µs for a 20-input replay. Convergence is a test, not a claim: under 20% loss, 5% duplication and 15 ms jitter, every tick the TypeScript client completes must equal the Go server’s state byte for byte.
- Exact match · prediction confirmed
- 9ns
- Confirmed exactly · 220 ms RTT · 12% loss
- ~98%
- Go vs TS steps · identical float32 bits
- 5,000
03 Verification
Correctness is enforced in CI, not asserted in a README.
- Conformance
- Go writes frozen vectors. TypeScript must decode and re-encode every case byte for byte.
- Convergence
- A world mutates at random under 20% loss. Every completed tick equals the server’s state bit for bit, through interest-managed views.
- Determinism
- 5,000 movement steps in Go and in TypeScript, with identical float32 bits.
- Resume
- Each held event arrives once per lane. An RPC sent into a dead connection runs once. A replay buffer that is too small fails cleanly.
- Allocation gates
testing.AllocsPerRun == 0per tick. Zero V8 collections over 200,000 frames.- Hostile input
- Every Go test under
-race. Native fuzzing on every parser that sees client bytes.
04 Non-goals
No WebSocket fallback: networks that block UDP/443 are out of scope. Not lockstep, not peer-to-peer, not a database. Below about 5 Hz, where every message matters, WebSockets or SSE are the simpler, correct tool.
v0 limits: one room per session, and 16-bit NetIDs cap a room at 65,535 replicated entities. No compatibility guarantee before 1.0.