castle-web-cli 0.4.170 → 0.4.171

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

@@ -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:09:53.271Z",
   "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-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:10:30.302Z"
 }

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

@@ -81,7 +81,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 +107,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 +122,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 +133,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);
+}