@zaisma/game-server 1.1.0 → 1.3.0

package/bin/node-parts.js

@@ -12,14 +12,29 @@ const MAXIMUM_PROFILE_COUNT = 10_000;
 /** The format the runner's saved room states are written in. A file with another is dropped, and rooms start fresh. */
 const ROOM_STATES_FORMAT_VERSION_NUMBER = 1;
 
-/** Fetch the public keys a JWKS URL publishes, caching them for an hour (fetched again at once when asked to refresh). */
+/** A refresh asked for by a pass with a key ID not in the cache waits this long after the last fetch, so passes with made-up key IDs can't make this fetch on every hello. */
+const MINIMUM_REFRESH_INTERVAL_MS = 30_000;
+
+/**
+ * Fetch the public keys a JWKS URL publishes, caching them for an hour (fetched again at once when asked to refresh,
+ * at most once in MINIMUM_REFRESH_INTERVAL_MS). A fetch that fails keeps answering with the keys already held.
+ */
 function keysFrom(jwksUrl) {
   let cache = null;
+  let fetchedAtMs = 0;
   return async (isRefreshing = false) => {
-    if (cache && !isRefreshing && Date.now() - cache.fetchedAtMs < KEYS_KEPT_MS) return cache.keys;
-    const response = await fetch(jwksUrl);
-    if (!response.ok) throw new Error(`Couldn't load Zaisma's keys from ${jwksUrl}`);
-    cache = { fetchedAtMs: Date.now(), keys: (await response.json()).keys };
+    const nowMs = Date.now();
+    if (cache && !isRefreshing && nowMs - cache.fetchedAtMs < KEYS_KEPT_MS) return cache.keys;
+    if (cache && isRefreshing && nowMs - fetchedAtMs < MINIMUM_REFRESH_INTERVAL_MS) return cache.keys;
+    fetchedAtMs = nowMs;
+    try {
+      const response = await fetch(jwksUrl);
+      if (!response.ok) throw new Error(`Couldn't load Zaisma's keys from ${jwksUrl}`);
+      cache = { fetchedAtMs: nowMs, keys: (await response.json()).keys };
+    } catch (error) {
+      if (cache) return cache.keys;
+      throw error;
+    }
     return cache.keys;
   };
 }

package/bin/node.js

@@ -23,8 +23,12 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { resolve } from "node:path";
 import { realpathSync } from "node:fs";
 import { BUSY_CLOSE_CODE, ENDED_CLOSE_CODE, ERROR_TEXT, NO_ANSWER_CLOSE_CODE, PASS_ISSUER_URL, PassError, ReceiptError, REMOVED_CLOSE_CODE, REQUEST_ERROR_HTTP_STATUS, REQUEST_LIMITS, ROOM_LIMITS, ROOM_TUNING, WEBHOOK_LIMITS, GameServerError, RoomCore, restoreInfoOf, passesAreFriends, passesHaveBlockBetween, answerRequest, startSchedules, checkRoomData, clientIdle, defineGameServer, errorMessage, isRoomCode, readRequestBody, relay, requestError, runWebhook, tidyRoomInfo, verifyPass, verifyReceipt, verifyWebhook } from "../src/internal.js";
+import { OutsideCallError } from "../src/outside-calls.js";
 import { checkedStartServerOptions, localDatabase, localRoomStates, passKeysFrom, profilesFrom, receiptKeysFrom, secretsFromEnvironment } from "./node-parts.js";
 
+// Code that names OutsideCallError, as Zaisma's sandbox lets it, moves unchanged: nothing here refuses a call, so instanceof is simply false.
+globalThis.OutsideCallError ??= OutsideCallError;
+
 const HELLO_MS = 5000;
 /**
  * How often rooms check on their players (idle, hidden, held seats, players whose time to reconnect ran
@@ -280,14 +284,15 @@ export function startServer(options) {
             .catch((error) => console.error("Couldn't move players:", error));
         },
       },
-      // As in Zaisma's rooms: a room that ticks comes back with its state and onRestored, its match's players away until they
-      // reconnect; a turn-based room comes back with its state and its room settings alone.
-      saved ? { state: saved.state, room: saved.savedRoom, ...(definition.ticksPerSec ? { restoreInfo: restoreInfoOf(saved.savedAtMs, Date.now(), null, saved.isSavedEmpty), lostPlayers: saved.matchPlayers } : {}) } : { start },
+      // As in Zaisma's rooms: a room that ticks, or a turn-based one that had players in its match, comes back with its state and
+      // onRestored, its match's players away until they reconnect; a turn-based room nobody was in comes back with its state and its room settings alone.
+      saved ? { state: saved.state, room: saved.savedRoom, ...(definition.ticksPerSec || saved.matchPlayers?.length ? { restoreInfo: restoreInfoOf(saved.savedAtMs, Date.now(), null, saved.isSavedEmpty), lostPlayers: saved.matchPlayers } : {}) } : { start },
     );
     if (saved) core.savedAtMs = saved.savedAtMs;
     // passes: each player's checked pass, newest, for the blocks and friendships between them (passesHaveBlockBetween, passesAreFriends).
     // savedStateKey: what the room last saved (its state and its match's players), so an unchanged one isn't written again.
-    room = { core, sockets, passes: new Map(), timer: null, waiting: false, savedStateKey: saved ? stateKeyOf(saved.stateJson, saved.matchPlayers, saved.savedRoom.isKept === true) : null, hasReportedStateSize: false };
+    // seatedAtMs: when each player came into this room on their own, for the game's one-room rule (the oldest seat closes first).
+    room = { core, sockets, passes: new Map(), seatedAtMs: new Map(), timer: null, probeTimer: null, waiting: false, savedStateKey: saved ? stateKeyOf(saved.stateJson, saved.matchPlayers, saved.savedRoom.isKept === true) : null, hasReportedStateSize: false };
     rooms.set(code, room);
     return room;
   }
@@ -354,6 +359,8 @@ export function startServer(options) {
       if (room.timer) return;
       let lastTickAtMs = Date.now();
       room.core.savedAtMs ??= lastTickAtMs;
+      // A tick slower than the probe interval can't probe on time (the player's game reconnects after 8 seconds of silence): check twice an interval on a timer of its own, so a probe is never a whole interval late.
+      if (1000 / definition.ticksPerSec > ROOM_TUNING.probeIntervalSec * 1000) room.probeTimer = setInterval(() => room.core.probeDue(), (ROOM_TUNING.probeIntervalSec * 1000) / 2);
       room.timer = setInterval(() => {
         const nowMs = Date.now();
         room.core.tick((nowMs - lastTickAtMs) / 1000);
@@ -361,12 +368,39 @@ export function startServer(options) {
         if (nowMs - room.core.savedAtMs >= stateSaveIntervalMs) saveRoom(code, room);
       }, 1000 / definition.ticksPerSec);
     } else if (room.timer) {
-      clearInterval(room.timer);
-      room.timer = null;
+      stopTimers(room);
       saveRoom(code, room);
     }
   }
 
+  function stopTimers(room) {
+    if (room.timer) clearInterval(room.timer);
+    if (room.probeTimer) clearInterval(room.probeTimer);
+    room.timer = null;
+    room.probeTimer = null;
+  }
+
+  /**
+   * A player came into a room on their own: their seats in the game's other rooms here past maximumRoomCountPerPlayer, the oldest
+   * first, are given up as in Zaisma's rooms. They hear "Joined from somewhere else", and the game's onLeave runs with reason "left".
+   */
+  function takeSeat(playerId, code, room) {
+    room.seatedAtMs.set(playerId, Date.now());
+    const others = [...rooms]
+      .filter(([otherCode, other]) => otherCode !== code && !other.core.ended && other.core.players.has(playerId))
+      .sort(([, first], [, second]) => (first.seatedAtMs.get(playerId) ?? 0) - (second.seatedAtMs.get(playerId) ?? 0));
+    for (const [otherCode, other] of others.slice(0, Math.max(0, others.length - (room.core.maximumRoomCountPerPlayer - 1)))) {
+      const ws = other.sockets.get(playerId);
+      other.sockets.delete(playerId);
+      other.seatedAtMs.delete(playerId);
+      other.core.leave(playerId, "left");
+      ws?.close(REMOVED_CLOSE_CODE, "Joined from somewhere else");
+      dismissSpectatorsIfAlone(other);
+      pace(otherCode, other);
+      closeIfEmpty(otherCode, other);
+    }
+  }
+
   /** Keep a room for players on their way, even if it empties meanwhile. */
   function wait(code, room, durationMs) {
     room.waiting = true;
@@ -394,7 +428,7 @@ export function startServer(options) {
   // One that empties keeps its saved state for a day (a kept one until it ends); one that ended keeps none.
   function closeIfEmpty(code, room) {
     if (rooms.get(code) !== room || room.waiting || (!room.core.ended && (room.sockets.size > 0 || room.core.heldSeatCount > 0 || room.core.nextReconnectDeadlineMs() !== null))) return;
-    if (room.timer) clearInterval(room.timer);
+    stopTimers(room);
     rooms.delete(code);
     try {
       if (room.core.ended) roomStates?.remove(code);
@@ -447,7 +481,7 @@ export function startServer(options) {
     const helloTimer = setTimeout(() => playerId || refuse("no_hello"), HELLO_MS);
     ws.zaismaSeenAtMs = Date.now();
 
-    ws.on("message", async (received, isBinary) => {
+    const onMessage = async (received, isBinary) => {
       const text = isBinary ? null : received.toString();
       ws.zaismaSeenAtMs = Date.now();
       // Games ping every 25 seconds or so, so a connection that stops answering can be dropped.
@@ -509,6 +543,8 @@ export function startServer(options) {
         room.core.setFriends(player.id, [...room.passes].filter(([id, other]) => id !== player.id && passesAreFriends(claims, other)).map(([id]) => id));
       }
       // Rooms here aren't in Zaisma's room lists, but listed, open and closed work the same for the game.
+      // Players who come on their own take a seat; those the game moved here (or reserved this room for), reconnects and spectators don't.
+      const takesSeat = !isSpectator && !room.core.players.has(player.id) && !room.core.isArrivingByMove(player.id);
       const joined = room.core.join(player, { ...made, isSpectator });
       if (!joined.isAllowed) {
         room.sockets.delete(player.id);
@@ -517,7 +553,15 @@ export function startServer(options) {
       }
       playerId = player.id;
       room.waiting = false;
+      if (takesSeat) takeSeat(player.id, code, room);
       pace(code, room);
+    };
+    // Whatever a message hits, it ends that connection or that message, never the process and the matches on it.
+    ws.on("message", (received, isBinary) => {
+      onMessage(received, isBinary).catch((error) => {
+        console.error("Couldn't handle a message:", error);
+        if (!playerId) refuse("busy");
+      });
     });
 
     // A frame over the size limit (or a broken one) is an error on this one socket: it closes and the close handler below takes it out, the runner keeps going.
@@ -543,7 +587,7 @@ export function startServer(options) {
       clearInterval(catcher);
       schedules.stop();
       for (const [code, room] of rooms) {
-        if (room.timer) clearInterval(room.timer);
+        stopTimers(room);
         saveRoom(code, room);
       }
       // Players' games hear a restart (1012) and reconnect, to the same room once this server is back.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zaisma/game-server",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Run your Zaisma game server: the same rooms on Zaisma or on your own server.",
   "license": "MIT",
   "homepage": "https://zaisma.com",

package/src/room.d.ts

@@ -395,6 +395,13 @@ export interface GameServer<S = any> {
      * run, so you can freeze their character; held seats come after (seatHoldDurationSec).
      */
     reconnectTimeoutSec?: number;
+    /**
+     * How many of your game's rooms one player may sit in at once: 1 to 10, 1 by default, as on Steam. When
+     * a player joins another room of the game, their seat in the oldest is closed ("Joined from somewhere
+     * else") and the room's onLeave runs with reason "left". Raise it for a hangout hub beside matches.
+     * Moving a player (room.moveTo, room.reserve) and watching (isSpectator) never close a seat.
+     */
+    maximumRoomCountPerPlayer?: number;
     /**
      * Send each player the state, then only what changes: a full copy when they join (and after their
      * connection was backed up), then the changes after each tick, or after each handler in a turn-based
@@ -587,7 +594,7 @@ export declare function readJoinAnswer(answer: unknown): {
     mistake: GameServerError;
 };
 /** Everything a game server object may have, in the order the docs give them. Anything else is refused. */
-export declare const GAME_SERVER_OPTIONS: readonly ["maximumPlayerCount", "maximumSpectatorCount", "ticksPerSec", "hostControlsEnabled", "idleCheck", "idleTimeoutSec", "awayMode", "seatHoldDurationSec", "stateSyncEnabled", "reconnectTimeoutSec", "stateSaveIntervalSec", "setup", "onJoin", "canJoin", "onMoved", "onLeave", "onSpectatorJoin", "onSpectatorLeave", "onAway", "onBack", "onMessage", "onBytes", "onPurchase", "onRefund", "onTick", "onEnding", "onRestored", "stateView", "onVersionUpdate", "onRequest", "schedules", "onSchedule", "onWebhook"];
+export declare const GAME_SERVER_OPTIONS: readonly ["maximumPlayerCount", "maximumSpectatorCount", "ticksPerSec", "hostControlsEnabled", "idleCheck", "idleTimeoutSec", "awayMode", "seatHoldDurationSec", "stateSyncEnabled", "reconnectTimeoutSec", "maximumRoomCountPerPlayer", "stateSaveIntervalSec", "setup", "onJoin", "canJoin", "onMoved", "onLeave", "onSpectatorJoin", "onSpectatorLeave", "onAway", "onBack", "onMessage", "onBytes", "onPurchase", "onRefund", "onTick", "onEnding", "onRestored", "stateView", "onVersionUpdate", "onRequest", "schedules", "onSchedule", "onWebhook"];
 export declare const ROOM_LIMITS: {
     /** Players in one room: what one room carries at 60 ticks a second (test/load/room-load.test.ts). */
     readonly maximumPlayerCount: 100;
@@ -628,6 +635,9 @@ export declare const ROOM_LIMITS: {
     /** How long a player whose connection dropped stays in the match by default, and at most (reconnectTimeoutSec). */
     readonly defaultReconnectTimeoutSec: 30;
     readonly maximumReconnectTimeoutSec: 300;
+    /** Rooms of one game a player sits in at once by default, and at most (maximumRoomCountPerPlayer); a newer seat past it closes the oldest. */
+    readonly defaultMaximumRoomCountPerPlayer: 1;
+    readonly maximumRoomCountPerPlayer: 10;
     /** How often a real-time room saves its state by default, and the range (stateSaveIntervalSec). */
     readonly defaultStateSaveIntervalSec: 5;
     readonly minimumStateSaveIntervalSec: 1;
@@ -907,6 +917,8 @@ export interface SavedRoom extends RoomSettings {
     expected?: Record<string, Expected>;
     held?: Record<string, Held>;
     kept?: Record<string, AwayReason>;
+    /** Players a reserved room was made for who haven't arrived yet: the room keeps remembering them. */
+    reservedPlayerIds?: string[];
     /** Players whose connection dropped, with when their time to come back runs out (reconnectTimeoutSec). */
     reconnecting?: Record<string, Reconnecting>;
     lobbyRoomCode?: string;
@@ -1131,6 +1143,8 @@ export declare class RoomCore<S = any> {
     listingChanged: boolean;
     /** Players who have been in this room, newest last: they may come back after it closes. */
     readonly known: Set<string>;
+    /** Players a reserved room was made for who haven't arrived: never forgotten until they do. */
+    private readonly reservedPlayerIds;
     /** Players kicked and kept out for the rest of the match, with the message they were given. */
     readonly keptOut: Map<string, string>;
     /** Players other rooms are sending here (room.moveTo), with a seat each until they arrive. */
@@ -1184,6 +1198,15 @@ export declare class RoomCore<S = any> {
      * one after another, each with the state the last one left.
      */
     private queue;
+    /** Handlers queued so far, to tell the work a handler scheduled itself from the ticks and messages queued later (settled). */
+    private linkCount;
+    /** The queued handler running now, so what it schedules as it ends knows whose it is. */
+    private runningLinkIndex;
+    private isFlushing;
+    /** Handlers the room has started, so a runtime can tell whether a message started one. */
+    private startedCount;
+    /** Handlers a handler scheduled itself (a kicked player's onLeave), until they finish: settled waits for those of the handlers it waits for. */
+    private readonly followUps;
     /** Handlers waiting in the queue, so ticks don't pile up behind a slow game server. */
     private waitingCount;
     /** Handlers running right now, and what waits for them to finish (a kicked player's onLeave). */
@@ -1252,9 +1275,25 @@ export declare class RoomCore<S = any> {
     private sessionBlock;
     /** Players in the match who haven't walked away: what room lists and "playing now" count. */
     get playingCount(): number;
-    /** Seats the room holds for players on their way (room.moveTo) or out of the match for now. */
+    /**
+     * Seats the room holds for players on their way (room.moveTo) and for players out of the match for now,
+     * and the seats of players it keeps (dropped, or kept by onAway), who are in players but not in
+     * playingCount: playingCount + heldSeatCount is exactly what door() counts, so a room list never offers a seat the door refuses.
+     */
     get heldSeatCount(): number;
-    /** Resolves once every handler started so far has finished (at once for game servers that answer at once). */
+    /** How many game server handlers this room has started. */
+    get handlerStartCount(): number;
+    /** Whether the game server only queues players' input for its next call (a real-time game in a sandbox), so input starts no handler. */
+    get queuesInput(): boolean;
+    /** How many of the game's rooms a player may sit in at once (the option, or one). */
+    get maximumRoomCountPerPlayer(): number;
+    /** Whether a player comes here because the game sent them (room.moveTo) or reserved this room for them: their seat elsewhere stays. */
+    isArrivingByMove(playerId: string): boolean;
+    /**
+     * Resolves once every handler started so far has finished, and the work they scheduled themselves
+     * (a kicked player's onLeave, purchase hand-overs), not the ticks and messages queued after the call:
+     * a ticking room whose game server takes longer than a tick never goes idle. At once for game servers that answer at once.
+     */
     settled(): Promise<void>;
     get ticking(): boolean;
     /** How many are watching. */
@@ -1421,7 +1460,7 @@ export declare class RoomCore<S = any> {
     private limit;
     /** Remove a player (room.kick). Their onLeave runs once the handler that kicked them is done. */
     kick(playerId: string, kickOptions?: KickOptions): void;
-    /** Keep players out, newest last, up to as many as the room remembers. */
+    /** Keep players out, newest last, up to KEPT_OUT_PLAYER_COUNT: well past a full room, so nobody kicked for the match is let back by the cap. */
     private keepOut;
     /** Run now, or once the handler running now is done, so a handler never runs inside another. */
     private soon;
@@ -1503,8 +1542,11 @@ export declare class RoomCore<S = any> {
     private sent;
     /** Probe a player for their ping and a clock sample. Probes aren't counted as bytes sent, so a probe never sets off another. */
     private probe;
-    /** A ticking room probes each player in the match, and each spectator, every ROOM_TUNING.probeIntervalSec, and drops those who stopped answering. */
-    private probeDue;
+    /**
+     * A ticking room probes each player in the match, and each spectator, every ROOM_TUNING.probeIntervalSec, and drops those who stopped answering.
+     * The runtime calls this on its own 2-second timer when the room ticks slower than that, so its players never hear 8 seconds of silence.
+     */
+    probeDue(): void;
     /** A player whose oldest unanswered probe is ROOM_TUNING.probeAnswerTimeoutSec old is dropped. */
     private checkAnswers;
     /** A probe answer: the player's ping moves a quarter of the way to this sample. False if it answers no probe of theirs. */
@@ -1539,6 +1581,8 @@ export declare class RoomCore<S = any> {
      * round follows a turn-based room's handlers and a real-time room's tick (isTick).
      */
     private run;
+    /** Queue work after the handlers already queued. Work queued as a handler ends is that handler's own (settled waits for it). */
+    private chain;
 }
 /** Whether a handler's answer can be the state: a plain object (prototype Object.prototype or null) or an array. */
 export declare function isStateAnswer(given: unknown): boolean;

package/src/room.js

@@ -60,6 +60,7 @@ export const GAME_SERVER_OPTIONS = [
     "seatHoldDurationSec",
     "stateSyncEnabled",
     "reconnectTimeoutSec",
+    "maximumRoomCountPerPlayer",
     "stateSaveIntervalSec",
     "setup",
     "onJoin",
@@ -124,6 +125,9 @@ export const ROOM_LIMITS = {
     /** How long a player whose connection dropped stays in the match by default, and at most (reconnectTimeoutSec). */
     defaultReconnectTimeoutSec: 30,
     maximumReconnectTimeoutSec: 300,
+    /** Rooms of one game a player sits in at once by default, and at most (maximumRoomCountPerPlayer); a newer seat past it closes the oldest. */
+    defaultMaximumRoomCountPerPlayer: 1,
+    maximumRoomCountPerPlayer: 10,
     /** How often a real-time room saves its state by default, and the range (stateSaveIntervalSec). */
     defaultStateSaveIntervalSec: 5,
     minimumStateSaveIntervalSec: 1,
@@ -222,7 +226,7 @@ export function defineGameServer(server) {
         }
     }
     checkSchedules(server.schedules, typeof server.onSchedule === "function");
-    const { maximumPlayerCount, maximumSpectatorCount, ticksPerSec, hostControlsEnabled, idleCheck, idleTimeoutSec, awayMode, seatHoldDurationSec, reconnectTimeoutSec, stateSaveIntervalSec } = server;
+    const { maximumPlayerCount, maximumSpectatorCount, ticksPerSec, hostControlsEnabled, idleCheck, idleTimeoutSec, awayMode, seatHoldDurationSec, reconnectTimeoutSec, maximumRoomCountPerPlayer, stateSaveIntervalSec } = server;
     if (maximumPlayerCount !== undefined && !(Number.isInteger(maximumPlayerCount) && maximumPlayerCount >= 1 && maximumPlayerCount <= ROOM_LIMITS.maximumPlayerCount)) {
         throw bad("maximumPlayerCount", `maximumPlayerCount is ${JSON.stringify(maximumPlayerCount)}.`, `Give a whole number from 1 to ${ROOM_LIMITS.maximumPlayerCount}, like 8.`);
     }
@@ -252,6 +256,9 @@ export function defineGameServer(server) {
     if (reconnectTimeoutSec !== undefined && !(typeof reconnectTimeoutSec === "number" && reconnectTimeoutSec >= 0 && reconnectTimeoutSec <= ROOM_LIMITS.maximumReconnectTimeoutSec)) {
         throw bad("reconnectTimeoutSec", `reconnectTimeoutSec is ${JSON.stringify(reconnectTimeoutSec)}.`, `Give seconds from 0 (leave at once) to ${ROOM_LIMITS.maximumReconnectTimeoutSec}, like 30.`);
     }
+    if (maximumRoomCountPerPlayer !== undefined && !(Number.isInteger(maximumRoomCountPerPlayer) && maximumRoomCountPerPlayer >= 1 && maximumRoomCountPerPlayer <= ROOM_LIMITS.maximumRoomCountPerPlayer)) {
+        throw bad("maximumRoomCountPerPlayer", `maximumRoomCountPerPlayer is ${JSON.stringify(maximumRoomCountPerPlayer)}.`, `Give an integer from 1 to ${ROOM_LIMITS.maximumRoomCountPerPlayer}; leave it out for ${ROOM_LIMITS.defaultMaximumRoomCountPerPlayer}.`);
+    }
     if (stateSaveIntervalSec !== undefined && !(typeof stateSaveIntervalSec === "number" && stateSaveIntervalSec >= ROOM_LIMITS.minimumStateSaveIntervalSec && stateSaveIntervalSec <= ROOM_LIMITS.maximumStateSaveIntervalSec)) {
         throw bad("stateSaveIntervalSec", `stateSaveIntervalSec is ${JSON.stringify(stateSaveIntervalSec)}.`, `Give a number of seconds from ${ROOM_LIMITS.minimumStateSaveIntervalSec} to ${ROOM_LIMITS.maximumStateSaveIntervalSec}, like ${ROOM_LIMITS.defaultStateSaveIntervalSec}, or leave it out for ${ROOM_LIMITS.defaultStateSaveIntervalSec}.`);
     }
@@ -412,6 +419,8 @@ function messageTypeOf(messageData) {
 }
 /** How many past players a room remembers, so they can come back to a closed room, and how many it keeps out: at least everyone a full room can hold, so blocks and friends are found among all of them. */
 const REMEMBERED_PLAYER_COUNT = ROOM_LIMITS.maximumPlayerCount;
+/** How many players a room keeps out (keepOut) for the match: well past what a full room can hold, since a kicked player must stay out for the rest of it. */
+const KEPT_OUT_PLAYER_COUNT = ROOM_LIMITS.maximumPlayerCount * 10;
 const NOBODY_JOINED = { fromRoomCode: null, isReturning: false, isSpectator: false };
 const WATCHING = { fromRoomCode: null, isReturning: false, isSpectator: true };
 /** Two players with a block between them, in either order (player IDs have no spaces). */
@@ -453,6 +462,8 @@ export class RoomCore {
     listingChanged = false;
     /** Players who have been in this room, newest last: they may come back after it closes. */
     known = new Set();
+    /** Players a reserved room was made for who haven't arrived: never forgotten until they do. */
+    reservedPlayerIds = new Set();
     /** Players kicked and kept out for the rest of the match, with the message they were given. */
     keptOut = new Map();
     /** Players other rooms are sending here (room.moveTo), with a seat each until they arrive. */
@@ -506,6 +517,15 @@ export class RoomCore {
      * one after another, each with the state the last one left.
      */
     queue = null;
+    /** Handlers queued so far, to tell the work a handler scheduled itself from the ticks and messages queued later (settled). */
+    linkCount = 0;
+    /** The queued handler running now, so what it schedules as it ends knows whose it is. */
+    runningLinkIndex = 0;
+    isFlushing = false;
+    /** Handlers the room has started, so a runtime can tell whether a message started one. */
+    startedCount = 0;
+    /** Handlers a handler scheduled itself (a kicked player's onLeave), until they finish: settled waits for those of the handlers it waits for. */
+    followUps = new Set();
     /** Handlers waiting in the queue, so ticks don't pile up behind a slow game server. */
     waitingCount = 0;
     /** Handlers running right now, and what waits for them to finish (a kicked player's onLeave). */
@@ -552,6 +572,8 @@ export class RoomCore {
             this.labels = saved.labels ?? {};
             for (const id of saved.knownPlayerIds ?? [])
                 this.known.add(id);
+            for (const id of saved.reservedPlayerIds ?? [])
+                this.reservedPlayerIds.add(id);
             this.setupData = saved.setupData ?? null;
             this.keepOut(saved.keptOut);
             for (const [id, expected] of Object.entries(saved.expected ?? {}))
@@ -590,8 +612,10 @@ export class RoomCore {
             this.friendJoinsEnabled = start.friendJoinsEnabled !== false;
             this.name = start.name;
             this.labels = start.labels;
-            for (const id of start.playerIds)
+            for (const id of start.playerIds) {
                 this.known.add(id);
+                this.reservedPlayerIds.add(id);
+            }
             this.setupData = start.setupData ?? null;
             this.keepOut(start.keptOut);
             this.lobbyRoomCode = start.lobbyRoomCode ?? null;
@@ -737,6 +761,7 @@ export class RoomCore {
         return {
             ...this.settings(),
             knownPlayerIds: [...this.known],
+            ...(this.reservedPlayerIds.size ? { reservedPlayerIds: [...this.reservedPlayerIds] } : {}),
             ...(this.setupData !== null ? { setupData: this.setupData } : {}),
             ...(this.keptOut.size ? { keptOut: Object.fromEntries(this.keptOut) } : {}),
             ...(this.expected.size ? { expected: Object.fromEntries(this.expected) } : {}),
@@ -853,21 +878,59 @@ export class RoomCore {
     get playingCount() {
         return this.players.size - this.kept.size;
     }
-    /** Seats the room holds for players on their way (room.moveTo) or out of the match for now. */
+    /**
+     * Seats the room holds for players on their way (room.moveTo) and for players out of the match for now,
+     * and the seats of players it keeps (dropped, or kept by onAway), who are in players but not in
+     * playingCount: playingCount + heldSeatCount is exactly what door() counts, so a room list never offers a seat the door refuses.
+     */
     get heldSeatCount() {
-        return this.countHeldSeats();
+        return this.countHeldSeats() + this.kept.size;
+    }
+    /** How many game server handlers this room has started. */
+    get handlerStartCount() {
+        return this.startedCount;
+    }
+    /** Whether the game server only queues players' input for its next call (a real-time game in a sandbox), so input starts no handler. */
+    get queuesInput() {
+        return this.server[QUEUES_INPUT] === true;
     }
-    /** Resolves once every handler started so far has finished (at once for game servers that answer at once). */
+    /** How many of the game's rooms a player may sit in at once (the option, or one). */
+    get maximumRoomCountPerPlayer() {
+        return this.server.maximumRoomCountPerPlayer ?? ROOM_LIMITS.defaultMaximumRoomCountPerPlayer;
+    }
+    /** Whether a player comes here because the game sent them (room.moveTo) or reserved this room for them: their seat elsewhere stays. */
+    isArrivingByMove(playerId) {
+        return this.seat(playerId) !== null || this.reservedPlayerIds.has(playerId);
+    }
+    /**
+     * Resolves once every handler started so far has finished, and the work they scheduled themselves
+     * (a kicked player's onLeave, purchase hand-overs), not the ticks and messages queued after the call:
+     * a ticking room whose game server takes longer than a tick never goes idle. At once for game servers that answer at once.
+     */
     async settled() {
-        while (this.queue || this.purchaseDeliveries.size) {
+        let horizonLinkIndex = this.linkCount;
+        const waited = new Set();
+        const tail = this.queue;
+        for (;;) {
             if (this.purchaseDeliveries.size)
                 await Promise.all([...this.purchaseDeliveries]);
-            const queued = this.queue;
-            if (!queued)
+            const links = [];
+            if (tail && !waited.has(tail))
+                links.push(tail);
+            for (const followUp of this.followUps) {
+                if (followUp.parentLinkIndex > horizonLinkIndex || waited.has(followUp.link))
+                    continue;
+                links.push(followUp.link);
+                horizonLinkIndex = Math.max(horizonLinkIndex, followUp.linkIndex);
+            }
+            if (!links.length) {
+                if (!this.purchaseDeliveries.size)
+                    return;
                 continue;
-            await queued;
-            if (this.queue === queued && !this.purchaseDeliveries.size)
-                return;
+            }
+            for (const link of links)
+                waited.add(link);
+            await Promise.all(links);
         }
     }
     get ticking() {
@@ -984,8 +1047,11 @@ export class RoomCore {
         const expected = this.expected.get(id);
         if (expected && expected.untilMs > this.now())
             return expected;
-        if (expected)
+        if (expected) {
             this.expected.delete(id);
+            this.listingChanged = true;
+            this.dirty = true;
+        }
         return null;
     }
     /** Seats held for players other rooms are sending and players out of the match, dropping those that ran out. */
@@ -1019,8 +1085,10 @@ export class RoomCore {
             else
                 answer.refusals.push({ playerId: player.id, code: verdict.code, message: verdict.message || ERROR_TEXT[verdict.code] });
         }
-        if (answer.movedPlayerIds.length)
+        if (answer.movedPlayerIds.length) {
             this.dirty = true;
+            this.listingChanged = true;
+        }
         return answer;
     }
     /**
@@ -1239,6 +1307,7 @@ export class RoomCore {
             this.listingChanged = true;
             this.dirty = true;
             this.run(() => this.server.onAway(this.state, player, this.api, { reason }), "onAway");
+            this.broadcastPlayers();
             return;
         }
         this.out(playerId);
@@ -1328,9 +1397,17 @@ export class RoomCore {
             else if (this.ticking && presence.hiddenAtMs !== undefined && nowMs - presence.hiddenAtMs >= ROOM_LIMITS.hiddenTimeoutSec * 1000)
                 this.walkAway(id, "hidden");
         }
-        // Rooms that don't tick check their probes here.
-        for (const id of [...this.presence.keys()])
+        // Rooms that don't tick check their probes here, and tell players a ping they haven't heard yet.
+        for (const [id, presence] of [...this.presence]) {
             this.checkAnswers(id);
+            if (presence.isPingStale && !this.kept.has(id)) {
+                presence.pingProbeAtMs = nowMs;
+                this.probe(id);
+            }
+        }
+        // Seats held for players on their way that ran out leave the room's row.
+        for (const id of [...this.expected.keys()])
+            this.seat(id);
         for (const [id, held] of [...this.held]) {
             if (held.untilMs > nowMs)
                 continue;
@@ -1700,14 +1777,14 @@ export class RoomCore {
             this.broadcastPlayers();
         });
     }
-    /** Keep players out, newest last, up to as many as the room remembers. */
+    /** Keep players out, newest last, up to KEPT_OUT_PLAYER_COUNT: well past a full room, so nobody kicked for the match is let back by the cap. */
     keepOut(players) {
         for (const [id, message] of Object.entries(players ?? {})) {
             if (typeof message !== "string")
                 continue;
             this.keptOut.delete(id);
             this.keptOut.set(id, message.slice(0, ROOM_LIMITS.maximumKickMessageCharacterCount));
-            if (this.keptOut.size > REMEMBERED_PLAYER_COUNT)
+            if (this.keptOut.size > KEPT_OUT_PLAYER_COUNT)
                 this.keptOut.delete(this.keptOut.keys().next().value);
         }
     }
@@ -1719,21 +1796,26 @@ export class RoomCore {
             work();
     }
     flush() {
-        while (!this.depth && this.afterHandler.length)
-            this.afterHandler.shift()();
+        const wasFlushing = this.isFlushing;
+        this.isFlushing = true;
+        try {
+            while (!this.depth && this.afterHandler.length)
+                this.afterHandler.shift()();
+        }
+        finally {
+            this.isFlushing = wasFlushing;
+        }
     }
     remember(id) {
         this.known.delete(id);
         this.known.add(id);
-        // Forget the oldest who isn't here or holding a seat, so no player in the match drops out of what the room knows of them.
-        if (this.known.size > REMEMBERED_PLAYER_COUNT) {
-            for (const oldest of this.known) {
-                if (oldest === id || this.players.has(oldest) || this.holding(oldest) !== null)
-                    continue;
-                this.known.delete(oldest);
-                break;
-            }
-        }
+        this.reservedPlayerIds.delete(id);
+        if (this.known.size <= REMEMBERED_PLAYER_COUNT)
+            return;
+        // Only players who left are forgotten, the oldest first, past REMEMBERED_PLAYER_COUNT of them: nobody in the match, holding a seat, expected or reserved for drops out of what the room knows of them.
+        const gone = [...this.known].filter((other) => other !== id && !this.players.has(other) && !this.reservedPlayerIds.has(other) && this.holding(other) === null && this.seat(other) === null);
+        for (const other of gone.slice(0, Math.max(0, gone.length - REMEMBERED_PLAYER_COUNT)))
+            this.known.delete(other);
     }
     tick(tickDurationSec) {
         if (this.ended)
@@ -1830,7 +1912,7 @@ export class RoomCore {
         if (syncs)
             return this.run(() => syncs(this.state, this.api), "stateSync");
         if (this.queue)
-            this.queue = this.queue.then(() => this.syncState());
+            this.chain(() => this.syncState());
         else
             this.soon(() => this.syncState());
     }
@@ -2030,11 +2112,15 @@ export class RoomCore {
             presence.unansweredProbes.delete(presence.unansweredProbes.keys().next().value);
         presence.lastProbeAtMs = nowMs;
         presence.lastProbeSentByteCount = presence.sentByteCount;
+        presence.isPingStale = false;
         const text = JSON.stringify({ type: "probe", probeNumber, serverTimeMs: nowMs, pingDurationMs: presence.pingDurationMs });
         this.transport.send(playerId, text);
         this.countTraffic("outbound", ZAISMA_MESSAGE_TYPE, 1, text.length);
     }
-    /** A ticking room probes each player in the match, and each spectator, every ROOM_TUNING.probeIntervalSec, and drops those who stopped answering. */
+    /**
+     * A ticking room probes each player in the match, and each spectator, every ROOM_TUNING.probeIntervalSec, and drops those who stopped answering.
+     * The runtime calls this on its own 2-second timer when the room ticks slower than that, so its players never hear 8 seconds of silence.
+     */
     probeDue() {
         const nowMs = this.now();
         for (const id of this.everyone()) {
@@ -2069,6 +2155,16 @@ export class RoomCore {
         // The first measurement: probe again at once, so the player's game hears its ping too, even in a room that doesn't tick.
         if (previousMs === null)
             this.probe(playerId);
+        else if (!this.ticking && presence.pingDurationMs !== previousMs) {
+            // A room that doesn't tick has no regular probes, so tell their game the new ping: now, at most once every probe interval, and the sweep sends the rest.
+            const nowMs = this.now();
+            if (nowMs - presence.pingProbeAtMs >= ROOM_TUNING.probeIntervalSec * 1000) {
+                presence.pingProbeAtMs = nowMs;
+                this.probe(playerId);
+            }
+            else
+                presence.isPingStale = true;
+        }
         // An answer is when a backed-up connection shows it caught up.
         this.soon(() => this.catchUp());
         return true;
@@ -2212,6 +2308,7 @@ export class RoomCore {
      * round follows a turn-based room's handlers and a real-time room's tick (isTick).
      */
     run(handler, handlerName, isTick = false) {
+        this.startedCount++;
         const isSyncing = this.stateTracker !== null && (isTick || !this.ticking);
         if (!this.queue) {
             let next;
@@ -2239,7 +2336,7 @@ export class RoomCore {
             handler = () => started;
         }
         this.waitingCount++;
-        this.queue = this.queue.then(async () => {
+        this.chain(async () => {
             this.depth++;
             try {
                 const next = await handler();
@@ -2258,6 +2355,20 @@ export class RoomCore {
             }
         });
     }
+    /** Queue work after the handlers already queued. Work queued as a handler ends is that handler's own (settled waits for it). */
+    chain(work) {
+        const linkIndex = ++this.linkCount;
+        const link = this.queue.then(() => {
+            this.runningLinkIndex = linkIndex;
+            return work();
+        });
+        if (this.isFlushing) {
+            const followUp = { link, linkIndex, parentLinkIndex: this.runningLinkIndex };
+            this.followUps.add(followUp);
+            void link.then(() => this.followUps.delete(followUp));
+        }
+        this.queue = link;
+    }
 }
 /** The calls that change the room or send from it: not for canJoin or stateView, which only decide and answer. */
 const CHANGING_CALLS = ["broadcast", "send", "broadcastBytes", "sendBytes", "end", "setListed", "setOpen", "setFriendJoinsEnabled", "setKept", "setInfo", "reserve", "kick", "moveTo", "applyVersionUpdate"];
@@ -2292,7 +2403,7 @@ function isPromise(given) {
 }
 /** A player's presence as they come in: nothing sent and nothing measured yet. A room waking from sleep starts its probes afresh. */
 function newPresence(seenAtMs, clientIdle) {
-    return { seenAtMs, clientIdle, sentByteCount: 0, answeredSentByteCount: 0, lastProbeSentByteCount: 0, lastProbeAtMs: 0, unansweredProbes: new Map(), pingDurationMs: null };
+    return { seenAtMs, clientIdle, sentByteCount: 0, answeredSentByteCount: 0, lastProbeSentByteCount: 0, lastProbeAtMs: 0, unansweredProbes: new Map(), pingDurationMs: null, pingProbeAtMs: Number.NEGATIVE_INFINITY, isPingStale: false };
 }
 /** How many bytes a text takes on the wire. */
 function utf8ByteCount(text) {

package/src/schedules.js

@@ -159,7 +159,9 @@ const MAXIMUM_TIMER_MS = 24 * 3_600_000;
 export function startSchedules(handler, server, onFailure) {
     const timers = new Set();
     let isStopped = false;
-    for (const schedule of handler.schedules ?? []) {
+    // Run from the checked list, so run.cron is the tidied cron on every runtime (get_stats lists it that way too).
+    const read = readSchedules(handler.schedules, typeof handler.onSchedule === "function");
+    for (const schedule of "schedules" in read ? read.schedules : []) {
         const plan = (afterMs) => {
             const atMs = nextRunAtMs(schedule.cron, afterMs);
             if (atMs === null || isStopped)