castle-web-cli 0.4.230 → 0.4.232

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 (92) 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/dist/serverBundle.js +5 -3
  11. package/kits/base/castle.json +1 -1
  12. package/kits/base/sdk/README.md +148 -1
  13. package/kits/base/sdk/castle.d.ts +4 -0
  14. package/kits/base/sdk/castle.js +2 -0
  15. package/kits/base/sdk/commands.d.ts +15 -0
  16. package/kits/base/sdk/multiplayer.js +52 -4
  17. package/kits/base/sdk/save.d.ts +197 -0
  18. package/kits/base/sdk/save.js +525 -0
  19. package/kits/base/sdk/saveCoordinator.d.ts +39 -0
  20. package/kits/base/sdk/saveCoordinator.js +252 -0
  21. package/kits/base/sdk/server/storage.d.ts +3 -2
  22. package/kits/base/sdk/server/storage.js +25 -5
  23. package/kits/base/sdk/server/wrapper.d.ts +4 -0
  24. package/kits/base/sdk/server/wrapper.js +2 -0
  25. package/kits/base/sdk/store.d.ts +3 -2
  26. package/kits/base/sdk/store.js +5 -0
  27. package/kits/hub-game/CLAUDE.md +29 -4
  28. package/kits/hub-game/code/client/avatar.js +39 -0
  29. package/kits/hub-game/code/client/chat.js +12 -0
  30. package/kits/hub-game/code/client/chrome.js +237 -13
  31. package/kits/hub-game/code/client/grab.js +166 -7
  32. package/kits/hub-game/code/client/hats.js +26 -0
  33. package/kits/hub-game/code/client/hookLayer.js +36 -3
  34. package/kits/hub-game/code/client/hudClear.js +126 -0
  35. package/kits/hub-game/code/client/state.js +35 -1
  36. package/kits/hub-game/code/client/talk.js +10 -36
  37. package/kits/hub-game/code/client/tiers.js +505 -0
  38. package/kits/hub-game/code/client/together.js +144 -4
  39. package/kits/hub-game/code/client/wear.js +96 -14
  40. package/kits/hub-game/code/server/actors.js +5 -0
  41. package/kits/hub-game/code/server/grab.js +299 -13
  42. package/kits/hub-game/code/server/hub.js +162 -7
  43. package/kits/hub-game/code/server/manifest.js +80 -8
  44. package/kits/hub-game/code/server/npcs.js +21 -33
  45. package/kits/hub-game/code/server/party.js +75 -6
  46. package/kits/hub-game/code/server/say.js +8 -2
  47. package/kits/hub-game/code/server/wear.js +116 -11
  48. package/kits/hub-game/code/systems/hub.js +386 -21
  49. package/kits/hub-game/docs/contract.md +285 -19
  50. package/kits/hub-game/package.json +1 -1
  51. package/kits/hub-game/scripts/test-chat.mjs +32 -0
  52. package/kits/hub-game/scripts/test-grab-client.mjs +511 -0
  53. package/kits/hub-game/scripts/test-grab.mjs +857 -3
  54. package/kits/hub-game/scripts/test-hats.mjs +229 -0
  55. package/kits/hub-game/scripts/test-hub-trip.mjs +721 -0
  56. package/kits/hub-game/scripts/test-hud-clear.mjs +676 -0
  57. package/kits/hub-game/scripts/test-manifest.mjs +122 -1
  58. package/kits/hub-game/scripts/test-npcs.mjs +34 -24
  59. package/kits/hub-game/scripts/test-party.mjs +108 -4
  60. package/kits/hub-game/scripts/test-say.mjs +59 -2
  61. package/kits/hub-game/scripts/test-tiers.mjs +854 -0
  62. package/kits/hub-game/scripts/test-together.mjs +33 -1
  63. package/kits/hub-game/scripts/test-try-on.mjs +940 -0
  64. package/kits/physics-2d/CLAUDE.md +2 -0
  65. package/kits/physics-2d/castle.json +2 -2
  66. package/kits/physics-2d/engine/scene.js +127 -0
  67. package/kits/physics-2d/package.json +1 -1
  68. package/kits/physics-2d/scripts/test-skip-unchanged.mjs +298 -0
  69. package/kits/physics-3d/CLAUDE.md +531 -0
  70. package/kits/physics-3d/behaviors/Player.jsx +437 -3
  71. package/kits/physics-3d/castle.json +3 -3
  72. package/kits/physics-3d/docs/pxmodel-format.md +4 -0
  73. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +33 -1
  74. package/kits/physics-3d/engine3d/actornode.js +253 -0
  75. package/kits/physics-3d/engine3d/nearshadows.js +600 -0
  76. package/kits/physics-3d/engine3d/optimize.js +49 -0
  77. package/kits/physics-3d/engine3d/orbitinput.js +277 -0
  78. package/kits/physics-3d/engine3d/unchanged.js +153 -0
  79. package/kits/physics-3d/engine3d/world3d.js +525 -11
  80. package/kits/physics-3d/package.json +1 -1
  81. package/kits/physics-3d/scripts/Player.before-orbit.mjs +310 -0
  82. package/kits/physics-3d/scripts/Scene3DPlayer.before-orbit.jsx +337 -0
  83. package/kits/physics-3d/scripts/test-camera-follow.mjs +543 -0
  84. package/kits/physics-3d/scripts/test-camera-orbit.mjs +2105 -0
  85. package/kits/physics-3d/scripts/test-drop-empty-parts.mjs +787 -0
  86. package/kits/physics-3d/scripts/test-near-shadows.mjs +1073 -0
  87. package/kits/physics-3d/scripts/test-static-actors.mjs +667 -0
  88. package/kits/physics-3d/scripts/test-static-passes.mjs +459 -0
  89. package/kits/physics-3d/scripts/test-static-physics.mjs +128 -0
  90. package/kits/physics-3d/scripts/test-steady-hover.mjs +633 -0
  91. package/kits/physics-3d/systems/physics3d.js +273 -9
  92. package/package.json +1 -1
@@ -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.30** (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
@@ -60,7 +60,10 @@ curation where it cannot:
60
60
  "fallY": -10, // optional (v1.1); below this a player has fallen (§5)
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
+ "hud": { "clear": true }, // optional (v1.26); a shorter HUD, and labels kept out from under it (§9)
63
64
  "nearestPlayers": 30, // optional; 1..100, how many other players each client is sent (§12)
65
+ "tiers": true, // optional (v1.21); a cheaper picture on a slow device, client only
66
+ "cues": true, // optional (v1.23); a town says more about the friends and party a player came with
64
67
  "places": { } // optional; more places in the same deck (§3)
65
68
  }
66
69
  ```
@@ -80,9 +83,12 @@ curation where it cannot:
80
83
  | `places` | object | §3. |
81
84
  | `npcs` | object | §13. |
82
85
  | `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). |
86
+ | `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. v1.25 adds `keepHeld`, true or false: a held object stays its holder's, whoever stands nearer (§6); left out or `false`, a place is sent, simulated and drawn exactly as it was. `false` or absent: no grabbing (§6). |
84
87
  | `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). |
88
+ | `hud` | object | v1.26. `{ clear }`, `clear` true or false (default false; `false` and `{}` are the same as leaving `hud` out). `true`: the place's HUD is laid out to stay short and what the hub draws over the world is kept out from under it (§9, "A clear HUD"). Client only: the server reads it, tells the client, and does nothing else by it. A place without it is sent and drawn exactly what it was. |
85
89
  | `nearestPlayers` | integer | 1-100, default 30. Each client is sent the poses of only this many other players, the nearest (§12). |
90
+ | `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. v1.30: an actor in a scene file may carry `"tier": "keep"` -- a field of the actor beside `id` and `components`, not a component -- and is then drawn on every tier at any distance, whatever its components; a place's ground (paving, grass, merged dressing: plain `Transform`/`Shape`/`Model`) needs it, or Low draws the place standing on nothing. The mark is read from the scene file, so it says nothing of an actor spawned while playing (those were never hidden); any other value, or none, is an actor as before. The scene editor has no control for it (it is written in the file) and keeps it through a save, and a duplicated actor carries it. 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. |
91
+ | `cues` | boolean | v1.23, the deck's (not a place's). `true`, in a town (a place with no `result`): (a) while someone in the roster with a known user id is not named by the host as a friend, the host is asked for the player's friends again a few times in the ~16 s after they were first seen (at about 1, 3, 9 and 15 s -- v1.32; 1, 5, 10, 16 in v1.31; 2, 6, 11 and 17 s before, when the host learned who is in a town only on its heartbeat; those here when the player came in count from then), because the host names a friend only once it knows both are in the town (within a few seconds in the same layer, on its heartbeat across layers) -- never while an ask is out, at most two such asks in any 8 s and 2 s apart however many come in (one in 4 s before v1.32), stopping when the host names them or they leave, the ordinary 20 s ask after that, and a friend already here when the player came in is announced as one who arrives later is ("amy is here · People to join", pointed to), once per friend per session and not where "You're next to amy" said it; (b) the chat field's placeholder says who reads a line ("To your follows…"; the whole sentence is its accessible label) or, disabled, "Friends only" with one sentence as its note and label whatever the reason, so neither tells which it is (v1.29: "Typed chat is for friends who follow each other. Emotes work with everyone."; before v1.29 "No follows here" / "Chat not available" and the longer notes), and the host is asked for chat peers within about a second of someone coming in; (c) "Let's play…" names the door of the speaker's open party proposal before the door they stand by; (d) a party that gains a member says so ("You joined amy's party", "bo joined your party"); (e) v1.29: a player back from a game through one of the town's doors is asked, for 20 s and after any invitation or party proposal, "Play <door> again?" -- Play again is the Doors list's Go for that door (onto its pad; in a party, and for a door that is not `solo`, "Play <door> again together?" / Go together, which proposes it to the party), Not now puts it away. Who is a friend is only what `Hub.friends` already says, and a party is the place's own; chat's rules are ghost's, unchanged. `false` or absent: none of it -- the deck is sent and draws exactly what it did. |
86
92
 
87
93
  Unknown keys are a check failure, not ignored: a typo in a contract field must
88
94
  not publish as "no such rule".
@@ -172,11 +178,13 @@ of any of these. Every hook gets `hub`, the place's context, first:
172
178
  | `hub.spawn(fromActorId, { x, y, z, rotationY }?)` / `hub.despawn(id)` | a copy of a scene actor for everyone, returning its id (§10, v1.2) |
173
179
  | `hub.tune(playerId, { speed, jump })` | one player's own walk controller, as multipliers of the preset (§6, v1.2); `null` puts the preset back |
174
180
  | `hub.drop(playerId?)` / `hub.holding(playerId)` | v1.3: whoever holds an object lets go (default: everyone; a goal, a whistle), returning how many were told; the actor id a player holds, or null (§6) |
181
+ | `hub.keepFor(actorId, playerId \| null)` | v1.27: keep a loose (dynamic) object of a place with `grab` for one player: nobody else is offered it or may grab it, and the `grab` hook is not asked about their tries; `null` makes it anyone's again. Returns whether it is now kept as asked: an actor that is not a dynamic one of the scene, a player who is not here, or a place without `grab` is warned about once, returns `false` and changes nothing (§6) |
175
182
  | `hub.emote(playerId, id)` | v1.6, a place with `idle.emotes`: play a kit emote (`"wave"`, `"dance"`, `"cheer"`, `"bow"`, `"spin"`) on a player's avatar for everyone, without the hook or the rate a player's own request has; true when it took (§6) |
176
183
  | `hub.seat(playerId)` | v1.6: the seat actor id a player sits on, or null (§6) |
177
184
  | `hub.sound(actorId, file, { loop, volume, radius }?)` | v1.6, a place with `idle.sounds`: play one of them at a scene actor for everyone, `volume` 0-1 (default 1), silent `radius` metres away (1-60, default 20); a loop plays until `hub.sound(actorId, null)`; true when it took (§6) |
178
185
  | `hub.mark(playerId, { text, color })` | a coloured tag over a player's avatar for everyone: a team, who is it; `null` clears it (§11, v1.1) |
179
- | `hub.wear(playerId, { kind, color, rarity })` | put a wearable on a player's avatar, kept on their account in every hub place where the host runs the hub: `kind` `"halo"`, `"aura"` or `"orbit"`, `color` `#rrggbb`, `rarity` 0-9; `null` takes it off; true when taken (§11, v1.4) |
186
+ | `hub.wear(playerId, { kind, color, rarity })` | put a wearable on a player's avatar, kept on their account in every hub place where the host runs the hub: `kind` `"halo"`, `"aura"`, `"orbit"` or, v1.24, a hat `"hat-<id>"`, `color` `#rrggbb`, `rarity` 0-9; `null` takes it off; true when taken (§11, v1.4) |
187
+ | `hub.tryOn(playerId, { kind, color, rarity } \| null)` | v1.28: show a wearable on a player in this place only, instead of the one they own, until `null`, their leaving or the place's end. Never saved: nothing goes to ghost, the wearable on the account is neither read nor changed, and no other place hears of it. The same shape and refusals as `hub.wear`; true when taken (§11) |
180
188
  | `hub.label(actorId, text, { style, ttlMs, to }?)` | words over a scene actor for everyone, or with `to: [playerIds]` for those players only (theirs replace everyone's until cleared the same way): `style` `"tag"` (a pad's count), `"speech"` (an NPC's line) or `"sign"` (a street's or a building's name, drawn at any distance in a town), ≤ 64 chars; `null` clears it (§10). An NPC body's own `say` (§13) runs to 240 chars and its bubble is kept on screen |
181
189
  | `hub.npc(actorId)`, `hub.npcs()` | the place's NPC bodies (§13) |
182
190
  | `hub.results(playerId)` | ghost's record of a player's hub results: `{ recent, records, readAt }` -- their newest results across places and their record per place -- or null (dev serve, anonymous). Read at arrival and once a minute for everyone here (§7, v1.5) |
@@ -274,8 +282,10 @@ layer door. On the dev serve the door is a `deck:<name>` door like any other.
274
282
  - A late joiner arrives the same way, alone.
275
283
  - **Jumping to a door.** In a town (a place with no `result`) the chrome's Doors
276
284
  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
285
+ `HubPad` actor naming it, v1.10: inside its radius, so the pad counts them;
286
+ v1.20: on a spot no one stands within 1.1 m of, a ring 1.2 m about its
287
+ middle first, then nearer its edge, then the middle, else the spot with the
288
+ most room), facing the door, or 7 m in front of a door with no pad, in the
279
289
  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
290
  has no list.
281
291
  - **Where a player came from** is ghost's arrival where the host has hub ops
@@ -299,6 +309,22 @@ layer door. On the dev serve the door is a `deck:<name>` door like any other.
299
309
  trail the runtime's first join is made again into the place already loading,
300
310
  anywhere deeper the player leaves by that place's way back, twice at most.
301
311
  Acquisitions and `Hub.cancel` run one at a time.
312
+ - **A place replaced under its players (v1.18).** When a place's session ends
313
+ under a player who is not on a trip (a new version of it was saved, or its
314
+ server stopped): a game is left as before ("The game ended", then its way
315
+ back); any other place reached through a door (the host's trail holds the
316
+ trip) is left by its way back at once, with a line saying it was updated
317
+ ("This place was updated. Back to <the place left>…"), and is entered again
318
+ through its door, which acquires the new version and its content. A join
319
+ cannot be made again from inside such a place: its handoff is spent, and
320
+ only a door's acquisition names the release to mount. The way back is asked
321
+ once per ending; one that is refused leaves the player where they are with
322
+ the host's Back control, as any refused way back does. The town itself, at
323
+ the root of the host's trail, joins again where it stands with the join the
324
+ runtime began with ("Reconnecting…"; the kit did this before v1.18, and it
325
+ is written down here). A player barred from the hub is neither sent back nor
326
+ joined again. The place's server sees nothing new: the players of the old
327
+ session had `leave`, and those who walk back in `arrive` like anyone.
302
328
  - **A cabinet's trip (v1.7).** A `hub-go` with `classic` is a hub trip with no
303
329
  destination session and no content. The client asks `Hub.go(door)`, which a
304
330
  host that can play classic decks answers `{ status: 'ok', kind: 'classic' }`
@@ -328,7 +354,9 @@ layer door. On the dev serve the door is a `deck:<name>` door like any other.
328
354
  <door> pad" for a `HubPad` actor's circle, "near <door>" within 7 m of a
329
355
  door, else the place's `where` hook (§4), else "in town". Join
330
356
  (`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
357
+ door does, but never on a door's pad nor at its edge, theirs included (v1.19:
358
+ beside a friend on a pad is just off its edge, so joining their game is a
359
+ step the player takes): a town only, at most once a second, never a held player, never
332
360
  across a block; a sitter stands first. The server does not know who is whose
333
361
  friend, so it moves a player beside any player of the session they may see;
334
362
  only the chrome's list limits Join to friends. Find moves nobody: it puts
@@ -402,7 +430,9 @@ layer door. On the dev serve the door is a `deck:<name>` door like any other.
402
430
  - **Exit** is always through the door the player came in by: the hub-drawn Back
403
431
  control, `hub.end`, `maxDurationSec`, a crash or a republish. The game cannot
404
432
  name the destination; the client's return ticket does (ghost's, once it
405
- exists). Returning players come out at that door, facing the square.
433
+ exists). Returning players come out at that door, where and facing the way
434
+ the place puts them (the town: in front of it with their back to it, so the
435
+ follow camera, which starts behind them, stands over the street).
406
436
 
407
437
  ## 6. Controller presets
408
438
 
@@ -464,6 +494,100 @@ and at a game's end. `hub.drop(playerId?)` makes a player let go (a goal, a
464
494
  whistle): the object falls where it is. A place without `grab` draws no button
465
495
  and is sent exactly what it was.
466
496
 
497
+ **A steadier offer (v1.22).** The offer is tested afresh every frame: within
498
+ the reach, within 60 degrees of facing, and this client's to simulate (the
499
+ multiplayer kit hands an object to the nearest player). At any of those edges
500
+ -- a player turning, two players near one object -- the button comes and
501
+ goes, and on a phone a press lands on nothing. A place may set, in `grab`:
502
+
503
+ - `reach` (1.6-3 m): objects are offered this far from their near side instead
504
+ of 1.6 m.
505
+ - `steady: true`: once an object is offered, it stays the one offered while
506
+ its near side is within the reach and 0.4 m more and it is within 90
507
+ degrees of facing, even when another is nearer. When it fails that for a
508
+ moment -- briefly someone else's to simulate, a turn past the cone, a step
509
+ back -- the button stays up for 600 ms. A press in that time waits up to
510
+ 500 ms for the object to pass the test again (this client's own included)
511
+ and grabs it then; if it does not, the press is dropped. Another object
512
+ that passes the ordinary test takes the offer over meanwhile.
513
+
514
+ With either set, an object is also never offered when its centre is more than
515
+ 3 m from the player's, and less the faster the player is moving (their body's
516
+ speed, jumps included, or their tuned speed, over the 0.2 s the server's view of
517
+ them may trail), keeping inside the server's 4 m in ordinary play; a grab the
518
+ server still refuses is let go, as any refused grab is. Nothing changes on the server: it checks every grab
519
+ as it always has, and the client still sends a grab only for an object that
520
+ is its own at that moment. A place that sets neither runs the offer it always
521
+ did, and is sent and drawn exactly what it was.
522
+
523
+ **A held object kept (v1.25).** The multiplayer kit hands a loose object to
524
+ whichever player is nearer, a held one included: a player standing close to
525
+ someone carrying something takes it out of their hands, and the hold ends. A
526
+ place that sets `keepHeld: true` in `grab` keeps a held object its holder's:
527
+ from the grab the server accepts until the hold ends, nobody else is granted
528
+ the object, however near they stand, so it cannot be taken, pushed or
529
+ grabbed by another player. The hold ends as it always has -- a throw,
530
+ `hub.drop`, a refused grab, the place hiding the object, `hub.reset`, the
531
+ player held still (§8), leaving, the game's end for them, the object handed
532
+ back to the server (the holder's reports stopped for 1.5 s, or one moved it
533
+ too fast) -- and on each of those the object is at once anyone's again; a
534
+ reset object keeps the reset's own half second first. While it holds, the
535
+ holder's client says so once a second (`hub-grab` with `op: "hold"`, §12),
536
+ and the server keeps the object for 2.5 s past the last word: a client that
537
+ let go by itself (a trip, the talk panel) or one from before v1.25 says
538
+ nothing, and the object is anyone's again within that time, as it was before
539
+ v1.25. The word renews only a hold still in force: one the server accepted
540
+ (the `grab` hook included) and has not since ended or refused, by a player
541
+ who has arrived, is not held and whose game has not ended, of an object that
542
+ is theirs to simulate and within 6 m of their body by the server's own
543
+ poses. Past that distance the hold is over, at the next tick or word. What the
544
+ place's `grab` hook does while it is asked stands: if it drops that player,
545
+ hides or resets the object or holds the player still, even undoing it before
546
+ it returns, the grab is refused (`hub-grab-deny`) rather than held. The grab
547
+ is also checked again after the hook, as it was before it, and refused the
548
+ same way if the hook ended the player's game, moved them out of reach or
549
+ took the object from them. Taking a held object from its holder is the place's to do
550
+ (`hub.drop`, the `grab` hook). A place without `keepHeld` hands a held object
551
+ to a nearer player exactly as before, and is sent nothing new.
552
+
553
+ **An object kept for one player (v1.27).** The Grab button offers the nearest
554
+ loose object, and where a place gives each player one of their own (a pillow,
555
+ a ball) the nearest is often someone else's: the place's hook refuses it, and
556
+ the player's own, a step farther, is never offered. `hub.keepFor(actorId,
557
+ playerId)` keeps a loose object for one player:
558
+
559
+ - **The offer.** Every client is told whose it is (`hubKept`, §12), and no
560
+ other player is offered it: it is passed over, so the nearest object a
561
+ player may take is the one offered, their own included when another's lies
562
+ nearer. With `grab.steady` it does not hold the offer either: an object
563
+ that becomes someone else's while it is offered gives the button up at
564
+ once, grace and waiting press included.
565
+ - **The server.** A grab of it by anyone else is refused (`hub-grab-deny`)
566
+ after the checks every grab passes and **before the place's `grab` hook,
567
+ which is not called for it**. The keeper's grab is checked, put to the hook
568
+ and held exactly as any grab is. Someone else holding the object when it is
569
+ kept lets go (`hub-drop`, as `hub.drop` tells them). A hook that keeps the
570
+ object for another player while it is asked about a grab refuses that grab.
571
+ - **How long.** Until `hub.keepFor(actorId, null)`, until the place hides the
572
+ object (`hub.hide`; shown again it is anyone's), and until its player
573
+ leaves. It outlives `hub.reset`, a throw and a hold. A place that wants it
574
+ kept across a hide calls `keepFor` again after `hub.show`.
575
+ - **What it takes.** A place with `grab`, a dynamic actor of its scene (hidden
576
+ or not), and a player who is in the place (from their `arrive`). Anything
577
+ else is warned about once in the server log, returns `false` and leaves the
578
+ mark as it was; `null` for an object kept for nobody is fine.
579
+
580
+ It decides who may **grab** an object, not who simulates it. The multiplayer
581
+ kit still hands a loose object to the nearest player in reach, and a client
582
+ is offered only an object that is its own to simulate, so a keeper is offered
583
+ their object when they are the nearest player to it, and not while another
584
+ player stands nearer (that player is not offered it, and may still push it
585
+ by walking into it). A place that needs more puts the object beside its
586
+ keeper (`hub.reset(actorId, at)`). Like every refusal here it binds the hub
587
+ client: see the next paragraph. A place that never calls `hub.keepFor` is
588
+ offered, asked and sent exactly what it was: `hubKept` is not sent until
589
+ something is kept.
590
+
467
591
  A refusal and `hub.drop` bind the hub client, which is the only client a hub
468
592
  place has; they do not take the object from its owner on the server. A
469
593
  modified client can carry a loose object it owns whatever the place says,
@@ -634,6 +758,46 @@ hub.setHud({ text: 'you are it!' }, playerId); // one player's override; null c
634
758
  Longer strings are cut, other keys dropped. A per-player spec replaces the
635
759
  shared one for that player.
636
760
 
761
+ **A clear HUD (v1.26).** The HUD hangs from the top middle of the screen, and
762
+ on a phone that is where much of what the hub draws over the world lands too:
763
+ with a title, a 56 px big line and a text line the box is over 100 px tall, the
764
+ text line is the part pushed farthest down, and a label, a goal chip or a
765
+ speech bubble near the top is drawn across it. A place whose manifest sets
766
+ `hud: { clear: true }` (§1) is drawn by these rules instead
767
+ (`code/client/hudClear.js`):
768
+
769
+ - **A smaller big line over a text line.** When the HUD shows both a big line
770
+ (`big`, or the timer standing in for it) and `text`, the big line is 32 px
771
+ (28 px on a short view, below), on one line. One too wide for its row (the
772
+ HUD's 70% of the view's width, less the Back button's side where one is
773
+ shown, never under half the view) shrinks to fit, never below 18 px; past
774
+ that it is cut with an ellipsis rather than wrapped. A big line with no text
775
+ under it keeps its 56 px and wraps as it always did.
776
+ - **Nothing under the HUD.** Whatever the hub chrome places over the world
777
+ whose box would lie over the HUD's box as drawn (measured, so it follows the
778
+ HUD's content) is moved straight down to 6 px under it: actor labels and
779
+ signs, speech bubbles (an NPC's line, a player's phrase, chat), a player's
780
+ mark, an emote, a seat's or object's prompt, the pointers to goals (v1.13)
781
+ and friends, a cabinet's card and the result ribbon. Nothing is hidden,
782
+ moved sideways or moved up; what is beside the HUD or already under it stays
783
+ where it was. Nothing is moved off the bottom of the view: a thing too tall
784
+ to lie both under the HUD and whole on screen (an open cabinet board on a
785
+ phone on its side) moves only as far as keeps its bottom edge in view, and
786
+ the HUD is left over its top. Two things moved under it may overlap each
787
+ other. While no HUD is drawn nothing moves.
788
+ - **A short view.** On a view 480 px tall or less that is wider than it is
789
+ tall (a phone on its side) the text line keeps to two lines (cut with an
790
+ ellipsis) and the box to 40% of the view's height. A portrait view is never
791
+ short, however small (the web player's card on a 360 px phone is about
792
+ 475 px tall).
793
+
794
+ The option is the place's: a game behind a town's door is drawn by the town's
795
+ client, which is told by the game's server (`hubPlace.hud`), so the game's own
796
+ manifest decides either way it is opened, and the town's own HUD is not
797
+ changed by a game that asks. A town running a kit older than v1.26 draws the
798
+ game as before. Fixed chrome (the Back button, an invitation card, the
799
+ buttons) is not moved.
800
+
637
801
  ## 10. Actor visibility
638
802
 
639
803
  `hub.hide(actorId)` removes a scene actor for everyone: its server body is
@@ -818,6 +982,21 @@ The latest call wins; `hub.wear(playerId, null)` takes it off everywhere.
818
982
  rarity); a kind it does not know is kept but not drawn, so a later kit may
819
983
  draw more. `color` is `#rrggbb`; `rarity` an integer 0-9, which grows the
820
984
  pieces and their glow a little.
985
+ - **Hats (v1.24).** A `kind` of `hat-<id>` is a hat the kit draws on the
986
+ avatar's head, turning with it: `sweatband`, `cap`, `foam-crown`, `laurel`,
987
+ `bat-clip`, `witch`, `lantern`, `crooked-top`, `straw`, `flower-crown`,
988
+ `beekeeper`, `sunflower`, `sailor`, `souwester`, `captain`, `lighthouse`
989
+ (`hub.wear(playerId, { kind: 'hat-straw', color: '#e8c96a', rarity: 0 })`).
990
+ A place's server reads the list from the kit, `HATS` (and `HAT_SETS`, the
991
+ same ids four to a set) in
992
+ `@imports/castle.hub-game/code/client/hats.js`, so it offers only hats
993
+ every client draws. `color` is the hat's main colour; a band, brim or trim
994
+ is the hat's own. `rarity` is kept and changes nothing: a hat is one size,
995
+ fitted to each avatar in each set, and does not glow. A hat is one to three
996
+ plain shapes, drawn for the players a client is sent (`nearestPlayers`, §1) at every
997
+ device tier, as the other wearables are. A `hat-` id not in the list is a
998
+ kind the kit does not know: kept, not drawn. Still one wearable per account:
999
+ a hat replaces a halo and a halo a hat.
821
1000
  - Ghost takes a wearable only from a curated hub place (an enabled door leads
822
1001
  into or out of it, the avatar's rule), only for a signed-in player, and at
823
1002
  most 30 changes a minute per player; the host checks the shape first.
@@ -832,6 +1011,46 @@ The latest call wins; `hub.wear(playerId, null)` takes it off everywhere.
832
1011
  A prize from a roll, a crown for the day's champion: the reason a game is
833
1012
  worth playing elsewhere.
834
1013
 
1014
+ **Trying one on (v1.28).** `hub.wear` saves: it replaces the one wearable the
1015
+ account keeps, so a place that only wants to dress a player for a while (a hat
1016
+ on a shop's mat before it is bought, a costume for one visit) would take away
1017
+ the hat they paid for, and has no way to read it first to put it back.
1018
+ `hub.tryOn(playerId, { kind: 'hat-witch', color: '#3a2a4a', rarity: 0 })`
1019
+ shows a wearable on the player **in this place only, without saving it**:
1020
+
1021
+ - **What is drawn.** While it is up, every client in the place draws it on
1022
+ the player instead of the wearable they own (the player included, over
1023
+ their own body), the same pieces `hub.wear` would draw. One per player: the
1024
+ latest call wins. A kind the kit does not draw is kept and draws nothing, so
1025
+ the player is bare-headed until it clears.
1026
+ - **What is not touched.** Nothing goes to ghost and nothing is read from it:
1027
+ the wearable on the account, and this place's copy of it (`hubWear`), are
1028
+ what they were throughout. No other place is told, the town included.
1029
+ - **How long.** Until `hub.tryOn(playerId, null)`, until the player leaves
1030
+ the place (theirs goes with them, as a mark does) or until the place ends.
1031
+ Then the wearable they own is drawn again, or nothing if they own none. A
1032
+ place holds at most one per player who is in it. As `hub.wear` does, it
1033
+ takes a player who has a body and whose client has not said hello yet: the
1034
+ try-on is shown from their hello, and goes with them if they leave before it.
1035
+ - **Every tick is fine.** Asking for the wearable a player already has on
1036
+ sends nothing: a shop may call it from `step` for whoever stands on a mat.
1037
+ A guest is dressed like anyone else; no account is involved.
1038
+ - **With `hub.wear`.** The two do not meet. A `hub.wear` made while a try-on
1039
+ is up saves exactly as it does without one (to ghost, into `hubWear`) and is
1040
+ not what is drawn until the try-on clears, when it shows; `hub.wear(playerId,
1041
+ null)` under a try-on takes the saved one off and leaves the try-on up. To
1042
+ sell the hat a player has on, `hub.wear` it and clear the try-on.
1043
+ - **Refused, and logged once**, as `hub.wear` refuses: a player who is not
1044
+ here, or a wearable that is not exactly `{ kind, color, rarity }` in range
1045
+ (`null`, or no second argument, clears). A refused call changes nothing.
1046
+ - **Old kits.** It is on by use: a place that never calls it is sent and
1047
+ drawn exactly what it was. A game that must run on a kit before v1.28 asks
1048
+ first (`typeof hub.tryOn === 'function'`). A place reached through a door
1049
+ is drawn by the client of the deck the player started in, so a town saved
1050
+ before v1.28 ignores `hubTry` and goes on drawing what the player owns:
1051
+ nothing breaks, the try-on is simply not seen there until that deck is
1052
+ saved again.
1053
+
835
1054
  ## 12. Wire (kit-internal, listed so a host or bot can speak it)
836
1055
 
837
1056
  Client → server: `{ k: 'hub-hello', avatar, from, party, carry }` once per session join
@@ -841,7 +1060,7 @@ Client → server: `{ k: 'hub-hello', avatar, from, party, carry }` once per ses
841
1060
  `{ k: 'hub-say', r }` or `{ k: 'hub-say', p }` (v1.11, §6);
842
1061
  `{ k: 'hub-party', op, player?, door? }` (v1.10, §5: `op` `"invite"` with `player`, `"accept"` and `"decline"` with `from` (the inviter), `"leave"`, `"go"` with `door`, `"go-yes"` and `"go-no"` with `id` (the proposal's));
843
1062
  `{ k: 'hub-where', ids }` (v1.9: where up to 12 players of this session are, at most once per 700 ms) and `{ k: 'hub-goto', player }` (v1.9: Join, §5);
844
- `{ k: 'hub-grab', actor, op }` (v1.3, `op` `"grab"` or `"throw"`, §6);
1063
+ `{ k: 'hub-grab', actor, op }` (v1.3, `op` `"grab"` or `"throw"`, §6; v1.25, `"hold"` once a second while holding, only in a place with `grab.keepHeld`, dropped unheard by any other);
845
1064
  `{ k: 'hub-emote', id }`, `{ k: 'hub-sit', seat }`, `{ k: 'hub-stand' }` (v1.6, §6);
846
1065
  `{ k: 'hub-npc-open', npc }`, `{ k: 'hub-npc-say', npc, text }` (authored mode
847
1066
  only), `{ k: 'hub-npc-end', npc }` (§13).
@@ -854,9 +1073,18 @@ actor id → `#rrggbb`), `marks` (v1.1, player id → `{ text, color }`), `hubDo
854
1073
  has worn one, and like `hubAv` without the players in a hidden pair), and in a
855
1074
  place with `idle` (v1.6) only the parts it turns on: `hubEmotes` (player id →
856
1075
  `{ id, at, until }`, simulation ms), `hubSeated` (player id → seat actor id),
857
- `hubSounds` (actor id → `{ file, volume, radius, since }`, the loops playing).
1076
+ `hubSounds` (actor id → `{ file, volume, radius, since }`, the loops playing);
1077
+ and `hubKept` (v1.27, actor id → the player id it is kept for, §6; only once
1078
+ the place has kept an object with `hub.keepFor`, then whenever it changes,
1079
+ `{}` once when the last is gone, and in the snapshot only while something is
1080
+ kept); and `hubTry` (v1.28, player id → `{ kind, color, rarity }`, the
1081
+ wearable the place shows on that player instead of their own, §11; the same
1082
+ rule: only once the place has called `hub.tryOn`, then whenever it changes,
1083
+ `{}` once when the last is gone, in the snapshot only while one is shown, and
1084
+ like `hubWear` without the players in a hidden pair). A client lays it over
1085
+ `hubWear`; one that does not know it draws `hubWear` alone.
858
1086
  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
1087
+ 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
1088
  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
1089
  `{ 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
1090
  `{ k: 'hub-arrived', facing }`, `{ k: 'hub-jumped', facing }` (after a jump to a door or, with `to` the player, to a player, §5),
@@ -865,10 +1093,16 @@ client: `{ k: 'hub-go', door, key, place, scene, title, party }` (in production
865
1093
  override), `{ k: 'hub-tune', tune }` (v1.2, that player's `{ speed, jump }` or null), `{ k: 'hub-labels', labels }` (that player's own labels),
866
1094
  `{ k: 'hub-result', result }`, `{ k: 'hub-end', why }`,
867
1095
  `{ 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? }`,
1096
+ `{ 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
1097
  `{ 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
1098
  hidden pair that this player may see, laid over the shared `hubAv`), `{ k: 'hub-wear', hubWear }`
871
- (v1.4, their wearables, laid over the shared `hubWear` the same way).
1099
+ (v1.4, their wearables, laid over the shared `hubWear` the same way),
1100
+ `{ k: 'hub-try', hubTry }` (v1.28, their try-ons, laid over the shared
1101
+ `hubTry`; only in a place that has called `hub.tryOn` with a hidden pair in
1102
+ it. Once a place has sent one, a client that joins afresh -- a `hub-hello`
1103
+ without `again` -- is sent the map as it is, empty or not, so one that comes
1104
+ back holds neither a try-on that came off while it was away nor misses one
1105
+ that is up; a client keeps it across a snapshot).
872
1106
  Version-tagged by `hubPlace.contract`.
873
1107
 
874
1108
  Blocks: two players a block hides from each other (either one blocked the
@@ -988,18 +1222,32 @@ door that names its own session.
988
1222
  | `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
1223
  | `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
1224
  | `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) |
1225
+ | `disclosure` | `"participants"` or `"world"`: read, and since v1.17 not acted on. A player's conversation with a character is theirs alone (below) |
992
1226
  | `followSec` | 10-600, default 120: how long a body follows before it goes home |
993
1227
 
994
1228
  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
1229
+ for the player the body is talking to, near it, with no listener of any kind,
1230
+ within the character's `turnsPerMinute`; anything else is refused
997
1231
  before a model is called, and over budget the place's `budget` line answers
998
1232
  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
1233
+ is ghost's text, shown in the speaker's panel and over the body for the
1234
+ speaker alone.
1235
+
1236
+ **A player's conversation is theirs alone (v1.17).** What a player types to a
1237
+ character, and what the character answers, reaches no other player: not as a
1238
+ bubble, not through the character's memory, not in another layer or a later
1239
+ session. Ghost keeps a turn's words for everyone its audience names (a listener
1240
+ reads them back and the character may repeat them), so a turn names no player
1241
+ and no character as a listener and is never `world`-disclosed: the kit's
1242
+ client sends an empty audience, the kit's server refuses any other
1243
+ (`HUB_NPC_AUDIENCE`), and ghost keeps a place mind's conversations per player
1244
+ whatever a client sent. The character still remembers the same player
1245
+ tomorrow: its memory of them is that player's own. Only words with nothing of
1246
+ any player's typing in them are public: authored lines, ambient lines, and
1247
+ what a mind says from ghost's verified news. A place must keep it so: never
1248
+ put what a player typed (`npcHeard`'s and `npcLine`'s `text`) into a line, a
1249
+ label, a HUD, storage another player reads, or another player's notes.
1250
+ A body follows a player
1003
1251
  only when its character chose its follow action (an action whose object effect
1004
1252
  hands the `follow` object to `"player"`); clients cannot start or aim it. The
1005
1253
  follow object is one per place, so only the body in the holder's layer follows.
@@ -1105,6 +1353,24 @@ Minor additions, each optional; a deck written before them reads the same.
1105
1353
 
1106
1354
  | date | change |
1107
1355
  | --- | --- |
1356
+ | 2026-10-04 (v1.32) | §2 `cues` (a): the extra friends asks come at about 1, 3, 9 and 15 s, bounded as two in any 8 s at least 2 s apart (was one in 4 s): measured on production after v1.31, the ask at 1 s often came back before the host had both connections and the next was 4 s later. The same number of asks over time (15 a minute, 16 in the worst-placed minute), four for someone never named. A deck without `hub.cues` asks exactly as before. |
1357
+ | 2026-10-04 (v1.31) | §2 `cues` (a): the extra friends asks come at about 1, 5, 10 and 16 s after someone is first seen (were 2, 6, 11, 17), and may follow any ask by 1 s (was 2). The host now names a mutual follow in the same layer within a few seconds of their joining, so the first of these is the one that tells a player their friend is here. Still at most one extra ask in 4 s, 15 a minute, four for someone never named. A deck without `hub.cues` asks exactly as before. |
1358
+ | 2026-10-04 (v1.30) | §1 `tiers`: `"tier": "keep"` on an actor in a scene file (beside `id`, not a component) has it drawn on every tier. Low does not draw an actor with only `Transform`/`Shape`/`Model`, which is what the hub world's ground is (paving, grass, the running track, merged per-cell dressing), so on Low its stalls and benches stood on black; giving ground a `Solid` or `Lookable` it does not need was the only way round. A marked actor is never taken out by Low: not as decoration, not as scenery past 30 m, not as an NPC body past 20 m. Client only, read from the scene file with the ids the tiers already read there; a scene with no mark, and a deck without `tiers`, are drawn exactly as before |
1359
+ | 2026-10-04 (v1.29) | §2 `cues`: the chat field that cannot be used reads "Friends only" with one sentence as its note and label for every reason ("Typed chat is for friends who follow each other. Emotes work with everyone."), and (e) a player back from a game through a door is asked "Play <door> again?" for 20 s. Behind `hub.cues`, a town only; a deck without it is unchanged. |
1360
+ | 2026-10-04 (v1.28) | §4 and §11 `hub.tryOn(playerId, { kind, color, rarity } \| null)`: a wearable shown on a player in this place only, instead of the one they own, until `null`, their leaving or the place's end. `hub.wear` was the only way to put anything on a player's head and it saves to the account, replacing what the player owns (a hat bought in the town) with no way to read it first: the town's hat shops want a try-on on a mat, and Trick-or-Treat Lane a costume for the visit (it had fallen back to a tag alone). Nothing is written to ghost or read from it; `hubWear` is unchanged by it; a `hub.wear` during a try-on saves as before and shows when the try-on clears. `hubTry` and `hub-try` (§12) tell clients, only once a place has called it; no manifest key. A client older than v1.28 ignores both and draws the owned wearable. A place that never calls it is sent and drawn exactly what it was |
1361
+ | 2026-10-04 (v1.27) | §4 and §6 `hub.keepFor(actorId, playerId \| null)`: a loose object kept for one player. No other player is offered it (their client passes it over for the next nearest, and it gives up a `steady` offer at once), and anyone else's grab of it is refused on the server before the place's `grab` hook, which is not called; the keeper's grab is unchanged. Ends with `null`, `hub.hide` and the player's leaving; outlives `hub.reset`. `hubKept` (§12) tells clients, only once something is kept. Pillow Dojo playtests and bots: each player has a pillow of their own, the button offered the nearest pillow, the hook answered NOT YOURS, and the player's own a step farther was never offered. It does not change who simulates an object: a keeper is offered theirs only while they are the nearest player to it. A place that never calls it is offered, asked and sent exactly what it was |
1362
+ | 2026-10-04 (v1.26) | §1 and §9 `hud: { clear: true }`: a place may ask for a clear HUD -- a big line drawn at 32 px on one line (shrunk to fit, at least 18 px) when a text line is under it, everything the hub chrome places over the world (labels, speech, marks, emotes, goal and friend pointers, a cabinet's card, the result ribbon) moved to just under the HUD's box when it would lie over it, and on a view 480 px tall or less the text kept to two lines and the box to 40% of the height. Playtests of ten games, most testers, on a phone: "the big banner covers the instructions", "labels overlap the HUD text", "HUD line cut off". The place's own key, told to the client in `hubPlace.hud`, so it holds whether the place is opened directly or through a town's door. A place without it is read, sent and drawn exactly what it was. |
1363
+ | 2026-10-04 (v1.25) | §1 and §6 `grab.keepHeld`: a held object stays its holder's until the hold ends, instead of going to whichever player stands nearer (the multiplayer kit's rule for every loose object); the holder's client says `hub-grab` `op: "hold"` once a second (§12) and the server keeps the object 2.5 s past the last. Flop Park playtests, 3 of 4 players: a carried dummy left its holder's hands whenever the other player came close. A place without `keepHeld` is sent, simulated and drawn exactly as before |
1364
+ | 2026-10-04 (v1.24) | §11 hats: the kit draws the wearable kinds `hat-<id>` for sixteen ids, listed for a place's server in `code/client/hats.js` (`HATS`). The town is to sell hats, and a `hat-` kind was already stored and relayed but drawn by nothing. No field, message or manifest key is new: ghost and the kit's server took any lowercase kind before. A place where nobody wears a hat is sent and drawn exactly what it was |
1365
+ | 2026-10-04 (v1.23) | §1 `cues`: a town may tell its players more about the friends and party they came with. Two-player playtests of the town: a friend who came in was not known as one for up to 20 s (so no "is here", no pointer, a disabled chat field for up to 15 s more), a friend already there was never announced, the chat field did not say who reads it, "Let's play…" named the nearest door rather than the one the party was asked to, and joining a party showed nothing. With `cues`: the friends ask is repeated a few times in the ~17 s after someone unnamed is first seen (the host learns presence on a heartbeat of about 15 s, so one early ask came back empty: measured on production, "is here" 21 s after a friend arrived); a friend already here is announced once; the chat field says who reads it or why it is off, and chat peers are asked for again when someone comes in; "Let's play…" names the party's proposed door; a party's new member is toasted. A deck without `cues` is sent and draws exactly what it did: the server picks the door as before, and the client takes none of the new branches |
1366
+ | 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 |
1367
+ | 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 |
1368
+ | 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). |
1369
+ | 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 |
1370
+ | 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 |
1371
+ | 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 |
1372
+ | 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 |
1373
+ | 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
1374
  | 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
1375
  | 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
1376
  | 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 scripts/test-hats.mjs && node scripts/test-try-on.mjs && node scripts/test-hud-clear.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": {
@@ -76,6 +76,38 @@ let n = 0;
76
76
  assert.deepEqual([calls.at(-1), reported], [['report', 'm1'], true]);
77
77
  n += 1;
78
78
 
79
+ // Cues (contract v1.23): someone came in. With peers the 2.5 s cadence is
80
+ // soon enough and nothing moves; with none the idle wait (15 s) is cut to
81
+ // about a second, once however many came in. Never called without cues.
82
+ {
83
+ const before = calls.filter(([k]) => k === 'chat').length;
84
+ const asks = () => calls.filter(([k]) => k === 'chat').length - before;
85
+ c.soon(4100);
86
+ c.frame(true, 5200);
87
+ await flush();
88
+ assert.equal(asks(), 0, 'peers here: the cadence is its own');
89
+ answer = { status: 'ok', canChat: true, peers: [], cursor: 'c2', messages: [] };
90
+ c.frame(true, 7000);
91
+ await flush();
92
+ assert.deepEqual([asks(), c.peers], [1, []]);
93
+ c.frame(true, 12000);
94
+ await flush();
95
+ assert.equal(asks(), 1, 'nobody to chat with: the idle wait');
96
+ c.soon(12000);
97
+ c.soon(12300);
98
+ c.frame(true, 12900);
99
+ await flush();
100
+ assert.equal(asks(), 1, 'not at once: the host is given a moment');
101
+ answer = { status: 'ok', canChat: true, peers: ['102'], cursor: 'c2', messages: [] };
102
+ c.frame(true, 13000);
103
+ await flush();
104
+ assert.deepEqual([asks(), c.peers], [2, ['102']], 'asked a second after they came in');
105
+ c.frame(true, 13500);
106
+ await flush();
107
+ assert.equal(asks(), 2, 'once for all who came in');
108
+ n += 1;
109
+ }
110
+
79
111
  // An answer that lands after the session changed is the old session's.
80
112
  answer = { status: 'ok', canChat: true, peers: ['102'], cursor: 'c3', messages: [{ id: 'late', fromUserId: '102', fromUsername: 'bo', text: 'late', at: '' }] };
81
113
  c.frame(true, 20000);