tickcli-js 0.0.0-stage → 0.1.1

package/client/room.js

@@ -0,0 +1,632 @@
+/* tickcli room.js - play a one-file browser game together, live. MIT. Load it BEFORE game.js and pass
+   multiplayer: {max, player:{field:[low, high]}} to Game({...}); the game shell (game.js) does the lobby, start, reconnects and notices.
+   This file is the low-level part the shell uses (window.tickcli). Pages normally never call it directly.
+
+   How it works: the page may be sandboxed with no network, so it says hello to the window around it (or to itself, when it is the top page); a relay
+   there (relay.js) answers with a private channel and keeps the one WebSocket to the server. The server decides who each player is, keeps the shared state and the order of changes, and picks one player as host.
+   Each player writes only their own state; the host writes the shared state; anyone can ask the host to do something (an action). */
+(function () {
+  "use strict";
+  // Others are drawn a little in the past, so their movement is smooth. How far is measured per room (Mirror's rule): the mean delay of the last 40
+  // updates (their arrival minus the sender's own sample time), plus 2 send intervals, plus the delay's spread, kept between 100 and 500 ms. The
+  // drawing clock follows that target by running 2% fast or 4% slow, never by a jump. With no newer update it goes on at the last speed for 100 ms,
+  // then holds.
+  var DELAY = 120, lags = [], drawT = 0, drawAt = 0;
+  var SEND_MS = 80;           // own state goes out at most 12 times a second (10 in rooms over 8 players); set() can be called every frame
+  var listeners = {}, port = null, info = null, ready = [], nonce = Math.random().toString(36).slice(2);
+  var R = {
+    available: false, status: "idle", you: null, code: null, priv: false, match: 0, term: 0, host: null, started: false, boot: null, max: 0,
+    players: {}, shared: {}, spec: null, guest: false, closed: null, saved: null, resumed: false, saveBusy: false, saveError: false, newer: false,
+  };
+  var prof = null, profOff = false, profPend = null, profWait = [], profT = 0, profGaveUp = false, profLate = null;
+  var roomsWait = [], roomsLast = null;   // rooms(): waiting callers, and the last answer (asked at most once a second)
+  var fxQ = [], fxTimes = [];   // effects over 20 a second wait for the next send slot (the server drops messages over its rate)
+  var FEATS = ["fxb"];          // told to the server in join: effects come inside the delta frame
+  var sentMe = {}, sentShared = {};   // what the server has from us (as sent, after rounding): only values that differ go out
+  var meAt = 0, sharedAt = 0;   // when the values waiting to go out were set (shared clock): sent along as their sample time
+  var mePend = null, sharedPend = null, lastSend = 0, flushT = 0, aliveAt = 0, actSeq = 0, acts = {}, offset = 0, syncAsked = 0;
+  // the clock: the last 8 ping answers {rtt, off, at}; the offset of the fastest one is the target, and the offset in use moves toward it over a second
+  var clk = [], offTarget = 0, offAt = 0, clockSet = false;
+
+  function emit(name, a, b, c, d) { var l = listeners[name] || []; for (var i = 0; i < l.length; i++) try { l[i](a, b, c, d); } catch (e) { console.error(e); } }
+  function post(m) { if (port) port.postMessage(m); }
+  function send(m) { post({ k: "send", m: m }); }
+  var copy = function (v) { return v == null ? v : JSON.parse(JSON.stringify(v)); };
+  var isObj = function (v) { return !!v && typeof v === "object" && !Array.isArray(v); };
+  /** Writes merge deeply, as on the server: {hp: {a: 80}} changes only a's hp, null removes a key, lists are replaced whole. */
+  function merge(into, patch) {
+    for (var k in patch) {
+      var v = patch[k];
+      if (v === null) delete into[k];
+      else if (isObj(v)) { if (!isObj(into[k])) into[k] = {}; merge(into[k], v); }
+      else into[k] = v;
+    }
+  }
+  // The shared state is never changed in place: a write makes new objects only along the paths it touches and reuses the rest (each one frozen).
+  // So a buffered copy for smoothing is just a reference, two versions differ only where === differs, and the game can read it without a copy.
+  function frozen(v) {
+    if (!v || typeof v !== "object" || Object.isFrozen(v)) return v;
+    for (var k in v) frozen(v[k]);
+    return Object.freeze(v);
+  }
+  /** A new version of `base` with `patch` merged in (same rules as merge); untouched branches are the same objects as in base. */
+  function cow(base, patch) {
+    var out = {}, k;
+    if (isObj(base)) for (k in base) out[k] = base[k];
+    for (k in patch) {
+      var v = patch[k];
+      if (v === null) delete out[k];
+      else if (isObj(v)) out[k] = cow(out[k], v);
+      else out[k] = v && typeof v === "object" ? frozen(copy(v)) : v;
+    }
+    return Object.freeze(out);
+  }
+  /** The part of a patch that changes `cur` (equal values left out, a null for a missing key too, lists compared as text); null = nothing. */
+  function diff(cur, patch) {
+    var out = null;
+    for (var k in patch) {
+      var v = patch[k], has = Object.prototype.hasOwnProperty.call(cur, k), c = has ? cur[k] : undefined, keep;
+      if (v === null || v === undefined) { if (!has) continue; keep = null; }
+      else if (isObj(v)) { if (isObj(c)) { keep = diff(c, v); if (!keep) continue; } else keep = v; }
+      else if (Array.isArray(v)) { if (Array.isArray(c) && JSON.stringify(c) === JSON.stringify(v)) continue; keep = v; }
+      else { if (c === v) continue; keep = v; }
+      (out = out || {})[k] = keep;
+    }
+    return out;
+  }
+  /** Two patches going out together (nulls kept). */
+  function join(into, patch) { for (var k in patch) { var v = patch[k]; if (isObj(v) && isObj(into[k])) join(into[k], v); else into[k] = v === undefined ? null : copy(v); } }
+  // The server's limits, counted the way it counts them: bytes (a Vietnamese letter is 3, an emoji 4), not characters.
+  var LIMIT = 12000;   // the server takes 16 KB per message: a bigger update goes out in several parts of at most this many bytes (the envelope fits in the rest)
+  var enc = typeof TextEncoder === "function" ? new TextEncoder() : null;
+  function size(v) { var t = JSON.stringify(v); return enc ? enc.encode(t).length : unescape(encodeURIComponent(t)).length; }
+  /** Split a patch into parts of at most LIMIT bytes. A big object (60 monsters) is split by its keys, at any depth; each part merges into the same
+      place. A single value that cannot be split (one long list or text) is not sent: tooBig(path) is called instead. */
+  function chunks(p, tooBig) {
+    var leaves = [];
+    (function walk(v, at) {
+      for (var k in v) {
+        var path = at.concat(k), one = wrap(path, v[k]), len = size(one);
+        if (len <= LIMIT) leaves.push({ one: one, len: len });
+        else if (isObj(v[k])) walk(v[k], path);
+        else if (tooBig) tooBig(path.join("."));
+      }
+    })(p, []);
+    var out = [], cur = null, used = 0;
+    for (var i = 0; i < leaves.length; i++) {
+      if (cur && used + leaves[i].len > LIMIT) { out.push(cur); cur = null; used = 0; }
+      if (!cur) cur = {};
+      join(cur, leaves[i].one); used += leaves[i].len;   // the sum of the parts is never smaller than them put together
+    }
+    if (cur) out.push(cur);
+    return out;
+  }
+  function wrap(path, v) { var o = {}, at = o; for (var i = 0; i < path.length - 1; i++) { at[path[i]] = {}; at = at[path[i]]; } at[path[path.length - 1]] = v; return o; }
+  // The shape the server takes (hub.ts SHAPE): text up to 200 characters, lists up to 64 items, 64 keys per object, 4 levels deep, keys up to 40
+  // characters, finite numbers. A write that breaks any of them is refused whole, so it is checked here first and never applied or sent.
+  var BAD = { __proto__: 1, constructor: 1, prototype: 1 };
+  function badPath(v, depth, at) {
+    if (v === null || v === undefined || typeof v === "boolean") return null;   // undefined: JSON leaves it out (a removal when it goes out)
+    if (typeof v === "number") return isFinite(v) ? null : at;
+    if (typeof v === "string") return v.length <= 200 ? null : at;
+    if (depth >= 4) return at;
+    var i, b;
+    if (Array.isArray(v)) {
+      if (v.length > 64) return at;
+      for (i = 0; i < v.length; i++) { b = badPath(v[i], depth + 1, at ? at + "." + i : String(i)); if (b !== null) return b; }
+      return null;
+    }
+    if (typeof v !== "object" || Object.getPrototypeOf(v) !== Object.prototype) return at;
+    var keys = Object.keys(v);
+    if (keys.length > 64) return at;
+    for (i = 0; i < keys.length; i++) {
+      var k = keys[i], here = at ? at + "." + k : k;
+      if (k.length > 40 || BAD[k] === 1) return here;
+      b = badPath(v[k], depth + 1, here);
+      if (b !== null) return b;
+    }
+    return null;
+  }
+  /** A write the server would refuse: tell the game (error event: code, path) instead of sending it. True when the patch is fine. */
+  function checked(patch) {
+    var b = badPath(patch, 0, "");
+    if (b === null) return true;
+    emit("error", "bad_value", b);
+    return false;
+  }
+  // Moving things in the shared state (monsters, minions, shots: any number named x, y, z, angle or rot) are drawn smoothly on every screen but the
+  // host's, the same way as players: a little in the past, eased between the two updates around that moment.
+  // A rotation in 3D is a unit quaternion in four fields qx, qy, qz, qw (three.js order): eased as one (slerp, the short way round), never per field.
+  var LERP = { x: 1, y: 1, z: 1, angle: 1, rot: 1, qx: 1, qy: 1, qz: 1, qw: 1 }, QK = { qx: 1, qy: 1, qz: 1, qw: 1 };
+  // Positions go out as whole numbers (pixels) unless the game asks for decimals (precision(2): a 3D world in metres keeps centimetres).
+  var POS = 1;
+  // angle and rot are radians: they ease the short way round (from 3.1 to -3.1 is a small turn, not a full spin backwards)
+  var TURN = { angle: 1, rot: 1 }, TAU = Math.PI * 2;
+  function ease(k, a, b, f) {
+    if (!TURN[k]) return a + (b - a) * f;
+    var d = (b - a) % TAU; if (d > Math.PI) d -= TAU; else if (d < -Math.PI) d += TAU;
+    return a + d * f;
+  }
+  /** out's quaternion (qx, qy, qz, qw) set to the slerp from A's to B's at f (f may run a little past 1: going on at the last speed). Needs all four in
+      both; q and -q are the same turn, so the short way round is taken. The result is always of length 1. */
+  function quatEase(out, A, B, f) {
+    var ax = A.qx, ay = A.qy, az = A.qz, aw = A.qw, bx = B.qx, by = B.qy, bz = B.qz, bw = B.qw;
+    if (typeof ax !== "number" || typeof ay !== "number" || typeof az !== "number" || typeof aw !== "number" ||
+        typeof bx !== "number" || typeof by !== "number" || typeof bz !== "number" || typeof bw !== "number") return;
+    var d = ax * bx + ay * by + az * bz + aw * bw;
+    if (d < 0) { d = -d; bx = -bx; by = -by; bz = -bz; bw = -bw; }
+    var s0 = 1 - f, s1 = f;
+    if (d < 0.9995) { var th = Math.acos(Math.min(1, d)), sn = Math.sin(th); s0 = Math.sin((1 - f) * th) / sn; s1 = Math.sin(f * th) / sn; }
+    var x = s0 * ax + s1 * bx, y = s0 * ay + s1 * by, z = s0 * az + s1 * bz, w = s0 * aw + s1 * bw, l = Math.sqrt(x * x + y * y + z * z + w * w);
+    if (!(l > 1e-9)) return;
+    out.qx = x / l; out.qy = y / l; out.qz = z / l; out.qw = w / l;
+  }
+  var sbuf = [];
+  /** Where two versions (made by cow()) differ in a moving number: {key: 1 (the number) or {...} (inside)}, null = nothing moves. Only branches that
+      differ (!==) are looked at; worked out once per pair of updates, not per frame. */
+  function movers(A, B, depth) {
+    if (A === B || !isObj(A)) return null;
+    var plan = null;
+    for (var k in B) {
+      var a = A[k], b = B[k];
+      if (a === b) continue;
+      if (typeof b === "number" && typeof a === "number") { if (LERP[k] && a !== b) (plan = plan || {})[k] = 1; }
+      else if (depth < 4 && isObj(b) && isObj(a)) { var sub = movers(a, b, depth + 1); if (sub) (plan = plan || {})[k] = sub; }
+    }
+    return plan;
+  }
+  /** B with the moving numbers in plan eased from A: new objects only along those paths, everything else is B's own. */
+  function eased(A, B, plan, f) {
+    var out = {}, k;
+    for (k in B) out[k] = B[k];
+    for (k in plan) out[k] = plan[k] === 1 ? ease(k, A[k], B[k], f) : eased(A[k], B[k], plan[k], f);
+    if (plan.qx || plan.qy || plan.qz || plan.qw) quatEase(out, A, B, f);
+    return Object.freeze(out);
+  }
+  var pA = null, pB = null, pPlan = null;
+  /** Where between two buffered updates (at) the drawing time t falls: 0..1 between them, up to 100 ms past the newer one (going on at the last
+      speed), then held there. */
+  function frac(t, A, B) { return Math.max(0, (Math.min(t, B.at + 100) - A.at) / (B.at - A.at)); }
+  function sharedView() {
+    if (R.host === R.you || sbuf.length < 2) return R.shared;
+    var t = drawTime(), i = sbuf.length - 1;
+    while (i > 0 && sbuf[i - 1].at > t) i--;
+    var A = sbuf[Math.max(0, i - 1)], B = sbuf[i];
+    if (A === B || B.at <= A.at) return R.shared;
+    if (pA !== A.s || pB !== B.s) { pA = A.s; pB = B.s; pPlan = movers(A.s, B.s, 0); }
+    return pPlan ? eased(A.s, B.s, pPlan, frac(t, A, B)) : B.s;
+  }
+  /** Buffer entries are kept in time order: a stamp at or before the last one is moved just after it. */
+  function push(buf, at, s, max) { var last = buf[buf.length - 1]; if (last && at <= last.at) at = last.at + 1; buf.push({ at: at, s: s }); if (buf.length > max) buf.splice(0, buf.length - max); }
+  function keepShared(at) { push(sbuf, at, R.shared, 8); }
+  /** One update arrived whose values were sampled at `stamp` (the sender's time on the shared clock). */
+  function lagOf(stamp) {
+    lags.push(serverMs() - stamp); if (lags.length > 40) lags.shift();
+    if (lags.length < 4) return;
+    var mean = 0, v = 0, i; for (i = 0; i < lags.length; i++) mean += lags[i]; mean /= lags.length;
+    for (i = 0; i < lags.length; i++) v += (lags[i] - mean) * (lags[i] - mean);
+    // on a slower update rate (Q.rate > 1) frames come further apart: the delay covers 2 of those gaps instead, up to 800 ms
+    var gap = Math.max(sendMs(), Q.every || 0);
+    DELAY = Math.max(100, Math.min(Q.rate > 1 ? 800 : 500, mean + 2 * gap + Math.sqrt(v / lags.length)));
+  }
+
+  // ---- update rate: fewer frames for a slow link or a slow device ----------------------------------------------------------------------
+  // The hub watches its own send queue to this page; the page watches two things the hub cannot see: how late frames arrive (the shared clock
+  // minus the hub's send time: on a link that cannot keep up this grows as messages queue, while a merely far-away player keeps a steady value),
+  // and how fast the game draws (game.js reports frames a second). When either is bad for 2 s the page asks for half the rate (then a quarter);
+  // after 15 s of good readings it asks one step back. The hub uses the slower of its reading and the page's ask and says which (rate {div}).
+  // navigator.connection (Chrome, Edge, Android) only sets the starting point: saveData or 3g = half, 2g = a quarter.
+  var Q = { rate: 1, every: 0, ask: 1, net: 1, dev: 1, lateMs: 0, fps: 0, rtt: 0 };
+  var late = [], lateBase = [], badSince = 0, goodSince = 0, devBad = 0, devGood = 0, askedAt = 0;
+  try {
+    var nc = navigator.connection;
+    if (nc) Q.net = nc.effectiveType === "slow-2g" || nc.effectiveType === "2g" ? 4 : nc.saveData || nc.effectiveType === "3g" ? 2 : 1;
+  } catch (e) { /* no Network Information API */ }
+  Q.ask = Q.net;
+  function askRate() {
+    var want = Math.max(Q.net, Q.dev);
+    if (want === Q.ask) return;
+    Q.ask = want; askedAt = Date.now();
+    send({ t: "rate", div: want });
+    emit("quality", quality());
+  }
+  function quality() { return { rate: Q.rate, ask: Q.ask, lateMs: Math.round(Q.lateMs), fps: Q.fps, rtt: Q.rtt, every: Q.every }; }
+  /** One frame's lateness (ms): the shared clock now minus the hub's send time. */
+  function lateSample(at) {
+    if (typeof document !== "undefined" && document.hidden) return;
+    var n = Date.now(), x = serverMs() - at;
+    late.push(x); if (late.length > 10) late.shift();
+    // the floor: the smallest lateness of each 2 s over the last 30 s (a far player's steady delay, which no rate change can fix)
+    var b = lateBase[lateBase.length - 1];
+    if (!b || n - b.at >= 2000) lateBase.push({ at: n, v: x }); else if (x < b.v) b.v = x;
+    while (lateBase.length > 15) lateBase.shift();
+    if (late.length < 5 || lateBase.length < 2) return;
+    var floor = Infinity; for (var i = 0; i < lateBase.length; i++) floor = Math.min(floor, lateBase[i].v);
+    var sorted = late.slice().sort(function (a, c) { return a - c; });
+    Q.lateMs = sorted[sorted.length >> 1] - floor;
+    if (Q.lateMs > 250) { goodSince = 0; if (!badSince) badSince = n; }
+    else if (Q.lateMs < 60) { badSince = 0; if (!goodSince) goodSince = n; }
+    else { badSince = 0; goodSince = 0; }
+    if (badSince && n - badSince >= 2000 && n - askedAt >= 3000 && Q.net < 4) { Q.net *= 2; badSince = 0; late = []; askRate(); }
+    else if (goodSince && n - goodSince >= 15000 && Q.net > 1) { Q.net /= 2; goodSince = 0; askRate(); }
+  }
+  /** game.js: frames drawn a second, about once a second while playing. Under 20 for 3 s: half rate; over 40 for 15 s: back. */
+  function deviceFps(fps) {
+    var n = Date.now();
+    Q.fps = Math.round(fps);
+    if (fps < 20) { devGood = 0; if (!devBad) devBad = n; } else if (fps > 40) { devBad = 0; if (!devGood) devGood = n; } else { devBad = 0; devGood = 0; }
+    if (devBad && n - devBad >= 3000 && Q.dev < 2) { Q.dev = 2; devBad = 0; askRate(); }
+    else if (devGood && n - devGood >= 15000 && Q.dev > 1) { Q.dev = 1; devGood = 0; askRate(); }
+  }
+  /** The time others are drawn at: the shared clock minus the measured delay, reached by running 2% fast or 4% slow (a jump only when far off). */
+  function drawTime() {
+    var now = serverMs(), want = now - DELAY;
+    if (!drawAt || Math.abs(drawT - want) > 1000) { drawT = want; drawAt = now; return drawT; }
+    var el = Math.max(0, now - drawAt), d = want - drawT;
+    drawAt = now;
+    drawT += el * (d > 2 ? 1.02 : d < -2 ? 0.96 : 1);
+    return drawT;
+  }
+  /** Own state and host writes go out every 80 ms, every 100 ms in rooms over 8 players (the server sends those every 100 ms). */
+  function sendMs() { var n = 0; for (var k in R.players) n++; return n > 8 ? 100 : SEND_MS; }
+  /** How often own and host writes go out: as sendMs, but once a second while this page is the only one in the room (playing alone, or
+   *  waiting for friends): nobody needs them sooner, and the server's copy (saves, a reload) is at most a second old. */
+  var ALONE_MS = 1000;
+  function sendGap() { var n = 0; for (var k in R.players) n++; return n <= 1 ? ALONE_MS : sendMs(); }
+
+  // ---- hello: ask the window around us for a private port (retry: it may not be listening yet) -----------------------------------------
+  var tries = 0, helloT = setInterval(function () {
+    if (port || ++tries > 20) { clearInterval(helloT); if (!port) { R.status = "unavailable"; emit("status", R.status); } return; }
+    try { parent.postMessage({ tickcli: "hello", n: nonce }, "*"); } catch (e) { /* no parent */ }
+  }, 250);
+  try { parent.postMessage({ tickcli: "hello", n: nonce }, "*"); } catch (e) { /* no parent */ }
+  addEventListener("message", function (e) {
+    var d = e.data;
+    if (port || e.source !== parent || !d || d.tickcli !== "port" || d.n !== nonce || !e.ports || !e.ports[0]) return;
+    port = e.ports[0];
+    port.onmessage = onPort;
+    clearInterval(helloT);
+    R.available = true;
+  });
+
+  function onPort(e) {
+    var d = e.data;
+    if (!d || typeof d !== "object") return;
+    if (d.k === "info") { info = d; R.guest = !!d.guest; R.anyone = !!d.anyone; var q = ready; ready = []; for (var i = 0; i < q.length; i++) q[i](d); emit("ready", d); return; }
+    if (d.k === "status") {
+      R.status = d.s;
+      if (d.s === "closed") R.closed = { code: d.code, reason: d.reason };
+      emit("status", d.s, d);
+      return;
+    }
+    if (d.k === "invite") { emit("invite", d.ok); return; }
+    if (d.k === "msg") onServer(d.m);
+  }
+
+  // ---- clock: the server's time, from ping answers (keep the fastest round trip; half of it is the one-way guess) -------------------------
+  function serverMs() {
+    var n = Date.now();
+    if (offAt && offset !== offTarget) offset = Math.abs(offTarget - offset) > 1000 ? offTarget : offset + (offTarget - offset) * Math.min(1, (n - offAt) / 1000);
+    offAt = n;
+    return n + offset;
+  }
+  /** A ping answer: keep the last 8 (none older than 60 s) and aim at the offset of the one with the shortest round trip (NTP's clock filter). */
+  function clockSample(c, srv) {
+    var n = Date.now(), rtt = n - c;
+    if (!(rtt >= 0) || rtt > 30000 || typeof srv !== "number") return;
+    clk.push({ rtt: rtt, off: srv + rtt / 2 - n, at: n });
+    while (clk.length > 8 || (clk.length && n - clk[0].at > 60000)) clk.shift();
+    var best = clk[0]; for (var i = 1; i < clk.length; i++) if (clk[i].rtt <= best.rtt) best = clk[i];
+    if (Math.abs(best.off - offTarget) > 50) { late = []; lateBase = []; }   // a new clock offset: lateness readings before it do not compare
+    offTarget = best.off; Q.rtt = best.rtt;
+    if (!clockSet) { offset = offTarget; clockSet = true; }
+    offAt = offAt || n;
+  }
+
+  // ---- server messages ---------------------------------------------------------------------------------------------------------------
+  function setPlayer(p) {
+    var cur = R.players[p.id];
+    var buf = cur ? cur.buf : [];
+    R.players[p.id] = { id: p.id, name: p.name, online: p.online, hidden: p.hidden, guest: p.guest, state: p.state || {}, buf: buf };
+    if (!cur) R.players[p.id].buf = [{ at: serverMs(), s: copy(p.state || {}) }];
+  }
+  var firstVer = "";   // the game version this page joined first: a reconnect into another one means the page itself is out of date
+  function full(m) {
+    var prevBoot = R.boot, wasStarted = R.started, prevMatch = R.match, prevYou = R.you;
+    var asked = m.t === "sync" && syncAsked > 0;   // the answer to our own sync request (a write was refused): the server's copy wins everywhere
+    if (asked) syncAsked = 0;
+    R.you = m.you; R.code = m.code; R.priv = !!m.private; R.match = m.match; R.term = m.term; R.host = m.host; R.started = !!m.started; R.boot = m.boot; R.max = m.max;
+    if (typeof m.now === "number" && !clockSet) { offset = offTarget = m.now - Date.now(); offAt = Date.now(); }
+    var mine = prevYou === m.you ? R.players[R.you] : null;
+    R.players = {};
+    for (var i = 0; i < m.players.length; i++) setPlayer(m.players[i]);
+    sentMe = R.players[R.you] ? copy(R.players[R.you].state) : {};
+    sentShared = copy(m.shared || {});
+    // kept: the server restarted but took the room over (same match, same shared state): the page carries on
+    var r = { restarted: !!prevBoot && prevBoot !== m.boot && wasStarted && !m.kept, newMatch: prevMatch && prevMatch !== m.match, kept: !!m.kept };
+    // our own state: keep what we hold locally if we were here before (it is newer than the server's copy). After a long drop the server may have
+    // forgotten it (the seat was given up): send it all again, so things set once (colour, score, health) show on the other screens too.
+    if (mine && R.players[R.you] && !asked) {
+      var srv = R.players[R.you].state;
+      R.players[R.you].state = mine.state;
+      if (m.t === "welcome" && !r.restarted && !r.newMatch && JSON.stringify(srv) !== JSON.stringify(mine.state)) {
+        mePend = mePend || {};
+        join(mePend, shape(mine.state));
+        schedule();
+      }
+    }
+    R.shared = frozen(m.shared || {});
+    R.saved = m.saved || null; R.resumed = !!m.resumed; R.saveBusy = !!m.saveBusy; R.saveError = !!m.saveError;
+    sharedPend = null;
+    sbuf = []; keepShared(serverMs());
+    return r;
+  }
+  /** The server refused a write: our copy and everyone else's differ. Ask for the server's copy (once per second at most). */
+  function resync() {
+    var n = Date.now();
+    if (n - syncAsked < 1000) return;
+    syncAsked = n;
+    send({ t: "sync" });
+  }
+  function onServer(m) {
+    if (!m || typeof m.t !== "string") return;
+    switch (m.t) {
+      case "welcome": case "sync": {
+        if (typeof m.ver === "string" && m.ver) {
+          if (!firstVer) firstVer = m.ver;
+          else if (m.ver !== firstVer) {   // the game was edited while this page was open: never play the old code in the new version's room
+            send({ t: "leave" }); R.closed = { code: 4007, reason: "this page has an older version of the game" }; R.status = "closed"; emit("status", "closed", R.closed); break;
+          }
+        }
+        if (m.t === "welcome") { R.idleAt = 0; Q.rate = 1; Q.every = 0; if (Q.ask > 1) send({ t: "rate", div: Q.ask }); }   // a new socket starts at the full rate
+        var r = full(m); emit(m.t, m, r); emit("players"); emit("shared"); emit("host", R.host); break; }
+      case "idle": R.idleAt = typeof m.closesAt === "number" ? m.closesAt : 0; emit("idle", R.idleAt); break;   // nobody did anything: the room closes then (0 = not any more)
+      case "rate": Q.rate = m.div > 1 ? m.div : 1; Q.every = typeof m.every === "number" ? m.every : 0; emit("quality", quality()); break;
+      case "rooms": {
+        var w = roomsWait; roomsWait = [];
+        var list = m.off ? null : Array.isArray(m.rooms) ? m.rooms : [];
+        for (var ri = 0; ri < w.length; ri++) { clearTimeout(w[ri].t); w[ri].done(list); }
+        emit("rooms", list);
+        break;
+      }
+      case "time": clockSample(m.c, m.s); break;
+      case "delta": {
+        if (typeof m.at === "number") lateSample(m.at);
+        // each update is buffered at the time its sender sampled it (pt, sc); a hub without them: the time it sent the frame
+        if (m.players) for (var id in m.players) {
+          if (id === R.you || !R.players[id]) continue;
+          var p = R.players[id], st = m.pt && typeof m.pt[id] === "number" ? m.pt[id] : m.at;
+          merge(p.state, m.players[id]);
+          push(p.buf, st, copy(p.state), 12);
+          lagOf(st);
+        }
+        // shared changes we wrote ourselves as host in this term come back to the others only (we already applied them)
+        if (m.shared && !(R.host === R.you && m.st === R.term)) { var sst = typeof m.sc === "number" ? m.sc : m.at; R.shared = cow(R.shared, m.shared); merge(sentShared, copy(m.shared)); keepShared(sst); lagOf(sst); emit("shared"); }
+        // effects ride the frame: after the players and the shared state of the same frame; our own were already played here
+        if (m.fx) for (var fi = 0; fi < m.fx.length; fi++) { var f = m.fx[fi]; if (f && f.from !== R.you) emit("fx", f.from, f.name, f.data); }
+        break;
+      }
+      case "joined": setPlayer(m.player); if (flushT) { clearTimeout(flushT); flushT = 0; schedule(); } emit("players"); emit("joined", m.player); break;   // not alone any more: a write waiting on the once-a-second pace goes now
+      case "online": if (R.players[m.player.id]) { var q = R.players[m.player.id]; q.name = m.player.name; q.online = m.player.online; q.hidden = m.player.hidden; } emit("players"); break;
+      case "left": delete R.players[m.player]; emit("players"); emit("left", m.player); break;
+      case "host": {
+        var was = R.host;
+        R.host = m.player; R.term = m.term;
+        if (m.player === R.you) sentShared = copy(R.shared);   // what everyone has: our next writes are compared with it
+        if (sharedPend && m.player !== R.you) sharedPend = null;   // writes from an old term would be refused anyway
+        emit("host", m.player, was);
+        break;
+      }
+      case "action": emit("action", m.id, m.from, m.name, m.data); break;
+      case "newer": R.newer = true; emit("newer"); break;   // someone opened the edited game with this room's code: a new room has it now
+      case "result": { var a = acts[m.id]; if (a) { delete acts[m.id]; clearTimeout(a.t); a.done({ ok: !!m.ok, error: m.error }); } break; }
+      case "fx": emit("fx", m.from, m.name, m.data); break;
+      case "saved": R.saved = m.at ? { at: m.at, v: typeof m.v === "number" ? m.v : 1 } : null; emit("saved"); break;
+      case "savestate": R.saveError = !!m.error; emit("saved"); break;   // the saved game could not be read (error) or was read after all
+      case "profile": {
+        // an answer after the game stopped waiting does not switch saving on by itself: the game adopts it (adoptProfile) only if it has not written yet
+        if (!m.off) R.profV = typeof m.v === "number" ? m.v : 1;
+        if (m.off) profOff = true; else if (profGaveUp && !profWait.length) { profLate = isObj(m.p) ? m.p : {}; emit("profile"); break; } else prof = isObj(m.p) ? m.p : {};
+        var w = profWait; profWait = [];
+        for (var wi = 0; wi < w.length; wi++) { clearTimeout(w[wi].t); w[wi].res(prof ? copy(prof) : null); }
+        break;
+      }
+      case "started": R.started = true; R.resumed = !!m.resumed; R.match = m.match; R.shared = frozen(m.shared || {}); sentShared = copy(R.shared); sbuf = []; keepShared(serverMs()); emit("shared"); emit("started", m.match); break;
+      case "ended": R.started = false; R.resumed = false; if (m.shared) { R.shared = frozen(m.shared); sentShared = copy(m.shared); } emit("shared"); emit("ended", m.match); break;
+      case "error":
+        if (m.code === "bad_value" || m.code === "too_big" || m.code === "out_of_range" || m.code === "too_fast") resync();
+        emit("error", m.code, m.ref);
+        break;
+    }
+  }
+
+  // ---- sending: own state sampled and merged, shared state with the host term --------------------------------------------------------
+  function shape(patch) {
+    var out = {}, spec = (R.spec && R.spec.player) || {};
+    for (var k in patch) {
+      var v = patch[k];
+      if (typeof v === "number" && spec[k]) {
+        var lo = spec[k][0], hi = spec[k][1];
+        v = Math.min(hi, Math.max(lo, v));
+        // positions as whole numbers: less data, same picture; quaternion fields to 3 decimals (2 would wobble by about a degree)
+        v = QK[k] ? Math.round(v * 1000) / 1000 : hi - lo >= 100 ? Math.round(v) : Math.round(v * 100) / 100;
+      }
+      out[k] = v;
+    }
+    return out;
+  }
+  // What the host sends is trimmed: positions (x, y, z) as whole numbers (or the decimals asked with precision()), quaternion fields to 3 decimals,
+  // other numbers to 2. The host keeps its exact values; the picture is the same, and 32 moving monsters take about half the data (measured:
+  // 2,860 -> 1,563 bytes per update).
+  function rnd(k, x) { return QK[k] ? Math.round(x * 1000) / 1000 : LERP[k] && k !== "angle" && k !== "rot" ? Math.round(x * POS) / POS : Math.round(x * 100) / 100; }
+  function trim(v, depth) {
+    if (!isObj(v) || depth > 4) return v;
+    var out = {};
+    for (var k in v) { var x = v[k]; out[k] = typeof x === "number" ? rnd(k, x) : isObj(x) ? trim(x, depth + 1) : x; }
+    return out;
+  }
+  function flush() {
+    flushT = 0;
+    lastSend = Date.now();
+    if (fxQ.length) {
+      var fn = lastSend; while (fxTimes.length && fn - fxTimes[0] >= 1000) fxTimes.shift();
+      var room = Math.max(1, 20 - fxTimes.length);   // at least one per slot, so the queue always drains
+      while (fxQ.length && room-- > 0) { fxTimes.push(fn); send(fxQ.shift()); }
+      if (fxQ.length) schedule();
+    }
+    if (mePend) { var md = diff(sentMe, mePend); if (md) { send({ t: "me", s: md, c: Math.round(meAt) }); merge(sentMe, copy(md)); } mePend = null; }
+    if (profPend) { var pp = chunks(profPend, tooBig); for (var pi = 0; pi < pp.length; pi++) send({ t: "save", p: pp[pi] }); profPend = null; }
+    if (sharedPend && R.host === R.you) {
+      var sd = diff(sentShared, trim(sharedPend, 0));
+      if (sd) { var parts = chunks(sd, tooBig); for (var i = 0; i < parts.length; i++) send({ t: "shared", term: R.term, p: parts[i], c: Math.round(sharedAt) }); merge(sentShared, copy(sd)); }
+    }
+    sharedPend = null;
+  }
+  function tooBig(path) { emit("error", "too_big", path); resync(); }
+  function schedule() {
+    if (flushT) return;
+    var wait = Math.max(0, sendGap() - (Date.now() - lastSend));
+    flushT = setTimeout(flush, wait);
+  }
+
+  /** The others, as they should be drawn now: numbers of declared fields eased between the two updates around (server time - DELAY). */
+  function view() {
+    var t = drawTime(), out = [], spec = (R.spec && R.spec.player) || {};
+    for (var id in R.players) {
+      var p = R.players[id], s = p.state;
+      if (id !== R.you && p.buf.length > 1) {
+        var b = p.buf, i = b.length - 1;
+        while (i > 0 && b[i - 1].at > t) i--;
+        var A = b[Math.max(0, i - 1)], B = b[i];
+        if (A !== B && B.at > A.at) {
+          var f = frac(t, A, B);
+          s = copy(B.s);
+          for (var k in spec) if (typeof A.s[k] === "number" && typeof B.s[k] === "number") s[k] = ease(k, A.s[k], B.s[k], f);
+          if (spec.qx || spec.qw) quatEase(s, A.s, B.s, f);
+        }
+      }
+      out.push({ id: id, name: p.name, online: p.online, away: !!p.hidden, me: id === R.you, host: id === R.host, state: s });
+    }
+    out.sort(function (a, b) { return a.me ? -1 : b.me ? 1 : a.name < b.name ? -1 : 1; });
+    return out;
+  }
+
+  window.tickcli = {
+    state: R,
+    on: function (name, fn) { (listeners[name] = listeners[name] || []).push(fn); },
+    /** Resolves once the app answered (or with null after ~10 s: no app around the page, e.g. a downloaded copy). */
+    ready: function () {
+      return new Promise(function (res) {
+        if (info) return res(info);
+        if (R.status === "unavailable") return res(null);
+        ready.push(res);
+        listeners.status = listeners.status || [];
+        listeners.status.push(function (s) { if (s === "unavailable") res(null); });
+      });
+    },
+    join: function (o) { R.spec = o.spec; R.closed = null; post({ k: "open", join: { spec: o.spec, code: o.code, priv: !!o.priv, alone: !!o.alone, name: o.name, f: FEATS } }); },
+    leave: function () { send({ t: "leave" }); R.status = "idle"; },
+    me: function () { return R.players[R.you] || null; },
+    setMe: function (patch) {
+      var p = R.players[R.you];
+      if (!p || !patch || typeof patch !== "object") return;
+      var s = shape(patch);
+      if (!checked(s)) return;
+      merge(p.state, s);
+      mePend = mePend || {};
+      join(mePend, s);
+      meAt = serverMs();
+      schedule();
+    },
+    setShared: function (patch) {
+      if (R.host !== R.you || !patch || typeof patch !== "object") return false;
+      if (!checked(patch)) return false;
+      R.shared = cow(R.shared, patch);
+      sharedPend = sharedPend || {};
+      join(sharedPend, patch);
+      sharedAt = serverMs();
+      schedule();
+      return true;
+    },
+    act: function (name, data) {
+      return new Promise(function (res) {
+        var id = ++actSeq;
+        acts[id] = { done: res, t: setTimeout(function () { delete acts[id]; res({ ok: false, error: "no answer" }); }, 8000) };
+        send({ t: "act", id: id, name: String(name), data: data === undefined ? null : data });
+      });
+    },
+    answer: function (id, ok, error) { send({ t: "result", id: id, ok: !!ok, error: error ? String(error).slice(0, 80) : undefined }); },
+    fx: function (name, data) {
+      var m = { t: "fx", name: String(name), data: data === undefined ? null : data }, n = Date.now();
+      while (fxTimes.length && n - fxTimes[0] >= 1000) fxTimes.shift();
+      if (fxTimes.length < 20 && !fxQ.length) { fxTimes.push(n); return send(m); }
+      if (fxQ.length >= 64) fxQ.shift();   // cosmetic: the oldest waiting one goes
+      fxQ.push(m); schedule();
+    },
+    /** The host's game loop calls this every frame; once a second it tells the server the game is running. */
+    alive: function () { var n = Date.now(); if (n - aliveAt >= 1000) { aliveAt = n; send({ t: "alive", term: R.term }); } },
+    /** Continue the saved world (resume true) or start a new game. */
+    start: function (resume) { if (sharedPend || profPend) flush(); send(resume ? { t: "start", resume: true } : { t: "start" }); },
+    /** The person's saved profile (an object), or null when saving is off here. Asked once; answers within 3 s. */
+    profile: function () {
+      return new Promise(function (res) {
+        if (prof) return res(copy(prof));
+        if (profOff) return res(null);
+        var w = { res: res, t: setTimeout(function () { var i = profWait.indexOf(w); if (i >= 0) profWait.splice(i, 1); if (!profWait.length) profGaveUp = true; res(null); }, 3000) };
+        profWait.push(w);
+        if (profWait.length === 1) send({ t: "profile" });
+      });
+    },
+    /** A profile that arrived after profile() gave up: take it (saving switches on) and get a copy, or null when there is none. */
+    adoptProfile: function () { if (!profLate) return null; prof = profLate; profLate = null; profGaveUp = false; return copy(prof); },
+    /** Merge into the saved profile (same rules as shared writes); goes out within a second. False when saving is off. */
+    setProfile: function (patch) {
+      if (!prof || !patch || typeof patch !== "object") return false;
+      if (!checked(patch)) return false;
+      merge(prof, copy(patch));
+      profPend = profPend || {};
+      join(profPend, patch);
+      if (!profT) profT = setTimeout(function () { profT = 0; flush(); }, 1000);
+      return true;
+    },
+    /** Host: the saved game is over (won, lost): forget the world save; nothing is saved again until the next start. */
+    clearWorld: function () { send({ t: "world", clear: true }); },
+    /** Send what is pending now (own state, host writes, profile). */
+    flush: function () { if (mePend || sharedPend || profPend) flush(); },   // seats and brackets the host just wrote arrive before the start
+    end: function () { if (sharedPend || profPend) flush(); send({ t: "end" }); },
+    kick: function (id) { send({ t: "kick", player: id }); },
+    rename: function (n) { send({ t: "name", name: String(n).slice(0, 40) }); },
+    invite: function () { if (R.code) post({ k: "invite", code: R.code }); },
+    /** Only when state.anyone (the host app offers it): the app shows how to let people without an account play (its public link). */
+    inviteAnyone: function () { if (R.anyone) post({ k: "invite-anyone" }); },
+    /** Where a patch breaks the limits the server keeps (a path such as "mobs.12.name"), or null when it is fine. */
+    check: function (patch) { return badPath(patch, 0, ""); },
+    /** The open rooms of this game you could join instead (needs a joined room; at most once a second, more often answers from the last list).
+     *  Resolves [{code, host, players, away, max, started, match, ping, slowed, full, you?}] (ping: the host's round trip to the server in ms,
+     *  0 = not known yet), null when the server does not list rooms, or [] after 3 s without an answer. */
+    rooms: function () {
+      return new Promise(function (res) {
+        if (R.status !== "open") return res([]);
+        var n = Date.now();
+        if (roomsLast && n - roomsLast.at < 1000) return res(roomsLast.list);
+        var w = { done: function (list) { roomsLast = { at: Date.now(), list: list }; res(list); }, t: 0 };
+        w.t = setTimeout(function () { var i = roomsWait.indexOf(w); if (i >= 0) roomsWait.splice(i, 1); res([]); }, 3000);
+        roomsWait.push(w);
+        if (roomsWait.length === 1) send({ t: "rooms", spec: R.spec });
+      });
+    },
+    /** How this page is doing: {rate (1 = every update, 2 = every second one, 4), ask, lateMs (frames late beyond this link's usual, ms), fps,
+     *  rtt (round trip to the server, ms), every (ms between updates on a slower rate)}. Event "quality" when it changes. */
+    quality: quality,
+    /** game.js tells the page how fast it draws (frames a second). */
+    frameRate: deviceFps,
+    /** The person pressed "keep this room" after an idle warning (any move, action or effect counts too). */
+    stay: function () { send({ t: "stay" }); },
+    now: function () { return serverMs() / 1000; },
+    /** Decimals kept on positions (x, y, z) the host shares: 0 (default, pixels) to 3. Player fields follow their declared range instead. */
+    precision: function (n) { n = Math.max(0, Math.min(3, Math.floor(Number(n)) || 0)); POS = Math.pow(10, n); },
+    view: view,
+    /** The shared state as it should be drawn now (positions eased on every screen but the host's). */
+    sharedView: sharedView,
+  };
+})();

package/dist/cli.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/** The command line as options; throws a message for anything it does not understand. */
+export declare function parseArgs(argv: string[], env?: Record<string, string | undefined>): {
+    games: string;
+    port: number;
+    host?: string;
+    saves?: string;
+    title?: string;
+    proxy?: boolean;
+    help: boolean;
+};