castle-web-cli 0.4.230 → 0.4.231

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. package/dist/castle-host/host.js +81 -0
  2. package/dist/devSaveStorage.d.ts +36 -0
  3. package/dist/devSaveStorage.js +469 -0
  4. package/dist/devSessionChild.js +22 -12
  5. package/dist/devSessionServer.js +8 -2
  6. package/dist/devSessionStorage.d.ts +9 -0
  7. package/dist/devSessionStorage.js +66 -1
  8. package/dist/init.js +1 -1
  9. package/dist/serve.js +5 -1
  10. package/kits/base/castle.json +1 -1
  11. package/kits/base/sdk/README.md +148 -1
  12. package/kits/base/sdk/castle.d.ts +4 -0
  13. package/kits/base/sdk/castle.js +2 -0
  14. package/kits/base/sdk/commands.d.ts +15 -0
  15. package/kits/base/sdk/multiplayer.js +52 -4
  16. package/kits/base/sdk/save.d.ts +197 -0
  17. package/kits/base/sdk/save.js +525 -0
  18. package/kits/base/sdk/saveCoordinator.d.ts +39 -0
  19. package/kits/base/sdk/saveCoordinator.js +252 -0
  20. package/kits/base/sdk/server/storage.d.ts +3 -2
  21. package/kits/base/sdk/server/storage.js +25 -5
  22. package/kits/base/sdk/server/wrapper.d.ts +4 -0
  23. package/kits/base/sdk/server/wrapper.js +2 -0
  24. package/kits/base/sdk/store.d.ts +3 -2
  25. package/kits/base/sdk/store.js +5 -0
  26. package/kits/hub-game/CLAUDE.md +4 -1
  27. package/kits/hub-game/code/client/chrome.js +43 -9
  28. package/kits/hub-game/code/client/grab.js +142 -7
  29. package/kits/hub-game/code/client/hookLayer.js +7 -1
  30. package/kits/hub-game/code/client/state.js +13 -1
  31. package/kits/hub-game/code/client/talk.js +10 -36
  32. package/kits/hub-game/code/client/tiers.js +480 -0
  33. package/kits/hub-game/code/client/together.js +78 -3
  34. package/kits/hub-game/code/server/grab.js +3 -2
  35. package/kits/hub-game/code/server/hub.js +99 -5
  36. package/kits/hub-game/code/server/manifest.js +34 -7
  37. package/kits/hub-game/code/server/npcs.js +21 -33
  38. package/kits/hub-game/code/server/party.js +64 -6
  39. package/kits/hub-game/code/systems/hub.js +133 -16
  40. package/kits/hub-game/docs/contract.md +84 -14
  41. package/kits/hub-game/package.json +1 -1
  42. package/kits/hub-game/scripts/test-grab-client.mjs +328 -0
  43. package/kits/hub-game/scripts/test-hub-trip.mjs +208 -0
  44. package/kits/hub-game/scripts/test-manifest.mjs +47 -1
  45. package/kits/hub-game/scripts/test-npcs.mjs +34 -24
  46. package/kits/hub-game/scripts/test-party.mjs +87 -4
  47. package/kits/hub-game/scripts/test-tiers.mjs +666 -0
  48. package/kits/hub-game/scripts/test-together.mjs +33 -1
  49. package/kits/physics-2d/CLAUDE.md +2 -0
  50. package/kits/physics-2d/castle.json +2 -2
  51. package/kits/physics-2d/engine/scene.js +92 -0
  52. package/kits/physics-2d/package.json +1 -1
  53. package/kits/physics-2d/scripts/test-skip-unchanged.mjs +254 -0
  54. package/kits/physics-3d/CLAUDE.md +279 -0
  55. package/kits/physics-3d/behaviors/Player.jsx +74 -1
  56. package/kits/physics-3d/castle.json +3 -3
  57. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +1 -1
  58. package/kits/physics-3d/engine3d/actornode.js +253 -0
  59. package/kits/physics-3d/engine3d/nearshadows.js +600 -0
  60. package/kits/physics-3d/engine3d/unchanged.js +153 -0
  61. package/kits/physics-3d/engine3d/world3d.js +465 -7
  62. package/kits/physics-3d/package.json +1 -1
  63. package/kits/physics-3d/scripts/test-camera-follow.mjs +533 -0
  64. package/kits/physics-3d/scripts/test-near-shadows.mjs +1073 -0
  65. package/kits/physics-3d/scripts/test-static-actors.mjs +662 -0
  66. package/kits/physics-3d/scripts/test-static-passes.mjs +459 -0
  67. package/kits/physics-3d/scripts/test-static-physics.mjs +128 -0
  68. package/kits/physics-3d/systems/physics3d.js +182 -3
  69. package/package.json +1 -1
@@ -7,7 +7,8 @@
7
7
  // ribbon, the avatar the player wears everywhere, grabbing and throwing
8
8
  // the place's loose objects where it offers that (`client/grab.js`), and idle
9
9
  // play -- emotes, seats and the place's sounds -- where it offers that
10
- // (`client/idle.js`, `client/sound.js`).
10
+ // (`client/idle.js`, `client/sound.js`), and, in a deck that asks for it, a
11
+ // cheaper picture on a slow device (`client/tiers.js`).
11
12
  //
12
13
  // One engine, one iframe (HUB.md decision 2): going through a door unloads this
13
14
  // place's scene, loads the next one's (`scene.requestedScene`), and moves the
@@ -35,6 +36,7 @@ import { makeIdle } from '../client/idle.js';
35
36
  import { makeSay, REACTIONS } from '../client/say.js';
36
37
  import { makeSound } from '../client/sound.js';
37
38
  import { makeTalk } from '../client/talk.js';
39
+ import { makeTiers } from '../client/tiers.js';
38
40
  import { makeTogether, pointerAt } from '../client/together.js';
39
41
  import { makeWear } from '../client/wear.js';
40
42
 
@@ -79,6 +81,8 @@ const START_NEAR_STAY_M = 4;
79
81
  const JUMP_GAP_MS = 1100;
80
82
  // How long "Let's play <door>" from someone here is offered as a Go.
81
83
  const PLAY_ASK_MS = 20000;
84
+ // How long "<friend> went into <door>" is offered as a Follow.
85
+ const WENT_ASK_MS = 45000;
82
86
  // The same player naming the same door is not offered again inside this.
83
87
  const PLAY_ASK_AGAIN_MS = 60000;
84
88
  // A cabinet (v1.7): how long the cover waits for the host to say it is playing
@@ -187,6 +191,8 @@ class HubSystem {
187
191
  // `${playerId}:${door}` -> when each was last offered.
188
192
  this.playAsk = null;
189
193
  this.playAsked = new Map();
194
+ // A friend who went through a door while the question could not be put.
195
+ this.wentAsk = null;
190
196
  this.chat = makeChat();
191
197
  this.namesTouched = new WeakMap();
192
198
  }
@@ -256,13 +262,7 @@ class HubSystem {
256
262
  // network pose each frame, which would lift a hidden one back up.
257
263
  if (this.lateFor !== scene && typeof scene.registerSystem === 'function') {
258
264
  this.lateFor = scene;
259
- scene.registerSystem({
260
- afterBehaviors: (s) => {
261
- this.applyVisibility(s);
262
- this.applyWear(s);
263
- this.fadeNames(s);
264
- },
265
- });
265
+ this.registerLate(scene);
266
266
  }
267
267
  this.applyVisibility(scene);
268
268
  this.applyWear(scene);
@@ -295,6 +295,46 @@ class HubSystem {
295
295
  this.measure(scene, mp, now);
296
296
  }
297
297
 
298
+ // Device tiers (`client/tiers.js`), only in a deck whose castle.json asks
299
+ // (`hub.tiers`): without it this is never called, nothing of theirs is made
300
+ // or run, and the place is drawn and behaves exactly as it did. A frame
301
+ // counts toward the judge only while the player is placed and no trip or
302
+ // ending is under way: a scene swap's frames say nothing about how this
303
+ // device draws the place.
304
+ deviceTier(scene, mp, now) {
305
+ if (!Hub.deck.tiers) {
306
+ return;
307
+ }
308
+ if (!this.tiers) {
309
+ this.tiers = makeTiers();
310
+ const pick = (mode) => {
311
+ this.tiers.set(mode);
312
+ this.chrome?.setGraphics?.(this.tiers.mode, pick);
313
+ };
314
+ this.chrome?.setGraphics?.(this.tiers.mode, pick);
315
+ }
316
+ const counts = !this.trip && this.pendingEnd === null && mp?.placed?.() === true;
317
+ this.tiers.frame(scene, counts, now);
318
+ globalThis.__hub.tier = this.tiers.handle;
319
+ }
320
+
321
+ // The systems that run after every other one, registered once per runtime.
322
+ registerLate(scene) {
323
+ scene.registerSystem({
324
+ afterBehaviors: (s) => {
325
+ this.applyVisibility(s);
326
+ this.applyWear(s);
327
+ this.fadeNames(s);
328
+ },
329
+ });
330
+ // Device tiers run as a system of their own, registered only in a deck
331
+ // that asks (`deck.tiers` is read once, as the page loads): a deck without
332
+ // it runs exactly the frame it always did.
333
+ if (Hub.deck.tiers) {
334
+ scene.registerSystem({ afterBehaviors: (s) => this.deviceTier(s, s.multiplayer, performance.now()) });
335
+ }
336
+ }
337
+
298
338
  // The places this player will walk back into stay built while they are away
299
339
  // (physics-3d's `residentScenes`): a return redraws the town from the nodes
300
340
  // it left, rather than rebuilding every mesh behind the door.
@@ -347,6 +387,7 @@ class HubSystem {
347
387
  this.say.clear();
348
388
  this.together.clear();
349
389
  this.playAsk = null;
390
+ this.wentAsk = null;
350
391
  this.playAsked.clear();
351
392
  }
352
393
 
@@ -440,6 +481,7 @@ class HubSystem {
440
481
  this.say.clear();
441
482
  this.together.clear();
442
483
  this.playAsk = null;
484
+ this.wentAsk = null;
443
485
  this.playAsked.clear();
444
486
  this.chat.reset();
445
487
  }
@@ -555,7 +597,18 @@ class HubSystem {
555
597
 
556
598
  // The session under this player ended without a trip of ours: the game's
557
599
  // server crashed or was replaced. A game is left through the door the player
558
- // came in by (contract §5); anywhere else the multiplayer kit rejoins.
600
+ // came in by (contract §5); anywhere else the multiplayer kit rejoins, but
601
+ // only a join it can make again. A player who came back to the town through
602
+ // a door is there by a hub join, whose handoff is spent: when the town's own
603
+ // server is replaced under them (a new version saved) nothing would join
604
+ // again and the town would stand there dead, so the join this runtime began
605
+ // with is made again, as a lost join at the root of the trail is. Deeper on
606
+ // the host's trail (a place behind a door) there is no join to make again
607
+ // from where the player stands -- the host's doors are this place's own, and
608
+ // only a new acquisition names the new version's content -- so the player is
609
+ // sent back the way they came, as from a game, and walks in again through
610
+ // the door. Once per close: `lastNet` is forgotten, the way back is a trip,
611
+ // and one that is refused leaves the host's Back to ask again.
559
612
  watchSession(scene, mp) {
560
613
  if (this.trip) {
561
614
  // Our own switch closes the old connection; that is not an ending.
@@ -571,10 +624,24 @@ class HubSystem {
571
624
  }
572
625
  this.lastNet = null;
573
626
  const inGame = Boolean(Hub.hub.place?.result);
627
+ const barred = last.closeError?.() === HUB_BANNED;
574
628
  Hub.clear();
575
629
  if (inGame && scene.persistent.hubTickets.length) {
576
630
  this.toast = { text: 'The game ended', until: performance.now() + TOAST_MS };
577
631
  this.back(scene);
632
+ } else if (!inGame && !barred && mp.target?.mode === 'hub' && !(scene.persistent.hubDepth > 0)) {
633
+ console.warn('[hub-door] this place ended under a hub join: joining it again');
634
+ mp.switchSession(scene, scene.persistent.hubRootJoin ?? { mode: 'public' });
635
+ this.helloNet = null;
636
+ this.toast = { text: 'Reconnecting…', until: performance.now() + TOAST_MS };
637
+ } else if (!inGame && !barred && mp.target?.mode === 'hub') {
638
+ console.warn('[hub-door] this place ended under a hub join behind a door: leaving by its way back');
639
+ const title = scene.persistent.hubTickets.at(-1)?.title;
640
+ this.toast = {
641
+ text: title ? `This place was updated. Back to ${title}…` : 'This place was updated. Going back…',
642
+ until: performance.now() + TOAST_MS,
643
+ };
644
+ this.back(scene);
578
645
  }
579
646
  }
580
647
 
@@ -1134,6 +1201,21 @@ class HubSystem {
1134
1201
  }
1135
1202
  }
1136
1203
 
1204
+ // Why chat reaches nobody when a friend exists but is not in this layer:
1205
+ // "amy is in Tile Fall · chat when they're back". Only the friends the
1206
+ // People list also names: one inside a game behind one of this town's
1207
+ // doors, or in another layer of it. Null when there is nobody to name.
1208
+ awayNote() {
1209
+ const title = (door) => Hub.hub.doors.find((d) => d.id === door)?.title ?? null;
1210
+ const rows = (this.friendsAll ?? []).filter((f) => f && !f.here && (typeof f.door !== 'string' || title(f.door)));
1211
+ const away = rows.find((f) => typeof f.door === 'string') ?? rows[0];
1212
+ if (!away) {
1213
+ return null;
1214
+ }
1215
+ const where = typeof away.door === 'string' ? `in ${title(away.door)}` : 'in another part of town';
1216
+ return `${away.username ?? 'Your friend'} is ${where} · chat when they're back`;
1217
+ }
1218
+
1137
1219
  // A pick from the speech card: a reaction or a phrase goes to the place; a
1138
1220
  // typed line goes to the host, which sends it to whoever ghost lets read it.
1139
1221
  saying(what) {
@@ -1142,7 +1224,10 @@ class HubSystem {
1142
1224
  return;
1143
1225
  }
1144
1226
  this.chat.send(what.text, (status) => {
1145
- const text = status === 'none' ? 'Nobody here can read that. Follow each other to chat.' : status === 'limited' ? 'Slow down a little.' : status === 'sent' ? null : "That didn't send.";
1227
+ // A sent line says whom it went to: there is no other sign it arrived.
1228
+ const to = this.chatReach ?? [];
1229
+ const sent = to.length ? `Sent to ${to.slice(0, 3).join(', ')}${to.length > 3 ? ` +${to.length - 3}` : ''}` : null;
1230
+ const text = status === 'none' ? 'Nobody here can read that. Follow each other to chat.' : status === 'limited' ? 'Slow down a little.' : status === 'sent' ? sent : "That didn't send.";
1146
1231
  if (text) {
1147
1232
  this.toast = { text, until: performance.now() + TOAST_MS };
1148
1233
  }
@@ -1167,7 +1252,14 @@ class HubSystem {
1167
1252
  const play = this.playAsk;
1168
1253
  if (play && performance.now() < play.until && Hub.hub.doors.some((d) => d.id === play.door) && !invite) {
1169
1254
  const title = Hub.hub.doors.find((d) => d.id === play.door)?.title ?? 'a game';
1170
- return { key: `play:${play.from}:${play.door}:${play.until}`, kind: 'play', door: play.door, text: `${play.name}: let's play ${title}`, yes: 'Go', no: 'Not now' };
1255
+ // A game that takes no late joiners cannot be followed into: the player
1256
+ // is told where their friend is, and that they will be back.
1257
+ const late = Hub.hub.doors.find((d) => d.id === play.door)?.late === true;
1258
+ if (play.went && !late) {
1259
+ return { key: `play:${play.from}:${play.door}:${play.until}`, kind: 'play', door: null, text: `${play.name} went into ${title} · back soon`, yes: 'OK', no: 'Go to the door' };
1260
+ }
1261
+ const text = play.went ? `${play.name} went into ${title}` : `${play.name}: let's play ${title}`;
1262
+ return { key: `play:${play.from}:${play.door}:${play.until}`, kind: 'play', door: play.door, text, yes: play.went ? 'Follow' : 'Go', no: 'Not now' };
1171
1263
  }
1172
1264
  if (invite) {
1173
1265
  return { key: `invite:${invite.from}`, kind: 'invite', from: invite.from, text: `${invite.username ?? 'Someone'} invited you to their party`, yes: 'Join party', no: 'No thanks' };
@@ -1181,9 +1273,13 @@ class HubSystem {
1181
1273
  return;
1182
1274
  }
1183
1275
  if (ask.kind === 'play') {
1276
+ // "Back soon" (no door on the question): OK stays, the other button
1277
+ // goes to wait at the door.
1278
+ const door = ask.door ?? (yes ? null : this.playAsk?.door ?? null);
1279
+ const go = ask.door ? yes : !yes;
1184
1280
  this.playAsk = null;
1185
- if (yes) {
1186
- this.sendJump(net, { k: 'hub-door-jump', door: ask.door });
1281
+ if (go && door) {
1282
+ this.sendJump(net, { k: 'hub-door-jump', door });
1187
1283
  }
1188
1284
  return;
1189
1285
  }
@@ -1863,6 +1959,21 @@ class HubSystem {
1863
1959
  chrome.setPeople?.(free ? this.people(scene, inGame) : null, town ? this.together.partyLine() : null);
1864
1960
  chrome.setAsk?.(town ? this.ask() : null);
1865
1961
  this.startBeside(scene, local, town, now);
1962
+ // A friend or party member went through a door: say so, and offer to follow.
1963
+ // Kept until the question can be put (not while talking to an NPC): the
1964
+ // name is taken now, while the friend is still remembered.
1965
+ for (const went of Hub.hub.wentEvents.splice(0)) {
1966
+ const name = place && !inGame ? went.players.map((id) => this.together.lately(id)).find(Boolean) : null;
1967
+ if (name) {
1968
+ this.wentAsk = { from: went.players[0], name, door: went.door, until: now + WENT_ASK_MS, went: true };
1969
+ }
1970
+ }
1971
+ if (town && this.wentAsk) {
1972
+ if (now < this.wentAsk.until && Hub.hub.doors.some((d) => d.id === this.wentAsk.door)) {
1973
+ this.playAsk = this.wentAsk;
1974
+ }
1975
+ this.wentAsk = null;
1976
+ }
1866
1977
  // A friend or party member who just came in: say so, and point to them.
1867
1978
  for (const who of town ? this.together.arrivals() : []) {
1868
1979
  this.toast = { text: `${who.username ?? 'A friend'} is here · People to join`, until: now + TOAST_MS };
@@ -1910,6 +2021,7 @@ class HubSystem {
1910
2021
  this.say.chat(now, from?.playerId ?? null, from?.username ?? message.fromUsername ?? 'Someone', message, CHAT_BUBBLE_MS);
1911
2022
  }
1912
2023
  const reach = (this.chat.peers ?? []).map((userId) => byUser.get(userId)?.username).filter(Boolean);
2024
+ this.chatReach = reach;
1913
2025
  // The field is always there where the host has chat, so it can be found;
1914
2026
  // when it cannot be used the card says why, in terms of this player alone
1915
2027
  // (never another player's age).
@@ -1917,7 +2029,7 @@ class HubSystem {
1917
2029
  ? "Chat isn't available on this account"
1918
2030
  : reach.length
1919
2031
  ? `Chat reaches ${reach.slice(0, 3).join(', ')}${reach.length > 3 ? ` +${reach.length - 3}` : ''}`
1920
- : 'Follow each other to chat. Nobody here follows you back yet.';
2032
+ : this.awayNote() ?? 'Chat is for players who follow each other. None of yours are here now · the phrases above reach everyone.';
1921
2033
  const chatPart = this.chat.available() && this.chat.peers !== null
1922
2034
  ? { input: this.chat.canChat && reach.length > 0, note: chatNote }
1923
2035
  : null;
@@ -1926,8 +2038,13 @@ class HubSystem {
1926
2038
  // Standing still beside someone: a small button invites them.
1927
2039
  const beside = town && !Hub.hub.party.invite && local ? this.together.beside(scene, local) : null;
1928
2040
  chrome.nearPrompt?.(
1929
- beside ? `+ Party · ${beside.username ?? 'this player'}` : null,
1930
- () => this.join(scene, beside, 'invite'),
2041
+ beside ? `${beside.sent ? 'Invited' : '+ Party'} · ${beside.username ?? 'this player'}` : null,
2042
+ () => {
2043
+ if (!beside.sent) {
2044
+ this.together.invited(beside.playerId);
2045
+ this.join(scene, beside, 'invite');
2046
+ }
2047
+ },
1931
2048
  );
1932
2049
  // Barred from the hub: the town's own join was refused, and is not asked again.
1933
2050
  if (scene.multiplayer?.joinError === HUB_BANNED) {
@@ -1,6 +1,6 @@
1
1
  # The hub-game contract
2
2
 
3
- **Version 1.14** (2026-10-04; v1 plus the optional additions under "Changes in
3
+ **Version 1.22** (2026-10-04; v1 plus the optional additions under "Changes in
4
4
  v1", each marked with the minor version that added it). Kit: `castle.hub-game` (`kits/hub-game`). Design:
5
5
  `cauldron-game-server` `docs/HUB.md` (decision 3: a hub game is a kit plus a
6
6
  contract). Inputs: the M0 report's Tier 0 gaps 1-9 (card
@@ -61,6 +61,7 @@ curation where it cannot:
61
61
  "grab": true, // optional (v1.3); players pick up loose objects and throw them (§6)
62
62
  "idle": { "emotes": true, "seats": true, "sounds": ["sounds/jukebox.mp3"] }, // optional (v1.6); emotes, seats, the place's sounds (§6)
63
63
  "nearestPlayers": 30, // optional; 1..100, how many other players each client is sent (§12)
64
+ "tiers": true, // optional (v1.21); a cheaper picture on a slow device, client only
64
65
  "places": { } // optional; more places in the same deck (§3)
65
66
  }
66
67
  ```
@@ -80,9 +81,10 @@ curation where it cannot:
80
81
  | `places` | object | §3. |
81
82
  | `npcs` | object | §13. |
82
83
  | `fallY` | number | v1.1. -25 to 50 metres; below it a player has fallen (§5). Default: none, or -20 in a scene with no ground. |
83
- | `grab` | boolean or object | v1.3. `true`, or `{ throwSpeed, holdDistance, holdHeight }`: 1-14 m/s (default 10), 0.8-3 m (default 1.4), 0-2.5 m (default 1.2); any left out takes its default. `false` or absent: no grabbing (§6). |
84
+ | `grab` | boolean or object | v1.3. `true`, or `{ throwSpeed, holdDistance, holdHeight }`: 1-14 m/s (default 10), 0.8-3 m (default 1.4), 0-2.5 m (default 1.2); any left out takes its default. v1.22 adds two, each optional: `reach`, 1.6-3 m, how far (flat, from the object's near side) an object is offered, and `steady`, true or false, an offer that holds through a moment at its edge (§6). Left out (or `steady: false`), neither is sent to the client nor changes anything: the place is offered, sent and drawn exactly what it was. `false` or absent: no grabbing (§6). |
84
85
  | `idle` | boolean or object | v1.6. `true` (emotes and seats), or `{ emotes, seats, sounds }`: `emotes` and `seats` true or false (default false), `sounds` up to 16 different `.mp3`/`.wav`/`.m4a` paths (lower-case extensions, as the engine bundles them) of this deck that `hub.sound` may play (each at most 256 KB, 1 MB in all, checked at publish). `false`, absent or all off: none of it (§6). |
85
86
  | `nearestPlayers` | integer | 1-100, default 30. Each client is sent the poses of only this many other players, the nearest (§12). |
87
+ | `tiers` | boolean | v1.21, the deck's (not a place's). `true`: each client draws a cheaper picture where the device is slow -- a weak phone GPU or 2 GB or less of memory, or frames slower than 40 ms (the median of the first 5 s after arrival, or of any 10 s after), remembered on the device for 7 days. Low has no sun shadow (the render resolution is unchanged), no decorative actors (only `Transform`/`Shape`/`Model`), and no scenery (those plus `Solid`/`Lookable`) past 30 m or NPC bodies past 20 m; doors, pads, players and anything else with gameplay are always drawn, and in a game reached through a door only the shadow changes. The Character card gains Graphics: Auto / Low / High, kept on the device; Low or High wins. Nothing changes on the wire or for other players. `false` or absent: none of it. |
86
88
 
87
89
  Unknown keys are a check failure, not ignored: a typo in a contract field must
88
90
  not publish as "no such rule".
@@ -274,8 +276,10 @@ layer door. On the dev serve the door is a `deck:<name>` door like any other.
274
276
  - A late joiner arrives the same way, alone.
275
277
  - **Jumping to a door.** In a town (a place with no `result`) the chrome's Doors
276
278
  button lists the place's doors; Go puts the player on that door's pad (the
277
- `HubPad` actor naming it, v1.10: within 0.9 m of its middle, so the pad
278
- counts them), facing the door, or 7 m in front of a door with no pad, in the
279
+ `HubPad` actor naming it, v1.10: inside its radius, so the pad counts them;
280
+ v1.20: on a spot no one stands within 1.1 m of, a ring 1.2 m about its
281
+ middle first, then nearer its edge, then the middle, else the spot with the
282
+ most room), facing the door, or 7 m in front of a door with no pad, in the
279
283
  door's own frame (at most once a second; never a held player). It is a walk, not a trip: the player stays in this session. A game
280
284
  has no list.
281
285
  - **Where a player came from** is ghost's arrival where the host has hub ops
@@ -299,6 +303,22 @@ layer door. On the dev serve the door is a `deck:<name>` door like any other.
299
303
  trail the runtime's first join is made again into the place already loading,
300
304
  anywhere deeper the player leaves by that place's way back, twice at most.
301
305
  Acquisitions and `Hub.cancel` run one at a time.
306
+ - **A place replaced under its players (v1.18).** When a place's session ends
307
+ under a player who is not on a trip (a new version of it was saved, or its
308
+ server stopped): a game is left as before ("The game ended", then its way
309
+ back); any other place reached through a door (the host's trail holds the
310
+ trip) is left by its way back at once, with a line saying it was updated
311
+ ("This place was updated. Back to <the place left>…"), and is entered again
312
+ through its door, which acquires the new version and its content. A join
313
+ cannot be made again from inside such a place: its handoff is spent, and
314
+ only a door's acquisition names the release to mount. The way back is asked
315
+ once per ending; one that is refused leaves the player where they are with
316
+ the host's Back control, as any refused way back does. The town itself, at
317
+ the root of the host's trail, joins again where it stands with the join the
318
+ runtime began with ("Reconnecting…"; the kit did this before v1.18, and it
319
+ is written down here). A player barred from the hub is neither sent back nor
320
+ joined again. The place's server sees nothing new: the players of the old
321
+ session had `leave`, and those who walk back in `arrive` like anyone.
302
322
  - **A cabinet's trip (v1.7).** A `hub-go` with `classic` is a hub trip with no
303
323
  destination session and no content. The client asks `Hub.go(door)`, which a
304
324
  host that can play classic decks answers `{ status: 'ok', kind: 'classic' }`
@@ -328,7 +348,9 @@ layer door. On the dev serve the door is a `deck:<name>` door like any other.
328
348
  <door> pad" for a `HubPad` actor's circle, "near <door>" within 7 m of a
329
349
  door, else the place's `where` hook (§4), else "in town". Join
330
350
  (`hub-goto`) puts the player beside that friend, facing them, as a jump to a
331
- door does: a town only, at most once a second, never a held player, never
351
+ door does, but never on a door's pad nor at its edge, theirs included (v1.19:
352
+ beside a friend on a pad is just off its edge, so joining their game is a
353
+ step the player takes): a town only, at most once a second, never a held player, never
332
354
  across a block; a sitter stands first. The server does not know who is whose
333
355
  friend, so it moves a player beside any player of the session they may see;
334
356
  only the chrome's list limits Join to friends. Find moves nobody: it puts
@@ -464,6 +486,32 @@ and at a game's end. `hub.drop(playerId?)` makes a player let go (a goal, a
464
486
  whistle): the object falls where it is. A place without `grab` draws no button
465
487
  and is sent exactly what it was.
466
488
 
489
+ **A steadier offer (v1.22).** The offer is tested afresh every frame: within
490
+ the reach, within 60 degrees of facing, and this client's to simulate (the
491
+ multiplayer kit hands an object to the nearest player). At any of those edges
492
+ -- a player turning, two players near one object -- the button comes and
493
+ goes, and on a phone a press lands on nothing. A place may set, in `grab`:
494
+
495
+ - `reach` (1.6-3 m): objects are offered this far from their near side instead
496
+ of 1.6 m.
497
+ - `steady: true`: once an object is offered, it stays the one offered while
498
+ its near side is within the reach and 0.4 m more and it is within 90
499
+ degrees of facing, even when another is nearer. When it fails that for a
500
+ moment -- briefly someone else's to simulate, a turn past the cone, a step
501
+ back -- the button stays up for 600 ms. A press in that time waits up to
502
+ 500 ms for the object to pass the test again (this client's own included)
503
+ and grabs it then; if it does not, the press is dropped. Another object
504
+ that passes the ordinary test takes the offer over meanwhile.
505
+
506
+ With either set, an object is also never offered when its centre is more than
507
+ 3 m from the player's, and less the faster the player is moving (their body's
508
+ speed, jumps included, or their tuned speed, over the 0.2 s the server's view of
509
+ them may trail), keeping inside the server's 4 m in ordinary play; a grab the
510
+ server still refuses is let go, as any refused grab is. Nothing changes on the server: it checks every grab
511
+ as it always has, and the client still sends a grab only for an object that
512
+ is its own at that moment. A place that sets neither runs the offer it always
513
+ did, and is sent and drawn exactly what it was.
514
+
467
515
  A refusal and `hub.drop` bind the hub client, which is the only client a hub
468
516
  place has; they do not take the object from its owner on the server. A
469
517
  modified client can carry a loose object it owns whatever the place says,
@@ -856,7 +904,7 @@ place with `idle` (v1.6) only the parts it turns on: `hubEmotes` (player id →
856
904
  `{ id, at, until }`, simulation ms), `hubSeated` (player id → seat actor id),
857
905
  `hubSounds` (actor id → `{ file, volume, radius, since }`, the loops playing).
858
906
  Server → every client: `{ k: 'hub-sound', actor, file, volume, radius }` (v1.6,
859
- a one-shot); `{ k: 'hub-said', player, r }` or `{ k: 'hub-said', player, p, door? }` (v1.11, §6: to each client a block does not hide the speaker from). Server → one
907
+ a one-shot); `{ k: 'hub-went', players, door }` (v1.15, a town: to each player staying, who of the players they may see went through `door`); `{ k: 'hub-said', player, r }` or `{ k: 'hub-said', player, p, door? }` (v1.11, §6: to each client a block does not hide the speaker from). Server → one
860
908
  client: `{ k: 'hub-go', door, key, place, scene, title, party }` (in production `key` is null and `pad` names the fired pad; a cabinet's, v1.7, has `classic: true`, no `key` and no `pad`, and `dev: true` on the dev serve),
861
909
  `{ k: 'hub-cabinet', actor, door, card }` (v1.7: a cabinet's card for the door actor `actor`, `{ title, label, cover, top: [{ username, score, photo, frame }] }`, or `card: null` when it is gone),
862
910
  `{ k: 'hub-arrived', facing }`, `{ k: 'hub-jumped', facing }` (after a jump to a door or, with `to` the player, to a player, §5),
@@ -865,7 +913,7 @@ client: `{ k: 'hub-go', door, key, place, scene, title, party }` (in production
865
913
  override), `{ k: 'hub-tune', tune }` (v1.2, that player's `{ speed, jump }` or null), `{ k: 'hub-labels', labels }` (that player's own labels),
866
914
  `{ k: 'hub-result', result }`, `{ k: 'hub-end', why }`,
867
915
  `{ k: 'hub-grab-deny', actor }` (v1.3: a grab refused; let go), `{ k: 'hub-drop', actor }` (v1.3: `hub.drop`),
868
- `{ k: 'hub-npc', npc, open, mind?, character?, name?, disclosure?, hearRange?, why? }`,
916
+ `{ k: 'hub-npc', npc, open, mind?, character?, name?, disclosure?, hearRange?, why? }` (since v1.17 `disclosure` is always `"participants"` and `hearRange` always 0: a client from before it named the players in that range as a turn's listeners),
869
917
  `{ k: 'hub-npc-line', npc, text, why }` (`why` v1.8, as `npcLine`'s), `{ k: 'hub-npc-notes', npc, prefix }` (v1.8, §13), `{ k: 'hub-av', hubAv }` (avatars of players in a
870
918
  hidden pair that this player may see, laid over the shared `hubAv`), `{ k: 'hub-wear', hubWear }`
871
919
  (v1.4, their wearables, laid over the shared `hubWear` the same way).
@@ -988,18 +1036,32 @@ door that names its own session.
988
1036
  | `route` | optional; a `server.destinations` route with `characters: "shared"`, joined only on SDKs without place characters. Without a route the minds are the place's alone: every layer addresses ghost's one place mind |
989
1037
  | `slot` | 1-64 of `[A-Za-z0-9_.-]`; default `"main"`; the fallback route's world. A world keeps the character definitions it was created with: after changing the bundle's characters, name a new slot (ghost refuses turns in the old world with `CAULDRON_SHARED_CHARACTER_CONFLICT`) |
990
1038
  | `turnsPerMinute` | 1-30, default 6: the conversation budget of each character's body, so per layer |
991
- | `disclosure` | `"participants"` (default) or `"world"`: who a turn's words may reach (below) |
1039
+ | `disclosure` | `"participants"` or `"world"`: read, and since v1.17 not acted on. A player's conversation with a character is theirs alone (below) |
992
1040
  | `followSec` | 10-600, default 120: how long a body follows before it goes home |
993
1041
 
994
1042
  Where a session has the place's characters, a player's words are a character turn. The kit admits it only
995
- for the player the body is talking to, near it, with an audience of players
996
- near it, within the character's `turnsPerMinute`; anything else is refused
1043
+ for the player the body is talking to, near it, with no listener of any kind,
1044
+ within the character's `turnsPerMinute`; anything else is refused
997
1045
  before a model is called, and over budget the place's `budget` line answers
998
1046
  instead, so a crowd degrades to authored lines rather than a queue. The reply
999
- is ghost's text, shown in the speaker's panel and over the body for the turn's
1000
- audience only: the speaker and the players within 6 m when they spoke (at most
1001
- seven), as `participants` disclosure; `"world"` also lets the exchange enter
1002
- the place's public knowledge, which every layer sees. A body follows a player
1047
+ is ghost's text, shown in the speaker's panel and over the body for the
1048
+ speaker alone.
1049
+
1050
+ **A player's conversation is theirs alone (v1.17).** What a player types to a
1051
+ character, and what the character answers, reaches no other player: not as a
1052
+ bubble, not through the character's memory, not in another layer or a later
1053
+ session. Ghost keeps a turn's words for everyone its audience names (a listener
1054
+ reads them back and the character may repeat them), so a turn names no player
1055
+ and no character as a listener and is never `world`-disclosed: the kit's
1056
+ client sends an empty audience, the kit's server refuses any other
1057
+ (`HUB_NPC_AUDIENCE`), and ghost keeps a place mind's conversations per player
1058
+ whatever a client sent. The character still remembers the same player
1059
+ tomorrow: its memory of them is that player's own. Only words with nothing of
1060
+ any player's typing in them are public: authored lines, ambient lines, and
1061
+ what a mind says from ghost's verified news. A place must keep it so: never
1062
+ put what a player typed (`npcHeard`'s and `npcLine`'s `text`) into a line, a
1063
+ label, a HUD, storage another player reads, or another player's notes.
1064
+ A body follows a player
1003
1065
  only when its character chose its follow action (an action whose object effect
1004
1066
  hands the `follow` object to `"player"`); clients cannot start or aim it. The
1005
1067
  follow object is one per place, so only the body in the holder's layer follows.
@@ -1105,6 +1167,14 @@ Minor additions, each optional; a deck written before them reads the same.
1105
1167
 
1106
1168
  | date | change |
1107
1169
  | --- | --- |
1170
+ | 2026-10-04 (v1.22) | §1 and §6 `grab.reach` (1.6-3 m) and `grab.steady`: a place may offer objects from farther away and keep an offer up through a moment at its edge (the same object kept within the reach plus 0.4 m and 90 degrees of facing; the button held 600 ms through a lost owner or a turn; a press then waits 500 ms for the object to be this client's again), never past 3 m centre to centre. Sonnet playtests of Pillow Dojo and Number Pals on phones: the Grab button came and went at the reach, the cone and a shared owner, and bouts went on walking. Client only; a place without them is sent and drawn exactly what it was |
1171
+ | 2026-10-04 (v1.21) | §1 `tiers`: a deck may ask for device tiers, a cheaper picture drawn by a slow device's client (no sun shadow, decorative actors not drawn, scenery past 30 m and NPC bodies past 20 m not drawn) and a Graphics: Auto / Low / High row in the Character card. Phones the town was measured on (Galaxy Tab A7 Lite, Redmi 9A) drew it at 12 fps. Client only; a deck without `tiers` is drawn and behaves exactly as before |
1172
+ | 2026-10-04 (v1.20) | §5 a jump onto a pad (Doors Go, a party's go) is put on a spot no one stands within 1.1 m of (a ring 1.2 m about the pad's middle, at most half its radius, then a ring nearer its edge, then the middle, else the spot with the most room): a body put down touching another was pushed apart by physics and could push the one already there off the pad, so a pad that needed both never fired (production 18:00Z Oct 4). |
1173
+ | 2026-10-04 (v1.19) | §5 Join and starting beside a friend (`hub-goto`, an arrival's `near`) never place a player on a door's pad or within a body's width of one, the friend's own pad included: a friend on a pad is joined from just off its edge, facing them, so nobody is taken into a game they did not step into. With no clear spot off every pad the player stays where they were put. A place whose players never stand on pads sees no change |
1174
+ | 2026-10-04 (v1.18) | §5 a place replaced under its players: a place that is not a game, reached through a door, whose session ends under a player (a new version saved) sends them back the way they came with a line saying it was updated, instead of leaving them in its scene with no HUD, labels or controls; they walk in again through the door, into the new version. Also written down: the town at the root of the host's trail joins again where it stands (kit behaviour since 2026-10-04, not recorded until now). A game's ending is unchanged, and a deck changes nothing |
1175
+ | 2026-10-04 (v1.17) | §13 a player's conversation with a character is theirs alone: a turn names no listener (the client sends an empty audience and the server refuses any other), a mind's reply is drawn over the body for its speaker only (it was drawn for up to seven players within 6 m, and ghost kept the speaker's words for them too, so the character repeated them to those players later), `npcs.disclosure` is read and no longer acted on, and the Say panel's "Players nearby can hear" line is gone. Authored and ambient lines are public as before |
1176
+ | 2026-10-04 (v1.16) | §4 `hub.partyOf(playerId)`: the other members of a player's party who are in the place, so a place may wait for them (the town adds 7 s to a pad's countdown). §5 a Doors row carries `late: true` where the door takes late joiners; a friend who went through a door that does not is announced as "back soon" with no Follow |
1177
+ | 2026-10-04 (v1.15) | §5 in a town, the players who stay are told who went through which door (`hub-went`, §12: `{ players, door }`, never across a block, not for a cabinet); each client shows it only for its own friends and party members ("amy went into Tile Fall": Follow / Not now, for 45 s, Follow being a jump to that door's pad). A game sends none of it |
1108
1178
  | 2026-10-04 (v1.14) | §5 a town's Doors rows carry `featured` (listed first, starred), `solo` (a door that takes one player: a party is told so and is not asked to come) and `need` (its minimum when over one); a member who picks the door their party is already going to has answered yes; a friend or party member who comes in after the first moments is announced ("amy is here") and pointed to. §6 the chat field is always shown where the host has chat, disabled with the reason when it cannot be used ("Follow each other to chat. Nobody here follows you back yet.", "Chat isn't available on this account"). A deck changes nothing |
1109
1179
  | 2026-10-04 (v1.13) | §10 goals: `hub.label`'s `style: "goal"`, a per-player pointer to a scene actor drawn at the screen's edge while it is out of view. Pebble Cove's playtesters could not find the villager an errand named: a sign is drawn only where it projects on screen, and the camera looks down. A place that sets no goal is drawn exactly as before |
1110
1180
  | 2026-10-03 (v1.12) | §6 free-text chat between players who follow each other and are both over 13, enforced by ghost through the host (`Hub.chat`, `Hub.say`, `Hub.reportChat`); the kit draws what it is handed and says only "Follow each other to chat" otherwise. Nothing on the place's wire, and nothing at all on a host without the commands |
@@ -3,7 +3,7 @@
3
3
  "private": true,
4
4
  "type": "module",
5
5
  "scripts": {
6
- "check": "eslint . && node scripts/test-manifest.mjs && node scripts/test-npcs.mjs && node scripts/test-avatar.mjs && node scripts/test-hub-ops.mjs && node scripts/test-actors.mjs && node scripts/test-grab.mjs && node scripts/test-idle.mjs && node scripts/test-keys.mjs && node scripts/test-attention.mjs && node scripts/test-hub-trip.mjs && node scripts/test-pack.mjs && node scripts/test-interest.mjs && node scripts/test-blocks.mjs && node scripts/test-ban-join.mjs && node scripts/test-door.mjs && node scripts/test-door-jump.mjs && node scripts/test-together.mjs && node scripts/test-party.mjs && node scripts/test-say.mjs && node scripts/test-chat.mjs && node scripts/test-no-forms.mjs && node scripts/test-classic.mjs && node --input-type=module -e \"const { bundleProject } = await import('../../cli/dist/bundle.js'); await bundleProject('.');\"",
6
+ "check": "eslint . && node scripts/test-manifest.mjs && node scripts/test-npcs.mjs && node scripts/test-avatar.mjs && node scripts/test-hub-ops.mjs && node scripts/test-actors.mjs && node scripts/test-grab.mjs && node scripts/test-grab-client.mjs && node scripts/test-idle.mjs && node scripts/test-keys.mjs && node scripts/test-attention.mjs && node scripts/test-hub-trip.mjs && node scripts/test-pack.mjs && node scripts/test-interest.mjs && node scripts/test-blocks.mjs && node scripts/test-ban-join.mjs && node scripts/test-door.mjs && node scripts/test-door-jump.mjs && node scripts/test-together.mjs && node scripts/test-party.mjs && node scripts/test-say.mjs && node scripts/test-chat.mjs && node scripts/test-no-forms.mjs && node scripts/test-classic.mjs && node scripts/test-tiers.mjs && node --input-type=module -e \"const { bundleProject } = await import('../../cli/dist/bundle.js'); await bundleProject('.');\"",
7
7
  "format": "prettier --write \"code/**/*.js\" \"scripts/**/*.mjs\" castle.json package.json"
8
8
  },
9
9
  "dependencies": {