castle-web-cli 0.4.170 → 0.4.172

package/kits/multiplayer-3d/CLAUDE.md

@@ -51,10 +51,31 @@ File names stay lowercase.
   builds a rapier world from the deck's own `scenes/main.scene` and steps it at
   `tickRate` (30). Never fork it.
 - **A game is added as hooks, not by replacing anything.** Write
-  `code/server/game.js` with a default export of up to six functions --
+  `code/server/game.js` with a default export of up to six gameplay functions --
   `ready(sim)`, `message(session, player, data)`, `place(sim, handovers)`,
   `step(sim, handovers)`, `join(sim)`, `delta(sim)` -- and it is found by glob.
   Optional, as is `code/server/deckComponents.js` for component defaults.
+- **What persists.** Object poses, the ids of despawned scene actors, each
+  player's last pose and `scene.persistent` 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 despawn is for everyone.** The client system reports a scene actor a
+  behavior despawned (a collected pickup); the session removes it for every
+  player, now and on every later visit.
+- **`scene.persistent` must stay JSON** -- no Sets, no actors. It rides in the
+  move report when it changes, capped at 4 KB, and comes back in the WORLD
+  snapshot before the Player behavior runs, which is how the camera angle and
+  score return.
+- **Players wear their Castle avatar.** The name tag over every player,
+  the local one included, carries their profile photo and frame
+  (`castle.physics-2d`'s `engine/avatarArt.js`, through `User.get`). A player
+  with no photo gets the name alone.
+- **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.
 - `place` runs BEFORE the physics step, which is where a write through a deferred
   channel (`player.at`, `setNextKinematicTranslation`) has to happen to reach the
   body this tick. `message` is dispatched before the world exists, so a lobby
@@ -78,8 +99,9 @@ File names stay lowercase.
 - The kit ships `code/systems/multiplayer.js`, the frame loop. A deck that writes
   its own file of that path gets its own instead; most decks should not.
 - Two players is the test that matters: `castle-web serve`, then the play URL in
-  two tabs. The session process holds the room, so restart the serve for a fresh
-  one.
+  two tabs. The room persists in deck storage across serve restarts; a fresh one
+  means removing its `world:<room>`, `game:<room>` and `player:<room>:*` rows
+  (the local serve's room is `dev`).
 
 ## Layout
 
@@ -238,12 +260,13 @@ Map())` — and the next `showPlayer` respawns it.
 - **The player blueprint itself.** The kit spawns a scene from the deck's own
   root; the deck ships it. `blueprints/other-player.scene` is only the name it
   looks for when the deck names none.
-- **Any HUD.** Five decks wrote five HUDs with no shared lines. The one
-  on-screen element the kit does draw is the solo badge
-  (`castle.real-time`'s `soloBadge.js`): when the join fell back to solo it
-  names why (`status().soloReason`), so a creator testing a private or
-  unpublished deck is told rather than left to guess. A deck's
-  `soloBadge(status)` client hook hides or rewords it.
+- **Any HUD.** Five decks wrote five HUDs with no shared lines. The kit draws
+  two on-screen elements, both `castle.real-time`'s: the solo badge
+  (`soloBadge.js`) names why a join fell back to solo (`status().soloReason`),
+  so a creator testing a private or unpublished deck is told rather than left
+  to guess -- a deck's `soloBadge(status)` client hook hides or rewords it; and
+  the join overlay (`joinOverlay.js`) covers the card with "Joining…" until the
+  session's first snapshot places the player, ten seconds at most.
 - **Gameplay verbs** — carry, vehicle, round, lobby. Measured across six decks
   and none of them survived contact; see the audit.
 

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

@@ -14,15 +14,15 @@
   "imports": {
     "castle.real-time": {
       "deckId": "xFVr-afOLuUQ",
-      "version": "2026-09-05T01:31:28.578Z"
+      "version": "2026-09-10T20:27:27.032Z"
     },
     "castle.physics-3d": {
       "deckId": "JH0SclbPVP0y",
-      "version": "2026-09-10T00:57:52.158Z"
+      "version": "2026-09-10T19:46:37.323Z"
     },
     "castle.physics-2d": {
       "deckId": "ckRZGFW4iPrx",
-      "version": "2026-09-10T00:57:31.408Z",
+      "version": "2026-09-10T20:21:12.665Z",
       "via": "castle.physics-3d"
     },
     "castle.base": {
@@ -33,7 +33,7 @@
   "autoUpdateWhenImported": true,
   "deckId": "ZwA_P_-VO-Qh",
   "cardId": "bvRmCzyUpt_a",
-  "publishedVersion": "2026-09-10T00:58:16.876Z",
+  "publishedVersion": "2026-09-10T20:28:53.356Z",
   "main": "main.jsx",
   "server": {
     "main": "code/server/index.js",

package/kits/multiplayer-3d/code/client/avatars.js

@@ -4,6 +4,7 @@
 
 import * as NameTags from './nameTags.js';
 import { applyPose } from './poses.js';
+import { avatarCanvas } from '@imports/castle.physics-2d/engine/avatarArt.js';
 
 // The blueprint spawned when a caller names none. A deck's own file wins; a deck
 // scaffolded from this kit has no blueprints yet, so the kit's copy stands in
@@ -33,7 +34,8 @@ export function makeAvatars() {
 //
 // A `username` of null draws no label. Options are `blueprint`, the scene to
 // spawn from (default `blueprints/other-player.scene`, the deck's own or the kit's),
-// and `tagHeight`, how far over the body the label floats.
+// `tagHeight`, how far over the body the label floats, and `userId`, whose
+// avatar the label carries.
 export function showPlayer(avatars, scene, playerId, username, pose, options = {}) {
   // The actor keeps the blueprint used at creation; `ensureActor` only spawns
   // when this player has no live actor in the current scene.
@@ -46,19 +48,20 @@ export function showPlayer(avatars, scene, playerId, username, pose, options = {
   if (username === null) {
     dropTag(avatars, scene, playerId);
   } else {
-    showTag(avatars, scene, playerId, username, transform, options.tagHeight);
+    showTag(avatars, scene, playerId, username, transform, options);
   }
   return actor;
 }
 
 // Update the local player's label over the engine's local Player actor. The SDK
 // roster can arrive several frames after connection, so an empty username
-// leaves the label absent until the roster supplies one.
-export function showSelf(avatars, scene, username, transform, tagHeight) {
+// leaves the label absent until the roster supplies one. Options are
+// `tagHeight` and `userId`, as for `showPlayer`.
+export function showSelf(avatars, scene, username, transform, options = {}) {
   if (!username) {
     return;
   }
-  showTag(avatars, scene, 'self', username, transform, tagHeight);
+  showTag(avatars, scene, 'self', username, transform, options);
 }
 
 // Despawn the actor and dispose the tag of every player absent from `present`.
@@ -106,20 +109,21 @@ function ensureActor(avatars, scene, playerId, pose, blueprint) {
   return spawned;
 }
 
-// Create a tag when the displayed text changes, then place it over the actor.
-// Each redraw allocates a canvas, texture, and sprite, so unchanged text reuses
-// the existing resources.
-function showTag(avatars, scene, key, username, transform, tagHeight) {
+// Create a tag when the displayed text or the avatar changes, then place it over
+// the actor. Each redraw allocates a canvas, texture, and sprite, so an unchanged
+// tag reuses the existing resources.
+function showTag(avatars, scene, key, username, transform, { tagHeight, userId } = {}) {
   const label = NameTags.shortName(username);
+  const avatar = avatarCanvas(userId);
   let tag = avatars.tags.get(key);
 
   // Compare against the shortened text stored on the tag. An
   // `anonymous-user-<uuid>` differs from the `anon-xxxxxx` string on the sprite.
-  if (!tag || tag.text !== label) {
+  if (!tag || tag.text !== label || tag.avatar !== avatar) {
     if (tag) {
       NameTags.disposeNameTag(scene.three, tag);
     }
-    tag = NameTags.makeNameTag(scene.three, label);
+    tag = NameTags.makeNameTag(scene.three, label, avatar);
     avatars.tags.set(key, tag);
   }
 

package/kits/multiplayer-3d/code/client/nameTags.js

@@ -1,6 +1,8 @@
-// Floating username-label sprites for other players and the local player. This module
-// draws text to a canvas, attaches the resulting sprite directly to the engine's
-// three.js scene, scales it by camera distance, and disposes its GPU resources.
+// Floating name tags for other players and the local player: the player's round
+// avatar over their username. This module draws them to a canvas, attaches the
+// resulting sprite directly to the engine's three.js scene, scales it by camera
+// distance, and disposes its GPU resources. A sprite always faces the camera,
+// so the avatar reads from every side.
 
 import * as THREE from 'three';
 
@@ -8,6 +10,11 @@ import * as THREE from 'three';
 const HEIGHT_ABOVE = 1.25;
 const PIXELS_PER_UNIT = 200;
 
+// Canvas pixels of the name pill, and of the avatar drawn above it.
+const LABEL_PX = 68;
+const AVATAR_PX = 112;
+const GAP_PX = 8;
+
 // The distance at which the label is the size it was drawn to be: 68 canvas
 // pixels over 200 per unit is 0.34m, which on a 500x700 card at fov 55 is 29px.
 // This reference distance matches the common camera placement in kit decks.
@@ -16,11 +23,12 @@ const SAME_SIZE_M = 8;
 // The minimum scale keeps a label readable when the camera is near the player.
 const MIN_SCALE = 0.35;
 
-// Create `{ sprite, text, width, height }` and add the sprite to the engine's
-// three.js scene. The engine actor-to-mesh sync does not update these directly
-// attached sprites, so callers move them each frame with `moveNameTag`.
-export function makeNameTag(world, text) {
-  const canvas = drawLabel(text);
+// Create `{ sprite, text, avatar, width, height, lift }` and add the sprite to
+// the engine's three.js scene. `avatar` is the canvas from `avatarArt.js`, or
+// null for a name alone. The engine actor-to-mesh sync does not update these
+// directly attached sprites, so callers move them each frame with `moveNameTag`.
+export function makeNameTag(world, text, avatar = null) {
+  const canvas = drawLabel(text, avatar);
   const texture = new THREE.CanvasTexture(canvas);
   texture.colorSpace = THREE.SRGBColorSpace;
   const sprite = new THREE.Sprite(
@@ -41,8 +49,11 @@ export function makeNameTag(world, text) {
   world.scene.add(sprite);
 
   // `text` is the string actually drawn, not the username it came from. The
-  // caller compares against it to decide whether a name changed.
-  return { sprite, text, width, height };
+  // caller compares against it, and against `avatar`, to decide whether to
+  // redraw. `lift` raises the sprite's centre so the name pill stays at
+  // `heightAbove` when an avatar is stacked over it.
+  const lift = (height - LABEL_PX / PIXELS_PER_UNIT) / 2;
+  return { sprite, text, avatar, width, height, lift };
 }
 
 // Move and scale a tag after its player pose is drawn for the current frame.
@@ -61,6 +72,7 @@ export function moveNameTag(tag, transform, camera, heightAbove = HEIGHT_ABOVE)
   // 0.8m 286px -> 100, 2m 114px -> 40, 4m 57px -> 29, 8m 29px -> 29, 20m 11 -> 11.
   const scale = Math.max(MIN_SCALE, Math.min(1, away / SAME_SIZE_M));
   tag.sprite.scale.set(tag.width * scale, tag.height * scale, 1);
+  tag.sprite.position.y += tag.lift * scale;
 }
 
 // Remove a tag from the three.js scene and release its texture and material.
@@ -78,24 +90,31 @@ export function shortName(username) {
   return anon ? `anon-${anon[1].replace(/-/g, '').slice(-6)}` : (username ?? 'player');
 }
 
-// Rasterize one display name into the canvas used as the sprite texture.
-function drawLabel(text) {
+// Rasterize one display name, with the avatar centred above it, into the canvas
+// used as the sprite texture.
+function drawLabel(text, avatar) {
   const canvas = document.createElement('canvas');
   const ctx = canvas.getContext('2d');
   const font = '600 44px Inter, system-ui, sans-serif';
   ctx.font = font;
-  const width = Math.ceil(ctx.measureText(text).width) + 40;
+  const pillWidth = Math.ceil(ctx.measureText(text).width) + 40;
+  const width = avatar ? Math.max(pillWidth, AVATAR_PX) : pillWidth;
+  const top = avatar ? AVATAR_PX + GAP_PX : 0;
 
   // Canvas resizing clears the context state, so measure before resizing and
   // restore the font before drawing.
   canvas.width = width;
-  canvas.height = 68;
+  canvas.height = top + LABEL_PX;
   ctx.font = font;
+  if (avatar) {
+    ctx.drawImage(avatar, (width - AVATAR_PX) / 2, 0, AVATAR_PX, AVATAR_PX);
+  }
+  const left = (width - pillWidth) / 2;
   ctx.fillStyle = 'rgba(12,12,16,0.72)';
-  ctx.roundRect(0, 0, width, 68, 16);
+  ctx.roundRect(left, top, pillWidth, LABEL_PX, 16);
   ctx.fill();
   ctx.fillStyle = '#f2f2f5';
   ctx.textBaseline = 'middle';
-  ctx.fillText(text, 20, 36);
+  ctx.fillText(text, left + 20, top + LABEL_PX / 2);
   return canvas;
 }

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);