castle-web-cli 0.4.237 → 0.4.238

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 (216) hide show
  1. package/dist/bundle.d.ts +24 -0
  2. package/dist/bundle.js +447 -4
  3. package/dist/bundleLatin1.d.ts +6 -0
  4. package/dist/bundleLatin1.js +333 -0
  5. package/dist/castle-host/host.d.ts +10 -1
  6. package/dist/castle-host/host.js +78 -9
  7. package/dist/castleJson.d.ts +2 -0
  8. package/dist/castleJson.js +1 -0
  9. package/dist/deckExports.d.ts +35 -0
  10. package/dist/deckExports.js +365 -0
  11. package/dist/importCheckHook.d.ts +1 -0
  12. package/dist/importCheckHook.js +1 -1
  13. package/dist/index.js +5 -0
  14. package/dist/init.js +2 -1
  15. package/dist/save-deck.js +4 -0
  16. package/kits/base/castle.json +1 -1
  17. package/kits/base/sdk/README.md +47 -0
  18. package/kits/base/sdk/castle.d.ts +3 -1
  19. package/kits/base/sdk/castle.js +1 -0
  20. package/kits/base/sdk/commands.d.ts +25 -1
  21. package/kits/base/sdk/commands.js +29 -1
  22. package/kits/base/sdk/hub.d.ts +17 -0
  23. package/kits/base/sdk/hub.js +33 -9
  24. package/kits/base/sdk/localCache.d.ts +27 -0
  25. package/kits/base/sdk/localCache.js +115 -0
  26. package/kits/base/sdk/localCacheStore.d.ts +15 -0
  27. package/kits/base/sdk/localCacheStore.js +358 -0
  28. package/kits/base/sdk/transport.d.ts +1 -0
  29. package/kits/base/sdk/transport.js +4 -5
  30. package/kits/hub-game/CLAUDE.md +22 -2
  31. package/kits/hub-game/castle.json +4 -1
  32. package/kits/hub-game/code/client/act.js +66 -91
  33. package/kits/hub-game/code/client/actCore.js +134 -0
  34. package/kits/hub-game/code/client/car.js +35 -0
  35. package/kits/hub-game/code/client/chrome.js +207 -381
  36. package/kits/hub-game/code/client/crowdNames.js +2 -2
  37. package/kits/hub-game/code/client/emoteWheel.js +109 -0
  38. package/kits/hub-game/code/client/hats.js +2 -0
  39. package/kits/hub-game/code/client/hookLayer.js +99 -48
  40. package/kits/hub-game/code/client/hostGo.js +77 -0
  41. package/kits/hub-game/code/client/hubControls.js +125 -0
  42. package/kits/hub-game/code/client/hubEntry.js +187 -0
  43. package/kits/hub-game/code/client/hudSurface.js +148 -0
  44. package/kits/hub-game/code/client/hudTree.js +96 -0
  45. package/kits/hub-game/code/client/idle.js +59 -13
  46. package/kits/hub-game/code/client/invites.js +13 -4
  47. package/kits/hub-game/code/client/menuIcons.js +8 -0
  48. package/kits/hub-game/code/client/noTrips.js +38 -0
  49. package/kits/hub-game/code/client/qualityEntry.js +6 -1
  50. package/kits/hub-game/code/client/rehello.js +3 -1
  51. package/kits/hub-game/code/client/riders.js +26 -0
  52. package/kits/hub-game/code/client/role.js +79 -0
  53. package/kits/hub-game/code/client/safeLayout.js +32 -3
  54. package/kits/hub-game/code/client/sound.js +10 -3
  55. package/kits/hub-game/code/client/soundscape.js +2 -2
  56. package/kits/hub-game/code/client/soundscapeAmbience.js +38 -8
  57. package/kits/hub-game/code/client/soundscapeBaked.js +24 -5
  58. package/kits/hub-game/code/client/soundscapeCues.js +2 -1
  59. package/kits/hub-game/code/client/state.js +19 -0
  60. package/kits/hub-game/code/client/stuck.js +2 -1
  61. package/kits/hub-game/code/client/talkSurface.js +178 -0
  62. package/kits/hub-game/code/client/talkTree.js +238 -0
  63. package/kits/hub-game/code/client/tiers.js +8 -5
  64. package/kits/hub-game/code/client/uiDom.js +600 -0
  65. package/kits/hub-game/code/client/uiTree.js +359 -0
  66. package/kits/hub-game/code/client/vehicle.js +154 -0
  67. package/kits/hub-game/code/client/wear.js +27 -5
  68. package/kits/hub-game/code/client/worldLabels.js +3 -2
  69. package/kits/hub-game/code/client/yours.js +10 -3
  70. package/kits/hub-game/code/server/actors.js +4 -3
  71. package/kits/hub-game/code/server/analytics.js +56 -6
  72. package/kits/hub-game/code/server/decor.js +56 -16
  73. package/kits/hub-game/code/server/hub.js +258 -46
  74. package/kits/hub-game/code/server/idle.js +118 -5
  75. package/kits/hub-game/code/server/manifest.js +46 -4
  76. package/kits/hub-game/code/server/npcs.js +4 -2
  77. package/kits/hub-game/code/server/players.js +3 -0
  78. package/kits/hub-game/code/server/role.js +142 -0
  79. package/kits/hub-game/code/server/standing.js +6 -4
  80. package/kits/hub-game/code/server/vehicle.js +126 -0
  81. package/kits/hub-game/code/shared/car.js +52 -0
  82. package/kits/hub-game/code/shared/deckFlags.js +34 -0
  83. package/kits/hub-game/code/shared/deviceClass.js +39 -0
  84. package/kits/hub-game/code/shared/expression.js +9 -0
  85. package/kits/hub-game/code/systems/hub.js +272 -84
  86. package/kits/hub-game/docs/analytics.md +11 -2
  87. package/kits/hub-game/docs/contract.md +352 -14
  88. package/kits/hub-game/docs/vehicle-preset.md +132 -0
  89. package/kits/hub-game/models/hats/baker-cap.pxmodel +89 -0
  90. package/kits/hub-game/models/hats/chef-toque.pxmodel +60 -0
  91. package/kits/hub-game/models/hats/delivery-cap.pxmodel +105 -0
  92. package/kits/hub-game/models/hats/fire-helmet.pxmodel +87 -0
  93. package/kits/hub-game/models/hats/hard-hat.pxmodel +71 -0
  94. package/kits/hub-game/models/hats/nurse-cap.pxmodel +61 -0
  95. package/kits/hub-game/models/hats/police-cap.pxmodel +105 -0
  96. package/kits/hub-game/models/hats/teacher-beret.pxmodel +52 -0
  97. package/kits/hub-game/models/role/square/top-apron.pxmodel +109 -0
  98. package/kits/hub-game/models/role/square/top-cardigan.pxmodel +141 -0
  99. package/kits/hub-game/models/role/square/top-coat.pxmodel +157 -0
  100. package/kits/hub-game/models/role/square/top-scrubs.pxmodel +93 -0
  101. package/kits/hub-game/models/role/square/top-tabard.pxmodel +109 -0
  102. package/kits/hub-game/models/role/square/top-vest.pxmodel +109 -0
  103. package/kits/hub-game/models/role/tool-bag.pxmodel +75 -0
  104. package/kits/hub-game/models/role/tool-bell.pxmodel +71 -0
  105. package/kits/hub-game/models/role/tool-hose.pxmodel +60 -0
  106. package/kits/hub-game/models/role/tool-parcel.pxmodel +61 -0
  107. package/kits/hub-game/models/role/tool-torch.pxmodel +55 -0
  108. package/kits/hub-game/models/role/tool-tray.pxmodel +75 -0
  109. package/kits/hub-game/models/role/top-apron.pxmodel +70 -0
  110. package/kits/hub-game/models/role/top-cardigan.pxmodel +102 -0
  111. package/kits/hub-game/models/role/top-coat.pxmodel +79 -0
  112. package/kits/hub-game/models/role/top-scrubs.pxmodel +54 -0
  113. package/kits/hub-game/models/role/top-tabard.pxmodel +70 -0
  114. package/kits/hub-game/models/role/top-vest.pxmodel +70 -0
  115. package/kits/hub-game/package-lock.json +1 -1
  116. package/kits/hub-game/package.json +1 -1
  117. package/kits/hub-game/scripts/check.mjs +7 -4
  118. package/kits/hub-game/scripts/fixtures/car-vectors.json +279 -0
  119. package/kits/hub-game/scripts/fixtures/decor-keyless-draw.json +2 -1
  120. package/kits/hub-game/scripts/fixtures/hud-surface.json +670 -0
  121. package/kits/hub-game/scripts/fixtures/talk-surface.json +3930 -0
  122. package/kits/hub-game/scripts/gen-hats.mjs +46 -2
  123. package/kits/hub-game/scripts/gen-role.mjs +80 -0
  124. package/kits/hub-game/scripts/test-act-core.mjs +167 -0
  125. package/kits/hub-game/scripts/test-actions-client.mjs +34 -0
  126. package/kits/hub-game/scripts/test-actors.mjs +48 -0
  127. package/kits/hub-game/scripts/test-analytics.mjs +99 -5
  128. package/kits/hub-game/scripts/test-apply-deck.mjs +122 -0
  129. package/kits/hub-game/scripts/test-back-visibility.mjs +3 -1
  130. package/kits/hub-game/scripts/test-ballot.mjs +2 -0
  131. package/kits/hub-game/scripts/test-car.mjs +43 -0
  132. package/kits/hub-game/scripts/test-decor-client.mjs +2 -1
  133. package/kits/hub-game/scripts/test-decor.mjs +77 -0
  134. package/kits/hub-game/scripts/test-device-class.mjs +83 -0
  135. package/kits/hub-game/scripts/test-emote-wheel.mjs +374 -0
  136. package/kits/hub-game/scripts/test-hats.mjs +5 -4
  137. package/kits/hub-game/scripts/test-host-go.mjs +265 -0
  138. package/kits/hub-game/scripts/test-hub-controls.mjs +108 -0
  139. package/kits/hub-game/scripts/test-hub-entry.mjs +531 -0
  140. package/kits/hub-game/scripts/test-hub-ops.mjs +75 -0
  141. package/kits/hub-game/scripts/test-hud-clear.mjs +12 -2
  142. package/kits/hub-game/scripts/test-hud-rate.mjs +6 -2
  143. package/kits/hub-game/scripts/test-hud-surface.mjs +272 -0
  144. package/kits/hub-game/scripts/test-idle.mjs +347 -1
  145. package/kits/hub-game/scripts/test-interest-cells.mjs +8 -1
  146. package/kits/hub-game/scripts/test-invites-client.mjs +42 -1
  147. package/kits/hub-game/scripts/test-manifest.mjs +30 -0
  148. package/kits/hub-game/scripts/test-no-trips.mjs +42 -0
  149. package/kits/hub-game/scripts/test-placement-cache.mjs +1 -1
  150. package/kits/hub-game/scripts/test-quality.mjs +13 -0
  151. package/kits/hub-game/scripts/test-rehello.mjs +258 -3
  152. package/kits/hub-game/scripts/test-resume-pose-server.mjs +203 -0
  153. package/kits/hub-game/scripts/test-resync.mjs +183 -0
  154. package/kits/hub-game/scripts/test-role-client.mjs +421 -0
  155. package/kits/hub-game/scripts/test-role.mjs +350 -0
  156. package/kits/hub-game/scripts/test-safe-layout.mjs +50 -1
  157. package/kits/hub-game/scripts/test-soundscape.mjs +124 -7
  158. package/kits/hub-game/scripts/test-standing.mjs +15 -1
  159. package/kits/hub-game/scripts/test-talk-surface.mjs +296 -0
  160. package/kits/hub-game/scripts/test-tiers.mjs +13 -0
  161. package/kits/hub-game/scripts/test-ui-dom-dom.mjs +96 -0
  162. package/kits/hub-game/scripts/test-ui-tree.mjs +711 -0
  163. package/kits/hub-game/scripts/test-vehicle-client.mjs +159 -0
  164. package/kits/hub-game/scripts/test-vehicle.mjs +135 -0
  165. package/kits/hub-game/scripts/test-yours.mjs +33 -0
  166. package/kits/hub-game/tools/hubScene/export.mjs +613 -0
  167. package/kits/hub-game/tools/hubScene/hubdata.mjs +921 -0
  168. package/kits/hub-game/tools/hubScene/merge-root.mjs +39 -0
  169. package/kits/hub-game/tools/hubScene/nodeworld.mjs +227 -0
  170. package/kits/hub-game/tools/hubScene/test/export-fixture.mjs +798 -0
  171. package/kits/hub-game/tools/hubScene/test/fixture.json +637 -0
  172. package/kits/hub-game/tools/hubScene/test/paint-export.mjs +40 -0
  173. package/kits/hub-game/tools/hubScene/test/upload.test.mjs +655 -0
  174. package/kits/hub-game/tools/hubScene/upload.mjs +636 -0
  175. package/kits/hub-game/tools/hubScene/validate-manifest.mjs +291 -0
  176. package/kits/multiplayer-3d/castle.json +4 -4
  177. package/kits/multiplayer-3d/code/client/resumeGate.js +30 -2
  178. package/kits/multiplayer-3d/code/client/steer.js +3 -1
  179. package/kits/multiplayer-3d/code/systems/multiplayer.js +30 -2
  180. package/kits/multiplayer-3d/package-lock.json +1 -1
  181. package/kits/multiplayer-3d/scripts/test-resume-gate.mjs +74 -2
  182. package/kits/physics-3d/CLAUDE.md +1 -1
  183. package/kits/physics-3d/behaviors/Player.jsx +37 -27
  184. package/kits/physics-3d/castle.json +2 -2
  185. package/kits/physics-3d/docs/engine-geometry-memory.md +23 -0
  186. package/kits/physics-3d/engine3d/memoryprofile.js +17 -0
  187. package/kits/physics-3d/engine3d/playerRun.js +6 -1
  188. package/kits/physics-3d/engine3d/pxmodel.js +6 -1
  189. package/kits/physics-3d/engine3d/world3d.js +6 -3
  190. package/kits/physics-3d/package.json +1 -1
  191. package/kits/physics-3d/play/behaviors/Player.js +40 -28
  192. package/kits/physics-3d/scripts/test-memory-profile.mjs +237 -0
  193. package/kits/physics-3d/systems/physics3d.js +5 -2
  194. package/kits/real-time/castle.json +2 -2
  195. package/kits/real-time/code/client/messages.js +5 -0
  196. package/kits/real-time/code/server/session.js +28 -1
  197. package/kits/real-time/package-lock.json +1 -1
  198. package/package.json +5 -4
  199. package/vendor/three/LICENSE +21 -0
  200. package/vendor/three/build/three.core.js +58773 -0
  201. package/vendor/three/build/three.module.js +18251 -0
  202. package/vendor/three/examples/jsm/controls/OrbitControls.js +1860 -0
  203. package/vendor/three/examples/jsm/controls/TransformControls.js +1918 -0
  204. package/vendor/three/examples/jsm/exporters/GLTFExporter.js +3595 -0
  205. package/vendor/three/examples/jsm/geometries/RoundedBoxGeometry.js +216 -0
  206. package/vendor/three/examples/jsm/math/MeshSurfaceSampler.js +315 -0
  207. package/vendor/three/examples/jsm/postprocessing/EffectComposer.js +363 -0
  208. package/vendor/three/examples/jsm/postprocessing/MaskPass.js +195 -0
  209. package/vendor/three/examples/jsm/postprocessing/OutputPass.js +139 -0
  210. package/vendor/three/examples/jsm/postprocessing/Pass.js +191 -0
  211. package/vendor/three/examples/jsm/postprocessing/RenderPass.js +183 -0
  212. package/vendor/three/examples/jsm/postprocessing/ShaderPass.js +135 -0
  213. package/vendor/three/examples/jsm/shaders/CopyShader.js +52 -0
  214. package/vendor/three/examples/jsm/shaders/OutputShader.js +103 -0
  215. package/vendor/three/examples/jsm/utils/BufferGeometryUtils.js +1435 -0
  216. package/vendor/three/package.json +134 -0
@@ -44,11 +44,11 @@ means own house; bit 0 is set only on the platform-generated first-use marker.
44
44
  | 8 | first_play | Platform first use of a door/activity per town/account/subject within 90 days |
45
45
  | 9 | pointer_stage | First-visit flow stage: subject 0 home, 1 like, 2 play, 3 stamp, 4 done |
46
46
  | 10 | reconnect | Restored connection; never another first arrival |
47
- | 11 | session_end | Connected segment duration; reason unknown (0) |
47
+ | 11 | session_end | Connected segment duration; result 0 left, 1 dropped, 2 continued (below) |
48
48
  | 12 / 13 | furniture_placed / furniture_moved | Accepted owner layout mutation; count in value |
49
49
  | 14 | pet_named | Accepted save name change; only a count, never the name |
50
50
  | 15 | guestbook_signed | Confirmed stamp write; no stamp image, name or text |
51
- | 16 / 17 | house_visit / house_time | Entry and connected segment duration, subject 10; owner flag stamped by platform |
51
+ | 16 / 17 | house_visit / house_time | Entry and connected segment duration, subject 10; owner flag stamped by platform; house_time result as session_end |
52
52
  | 18 | npc_chat_count | Accepted NPC conversation opened; count only |
53
53
  | 19 / 20 | token_earned / token_spent | Confirmed positive amount; no raw transaction strings |
54
54
  | 21 | invite_sent | An invite row committed and its link was made; subject 0 town or 10 house; value 1, result 0 |
@@ -58,6 +58,15 @@ means own house; bit 0 is set only on the platform-generated first-use marker.
58
58
  | 25 | join_failed | Refused/failed public town admission at Ghost's outer resolver boundary; subject 0 town or 10 house; value 0; fixed reason is in result |
59
59
  | 27 | load_abandoned | v1.138 `loadTelemetry`: a town connection that never arrived; subject is the load stage, value ms from connect (≤ 120000), result 1 closed, 2 timeout; never an arrival |
60
60
 
61
+ Session-end results (kinds 11 and 17). The host resolves a departed player for
62
+ under a minute while a place may hold the visit for five, so a connection that
63
+ drops and stays away for 40 s (`DROP_REPORT_MS`) is reported then, with the
64
+ time connected up to the drop, result 1. A return inside those 40 s is the same
65
+ segment, less the time away. A return after the report starts a continuation,
66
+ whose own end is result 2. An ordinary leave (a trip, shutdown, a place with
67
+ no resume hold) is result 0. Rows with result 0 or 1 count each visit once;
68
+ summing `value` over all three gives connected time.
69
+
61
70
  Arrival-source results: 0 unknown, 1 direct, 2 invite, 3 door return, 4 return
62
71
  from an owner house, 5 push, 6 explore. Push is reserved and is not emitted: Ghost has no
63
72
  trusted push evidence today, so it never infers push from caller input. Explore is
@@ -1,6 +1,6 @@
1
1
  # The hub-game contract
2
2
 
3
- **Version 1.145** (2026-10-17; v1 plus the optional additions under "Changes in
3
+ **Version 1.157** (2026-10-20; 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
@@ -130,7 +130,7 @@ reading the saved deck, treats the same list as no unlocks at all.
130
130
  | `npcs` | object | §13. |
131
131
  | `fallY` | number | v1.1. -25 to 50 metres; below it a player has fallen (§5). Default: -20. |
132
132
  | `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). |
133
- | `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). |
133
+ | `idle` | boolean or object | v1.6. `true` (emotes and seats), or `{ emotes, seats, sounds, expression }`: v1.158 `expression` is `true` or `{ roleEmotes: [{ id, emoji, label, motion, ms }] }` (up to 12), requires `emotes: true`, and enables the expression wheel and sit-anywhere (§6); unknown keys are errors. `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). |
134
134
  | `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. |
135
135
  | `actions` | boolean | v1.74, a place's (`hub.actions` or `hub.places.<id>.actions`): `true` enables private action chips (§9). Any value other than `true` or an absent key is a manifest error. Absent: no API, action hook lookup, private state, chrome, message or snapshot key; existing wire bytes stay identical. |
136
136
  | `companion` | boolean or object | v1.71, a place's (`hub.companion` or `hub.places.<id>.companion`): `true` enables the private companion (§9); `{ "chat": { "character": "companion", "name": "Chirp" } }` also enables owner-only NPC chat (§13). Chat needs `npcs` configured; unknown keys at either nesting level are errors. `character` names an id in the deck's `characterBundle` (non-blank, up to 100 characters / 128 UTF-8 bytes, no NUL); `name` is non-blank, 1..24 code points with no control characters. Leave the key out to disable it. Absent: no API, private state, drawer, message or `hubGlow`; existing wire bytes stay identical. |
@@ -149,6 +149,7 @@ reading the saved deck, treats the same list as no unlocks at all.
149
149
  | `quality` | `{ low: { decor, players, labels, spawned, farMindsHz, physicsHz? } }` | v1.137, root only, requires `tiers: true`; client-only Low build/draw budgets. Unknown keys refused. See "v1.137 hub.quality" below. `physicsHz` is reserved, no effect yet. Absent quality preserves previous behavior and bytes. |
150
150
  | `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.69: and its kit sky is not drawn on Low). 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); v1.63: `"tier": "near"` instead treats a non-NPC actor as scenery on Low, whatever its components: its node is taken out beyond 30 m of its bounds (the same sized test as static scenery) and put back within that distance. High never hides it; NPCs retain their own 20 m rule, and `keep` wins (the field carries one mark). v1.69: `"tier": "low"` draws an authored actor only on Low, at any distance, without the decoration/scenery/NPC distance rules; High removes its node from the scene graph, and switching back to Low restores its original parent. On High the node is drawn in the one frame that built it (a scene load, or the actor's rebuild): the tier rules run before the engine builds nodes. The place's per-viewer hiding and visibility cells still apply on Low. Low also draws no `engine.sky` dome at all (no drawing, zone stepping or texture uploads), in whatever scene plays, the frame of a scene load included; High draws the zone skies as authored. Both change on the frame after Graphics or the auto judge changes tier. A scene may therefore provide the kit sky for High and a cheap sky actor marked `"tier": "low"` for Low. No physics-3d change: while Low, hub-game puts an own `sky` of null on the scene runtime, over the getter the engine reads each frame, and deletes it on leaving Low; a device that is never Low has no such property. A scene with no low mark draws on High exactly as before, and a scene without the sky key draws on Low exactly as before. Labels, colliders and server state are untouched. 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. v1.64: a scene file may carry a top-level `cells` key beside `engine` and `actors` -- `{ version: 1, eyeMax, hysteresis, cells: [{ id, outline: [[x, z], ...], sees: [ids], why? }] }`, outlines partitioning the ground (x east, z south), `sees` the cells visible from somewhere in that one -- and an actor a `cell` field beside `id` (`"n-plaza"`, or a list for one spanning several). On Low only, an eye outside every outline or at a non-finite place has no cell, whatever the hysteresis; otherwise the camera's cell is the one its x, z is in, kept while the eye is inside it or within `hysteresis` m of it. An authored, tagged actor none of whose cells that cell sees is not drawn, `"tier": "keep"` and `"tier": "near"` included: keep exempts distance, not what is in the way (a list is drawn when any of its cells is seen). Only an inert actor is ever out for its cell: every component it has now is one of `Transform`, `Shape`, `Model`, `Solid`, `Lookable`, `RouteAnchor`, `WalkSurface` (`CELL_INERT`; a Lookable's words are read from the scene data either way) and none is in the backstop `CELL_PROTECTED` (`HubDoor`, `HubPad`, `HubNpc`, `Body`, `Player`, `Ball`, `HubSpin`, `TownHats`, `TownStamp`, `TownHatMat`, `TownWardrobeMat`, `TownWardrobeItem`, `TownWardrobe`). Anything that reacts to a player or the server or that something moves (a seat, a sign, a court piece, a statue, any other `Hub*`/`Town*` or unknown component), or an actor with no components, is never out for its cell, whatever its `cell` or `tier` says, and the other Low rules apply to it as before. This is decided from the actor's current components on every look, never remembered: an actor replaced under the same id, or given a component while playing, is decided again on the next look. An eye above `eyeMax` or with no cell, or a game through a door: the cells hide nothing. A malformed table (another version, a cell without a string id, an outline of three or more finite pairs or a `sees` of known ids that includes its own, a duplicate id, a non-finite `eyeMax`/`hysteresis`) is no table; a `cell` that is empty, not strings, or names an unknown id is no cell. `?hubcells=1` shows an overlay (the cell, what is out and why, the last change). Nothing on the wire; a scene without the key is drawn exactly as before. `false` or absent: none of it. |
151
151
  | `yourGames` | boolean | v1.54, the deck's (not a place's). `true`: signed-in players in towns get private hearted/recent door rows, account hearts and an arrival offer (§5). `false` or absent: no command, message, UI or storage read; the deck draws exactly what it did. |
152
+ | `spawnCap` | integer | v1.161, deck-only and server-only: 96..192, how many `hub.spawn` copies may be alive at once in each of the deck's places (§4, §10). Any other value, or one under a place, is refused, by the publish check too. Absent: 96, and the manifest and wire are byte-identical. Low tier's client-side `quality.low.spawned` cap is unchanged. |
152
153
  | `safeInsets` | boolean | v1.123, deck-only and client-only. `true`: §9 safe edges, reserved host corners and complete measured chrome. Absent/false preserves the previous rendering; no server or `hubPlace` field. |
153
154
  | `playCards` | boolean | v1.122, the deck's. `true`: §6 play cards go to mutual friends and party members anywhere in the layer; strangers must be within 12 m in x/z when the phrase arrives. At most one stranger card is retained at a time, and each stranger can offer one per 60 s across all doors. Absent/false preserves the v1.11 cards and cooldown per player and door. Bubbles, feed and block filtering are unchanged. |
154
155
  | `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. |
@@ -218,8 +219,8 @@ of any of these. Every hook gets `hub`, the place's context, first:
218
219
  | `shutdown(hub)` | v1.2: the session is stopping. Anyone still here has had `leave` first; return a promise to finish writing (awaited up to 1.5 s, inside the host's own grace) |
219
220
  | `grab(hub, playerId, actorId, op)` | v1.3, a place with `grab`: a player grabbed (`op` `"grab"`) or threw (`"throw"`) a loose object (§6). Return `false` to a grab to refuse it (the player lets go at once); a throw is only told. A hook that throws refuses the grab |
220
221
  | `emote(hub, playerId, id)` | v1.6, a place with `idle.emotes`: a player asked to play emote `id` (§6). Return `false` to refuse it (nobody sees it); a hook that throws refuses it |
221
- | `npcReact(hub, npc, playerId, { emote })` | v1.47: a nearby free NPC may answer this player's emote (§6, §13). Return `false` to leave it alone, null or undefined for its props and the kit's defaults, or `{ emote, line }` to replace either. `emote` is a kit id or null for no motion; `line` is public speech, cut to 80 characters, or null for none. Errors are logged once and use the defaults. Async results are unsupported and ignored; rejected promises are caught with fixed log text. No model is called |
222
- | `sit(hub, playerId, seatId)` | v1.6, a place with `idle.seats`: a player asked to sit on seat actor `seatId` (§6). Return `false` to refuse; a hook that throws refuses |
222
+ | `npcReact(hub, npc, playerId, { emote })` | v1.47: a nearby free NPC may answer this player's emote (§6, §13). Return `false` to leave it alone, null or undefined for its props and the kit's defaults, or `{ emote, line }` to replace either. `emote` is one of the original five kit ids or null for no motion (also at v1.158 expression places); `line` is public speech, cut to 80 characters, or null for none. Errors are logged once and use the defaults. Async results are unsupported and ignored; rejected promises are caught with fixed log text. No model is called |
223
+ | `sit(hub, playerId, seatId)` | v1.6, a place with `idle.seats`: a player asked to sit on seat actor `seatId` (§6). v1.158 `idle.expression` also calls this with `seatId: null` for sit-anywhere, independently of `idle.seats`. Return `false` to refuse; a hook that throws refuses |
223
224
  | `action(hub, playerId, id)` | v1.74, a place with `actions: true`: an arrived, connected player pressed an id in their current offer, carrying a safe-integer `n` equal to that offer's current version (§9). Stale, removed, another player's, malformed or over-budget presses are silently dropped. Six presses/s with a burst of eight per player; dropped or refused presses spend tokens too. The return is ignored; throws and rejections are contained and logged once. Async hooks are neither serialised nor cancelled when the player leaves. |
224
225
  | `menu(hub, playerId, id)` | v1.79, only with `menu: true`: an arrived, connected player picked an item in their current, last-sent menu with its safe-integer `n`, or closed the sheet (`id: "close"`). Stale, unknown, malformed and over-budget picks are dropped; readOnly refuses item picks but still delivers close. Six attempts/s, burst eight per player, including dropped presses. Return ignored; throws/rejections contained and logged once. Async hooks are neither serialised nor cancelled on leave. |
225
226
  | `answer(hub, playerId, id, text)` | v1.75, only in a place with `ask: true`: that arrived, connected player answered their last-sent and still-current prompt; `text` is the exact string they typed, or `null` for Cancel (§9). The prompt is consumed and its close queued before the hook runs. Refused text on a current id/version consumes the prompt and calls the hook with null; it is never passed on. Two attempts/s, burst four per player; stale, malformed, oversized and dropped messages spend tokens too. Return ignored; throws and rejections contained and logged once without the text or error details. A place must never show what a player typed to another player. |
@@ -262,12 +263,16 @@ of any of these. Every hook gets `hub`, the place's context, first:
262
263
  | `hub.tint(actorId, color)` | paint a Shape actor `#rrggbb` for everyone; `null` puts back its authored colour (§10, v1.1) |
263
264
  | `hub.pose(actorId)` | where an actor's body is now: `{ x, y, z, rotationY, velocity, owner }` (`owner` the player whose client simulates a loose object, or null), or null (§10, v1.3) |
264
265
  | `hub.reset(actorId, { x, y, z, rotationY }?)` | put a loose (dynamic) object back where it was authored, or at a point, at rest, taking it from the client simulating it (§10, v1.3) |
265
- | `hub.spawn(fromActorId, { x, y, z, rotationY }?)` / `hub.despawn(id)` | a copy of a scene actor for everyone, returning its id (§10, v1.2) |
266
- | `hub.tune(playerId, { speed, jump })` | one player's own walk controller, as multipliers of the preset (§6, v1.2); `null` puts the preset back |
266
+ | `hub.spawn(fromActorId, { x, y, z, rotationY }?)` / `hub.despawn(id)` | a copy of a scene actor for everyone, returning its id (§10, v1.2); at most 96 copies alive, or the deck's `spawnCap` (v1.161, up to 192) |
267
+ | `hub.tune(playerId, { speed, jump })` | one player's own walk controller, as multipliers of the preset (§6, v1.2); `null` puts the preset back; kept while driving and applied on getting out (v1.160) |
268
+ | `hub.drive(playerId, car)` / `hub.drive(playerId, null, at?)` | v1.160: drive or respray a car; get everyone out, optionally placing the driver at `{ x, z, y?, facing? }`; boolean (§6 Cars) |
269
+ | `hub.ride(playerId, driverId, seat)` / `hub.ride(playerId, null)` | v1.160: join a free passenger seat (1-based) within 6 m, or get out beside it; boolean (§6 Cars) |
270
+ | `hub.vehicle(playerId)` | v1.160: `{ driver: true, car }`, `{ driver: false, of, seat }`, or null (§6 Cars) |
267
271
  | `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) |
268
272
  | `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) |
269
- | `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) |
270
- | `hub.seat(playerId)` | v1.6: the seat actor id a player sits on, or null (§6) |
273
+ | `hub.emotesFor(playerId, ids \| null)` | v1.158, only at an `idle.expression` place: replace this arrived player’s visit-only grants with declared role emote ids; null clears. Unknown ids warn once and are dropped; duplicates are removed. True when valid, false for an absent player or invalid list. Only changed lists are sent, privately (§6). |
274
+ | `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; v1.158 at an `idle.expression` place also accepts the five new kit ids and any declared role id, regardless of that player's grants. True when it took (§6) |
275
+ | `hub.seat(playerId)` | v1.6: the seat actor id a player sits on, or null (§6); v1.158 an `idle.expression` ground sitter returns the string `'ground'` |
271
276
  | `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) |
272
277
  | `hub.danceIdle(actorId, { bpm, floors })` | v1.109, a place with `idle.emotes`: after starting a sound loop at `actorId`, give its tempo (30–300 BPM) and 1–16 axis-aligned floor bounds `{ x, z, halfX, halfZ }` (positive half sizes at most 100 m; coordinates within ±1,000,000 m). Returns true when valid. `hub.danceIdle(actorId, null)` clears it. Replacing/stopping the loop invalidates the previous clock. No emote, scoring hook or cooldown is triggered. |
273
278
  | `hub.cue({ player } or { actor, radius? }, name)` | v1.50, a deck with `soundscape.cues: true`: a named synthesised cue for one connected player or near a scene actor, radius 1–60 m (default 12); true when sent, otherwise false and warn once. Six cues/s with burst six per player, or shared per place for actor broadcasts; closed `CUE_NAMES`, no files (§6). v1.60 `busker-jig`/`busker-waltz` loop at an actor within radius under a 25 s re-send lease, one loop per client, or play one full-gain pass to a player. |
@@ -279,6 +284,8 @@ of any of these. Every hook gets `hub`, the place's context, first:
279
284
  | `hub.friendBests(key, { better: 'higher' or 'lower' })` | v1.57: a helper with `report(playerId, best): Promise<void>` and `friendFor(playerId): Promise<{ userId, username, best } or null>`. Signed-in players only, finite numbers. `report` keeps each user's best in a top-100 deck-storage index `fb:<key>` of `{ userId, username, best, at }` (20-character username, `at` wall-clock milliseconds), through one serialized writer per key per layer. Cross-layer lost updates are acceptable. Index reads cache for 60 s; `friendFor` caches empty membership for 40 s and non-empty membership for 10 min per player per visit, and selects the best friend from the index. Leaving clears the visit cache. Both methods swallow failures. Keys are 1–60 letters, digits, `_`, `.`, `:`, `-`; use one direction per key. No manifest key, reads or writes until used |
280
285
  | `hub.leaving(playerId, text)` | v1.52: the line this player reads when leaving this place; a string, trimmed and cut at 120 characters, `null` or empty clears it. The latest call wins; true when taken, otherwise false and warn once. Sent to this player alone, only on change; never in a snapshot (§5) |
281
286
  | `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) |
287
+ | `hub.role(playerId, spec \| null)` | v1.157: set a visit-only role `{ id, label, color, hat?, top?, tool? }`; true when taken, false and logged once when refused. Null or no second argument clears; no host calls (§11) |
288
+ | `hub.roleOf(playerId)` | v1.157: a copy of the current role spec, or null for none or a player not here (§11) |
282
289
  | `hub.wearing(playerId)` | v1.41: the wearable a player here owns, `{ kind, color, rarity }` (a copy), as this place last knew it (a `hub.wear`, or ghost's on the arrival read), or null: none, or a player not here. A try-on shown over it does not change it. For a place to say what someone is wearing (§11) |
283
290
  | `hub.unlock(playerId, itemId)` | v1.53: give a player one of this deck's declared earned items (`hub.unlocks`), for the deed it states. A promise of `{ isNew, earned, saved }` (`earned` what the player now shows, an EarnedItem, or null -- never a home item (v1.70); `saved` false when it is kept in this session only -- a guest, the dev serve -- so `isNew` is true on every visit there and a game need not announce it), or of null when refused: never rejects, and each refusal is logged once and changes nothing. Ghost keeps it for a signed-in player in a curated place; a guest's, and any on the dev serve, lasts the session. A delayed host receipt updates local shown state only while the same session and account still own that player id (§11, v1.112). |
284
291
  | `hub.wearEarned(playerId, { deckId, id } \| null)` | v1.53: the town's choice of which owned earned item a player shows; `null` shows none. Ghost takes it only from the town. Home items resolve null and log `CAULDRON_HUB_EARNED_NOT_WEARABLE` locally when known, without calling the host. A promise of `{ earned, saved }` (`saved` as for `hub.unlock`), or of null when refused (logged once) (§11) |
@@ -295,6 +302,7 @@ of any of these. Every hook gets `hub`, the place's context, first:
295
302
  | `hub.doors()` | this place's doors: `[{ id, to, actor, t, props, title, minPlayers, maxPlayers, lateJoin, classic }]`, the destination's numbers from its manifest; `classic` (v1.7) is true for a cabinet, a door to a classic deck, once ghost's board says so |
296
303
  | `hub.go(door, playerIds, { instance }?)` | send players through a door of this place (a town's pad firing) into a new instance, or into `instance`, one an earlier `go` returned (a late join); returns the instance |
297
304
  | `hub.pad(door, playerIds)` | who stands on a pad door's pad; call it as often as they change (each step is fine). Where the host has hub ops the kit tells ghost, which then holds the pad's group; nothing in dev |
305
+ | `hub.noTrips(playerId)` | v1.156: true for a player whose app cannot go through doors (its host has no `hub.go`: released iOS Castle 1.150 and 1.151 refuse every hub command). The kit already leaves them out of `hub.pad`'s group and of `hub.go`, and says "Update Castle to play" over the door to them alone while `hub.pad` names them; a place that counts its own pads (a countdown, a minimum) leaves them out too and may say the same over its pad. False for everyone else |
298
306
  | `hub.coming(door)` | v1.10: how many members of a party were asked to this door and have not answered yet (§5 parties), so a place may hold its pad's countdown for them; 0 where there are none |
299
307
  | `hub.board(door)` | the best scores behind a door of this place, `{ title, unit, better, top: [{ userId, username, score, at }], featured, minPlayers, maxPlayers, lateJoin, event }`, or `null` (dev, or not read yet). `featured`: today's rotation features the door. `minPlayers`, `maxPlayers`, `lateJoin`: the door row's group (null where the row does not say); a door to another deck takes its title and group from here rather than its scene props. `event`, on an event gate only: `{ day, open, opensAt, closesAt, last: { day, toDeckId, title, unit, better, top } }`, and `top` is the current event's own board. v1.112 weekly boards add `event.validResultCount` and `event.last.validResultCount`: distinct participants with any valid durable result in that occurrence, including an outcome without a numeric score, so replays never inflate either count. Numeric matching scores remain required for ranking. Daily-only boards omit both fields. |
300
308
  | `hub.send(playerId, data)`, `hub.broadcast(data)` | the game's own messages |
@@ -639,7 +647,24 @@ suppressed. The chip fits within 94vw and its personal line ellipsizes.
639
647
  the capability and retain their existing host Back behavior. iOS, portrait,
640
648
  browser hosts, travel covers and root visits retain their previous behavior.
641
649
  The kit control uses the existing `Hub.back()` return, with the same modal
642
- dismissal and duplicate-trip guards as host Back. Nothing of
650
+ dismissal and duplicate-trip guards as host Back. v1.155: a host may also
651
+ post a hub Go event naming one of the place's doors (SDK `Hub.onGo`; the
652
+ host's `hubGoEnvelope({ doorId, owner?, title?, party? })`, posted as
653
+ `{ castleSdk: 1, hub: { type: "go", doorId, owner?, title?, party? } }`),
654
+ e.g. a trip begun outside the page that hands back to the Town. The kit
655
+ takes it through that door as if its pad had fired: the same production
656
+ trip (`Hub.go(door)`, with `owner` as `ownerUserId` when set; the door beat,
657
+ the cover, the ticket for the way back), without a pad countdown. It waits
658
+ until the place is settled (the first hello on this connection, placed, not
659
+ held, not ending, its Doors list known) with no trip under way; the latest
660
+ Go wins. It is dropped after 60 s, when a trip starts first, when one
661
+ arrives during a trip (never queued behind it), and for a door the place's
662
+ Doors list lacks -- a cabinet never is listed, so a classic deck's door is
663
+ dropped too (the host plays those itself). The SDK refuses a Go with an
664
+ empty or overlong `doorId` or a malformed `owner` outright, and drops a
665
+ non-string `title` or a party that is not a positive integer. A host Go is
666
+ client-side like a hub-entry link's trip: the place's server is not told
667
+ (no `hub-went` to others). Nothing of
643
668
  the destination is mounted until the host commits the join
644
669
  (`multiplayer.joinState()`); a join it does not commit leaves the player's
645
670
  place as it was: a door's trip rejoins the session it left when that is not
@@ -803,7 +828,8 @@ suppressed. The chip fits within 94vw and its personal line ellipsizes.
803
828
  | preset | what | status |
804
829
  | --- | --- | --- |
805
830
  | `walk` | physics-3d's `Player`: tank-style walk/turn, drag-stick on touch, jump, follow camera; client-predicted, server-clamped | v1 |
806
- | `vehicle`, `fixed-camera` | reserved names | refused until built |
831
+ | `vehicle` | per-player car, selected by `hub.drive`; predicted capsule, seated avatars and passengers | v1.160 |
832
+ | `fixed-camera` | reserved name | refused until built |
807
833
 
808
834
  A game chooses a preset; it does not extend one (HUB.md open question 6 stays
809
835
  open for v2). The scene's `Player` actor is the spawn and the preset's tuning
@@ -821,6 +847,83 @@ while everyone else keeps the place's limit. It needs multiplayer-3d from
821
847
  player tuned past twice the preset is pulled back. A tune lasts the visit and
822
848
  goes with the player.
823
849
 
850
+ ### Cars (v1.160)
851
+
852
+ `hub.drive(playerId, car)` switches an arrived, unheld player outside a trip
853
+ from walking to driving. It returns true, or false with a once-per-reason
854
+ warning. Calling it again replaces the car (a respray), preserving riders;
855
+ a replacement that removes an occupied seat is refused. A rider cannot drive.
856
+ The scene's place-wide `controller` remains `walk`: vehicles are selected per
857
+ player by this API, rather than by a place-wide controller without a car spec.
858
+
859
+ | car field | default | rule |
860
+ | --- | --- | --- |
861
+ | `look` | required | scene actor id with a `Model`; usually a hidden template |
862
+ | `color` | absent | `#rrggbb`, tinting paint parts only |
863
+ | `seats` | `[[0,0,0]]` | 1–4 finite `[x,y,z]` points, metres in car-local space, +Z forward; seat 0 is over the driver's body |
864
+ | `length`, `width` | 4, 1.8 | clamped to 2–10, 1–3 m |
865
+ | `speed`, `reverse` | 12, 4 | clamped to 2–16, 1–6 m/s |
866
+ | `accel`, `brake` | 6, 14 | clamped to 1–20 m/s² |
867
+ | `turn` | 1.6 | clamped to 0.3–3 rad/s |
868
+ | `camDistance`, `camHeight` | Player's × 1.4 | finite positive metres |
869
+ | `horn` | absent | file listed in this place's `idle.sounds`; offers Horn |
870
+
871
+ A car is the driver's own predicted capsule, moved by the walk controller's
872
+ velocity-matching impulse, with the same ground hover and camera/HUD. Up/W
873
+ accelerates forward, down/S brakes then reverses, sideways steers; the touch
874
+ stick is tank-style even with the orbit camera. There is no jump. Speed
875
+ eases toward the requested forward/reverse speed at `accel`, at `brake` while
876
+ opposing existing motion, and coasts toward zero at 2 m/s² without input.
877
+ Yaw rate is `turn * steer * min(abs(speed)/4,1) * sign(speed)`, taken off the heading: a right steer lowers it and turns right, as the walk's right turn lowers its facing. No turn at rest.
878
+ Two body-height rays reach `length/2` forward and backward; a hit in the
879
+ travel direction stops horizontal motion, including held input against the
880
+ hit, and permits backing off. Players do not block cars. Corners are not
881
+ probed: a scrape can overlap by at most `width/2`.
882
+
883
+ The car's cloned, merged pxmodel is drawn under the driver's avatar node at
884
+ the look's authored Model scale and yOffset, translated by minus seat 0.
885
+ Pxmodels use part colours/material presets rather than a named material
886
+ table: parts with id/name/material `paint` take the tint; other parts retain
887
+ their colours. The shared template is untouched. Avatar visibility, cell
888
+ interest, distant-avatar limits and Low apply through that same node.
889
+ Drivers and passengers use the existing sit pose. No actor is created for a
890
+ car, and no car pose stream is added.
891
+
892
+ `hub.ride(playerId, driverId, seat)` holds an arrived walker in a free seat
893
+ 1 through `seats.length-1`. Held players, drivers, existing riders, absent
894
+ or departing drivers, invalid/taken seats, and players farther than 6 m in
895
+ 3D from the driver's body are refused. Each tick the server places riders
896
+ at the driver's server pose plus the rotated difference between their seat
897
+ and seat 0. Rider pose reports are dropped. Clients send no rider pose and
898
+ draw each rider from the driver's interpolated DRAWN pose, with the local
899
+ rider's camera following the car and movement/jump input ignored. The place's
900
+ own Get out action may call `hub.ride(playerId, null)`.
901
+
902
+ `hub.drive(playerId, null, at?)` gets the driver and all riders out. The
903
+ default exit is 1.6 m to the car's left for the driver, and beside each
904
+ rider's seat for riders. Optional `{ x,z,y?,facing? }` replaces the driver's
905
+ exit only; y defaults to their current body height, facing is degrees and
906
+ defaults to their heading. Supplied points must be finite and inside the
907
+ world box (§10). `hub.ride(playerId, null)` gets just that rider out.
908
+ `hub.vehicle` returns a copy of the current state or null.
909
+
910
+ The driver's movement clamp follows the larger of forward and reverse top
911
+ speed, so reverse remains legal for a slow-forward car. Walk tuning is kept
912
+ and applies again on exit. `hub.hold` stops a driver while preserving their
913
+ car and riders; `release` lets them drive on. As with a bench seat, an
914
+ explicit hold/release of a rider replaces/ends that seat. HubSeats cannot be
915
+ taken by drivers or riders. Leaving, a trip, game end/`hub.end`, shutdown or
916
+ expiry of a retained visit releases occupants. A retained reconnect (§12,
917
+ v1.89) keeps the car and riders and sends them in the joining snapshot.
918
+ At most 24 cars exist in a place, each with at most four seats.
919
+
920
+ In a town with `hub.stuck`, forward/reverse drive input counts toward the
921
+ existing stuck rule and the chip reads **“Stuck? Tap to reset the car”**.
922
+ The existing `unstick` hook chooses a road pose/facing. The driver stays in
923
+ the car there and riders follow; the existing held, arrival and cooldown
924
+ checks still apply. No vehicle fields, messages or drawing are added in a
925
+ place that never calls `hub.drive`.
926
+
824
927
  **Grabbing and throwing (v1.3).** A place with `grab` in its manifest lets
825
928
  players pick up its loose objects -- scene actors whose `Body` is `"dynamic"`
826
929
  -- and throw them. The hub draws a Grab button (bottom right; E or F on a
@@ -1028,6 +1131,70 @@ without it draws nothing new and is sent exactly what it was.
1028
1131
  place plays only its own content's files, never a same-named file of the
1029
1132
  town's.
1030
1133
 
1134
+ **Expression (v1.158, optional).** A place may add `idle.expression: true`
1135
+ (or `{ roleEmotes: [...] }`) alongside `idle.emotes: true`; without emotes
1136
+ it is a manifest error. Unknown keys in expression or a role declaration are
1137
+ errors. Absent expression keeps the same five-button picker, behavior and
1138
+ wire bytes, including existing seats; no role grants or definitions are sent.
1139
+ Expression alone does not enable seats or change chat, bubbles, moderation or
1140
+ under-13 rules.
1141
+
1142
+ The ☺ button opens a wheel of eight labeled basics: wave 👋, sit 🪑,
1143
+ sleep 😴, eat 🍔, dance 💃, cry 😢, laugh 😂 and point 👉. More opens pages
1144
+ of up to six buttons containing the original cheer/bow/spin and only this
1145
+ player's granted role emotes. Short viewports use a four-column, two-row
1146
+ grid of basics when the ring and navigation do not fit, and extras use fewer
1147
+ rows per page as needed. The ring and pages fit portrait and landscape phones
1148
+ inside the safe layout, clear of existing chrome; buttons are at least 44 px,
1149
+ have accessible labels, and close on selection, an outside tap or Escape.
1150
+ The five new emotes are model-only: sleep (4 s) slowly tilts sideways and
1151
+ drops slightly; eat (3 s) repeats small forward nods; cry (3 s) shakes with
1152
+ the head down; laugh (2.4 s) bounces while rocking back; point (2 s) leans
1153
+ forward with a slight turn. Both a client's `hub-emote` and the place's
1154
+ `hub.emote` refuse these ids without expression. Existing emote cooldowns
1155
+ and hooks apply. NPCs answer laugh with cheer and the other new ids with
1156
+ wave, reusing existing lines; NPC answer ids remain the original five.
1157
+ Soundscape cues reuse existing sounds, with no new synthesis.
1158
+
1159
+ `roleEmotes` declares up to 12 `{ id, emoji, label, motion, ms }` entries.
1160
+ An id matches `^[a-z][a-z0-9-]{0,23}$`, is unique, and cannot equal any of the
1161
+ ten kit emote ids. `emoji` is a single emoji string of at most 8 UTF-16 units;
1162
+ `label` is 1..16 characters (not blank); `motion` is wave, dance, cheer, bow,
1163
+ spin, sleep, eat, cry, laugh or point; `ms` is 1000..6000. Nobody gets these
1164
+ by default: `hub.emotesFor(playerId, ids)` replaces that player's role
1165
+ emote grants for this visit, and null clears them. Unknown ids warn once and
1166
+ are dropped. A client request for an ungranted role id is refused; the
1167
+ place's `hub.emote(playerId, roleId)` can play any declared role regardless
1168
+ of grants. Leaving clears grants. Only changed lists go to that player in
1169
+ `{ k: 'hub-emotes-for', ids }`, never to other viewers or shared snapshots.
1170
+ The public place info's `idle.expression.roleEmotes` contains definitions,
1171
+ so every viewer resolves the emoji and model motion from the existing
1172
+ `hubEmotes` id; grants do not control seeing someone else's role emote.
1173
+
1174
+ The wheel's Sit sends `{ k: 'hub-sit-here' }`, independent of `idle.seats`,
1175
+ and retries every 400 ms until the player is reported seated or 1.6 s elapse.
1176
+ Any walk/turn/jump input cancels the pending request.
1177
+ It requires an arrived player here who is not held or already seated and
1178
+ holds no grabbed object. The body must stay within 0.05 m horizontally and
1179
+ 0.08 m vertically of an anchor pose for at least 250 ms; moving farther
1180
+ resets the anchor and timer. Sitting on a seat or the ground and standing
1181
+ clear the anchor, so the next ground sit needs a fresh still period.
1182
+ The last tick's horizontal step must also be at most 0.015 m, so a walk's
1183
+ first step never sits.
1184
+ Fixed floor support must be within -0.15..0.12 m
1185
+ of its feet. The kit uses its standing body bounds,
1186
+ implicit ground or the fixed floor shapes used for placement. The place's
1187
+ `sit(hub, playerId, null)` hook may refuse, including by throwing. The kit
1188
+ holds the player at their current x/z and facing, no higher than standing
1189
+ on the support found (its top plus the body's half height and 0.06 m, so a
1190
+ body caught rising is lowered onto it), with the ordinary seated
1191
+ model drop (0.45 m) and tilt, and publishes `hubSeated[playerId]: 'ground'`;
1192
+ `hub.seat(playerId)` returns `'ground'`. Ground sitters do not occupy a
1193
+ HubSeat. Stand, any walk/turn/jump input, a door jump, place hold/release,
1194
+ end and leaving stand them as with seats. Sit-here shares the existing
1195
+ 3/s sit/stand budget. With a HubSeat in reach, the bottom-centre Sit button
1196
+ continues to sit on that seat.
1197
+
1031
1198
  **The soundscape (v1.42, v1.49, v1.50, v1.56).** A deck with `soundscape` in its manifest (§1) has
1032
1199
  the kit make sounds of its own, in every one of its places. All of it is
1033
1200
  synthesised in the client (WebAudio); none of it is a file, none of it is
@@ -1156,6 +1323,31 @@ named cue messages, in a deck with `soundscape.cues: true`.
1156
1323
  rate to preserve wash RMS, using about 8.5/9.2 MB of mono loop memory at
1157
1324
  44.1/48 kHz (8.1/8.8 MiB).
1158
1325
 
1326
+ Low-memory soundscape retention:
1327
+
1328
+ The player renderer's `scene.three.lowMemory` profile reaches soundscape
1329
+ construction internally; there is no additional manifest field. In this profile,
1330
+ only the current heavy zone bed (crowd, market or harbour), or a nearby heavy
1331
+ spot while in a light zone, is prewarmed and cached. Fulfilled promises, stopped
1332
+ sources and bed references for inactive loops are released. Quiet/dispose also
1333
+ evicts the private cache. A running offline render cannot be cancelled; its
1334
+ obsolete result is ignored, and the next selected render starts serially.
1335
+
1336
+ To keep one heavy loop buffer at most, heavy outgoing beds stop on selection
1337
+ changes instead of crossfading into another heavy loop. Light beds retain their
1338
+ fades. A simultaneous secondary heavy spot uses its existing live generator;
1339
+ this trades some synthesis CPU for bounded retained buffer memory. Returning to
1340
+ an evicted zone re-renders it and fades in when ready. Rates, mono output,
1341
+ seeded synthesis and calibrated levels are unchanged.
1342
+
1343
+ Retained Float32 loop bytes are crowd 3,840,000 (40 s × 24 kHz), market
1344
+ 5,760,000 (60 s × 24 kHz), and harbour 8,467,200 at 44.1 kHz or 9,216,000 at
1345
+ 48 kHz (48 s × live rate). At 44.1 kHz the three formerly cached loops total
1346
+ 18,067,200 bytes; retaining one saves 9,600,000–14,227,200 bytes, or all
1347
+ 18,067,200 in a light zone without a heavy spot. Offline rendering temporarily
1348
+ also allocates lead-in/tail and output buffers; these are not a retained-memory
1349
+ cap. The default profile keeps its shared cache, prewarming and crossfades.
1350
+
1159
1351
  `music: true` selects original built-in music (v1.50 rounds 2–3):
1160
1352
 
1161
1353
  | Zone | Songs | Music nodes |
@@ -2288,7 +2480,7 @@ not a template: a copy, an actor with a dynamic `Body` or a `Pickup`, a
2288
2480
  `Player`, a `HubDoor`, `HubPad` or `HubNpc`. A copy a behavior removes on one
2289
2481
  client is reported gone like any scene actor and is never re-made there; one
2290
2482
  the place despawns is forgotten by every client, pose history included. Bounded: 96 copies
2291
- alive at once and 10 spawns a second with bursts of 40; past either, `spawn`
2483
+ (v1.161: or the deck's `hub.spawnCap`, 96..192) alive at once and 10 spawns a second with bursts of 40; past either, `spawn`
2292
2484
  returns null and logs once, and a game tries again later. A copy a client
2293
2485
  reports gone (the multiplayer kit's pickup rule) is gone for the game too.
2294
2486
 
@@ -2302,6 +2494,30 @@ of those to a marked actor; the actor is then an ordinary one until the scene
2302
2494
  is loaded again. A place whose own client code writes a marked actor's
2303
2495
  components calls `scene.touch(id)` first.
2304
2496
 
2497
+ The save-time native export bakes such scenery into merged chunks, where an
2498
+ actor has no node of its own: a native client can then neither hide, show nor
2499
+ copy it. It keeps apart every marked actor another actor's component names,
2500
+ whose id the deck's code quotes beside a `hide`, `show`, `tint`, `move`,
2501
+ `despawn` or `touch` call or passes as a literal to `hub.spawn` (a template),
2502
+ or that carries `"decor": true`. An id the
2503
+ code builds at run time or reads from config is not seen: list it in the
2504
+ scene's `"engine": { "hubKeepNodes": ["statue-*", "lamp-tpl"] }` (ids, `*`
2505
+ matching any run of characters) and it keeps its own node. Exporter only:
2506
+ the page, the wire and the check are unchanged, and a scene without the key
2507
+ exports exactly as before.
2508
+
2509
+ An export taken from a live page sees what the place has hidden by then: a
2510
+ spawn template or a car look its ready code ran `hub.hide` on. Copies
2511
+ (`hub.spawn`), a car's look and a later `hub.show` are all drawn from that
2512
+ actor's own node, so every scene actor not drawn at export (its node hidden,
2513
+ or dropped far below the ground by `hub.hide`) still has its meshes in the
2514
+ scene glb and its split model, posed at its authored Transform. It stays
2515
+ `visibleAtExport: false` and in its profile's `hiddenAtExport`, is never
2516
+ merged and is no floor; its bounds describe the authored pose, and the
2517
+ `drawn*` stats leave it out while `meshes` and `triangles` (what the glb
2518
+ holds) count it. Players, NPCs and avatars are left as they were. A scene
2519
+ with nothing hidden at export exports exactly as before.
2520
+
2305
2521
  **Recolouring an actor (v1.1).** `hub.tint(actorId, '#rrggbb')` paints a scene
2306
2522
  actor drawn by a `Shape` for everyone, later joiners included; a Shape that
2307
2523
  glows (`emissive`) glows in the new colour. `hub.tint(actorId, null)` puts its
@@ -2359,6 +2575,22 @@ There are 1..3 unique layer ids. Catalogue, tab, swatch and layer ids match
2359
2575
  `[a-z][a-z0-9_-]{0,23}`; actor ids are non-empty strings of at most 128 chars.
2360
2576
  The publish check refuses an invalid declaration or missing origin actor.
2361
2577
 
2578
+ (v1.159) A place with several furnishing areas, such as one house interior per
2579
+ lot, may also or instead declare `grids`: 1..16 named grids, each id a short id
2580
+ like the others and each grid validated exactly like `grid`, its origin actor
2581
+ checked by the publish check too. `grid` is then optional; a place declares at
2582
+ least one of the two.
2583
+
2584
+ ```json
2585
+ "decor": {
2586
+ "grids": {
2587
+ "lot-1": { "origin": "lot-1-floor", "w": 6, "d": 6, "cell": 1 },
2588
+ "lot-2": { "origin": "lot-2-floor", "w": 6, "d": 6, "cell": 1 }
2589
+ },
2590
+ "layers": ["rug", "floor"]
2591
+ }
2592
+ ```
2593
+
2362
2594
  The server receives `hub.decor` only in a place with that key:
2363
2595
 
2364
2596
  | call | what it does |
@@ -2375,6 +2607,7 @@ changing state. Specifications contain only these fields:
2375
2607
  ```js
2376
2608
  {
2377
2609
  title: 'Only you can change your house', // optional, at most 40 characters
2610
+ // grid: 'lot-1', // optional (v1.159), a key of decor.grids
2378
2611
  tabs: [{ id: 'furniture', label: 'Furniture' }],
2379
2612
  items: [{
2380
2613
  id: 'chair', tab: 'furniture', label: 'Chair', template: 'chair-template',
@@ -2399,6 +2632,12 @@ spawned actors, item/layer matching the catalogue, integer x,z inside the
2399
2632
  grid, rot 0..3; the rotated footprint must fit. All arrays except swatches
2400
2633
  are required, including empty items/placed arrays. Unknown keys are refused.
2401
2634
 
2635
+ (v1.159) `grid` names one of the place's `grids`; without it the place's own
2636
+ `grid` is used, so a place that declared only `grids` must name one, and an
2637
+ unknown id throws. The chosen grid bounds `placed`, the ops' cells and the
2638
+ preview: the client is sent its resolved origin and size as before, not its
2639
+ id. `update` may change `grid` like any other named field.
2640
+
2402
2641
  `decor(hub, playerId, op)` receives one of:
2403
2642
 
2404
2643
  ```js
@@ -2748,6 +2987,44 @@ shows a wearable on the player **in this place only, without saving it**:
2748
2987
  nothing breaks, the try-on is simply not seen there until that deck is
2749
2988
  saved again.
2750
2989
 
2990
+ **Roles (v1.157).** A place may dress a player for the visit:
2991
+ `hub.role(playerId, { id: 'police', label: 'Police', color: '#22335a',
2992
+ hat: 'police-cap', top: 'vest', tool: 'torch' })`. Nothing goes to ghost.
2993
+ The account's Look and Earned slots are unchanged.
2994
+
2995
+ - **The shape.** Exactly `{ id, label, color, hat?, top?, tool? }`. `id` is
2996
+ the deck's own id, `[a-z][a-z0-9-]{0,23}`. `label` is a string, trimmed,
2997
+ 1–16 characters (Unicode code points); longer labels are refused, never
2998
+ cut. Control characters and line breaks are refused. `color` is `#rrggbb`,
2999
+ stored lowercase. Optional `hat` is an id in `code/client/hats.js` `HATS`.
3000
+ `top` is one of `ROLE_TOPS`: `vest`, `scrubs`, `coat`, `apron`, `cardigan`,
3001
+ `tabard`. `tool` is one of `ROLE_TOOLS`: `torch`, `bag`, `hose`, `tray`,
3002
+ `bell`, `parcel` (`code/client/role.js`). Unknown keys or pieces are refused.
3003
+ - **Set and read.** True when taken; false when refused, logged once, with
3004
+ no change. A player with a body who has not said hello yet is accepted,
3005
+ as with try-on. Null, or no second argument, clears. A resident needs no
3006
+ role. `hub.roleOf(playerId)` returns a copy of the current spec or null,
3007
+ also null for a player not here. Calling with the same spec every tick
3008
+ sends nothing.
3009
+ - **What is drawn.** A small pill below the player's name tag, including
3010
+ over their own body, in the role colour with marks' contrasting text.
3011
+ It follows the same label list as marks and hides with the drawn avatar.
3012
+ A role hat replaces try-on and owned Look while named; without `hat`,
3013
+ Look draws as before. The torso piece rises from the waist to below the
3014
+ chest, in the role colour with fixed trims. It hides an earned belt or
3015
+ sash. The tool sits in the right hand and hides an earned held item.
3016
+ Badge and pin remain. All pieces move and hide under the avatar's node,
3017
+ fitted to the drawn avatar, including a cap's stand-in. Clearing restores
3018
+ Look, try-on and Earned as they were.
3019
+ - **How long.** This visit only. A short drop with a retained visit (§12,
3020
+ v1.89) keeps the role; the same player id's return shows it to everyone
3021
+ again. A fresh restart, account change, final leave or place end clears it.
3022
+ Absent retained bodies are not drawn or listed in `hubRole`.
3023
+ - **Old kits.** Old clients ignore `hubRole` and `hub-role`. A place on an
3024
+ older kit has no `hub.role`; decks ask `typeof hub.role === 'function'`
3025
+ first. No manifest key is needed. A place that never calls it sends and
3026
+ draws exactly what it did before.
3027
+
2751
3028
  **The Earned slot (v1.53).** A player has two wearable slots. The **Look**
2752
3029
  (`hub.wear`, above: hats, halos, auras, anything with a rarity) is the town's
2753
3030
  and, later, the shop's. The **Earned** slot holds one small thing a game gave
@@ -2886,6 +3163,23 @@ it in the decor tray, Rooms tab or pet book according to its class.
2886
3163
 
2887
3164
  ## 12. Wire (kit-internal, listed so a host or bot can speak it)
2888
3165
 
3166
+ ### Vehicles (v1.160)
3167
+
3168
+ Only while cars exist, WORLD includes `hubCars`, a dictionary keyed by driver
3169
+ player id. Its latched delta sends that dictionary only when it changes,
3170
+ including `{}` once after the last car leaves. Values are
3171
+ `{ look, color?, seats, length, width, speed, reverse, accel, brake, turn,
3172
+ cam: { distance?, height? }, horn?, riders: { [seat]: playerId } }`.
3173
+ A rider finds their seat from `riders`. A place that never drives sends no key.
3174
+ A snapshot without this key clears any old client cars.
3175
+
3176
+ Client → server `{ k: 'hub-horn' }`: an arrived driver with a declared horn,
3177
+ once per second. Server → clients uses the existing one-shot sound path,
3178
+ `{ k: 'hub-sound', player: driverId, file, volume: 1, radius: 20 }`. The
3179
+ optional `player` source identifies the drawn driver avatar instead of the
3180
+ scene `actor` source used by `hub.sound`; absent avatars are silent. This
3181
+ adds no actor and changes no existing sound call or event.
3182
+
2889
3183
  ### Weakest-phone picture (v1.97, opt-in)
2890
3184
 
2891
3185
  A deck with both `hub.tiers: true` and `hub.weakestTier: true` offers a
@@ -2982,7 +3276,7 @@ Decorating (v1.67, §10) adds client `{ k: 'decor', ...op }` only in a
2982
3276
  concerned player only. These private states never enter WORLD or deltas.
2983
3277
 
2984
3278
 
2985
- Client → server: `{ k: 'hub-hello', avatar, from, party, carry }` once per session join
3279
+ Client → server: `{ k: 'hub-hello', avatar, from, party, carry, device? }` once per session join
2986
3280
  (and again with `again: true` when only the avatar changed, v1.7; and again,
2987
3281
  fresh, with `resume: true`, `party: 1` and no `carry` or `near`, when the
2988
3282
  session gives this connection a body again after a drop (a second WORLD on the
@@ -2997,6 +3291,13 @@ labels, tune and avatar overrides once on the next tick, sending nothing for
2997
3291
  a channel never set or whose last sent value was empty (a `resume: true` hello,
2998
3292
  whose client may have missed a clear, is re-sent empty ones too), with no new
2999
3293
  wire keys.
3294
+
3295
+ Optional `device` is the packed device class documented in `code/shared/deviceClass.js`.
3296
+ The server accepts only safe integers greater than 0 and below 2^29, retaining
3297
+ the previous value when omitted or invalid. Arrival analytics store it in `value`
3298
+ for `arrive` and `house_visit` (including deferred first-visit arrivals); old clients
3299
+ without the key record 0. Reconnect analytics keep their existing meaning.
3300
+
3000
3301
  A game takes neither under the same player id; under a new one its client
3001
3302
  says an ordinary first hello, a party of one. v1.72: a game whose place says `resume: true`
3002
3303
  takes both under the same player id, as any place does (`hubPlace.resume:
@@ -3024,7 +3325,7 @@ not arrived again, and is re-sent all of the above);
3024
3325
  `{ 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);
3025
3326
  `{ k: 'hub-house-visit', door, owner }` (2026-10-16, §5: Join on a friend at home; with a platform hub, a well-formed `owner` and a signed-in sender the place sends `hub-go` with no `key` and that `owner`, ending the visit as any door's trip does; otherwise it is `hub-door-jump`);
3026
3327
  `{ 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);
3027
- `{ k: 'hub-emote', id }`, `{ k: 'hub-sit', seat }`, `{ k: 'hub-stand' }` (v1.6, §6);
3328
+ `{ k: 'hub-emote', id }`, `{ k: 'hub-sit', seat }`, `{ k: 'hub-stand' }` (v1.6, §6); v1.158 an expression place also accepts `{ k: 'hub-sit-here' }` and privately sends changed role grants as `{ k: 'hub-emotes-for', ids }`;
3028
3329
  `{ k: 'hub-npc-open', npc }`, `{ k: 'hub-npc-say', npc, text, rid? }` (authored mode
3029
3330
  only), `{ k: 'hub-npc-end', npc }` (§13).
3030
3331
  Server → client, in deltas and the WORLD snapshot: `hubPlace` (the place's
@@ -3035,7 +3336,7 @@ actor id → `#rrggbb`), `marks` (v1.1, player id → `{ text, color }`), `hubDo
3035
3336
  (v1.4, player id → `{ kind, color, rarity }`; only once someone in the place
3036
3337
  has worn one, and like `hubAv` without the players in a hidden pair), and in a
3037
3338
  place with `idle` (v1.6) only the parts it turns on: `hubEmotes` (player id →
3038
- `{ id, at, until }`, simulation ms), `hubSeated` (player id → seat actor id),
3339
+ `{ id, at, until }`, simulation ms), `hubSeated` (player id → seat actor id, or v1.158 `'ground'` for expression sit-anywhere),
3039
3340
  `hubSounds` (actor id → `{ file, volume, radius, since }`, the loops playing);
3040
3341
  v1.47 adds `hubNpcEmotes` (NPC actor id → `{ id, at, until }`, simulation ms)
3041
3342
  only after an NPC has emoted back, then latched when it changes, including
@@ -3057,6 +3358,12 @@ only, `hubStuck` (v1.33, `{ to }`: this place answers `hub-unstick`, and `to`
3057
3358
  is its name for its arrival or null, §5; only a town of a deck with
3058
3359
  `hub.stuck`; v1.39, with `hook: true` in a place that has the `unstick`
3059
3360
  hook, and no such key in any other).
3361
+ `hubRole` (v1.157, player id → `{ id, label, color, hat?, top?, tool? }`,
3362
+ §11) is a whole block, latched as `hubTry`: join snapshots include it only
3363
+ when non-empty. Deltas send changed blocks only after a role was shown,
3364
+ and `{}` once to clear the last. The blocked-pair rule removes hidden pairs
3365
+ from the shared block. A place that never calls `hub.role` has no `hubRole`
3366
+ key or `hub-role` message, byte for byte.
3060
3367
  `hubGlow` (v1.71, §9) is a sorted array of the helloed, arrived player ids
3061
3368
  with a non-null companion, and nothing else: no look, words or target. Only
3062
3369
  an opted-in place carries it, in snapshots once anyone in this session has
@@ -3129,6 +3436,12 @@ it. Once a place has sent one, a client that joins afresh -- a `hub-hello`
3129
3436
  without `again` -- is sent the map as it is, empty or not, so one that comes
3130
3437
  back holds neither a try-on that came off while it was away nor misses one
3131
3438
  that is up; a client keeps it across a snapshot).
3439
+ `{ k: 'hub-role', hubRole }` (v1.157) gives each permitted viewer the
3440
+ roles of players in hidden pairs, over the shared `hubRole`. Its effective
3441
+ role is `roleMe[playerId] ?? roleAll[playerId]`. It follows `hub-try` replay:
3442
+ a fresh hello without `again` resends the current private map, empty or not,
3443
+ once the place has ever sent one. Clients keep that map across snapshots;
3444
+ a snapshot without `hubRole` clears only the shared map. Old clients ignore it.
3132
3445
  Version-tagged by `hubPlace.contract`.
3133
3446
 
3134
3447
  Blocks: two players a block hides from each other (either one blocked the
@@ -4281,6 +4594,14 @@ a deck written before them remains valid.
4281
4594
 
4282
4595
  | date | change |
4283
4596
  | --- | --- |
4597
+ | 2026-10-21 | `hub.safeInsets`: the character sheet's landscape strip (one row of tiles with its own Close, at 844x390 and similar) is no longer moved or narrowed by the safe layout around the controls it covers: it stays where it fits itself and still counts as an obstacle for other cards. Before, a visible prompt such as "Talk to Rowan" could push it into a side lane and clip it off the right edge with its Close. The portrait and lane sheets are placed as before. No manifest or wire change. Within `hub.contract: 1`. |
4598
+ | 2026-10-21 | §5 invite actions: a place action whose id is `invite-friend`, `share-win` or `share-town` (a pick that calls `hub.invite`) is drawn, and its pick sent, only in a place with `invite` while the host's `Hub.canInvite` answer allows this socket's player; otherwise the other actions are drawn as before. A share the host then refuses shows "Sharing is unavailable here." instead of nothing; a stale socket, player or account still cancels silently. No manifest or wire change. Within `hub.contract: 1`. |
4599
+ | 2026-10-20 (v1.161) | §1 `hub.spawnCap`: a deck may raise `hub.spawn`'s cap on copies alive in a place from 96 to at most 192 (an integer 96..192, root only, refused otherwise by the manifest and the publish check). The spawn rate and burst, and Low tier's client-side `quality.low.spawned` cap, are unchanged. Absent key = same bytes and behaviour. Within `hub.contract: 1`. |
4600
+ | 2026-10-20 (v1.159) | §10 `decor.grids`: a place may declare 1..16 named decor grids (each like `grid`, origin checked at publish), with `grid` optional once `grids` is present; a catalogue spec's optional `grid` names the one it furnishes, which bounds `placed`, op cells and the sent grid, and `update` may change it. The id stays off the wire. Absent key = same bytes. Within `hub.contract: 1`. |
4601
+ | 2026-10-20 (v1.158) | Optional `idle.expression`: an emote wheel, five RP motions, sit-anywhere and private visit role-emote grants via `hub.emotesFor` (§6). No key preserves existing UI, behavior and wire bytes. |
4602
+ | 2026-10-20 (v1.156) | §4 `hub.noTrips(playerId)`: a client in the app (`CastleEmbed.host === "mobile"`) asks `Hub.doors()` once a page, and a host that refuses it as UNKNOWN_COMMAND (an app from before hub commands, released iOS 1.150 and 1.151) has no door trips: after each hello it sends `hub-no-trips`, and that player is left out of every pad's group, `hub.go` and house visits for the visit, with "Update Castle to play" over a door whose pad they stand on, to them alone. Any other answer (rows, `unavailable`, a timeout) and every web page change nothing. Every deck, no key. Within `hub.contract: 1`. |
4603
+ | 2026-10-19 (v1.155) | §5 the host may post a hub Go event (SDK `Hub.onGo`, `{ castleSdk: 1, hub: { type: "go", doorId, owner?, title?, party? } }`): the kit takes the player through the named door like a fired pad (`Hub.go` with `owner` as `ownerUserId`, the door beat, the cover), only once the place is settled and with no trip in flight, and drops it after 60 s, when it arrives during a trip, or for a door this place's Doors list lacks (a cabinet included). An older SDK or kit ignores it. Every deck, no key. Within `hub.contract: 1`. |
4604
+ | 2026-10-19 | §5 hub-entry link: on a page load whose first place is a root place (no hub join, no door behind it, not a game), the client reads `Multiplayer.joinHint()` once; `{ routeId: 'hub-entry', slot }` with `slot` `house` sends a signed-in player through the nearest listed House door (`HubDoor.to` `deck:house`) to their own House (`Hub.go` with no owner), and a guest stays with "Sign in to have a House of your own". `door:<id>` of a listed door: a host row placed by `layer`/`exact` needing one player is a trip through it; a pad door (ghost takes only a fired pad's group) or one needing more players is the Doors list's Go onto its pad, the latter saying how many it needs; a House door is the House rule; a disabled row says it is closed; a guest stays for every door, told "<Title> is in the Town · sign in to play". It waits while the player is held, and checks everything again after its door lookup, right before acting. An invite arrival wins; a trip, session swap, re-admission or new player id on the same connection, or 30 s unplaced spends it; unknown slots, unknown doors and hosts without the command change nothing. Every deck, no key; nothing new sent or kept. Within `hub.contract: 1`. |
4284
4605
  | 2026-10-18 (v1.154) | §5 a door asked within 16 s of this player's arrival in a session (a join, a trip's, a reconnect; ghost's roster lags it by up to 15 s, during which the SDK asks again through `forbidden`) keeps its cover up for the 15 s loading limit counted from that window's end, not the trip's start: a door that answers ok after 14 s of `forbidden` goes through instead of "it took too long". A door that never answers still shuts, by 31 s at most; one asked later keeps 15 s. Every deck, no key. Within `hub.contract: 1`. |
4285
4606
  | 2026-10-17 (v1.147) | §5 a joining player's body without a readable saved pose starts on the scene's spawn itself (its x and z, at the v1.48 standing height), not on the multiplayer spawn ring 1.1 m around it. The client starts its own body at the spawn; on the live Town the first WORLD snapped it to its ring slot, and the kit's arrival row back at the spawn then reached it as a correction under the client's 4 m snap distance, eased a quarter of the way a frame: a 1.1 m glide just after the cover lifted (3 of 5 captures, web and TECNO). Players waiting together share the spot until the arrival row spreads them; the row, the v1.40 settle and every later placement are unchanged. Saved and resumed poses are unchanged. A default in every hub place; no key, nothing new sent. |
4286
4607
  | 2026-10-18 (v1.150) | §12 and §13 authored mind taps also apply in `under13Choices` places: an under-13 speaker receives the place's authored asks ahead of both bundle `childAsks` and the three legacy choices. A matching trimmed `hub-npc-say` is answered through `npcLine` `why: 'authored'`; legacy strings outside those taps are ignored, and mind turns remain refused with `HUB_NPC_CHOICE_REQUIRED`. Mind-less NPCs, minds without authored asks, adults and unknown ages are unchanged. Within `hub.contract: 1`. |
@@ -4807,3 +5128,20 @@ The editor and mounted door content are unaffected. The key is client-only,
4807
5128
  validated as a boolean and omitted from the server manifest and wire.
4808
5129
 
4809
5130
  Tests: `scripts/test-high-only.mjs`.
5131
+
5132
+ ### v1.157 visit roles
5133
+
5134
+ `hub.role` and `hub.roleOf` (§11) add visit-only role labels, hats, torso
5135
+ pieces and carried tools. `hubRole` and `hub-role` (§12) follow try-on's
5136
+ whole-block latch, blocked-pair delivery and fresh-client replay. Retained
5137
+ visits keep roles through a short drop; fresh visits and account changes
5138
+ clear them. No host write, manifest integer change or bytes where unused.
5139
+
5140
+ ### v1.158 expression
5141
+
5142
+ Optional place-level `idle.expression` requires `idle.emotes: true`. It adds
5143
+ an eight-slot emote wheel with paged extras, five RP basics, sit-anywhere
5144
+ (`hub.seat` returns `'ground'`, the sit hook receives null) and declared role
5145
+ emotes granted per visit with `hub.emotesFor`. Definitions are public; grants
5146
+ are private and sent only on change. Absent expression preserves the old
5147
+ five-emote picker, behavior and wire bytes. See §6 for bounds and lifecycle.