kayf.dev

01 / 03 Real-time state replication

WebTransport State Engine

Bypassing TCP limits. Zero-allocation frame loops. Bit-exact determinism.

Glowing world lines of networked entities in space-time: snapshot beads along each path, dropped packets as hollow rings, a translucent render-time plane and dashed predictions beyond it
examples/arena120 ms RTT · 20% loss

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.

Domain
Server-authoritative state replication
Stack
Go 1.22 · TypeScript · zero core dependencies
Transport
WebTransport · HTTP/3 · QUIC datagrams
Status
Pre-alpha · protocol v0 · Apache-2.0

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.

  1. 01

    wtsec

    One .wtse file compiles to Go and TypeScript codecs, size proofs and a handshake hash.

  2. 02

    Room goroutine

    Fixed tick, single writer. Inputs drain from lock-free rings; commit fills an immutable ring slot.

  3. 03

    Encoder pool

    Per-peer relevance from the slot’s spatial hash, delta-encoded against the last acknowledged tick.

  4. 04

    QUIC

    Snapshots and inputs as datagrams. RPCs and events on their own reliable streams.

  5. 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.

examples/arena/arena.wtseWTSE
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 checkConsole
$ 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.

web/src/gen/arena.wtse.tsTypeScript
// 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

  1. 41delivered
  2. 42lost
  3. 43held
  4. 44held

42, 43 and 44 reach the app together, at least one RTT late.

WTSE · WebTransport over QUIC

  1. 41delivered
  2. 42lost, never resent
  3. 43delta vs last ack
  4. 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.

interest.goGo
// 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}
Four entity traces over time with snapshot beads, dropped-packet rings, a render-time line and a shaded jitter-buffer band
Four entities as scope traces. Beads are snapshots, rings are dropped datagrams bridged by interpolation. The bright line is the render clock; the band ahead of it is the adaptive delay that absorbs jitter.

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.

ts/packages/wtse/src/time.tsTypeScript
/** 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.

examples/arena/game/sim.goGo · server
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)
examples/arena/web/src/sim.tsTypeScript · client
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 == 0 per 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.

Source

github.com/kayfdev/wtse View Source Code & Benchmarks Apache-2.0 · Go 1.22+ · zero core dependencies · make bench && make bench-ts (opens in a new tab)