gizgame/net
the parts of a networked game that do not depend on the wire. The server is the authority: it runs the simulation at a fixed tick, takes each player's inputs (with their sequence numbers) and sends each player the state of what is near it (Interest). A state is records, one a replicated entity, and an input is a record too: each goes on the wire as its gizlang/wire bytes, or a record as the game's own quantized bytes (Writer); a player gets only what changed since the state it acknowledged (delta). A client predicts its own player with the same systems (Predictor) and replays its unacknowledged inputs over each state it gets, so its moves answer at once and still end where the server says. A shot is judged as the shooter saw it: the server keeps the targets of the last ticks (History) and rewinds to the tick the shooter's input names (lag compensation). Messages are bytes (encode, decode); Server and Client run a game of the game's Rules over them, and gizapp/netplay carries them on a WebSocket.
import * as Net from "gizgame/net";Types
Writer
class Writer { out: bytes = b""; unsigned(v: i64): Writer { Text.writeUVarint(this.out, u64(v)); return this; } signed(v: i64): Writer { Text.writeVarint(this.out, v); return this; } real(v: f64, step: f64): Writer { return this.signed(i64(Math.round(v/step))); } bytes(b: bytes): Writer { this.unsigned(b.length); this.out+ = b; return this; } text(s: string): Writer { return this.bytes(utf8(s)); } }Bytes written a value at a time: unsigned and signed (zigzag) varints of gizlang/text, and quantized reals.
out:bytes
Reader
class Reader { private data: bytes; at: i64 = 0; constructor(data: bytes) { this.data = data; } done(): bool { return this.at> = this.data.length; } unsigned(): i64 throws string { let r: Text.VarintUnsigned; try { r = Text.readUVarint(this.data, this.at, 63); } catch { throw "A message ends early"; } this.at = r.next; return i64(r.value); } signed(): i64 throws string { let r: Text.VarintSigned; try { r = Text.readVarint(this.data, this.at, 64); } catch { throw "A message ends early"; } this.at = r.next; return r.value; } real(step: f64): f64 throws string { return f64(this.signed())*step; } bytes(): bytes throws string { const n = this.unsigned(); if (n> this.data.length-this.at) { throw "A message ends early"; } const out = this.data.slice(this.at, this.at+n); this.at+ = n; return out; } text(): string throws string { return string(this.bytes()); } }The reader of what a Writer wrote; reading past the end fails ("A message ends early").
data:bytesat:i64
Message
type Message = { kind: i64; player: i64; tick: i64; sequence: i64; base: i64; text: string; data: bytes; }A message of any kind; the fields its kind does not use keep the values of message.
kind:i64player:i64tick:i64sequence:i64base:i64text:stringdata:bytes
State
type State = Map<i64, bytes>A state: each replicated entity's record by its ID.
Interest
class Interest { private cell: f64; private cells = new Map<string, Vec<i64>>(); private where = new Map<i64, string>(); constructor(cell: f64) { this.cell = cell; } private key(x: i64, z: i64): string { return `${x }, ${ z }`; } set(id: i64, x: f64, z: f64): void { const k = this.key(i64(Math.floor(x/this.cell)), i64(Math.floor(z/this.cell))); const old = this.where.get(id); if (old !== undefined && old! === k) { return; } if (old !== undefined) { this.cells.set(old!, (this.cells.get(old!) ?? []).filter(o => o !== id)); } let list = this.cells.get(k) ?? []; list.push(id); this.cells.set(k, list); this.where.set(id, k); } remove(id: i64): void { const old = this.where.get(id); if (old === undefined) { return; } this.cells.set(old!, (this.cells.get(old!) ?? []).filter(o => o !== id)); this.where.delete(id); } around(x: f64, z: f64, radius: f64): Vec<i64> { const cx = i64(Math.floor(x/this.cell)); const cz = i64(Math.floor(z/this.cell)); const n = i64(Math.ceil(radius/this.cell)); let out: Vec<i64> = []; for (const dz of range(-n, n+1)) { for (const dx of range(-n, n+1)) { for (const id of this.cells.get(this.key(cx+dx, cz+dz)) ?? []) { out.push(id); } } } return out.toSorted((a, b) => a <b); } }Who is where on x, z, in cells of CELL meters: what a player is near is what it is sent.
cell:f64cells:_gizlang_sdk_collections.Map<string, Vec<i64>>where:_gizlang_sdk_collections.Map<i64, string>
Target
type Target = { id: i64; center: Point3; radius: f64; }A target as a shot meets it: its ID and a sphere (a hitbox).
id:i64center:gizlang_geometry.Point3radius:f64
History
class History { private ticks: Vec<i64> = []; private frames: Vec<Vec<Target>> = []; private most: i64; constructor(most: i64 = 16) { this.most = most; } record(tick: i64, targets: Vec<Target>): void { this.ticks.push(tick); this.frames.push(targets); if (this.ticks.length> this.most) { this.ticks.splice(0, 1); this.frames.splice(0, 1); } } at(tick: i64): Vec<Target> { for (const k of range(0, this.ticks.length)) { if (this.ticks[k] === tick) { return this.frames[k]; } } return this.frames.length> 0 ? (tick <this.ticks[0] ? this.frames[0]: this.frames[this.frames.length-1]): []; } shot(tick: i64, origin: Point3, direction: Point3, farthest: f64, shooter: i64): Target | undefined { let best: Target | undefined = undefined; let nearest = farthest; for (const t of this.at(tick)) { if (t.id === shooter) { continue; } const m = sub(origin, t.center); const b = dot(m, direction); const c = dot(m, m)-t.radius*t.radius; if (c> 0.0 && b> 0.0) { continue; } const disc = b*b-c; if (disc <0.0) { continue; } const d = Math.max(0.0, -b-Math.sqrt(disc)); if (d <nearest) { nearest = d; best = t; } } return best; } }The targets of the last TICKS ticks, for judging a shot at the tick its shooter saw.
ticks:Vec<i64>frames:Vec<Vec<M186.Target>>most:i64
Pending
type Pending<I> = { sequence: i64; input: I; }An input I of the client's own player, kept until the server has taken it.
Opaque: create and use it through this module's functions.
Predictor
class Predictor<S, I> { state: S; private pending: Vec<Pending<I>> = []; private step: (s: S, input: I) => S; constructor(state: S, step: (s: S, input: I) => S) { this.state = state; this.step = step; } predict(sequence: i64, input: I): void { this.pending.push({ sequence, input }); this.state = this.step(this.state, input); } reconcile(authority: S, taken: i64): void { this.pending = this.pending.filter(p => p.sequence> taken); let s = authority; for (const p of this.pending) { s = this.step(s, p.input); } this.state = s; } waiting(): i64 { return this.pending.length; } }A client's prediction of its own player of state S: STEP applies one input I to S (the systems the server runs on it). Each input applies at once; a server state takes the place of the prediction and the inputs the server has not taken apply again on top.
Opaque: create and use it through this module's functions.
Shot
type Shot = { origin: Point3; direction: Point3; farthest: f64; }A shot an input fires: from ORIGIN along the unit DIRECTION, as far as FARTHEST (where the world stops it).
origin:gizlang_geometry.Point3direction:gizlang_geometry.Point3farthest:f64
Rules
type Rules<P, I> = { spawn: (player: i64) => P; idle: I; step: (p: P, input: I, dt: f64) => P; where: (p: P) => Point3; aim?: (p: P, input: I) => Shot | undefined; hurt?: (target: P, shooter: i64) => P; credit?: (shooter: P, before: P, after: P) => P; radius?: f64; write?: (p: P) => bytes; read?: (b: bytes) => P throws string; }A game's players of record P and their inputs of record I, as Server and Client run them. SPAWN makes player N's record, IDLE is the input of a tick with none (and the shape of every input), and STEP applies one input for DT seconds: the server runs it, and the client predicts with the same function. WHERE is where a record stands. When shots matter, AIM is the shot an input fires, HURT what a hit does to its target, CREDIT what the shooter gets for it (the target before and after the hit), and RADIUS the hitbox around a record's WHERE. Records and inputs go on the wire as gizlang/wire writes them; WRITE and READ, when given, are a record's own smaller bytes (Writer's quantized reals).
Opaque: create and use it through this module's functions.
Sent
type Sent = { player: i64; message: bytes; }A message for PLAYER, as a tick gives it.
player:i64message:bytes
Server
class Server<P, I> { hz: f64; tick: i64 = 0; private rules: Rules<P, I>; private wire: Codec<P, I>; private reach: f64; private players = new Map<i64, P>(); private inputs = new Map<i64, Vec<Message>>(); private taken = new Map<i64, i64>(); private acked = new Map<i64, i64>(); private sent = new Map<i64, Map<i64, State>>(); private welcomes: Vec<i64> = []; private driven = new Set<i64>(); private next: i64 = 0; private interest: Interest; private history: History; constructor(hz: f64, rules: Rules<P, I>, reach: f64 = 80.0) throws string { this.wire = new Codec<P, I>(rules); this.hz = hz; this.rules = rules; this.reach = reach; this.interest = new Interest(reach*0.5); this.history = new History(i64(hz)); } seated(): Vec<i64> { return this.players.keys().toSorted((a, b) => a <b); } player(n: i64): P | undefined { return this.players.get(n); } join(driven: bool = false): i64 { const n = this.next; this.next+ = 1; const p = this.rules.spawn(n); this.players.set(n, p); this.inputs.set(n, []); this.taken.set(n, -1); this.acked.set(n, -1); if (driven) { this.driven.add(n); } else { this.sent.set(n, new Map<i64, State>()); this.welcomes.push(n); } const at = this.rules.where(p); this.interest.set(n, at.x, at.z); return n; } leave(n: i64): void { this.players.delete(n); this.inputs.delete(n); this.taken.delete(n); this.acked.delete(n); this.sent.delete(n); this.driven.delete(n); this.welcomes = this.welcomes.filter(w => w !== n); this.interest.remove(n); } drive(n: i64, input: I): void { const queue = this.inputs.get(n); if (queue === undefined || !this.driven.has(n)) { return; } let m = message(INPUT); m.tick = this.tick; m.sequence = (this.taken.get(n) ?? -1)+queue!.length+1; m.data = this.wire.input(input); let q = queue!; q.push(m); this.inputs.set(n, q); } heard(n: i64, data: bytes): void { const decoded = decode(data).maybe(); if (decoded === undefined) { return; } const m = decoded!; const queue = this.inputs.get(n); if (queue === undefined) { return; } if (m.kind === INPUT && queue!.length <QUEUED) { let q = queue!; q.push(m); this.inputs.set(n, q); } if (m.kind === ACK) { this.acked.set(n, Math.maxI64(this.acked.get(n) ?? -1, m.tick)); } } step(): Vec<Sent> { const dt = 1.0/this.hz; const r = this.rules; const ids = this.seated(); const box = r.radius ?? 0.5; const aim = r.aim; const hurt = r.hurt; const credit = r.credit; if (aim !== undefined) { this.history.record(this.tick, ids.map((id: i64): Target => ({ id, center: r.where(this.players.get(id)!), radius: box }))); } for (const n of ids) { for (const m of this.inputs.get(n) ?? []) { if (!this.players.has(n)) { break; } const input = this.wire.order(m.data).maybe() ?? r.idle; const p = r.step(this.players.get(n)!, input, dt); this.players.set(n, p); this.taken.set(n, m.sequence); const shot = aim === undefined ? undefined: aim!(p, input); if (shot === undefined || hurt === undefined) { continue; } const hit = this.history.shot(m.tick, shot!.origin, shot!.direction, shot!.farthest, n); if (hit === undefined || !this.players.has(hit!.id)) { continue; } const before = this.players.get(hit!.id)!; const after = hurt!(before, n); this.players.set(hit!.id, after); if (credit !== undefined) { this.players.set(n, credit!(this.players.get(n)!, before, after)); } } this.inputs.set(n, []); const p = this.players.get(n); if (p !== undefined) { const at = r.where(p!); this.interest.set(n, at.x, at.z); } } this.tick+ = 1; let out: Vec<Sent> = []; for (const n of this.welcomes) { let w = message(WELCOME); w.player = n; w.tick = this.tick; out.push({ player: n, message: encode(w) }); } this.welcomes = []; for (const n of ids) { const p = this.players.get(n); if (p === undefined || this.driven.has(n)) { continue; } const at = r.where(p!); let now = new Map<i64, bytes>(); for (const id of this.interest.around(at.x, at.z, this.reach)) { const o = this.players.get(id); if (o !== undefined) { now.set(id, this.wire.record(o!)); } } let kept = this.sent.get(n)!; const acked = this.acked.get(n) ?? -1; const base = kept.get(acked); let s = message(STATE); s.tick = this.tick; s.sequence = this.taken.get(n) ?? -1; s.base = base === undefined ? -1: acked; s.data = base === undefined ? stateBytes(now): delta(base!, now); kept.set(this.tick, now); for (const old of kept.keys()) { if (old <= this.tick-KEPT) { kept.delete(old); } } this.sent.set(n, kept); out.push({ player: n, message: encode(s) }); } return out; } }The authority of a networked game at HZ ticks a second: it seats players, applies each one's inputs at its tick (a shot judged at the tick its shooter saw), and sends each the records within REACH meters of it, as a delta from the last state that player acknowledged. One thread owns it (gizapp/netplay's room).
Opaque: create and use it through this module's functions.
Client
class Client<P, I> { player: i64 = -1; tick: i64 = 0; now: State = new Map<i64, bytes>(); before: State = new Map<i64, bytes>(); private rules: Rules<P, I>; private wire: Codec<P, I>; private hz: f64; private own: Predictor<P, I> | undefined = undefined; private states = new Map<i64, State>(); private sequence: i64 = 0; private out: Vec<bytes> = []; constructor(hz: f64, rules: Rules<P, I>) throws string { this.hz = hz; this.rules = rules; this.wire = new Codec<P, I>(rules); } welcomed(): bool { return this.own !== undefined; } mine(): P | undefined { return this.own === undefined ? undefined: this.own!.state; } heard(data: bytes): void throws string { const m = decode(data); const r = this.rules; const dt = 1.0/this.hz; if (m.kind === WELCOME) { this.player = m.player; this.tick = m.tick; this.own = new Predictor<P, I>(r.spawn(m.player), (s: P, input: I): P => r.step(s, input, dt)); return; } if (m.kind !== STATE) { return; } const base: Option<Map<i64, bytes>> = m.base <0 ? new Map<i64, bytes>(): this.states.get(m.base); if (base === undefined) { return; } const s = applied(base!, m.data); this.states.set(m.tick, s); for (const old of this.states.keys()) { if (old <= m.tick-KEPT) { this.states.delete(old); } } this.before = this.now; this.now = s; this.tick = m.tick; let ack = message(ACK); ack.tick = m.tick; this.out.push(encode(ack)); const mine = s.get(this.player); if (mine !== undefined && this.own !== undefined) { this.own!.reconcile(this.wire.player(mine!), m.sequence); } } input(input: I): void { if (this.own === undefined) { return; } this.sequence+ = 1; this.own!.predict(this.sequence, input); let i = message(INPUT); i.tick = this.tick; i.sequence = this.sequence; i.data = this.wire.input(input); this.out.push(encode(i)); } next(): bytes { if (this.out.length === 0) { return b""; } const first = this.out[0]; this.out.splice(0, 1); return first; } others(): Vec<P> throws string { let out: Vec<P> = []; for (const id of this.now.keys().toSorted((a, b) => a <b)) { if (id !== this.player) { out.push(this.wire.player(this.now.get(id)!)); } } return out; } }A player's side of a networked game: it takes the server's messages (heard), sends its inputs at once and predicts its own record with the server's STEP (input), and gives what to send (next). OWN is its record as predicted, NOW and BEFORE the last two states (draw the others between them).
Opaque: create and use it through this module's functions.
Seats
type Seats = { hz: f64; guests: bool; join: (id: string, name: string) => i64 throws string; heard: (player: i64, message: bytes) => void; leave: (player: i64) => void; tick: () => Vec<Sent>; }A match's seats, which a served game's room carries (gizapp/netplay, on a thread of its own) or a Session runs in one program: HZ ticks a second; GUESTS, whether a player with no Giz account may sit; JOIN seats the account ID ("" a guest) named NAME, or says why not; HEARD takes a player's message; LEAVE frees its seat; TICK advances one tick and gives what to send.
hz:f64guests:booljoin:(arg0: string, arg1: string) => i64 throws stringheard:(arg0: i64, arg1: bytes) => voidleave:(arg0: i64) => voidtick:() => Vec<M186.Sent>
Session
class Session<P, I> { client: Client<P, I>; online: bool = false; private hz: f64; private rules: Rules<P, I>; private make: () => Seats; private seats: Seats | undefined = undefined; private me: i64 = -1; constructor(hz: f64, rules: Rules<P, I>, make: () => Seats) throws string { this.hz = hz; this.rules = rules; this.make = make; this.client = new Client<P, I>(hz, rules); } tick(): void throws string { if (this.online) { return; } if (this.seats === undefined) { const s = this.make(); this.seats = s; this.me = s.join("", "Guest"); } const seats = this.seats!; while (true) { const m = this.client.next(); if (m.length === 0) { break; } seats.heard(this.me, m); } for (const s of seats.tick()) { if (s.player === this.me) { this.client.heard(s.message); } } } carry(input: bytes): bytes { if (!this.online) { this.online = true; this.seats = undefined; this.client = new Client<P, I>(this.hz, this.rules)!; } if (input.length> 0) { void(this.client.heard(input).maybe()); return b""; } return this.client.next(); } }A player's match. Alone, the seats that MAKE gives run in this program and CLIENT plays on them through the same messages a server would carry; once a host carries the messages (carry, the program's net export), the server it reaches decides and the seats here are dropped.
Opaque: create and use it through this module's functions.
Functions
constructor
constructor(data: bytes)A reader at the start of DATA.
Effects: fail, read, write, alloc.
message
function message(kind: i64): MessageAn empty message of KIND.
Effects: fail.
encode
function encode(m: Message): bytesThe bytes of M.
Effects: fail, alloc.
decode
function decode(b: bytes): Message throws stringThe message of B; it fails on bytes that are no message.
Effects: fail, alloc.
delta
function delta(base: State, now: State): bytesThe change from BASE to NOW: each record removed, new, or changed (its bytes XORed with the base's and the runs of zeros counted, so a record that barely changed costs a few bytes).
Effects: fail, read, write, alloc.
applied
function applied(base: State, d: bytes): State throws stringBASE changed by DELTA.
Effects: fail, read, write, alloc.
stateBytes
function stateBytes(s: State): bytesA state as one message's bytes (stateOf reads them back).
Effects: fail, read, write, alloc.
stateOf
function stateOf(b: bytes): State throws stringThe state of bytes that stateBytes wrote.
Effects: fail, read, write, alloc.
constructor
constructor(cell: f64)An empty grid of CELL meters.
Effects: fail, read, write, alloc.
constructor
constructor(most: i64 = 16)A history that keeps the last MOST ticks.
Effects: fail, read, write, alloc.
constructor
constructor(state: S, step: (s: S, input: I) => S)A prediction from STATE, where STEP applies an input.
constructor
constructor(hz: f64, rules: Rules<P, I>, reach: f64 = 80.0) throws stringA server of RULES at HZ ticks a second; a player is sent what is within REACH meters.
constructor
constructor(hz: f64, rules: Rules<P, I>) throws stringA client of RULES at HZ ticks a second, before its welcome.
seatsOf
function seatsOf<P, I>(server: Server<P, I>, guests: bool, drive: () => void): SeatsThe seats of SERVER, GUESTS as Seats says: each tick, DRIVE first gives the inputs of the seats this program plays itself (Server.drive), then the server steps.
constructor
constructor(hz: f64, rules: Rules<P, I>, make: () => Seats) throws stringA session of RULES at HZ ticks a second; MAKE gives the seats of a match in this program.
Methods
Writer.unsigned
unsigned(v: i64): WriterWrites V, at least 0, as an unsigned varint.
Effects: fail, read, write, alloc.
Writer.signed
signed(v: i64): WriterWrites V as a signed (zigzag) varint.
Effects: fail, read, write, alloc.
Writer.real
real(v: f64, step: f64): WriterV to the nearest STEP (a millimeter for a position, 1/4096 of a radian for an angle).
Effects: fail, read, write, alloc.
Writer.bytes
bytes(b: bytes): WriterWrites B after its length.
Effects: fail, read, write, alloc.
Writer.text
text(s: string): WriterWrites S as its UTF-8 bytes.
Effects: fail, read, write, alloc.
Reader.done
done(): boolWhether every byte is read.
Effects: fail, read.
Reader.unsigned
unsigned(): i64 throws stringThe next unsigned varint.
Effects: fail, read, write.
Reader.signed
signed(): i64 throws stringThe next signed (zigzag) varint.
Effects: fail, read, write.
Reader.real
real(step: f64): f64 throws stringThe next real that Writer.real wrote to the nearest STEP.
Effects: fail, read, write.
Reader.bytes
bytes(): bytes throws stringThe next bytes, after their length.
Effects: fail, read, write, alloc.
Reader.text
text(): string throws stringThe next text.
Effects: fail, read, write, alloc.
Interest.set
set(id: i64, x: f64, z: f64): voidPuts ID at X, Z.
Effects: fail, read, write, alloc.
Interest.remove
remove(id: i64): voidForgets where ID is.
Effects: fail, read, write, alloc.
Interest.around
around(x: f64, z: f64, radius: f64): Vec<i64>The IDs in the cells within RADIUS of X, Z, in order.
Effects: fail, read, alloc.
History.record
record(tick: i64, targets: Vec<Target>): voidKeeps TARGETS as they are at TICK, dropping the oldest past MOST.
Effects: fail, read, write, alloc.
History.at
at(tick: i64): Vec<Target>The targets at TICK, else the oldest kept (a shooter further behind is judged at the edge).
Effects: fail, read, alloc.
History.shot
shot(tick: i64, origin: Point3, direction: Point3, farthest: f64, shooter: i64): Target | undefinedThe nearest target at TICK that the ray from ORIGIN along the unit DIRECTION meets within FARTHEST, not SHOOTER.
Effects: fail, read, alloc.
Predictor.predict
predict(sequence: i64, input: I): voidApplies INPUT of SEQUENCE now and keeps it.
Predictor.reconcile
reconcile(authority: S, taken: i64): voidThe server's state AUTHORITY after its input TAKEN: the prediction from there.
Predictor.waiting
waiting(): i64How many inputs wait for the server.
Server.seated
seated(): Vec<i64>The seated players' numbers, in order.
Server.player
player(n: i64): P | undefinedThe record of player N, if seated.
Server.join
join(driven: bool = false): i64Seats a new player: its number. A DRIVEN seat is one this program plays itself (a bot: drive): it is sent nothing.
Server.leave
leave(n: i64): voidFrees the seat of player N.
Server.drive
drive(n: i64, input: I): voidThe INPUT of the driven seat N for this tick, as its client would send it.
Server.heard
heard(n: i64, data: bytes): voidThe message DATA of player N. One that does not decode, or that a client may not send, is dropped.
Server.step
step(): Vec<Sent>One tick: every queued input applied, then the messages to send.
Client.welcomed
welcomed(): boolWhether the server has welcomed this player (seated it).
Client.mine
mine(): P | undefinedThe own record, as predicted.
Client.heard
heard(data: bytes): void throws stringA message of the server.
Client.input
input(input: I): voidApplies the own INPUT now and sends it.
Client.next
next(): bytesThe next message to send, b"" none.
Client.others
others(): Vec<P> throws stringThe other players' records in the last state, with their numbers.
Session.tick
tick(): void throws stringAfter the tick's input: alone, its messages through the seats here, and theirs back.
Session.carry
carry(input: bytes): bytesThe host's call (Program.net): INPUT, a message of the server; b"", the next one to send (b"" none). The first call takes the match online. A message that does not decode is dropped.
Constants
MILLIMETER
const MILLIMETER = 0.001The step of a position that a state writes: a millimeter.
ANGLE
const ANGLE = 0.000244140625The step of an angle that a state writes: 1/4096 of a radian.
WELCOME
const WELCOME: i64 = 1WELCOME to a client (its player and the tick), INPUT from it (the tick it is for, its sequence and the game's bytes), STATE to it (the tick, the last input sequence the server took, the tick of the state it is a delta from, -1 none, and the delta), ACK from it (the tick of the last state it took). Who a client is the transport settles before the first message (gizapp/netplay: a Giz sign-in token).
INPUT
const INPUT: i64 = 2From a client: its input for a tick.
STATE
const STATE: i64 = 3To a client: the state of a tick, whole or a delta.
ACK
const ACK: i64 = 4From a client: the tick of the last state it took.