castle-web-cli 0.4.170 → 0.4.172

package/kits/multiplayer-3d/code/systems/multiplayer.js

@@ -10,7 +10,11 @@ import * as Smoothing from '@imports/castle.real-time/code/client/smooth.js';
 import * as Poses from '../client/poses.js';
 import { connectSession } from '@imports/castle.real-time/code/client/connection.js';
 import { showSoloBadge, updateSoloBadge } from '@imports/castle.real-time/code/client/soloBadge.js';
-import { STATE, WORLD } from '@imports/castle.real-time/code/client/messages.js';
+import { showJoinOverlay } from '@imports/castle.real-time/code/client/joinOverlay.js';
+import { GONE, STATE, WORLD } from '@imports/castle.real-time/code/client/messages.js';
+
+// How long the joining overlay may hold the card before giving up.
+const JOIN_WAIT_MS = 10000;
 import { game } from '@imports/castle.real-time/code/client/gameHooks.js';
 
 // Apply this fraction of a server player correction per frame. Corrections over
@@ -46,6 +50,11 @@ class MultiplayerSystem {
   constructor() {
     // The Castle transport is created on the first stepped frame.
     this.net = null;
+    // False until a server snapshot carries this player's pose. The overlay
+    // stays up from the first stepped frame until then, or until JOIN_WAIT_MS
+    // after the join began if the session never answers.
+    this.joined = false;
+    this.joinStartedAt = 0;
 
     // `starting` prevents concurrent join attempts while the promise is pending.
     this.starting = false;
@@ -68,6 +77,16 @@ class MultiplayerSystem {
 
     // A clamp stores the last server position that rejected a local move.
     this.clampedTo = null;
+
+    // Scene actors the session has removed for good, and the actor ids present
+    // at the end of the last frame. An id that was there and is not now was
+    // despawned by a behavior this frame, and is reported.
+    this.gone = new Set();
+    this.seen = null;
+
+    // The JSON of the last state block sent, so a block goes out only when it
+    // changes.
+    this.sentState = '';
   }
 
   // Run the network frame after engine behaviors and local physics. Connection,
@@ -76,12 +95,15 @@ class MultiplayerSystem {
     // Connecting on the first stepped frame keeps editor-only runtimes out of
     // multiplayer sessions because the scene editor constructs but never steps them.
     if (!this.net) {
+      showJoinOverlay(this.joiningOverlayWanted());
       return void this.start();
     }
     const local = scene.actorWith('Player');
 
     // Drain all queued messages before choosing the render time for this frame.
     this.receive(scene);
+    this.applyGone(scene);
+    this.reportGone(scene);
 
     // Draw at a fixed delay behind the server clock so interpolation normally has
     // samples on both sides. The local engine keeps stepping before the first
@@ -98,7 +120,9 @@ class MultiplayerSystem {
     // Deck code can make a final local adjustment after engine Player behavior
     // and physics, then optionally replace the kit's standard report.
     game.beforeReport?.(scene, local, this);
-    if (game.report) {
+    if (!this.joined) {
+      // Nothing reported until the session has placed this player.
+    } else if (game.report) {
       game.report(scene, local, this);
     } else {
       this.report(scene, local);
@@ -117,6 +141,7 @@ class MultiplayerSystem {
     }
     this.publish(scene, local);
     updateSoloBadge(this.net.status(), game);
+    showJoinOverlay(this.joiningOverlayWanted());
   }
 
   // Join the Castle public session once and retain the transport across scene loads.
@@ -125,6 +150,7 @@ class MultiplayerSystem {
       return;
     }
     this.starting = true;
+    this.joinStartedAt ||= performance.now();
     try {
       this.net = await connectSession({ onLog: (text) => console.log(`[multiplayer] ${text}`) });
     } catch (err) {
@@ -145,6 +171,21 @@ class MultiplayerSystem {
 
       // Pair simulation time with the page arrival time before filing samples.
       Clock.noteArrival(this.clock, msg.t, msg.localMs);
+      if (!this.joined && (msg.k === WORLD || (msg.ps ?? []).some((pose) => pose[0] === selfId))) {
+        this.joined = true;
+        console.log('[multiplayer] placed by the session');
+      }
+      for (const id of msg.gone ?? []) {
+        this.gone.add(id);
+      }
+
+      // The WORLD snapshot carries this player's own saved block. It goes back
+      // on `scene.persistent`, which is where the engine's Player behavior keeps
+      // the camera angle and score, before that behavior runs again.
+      if (msg.k === WORLD && msg.me) {
+        Object.assign((scene.persistent ??= {}), msg.me);
+        this.sentState = JSON.stringify(scene.persistent);
+      }
 
       // Apply ownership first so an object granted this tick stops receiving
       // network poses on the same frame local simulation begins.
@@ -152,9 +193,11 @@ class MultiplayerSystem {
       for (const [id, x, y, z, facing, clamped] of msg.ps ?? []) {
         if (id !== selfId) {
           sample(this.players, msg, id, [x, y, z, facing]);
-        } else if (clamped) {
-          // The local player's returned pose is used only when the server marks
-          // it clamped; ordinary local movement remains client-simulated.
+        } else if (clamped || msg.k === WORLD) {
+          // The local player's returned pose is used when the server marks it
+          // clamped, and on the WORLD snapshot that starts a session: that one
+          // carries where this player left off. Ordinary local movement remains
+          // client-simulated.
           this.clampedTo = { x, y, z };
         }
       }
@@ -219,6 +262,7 @@ class MultiplayerSystem {
       }
       Avatars.showPlayer(this.avatars, scene, playerId, look.username ?? null, pose, {
         blueprint: look.blueprint,
+        userId: this.net.userId(playerId),
       });
     }
     Avatars.dropMissing(this.avatars, scene, others);
@@ -300,8 +344,16 @@ class MultiplayerSystem {
 
     // `sendMove` only goes out at MOVE_HZ; claims are held until it does. The
     // transport takes a packed pose, so the Transform is encoded here.
-    this.net.sendMove(Poses.packMove(me), owned, claims, releases);
-    Avatars.showSelf(this.avatars, scene, this.net.status().you, me);
+    // The state block rides in a move packet when it changed since the last one
+    // that went out.
+    const stateJson = JSON.stringify(scene.persistent ?? {});
+    const state = stateJson === this.sentState ? undefined : (scene.persistent ?? {});
+    if (this.net.sendMove(Poses.packMove(me), owned, claims, releases, state) && state) {
+      this.sentState = stateJson;
+    }
+    Avatars.showSelf(this.avatars, scene, this.net.status().you, me, {
+      userId: this.net.userId(this.net.selfId()),
+    });
   }
 
   // Return `[id, Transform]` for every scene object known from server snapshots.
@@ -388,6 +440,56 @@ class MultiplayerSystem {
     this.own = Ownership.makeOwnership();
     this.shown = Smoothing.makeSmoothing();
     this.clampedTo = null;
+    this.seen = null;
+  }
+
+  //
+  // Actors removed for good
+  //
+
+  // Despawn every actor the session says is gone. Runs each frame, so a scene
+  // load that brings an actor back from the file loses it again at once.
+  applyGone(scene) {
+    for (const id of this.gone) {
+      if (scene.actors.has(id)) {
+        scene.despawnActor(id);
+      }
+    }
+  }
+
+  // Report actors a behavior despawned this frame (a collected pickup, say).
+  // Other players' avatars are the kit's own and are not reported. Nothing is
+  // reported before the session has placed this player.
+  reportGone(scene) {
+    const ids = new Set(scene.actors.keys());
+    if (this.seen && this.joined) {
+      const avatars = new Set(this.avatars.actors.values());
+      for (const id of this.seen) {
+        if (ids.has(id) || this.gone.has(id) || avatars.has(id)) {
+          continue;
+        }
+        this.gone.add(id);
+        this.net.send({ k: GONE, id });
+      }
+    }
+    this.seen = ids;
+  }
+
+  // Whether the overlay should be up: joining or connected, not solo, and not
+  // yet placed. A session that never answers releases it after JOIN_WAIT_MS so
+  // the deck is not stuck behind it.
+  joiningOverlayWanted() {
+    if (this.joined || this.net?.status().solo) {
+      return false;
+    }
+    if (this.joinStartedAt && performance.now() - this.joinStartedAt > JOIN_WAIT_MS) {
+      if (!this.joinWarned) {
+        this.joinWarned = true;
+        console.warn('[multiplayer] no snapshot from the session yet; playing unplaced');
+      }
+      return false;
+    }
+    return true;
   }
 
   // Release scene resources and leave the session when the engine runtime ends.
@@ -396,6 +498,9 @@ class MultiplayerSystem {
     this.reset(scene);
     this.net?.close();
     this.net = null;
+    this.joined = false;
+    this.joinStartedAt = 0;
+    showJoinOverlay(false);
     // The badge is a fixed element outside the scene, so a disposed runtime
     // (an editor preview closing, say) has to take it down explicitly.
     showSoloBadge(null);

package/kits/multiplayer-3d/package-lock.json

@@ -16,8 +16,10 @@
         "@dnd-kit/modifiers": "^9.0.0",
         "@dnd-kit/sortable": "^10.0.0",
         "@dnd-kit/utilities": "^3.2.2",
+        "@fortawesome/free-solid-svg-icons": "^5.15.4",
         "@lezer/highlight": "^1.2.3",
         "castle-web-fonts": "^1.0.0",
+        "castle-web-sdk": "file:../../sdk",
         "codemirror": "^6.0.2",
         "matter-js": "^0.20.0",
         "react": "^19.2.4",
@@ -30,7 +32,7 @@
     },
     "../../sdk": {
       "name": "castle-web-sdk",
-      "version": "0.4.26",
+      "version": "0.4.27",
       "dev": true,
       "devDependencies": {
         "eslint": "^9.0.0",
@@ -208,6 +210,29 @@
         "react": ">=16.8.0"
       }
     },
+    "node_modules/@fortawesome/fontawesome-common-types": {
+      "version": "0.2.36",
+      "resolved": "https://registry.npmjs.org/@fortawesome/fontawesome-common-types/-/fontawesome-common-types-0.2.36.tgz",
+      "integrity": "sha512-a/7BiSgobHAgBWeN7N0w+lAhInrGxksn13uK7231n2m8EDPE3BMCl9NZLTGrj9ZXfCmC6LM0QLqXidIizVQ6yg==",
+      "hasInstallScript": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/@fortawesome/free-solid-svg-icons": {
+      "version": "5.15.4",
+      "resolved": "https://registry.npmjs.org/@fortawesome/free-solid-svg-icons/-/free-solid-svg-icons-5.15.4.tgz",
+      "integrity": "sha512-JLmQfz6tdtwxoihXLg6lT78BorrFyCf59SAwBM6qV/0zXyVeDygJVb3fk+j5Qat+Yvcxp1buLTY5iDh1ZSAQ8w==",
+      "hasInstallScript": true,
+      "license": "(CC-BY-4.0 AND MIT)",
+      "dependencies": {
+        "@fortawesome/fontawesome-common-types": "^0.2.36"
+      },
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/@lezer/common": {
       "version": "1.5.2",
       "resolved": "https://registry.npmjs.org/@lezer/common/-/common-1.5.2.tgz",

package/kits/multiplayer-3d/package.json

@@ -17,8 +17,10 @@
     "@dnd-kit/modifiers": "^9.0.0",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
+    "@fortawesome/free-solid-svg-icons": "^5.15.4",
     "@lezer/highlight": "^1.2.3",
     "castle-web-fonts": "^1.0.0",
+    "castle-web-sdk": "file:../../sdk",
     "codemirror": "^6.0.2",
     "matter-js": "^0.20.0",
     "react": "^19.2.4",

package/kits/physics-2d/castle.json

@@ -72,7 +72,7 @@
   "main": "main.jsx",
   "autoUpdateWhenImported": true,
   "title": "physics-2d",
-  "publishedVersion": "2026-09-10T00:57:31.408Z",
+  "publishedVersion": "2026-09-10T20:28:41.310Z",
   "imports": {
     "castle.base": {
       "deckId": "yRcmH4_aYllE",

package/kits/physics-2d/editors/PxArtEditor.jsx

@@ -419,7 +419,7 @@ export function PxArtEditor({ path, text, onChange, files, readOnly = false, ...
   const artboardCanvasStyle = canvasSize ?? canvasStyle;
   // `canvasStyle`'s width is the artboard's CURRENT display size (recomputed
   // by useArtboardFit's own ResizeObserver whenever the wrap resizes — e.g. a
-  // dockview panel drag). Feeding it in here is what keeps the supersampled
+  // panel resize). Feeding it in here is what keeps the supersampled
   // canvas's resolution in sync with that display size: without it, this
   // effect has no way to know the wrap resized (nothing about `text`,
   // `frameIndex`, or `cornerRadius` changes on a pure container resize), so
@@ -2458,7 +2458,7 @@ function useArtboardRender(canvasRef, text, sprite, previewIndex, onion, playing
 // the `sprite` object (a fresh object every render) so it only redraws on an
 // actual content/frame/radius change, not on every hover-driven re-render of
 // the tool preview — PLUS `displayWidth` (the artboard's current CSS width
-// from useArtboardFit), so a wrap resize (e.g. a dockview panel drag) also
+// from useArtboardFit), so a wrap resize (e.g. a panel drag) also
 // triggers a re-render at the new supersample scale, not just a content
 // change. The supersample factor auto-fits to the displayed size (capped
 // between 4x and 16x).

package/kits/physics-2d/engine/avatarArt.js

@@ -0,0 +1,91 @@
+// A player's round avatar for drawing in a scene: the photo clipped to a circle
+// with their frame over it, as a canvas. Read through `User.get` once per user
+// id and kept for the page. A player with no photo has no avatar, and a caller
+// keeps its default look.
+//
+// `avatarCanvas` is for code that draws with a canvas context, like a name tag.
+// `avatarSpritePath` registers the same picture as image art in `scene.sprites`,
+// so a `Sprite` component can show it by file path.
+
+import { User } from 'castle-web-sdk';
+import { imageArt } from './art';
+
+const SIZE = 128;
+
+// A frame is drawn around a photo two thirds its size, the proportion Castle's
+// own profile views use.
+const FRAMED_INSET = SIZE / 6;
+
+// userId -> { canvas }, present from the first ask; `canvas` fills in when the
+// read completes.
+const avatars = new Map();
+
+// The avatar for one user id, or null until it is loaded or when there is none.
+export function avatarCanvas(userId) {
+  if (!userId) {
+    return null;
+  }
+  let entry = avatars.get(userId);
+  if (!entry) {
+    entry = { canvas: null };
+    avatars.set(userId, entry);
+    void load(userId, entry);
+  }
+  return entry.canvas;
+}
+
+// The `scene.sprites` path holding this user's avatar, or null while there is
+// none. A `Sprite` with this `file` draws it.
+export function avatarSpritePath(scene, userId) {
+  const canvas = avatarCanvas(userId);
+  if (!canvas) {
+    return null;
+  }
+  const path = `avatars/${userId}.png`;
+  if (!scene.sprites[path]) {
+    scene.sprites[path] = imageArt(path, canvas.toDataURL());
+  }
+  return path;
+}
+
+async function load(userId, entry) {
+  try {
+    const user = await User.get(userId);
+    const [photo, frame] = await Promise.all([loadImage(user?.photoUrl), loadImage(user?.frameUrl)]);
+    if (photo) {
+      entry.canvas = compose(photo, frame);
+    }
+  } catch {
+    // A failed read leaves the entry without a canvas; the next page asks again.
+  }
+}
+
+function loadImage(url) {
+  if (!url) {
+    return Promise.resolve(null);
+  }
+  return new Promise((resolve) => {
+    const image = new Image();
+    image.onload = () => resolve(image);
+    image.onerror = () => resolve(null);
+    image.src = url;
+  });
+}
+
+function compose(photo, frame) {
+  const canvas = document.createElement('canvas');
+  canvas.width = SIZE;
+  canvas.height = SIZE;
+  const ctx = canvas.getContext('2d');
+  const inset = frame ? FRAMED_INSET : 0;
+  ctx.save();
+  ctx.beginPath();
+  ctx.arc(SIZE / 2, SIZE / 2, SIZE / 2 - inset, 0, Math.PI * 2);
+  ctx.clip();
+  ctx.drawImage(photo, inset, inset, SIZE - 2 * inset, SIZE - 2 * inset);
+  ctx.restore();
+  if (frame) {
+    ctx.drawImage(frame, 0, 0, SIZE, SIZE);
+  }
+  return canvas;
+}

package/kits/physics-3d/behaviors/Pickup.jsx

@@ -4,7 +4,9 @@
 //
 // Collection is remembered in the persistent store keyed by scene + actor id,
 // so re-entering a scene doesn't respawn (and double-count) shards
-// -- scene loads otherwise reset the world to its authored state.
+// -- scene loads otherwise reset the world to its authored state. The store is
+// a plain object, not a Set: `scene.persistent` has to survive JSON, since a
+// multiplayer kit saves it per player.
 function pickupKey(scene, actor) {
   return `${scene.currentScenePath ?? ''}:${actor.id}`;
 }
@@ -18,7 +20,7 @@ export class Pickup {
   }
 
   update(actor, scene, dt) {
-    if (scene.persistent?.collected?.has(pickupKey(scene, actor))) {
+    if (scene.persistent?.collected?.[pickupKey(scene, actor)]) {
       scene.despawnActor(actor.id);
       return;
     }
@@ -33,7 +35,7 @@ export class Pickup {
     if (!other.components.Player) return;
     const per = (scene.persistent ??= {});
     per.score = (per.score ?? 0) + 1;
-    (per.collected ??= new Set()).add(pickupKey(scene, actor));
+    (per.collected ??= {})[pickupKey(scene, actor)] = true;
     scene.despawnActor(actor.id);
   }
 }

package/kits/physics-3d/castle.json

@@ -69,5 +69,5 @@
   "autoUpdateWhenImported": true,
   "deckId": "JH0SclbPVP0y",
   "cardId": "eXfAaUdbSU5A",
-  "publishedVersion": "2026-09-10T00:57:52.158Z"
+  "publishedVersion": "2026-09-10T20:10:28.916Z"
 }

package/kits/real-time/CLAUDE.md

@@ -20,6 +20,16 @@ imports these modules from here directly.
 - **A deck normally writes nothing against it.** The multiplayer kit it came with
   already drives all of this; a deck's own code goes in `code/server/game.js` and
   `code/client/game.js`, which that kit documents.
+- **What persists.** Object poses, the ids of scene actors a client despawned,
+  each player's last pose and state block by account, and whatever the optional
+  `save(sim)` hook returns. Written every ten seconds when something moved and
+  at a clean shutdown. Nothing to configure.
+- **A returning player starts where they left off.** A second connection from
+  the same account while the first is still playing gets a new character at the
+  spawn. The room is `session.sessionId`; every `public` shard shares one.
+- `restore(sim, saved)` receives the last `save` result before `ready`. Storage
+  is keyed by deck, so the deck must be published; `castle-web serve` brokers it
+  as the deck's creator.
 - A pose is an opaque array of numbers here, so anything reading inside one takes
   the kit's `code/client/poses.js` as an argument. That is the seam to use when
   something genuinely needs a lower level.
@@ -59,10 +69,19 @@ never learns the format.
 values of a player pose are geometry before the `clamped` flag, and `epsilonAt`,
 which a kit whose pose values are all one unit leaves undefined.
 
-`soloBadge.js` is the one file here that touches the DOM: a fixed badge that
-names why a session fell back to solo (`status().soloReason` from
-`connection.js`), drawn by both kits each frame through `updateSoloBadge`. It
-stays dependency-free and hides itself when a deck's `soloBadge` hook says so.
+Persistence adds to that contract: `world.restorePoses(sim, poses)` puts saved
+poses back on the bodies the scene still has, and `players.addPlayer` takes the
+saved pose a returning player starts from. Optional beside those:
+`world.removeActor(sim, id)` drops a despawned actor's body, and
+`players.setState` / `players.stateOf` keep the block a client reports.
+
+Two files here touch the DOM, both dependency-free. `soloBadge.js` is a fixed
+badge that names why a session fell back to solo (`status().soloReason` from
+`connection.js`), drawn by both kits each frame through `updateSoloBadge`; a
+deck's `soloBadge` hook hides it. `joinOverlay.js` covers the card with
+"Joining…" from the first frame until the session's first snapshot places the
+player, so nobody plays from the scene's spawn before the saved spot arrives;
+it gives up after ten seconds with a console warning.
 
 ## Rules for editing this kit
 

package/kits/real-time/castle.json

@@ -15,5 +15,5 @@
   "autoUpdateWhenImported": true,
   "deckId": "xFVr-afOLuUQ",
   "cardId": "w6G45sy3_P_m",
-  "publishedVersion": "2026-09-05T01:31:28.578Z"
+  "publishedVersion": "2026-09-10T20:28:42.134Z"
 }

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

@@ -12,6 +12,7 @@ const SEND_MS = 1000 / Messages.MOVE_HZ;
 //   connection  the SDK connection
 //   inbox       arrived messages, each with `localMs` added
 //   roster      playerId -> username, as the platform last reported it
+//   userIds     playerId -> userId, from the same roster
 //   you         the SDK's entry for the local player, null until a roster has it
 //   sentAt      `performance.now()` of the last move, so sends stay at MOVE_HZ
 //   claims      ids asked for since the last send, held until it goes
@@ -21,6 +22,7 @@ function makeNet(connection) {
     connection,
     inbox: [],
     roster: new Map(),
+    userIds: new Map(),
     you: null,
     sentAt: 0,
     claims: new Set(),
@@ -48,6 +50,7 @@ export async function connectSession({ onLog = () => {} } = {}) {
 
     // Replace the map from the complete SDK roster so departures disappear.
     net.roster = new Map(players.map((player) => [player.playerId, player.username]));
+    net.userIds = new Map(players.map((player) => [player.playerId, player.userId]));
     net.you = you;
   });
 
@@ -61,6 +64,9 @@ export async function connectSession({ onLog = () => {} } = {}) {
     // A stable fallback until the SDK roster includes this player.
     username: (playerId) => net.roster.get(playerId) ?? 'player',
 
+    // The account behind a player, for `User.get`; null until the roster has it.
+    userId: (playerId) => net.userIds.get(playerId) ?? null,
+
     // Every other player's roster entry. The local player is simulated by this client,
     // so the deck draws only these from network samples.
     others: () => new Map([...net.roster].filter(([id]) => id !== connection.playerId)),
@@ -81,7 +87,8 @@ export async function connectSession({ onLog = () => {} } = {}) {
     // the transport handles every dimensional format in the same way.
     // The client system calls this every frame; most calls only accumulate the
     // ownership requests, which are held until the next rate-limited send.
-    sendMove: (pose, owned, claims, releases) => sendMove(net, pose, owned, claims, releases),
+    sendMove: (pose, owned, claims, releases, state) =>
+      sendMove(net, pose, owned, claims, releases, state),
 
     // Send deck-specific data. The server routes these to `code/server/game.js`.
     send: (data) => net.connection.send(data),
@@ -106,8 +113,10 @@ export async function connectSession({ onLog = () => {} } = {}) {
   };
 }
 
-// Collect ownership requests from every frame and send at `MOVE_HZ`.
-function sendMove(net, pose, owned, claims, releases) {
+// Collect ownership requests from every frame and send at `MOVE_HZ`. `state` is
+// the player's own block, sent along when the caller has one to send. Returns
+// whether a packet went out.
+function sendMove(net, pose, owned, claims, releases, state) {
   // Gathered on every frame, including the ones that send nothing, so a claim
   // made in between is still in the next message. The sets also collapse
   // repeated requests for the same object over that interval.
@@ -119,7 +128,7 @@ function sendMove(net, pose, owned, claims, releases) {
   }
   const now = performance.now();
   if (now - net.sentAt < SEND_MS) {
-    return;
+    return false;
   }
   net.sentAt = now;
 
@@ -130,9 +139,11 @@ function sendMove(net, pose, owned, claims, releases) {
     c: [...net.claims],
     r: [...net.releases],
     o: owned,
+    ...(state === undefined ? {} : { s: state }),
   });
 
   // Clear only after a packet; rate-limited returns above retain the requests.
   net.claims.clear();
   net.releases.clear();
+  return true;
 }

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

@@ -0,0 +1,46 @@
+// A full-card overlay shown from connecting until the server's first snapshot
+// places this player. Under it the local character may still be standing at the
+// scene's spawn; the overlay hides that and takes the pointer, so nothing is
+// played until the session says where things are.
+//
+// It mounts inside the card when the sdk has marked one, so a capture of the
+// card (a cover, a playtest frame) includes it; otherwise it covers the page.
+//
+// Dependency-free DOM, like the solo badge: the kits draw their scenes
+// differently and share no HUD.
+
+let element = null;
+
+// Show or hide the overlay. Idempotent; cheap enough to call every frame.
+export function showJoinOverlay(visible) {
+  if (typeof document === 'undefined') {
+    return;
+  }
+  if (!visible) {
+    element?.remove();
+    element = null;
+    return;
+  }
+  if (element) {
+    return;
+  }
+  const card = document.querySelector('#castle-card, [data-castle-card]');
+  if (card && getComputedStyle(card).position === 'static') {
+    card.style.position = 'relative';
+  }
+  element = document.createElement('div');
+  element.setAttribute('data-castle-join-overlay', '');
+  element.style.cssText = [
+    card ? 'position:absolute' : 'position:fixed',
+    'inset:0',
+    'display:flex',
+    'align-items:center',
+    'justify-content:center',
+    'background:#0a0a0a',
+    'color:#fff',
+    'font:500 15px/1.4 system-ui,sans-serif',
+    'z-index:2147483646',
+  ].join(';');
+  element.textContent = 'Joining…';
+  (card ?? document.body).appendChild(element);
+}

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`