castle-web-cli 0.4.170 → 0.4.171

package/kits/real-time/code/client/messages.js

@@ -15,6 +15,10 @@ export const MOVE = 'i';
 export const WORLD = 'w';
 export const STATE = 's';
 
+// A client reports that it removed a scene actor: `{ k: GONE, id }`. The
+// session removes it for everyone, for good.
+export const GONE = 'g';
+
 // Movement reports run below the render rate and below the platform's roughly
 // 30-message-per-second client cap. A second report inside one server tick would
 // be overwritten before the simulation read it.

package/kits/real-time/code/server/gameHooks.js

@@ -21,8 +21,12 @@ const bodyModules = {
 // `session.js` receives this value from the dimensional kit's server entry and
 // calls the hooks at the stages listed below.
 //
+//   restore(sim, saved)           the value the last `save` returned for this
+//                                 room, or null. Runs before `ready`
 //   ready(sim)                    after the world and its scene bodies exist,
 //                                 before the first server tick
+//   save(sim)                     JSON kept for this room, written with the
+//                                 world every ten seconds and at shutdown
 //   message(session, player, d)   client data that is not a pose report. It
 //                                 receives no handover list, so a world change
 //                                 is kept and applied later by `place` or `step`

package/kits/real-time/code/server/persist.js

@@ -0,0 +1,105 @@
+// Deck storage for a real-time session: the world, the players, and the deck's
+// own block.
+//
+//   world:<room>            { poses, gone }: object poses and the ids of scene
+//                           actors removed for good
+//   game:<room>             whatever the deck's `save` hook returned
+//   player:<room>:<userId>  { pose, state }: where the player was and the
+//                           block their client reported
+//
+// Storage rows are keyed by deck and not by session, so every key here carries
+// the room the session belongs to. A named session and a party each have their
+// own room; every public shard shares one.
+//
+// The server owns `deck` scope once a deck publishes a server. An unpublished
+// deck has no storage at all, so a failure is reported and the session runs on
+// without persistence.
+
+// The room a session persists under.
+export function roomOf(session) {
+  return session.mode === 'public' ? 'public' : session.sessionId;
+}
+
+// Read one room's world and deck block. A world saved before the gone list
+// existed is a bare pose array.
+export async function loadRoom(session, room) {
+  const saved = await read(session, [`world:${room}`, `game:${room}`], 'loadRoom');
+  const world = saved[`world:${room}`];
+  return {
+    world: Array.isArray(world) ? { poses: world, gone: [] } : (world ?? null),
+    game: saved[`game:${room}`] ?? null,
+  };
+}
+
+// Read one user's saved pose and state in this room, or null. A row saved
+// before state existed is a bare pose array.
+export async function loadPlayer(session, room, userId) {
+  const key = playerKey(room, userId);
+  const saved = await read(session, [key], 'loadPlayer');
+  const row = saved[key];
+  if (Array.isArray(row)) {
+    return { pose: row, state: null };
+  }
+  return Array.isArray(row?.pose) ? { pose: row.pose, state: row.state ?? null } : null;
+}
+
+// Write a room's world, deck block and present players in one request.
+// `players` is a list of `[userId, { pose, state }]`.
+export async function saveRoom(session, room, { world, game, players }) {
+  const values = { [`world:${room}`]: world };
+  if (game !== null && game !== undefined) {
+    values[`game:${room}`] = game;
+  }
+  for (const [userId, saved] of players) {
+    values[playerKey(room, userId)] = saved;
+  }
+  const stored = await write(session, values, 'saveRoom');
+
+  // Logged once; the same line every ten seconds says nothing more.
+  if (stored && !announced) {
+    announced = true;
+    console.log(`[persist] saving ${Object.keys(values).length} keys under ${room}`);
+  }
+}
+
+// Write one user's pose and state, which is where a later session starts them.
+export async function savePlayer(session, room, userId, saved) {
+  await write(session, { [playerKey(room, userId)]: saved }, 'savePlayer');
+}
+
+function playerKey(room, userId) {
+  return `player:${room}:${userId}`;
+}
+
+async function read(session, keys, operation) {
+  try {
+    return await session.storage.deck.get(keys);
+  } catch (error) {
+    report(operation, error);
+    return {};
+  }
+}
+
+async function write(session, values, operation) {
+  try {
+    await session.storage.deck.set(values);
+    return true;
+  } catch (error) {
+    report(operation, error);
+    return false;
+  }
+}
+
+let announced = false;
+
+// Operations that have already reported a failure, so a broken setup is named
+// once.
+const reported = new Set();
+
+function report(operation, error) {
+  if (reported.has(operation)) {
+    return;
+  }
+  reported.add(operation);
+  console.error(`[persist] ${operation} failed: ${error?.message ?? error}`);
+}

package/kits/real-time/code/server/session.js

@@ -7,20 +7,44 @@
 // kit modules or through the callbacks the kit's pose codec exports.
 
 import * as Messages from '../client/messages.js';
+import * as Persist from './persist.js';
 
 // Maximum wall-clock duration passed to physics for one session tick.
 const MAX_TICK_SECONDS = 0.25;
 
+// How often a moved world and its players are written to storage.
+const SAVE_INTERVAL_MS = 10000;
+
+// How long a joining player waits for their saved pose before starting at the
+// scene's spawn.
+const RESUME_WAIT_MS = 3000;
+
+// A player whose last report is older than this has gone: a closed tab whose
+// connection the platform has not reaped yet.
+const GHOST_MS = 2000;
+
 // The state one session process keeps, beside the modules it was built with:
 //
 //   label            prefix for this process in log messages
 //   poses            the kit's pose codec, for `PLAYER_GEOMETRY` and the
 //                    per-index `epsilonAt` the delta comparison reads
-//   world            createSimulation, step, objectPoses
+//   world            createSimulation, step, objectPoses, restorePoses
 //   players          addPlayer, removePlayer, setPose, playerPoses
 //   ownership        claim, release, setObjectPoses, sweepOwners, ownerships
 //   game             the deck's hooks, from `gameHooks.js`
 //   sim              the simulation, null until it is built
+//   building         the pending simulation, from `createSimulation`
+//   session          the Castle session, from the first callback carrying one
+//   room             the storage room this session persists under
+//   joining          playerId -> { done, saved, userId, until } while a saved
+//                    player row is being read
+//   gone             ids of scene actors removed for good, by any client
+//   newlyGone        ids removed since the last broadcast
+//   resumedUsers     userId -> playerId, for bodies that started from a saved
+//                    pose or took over a gone player's
+//   moved            whether a pose moved since the last save
+//   savedAt          wall clock of the last save
+//   saving           the save in flight, or null
 //   lastTickAt       wall clock at the previous tick
 //   sent             the last pose broadcast for each id, so a later tick can
 //                    send only what changed
@@ -31,6 +55,16 @@ function newServer(parts) {
   return {
     ...parts,
     sim: null,
+    building: null,
+    session: null,
+    room: '',
+    joining: new Map(),
+    gone: new Set(),
+    newlyGone: [],
+    resumedUsers: new Map(),
+    moved: false,
+    savedAt: 0,
+    saving: null,
     lastTickAt: 0,
     sent: { players: new Map(), objects: new Map() },
     waitingForWorld: new Set(),
@@ -45,17 +79,29 @@ function newServer(parts) {
 // and messages between them.
 export function makeSession(parts) {
   const server = newServer(parts);
-  buildWorld(server);
+
+  // Castle's handlers remain available while `createSimulation` is pending.
+  server.building = server.world.createSimulation();
   return {
+    onStart(session) {
+      attach(server, session);
+    },
+
     // Joins are logged here; the simulation's players are reconciled from the
     // full session roster on the next tick.
     onPlayerJoin(session, player) {
+      attach(server, session);
       console.log(`[${server.label}] join ${player.username} (${player.playerId})`);
+
+      // The saved pose is read now, so the body this player is given on a later
+      // tick can start there.
+      beginResume(server, player);
     },
 
     onPlayerLeave(session, player) {
       // The next roster reconciliation removes the simulation player and body.
       console.log(`[${server.label}] leave ${player.username}`);
+      savePlayer(server, player);
     },
 
     onMessage(session, player, data) {
@@ -63,6 +109,7 @@ export function makeSession(parts) {
     },
 
     onTick(session) {
+      attach(server, session);
       tick(server, session);
     },
 
@@ -70,27 +117,64 @@ export function makeSession(parts) {
       // Tell the connected clients when Castle replaces this session process.
       session.broadcast({ k: 'replaced' });
     },
+
+    async onShutdown() {
+      await saveRoom(server);
+    },
   };
 }
 
-// Start building the simulation when the handler object is created. Castle's
-// handlers remain available while `createSimulation` is pending.
-function buildWorld(server) {
-  server.world.createSimulation().then(
-    (created) => {
-      server.sim = created;
+// Keep the first session a callback carries and build the world with it. The
+// room the session persists under is not known before this.
+function attach(server, session) {
+  if (server.session) {
+    return;
+  }
+  server.session = session;
+  server.room = Persist.roomOf(session);
+  buildWorld(server);
+}
 
-      // Invoke the deck's ready hook with the built world before the first tick.
-      server.game.ready?.(created);
-      console.log(`[${server.label}] simulation ready`);
-    },
-    (err) => console.error(`[${server.label}] simulation failed: ${err?.message ?? err}`),
-  );
+// Finish the simulation: read the saved room, run the deck's restore and ready
+// hooks, and apply the saved object poses. `server.sim` is assigned last, so the
+// first WORLD snapshot anybody receives is the restored one.
+async function buildWorld(server) {
+  try {
+    const created = await server.building;
+    const saved = await Persist.loadRoom(server.session, server.room);
+    server.game.restore?.(created, saved.game);
+
+    // Invoke the deck's ready hook with the built world before the first tick.
+    server.game.ready?.(created);
+
+    // Saved poses go on after both hooks, which is where a deck adds objects of
+    // its own. Ids the scene no longer has are skipped.
+    const applied = Array.isArray(saved.world?.poses)
+      ? server.world.restorePoses(created, saved.world.poses)
+      : 0;
+    for (const id of saved.world?.gone ?? []) {
+      if (typeof id === 'string') {
+        server.gone.add(id);
+        server.world.removeActor?.(created, id);
+      }
+    }
+    server.sim = created;
+    console.log(
+      `[${server.label}] simulation ready, ${applied} object poses restored, ${server.gone.size} actors gone`,
+    );
+  } catch (err) {
+    console.error(`[${server.label}] simulation failed: ${err?.message ?? err}`);
+  }
 }
 
 // Route one client message. Movement reports update the simulation, and other
 // message kinds go to the deck hook.
 function receive(server, session, player, data) {
+  if (data?.k === Messages.GONE) {
+    markGone(server, data.id);
+    return;
+  }
+
   // Deck control messages can run before simulation initialization completes.
   if (data?.k !== Messages.MOVE) {
     server.game.message?.(session, player, data);
@@ -112,6 +196,18 @@ function receive(server, session, player, data) {
   server.ownership.release(server.sim, player.playerId, data.r, server.handovers);
 }
 
+// Remove a scene actor for everyone. The id is a scene actor id; anything else
+// is ignored. The world drops the actor's body when it has one.
+function markGone(server, id) {
+  if (!server.sim || typeof id !== 'string' || id.length > 128 || server.gone.has(id)) {
+    return;
+  }
+  server.gone.add(id);
+  server.newlyGone.push(id);
+  server.world.removeActor?.(server.sim, id);
+  server.moved = true;
+}
+
 // One session tick: reconcile players, sweep ownership, run the deck's hooks
 // around physics, and send the join snapshots and the delta.
 function tick(server, session) {
@@ -144,16 +240,22 @@ function tick(server, session) {
   // A new player gets the whole world and the current ownerships. Sending the
   // ownerships with that first snapshot stops the client from simulating an
   // object somebody else already holds.
+  // A new player also gets every actor that is gone and their own saved block,
+  // which their client restores before it plays.
   for (const playerId of server.waitingForWorld) {
+    const state = server.players.stateOf?.(server.sim, playerId) ?? null;
     session.send(playerId, {
       k: Messages.WORLD,
       ...snapshot,
       own: server.ownership.ownerships(server.sim),
+      gone: [...server.gone],
+      ...(state === null ? {} : { me: state }),
       ...server.game.join?.(server.sim),
     });
   }
   server.waitingForWorld.clear();
   broadcastDelta(server, session, snapshot);
+  maybeSave(server);
 }
 
 // Make the simulation's player map match Castle's roster. The roster covers the
@@ -165,9 +267,11 @@ function reconcilePlayers(server, session) {
       continue;
     }
 
-    // A newly observed roster id gets a body and a full WORLD on this tick.
-    server.players.addPlayer(server.sim, playerId);
-    server.waitingForWorld.add(playerId);
+    // A newly observed roster id gets a body and a full WORLD on the tick its
+    // saved pose has been read.
+    if (admit(server, session, playerId)) {
+      server.waitingForWorld.add(playerId);
+    }
   }
   for (const playerId of [...server.sim.players.keys()]) {
     if (present.has(playerId)) {
@@ -180,6 +284,159 @@ function reconcilePlayers(server, session) {
   }
 }
 
+// Give one roster id a body. A gone player of the same account is taken over at
+// once; otherwise the saved pose is waited for, up to `RESUME_WAIT_MS`.
+function admit(server, session, playerId) {
+  const entry = server.joining.get(playerId);
+  const ghost = entry ? ghostOf(server, session, playerId, entry.userId) : null;
+  if (ghost === undefined) {
+    // Another connection of this account is still playing: a second character.
+    server.joining.delete(playerId);
+    server.players.addPlayer(server.sim, playerId, null);
+    return true;
+  }
+  if (ghost) {
+    server.joining.delete(playerId);
+    server.resumedUsers.set(entry.userId, playerId);
+    server.players.addPlayer(server.sim, playerId, poseOf(server, ghost));
+    server.players.setState?.(server.sim, playerId, server.players.stateOf?.(server.sim, ghost));
+    return true;
+  }
+  if (entry && !entry.done && Date.now() < entry.until) {
+    return false;
+  }
+  server.joining.delete(playerId);
+  const saved = resumeSaved(server, playerId, entry);
+  server.players.addPlayer(server.sim, playerId, saved?.pose ?? null);
+  server.players.setState?.(server.sim, playerId, saved?.state ?? null);
+  return true;
+}
+
+// The playerId of a present player of the same account whose reports have
+// stopped: a tab that was closed and not yet reaped. `undefined` when such a
+// player is still reporting, null when there is none.
+function ghostOf(server, session, playerId, userId) {
+  for (const player of session.players) {
+    if (player.playerId === playerId || player.userId !== userId) {
+      continue;
+    }
+    const body = server.sim.players.get(player.playerId);
+    if (!body) {
+      continue;
+    }
+    return server.sim.timeMs - body.movedAt > GHOST_MS ? player.playerId : undefined;
+  }
+  return null;
+}
+
+// The saved row a joining player resumes from, or null for the scene's spawn
+// with no state.
+function resumeSaved(server, playerId, entry) {
+  if (!entry?.saved || server.resumedUsers.has(entry.userId)) {
+    return null;
+  }
+  server.resumedUsers.set(entry.userId, playerId);
+  return entry.saved;
+}
+
+// Start reading a joining player's saved row.
+function beginResume(server, player) {
+  if (!player.userId) {
+    return;
+  }
+  const entry = {
+    done: false,
+    saved: null,
+    userId: player.userId,
+    until: Date.now() + RESUME_WAIT_MS,
+  };
+  server.joining.set(player.playerId, entry);
+  void Persist.loadPlayer(server.session, server.room, player.userId).then((saved) => {
+    entry.saved = saved;
+    entry.done = true;
+  });
+}
+
+// Write a leaving player's last pose. Their body is still in the simulation
+// until the next reconciliation. A player another connection took over writes
+// nothing: the newer body's pose is the one to keep.
+function savePlayer(server, player) {
+  server.joining.delete(player.playerId);
+  const holder = server.resumedUsers.get(player.userId);
+  if (holder && holder !== player.playerId) {
+    return;
+  }
+  server.resumedUsers.delete(player.userId);
+  const pose = poseOf(server, player.playerId);
+  if (!pose || !player.userId) {
+    return;
+  }
+  const state = server.players.stateOf?.(server.sim, player.playerId) ?? null;
+  void Persist.savePlayer(server.session, server.room, player.userId, { pose, state });
+}
+
+// Write the world every `SAVE_INTERVAL_MS`, and only when a pose moved since the
+// last write.
+function maybeSave(server) {
+  const now = Date.now();
+  if (!server.moved || server.saving || now - server.savedAt < SAVE_INTERVAL_MS) {
+    return;
+  }
+  server.moved = false;
+  void saveRoom(server);
+}
+
+// Write the world, the deck's block and every present player. A save already in
+// flight is waited for, so a shutdown during the timer's write still lands its
+// own.
+async function saveRoom(server) {
+  if (!server.sim || !server.session) {
+    return;
+  }
+  if (server.saving) {
+    await server.saving;
+  }
+  server.savedAt = Date.now();
+  server.saving = Persist.saveRoom(server.session, server.room, {
+    world: { poses: server.world.objectPoses(server.sim), gone: [...server.gone] },
+    game: server.game.save?.(server.sim) ?? null,
+    players: presentPlayers(server),
+  });
+  try {
+    await server.saving;
+  } finally {
+    server.saving = null;
+  }
+}
+
+// Every present player's pose and state, by user id.
+function presentPlayers(server) {
+  const users = new Map(server.session.players.map((player) => [player.playerId, player.userId]));
+  const out = [];
+  for (const [playerId, ...pose] of server.players.playerPoses(server.sim)) {
+    const userId = users.get(playerId);
+    if (userId) {
+      const state = server.players.stateOf?.(server.sim, playerId) ?? null;
+      out.push([userId, { pose: pose.slice(0, server.poses.PLAYER_GEOMETRY), state }]);
+    }
+  }
+  return out;
+}
+
+// One player's current pose, without the `clamped` flag that belongs to a
+// single tick.
+function poseOf(server, playerId) {
+  if (!server.sim) {
+    return null;
+  }
+  for (const [id, ...pose] of server.players.playerPoses(server.sim)) {
+    if (id === playerId) {
+      return pose.slice(0, server.poses.PLAYER_GEOMETRY);
+    }
+  }
+  return null;
+}
+
 // Broadcast what changed since the previous tick. A tick where nothing changed
 // sends nothing at all.
 function broadcastDelta(server, session, snapshot) {
@@ -202,14 +459,27 @@ function broadcastDelta(server, session, snapshot) {
   // a new list for the next broadcast.
   const own = server.handovers;
   server.handovers = [];
+  const gone = server.newlyGone;
+  server.newlyGone = [];
+
+  // Only a moved pose makes the next save worth making.
+  server.moved = server.moved || ps.length > 0 || os.length > 0;
 
   // A changed deck block is its own reason to broadcast, including on a tick
   // where no pose and no ownership moved.
   const block = server.game.delta?.(server.sim) ?? null;
-  if (ps.length === 0 && os.length === 0 && own.length === 0 && !block) {
+  if (ps.length === 0 && os.length === 0 && own.length === 0 && gone.length === 0 && !block) {
     return;
   }
-  session.broadcast({ k: Messages.STATE, t: snapshot.t, ps, os, own, ...block });
+  session.broadcast({
+    k: Messages.STATE,
+    t: snapshot.t,
+    ps,
+    os,
+    own,
+    ...(gone.length ? { gone } : {}),
+    ...block,
+  });
 }
 
 // Whether one player's pose belongs in this delta, recording it as the new