castle-web-cli 0.4.169 → 0.4.171

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

@@ -14,26 +14,26 @@
   "imports": {
     "castle.real-time": {
       "deckId": "xFVr-afOLuUQ",
-      "version": "2026-09-05T01:31:28.578Z"
+      "version": "2026-09-10T19:46:34.652Z"
     },
     "castle.physics-3d": {
       "deckId": "JH0SclbPVP0y",
-      "version": "2026-09-01T01:02:48.784Z"
+      "version": "2026-09-10T19:46:37.323Z"
     },
     "castle.physics-2d": {
       "deckId": "ckRZGFW4iPrx",
-      "version": "2026-09-01T01:02:46.041Z",
+      "version": "2026-09-10T00:57:31.408Z",
       "via": "castle.physics-3d"
     },
     "castle.base": {
       "deckId": "yRcmH4_aYllE",
-      "version": "2026-09-05T01:31:11.287Z"
+      "version": "2026-09-10T00:56:59.388Z"
     }
   },
   "autoUpdateWhenImported": true,
   "deckId": "ZwA_P_-VO-Qh",
   "cardId": "bvRmCzyUpt_a",
-  "publishedVersion": "2026-09-05T01:32:53.625Z",
+  "publishedVersion": "2026-09-10T20:10:41.318Z",
   "main": "main.jsx",
   "server": {
     "main": "code/server/index.js",

package/kits/multiplayer-3d/code/server/players.js

@@ -7,6 +7,9 @@ import { earned, number } from '@imports/castle.real-time/code/server/limits.js'
 import * as Limits from './limits.js';
 import { createBody } from './world.js';
 
+// The largest state block a client may report, as JSON text.
+const STATE_BYTES = 4096;
+
 // An entry in `sim.players`:
 //
 //   body     the kinematic capsule in the rapier world
@@ -14,18 +17,26 @@ import { createBody } from './world.js';
 //   facing   radians, as the client sent them
 //   clamped  true only on the tick a move was refused
 //   movedAt  simulation time of that acceptance
-function newPlayer(body, at) {
-  return { body, at, facing: 0, clamped: false, movedAt: 0 };
+//   settled  whether this connection has ever reported a pose the server took
+//   state    the block the client last reported: the engine's `scene.persistent`
+//            (score, camera angle, collected pickups). Saved with the pose and
+//            handed back on rejoin. The server never reads inside it.
+function newPlayer(body, at, movedAt) {
+  return { body, at, facing: 0, clamped: false, movedAt, settled: false, state: null };
 }
 
 // Add a kinematic capsule for a session player. `world.step` places it at
 // `player.at` before physics; zero friction prevents a capsule leaning against a
 // wall from remaining attached to it.
-export function addPlayer(sim, playerId) {
+//
+// `pose` is where a returning player left off, as `[x, y, z, facing]`. Without
+// one the capsule starts on the spawn ring.
+export function addPlayer(sim, playerId, pose) {
   // The shape comes off the scene's own player actor, so the server collides
   // with the same body the browser draws. The default is a person-sized capsule.
   const shape = sim.template?.shape ?? { kind: 'capsule', radius: 0.35, height: 1.4 };
-  const at = spawnPoint(sim);
+  const resumed = pose ? Limits.readPoint(pose) : null;
+  const at = resumed ?? spawnPoint(sim);
   const body = createBody(
     sim,
     { components: { Solid: {} } },
@@ -33,7 +44,15 @@ export function addPlayer(sim, playerId) {
     shape,
     { type: 'kinematic', friction: 0 },
   );
-  sim.players.set(playerId, newPlayer(body, at));
+
+  // The movement allowance runs from now. A body that starts where a player left
+  // off would otherwise let that player's first report cover half a second of
+  // travel back to wherever their own copy of the scene put them.
+  const player = newPlayer(body, at, sim.timeMs);
+  if (resumed) {
+    player.facing = number(pose[3]);
+  }
+  sim.players.set(playerId, player);
 }
 
 // Remove a departing player's Rapier body and simulation entry.
@@ -64,6 +83,9 @@ export function setPose(sim, playerId, message) {
   // changes the rendered model orientation and has no effect on the upright
   // capsule's movement or collision shape.
   player.facing = number(message?.p?.[3]);
+  if (message?.s !== undefined) {
+    setState(sim, playerId, message.s);
+  }
 
   // Combine elapsed-time movement allowance with fixed delivery slack.
   const reach = Limits.MAX_SPEED * earned(sim, player.movedAt) + Limits.MOVE_SLACK;
@@ -77,6 +99,15 @@ export function setPose(sim, playerId, message) {
   if (distance <= reach) {
     player.at = asked;
     player.clamped = false;
+    player.settled = true;
+    return;
+  }
+
+  // The first report moves nothing. A client starts its own body from the scene
+  // and does not know yet where the session put this player, so the server
+  // position stands until the client has agreed with it once.
+  if (!player.settled) {
+    player.clamped = true;
     return;
   }
 
@@ -92,6 +123,24 @@ export function setPose(sim, playerId, message) {
   player.clamped = true;
 }
 
+// Keep a player's state block. Only a plain object under `STATE_BYTES` of JSON
+// is kept; anything else leaves the block as it was.
+export function setState(sim, playerId, state) {
+  const player = sim.players.get(playerId);
+  if (!player || typeof state !== 'object' || Array.isArray(state)) {
+    return;
+  }
+  if (state !== null && JSON.stringify(state).length > STATE_BYTES) {
+    return;
+  }
+  player.state = state;
+}
+
+// A player's state block, or null.
+export function stateOf(sim, playerId) {
+  return sim.players.get(playerId)?.state ?? null;
+}
+
 // Pack current Rapier body poses for a WORLD or STATE message. Physics contacts
 // can make the body position differ from the last accepted target in `player.at`.
 export function playerPoses(sim) {

package/kits/multiplayer-3d/code/server/world.js

@@ -4,7 +4,12 @@
 
 import RAPIER from '@dimforge/rapier3d-compat';
 import { packPose } from '../client/poses.js';
-import { MAX_STEPS_PER_TICK, STEP, clamp } from '@imports/castle.real-time/code/server/limits.js';
+import {
+  MAX_STEPS_PER_TICK,
+  STEP,
+  clamp,
+  number,
+} from '@imports/castle.real-time/code/server/limits.js';
 import { readScene } from './sceneBodies.js';
 import * as Limits from './limits.js';
 
@@ -13,6 +18,7 @@ const DEG = Math.PI / 180;
 // The simulation every hook is handed as `sim`:
 //
 //   world      the rapier world
+//   bodies     actor id -> rapier body, for every scene actor with a shape
 //   objects    actor id -> { body, home, claimable, fast, owner, reportedAt,
 //              claimedAt }
 //   doors      [{ body, props, baseY, openT }]
@@ -27,6 +33,7 @@ function emptySim() {
   return {
     world: new RAPIER.World({ x: 0, y: -9.81, z: 0 }),
     objects: new Map(),
+    bodies: new Map(),
     doors: [],
     players: new Map(),
     spawn: { x: 0, y: 1, z: 0 },
@@ -76,6 +83,7 @@ function buildScene(sim) {
       continue;
     }
     const rb = createBody(sim, actor, t, shape, body);
+    sim.bodies.set(actor.id, rb);
     if (door) {
       sim.doors.push({ body: rb, props: door, baseY: t.y, openT: 0 });
     }
@@ -102,6 +110,19 @@ function buildScene(sim) {
   }
 }
 
+// Take a scene actor out of the simulation for good. An id with no body here
+// (a gem, say, that the engine handles as a sensor) is a no-op.
+export function removeActor(sim, id) {
+  const rb = sim.bodies.get(id);
+  if (!rb) {
+    return;
+  }
+  sim.world.removeRigidBody(rb);
+  sim.bodies.delete(id);
+  sim.objects.delete(id);
+  sim.doors = sim.doors.filter((door) => door.body !== rb);
+}
+
 // Create one Rapier body and collider from engine component data. These mappings
 // mirror the engine's `bodyDescFor` and `colliderDescFor`, so server and browser
 // worlds use the same body type, material values, shape, and sensor state.
@@ -289,6 +310,29 @@ export function objectPoses(sim) {
   return out;
 }
 
+// Put saved poses back on the bodies they were read from. An id the scene no
+// longer has is skipped. Velocities are cleared: a restored body starts at rest.
+// Returns how many poses were applied.
+export function restorePoses(sim, poses) {
+  let applied = 0;
+  for (const pose of poses) {
+    const entry = sim.objects.get(pose?.[0]);
+    const at = entry ? Limits.readPoint(pose.slice(1)) : null;
+    if (!at) {
+      continue;
+    }
+    entry.body.setTranslation(at, true);
+    entry.body.setRotation(
+      { x: number(pose[4]), y: number(pose[5]), z: number(pose[6]), w: number(pose[7]) },
+      true,
+    );
+    entry.body.setLinvel({ x: 0, y: 0, z: 0 }, true);
+    entry.body.setAngvel({ x: 0, y: 0, z: 0 }, true);
+    applied += 1;
+  }
+  return applied;
+}
+
 // Convert the engine Transform's degree Euler angles to a Rapier quaternion.
 function quatFromEuler(t) {
   const cx = Math.cos((t.rotationX ?? 0) * DEG * 0.5);

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 };
         }
       }
@@ -300,7 +343,13 @@ 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);
+    // 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);
   }
 
@@ -388,6 +437,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 +495,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

@@ -19,6 +19,7 @@
         "@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",
@@ -31,7 +32,7 @@
     },
     "../../sdk": {
       "name": "castle-web-sdk",
-      "version": "0.4.26",
+      "version": "0.4.27",
       "dev": true,
       "devDependencies": {
         "eslint": "^9.0.0",
@@ -159,7 +160,6 @@
       "resolved": "https://registry.npmjs.org/@dnd-kit/core/-/core-6.3.1.tgz",
       "integrity": "sha512-xkGBRQQab4RLwgXxoqETICr6S5JlogafbhNsidmrkVv2YRs5MLwpjoF2qpiGjQt8S9AoxtIV603s0GIUpY5eYQ==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@dnd-kit/accessibility": "^3.1.1",
         "@dnd-kit/utilities": "^3.2.2",
@@ -316,7 +316,6 @@
       "resolved": "https://registry.npmjs.org/react/-/react-19.2.8.tgz",
       "integrity": "sha512-PWaYA1L/q9u2u7xYQi+Y3L3Yfnie7XyLeaJICV1MGD6LprsBxcAqGjYyr0eY3p+QdsA+x/Irkt4Qif8D63+Sbw==",
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=0.10.0"
       }
@@ -326,7 +325,6 @@
       "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.2.8.tgz",
       "integrity": "sha512-rVprimfGBG3DR+Tq0IQG2DT5PxKth1WIGDmj5yPmlzr4YBe7uyE+Du4oVqTDXZSHGGGXRtTJEGSSePyQCMBglQ==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "scheduler": "^0.27.0"
       },

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

@@ -20,6 +20,7 @@
     "@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",